Skip to content

Commit 79db2e3

Browse files
tanmay-dixittanmay-dixit
authored
Merge pull request #262 from SetuHQ/cou-upms-staging-new
UPMS docs for staging
2 parents e557d8e + 906a4ba commit 79db2e3

File tree

7 files changed

+7778
-2820
lines changed

7 files changed

+7778
-2820
lines changed

‎api-playground/json/payments/billpay/api-integration/FetchRequest.json

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,10 @@
3232
}
3333
],
3434
"mobile": "9481773053"
35+
},
36+
"mandate": {
37+
"registrationType": "VIEW_N_PAY",
38+
"billPeriod": "ASPRESENTED"
3539
}
3640
}
3741
}

‎api-references/payments/billpay/api-integration.json

Lines changed: 6233 additions & 2808 deletions
Large diffs are not rendered by default.

‎content/payments/billpay/api-integration/api-reference.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
sidebar_title: API reference
33
page_title: COU Direct Connectivity API reference
4-
order: 6
4+
order: 7
55
visible_in_sidebar: true
66
---

‎content/payments/billpay/api-integration/apis.mdx

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,9 @@ For e.g., if your customer wants to pay their phone bill for Vodafone Postpaid,
3030
</li>
3131
</ul>
3232

33+
Optionally, you can also registration the customer with this biller simultaneously to receive future bills as and when they are generated (See [UPMS Integration Guide](upms.mdx)).
34+
35+
3336
<Card padding="nano" shape="rounded">
3437
<details>
3538
<summary>

‎content/payments/billpay/api-integration/objects.mdx

Lines changed: 119 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -49,14 +49,28 @@ Payment modes supported by a biller.
4949

5050
## Customer
5151

52-
Customer object holds the customer mobile number and the customer bill parameters.
52+
Customer object holds the customer mobile number and the customer bill parameters. This object is used in the V1 API.
5353

54-
| parameter | type | description |
55-
| ------------------------ | ---------------------------------- | -------------------------------------------------------------------------------------------------- |
56-
| `mobile` | `string` (6, 10 and 20 digits) | Customer Mobile Number |
57-
| `billParameters` | `{ name: string, value: string}[]` | Bill Parameters. The parameters to send is found in the biller details API. |
58-
| `billParameters[].name` | `string` | Name of the bill parameter. name should match the parameter in biller details API. |
59-
| `billParameters[].value` | `string` | Value of the bill parameter. Value is validate according to the regex found in the biller details. |
54+
| parameter | type | description |
55+
| -------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
56+
| `mobile` | `string` (6, 10 and 20 digits) | Customer Mobile Number |
57+
| `billParameters` | `{ name: string, value: string}[]` | Bill Parameters used for standard bill fetch/payment. The parameters to send is found in the biller details API. |
58+
| `billParameters[].name` | `string` | Name of the bill parameter. name should match the parameter in biller details API. |
59+
| `billParameters[].value` | `string` | Value of the bill parameter. Value is validate according to the regex found in the biller details. |
60+
61+
## CustomerV2
62+
63+
CustomerV2 object holds the customer mobile number and the customer bill parameters. This is a new object introduced in the V2 API.
64+
65+
| parameter | type | description |
66+
| -------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
67+
| `mobile` | `string` (6, 10 and 20 digits) | Customer Mobile Number |
68+
| `customerParams` | `{ name: string, value: string}[]` | Customer Parameters used for standard bill fetch/payment. The parameters to send is found in the biller details API. |
69+
| `customerParams[].name` | `string` | Name of the customer parameter. name should match the parameter in biller details API. |
70+
| `customerParams[].value` | `string` | Value of the customer parameter. Value is validate according to the regex found in the biller details. |
71+
| `name` | `string` (Optional) | Customer's name as registered with the biller. Only present in UPMS registration callbacks if provided by the biller's system. |
72+
73+
Note: `customerParams` is a new field introduced in the V2 API in place of `billParameters`.
6074

6175
## Biller
6276

@@ -125,6 +139,17 @@ Details pertaining to the Agent which initiates the transaction. Values of the f
125139
| message | `string` | Error code description |
126140
| type | `FUND_TRANSFER` or `BBPS` or `APP` | Error Type. BBPS errors are due to BBPS, and code and message field contain the actual BBPS error. |
127141

142+
## Error Object (Generic)
143+
144+
A standard structure for representing errors in API responses or callbacks.
145+
146+
| parameter | type | description |
147+
| --------- | -------- | -------------------------------------------------------------------------------------------------------------- |
148+
| `code` | `string` | A short code identifying the error category (e.g., `validation-error`, `biller-registration-failed`). |
149+
| `message` | `string` | A human-readable description of the error. |
150+
151+
**Note:** In some asynchronous UPMS callbacks (e.g., for failed registration/update/cancel), the field names might appear as `Code` and `Message` (PascalCase) instead of `code` and `message`. Your callback handler should accommodate this potential difference.
152+
128153
## Payment Details
129154

130155
| parameter | type | description |
@@ -189,6 +214,93 @@ The Payment Bill object contains information about a specific bill to be paid.
189214
| `ASPRESENTED` |
190215
| `NA` |
191216

217+
## UPMS Registration Type
218+
219+
Indicates the type of UPMS registration.
220+
221+
| type | description |
222+
| -------------- | ------------------------------------------------------------------------------ |
223+
| `VIEW_N_PAY` | Standard presentment. Bills are notified, user manually initiates payment. |
224+
| `AUTO_PAY` | Auto-payment mandate. Bills are paid automatically using pre-configured info. |
225+
226+
## UPMS Debit Type
227+
228+
Specifies the debit rule for `AUTO_PAY` registrations.
229+
230+
| type | description |
231+
| -------------- | ------------------------------------------------------- |
232+
| `FIXED_AMOUNT` | Pay the exact bill amount presented. |
233+
| `MAX_AMOUNT` | Pay the bill amount, up to the specified maximum limit. |
234+
235+
## UPMS Registration Status
236+
237+
Represents the lifecycle state of a UPMS registration.
238+
239+
| type | description |
240+
| ------------- | -------------------------------------------------------------------------- |
241+
| `PENDING` | Initial state after request, before confirmation. |
242+
| `SUCCESS` | Registration active; bills will be presented via callbacks. |
243+
| `FAILED` | Registration could not be completed (e.g., invalid details). |
244+
| `CANCELLED` | Registration permanently cancelled by user or system. |
245+
| `DEACTIVATED` | Registration is temporarily inactive (currently not used, future scope). |
246+
247+
## UPMS Debit Info
248+
249+
Contains details for automatic debit configuration, required only when `registrationType` is `AUTO_PAY`.
250+
251+
| parameter | type | description |
252+
| ------------- | ----------------------------------------------- | -------------------------------------------------------------------------------------- |
253+
| `debitType` | [UPMS Debit Type](#upms-debit-type) (Mandatory) | The rule for auto-debit (`FIXED_AMOUNT` or `MAX_AMOUNT`). |
254+
| `amount` | `integer` (Mandatory) | The fixed or maximum amount for auto-debit, in paise. |
255+
| `currency` | `integer` (Mandatory) | Currency code (use `356` for INR). |
256+
| `paymentMode` | [Payment Mode](#payment-mode) (Mandatory) | The payment method intended for auto-debit (e.g., `Internet Banking`, `UPI`). |
257+
| `debitDate` | `string` (Optional) | Preferred date format (`DD-MMM`, e.g., `10-Feb`) for attempting auto-debit each cycle. |
258+
259+
## UPMS Mandate
260+
261+
Represents the customer's mandate details provided during UPMS registration creation or update.
262+
263+
| parameter | type | description |
264+
| ------------------ | ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
265+
| `registrationType` | [UPMS Registration Type](#upms-registration-type) (Mandatory) | `VIEW_N_PAY` or `AUTO_PAY`. |
266+
| `billPeriod` | [Bill Period](#bill-period) (Conditional) | Frequency of expected bills (e.g., `MONTHLY`, `ASPRESENTED`). Mandatory for some billers. |
267+
| `toDate` | `string` (YYYY-MM-DD) (Optional) | Expiry date of the registration. |
268+
| `debitInfo` | [UPMS Debit Info](#upms-debit-info) (Optional) | Required only if `registrationType` is `AUTO_PAY`. Contains auto-debit parameters. |
269+
| `billerParams` | `{ name: string, value: string}[]` (Optional) | Additional parameters specific to the biller for the mandate (e.g., "Low Balance Threshold"). Structure matches `billParameters`. |
270+
271+
## UPMSRegistration
272+
273+
Represents the complete details of a UPMS registration, typically received in webhook callbacks.
274+
275+
| parameter | type | description |
276+
| -------------- | ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
277+
| `refId` | `string` (Mandatory) | The unique reference ID for this specific UPMS registration instance. |
278+
| `status` | [UPMS Registration Status](#upms-registration-status) (Mandatory) | The current status of the registration (e.g., `PENDING`, `SUCCESS`, `FAILED`, `CANCELLED`, `DEACTIVATED`). |
279+
| `biller` | [Biller](#biller) (Mandatory) | Object containing the `id` of the associated biller. |
280+
| `customer` | [CustomerV2](#customerv2) (Mandatory) | Object containing customer details (`customerParams`, `mobile`, optionally `name`) used for registration. |
281+
| `mandate` | [UPMS Mandate](#upms-mandate) (Mandatory) | The mandate details associated with this registration. |
282+
| `createdAt` | `string` (ISO 8601 datetime) (Mandatory) | Timestamp when the registration was created. |
283+
| `updatedAt` | `string` (ISO 8601 datetime) (Mandatory) | Timestamp when the registration was last updated (status change, modification, cancellation). |
284+
285+
## UPMS Duplicate Info
286+
287+
Indicates that a UPMS registration attempt was a duplicate of an existing one. Received within the `data` object of a `CREATE_UPMS_REGISTRATION` callback.
288+
289+
| parameter | type | description |
290+
| --------- | -------- | ------------------------------------------------------------------------------ |
291+
| `code` | `string` | Code indicating the duplicate situation (e.g., `duplicate-upms-registration`). |
292+
| `message` | `string` | Description of the duplicate situation. |
293+
| `refId` | `string` | The reference ID (`refId`) of the *existing* successful/pending registration. |
294+
295+
## Skip Payment Data
296+
297+
Contains details about a bill payment that was skipped because it was paid via an external channel. Received within the `data` object of a `SKIP_PAYMENT` callback.
298+
299+
| parameter | type | description |
300+
| --------------- | ---------------------------- | ----------------------------------------------------------------------------- |
301+
| `billRefId` | `string` | The unique reference ID of the specific bill instance that was skipped/paid. |
302+
| `dateOfPayment` | `string` (ISO 8601 datetime) | Timestamp indicating when the payment occurred on the external channel. |
303+
192304
## Biller Selection Type
193305

194306
| type | description |

0 commit comments

Comments
 (0)