—
–
/

to search

Introducing Setu Changelog Check it out ↗

Reading time — 14 minutes

Edit this page ↗

#Quickstart—API integration

Below is a quick summary of the APIs you need to start integrating with for testing out the BBPS COU product.

The primary actions you will take as an agent of the BBPS system, is to let your customers fetch bills from any business listed on BBPS, and let them pay said business.

For this, the core fetch, pay and dispute APIs are asynchronous. Each API has a request endpoint and a response endpoint. The request endpoint registers the call and the response endpoint is used to retrieve the status of the registered call.

#Fetch bill

The Fetch bill API with endpoint /bbps/bills/fetch/request is used to get bill details for a customer. You need to pass the details of the customer and also the business they want to fetch their bill from.

For e.g., if your customer wants to pay their phone bill for Vodafone Postpaid, you will need to provide—

  • the customer's identifier (mobile number in this case)

  • the business's identifier (BBPS ID for Vodafone, in this case)

Optionally, you can also register the customer with this biller simultaneously to receive future bills as and when they are generated (See UPMS Integration Guide). If you include the mandate object in the request, a registration will be initiated for the customer with the biller.

Sample Request


{
  "customer": {
    "mobile": "9505987798",
    "customerParams": [
      {
        "name": "Parameter 1",
        "value": "Value 1"
      },
      {
        "name": "Parameter 2",
        "value": "Value 2"
      },
      {
        "name": "Parameter 3",
        "value": "Value 3"
      }
    ]
  },
  "agent": {
    "app": "SmartPay",
    "channel": "INT",
    "geocode": "19.0139,72.8254",
    "id": "AX01AI06512391457204",
    "ifsc": "ICIC0000152",
    "imei": "123456789012345",
    "ip": "124.170.23.24",
    "mac": "48-4D-7E-CB-DB-6F",
    "mobile": "9481773011",
    "os": "iOS",
    "postalCode": "600001",
    "terminalId": "6000011234"
  },
  "biller": {
    "id": "VODA00000MUM03"
  },
  // optional - include to register customer with biller using UPMS
  "mandate": {
    "registrationType": "VIEW_N_PAY",
    "billPeriod": "ASPRESENTED"
  }
}

You get a refId in the response, a unique identifier that can be further used to check the status of the bill fetch. If a UPMS registration was requested, the response will also include upmsRegistration.refId and upmsRegistration.status.

Sample Response


{
    "data": {
        "refId": "LNMSQQR4RKT7X1UGPY7JGUV454PL9T2C689",
        "upmsRegistration": {
            "status": "PENDING", 
            "refId": "HENSVVR4QOS7X1UGPY7JGUV444P10102202"
        }
    },
    "success": true,
    "traceId": "C3SFG0O6N88R6UI7EQ" 
}

You may also use the /bbps/bills/fetch/response endpoint with above refId to check status of the bill fetch—

Sample Request


{
    "refId": "LNMSQQR4RKT7X1UGPY7JGUV454PL9T2C689"
}

In the response you either get the bill details, or "Processing" status if the bill fetch is still in progress.

#Val Add (Value Added Services)

Some BBPS billers support value added services (Val Add) such as customer onboarding / OTP verification / markup & best-price discovery flows. COU exposes these flows as asynchronous APIs (request + response) — with webhooks as the primary mechanism and polling as fallback.

requestType is one of:

  • GetCustomerId
  • GenerateOTP
  • ValidateOTP
  • GetBankMarkup
  • FetchBestPrice
Sample Request — GetCustomerId


{
  "agent": {
    "id": "AX01AX26INBU00000001",
    "channel": "INTB",
    "ip": "124.170.23.24",
    "mac": "48-4D-7E-CB-DB-6F"
  },
  "biller": {
    "id": "FXRE00000KER3U"
  },
  "inputParams": [
    {
      "name": "mobileNumber",
      "value": "9812000000"
    }
  ]
}

Sample Request — GenerateOTP


{
  "agent": {
    "id": "AX01AX26INBU00000001",
    "channel": "INTB",
    "ip": "124.170.23.24",
    "mac": "48-4D-7E-CB-DB-6F"
  },
  "biller": {
    "id": "FXRE00000KER3U"
  },
  "inputParams": [
    { "name": "mobileNumber", "value": "8838151414" },
    { "name": "emailId", "value": "jayasurya.s_tra@npci.org.in" },
    { "name": "bankId", "value": "10128" },
    { "name": "bankName", "value": "INDIA POST PAYMENTS BANK LIMITED" },
    { "name": "bankAccountNumber", "value": "150002000" },
    { "name": "customerAccountType", "value": "Savings" },
    { "name": "ifsc", "value": "ZSBL0000341" },
    { "name": "accountHolderName", "value": "jayasurya" },
    { "name": "customerType", "value": "ResidentIndividual" },
    { "name": "pan", "value": "JS00024252" },
    { "name": "panValidated", "value": "true" }
  ]
}

Sample Request — ValidateOTP


{
  "agent": {
    "id": "AX01AX26INBU00000001",
    "channel": "INTB",
    "ip": "124.170.23.24",
    "mac": "48-4D-7E-CB-DB-6F"
  },
  "biller": {
    "id": "FXRE00000KER3U"
  },
  "inputParams": [
    { "name": "mobileNumber", "value": "9182583612" },
    { "name": "emailId", "value": "pragna.n@npci.org.in" },
    { "name": "mobileOTP", "value": "870398" },
    { "name": "emailOTP", "value": "806963" },
    { "name": "bankId", "value": "10128" },
    { "name": "bankName", "value": "INDIA POST PAYMENTS BANK LIMITED" },
    { "name": "bankAccountNumber", "value": "150002000" },
    { "name": "customerAccountType", "value": "Savings" },
    { "name": "ifsc", "value": "ZSBL0000341" },
    { "name": "accountHolderName", "value": "Pragna" },
    { "name": "customerType", "value": "ResidentIndividual" },
    { "name": "pan", "value": "NP00024253" },
    { "name": "panValidated", "value": "true" },
    { "name": "tcFlag", "value": "true" }
  ]
}

Sample Request — GetBankMarkup


{
  "agent": {
    "id": "AX01AX26INBU00000001",
    "channel": "INTB",
    "ip": "124.170.23.24",
    "mac": "48-4D-7E-CB-DB-6F"
  },
  "biller": {
    "id": "FXRE00000KER3U"
  },
  "inputParams": [
    { "name": "mobileNumber", "value": "7075465595" },
    { "name": "customerId", "value": "IN0025000217" },
    { "name": "pan", "value": "NB00024252" }
  ]
}

Sample Request — FetchBestPrice


{
  "agent": {
    "id": "AX01AX26INBU00000001",
    "channel": "INTB",
    "ip": "124.170.23.24",
    "mac": "48-4D-7E-CB-DB-6F"
  },
  "biller": {
    "id": "RBFX00000KARDG"
  },
  "inputParams": [
    { "name": "bankBranch", "value": "SHIVAJI NAGAR" },
    { "name": "bankId", "value": "10128" },
    { "name": "currency", "value": "USD" },
    { "name": "customerId", "value": "IN0025000213" },
    { "name": "deliveryMode", "value": "Currency" },
    { "name": "ifsc", "value": "ZSBL0000341" },
    { "name": "instrumentType", "value": "CASH" },
    { "name": "markup", "value": "0.5" },
    { "name": "mobileNumber", "value": "8838151414" },
    { "name": "orderQuantity", "value": "1000" },
    { "name": "pan", "value": "JS00024252" },
    { "name": "relationshipBank", "value": "INDIA POST PAYMENTS BANK LIMITED" },
    { "name": "tcFlag", "value": "true" },
    { "name": "transactionType", "value": "PURCHASE" },
    { "name": "units", "value": "fixed" }
  ]
}

The response will acknowledge the request and provide a refId. You’ll receive the final outcome via webhook; alternatively, you can poll using /bbps/valadd/{requestType}/response.

Sample Response


{
  "status": "Processing",
  "data": {
    "refId": "HENSVVR4QOS7X1UGPY7JGUV444P10102202"
  },
  "traceId": "CV4PE82LTNJE9O014OE1"
}

Sample Response — GetCustomerId (Success)


{
  "status": "Success",
  "refId": "HENSVVR4QOS7X1UGPY7JGUV444P10102202",
  "traceId": "CV4PE82LTNJE9O014OE0",
  "data": {
    "billerResponse": [
      { "name": "customerId", "value": "IN0025000213" },
      { "name": "customerType", "value": "RESIDENTINDIVIDUAL" }
    ]
  }
}

Sample Response — GenerateOTP (Success)


{
  "status": "Success",
  "refId": "OTPGENREF1234567890ABCDEFGHIJKLMNOPQ",
  "traceId": "CV4PE82LTNJE9O014OTP",
  "data": {
    "billerResponse": [
      { "name": "mobileNumber", "value": "9812000000" },
      { "name": "emailId", "value": "jane.doe@gmail.com" },
      { "name": "bankId", "value": "10128" },
      { "name": "bankName", "value": "INDIA POST PAYMENTS BANK LIMITED" },
      { "name": "bankAccountNumber", "value": "150002000" },
      { "name": "customerAccountType", "value": "Savings" },
      { "name": "ifsc", "value": "ICIC0006720" },
      { "name": "accountHolderName", "value": "jayasurya" },
      { "name": "customerType", "value": "Individual" },
      { "name": "pan", "value": "BPEPS55XXX" },
      { "name": "panValidated", "value": "true" },
      { "name": "authenticationMethod", "value": "OTP" }
    ]
  }
}

Sample Response — ValidateOTP (Success)


{
  "status": "Success",
  "refId": "OTPVALREF1234567890RSTUVWXYZABCDEFG",
  "traceId": "CV4PE82LTNJE9O01VAL",
  "data": {
    "billerResponse": [
      { "name": "customerId", "value": "IN0025000219" },
      { "name": "customerType", "value": "RESIDENTINDIVIDUAL" }
    ]
  }
}

Sample Response — GetBankMarkup (Success)


{
  "status": "Success",
  "refId": "MARKUPREF1234567890HIJKLMNOPQRSTUV",
  "traceId": "CV4PE82LTNJE9O0MARK",
  "data": {
    "billerResponse": [
      {
        "name": "relationshipBank",
        "value": "INDIA POST PAYMENTS BANK LIMITED",
        "billerSpecificInfo": {
          "billerId": "BBPSRELATIONSHIPBANK1",
          "rate": "0.5",
          "units": "fixed",
          "indicativePrice": "8500",
          "bankId": "10128",
          "homeBranchIFSC": "ZSBL0000341"
        }
      }
    ],
    "additionalInfo": [
      { "name": "accountHolderName", "value": "Pragna" },
      { "name": "tcFlag", "value": "true" }
    ]
  }
}

Sample Response — FetchBestPrice (Success)


{
  "status": "Success",
  "refId": "BESTPRCREF123456789WXYZABCDEFGHIJKL",
  "traceId": "CV4PE82LTNJE9O0BEST",
  "data": {
    "billerResponse": [
      { "name": "currency", "value": "USD" },
      { "name": "dateOfDelivery", "value": "2025-05-22" },
      { "name": "orderQuantity", "value": "1000" },
      { "name": "bestPrice", "value": "8505.5" },
      { "name": "markup", "value": "0.5" },
      { "name": "units", "value": "fixed" },
      { "name": "totalPayableAmount", "value": "8506000" }
    ]
  }
}

Sample Response — Failure (Generic)


{
  "status": "Failure",
  "refId": "HENSVVR4QOS7X1UGPY7JGUV444P10102202",
  "traceId": "CV4PE82LTNJE9O014OE0",
  "data": {
    "errors": [
      { "code": "error-code", "message": "Error message" }
    ]
  }
}

#FX Mandate booking

For the FX transaction flow, COU exposes APIs to book an FX mandate and to poll the booking status (fallback for webhooks).

Sample Request — Book FX mandate


{
  "agent": {
    "id": "AX01AX26INBU00000001",
    "channel": "INTB",
    "ip": "124.170.23.24",
    "mac": "48-4D-7E-CB-DB-6F"
  },
  "biller": {
    "id": "HD5140000NAT02"
  },
  "customer": {
    "customerParams": [
      { "name": "mobileNumber", "value": "8838151414" },
      { "name": "customerId", "value": "IN0025000213" },
      { "name": "currency", "value": "USD" },
      { "name": "instrumentType", "value": "CASH" },
      { "name": "markup", "value": "0.5" },
      { "name": "bestPrice", "value": "8505.5" }
    ]
  },
  "mandate": {
    "mode": "UPI",
    "amount": 8260000,
    "mandateRefId": "d30eb5d76250a2faa76c5a2a59c76cc3"
  }
}

Similar to other async COU APIs, you get a refId in the response, and can poll status using /bbps/bills/mandate/response if needed.

Possible Mandate error codes (FX Retail)
Error CodeDescription
MOB001Mobile number should not be empty
MOB002Invalid mobile number
MOB004Mobile number does not exist for the customer
CUS002Customer status is not active. Current status is <status> (e.g., suspend, terminate)
CUS003Customer Id should not be empty
CUS004Invalid Customer Id
CUS005No active bank relationship for the customer
CST002Customer type should be RESIDENTINDIVIDUAL/SOLEPROPRIETORSHIP
CUR001Currency should not be empty
CUR002Invalid currency
TXN001Transaction Type should not be empty
TXN002Invalid transaction type
INT001Instrument Type should not be empty
INT002Invalid instrument type
BNK001Bank Name should not be empty
BNK002Invalid Bank Name
BNK003Bank does not exist
BNK004Bank status is not active. Current status is <status> (e.g., suspend, terminate)
MRK001Markup should not be empty
MRK002Invalid Markup
DLM001Delivery mode should not be empty
DLM002Delivery mode should only be Currency, Forex Card Load, Remittance
ORQ001Order Quantity should not be empty
ORQ002Order Quantity should be a positive value
ORQ003Order Quantity should be greater than zero
ORQ004Order Quantity should not be less than Minimum Order Quantity
ORQ005Order Quantity should contain only 2 decimals
ORQ006Maximum Order Quantity is breached. Allowed maximum value is <maximum value defined in system>
BRH001Bank Branch should not be empty
BRH002Invalid Bank Branch
BNK005Bank id should not be empty
AMT001Amount should not be empty
AMT002Invalid Amount
TXN003Txn Reference Id should not be empty
TXN004Invalid Txn Reference Id
TXN005Txn Reference Id should be unique
MRI001Mandate Ref Id should not be empty
MRI002Invalid Mandate Ref Id
CTS001Customer Transaction services are closed for today. Please try again tomorrow during business hours.
CUS007Customer does not exist
MAN001User level limit price hard check failure
internal-errorInternal Server Error

#Pay bill

The Pay bill API is used to send details of a payment done by a user on your app/website to Setu. Setu uses this information to confirm a payment with the biller.

FX Retail (Val Add + Mandate flows): When the payment is being initiated as part of the FX mandate journey, include paymentType: "MANDATE_AND_PAY" in the request body of the Pay bill API. The rest of the Pay bill payload remains the same.

#Raise dispute

The Raise Dispute API is used to Raise a compliant for a payment done by a user on your app/website to Setu. Setu uses this information and raises a compliant on the BBPS Platform.

#List data in bulk

For your convenience, Setu also provides actions to list data in bulk, that can come in handy for keeping your systems up to date with the latest data. The following APIs are available—

  • List categories—lists all categories on BBPS.
  • List billers—lists all billers on BBPS.
    FX Retail fields (present on every biller):
    • valAddFlag (boolean) — indicates if value-added services are enabled for the biller.
    • valAddCustParams (ValAddCustParamSpec[]) — customer parameters required for value-added service flows. Each entry includes requestType (e.g. MANDATE_AND_PAY for FX Retail mandate+pay) and the corresponding customerParams specs.
    • mandateRequirement (string) — mandate requirement for the biller (e.g. MANDATORY). For FX Retail billers, use this to decide whether mandate+pay flow is required.
    • pseudoBiller (boolean) — indicates if the biller is a pseudo biller.
  • List plans—lists all plans for billers on BBPS.
  • List disputes—lists all the raised disputes using the Dispute API.

#Managing Customer Registrations via UPMS

These APIs allow you to manage the lifecycle of UPMS (Unified Presentment Management Service) registrations for your customers. Refer to the UPMS Integration Guide for detailed flows and callback handling.

#Viewing Registration Details

To retrieve the current status and details of a specific, existing UPMS registration.

API Reference: GET /api/v2/upms/registrations/{upmsRegistrationRefID}

Sample Success Response


{
    "data": {
        "biller": {
        "id": "ABLP01000ANP03"
        },
        "createdAt": "2025-04-24T14:38:46.377Z",
        "customer": {
        "customerParams": [
            {
            "name": "Roll No",
            "value": "27257063"
            }
        ],
        "mobile": "9039403265",
        "name": "Priya Shukla"
        },
        "mandate": {
        "billPeriod": "ASPRESENTED",
        "billerParams": [
            {
            "name": "Low Balance Threshold",
            "value": "500"
            }
        ],
        "debitInfo": {
            "amount": 999999999,
            "currency": 356, 
            "debitDate": "10-Feb",
            "paymentMode": "Internet Banking",
            "type": "FIXED_AMOUNT"
        },
        "registrationType": "AUTO_PAY",
        "toDate": "2025-12-22"
        },
        "refId": "D054PTM52FL7R8CJPQ90GZ2ORTG51142008",
        "status": "SUCCESS",
        "updatedAt": "2025-04-24T14:38:47.389Z" 
    },
    "success": true,
    "traceId": "D055CNT3GMB863CND9LG"
}

#Updating a Registration

To modify specific details of an existing, active UPMS registration. This is an asynchronous operation; the final result is delivered via the Update UPMS Registration webhook.

API Reference: PATCH /api/v2/upms/registrations/{upmsRegistrationRefID}

Sample Request Body


{
    "mandate": {
        "toDate": "2025-12-31",
        "debitInfo": {
            "amount": 750000 
        }
    }
}

Sample Success Response


{
    "success": true,
    "traceId": "CV4PE82LTNJE9O014OE0"
}

#Cancelling a Registration

To permanently cancel an existing UPMS registration. This is an asynchronous operation; confirmation comes via the Cancel UPMS Registration webhook.

API Reference: DELETE /api/v2/upms/registrations/{upmsRegistrationRefID}

Sample Success Response


{
    "success": true,
    "traceId": "CV4PE82LTNJE9O014OE0"
}

#Check server health

The health check API tells you the health of the Setu BillPay server.

Aside from the above, there are other APIs which are also vital for a complete customer payment experience. See the full API reference for more details.

Was this page helpful?