Accept One-time Payment using Maya Checkout

Overview

This guide walks you through integrating Maya Checkout via the REST API into your website or application.

By the end of this guide, you will:

• Understand the required pages and flows for a checkout journey
• Know how to create a checkout transaction and redirect customers securely
• Be able to monitor payment status using both webhooks and retrieval APIs

---

Before You Begin

Before you start integrating, learn About Maya Checkout and understand the key concepts for a successful integration.

Prerequisites

Confirm that the following are ready before you start:

• Completed Maya Checkout Onboarding:
  • For direct-to-production commitment, follow the Getting Started in Maya Checkout (Maya Business Manager)
  • For sales-assisted, follow the Getting Started in Maya Checkout (Maya Manager 1.0)
• Access to Maya Business Manager or Maya Manager 1.0
• API Keys: Public Key (pk-...) and Secret Key (sk-...)
• Correct environment setup (Sandbox or Production)
• A Webhook endpoint to listen for payment updates

---

Integrating with Maya Checkout

Step 1: Build Your Integration

1.1. Create Your Checkout Button

• Add a Checkout button where your customers will start the payment process.
• The button should trigger a call to the Create Checkout API.

1.2. Create Your Response Pages

• Prepare dedicated result pages to show transaction outcomes (e.g., success, failure, cancellation).
• Host these pages in your system.
• Use these page URLs in the redirectUrl object when creating a checkout.

This ensures customers are always redirected back to your platform with clear feedback on their payment status.

Step 2: Create a Maya Checkout Transaction

2.1 Prepare the Checkout request

When a customer clicks the Checkout button:

• Build your request following the Create Checkout API specifications
• Include the required fields
• Include redirectUrl(your response pages)

2.2 Call the Create Checkout API

• Send a POST request to /checkout/v1/checkouts
• Receive checkoutId (the paymentId) and redirectUrl from Maya

2.3 Redirect to Maya Checkout

• Use the redirectUrl from the response to send your customer to the Maya-hosted checkout page.
• Checkout sessions are valid for 1 hour. If expired, generate a new checkout request.

Step 3: Monitor Real-Time Transaction Events

3.1 Use Webhooks

Webhooks notify your system of events (e.g., payment success, failure, cancellation).

To get started with webhooks, see Configuring Your Webhook for Maya Checkout.

3.2 Fallback: Retrieve Transaction Status

If webhooks fail (e.g., network issues), use these APIs:

• GET /payments/v1/payments/{paymentId} → Retrieve by payment ID
• GET /payments/v1/payment-rrns/{rrn} → Retrieve by request reference number
• GET /payments/v1/payments/{paymentId}/status → Retrieve payment status

---

Endpoints

By now, you should understand the essentials of integrating Maya Checkout, including:

• Which endpoints to call during the payment flow
• When to use each endpoint
• Which API key (Public or Secret) is required

The table below summarizes the most relevant endpoints for a standard Maya Checkout integration.

---

API Sequence

1. Customer triggers paymey in your platform.
2. Your platform calls Create Checkout → receives checkoutId + redirectUrl.
3. Customer is redirected to the Maya Checkout page.
4. Customer selects a payment method and authorizes.
   • If canceled → Maya Checkout triggers redirectUrl.cancel.
5. Maya Checkout processes the payment with the financial entity.
6. Maya Checkout redirects customer:
   • Success → redirectUrl.success
   • Failure → redirectUrl.failure
7. Maya Checkout sends webhook with transaction result.
8. Your platform replies 200 OK (process payload after).
9. Your platform updates order status and notifies the customer.

---

FAQs

Q: My transaction in Sandbox keeps failing. How can I fix this?

Answer:

• Check that your code follows the required steps
• Review the Sandbox Health page to confirm service availability
• If the service is up, retrieve the error code and search the Maya Developer Hub for troubleshooting guides

Q: Why am I getting timeouts in Sandbox?

Answer:

• First, check the Sandbox Health page
• If the service is operational but issues persist, escalate via the Support Page

Q: How long are Checkout sessions valid?

A: Checkout sessions are valid for 1 hour. If expired, create a new checkout request with updated metadata and redirect URLs.

---

Next Steps

You have successfully implemented Maya Checkout for one-time payments. To build a more robust and production-ready integration, we recommend exploring the following:

1. Understand Payment Statuses
   • Learn how Maya Checkout payment statuses work and how they transition, so you can correctly track transactions end-to-end. See Understanding Payment Statuses in Maya Checkout
2. Set Up Webhooks
   • Configure webhooks to receive reliable, real-time payment updates. See Configuring Your Webhook for Maya Checkout.
3. Manage Voids and Refunds
   • Review the best practices in Managing Voids and Refunds in Maya Checkout to handle cancellations and refunds properly.
4. Handle Errors Effectively
   • Go through Understanding Errors in Maya Checkout to see error types, decline codes, and recommended handling strategies.
5. Test Your Integration
   • Follow the Testing and Validating Your Maya Checkout Integration guide to ensure your implementation behaves correctly in Sandbox before going live.