Events

Event Name	Status	Description
`transfer.completed`	COMPLETED	Internal transfer completed successfully

transfer.completed

Triggered when an internal transfer between customers is completed successfully.

Important: This webhook is sent only to the receiving customer. The sending customer does not receive a webhook notification for outgoing transfers.

Payload

{
  "event_name": "transfer.completed",
  "resource": {
    "type": "transfers",
    "id": "tf_a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  },
  "data": {
    "status": "COMPLETED",
    "customer_id": "cus_receiver_id",
    "transaction_id": "tf_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "direction": "IN",
    "from_customer_id": "cus_sender_id",
    "asset": "USDC",
    "amount": "1000.00",
    "memo": "Payment for invoice #12345",
    "created_at": "2024-01-22T12:00:00.000Z"
  }
}

Fields

Field	Type	Description
`status`	string	Always `COMPLETED` for this event
`customer_id`	string	The receiving customer's ID
`transaction_id`	string	Unique identifier for the transfer
`direction`	string	Always `IN` (from the recipient's perspective)
`from_customer_id`	string	The sending customer's ID
`asset`	string	Asset code (e.g., `USDC`, `USD`, `BTC`, `ETH`)
`amount`	string	Transfer amount as a decimal string
`memo`	string \| null	Optional memo provided by the sender
`created_at`	string	ISO 8601 timestamp when the transfer was created

Payload Comparison

The transfer webhook payload is richer than other transaction webhooks:

Field	Transfers	Deposits/Withdrawals/Conversions
`asset`	✅ Included	❌ Not included
`amount`	✅ Included	❌ Not included
`from_customer_id`	✅ Included	N/A
`direction`	✅ Included	N/A
`memo`	✅ Included	N/A
`modified_at`	❌ Not included	✅ Included

This design allows the receiving customer to immediately understand the transfer details without making additional API calls.

Example Use Cases

Scenario 1: Payment Notification

When Customer A sends 1,000 USDC to Customer B, Customer B receives a webhook:

{
  "data": {
    "from_customer_id": "cus_customer_a",
    "asset": "USDC",
    "amount": "1000.00",
    "memo": "Invoice #INV-2024-001"
  }
}

Scenario 2: Internal Settlement

Your system can automatically reconcile incoming transfers by matching the memo field or from_customer_id.

Retrieving Full Transfer Details

To get complete transfer information (including fees, timestamps, etc.), use the Retrieve Transfer endpoint with the transaction_id.