Biller API
What the Biller API does for you?
Maya offers multiple Bills payment integration opportunities. These are the features in the scope of the integration with the Maya Biller API.
Features | Description |
---|---|
Integration Development | As a Partner Biller, you have a development team ready to integrate with Maya’s Bills Payment APIs. Use Maya’s Biller API to integrate, receive bills payment transactions, and perform transaction callback. |
Transaction Validation | Both Maya and the Partner Biller validates. Maya validates initial transaction requests once customers input payment details. As a Partner Biller, you will be receiving the transaction details, which enables you to pre-validate the information. |
Transaction Posting | Perform posting on both Maya and the Partner Biller automatically. Within the same transaction flow, expect a posting transaction request that enables you to trigger the Bills Pay Callback, and confirm the transaction as Fulfilled. |
Reconciliation and Report | Download the settlement reports from the Maya Manager and use it for reconciliation with your other reports. |
What APIs should you use?
Maya has multiple APIs that the partner can use during the Bills Payment transaction.
The Mandatory APIs
There are three (3) mandatory APIs that are used within a singular customer transaction. The sequence of the APIs is as follows: Validate Bills Payment, Post Bills Payment, and Send Posting callback.
As for Inquire Transaction, it should still be implemented by Partner Biller.
For more details on how each API is used, proceed to
API | Description |
---|---|
Validate Bills Payment | Maya’s Biller API will send a request to the Partner’s Service to validate the correctness of the Bills Payment transaction details. These are the inputs of the customer via the Maya app. The Partner Service shall perform the validation of the fields. |
Post Bills Payment | After the Validate Bills Payment API, Maya’s Biller API shall send a Post Bill Payment transaction request to the Partner Service indicating that the customer’s Maya account has been debited with the paid amount. This also signals the Partner Service to validate and update/credit their customer’s account on their side. |
Send Posting Callback | The Partner Service to initiate a callback to the Maya Biller API to confirm the posting of the transaction. If the Partner Service fails to send a Callback or declines the Posting, Maya’s Biller API shall provide a declined response and shall reverse the payment to the customer. |
Inquire Transaction | Maya’s Biller API sends an Inquire Transaction request to the Partner Biller to verify the transaction’s status. |
Contact your Maya Relationship Manager for the complete Biller API specifications.
The Optional APIs
These APIs are optional to be included within the same transaction flow of the Bills Payment transaction. The Partner Biller should be ready to receive transaction requests from Maya’s Biller APIs.
API | Description |
---|---|
Get Fee | Maya’s Biller API sends a request to retrieve the fee value. NOTE: Fee rates are defined at the onset of the contract engagement, Get Fee can be used for possible fee change requests from the Partner. |
Contact your Maya Relationship Manager for the complete Biller API specifications.
Signature and Authorization
The Partner Biller should understand the request header that they will be receiving and sending, within the transaction flow.
Validate Bills Payment and Post Bills Payment
Maya will be sending the Validate Bills Payment and Post Bills Payment requests to the Partner Biller. The header on the requests will include the paymaya-signature.
Components of a paymaya-signature
- Its value is a hash of the stringified request body
- signed using the secret-key (This will be provided during the Biller API onboarding)
Request-Reference-No: [RRN Value Here]
paymaya-signature: [Paymaya Signature]
How to compute for the paymaya-signature
The hash & encoding to be used are as follows:
- Hash: SHA256
- Signature Encoding: Base64
To compute for the paymaya-signature, the Partner Biller can use these Sample Codes for Signature Computation:
Language | Link | Description |
---|---|---|
NodeJS | Sample NodeJS Signer Tool Code | Requires at least NodeJS v8 |
Java | Sample Java Signer Tool Code | Requires at least Java 8 |
Instruction in using the tool and sample data is in the README.md
file.
The request has been verified by the Partner Biller if the generated signature both by the partner and Maya match. This ensures that the request has not been modified by an external party.
Callback
The Partner Biller shall send the Send Posting Callback to Maya’s Biller API, to fulfill or fail the authorized Bills Payment transaction. The request is expected to have an HTTP basic access authentication. The header field will be in the form of Authorization: Basic <credentials>
.
Components of the header field Authorization: Basic <credentials>
Authorization: Basic <credentials>
Basic
indicates the authentication scheme<credentials>
is the the Secret Key encoded in Base64
Request-Reference-No: [RRN Value Here]
Authorization: Basic (Secret key encoded in Base64)
The following steps narrate how to use your API Keys:
- Use the appropriate or required key as the Username, followed by a ':' (colon) and then the Password which should be left blank. If your API key is
pk-Z0OSzLvIcOI2UIvDhdTGVVfRSSeiGStnceqwUE7n0Ah
, the resulting string is:
pk-Z0OSzLvIcOI2UIvDhdTGVVfRSSeiGStnceqwUE7n0Ah:
- Apply Base64 encoding to the resulting string from Step 1. Using the sample value above, the Base64 encoded string will be:
cGstWjBPU3pMdkljT0kyVUl2RGhkVEdWVmZSU1NlaUdTdG5jZXF3VUU3bjBBaDo=
- Indicate the authorization method i.e. “Basic” followed by a space then the Base64 encoded string in Step 2. An example is shown below:
Authorization: Basic cGstWjBPU3pMdkljT0kyVUl2RGhkVEdWVmZSU1NlaUdTdG5jZXF3VUU3bjBBaDo=
See also: HTTP Basic Auth
How to Process Maya Biller API
Refer to BILLS PAYMENT for Maya Bills payment customer journey via the Maya Consumer and Business (Negosyo) app.
The API calls to Validate Bills Payment, Post Bills Payment, and Callback endpoints should always be sequential.
Step 1: Create and Validate Bills Payment (to Receive)
What is the endpoint expected to do:
- Send to Partner’s Biller Validate Endpoint, to validate the correctness of the bill payment transaction details.
- Treat as a validation request. Do not save validation request in Partner Biller’s Database.
- Partner’s Biller Validate Endpoint should respond with a
result.code
. If the result code value is NOT 0000, then theresult.message
should reflect the error message matching the result.code.
See table below.
Code | Mapped | Description | Sample (result.message) |
---|---|---|---|
0000 | N | Bill payment details are valid. The customer may proceed with payment. | N/A |
2559 | Y | Error messages from responses would be mapped back to the customer in the app. The message is not customizable. | Account Number is invalid |
2596 | Y | Error messages from responses would be mapped back to the customer in the app. | Some example messages include: - Amount is invalid - MobileNo is invalid / required - Billing data does not exist - Bill is expired - ReferenceNo is expired |
ACQ018 | N | Error message to be sent to MAYA for internal consumption only. The message is customizable. - Should be descriptive to help Maya know the exact error for proper monitoring (ex. system errors) | Some example messages include: - Maya signature mismatch. - The biller cannot accept payments right now. Please try again later. |
If
result.code
value is not in the list of the valid values, the Bills Payment transaction shall be considered as invalid and shall be marked as FAILED.
Contact your Maya Relationship Manager for the complete Biller API specifications.
- User fills out the payment details through the Maya app and clicks “Continue“.
- The Maya app initiates the Create Bill Payment request, with the customer’s bills payment details.
- The Maya Biller API shall call the
v1/validate
endpoint of the Biller Validate endpoint. - The Biller Validate endpoint shall validate the bills payment details, e.g. Account Number is invalid, etc.
- The Biller Validate endpoint shall send a response which includes the
result.code
and fees. The Maya Biller API will create the payment slip will the transaction details. - This prompts the user to review and confirm the payment slip. The status of the transaction will be updated to “Processing“.
The setup of fees between Maya and the Partner Biller should match, which is based from the contract agreement. For changes in fees, contact your assigned Maya Relationship Manager. Maya Biller API may use Get Fee API for fee updates.
Step 2: Execute and Post Bills Payment (to Receive)
What is the endpoint expected to do:
- Partner’s Biller Post Endpoint to receive a Post Bill Request, which includes the bill details, amount, fee, and callback URL.
- Biller Post Endpoint is required to persist the transaction request and manage the bill payment states.
The table below enumerates the list of HTTP Status Codes the Biller API expects to receive.
HTTP Status Code | Description |
---|---|
2xx | The request was successfully received by the Biller and shall be queued for processing. |
503, 504, 598, 599 | A timeout has occurred. Once received, Biller API shall retry sending the request until it receives a successful response or reaches the maximum number of retries. |
4xx, 5xx | A Client or Server error occurred. Once received, Biller API shall mark the request as POSTING FAILED. |
Maya will not be sending a Post Bills Payment request without a prior Validate Bills Payment request. As a security measure, the Partner’s Biller Post endpoint can revalidate the payment details provided in the request before processing.
Contact your Maya Relationship Manager for the complete Biller API specifications.
- Through the Maya app, the user reviews the payment details using the Maya app and clicks “Pay“ to confirm.
- Maya’s Biller API performs the following:
- Creates the Bills Payment transaction.
- Charges the bill amount (amount + convenience fee) from the customer account.
- Sends the transaction posting request to the Merchant’s Biller Post endpoint.
- The Maya Biller API shall call the
v1/post
endpoint of the Biller Post endpoint. - The
v1/post
of the Biller Post endpoint should respond to the Maya Biller API as soon as the request is queued for processing. - The Maya Biller API will receive the HTTP status code response, and returns the status of the request to the Maya app.
- The user is prompted with the payment receipt together with the status “Authorized“.
The Partner’s actual processing of the payment should be done in the background and NOT during the Post Bill Payment Sequence. Otherwise, Maya Biller API may encounter timeouts if
v1/post
takes time to respond.
Step 3: Send Posting Callbacks (to Send)
What is the endpoint expected to do:
- The Partner Biller’s endpoint is to send at least one (1) call back for each posted Bills Payment transaction.
- The Posting Callback
result.code
andresult.message
shall indicate the Partner Biller’s handling of the posted transactions queued on their side. - If the Partner Biller fails to send a callback before the expiry setting, Maya’s Biller API shall reverse the payment to the customer’s account and set the transaction’s status to POSTING FAILED.
Contact your Maya Relationship Manager for the complete Biller API specifications.
- The Partner’s Biller Endpoint to send callback
v1/billspay/{id}
to inform the final status of the payment. - Maya’s Callback Service shall acknowledge the callback message and shall send the response code status.
- Maya updates the status of the bills payment based on the callback's
result.message
.
What are the expected responses:
A. Callback Request (from Partner Biller Endpoint)
Partner’s Biller Validate Endpoint should respond with a result.code
. If result code is NOT 0000, the result.message
should reflect matching the result.code.
If the
result.code
value is not in the list of valid values, the Bills Payment transaction shall be considered invalid and shall be marked as POSTING FAILED.
The Mapped column indicates if the result.message
requires mapping.
Code | Mapped | Description |
---|---|---|
0000 | N/A | Bills Pay was successfully posted |
2559 | Y | Account Number is invalid |
2593 | Y | [Field] is invalid / required |
2596 | N | Bill Payment does not exist |
ACQ018 | N | Generic Biller Validation Error |
B. Callback Response (From Maya Biller API)
Upon receiving the callback, Biller API shall respond with the Status Code listed on the table below.
HTTP Status Code | Description |
---|---|
2xx | The request was successfully received. |
5xx | An Internal Server error occurred. Once received, it is advised that the Partner Service retries sending the callback. There is no limit to the number of times a callback is sent. |
4xx | A Client error occurred. A description of the error can be seen in the response’s error.description . It is advised that the Partner Service retry sending the request once the error is fixed on their end. |
Biller API Response Error Codes
4xx Error Codes | Description |
---|---|
2596 | Bills Payment is not found |
2593 | [Field] is invalid / required |
ACQ019 | General Biller System Error |
ACQ020 | Bill payment is already expired |
ACQ021 | Bills Payment’s status is already fulfilled |
ACQ022 | Bills Payment Status is invalid (Not Posted) |
1997 | Authorization is invalid Authorization is expired Authorization does not have a scope |
Callback Strategy
During the Onboarding preparations, the Biller Partner has the option to choose between the two (2) strategies on how they will handle the sending of Posting Callback to the Maya Biller API, whether Live or via Batch.
Strategy | Description | Remarks |
---|---|---|
Live Posting | The callback is sent right after Posting | The Partner Service to send a Callback to Maya’s Biller API, with a minimum of 30 seconds delay, after responding to the Post Bills Payment request. |
Batch Posting | The callback is sent at a scheduled time by the Biller Partner. | At least once (1) a day bulk Callback. If this option is preferred, the configuration of the transaction expiration should account for the batch schedule. The expiration and schedule of the batch may affect the settlement reports. |
Expiration Configuration
As part of the onboarding requirements, the Partner Service shall define the configuration on how long the transaction shall be considered PROCESSING on their end. If the Callback has not been sent before the transaction expires, Maya will fail the transaction and reverse the balance.
See the table below as an example:
Biller | Expiration | Transaction Date/Time | Expiration Date/Time |
---|---|---|---|
A | 24 hours | 08/14/2019 12:00 PM | 08/15/2019 12:00 PM |
B | 12 hours | 01/02/2019 1:00 AM | 01/02/2019 1:00 PM |
C | 2 hours | 06/12/2019 3:00 PM | 06/12/2019 5:00 PM |
Choose the Callback Strategy first, then decide on the Expiration Configuration. Transaction should not expire immediately if the Callback Strategy is via batch.
Generate Reports
Maya Settlement Reports
View daily settlement reports via Maya Business Manager, which covers all previous day successful purchase transactions and refunds. The fees, either Service Fee or Convenience Fee, are also indicated in the generated report, and is deducted/added accordingly to compute total settlement amount.
Not yet familiar with how to download Settlement Reports?
Understanding the States of a Transaction
States show the current status of the Bills Payment transaction. It is determined by the actions of the Bills Payment API and Partner’s API.
The figure and the table below shows the State lifecycle as it is processed by the Maya Bills Payment API and the partner’s integrating service/API.
State | Description |
---|---|
NEW | During this stage, the New state indicates that the transaction is created and Step 1: Create and Validate Bills Payment (to Receive) is successful. |
PROCESSING | With Processing, this means Step 2: Execute and Post Bills Payment (to Receive) has started and ongoing processing of the bill payment details. |
AUTHORIZED | Bills Payment was successfully authorized by the payment facility involved during the Execute and Post Bills Payment. Once authorized, the charge amount will be deducted from the Maya wallet of the customer. |
POSTING | This is the status after a successful Post Bills Payment to the Partner Biller Post Endpoint. |
FAILED | Bill payment was not successful due to a failed wallet debit or other related errors. |
FULFILLED | Within Step 3. Send Posting Callbacks (to Send), the status will be Fulfilled if the callback request result code is success (0000). Fulfilled transactions will be included in the settlement reports. |
POSTING FAILED | The callback request result code is an error (any response besides 0000). The transaction amount will be refunded back to the customer’s account. |
Test your endpoints
Maya Biller API Quick Start Guide to learn more about the integration requirements.
Go to
Local Development Testing
While you are still ongoing on the local development of your Biller endpoints, you may use the Local Development Mock Testing Postman collection. Here you may simulate transactions using Maya's mock API endpoints, integrated into your developed platform endpoints.
Make sure test results have passed the minimum requirements for each Biller API. In cases of errors that require troubleshooting, refer to
Sandbox Integration Testing
The Biller API Sandbox Integration Testing is a testing phase performed in the Sandbox environment, wherein you test the integration between Maya's Sandbox API endpoints and your Biller services.
Download the Biller API Sandbox Integration Testing Postman collection, and follow the steps for integration testing between Maya and your platform.
Make sure you are done with the Local Development Mock Testing and you have been notified by your designated Maya Relationship Manager, that you have been onboarded in the Sandbox environment.
Updated 6 months ago