Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.carbn.xyz/llms.txt

Use this file to discover all available pages before exploring further.

Payouts let you send funds from your Carbn balance to a user’s bank account in local currency. Key API reference pages:

​
Prerequisites

Before you implement payouts, make sure:
  • Users are onboarded and KYC‑verified (status active).
  • Funds are available in the payout currency for the user.
  • API key is configured with payment permissions (see Authentication).
  • The destination bank account or wallet (for example INSTAPAY) is supported for the corridor.

​
Payout lifecycle

1

Check the user’s payout balance

API Reference: /payouts/get-payout-balances-by-user
curl --location 'https://api.carbnconnect.com/payment/api/v1/payout/balances/{user_id}' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>'
Typical response (trimmed):
{
  "balances": [
    {
      "currency": "PHP",
      "amount": "506.54"
    }
  ]
}
2

Create a payout

API Reference: /payouts/create-payout
curl --location 'https://api.carbnconnect.com/payment/api/v1/payout' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "user_id": "9973efd0-410c-4b1a-991c-5a00f1581734",
    "currency": "php",
    "customer_payout_id": "491595e0-2d40-4aa3-9f3d-4e8cdd79511e",
    "amount": "20",
    "recipient_details": {
      "bank_name": "gotyme",
      "account_holder_name": "Chelsea Mae Esguerra",
      "recipient_account_number": "019794249552"
    }
  }'
Successful response (key fields):
{
  "id": "052471e2-1819-448f-ad74-03f237c1dfd6",
  "currency": "php",
  "rail": "INSTAPAY",
  "amount": 20,
  "status": "INITIATED",
  "user_id": "9973efd0-410c-4b1a-991c-5a00f1581734",
  "customer_payout_id": "491595e0-2d40-4aa3-9f3d-4e8cdd79511e",
  "rail_fee": 10,
  "account_details": {
    "bank_name": "gotyme",
    "account_holder_name": "Chelsea Mae Esguerra",
    "recipient_account_number": "019794249552"
  }
}
3

Track payout status

API Reference: /payouts/get-payout
curl --location 'https://api.carbnconnect.com/payment/api/v1/payout/{payout_id}' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>'
Example (processed):
{
  "id": "052471e2-1819-448f-ad74-03f237c1dfd6",
  "currency": "php",
  "rail": "INSTAPAY",
  "reference": "051567",
  "amount": 20.0,
  "status": "PAYOUT_PROCESSED",
  "user_id": "9973efd0-410c-4b1a-991c-5a00f1581734",
  "customer_payout_id": "491595e0-2d40-4aa3-9f3d-4e8cdd79511e",
  "rail_fee": 10.0,
  "account_details": {
    "bank_name": "gotyme",
    "account_holder_name": "Chelsea Mae Esguerra",
    "recipient_account_number": "019794249552"
  },
  "created_at": "2026-03-13T16:32:17.604935Z",
  "updated_at": "2026-03-13T16:32:46.364880Z"
}
4

Subscribe to payout webhooks

For real-time updates, configure a webhook with the PAYOUT event category (see Configure Webhooks).When enabled, Carbn will send payout status changes (for example from INITIATED to PAYOUT_PROCESSED) to your webhook endpoint.

​
Payout statuses

INITIATED

Payout has been created and queued for processing by the rail.

PAYOUT_PROCESSED

Rail has confirmed the payout; funds are considered delivered.

FAILED

Payout could not be completed (for example, rail or account error); check logs and webhooks for details.