> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tabsglobal.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Initiate a Payout

> Disburse bank transfers locally or internationally with bank-grade idempotency protection.

Executes an outbound bank transfer or international payout. Supports idempotency via the `Idempotency-Key` header.

### Scopes required

`payouts:write` or `*`

### Headers

<ParamField header="Authorization" type="string" required>
  Bearer API secret key formatted as `Bearer sk_live_...` or `Bearer sk_test_...`.
</ParamField>

<ParamField header="Idempotency-Key" type="string">
  Unique UUID v4 string to prevent duplicate transfers during network retries.
</ParamField>

### Body

<ParamField body="amount" type="number">
  Amount in major currency units for same-currency payouts (e.g. `25000` for 25,000 NGN).
</ParamField>

<ParamField body="sourceCurrency" type="string">
  Source wallet currency debited (e.g. `NGN`, `USD`). Defaults to `NGN`.
</ParamField>

<ParamField body="payoutCurrency" type="string">
  Destination currency received by the beneficiary (e.g. `NGN`, `USD`). Defaults to `sourceCurrency`.
</ParamField>

<ParamField body="recipientName" type="string" required>
  Full legal name of the beneficiary.
</ParamField>

<ParamField body="bankCode" type="string">
  3-digit CBN bank code (for Nigerian NIP payouts).
</ParamField>

<ParamField body="accountNumber" type="string">
  10-digit NUBAN account number (for Nigerian NIP payouts).
</ParamField>

<ParamField body="recipientAddress" type="string">
  Recipient physical address (required for international wires).
</ParamField>

<ParamField body="routing" type="string">
  9-digit ABA routing number (for US ACH/Wire payouts).
</ParamField>

<ParamField body="iban" type="string">
  International Bank Account Number (for EUR SEPA payouts).
</ParamField>

<ParamField body="bic" type="string">
  SWIFT / BIC code.
</ParamField>

<ParamField body="sortCode" type="string">
  6-digit UK sort code (for GBP Faster Payments).
</ParamField>

<ParamField body="quoteId" type="string">
  Guaranteed quote ID from `POST /v1/fx/quotes` if performing a cross-currency payout.
</ParamField>

<ParamField body="narration" type="string">
  Transfer memo or narration displayed on recipient's bank statement.
</ParamField>

### Response

<ResponseField name="id" type="string">
  Transaction UUID.
</ResponseField>

<ResponseField name="reference" type="string">
  Unique payout reference code (e.g. `PO-A1B2C3D4`).
</ResponseField>

<ResponseField name="type" type="string">
  Transaction type (`PAYOUT`).
</ResponseField>

<ResponseField name="status" type="string">
  Processing status: `PROCESSING` (for instant local NIP) or `PENDING` (for cross-currency FX payouts).
</ResponseField>

<ResponseField name="currency" type="string">
  Payout currency code.
</ResponseField>

<ResponseField name="amountMinor" type="string">
  Amount in minor currency units as a string (e.g. `2500000` = 25,000.00 NGN).
</ResponseField>

<ResponseField name="ngnAmountMinor" type="string">
  Total NGN debit amount in minor units.
</ResponseField>

<ResponseField name="recipient" type="string">
  Recipient legal name.
</ResponseField>

<ResponseField name="metadata" type="object">
  Rail reference and integration provider metadata.
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO creation timestamp.
</ResponseField>

<ResponseField name="completedAt" type="string">
  Settlement completion timestamp, or `null` if in-flight.
</ResponseField>

<ResponseField name="payout" type="object">
  Detailed payout execution breakdown.

  <Expandable title="Payout properties">
    <ResponseField name="rate" type="number">
      Applied conversion rate.
    </ResponseField>

    <ResponseField name="transferFeeMinor" type="string">
      Transfer fees in minor units.
    </ResponseField>

    <ResponseField name="totalDebitMinor" type="string">
      Total wallet debit in minor units.
    </ResponseField>

    <ResponseField name="accountNumber" type="string">
      Beneficiary account number.
    </ResponseField>

    <ResponseField name="bank" type="string">
      Beneficiary bank code or name.
    </ResponseField>

    <ResponseField name="narration" type="string">
      Payment memo.
    </ResponseField>

    <ResponseField name="eta" type="string">
      Estimated settlement arrival (e.g. `Instant`).
    </ResponseField>

    <ResponseField name="railReference" type="string">
      Banking switch reference.
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.tabsglobal.co/v1/payouts" \
    -H "Authorization: Bearer sk_live_..." \
    -H "Idempotency-Key: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" \
    -H "Content-Type: application/json" \
    -d '{
      "amount": 25000,
      "sourceCurrency": "NGN",
      "payoutCurrency": "NGN",
      "bankCode": "058",
      "accountNumber": "0123456789",
      "recipientName": "ADEWALE ADELEKE",
      "narration": "Invoice settlement #1042"
    }'
  ```

  ```javascript Node.js theme={null}
  import { randomUUID } from "node:crypto";

  const response = await fetch("https://api.tabsglobal.co/v1/payouts", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.TABS_SECRET_KEY}`,
      "Idempotency-Key": randomUUID(),
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      amount: 25000,
      sourceCurrency: "NGN",
      payoutCurrency: "NGN",
      bankCode: "058",
      accountNumber: "0123456789",
      recipientName: "ADEWALE ADELEKE",
      narration: "Invoice settlement #1042",
    }),
  });

  const payout = await response.json();
  console.log(payout);
  ```

  ```python Python theme={null}
  import uuid
  import requests

  url = "https://api.tabsglobal.co/v1/payouts"
  headers = {
      "Authorization": f"Bearer {API_KEY}",
      "Idempotency-Key": str(uuid.uuid4()),
      "Content-Type": "application/json",
  }
  payload = {
      "amount": 25000,
      "sourceCurrency": "NGN",
      "payoutCurrency": "NGN",
      "bankCode": "058",
      "accountNumber": "0123456789",
      "recipientName": "ADEWALE ADELEKE",
      "narration": "Invoice settlement #1042",
  }

  response = requests.post(url, headers=headers, json=payload)
  print(response.json())
  ```
</RequestExample>

<ResponseExample>
  ```json 201 Created theme={null}
  {
    "id": "7d9c0245-31ba-4f27-a0c3-fba4313f89e2",
    "reference": "PO-AB12CD34",
    "type": "PAYOUT",
    "status": "PROCESSING",
    "currency": "NGN",
    "amountMinor": "2500000",
    "ngnAmountMinor": "2500000",
    "recipient": "ADEWALE ADELEKE",
    "metadata": {
      "railReference": "NIP-9948102941",
      "provider": "embedly"
    },
    "createdAt": "2026-09-21T02:00:00.000Z",
    "completedAt": null,
    "payout": {
      "rate": 1,
      "transferFeeMinor": "0",
      "totalDebitMinor": "2500000",
      "recipientAddress": null,
      "bank": null,
      "accountNumber": "0123456789",
      "routing": null,
      "sortCode": null,
      "iban": null,
      "bic": null,
      "narration": "Invoice settlement #1042",
      "eta": "Instant",
      "railReference": "NIP-9948102941"
    }
  }
  ```
</ResponseExample>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.