Overview
Use the Maya Checkout to initiate one-time online payments via e-wallets, QR Codes, or cards.
Leverage Maya Checkout to perform the following:
- Use Maya’s ready-made checkout form - no need to create your own.
- Offer your customers a variety of payment options.
Experience Maya Checkout on our demo website and test how it works using the Sandbox Credentials and Cards
.
API Sequence
Learn the API sequence and transaction flow of Maya Checkout.
- The customer provides Checkout information to the API Consumer.
- Your platform (or the API Consumer) sends the transaction details to Maya Checkout via the Create Checkout
endpoint.
- Maya Checkout processes the request and generates a
checkoutId
. - Maya Checkout responds to your platform with the
checkoutId
, andredirectUrl
. - Your platform will redirect the customer to the
redirectUrl
, obtained from the Create Checkoutresponse in Step 4.
- The customer chooses the payment method and completes the authorization process.
- If the customer does not choose a payment method, cancels, and clicks “Back to Merchant“; Maya Checkout will cancel the transaction and call redirectUrl.cancel from the redirectUrl object from the Create Checkout request.
- Once the customer completes the authorization process, Maya Checkout will initiate the processing of the payment transaction.
- Maya checkout processes the payment with the financial entity (issuing bank or wallet providers).
- Upon successful transaction processing, Maya Checkout will redirect the customer to your success page,
redirectUrl.success
, as provided in the redirectUrl object from the Create Checkoutrequest (Step 2).
- If the transaction fails, Maya Maya Checkout will redirect the customer to your failure page,
redirectUrl.failure
.
- If the transaction fails, Maya Maya Checkout will redirect the customer to your failure page,
- Maya Checkout sends a webhook notification to your platform.
- Your platform acknowledges the webhook payload and returns
200 OK
. Please avoid processing complex logic before you reply to webhook to prevent timeouts. - Your platform parses and processes the webhook payload.
- Your platform processes the transaction and notifies the customer for further updates.
Build your Integration
This solution uses Basic Authentication, which requires API keys to authenticate incoming requests. To obtain your API key, please refer to the Generate API Keys for Online Payments guide.
Build the required pages
Design and host your response web pages.
1. Create your Checkout button
Based on your envisioned customer journey, design and create a Checkout button within your page for your customers to initiate the checkout payment.
![](https://files.readme.io/ae95248-maya-checkout-button.png)
2. Create your Response pages
Every payment state should show an appropriate web page for the customer to know the status of their transaction. You need to host these pages on your website.
Created URLs will be used in the redirectUrl
object on the Create Checkout transaction request defining where the customer will be redirected when processing the transaction.
![](https://files.readme.io/e7bfa8d-status-pages.png)
Create a Maya Checkout transaction
Handle the ‘Check Out’ button event to proceed with the payment.
Step 1: Create Checkout
Handle the button event in your website to trigger the Create Checkout and redirect your customer to Maya's Checkout page.
When calling this endpoint, your system must define the redirectUrl
– the URL of your result pages where your customer will be redirected based on the payment status.
Step 2: Redirect the customer to Maya Checkout
Redirect your customer to Maya’s Checkout page using the redirectUrl
value from the Create Checkout endpoint response.
Maya's Checkout page is valid for one hour only. Once the request expires, the customer cannot proceed with the payment.
When this happens, your system must create a new checkout by sending a new request to the Create Checkout endpoint.
Monitor Real-time Transaction Events
Monitor and receive transaction updates.
Maya uses webhooks to inform your application about specific events related to payment requests. These notifications include the payment status and response codes.
Refer to the following resources to understand Webhooks and how to handle errors and declined payments:
If your application doesn't receive webhook notifications, use the following retrieve endpoints as an alternative:
Endpoints
The following are the relevant endpoints for Maya Checkout.
Name | HTTP Method | Key Type | Endpoint | Description |
---|---|---|---|---|
Create Checkout | POST | PUBLIC | /checkout/v1/checkouts | Creates a checkout transaction. This endpoint generates the checkoutId and redirectUrl . |
Managing Payment Transactions
Name | HTTP Method | Key Type | Endpoint | Description |
---|---|---|---|---|
Retrieve Payment via ID | GET | SECRET | /payments/v1/payments/{paymentId} | Retrieve the transaction information by providing the paymentId . The resulting response will be an array of the payment information.`. |
Retrieve Payment via RRN | GET | SECRET | /payments/v1/payment-rrns/{rrn} | Retrieve the transaction information by providing the merchant’s request reference number. Functionality is similar to Retrieve Payment via ID, but instead of the paymentID , rrn is used. |
Retrieve Payment Status | GET | PUBLIC | /payments/v1/payments/{paymentId}/status | By providing the paymentId , use this API to get the payment status. |
Cancel Payment via ID | POST | SECRET | /payments/v1/payments/{paymentId}/cancel | This API is used to cancel a payment transaction by providing the paymentId ; before it can be authenticated and card payment is made. |
Business Rules to Code
To supplement your knowledge of the integration, it is essential to familiarize the Business Rules to Code for Online Payments . This ensures that technology requirements and other development considerations are met.
At this point, you have understood the following:
- The necessary APIs and their endpoints
- The sequence and purpose of each API
- The prerequisites for building your integration