BBPS COU Payment Scenarios

This page covers every supported payment scenario for BBPS COU integrations. Each scenario shows the exact bbps block to use in the Create Order API and the key fields to include in the Bill Payment Request API. All examples use sandbox test values.

Bill Payment request examples below show only the fields that vary by scenario. Always include all required fields as described in the Bill Payment Request API.

Key terms

The following terms are used throughout this page.

Term	Meaning
`amount_to_be_paid`	The amount being paid against one bill. Allowed values depend on the biller’s `payment_amount_exactness` (see the next section). In the Bill Payment Request, pass this as `amount.amt.amount`.
Shortfall	The portion of `amount_to_be_paid` not collected from the customer, for example a discount, coin burn, or cashback that the Agent Institution absorbs. Cashfree funds the shortfall against the Agent Institution’s shortfall wallet. Applicable only for postfunding Agent Institutions.
Split	A portion of the PG order amount settled to a vendor account instead of going through the BBPS settlement flow, for example a convenience fee the Agent Institution charges on top of the bill.
`order_amount`	The amount the customer pays at the PG. For prefunding Agent Institutions, this is the Agent Institution’s choice. For postfunding Agent Institutions, it must equal `Σ(amount_to_be_paid − shortfall_amount + vendor_splits amounts)` across all bills.

Amount to be paid by biller type

Before setting amount_to_be_paid, check the biller’s payment_amount_exactness field from the Fetch Biller MDM Details API. The examples below assume a bill of ₹1,000.

`payment_amount_exactness`	Allowed `amount_to_be_paid`	Example
`Exact`	Exactly the bill amount	1000
`Exact and below`	Up to the bill amount (partial payment allowed)	500
`Exact and above`	The bill amount or more, for example to include overdue charges	1050
`RANGE`	Any value between the bill’s `min_amount` and `max_amount` from the fetch response	Any value in range

Funding models

The two funding models determine how money flows from the customer to the biller and how your integration differs.

	Prefunding	Postfunding
Who funds the biller	The Agent Institution’s prefunded wallet, debited at Bill Payment	PG settlement to BBPS escrow, plus Cashfree for any shortfall against the Agent Institution’s shortfall wallet
Where the PG amount settles	Cashfree’s current account	BBPS escrow (splits go to the vendor account)
`bbps` block format	Top-level fields or `bills` array	`bills` array only
`shortfall_amount` and `payment_breakdown`	Not used	Required. Must match each other per bill.
`vendor_splits` and `order_splits`	Not supported	Supported. Σ `vendor_splits` amounts across all bills must equal the `order_splits` amount. Only `amount` is supported, not `percentage`.
`order_amount`	Agent Institution’s choice	`Σ(amount_to_be_paid − shortfall_amount + vendor_splits amounts)` across all bills
What Bill Payment debits	`amount_to_be_paid` from the prefunded wallet	The shortfall amount from the Agent Institution’s shortfall wallet

Settlement flows

Prefunding

Customer → Cashfree PG → Cashfree's current account (splits → vendor account)
Agent Institution prefunded wallet (debited by amount_to_be_paid) → BBPS escrow → NBBL → BOU → Biller

Postfunding

Customer → Cashfree PG → BBPS escrow (splits → vendor account)
Cashfree (shortfall, if any) → BBPS escrow → NBBL → BOU → Biller

Prefunding scenarios

For prefunding Agent Institutions, Cashfree debits amount_to_be_paid from your prefunded wallet at Bill Payment, regardless of the PG order amount. Because the PG amount settles to Cashfree’s current account, discounts and fees are handled on your side. Do not send shortfall_amount or payment_breakdown in the Bill Payment request. This section covers the following prefunding scenarios:

Standard payment
Discount or coin burn
Vendor split
Discount and vendor split
Skip the PG transaction

Standard payment with prefunding

Use this scenario when the customer pays the full bill with no discount and no split. Amounts: Bill ₹1,000 · amount_to_be_paid 1,000 · PG order 1,000 · Wallet debit 1,000. Create Order request

{
  "order_amount": 1000,
  "order_currency": "INR",
  "customer_details": {
    "customer_id": "7112AAA812234",
    "customer_phone": "9898989898"
  },
  "bbps": {
    "bill_fetch_ref_id": "b73a14a591874eb3a22296b2dd861511952",
    "biller_id": "SWAR00027NAT2J",
    "agent_id": "CH01CH02INB516193127"
  }
}

Bill Payment request: key fields

{
  "bill_payment_request": {
    "head": {
      "bill_fetch_ref_id": "b73a14a591874eb3a22296b2dd861511952",
      "pg_reference_id": "1461688981422088704"
    },
    "amount": {
      "amt": {
        "amount": "1000.00",
        "cust_conv_fee": "0",
        "cou_cust_conv_fee": "0",
        "currency": "INR"
      }
    }
  }
}

Discount or coin burn with prefunding

Use this scenario when you give the customer a ₹100 discount on a ₹1,000 bill. Your prefunded wallet absorbs the discount. You do not need shortfall fields because the PG collects less from the customer. Amounts: Bill ₹1,000 · amount_to_be_paid 1,000 · PG order 900 · Wallet debit 1,000. The ₹100 discount is covered by your prefunded wallet. Create Order request

{
  "order_amount": 900,
  "order_currency": "INR",
  "customer_details": {
    "customer_id": "7112AAA812234",
    "customer_phone": "9898989898"
  },
  "bbps": {
    "bill_fetch_ref_id": "b73a14a591874eb3a22296b2dd861511952",
    "biller_id": "SWAR00027NAT2J",
    "agent_id": "CH01CH02INB516193127"
  }
}

Bill Payment request: key fields

{
  "bill_payment_request": {
    "head": {
      "bill_fetch_ref_id": "b73a14a591874eb3a22296b2dd861511952",
      "pg_reference_id": "1461688981422088704"
    },
    "amount": {
      "amt": {
        "amount": "1000.00",
        "cust_conv_fee": "0",
        "cou_cust_conv_fee": "0",
        "currency": "INR"
      }
    }
  }
}

Vendor split with prefunding

Use this scenario when you charge a ₹50 convenience fee on top of the bill and want it settled to a separate vendor account. Amounts: Bill ₹1,000 · amount_to_be_paid 1,000 · Split 50 · PG order 1,050 · Wallet debit 1,000. Create Order request

{
  "order_amount": 1050,
  "order_currency": "INR",
  "customer_details": {
    "customer_id": "7112AAA812234",
    "customer_phone": "9898989898"
  },
  "order_splits": [
    {
      "vendor_id": "VENDOR_001",
      "amount": 50
    }
  ],
  "bbps": {
    "bills": [
      {
        "bill_fetch_ref_id": "b73a14a591874eb3a22296b2dd861511952",
        "biller_id": "SWAR00027NAT2J",
        "agent_id": "CH01CH02INB516193127",
        "amount_to_be_paid": 1000,
        "vendor_splits": [
          {
            "vendor_id": "VENDOR_001",
            "amount": 50
          }
        ]
      }
    ]
  }
}

Bill Payment request: key fields

{
  "bill_payment_request": {
    "head": {
      "bill_fetch_ref_id": "b73a14a591874eb3a22296b2dd861511952",
      "pg_reference_id": "1461688981422088704"
    },
    "amount": {
      "amt": {
        "amount": "1000.00",
        "cust_conv_fee": "0",
        "cou_cust_conv_fee": "0",
        "currency": "INR"
      }
    }
  }
}

Discount and vendor split with prefunding

Use this scenario when you apply a ₹100 discount and charge a ₹50 convenience fee on the same bill. Amounts: Bill ₹1,000 · Discount 100 · Split 50 · PG order 1,000 − 100 + 50 = 950 · Wallet debit 1,000. Create Order request

{
  "order_amount": 950,
  "order_currency": "INR",
  "customer_details": {
    "customer_id": "7112AAA812234",
    "customer_phone": "9898989898"
  },
  "order_splits": [
    {
      "vendor_id": "VENDOR_001",
      "amount": 50
    }
  ],
  "bbps": {
    "bills": [
      {
        "bill_fetch_ref_id": "b73a14a591874eb3a22296b2dd861511952",
        "biller_id": "SWAR00027NAT2J",
        "agent_id": "CH01CH02INB516193127",
        "amount_to_be_paid": 1000,
        "vendor_splits": [
          {
            "vendor_id": "VENDOR_001",
            "amount": 50
          }
        ]
      }
    ]
  }
}

Bill Payment request: key fields

{
  "bill_payment_request": {
    "head": {
      "bill_fetch_ref_id": "b73a14a591874eb3a22296b2dd861511952",
      "pg_reference_id": "1461688981422088704"
    },
    "amount": {
      "amt": {
        "amount": "1000.00",
        "cust_conv_fee": "0",
        "cou_cust_conv_fee": "0",
        "currency": "INR"
      }
    }
  }
}

Skip the PG transaction with prefunding

Use this scenario when you want to pay the entire bill from your prefunded wallet without collecting anything from the customer through the PG. Skip the Create Order step entirely. Set skip_pg_transaction: true and pass your PG account’s client ID in pg_app_id. Amounts: Bill ₹1,000 · amount_to_be_paid 1,000 · No PG transaction. Wallet debit 1,000.

When skip_pg_transaction is true, do not create a PG order. Pass pg_app_id instead of pg_reference_id. Cashfree creates a zero-value transaction on your PG account for NBBL compliance.

Bill Payment request: key fields

{
  "bill_payment_request": {
    "head": {
      "bill_fetch_ref_id": "b73a14a591874eb3a22296b2dd861511952",
      "pg_app_id": "<PG_APP_ID>",
      "skip_pg_transaction": true
    },
    "amount": {
      "amt": {
        "amount": "1000.00",
        "cust_conv_fee": "0",
        "cou_cust_conv_fee": "0",
        "currency": "INR"
      }
    }
  }
}

Postfunding scenarios

For postfunding Agent Institutions, the PG amount settles to BBPS escrow and Cashfree funds any shortfall against your shortfall wallet. Always use the bills array in the bbps block. Always send payment_breakdown.shortfall_amount in the Bill Payment request, matching shortfall_amount in the Create Order request.

order_amount must equal Σ(amount_to_be_paid − shortfall_amount + vendor_splits amounts) across all bills.

This section covers the following postfunding scenarios:

Standard payment
Shortfall
Skip the PG transaction
Vendor split
Shortfall and vendor split

Standard payment with postfunding

Use this scenario when the customer pays the full bill with no shortfall and no split. Amounts: Bill ₹1,000 (Exact) · amount_to_be_paid 1,000 · Shortfall 0 · PG order 1,000. Create Order request

{
  "order_amount": 1000,
  "order_currency": "INR",
  "customer_details": {
    "customer_id": "7112AAA812234",
    "customer_phone": "9898989898"
  },
  "bbps": {
    "bills": [
      {
        "bill_fetch_ref_id": "b73a14a591874eb3a22296b2dd861511952",
        "biller_id": "SWAR00027NAT2J",
        "agent_id": "CH01CH02INB516193127",
        "amount_to_be_paid": 1000,
        "shortfall_amount": 0
      }
    ]
  }
}

Bill Payment request: key fields

{
  "bill_payment_request": {
    "head": {
      "bill_fetch_ref_id": "b73a14a591874eb3a22296b2dd861511952",
      "pg_reference_id": "1461688981422088704"
    },
    "amount": {
      "amt": {
        "amount": "1000.00",
        "cust_conv_fee": "0",
        "cou_cust_conv_fee": "0",
        "currency": "INR"
      }
    },
    "payment_breakdown": {
      "shortfall_amount": "0.00"
    }
  }
}

Shortfall with postfunding

Use this scenario when you give the customer a ₹100 discount or coin burn and Cashfree funds it from your shortfall wallet. Amounts: Bill ₹1,000 · amount_to_be_paid 1,000 · Shortfall 100 · PG order 900. Your shortfall balance moves 100 more negative. Create Order request

{
  "order_amount": 900,
  "order_currency": "INR",
  "customer_details": {
    "customer_id": "7112AAA812234",
    "customer_phone": "9898989898"
  },
  "bbps": {
    "bills": [
      {
        "bill_fetch_ref_id": "b73a14a591874eb3a22296b2dd861511952",
        "biller_id": "SWAR00027NAT2J",
        "agent_id": "CH01CH02INB516193127",
        "amount_to_be_paid": 1000,
        "shortfall_amount": 100
      }
    ]
  }
}

Bill Payment request: key fields

{
  "bill_payment_request": {
    "head": {
      "bill_fetch_ref_id": "b73a14a591874eb3a22296b2dd861511952",
      "pg_reference_id": "1461688981422088704"
    },
    "amount": {
      "amt": {
        "amount": "1000.00",
        "cust_conv_fee": "0",
        "cou_cust_conv_fee": "0",
        "currency": "INR"
      }
    },
    "payment_breakdown": {
      "shortfall_amount": "100.00"
    }
  }
}

Skip the PG transaction with postfunding

Use this scenario when you want to pay the entire bill from the shortfall wallet without collecting anything from the customer through the PG. Skip the Create Order step entirely. Set skip_pg_transaction: true and pass your PG account’s client ID in pg_app_id. Amounts: Bill ₹1,000 · Shortfall 1,000 · No PG transaction.

When skip_pg_transaction is true, do not create a PG order. Pass pg_app_id instead of pg_reference_id. Cashfree creates a zero-value transaction on your PG account for NBBL compliance.

Bill Payment request: key fields

{
  "bill_payment_request": {
    "head": {
      "bill_fetch_ref_id": "b73a14a591874eb3a22296b2dd861511952",
      "pg_app_id": "<PG_APP_ID>",
      "skip_pg_transaction": true
    },
    "amount": {
      "amt": {
        "amount": "1000.00",
        "cust_conv_fee": "0",
        "cou_cust_conv_fee": "0",
        "currency": "INR"
      }
    },
    "payment_breakdown": {
      "shortfall_amount": "1000.00"
    }
  }
}

Vendor split with postfunding

Use this scenario when you charge a ₹50 convenience fee on top of the bill, want it settled to a vendor account, and have no shortfall. Amounts: Bill ₹1,000 · amount_to_be_paid 1,000 · Shortfall 0 · Split 50 · PG order 1,050 · Bill Payment 1,000. Create Order request

{
  "order_amount": 1050,
  "order_currency": "INR",
  "customer_details": {
    "customer_id": "7112AAA812234",
    "customer_phone": "9898989898"
  },
  "order_splits": [
    {
      "vendor_id": "VENDOR_001",
      "amount": 50
    }
  ],
  "bbps": {
    "bills": [
      {
        "bill_fetch_ref_id": "b73a14a591874eb3a22296b2dd861511952",
        "biller_id": "SWAR00027NAT2J",
        "agent_id": "CH01CH02INB516193127",
        "amount_to_be_paid": 1000,
        "shortfall_amount": 0,
        "vendor_splits": [
          {
            "vendor_id": "VENDOR_001",
            "amount": 50
          }
        ]
      }
    ]
  }
}

Bill Payment request: key fields

{
  "bill_payment_request": {
    "head": {
      "bill_fetch_ref_id": "b73a14a591874eb3a22296b2dd861511952",
      "pg_reference_id": "1461688981422088704"
    },
    "amount": {
      "amt": {
        "amount": "1000.00",
        "cust_conv_fee": "0",
        "cou_cust_conv_fee": "0",
        "currency": "INR"
      }
    },
    "payment_breakdown": {
      "shortfall_amount": "0.00"
    }
  }
}

Shortfall and vendor split with postfunding

Use this scenario when the customer makes a partial payment of a bill, and you apply both a discount and a convenience fee. Amounts: Bill ₹1,000 (Exact and below) · amount_to_be_paid 500 · Shortfall 100 · Split 50 · PG order 500 − 100 + 50 = 450 · Bill Payment 500 with shortfall 100. Create Order request

{
  "order_amount": 450,
  "order_currency": "INR",
  "customer_details": {
    "customer_id": "7112AAA812234",
    "customer_phone": "9898989898"
  },
  "order_splits": [
    {
      "vendor_id": "VENDOR_001",
      "amount": 50
    }
  ],
  "bbps": {
    "bills": [
      {
        "bill_fetch_ref_id": "b73a14a591874eb3a22296b2dd861511952",
        "biller_id": "SWAR00027NAT2J",
        "agent_id": "CH01CH02INB516193127",
        "amount_to_be_paid": 500,
        "shortfall_amount": 100,
        "vendor_splits": [
          {
            "vendor_id": "VENDOR_001",
            "amount": 50
          }
        ]
      }
    ]
  }
}

Bill Payment request: key fields

{
  "bill_payment_request": {
    "head": {
      "bill_fetch_ref_id": "b73a14a591874eb3a22296b2dd861511952",
      "pg_reference_id": "1461688981422088704"
    },
    "amount": {
      "amt": {
        "amount": "500.00",
        "cust_conv_fee": "0",
        "cou_cust_conv_fee": "0",
        "currency": "INR"
      }
    },
    "payment_breakdown": {
      "shortfall_amount": "100.00"
    }
  }
}

Pay Together for multiple bills

Pay Together lets the customer pay bills across multiple billers in a single PG transaction. Each bill has its own bill fetch and its own Bill Payment request, but all bills are paid under a single PG order. The flow is as follows:

Run a bill fetch for each bill separately and store each ref_id.
Create one PG order with one object per bill in the bills array. Each object has its own bill_fetch_ref_id, biller_id, agent_id, and amount_to_be_paid.
After the single PG payment succeeds, send one Bill Payment request per bill. Each request uses its own bill_fetch_ref_id and the same pg_reference_id from the PG payment.

Each bill in the bills array must have a unique biller_id. Passing more than one bill for the same biller in a single Create Order request results in a validation error.

This section covers Pay Together for both funding models:

Pay Together with postfunding
Pay Together with prefunding

Pay Together with postfunding

Amounts: Bill 1 (Loan, ₹1,000, Exact): amount_to_be_paid 1,000 · Shortfall 100 · Split 20 → net contribution 920. Bill 2 (Electricity, ₹500, Exact and above, paying ₹540 with overdue charges): amount_to_be_paid 540 · Shortfall 0 · No split → net contribution 540. PG order = 920 + 540 = 1,460. Create Order request

{
  "order_amount": 1460,
  "order_currency": "INR",
  "customer_details": {
    "customer_id": "7112AAA812234",
    "customer_phone": "9898989898"
  },
  "order_splits": [
    {
      "vendor_id": "VENDOR_001",
      "amount": 20
    }
  ],
  "bbps": {
    "bills": [
      {
        "bill_fetch_ref_id": "b73a14a591874eb3a22296b2dd861511952",
        "biller_id": "SWAR00027NAT2J",
        "agent_id": "CH01CH02INB516193127",
        "amount_to_be_paid": 1000,
        "shortfall_amount": 100,
        "vendor_splits": [
          {
            "vendor_id": "VENDOR_001",
            "amount": 20
          }
        ]
      },
      {
        "bill_fetch_ref_id": "a92b25b691874eb3a33407c3ee972622063",
        "biller_id": "ELEC00045DEL1K",
        "agent_id": "CH01CH02INB516193127",
        "amount_to_be_paid": 540,
        "shortfall_amount": 0
      }
    ]
  }
}

Bill Payment requests: one per bill

{
  "bill_payment_request": {
    "head": {
      "bill_fetch_ref_id": "b73a14a591874eb3a22296b2dd861511952",
      "pg_reference_id": "1461688981422088704"
    },
    "amount": {
      "amt": {
        "amount": "1000.00",
        "cust_conv_fee": "0",
        "cou_cust_conv_fee": "0",
        "currency": "INR"
      }
    },
    "payment_breakdown": {
      "shortfall_amount": "100.00"
    }
  }
}

{
  "bill_payment_request": {
    "head": {
      "bill_fetch_ref_id": "a92b25b691874eb3a33407c3ee972622063",
      "pg_reference_id": "1461688981422088704"
    },
    "amount": {
      "amt": {
        "amount": "540.00",
        "cust_conv_fee": "0",
        "cou_cust_conv_fee": "0",
        "currency": "INR"
      }
    },
    "payment_breakdown": {
      "shortfall_amount": "0.00"
    }
  }
}

Pay Together with prefunding

Amounts: Same two bills, paying ₹1,000 and ₹540. You choose the PG order amount, for example ₹1,400 after a ₹140 discount. Bill Payments are for ₹1,000 and ₹540, so your prefunded wallet is debited ₹1,540. Create Order request

{
  "order_amount": 1400,
  "order_currency": "INR",
  "customer_details": {
    "customer_id": "7112AAA812234",
    "customer_phone": "9898989898"
  },
  "bbps": {
    "bills": [
      {
        "bill_fetch_ref_id": "b73a14a591874eb3a22296b2dd861511952",
        "biller_id": "SWAR00027NAT2J",
        "agent_id": "CH01CH02INB516193127",
        "amount_to_be_paid": 1000
      },
      {
        "bill_fetch_ref_id": "a92b25b691874eb3a33407c3ee972622063",
        "biller_id": "ELEC00045DEL1K",
        "agent_id": "CH01CH02INB516193127",
        "amount_to_be_paid": 540
      }
    ]
  }
}

Bill Payment requests: one per bill

{
  "bill_payment_request": {
    "head": {
      "bill_fetch_ref_id": "b73a14a591874eb3a22296b2dd861511952",
      "pg_reference_id": "1461688981422088704"
    },
    "amount": {
      "amt": {
        "amount": "1000.00",
        "cust_conv_fee": "0",
        "cou_cust_conv_fee": "0",
        "currency": "INR"
      }
    }
  }
}

{
  "bill_payment_request": {
    "head": {
      "bill_fetch_ref_id": "a92b25b691874eb3a33407c3ee972622063",
      "pg_reference_id": "1461688981422088704"
    },
    "amount": {
      "amt": {
        "amount": "540.00",
        "cust_conv_fee": "0",
        "cou_cust_conv_fee": "0",
        "currency": "INR"
      }
    }
  }
}

BBPS for Business

BBPS for Customers

Payment Scenarios

Key terms

Amount to be paid by biller type

Funding models

Settlement flows

Prefunding scenarios

Standard payment with prefunding

Discount or coin burn with prefunding

Vendor split with prefunding

Discount and vendor split with prefunding

Skip the PG transaction with prefunding

Postfunding scenarios

Standard payment with postfunding

Shortfall with postfunding

Skip the PG transaction with postfunding

Vendor split with postfunding

Shortfall and vendor split with postfunding

Pay Together for multiple bills

Pay Together with postfunding

Pay Together with prefunding

​Key terms

​Amount to be paid by biller type

​Funding models

​Settlement flows

​Prefunding scenarios

​Standard payment with prefunding

​Discount or coin burn with prefunding

​Vendor split with prefunding

​Discount and vendor split with prefunding

​Skip the PG transaction with prefunding

​Postfunding scenarios

​Standard payment with postfunding

​Shortfall with postfunding

​Skip the PG transaction with postfunding

​Vendor split with postfunding

​Shortfall and vendor split with postfunding

​Pay Together for multiple bills

​Pay Together with postfunding

​Pay Together with prefunding

Key terms

Amount to be paid by biller type

Funding models

Settlement flows

Prefunding scenarios

Standard payment with prefunding

Discount or coin burn with prefunding

Vendor split with prefunding

Discount and vendor split with prefunding

Skip the PG transaction with prefunding

Postfunding scenarios

Standard payment with postfunding

Shortfall with postfunding

Skip the PG transaction with postfunding

Vendor split with postfunding

Shortfall and vendor split with postfunding

Pay Together for multiple bills

Pay Together with postfunding

Pay Together with prefunding