Collect
Payment Sessions
Introduction to Payment Sessions
The Payment Sessions API is a unified solution designed to streamline payment processing for merchants.
The following table summarises the differences:
The transitions below ensure that the payment session lifecycle is fully traceable and supports retries where appropriate:
Key Features
- Flexible Payment Flows: Handle one-time payments, first-time setup payments for subscriptions, and repeat charges with minimal effort.
- Branded Checkout Experience: Redirect your customers to a secure, customizable checkout page to complete their transactions.
- Seamless Recurring Payments: Use saved payment methods for a series of transactions initiated and completed without customer interaction.
Benefits
- Simplicity: Manage various payment scenarios with a single API.
- Customizability: Tailor the payment experience to fit your brand.
- Scalability: Support a variety of payment methods and grow your business globally.
How It Works
1
Create a Payment Session
Start by creating a payment session with all necessary details like amount, currency, and payment type.
2
Redirect if Required
- For payments, where the customer is present, redirect them to the checkout page provided in the
session_urlto complete the payment. - For recurring payments, where the customer is not present, use the customer’s saved payment method for processing the payment without any customer interaction.
3
Track Payment Status
Monitor the status of your payments in real-time using webhooks or API calls.
Session Type
The API supports three distinct types of payment sessions to uniformly handle both customer-present and customer-not-present payments, as follows:one_time: A one-time payment, where the customer is present in the flow and completes the payment in real-time. This session type also offers the flexibility to save the customer’s payment method for future use during other payments where the customer is present in the flow.first_in_series: The first payment in a series, where the customer is present in the flow, allowing the customer to authorise and save their payment method for future payments where the customer is not present in the flow. This authorisation is referred to as a mandate. This session type is typically used to set up recurring payments, such as subscriptions or installment plans.next_in_series: A next payment in a series, where the customer is not present in the flow, using a previously saved payment method and relying on an existing mandate. This session type is fully programmatic, requires no customer interaction, and is ideal for recurring payments like monthly subscriptions or utility bills.
A mandate is an authorisation that allows a merchant to initiate future payments when the customer is not present in the flow.
The following table summarises the differences:
one_time | first_in_series | next_in_series | |
|---|---|---|---|
| Primary Purpose | One-time payment by the customer. | First payment to set up future automatic payments. | Next payment in a series. |
| Customer Interaction | Required (customer is present). | Required (customer is present). | Not required (customer is absent). |
| Saving Payment Method | Optional (for customer present use). | Mandatory (for customer absent use). | Not applicable (uses saved method). |
| Mandate Creation | No mandate created. | Mandate created for future payments. | Relies on an existing mandate. |
| Payment Flow | Customer completes via Checkout page. | Customer completes via Checkout page. | Payment processed programmatically. |
| Examples | One-off purchase with the option to save for future purchases. | Subscription setup or installment plan. | Monthly subscription charge or utility bill. |
Use Cases
There are multiple possible scenarios, each tailored to specific customer and merchant interactions. Below are some examples:One-Off Payment Without Saving the Payment Method
One-Off Payment Without Saving the Payment Method
- Scenario: A one-time payment where the customer is present, and the payment method is not saved for future use.
- Use Case: Customers making a one-time purchase without any desire to save their payment method for future use.
- Session Type:
one_time - Behavior:
- The customer completes the payment via the hosted Checkout page.
- The payment method is not saved because the
save_payment_methodoption is set tonever.
- Example: Buying a product or service without storing the card for future payments.
One-Off Payment With Saving the Payment Method
One-Off Payment With Saving the Payment Method
- Scenario: A one-time payment where the customer is present, and the payment method is only saved for future payments where the customer is present.
- Use Case: Customers who want to reuse their payment method for other purchases initiated by them in the future.
- Session Type:
one_time - Behavior:
- The customer completes the payment via the hosted Checkout page.
- The payment method is saved for use when the customer is present and the
save_payment_methodoption is set toalwaysorprompt.
- Example: Purchasing a product and saving the card for future use during checkout.
Setup for Future Payments
Setup for Future Payments
- Scenario: The first payment in a series where the customer is present, and the payment method is saved with a mandate for future payments.
- Use Case: Merchants setting up recurring payments for subscriptions or installment plans.
- Session Type:
first_in_series - Behavior:
- The customer completes the initial payment via the hosted Checkout page.
- A mandate is created authorising future payments that occur when the customer is not present.
- Example: Signing up for a monthly subscription with an initial payment.
Recurring Payments
Recurring Payments
- Scenario: A follow-up payment where the customer is not present, using a payment method saved in a previous
first_in_seriessession. - Use Case: A merchant initiates a recurring payment based on an existing mandate.
- Session Type:
next_in_series - Behavior:
- No customer interaction is required.
- The payment is processed programmatically using the saved payment method and existing mandate.
- Example: Charging a subscription fee each month.
A quick overview of the differences between these scenarios are as follows:
| Scenario | Session Type | Customer Interaction | Saving Payment Method | Examples |
|---|---|---|---|---|
| One-off payment without saving | one_time | Required (customer-present) | No | Buying a product one time. |
| One-off payment with saving | one_time | Required (customer-present) | Yes (for future customer-present use) | Purchasing and saving card for later. |
| Setup for future payments | first_in_series | Required (customer-present) | Yes (for future customer-not-present use) | Signing up for a subscription. |
| Recurring payment | next_in_series | Not required (customer-not-present) | Uses previously saved payment method | Monthly subscription charge. |
Status
Thestatus field of a payment session represents the current stage in the payment session lifecycle:
active
active
The session is currently in progress.
- For
one_timeandfirst_in_series: The session remains in an active state while the customer is interacting with the Checkout page via thesession_url. In the event of a failed payment, the session remains in an active state to allow a customer to make another payment attempt. In the event of a successful payment, the session transitions into a completed state. - For
next_in_series: The session is briefly in an active state while the payment is being processed without customer interaction using a saved payment method. In the event of both successful and failed payments, the session transitions into a completed state.
(payment_status) will reflect the outcome of the payment, either paid or unpaid. If the payment status is paid the payment_id field represents the associated payment.completed
completed
The session has completed.
- For
one_timeandfirst_in_series: The session has completed with the customer having completed the payment flow. This typically implies the payment was successful, but should be verified by interrogating the payment status(payment_status)as described below. - For
next_in_series: The session has completed without customer interaction using a saved payment method, but the payment may have either suceeded or failed. The status should verified by interrogating the payment status field(payment_status)as described below.
(payment_status) will reflect the outcome of the payment, either paid or unpaid. If the payment status is paid the payment_id field represents the associated payment.expired
expired
The session expired due to inactivity or a timeout.
- For
one_timeandfirst_in_series: The customer did not complete the checkout process in time. - For
next_in_series: Not applicable.
cancelled
cancelled
The session was explicitly cancelled by the customer or merchant.
- For
one_timeandfirst_in_series: The customer or merchant chose to cancel the payment. - For
next_in_series: Not applicable
One Time and First In Series Payment Sessions
One Time and First In Series Payment Sessions
| From State | To State | Condition | Description |
|---|---|---|---|
active | completed | Payment was successful. | The session completed successfully, and the payment was successful. The payment status (payment_status) will reflect the outcome of the payment as paid. |
active | active | Payment failed. | The session remains in an active state after a failed payment to allow the customer to make another payment attempt. |
active | expired | The session timed out due to inactivity. | The session expired because the customer didn’t complete the payment or the authorization timed out. |
active | cancelled | The session was explicitly cancelled by the customer or merchant. | The session was cancelled during checkout or before the programmatic payment was processed. |
Next In Series Payment Sessions
Next In Series Payment Sessions
| From State | To State | Condition | Description |
|---|---|---|---|
active | completed | Payment was successful. | The session completed successfully, and the payment was successful. The payment status (payment_status) will reflect the outcome of the payment as paid. |
active | completed | Payment failed. | The session completed successfully, however the payment failed. The payment status (payment_status) will reflect the outcome of the payment as unpaid. |
Webhooks
The state of the payment session can be tracked by consuming webhook events. The event will contain apayment_session object that includes, amongst other fields, the created_at, updated_at and payment_id fields.
Where applicable the customer_id and payment_method_id fields, that are needed for a subsequent (next_in_series) payment, is also included, and is sometimes referred to as a token.
The payment session events are:
payment_session.created: Indicates a payment session was created successfully and can be used to initiate the payment process. See the payment_session.created event for more information.payment_session.updated: Indicates a payment session was updated successfully and can be used for tracking the status of the payment session. See the payment_session.updated event for more information.