API ReferenceCustomersAPI IntegrationPayments

Create FX conversion and payment

Beta

Create a new FX conversion and payment instruction for a customer. This endpoint lets you create foreign exchange requests with recipient payout details and transaction information.

Requirements:

  • Quote must be active and not expired
  • Recipient details must be valid and active

Authentication: Bearer token required

The following diagram illustrates the Confirmation of Payee (CoP) handling flow for this endpoint:

Path parameters

customer_idstringRequired
Unique identifier for the customer who will initiate the payment transaction.

Headers

AuthorizationstringRequired

Bearer authentication of the form Bearer <token>, where token is your auth token.

Request

This endpoint expects an object.
purpose_of_transactionenumRequired

Purpose of the transaction. Must be one of the predefined values.

Validation Rules:

  • Must be provided and cannot be null or empty
  • Must be one of the allowed enum values
  • Case sensitive - must match exactly
amountobjectRequired

Amount to be converted and paid out in the destination currency. Must be an object with currency and value fields. Example: {“currency”: “GBP”, “value”: 50000.00}

recipient_detailslist of objectsRequired

Container for recipient details.

Validation Rules:

  • Must contain at least one recipient
  • Cannot be null or empty
  • Sum of all recipient amounts must equal the payment amount
quote_idstringRequired

Quote ID associated with this payment.

Validation Rules:

  • Quote must exist and be in a active state for payment processing

Reference: This should be an active quote_id obtained from the Create Quote API.

property_refstringRequired

The unique identifier for the property receiving this payment. Must match a property_ref from a previously onboarded property. Used to identify the property and map payments to the correct client account for fund segregation.

client_reference_idstringOptional
Unique reference id that you want to assign to this payment for your own purposes.
is_third_party_paymentbooleanOptionalDefaults to false

Determines whether this payment is processed for a third-party client or directly from your wallet.

How It Works

For Third Party Payments (is_third_party_payment: true):

  • The system maps your client_customer_ref to a specific property_ref
  • Funds are segregated using this property_ref for precise tracking
  • If sufficient segregated funds are available for that property, the FX and payout execute immediately
  • If insufficient funds are available, the system waits for incoming wire transfers tagged with the property_ref
  • Once matching funds are received (identified by the property reference in the wire transfer), the transaction processes automatically
  • Bank instructions available via Get Bank Transfer Instructions endpoint

For Payment From Wallet (is_third_party_payment: false):

  • The system processes the transaction using available general wallet balance
  • No fund segregation or reference matching occurs
  • If insufficient wallet funds are available, the system waits for any incoming funds up to the specified deadline
client_customer_refstringOptional

The unique reference identifier of the third party client for whom this payment is being made. This must match a client_customer_ref from a previously onboarded third party. The system uses this to identify the client and map to the corresponding property reference for fund segregation.

confirm_recipientobjectOptional
Container for confirmation of recipient details. It is required only if CoP check has failed in first iteration.

Response

FX conversion and payment created successfully
payment_idstring
Unique transaction identifier. Generated after payment creation and used to track and reference the payment throughout its lifecycle.
amountobject
The total amount to be credited across all recipient bank accounts, denominated in the recipient's bank account currency.
recipient_detailslist of objects
Container for recipient details.
statusenum

Current status of the payment. Refer to the Payment Status Events section for more details about the statuses.

created_datetimedatetime
Timestamp when the payment was created.

Errors