Sign in
Cross-Currency Transfers

Create a transfer quote

Generate a quote for a cross-currency transfer between any combination of accounts and UMA addresses. This endpoint handles currency exchange and provides the necessary instructions to execute the transfer.

Transfer Types Supported:

  • Account to Account: Transfer between internal/external accounts with currency exchange.
  • Account to UMA: Transfer from an internal account to an UMA address.
  • UMA to Account or UMA to UMA: This transfer type will only be funded by payment instructions, not from an internal account.

Key Features:

  • Flexible Amount Locking: Always specify whether you want to lock the sending amount or receiving amount
  • Currency Exchange: Handles all cross-currency transfers with real-time exchange rates
  • Payment Instructions: For UMA or customer ID sources, provides banking details needed for execution

Important: If you are transferring funds in the same currency (no exchange required), use the /transfer-in or /transfer-out endpoints instead.

Sandbox Testing: When using the externalAccountDetails destination type in sandbox mode, use account number patterns ending in specific digits to test different scenarios. These patterns should be used with the primary alias, address, or identifier of whatever account type you're testing. For example, the US account number, a CLABE, an IBAN, a spark wallet address, etc. The failure patterns are:

  • Account numbers ending in 002: Insufficient funds (transfer-in will fail)
  • Account numbers ending in 003: Account closed/invalid (transfers will fail)
  • Account numbers ending in 004: Transfer rejected (bank rejects the transfer)
  • Account numbers ending in 005: Timeout/delayed failure (stays pending ~30s, then fails)
  • Any other account number: Success (transfers complete normally)
post/quotes

Request body

lookupIdstring

Lookup ID from a previous receiver lookup request. If provided, this can make the quote creation more efficient by reusing cached lookup data. NOTE: This is required for UMA destinations due to counterparty institution requirements. See senderCustomerInfo for more information.

lockedCurrencySide'SENDING' | 'RECEIVING' required

The side of the quote which should be locked and specified in the lockedCurrencyAmount. For example, if I want to send exactly $5 MXN from my wallet, I would set this to "sending", and the lockedCurrencyAmount to 500 (in cents). If I want the receiver to receive exactly $10 USD, I would set this to "receiving" and the lockedCurrencyAmount to 10000 (in cents).

lockedCurrencyAmountinteger required

The amount to send/receive in the smallest unit of the locked currency (eg. cents). See lockedCurrencySide for more information.

immediatelyExecuteboolean

Whether to immediately execute the quote after creation. If true, the quote will be executed and the transaction will be created at the current exchange rate. It should only be used if you don't want to lock and view rate details before executing the quote. If you are executing a pre-existing quote, use the /quotes/{quoteId}/execute endpoint instead. This is false by default.

descriptionstring

Optional description/memo for the transfer

senderCustomerInfoobject

Only relevant for UMA destinations. Key-value pairs of information about the sender which was requested by the counterparty (recipient) institution. Any fields specified in requiredPayerDataFields from the response of the /receiver/uma/{receiverUmaAddress} (lookupUma) endpoint MUST be provided here if they were requested. If the counterparty (recipient) institution did not request any information, this field can be omitted.

Example request

{
  "lookupId": "Lookup:019542f5-b3e7-1d02-0000-000000000009",
  "source": {
    "accountId": "InternalAccount:85dcbd6-dced-4ec4-b756-3c3a9ea3d965"
  },
  "destination": {
    "accountId": "a12dcbd6-dced-4ec4-b756-3c3a9ea3d123",
    "currency": "EUR"
  },
  "lockedCurrencyAmount": 1000,
  "description": "Invoice #1234 payment",
  "senderCustomerInfo": {
    "FULL_NAME": "Jane Receiver",
    "NATIONALITY": "FR"
  }
}

Response

Transfer quote created successfully. The response includes exchange rates, fees, and transfer details. For transfers involving UMA addresses, payment instructions are also included for execution through banking systems.

quoteIdstring required

Unique identifier for this quote

status'PENDING' | 'PROCESSING' | 'COMPLETED' | 'FAILED' | 'EXPIRED' required

Current status of the quote

createdAtstring date-time required

When this quote was created

expiresAtstring date-time required

When this quote expires (typically 1-5 minutes after creation)

totalSendingAmountinteger required

The total amount that will be sent in the smallest unit of the sending currency (eg. cents).

totalReceivingAmountinteger required

The total amount that will be received in the smallest unit of the receiving currency (eg. cents).

exchangeRatenumber required

Number of sending currency units per receiving currency unit.

feesIncludedinteger required

The fees associated with the quote in the smallest unit of the sending currency (eg. cents).

transactionIdstring required

The ID of the transaction created from this quote.

originalQuoteIdstring

ID of the quote that is being retried

Example response

{
  "quoteId": "Quote:019542f5-b3e7-1d02-0000-000000000006",
  "status": "PENDING",
  "createdAt": "2025-10-03T12:00:00Z",
  "expiresAt": "2025-10-03T12:05:00Z",
  "source": {
    "accountId": "InternalAccount:85dcbd6-dced-4ec4-b756-3c3a9ea3d965"
  },
  "destination": {
    "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123",
    "currency": "EUR"
  },
  "sendingCurrency": {
    "code": "USD",
    "name": "United States Dollar",
    "symbol": "$",
    "decimals": 2
  },
  "receivingCurrency": {
    "code": "USD",
    "name": "United States Dollar",
    "symbol": "$",
    "decimals": 2
  },
  "totalSendingAmount": 123010,
  "totalReceivingAmount": 1000,
  "feesIncluded": 10,
  "paymentInstructions": [
    {
      "accountType": "US_ACCOUNT",
      "accountNumber": "1234567890",
      "routingNumber": "021000021",
      "bankName": "Chase Bank",
      "referenceCode": "REF123456"
    },
    {
      "accountType": "SPARK_WALLET",
      "address": "spark1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu",
      "invoice": "lnbc15u1p3xnhl2pp5jptserfk3zk4qy42tlucycrfwxhydvlemu9pqr93tuzlv9cc7g3sdqsvfhkcap3xyhx7un8cqzpgxqzjcsp5f8c52y2stc300gl6s4xswtjpc37hrnnr3c9wvtgjfuvqmpm35evq9qyyssqy4lgd8tj637qcjp05rdpxxykjenthxftej7a2zzmwrmrl70fyj9hvj0rewhzj7jfyuwkwcg9g2jpwtk3wkjtwnkdks84hsnu8xps5vsq4gj5hs"
    }
  ],
  "transactionId": "Transaction:019542f5-b3e7-1d02-0000-000000000005",
  "originalQuoteId": "Quote:019542f5-b3e7-1d02-0000-000000000001",
  "rateDetails": {
    "counterpartyMultiplier": 1.08,
    "counterpartyFixedFee": 10,
    "gridApiMultiplier": 0.925,
    "gridApiFixedFee": 10,
    "gridApiVariableFeeRate": 0.003,
    "gridApiVariableFeeAmount": 30
  }
}

Changes