Know before you code

Remittance Service

This solution provides you the capability to allow your customers / users to send remittances directly to Maya Wallet accounts.

Transfer can have five (5) states: CREATED, PROCESSING, APPROVED, DECLINED and EXPIRED. You can start by creating intents to transfer then execute after your validation.

HTTP Headers


Remittance Service 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 Renittance Service’s endpoints. Set it as the username on the Basic authentication process with a blank password.

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

Request Reference Number

You are required to send a Request-Reference-Number 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-Number.


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

⚠️ Remittance Service does NOT check the existence of the Request-Reference-Number being passed by the integrating system.

Each intent is assigned its own transactionReferenceNumber. 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.

Currently, Remittance Service 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.

Statement of Accounts

This report is generated daily (every 12:30AM) and will be sent immediately after to the email address of your nominated SOA recipient.

SOA Report Email Notification

SOA Report Email Notification

It captures all of yesterday’s successful and failed transactions-- every single transaction that affects the account balance. It also displays the starting and ending balance for each report. Due to the sensitivity of information shown in this report, it is password-protected.

SOA Report filename format:


SOA Report header specifications:

Field Name Description Sample Data
Daily Transaction Report for Client Name merchant name
Generation Date The date when report was generated. Date is in YYYY-MM-DD format 2023-05-19
Account Number Account Number or Hashed PAN of client 12345678


Account Type Specifies if the Account is a Funded account (Debit) or a Receivable account (Credit) Debit

Starting Balance Two (2) columns that show the:
  • (1) Timestamp of the first transaction of the day (PHT)
    • Format:MM/dd/yyyy hh:mm:ss.SSS a
  • (2) Account balance before the first transaction of the day in Philippine peso (PHP)
05/19/2023 09:44:49.279 AM

Ending Balance Two (2) columns that show the:
  • (1) Timestamp of the last transaction of the day (PHT)
    • Format:MM/dd/yyyy hh:mm:ss.SSS a
  • (2) Account balance after the last transaction of the day in Philippine peso (PHP)
05/19/2023 11:22:01.739 AM


SOA Report transaction list (body) specifications:

Column Name Description Possible Values / Sample Data
DateTime Date/Time the transaction was performed in PHT
Format: MM/dd/yyyy hh:mm:ss.SSS a
05/19/2023 10:01:33.083 AM
PAYMAYA RRN Transaction ID generated by Maya cac30d99-86c1-4dfd-afd6-0ef57faa63e8
Amount Transaction Amount in Philippine peso (PHP) 10000.00
Type Identifies if the transaction amount is a debit (Dr) or credit (Cr) to the account Dr

Transaction Type Human-readable description of the transaction, mapped from Money Movement entry code Receive from PESONet
Balance Wallet balance amount after each transaction in Philippine peso (PHP) 10750710.43

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