Accept Payments
Simply integrate with our Checkout API library and you are ready to accept payments!
caution
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.
Steps
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.
Headers
| Parameter | Type | Description |
|---|---|---|
| Authorization | string | The secret key for your account. |
| Idempotency-Key | string | An optional idempotency key enables you to safely retry a request without risking the user being charged multiple times. |
Body
| Parameter | Type | Description |
|---|---|---|
| amount | integer | The final amount you would like to charge the customer, in cents. Including all the discounts and applicable taxes. |
| currency | string | The 3-letter currency code in ISO 4217 format. Currently we only support ZAR. |
| cancelUrl | string | The URL to redirect customers to when the checkout is cancelled. |
| successUrl | string | The URL to optionally redirect customers to when the checkout completes successfully. |
| failureUrl | string | The URL to optionally redirect customers to when the checkout does not complete successfully. |
| metadata | map | Used to record additional details about the checkout, often used to reconcile data with an external system. |
| totalDiscount | integer | The total discount, in cents, is used for display only. It must already be included in the amount to collect. |
| totalTaxAmount | integer | The total tax, in cents, is used for display only. It must already be included in the amount to collect. |
| subtotalAmount | integer | The subtotal, in cents, is used for display only and represents the total value collected including taxes and excluding discounts. |
| lineItems | list | The line items are used for display only and provide additional details for the items purchased during checkout. |
important
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.
caution
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.
Sample request
- cURL
important
Replace <secret-key> with your secret API integration key. For more information, see here.
important
We do not accept payments that are less than R2.
Sample response
The response contains a redirectUrl which is used to redirect the customer to the checkout page.
- Successful
important
You should retain the id and redirectUrl returned. This will be used in the following steps.
More examples:
2. Redirect the customer to the Checkout page
After creating the Checkout, redirect your customer to the redirectUrl.
This will redirect the customer to the checkout page where they can complete the payment.
3. Verify that the payment is successful
Now all you need to do is confirm the payment status so that you can fulfill the customer's order after they pay. You can do this by retrieving the status of the Checkout.
To determine the payment status, you need to examine the status field provided in the above response.
A payment is considered successful if it has a completed status.
| Checkout status | Description |
|---|---|
created | The Checkout has been created, but the checkout page has not been visited. |
started | The checkout page has been visited. |
processing | Waiting on payment result. |
completed | The payment was completed. |
refunded | The payment was refunded. |
reversed | The payment was reversed. |
Add an endpoint to get the Checkout using the id from the response in Step 1: Create the Checkout.
Headers
| Parameter | Type | Description |
|---|---|---|
| Authorization | string | The secret key for your account |
Sample request
- cURL
important
Replace <secret-key> with your secret API integration key. For more information, see here.
Sample response
- Successful
Errors
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.)
General errors
| Description | Reason | Solution |
|---|---|---|
| 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 same-origin policy. | 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.
| Status code | Description | Reason | Solution |
|---|---|---|---|
403 | A key is required, but has not been specified. | Secret API key is not included in header, or is incorrect. | Confirm that the Authorization header is included in your request and that the API key is correct. For more information, see here. |
409 | Conflict | A request with the same idempotency key is already being processed. | Try again later, or use a different idempotency key. |
422 | 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 Idempotency-Key header is unique for each request. |