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
limitinteger · min: 1 · max: 100Number of records to return per page. Use with cursor-based pagination.
Default: 10firstinteger · min: 1 · max: 100Number of records to return for forward pagination. Use with
aftercursor.afterstringCursor for forward pagination. Returns records after this cursor.
lastinteger · min: 1 · max: 100Number of records to return for backward pagination. Use with
beforecursor.beforestringCursor for backward pagination. Returns records before this cursor.
statusstring · enumFilter checkout sessions by status.
Enum values:opencompleteexpiredcurrencystring · enumFilter checkout sessions by currency ISO code.
Enum values:usdzwgstart_datestring · dateFilter checkout sessions created on or after this date. Use ISO 8601 format (YYYY-MM-DD).
end_datestring · dateFilter checkout sessions created on or before this date. Use ISO 8601 format (YYYY-MM-DD).
Responses
A list of checkout sessions
objectstringType of the returned object.
dataobject[]Array of checkout session objects.
pagingobjectPagination 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.
Request Body
line_itemsobject[] · requiredA 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.
modestring · enum · requiredThe mode of the Checkout Session. Currently only supports
paymentas the mode for one time purchases.In the future, other modes like subscription or setup might be supported.
Enum values:paymentsuccess_urlstring · uri · requiredThe 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_urlstring · uri · requiredThe 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.
currencystring · enum · requiredA three-letter ISO currency code. Currently, only
usdandzwgare supported.All line items in the checkout must use the same currency.
Enum values:zwgusd
customer_emailstring · 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_idstringA 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.
sourcestring · enumThe 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
Enum values:poswebmobileussdmetadataobject · maxProps: 5A 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.
expandstring[]Specifies which fields in the response should be expanded. Currently, only
line_itemsis supported for expansion.When
line_itemsis included in the expand array, the response will include the complete line item details rather than just IDs.submit_typestring · enumThis 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
Enum values:paydonatebookDefault: paypayment_method_typesstring[]A 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
Enum values:ecocashonemoneycardzimswitch
Responses
Checkout session created successfully
idstringUnique identifier for the checkout session. This ID is used to reference the session in other API calls.
objectstringString representing the object's type. Always
"checkout_session"for checkout session objects.statusstring · enumThe 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.
Enum values:opencompleteexpiredmodestring · enumThe mode of the Checkout Session. Currently only supports
paymentfor one-time purchases.In the future, other modes like subscription or setup might be supported.
Enum values:paymentmetadataobjectSet 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.
currencystringA three-letter ISO currency code. This is the currency used for all items in the checkout session.
urlstring · uriThe 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.
livemodebooleanHas 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_typesstring[]A 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 (
cardandzimswitch) are only available through Checkout Sessions and cannot be used with charges.client_secretstringA 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_totalintegerTotal 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_idstringA 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_atintegerThe 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_referencestringThe 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.
createdintegerTime 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_subtotalintegerTotal 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_urlstring · uriThe 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_emailstring · 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_statusstring · enumThe 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.
Enum values:requires_payment_methodpendingsucceededfailedcancelledfailure_codestringError 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_reasonstringA 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_urlstring · uriThe URL to redirect customers upon successful payment.
After completing the payment, the customer will be redirected to this URL.
submit_typestring · enumDescribes 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
Enum values:paydonatebookshippingobjectShipping 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.
line_itemsobject[]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_itemswas included in theexpandarray 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
idstring · requiredUnique identifier for the checkout session
query Parameters
expandstring · enumSpecifies which fields in the response should be expanded
Enum values:line_items
Responses
Checkout session details retrieved successfully
idstringUnique identifier for the checkout session. This ID is used to reference the session in other API calls.
objectstringString representing the object's type. Always
"checkout_session"for checkout session objects.statusstring · enumThe 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.
Enum values:opencompleteexpiredmodestring · enumThe mode of the Checkout Session. Currently only supports
paymentfor one-time purchases.In the future, other modes like subscription or setup might be supported.
Enum values:paymentmetadataobjectSet 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.
currencystringA three-letter ISO currency code. This is the currency used for all items in the checkout session.
urlstring · uriThe 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.
livemodebooleanHas 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_typesstring[]A 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 (
cardandzimswitch) are only available through Checkout Sessions and cannot be used with charges.client_secretstringA 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_totalintegerTotal 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_idstringA 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_atintegerThe 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_referencestringThe 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.
createdintegerTime 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_subtotalintegerTotal 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_urlstring · uriThe 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_emailstring · 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_statusstring · enumThe 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.
Enum values:requires_payment_methodpendingsucceededfailedcancelledfailure_codestringError 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_reasonstringA 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_urlstring · uriThe URL to redirect customers upon successful payment.
After completing the payment, the customer will be redirected to this URL.
submit_typestring · enumDescribes 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
Enum values:paydonatebookshippingobjectShipping 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.
line_itemsobject[]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_itemswas included in theexpandarray 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
idstring · requiredUnique identifier for the checkout session
Responses
Checkout session expired successfully
idstringUnique identifier for the checkout session. This ID is used to reference the session in other API calls.
objectstringString representing the object's type. Always
"checkout_session"for checkout session objects.statusstring · enumThe 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.
Enum values:opencompleteexpiredmodestring · enumThe mode of the Checkout Session. Currently only supports
paymentfor one-time purchases.In the future, other modes like subscription or setup might be supported.
Enum values:paymentmetadataobjectSet 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.
currencystringA three-letter ISO currency code. This is the currency used for all items in the checkout session.
urlstring · uriThe 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.
livemodebooleanHas 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_typesstring[]A 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 (
cardandzimswitch) are only available through Checkout Sessions and cannot be used with charges.client_secretstringA 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_totalintegerTotal 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_idstringA 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_atintegerThe 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_referencestringThe 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.
createdintegerTime 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_subtotalintegerTotal 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_urlstring · uriThe 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_emailstring · 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_statusstring · enumThe 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.
Enum values:requires_payment_methodpendingsucceededfailedcancelledfailure_codestringError 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_reasonstringA 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_urlstring · uriThe URL to redirect customers upon successful payment.
After completing the payment, the customer will be redirected to this URL.
submit_typestring · enumDescribes 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
Enum values:paydonatebookshippingobjectShipping 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.
line_itemsobject[]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_itemswas included in theexpandarray when creating or retrieving the checkout session.