Technical Details

Managing sessions

Managing sessions are important to establish secure access and leverage Disbursement API functionalities.

Initiate session

Create a session with Maya’s Disbursement API using your registered email and password. This session is valid for 10 minutes and will be automatically extended by another 10 minutes for each successful API call.

  1. Client sends a POST request via the /session endpoint providing email, password and the x-api-key.

    ℹ️ API keys and registration of email will be done during onboarding. See Quick Start Guide for more details.

  2. Disbursement API will authenticate Client by the credentials provided and returns the status of the request.
You may checkout the complete API specs in our API Reference page.
Optional: Terminate session

An optional operation. A session automatically times out 10 minutes after the last successful API call.

  1. For manual termination of session, Client sends a DEL request via the /sessions API endpoint.
  2. Upon receiving this request, Disbursement API will terminate the session.
You may checkout the complete API specs in our API Reference page.

Inviting Members

In this stage, Disbursement API facilitates the following procedures to make members become an eligible recipient of your disbursement process:

  • Creation of Maya Consumer account for an employee/student/etc in order to receive Maya credits. If member already has a Maya account, Disbursement API will use it. Member should still accept the invitation to receive funds from the client.
  • Enrolling their Maya accounts to become a member or beneficiary of the client. To comply with the Maya Business Rules, members will receive an invite via SMS and must confirm by replying to that SMS.

ℹ️ Invite will automatically expire after seven (7) days.

Invited members should receive two (2) SMS to confirm the creation of their Maya account.


To successfully create an UPGRADED Maya account, the recipient should reply YES to 29290290 or opt-in via the web link online.

How to invite members

Step 1: Create the input Member File

Refer here for the specifications of the input member file.
You may also download the sample file for reference: sample-members-file.csv

Step 2: Initiate Session

ℹ️ Conditional: This is if NO existing session or previous session has already expired.

See Managing Sessions on how to initiate session with Maya’s Disbursement API.

Step 3: Submit Member File

Submit a CSV file containing details of the members to register and tag their accounts as beneficiaries. Members will receive an invite and must confirm by replying to the SMS.

  1. Client submits the member file in CSV format via the POST /members request. Request should have the x-api-key.
  2. Disbursement API will process the file and sends invite to members via SMS.
  3. After sending the invite, Disbursement API will return a response having the total number of members that have been invited.
You may checkout the complete API specs in our API Reference page.
Optional: Check Member Record Status

Check the member’s invite status by using their phone numbers in this API endpoint.

  1. Client sends request via GET /members/{phoneNumber} providing the member's phone number on the path parameter. Request should have the x-api-key.
  2. Disbursement API will return the status of the member retrieved using the phoneNumber.
You may checkout the complete API specs in our API Reference page.

Member Record Statuses

StatusDescription
ACTIVEUser successfully invited; Maya account was created and added in the master list
EXPIREDUser did not reply with YES to the SMS invite within seven (7) days OR another institution sent an invite to the same user
INVITE_FAILEDSMS invite was not successfully sent to the user
INVITINGSMS invite is still in the process of sending
INVITEDSMS invite was successfully sent to the user
DECLINEDUser replied NO to the SMS invite
PENDINGUser replied YES to the SMS invite and is already being processed for Maya account creation
ERROR
SUSPENDED
DUPLICATED
CLOSED
Processing of the account creation was unsuccessful; contact Maya Partner Account Services at [email protected] for assistance
REMOVEDUser is now deactivated as a member. User can no longer be recipient of disbursement

Disbursing Money

In disbursement flow, you are provided with APIs that will empower you to create and execute disbursements to your registered beneficiaries.

How to do disbursement

Step 1: Create the disbursement file You may download the sample file for reference: sample-disbursement-file.csv

Field NameDescriptionAttribute (character limit)Sample ValueM/O/C
Mobile NumberRegistered mobile number of the member.NS (13)Strict Format: +639xxxxxxxxx

+639471234567
M
AmountAmount to be disbursed (in Philippine Peso)NS (12)123456789.12M
Step 2: Initiate session

ℹ️ Conditional: This is if NO existing session or previous session has already expired.

See Managing Sessions on how to initiate session with Maya's Disbursement API.

Step 3: Submit disbursement file

Client must submit a CSV file containing the registered mobile number of the beneficiaries and amount to be disbursed.

  1. Client submits the file via the POST /disbursement endpoint
  2. Disbursement API acknowledges the request and returns disbursementId referencing to the disbursement file.
You may checkout the complete API specs in our API Reference page.

ℹ️ This endpoint requires you to provide your walletId which you can acquire by calling the GET /wallet endpoint.

Step 4: Get the disbursement file status

By providing the ID acquired during submission of disbursement file, use this API to check the status of the disbursement file.

  1. Using the disbursementId, Client can get the disbursement file status via the GET /disbursements/{disbursementId} endpoint.
  2. Disbursement API will return the status for the disbursement file.
You may checkout the complete API specs in our API Reference page.

Disbursement File Status

StatusDescription
Creating…Started the creation of disbursement records in Disbursement API
Ready to DisburseDone creating disbursement record and is ready for execution
Disbursing…Execution of disbursement has started
CompletedAll records on the file were disbursed successfully
Completed (with errors)Some records succeeded; some have failed.
FailedNo records on the file were disbursed successfully
Step 5: Execute disbursement

When the status of the disbursement file becomes ‘Ready to Disburse’, proceed with the disbursement by providing the disbursement ID and password when calling this API.

  1. Using the disbursementId, process the disbursement file via the POST /disbursements/{disbursementId} endpoint.
  2. Disbursement API will return a status acknowledging the request to process the disbursement file.
  3. Disbursement API process the disbursement file records, including sending of funds to the target members.
You may checkout the complete API specs in our API Reference page.
Optional: Inquire balance

Check your wallet balances to make sure you have sufficient balance to disburse credits to your beneficiaries.

  1. Client to send a request via GET /wallet endpoint
  2. Disbursement API will return the client's account balance details
You may checkout the complete API specs in our API Reference page.

Extracting Transaction Records

How to extract transaction records

Step 1: Initiate session

ℹ️ Conditional: This is if NO existing session or previous session has already expired.

See Managing Sessions on how to initiate session with Disbursement API.

Step 2: Extract transaction records

Use these endpoints to retrieve the disbursement transactions. An endpoint is provided for successful transactions and a separate endpoint for the failed transactions.

Successful Transactions:

  1. Client to send request via the GET /disbursements/{disbursementId}/records-success endpoint
  2. Disbursement API will return a list of disbursement records with status TRANSFER_ACCEPTED
You may checkout the complete API specs in our API Reference page.

Failed Transactions:

  1. Client to send a request via the GET /disbursements/{disbursementId}/records-failed endpoint
  2. Disbursement API will return a list of disbursement records that has the following statuses:
    • CREATE_FAILED
    • TRANSFER_FAILED
    • REFUNDED
    • REFUND_FAILED
    • FAILED
You may checkout the complete API specs in our API Reference page.