Transfers

BETA: This endpoint is subject to change without notice.

A transfer moves funds between a parent account and one of its child accounts. Transfers settle immediately — both accounts' balances are updated in the same transaction.

Creating a transfer

API reference

Transfer funds from a parent account to a child account. 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_PARENT_ACCOUNT/transfers \
  -H "Authorization: Api-Key $API_KEY" \
  -H "Idempotency-Key: YOUR_UNIQUE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_name": "accounts/acct_CHILD_ACCOUNT",
    "amount": "50000",
    "currency": "GBP",
    "description": "January payout split"
  }'

Response

{
  "name": "accounts/acct_PARENT_ACCOUNT/transfers/txfr_TRANSFER_ID",
  "type": "DIRECT",
  "source_account_name": "accounts/acct_PARENT_ACCOUNT",
  "destination_account_name": "accounts/acct_CHILD_ACCOUNT",
  "currency": "GBP",
  "amount": "50000",
  "description": "January payout split",
  "create_time": "2026-01-15T10:30:00Z",
  "update_time": "2026-01-15T10:30:00Z"
}

The transfer settles immediately. A debit balance line is created on the parent account and a credit balance line on the child account.

Key fields

Request

Field	Description
`account_name`	Resource name of the child account receiving the transfer (required)
`amount`	Amount in smallest currency unit (required)
`currency`	ISO 4217 currency code (required)
`description`	Optional description — recorded on the balance lines
`metadata`	Key-value pairs for your own use (max 50 keys, key max 40 chars, value max 500 chars)

Response (Transfer)

Field	Description
`name`	Resource name of the transfer
`type`	`DIRECT` for explicit transfers, `CHARGE_SPLIT` for charge splits
`source_account_name`	Account that funds were debited from
`destination_account_name`	Account that funds were credited to
`currency`	ISO 4217 currency code
`amount`	Amount in smallest currency unit
`description`	Description provided at creation
`charge_name`	Resource name of the associated charge (only set for `CHARGE_SPLIT` transfers)

Transfers can also be created automatically when a charge succeeds — see Charge Splits for details.

Retrieving a transfer

API reference

curl https://api.synaptopay.com/v1/accounts/acct_PARENT_ACCOUNT/transfers/txfr_TRANSFER_ID \
  -H "Authorization: Api-Key $API_KEY"

Listing transfers

API reference

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

You can filter by time range:

curl -X POST https://api.synaptopay.com/v1/accounts/acct_YOUR_ACCOUNT/transfers:list \
  -H "Authorization: Api-Key $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "start_create_time": "2026-01-01T00:00:00Z",
      "end_create_time": "2026-02-01T00:00:00Z"
    },
    "page_size": 50
  }'

Batch create

API reference

Create multiple transfers in a single atomic request. All transfers settle in the same transaction — the entire batch is rejected if any individual transfer fails.

curl -X POST https://api.synaptopay.com/v1/transfers:batchCreate \
  -H "Authorization: Api-Key $API_KEY" \
  -H "Idempotency-Key: YOUR_UNIQUE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "requests": [
      {
        "parent": "accounts/acct_PARENT_ACCOUNT",
        "account_name": "accounts/acct_SELLER_A",
        "amount": "30000",
        "currency": "GBP",
        "description": "Order #1234 seller share"
      },
      {
        "parent": "accounts/acct_PARENT_ACCOUNT",
        "account_name": "accounts/acct_SELLER_B",
        "amount": "20000",
        "currency": "GBP",
        "description": "Order #1234 seller share"
      }
    ]
  }'

Response

{
  "transfers": [
    {
      "name": "accounts/acct_PARENT_ACCOUNT/transfers/txfr_TRANSFER_A",
      "type": "DIRECT",
      "source_account_name": "accounts/acct_PARENT_ACCOUNT",
      "destination_account_name": "accounts/acct_SELLER_A",
      "currency": "GBP",
      "amount": "30000",
      "description": "Order #1234 seller share"
    },
    {
      "name": "accounts/acct_PARENT_ACCOUNT/transfers/txfr_TRANSFER_B",
      "type": "DIRECT",
      "source_account_name": "accounts/acct_PARENT_ACCOUNT",
      "destination_account_name": "accounts/acct_SELLER_B",
      "currency": "GBP",
      "amount": "20000",
      "description": "Order #1234 seller share"
    }
  ]
}

Lifecycle

Step	Parent account	Child account
Transfer created	SETTLED balance line, negative amount — available reduced	SETTLED balance line, positive amount — available increased

Transfers settle immediately in a single transaction — there is no pending state.

Webhooks

When a transfer settles, a transfer.settled event is sent to your webhook endpoints. For direct transfers this fires immediately since they settle in a single transaction. See Flow Webhook Events for details.