Partner API reference

Base URL: https://api.sendeasy.cash/v1

All request and response bodies are JSON. Unknown fields in a request body are rejected with a 400 — the API will not silently drop a typo.

A "Collection" debits an end-customer’s Benin mobile money account and credits the result into your own sendEasy wallet. A "Remittance" debits your sendEasy wallet and pays a recipient out via mobile money (Benin), a Nigerian bank account, a cross-border mobile wallet (UEMOA/CEMAC/DR Congo), or sendEasy's international bank-transfer network (reaching every country that network supports, including Nigeria as an alternative to the virtual-account rail). Collections never convert currency. A Remittance only converts when you send sourceCurrency (your wallet currency) that differs from currency (the payout currency); otherwise amount and currency are the same on both sides.

Every operations-API request needs an X-Api-Key header. Get your keys from the partner dashboard after you register — a SANDBOX key is issued automatically and works immediately; a PRODUCTION key can be created once your account is approved (status ACTIVE).

Sandbox keys start with pk_test_, production keys with pk_live_. Treat both as secrets: don’t commit them, and only ever send them from your backend, never from a browser or mobile app.

The dashboard itself (register, login, API key and webhook management) uses a separate Bearer JWT — that’s for the humans on your team managing the integration, not for the operations API your servers call.

Every operation created with a SANDBOX key is fully simulated — it never touches a real mobile money network or bank rail, and never shares sendEasy’s own production credentials or quota. A simulated collection or remittance sits at PENDING for a few seconds (so your polling and webhook-handling code gets genuinely exercised), then resolves to SUCCESS.

This means you can build and test your entire integration — requests, polling, webhooks, error handling — without ever moving real money or needing real recipient accounts.

Every error — validation failures, auth failures, not-found, or an unexpected server error — is returned with the same envelope shape.

partnerReference is your own idempotency key, required on both create-collection and create-remittance and unique per partner (not globally). If you POST the same partnerReference twice, the second call returns the already-existing operation unchanged instead of creating a duplicate — safe to retry a request after a timeout without double-charging or double-paying out.

The reference field in the response (e.g. "PO-2026-00012345") is sendEasy’s own identifier — use it, not partnerReference, when calling GET /partner/operations/:reference.

sendEasy fees are charged on top of the amount, never taken out of it. Fees are set per service — collection, disbursement, remittance, and bills — and can differ per partner; ask your account manager for your rates. A fee can be flat, a percentage, or tiered by amount, with an optional minimum and maximum.

Collections: the full amount is credited to your wallet, then the fee is debited as a separate entry. Remittances: your wallet is debited the principal plus the fee. When sourceCurrency differs from currency, the principal is the converted amount plus your agreed FX margin, and the fee is calculated on that principal in your wallet currency. A failed remittance refunds the same total. Bills: the fee is added to the amount owed to the biller. Every operation response includes feeAmount, and cross-currency remittances also include sourceCurrency, sourceAmount, fxRate, and fxMarginPercent.

Returns exactly what an operation would cost before you create it, so you can decide whether to proceed. Nothing is debited or created, and quotes are not binding: the FX rate and your pricing may change between a quote and the actual request.

For type COLLECTION, send amount and currency; the response has fee and netCredit. For type REMITTANCE, also send destinationRailType (and sourceCurrency to price a conversion); the response has principalDebit, fxRate, fxMarginPercent, fee, and totalDebit in your wallet currency.

Returns the current exchange rate for a currency pair as it applies to you. from is your wallet currency and to is the payout currency. baseRate is how many units of to you get for 1 unit of from before your margin; fxMarginPercent is your agreed margin; effectiveRate is the rate after the margin (baseRate divided by 1 + margin). The rate is indicative: the binding figures are returned when you create the remittance (see sourceCurrency), and a POST /partner/quote gives the exact debit for a specific amount.

Optionally pass destinationRailType if your margin differs by payout type. An unsupported pair returns a 400.

Debits an end-customer’s Benin mobile money account for the given amount and credits your sendEasy wallet once it succeeds. Processing happens asynchronously — the response is always status PENDING; poll GET /partner/operations/:reference or wait for a collection.succeeded / collection.failed webhook.

Debits your sendEasy wallet and pays a recipient out. Which fields are required depends on destinationRailType — the four supported types are shown below. Like collections, this is asynchronous: the response is always status PENDING, and the debit is reserved upfront so two concurrent requests can’t overdraw your balance.

If your wallet balance is too low, you get an immediate 400 (“Insufficient {currency} balance”). In the rare case the balance check races with another debit, the reservation itself is refused and the operation fails asynchronously (status FAILED, a remittance.failed webhook) rather than returning a synchronous error.

Requires momoOperator and momoNumber. destinationCountry must be "BJ" — mobile money payout is not yet available for other countries.

Requires bankCode and bankAccountNumber (bankName is recommended for display purposes). destinationCountry must be "NG".

For payouts to a mobile wallet outside Benin/Nigeria — UEMOA (BF, CI, GW, ML, NE, SN, TG), CEMAC (CM, CF, TD, CG, GQ, GA), or DR Congo (CD). Requires momoNumber as the recipient’s wallet number, plus the real individual sender’s identity: senderFullName, senderPhoneNumber, and senderCountryOfResidence are mandatory (this rail requires the actual sender’s KYC, not a corporate/partner identity) — senderNationality, senderDateOfBirth, senderIdType, senderIdExpiryDate, senderAddress, and senderCity are optional but recommended, since missing fields may cause the payout to require manual review. recipientComplianceProfile is an optional free-form object for any additional recipient-side compliance fields.

For payouts straight into a real bank account anywhere sendEasy's international bank-transfer network reaches — this rail isn't limited to one destinationCountry the way VIRTUAL_ACCOUNT_BANK and MOBILE_MONEY are, it covers every country sendEasy lists banks for, and you choose it explicitly per request rather than sendEasy auto-selecting it. In Nigeria it's an alternative to VIRTUAL_ACCOUNT_BANK — some accounts route better one way or the other; try the other rail if a specific recipient bank is rejected.

Requires bankCode, bankName, and bankAccountNumber (bankName must match the exact label from sendEasy's bank list for that country — a mismatched label is rejected), plus momoNumber as the recipient's own mobile number. Recipient identity fields (recipientNationality as an ISO-2 code such as "NG", recipientAddress, recipientIdType in uppercase such as "PASSPORT", recipientIdNumber) are only required for destination countries that ask for them — they are not required for Nigeria — and when sent, recipientAddress must be a normal, valid street address (street, area, city), not a placeholder. Because the payer is a real individual, also send the sender context where you have it: senderFullName, senderPhoneNumber, senderCountryOfResidence, senderAddress, senderCity, senderStateProvince, senderPostalCode, plus remittancePurpose, sourceOfFunds, and relationshipSender (for example "Family Maintenance", "Salary", "Brother"). Missing mandatory details for the chosen corridor are rejected with a 400 naming the missing fields. Amounts are paid out in whole currency units, and each corridor enforces its own minimum and maximum per transaction (for Nigeria, NGN 1,500 to NGN 4,878,000); amounts outside the limits are rejected. originCountry (ISO-2, defaults to "BJ") tells sendEasy which of its own settlement markets the payment is considered to originate from — it is not the recipient's country and does not need to match destinationCountry.

Looks up a collection or remittance by its sendEasy reference (the value returned as reference when you created it). status is one of PENDING, PROCESSING, SUCCESS, FAILED — poll this if you’d rather not rely on webhooks, or use it to reconcile after a webhook arrives.

Pays a bill (utility, pay-TV, school fees, airtime top-up) on behalf of your own end-customer, drawing on your same prefunded sendEasy wallet — SANDBOX and PRODUCTION keys share one balance, only the rail call is simulated in sandbox. Unlike collections and remittances, bill payments are synchronous end to end: sendEasy's biller integrations don't have a pending/polling window, so both steps below return the final result directly, with no webhook involved.

The flow is two calls. First, inquire prices the bill and returns a BillPayment in status INQUIRED with the amount now known — nothing is debited yet. params is a loose object whose required keys depend on billerCode (a card number for CANALPLUS, a meter number for SBEE_PREPAID, a student ID for UP_SCOLARITE/UAC_SCOLARITE, and so on) — see your dashboard's sandbox console for the full per-biller field list, mirrored from the consumer app's own form.

Confirms a previously-inquired bill payment (status must still be INQUIRED — inquire again if it's gone stale). This debits your wallet for the priced amount plus sendEasy's own margin (if any), then settles the bill synchronously and resolves to SUCCESS or REFUNDED in the same response — there is nothing to poll or wait on. :id is the id field returned by inquire, not partnerReference (bill payments have no partner-supplied idempotency key — retry the whole inquire → pay sequence if a request times out). There is no request body: unlike the consumer and agent apps, a Partner API call carries no transaction PIN — your X-Api-Key is the only authorization this endpoint checks.

If the biller rejects or errors on the payment, your wallet is refunded automatically and the response comes back with status REFUNDED and a failureReason — you don't need to reverse anything yourself.

Two billers need a browse-before-price step with no BillPayment row created yet: GET /partner/bill-payments/canalplus/offers?numCard=... lists available Canal+ bouquets, and GET /partner/bill-payments/airtime/products?msisdn=...&productType=... lists eligible airtime/data/combo/pin products for a beneficiary number.

For bills, GET /partner/bill-payments/:id/quote on an inquired payment returns amount, operationCost, fee, and totalDebit before you call pay. GET /partner/bill-payments lists your own bill payments (paginated, newest first); GET /partner/bill-payments/:id fetches one. POST /partner/bill-payments/:id/refresh-status re-checks status with the biller network for a payment stuck in PROCESSING — in practice this should never be needed given the synchronous flow above, but it exists as a safety net for the rare case your connection drops between the debit and the biller's response.

Configure a webhook URL from the partner dashboard (or override it per-request with callbackUrl). sendEasy POSTs a signed JSON payload to it when an operation reaches a terminal state — event is one of collection.succeeded, collection.failed, remittance.succeeded, remittance.failed.

Deliveries are retried up to 8 times with exponential backoff (starting at 10s) until your endpoint returns a 2xx. Every attempt — success or failure — is visible in the delivery log on your dashboard, and you can manually trigger a redelivery from there.

Verify every delivery: recompute the HMAC-SHA256 of "{timestamp}.{raw request body}" using your webhook signing secret (shown once at registration, or rotatable from the dashboard), and compare it to the v1 value in X-SendEasy-Signature using a constant-time comparison. Reject anything that doesn’t match, and reject deliveries with a timestamp too far in the past to guard against replay.

Collections (debiting an end-customer) are Benin-only today, via MTN, Moov, Celtiis, or a linked sendEasy wallet.

Remittance payouts: mobile money is Benin-only; the virtual-account bank rail (VIRTUAL_ACCOUNT_BANK) is Nigeria-only; the cross-border mobile-wallet rail covers Burkina Faso, Côte d’Ivoire, Guinea-Bissau, Mali, Niger, Senegal, Togo, Cameroon, Central African Republic, Chad, Republic of the Congo, Equatorial Guinea, Gabon, and DR Congo; the international bank-transfer rail (BANK_TRANSFER_INTERNATIONAL) reaches every country sendEasy's bank-transfer network supports — including Nigeria, as an alternative to VIRTUAL_ACCOUNT_BANK. Reach out to sendEasy support if you need a corridor that isn’t listed — coverage expands regularly.