Receiving payouts
Let other Customers pay you with your Receiving Code, choose where the money lands, and follow each incoming payment.
Other Customers of the platform can pay you without ever seeing your bank details. You give them your Receiving Code; they add you as a Beneficiary with it; and you follow every payment they send you as an Incoming Payout.
How it works
- Receiving Code: a short code such as
RC-7KQ2-M9XDthat you hand to whoever pays you. One code is in force at a time. - Receiving Account: one of your own verified bank accounts. Payments sent with your code are paid into it.
- Incoming Payout: a payment another Customer sends you, as you see it: who sent it, how much arrives, and where it stands.
The sender sees your name and the last four characters of your account. You see the sender's name and what you receive. Neither sees more.
Set up receiving
The two writes need an API key with customer:beneficiaries:write; reading needs customer:read. Your account must be active.
Register your own account
Create a Beneficiary of kind own_account with a proof_reference, as in Beneficiaries. Lina, a business in Pakistan, registers her company's PKR account. It starts as pending_verification; our compliance team checks the proof and verifies it.
Choose it as your Receiving Account
Once it is verified, name it with PUT /v1/receiving/account.
Get your code
POST /v1/receiving/code puts a code in force. If you chose an account first, a code is created with it.
Share the code
The sender enters it with POST /v1/beneficiaries/link. See Link another Customer.
curl -X PUT "$APEX_BASE_URL/v1/receiving/account" \
-H "Authorization: Bearer $APEX_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "beneficiary_id": "e2b9c7a1-4d3f-4e8a-b6c5-1f0a9d8e7c62" }'
curl -X POST "$APEX_BASE_URL/v1/receiving/code" \
-H "Authorization: Bearer $APEX_API_KEY"All three routes, GET /v1/receiving included, answer the same view:
{
"code": "RC-7KQ2-M9XD",
"account": {
"beneficiary_id": "e2b9c7a1-4d3f-4e8a-b6c5-1f0a9d8e7c62",
"name": "Lina Textiles Ltd",
"country": "PK",
"asset": "PKR",
"account_hint": "6789"
},
"credit_asset": ""
}| Field | Meaning |
|---|---|
code | Your Receiving Code, or null until you have one. |
account | Your Receiving Account, or null until you choose one. It also reads null if that account was blocked after you chose it. |
credit_asset | When set, payments sent with your code are credited to your platform balance in this asset. Empty otherwise. See below. |
PUT /v1/receiving/account takes only one of your own own_account Beneficiaries that is verified. Anything else answers receiving_account_invalid (422).
Where the money lands
delivered_to | What happens |
|---|---|
bank_account | The payment is paid out to your Receiving Account. This is the default. |
balance | The payment is credited to your platform balance, in your own country's currency. |
In some countries, payments sent to you with your code are credited to your balance instead of being paid out. credit_asset in GET /v1/receiving tells you whether that applies to you, for example "PKR". You do not choose it, and it applies only to your own country:
- With
credit_assetset, you need no Receiving Account to be paid. You need one only to withdraw the balance to your bank. - If your Receiving Account is in another country or currency than the credit, payments go to that account and
credit_assetis empty.
A credited payment appears in GET /v1/balances like a deposit. You can send it on, or withdraw it to your own account with an ordinary Payout. See Balances and deposits.
The sender sees the same thing in advance: its Beneficiary for you carries delivers_to, and its Payout carries delivered_to.
Follow incoming payments
GET /v1/incoming-payouts lists the payments sent to you, newest first. GET /v1/incoming-payouts/{id} answers one. Both need customer:read.
curl "$APEX_BASE_URL/v1/incoming-payouts?limit=20" \
-H "Authorization: Bearer $APEX_API_KEY"{
"items": [
{
"id": "8d4f2b6a-0c1e-4a7b-9e3d-5f6a7b8c9d01",
"sender_name": "Tom Trading LLC",
"amount": { "amount": "277664.5", "asset": "PKR" },
"purpose": "supplier",
"status": "delivered",
"delivered_to": "bank_account",
"account_hint": "6789",
"created_at": "2026-11-12T10:00:20Z",
"delivered_at": "2026-11-12T12:01:30Z",
"updated_at": "2026-11-12T12:01:30Z"
}
],
"next_cursor": "MjAyNi0xMS0xMlQxMDowMDoyMFp8OGQ0ZjJiNmE"
}| Field | Meaning |
|---|---|
sender_name | The sending Customer's legal name when it sent the payment. |
amount | What you receive. |
purpose | The purpose the sender declared: services, payroll, supplier, goods or digital_goods. |
status | Where the payment stands, below. |
delivered_to | bank_account or balance. |
account_hint | The last four characters of the account it is paid into. Empty for balance. |
delivered_at | When it reached your account or balance; null until then. |
Paging works as on GET /v1/payouts: limit from 1 to 100 (default 50), and cursor set to the previous page's next_cursor, which is absent on the last page.
Statuses
status | Meaning |
|---|---|
on_the_way | The sender's money is set aside and the payment is on its way to you. |
delivered | It arrived: paid into your account, or credited to your balance. |
delayed | It is taking longer than expected. Our operations team is on it; it may still arrive, or be returned. Nothing for you to do. |
returned | It went back to the sender and will not arrive. Ask the sender if you expected it. |
A payment appears only once the sender's money is set aside for it. While it waits for the sender's own approval or funds, and if the sender cancels it before then, you never see it. You never see what the sender paid, its fees, the route or the Providers. An id that is not one of your visible incoming payments answers payout_not_found (404).
Notifications
- Webhook: subscribe an endpoint to
payout.incoming.updated. You get the Incoming Payout above each time itsstatuschanges. See Webhooks. - Email: when a payment is delivered, your people get an email naming the sender, the amount and where it landed.
Replace your code
Call POST /v1/receiving/code again. The old code stops working for new senders at once. Customers who already added you keep paying you as before. If your code leaked or you no longer want new senders to find you with it, replace it.
Errors
| Code | Status | Cause |
|---|---|---|
receiving_account_invalid | 422 | The Beneficiary is not one of your own verified own_account Beneficiaries. |
payout_not_found | 404 | No incoming payment of yours with this id is visible. |
bad_limit, bad_cursor | 422 | limit is outside 1 to 100, or cursor is not one this API answered. |
customer_suspended | 403 | Your account is suspended and can only read. |
customer_not_active | 403 | Your account is not open yet, or is closed. |