Overview
Use the Pay with Maya to allow customers to link their Maya account directly to your application and use it for future payments.
Leverage Pay with Maya to perform:
- One-time user authentication during linking to verify the eligibility of your customer’s Maya account. There are no test charges during account linking.
API Sequence
Learn the API sequence and transaction flow to Link a Maya Wallet.
- The customer initiates Maya Wallet linking in the API Consumer’s application.
- API consumer triggers Create Wallet Link
endpoint.
- Pay with Maya API responds with a
linkIdto identify the wallet link and theredirectUrlfor user authorization. - API consumer saves the linkId.
- API consumer redirects the customer to the Maya’s
redirectUrl. - The customer authorizes the wallet linking by logging in to their Maya account on the Maya login page.
- Pay with Maya API processes the authorized wallet linking request.
- Pay with Maya API will redirect the customer to the API Consumer’s result pages. The
redirectUrlwas provided by the API Consumer upon calling the Create Wallet Linkendpoint.
- After redirecting to API Consumer’s result pages, API Consumer calls Get Wallet Link
endpoint to retrieve the status of the wallet link.
- API Consumer then saves the Maya wallet link status.
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 'Link a Maya Account' button to your application
Create a 'Link a Maya Account' button on your 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 Wallet Link 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 Maya Wallet Link
Handle the 'Link a Maya Account' button event to trigger the linking of Maya wallet.
Step 1: Create Wallet Link
Handle the button event by calling the Create Wallet Link endpoint. This endpoint will return a
linkId and redirectUrl.
Save the generated linkId
- A Maya Account Link is identified through link ID (id) - a unique string in UUID format.
- The account link is bound to your API keys. With this, you could only utilize link ID by using the corresponding API keys.
- You can use this ID to:
- Track and manage a Maya Account Link
- Execute the current and future payments on behalf of the user.
Step 2: Redirect customer to Maya Login Page
Obtain the redirectUrl from the response of the Create Wallet Link endpoint and use it to redirect your customer to the Maya page, where they need to log in to their Maya account and authorize the wallet linking.
Note that the redirectUrl is only valid for 15 minutes. Any attempt after the said duration will result in an error.
Get Maya Wallet Link
Manage the Maya Wallet linking status.
Once Maya redirects the user to your result pages, call the Get Wallet Link endpoint providing the
linkId to validate the linking status and update the linking state in your system accordingly.
Managing Maya Wallet Link
Pay with Maya provides dedicated endpoints to assist in managing the wallet link, allowing you to retrieve the wallet link or unlink the wallet.
What's Next?
Once Maya Wallet is successfully linked, you can use it for future payments. For guidance, check out our guide on Pay using a Linked Maya Wallet .
Endpoints
The following are the endpoints needed for implementing Link a Maya Wallet.
| Name | HTTP Method | Key Type | Endpoint | Description |
|---|---|---|---|---|
| Create Wallet Link | POST | PUBLIC | /payby/v2/paymaya/link | Creates a wallet link that allows charging to a Maya account. |
Managing Maya Wallet Link
| Name | HTTP Method | Key Type | Endpoint | Description |
|---|---|---|---|---|
| Get Wallet Link | GET | SECRET | /payby/v2/paymaya/link/{linkId} | Retrives details of a linked Maya wallet account. |
| Delete Wallet Link | DELETE | SECRET | /payby/v2/paymaya/link/{linkId} | Used to deactivate a Maya wallet link. |
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
Does Maya Wallet Link expires?
Answer: Self-expiration of Maya Wallet Link is not yet supported but may be implemented in the future.
When a Maya Wallet Link is created, it will be usable unless it gets canceled or deactivated by the merchant. Deactivating the Maya Wallet Link can be done by your application by using the Delete Wallet Link endpoint.