Simply integrate with our Checkout API library and you are ready to accept payments!
The Checkout API should only be called from your server. This flow ensures the security of your payments and provides a trusted result to your server.
1. Create the Checkout
The Checkout API requires authenticated access, see here for more details.
A Checkout represents what your customer sees on the payment page such as the amount to collect, currency and any other additional details. Add an endpoint on your server that creates a Checkout.
|The secret key for your account.|
|An optional idempotency key enables you to safely retry a request without risking the user being charged multiple times.|
|The final amount you would like to charge the customer, in cents. Including all the discounts and applicable taxes.|
|The 3-letter currency code in ISO 4217 format. Currently we only support |
|The URL to redirect customers to when the checkout is cancelled.|
|The URL to optionally redirect customers to when the checkout completes successfully.|
|The URL to optionally redirect customers to when the checkout does not complete successfully.|
|Used to record additional details about the checkout, often used to reconcile data with an external system.|
|The total discount, in cents, is used for display only. It must already be included in the amount to collect.|
|The total tax, in cents, is used for display only. It must already be included in the amount to collect.|
|The subtotal, in cents, is used for display only and represents the total value collected including taxes and excluding discounts.|
|The line items are used for display only and provide additional details for the items purchased during checkout.|
We do not recommend using the successUrl as a way to verify if the payment was successful. Rather follow the instructions in Step 3: Verify that the payment is successful.
The following fields are solely utilised for display purposes and never subject to validation: totalDiscount, totalTaxAmount, subtotalAmount and lineItems.
Before creating the Checkout, it is important to do your own validation on these fields.
Replace <secret-key> with your secret API integration key. For more information, see here.
We do not accept payments that are less than R2.
The Checkout response contains a
redirectUrl which is used to redirect the customer to the checkout page.
You should retain the id and redirectUrl returned. This will be used in the following steps.
2. Redirect the customer to the Checkout page
After creating the Checkout, redirect your customer to the
This will redirect the customer to the checkout page where they can complete the payment.
3. Verify that the payment is successful
When a payment is successful, we will send a webhook event to your server. It is highly recommended to use webhooks to check the payment status before fulfilling the order.
For more information on receiving webhook events, see here.
The status of the payment can be verified by referring to the
type field of the webhook event.
A payment is considered successful if its
type is marked as
For more information about the successful payment event, see here.
The Checkout API uses conventional HTTP response codes to indicate the success or failure of requests. In general, codes in the
2xx range indicate success.
Codes in the
4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, etc.).
Codes in the
5xx range indicate an error with our servers. (These do not happen often.)
|CORS||The request is not being sent over HTTPS from your server. Browser security prevents a web page from making requests to a different domain than the one that served the web page. This restriction is called the ||Ensure you are making calls to the the Checkout API from your server and use HTTPs for those calls. This also ensures your secret key is not exposed.|
HTTP response errors
Below are potential errors that may occur, along with additional information to assist you in resolving them. Please note that this list is not exhaustive.
|A key is required, but has not been specified.||Secret API key is not included in header, or is incorrect.||Confirm that the |
|Conflict||A request with the same idempotency key is already being processed.||Try again later, or use a different idempotency key.|
|The request payload (method, path, parameters) does not match the original request.||An initial request was sent with an idempotency key, followed by a subsequent request with the same idempotency key.||Confirm that the |