Payer Checkout API
Accept Payments Online with Payer
Last updated
Accept Payments Online with Payer
Last updated
Payer Checkout allows apps and websites to accept payments online from Payer customers. This documentation provides a comprehensive overview of the API endpoints and processes involved with integrating Payer Checkout into your platform.
The Payer Checkout API uses a redirect-response flow similar to most payment gateways. You can generate a checkout URL and pass it to your customer or redirect them to the page. Once the transaction is completed, Payer will redirect the user back to your application with the transaction details. The following sequence diagram demonstrates the flow in detail:
Each merchant receives a security token and a secret key. The token must be used as an Authorization header for all API calls, allowing the server to identify the merchant. When creating a checkout link, an additional HMAC-SHA256 signature is required. This signature is generated using your secret key, and the server will verify it using the same key.
Merchants can regenerate tokens anytime using the Merchant Portal by selecting the "API Tokens" option.
A redirect URL must be provided when creating a token. Upon completing the transaction, the user will be redirected to this URL along with the response parameters.
Development Environment: https://api.nonprod.payer.app
Production Environment: https://api.payer.app
The first step to accepting a payment with Payer is to create a Checkout URL. You can generate the Checkout URL by making a POST request to /checkout/sessions.
The HMAC signature is generated by combining the amount and reference number and signing it with the secret key. Additionally, the signature should be base64 encoded.
Signature Example
Data to Sign: AMOUNT + REFERENCE = 100KF/2014
Secret: test_secret
Generated Signature: zXXwmHYLpBVrFLvN3r8JTWJmPjWIaJHpRmxX+PhVzUo=
Success (200)
For a successful request, the server will return a 200 status code with the following response. The merchant must redirect the user to the provided URL. Once the transaction is completed, the user will be redirected back to the merchant's callback URL.
Invalid Token (419)
f the provided token is invalid, the server returns a 419 status code.
Response Error (422)
If the request contains errors, the server returns a 422 status code with a descriptive error message.
Upon completion or cancellation of the transaction, the user is redirected to the merchant's callback URL. The response data is posted, and the merchant can verify the authenticity of the response by generating an HMAC signature containing amount, reference and status and cross-referencing it with the signature posted from the server. Use this information to identify the transaction status and perform post-transaction operations such as issuing notifications or updating records.
If your request fails during transit or if you need to retrieve the payment details for any reason, you can call the retrieve transaction endpoint. You can pass the UUID or reference to retrieve the payment details.
If you need to cancel a payment for any reason, you can make a POST request to the cancel payment URL. You'll need to provide the UUID as the query parameter.
You can generate this signature online using .
You can find our starter application on GitHub. Clone the repository and get started:
