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

> Integrate fiat payouts to bank accounts using Carbn

Payouts let you send funds from your Carbn balance to a user's bank account in local currency.

Key API reference pages:

* [Create Payout](/api-reference/payouts/create-payout)
* [Get Payout](/api-reference/payouts/get-payout)
* [Get Payout Balances by User](/api-reference/payouts/get-payout-balances-by-user)

***

## 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](/api-reference/authentication)).
* The destination **bank account or wallet** (for example INSTAPAY) is supported for the corridor.

***

## Payout lifecycle

<Steps>
  <Step title="Check the user’s payout balance">
    API Reference: **[/payouts/get-payout-balances-by-user](/api-reference/payouts/get-payout-balances-by-user)**

    <CodeGroup>
      ```bash cURL theme={null}
      curl --location 'https://api.carbnconnect.com/payment/api/v1/payout/balances/{user_id}' \
        --header 'Content-Type: application/json' \
        --header 'x-api-key: <api-key>'
      ```

      ```javascript JavaScript theme={null}
      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' }]
      ```
    </CodeGroup>

    Typical response (trimmed):

    ```json theme={null}
    {
      "balances": [
        {
          "currency": "PHP",
          "amount": "506.54"
        }
      ]
    }
    ```
  </Step>

  <Step title="Create a payout">
    API Reference: **[/payouts/create-payout](/api-reference/payouts/create-payout)**

    <CodeGroup>
      ```bash cURL theme={null}
      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"
          }
        }'
      ```

      ```javascript JavaScript theme={null}
      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
      ```
    </CodeGroup>

    Successful response (key fields):

    ```json theme={null}
    {
      "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"
      }
    }
    ```
  </Step>

  <Step title="Track payout status">
    API Reference: **[/payouts/get-payout](/api-reference/payouts/get-payout)**

    <CodeGroup>
      ```bash cURL theme={null}
      curl --location 'https://api.carbnconnect.com/payment/api/v1/payout/{payout_id}' \
        --header 'Content-Type: application/json' \
        --header 'x-api-key: <api-key>'
      ```

      ```javascript JavaScript theme={null}
      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)
      ```
    </CodeGroup>

    Example (processed):

    ```json theme={null}
    {
      "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"
    }
    ```
  </Step>

  <Step title="Subscribe to payout webhooks">
    For real-time updates, configure a webhook with the `PAYOUT` event category (see [Configure Webhooks](/documentation/getting-started/configure-webhook)).

    When enabled, Carbn will send payout status changes (for example from `INITIATED` to `PAYOUT_PROCESSED`) to your webhook endpoint.
  </Step>
</Steps>

***

## Payout statuses

<AccordionGroup>
  <Accordion title="INITIATED" icon="clock" defaultOpen>
    <Info>Payout has been created and queued for processing by the rail.</Info>
  </Accordion>

  <Accordion title="PAYOUT_PROCESSED" icon="circle-check" defaultOpen>
    <Check>Rail has confirmed the payout; funds are considered delivered.</Check>
  </Accordion>

  <Accordion title="FAILED" icon="triangle-alert" defaultOpen>
    <Danger>Payout could not be completed (for example, rail or account error); check logs and webhooks for details.</Danger>
  </Accordion>
</AccordionGroup>