API ReferenceCustomersHosted ExperienceSessions

Create a payment session

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.) and session configuration (like allowed domains), 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. For real-time payment status updates, use the Webhook Subscription API to subscribe to the [PAYMENT STATUS](/api-reference/customers/api-integration/webhooks/create-webhook) event.

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

  • Uniqueness is enforced for third-party payments only: must be unique per customer (per Redpin customer_id); duplicate references for the same customer will be rejected. Hosted sessions are third-party, so this applies.
  • Maximum length: 36 characters
  • Allowed characters: alphanumeric (A-Z, a-z, 0-9), hyphens (-), and underscores (_)
amountobjectRequired
due_datedateRequired

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

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

400
Bad Request Error
500
Internal Server Error