Create FX conversion and payment | Redpin

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:

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) 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 failure"| D[Error: CoP 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_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

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

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.

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_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

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](/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_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.

Required when: is_third_party_payment: true

Optional when: is_third_party_payment: false

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. **Required when:** `is_third_party_payment: true` **Optional when:** `is_third_party_payment: false`

property_refstringOptional

Required when: is_third_party_payment: true

Optional when: is_third_party_payment: false

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. **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

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.

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

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

1	curl -X POST https://api.redpincompany.com/v3/customers/cust_123456789/payments \
2	-H "Authorization: Bearer <token>" \
3	-H "Content-Type: application/json" \
4	-d '{
5	"purpose_of_transaction": "PROPERTY_PURCHASE",
6	"amount": {
7	"currency": "GBP",
8	"value": 50000
9	},
10	"recipient_details": [
11	{
12	"amount": {
13	"currency": "GBP",
14	"value": 50000
15	},
16	"recipient_id": "REC-001",
17	"payment_reference": "PROPERTY_PURCHASE_PAYMENT"
18	}
19	],
20	"quote_id": "548eb44b-5e1b-45fb-86eb-88eb5bcaa781",
21	"is_third_party_payment": true,
22	"client_customer_ref": "CUST-001",
23	"property_ref": "PROPERTY-001"
24	}'

1	{
2	"payment_id": "PAY-2024-001",
3	"instruction_number": "CUST-001-0001",
4	"amount": {
5	"currency": "AUD",
6	"value": 50000
7	},
8	"recipient_details": [
9	{
10	"recipient_id": "REC-001",
11	"recipient_name": "John Smith",
12	"amount": {
13	"currency": "AUD",
14	"value": 50000
15	},
16	"payment_reference": "PROPERTY_PURCHASE_PAYMENT",
17	"country": "GBR"
18	}
19	],
20	"status": "AWAITING_FUNDS",
21	"created_datetime": "2024-01-15T10:30:00Z"
22	}