Cash In via MI3 API

Authentication

During the onboarding process, partners will be given their API keys using files encrypted through GPG. These files will be sent to the nominated API key recipient from the partner’s organization. Within the file is the API key starting with sk- (e.g. sk-xxxx). This key should be sent alongside each request to the Maya endpoint through the Authorization header.

🚧

Don't know how to decrypt the files using GPG?

You may check the GPG Guide page for reference.

Basic authentication is used during the process where the username is the API key with a blank password.

For example, using the example API key, the authorization header will be as follows:

base64(username:password) // Initial values
base64(<API Key>:<blank>) // Replace the username with the API key and leaving the password blank

base64(sk-xxxx:) // Expected base64 encoding

Notice that the password section is blank and the key is effectively encoded appending a : to the end. The authorization header for the sample key should look like this

Authorization: Basic c2steHh4eDo=

Rate Limiting

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

HTTP Headers

Consumers are required to send a Request-Reference-No in the HTTP header for each request execution. The said field will receive an alphanumeric string with a maximum of 50 characters. We recommend to use a UUID generator when creating your RRN.

--header 'Request-Reference-No: 7220558d-ca06-4c97-a039-69cb3a0ee6c4'

Transfer Flow

Transfer transactions can have 4 states: CREATED, APPROVED, DECLINED and CANCELLED. These states can be manipulated using the Cash In via MI3 API and will strictly follow the transition indicated on the diagram below.

Transfer state diagramTransfer state diagram

Transfer state diagram

API Endpoints

🚧

If you receive a field in the response that is not in this spec, that field will be deprecated soon.

Creating a Transfer

POST /transfers

This creates an intent to transfer. No movement of funds happen during this request. This transaction allows partners to pre-validate the transfer and the recipient information and to calculate any fees that may additionally be incurred to the customer. The resulting increase in the recipient’s funds will be the net amount after deducting fees. The relation of the fees and the transaction amount is further detailed in Maya FAQ: How is the convenience fee computed by different Maya Cash In partner channels?.

As a quick example, a Transfer of PHP 101 will charge PHP 1 and the resulting amount to be given to the recipient is PHP 100.

Transaction state becomes CREATED.

Request Body

Content-Type: application/json

Field

Type

Description

recipient

Account

Required. Account details of customer to receive funds.

recipient.type

String

Required. The type of account of the recipient. Either “DIRECT”, “CODE”, or “TOKEN”.

recipient.value

String

The account number of the recipient.

For recipient type “DIRECT”, this is the mobile number or account number of the recipient customer.

For recipient type “CODE”, this is the generated cash in code by the recipient customer.

For recipient type “TOKEN”, this is the access token given by Maya Connect (JWT format) OAuth representing the recipient customer. Similarly, this can also be the Open Platform JWE token. Required

amount

Amount

Required. Value and currency of funds to add.

amount.currency

String

Required. The currency of the amount to add. Normally “PHP”.

amount.value

String

Required. The exact amount to add to the recipient.

note

String

Optional message for the transaction (max 127 characters)

Response

Field

Type

Description

transferId

UUID String

The unique identifier of the intent to transfer. The transferId field in a successful response and the transaction_reference_no in the error response refer to the same internal value.

createTime

ISO8601 String

The timestamp when the intent to transfer was created in ISO8601 format.

updateTime

ISO8601 String

The timestamp when the intent to transfer was updated in ISO8601 format. Usually equal to createTime.

state

String

The current state of the intent to transfer. Successful creation of intent to transfer always yields CREATED.

recipient

Account

The recipient of the intent to transfer. Echoed from the request. The recipient type will be changed to PAYMAYA if the validation succeeded.

amount

Amount

The exact amount to add to the recipient. Echoed from the request.

note

String

Optional message for the transaction. Echoed from the request.

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. Partners are advised to 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, Maya Cash In does not support retries of the same transaction and all errors are final (i.e. temporary errors are not distinguishable).

❗️

Caution on idempotency

This behavior may change soon. The request reference number may be used to identify if a transaction is a duplicate during creation.

Executing a Transfer

PUT /transfers/{transferId}/execute

This executes an intent to transfer previously created. That is, execution of a particular created transfer can only be done once and any subsequent execution will return an error (NOT FOUND). It only requires the transferId generated during transfer creation

Transaction state becomes APPROVED or DECLINED.

Response

Field

Type

Description

transferId

UUID String

The unique identifier of the intent to transfer

createTime

ISO8601 String

The timestamp when the intent to transfer was created in ISO8601 format.

updateTime

ISO8601 String

The timestamp when the intent to transfer was updated in ISO8601 format. During execution, this will be timestamp when the execute was done.

state

String

The current state of the intent to transfer. Successful execution of transfers always yield APPROVED and failed transactions will show DECLINED.

sender

Account

The internal account representing the partner that acted as the sender for the transfer. (May be deprecated soon)

recipient

Account

The recipient of the intent to transfer. This will be the recipient account number represented by the Cash In Code.

amount

Amount

The exact amount to add. Same value as what was provided while creating the intent to transfer.

note

String

Optional message for the transaction. Same value as what was provided while creating the intent to transfer.

📘

There is currently no time limit for executing a transfer after creation. However, such a limit may be imposed soon.

Retrieving a Transfer

GET /transfers/{transferId}

This retrieves the transaction and displays its status. Once a transaction has been Created or Executed, partners can retrieve it using the provided transferId. This will allow partners to verify its status especially during execution if the response is ambiguous. A potential use-case for this is if the transaction times out or the socket is closed and the partner is not sure if the funds were successfully given to the customer.

It only requires the transferId generated during transfer creation

Response

Field

Type

Description

transferId

UUID String

The unique identifier of the intent to transfer

createTime

ISO8601 String

The timestamp when the intent to transfer was created in ISO8601 format.

updateTime

ISO8601 String

The timestamp when the intent to transfer was updated in ISO8601 format. During execution, this will be timestamp when the execute was done.

state

String

The current state of the intent to transfer. Can be CREATED, APPROVED, DECLINED, or CANCELLED.

sender

Account

The internal account representing the partner that acted as the sender for the transfer. (May be deprecated soon)

recipient

Account

The recipient of the intent to transfer. Same value as what was provided while creating the intent to transfer.

amount

Amount

The exact amount to add. Same value as what was provided while creating the intent to transfer.

note

String

Optional message for the transaction. Same value as what was provided while creating the intent to transfer

Cancelling a Transfer

DELETE /transfers/{transferId}

This cancels an approved transfer and takes back the funds that were credited to the recipient. Use with extreme caution and in accordance with contractual agreements.

It only requires the transferId generated during transfer creation

🚧

Cancelling a newly created transfer

Only transfers with APPROVED state can be cancelled.

Response

The endpoint will return HTTP 204 No content if the transferId is valid.

❗️

Reversal

Reversing after a certain period may result to negative balances due to the customer having already spent the credited funds. Currently, no time limit is set for cancelling but one may be imposed soon.

Balance Inquiry

This endpoint will help the partner determine the current and available balance of their wallet

GET /balance

Response

Field

Type

Description

metadata

Object

Meta-information about the inquiry.

balance

Balance

Object. The balance object containing available and current balance information as described below.

balance.available_balance

Amount

The remaining usable balance of the partner.

balance.current_balance

Amount

The remaining balance including any authorized amounts that are waiting to be posted.


Did this page help you?