Overview
Use the Pay with Maya to generate and present QRPh for a more efficient payment experience.
Leverage Pay with Maya to implement either of the following:
- Use Maya’s QRPh Payment Page to reduce your expenses in developing and maintaining your web pages.
- Embed the Maya QRPh into your self-hosted webpage without the hassle of generating your own QRPh code, all while ensuring compliance with QRPh Code standards.
API Sequence
Learn the API sequence and transaction flow to Generate and present a Maya QRPh.
- The customer chooses to pay using Maya in the API Consumer’s application.
- The API Consumer calls Create Dynamic QR
endpoint of Pay with Maya API.
- Upon generating a QRPh, Maya initiates the creation of a 'payment' record with Maya reference ID to uniquely identify the generated QRPh.
- Pay with Maya API responds with a
paymentId,redirectUrlandqrCodeBodyto the API Consumer. - API Consumer saves the
paymentIdand proceed in presenting QRPh based on their preferred implementation:- If using the Maya-hosted page, the API Consumer directs the customer to the
redirectUrl. - If presenting the generated QRPh Code to the self-hosted pages, the API Consumer uses the
qrCodeBodyand incorporates it into their hosted pages.
- If using the Maya-hosted page, the API Consumer directs the customer to the
- When a user uses a Maya wallet or another wallet of the QRPh-participating financial institution, the issuer should read and process the QRPh code, send a request to BancNet, including the corresponding Maya reference ID and the issuer-generated reference number (invoice/receipt)
- BancNet, in turn, transmits the transaction details to Maya.
- Maya processes the transaction associated with the original Maya reference ID.
- If using the Maya-hosted page, Maya will direct the customer to the API Consumer's result pages.
- Subsequently, Maya notifies the API Consumer of the completed transaction using a webhook.
- API Consumer acknowledges the receipt of webhook by returning
200 OK. - API Consumer processes webhook.
- Maya communicates the transaction status to BancNet.
- BancNet then relays the response to the financial institution for reconciliation.
- The financial institution then notifies the customer that the payment request has been processed.
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 Dynamic QR 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 .
Create a dynamic QRPh
Handle the ‘Pay with Maya’ button event to trigger the generation of QRPh Code.
Handle the button event by calling the Create Dynamic QR endpoint. This endpoint will return a
paymentId, redirectUrl, and the qrCodeBody.
Maya Dynamic QRPh codes are designed for one-time use and remain valid for 1 hour from their creation time.
Once the QR code has been scanned or has expired, any subsequent payment attempts using the same QR code will be unsuccessful. This ensures the security and integrity of the payment process.
Present the generated QRPh
Present the generated QRPh according to your preferred implementation.
Redirect to Maya-hosted page
Get the redirectUrl from the response of Create Dynamic QR and use it to redirect the customer to Maya's page. This page will showcase the dynamic QRPh code generated.
Embed QRPh to your page
Use the qrCodeBody from the response of Create Dynamic QR to incorporate the generated Maya QRPh code into your self-hosted page. Additionally, the response still includes the redirect URL to Maya's page if you opt to use it.
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:
See also Guidelines for Monitoring QRPh Transactions .
Endpoints
The following are the endpoints needed for implementing Maya’s QRPh.
| Name | HTTP Method | Key Type | Endpoint | Description |
|---|---|---|---|---|
| Create Dynamic QR | POST | PUBLIC | /payments/v1/qr/payments | Creates a dynamic QR payment transaction. |
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
Pay with Maya’s QR Codes
QRPh payment codes generated by Maya comply with ISO 18004:2015 and follow the Philippine QR Code standards for P2M (Person-to-Merchant) issued by Philippine Payments Management, Inc (PPMI).
Some of the details and information required by PPMI that you can find in the QRPh payment codes are:
- Merchant ID: The unique identifier assigned to the merchant.
- Merchant Category Code (MCC): Classifies merchants and businesses based on the type of goods or services they provide.
- Transaction Currency Code: Identifies the currency used for the transaction.
- Transaction Amount: Specifies the monetary value of the transaction.
- Country Code: Denotes the country associated with the merchant's location or the transaction.
- Merchant Name: Indicates the name of the merchant conducting the transaction.
- Merchant City: Specifies the city where the merchant is located.
- Reference Label / Maya Reference ID: Provides a unique label or reference ID associated with the transaction, facilitating easy identification and tracking within the Maya system.