Know before you code

Money Movement

This solution provides you the capability to transfer funds from your provisioned Maya mother account to your recipients. Transfer can have four (4) states: CREATED, APPROVED, DECLINED and CANCELLED. You can start by creating intents to transfer then execute after your validation.


HTTP Headers

Authentication

Money Movement solution uses API keys to authenticate requests.

Your API keys carry many privileges. For a secure handover of API keys, they will be sent to your nominated recipient. These keys will be stored in a file that is encrypted using your public GPG keys. Be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

Use your API key in the Authorization header for every call to Money Movement’s endpoints. Set it as the username on the Basic authentication process with a blank password.

  1. Initial values
    base64(username:password)
  2. Replace the username with the API key and leaving the password blank
    base64(<API Key>:<blank>)
  3. Expected base64 encoding
    base64(sk-xxxx:)

Request Reference Number

You are required to send a Request-Reference-No in the HTTP header for each API request. This field will receive an alphanumeric string with a maximum of 50 characters.

ℹ️ We recommend to use a UUID generator when creating your Request-Reference-No.

Idempotency

Creating transfers always result in a new intent even when using the same request reference number. As long as a new transferId is returned, it’s treated as a new independent transaction. We suggest you randomly generate a new request reference number for each transfer intent.

⚠️ Money Movement does NOT check the existence of the request-reference-no being passed by the integrating system.

Each intent is assigned its own transferId. This ID is always unique and will serve to facilitate idempotency during execution. Each transfer can only be executed exactly once regardless of the provided request reference number. The same applies for cancellation.

Currently, Money Movement does not support retries of the same transaction and all errors are final (i.e. temporary errors are not distinguishable).

Rate Limiting

Maya enforces rate limiting in its endpoints. We encourage you to implement some sort of exponential back-off behavior in their invocations to Maya endpoints upon receiving an HTTP 429 response.

Daily Transaction Reconciliation

A report that is generated daily (every 4AM) and will be sent to your nominated MDTR recipient. This report captures all yesterday’s successful and failed transactions.

Header

Field Description Sample Data
Headline (row 1) Headlines of the report including the Client ID Partner Name MDTR Report
Generation Date
(row 2)
The date when report was generated. Date is in YYYYMMDD format 20220201

Transaction List (Body)

Column Name Description Sample Data
DateTime Date/Time the transaction was performed in PHT.
Format: YYYY-MM-DD HH:mm:ss
2022-01-31 09:48:46
Target PAN Target wallet account details. Value could be hash / masked if it is the PAN (Primary Account Number) 542482******5545
Target MSISDN Mobile number linked to the target wallet account. 639123456789
Target type Target account type. (default PAYMAYA) PAYMAYA
Partner RRN Transaction Reference number you have provided. fce48a15-7e54-4c36-b2af-eee19a6abd9c
MI3 RRN Transaction ID generated by Money Movement. 595213fb-f040-438e-ba55-4dc2bd183de4
Amount Transaction Amount in Philippine peso 100.00
Response Code Transaction response 0 (Please see list of Error Codes)

Transaction Summary (Footer)

Field Description Sample Data
Total Debit Amount Total amount debited to your wallet account 1900.00
Total No. of Successful Transactions Total count of successful transactions on the generated report 8
Total No. of Failed Transactions Total count of failed transactions on the generated report 3
Current balance as of generation date This is your account’s remaining balance by the time this report was generated. 55.00
Available balance as of generation date This is your account’s remaining balance by the time this report was generated. 55.00

ℹ️ Get your end-of-day (EOD) account balance given your specific date by reaching out to your Relationship Manager to request for extraction.

Error Codes

If processing a transaction has encountered an error, Money Movement will return the response body containing the error object. Error code represents the error encountered during transaction creation and processing. Please refer to the list of error codes below.

Gateway Errors
HTTP Status Description What to do?
502 Gateway error In cases that you have acquired and processing the transferId (like executing a transfer), it is recommended to validate the status of the transfer by calling the Retrieve a Transfer endpoint with the transferId.

Otherwise, you may retry the request.

ℹ️ When the error still persist after a number of retries, kindly raise it to [email protected].

503 Gateway error In cases that you have acquired and processing the transferId (like executing a transfer), it is recommended to validate the status of the transfer by calling the Retrieve a Transfer endpoint with the transferId.

Otherwise, you may retry the request.

ℹ️ When the error still persist after a number of retries, kindly raise it to [email protected].

504 Gateway error In cases that you have acquired and processing the transferId (like executing a transfer), it is recommended to validate the status of the transfer by calling the Retrieve a Transfer endpoint with the transferId.

Otherwise, you may retry the request.

ℹ️ When the error still persist after a number of retries, kindly raise it to [email protected].

No Code Any timeout error In cases that you have acquired and processing the transferId (like executing a transfer), it is recommended to validate the status of the transfer by calling the Retrieve a Transfer endpoint with the transferId.

Otherwise, you may retry the request.

ℹ️ When the error still persist after a number of retries, kindly raise it to [email protected].

General Errors
Code HTTP Status Description What to do?
7011 400 Temporary failure encountered In cases that you have acquired and processing the transferId (like executing a transfer), it is recommended to validate the status of the transfer by calling the Retrieve a Transfer endpoint with the transferId.

Otherwise, you may retry the request.

ℹ️ When the error still persist after a number of retries, kindly raise it to [email protected]ph.

7012 400 The transaction is still processing or connection failure is encountered. The client is advised to retrieve the transfer to verify the actual status. In cases that you have acquired and processing the transferId (like executing a transfer), it is recommended to validate the status of the transfer by calling the Retrieve a Transfer endpoint with the transferId.

Otherwise, you may retry the request.

ℹ️ When the error still persist after a number of retries, kindly raise it to [email protected].

During Create Transfer
Code HTTP Status Description What to do?
1096 400 Transfer to the same account is not allowed. Usually applicable to funded partners if they try to add money to their Maya Corporate Account. Align your use case and note that Money Movement prohibits using the same Maya account as the source and the receiver.
1301 400 Invalid Client-Id header. Validate if you’re providing the correct Client ID values.

ℹ️ When the error still persist after providing the correct values, kindly raise it to the following:

1630 400 Invalid Product Type. Recipient type must always be PAYMAYA. Validate if you’re providing correct values on the transfer request’s Recipient Type, it should be either of the following:
  • TOKEN for Transfer Funds to Maya Wallet or Maya Mini Apps
  • CODE for Add Money via Cash In Code

ℹ️ When the error still persist after providing the correct values, kindly raise it to the following:

2841 400 Recipient value is invalid. Validate if you’re providing the correct values for the Recipient Value of the transfer request. Revisit the following references for the correct values:

ℹ️ When the error still persist after providing the correct values, kindly raise it to the following:

1646 400 The recipient type is not allowed to receive money from this partner. Must be PAYMAYA.
2856 400 The recipient is not a recognized PayMaya account. Validate if you’re providing the correct values for the Recipient Value of the transfer request. Revisit the following references for the correct values:

ℹ️ When the error still persist after providing the correct values, kindly raise it to the following:

M001 400 No mother account defined for the partner. Usually appears if there are errors in onboarding a funded partner.

ℹ️ When the error still persist after providing the correct values, kindly raise it to the following:

M003 400 Invalid Mother Account Product Type. Usually appears if there are errors in onboarding a funded partner.

ℹ️ When the error still persist after providing the correct values, kindly raise it to the following:

M122 400 Recipient is inactive and cannot receive funds. You will encounter this error when recipient’s account was not active - either closed per request of the user or not yet active. You may ask the user to coordinate with Maya Customer Care to check their account.

ℹ️ Discuss with your Maya Relationship Manager to know more on handling and spiels.

M036 400 Add Money code is invalid. The recipient value isn’t found in the Add Money code records. This usually happens when user provides an incorrect Add Money code or a code that is not generated from the Maya app.

Make sure that the user generates the Add Money Code from their Maya App and provided it to your system.
M055 400 Amount does not match Happens when the amount inputted by the customer is different from the amount currency and value provided by your system.

Make sure that customer provided the correct details to proceed with the funding.
M056 400 Amount value does not match Happens when the amount inputted by the customer is different from the amount value provided by your system.

Make sure that customer provided the correct details to proceed with the funding.
M057 400 Amount currency does not match Happens when the amount inputted by the customer is different from the amount currency provided by your system.

Make sure that customer provided the correct details to proceed with the funding.
M132 422 Recipient funding is closed and cannot receive funds. You will encounter this error when recipient’s account was closed - either closed per request of the user or got blocked due to suspicious activity. You may ask the user to coordinate with Maya Customer Care to check their account.

ℹ️ Discuss with your Maya Relationship Manager to know more on handling and spiels.

M133 422 The recipient profile is not allowed to receive money from this partner. Consult with onboarding team what profiles are allowed You will encounter this error when recipient’s account is not yet upgraded (KYC1). You may ask the user to upgrade their account prior to do funding.

ℹ️ Discuss with your Maya Relationship Manager to know more on handling and spiels.

During Execute Transfer

⚠️ Most errors during execution are due to customer account problems (except for 6051 which would apply to your wallet account). These errors usually start with 60xx. You may safely prompt consumers about these errors.

Code HTTP Status Description What to do?
6014 400 Invalid account Details. You may ask the user to coordinate with Maya Customer Care to check their account.
6041 400 Recipient’s primary account marked as Lost You will encounter this error when recipient’s account was not active - either closed per request of the user or not yet active. You may ask the user to coordinate with Maya Customer Care to check their account.
6043 400 Recipient’s primary account marked as Card Stolen You will encounter this error when recipient’s account was not active - either closed per request of the user or not yet active. You may ask the user to coordinate with Maya Customer Care to check their account.
6051 400 Your funds are not enough to give to the customer. You need to replenish the balance of your Maya Corporate Account. You may contact your Maya Relationship Manager for further assistance.
6054 400 Recipient’s primary account has expired. You may ask the user to coordinate with Maya Customer Care to check their account.
6058 400 Recipient’s profile is not permitted to transact with this partner in our ledgers. You may ask the user to coordinate with Maya Customer Care to check their account.
6061 400 Recipient has reached their Add Money limit (amount). You may inform the user that they have already reached the wallet limit.
6065 400 Recipient has reached their Add Money limit (count). You may inform the user that they have already reached the wallet limit.
6072 400 Partner’s account has reached its limit. You reached your account limit. You may contact your Maya Relationship Manager for further assistance.
6076 400 Recipient’s primary account is Invalid. You may ask the user to coordinate with Maya Customer Care to check their account.
6091 504 Internal ledger error. In cases that you have acquired and processing the transferId (like executing a transfer), it is recommended to validate the status of the transfer by calling the Retrieve a Transfer endpoint with the transferId.

Otherwise, you may retry the request.

ℹ️ When the error still persist after a number of retries, kindly raise it to [email protected].

6096 400 Internal ledger error. In cases that you have acquired and processing the transferId (like executing a transfer), it is recommended to validate the status of the transfer by calling the Retrieve a Transfer endpoint with the transferId.

Otherwise, you may retry the request.

ℹ️ When the error still persist after a number of retries, kindly raise it to [email protected].

6097 400 Internal ledger error. In cases that you have acquired and processing the transferId (like executing a transfer), it is recommended to validate the status of the transfer by calling the Retrieve a Transfer endpoint with the transferId.

Otherwise, you may retry the request.

ℹ️ When the error still persist after a number of retries, kindly raise it to [email protected].

6098 504 Internal ledger timeout. In cases that you have acquired and processing the transferId (like executing a transfer), it is recommended to validate the status of the transfer by calling the Retrieve a Transfer endpoint with the transferId.

Otherwise, you may retry the request.

ℹ️ When the error still persist after a number of retries, kindly raise it to [email protected].

6005 400 Internal ledger error. In cases that you have acquired and processing the transferId (like executing a transfer), it is recommended to validate the status of the transfer by calling the Retrieve a Transfer endpoint with the transferId.

Otherwise, you may retry the request.

ℹ️ When the error still persist after a number of retries, kindly raise it to [email protected].

2896 504 Internal service timeout. In cases that you have acquired and processing the transferId (like executing a transfer), it is recommended to validate the status of the transfer by calling the Retrieve a Transfer endpoint with the transferId.

Otherwise, you may retry the request.

ℹ️ When the error still persist after a number of retries, kindly raise it to [email protected].


Explore what Maya’s Money Movement Solution can offer!

Want a secure fund transfer from your system to the consumer’s Maya wallet?

Fund a Maya Wallet is the solution you are looking for!

Learn more →

Interested in becoming one of our growing Add Money or Cash In centers?

Add money using Cash In Code is the right solution for you!

Learn more →