Payouts

BETA: This endpoint is subject to change without notice.

A payout moves funds from an account's available balance to a registered external bank account. Payouts require approval in the Dashboard before they are submitted to the bank.

Creating a payout

API reference

The Idempotency-Key header lets you safely retry the request if it fails — see Idempotency.

curl -X POST https://api.synaptopay.com/v1/accounts/acct_YOUR_ACCOUNT/payouts \
  -H "Authorization: Api-Key $API_KEY" \
  -H "Idempotency-Key: YOUR_UNIQUE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "payout": {
      "external_bank_account_name": "accounts/acct_YOUR_ACCOUNT/external-bank-accounts/ba_BANK_ACCOUNT_ID",
      "currency": "GBP",
      "amount": "150000"
    }
  }'

Response

{
  "name": "accounts/acct_YOUR_ACCOUNT/payouts/po_PAYOUT_ID",
  "state": "REQUIRES_APPROVAL",
  "external_bank_account_name": "accounts/acct_YOUR_ACCOUNT/external-bank-accounts/ba_BANK_ACCOUNT_ID",
  "currency": "GBP",
  "amount": "150000",
  "create_time": "2026-01-15T10:30:00Z",
  "update_time": "2026-01-15T10:30:00Z"
}

The payout is created in REQUIRES_APPROVAL state. An authorized user must approve it in the Dashboard before funds are sent.

Payout lifecycle

When a payout is created, funds are reserved from the account's available balance. The payout then moves through the following states:

A payout can fail in two ways:

• Submission failure — the payout could not be submitted to the bank (e.g. the bank is temporarily unavailable). The reserved funds are returned to available balance.
• Bank reversal — the payout was successfully sent (PAID) but the receiving bank returned the funds (e.g. the destination account is closed or frozen). The funds are credited back to your available balance.

Approval

The payout remains in REQUIRES_APPROVAL until a user with the APPROVER role approves it in the Dashboard. The APPROVER role is separate from ADMIN — an ADMIN cannot approve payouts unless they also have the APPROVER role. Contact Synapto ([email protected]) to assign the APPROVER role to a user.

Once approved, the payout moves to PENDING and is submitted to the bank.

Payout schedules

Payouts are most commonly created automatically via payout schedules. A payout schedule periodically creates a payout for the account's full available balance.

Schedules are configured in the Dashboard and support three intervals:

Each schedule is per-currency. A minimum amount can be set — if the available balance is below this threshold, the payout is skipped and the balance carries over to the next scheduled date.

The account must have exactly one active external bank account for the schedule's currency. If there are none, or more than one, the scheduled payout is skipped.

Payout policies

A parent account can set a payout policy to provide defaults for its child accounts. A payout policy can:

• Set a default interval and day — child accounts without their own schedule inherit this
• Set an enforced minimum amount — child accounts cannot set a minimum below this threshold

Policies are per-currency. A child account can override the parent's default interval by setting its own schedule, but the enforced minimum always applies.

Key fields

Retrieving a payout

API reference

curl https://api.synaptopay.com/v1/accounts/acct_YOUR_ACCOUNT/payouts/po_PAYOUT_ID \
  -H "Authorization: Api-Key $API_KEY"

Listing payouts

API reference

curl -X POST https://api.synaptopay.com/v1/accounts/acct_YOUR_ACCOUNT/payouts:list \
  -H "Authorization: Api-Key $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "page_size": 20
  }'

You can filter by state and time range:

curl -X POST https://api.synaptopay.com/v1/accounts/acct_YOUR_ACCOUNT/payouts:list \
  -H "Authorization: Api-Key $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "states": ["REQUIRES_APPROVAL", "PENDING"],
      "start_create_time": "2026-01-01T00:00:00Z"
    },
    "page_size": 20
  }'

Batch create

API reference

Create multiple payouts in a single atomic request. The entire batch is rejected if any individual payout fails validation.

curl -X POST https://api.synaptopay.com/v1/payouts:batchCreate \
  -H "Authorization: Api-Key $API_KEY" \
  -H "Idempotency-Key: YOUR_UNIQUE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "requests": [
      {
        "parent": "accounts/acct_ACCOUNT_A",
        "payout": {
          "external_bank_account_name": "accounts/acct_ACCOUNT_A/external-bank-accounts/ba_BANK_A",
          "currency": "GBP",
          "amount": "50000"
        }
      },
      {
        "parent": "accounts/acct_ACCOUNT_B",
        "payout": {
          "external_bank_account_name": "accounts/acct_ACCOUNT_B/external-bank-accounts/ba_BANK_B",
          "currency": "GBP",
          "amount": "75000"
        }
      }
    ]
  }'

Response

{
  "payouts": [
    {
      "name": "accounts/acct_ACCOUNT_A/payouts/po_PAYOUT_A",
      "state": "REQUIRES_APPROVAL",
      "currency": "GBP",
      "amount": "50000"
    },
    {
      "name": "accounts/acct_ACCOUNT_B/payouts/po_PAYOUT_B",
      "state": "REQUIRES_APPROVAL",
      "currency": "GBP",
      "amount": "75000"
    }
  ]
}

Webhooks

See Flow Webhook Events for details.