Collect in the US, pay out in Kenya

Collect USD from US contributors, be paid the net into your USD account, convert it to KES, and pay it out in Kenya in KES or USD — all live, on one credential.

Your contributors are in the US. Your recipients are in Kenya. This is the whole of that journey, in three parts.

One Collections credential covers every part: conversions:read and conversions:write come with Collections, and transfers:write, transfers:read and confirmations:write are issued to every partner regardless of product — see Products and scopes — so a Collections account does not need a second product or a second credential to convert USD and send a bank transfer.

Part 1 — collecting in the US (live)

Open a collection for each payment you expect — one collection takes one deposit, so a contributor who pays twice needs two. The full request and response, depositMessage, and what a read-back returns are all in Open a collection — this is the one call unique to this journey:

POST /v1/collections
Content-Type: application/json

{
  "currency": "USD",
  "partnerReference": "campaign-2026-09",
  "payerLabel": "September community appeal"
}

The response carries the reference and deposit details to hand your contributor. Return the deposit details verbatim. Do not reformat the account number, and do not substitute your own name for beneficiaryName — these are the values the contributor's bank matches on.

The depositMessage is how the money finds you

Most accounts share one account number across many references, and depositMessage is what separates them. Your contributor has to include it in the transfer — the wire memo, or the ACH description.

A deposit that arrives without it matches no collection. It is not credited, and it does not appear on the collection at any status; it has to be reconciled by hand or returned. Put the code in front of your payer at the moment they set the transfer up, not in a follow-up email.

Some accounts are configured with a dedicated account number per collection instead, and then no code is needed — depositMessage is simply absent. Branch on whether the field is present rather than assuming one shape.

Read the deposit back

When the money lands, the collection carries the deposit. Read it back with GET /v1/collections/{id} — or list them filtered by reference, status or date — and once a deposit has landed it carries these fields:

Field	What it is
`reference`	the one you handed out
`status`	where the collection is, e.g. `received`
`grossAmount`	what the contributor sent, as a decimal string
`feeAmount`	the disclosed fee
`netAmount`	what is paid into your account

Be told when the net is paid to you

Once the deposit is attributed and your fee applied (received), we pay the netAmount into your USD account. The collection reads crediting while that payout is in flight and credited once it has settled — at which point we send the collection.received webhook. If a payout did not go through, the collection returns to received and the payout is retried. Open a collection has the full lifecycle.

Read the collection back as well as listening for the webhook: the webhook can be delayed or dead-lettered, and the collection's status carries the same information.

GET /v1/balances shows the USD you have been paid under usd, beside your KES account under kes. That usd.available is what you can convert or pay out next.

Part 2 — convert with `POST /v1/conversions` (live)

Once the net is in your USD account, convert it to KES. One call takes the USD from your USD account and pays the KES into your KES account:

POST /v1/conversions
Content-Type: application/json

{
  "from": "USD",
  "to": "KES",
  "amount": "98.50",
  "partnerReference": "campaign-2026-09-payout",
  "idempotencyKey": "cnv-campaign-2026-09"
}

The answer is a 202 with the conversion's id. Wait for conversion.settled, or read GET /v1/conversions/{id} until status is settled; its target is the KES now in your KES account. Convert USD to KES has the quote, the full read-back, and what each failure reason means.

Part 3 — pay out in Kenya, in KES or USD (live)

KES, on any rail. The converted KES is in your KES account, so paying it out is an ordinary KES transfer — M-PESA, PesaLink, RTGS, EFT, SWIFT or on-us. transfers:write is already on your credential — see Send money from your KES account for the request shape, which is not specific to Collections in any way.

USD, without converting. You do not have to convert to pay out. POST /v1/transfers with amount.currency "USD" pays from your USD account, in USD, over RTGS or EFT to a USD account at a Kenyan bank, or over SWIFT to a USD account abroad. M-PESA, PesaLink and on-us transfers take KES only. The consent step, caps, idempotency and the transfer.settled / transfer.failed webhooks are the ones every transfer has; the rail-by-currency table and what differs for USD are in Send money: Paying out USD. A batch can pay USD too, one currency per batch.

In sandbox

Every part runs on simulated money in sandbox: a simulated deposit credits your simulated USD balance, a conversion moves simulated USD to simulated KES, and a KES or USD payout is paid from the simulated balance it names. GET /v1/balances reports those simulated figures. See Testing in sandbox.

Availability

All three parts are live: opening a collection and being paid the net into your USD account with a collection.received webhook (Part 1), converting it to KES with a conversion.settled webhook (Part 2), and paying it out in KES or USD (Part 3).