Checkout Sessions
A Checkout Session represents your customer's session as they pay for one-time purchases through Checkout. Checkout Sessions provide a simple way to create a payment page for your customers.
List checkout sessions
Returns a paginated list of checkout sessions. The sessions are returned sorted by creation date, with the most recently created sessions appearing first.
Using pagination
By default, this endpoint returns 10 checkout sessions per page. You can adjust this with the limit parameter
and navigate through pages using the after cursor returned in the paging object.
Code
query Parameters
limitNumber of records to return per page. Use with cursor-based pagination.
firstNumber of records to return for forward pagination. Use with after cursor.
afterCursor for forward pagination. Returns records after this cursor.
lastNumber of records to return for backward pagination. Use with before cursor.
beforeCursor for backward pagination. Returns records before this cursor.
statusFilter checkout sessions by status.
currencyFilter checkout sessions by currency ISO code.
start_dateFilter checkout sessions created on or after this date. Use ISO 8601 format (YYYY-MM-DD).
end_dateFilter checkout sessions created on or before this date. Use ISO 8601 format (YYYY-MM-DD).
List checkout sessions › Responses
A list of checkout sessions
objectType of the returned object.
Array of checkout session objects.
Pagination metadata
Create a checkout session
Creates a new checkout session for a customer to complete a purchase. A checkout session represents a customer's session as they pay for one-time purchases using Checkout.
Request Body Example
Code
Using the Checkout Session
After creating a checkout session, redirect your customer to the URL provided in the url field of the session object.
This will take them to the Payonify hosted checkout page where they can securely complete their payment.
Checkout Session Status
A checkout session can have one of the following statuses:
open: The checkout session is still active and can be used by the customer.complete: The checkout session has been completed successfully.expired: The checkout session has expired and can no longer be used.
Create a checkout session › Request Body
A list of items the customer is purchasing. Each item in the list represents a product or service that will be displayed to the customer on the checkout page.
At least one line item must be provided.
modeThe mode of the Checkout Session. Currently only supports payment as the
mode for one time purchases.
In the future, other modes like subscription or setup might be supported.
success_urlThe URL to which Payonify should return customers upon successful payment.
After completing the payment, the customer will be redirected to this URL.
You can include the session ID in the URL by adding the {CHECKOUT_SESSION_ID}
placeholder, which will be replaced with the actual session ID.
Example: https://example.com/success?session_id={CHECKOUT_SESSION_ID}
cancel_urlThe URL that will appear on the Checkout page so that if customers need to cancel and go back to your website they can.
If the customer clicks the "back" or "cancel" button on the checkout page, they will be redirected to this URL.
currencyA three-letter ISO currency code. Currently, only usd and zwg are supported.
All line items in the checkout must use the same currency.
customer_emailIf provided it will be used to prefill customer data on the checkout page. This improves the checkout experience by eliminating the need for the customer to manually enter their email.
client_reference_idA unique string to reference the Checkout Session. This can be anything your system can generate, e.g. Customer ID or Cart ID.
This can be used to reconcile the checkout session with your internal systems, such as an order management system.
sourceThe source of the checkout request. This indicates where the checkout session is originating from.
pos: Point of Sale systemweb: Web applicationmobile: Mobile applicationussd: USSD service
A set of key-value pairs that can be attached to an object. This is useful for storing additional information about the checkout session in a structured way.
You can specify up to 5 keys, with key names up to 40 characters long and values up to 500 characters long.
Metadata is not displayed to the customer.
expandSpecifies which fields in the response should be expanded. Currently,
only line_items is supported for expansion.
When line_items is included in the expand array, the response will include
the complete line item details rather than just IDs.
submit_typeThis is used to customize the text on the Checkout page for the submit button. Different types convey different intentions to the customer.
pay: Standard payment (default)donate: Donation to a causebook: Booking a service or reservation
payment_method_typesA list of the types of payment methods this Checkout Session can accept. If omitted, all active payment methods for the selected currency will be used.
Available payment methods:
ecocash: Mobile money via Econet EcoCashonemoney: Mobile money via NetOne OneMoneycard: Card payments (Visa, Mastercard) - USD onlyzimswitch: Card payments via Zimswitch
Create a checkout session › Responses
Checkout session created successfully
idUnique identifier for the checkout session. This ID is used to reference the session in other API calls.
objectString representing the object's type. Always "checkout_session" for
checkout session objects.
statusThe status of the Checkout Session. This indicates the current state of the checkout process.
open: The checkout session is still active and can be used by the customer.complete: The checkout session has been completed successfully.expired: The checkout session has expired and can no longer be used.
modeThe mode of the Checkout Session. Currently only supports payment for
one-time purchases.
In the future, other modes like subscription or setup might be supported.
Set of key-value pairs attached to the object. This contains the metadata that was provided when creating the checkout session.
This can be used to store additional information about the checkout session for internal purposes.
currencyA three-letter ISO currency code. This is the currency used for all items in the checkout session.
urlThe URL of the Checkout Session that the customer should be redirected to.
After creating a checkout session, redirect your customer to this URL to complete the payment on the Payonify hosted checkout page.
livemodeHas the value true if the object exists in live mode or the value false if the object exists in test mode.
This helps distinguish between test transactions and real payments.
payment_method_typesA list of the types of payment methods this Checkout Session can accept.
This array contains all the payment methods that will be available to the customer on the checkout page.
Available payment methods:
ecocash: Mobile money via Econet EcoCashonemoney: Mobile money via NetOne OneMoneycard: Card payments (Visa, Mastercard) - USD only, checkout onlyzimswitch: Card payments via Zimswitch - checkout only
Note: Card payments (card and zimswitch) are only available through
Checkout Sessions and cannot be used with charges.
client_secretA client secret for the charge associated with this checkout session.
This secret is used when implementing client-side confirmation of payments. It should be kept secure and only used in secure contexts.
amount_totalTotal of all items after discounts and taxes.
This is the final amount that will be charged to the customer, represented in the smallest unit of the currency (e.g., cents).
client_reference_idA unique string to reference the Checkout Session. This is the same ID that was provided when creating the session, or an auto-generated one if none was provided.
This can be used to reconcile the checkout session with your internal systems.
expires_atThe time in seconds (Unix epoch) at which the Checkout Session will expire.
By default, checkout sessions expire after 24 hours. Once expired, they can no longer be used to complete a payment.
charge_referenceThe Charge reference associated with this Checkout Session.
When a checkout session is created, a charge is also created in a pending state. This is the ID of that charge, which can be used to retrieve details or perform operations on the charge if needed.
createdTime at which the object was created. Measured in seconds since the Unix epoch.
This timestamp can be used to track when the checkout session was initially created.
amount_subtotalTotal of all items before any discounts or taxes.
This is the sum of (unit_amount * quantity) for all line items, represented in the smallest unit of the currency (e.g., cents).
cancel_urlThe URL to redirect customers who cancel checkout.
If the customer clicks the "back" or "cancel" button on the checkout page, they will be redirected to this URL.
customer_emailCustomer email address. If provided when creating the checkout session, this will be pre-filled on the checkout page.
This improves the checkout experience by eliminating the need for the customer to manually enter their email.
payment_statusThe payment status of the Checkout Session. This indicates the current state of the payment process.
requires_payment_method: The customer has not yet provided a payment method.pending: The payment is being processed.succeeded: The payment completed successfully.failed: The payment attempt failed.cancelled: The payment was cancelled.
failure_codeError code for a failed checkout payment. This field will be populated only if the payment failed. The code can be used to programmatically handle specific error cases.
If the payment was processed successfully, this field will be null.
failure_reasonA human-readable message providing more details about why the payment failed. This message can be displayed to the user or used for debugging.
If the payment was processed successfully, this field will be null.
success_urlThe URL to redirect customers upon successful payment.
After completing the payment, the customer will be redirected to this URL.
submit_typeDescribes the type of transaction being performed. This affects the text displayed on the submit button on the checkout page.
pay: Standard payment (default)donate: Donation to a causebook: Booking a service or reservation
Shipping information for the charge. This object contains delivery details for physical goods, including the recipient's name, address, and shipping method.
This information is optional but recommended for charges related to physical goods to help with order tracking and delivery.
A list of items the customer is purchasing. Each item in the list represents a product or service that will be displayed to the customer on the checkout page.
This field is only included in the response if line_items was included in
the expand array when creating or retrieving the checkout session.
Retrieve a checkout session
Retrieves the details of an existing checkout session. You can use this endpoint to check the status of a checkout session.
Retrieving line items
By default, this endpoint returns basic information about the checkout session. To include detailed
line item information, use the expand query parameter with the value line_items.
Code
Payment Status
The payment associated with a checkout session can have one of these statuses:
requires_payment_method: The customer has not yet provided a payment method.pending: The payment is being processed.succeeded: The payment completed successfully.failed: The payment attempt failed.cancelled: The payment was cancelled.
path Parameters
idUnique identifier for the checkout session
query Parameters
expandSpecifies which fields in the response should be expanded
Retrieve a checkout session › Responses
Checkout session details retrieved successfully
idUnique identifier for the checkout session. This ID is used to reference the session in other API calls.
objectString representing the object's type. Always "checkout_session" for
checkout session objects.
statusThe status of the Checkout Session. This indicates the current state of the checkout process.
open: The checkout session is still active and can be used by the customer.complete: The checkout session has been completed successfully.expired: The checkout session has expired and can no longer be used.
modeThe mode of the Checkout Session. Currently only supports payment for
one-time purchases.
In the future, other modes like subscription or setup might be supported.
Set of key-value pairs attached to the object. This contains the metadata that was provided when creating the checkout session.
This can be used to store additional information about the checkout session for internal purposes.
currencyA three-letter ISO currency code. This is the currency used for all items in the checkout session.
urlThe URL of the Checkout Session that the customer should be redirected to.
After creating a checkout session, redirect your customer to this URL to complete the payment on the Payonify hosted checkout page.
livemodeHas the value true if the object exists in live mode or the value false if the object exists in test mode.
This helps distinguish between test transactions and real payments.
payment_method_typesA list of the types of payment methods this Checkout Session can accept.
This array contains all the payment methods that will be available to the customer on the checkout page.
Available payment methods:
ecocash: Mobile money via Econet EcoCashonemoney: Mobile money via NetOne OneMoneycard: Card payments (Visa, Mastercard) - USD only, checkout onlyzimswitch: Card payments via Zimswitch - checkout only
Note: Card payments (card and zimswitch) are only available through
Checkout Sessions and cannot be used with charges.
client_secretA client secret for the charge associated with this checkout session.
This secret is used when implementing client-side confirmation of payments. It should be kept secure and only used in secure contexts.
amount_totalTotal of all items after discounts and taxes.
This is the final amount that will be charged to the customer, represented in the smallest unit of the currency (e.g., cents).
client_reference_idA unique string to reference the Checkout Session. This is the same ID that was provided when creating the session, or an auto-generated one if none was provided.
This can be used to reconcile the checkout session with your internal systems.
expires_atThe time in seconds (Unix epoch) at which the Checkout Session will expire.
By default, checkout sessions expire after 24 hours. Once expired, they can no longer be used to complete a payment.
charge_referenceThe Charge reference associated with this Checkout Session.
When a checkout session is created, a charge is also created in a pending state. This is the ID of that charge, which can be used to retrieve details or perform operations on the charge if needed.
createdTime at which the object was created. Measured in seconds since the Unix epoch.
This timestamp can be used to track when the checkout session was initially created.
amount_subtotalTotal of all items before any discounts or taxes.
This is the sum of (unit_amount * quantity) for all line items, represented in the smallest unit of the currency (e.g., cents).
cancel_urlThe URL to redirect customers who cancel checkout.
If the customer clicks the "back" or "cancel" button on the checkout page, they will be redirected to this URL.
customer_emailCustomer email address. If provided when creating the checkout session, this will be pre-filled on the checkout page.
This improves the checkout experience by eliminating the need for the customer to manually enter their email.
payment_statusThe payment status of the Checkout Session. This indicates the current state of the payment process.
requires_payment_method: The customer has not yet provided a payment method.pending: The payment is being processed.succeeded: The payment completed successfully.failed: The payment attempt failed.cancelled: The payment was cancelled.
failure_codeError code for a failed checkout payment. This field will be populated only if the payment failed. The code can be used to programmatically handle specific error cases.
If the payment was processed successfully, this field will be null.
failure_reasonA human-readable message providing more details about why the payment failed. This message can be displayed to the user or used for debugging.
If the payment was processed successfully, this field will be null.
success_urlThe URL to redirect customers upon successful payment.
After completing the payment, the customer will be redirected to this URL.
submit_typeDescribes the type of transaction being performed. This affects the text displayed on the submit button on the checkout page.
pay: Standard payment (default)donate: Donation to a causebook: Booking a service or reservation
Shipping information for the charge. This object contains delivery details for physical goods, including the recipient's name, address, and shipping method.
This information is optional but recommended for charges related to physical goods to help with order tracking and delivery.
A list of items the customer is purchasing. Each item in the list represents a product or service that will be displayed to the customer on the checkout page.
This field is only included in the response if line_items was included in
the expand array when creating or retrieving the checkout session.
Expire a checkout session
Invalidates a checkout session that hasn't been used. This endpoint is useful when you want to explicitly expire a checkout session before its automatic expiration time.
After a checkout session is expired, it can no longer be used to complete a payment.
When to expire a session
Common scenarios for manually expiring a checkout session include:
- The customer changed their mind about the purchase
- The items in the cart are no longer available
- You want to create a new checkout session with updated pricing or items
path Parameters
idUnique identifier for the checkout session
Expire a checkout session › Responses
Checkout session expired successfully
idUnique identifier for the checkout session. This ID is used to reference the session in other API calls.
objectString representing the object's type. Always "checkout_session" for
checkout session objects.
statusThe status of the Checkout Session. This indicates the current state of the checkout process.
open: The checkout session is still active and can be used by the customer.complete: The checkout session has been completed successfully.expired: The checkout session has expired and can no longer be used.
modeThe mode of the Checkout Session. Currently only supports payment for
one-time purchases.
In the future, other modes like subscription or setup might be supported.
Set of key-value pairs attached to the object. This contains the metadata that was provided when creating the checkout session.
This can be used to store additional information about the checkout session for internal purposes.
currencyA three-letter ISO currency code. This is the currency used for all items in the checkout session.
urlThe URL of the Checkout Session that the customer should be redirected to.
After creating a checkout session, redirect your customer to this URL to complete the payment on the Payonify hosted checkout page.
livemodeHas the value true if the object exists in live mode or the value false if the object exists in test mode.
This helps distinguish between test transactions and real payments.
payment_method_typesA list of the types of payment methods this Checkout Session can accept.
This array contains all the payment methods that will be available to the customer on the checkout page.
Available payment methods:
ecocash: Mobile money via Econet EcoCashonemoney: Mobile money via NetOne OneMoneycard: Card payments (Visa, Mastercard) - USD only, checkout onlyzimswitch: Card payments via Zimswitch - checkout only
Note: Card payments (card and zimswitch) are only available through
Checkout Sessions and cannot be used with charges.
client_secretA client secret for the charge associated with this checkout session.
This secret is used when implementing client-side confirmation of payments. It should be kept secure and only used in secure contexts.
amount_totalTotal of all items after discounts and taxes.
This is the final amount that will be charged to the customer, represented in the smallest unit of the currency (e.g., cents).
client_reference_idA unique string to reference the Checkout Session. This is the same ID that was provided when creating the session, or an auto-generated one if none was provided.
This can be used to reconcile the checkout session with your internal systems.
expires_atThe time in seconds (Unix epoch) at which the Checkout Session will expire.
By default, checkout sessions expire after 24 hours. Once expired, they can no longer be used to complete a payment.
charge_referenceThe Charge reference associated with this Checkout Session.
When a checkout session is created, a charge is also created in a pending state. This is the ID of that charge, which can be used to retrieve details or perform operations on the charge if needed.
createdTime at which the object was created. Measured in seconds since the Unix epoch.
This timestamp can be used to track when the checkout session was initially created.
amount_subtotalTotal of all items before any discounts or taxes.
This is the sum of (unit_amount * quantity) for all line items, represented in the smallest unit of the currency (e.g., cents).
cancel_urlThe URL to redirect customers who cancel checkout.
If the customer clicks the "back" or "cancel" button on the checkout page, they will be redirected to this URL.
customer_emailCustomer email address. If provided when creating the checkout session, this will be pre-filled on the checkout page.
This improves the checkout experience by eliminating the need for the customer to manually enter their email.
payment_statusThe payment status of the Checkout Session. This indicates the current state of the payment process.
requires_payment_method: The customer has not yet provided a payment method.pending: The payment is being processed.succeeded: The payment completed successfully.failed: The payment attempt failed.cancelled: The payment was cancelled.
failure_codeError code for a failed checkout payment. This field will be populated only if the payment failed. The code can be used to programmatically handle specific error cases.
If the payment was processed successfully, this field will be null.
failure_reasonA human-readable message providing more details about why the payment failed. This message can be displayed to the user or used for debugging.
If the payment was processed successfully, this field will be null.
success_urlThe URL to redirect customers upon successful payment.
After completing the payment, the customer will be redirected to this URL.
submit_typeDescribes the type of transaction being performed. This affects the text displayed on the submit button on the checkout page.
pay: Standard payment (default)donate: Donation to a causebook: Booking a service or reservation
Shipping information for the charge. This object contains delivery details for physical goods, including the recipient's name, address, and shipping method.
This information is optional but recommended for charges related to physical goods to help with order tracking and delivery.
A list of items the customer is purchasing. Each item in the list represents a product or service that will be displayed to the customer on the checkout page.
This field is only included in the response if line_items was included in
the expand array when creating or retrieving the checkout session.