#BillPay APIs — Mock environment

BillPay Sandbox API supports both Mock and UAT environments.

UAT in BillPay’s context, refers to the entire API lifecycle where Setu connects to both Axis and NPCI’s UAT Servers.

On the other hand, Mock is a simulated environment where Setu handles everything and is independent of both NPCI and Axis. Multiple mock APIs are defined so that you can integrate predictably.

You can change the environment from UAT to Mock by changing the endpoint as below

UAT - https://sandbox.cou.setu.co/api/bills/uat/biller-categories
MOCK - https://sandbox.cou.setu.co/api/bills/mock/biller-categories

The mock environment has been set up to mimic the actual process, so you’ll often see there’s a delay of about 30 secs until the bill is populated (until that time you’ll be shown ERR000). Also we have simulated cases where you’d see billers being down or giving timeout related errors.

#List of APIs

Get all biller categories

Use the Get categories API to get a list of all categories on BBPS.

Method - GET
Endpoint - https://sandbox.cou.setu.co/api/bills/mock/biller-categories
Request Body - None

In production, presently there are 23 categories in total. The following categories are supported in the mock environment—

Get biller list for a category

Use the Get biller list API to get all billers for a particular category by providing the category code.

Method - GET
Method - POST
Endpoint - https://sandbox.cou.setu.co/api/bills/mock/biller-list
Request Body -
    {
        "categoryCode":"1"
    }

You can also pass following parameters to the API—

Get biller details

Use the Get biller details API to—

• get the inputs required by the biller to fetch a bill
• get details on biller’s availability for payment
• to get the list of validations used by biller to qualify a payment attempt
• and more...

Method - POST
Endpoint - https://sandbox.cou.setu.co/api/bills/mock/biller-details
Request Body -
    {
        "billerId": "MAHI00000NATIC",
        "categoryCode": "12"
    }

You can use the following combinations in the mock environment—

Get biller fields

Use the Get biller fields API to list all input fields needed by a biller to do a bill fetch from biller system. The response to this API is a subset of the Get biller details API.

Method - POST
Endpoint - https://sandbox.cou.setu.co/api/bills/mock/biller-fields
Request Body -
    {
        "billerId": "MAHI00000NATIC",
        "categoryCode": "12"
    }

You can use the following combinations in the mock environment—

Bill fetch and payment

Use the Register for bill fetch API to pass on details that you have collected from your customer. These are the details required to do a bill fetch from the biller’s system.

Method - POST
Method - POST
Endpoint - https://sandbox.cou.setu.co/api/bills/mock/bill-fetch-request
Request Body -
    {
        "agent": {
            ** Please Find Values Below In Agent Ids Section **
        },
        "mobileNumber": "9192990013",
        "billerId": "Example Biller Id from below examples",
        "categoryCode": "Example Category Code from below examples",
        "customerParams": [
            {
                "name": "Example Name from below examples",
                "value": "Example Value from below examples"
            }
        ]
    }

Follow these steps—

1. Call the Register for bill fetch API with sample data given under each error scenario described below
2. Use the context you get in the response from the Register for bill fetch API response for the next API called described in below errors. Verify that you get the expected error and repeat above steps with data provided under other error scenarions.

Error scenario 1 — Biller down

The below data, when used in the Register for bill fetch API will always give biller down error (BFR008) when you call the Get fetched bill API.

"billerId": "AVVNL0000RAJ01",
    "categoryCode": "1",
    "customerParams": [
        {
            "name": "K Number",
            "value": "100"
        }
    ]

Error scenario 2 — BOU Timeout

The below data, when used in Register for bill fetch API will always give BOU timeout error when you call the Get fetched bill API.

"billerId": "APDCL0000ASM01",
    "categoryCode": "1",
    "customerParams": [
        {
            "name": "Consumer ID",
            "value": "100"
        }
    ]

Error scenario 3 — Backside connection error

The below data, when used in the Register for bill fetch API will always give backside connection error when you call the Get fetched bill API.

"billerId": "SBPDCL000BHI01",
    "categoryCode": "1",
    "customerParams": [
        {
            "name": "CA Number",
            "value": "10085"
        }
    ]

Error scenario 4 — Non JSON error

The below data, when used in the Register for bill fetch API will always give non JSON error when you call the Get fetched bill API

"billerId": "SKPR00000SIK01",
    "categoryCode": "1",
    "customerParams": [
        {
            "name": "Contract Acc Number",
            "value": "10085"
        }
    ]

Error scenario 5 — Too many requests error

The below data, when used in the Register for bill fetch API will always give too many requests error when you call the Get fetched bill API.

"billerId": "WESCO0000ODI01",
    "categoryCode": "1",
    "customerParams": [
        {
            "name": "Consumer Number",
            "value": "10085"
        }
    ]

Error scenario 6 — Technical error

The below data, when used in the Register for bill fetch API will always give technical error when you call the Get fetched bill API.

"billerId": "BSESRAJPLDEL01",
    "categoryCode": "1",
    "customerParams": [
        {
            "name": "CA Number",
            "value": "10085"
        }
    ]

Error scenario 7 — Mandatory tag(s) not present

The below data, when used in the Register for bill fetch API will give Mandatory tag(s) not present error when you call the Get fetched bill API.

"billerId": "MAHI00000NATKR",
    "categoryCode": "12",
    "customerParams": [
        {
            "name": "Loan Account Number",
            "value": "3523122"
        }
    ]

Error scenario 8 — Client code regex validation failure

The below data, when used in the Register for bill fetch API will give client code regex validation failure error when you call the Get fetched bill API

"billerId": "MAHI00000NATKR",
    "categoryCode": "12",
    "customerParams": [
        {
            "name": "Loan Account Number",
            "value": "10001"
        },{
            "name": "Mobile or Vehicle Registration Number",
            "value": "2121"
        }
    ]

Error scenario 9 — Failed payment due to techincal decline

The below data, when used in the Register for bill fetch API will always give a technical decline when you call the Make payment API.

In the mock environment, the technical decline happens with a probablility of 80% and will work 20% of the time. This is helpful for you to build a retry logic.

"billerId": "MAHI00000NATIC",
    "categoryCode": "12",
    "customerParams": [
        {
            "name": "Loan Number",
            "value": "10805"
        }
    ]

Error scenario 10 — Failed payment due to business decline{" "}

The below data, when used in the Register for bill fetch API will give data.status, ie, payment status as Cancelled when you call the Get payment status API.

"billerId": "MAHI00000NATIC",
    "categoryCode": "12",
    "customerParams": [
        {
            "name": "Loan Number",
            "value": "10505"
        }
    ]