Remittance to Maya Wallet Technical Guide
The Maya Remittance Service is a robust API-based platform designed to empower remittance service providers, to enable direct money transfers to the beneficiary’s Maya wallet.
With tens of millions of monthly active users in the Philippines, and being the preferred all-in-one money app for Filipinos, you can significantly expand your reach. Maya’s Remittance service provides access to this extensive user base, enabling your customers/users to send remittances directly to Maya accounts. Clients that would benefit from this solution include international remittance partners based overseas, whose customers abroad seek to send money to their loved ones in the Philippines.
Maya’s Remittance Service Experience
Remittance Experience
How it Works
Remittance to Maya Wallet - Sender View
Remittance to Maya Wallet - Beneficiary View
Remittance States
When you initiate a remittance transfer, a corresponding transaction record is generated. This record undergoes various state transitions based on the processing steps, validity, and outcomes. Please refer to the diagram below for a visual guide on the state transitions of a remittance transfer.
Remittance States
| State | Description |
|---|---|
CREATED | The initial state of the remittance transfer intent upon successful creation. |
PROCESSING | This state means that Maya has initiated the processing of the remittance transfer upon calling the execute remittance transfer endpoint. It indicates that the process is currently underway and has not yet been completed. |
APPROVED | A state when the remittance transfer passed all the validations and was processed successfully. |
DECLINED | A remittance transaction will transition to this state when it does not pass the validation checks and/or encounters processing errors. For the list of error codes, please refer to: Remittance Errors  . |
EXPIRED | A status for a remittance transaction that is not executed within one (1) hour after its creation. |
Getting Started
To seamlessly integrate Maya’s Remittance Service into your systems or platforms, it is essential to familiarize yourself with the necessary requirements and understand the onboarding process. For a step-by-step guide to quickstart your integration, please refer to the Remittance Quick Start Guide .
Send Remittances Direct to Maya Wallet
After completing the onboarding process, you should now be able to implement Maya’s Remittance Direct to Maya wallet. To guide you on implementing the solution effectively, please follow the steps below:
Step 1: Acquire the required information to make a remittance transaction
Click here to view full details
In compliance with Maya’s business rules, information about the sender and beneficiary is required to initiate a remittance transfer.
Keep in mind
Refer here
You need to procure the following information from the sender:
- Sender KYC information
- sender details
- country of origin
- Beneficiary Account information
- beneficiary details
- account number / MSISDN of beneficiary
- Remittance Transaction information
- transfer amount and currency
Acquire required information
Step 2: Create a Remittance Transfer
Click here to view full details
After acquiring and preparing the information needed for remittance, call this endpoint to create a transfer intent:
Create Remittance
What happens during the create remittance transfer:
- After acquiring the required transaction details, your system must furnish the create remittance payload and send it to the create remittance endpoint POST
/remittances/v2. - Maya processes the payload which then creates an intent record with initial status
CREATED. - Maya then returns the status of the request and the generated
transactionReferenceNumber(remittance ID) in the response.
After this step, you should be able to acquire a
transactionReferenceNumberthat is crucial when executing and monitoring.
A Created Remittance transaction is only valid for one (1) hour, you must execute it within one (1) hour or the transaction will be expired.
Step 3: Execute Remittance Transfer
Click here to view full details
After creating an intent, initiate the processing of transfer by calling this endpoint:
Utilize the transactionReferenceNumber (remittance ID) acquired during Step 2 as the API endpoint parameter.
Execute Remittance
What happens during the execute remittance transfer:
- After creating the transfer intent and having obtained the
transactionReferenceNumber, call the PUT/remittances/v2/{transactionReferenceNumber}/executeendpoint to process the remittance. - Maya will then proceed with the processing of the transfer intent identified by the provided
transactionReferenceNumber. During this step, transaction status will transition fromCREATEDtoPROCESSING.
Upon processing the remittance transfer, Maya will debit the remittance amount from your Mother account and credit the amount to the target Maya wallet of the beneficiary.
- After processing the remittance, Maya will respond to your platform with the status of the transfer record depending on the result of processing (
APPROVEDorDECLINED).
Keep in mind
If your platform has a configured callback URL, Maya will not wait to complete the execute transfer process and will respond to your platform with the transfer status
PROCESSING.
Upon completing the transfer processing, Maya will update your platform with the final status (APPROVEDorDECLINED) through the webhook notification.
- After getting the response from Maya, notify the user accordingly.
Step 4: Monitor Remittance Transactions
Click here to view full details
There are two (2) ways to monitor remittance transactions: by utilizing Webhooks or via Check Remittance endpoint:
- Webhooks (recommended)
- Check Remittance
Utilizing Webhooks
If your system incorporated a valid webhook endpoint in the callbackUrl field during Create Remittance, Maya will automatically send webhook events to the specified endpoint. The event will be the result of the remittance transfer processing, and will be either APPROVED or DECLINED.
Please note that your webhook endpoint must be registered and whitelisted in Maya to utilize this feature effectively.
Monitor remittance using webhooks
Sample Webhook Notification:
{
"transactionReferenceNumber":"bc43b7c9-b721-4d27-ace3-a925f013fc72",
"requestReferenceNumber":"123456789012",
"responseCode":"0000",
"description":"successful",
"status":"APPROVED"
}
Check Remittance
Check status of remittance by calling this endpoint:
Utilize the transactionReferenceNumber (remittance ID) acquired during Step 2 as the API endpoint parameter.
Check Remittance
Refund, Void and Settlement
Should you have refund, void, and settlement issues or inquiries in Production, you may contact [email protected].
Errors and Handling
Acquire a better understanding of errors and their resolution methods to ensure appropriate management of errors.
Maya adopts a RESTful architecture and relies on HTTP response and error codes to notify clients about the outcome of their requests, whether successful or not.
When an error occurs, the following is the response format:
{
"result": "FAIL",
"error": {
"code": "ANC001",
"message": "Missing/invalid parameters.",
}
}
See this page for the list of error codes and messages for remittance transactions.
Additional References
Need support? If you have any questions or feedback, feel free to reach out to us via our Support
Updated about 1 year ago