Create a payment session | Redpin

A Payment Session is a temporary, secure, and hosted interaction between your platform and Redpin, designed to facilitate cross-border payments.

The OAuth 2.0 Authenticated Create Payment Session API allows you to create a new hosted payment session. You provide the payment details (amount, items, recipients, etc.), session configuration (like allowed domains and callbacks), and receive a unique session URL in response. This URL can be embedded in your app or website to launch the hosted payment flow in a secure, guided interface.

Payment sessions are time-bound and will automatically expire at the specified expires_at timestamp. Once expired, the session URL becomes inaccessible and can no longer be used to complete the payment. If the payment is not completed before the session expires, a new session must be created again to initiate the payment.

A Payment Session is a temporary, secure, and hosted interaction between your platform and Redpin, designed to facilitate cross-border payments. The [OAuth 2.0 Authenticated](/api-guide/getting-started/authentication#oauth-20-authentication) Create Payment Session API allows you to create a new hosted payment session. You provide the payment details (amount, items, recipients, etc.), session configuration (like allowed domains and callbacks), and receive a unique session URL in response. This URL can be embedded in your app or website to launch the hosted payment flow in a secure, guided interface. Payment sessions are time-bound and will automatically expire at the specified `expires_at` timestamp. Once expired, the session URL becomes inaccessible and can no longer be used to complete the payment. If the payment is not completed before the session expires, a new session must be created again to initiate the payment.

Authentication

AuthorizationBearer

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

Path parameters

customer_idstringRequired

A unique identifier for the customer initiating the session.

Request

This endpoint expects an object.

client_customer_refstringRequired

The API caller’s internal customer ID for the person initiating the payment. It must be the same reference used when invoking the Pre-eligibility check API.

client_reference_idstringRequiredformat: "^[A-Za-z0-9_-]+$"1-100 characters

A unique reference identifier for this payment session in your system. This reference is used to uniquely identify and track this specific payment.

Validation Rules:

Must be unique per client (duplicate references will be rejected)
Maximum length: 100 characters
Allowed characters: alphanumeric (A-Z, a-z, 0-9), hyphens (-), and underscores (_)

A unique reference identifier for this payment session in your system. This reference is used to uniquely identify and track this specific payment. **Validation Rules:** - Must be unique per client (duplicate references will be rejected) - Maximum length: 100 characters - Allowed characters: alphanumeric (A-Z, a-z, 0-9), hyphens (-), and underscores (_)

amountobjectRequired

due_datestringRequiredformat: "date"

The date by which the amount must be credited to all recipient bank accounts. Must follow the ISO 8601 format (YYYY-MM-DD) and be at least 5 calendar days from the current date.

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

recipient_detailslist of objectsRequired

List of recipients who will receive payment funds. Independent of items, allowing flexible fund distribution.

Validation Rules:

At least one recipient is required
Sum of all recipient amounts must equal the session total amount
All recipient currencies must match the session amount currency

List of recipients who will receive payment funds. Independent of items, allowing flexible fund distribution. **Validation Rules:** - At least one recipient is required - Sum of all recipient amounts must equal the session total amount - All recipient currencies must match the session amount currency

itemslist of objectsOptional

List of payment items describing what is being paid for in this session. Each item represents a line item (property, invoice, booking, service fee, etc.).

Validation Rules:

At least one item is required
Sum of all item amounts must equal the session total amount
All item currencies must match the session amount currency

List of payment items describing what is being paid for in this session. Each item represents a line item (property, invoice, booking, service fee, etc.). **Validation Rules:** - At least one item is required - Sum of all item amounts must equal the session total amount - All item currencies must match the session amount currency

allowed_originslist of stringsOptional

Origins (or app identifiers) from which the hosted payment session is expected to be launched. Also used as a proxy to determine whether OTP based verification is required.

Each entry must be one of the following:

A valid HTTPS origin for web applications (e.g., https://example.com)
A valid Android package name (e.g., com.example.app) for native Android apps
A valid iOS bundle identifier (e.g., com.example.iosapp) for native iOS apps

OTP enforcement logic:

If this field is empty or omitted → OTP is required. The customer will be prompted to enter an OTP sent to the mobile number supplied during Third-Party Customer creation. The customer can choose to receive the OTP via SMS or voice call based on their preference.
If this field is set (contains one or more entries) → OTP is not required.

Notes:

Wildcards or regular expressions are not supported.
If this field is not provided, the session will be accessible from any origin and OTP will be enforced as described above.

Origins (or app identifiers) from which the hosted payment session is expected to be launched. Also used as a proxy to determine whether OTP based verification is required. Each entry must be one of the following: - A valid HTTPS origin for web applications (e.g., https://example.com) - A valid Android package name (e.g., com.example.app) for native Android apps - A valid iOS bundle identifier (e.g., com.example.iosapp) for native iOS apps OTP enforcement logic: - If this field is empty or omitted → OTP is required. The customer will be prompted to enter an OTP sent to the mobile number supplied during [Third-Party Customer](/api-reference/customers/api-integration/third-parties/create-third-party-customer) creation. The customer can choose to receive the OTP via SMS or voice call based on their preference. - If this field is set (contains one or more entries) → OTP is not required. Notes: - Wildcards or regular expressions are **not supported**. - If this field is **not provided**, the session will be accessible from **any origin** and OTP will be enforced as described above.

callbackslist of stringsOptional

List of callback URLs that will receive webhook notifications when the session status changes.

These URLs must be publicly accessible from Redpin’s servers.
For detailed payload structure and supported status events, refer to the Webhook Reference

List of callback URLs that will receive webhook notifications when the session status changes. - These URLs must be publicly accessible from Redpin's servers. - For detailed payload structure and supported status events, refer to the Webhook Reference

Response

Payment session created successfully

session_idstring

A unique identifier automatically generated for each payment session.

client_reference_idstring

The unique payment reference provided by the client in the request, returned for confirmation and tracking purposes.

expires_atdatetime

The exact date and time (in ISO 8601 format) when the session becomes invalid.

The session URL becomes inaccessible and can no longer be used to complete the payment. If the payment is not completed before the session expires, a new session must be created again to initiate the payment.

The exact date and time (in ISO 8601 format) when the session becomes invalid. - The session URL becomes inaccessible and can no longer be used to complete the payment. If the payment is not completed before the session expires, a new session must be created again to initiate the payment.

session_urlstring

A hosted payment page URL that displays Redpin’s secure payment flow. This URL can be integrated into your mobile app (via webview) or website (via redirect or iframe), allowing users to review payment details and complete the cross-border transaction.

Errors

Origins (or app identifiers) from which the hosted payment session is expected to be launched. Also used as a proxy to determine whether OTP based verification is required.

Each entry must be one of the following:

A valid HTTPS origin for web applications (e.g., https://example.com)
A valid Android package name (e.g., com.example.app) for native Android apps
A valid iOS bundle identifier (e.g., com.example.iosapp) for native iOS apps

OTP enforcement logic:

If this field is empty or omitted → OTP is required. The customer will be prompted to enter an OTP sent to the mobile number supplied during Third-Party Customer creation. The customer can choose to receive the OTP via SMS or voice call based on their preference.
If this field is set (contains one or more entries) → OTP is not required.

Notes:

Wildcards or regular expressions are not supported.
If this field is not provided, the session will be accessible from any origin and OTP will be enforced as described above.

1	import requests
2
3	url = "https://api.redpincompany.com/v1/customers/customer_123/sessions"
4
5	payload = {
6	"client_customer_ref": "CUST-1001-TXN",
7	"client_reference_id": "PAY-2025-08-15-001",
8	"amount": {
9	"currency": "AED",
10	"value": 125000
11	},
12	"due_date": "2025-08-15",
13	"purpose_of_transaction": "PROPERTY_PURCHASE",
14	"recipient_details": [
15	{
16	"amount": {
17	"currency": "AED",
18	"value": 125000
19	},
20	"recipient": {
21	"name": "ABC Real Estate Development LLC",
22	"type": "Corporate",
23	"payment_reference": "SEASIDE-MULTI-AUG",
24	"customer_own_account": "no",
25	"address": {
26	"address_line": "Downtown District",
27	"city": "Dubai",
28	"state": "Dubai",
29	"country": "ARE",
30	"post_code": "12345"
31	},
32	"recipient_bank_details": {
33	"currency": "AED",
34	"iban": "AE070331234567890123456"
35	},
36	"purpose_of_transaction": "PROPERTY_PURCHASE"
37	}
38	}
39	],
40	"items": [
41	{
42	"item_name": "Seaside Towers - Unit 1204 - Installment 2 of 4",
43	"amount": {
44	"currency": "AED",
45	"value": 50000
46	},
47	"item_ref": "INV-2025-10234",
48	"item_type": "installment"
49	},
50	{
51	"item_name": "Seaside Towers - Unit 1204 - Service charge Q2",
52	"amount": {
53	"currency": "AED",
54	"value": 3500
55	},
56	"item_ref": "INV-2025-10235",
57	"item_type": "service_charge"
58	},
59	{
60	"item_name": "Seaside Towers - Unit 2108 - Installment 3 of 6",
61	"amount": {
62	"currency": "AED",
63	"value": 65000
64	},
65	"item_ref": "INV-2025-10236",
66	"item_type": "installment"
67	},
68	{
69	"item_name": "Seaside Towers - Unit 2108 - Admin fee",
70	"amount": {
71	"currency": "AED",
72	"value": 6500
73	},
74	"item_ref": "INV-2025-10237",
75	"item_type": "admin_fee"
76	}
77	],
78	"allowed_origins": ["https://app.example.com"],
79	"callbacks": ["https://webhook.example.com/redpin/session-update"]
80	}
81	headers = {
82	"Authorization": "Bearer <token>",
83	"Content-Type": "application/json"
84	}
85
86	response = requests.post(url, json=payload, headers=headers)
87
88	print(response.json())

1	{
2	"session_id": "cbf9e10a-b876-491c-9c28-0d1be0581bf7",
3	"client_reference_id": "PAY-2025-001-TXN",
4	"expires_at": "2025-07-03T08:18:53Z",
5	"session_url": "https://app.redpin.com/session/cbf9e10a-b876-491c-9c28-0d1be0581bf7"
6	}