API ReferenceCustomersAPI IntegrationPayments

Create payment

Beta
Create a new payment instruction for a customer. This endpoint lets you create payments with recipient payout details and transaction information. **FX Conversion:** - If you need to convert currency, provide a `quote_id` from an active quote. The quote must be active and not expired. - If no currency conversion is needed (same currency payment), do not send `quote_id`. **Requirements:** - Recipient details must be valid and active - If `quote_id` is provided, the quote must be active and not expired **Authentication:** [Bearer token required](/api-guide/getting-started/authentication#oauth-20-authentication) The following diagram illustrates the Confirmation of Payee (CoP) or Verification of Payee (VoP) handling flow for this endpoint: ```mermaid graph TD A[User] -->|"POST /v3/customers/{customer_id}/payments"| B[Create Payment] B -->|Success| C[Payment Complete] B -->|"CoP/VoP failure"| D[Error: CoP/VoP Error] D --> E[Display error and options to user] E -->|User chooses to update details| F[User updates payment details] F -->|"POST /v3/customers/{customer_id}/payments"| B E -->|User chooses to override or accept suggestion| G[User confirms action] G -->|"POST /v3/customers/{customer_id}/payments with confirm_recipient"| B ```

Authentication

AuthorizationBearer

OAuth 2.0 Bearer token authentication. This API uses OAuth 2.0 Client Credentials flow. Please refer to the Authentication section for detailed information on how to obtain and use your OAuth credentials.

Path parameters

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

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 paid out in the destination currency. If currency conversion is needed, provide a quote_id for the conversion. If no conversion is needed, the amount will be paid directly. 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
client_reference_idstringOptional<=36 characters

Your reference for this payment for reconciliation purposes.

Validation Rules:

  • Required when: is_third_party_payment: true
  • Optional when: is_third_party_payment: false
  • Uniqueness: Enforced only for third-party payments — must be unique per customer (per customer_id); duplicates for the same customer will be rejected.
  • Maximum length: 36 characters.
quote_idstringOptional

Quote ID associated with this payment for FX conversion.

Required when: Currency conversion is needed (different currencies between source and destination).

Do not send when: No currency conversion is needed (same currency payment). Omit this field entirely.

Validation Rules:

  • If provided, the quote must exist and be in an active state for payment processing
  • Quote must not be expired

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

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):

  • client_reference_id must be provided
  • A valid client_customer_ref must be provided
  • The system uses this to map the payment to the correct client account for fund segregation.
  • 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.

Required when: is_third_party_payment: true

Optional when: is_third_party_payment: false

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

Response

Payment created successfully
payment_idstring
Unique transaction identifier. Generated after payment creation and used to track and reference the payment throughout its lifecycle.
instruction_numberstring
Instruction number assigned by the API when the payment is created.
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

400
Bad Request Error
404
Not Found Error
500
Internal Server Error