Transfers

Transfers are used to move funds between two platform-managed accounts that are denominated in the same currency.

Endpoints

POST /transfers Create transfer POST /transfers/{id}/accept Accept transfer GET /transfers/{id} Retrieve transfer

POST /transfers

Create a transfer between two accounts. Both accounts must hold the same currency.

Request Body

Field	Type	Description
`source_account_id` required	string	Source account ID
`destination_account_id` required	string	Destination account ID
`amount` required	string	Transfer amount
`reference`	string	Optional reference or memo

Example Request

Request

{
  "source_account_id": "acc_123456789",
  "destination_account_id": "acc_987654321",
  "amount": "1000.00",
  "reference": "P2P Transfer"
}

Response

201 Created

{
  "id": "tfr_555444333",
  "source_account_id": "acc_123456789",
  "destination_account_id": "acc_987654321",
  "amount": "1000.00",
  "currency": "USD",
  "status": "REQUESTED",
  "reference": "P2P Transfer",
  "created_at": "2026-01-15T10:30:00Z"
}

POST /transfers/{id}/accept

Accept and execute a transfer. Transfers are typically executed immediately.

Path Parameters

Parameter	Type	Description
`id` required	string	The transfer ID

Headers

Header	Required	Description
`x-bultra-idempotency-id`	Recommended	Idempotency key for safe retries

Response

200 OK

{
  "id": "tfr_555444333",
  "source_account_id": "acc_123456789",
  "destination_account_id": "acc_987654321",
  "amount": "1000.00",
  "currency": "USD",
  "status": "EXECUTED",
  "reference": "P2P Transfer",
  "created_at": "2026-01-15T10:30:00Z",
  "accepted_at": "2026-01-15T10:30:05Z",
  "executed_at": "2026-01-15T10:30:05Z"
}

GET /transfers/{id}

Retrieve details of a specific transfer.

Response

200 OK

{
  "id": "tfr_555444333",
  "source_account_id": "acc_123456789",
  "destination_account_id": "acc_987654321",
  "amount": "1000.00",
  "currency": "USD",
  "status": "EXECUTED",
  "reference": "P2P Transfer",
  "source_transaction_id": "txn_aaa111",
  "destination_transaction_id": "txn_bbb222",
  "created_at": "2026-01-15T10:30:00Z",
  "accepted_at": "2026-01-15T10:30:05Z",
  "executed_at": "2026-01-15T10:30:05Z"
}

Transfer Status Values

Status	Description
`REQUESTED`	Transfer created, awaiting acceptance
`EXECUTED`	Transfer completed successfully
`FAILED`	Transfer failed (e.g., insufficient funds)
`CANCELLED`	Transfer was cancelled