One-time Payment using Maya Wallet

Overview

Use the Pay with Maya to initiate a one-time payment using the customer’s Maya Wallet.

Leverage Pay with Maya to perform the following:

  • Accept Maya wallet payments via Maya login.
  • Enable scan-to-pay using the Maya QRPh.

Mobile customers are directed to the Maya login page, while Web customers are directed to a Maya page to log in or scan the QRPh code.


API Sequence

Learn the API sequence and transaction flow of One-Time Payment using Maya Wallet.



  1. The customer chooses to pay using Maya in the API Consumer’s application.
  2. The API Consumer calls the Create Single Payment endpoint of Pay with Maya API.
  3. Pay with Maya API responds with an paymentId and redirectUrl to the API Consumer.
  4. The API consumer saves the paymentId.
  5. The API Consumer uses the redirectUrl to redirect the customer to Pay with Maya’s page.
  6. The customer either logs in to their Maya account or scans the generated QRP using the Maya App to authorize the transaction.
  7. Upon initiating the payment:
    • If the payment was authorized:
      • Pay with Maya API will proceed in processing the payment.
      • If the payment succeeds, the customer will be redirected to the API Consumer’s success page.
      • If the payment fails, the customer will be redirected to the API Consumer’s failure page.
    • If the customer cancels and clicks Back to Merchant:
      • Pay with Maya will cancel the payment.
      • Pay with Maya will redirect the customer to the API Consumer’s cancel page.
  8. After processing payment, Pay with Maya will send a webhook notification to the API consumer’s webhook endpoint
  9. The API Consumer acknowledges the receipt of the webhook by responding with 200 OK.
  10. The API Consumer parses and processes the webhook payload received.
  11. The API Consumer notifies the customer.

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

Add a button to your application. Design and host your response web pages.


1. Add a 'Pay with Maya' button to your application

Create a Pay with Maya button on your application or website that will allow customers to trigger the payment.


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 Single Payment transaction request defining where the customer will be redirected when processing the transaction.


If the customer closes the browser, Maya cannot redirect them to your success or failure pages. To ensure a complete and seamless system experience, implement webhooks .

Initiate Payment

Handle the ‘Pay with Maya’ button event to trigger a single payment.


Step 1: Create Single Payment

Handle the button event in your website to trigger the Create Single Payment endpoint. This endpoint will return a paymentId and redirectUrl.

When calling this endpoint, your system must define the redirectUrl – URL of the page where your customer will be redirected based on the payment status.


Step 2: Redirect the Customer to the Maya-hosted page

User authorization is required before processing the payment request. To get the user authorization and to proceed with the payment, redirect the user to the Maya-hosted payment page using the redirectUrl received in Step 1.

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:

  1. How to create and configure your webhook
  2. Online payment errors

If your application doesn't receive webhook notifications, use the following retrieve endpoints as an alternative:


Endpoints

The following are the Pay with Maya endpoints for the One-time Payment using Maya Wallet.

NameHTTP MethodKey TypeEndpointDescription
Create Single PaymentPOSTPUBLIC/payby/v2/paymaya/paymentsCreates a single payment transaction using a Maya account.

Managing Payment Transactions

NameHTTP MethodKey TypeEndpointDescription
Retrieve Payment via IDGETSECRET/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 RRNGETSECRET/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 StatusGETPUBLIC/payments/v1/payments/{paymentId}/statusBy providing the paymentId, use this API to get the payment status.
Cancel Payment via IDPOSTSECRET/payments/v1/payments/{paymentId}/cancelThis 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

Frequently Asked