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.
- 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.
- Disbursement API will authenticate Client by the credentials provided and returns the status of the request.
Optional: Terminate session
An optional operation. A session automatically times out 10 minutes after the last successful API call.
- For manual termination of session, Client sends a DEL request via the /sessions API endpoint.
- Upon receiving this request, Disbursement API will terminate the session.
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.
- Client submits the member file in CSV format via the
POST /membersrequest. Request should have the x-api-key. - Disbursement API will process the file and sends invite to members via SMS.
- After sending the invite, Disbursement API will return a response having the total number of members that have been invited.
Optional: Check Member Record Status
Check the member’s invite status by using their phone numbers in this API endpoint.
- Client sends request via
GET /members/{phoneNumber}providing the member's phone number on the path parameter. Request should have the x-api-key. - Disbursement API will return the status of the member retrieved using the phoneNumber.
Member Record Statuses
| Status | Description |
|---|---|
| ACTIVE | User successfully invited; Maya account was created and added in the master list |
| EXPIRED | User did not reply with YES to the SMS invite within seven (7) days OR another institution sent an invite to the same user |
| INVITE_FAILED | SMS invite was not successfully sent to the user |
| INVITING | SMS invite is still in the process of sending |
| INVITED | SMS invite was successfully sent to the user |
| DECLINED | User replied NO to the SMS invite |
| PENDING | User 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 |
| REMOVED | User 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 Name | Description | Attribute (character limit) | Sample Value | M/O/C |
|---|---|---|---|---|
| Mobile Number | Registered mobile number of the member. | NS (13) | Strict Format: +639xxxxxxxxx +639471234567 | M |
| Amount | Amount to be disbursed (in Philippine Peso) | NS (12) | 123456789.12 | M |
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.
- Client submits the file via the
POST /disbursementendpoint - Disbursement API acknowledges the request and returns disbursementId referencing to the disbursement file.
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.
- Using the disbursementId, Client can get the disbursement file status via the
GET /disbursements/{disbursementId}endpoint. - Disbursement API will return the status for the disbursement file.
Disbursement File Status
| Status | Description |
|---|---|
| Creating… | Started the creation of disbursement records in Disbursement API |
| Ready to Disburse | Done creating disbursement record and is ready for execution |
| Disbursing… | Execution of disbursement has started |
| Completed | All records on the file were disbursed successfully |
| Completed (with errors) | Some records succeeded; some have failed. |
| Failed | No 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.
- Using the disbursementId, process the disbursement file via the POST /disbursements/{disbursementId} endpoint.
- Disbursement API will return a status acknowledging the request to process the disbursement file.
- Disbursement API process the disbursement file records, including sending of funds to the target members.
Optional: Inquire balance
Check your wallet balances to make sure you have sufficient balance to disburse credits to your beneficiaries.
- Client to send a request via
GET /walletendpoint - Disbursement API will return the client's account balance details
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:
- Client to send request via the
GET /disbursements/{disbursementId}/records-successendpoint - Disbursement API will return a list of disbursement records with status TRANSFER_ACCEPTED
Failed Transactions:
- Client to send a request via the
GET /disbursements/{disbursementId}/records-failedendpoint - Disbursement API will return a list of disbursement records that has the following statuses:
- CREATE_FAILED
- TRANSFER_FAILED
- REFUNDED
- REFUND_FAILED
- FAILED
Updated almost 2 years ago