Technical Details

Managing sessions

Managing sessions are important to establish secure access and leverage Payout 1.0 functionalities.

Initiate session

Create a session with the Maya’s Payout 1.0 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.
  2. Payout 1.0 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, Payout will terminate the session.
You may checkout the complete API specs in our API Reference page.

Inviting Members

In this stage, Payout 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, Payout 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 Payout 1.0.

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. Payout 1.0 will process the file and sends invite to members via SMS.
  3. After sending the invite, Payout 1.0 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. Payout 1.0 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

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 Payout 1.0.

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. Payout acknowledges the request and returns disbursementId referencing to the disbursement file.
You may checkout the complete API specs in our API Reference page.
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. Payout 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 Payout
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. Payout will return a status acknowledging the request to process the disbursement file.
  3. Payout 1.0 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 GET request via the /wallet endpoint
  2. Payout 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 Payout 1.0.

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 a GET request via the /disbursements/{disbursementId}/records-success endpoint
  2. Payout 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 GET request via the /disbursements/{disburementId}/records-failed endpoint
  2. Payout 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.

Did this page help you?