Biller API Local Development Mock Testing

The Biller API Local Development Mock Testing is a testing phase during your development wherein you simulate the API calls between Maya's mock API endpoints and your developed platform endpoints. Go to Maya Biller API Quick Start Guide to learn more about the integration requirements.

⚠️ This tool is designed solely for mock simulation testing as you continue coding for your Biller API endpoints.

Objectives

At the end of this local development testing phase, the following objectives are expected to be attained:

  1. To help the merchant developers ensure that their developed services align with Maya's Biller API Specifications:
    1. Familiarization on the expected requests to be ingested by merchant’s services for both Validate and Post legs.
    2. Correct computation for the expected security headers: paymaya-signature header value for Validate and Post, Authentication header value for Callback.
    3. Proper response codes for each scenario in the Validate and Post legs.
  2. For merchant developers to be empowered to test developed services, troubleshoot, and enhance their services, based on expected results from the tool.

Pre-requisites

  1. Has read and understood the following:
    1. API sequence of initiating a Bills payment transaction
    2. The in-app Bills payment customer journey
  2. Obtained initial integration requirements and developed required endpoints based from the Biller API Specifications.
  3. Download and install Postman application.
  4. Download the Maya Bills Pay Direct Postman Collection .

⚠️ The postman application is external to Maya. Changes, updates, or issues outside of the provided Postman Collection or done by the developer, is out of scope of Sandbox support.


How to Setup the Postman Collection

Setting up the downloaded Postman application and the Maya Bills Pay Direct Postman collection.

Click here to view full details
  1. Download Postman from the link provided above and install it.
  2. Download the Maya Bills Pay Direct Biller Postman Collection package.
  3. Create a new workspace by clicking Workspaces + Create Workspace.
  1. In the workspace, click Import and on the File tab, click on Choose Files.
  1. Select the downloaded Maya Bills Pay Direct Biller.postman_collection.json file and click Import.
  1. When successful, the collection should be added as shown below.

How to Configure Your Variables

Once you have installed Postman and imported the Maya Bills Pay Direct Postman Collection, the next step is to configure the variables within the Postman Collection, to include provisioned biller information; such as the biller internal ID, the Biller secret key, and your biller endpoint, among others.

Click here to view full details
  1. In the Maya Bills Pay Direct Biller collection, click on the Variables tab.
  1. Update the below variables in the CURRENT VALUE column. Click on the SAVE button once values have been updated to apply the changes made.
VariableDescriptionRemarks
BILLER_SECRET_KEYThis is your API secret keyInput here the currently configured secret key from your service.

During the local development mock testing stage, you may use a dummy secret key. A Sandbox key will be provided during Integration Testing with Maya Bills Pay.
BILLER_ENDPOINTThis is your API-based endpoint.If your full URL /v1/validate is https://billspay.company.com/path/v1/validate, then the value for BILLER_ENDPOINT should be https://billspay.company.com/path

The local development mock Postman testing tool can be used to test local deployments as well, i.e: http://localhost:8080
BILLER_SLUGThis is your biller's internal ID.Biller slug assigned to biller partner would be provided during Integration Testing with Maya Bills Pay.

For this stage, a dummy BILLER_SLUG could be used. We would suggest making your services’ BILLER_SLUG configurable to easily switch once the actual BILLER_SLUG has been designated.
BILLER_CALLBACK_URLThis is Maya’s callback endpoint.No need to update for now.
BILLER_CALLBACK_METHOD_URLThis is Maya’s callback HTTP method.No need to update for now.
AUTHORIZATION_HEADERThis would be the value for the Authorization header for your Callback request to Maya.Refer to Biller API Signature and Authorization for the computation of the authorization header.

The Sandbox key will be provided during Sandbox Integration Testing with Maya Bills Pay.

You can use a dummy secret key and/or Authorization header during the local development mock testing of your service. Note that if you use a dummy Authorization header value, also update the Initial value column for this variable.
MOCK_CALLBACK_URLThis is a mock callback endpoint created using Postman mock.No need to update.
rrnRequest Reference Number to be used on callback requests in local development mock Postman collection.No need to update.

Start your Testing

At this point, you should have the following:

  1. Have downloaded the Postman and the Maya Bills Pay Direct Postman Collection ; and have setup the variables.
  2. You have a developed endpoints for your services, and understood the in-app customer journey and API sequence of Maya's Bills payment.
  3. Reviewed and understood the Biller API guides.

⚠️ Make sure test results have passed the minimum requirements for each Biller API. In cases of errors that require troubleshooting, refer to Bills Payment Troubleshooting Guide.

Validate Endpoint Testing

This is the stage wherein the biller's Validate endpoint receives the transaction request to validate the correctness of the bill payment transaction details.

Click here to view full details
  1. For each validate request included in the Postman collection, you need to update the following fields from the JSON body (this should depend on the scenario to test):
Request FieldRequiredRemarks
biller.accountNumberYesUpdate the value depending on the test scenario to accomplish. Input a valid account number for your successful scenario. Use an invalid account number to test for an invalid account number scenario.
biller.fieldsNoUpdate the key-value pairs accordingly if you are expecting other fields. NOTE: If you are not expecting any custom fields, leave the fields as a blank node {}.
transaction.amount.valueYesUpdate the value to any acceptable value by your service. For Declined scenarios involving amount validation, update as necessary.
  1. Click on the SAVE button once values have been updated to apply the changes made.
  2. Click on the Send button to execute the request.
  3. Check the bottom part of the Postman window for the response body from your service. Corresponding tests have been provided as well per request to verify if your API’s response complies with Maya’s Biller API requirements.
Validate Response Body

Validate Response Body

Validate Test Results

Validate Test Results

Validate Scenarios

Click here to view full details
ScenarioDescription
Successful Validate EndpointHappy path testing for validate endpoint.

Input valid account number in biller.accountNumber

If applicable, input valid/acceptable values under biller.fields and transaction.amount.value to test all valid scenarios for your API.
Declined Validate Endpoint - Invalid Account NumberRequest to test your invalid account number scenario.

Input an expected invalid account number in biller.accountNumber.
Declined Validate Endpoint - Other Validation ErrorsRequest to test any other validation error scenarios.

By default, the Postman collection has a negative value for transaction.amount.value as this is an expected validation error for the amount field.

If your API has an expected validation logic, update the appropriate fields as necessary.

Examples:
1. You have a minimum amount of validation for your API of Php 500. Input a value less than 500 under transaction.amount.value to test your validation logic.

2. You have to match on your end that an account number inputted belongs to a person with First Name: Juan and Last Name: Dela Cruz. Update the values under biller.fields to test your validation logic for this.

NOTE: For such validation logic that your API might have, we suggest returning a descriptive error message under result.message in your validation response. This exact message would be directly displayed in the Maya App and read by the customer trying to pay for the bill.

Examples:

1. Amount should be greater than 500.
2. Account Number does not match the user on record.
Declined Validate Endpoint - Invalid Paymaya SignatureRequest to test if your API has computed the paymaya-signature header correctly.

Post Endpoint Testing

Partner’s Biller Post Endpoint to receive a Post Bill Request which includes the bill details, amount, fee, and callback URL.

Click here to view full details
  1. For both post requests included in the Postman collection, you need to update the following fields from the JSON body:
Request FieldRequiredRemarks
biller.accountNumberYesUpdate the value depending on the test scenario to accomplish. Input a valid account number for your successful scenario. Use an invalid account number to test for invalid account number scenario.
biller.fieldsNoUpdate the key-value pairs accordingly if you are expecting other fields. NOTE: If you are not expecting any custom fields, leave the fields as a blank node {}.
transaction.amount.valueYesUpdate the value to any acceptable value by your service.

This should be the total amount of the bill payment transaction.

i.e: base amount + fee amount
transaction.amount.base.valueYesThis should be the base amount of the bill payment transaction and should exclude fees.
transaction.amount.fee.valueYesThis should be the fee amount of the bill payment transaction.

The fee amount is the amount the customer needs to pay on top of the bill amount to be paid.
  1. Click on the SAVE button once values have been updated to apply the changes made.
  2. Click on the Send button to execute the request.
  3. Check the bottom part of the Postman window for the response body from your service. Corresponding tests have been provided as well per request to verify if your API’s response complies with Maya’s Biller API requirements.
Post Response Body

Post Response Body

Post Test Result

Post Test Result

Post Scenarios

Click here to view full details
ScenarioDescription
Successful Post EndpointHappy path testing for post endpoint.

Input valid account number in biller.accountNumber

If applicable, input valid/acceptable values under biller.fields and transaction.amount.total.value / transaction.amount.base.value / transaction.amount.fee.value to test all valid scenarios for your API.

For this leg, your service should persist the request on your end as these are for posting already. We recommend persisting the callback URL included in the request as well as this is the endpoint to hit to inform Maya if the bill payment has been successfully posted.
Declined Post Endpoint - Invalid Paymaya SignatureRequest to test if your API has computed the paymaya-signature header correctly.

Callback Testing

The callback tests provided in the Local Development Mock Testing Postman collection could serve as a guide on how the direct biller partner integration would hit Maya’s Callback API. Included per request is the expected response by Maya's callback service per scenario.

⚠️ The Postman requests are using Postman Mock endpoints only. Thus, calls made to the provided callback endpoints do not reach Maya’s end. Again, it will only serve as a guide for Biller partners on the correct way in calling the callback API.

Callback Scenarios

Click here to view full details
ScenarioDescription
Successful CallbackHappy path testing for callback endpoint assuming biller would be notifying Maya that the bills payment made has already been posted on their end.

For successful posting callback, result.code should be 0000.
Successful Callback - Failed PostingHappy path testing for callback endpoint assuming biller would be notifying Maya that the bills payment made has failed posting on their end.

For failed posting callback, result.code should NOT be 0000.
Declined Callback - Missing RRN HeaderPostman request to simulate a callback request wherein the request lacks the Request-Reference-No header and value
Declined Callback - Missing Authorization HeaderPostman request to simulate a callback request wherein the request lacks the Authorization header and value.

Also please take note on how to correctly compute for the value to input for the Authorization header: Basic <Base64 encoded Secret Key>
Declined Callback - Bill Payment ID not matchingPostman request to simulate a callback request wherein the request has mismatched values for the id field.

Note that the id in the request body and the id in the URL parameter should be the same.
Declined Callback - Bill Payment ID is Invalid/MissingPostman request to simulate a callback request wherein the request body did not include id.
Declined Callback - Receipt Number is Invalid/MissingPostman request to simulate a callback request wherein the request body did not include transaction.receiptNumber.
Declined Callback - Account Number is Invalid/MissingPostman request to simulate a callback request wherein the request body did not include biller.accountNumber.

Execute and Submit Locally Developed Mock Tests

Once you are done with the development of the necessary services and running the individual tests from the locally developed mock testing Postman, you will need to do a final Postman run for the collection and submit it to Maya for further API compliance checking.

⚠️ Make sure test results have passed the minimum requirements for each Biller API. In cases of errors that require troubleshooting, refer to Bills Payment Troubleshooting Guide.

Click here to view full details

⚠️IMPORTANT

Before proceeding with test execution, clear your Postman Console logs first. This is to ensure that the logs to submit would only be for the corresponding test run only.

To clear console logs:

  1. From the bottom part of your Postman window, click on the Console button. The console tab should appear.
  2. From the upper-right corner of the Console tab, click on the Clear button.
  3. All previous Console logs should be cleared. You may now close the Console tab again by clicking on the X button at the upper-right corner of the tab.
  1. From Postman, click on the collection and click on the Run button on the right side of the page. The Runner tab should be displayed.
  1. From the Runner tab, check that all included tests are ticked. Tick on the Persist responses for a session option. Click on the Run Maya Bills Pay Direct Biller button. All tests included in the collection should run.
  1. Once the Runner is done executing the requests, take a screenshot of the Run summary page to be attached and submitted later. Also, tap on the Export Results button at the right side of the window. Rename the file with the format: <YYYY.MMDD_BILLERNAME> and save.
  1. Open your Console logs and copy the entire console logs by clicking on the Copy button. Paste on your preferred Notepad application and save it as a text file with the filename format: <YYYY.MMDD_BILLERNAME_LOGS>.
  1. Submit the Export Results and Console Logs files to Maya for checking.

Send the results via email with the following information

  1. Email the files to your designated Maya Relationship Manager and cc [email protected] .
  2. With Email Subject: (Merchant Biller Name) - Local Development Testing Results.
  3. Attach the screenshot of the test run results in the e-mail body.
  4. Attach the Export Results and Console Log Files.

ℹ️ Feedback Lead time is 3-5 Business days. Coordinate with your designated Maya Relationship Manager for updates.


Proceed to Sandbox Integration

ℹ️ Go to Maya Biller API Quick Start Guide to learn more about the integration requirements.

Click here to view full details

Once you are done with the Create and Develop stage of the Biller API integration, the next step would be Maya's onboarding in the Sandbox environment.

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 folowing:

  1. Done with the Sandbox Integration setup.
  2. Local Development Mock Testing.
  3. You have been notified by your designated Maya Relationship Manager, that you have been onboarded in the Sandbox environment.