Franco Pay API — Developer Documentation

Accept card payments through Franco Pay from your own website or system. Authorize first, capture on delivery. The platform charges on its own US Stripe account and pays verified businesses through Stripe Global Payouts (Trinidad & Tobago and Antigua & Barbuda) or Remitly (Dominica). Caribbean businesses can charge customers in more than 130 countries, in more than 130 currencies — build your own app or website on this API.

✅ 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.

ScopeAllows
charges:readRead and list charges
charges:writeCreate, capture and cancel charges
refunds:writeCreate refunds
transactions:readList ledger transactions
balance:readRead 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.

MethodPathAuthDescription
GET/v1/cardsNo authAccepted card brands by country (see Accepted cards below). No auth — works even before launch.
POST/v1/public/chargesAPI key / ID tokenCreate 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/:idAPI key / ID tokenGet one public-origin charge. Scope charges:read.
GET/v1/public/chargesAPI key / ID tokenList public-origin charges, newest first, paginated. Filter ?status= (authorized, awaiting_payment, captured, canceled, refunded, partially_refunded). Scope charges:read.
POST/v1/public/charges/:id/captureAPI key / ID tokenCapture an authorized charge. Optional amount for a partial capture (never more than authorized; default: full amount). Scope charges:write.
POST/v1/public/charges/:id/cancelAPI key / ID tokenCancel an authorization. No money moves. Scope charges:write.
POST/v1/public/refundsAPI key / ID tokenRefund a captured charge. Idempotency-Key required. Fees are never returned. Scope refunds:write.
GET/v1/public/transactionsAPI key / ID tokenList ledger movements for public-origin charges only, paginated. Filters ?from= / ?to= (ISO dates). Scope transactions:read.
GET/v1/public/balanceAPI key / ID tokenBusiness wallet balance: available, pending, authorized. Scope balance:read.
GET/v1/public/feesAPI key / ID tokenCommission rates and the minimum charge (see Fees). Scope balance:read.
POST/v1/public/keysID token onlyMint a public API key (ff_live_ or ff_test_). The full key is returned ONCE. Max 5 active keys.
GET/v1/public/keysID token onlyList the business’s keys — prefix only, never the full key.
POST/v1/public/keys/:id/revokeID token onlyRevoke a key. Rejected immediately; revoking twice returns the same object.
POST/v1/public/webhooksID token onlyRegister an HTTPS endpoint to receive Franco Pay events. Idempotency-Key required. The HMAC secret is returned ONCE.
GET/v1/public/webhooksID token onlyList webhook registrations — never the secret.
POST/v1/public/webhooks/:id/deactivateID token onlyDeactivate a webhook registration. The endpoint stops receiving events; the secret is kept for reactivation by admin.
GET/v1/public/webhooks/deliveriesID token onlyList delivery attempts (delivered / failed, status code, error, attempt). Filter ?event=.
GET/v1/public/auditID token onlyAudit 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.

RoleCanCannot
OwnerEverything — charges, invoices, refunds, withdrawals, team, keys—
ManagerCharges, invoices, refunds, client licences, readsWithdrawals, team members, API keys
StaffCharges, basic readsInvoices, refunds, withdrawals, team members, API keys
ViewerBasic reads onlyCharges, 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

MethodPathAuthDescription
POST/v1/chargesAPI key / ID tokenCreate a charge. Idempotency-Key required.
POST/v1/charges/:id/captureAPI key / ID tokenCapture an authorized charge
POST/v1/charges/:id/confirm-deliveryAPI key / ID tokenConfirm delivery for a charge
POST/v1/charges/:id/cancelAPI key / ID tokenCancel an authorization
GET/v1/quoteAPI key / ID tokenGet a fee quote

Invoices

MethodPathAuthDescription
POST/v1/invoicesAPI key / ID tokenCreate an invoice. Idempotency-Key required.
POST/v1/invoices/:id/sendAPI key / ID tokenSend an invoice. Idempotency-Key required.
POST/v1/invoices/:id/cancelAPI key / ID tokenCancel an invoice. Idempotency-Key required.
POST/v1/invoices/:id/remindAPI key / ID tokenRemind an invoice. Idempotency-Key required.

Refunds

MethodPathAuthDescription
POST/v1/refundsAPI key / ID tokenCreate a refund. Idempotency-Key required.

Withdrawals

MethodPathAuthDescription
POST/v1/withdrawalsAPI key / ID tokenRequest a withdrawal. Idempotency-Key required.
GET/v1/withdrawalsAPI key / ID tokenList withdrawals
GET/v1/withdrawals/detailsAPI key / ID tokenGet payout details
POST/v1/withdrawals/detailsAPI key / ID tokenSave payout details
POST/v1/withdrawals/global-payoutsAPI key / ID tokenRequest a Global Payouts withdrawal
POST/v1/withdrawals/:id/transitionAdmin onlyMove a withdrawal. Admin only.
GET/v1/withdrawals/:id/cardAdmin onlyGet a withdrawal’s full card number. Admin only.

Payouts (Global Payouts / Treasury)

MethodPathAuthDescription
POST/v1/payouts/recipientsAPI key / ID tokenCreate a Global Payouts recipient
GET/v1/payouts/recipientsAPI key / ID tokenList Global Payouts recipients
GET/v1/payouts/recipients/:idAPI key / ID tokenGet a Global Payouts recipient
GET/v1/payouts/recipients/:id/bankAdmin onlyGet a recipient’s full bank account number
GET/v1/payouts/treasuryAdmin onlyGet Treasury and funding status

Balance & transactions

MethodPathAuthDescription
GET/v1/balanceAPI key / ID tokenGet wallet balance
GET/v1/transactionsAPI key / ID tokenList transactions
GET/v1/pending-paymentsID token onlyList my pending pay-on-delivery payments

Customers & clients

MethodPathAuthDescription
GET/v1/customersAPI key / ID tokenList customers
GET/v1/customers/:idAPI key / ID tokenGet a customer
GET/v1/customers/:id/transactionsAPI key / ID tokenList a customer’s transactions
POST/v1/clients/:id/license-verificationAPI key / ID tokenSubmit a client license verification
GET/v1/clients/:id/licenseAPI key / ID tokenGet a client license status
GET/v1/clients/pending-reviewAdmin onlyList clients pending review. Admin only.
POST/v1/clients/:id/license-verifyAdmin onlyApprove or reject a client license. Admin only.

Businesses & verification

MethodPathAuthDescription
GET/v1/businessesAPI key / ID tokenList businesses
GET/v1/businesses/:idAPI key / ID tokenGet a business
POST/v1/businesses/:id/verificationAPI key / ID tokenSubmit a business verification
GET/v1/businesses/pending-reviewAdmin onlyList businesses pending review. Admin only.
POST/v1/businesses/:id/verifyAdmin onlyApprove or reject a verification. Admin only.

Disputes

MethodPathAuthDescription
GET/v1/disputesAPI key / ID tokenList disputes

Team (memberships)

MethodPathAuthDescription
GET/v1/memberships/mineID token onlyMy businesses and roles
GET/v1/membershipsAPI key / ID tokenList team members of the business
POST/v1/membershipsID token onlyInvite a team member. Owner only.
POST/v1/memberships/:id/roleID token onlyChange a team member’s role. Owner only.
POST/v1/memberships/:id/removeID token onlyRemove a team member. Owner only.

Settings (admin)

MethodPathAuthDescription
GET/v1/settingsAdmin / SupportRead Franco Pay settings
POST/v1/settingsAdmin onlyUpdate Franco Pay settings. Admin only.
POST/v1/webhooks/outAdmin onlyRegister an outbound webhook. Idempotency-Key required. Admin only.

No-auth & Stripe inbound

MethodPathAuthDescription
GET/v1/healthNo authHealth check — no auth
GET/v1/cardsNo authAccepted card brands by country — no auth
POST/v1/webhooks/stripeStripe signatureStripe 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&currency=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 }

FieldTypeMeaning
amountnumberTop-up amount, 1–500, in wallet_topup.currency.
idemstringIdempotency key (8–64 chars). Same key + same body returns the same PaymentIntent — never a second charge or credit.
wallet_topup.recipientEmailstringFriend’s Franco Food email. Either this or recipientPhone is required.
wallet_topup.recipientPhonestringFriend’s Franco Food phone.
wallet_topup.currencystringCurrency you pay in (USD, TTD or XCD). Defaults to your own wallet currency.

Auth: Authorization: Bearer <Firebase ID token>.

Response

FieldMeaning
id / client_secretStripe 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.
publishableKeyStripe 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

HTTPCodeMeaning
404RECIPIENT_NOT_FOUNDNo Franco Food user with that email or phone — no charge was made.
422RECIPIENT_NOT_ELIGIBLEThe friend’s email/phone is not verified for Franco Pay — no charge was made.
422FX_RATE_REQUIREDNo frozen rate for this currency pair — the top-up is rejected, never estimated.
429RATE_LIMITEDMore 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>

FieldMeaning
foundtrue when a Franco Food user matches the email or phone.
uid / name / currencyThe 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.
isSelftrue 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

FieldTypeMeaning
recipientUidstringThe recipient’s uid (from the lookup). Either this, recipientEmail or recipientPhone is required.
recipientEmailstringThe recipient’s Franco Food email.
recipientPhonestringThe recipient’s Franco Food phone.
amountnumberAmount to send, in the sender’s wallet currency. Minimum US$5 equivalent.
currencystringOptional. Must match the sender’s wallet currency when given — anything else is rejected.
notestringOptional 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

FieldMeaning
idTransfer id — the same id on both ledger entries and in both histories.
senderId / receiverId / receiverNameWho sent it and who received it.
amount / currencyWhat the sender sent, in the sender’s currency (debited from their wallet).
receiverAmount / receiverCurrencyWhat the receiver was credited, in THEIR currency — the converted amount when the currencies differ.
fxRateThe frozen rate used (receiver units per 1 sender unit). 1 when the currencies match.
fee0 — transfers are free.
statuscompleted — the money moves in one atomic transaction.
senderBalanceThe sender’s new available balance.
createdAtISO 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

HTTPCodeMeaning
400AMOUNT_INVALIDThe amount is not a positive number.
400BELOW_MINIMUMThe amount is below the US$5 equivalent minimum.
400SELF_TRANSFERThe sender and the recipient are the same user.
400VALIDATIONMissing recipient, missing Idempotency-Key, or a currency that does not match the sender’s wallet.
403FORBIDDENAn 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).
404RECIPIENT_NOT_FOUNDNo Franco Food user with that email/phone/uid, or the account is a guest — no money moved.
422INSUFFICIENT_AVAILABLEThe sender’s available balance does not cover the amount (pending, reserve and authorized money cannot be sent).
422FX_RATE_REQUIREDNo frozen rate for this currency pair, or the receiver has no registered currency — the transfer is rejected, never estimated.
429RATE_LIMITEDMore than 5 transfers from this user in one minute.
409IDEMPOTENCY_CONFLICTThe 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.

FeeRate
Franco commission — unverified business5%
Franco commission — verified business (ffPayVerified)3.5%
Volume tier — unverified, over US$10,000 / month4%
Volume tier — verified, over US$10,000 / month3%
Minimum chargeUS$5
Reserve held back0%
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.

CountryAccepted ✓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

LimitValue
Requests per minute, per API key120 (a per-key override can change it; exceeding it returns 429 RATE_LIMITED)
Pagination — default page size20
Pagination — maximum page size (?limit=)100
Pagination — cursorPass the nextCursor from the previous response as ?cursor=. The cursor is the document id of the last item on the previous page.
Minimum chargeUS$5
Active API keys per business5
Authorization window7 days — an authorization expires after 7 days if never captured.
Anti-structuringIdentical 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:

EventWhen
charge.authorizedA charge was authorized
charge.capturedA charge was captured
charge.refundedA charge was refunded
charge.canceledAn authorization was canceled
withdrawal.requestedA withdrawal was requested
withdrawal.completedA withdrawal completed
invoice.sentAn 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.

HTTPCodeMeaning
503PUBLIC_API_DISABLEDThe public API is disabled — returned only while the API flag is off.
403SCOPE_FORBIDDENThe key does not have the scope this endpoint needs.
403KEY_NOT_PUBLICAn internal key (kind internal) called the public API. Internal keys never enter the public API.
403LIVE_REQUIRES_VERIFICATIONA live call requires a verified business (ffPayVerified). Use a test key, or verify the business first.
409KEY_LIMIT_REACHEDThe business already has 5 active API keys. Revoke one before minting another.
400INVALID_SCOPEThe requested scope list is empty or contains an unknown scope.
404NOT_FOUNDThe resource does not exist, or belongs to another business (ownership is never leaked).
429RATE_LIMITEDMore than 120 requests per minute for this key. Wait and retry.
400VALIDATIONMissing or invalid data — including a missing Idempotency-Key where one is required, and rejected fields (kind, orderId, driverId) on public charges.
400AMOUNT_INVALIDThe amount is invalid (for example, zero or negative).
400BELOW_MINIMUMThe charge is below the US$5 minimum.
409CHARGE_NOT_AUTHORIZEDThe charge is not in authorized status — it cannot be captured, canceled or refunded in its current state.
409REFUND_EXCEEDSThe refund is larger than the remaining captured amount.
409IDEMPOTENCY_CONFLICTThe Idempotency-Key was already used with a different body.
401UNAUTHORIZED / INVALID_KEYAuthentication is required, or the API key is invalid or unknown.
401KEY_REVOKEDThe API key has been revoked.
403FORBIDDENYou do not have access to this business.
403PERMISSION_DENIEDYour team role does not allow this. Ask the business owner to change your role (see Team roles in the Dashboard API).
409MEMBER_EXISTSThis user is already a member of this business.
404MEMBER_NOT_FOUNDNo Franco Food account with that email. The user must create a Franco Food account first.
403FRANCO_PAY_EMAIL_NOT_VERIFIEDThe team member's email is not verified yet. They must verify their email in Franco Food first.
403FRANCO_PAY_NO_REGISTRATIONFranco Pay requires a Franco Food account. Create a Franco Food account first, with a verified email and phone.
403READ_ONLY_ROLESupport agents have read-only access and cannot move money.
403BUSINESS_NOT_VERIFIEDThe business is not verified for this operation.
500INTERNALAn 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" and sandbox: 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 / fromAvailable are 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.