POST/transactions/{userId}/cross-border/preview

Preview Cross Border Payment

Previews a cross-border payment before execution. Returns exchange rate, fees, and destination amount breakdown.

Path variables

Field	Type	Required	Possible values	Description
`userId`	string	Required	—	Unique user ID initiating the cross-border payment and respective user status must be `active`

Headers

Field	Type	Required	Possible values	Description
`session-token`	string	Required	—	SessionToken obtained from the Create GMA Session endpoint. All secured endpoints require this header.

Request body

Field	Type	Required	Possible values	Description
`InstrumentId`	string	Required	—	Cross-border payment instrument ID.
`DestinationAmount`	string	Required	—	Amount in destination currency.
`DestinationCurrency`	string	Required	GBP \| EUR \| SGD \| AED \| ARS \| AUD \| BRL \| CAD \| CLP \| COP \| DKK \| JPY \| MXN \| HKD \| IDR \| KRW \| MYR \| PEN \| THB \| VND \| ZAR	Target currency for the cross-border payment.
`Purpose`	string	Required	Refer to the Payment Purpose endpoint to get the list of possible values.	Payment purpose code.
`CryptoBuySellActivity`	string	Required	Yes \| No	Indicates crypto activity.
`Description`	string	Optional	—	Payment description.
`DocumentReferenceNumber`	string	Optional	—	Reference number for supporting document.
`SupportingDocument`	string	Optional	—	File ID from the File Upload endpoint. Required when the source amount exceeds the configured threshold for the user's group. The threshold value can be retrieved from the Config Data endpoint.
`Additional_Info.Originator_Identity_Type`	string	Optional	PASSPORT \| NATIONAL_ID \| DRIVING_LICENSE	Type of identity document provided by the originator. Required for CROSS_BORDER_BRL_DOMESTIC, CROSS_BORDER_JPY_DOMESTIC, and CROSS_BORDER_AED_DOMESTIC transfers; optional for CROSS_BORDER_MYR_DOMESTIC and CROSS_BORDER_IDR_DOMESTIC transfers; not supported for other transfer types.
`Additional_Info.Originator_Identity_Number`	string	Optional	—	Identity document number provided by the originator. Required for CROSS_BORDER_BRL_DOMESTIC, CROSS_BORDER_JPY_DOMESTIC, and CROSS_BORDER_AED_DOMESTIC transfers; optional for CROSS_BORDER_MYR_DOMESTIC and CROSS_BORDER_IDR_DOMESTIC transfers; not supported for other transfer types.
`Additional_Info.Source_Of_Funds`	string	Optional	CASH \| BUSINESS \| GIFT \| LOTTERY \| SAVINGS \| OTHER	Source of funds provided by the originator. Required for CROSS_BORDER_JPY_DOMESTIC and CROSS_BORDER_AED_DOMESTIC transfers; optional for CROSS_BORDER_MYR_DOMESTIC and CROSS_BORDER_IDR_DOMESTIC transfers; not supported for other transfer types.

Example request

{
  "InstrumentId": "{{instrumentId}}",
  "DestinationAmount": "50.00",
  "DestinationCurrency": "GBP",
  "Description": "GBP payment test",
  "Purpose": "Asset_Purchase",
  "CryptoBuySellActivity": "No",
  "DocumentReferenceNumber": "1234",
  "SupportingDocument": "-3928373292172922988"
}

{
  "InstrumentId": "{{instrumentId}}",
  "DestinationAmount": "50.00",
  "DestinationCurrency": "GBP",
  "Description": "GBP payment test",
  "Purpose": "Asset_Purchase",
  "CryptoBuySellActivity": "No",
  "DocumentReferenceNumber": "1234",
  "SupportingDocument": "-3928373292172922988"
}

Response

Field	Type	Possible values	Description
`ResponseCode`	integer	200 \| 201 \| 204 \| 301 \| 400 \| 401 \| 403 \| 404 \| 410 \| 422 \| 500 \| 503	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	Cross-border payment preview with exchange rate, fees, and source/destination amounts.

Example response

{
  "ResponseCode": 200,
  "ResponseMessage": "Success",
  "ResponseData": {
    "BeneficiaryPaymentInstrumentID": "-9125527262158475302",
    "From": "John Doe",
    "To": "UK Faster Payments Account",
    "DestinationAmount": "50",
    "DestinationCurrency": "GBP",
    "FXRate": "1.349851",
    "SourceAmount": "67.49255",
    "FeeInUSD": "35",
    "TotalAmountInUSD": "102.49255",
    "QuoteId": "54e0f55f-9f9c-49d9-9f87-ace7feb95617",
    "Purpose": "Asset_Purchase",
    "Description": "SEPA payment test"
  }
}

{
  "ResponseCode": 200,
  "ResponseMessage": "Success",
  "ResponseData": {
    "BeneficiaryPaymentInstrumentID": "-9125527262158475302",
    "From": "John Doe",
    "To": "UK Faster Payments Account",
    "DestinationAmount": "50",
    "DestinationCurrency": "GBP",
    "FXRate": "1.349851",
    "SourceAmount": "67.49255",
    "FeeInUSD": "35",
    "TotalAmountInUSD": "102.49255",
    "QuoteId": "54e0f55f-9f9c-49d9-9f87-ace7feb95617",
    "Purpose": "Asset_Purchase",
    "Description": "SEPA payment test"
  }
}

Use Perform Cross Border Payment to execute after previewing.

Requires `session-token: {SessionToken}` from Create GMA Session. Use the same client IP as authentication.