Escrow as an API for your marketplace. L'entiercement en API pour votre marketplace.

AuthenticationAuthentification

Base URLs: live https://api.fiappay.com, sandbox https://sandbox.api.fiappay.com; every path below hangs off them. Every request carries a bearer key. Content type is always JSON; the maximum request body is 1 MiB.URL de base : production https://api.fiappay.com, sandbox https://sandbox.api.fiappay.com ; tous les chemins ci-dessous s'y rattachent. Chaque requête porte une clé Bearer. Le type de contenu est toujours JSON ; le corps de requête est limité à 1 Mio.

Authorization: Bearer <your_api_key>
Content-Type: application/json

• ▸Keys are compared in constant time against a stored SHA-256 hash. The plaintext key is never stored, never logged and cannot be recovered by anyone, including us.Les clés sont comparées en temps constant à un hachage SHA-256 stocké. La clé en clair n'est jamais stockée, jamais journalisée et ne peut être récupérée par personne, nous compris.
• ▸A missing, unknown or suspended client's key all return the same 401. Account status is deliberately not probeable.Une clé absente, inconnue ou appartenant à un client suspendu renvoie le même 401. Le statut du compte n'est volontairement pas sondable.
• ▸If a client is suspended, its in-flight escrows keep settling normally and keep emitting webhooks. Money already in escrow is never stranded by an account action.Si un client est suspendu, ses entiercements en cours continuent de se dénouer normalement et d'émettre des webhooks. L'argent déjà entiercé n'est jamais bloqué par une action sur le compte.
• ▸Rotating a key invalidates the old one immediately. Plan for a short deploy window when you rotate.La rotation d'une clé invalide l'ancienne immédiatement. Prévoyez une courte fenêtre de déploiement lors d'une rotation.
• ▸Keep the key server-side. It must never reach a browser, a mobile app bundle, or a repository.Conservez la clé côté serveur. Elle ne doit jamais atteindre un navigateur, un paquet d'application mobile ou un dépôt de code.
• ▸Rate limits, per client: 120 requests a minute overall and 20 escrow creations a minute (each one sends a real Mobile Money prompt). Over the limit you get 429 rate_limited with a Retry-After header in seconds; nothing was done, so retry after the delay with the same Idempotency-Key. Failed authentication is also limited per source IP: after 30 bad or missing keys in a minute, that address gets 429 before its key is even checked, so fix a rejected key instead of retrying it in a loop.Limites de débit, par client : 120 requêtes par minute au total et 20 créations d'entiercement par minute (chacune envoie une vraie invite Mobile Money). Au-delà, vous recevez 429 rate_limited avec un en-tête Retry-After en secondes ; rien n'a été fait, réessayez donc après ce délai avec la même Idempotency-Key. Les échecs d'authentification sont aussi limités par adresse IP source : après 30 clés invalides ou absentes en une minute, cette adresse reçoit 429 avant même la vérification de sa clé ; corrigez donc une clé refusée au lieu de la réessayer en boucle.

Conventions and errorsConventions et erreurs

Escrow status vocabularyVocabulaire des statuts

Error shapeFormat des erreurs

{ "error": { "code": "invalid_request", "message": "…human readable…" } }

Codes: unauthorized (401), invalid_request (400), not_found (404), conflict (409), idempotency_key_reused (422), rate_limited (429), upstream_error (502), internal_error (500). A request the server cannot parse gets a plain-text response instead: malformed JSON 400, missing Content-Type: application/json 415, a missing or wrongly typed field 422, a body over 1 MiB 413, and a request over 30 s 408. Branch on error.code only when the body has one.Codes : unauthorized (401), invalid_request (400), not_found (404), conflict (409), idempotency_key_reused (422), rate_limited (429), upstream_error (502), internal_error (500). Une requête que le serveur ne peut pas analyser reçoit à la place une réponse en texte brut : JSON invalide 400, Content-Type: application/json absent 415, champ manquant ou de mauvais type 422, corps de plus de 1 Mio 413, requête de plus de 30 s 408. Ne vous fiez à error.code que lorsque le corps en contient un.

Vendor endpointsPoints d'accès vendeurs

Registers a payee, or idempotently returns the one you already registered. The account name is checked against the Mobile Money holder record. That check is advisory only and never routes money by itself: a mismatch does not block onboarding, it is information for you to act on.Enregistre un bénéficiaire, ou renvoie de façon idempotente celui que vous avez déjà enregistré. Le nom du compte est confronté au titulaire déclaré chez l'opérateur Mobile Money. Cette vérification est purement indicative et ne détermine jamais à elle seule un acheminement de fonds : une divergence ne bloque pas l'enrôlement, c'est une information sur laquelle vous décidez.

{
  "external_ref": "panier-seller-123",
  "whatsapp_phone": "237670000000",
  "momo_number": "237677000000",
  "account_name": "Jean Dupont"
}

{
  "vendor_code": "V-8X2A",
  "kyc_status": "verified"
}

• ▸kyc_status is verified (holder name matches), name_mismatch (it differs; worth a look before you let them sell), or unverified (the lookup was unavailable).vaut verified (le nom du titulaire correspond), name_mismatch (il diffère ; à examiner avant de laisser vendre) ou unverified (la vérification était indisponible).
• ▸Idempotent on your external_ref: repeating it with the same phones returns the existing vendor with 200 OK, as the full vendor object shown under GET below.Idempotent sur votre external_ref : le répéter avec les mêmes numéros renvoie le vendeur existant avec 200 OK, sous la forme de l'objet vendeur complet présenté pour GET ci-dessous.
• ▸All four fields are required, at most 128 characters each. Phone numbers are digits only with an optional leading +, 8 to 15 digits; a pre-2016 8-digit Cameroon number (without the leading 6) gets 400 naming the corrected number. external_ref must not have leading or trailing spaces.Les quatre champs sont obligatoires, 128 caractères au plus chacun. Les numéros ne contiennent que des chiffres, avec un + initial facultatif, de 8 à 15 chiffres ; un ancien numéro camerounais à 8 chiffres (sans le 6 initial) renvoie 400 en indiquant le numéro corrigé. external_ref ne doit pas commencer ni finir par des espaces.
• ▸A WhatsApp number belongs to the first platform that registers it. Another platform registering the same number gets 409 conflict. Reusing one of your own external_refs for a different phone also gets 409, and so does registering a known WhatsApp number with a different payout number: payout numbers can only be changed by FiapPay.Un numéro WhatsApp appartient à la première plateforme qui l'enregistre. Une autre plateforme enregistrant le même numéro obtient 409 conflict. Réutiliser l'un de vos external_ref pour un autre téléphone renvoie également 409, tout comme enregistrer un numéro WhatsApp connu avec un numéro de versement différent : seul FiapPay peut modifier un numéro de versement.

Reads back one of your vendors. Someone else's code, or an unknown one, returns 404. account_name is the name on the Mobile Money account when the holder lookup succeeded (even on name_mismatch), and the name you sent only when it was unverified.Relit l'un de vos vendeurs. Le code d'un autre client, ou un code inconnu, renvoie 404. account_name est le nom du titulaire du compte Mobile Money lorsque la vérification a abouti (même en cas de name_mismatch), et le nom que vous avez envoyé seulement lorsqu'il est unverified.

{
  "vendor_code": "V-8X2A",
  "external_ref": "panier-seller-123",
  "whatsapp_phone": "237670000000",
  "momo_number": "237677000000",
  "account_name": "JEAN DUPONT",
  "kyc_status": "verified"
}

Escrow endpointsPoints d'accès entiercements

Prices every leg, creates the escrow, and fires the buyer's Mobile Money prompt for the payer charge. Send an Idempotency-Key header (1–255 printable ASCII characters, no spaces, not starting with ext:, else 400). Retries are already deduplicated on external_ref; the key also returns your result without spending create budget, and rejects reuse with different parameters.Valorise chaque poste, crée l'entiercement et déclenche l'invite Mobile Money de l'acheteur pour le montant à sa charge. Envoyez un en-tête Idempotency-Key (1 à 255 caractères ASCII imprimables, sans espace, ne commençant pas par ext:, sinon 400). Les relances sont déjà dédoublonnées sur external_ref ; la clé renvoie en plus votre résultat sans consommer de budget de création, et refuse une réutilisation avec des paramètres différents.

Idempotency-Key: 9f1c…-opaque

{
  "external_ref": "panier-order-9981",
  "payer_phone": "237600000001",
  "payee_vendor_code": "V-8X2A",
  "base_amount": 100000,
  "currency": "XAF",
  "payer_commission": 0,
  "payee_commission": 10000,
  "metadata": { "order_id": "9981" }
}

{
  "escrow_id": "5f2b…-uuid",
  "external_ref": "panier-order-9981",
  "status": "AwaitingPayment",
  "base_amount": 100000,
  "payer_charge": 102500,
  "payee_payout": 87500,
  "fee_total": 5000,
  "fee_bps": 500,
  "payer_commission": 0,
  "payee_commission": 10000,
  "refund_amount": 96000,
  "payout_status": null,
  "currency": "XAF",
  "created_at": "…",
  "updated_at": "…"
}

FieldsChamps

ValidationValidation

• ▸currency must bedoit valoir "XAF".
• ▸base_amount must sit inside the configured range (defaults: 100 to 1,000,000 FCFA).doit se situer dans la plage configurée (par défaut : 100 à 1 000 000 FCFA).
• ▸payee_vendor_code must be one of your vendors, else 400. A vendor FiapPay has suspended gets 409 (its existing escrows still settle).doit être l'un de vos vendeurs, sinon 400. Un vendeur suspendu par FiapPay renvoie 409 (ses entiercements existants se dénouent normalement).
• ▸external_ref, payer_phone, payee_vendor_code, base_amount and currency are required; strings at most 128 characters, external_ref without leading or trailing spaces. payer_phone follows the vendor phone rules above.external_ref, payer_phone, payee_vendor_code, base_amount et currency sont obligatoires ; chaînes de 128 caractères au plus, external_ref sans espaces au début ni à la fin. payer_phone suit les règles des numéros de vendeur ci-dessus.
• ▸Each commission must sit within your commission cap (30% of base_amount by default, set per client, hard ceiling 50%), else 400 invalid_request naming the cap. The cap is a safety bound on how much of a vendor's payout one request can redirect. It is not a rule about what you may charge.Chaque commission doit respecter votre plafond de commission (30 % de base_amount par défaut, défini par client, plafond absolu 50 %), sinon 400 invalid_request en nommant le plafond. Ce plafond borne la part du versement d'un vendeur qu'une seule requête peut rediriger. Ce n'est pas une règle sur ce que vous pouvez facturer.
• ▸A payee_commission that would leave the vendor with nothing is refused with 400.Une payee_commission qui ne laisserait rien au vendeur est refusée avec 400.

Returns the same snapshot shape, reflecting live status. Note that payee_payout is the vendor's payout net of your payee_commission, not the base price. Use this for reconciliation, not as a substitute for webhooks.Renvoie le même format d'instantané, avec le statut à jour. Notez que payee_payout est le versement au vendeur net de votre payee_commission, et non le prix de base. Utilisez ce point d'accès pour le rapprochement, pas en remplacement des webhooks.

Body: empty {}. This call is server-authoritative: by making it, your platform asserts that the buyer confirmed delivery in your app. It replaces the WhatsApp Release PIN for API escrows, so guard it in your own product the way you would guard a payout button.Corps : {} vide. Cet appel fait foi côté serveur : en l'émettant, votre plateforme atteste que l'acheteur a confirmé la livraison dans votre application. Il remplace le code PIN de libération WhatsApp pour les entiercements API : protégez-le dans votre produit comme vous protégeriez un bouton de versement.

• ▸Atomically moves FundsLocked → Released under a double-spend guard and disburses payee_payout.Fait passer atomiquement FundsLocked → Released sous garde anti-double-dépense et verse payee_payout.
• ▸Idempotent: releasing an already-released escrow returns 200 and does not pay twice.Idempotent : libérer un entiercement déjà libéré renvoie 200 sans payer deux fois.
• ▸AwaitingPayment (not funded),(non financé), Refunded, Expired orou Disputed → 409. A vendor with no Mobile Money number on file also gets 409.Un vendeur sans numéro Mobile Money enregistré renvoie également 409.
• ▸If the immediate payout is rejected by the network, the escrow is still Released and the payout is retried by our reconcile worker. The escrow.released webhook fires when the money actually lands, not when you called. payout_status shows where it is: null before release, then pending → sent, or failed (retried automatically) or ambiguous (outcome unknown, reviewed by an operator before any retry).Si le versement immédiat est rejeté par l'opérateur, l'entiercement reste tout de même Released et le versement est relancé par notre processus de rapprochement. Le webhook escrow.released se déclenche quand l'argent arrive réellement, pas au moment de votre appel. payout_status indique où il en est : null avant la libération, puis pending → sent, ou failed (relancé automatiquement) ou ambiguous (issue inconnue, examinée par un opérateur avant toute relance).
• ▸Your commissions accrue to your settlement balance once the vendor payout succeeds.Vos commissions sont créditées sur votre solde de règlement dès que le versement au vendeur a réussi.

Body: empty {}. Atomically moves FundsLocked → Refunded under the same double-spend guard and returns refund_amount to the buyer's Mobile Money, priced under the refund terms snapshotted on the escrow.Corps : {} vide. Fait passer atomiquement FundsLocked → Refunded sous la même garde anti-double-dépense et restitue refund_amount sur le Mobile Money de l'acheteur, valorisé selon les conditions de remboursement figées sur l'entiercement.

• ▸Idempotent: refunding an already-refunded escrow returns 200 and does not refund twice.Idempotent : rembourser un entiercement déjà remboursé renvoie 200 sans rembourser deux fois.
• ▸AwaitingPayment orou Expired → 409 (nothing was collected, so there is nothing to refund).(rien n'a été encaissé, donc rien à rembourser). Released orou Disputed → 409.
• ▸Your payee_commission never accrues on a refund. Your payer_commission is either returned to the buyer or kept for you, according to your client terms.Votre payee_commission n'est jamais acquise en cas de remboursement. Votre payer_commission est soit restituée à l'acheteur, soit conservée pour vous, selon les conditions de votre compte.
• ⚠Limitation: a failed refund transfer is not auto-retried. Our reconcile worker only retries vendor payouts. The escrow is marked Refunded and an operator alert is raised so a human completes the transfer. No escrow.refunded webhook is sent in that case: the 200 response is your signal. If a buyer tells you a refund has not arrived, contact us rather than calling the endpoint again.Limite : un transfert de remboursement échoué n'est pas relancé automatiquement. Notre processus de rapprochement ne relance que les versements aux vendeurs. L'entiercement est marqué Refunded et une alerte opérateur est levée pour qu'un humain achève le transfert. Aucun webhook escrow.refunded n'est envoyé dans ce cas : la réponse 200 fait foi. Si un acheteur signale un remboursement non reçu, contactez-nous plutôt que de rappeler le point d'accès.

Idempotency: how not to charge twiceIdempotence : comment ne pas débiter deux fois

Networks retry, timeouts lie, and a user will tap Pay twice. This API is built on the assumption that duplicates will arrive.Les réseaux relancent, les délais d'attente mentent, et un utilisateur appuiera deux fois sur Payer. Cette API est conçue en partant du principe que des doublons arriveront.

• ▸Same Idempotency-Key (per client) with the same parameters → 200 with the escrow's current snapshot (it may have been funded since). A replay never spends your create budget. The same key with different parameters (reference, phone, vendor, amounts or currency) → 422 idempotency_key_reused, and nothing is created.Même Idempotency-Key (par client) avec les mêmes paramètres → 200 avec l'instantané actuel de l'entiercement (il a pu être financé depuis). Une relance ne consomme jamais votre budget de création. La même clé avec des paramètres différents (référence, téléphone, vendeur, montants ou devise) → 422 idempotency_key_reused, et rien n'est créé.
• ▸Same external_ref (per client) with the same parameters → the existing escrow is returned with 200. With different parameters → 409 conflict: a new order needs a new external_ref.Même external_ref (par client) avec les mêmes paramètres → l'entiercement existant est renvoyé avec 200. Avec des paramètres différents → 409 conflict : une nouvelle commande exige un nouvel external_ref.
• ▸The buyer's Mobile Money prompt is fired at most once per external_ref.L'invite Mobile Money de l'acheteur est déclenchée au plus une fois par external_ref.
• ▸A concurrent in-flight duplicate returns 409 conflict. Retry once the first has settled.Un doublon concurrent en cours renvoie 409 conflict. Réessayez une fois le premier dénoué.
• ▸If CamPay definitely rejects the prompt, the escrow is rolled back (nothing is left half-created) and you get 502 upstream_error; you may safely retry the same external_ref. If the call to CamPay times out, the prompt may have reached the buyer, so the escrow is kept and returned 201 AwaitingPayment: a retry can never prompt twice. It locks if the payment arrives and expires after 48 h if not.Si CamPay refuse clairement l'invite, l'entiercement est annulé (rien ne reste à moitié créé) et vous recevez 502 upstream_error ; vous pouvez réessayer sans risque le même external_ref. Si l'appel à CamPay expire, l'invite a pu atteindre l'acheteur : l'entiercement est donc conservé et renvoyé 201 AwaitingPayment, et une relance ne peut jamais solliciter deux fois. Il passe à FundsLocked si le paiement arrive et expire au bout de 48 h sinon.

Webhooks

When an API-created escrow changes state, we POST a signed event to your webhook_url, which must be https://. Delivery goes through a durable outbox and a retrying dispatcher, so it is at-least-once: you must dedupe on the event id.Lorsqu'un entiercement créé via l'API change d'état, nous envoyons un événement signé à votre webhook_url, qui doit être en https://. La distribution passe par une file durable et un répartiteur avec relances : elle est donc au moins une fois, et vous devez dédoublonner sur l'identifiant d'événement.

For API escrows, escrow.funds_locked replaces the WhatsApp notifications: the buyer and vendor get no message and no Release PIN. In a normal API flow you cancel with POST …/refund rather than through a dispute.Pour les entiercements API, escrow.funds_locked remplace les notifications WhatsApp : l'acheteur et le vendeur ne reçoivent ni message ni code PIN. Dans un flux API normal, vous annulez avec POST …/refund plutôt que par un litige.

Likewise, escrow.payment_failed replaces the WhatsApp "payment failed" message: tell the buyer yourself, and create a new escrow with a new external_ref if they want to try again. Expired is terminal with one rare exception: if the buyer's money arrives late anyway, the escrow is revived and you receive escrow.funds_locked. We never keep a payment we cannot hold in escrow; if you had cancelled the order, release or refund it as usual.De même, escrow.payment_failed remplace le message WhatsApp « paiement échoué » : prévenez vous-même l'acheteur, et créez un nouvel entiercement avec un nouvel external_ref s'il souhaite réessayer. Expired est définitif, à une rare exception près : si l'argent de l'acheteur arrive malgré tout en retard, l'entiercement est réactivé et vous recevez escrow.funds_locked. Nous ne conservons jamais un paiement que nous ne pouvons pas placer en entiercement ; si vous aviez annulé la commande, libérez ou remboursez-la comme d'habitude.

Content-Type: application/json
X-FiapPay-Timestamp: <unix seconds>
X-FiapPay-Signature: sha256=<hex hmac>
X-FiapPay-Event-Id: <uuid>
X-FiapPay-Event-Type: escrow.released

{
  "id": "e2c1…-uuid",
  "type": "escrow.released",
  "created_at": "2026-09-03T05:31:00.482913507+00:00",
  "data": {
    "escrow_id": "5f2b…-uuid",
    "external_ref": "panier-order-9981",
    "status": "Released",
    "base_amount": 100000,
    "payer_charge": 102500,
    "payee_payout": 87500,
    "fee_total": 5000,
    "fee_bps": 500,
    "payer_commission": 0,
    "payee_commission": 10000,
    "refund_amount": 96000,
    "currency": "XAF"
  }
}

Verifying a deliveryVérifier une livraison

ts = headers["X-FiapPay-Timestamp"]
if not is_integer(ts) or abs(now_unix() - int(ts)) > 300:
    return 401   # stale or replayed
# over the timestamp + "." + the RAW request bytes, exactly as received
expected = "sha256=" + hex(hmac_sha256(webhook_secret, ts + "." + raw_request_body))
if not constant_time_equals(expected, headers["X-FiapPay-Signature"]):
    return 401
if seen(headers["X-FiapPay-Event-Id"]):
    return 200   # already handled, idempotent
process(body); mark_seen(id); return 200

• ▸Sign and verify over the raw bytes, before any JSON parsing or re-serialisation. Re-encoding the body will break the signature.Signez et vérifiez sur les octets bruts, avant toute analyse JSON ou re-sérialisation. Ré-encoder le corps casse la signature.
• ▸Compare in constant time. A plain string equality here is a timing oracle.Comparez en temps constant. Une simple égalité de chaînes constitue ici un oracle temporel.
• ▸The timestamp is inside the signature, so a captured delivery cannot be replayed later or re-dated. Each retry is signed afresh with its own send time. Reject anything more than 5 minutes off your clock, and keep that clock NTP-synced.L'horodatage fait partie de la signature : une livraison interceptée ne peut être ni rejouée plus tard ni redatée. Chaque relance est signée à nouveau avec sa propre heure d'envoi. Rejetez tout écart de plus de 5 minutes avec votre horloge, et synchronisez celle-ci par NTP.
• ▸Answer 2xx to acknowledge. Any non-2xx or timeout triggers retry with exponential backoff (base 30s, capped at 1h, up to 12 attempts) before the delivery is marked failed.Répondez 2xx pour accuser réception. Tout code non-2xx ou délai dépassé déclenche une relance à intervalle exponentiel (base 30 s, plafonné à 1 h, jusqu'à 12 tentatives) avant que la livraison ne soit marquée en échec.
• ▸A missing signing key never causes an event to be sent unsigned or dropped: deliveries wait in the outbox without using up retry attempts. An event's created_at is RFC 3339 with fractional seconds (3, 6 or 9 digits); an escrow's created_at and updated_at are UTC YYYY-MM-DD HH:MM:SS.Une clé de signature indisponible n'entraîne jamais l'envoi d'un événement non signé ni son abandon : les livraisons patientent dans la file sans consommer de tentatives. Le created_at d'un événement est au format RFC 3339 avec fractions de seconde (3, 6 ou 9 chiffres) ; les created_at et updated_at d'un entiercement sont en UTC au format YYYY-MM-DD HH:MM:SS.
• ▸Events can arrive out of order (each retries on its own schedule), and a payload is a snapshot taken when the event was queued. When an event contradicts what you hold, treat GET /v1/escrows/{id} as the source of truth. Acknowledge within 10 s (our timeout) and do slow work after replying.Les événements peuvent arriver dans le désordre (chacun est relancé selon son propre calendrier), et une charge utile est un instantané pris au moment de la mise en file. Si un événement contredit ce que vous détenez, GET /v1/escrows/{id} fait foi. Accusez réception en moins de 10 s (notre délai) et effectuez les traitements longs après avoir répondu.

Fees and your commissionsFrais et vos commissions

The list price is 5% of base_amount, split 2.5% onto the buyer and 2.5% off the vendor (fee_bps: 500). Volume tiers are agreed per platform and reported as fee_bps on every snapshot. The rate is snapshotted at creation, so a later tier change never re-prices an escrow that is already in flight. It is computed server-side and is never client-supplied.Le tarif public est de 5 % de base_amount, réparti en 2,5 % ajoutés à l'acheteur et 2,5 % déduits du vendeur (fee_bps: 500). Les paliers de volume sont convenus par plateforme et reportés dans fee_bps sur chaque instantané. Le taux est figé à la création : un changement de palier ultérieur ne revalorise jamais un entiercement déjà en cours. Il est calculé côté serveur et n'est jamais fourni par le client.

Your commission, stacked on topVotre commission, ajoutée par-dessus

The same 100,000 FCFA item under four different marketplace models. Every row balances exactly.Le même article à 100 000 FCFA selon quatre modèles de marketplace. Chaque ligne s'équilibre exactement.

Read the second row carefully: with a vendors-only commission, your buyer's experience is identical to having no marketplace commission at all: they still pay 102,500. Your 10,000 comes out of the vendor's side.Lisez attentivement la deuxième ligne : avec une commission côté vendeurs uniquement, l'expérience de votre acheteur est identique à celle sans aucune commission : il paie toujours 102 500. Vos 10 000 proviennent du côté vendeur.

How your commissions are settledComment vos commissions sont réglées

Your commissions are carved out of money FiapPay already holds, so they never touch the escrow flow and never delay a vendor. They are earned when an escrow is released and credited to your settlement balance once the vendor payout succeeds. On a refund your payee_commission is never earned; your payer_commission is credited only if your terms keep it.Vos commissions sont prélevées sur des fonds que FiapPay détient déjà : elles n'interfèrent donc jamais avec le flux d'entiercement et ne retardent jamais un vendeur. Elles sont acquises à la libération d'un entiercement et créditées sur votre solde de règlement dès que le versement au vendeur a réussi. En cas de remboursement, votre payee_commission n'est jamais acquise ; votre payer_commission n'est créditée que si vos conditions la conservent.

Because FiapPay never absorbs rail costs, your balance carries the rail costs attributable to your own commissions:FiapPay n'absorbant jamais les coûts de rail, votre solde supporte les coûts de rail imputables à vos propres commissions :

Settlement is monthly: we transfer the largest amount your balance covers after the 1% payout cost (for example 10,100 → 10,000 sent + 100 cost) to your settlement Mobile Money number and record it. Refund debits can take your balance below zero; nothing is paid out until later commissions bring it back above zero. The ledger is append-only, and a statement is available on request at any time.Le règlement est mensuel : nous transférons le montant le plus élevé que couvre votre solde après le coût de versement de 1 % (par exemple 10 100 → 10 000 envoyés + 100 de coût) vers votre numéro Mobile Money de règlement et l'enregistrons. Les débits liés aux remboursements peuvent rendre votre solde négatif ; rien n'est versé tant que de nouvelles commissions ne l'ont pas ramené au-dessus de zéro. Le registre est en ajout seul, et un relevé est disponible sur demande à tout moment.

Limits and things we would rather you heard from usLimites et points que nous préférons vous dire nous-mêmes

• ⚠Refunds are not auto-retried. Vendor payouts are; refunds are not. A failed refund raises an operator alert and is completed by hand.Les remboursements ne sont pas relancés automatiquement. Les versements aux vendeurs le sont, pas les remboursements. Un remboursement en échec lève une alerte opérateur et est complété manuellement.
• ⚠Vendor phone ownership is global. The first platform to register a WhatsApp number owns it; another platform registering the same number gets 409. If you and another FiapPay platform share a seller, talk to us.La propriété d'un numéro de vendeur est globale. La première plateforme à enregistrer un numéro WhatsApp le détient ; une autre plateforme obtient 409. Si vous partagez un vendeur avec une autre plateforme FiapPay, contactez-nous.
• ⚠Unfunded escrows cannot be refunded. Nothing was collected, so there is nothing to return. Let an unpaid escrow expire instead.Un entiercement non financé ne peut pas être remboursé. Rien n'a été encaissé, donc rien à restituer. Laissez plutôt expirer un entiercement impayé.
• ⚠Payment failures come to you, not the buyer. On API escrows the buyer gets no WhatsApp message or retry link; you receive escrow.payment_failed and handle the retry in your own app.Les échecs de paiement vous sont signalés, pas à l'acheteur. Sur les entiercements API, l'acheteur ne reçoit ni message WhatsApp ni lien de relance ; vous recevez escrow.payment_failed et gérez la relance dans votre propre application.
• ⚠Throughput is finite and we will tell you the number. Escrow creation is serialised. Before you point sustained high-volume traffic at us, agree a rate with us so we can provision for it. We would rather size the platform for your launch than discover it during one.Le débit est fini et nous vous en donnerons le chiffre. La création d'entiercements est sérialisée. Avant de diriger vers nous un trafic soutenu à fort volume, convenez d'un débit avec nous afin que nous puissions dimensionner l'infrastructure. Nous préférons la préparer pour votre lancement que la découvrir pendant celui-ci.
• ⚠Escrows are XAF and Cameroon Mobile Money only at v1: MTN and Orange, via CamPay. Other markets are on the roadmap, not in this contract.Les entiercements sont en XAF et uniquement sur le Mobile Money camerounais en v1 : MTN et Orange, via CamPay. D'autres marchés figurent dans la feuille de route, pas dans ce contrat.

Go-live checklistCheck-list de mise en production

Work through this before you route a real customer's money.Parcourez cette liste avant de faire transiter l'argent d'un vrai client.

• ☐The API key lives only in server-side configuration, never in a client bundle, never in git.La clé d'API réside uniquement dans la configuration côté serveur, jamais dans un paquet client, jamais dans git.
• ☐Webhook signatures are verified over raw bytes, in constant time, and unsigned or badly-signed deliveries are rejected.Les signatures de webhook sont vérifiées sur les octets bruts, en temps constant, et toute livraison non signée ou mal signée est rejetée.
• ☐Events are deduped on X-FiapPay-Event-Id; replaying the same event twice does not ship an order twice.Les événements sont dédoublonnés sur X-FiapPay-Event-Id ; rejouer deux fois le même événement n'expédie pas deux fois une commande.
• ☐You treat escrow.funds_locked, not the create response, as proof of payment.Vous considérez escrow.funds_locked, et non la réponse de création, comme preuve de paiement.
• ☐Every create carries a stable external_ref and a per-attempt Idempotency-Key.Chaque création porte un external_ref stable et un Idempotency-Key propre à la tentative.
• ☐Amounts are handled as integers end to end. No floats, no rounding, anywhere in your stack.Les montants sont traités en entiers de bout en bout. Aucun flottant, aucun arrondi, nulle part dans votre pile.
• ☐Your checkout shows the buyer the charge, the vendor payout and refund_amount before they approve.Votre tunnel d'achat affiche à l'acheteur le montant débité, le versement au vendeur et refund_amount avant validation.
• ☐The release call is behind real authorisation in your app: it is the API's payout button.L'appel de libération est protégé par une véritable autorisation dans votre application : c'est le bouton de versement de l'API.
• ☐You have run at least one real end-to-end escrow, including a refund, at the minimum amount, on phones you control.Vous avez exécuté au moins un entiercement réel de bout en bout, remboursement compris, au montant minimum, sur des téléphones que vous contrôlez.
• ☐Your logs record escrow ids and order ids, never phone numbers, account names or full request bodies.Vos journaux enregistrent les identifiants d'entiercement et de commande, jamais les numéros de téléphone, les noms de compte ni les corps de requête complets.