Payouts - Carbn Connect

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

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>'

const response = await fetch(
  'https://api.carbnconnect.com/payment/api/v1/payout/balances/{user_id}',
  {
    method: 'GET',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': '<api-key>',
    },
  }
);

const { balances } = await response.json();
// e.g. [{ currency: 'PHP', amount: '506.54' }]

Typical response (trimmed):

{
  "balances": [
    {
      "currency": "PHP",
      "amount": "506.54"
    }
  ]
}

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"
    }
  }'

const response = await fetch(
  'https://api.carbnconnect.com/payment/api/v1/payout',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': '<api-key>',
    },
    body: JSON.stringify({
      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',
      },
    }),
  }
);

const payout = await response.json();
// Save payout.id and customer_payout_id for reconciliation

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"
  }
}

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>'

const response = await fetch(
  'https://api.carbnconnect.com/payment/api/v1/payout/{payout_id}',
  {
    method: 'GET',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': '<api-key>',
    },
  }
);

const payout = await response.json();
// payout.status === 'INITIATED' | 'PAYOUT_PROCESSED' | 'FAILED' (depending on rail)

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"
}

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.

​Prerequisites

​Payout lifecycle

​Payout statuses

Prerequisites

Payout lifecycle

Payout statuses