Create FX conversion and payment
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](/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
Bearer authentication of the form Bearer <token>, where token is your auth token.
Path parameters
customer_id
Unique identifier for the customer who will initiate the payment transaction.
Request
This endpoint expects an object.
purpose_of_transaction
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
amount
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_details
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_id
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](/api-reference/customers/api-integration/quotes/create-quote).
client_reference_id
Unique reference id that you want to assign to this payment for your own purposes.
Required when: is_third_party_payment: true
Optional when: is_third_party_payment: false
is_third_party_payment
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](/v3/customers/{customer_id}/payments/{payment_id}/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_ref
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_recipient
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_id
Unique transaction identifier. Generated after payment creation and used to track and reference the payment throughout its lifecycle.
instruction_number
Instruction number assigned by the API when the payment is created.
amount
The total amount to be credited across all recipient bank accounts, denominated in the recipient's bank account currency.
recipient_details
Container for recipient details.
status
Current status of the payment. Refer to the Payment Status Events section for more details about the statuses.
created_datetime
Timestamp when the payment was created.
