✅ The public API is open. The public API is live since 12 November 2026. Sandbox keys (ff_test_) work for testing without moving money; live charges (ff_live_) need a verified business (ffPayVerified).
Base URL (local / preview): https://us-central1-franco-food-8ba71.cloudfunctions.net/payApiV1
Quickstart
1. Sign in to Franco Pay with your Franco Food business account and verify it (ffPayVerified). Verification is required for live keys — test keys never require it.
2. In the Dashboard, create an API key. A live key starts with ff_live_, a test key with ff_test_, followed by 32 hex characters. The full key is shown ONCE, at creation — save it as a secret; it is never stored or shown again.
3. Send every call with Authorization: Bearer <your key>. Create a charge with mode authorize (default) or immediate, then capture it after delivery is confirmed. Money only moves on capture.
Your first charge (sandbox)
curl -X POST https://us-central1-franco-food-8ba71.cloudfunctions.net/payApiV1/v1/public/charges \
-H "Authorization: Bearer ff_test_<32 hex>" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-1001" \
-d '{
"amount": 100,
"currency": "USD",
"mode": "authorize",
"customerEmail": "buyer@example.com",
"description": "Order #1001"
}'
# 201 → charge object + clientSecret + publishableKey + quote
# (amounts are in major units: 100 = $100)
Response: the charge object, a clientSecret and publishableKey to confirm the card with Stripe.js, and a quote with the full fee breakdown. Every charge object carries testMode and sandbox flags. Replaying the same Idempotency-Key returns 200 with replayed: true and the same charge — never a second charge.
Authentication
Two ways to authenticate. A public API key (ff_live_ / ff_test_ + 32 hex) authenticates as one business and is limited to the scopes it was created with. A Firebase ID token (your signed-in Franco Pay Dashboard session) authenticates as the business owner and is the only way to manage keys, webhooks and the audit log.
Authorization: Bearer ff_live_<32 hex> # public API key
Authorization: Bearer <Firebase ID token> # Dashboard session
Scopes
Each key carries a subset of these scopes (default: all five). A call outside the key’s scopes returns 403 SCOPE_FORBIDDEN.
| Scope | Allows |
|---|---|
charges:read | Read and list charges |
charges:write | Create, capture and cancel charges |
refunds:write | Create refunds |
transactions:read | List ledger transactions |
balance:read | Read balance and fee rates |
Key rules
- Maximum 5 active keys per business — a sixth mint returns 409 KEY_LIMIT_REACHED.
- Only the Dashboard (Firebase ID token) can create, list or revoke keys. A key can never mint keys: an API-key call to key management returns 403.
- Internal keys (kind
internal, used by the Franco Food app itself) can never call the public API: 403 KEY_NOT_PUBLIC. - Live keys require a verified business (ffPayVerified): 403 LIVE_REQUIRES_VERIFICATION. Test keys never require verification.
- The server stores only the key prefix (first 16 characters) and a SHA-256 hash — the full key is never stored, logged or returned again. A revoked key is rejected immediately (401 KEY_REVOKED).
- Ownership is checked on every call: a key can only see its own business’s charges, transactions and balance. A public key can never read app (non-public) charges — an app charge id returns 404, indistinguishable from a missing charge.
Rate limit: 120 requests per minute per key (a per-key override can change it). See Idempotency & limits.
Endpoints
Base: https://francoapp.com/api/v1 (live hosted base). Direct: https://us-central1-franco-food-8ba71.cloudfunctions.net/payApiV1. All 17 public routes live under /v1/public/*. Amounts are in major units (100 = $100) unless stated otherwise.
| Method | Path | Auth | Description |
|---|---|---|---|
| GET | /v1/cards | No auth | Accepted card brands by country (see Accepted cards below). No auth — works even before launch. |
| POST | /v1/public/charges | API key / ID token | Create a charge (authorize or immediate). Idempotency-Key required. kind, orderId and driverId are rejected — a third party never touches a Franco Food order. Scope charges:write. |
| GET | /v1/public/charges/:id | API key / ID token | Get one public-origin charge. Scope charges:read. |
| GET | /v1/public/charges | API key / ID token | List public-origin charges, newest first, paginated. Filter ?status= (authorized, awaiting_payment, captured, canceled, refunded, partially_refunded). Scope charges:read. |
| POST | /v1/public/charges/:id/capture | API key / ID token | Capture an authorized charge. Optional amount for a partial capture (never more than authorized; default: full amount). Scope charges:write. |
| POST | /v1/public/charges/:id/cancel | API key / ID token | Cancel an authorization. No money moves. Scope charges:write. |
| POST | /v1/public/refunds | API key / ID token | Refund a captured charge. Idempotency-Key required. Fees are never returned. Scope refunds:write. |
| GET | /v1/public/transactions | API key / ID token | List ledger movements for public-origin charges only, paginated. Filters ?from= / ?to= (ISO dates). Scope transactions:read. |
| GET | /v1/public/balance | API key / ID token | Business wallet balance: available, pending, authorized. Scope balance:read. |
| GET | /v1/public/fees | API key / ID token | Commission rates and the minimum charge (see Fees). Scope balance:read. |
| POST | /v1/public/keys | ID token only | Mint a public API key (ff_live_ or ff_test_). The full key is returned ONCE. Max 5 active keys. |
| GET | /v1/public/keys | ID token only | List the business’s keys — prefix only, never the full key. |
| POST | /v1/public/keys/:id/revoke | ID token only | Revoke a key. Rejected immediately; revoking twice returns the same object. |
| POST | /v1/public/webhooks | ID token only | Register an HTTPS endpoint to receive Franco Pay events. Idempotency-Key required. The HMAC secret is returned ONCE. |
| GET | /v1/public/webhooks | ID token only | List webhook registrations — never the secret. |
| POST | /v1/public/webhooks/:id/deactivate | ID token only | Deactivate a webhook registration. The endpoint stops receiving events; the secret is kept for reactivation by admin. |
| GET | /v1/public/webhooks/deliveries | ID token only | List delivery attempts (delivered / failed, status code, error, attempt). Filter ?event=. |
| GET | /v1/public/audit | ID token only | Audit log of the business’s public API calls (route, method, key, status, error) — including rejected calls. |
Examples
Create a charge — full body
curl -X POST https://us-central1-franco-food-8ba71.cloudfunctions.net/payApiV1/v1/public/charges \
-H "Authorization: Bearer ff_live_<32 hex>" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-1002" \
-d '{
"amount": 250,
"currency": "USD",
"mode": "authorize",
"customerEmail": "buyer@example.com",
"customerName": "Ana Gomez",
"customerPhone": "+18685550123",
"customerCountry": "TT",
"description": "Order #1002 — catering",
"invoiceId": "inv_abc123",
"receiptOption": "email"
}'
# Fields: amount (required, major units), currency (default: business currency),
# mode "authorize" (default) | "immediate", customerEmail / customerName /
# customerPhone / customerCountry, description (max 200 chars), invoiceId,
# receiptOption "email" (default, free). "email_pdf" is NOT available in v1.
# kind / orderId / driverId are REJECTED with 400 VALIDATION.
Capture (partial) and cancel
curl -X POST https://us-central1-franco-food-8ba71.cloudfunctions.net/payApiV1/v1/public/charges/ch_abc123/capture \
-H "Authorization: Bearer ff_live_<32 hex>" \
-H "Content-Type: application/json" \
-d '{"amount": 200}'
# → charge object + receiptQueued (false for sandbox charges)
curl -X POST https://us-central1-franco-food-8ba71.cloudfunctions.net/payApiV1/v1/public/charges/ch_abc123/cancel \
-H "Authorization: Bearer ff_live_<32 hex>"
# → charge object, status "canceled". No money moves.
List charges and read the balance
curl "https://us-central1-franco-food-8ba71.cloudfunctions.net/payApiV1/v1/public/charges?status=captured&limit=20" \
-H "Authorization: Bearer ff_live_<32 hex>"
# → { items: [charge], nextCursor } — pass ?cursor=<nextCursor> for the next page
curl https://us-central1-franco-food-8ba71.cloudfunctions.net/payApiV1/v1/public/balance \
-H "Authorization: Bearer ff_live_<32 hex>"
# → { businessId, currency, available, pending, authorized }
Refund a captured charge
curl -X POST https://us-central1-franco-food-8ba71.cloudfunctions.net/payApiV1/v1/public/refunds \
-H "Authorization: Bearer ff_live_<32 hex>" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: refund-order-1002" \
-d '{"chargeId": "ch_abc123", "amount": 50, "reason": "Customer returned the item"}'
# → { id, businessId, chargeId, amount, reason, stripeRefundId, chargeStatus,
# feesReturned: 0, fromPending, fromAvailable, sandbox, note }
# Fees are never returned: the Stripe fee and the Franco commission stay with
# the platform. Refunds come from pending first, then available.
Fee rates and transactions
curl https://us-central1-franco-food-8ba71.cloudfunctions.net/payApiV1/v1/public/fees \
-H "Authorization: Bearer ff_live_<32 hex>"
# → { unverifiedPct, verifiedPct, volumeThresholdMonthly, volumeUnverifiedPct,
# volumeVerifiedPct, minChargeAmount, currency, note }
curl "https://us-central1-franco-food-8ba71.cloudfunctions.net/payApiV1/v1/public/transactions?from=2026-11-01&to=2026-11-08&limit=20" \
-H "Authorization: Bearer ff_live_<32 hex>"
# → { items: [ledger movement], nextCursor } — public-origin charges only.
# Sandbox charges write no ledger rows, so they never appear here.
Mint, list and revoke keys (Dashboard — Firebase ID token)
curl -X POST https://us-central1-franco-food-8ba71.cloudfunctions.net/payApiV1/v1/public/keys \
-H "Authorization: Bearer <Firebase ID token>" \
-H "Content-Type: application/json" \
-d '{"testMode": true, "scopes": ["charges:read", "charges:write"], "label": "Website checkout"}'
# → { id, businessId, keyPrefix, testMode, scopes, label, revoked: false,
# createdAt, key } — the full key is returned ONCE. Save it now.
curl https://us-central1-franco-food-8ba71.cloudfunctions.net/payApiV1/v1/public/keys \
-H "Authorization: Bearer <Firebase ID token>"
# → { items: [key] } — prefix only, never the full key.
curl -X POST https://us-central1-franco-food-8ba71.cloudfunctions.net/payApiV1/v1/public/keys/key_abc123/revoke \
-H "Authorization: Bearer <Firebase ID token>"
# → key object, revoked: true.
Register a webhook (Dashboard — Firebase ID token)
curl -X POST https://us-central1-franco-food-8ba71.cloudfunctions.net/payApiV1/v1/public/webhooks \
-H "Authorization: Bearer <Firebase ID token>" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: webhook-1" \
-d '{"url": "https://example.com/franco-pay/events",
"events": ["charge.authorized", "charge.captured", "charge.refunded"]}'
# → { id, businessId, url, events, active: true, secret, createdAt }
# The HMAC secret is returned ONCE. URL must be https, max 2048 chars,
# no userinfo. Events must be a subset of the 7 listed in Webhooks below.
Dashboard API
Franco Pay has two API surfaces. The Public API (/v1/public/*, documented above) is for third-party platforms and is opened with an API key — it is gated by 503 until launch. The Dashboard API below is the same API the Franco Pay Dashboard and app use: it is live today, it authenticates with your signed-in Dashboard session (a Firebase ID token), and most routes also accept a public API key. Use it to automate your own business — invoices, withdrawals, customers, team — from your own system.
Base: https://francoapp.com/api/v1 (live hosted base — verified). Direct: https://us-central1-franco-food-8ba71.cloudfunctions.net/payApiV1. Amounts are in major units (100 = $100) unless stated otherwise.
The endpoint reference below is in English — the API’s source language. The explanations around it are translated.
Authentication — Dashboard session
Send your Firebase ID token (the token of your signed-in Franco Pay Dashboard session) as Authorization: Bearer <Firebase ID token>. A public API key (ff_live_ / ff_test_) also works on the routes marked “API key / ID token” — but a key can never manage keys, webhooks or team members, and it can never act for another business. Admin-only routes need a platform admin session. The two no-auth routes (GET /v1/health, GET /v1/cards) work without any token.
Authorization: Bearer <Firebase ID token> # Dashboard session (owner / team member)
Team roles — what each role can do
A business can have a team. The owner invites members (see Team below); a member must be a registered Franco Food user with a verified email — a phone number is NOT required for members. The owner always has full access. A call outside a member’s role returns 403 PERMISSION_DENIED.
| Role | Can | Cannot |
|---|---|---|
| Owner | Everything — charges, invoices, refunds, withdrawals, team, keys | — |
| Manager | Charges, invoices, refunds, client licences, reads | Withdrawals, team members, API keys |
| Staff | Charges, basic reads | Invoices, refunds, withdrawals, team members, API keys |
| Viewer | Basic reads only | Charges, invoices, refunds, withdrawals, team members, API keys |
Withdrawals are owner-only: no team role can request one, and a member’s API key can never withdraw either — the owner withdraws from the Dashboard. API-key callers bypass the team-role check (a key acts as the business), except where a route says “ID token only”.
No payment-links endpoint
There is no standalone payment-links endpoint in v1. To charge a customer, create a charge (POST /v1/charges) — the response carries a clientSecret and publishableKey to confirm the card with Stripe.js. Invoices do not have a payment page in v1 either: an invoice’s paymentLink is always null — the customer pays from the Franco Pay app (the invoice email links there).
Endpoints — Dashboard API (49 routes)
Every route below exists in the live API. The Auth column says how to authenticate; Admin only means a platform admin session (a business key gets 403). Routes marked “Idempotency-Key required” fail with 400 VALIDATION without the header — see the full list under Idempotency below.
Charges & quotes
| Method | Path | Auth | Description |
|---|---|---|---|
| POST | /v1/charges | API key / ID token | Create a charge. Idempotency-Key required. |
| POST | /v1/charges/:id/capture | API key / ID token | Capture an authorized charge |
| POST | /v1/charges/:id/confirm-delivery | API key / ID token | Confirm delivery for a charge |
| POST | /v1/charges/:id/cancel | API key / ID token | Cancel an authorization |
| GET | /v1/quote | API key / ID token | Get a fee quote |
Invoices
| Method | Path | Auth | Description |
|---|---|---|---|
| POST | /v1/invoices | API key / ID token | Create an invoice. Idempotency-Key required. |
| POST | /v1/invoices/:id/send | API key / ID token | Send an invoice. Idempotency-Key required. |
| POST | /v1/invoices/:id/cancel | API key / ID token | Cancel an invoice. Idempotency-Key required. |
| POST | /v1/invoices/:id/remind | API key / ID token | Remind an invoice. Idempotency-Key required. |
Refunds
| Method | Path | Auth | Description |
|---|---|---|---|
| POST | /v1/refunds | API key / ID token | Create a refund. Idempotency-Key required. |
Withdrawals
| Method | Path | Auth | Description |
|---|---|---|---|
| POST | /v1/withdrawals | API key / ID token | Request a withdrawal. Idempotency-Key required. |
| GET | /v1/withdrawals | API key / ID token | List withdrawals |
| GET | /v1/withdrawals/details | API key / ID token | Get payout details |
| POST | /v1/withdrawals/details | API key / ID token | Save payout details |
| POST | /v1/withdrawals/global-payouts | API key / ID token | Request a Global Payouts withdrawal |
| POST | /v1/withdrawals/:id/transition | Admin only | Move a withdrawal. Admin only. |
| GET | /v1/withdrawals/:id/card | Admin only | Get a withdrawal’s full card number. Admin only. |
Payouts (Global Payouts / Treasury)
| Method | Path | Auth | Description |
|---|---|---|---|
| POST | /v1/payouts/recipients | API key / ID token | Create a Global Payouts recipient |
| GET | /v1/payouts/recipients | API key / ID token | List Global Payouts recipients |
| GET | /v1/payouts/recipients/:id | API key / ID token | Get a Global Payouts recipient |
| GET | /v1/payouts/recipients/:id/bank | Admin only | Get a recipient’s full bank account number |
| GET | /v1/payouts/treasury | Admin only | Get Treasury and funding status |
Balance & transactions
| Method | Path | Auth | Description |
|---|---|---|---|
| GET | /v1/balance | API key / ID token | Get wallet balance |
| GET | /v1/transactions | API key / ID token | List transactions |
| GET | /v1/pending-payments | ID token only | List my pending pay-on-delivery payments |
Customers & clients
| Method | Path | Auth | Description |
|---|---|---|---|
| GET | /v1/customers | API key / ID token | List customers |
| GET | /v1/customers/:id | API key / ID token | Get a customer |
| GET | /v1/customers/:id/transactions | API key / ID token | List a customer’s transactions |
| POST | /v1/clients/:id/license-verification | API key / ID token | Submit a client license verification |
| GET | /v1/clients/:id/license | API key / ID token | Get a client license status |
| GET | /v1/clients/pending-review | Admin only | List clients pending review. Admin only. |
| POST | /v1/clients/:id/license-verify | Admin only | Approve or reject a client license. Admin only. |
Businesses & verification
| Method | Path | Auth | Description |
|---|---|---|---|
| GET | /v1/businesses | API key / ID token | List businesses |
| GET | /v1/businesses/:id | API key / ID token | Get a business |
| POST | /v1/businesses/:id/verification | API key / ID token | Submit a business verification |
| GET | /v1/businesses/pending-review | Admin only | List businesses pending review. Admin only. |
| POST | /v1/businesses/:id/verify | Admin only | Approve or reject a verification. Admin only. |
Disputes
| Method | Path | Auth | Description |
|---|---|---|---|
| GET | /v1/disputes | API key / ID token | List disputes |
Team (memberships)
| Method | Path | Auth | Description |
|---|---|---|---|
| GET | /v1/memberships/mine | ID token only | My businesses and roles |
| GET | /v1/memberships | API key / ID token | List team members of the business |
| POST | /v1/memberships | ID token only | Invite a team member. Owner only. |
| POST | /v1/memberships/:id/role | ID token only | Change a team member’s role. Owner only. |
| POST | /v1/memberships/:id/remove | ID token only | Remove a team member. Owner only. |
Settings (admin)
| Method | Path | Auth | Description |
|---|---|---|---|
| GET | /v1/settings | Admin / Support | Read Franco Pay settings |
| POST | /v1/settings | Admin only | Update Franco Pay settings. Admin only. |
| POST | /v1/webhooks/out | Admin only | Register an outbound webhook. Idempotency-Key required. Admin only. |
No-auth & Stripe inbound
| Method | Path | Auth | Description |
|---|---|---|---|
| GET | /v1/health | No auth | Health check — no auth |
| GET | /v1/cards | No auth | Accepted card brands by country — no auth |
| POST | /v1/webhooks/stripe | Stripe signature | Stripe webhook |
Examples — Dashboard API
Create an invoice and send it
curl -X POST https://francoapp.com/api/v1/invoices \
-H "Authorization: Bearer <Firebase ID token>" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: inv-2026-0001" \
-d '{
"lines": [{"description": "Catering — office lunch", "qty": 1, "price": 120}],
"customerEmail": "buyer@example.com",
"customerName": "Ana Gomez",
"currency": "USD",
"send": true
}'
# → Invoice { id, customerEmail, total: 120, currency: "USD",
# status: "pending", paymentLink: null, sentAt, mailQueued: true }
# send: true creates the invoice already sent. To send a draft later:
curl -X POST https://francoapp.com/api/v1/invoices/inv_abc123/send \
-H "Authorization: Bearer <Firebase ID token>" \
-H "Idempotency-Key: inv-2026-0001-send"
# → Invoice, status "pending". Re-sending never mails twice to the same customer.
Request a withdrawal (debit card)
curl -X POST https://francoapp.com/api/v1/withdrawals \
-H "Authorization: Bearer <Firebase ID token>" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: wd-2026-0001" \
-d '{
"method": "debit_card",
"amount": 50,
"currency": "USD",
"fullName": "Example Person",
"address": "1 Example Street, Port of Spain, Trinidad and Tobago",
"cardNumber": "4111111111111111",
"debitConfirmed": true
}'
# → { id, businessId, amount: 50, currency: "USD", status: "requested",
# method: "debit_card", payoutPartner: "Laparkan Trinidad",
# payoutCurrency: "TTD", debitCardBrand: "visa", debitCardLast4: "1111" }
# "4111111111111111" is the Stripe TEST card — never send a real card number
# in an example. Only AVAILABLE (already released) balance can be withdrawn,
# never pending. The full card number is stored only in the restricted
# secrets collection — the withdrawal itself keeps brand + last 4.
List transactions and read the balance
curl "https://francoapp.com/api/v1/transactions?limit=20" \
-H "Authorization: Bearer <Firebase ID token>"
# → { items: [{ id, kind, amount, type, concept, chargeId, state, origin, date }],
# nextCursor } — pass ?cursor=<nextCursor> for the next page.
curl https://francoapp.com/api/v1/balance \
-H "Authorization: Bearer <Firebase ID token>"
# → { businessId, currency, available, pending, reserve, authorized,
# heldWithdrawals, heldWithdrawalCount, nextReleaseAt }
Get a fee quote before charging
curl "https://francoapp.com/api/v1/quote?amount=100¤cy=USD" \
-H "Authorization: Bearer <Firebase ID token>"
# → { gross: 100, amount: 100, currency: "USD", stripeFee: 3.20,
# francoFee: 5.00, francoFeePct: 0.05, receiptOption: "email", net: 91.80,
# customerTotal: 100, minChargeAmount: 5 }
# $100 online, unverified business: Stripe $3.20 + Franco 5% ($5.00) = net $91.80.
Invite a team member and change their role (owner only)
curl -X POST https://francoapp.com/api/v1/memberships \
-H "Authorization: Bearer <Firebase ID token>" \
-H "Content-Type: application/json" \
-d '{"email": "manager@example.com", "role": "manager"}'
# → { member: { id, memberUid, businessId, email, displayName,
# role: "manager", status: "active", createdAt, updatedAt } }
# The invited user must already be a registered Franco Food user with a
# verified email — otherwise 404 MEMBER_NOT_FOUND.
curl -X POST https://francoapp.com/api/v1/memberships/<memberUid>/role \
-H "Authorization: Bearer <Firebase ID token>" \
-H "Content-Type: application/json" \
-d '{"role": "staff"}'
# → { member: { ..., role: "staff" } }. A member can never change their own role.
Idempotency — Dashboard API
The same Idempotency-Key rules as the Public API, on more routes. The header is required on: POST /v1/charges, POST /v1/invoices, POST /v1/invoices/:id/send, POST /v1/invoices/:id/cancel, POST /v1/invoices/:id/remind, POST /v1/refunds, POST /v1/withdrawals, POST /v1/withdrawals/global-payouts and POST /v1/webhooks/out. Without it the call fails with 400 VALIDATION (idempotency_required). Replaying the same key with the same body returns the original result (200 with replayed: true); the same key with a different body returns 409 IDEMPOTENCY_CONFLICT. The 120-requests-per-minute per-key rate limit (429 RATE_LIMITED) applies to API-key calls; see Idempotency & limits.
Top up a friend
Top up a friend or family member’s Franco Pay wallet by card — from anywhere in the world. You pay the amount plus the Stripe fee and a 1% Franco Pay fee; your friend receives the exact amount in their own currency. This is a Dashboard call (Firebase ID token), not a public API-key call: the endpoint is the createPaymentIntent HTTPS function, purpose wallet_topup.
Authentication — Firebase ID token (the signed-in Franco Food user). The caller pays by card and needs no wallet balance of their own.
Request
POST https://createpaymentintent-ykrei72r5a-uc.a.run.app — purpose: "wallet_topup" + wallet_topup: { recipientEmail | recipientPhone, currency }
| Field | Type | Meaning |
|---|---|---|
amount | number | Top-up amount, 1–500, in wallet_topup.currency. |
idem | string | Idempotency key (8–64 chars). Same key + same body returns the same PaymentIntent — never a second charge or credit. |
wallet_topup.recipientEmail | string | Friend’s Franco Food email. Either this or recipientPhone is required. |
wallet_topup.recipientPhone | string | Friend’s Franco Food phone. |
wallet_topup.currency | string | Currency you pay in (USD, TTD or XCD). Defaults to your own wallet currency. |
Auth: Authorization: Bearer <Firebase ID token>.
Response
| Field | Meaning |
|---|---|
id / client_secret | Stripe PaymentIntent — confirm it with Stripe.js (confirmCardPayment) using publishableKey. |
recipient | { uid, name, email, currency } — the friend, looked up and verified BEFORE any charge. Show the name before the user pays. |
topup | { amount, stripeFee, platformFee, total, currency } — the fee breakdown. The card is charged total. |
credit | { amount, currency, fxRate, topupAmount, topupCurrency } — what the friend is credited, in THEIR currency, after the one frozen-rate conversion. |
publishableKey | Stripe publishable key for Stripe.js (returned by the server at runtime; never hardcode a key). |
Example
curl -X POST https://createpaymentintent-ykrei72r5a-uc.a.run.app \
-H "Authorization: Bearer <Firebase ID token>" \
-H "Content-Type: application/json" \
-d '{
"purpose": "wallet_topup",
"amount": 10,
"idem": "tuf-2026-0001",
"wallet_topup": { "recipientEmail": "friend@example.com", "currency": "USD" }
}'
# → { id: "pi_…", client_secret: "pi_…_secret_…",
# recipient: { uid, name: "María Pérez", email: "friend@example.com", currency: "TTD" },
# topup: { amount: 10, stripeFee: 0.61, platformFee: 0.10, total: 10.71, currency: "USD" },
# credit: { amount: 68.00, currency: "TTD", fxRate: 6.8, topupAmount: 10, topupCurrency: "USD" },
# publishableKey: "pk_live_…" }
# Confirm with Stripe.js, then the webhook credits TT$68.00 to the friend
# and notifies them. A retry with the same idem returns the same intent
# (reused: true) — never a second charge.
Fee math
US$10 top-up to a friend: Stripe US$0.61 + Franco Pay 1% US$0.10 = total charged US$10.71; the friend is credited exactly US$10.00 (converted once at the frozen rate when the currencies differ).
Currency — the friend is always credited in their own currency
The wallet is always in the account’s registered-country currency (Trinidad and Tobago → TTD, Antigua and Barbuda / Dominica → XCD, United States → USD, any other country → its registered currency). The top-up converts once at the frozen config/wallet_fx rate (USD 1, XCD 2.70, TTD 6.80). Example: US$10 to a friend in Trinidad and Tobago credits TT$68.00 at 1 USD = 6.80 TTD. Same currency: no conversion. No rate for the pair: 422 FX_RATE_REQUIRED — never estimated, never 1:1. The conversion (amount, currency, rate, credited amount and currency) is recorded on both ledger entries.
Errors
| HTTP | Code | Meaning |
|---|---|---|
| 404 | RECIPIENT_NOT_FOUND | No Franco Food user with that email or phone — no charge was made. |
| 422 | RECIPIENT_NOT_ELIGIBLE | The friend’s email/phone is not verified for Franco Pay — no charge was made. |
| 422 | FX_RATE_REQUIRED | No frozen rate for this currency pair — the top-up is rejected, never estimated. |
| 429 | RATE_LIMITED | More than 20 friend top-ups from this user today. |
| 400 | — | Amount outside 1–500, or a missing/invalid idem key. |
Notifications & history
When the friend’s wallet is credited, they get a push notification, an in-app notification and a designed email naming the sender and the exact amount credited — never the sender’s card or the fees. The top-up appears in both users’ transaction histories (GET /v1/transactions).
Transfers — wallet to wallet
Send money from your wallet to another Franco Food user’s wallet — free and instant. The sender is always the signed-in user; the receiver gets exactly the amount sent (same currency) or the converted equivalent (other currency, once, at the frozen rate). This is a Dashboard call (Firebase ID token), not a public API-key call.
Authentication — Firebase ID token (the signed-in Franco Food user). An API key can never send a transfer: only the account owner, signed in, can move money from their own wallet.
Look up the recipient first
GET https://francoapp.com/api/v1/transfers/lookup?email=<email> or ?phone=<phone>
| Field | Meaning |
|---|---|
found | true when a Franco Food user matches the email or phone. |
uid / name / currency | The recipient — show the name before the user confirms, so money never goes to the wrong person. currency is the recipient’s registered-country wallet currency. |
isSelf | true when the lookup matches the caller — self-transfers are rejected. |
The lookup returns only the name and currency — never the recipient’s balance, email or phone. An unknown recipient returns found: false, not an error.
Request
POST https://francoapp.com/api/v1/transfers
| Field | Type | Meaning |
|---|---|---|
recipientUid | string | The recipient’s uid (from the lookup). Either this, recipientEmail or recipientPhone is required. |
recipientEmail | string | The recipient’s Franco Food email. |
recipientPhone | string | The recipient’s Franco Food phone. |
amount | number | Amount to send, in the sender’s wallet currency. Minimum US$5 equivalent. |
currency | string | Optional. Must match the sender’s wallet currency when given — anything else is rejected. |
note | string | Optional note (max 200 characters), shown on both ledger entries. |
Headers: Authorization: Bearer <Firebase ID token> + Idempotency-Key: <unique key> (required — without it the call fails with 400 VALIDATION).
Response
| Field | Meaning |
|---|---|
id | Transfer id — the same id on both ledger entries and in both histories. |
senderId / receiverId / receiverName | Who sent it and who received it. |
amount / currency | What the sender sent, in the sender’s currency (debited from their wallet). |
receiverAmount / receiverCurrency | What the receiver was credited, in THEIR currency — the converted amount when the currencies differ. |
fxRate | The frozen rate used (receiver units per 1 sender unit). 1 when the currencies match. |
fee | 0 — transfers are free. |
status | completed — the money moves in one atomic transaction. |
senderBalance | The sender’s new available balance. |
createdAt | ISO timestamp of the transfer. |
201 on success; 200 with replayed: true when the same Idempotency-Key + body is sent again — never a double send.
Example
curl -X POST https://francoapp.com/api/v1/transfers \
-H "Authorization: Bearer <Firebase ID token>" \
-H "Idempotency-Key: trf-2026-0001" \
-H "Content-Type: application/json" \
-d '{
"recipientEmail": "friend@example.com",
"amount": 100,
"currency": "USD"
}'
# → { id: "trf_…", senderId: "…", receiverId: "…", receiverName: "Carlos Pérez",
# amount: 100, currency: "USD", receiverAmount: 680.00, receiverCurrency: "TTD",
# fxRate: 6.8, fee: 0, status: "completed", senderBalance: 400, createdAt: "2026-11-08T…" }
# The receiver (Trinidad and Tobago, wallet in TTD) is credited TT$680.00 —
# US$100 converted once at the frozen 1 USD = 6.80 TTD. A retry with the same
# Idempotency-Key returns the same transfer (replayed: true).
Fee — free
Transfers are free: no platform fee, no Stripe fee (no card is involved — the money moves between two wallets). The receiver gets exactly the amount sent (same currency) or the converted equivalent (other currency). The sender’s balance is debited the amount sent; nothing else is charged.
Currency — the receiver is always credited in their own currency
The wallet is always in the account’s registered-country currency (Trinidad and Tobago → TTD, Antigua and Barbuda / Dominica → XCD, United States → USD, any other country → its registered currency). A transfer between different currencies converts once at the frozen config/wallet_fx rate (USD 1, XCD 2.70, TTD 6.80). Example: US$100 to Trinidad and Tobago credits TT$680.00 at 1 USD = 6.80 TTD; XCD$270 to Trinidad and Tobago credits TT$680.00 at 6.80 / 2.70. Same currency: no conversion. No rate for the pair: 422 FX_RATE_REQUIRED — never estimated, never 1:1, and a wallet is never credited in a currency different from the account’s. The conversion (amount, currency, rate, credited amount and currency) is recorded on both ledger entries.
Errors
| HTTP | Code | Meaning |
|---|---|---|
| 400 | AMOUNT_INVALID | The amount is not a positive number. |
| 400 | BELOW_MINIMUM | The amount is below the US$5 equivalent minimum. |
| 400 | SELF_TRANSFER | The sender and the recipient are the same user. |
| 400 | VALIDATION | Missing recipient, missing Idempotency-Key, or a currency that does not match the sender’s wallet. |
| 403 | FORBIDDEN | An API key called this route — transfers are ID-token only. A team member also gets 403 PERMISSION_DENIED (only the owner sends from their own wallet). |
| 404 | RECIPIENT_NOT_FOUND | No Franco Food user with that email/phone/uid, or the account is a guest — no money moved. |
| 422 | INSUFFICIENT_AVAILABLE | The sender’s available balance does not cover the amount (pending, reserve and authorized money cannot be sent). |
| 422 | FX_RATE_REQUIRED | No frozen rate for this currency pair, or the receiver has no registered currency — the transfer is rejected, never estimated. |
| 429 | RATE_LIMITED | More than 5 transfers from this user in one minute. |
| 409 | IDEMPOTENCY_CONFLICT | The same Idempotency-Key was used with a different body. |
History
The transfer appears in both users’ transaction histories (GET /v1/transactions, kind ffpay_transfer) — the sender sees “Transfer to <name>” with a minus, the receiver sees “Transfer from <name>” with a plus, each in their own currency, with the date and the transfer id. The same transfer also appears in the Franco Food wallet history, because the wallet is shared.
Fees
The customer pays the total with fees included (gross-up): the business receives the net amount. The rates below are the decided Franco Pay rates (Lester, 8 November 2026) and are configurable in the platform settings — they are not hard-coded in the API. Read the live rates any time with GET /v1/public/fees.
| Fee | Rate |
|---|---|
| Franco commission — unverified business | 5% |
| Franco commission — verified business (ffPayVerified) | 3.5% |
| Volume tier — unverified, over US$10,000 / month | 4% |
| Volume tier — verified, over US$10,000 / month | 3% |
| Minimum charge | US$5 |
| Reserve held back | 0% |
| Receipt PDF (optional extra) | US$0.50 |
Payout costs are paid by the customer at charge time, on top of the price, so the business is paid in full: Trinidad & Tobago local bank US$2.50 per payout + 1% FX; Antigua & Barbuda wire US$25 per payout + 1% FX; Dominica via Remitly. The Stripe card fee is also charged to the customer (gross-up) — the business receives the net. Refunds never return fees: the Stripe fee and the Franco commission stay with the platform.
The receipt PDF option (receiptOption: "email_pdf") is priced at US$0.50 but is NOT delivered in v1 — the mail system cannot send attachments yet. Do not request it; the email receipt is free and is the default.
Currencies
Charge in more than 130 currencies, from customers in more than 130 countries. Pass any supported currency code in currency when you create a charge (POST /v1/public/charges) or get a quote (GET /v1/quote) — the customer pays in that currency.
Settlement — the wallet is always credited in the wallet currency (USD, TTD or XCD by country). A charge in any other currency is converted once at the frozen rate (config/wallet_fx); the conversion (amount, currency, rate and credited amount) is recorded on the ledger entry.
Conversion fee — 2% total when the charge currency differs from the wallet currency (1% Stripe + 1% Franco Pay), shown to the customer as one "Conversion 2%" line. GET /v1/quote returns it as conversionFee (with stripeFeeProcessing, fxFee, netWalletAfterFx).
One exception — STD (São Tomé and Príncipe dobra) is listed but has no frozen rate yet, so charges in STD return 422 FX_RATE_REQUIRED. The full list of 134 codes is in the panel (Developer → API docs).
Build on it: your own app or website can take card payments through the Franco Pay API — create a charge, share the payment link, or confirm the card with Stripe.js. The full reference is in the panel (Developer → API docs).
Accepted cards
Which card brands your customers can pay with through Stripe, per country. Franco Pay charges on its own US Stripe account, so the same brands apply in every country — the four rows below are identical by design, not by mistake.
| Country | Accepted ✓ | Not accepted ✗ |
|---|---|---|
| Trinidad & Tobago (TT) | Visa, Mastercard, American Express, Discover, Diners Club, JCB, China UnionPay, Cartes Bancaires (French cards only) | eftpos (Australia only) |
| Antigua & Barbuda (AG) | Visa, Mastercard, American Express, Discover, Diners Club, JCB, China UnionPay, Cartes Bancaires (French cards only) | eftpos (Australia only) |
| Dominica (DM) | Visa, Mastercard, American Express, Discover, Diners Club, JCB, China UnionPay, Cartes Bancaires (French cards only) | eftpos (Australia only) |
| United States (US) | Visa, Mastercard, American Express, Discover, Diners Club, JCB, China UnionPay, Cartes Bancaires (French cards only) | eftpos (Australia only) |
Source: Stripe Docs, “Cards”, table “Online card brand capabilities”, column “Stripe Account Country” (US account). Or read the live list any time with GET /v1/cards — no auth.
Example
curl https://us-central1-franco-food-8ba71.cloudfunctions.net/payApiV1/v1/cards
Idempotency & limits
Idempotency-Key — required on these POSTs
Send a unique Idempotency-Key header with every call to POST /v1/public/charges, POST /v1/public/refunds and POST /v1/public/webhooks. Without it the call fails with 400 VALIDATION (idempotency_required). Retrying with the same key and the same body returns the original result (200 with replayed: true) — no second charge, refund or webhook. The same key with a different body returns 409 IDEMPOTENCY_CONFLICT. Use one key per order in your own system (for example, your order number).
Limits
| Limit | Value |
|---|---|
| Requests per minute, per API key | 120 (a per-key override can change it; exceeding it returns 429 RATE_LIMITED) |
| Pagination — default page size | 20 |
Pagination — maximum page size (?limit=) | 100 |
| Pagination — cursor | Pass the nextCursor from the previous response as ?cursor=. The cursor is the document id of the last item on the previous page. |
| Minimum charge | US$5 |
| Active API keys per business | 5 |
| Authorization window | 7 days — an authorization expires after 7 days if never captured. |
| Anti-structuring | Identical amount + customer, maximum 3 per 60 minutes — 422 STRUCTURING_SUSPECTED when exceeded. |
Charge statuses: authorized → captured (or canceled); awaiting_payment while the card has not been confirmed yet; refunded / partially_refunded after a refund.
Webhooks (outbound)
Register one HTTPS endpoint per business and Franco Pay POSTs an event to it every time one of these happens:
| Event | When |
|---|---|
charge.authorized | A charge was authorized |
charge.captured | A charge was captured |
charge.refunded | A charge was refunded |
charge.canceled | An authorization was canceled |
withdrawal.requested | A withdrawal was requested |
withdrawal.completed | A withdrawal completed |
invoice.sent | An invoice was sent |
Verifying the signature
Every delivery is signed. The header is X-Franco-Pay-Signature: t=<unix timestamp>,v1=<hex>, where v1 is the HMAC-SHA256 of the string "<ts>.<raw JSON body>" using your webhook secret as the key. Always verify the signature before trusting an event — the secret is issued once, at registration, and is stored only in the restricted secrets collection.
// Node.js — verify an incoming Franco Pay webhook
const crypto = require('crypto');
function verifyFrancoPay(req, secret) {
const sig = req.headers['x-franco-pay-signature'] || '';
const m = sig.match(/t=(\d+),v1=([0-9a-f]+)/);
if (!m) return false;
const expected = crypto.createHmac('sha256', secret)
.update(m[1] + '.' + req.rawBody) // raw JSON body, exactly as received
.digest('hex');
return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(m[2]));
}
Retries
A 2xx response means delivered. Anything else is retried, up to 8 attempts, with backoff in minutes: [1, 5, 15, 60, 360, 1440]. After 8 failed attempts the delivery is dead. Delivery attempts are listed in GET /v1/public/webhooks/deliveries (filter ?event=). Events are delivered by a scheduler every 5 minutes.
Error codes
Every error response has the shape { "error": { "code": "…", "message": "…" } }. The HTTP status and the code are both stable — check the code, not the message text.
| HTTP | Code | Meaning |
|---|---|---|
| 503 | PUBLIC_API_DISABLED | The public API is disabled — returned only while the API flag is off. |
| 403 | SCOPE_FORBIDDEN | The key does not have the scope this endpoint needs. |
| 403 | KEY_NOT_PUBLIC | An internal key (kind internal) called the public API. Internal keys never enter the public API. |
| 403 | LIVE_REQUIRES_VERIFICATION | A live call requires a verified business (ffPayVerified). Use a test key, or verify the business first. |
| 409 | KEY_LIMIT_REACHED | The business already has 5 active API keys. Revoke one before minting another. |
| 400 | INVALID_SCOPE | The requested scope list is empty or contains an unknown scope. |
| 404 | NOT_FOUND | The resource does not exist, or belongs to another business (ownership is never leaked). |
| 429 | RATE_LIMITED | More than 120 requests per minute for this key. Wait and retry. |
| 400 | VALIDATION | Missing or invalid data — including a missing Idempotency-Key where one is required, and rejected fields (kind, orderId, driverId) on public charges. |
| 400 | AMOUNT_INVALID | The amount is invalid (for example, zero or negative). |
| 400 | BELOW_MINIMUM | The charge is below the US$5 minimum. |
| 409 | CHARGE_NOT_AUTHORIZED | The charge is not in authorized status — it cannot be captured, canceled or refunded in its current state. |
| 409 | REFUND_EXCEEDS | The refund is larger than the remaining captured amount. |
| 409 | IDEMPOTENCY_CONFLICT | The Idempotency-Key was already used with a different body. |
| 401 | UNAUTHORIZED / INVALID_KEY | Authentication is required, or the API key is invalid or unknown. |
| 401 | KEY_REVOKED | The API key has been revoked. |
| 403 | FORBIDDEN | You do not have access to this business. |
| 403 | PERMISSION_DENIED | Your team role does not allow this. Ask the business owner to change your role (see Team roles in the Dashboard API). |
| 409 | MEMBER_EXISTS | This user is already a member of this business. |
| 404 | MEMBER_NOT_FOUND | No Franco Food account with that email. The user must create a Franco Food account first. |
| 403 | FRANCO_PAY_EMAIL_NOT_VERIFIED | The team member's email is not verified yet. They must verify their email in Franco Food first. |
| 403 | FRANCO_PAY_NO_REGISTRATION | Franco Pay requires a Franco Food account. Create a Franco Food account first, with a verified email and phone. |
| 403 | READ_ONLY_ROLE | Support agents have read-only access and cannot move money. |
| 403 | BUSINESS_NOT_VERIFIED | The business is not verified for this operation. |
| 500 | INTERNAL | An unexpected server error. Retry once with the same Idempotency-Key — a retried charge or refund never double-charges. |
Sandbox
Keys starting with ff_test_ create sandbox charges. Use them to integrate and test the whole flow — create, capture, refund, webhooks — before going live. Sandbox and live are the same API; only the key prefix changes the mode.
- A sandbox charge is captured and ends with status
"captured"andsandbox: true— but no wallet is ever credited, no ledger row is written, there is no Treasury funding and no receipt is sent. - Sandbox refunds run the Stripe TEST refund and the charge tracks the refund, but no wallet money moves (
fromPending/fromAvailableare 0,sandbox: true). - Fees are still calculated and recorded on sandbox charges, so you can see exactly what a live charge would cost — they just never move money.
- Sandbox charges write no ledger rows, so they never appear in
GET /v1/public/transactions— only real (live) public money appears there. - Test keys never require business verification. Live keys do (ffPayVerified).
Sandbox charges use Stripe test mode. No real card is ever charged and no real money ever moves.
Compliance guardrails — read this first
- Only verified businesses get live keys. Without ffPayVerified there are no live charges and no payouts to third parties — sandbox only.
- Charges flow through the platform. Every charge is made on Franco Pay’s own US Stripe account and held in a Stripe Treasury financial account. Payouts go through Stripe Global Payouts — Trinidad & Tobago to a local bank in TTD, Antigua & Barbuda by wire in XCD — or Remitly for Dominica. Nothing Stripe does not allow.
- This v1 is NOT a PayFac. Franco Pay charges on its own account and pays verified businesses. It does not open processing sub-accounts for third parties.
- Money-transmission licensing may apply. The model “third parties charge and receive payouts through Franco Pay” may require a money-transmission licence or Stripe approval depending on the jurisdiction. Global Payouts is for businesses that already hold the licences to move money — the legal burden falls on the platform. This page is not legal advice.
- Prohibited and restricted categories apply (adult, drugs, weapons, unlicensed gambling, counterfeit, fraud, money-transmission P2P, payment facilitation, and others) and sanctioned countries (CU, IR, KP, SY) are blocked. A prohibited business is rejected with 403 PROHIBITED_BUSINESS; a sanctioned country with 403 SANCTIONED_COUNTRY.
- Franco Pay login requires a Franco Food account with a verified email and a verified phone number. There is no standalone Franco Pay registration.
- Supported currencies include USD, EUR, GBP, CAD, AUD, NZD, CHF, JPY, MXN, BRL, TTD, XCD, DOP, JMD, BBD and BSD. Non-USD charges need a frozen FX rate at charge time.
Need a key or integration help? Write to team@francoapp.com. Franco Pay support documentation: Franco Pay.
Franco Food