General Knowledge in using MI3

Fund Transfers

MI3 is a service that 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

The MI3 APIs 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 mi3 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.

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, mi3 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.

MI3 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 Mi3. 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

Error Codes

General Errors

CodeDescription
7011Temporary failure encountered
7012The transaction is still processing or connection failure is encountered. The client is advised to retrieve the transfer to verify the actual status.

During Create Transfer

Show errors during create transfers
CodeDescription
1096Transfer to the same account is not allowed. Usually applicable to funded partners if they try to add money to themselves.
1301Invalid Client-Id header.
1630Invalid Product Type. Recipient type must always be PAYMAYA.
2841Recipient value is invalid.
1646The recipient type is not allowed to receive money from this partner. Must be PAYMAYA.
2856The recipient is not a recognized PayMaya account.
M001No mother account defined for the partner. Usually appears if there are errors in onboarding a funded partner.
M003Invalid Mother Account Product Type. Usually appears if there are errors in onboarding a funded partner.
M122Recipient is inactive and cannot receive funds.
M036Add Money code is invalid. The recipient value isn’t found in the Add Money code records.
M055Amount does not match
M056Amount value does not match
M057Amount currency does not match
M132Recipient funding is closed and cannot receive funds.
M133The recipient profile is not allowed to receive money from this partner. Consult with onboarding team what profiles are allowed.

During Execute Transfer

Show errors during execute transfers

⚠️ 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.

CodeDescription
6014Invalid account Details
6041Recipient’s primary account marked as Lost.
6043Recipient’s primary account marked as Card Stolen.
6051Your funds are not enough to give to the customer.
6054Recipient’s primary account has expired.
6058Recipient’s profile is not permitted to transact with this partner in our ledgers.
6061Recipient has reached their Add Money limit (amount).
6065Recipient has reached their Add Money limit (count).
6072Partner’s account has reached its limit.
6076Recipient’s primary account is Invalid.
6091Internal ledger error.
6096Internal ledger error.
6076Internal ledger error.
6098Internal ledger timeout.
6005Internal ledger error.
2896Internal service timeout.

Explore what MI3 can offer!

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

Transfer funds to 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 ->

Did this page help you?