Biller API

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 the result.message should reflect the error message matching the result.code.

See table below.

⚠️ 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.

1. User fills out the payment details through the Maya app and clicks “Continue“.
2. The Maya app initiates the Create Bill Payment request, with the customer’s bills payment details.
3. The Maya Biller API shall call the v1/validate endpoint of the Biller Validate endpoint.
4. The Biller Validate endpoint shall validate the bills payment details, e.g. Account Number is invalid, etc.
5. 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.
6. 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.

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.

⚠️ 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.

1. Through the Maya app, the user reviews the payment details using the Maya app and clicks “Pay“ to confirm.
2. Maya’s Biller API performs the following:
   1. Creates the Bills Payment transaction.
   2. Charges the bill amount (amount + convenience fee) from the customer account.
   3. Sends the transaction posting request to the Merchant’s Biller Post endpoint.
3. The Maya Biller API shall call the v1/post endpoint of the Biller Post endpoint.
4. The v1/post of the Biller Post endpoint should respond to the Maya Biller API as soon as the request is queued for processing.
5. The Maya Biller API will receive the HTTP status code response, and returns the status of the request to the Maya app.
6. 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.

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 and result.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.

1. The Partner’s Biller Endpoint to send callback v1/billspay/{id} to inform the final status of the payment.
2. Maya’s Callback Service shall acknowledge the callback message and shall send the response code status.
3. 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.

B. Callback Response (From Maya Biller API)

Upon receiving the callback, Biller API shall respond with the Status Code listed on the table below.

Biller API Response Error Codes

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.

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:

ℹ️ Choose the Callback Strategy first, then decide on the Expiration Configuration. Transaction should not expire immediately if the Callback Strategy is via batch.