Create a payment session | Redpin

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

The OAuth 2.0 Authenticated Create Payment Session API allows you to create a new hosted payment session. You provide the payment details (amount, 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 a cross-border property payment. 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, 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.

property_refstringRequired

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.

payment_detailsobjectRequired

allowed_originslist of stringsOptional

A list of allowed domain origins from which the hosted payment session can be launched. 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

Note

Wildcards or regular expressions are not supported.
If this field is not provided, the session will be accessible from any origin (i.e., no origin-based restriction will be applied).

A list of allowed domain origins from which the hosted payment session can be launched. 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 **Note** - Wildcards or regular expressions are **not supported**. - If this field is **not provided**, the session will be accessible from **any origin** (i.e., no origin-based restriction will be applied).

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.

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

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

1	curl -X POST https://api.redpincompany.com/v1/customers/customer_123/sessions \
2	-H "Authorization: Bearer <token>" \
3	-H "Content-Type: application/json" \
4	-d '{
5	"client_customer_ref": "CUST-1001-TXN",
6	"property_ref": "PROPERTY-001",
7	"payment_details": {
8	"type": "expression of interest",
9	"amount": {
10	"currency": "AED",
11	"value": 5000.5
12	},
13	"due_date": "2025-08-15",
14	"recipient_details": [
15	{
16	"amount": {
17	"currency": "AED",
18	"value": 3000.25
19	},
20	"recipient": {
21	"name": "John Doe",
22	"type": "Individual",
23	"payment_reference": "RentAug",
24	"customer_own_account": "no",
25	"address": {
26	"address_line": "51 Moorgate",
27	"city": "Dubai",
28	"state": "Dubai",
29	"country": "ARE",
30	"post_code": "123456"
31	},
32	"recipient_bank_details": {
33	"currency": "AED",
34	"iban": "AE070331234567890123456"
35	}
36	}
37	},
38	{
39	"amount": {
40	"currency": "AED",
41	"value": 2000.25
42	},
43	"recipient": {
44	"name": "Jane Smith",
45	"type": "Corporate",
46	"payment_reference": "payment_reference",
47	"customer_own_account": "yes",
48	"address": {
49	"address_line": "221B Baker Street",
50	"city": "Dubai",
51	"state": "Dubai",
52	"country": "ARE",
53	"post_code": "508206"
54	},
55	"recipient_bank_details": {
56	"currency": "AED",
57	"iban": "GB29NWBK60161331926819"
58	}
59	}
60	}
61	]
62	},
63	"allowed_origins": [
64	"https://app.example.com"
65	],
66	"callbacks": [
67	"https://webhook.example.com/redpin/session-update"
68	]
69	}'

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