Bills Payment FAQ

Direct Biller API

Overview

1. What is the scope of the merchant in development?

Develop the Biller API, follow specs to accomplish this.

2. Do we have an Open API version?

We are working on it! But for now, please refer to our Biller API Tech Guide.

3. Can we use a managed service to develop?

No. Please use a standalone scaleable solution / service.

Signature and Authorization

1. What's the difference between authorization on VALIDATE / POST and CALLBACK?

2. How to do the Maya signature computation?

Do not convert to object first; use raw REQUEST body.

3. For NodeJS sample signature computation, which of the output is the Maya signature?

Validate

1. How do we derive the fee part in the RESPONSE body?

Use base amount.

2. Can we change the fees in the body any time?

3. What is the difference between Biller Convenience Fee and Service Fee?

In Biller API, it's always convenience fee.

4. Do we note the breakdown of shares here in the API?

SOA

5. Can you change the timezone in the REQUEST body from UTC to different time zones?

No.

6. Can we change the endpoint URL for the APIs?

Yes. Just ensure to indicate the appropriate endpoint in the integration form.
/v1/ is just an internal reference. Whatever is inputted in the form is what we will be onboarding

7. Can I provide a specific app error message associated with the error code?

You can utilize error code 2596.
Check the response code mapping table under How to Process Maya Biller API Step 1

8. Do you have a flowchart to map the error codes?

9. Do you have a sequence diagram?

Post

1. In our POST request body, does our callback URL inclusive of the Bills Payment ID already?

Yes.

2. Does the ID in Validate match the ID in Post?

No.

3. Should our technical implementation be asynchronous?

Yes.
POST API should acknowledge Request, but actual processing happens independently.

4. What value should be used for the receiptNumber?

Any ID to uniquely identify the transaction in the biller's side. Max 250 length.

Testing

1. How do we test our service before staging?

Test thru Postman first, then Maya will assist for integration testing.
(include mocking via Wiremock)

2. Do you have a test environment for this integration?

No.

Infrastructure

1. Can Maya accept either IPs: static or dynamic?

Static or dynamic is ok, just needs to be coordinated with Maya.
For dynamic IPs, please use the same DNS.

2. Can you change the timezone in the services and databases from UTC to different time zones?

No.

3. How do we transmit the GPG Public Key to Maya?

Via email

Check Digit Validation

1. What if the customer types in a wrong account number, but is successfully passes the CDV validation?

Maya can perform refund as per request of Customer or Partner Biller.

Biller Portal

Tutorial

Video links

About the Portal

1. What is the Maya Biller Portal?

The Maya Biller Portal is an integration tool used by merchants to manually validate the details of the transactions / payments of customers.

2. Why do I need to validate my transaction first before settlement?

It is important to validate the details of the transactions / payments of customers to ensure accuracy in posting the payments to the customer's account. This must be done before settlement of funds to the merchant.

3. Are there fees to use the Maya Biller Portal?

There are no platform fees to use the Maya Biller Portal. The only fees to be charged by Maya will be the biller convenience fee / service fees associated with each transaction.

4. What is the difference between the Maya Biller Portal and the Maya Business Manager?

The Maya Biller Portal is an integration tool used by merchants to manually validate the details of the transactions / payments of customers. The Maya Business Manager is our current system for our partner merchants where they can download their settlement reports.
We are working on migrating all of the Maya Business Manager's features, including new ones, into the Maya Manager 2.0 BETA. Existing partner merchants may still use Maya Manager, so no action is needed from you at this point; we will be sending you an email once we have completed migration of your account to Maya Manager 2.0 BETA. For more information, [click here]().

5. Can I download my settlement report in the Maya Biller Portal?

No, you can only download your settlement report in the Maya Business Manager. You can download a validation report in the Maya Biller Portal, which consists of transactions for the validation of the merchant. The transactions listed in the validation report aren't guaranteed to be for settlement. For more info, click [here]().

6. Why does the portal look disoriented or disorganized?

You may be using a browser that may not be fit for the Maya Biller Portal.
Please use the following browser versions below:
- Google Chrome - Version 100.0.4896.127 and up
- Safari - Version 15 and up
- Microsoft Edge - Version 100.0.1185.50 and up
- Brave - Version 1.37.116 and up
- Mozilla Firefox
- Internet Explorer

Approve/Reject

1. What happens if I approve a transaction?

All approved transactions / payments are to be settled to the merchant next business day. All such transactions / payments are expected to be posted in the customer's accounts.

2. What happens if I reject a transaction?

All rejected transactions / payments are to be refunded back to the customer within the day. The customer will receive a text message indicating that their transaction with the merchant was unsuccessful.

3. What happens if I incorrectly approved or rejected a transaction?

As of now, there is no way to undo approval or rejection of a transaction due to the system's real-time fulfillment or reversal of transaction.

4. What happens if I do not approve or reject a transaction on the agreed upon agreement / SLA?

If the merchant was unable to approve / reject the transaction on the agreed upon SLA, the transaction will expire and it will automatically be deemed "rejected."
All rejected transactions / payments are to be refunded back to the customer within the day. The customer will receive a text message indicating that their transaction with the merchant was unsuccessful.

5. When and why do transactions expire?

Transactions expire if it was not approved within SLA. Transactions should be approved latest T+3, 11pm. For example, customer paid on Jan 1, 2022 (Friday), 11:30pm. The merchant has to approve the transaction latest Jan 4, 2022 (Monday, 11pm).
Transactions expire so customers immediately get feedback on their payments. If the transaction is approved, customer will get a confirmation in his receipt that the payment is for posting. If the transaction is rejected or expired, customer will get a text message indicating that their transaction with the merchant was unsuccessful.

6. When and how will the customer know if I approved or rejected the transaction?

If the transaction is approved, customer will get a confirmation in his receipt that the payment is for posting.
If the transaction is rejected or expired, customer will get a text message indicating that their transaction with the merchant was unsuccessful. Their payments are to be refunded back within the day.

7. When will the approved transactions / payments be settled to me?

Approved transactions will be settled to the merchant the next business day, on or before 12pm. Note that only approved transactions are to be settled.
For example, merchant approved a transaction dated Jan 1, 2022 on Jan 1, 2022 (Friday), 6pm, the transaction will be settled on Jan 4, 2022 (Monday).
If the merchant approved a transaction dated Jan 1, 2022 on Jan 2, 2022 (Saturday), 7am, the transaction will be settled on Jan 4, 2022 (Monday).

8. How will I approve or reject if I cannot access the portal for some reason?

Please immediately contact your Maya partner if you are having trouble accessing the portal.

View Transaction

1. Is the amount presented in the portal as gross or net amount?

The amount presented in the portal is the gross amount, exclusive of fee charges. The breakdown of the fee charges will be listed in the settlement report, downloadable in the Maya Business Manager.

2. When do transactions come in to the portal?

The transactions / payment details come real-time. Once a customer or agent transacts in the Maya app, it will automatically be listed in the Maya Biller Portal. This is to allow the merchant to validate the transactions in his preferred schedule (as long as it is before the agreed upon SLA).

3. What is the basis of the details of the transactions in the portal?

All the details in the portal (besides the transaction date, status, and reference number) are provided by the customers during payment in the app. Maya does not alter this in any manner.

4. Why are some details not in the transaction page?

There is a maximum number of columns of data presented in the portal's transaction page. This is to ensure the portal is still easy to use and data can be easily read.
You may view the complete details of the transaction by clicking on the account number in the transaction page. You may also view the complete details by downloading a report.

5. What is the basis of the date and time in each transaction?

The transaction date is the actual time we received the payment of the customer and debited their wallet.

6. How do I view the complete details of my transaction?

You may view the complete details of the transaction by clicking on the account number in the transaction page. You may also view the complete details by downloading a report.

7. What is the reference number?

The reference number is the unique identifier of the transaction / payment. Customer and merchants alike can use this number for any after-sales concerns.

Summary Page

1. Why are there only four days listed in the summary page?

The page lists down the total transactions and number of transactions to be approved still. It reflects four days to showcase the agreed upon SLA (T+3, 11pm) accordingly.

Download Report

1. When can I download the report?

You can download a report anytime. The reports will showcase all the transaction details currently present on the portal, depending on your filter.

2. Up to what date can I download a previous report?

You can download a report which is dated on or before 31 days from today.

3. Can I request for a report in a different format apart from what the portal currently has?

As of now, the portal only supports XLSX and CSV file formats.

4. Can I request to change any specification in the report (ex. filename, file type, data element)?

As of now, the portal will only list down all the data elements provided by the customer; along with the transaction date, status, and reference number. It is not possible to tweak any specification in the report post-onboarding.

5. Can I request to password protect the report I download from the portal?

As of now, there is no way to password protect the reports downloaded from the portal.

6. Why is there no total volume in the report I downloaded?

You may have downloaded a report with a combination of states. Example, you downloaded an FOR APPROVAL + APPROVED report. Given the differences in states, there would be no use for the total volume. Try downloading a report with a single state only.

7. Why are the account numbers seemingly incorrect in my report?

Most of the time, this means the customer provided the incorrect account number. You may reject the transaction or contact the customer if this is the case.
In rare cases, you may have downloaded a report in CSV and your account numbers start with "0". Excel automatically hides the "0" if it is the first number in the cell.

8. Is there a way I can dump a report in the portal and use that as basis to approve?

As of now, dumping / attaching files in the portal is not supported. The only way you can approve is by clicking the "Approve" or "Approve All" button.

9. Is the report I download from the portal different from the settlement report?

Yes, it is different. You can only download your settlement report in the Maya Business Manager.
You can download a validation report in the Maya Biller Portal, which consists of transactions for the validation of the merchant. The transactions listed in the validation report aren't guaranteed to be for settlement. For more info, click []().

10. Why is there an N/A in the report?

The N/A indicates that the customer did not provide any details for that particular field. Given that the field was optional, the customer was able to pay without providing this detail.

Account Management

1. How do I access the Maya Biller Portal?

Please get in touch with your Maya Relationship Manager so they can provide your authorized users access to the portal.
Once your Relationship Manager confirms your request and access, you may check out the portal here:
- Log in to https://biller.paymaya.com
- Check your OTP in your email and input it in the field.
- Use the Maya Biller Portal.

2. What documents do I need to submit to get an access to the Maya Biller Portal?

You will need to submit the following documents to get an access to the portal:
- Signed Proposal
- Bills Payment Client Application Form and Terms and Conditions
- Merchant Information Template (MIT)
- Valid government IDs of signatories and Ultimate Beneficiary Owners
- Secretary Certificate OR Board Resolution with UBO Declaration
- BIR Certificate of Registration (Form 2303)
- Bank Statement or Open Passbook where settlement will be deposited
- Mayors/Business Permit
- By-Laws
- SEC Registration
- Latest Audited Financial Statement
- FAQs
- Escalation matrix and SLAs for disputes and reversal

3. I forgot my password. To whom can I ask for help?

You may refresh your password thru the following steps:
- Go to https://connect.paymaya.com/login
- Click "Forget your password"
- Enter your email.
- Follow the instructions in the automated email to reset your password.
If it didn't work, please get in touch with your Maya Relationship Manager to assist you in refreshing your password.

4. How can I add or remove a user?

As of now, you would need to send a revised Secretary Certificate with the inclusion / deletion of the changes. Please get in touch with your Maya Relationship Manager and submit the revised document.

5. How can I assign roles to a user?

As of now, this feature is not applicable. All authorized users will get full access to all the features of the portal.

6. How can I update the details of my business in the portal?

Please get in touch with your Maya Relationship Manager to update the details of your business in the portal.

7. Can I have multiple users accessing the portal?

Yes, but these users should all be declared in your Secretary Certificate.
Please get in touch with your Maya Relationship Manager to add more users.

8. How do I change my password?

You may refresh your password thru the following steps:
- Go to https://connect.paymaya.com/login
- Click "Forget your password"
- Enter your email.
- Follow the instructions in the automated email to reset your password.
If it didn't work, please get in touch with your Maya Relationship Manager to assist you in refreshing your password.

9. Where do I receive my OTP?

You may check your OTP in the email that has authorized access to the portal.

10. I am not receiving my OTP. What can I do?

There may be special circumstances out of Maya's control, such as weak network signal, that may prevent you from receiving your OTP at the designated timeframe. Make sure that you have stable network signal to receive the OTP key in your email. You may also check your spam folder.

Other concerns

1. I have a concern but it's not in the FAQs. Who can I contact?

You may get in touch with us through the following links below:
- Account Management: File a ticket here: https://enterprisehelp.paymaya.com/s/contactsupport
- Other Concerns: Email us in [email protected]