Sign in

v1

latestOpenAPI 3.0.02026-07-224537337.5 KB

Create a Transfer

Create a new transfer.

post/v2/transfer

Request body

OR

Example request

{
  "customer": "customer_1234567890",
  "quoteId": "quote_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "externalId": "merchant_ref_123",
  "source": {
    "type": "wallet",
    "id": "wallet_1234567890abcdef1234567890abcdef12345678"
  },
  "destination": {
    "type": "wallet",
    "id": "wallet_1234567890abcdef1234567890abcdef12345678"
  },
  "paymentReason": "professional_services",
  "paymentDescription": "INV-2026-004 - Q1 software services",
  "documentId": "document_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"
}

Response

idstring required

A unique identifier for transfer.

externalIdstring

The external reference (not stored as unique).

type'on_ramp' | 'off_ramp' | 'unmatched_deposit' | 'microdeposit' required

The transfer type.

status'pendingFunding' | 'pendingReview' | 'fundsReceived' | 'processing' | 'succeeded' | 'undeliverable' | 'returned' | 'pendingRefundInformation' | 'failed' | 'canceled' | 'refunded' | 'unexpectedError' | 'failedPrecondition' | 'expired' required

The transfer status. See Transfer Lifecycle for status definitions and transitions.

customerstring required

The customer ID.

updatedstring date-time required

The last datetime the transfer was updated.

createdstring date-time required

The datetime the transfer was created.

paymentReasonstring

The reason for the payment. Present on BRL transfers and third-party off-ramp transfers.

paymentDescriptionstring

A free-text description of the payment purpose. Present on third-party off-ramp transfers.

Example response

{
  "id": "payout_a1b2c3d4e5f6a7b8c9d0e1f2",
  "externalId": "merchant_ref_123",
  "type": "on_ramp",
  "status": "pendingFunding",
  "statusHistory": [
    {
      "status": "pendingFunding",
      "transitionedAt": "2026-06-20T14:03:21.000Z"
    },
    {
      "status": "processing",
      "transitionedAt": "2026-06-20T14:05:10.000Z"
    }
  ],
  "customer": "customer_b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7",
  "fees": {
    "integratorFee": {
      "fixedAmount": "1.00",
      "bpsRate": "10",
      "bpsAmount": "0.10",
      "totalAmount": "1.10",
      "currency": "usd"
    },
    "platformFee": {
      "fixedAmount": "2.00",
      "bpsRate": "10",
      "bpsAmount": "0.10",
      "totalAmount": "2.10",
      "currency": "usd"
    }
  },
  "source": {
    "id": "bankAccount_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
    "type": "bank_account"
  },
  "destination": {
    "id": "wallet_e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2",
    "type": "wallet",
    "currency": "usdc",
    "network": "sol",
    "exchangeRate": "5.455"
  },
  "depositAccount": {
    "type": "bank_account",
    "bankDetails": {
      "bankName": "Bank of America",
      "accountHolderName": "John Doe",
      "accountType": "savings",
      "accountNumber": "1234567890",
      "routingNumber": "1234567890",
      "bic": "1234567890",
      "iban": "1234567890",
      "pixKey": "+5511999999999",
      "brCode": "00020126580014br.gov.bcb.pix0136a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "bankAddress": "123 Main St, Anytown, USA",
      "beneficiaryAddress": "123 Main St, Anytown, USA",
      "memo": "BBE6C7EB4A3F"
    }
  },
  "quote": {
    "id": "quote_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
    "expiresAt": "2021-01-01T00:00:00.000Z"
  },
  "updated": "2021-01-01T00:00:00.000Z",
  "created": "2021-01-01T00:00:00.000Z",
  "paymentReason": "professional_services",
  "paymentDescription": "INV-2026-004 - Q1 software services"
}