Know before you code

⚠️ Card Scheme Mandates

Card Schemes (MasterCard and VISA) roll out changes on the rules and requirements to merchants, acquirers and issuing banks in a uarterly duration or semi annual.

You will receive an email advisory in cases when you will be impacted by these changes. You may also refer to changelog for latest news or announcements.

Communication Timeout Setting

The following communication timeout settings are recommended:

Case Recommended Timeout Remarks
Connection Timeout 10 seconds

Time to wait before you can establish TCP connection with Maya’s Payments Processing Platform

Wait for Response (Read Timeout) 60 seconds

Time to wait before you gives up on the request going to Maya’s Payments Processing Platform

🧩 Tips

In the case of a Read Timeout, you may either:

  • Call Void Transaction if the transaction is voidable, or
  • Call Check Transaction to know if the transaction proceeded. You may proceed accordingly depending on the response of check transaction.

Idempotency and Retransmissions

Maya’s Payments Processing Platform POST APIs support optional idempotency for retransmissions.

🧠 Keep in mind

Any request with the header X-Idempotency-Key will be checked if it is a first transmission or a retransmission (i.e. there exists a similar request with the same X-Idempotency-Key).

When matching retransmissions against first transmissions, the following details must match:

  • requesting party
  • header Request-Reference-No
  • request method
  • request URL
  • header X-Idempotency-Key

ℹ️ Note that other parts of the request are not inspected. Only the specified details are used for idempotency matching. When the aforementioned details match, the request is considered a retransmission regardless of other details (like request body and etc.).

First Transmission Processing proceeds as NORMAL

Response of the corresponding first transmission is returned.

Retransmission responses are marked with the header X-Response-Retransmission set to true.

In the case that a retransmission is sent while a first transmission is still ongoing, a pending response is returned with the HTTP status 202.

    "status": "ONGOING",
    "message": "Transaction had been received and is still ongoing"

Details of first transmissions are kept strictly for 6 hours only for candidate retransmission matching. This feature is intended to be used within short intervals only (generally for retries and retries with backoffs) and thus we recommend to use this only for retransmission intervals guaranteed shorter than 6 hours.

Transaction Retention

Transaction retains only up to a period of 90 days in its Sandbox environment and 390 days in its Production environment.

Including Metadata

The Authorizations and Payments API supports adding metadata in the headers of the request message.

Geo-Tagging Requests

To geo-tag a request, add a Latitude header and a Longitude header in decimal degrees (DD) format. For example, a request sent from the United States Capitol would include the following headers:

Latitude: 38.8897
Longitude: -77.0089