POST/v2/cross-border/preview

Preview - Send Cross Border Payment

Previews a cross-border payment. Submit payment instrument ID, purpose, description, destination amount/currency, and related fields. On success, returns fees and FX details.

**The preview does not lock the FX rate.** The returned `FXRate`, `SourceAmount`, and `TotalAmountInUSD` are indicative at the time of the call. The returned `QuoteId` is informational only and is **not** accepted back on Submit Cross Border Payment — the server re-quotes at submit time, so the final rate may differ.

The `x-idempotency-key` header is accepted but has no effect here: preview never creates a payment, so no duplicate-key short-circuit is applied. Use the key on Submit Cross Border Payment.

Headers

Field	Type	Required	Possible values	Description
`Authorization`	string	Required	Bearer {SessionToken}	Session token from Get Session Token, sent as `Authorization: Bearer {SessionToken}`. Replace with the value from the `x-refresh-token` response header when present (typically within 2 minutes of expiry). Secured calls must use the same IP as the auth request.
`x-idempotency-key`	string	Optional	7b2c8f1a-4e3d-4a1b-9c0e-123456789abc	Optional client-supplied idempotency key (max 255 characters). When provided, it is stored on the payment and must be unique. Reusing the same key on payment create does not create a second payment: the request short-circuits before SupportingDocument validation and returns HTTP 200 with only `ResponseData.TransactionNumber` of the original payment. Use a new key for each distinct payment; reuse the same key only when retrying the same logical request. Two caveats: (1) the replayed request body is ignored, so reusing a key for a genuinely different payment silently returns the original transaction rather than creating the new one; (2) the duplicate check is not atomic, so two identical requests sent concurrently with the same key can both pass it — serialize retries instead of firing them in parallel. The header has no effect on `preview` endpoints, which never create a payment.

Request body

Field	Type	Required	Possible values	Description
`BeneficiaryPaymentInstrumentID`	string	Required	{paymentInstrumentID}	Payment instrument ID linked to the beneficiary (from List or Create Payment Instrument).
`Purpose`	string	Required	Asset_Purchase \| Contract_Payment \| Other \| Education_Payment \| Payroll \| dividends \| Mortgage_Payments \| Materials_Purchase \| Loan_Payments \| Professional_Service_Payments \| Invoice_Payment \| Investment_Purchase \| Savings \| Rent_Utility_Payments \| reimbursements \| Tax_Payments \| Personal_Family_Payment \| settlement_trade \| treasury_movement \| gift_donation \| remittance	Regulatory purpose code for the payment. Must be one of the allowed values.
`Description`	string	Required	Test API Payment	Short memo or narrative for the transaction (shown in history and details).
`DestinationAmount`	string	Required	150	Amount the beneficiary receives, in destination currency, as a decimal string.
`DestinationCurrency`	string	Required	EUR \| ARS \| CLP \| COP \| DKK \| IDR \| PEN	Currency the beneficiary receives (e.g. EUR, USD, GBP, ARS, CLP, COP, DKK, IDR, PEN).
`CryptoBuySellActivity`	string	Required	Yes \| No	Whether the transaction involves buying or selling cryptocurrency: `Yes` or `No`.
`SupportingDocument`	string	Required	{fileID}	File ID from Upload File (`customField`: Payment_Invoice) for invoice or supporting documentation.
`DocumentReferenceNumber`	string	Required	13214654987	Reference number for the supporting document (e.g. passport or driver license number).
`IsRemittanceTransaction`	string	Optional	Yes \| No	Marks the payment as a remittance submitted on behalf of your own end customer. Only available when the remittance feature is enabled on your account; sending it otherwise is rejected. Defaults to `No`.
`UltimateDebtorId`	string	Optional	{beneficiaryID}	Beneficiary ID of the Ultimate Debtor, i.e. your end customer who is the actual originator of the funds. Required when `IsRemittanceTransaction` is `Yes` and must be an active beneficiary belonging to your account. Must be omitted otherwise.

Example request

{
  "BeneficiaryPaymentInstrumentID": "{paymentInstrumentID}",
  "Purpose": "Savings",
  "Description": "Testing Payment endpoint (Business Endpoint)",
  "DestinationAmount": "12",
  "DestinationCurrency": "EUR",
  "CryptoBuySellActivity": "Yes",
  "SupportingDocument": "{fileID}",
  "DocumentReferenceNumber": "234234"
}

Response

Field	Type	Possible values	Description
`ResponseCode`	integer	200 \| 201 \| 204 \| 400 \| 401 \| 403 \| 404 \| 410 \| 422 \| 500 \| 301 \| 503 \| 422	API result code in the response envelope. Indicates success or the error category (e.g. 200 success, 400 bad request, 401 unauthorized).
`ResponseMessage`	string	Success \| Created \| NoContent \| BadRequest \| Unauthorized \| Forbidden \| NotFound \| Gone \| UnprocessableContent \| ServerError \| ResourceMoved \| ServiceUnAvailable \| UnProcessableEntity	Human-readable label paired with ResponseCode (e.g. Success, BadRequest, Unauthorized). Use with ResponseCode to interpret the outcome.
`ResponseData`	object	Please refer to below example for response body	Transaction preview including indicative FX, fees, and source/destination amounts. `QuoteId` is an internal provider reference returned for support and reconciliation only — it cannot be sent back on submit and does not hold the rate. SEPA instruments also return SepaReachability, LastCheckedAt, and DataVersion.

Example response

{
  "ResponseCode": 200,
  "ResponseMessage": "Success",
  "ResponseData": {
    "BeneficiaryPaymentInstrumentID": "{paymentInstrumentID}",
    "From": "Example Business",
    "To": "Earnest-TRF",
    "DestinationAmount": "150",
    "DestinationCurrency": "EUR",
    "FXRate": "0.92",
    "SourceAmount": "163.04",
    "FeeInUSD": "40",
  …

Requires `Authorization: Bearer {SessionToken}` from Get Session Token. Refresh via `x-refresh-token` when supplied; use the same client IP as authentication.