GuidesAPI ReferenceChangelog
API Reference

Internal Transfers

Webhook events for internal transfers between customers, including transfers across organizations.

The receiving account gets an internal.completed webhook when an internal transfer credits its balance. The sending account receives payouts.* webhooks to track its outgoing payment.

When internal.completed fires

  • Customer-to-customer transfer. When a transfer initiated through the Payout API or the admin console completes, the destination account receives the event.
  • Auto-sweep. When funds from a sub-account deposit sweep to the main account, the main account receives the event.
  • Payout funding. When the main account funds a sub-account for a payout on behalf of a sub-account, the sub-account receives the event. It confirms receipt of the internal funding transfer.

Example payload

In this example, BZ-RECV-1234 receives 1,000 USDC from BZ-SEND-1234.

{
  "event_name": "internal.completed",
  "resource": {
    "type": "transfers",
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "idempotency_key": "678160c6-ca41-40ee-bfe7-35057ade157d"
  },
  "data": {
    "status": "COMPLETED",
    "account_id": "BZ-RECV-1234",
    "transaction_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "direction": "IN",
    "from_account_id": "BZ-SEND-1234",
    "asset": "USDC",
    "amount": "1000.00",
    "memorandum": "Payment for invoice #12345",
    "created_at": "2024-01-22T12:00:00.000Z",
    "modified_at": "2024-01-22T12:00:00.000Z"
  }
}

Handling the credit

Use data.account_id to identify who received the funds. The from_account_id field identifies who sent them.

Deduplicate deliveries using the X-Webhook-Event-Id header so a retry or replay records the credit only once.