Skip to Content
Apex Settlement

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-M9XD that 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:

200 OK
{
  "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": ""
}
FieldMeaning
codeYour Receiving Code, or null until you have one.
accountYour Receiving Account, or null until you choose one. It also reads null if that account was blocked after you chose it.
credit_assetWhen 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_toWhat happens
bank_accountThe payment is paid out to your Receiving Account. This is the default.
balanceThe 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_asset set, 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_asset is 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"
200 OK
{
  "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"
}
FieldMeaning
sender_nameThe sending Customer's legal name when it sent the payment.
amountWhat you receive.
purposeThe purpose the sender declared: services, payroll, supplier, goods or digital_goods.
statusWhere the payment stands, below.
delivered_tobank_account or balance.
account_hintThe last four characters of the account it is paid into. Empty for balance.
delivered_atWhen 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

statusMeaning
on_the_wayThe sender's money is set aside and the payment is on its way to you.
deliveredIt arrived: paid into your account, or credited to your balance.
delayedIt is taking longer than expected. Our operations team is on it; it may still arrive, or be returned. Nothing for you to do.
returnedIt 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 its status changes. 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

CodeStatusCause
receiving_account_invalid422The Beneficiary is not one of your own verified own_account Beneficiaries.
payout_not_found404No incoming payment of yours with this id is visible.
bad_limit, bad_cursor422limit is outside 1 to 100, or cursor is not one this API answered.
customer_suspended403Your account is suspended and can only read.
customer_not_active403Your account is not open yet, or is closed.

Next steps

On this page