Create payment
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_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 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_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
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
quote_id
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](/api-reference/customers/api-integration/quotes/create-quote).
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
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.
