diff --git a/api-playground/json/payments/billpay/api-integration/CancelUPMSRegistration.json b/api-playground/json/payments/billpay/api-integration/CancelUPMSRegistration.json new file mode 100644 index 00000000..685a1955 --- /dev/null +++ b/api-playground/json/payments/billpay/api-integration/CancelUPMSRegistration.json @@ -0,0 +1,14 @@ +{ + "parameters": { + "header": [ + { + "X-PARTNER-ID": "1010225520484287807" + } + ], + "path": [ + { + "upmsRegistrationRefID": "SETUUPMSREFIDEXAMPLE123456789012345" + } + ] + } +} \ No newline at end of file diff --git a/api-playground/json/payments/billpay/api-integration/FetchRequest.json b/api-playground/json/payments/billpay/api-integration/FetchRequest.json index a34dac13..0541ac38 100644 --- a/api-playground/json/payments/billpay/api-integration/FetchRequest.json +++ b/api-playground/json/payments/billpay/api-integration/FetchRequest.json @@ -26,10 +26,11 @@ "value": "2775864" } ], - "mobile": "9999999861" + "mobile": "9481773053" }, "mandate": { - "registrationType": "VIEW_N_PAY" + "registrationType": "VIEW_N_PAY", + "billPeriod": "ASPRESENTED" } } } diff --git a/api-playground/json/payments/billpay/api-integration/SimulateBillNotification.json b/api-playground/json/payments/billpay/api-integration/SimulateBillNotification.json new file mode 100644 index 00000000..685a1955 --- /dev/null +++ b/api-playground/json/payments/billpay/api-integration/SimulateBillNotification.json @@ -0,0 +1,14 @@ +{ + "parameters": { + "header": [ + { + "X-PARTNER-ID": "1010225520484287807" + } + ], + "path": [ + { + "upmsRegistrationRefID": "SETUUPMSREFIDEXAMPLE123456789012345" + } + ] + } +} \ No newline at end of file diff --git a/api-playground/json/payments/billpay/api-integration/SimulateSkipPaymentNotification.json b/api-playground/json/payments/billpay/api-integration/SimulateSkipPaymentNotification.json new file mode 100644 index 00000000..1aaa4467 --- /dev/null +++ b/api-playground/json/payments/billpay/api-integration/SimulateSkipPaymentNotification.json @@ -0,0 +1,14 @@ +{ + "parameters": { + "header": [ + { + "X-PARTNER-ID": "1010225520484287807" + } + ], + "path": [ + { + "billRefId": "SETUBILLREFIDEXAMPLE123456789012345" + } + ] + } +} \ No newline at end of file diff --git a/api-playground/json/payments/billpay/api-integration/UpdateUPMSRegistration.json b/api-playground/json/payments/billpay/api-integration/UpdateUPMSRegistration.json new file mode 100644 index 00000000..01c1c759 --- /dev/null +++ b/api-playground/json/payments/billpay/api-integration/UpdateUPMSRegistration.json @@ -0,0 +1,24 @@ +{ + "parameters": { + "header": [ + { + "X-PARTNER-ID": "1010225520484287807" + } + ], + "path": [ + { + "upmsRegistrationRefID": "SETUUPMSREFIDEXAMPLE123456789012345" + } + ] + }, + "body": { + "mandate": { + "registrationType": "AUTO_PAY", + "toDate": "2027-01-01", + "debitInfo": { + "amount": 10000, + "type": "MAX_AMOUNT" + } + } + } +} \ No newline at end of file diff --git a/api-playground/json/payments/billpay/api-integration/ViewUPMSRegistration.json b/api-playground/json/payments/billpay/api-integration/ViewUPMSRegistration.json new file mode 100644 index 00000000..685a1955 --- /dev/null +++ b/api-playground/json/payments/billpay/api-integration/ViewUPMSRegistration.json @@ -0,0 +1,14 @@ +{ + "parameters": { + "header": [ + { + "X-PARTNER-ID": "1010225520484287807" + } + ], + "path": [ + { + "upmsRegistrationRefID": "SETUUPMSREFIDEXAMPLE123456789012345" + } + ] + } +} \ No newline at end of file diff --git a/api-references/payments/billpay/api-integration.json b/api-references/payments/billpay/api-integration.json index d7364423..7146132b 100644 --- a/api-references/payments/billpay/api-integration.json +++ b/api-references/payments/billpay/api-integration.json @@ -22,7 +22,9 @@ "paths": { "/api/v2/auth/token": { "post": { - "tags": ["Token API"], + "tags": [ + "Token API" + ], "description": "Fetch token to be used to authorize all Setu APIs", "operationId": "fetchToken", "requestBody": { @@ -101,7 +103,10 @@ "schema": { "allOf": [ { - "required": ["expiresIn", "token"], + "required": [ + "expiresIn", + "token" + ], "type": "object", "properties": { "expiresIn": { @@ -116,7 +121,10 @@ } }, { - "required": ["success", "traceId"], + "required": [ + "success", + "traceId" + ], "type": "object", "properties": { "success": { @@ -139,7 +147,11 @@ "content": { "application/json": { "schema": { - "required": ["error", "success", "traceId"], + "required": [ + "error", + "success", + "traceId" + ], "type": "object", "properties": { "traceId": { @@ -147,7 +159,10 @@ "example": "C3SFG0O6N88R6UI7EQ" }, "error": { - "required": ["code", "message"], + "required": [ + "code", + "message" + ], "type": "object", "properties": { "code": { @@ -202,59 +217,19 @@ "schema": { "allOf": [ { - "required": ["agent", "biller"], + "required": [ + "agent", + "biller" + ], "type": "object", "properties": { "agent": { - "required": ["channel", "id"], + "required": [ + "channel", + "id" + ], "type": "object", "properties": { - "mac": { - "type": "string", - "description": "Mandatory if channel is `INT`, `INTB`. Not required for others.", - "format": "mac", - "example": "48-4D-7E-CB-DB-6F" - }, - "mobile": { - "maxLength": 22, - "minLength": 6, - "pattern": "^\\d{6,22}$", - "type": "string", - "description": "Mobile number with 6 to 22 digits are valid." - }, - "postalCode": { - "pattern": "^[1-9][0-9]{5}$", - "type": "string", - "description": "Mandatory if channel is `AGT`, `BSC` and `BNKBRNCH`. Not required for others. This has to match the data submitted to NPCI for this agent ID\n", - "example": "600001" - }, - "id": { - "type": "string", - "description": "The ID of the agent initiating the BBPS transaction.", - "example": "AX01AI06512391457204" - }, - "ifsc": { - "type": "string", - "description": "Mandatory if channel is `BNKBRNCH`. Not required for others. This has to match the data submitted to NPCI for this agent ID\n", - "example": "ICIC0000152" - }, - "imei": { - "type": "string", - "description": "Mandatory if channel is `MOB`, `MOBB`. Not required for others.", - "example": "123456789012345" - }, - "ip": { - "type": "string", - "description": "Mandatory if channel is `INT`, `INTB`. Not required for others.", - "format": "ipv4", - "example": "124.170.23.24" - }, - "os": { - "type": "string", - "description": "Mandatory if channel is `MOB`, `MOBB`. Not required for others.", - "example": "iOS", - "enum": ["iOS", "Android"] - }, "app": { "type": "string", "description": "Mandatory if channel is `MOB`, `MOBB`. Not required for others.", @@ -278,6 +253,45 @@ "MPOS" ] }, + "imei": { + "type": "string", + "description": "Mandatory if channel is `MOB`, `MOBB`. Not required for others.", + "example": "123456789012345" + }, + "ip": { + "type": "string", + "description": "Mandatory if channel is `INT`, `INTB`. Not required for others.", + "format": "ipv4", + "example": "124.170.23.24" + }, + "mac": { + "type": "string", + "description": "Mandatory if channel is `INT`, `INTB`. Not required for others.", + "format": "mac", + "example": "48-4D-7E-CB-DB-6F" + }, + "mobile": { + "maxLength": 22, + "minLength": 6, + "pattern": "^\\d{6,22}$", + "type": "string", + "description": "Mobile number with 6 to 22 digits are valid." + }, + "os": { + "type": "string", + "description": "Mandatory if channel is `MOB`, `MOBB`. Not required for others.", + "example": "iOS", + "enum": [ + "iOS", + "Android" + ] + }, + "postalCode": { + "pattern": "^[1-9][0-9]{5}$", + "type": "string", + "description": "Mandatory if channel is `AGT`, `BSC` and `BNKBRNCH`. Not required for others. This has to match the data submitted to NPCI for this agent ID\n", + "example": "600001" + }, "geocode": { "type": "string", "description": "Mandatory if channel is `AGT`, `BSC` and `BNKBRNCH`. Not required for others. This has to match the data submitted to NPCI for this agent ID\n", @@ -290,59 +304,61 @@ } } }, + "biller": { + "required": [ + "id" + ], + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "The biller ID on BBPS", + "example": "MAHI00000NATIC" + } + }, + "x-go-gen-location": "models", + "x-go-name": "BillerDetails" + }, "remitter": { "type": "object", "properties": { "aadhaar": { "maxLength": 50, "minLength": 1, - "type": "string", - "example": "123456789012" + "type": "string" }, "email": { "maxLength": 50, "minLength": 1, - "type": "string", - "example": "test@example.com" + "type": "string" }, "name": { "maxLength": 50, "minLength": 1, - "type": "string", - "example": "John Doe" + "type": "string" }, "pan": { "maxLength": 50, "minLength": 1, - "type": "string", - "example": "ABDCE1121E" + "type": "string" } } - }, - "biller": { - "required": ["id"], - "type": "object", - "properties": { - "id": { - "type": "string", - "description": "The biller ID on BBPS", - "example": "MAHI00000NATIC" - } - }, - "x-go-gen-location": "models", - "x-go-name": "BillerDetails" } }, "x-omitempty": true }, { - "required": ["customer"], + "required": [ + "customer" + ], "type": "object", "properties": { "customer": { "allOf": [ { - "required": ["mobile"], + "required": [ + "mobile" + ], "type": "object", "properties": { "customerId": { @@ -360,20 +376,25 @@ } }, { - "required": ["customerParams"], + "required": [ + "customerParams" + ], "type": "object", "properties": { "customerParams": { "type": "array", "description": "The bill params for fetching the bill", "items": { - "required": ["name", "value"], + "required": [ + "name", + "value" + ], "type": "object", "properties": { "name": { "type": "string", "description": "The display name of the parameter. This has to match what is sent in fields.", - "example": "John Doe" + "example": "Loan Number" }, "value": { "type": "string", @@ -386,6 +407,82 @@ } } ] + }, + "mandate": { + "type": "object", + "properties": { + "billPeriod": { + "type": "string", + "description": "Mandatory for Validation & Pay billers. Allowed values: DAILY, WEEKLY, BIMONTHLY, MONTHLY, QUARTERLY, HALFYEARLY, YEARLY\nOptional for Fetch & Pay billers. Allowed values: ASPRESENTED\n", + "nullable": true, + "example": "MONTHLY", + "x-omitempty": true + }, + "billerParams": { + "type": "array", + "nullable": true, + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Captures the name of the biller parameter to be sent as part of UPMS registration.", + "example": "Low Balance Threshold" + }, + "value": { + "type": "string", + "description": "The value of the biller parameter to be sent as part of UPMS registration.", + "example": "500" + } + }, + "description": "Optional. Only some billers require this. Details of the biller parameter to be sent as part of UPMS registration." + }, + "x-omitempty": true + }, + "debitInfo": { + "type": "object", + "properties": { + "amount": { + "type": "integer", + "description": "The fixed or maximum amount set for auto-debit (value must be provided in paise).", + "example": 10000 + }, + "currency": { + "type": "integer", + "description": "The currency code. Use `356` for `INR`.", + "example": 356 + }, + "debitDate": { + "type": "string", + "description": "The preferred date format (`DD-MMM`) for attempting the auto-debit each cycle.", + "example": "10-Feb" + }, + "paymentMode": { + "type": "string", + "description": "The payment method intended for auto-debit, allowed values:\n - Internet Banking\n - Debit Card\n - Credit Card\n - Prepaid Card\n - IMPS\n - UPI\n - Wallet\n - NEFT\n - AEPS\n - Account Transfer\n - Bharat QR", + "example": "UPI" + }, + "type": { + "type": "string", + "description": "Specifies the debit rule. Can be `FIXED_AMOUNT` (pay the exact bill amount) or `MAX_AMOUNT` (pay up to this limit).", + "example": "FIXED_AMOUNT" + } + }, + "description": "Details for debit information (mandatory when registrationType is AUTO_PAY)" + }, + "registrationType": { + "type": "string", + "description": "The type of registration (AUTO_PAY or VIEW_N_PAY)", + "example": "AUTO_PAY" + }, + "toDate": { + "type": "string", + "description": "The UPMS registration is invalid after this date. Date format is YYYY-MM-DD", + "nullable": true, + "example": "2027-01-01", + "x-omitempty": true + } + } } } } @@ -446,15 +543,24 @@ "content": { "application/json": { "schema": { - "required": ["data", "success", "traceId"], + "required": [ + "data", + "success", + "traceId" + ], "type": "object", "properties": { "data": { - "required": ["refId"], + "required": [ + "refId" + ], "type": "object", "properties": { "duplicate": { - "required": ["code", "message"], + "required": [ + "code", + "message" + ], "type": "object", "properties": { "code": { @@ -462,20 +568,70 @@ "example": "error-code-if-any" }, "message": { - "type": "string", - "example": "error-message-if-any" + "type": "string" }, "refId": { "type": "string", - "description": "The generated BBPS Reference ID for the request.", - "example": "HENSVVR4QOS7X1UGPY7JGUV444P10102202" + "description": "The generated Reference ID for the request." } } }, "refId": { "type": "string", - "description": "The generated BBPS Reference ID for the request.", - "example": "HENSVVR4QOS7X1UGPY7JGUV444P10102202" + "description": "The generated Reference ID for the request." + }, + "upmsRegistration": { + "type": "object", + "properties": { + "duplicate": { + "required": [ + "code", + "message" + ], + "type": "object", + "properties": { + "code": { + "type": "string" + }, + "message": { + "type": "string" + }, + "refId": { + "type": "string", + "description": "The generated Reference ID for the request." + } + } + }, + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "example": "invalid-mandate" + }, + "message": { + "type": "string", + "example": "The mandate configuration is invalid" + } + }, + "description": "Present only when acknowledgement status for the registration is FAILED" + }, + "refId": { + "type": "string", + "description": "The reference ID for the UPMS registration", + "example": "HENSVVR4QOS7X1UGPY7JGUV444P10102202" + }, + "status": { + "type": "string", + "description": "Status of the registration request processing by our system", + "example": "PENDING", + "enum": [ + "PENDING", + "FAILED" + ] + } + }, + "description": "Present only when upmsRegistration was requested" } } }, @@ -499,7 +655,11 @@ "content": { "application/json": { "schema": { - "required": ["error", "success", "traceId"], + "required": [ + "error", + "success", + "traceId" + ], "type": "object", "properties": { "traceId": { @@ -507,7 +667,10 @@ "example": "C3SFG0O6N88R6UI7EQ" }, "error": { - "required": ["code", "message"], + "required": [ + "code", + "message" + ], "type": "object", "properties": { "code": { @@ -534,7 +697,11 @@ "content": { "application/json": { "schema": { - "required": ["error", "success", "traceId"], + "required": [ + "error", + "success", + "traceId" + ], "type": "object", "properties": { "traceId": { @@ -542,7 +709,10 @@ "example": "C3SFG0O6N88R6UI7EQ" }, "error": { - "required": ["code", "message"], + "required": [ + "code", + "message" + ], "type": "object", "properties": { "code": { @@ -567,13 +737,19 @@ }, "security": [ { - "Production": ["bbps:partner"] + "Production": [ + "bbps:partner" + ] }, { - "Sandbox": ["bbps:partner"] + "Sandbox": [ + "bbps:partner" + ] }, { - "QA": ["bbps:partner"] + "QA": [ + "bbps:partner" + ] } ], "x-codegen-request-body-name": "CouAgentBillFetchRequest" @@ -606,7 +782,9 @@ "content": { "application/json": { "schema": { - "required": ["refId"], + "required": [ + "refId" + ], "type": "object", "properties": { "refId": { @@ -744,7 +922,10 @@ "schema": { "allOf": [ { - "required": ["success", "traceId"], + "required": [ + "success", + "traceId" + ], "type": "object", "properties": { "success": { @@ -758,11 +939,16 @@ } }, { - "required": ["data"], + "required": [ + "data" + ], "type": "object", "properties": { "data": { - "required": ["refId", "status"], + "required": [ + "refId", + "status" + ], "type": "object", "properties": { "billerRefId": { @@ -773,7 +959,24 @@ "type": "string", "nullable": true, "example": "SINGLE", - "enum": ["SINGLE", "LIST", "SELECTIVE"], + "enum": [ + "SINGLE", + "LIST", + "SELECTIVE" + ], + "x-nullable": true, + "x-omitempty": false + }, + "billerSelectionType": { + "type": "string", + "description": "Defined only for billers with response type as LIST. SINGLE: User can pay only one of the bills in bill fetch response. MULTIPLE: User can pay any combination of bills in bill fetch response. ALL: User has to pay all the bills in bill fetch response.", + "nullable": true, + "example": "SINGLE", + "enum": [ + "SINGLE", + "MULTIPLE", + "ALL" + ], "x-nullable": true, "x-omitempty": false }, @@ -790,15 +993,45 @@ ], "type": "object", "properties": { + "amount": { + "type": "integer", + "nullable": true, + "x-omitempty": true + }, + "amountMultiple": { + "type": "integer", + "description": "Bill payment amount should be multiple of this value in paise", + "nullable": true, + "x-omitempty": true + }, "billDate": { "type": "string", "format": "date", "example": "2021-01-02" }, + "billNumber": { + "type": "string", + "example": "1232332" + }, + "billPeriod": { + "type": "string", + "example": "ONETIME|DAILY|WEEKLY|BIMONTHLY|MONTHLY|QUARTERLY|HALFYEARLY|YEARLY|ASPRESENTED" + }, "customerName": { "type": "string", "example": "Manoj Chekuri" }, + "dueDate": { + "type": "string", + "format": "date", + "example": "2021-09-24" + }, + "maxAmount": { + "type": "integer", + "description": "Maximum amount that can be paid for this bill in paise", + "nullable": true, + "x-omitempty": true + }, "minAmount": { "type": "integer", "description": "Minimum amount that can be paid for this bill in paise", @@ -809,12 +1042,20 @@ "type": "array", "nullable": true, "items": { - "required": ["name"], + "required": [ + "name" + ], "type": "object", "properties": { - "amountMultiple": { + "amount": { "type": "integer", - "description": "The payment amount should be a multiple of this value in paise.", + "description": "The amount that can be paid for this option in paise.", + "nullable": true, + "x-omitempty": true + }, + "amountMultiple": { + "type": "integer", + "description": "The payment amount should be a multiple of this value in paise.", "nullable": true, "x-omitempty": true }, @@ -833,53 +1074,17 @@ "name": { "type": "string", "description": "The display name of the option.", - "example": "John Doe" - }, - "amount": { - "type": "integer", - "description": "The amount that can be paid for this option in paise.", - "nullable": true, - "x-omitempty": true + "example": "2 Months EMI Amount" } } }, "x-omitempty": true }, - "amount": { - "type": "integer", - "nullable": true, - "x-omitempty": true - }, - "amountMultiple": { - "type": "integer", - "description": "Bill payment amount should be multiple of this value in paise", - "nullable": true, - "x-omitempty": true - }, - "dueDate": { - "type": "string", - "format": "date", - "example": "2021-09-24" - }, "label": { "type": "string", "nullable": true, "example": "Advance EMI", "x-omitempty": true - }, - "maxAmount": { - "type": "integer", - "description": "Maximum amount that can be paid for this bill in paise", - "nullable": true, - "x-omitempty": true - }, - "billNumber": { - "type": "string", - "example": "1232332" - }, - "billPeriod": { - "type": "string", - "example": "ONETIME|DAILY|WEEKLY|BIMONTHLY|MONTHLY|QUARTERLY|HALFYEARLY|YEARLY|ASPRESENTED" } }, "x-go-name": "BillData" @@ -898,7 +1103,10 @@ ] }, "failureReason": { - "required": ["code", "message"], + "required": [ + "code", + "message" + ], "type": "object", "properties": { "message": { @@ -919,35 +1127,6 @@ "type": "string", "example": "HENSVVR4QOS7X1UGPY7JGUV444P10102202" }, - "additionalInfo": { - "type": "array", - "description": "This tag captures the additional information provided by the Biller as part of response for a successful transaction.", - "items": { - "required": ["name", "value"], - "type": "object", - "properties": { - "value": { - "type": "string", - "example": "Value 1" - }, - "name": { - "type": "string", - "example": "John Doe" - } - } - }, - "x-go-name": "BillAdditionalInfo", - "x-omitempty": false - }, - "billerSelectionType": { - "type": "string", - "description": "Defined only for billers with response type as LIST. SINGLE: User can pay only one of the bills in bill fetch response. MULTIPLE: User can pay any combination of bills in bill fetch response. ALL: User has to pay all the bills in bill fetch response.", - "nullable": true, - "example": "SINGLE", - "enum": ["SINGLE", "MULTIPLE", "ALL"], - "x-omitempty": false, - "x-nullable": true - }, "status": { "type": "string", "example": "Success", @@ -957,6 +1136,12 @@ "Failure", "Credit_Adjustment" ] + }, + "upmsRegistrationRefId": { + "type": "string", + "nullable": true, + "example": "HENSVVR4QOS7X1UGPY7JGUV444P10102202", + "x-omitempty": true } } } @@ -971,13 +1156,19 @@ }, "security": [ { - "Production": ["bbps:partner"] + "Production": [ + "bbps:partner" + ] }, { - "Sandbox": ["bbps:partner"] + "Sandbox": [ + "bbps:partner" + ] }, { - "QA": ["bbps:partner"] + "QA": [ + "bbps:partner" + ] } ], "x-codegen-request-body-name": "CouAgentAsyncRequest" @@ -1012,54 +1203,45 @@ "schema": { "allOf": [ { - "required": ["paymentDetails"], + "required": [ + "paymentDetails" + ], "type": "object", "properties": { - "dummyCustomerMobile": { - "type": "string", - "description": "On debug, this hijacks the customer mobiler number COMFORT NEGATIVE 30, 31", - "nullable": true, - "example": "9876543210" - }, - "refId": { - "type": "string", - "example": "HENSVVR4QOS7X1UGPY7JGUV444P10102202" - }, - "biller": { - "required": ["id"], - "type": "object", - "properties": { - "id": { - "type": "string", - "description": "The biller ID on BBPS", - "example": "MAHI00000NATIC" - } - }, - "x-go-gen-location": "models", - "x-go-name": "BillerDetails" - }, "agent": { - "required": ["channel", "id"], + "required": [ + "channel", + "id" + ], "type": "object", "properties": { - "mac": { + "app": { "type": "string", - "description": "Mandatory if channel is `INT`, `INTB`. Not required for others.", - "format": "mac", - "example": "48-4D-7E-CB-DB-6F" + "description": "Mandatory if channel is `MOB`, `MOBB`. Not required for others.", + "example": "SmartPay" }, - "mobile": { - "maxLength": 22, - "minLength": 6, - "pattern": "^\\d{6,22}$", + "channel": { "type": "string", - "description": "Mobile number with 6 to 22 digits are valid." + "description": "This is the initiating channel.\n1. `AGT`: Offline agent.\n2. `BNKBRNCH`: Bank branch.\n3. `BSC`: Business correspondent\n4. `MOB`: Mobile application\n5. `INT`: Internet portal\n6. `INTB`: Internet banking\n7. `MOBB`: Mobile banking\n8. `ATM`: ATM\n9. `KIOSK`: KIOSK\n", + "example": "INT", + "enum": [ + "INT", + "INTB", + "MOB", + "BNKBRNCH", + "BSC", + "AGT", + "KIOSK", + "ATM", + "MOBB", + "POS", + "MPOS" + ] }, - "postalCode": { - "pattern": "^[1-9][0-9]{5}$", + "geocode": { "type": "string", - "description": "Mandatory if channel is `AGT`, `BSC` and `BNKBRNCH`. Not required for others. This has to match the data submitted to NPCI for this agent ID\n", - "example": "600001" + "description": "Mandatory if channel is `AGT`, `BSC` and `BNKBRNCH`. Not required for others. This has to match the data submitted to NPCI for this agent ID\n", + "example": "19.0139,72.8254" }, "id": { "type": "string", @@ -1082,39 +1264,33 @@ "format": "ipv4", "example": "124.170.23.24" }, - "os": { + "mac": { "type": "string", - "description": "Mandatory if channel is `MOB`, `MOBB`. Not required for others.", - "example": "iOS", - "enum": ["iOS", "Android"] + "description": "Mandatory if channel is `INT`, `INTB`. Not required for others.", + "format": "mac", + "example": "48-4D-7E-CB-DB-6F" }, - "app": { + "mobile": { + "maxLength": 22, + "minLength": 6, + "pattern": "^\\d{6,22}$", "type": "string", - "description": "Mandatory if channel is `MOB`, `MOBB`. Not required for others.", - "example": "SmartPay" + "description": "Mobile number with 6 to 22 digits are valid." }, - "channel": { + "os": { "type": "string", - "description": "This is the initiating channel.\n1. `AGT`: Offline agent.\n2. `BNKBRNCH`: Bank branch.\n3. `BSC`: Business correspondent\n4. `MOB`: Mobile application\n5. `INT`: Internet portal\n6. `INTB`: Internet banking\n7. `MOBB`: Mobile banking\n8. `ATM`: ATM\n9. `KIOSK`: KIOSK\n", - "example": "INT", + "description": "Mandatory if channel is `MOB`, `MOBB`. Not required for others.", + "example": "iOS", "enum": [ - "INT", - "INTB", - "MOB", - "BNKBRNCH", - "BSC", - "AGT", - "KIOSK", - "ATM", - "MOBB", - "POS", - "MPOS" + "iOS", + "Android" ] }, - "geocode": { + "postalCode": { + "pattern": "^[1-9][0-9]{5}$", "type": "string", - "description": "Mandatory if channel is `AGT`, `BSC` and `BNKBRNCH`. Not required for others. This has to match the data submitted to NPCI for this agent ID\n", - "example": "19.0139,72.8254" + "description": "Mandatory if channel is `AGT`, `BSC` and `BNKBRNCH`. Not required for others. This has to match the data submitted to NPCI for this agent ID\n", + "example": "600001" }, "terminalId": { "type": "string", @@ -1123,63 +1299,69 @@ } } }, - "remitter": { + "biller": { + "required": [ + "id" + ], "type": "object", "properties": { - "aadhaar": { - "maxLength": 50, - "minLength": 1, - "type": "string", - "example": "123456789012" - }, - "email": { - "maxLength": 50, - "minLength": 1, - "type": "string", - "example": "test@example.com" - }, - "name": { - "maxLength": 50, - "minLength": 1, - "type": "string", - "example": "John Doe" - }, - "pan": { - "maxLength": 50, - "minLength": 1, + "id": { "type": "string", - "example": "ABDCE1121E" + "description": "The biller ID on BBPS", + "example": "MAHI00000NATIC" } - } + }, + "x-go-gen-location": "models", + "x-go-name": "BillerDetails" + }, + "bills": { + "uniqueItems": true, + "type": "array", + "nullable": true, + "example": "Selection on bills in case of list billers", + "items": { + "required": [ + "amount", + "billNumber" + ], + "type": "object", + "properties": { + "amount": { + "minimum": 1, + "type": "integer", + "description": "Amount in Paise" + }, + "billNumber": { + "type": "string", + "example": "B1234567" + } + }, + "x-omitempty": true + }, + "x-omitempty": true }, "paymentDetails": { - "required": ["amount", "mode", "paymentRefId", "timestamp"], + "required": [ + "amount", + "mode", + "paymentRefId", + "timestamp" + ], "type": "object", "properties": { - "custConvFee": { + "COUcustConvFee": { "type": "integer", "nullable": true }, - "paymentRefId": { - "maxLength": 35, - "minLength": 6, - "type": "string", - "example": "BD019181220291" - }, - "timestamp": { + "Id": { "type": "string", - "format": "date-time", - "example": "2020-12-12T13:12:00+05:30" - }, - "COUcustConvFee": { - "type": "integer", - "nullable": true + "description": "Pass here the ID of the selected payment plan in payment request. If a plan was selected in payment request, its Id will be a part of the paymentDetails block in payment response.", + "example": "1" }, "accountInfo": { "maxLength": 50, "minLength": 1, - "type": "string", - "example": "some-info" + "type": "string" }, "amount": { "minimum": 1, @@ -1190,6 +1372,10 @@ "type": "integer", "nullable": true }, + "custConvFee": { + "type": "integer", + "nullable": true + }, "mode": { "type": "string", "example": "Internet Banking", @@ -1209,12 +1395,21 @@ "USSD" ] }, + "paymentRefId": { + "maxLength": 35, + "minLength": 6, + "type": "string", + "example": "BD019181220291" + }, "selectedPaymentOptions": { "type": "array", "description": "List of selected payment options", "nullable": true, "items": { - "required": ["amount", "name"], + "required": [ + "amount", + "name" + ], "type": "object", "properties": { "amount": { @@ -1225,48 +1420,50 @@ "name": { "type": "string", "description": "The name of the payment option as returned in bill fetch response.", - "example": "John Doe" + "example": "Early Payment Amount" } } }, "x-nullable": true, "x-omitempty": true + }, + "timestamp": { + "type": "string", + "format": "date-time", + "example": "2020-12-12T13:12:00+05:30" } - } + }, + "x-go-gen-location": "models", + "x-go-name": "BillerDetails" }, - "bills": { - "uniqueItems": true, - "type": "array", - "nullable": true, - "example": "Selection on bills in case of list billers", - "items": { - "required": ["amount", "billNumber"], - "type": "object", - "properties": { - "billNumber": { - "type": "string", - "example": "B1234567" - }, - "amount": { - "minimum": 1, - "type": "integer", - "description": "Amount in Paise" - } - }, - "x-omitempty": true - }, - "x-omitempty": true - }, - "dummyBillerResponseAmount": { - "type": "integer", - "description": "On debug, this is the amount passed in biller response COMFORT NEGATIVE 23", - "nullable": true - }, - "dummyOrigRefId": { + "refId": { "type": "string", - "description": "On debug, hijacks orig ref id of payment request - COMFORT PAYMENT - 83", - "nullable": true, "example": "HENSVVR4QOS7X1UGPY7JGUV444P10102202" + }, + "remitter": { + "type": "object", + "properties": { + "aadhaar": { + "maxLength": 50, + "minLength": 1, + "type": "string" + }, + "email": { + "maxLength": 50, + "minLength": 1, + "type": "string" + }, + "name": { + "maxLength": 50, + "minLength": 1, + "type": "string" + }, + "pan": { + "maxLength": 50, + "minLength": 1, + "type": "string" + } + } } }, "x-omitempty": true @@ -1277,7 +1474,9 @@ "customer": { "allOf": [ { - "required": ["mobile"], + "required": [ + "mobile" + ], "type": "object", "properties": { "customerId": { @@ -1295,14 +1494,19 @@ } }, { - "required": ["customerParams"], + "required": [ + "customerParams" + ], "type": "object", "properties": { "customerParams": { "type": "array", "description": "The bill params for fetching the bill", "items": { - "required": ["name", "value"], + "required": [ + "name", + "value" + ], "type": "object", "properties": { "name": { @@ -1381,15 +1585,24 @@ "content": { "application/json": { "schema": { - "required": ["data", "success", "traceId"], + "required": [ + "data", + "success", + "traceId" + ], "type": "object", "properties": { "data": { - "required": ["refId"], + "required": [ + "refId" + ], "type": "object", "properties": { "duplicate": { - "required": ["code", "message"], + "required": [ + "code", + "message" + ], "type": "object", "properties": { "code": { @@ -1409,8 +1622,60 @@ }, "refId": { "type": "string", - "description": "The generated BBPS Reference ID for the request.", - "example": "HENSVVR4QOS7X1UGPY7JGUV444P10102202" + "description": "The generated Reference ID for the request." + }, + "upmsRegistration": { + "type": "object", + "properties": { + "duplicate": { + "required": [ + "code", + "message" + ], + "type": "object", + "properties": { + "code": { + "type": "string" + }, + "message": { + "type": "string" + }, + "refId": { + "type": "string", + "description": "The generated Reference ID for the request." + } + } + }, + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "example": "invalid-mandate" + }, + "message": { + "type": "string", + "example": "The mandate configuration is invalid" + } + }, + "description": "Present only when acknowledgement status for the registration is FAILED" + }, + "refId": { + "type": "string", + "description": "The reference ID for the UPMS registration", + "example": "HENSVVR4QOS7X1UGPY7JGUV444P10102202" + }, + "status": { + "type": "string", + "description": "Status of the registration request processing by our system", + "example": "PENDING", + "enum": [ + "PENDING", + "FAILED" + ] + } + }, + "description": "Present only when upmsRegistration was requested" } } }, @@ -1434,7 +1699,11 @@ "content": { "application/json": { "schema": { - "required": ["error", "success", "traceId"], + "required": [ + "error", + "success", + "traceId" + ], "type": "object", "properties": { "traceId": { @@ -1442,7 +1711,10 @@ "example": "C3SFG0O6N88R6UI7EQ" }, "error": { - "required": ["code", "message"], + "required": [ + "code", + "message" + ], "type": "object", "properties": { "code": { @@ -1513,15 +1785,24 @@ "content": { "application/json": { "schema": { - "required": ["data", "success", "traceId"], + "required": [ + "data", + "success", + "traceId" + ], "type": "object", "properties": { "data": { - "required": ["refId"], + "required": [ + "refId" + ], "type": "object", "properties": { "duplicate": { - "required": ["code", "message"], + "required": [ + "code", + "message" + ], "type": "object", "properties": { "code": { @@ -1541,8 +1822,60 @@ }, "refId": { "type": "string", - "description": "The generated BBPS Reference ID for the request.", - "example": "HENSVVR4QOS7X1UGPY7JGUV444P10102202" + "description": "The generated Reference ID for the request." + }, + "upmsRegistration": { + "type": "object", + "properties": { + "duplicate": { + "required": [ + "code", + "message" + ], + "type": "object", + "properties": { + "code": { + "type": "string" + }, + "message": { + "type": "string" + }, + "refId": { + "type": "string", + "description": "The generated Reference ID for the request." + } + } + }, + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "example": "invalid-mandate" + }, + "message": { + "type": "string", + "example": "The mandate configuration is invalid" + } + }, + "description": "Present only when acknowledgement status for the registration is FAILED" + }, + "refId": { + "type": "string", + "description": "The reference ID for the UPMS registration", + "example": "HENSVVR4QOS7X1UGPY7JGUV444P10102202" + }, + "status": { + "type": "string", + "description": "Status of the registration request processing by our system", + "example": "PENDING", + "enum": [ + "PENDING", + "FAILED" + ] + } + }, + "description": "Present only when upmsRegistration was requested" } } }, @@ -1566,7 +1899,11 @@ "content": { "application/json": { "schema": { - "required": ["error", "success", "traceId"], + "required": [ + "error", + "success", + "traceId" + ], "type": "object", "properties": { "traceId": { @@ -1574,7 +1911,10 @@ "example": "C3SFG0O6N88R6UI7EQ" }, "error": { - "required": ["code", "message"], + "required": [ + "code", + "message" + ], "type": "object", "properties": { "code": { @@ -1599,13 +1939,19 @@ }, "security": [ { - "Production": ["bbps:partner"] + "Production": [ + "bbps:partner" + ] }, { - "Sandbox": ["bbps:partner"] + "Sandbox": [ + "bbps:partner" + ] }, { - "QA": ["bbps:partner"] + "QA": [ + "bbps:partner" + ] } ], "x-codegen-request-body-name": "CouAgentBillPaymentRequestV2" @@ -1638,7 +1984,9 @@ "content": { "application/json": { "schema": { - "required": ["refId"], + "required": [ + "refId" + ], "type": "object", "properties": { "refId": { @@ -1704,36 +2052,122 @@ "content": { "application/json": { "schema": { - "required": ["data", "success", "traceId"], + "required": [ + "data", + "success", + "traceId" + ], "type": "object", "properties": { "data": { - "required": ["refId", "status"], + "required": [ + "refId", + "status" + ], "type": "object", "properties": { - "paymentDetails": { - "required": ["amount", "mode", "paymentRefId", "timestamp"], + "additionalInfo": { + "type": "array", + "description": "This tag captures the additional information provided by the Biller as part of response for a successful transaction.", + "items": { + "required": [ + "name", + "value" + ], + "type": "object", + "properties": { + "name": { + "type": "string", + "example": "Line item 1" + }, + "value": { + "type": "string", + "example": "Value 1" + } + } + }, + "x-go-name": "BillAdditionalInfo", + "x-omitempty": false + }, + "billerId": { + "type": "string", + "description": "The biller ID on BBPS", + "example": "MAHI00000NATIC" + }, + "billerRefId": { + "type": "string", + "example": "ZA6291A177" + }, + "bills": { + "uniqueItems": true, + "type": "array", + "nullable": true, + "example": "The bills paid in case of list billers", + "items": { + "required": [ + "amount", + "billNumber" + ], + "type": "object", + "properties": { + "amount": { + "minimum": 1, + "type": "integer", + "description": "Amount in Paise" + }, + "billNumber": { + "type": "string", + "example": "B1234567" + } + }, + "x-omitempty": true + }, + "x-omitempty": true + }, + "failureReason": { + "required": [ + "code", + "message" + ], "type": "object", "properties": { - "custConvFee": { - "type": "integer", - "nullable": true - }, - "paymentRefId": { - "maxLength": 35, - "minLength": 6, + "code": { "type": "string", - "example": "BD019181220291" + "example": "ERR004" }, - "timestamp": { + "message": { "type": "string", - "format": "date-time", - "example": "2020-12-12T13:12:00+05:30" + "example": "customer not found" }, + "type": { + "type": "string", + "enum": [ + "FUND_TRANSFER", + "BBPS", + "APP" + ] + } + } + }, + "lastPaidDate": { + "type": "string", + "format": "date-time", + "nullable": true, + "example": "2020-12-12T13:12:00+05:30" + }, + "paymentDetails": { + "required": ["amount", "mode", "paymentRefId", "timestamp"], + "type": "object", + "properties": { "COUcustConvFee": { "type": "integer", "nullable": true }, + "Id": { + "type": "string", + "description": "Pass here the ID of the selected payment plan in payment request. If a plan was selected in payment request, its Id will be a part of the paymentDetails block in payment response.", + "example": "1" + }, "accountInfo": { "maxLength": 50, "minLength": 1, @@ -1749,6 +2183,10 @@ "type": "integer", "nullable": true }, + "custConvFee": { + "type": "integer", + "nullable": true + }, "mode": { "type": "string", "example": "Internet Banking", @@ -1768,12 +2206,21 @@ "USSD" ] }, + "paymentRefId": { + "maxLength": 35, + "minLength": 6, + "type": "string", + "example": "BD019181220291" + }, "selectedPaymentOptions": { "type": "array", "description": "List of selected payment options", "nullable": true, "items": { - "required": ["amount", "name"], + "required": [ + "amount", + "name" + ], "type": "object", "properties": { "amount": { @@ -1784,103 +2231,37 @@ "name": { "type": "string", "description": "The name of the payment option as returned in bill fetch response.", - "example": "John Doe" + "example": "Early Payment Amount" } } }, "x-nullable": true, "x-omitempty": true + }, + "timestamp": { + "type": "string", + "format": "date-time", + "example": "2020-12-12T13:12:00+05:30" } } }, - "billerId": { + "refId": { "type": "string", - "description": "The biller ID on BBPS", - "example": "MAHI00000NATIC" - }, - "bills": { - "uniqueItems": true, - "type": "array", - "nullable": true, - "example": "The bills paid in case of list billers", - "items": { - "required": ["amount", "billNumber"], - "type": "object", - "properties": { - "billNumber": { - "type": "string", - "example": "B1234567" - }, - "amount": { - "minimum": 1, - "type": "integer", - "description": "Amount in Paise" - } - }, - "x-omitempty": true - }, - "x-omitempty": true - }, - "failureReason": { - "required": ["code", "message"], - "type": "object", - "properties": { - "message": { - "type": "string", - "example": "error-message-if-any" - }, - "type": { - "type": "string", - "enum": ["FUND_TRANSFER", "BBPS", "APP"] - }, - "code": { - "type": "string", - "example": "error-code-if-any" - } - } - }, - "lastPaidDate": { - "type": "string", - "format": "date-time", - "nullable": true, - "example": "2020-12-12T13:12:00+05:30" - }, - "refId": { - "type": "string", - "example": "HENSVVR4QOS7X1UGPY7JGUV444P10102202" + "example": "HENSVVR4QOS7X1UGPY7JGUV444P10102202" }, "status": { "type": "string", "example": "Success", - "enum": ["Processing", "Success", "Failure", "Credit_Adjustment"] + "enum": [ + "Processing", + "Success", + "Failure", + "Credit_Adjustment" + ] }, "transactionId": { "type": "string", "example": "AX30910192192192192" - }, - "additionalInfo": { - "type": "array", - "description": "This tag captures the additional information provided by the Biller as part of response for a successful transaction.", - "items": { - "required": ["name", "value"], - "type": "object", - "properties": { - "value": { - "type": "string", - "example": "Value 1" - }, - "name": { - "type": "string", - "example": "John Doe" - } - } - }, - "x-go-name": "BillAdditionalInfo", - "x-omitempty": false - }, - "billerRefId": { - "type": "string", - "example": "ZA6291A177" } } }, @@ -1904,30 +2285,37 @@ "content": { "application/json": { "schema": { - "required": ["error", "success", "traceId"], + "required": [ + "error", + "success", + "traceId" + ], "type": "object", "properties": { - "traceId": { - "type": "string", - "example": "C3SFG0O6N88R6UI7EQ" - }, "error": { - "required": ["code", "message"], + "required": [ + "code", + "message" + ], "type": "object", "properties": { "code": { "type": "string", - "example": "error-code-if-any" + "example": "validation-error" }, "message": { "type": "string", - "example": "error-message-if-any" + "example": "Input is invalid" } } }, "success": { "type": "boolean", "example": false + }, + "traceId": { + "type": "string", + "example": "C3SFG0O6N88R6UI7EQ" } } } @@ -1939,30 +2327,37 @@ "content": { "application/json": { "schema": { - "required": ["error", "success", "traceId"], + "required": [ + "error", + "success", + "traceId" + ], "type": "object", "properties": { - "traceId": { - "type": "string", - "example": "C3SFG0O6N88R6UI7EQ" - }, "error": { - "required": ["code", "message"], + "required": [ + "code", + "message" + ], "type": "object", "properties": { "code": { "type": "string", - "example": "error-code-if-any" + "example": "validation-error" }, "message": { "type": "string", - "example": "error-message-if-any" + "example": "Input is invalid" } } }, "success": { "type": "boolean", "example": false + }, + "traceId": { + "type": "string", + "example": "C3SFG0O6N88R6UI7EQ" } } } @@ -1972,13 +2367,19 @@ }, "security": [ { - "Production": ["bbps:partner"] + "Production": [ + "bbps:partner" + ] }, { - "Sandbox": ["bbps:partner"] + "Sandbox": [ + "bbps:partner" + ] }, { - "QA": ["bbps:partner"] + "QA": [ + "bbps:partner" + ] } ], "x-codegen-request-body-name": "CouAgentAsyncRequest" @@ -2013,7 +2414,10 @@ "schema": { "allOf": [ { - "required": ["description", "disputeType"], + "required": [ + "description", + "disputeType" + ], "type": "object", "properties": { "description": { @@ -2030,13 +2434,20 @@ "others", "amount-deducted-biller-credited-no-transaction-id", "amount-deducted-biller-not-credited-no-transaction-id", - "amount-deducted-multiple-times" + "amount-deducted-multiple-times", + "service-not-received", + "service-disconnected", + "late-payment-surcharge", + "wrong-amount", + "payment-info-delay" ] } } }, { - "required": ["transactionId"], + "required": [ + "transactionId" + ], "type": "object", "properties": { "transactionId": { @@ -2137,15 +2548,24 @@ "content": { "application/json": { "schema": { - "required": ["data", "success", "traceId"], + "required": [ + "data", + "success", + "traceId" + ], "type": "object", "properties": { "data": { - "required": ["refId"], + "required": [ + "refId" + ], "type": "object", "properties": { "duplicate": { - "required": ["code", "message"], + "required": [ + "code", + "message" + ], "type": "object", "properties": { "code": { @@ -2153,20 +2573,70 @@ "example": "error-code-if-any" }, "message": { - "type": "string", - "example": "error-message-if-any" + "type": "string" }, "refId": { "type": "string", - "description": "The generated BBPS Reference ID for the request.", - "example": "HENSVVR4QOS7X1UGPY7JGUV444P10102202" + "description": "The generated Reference ID for the request." } } }, "refId": { "type": "string", - "description": "The generated BBPS Reference ID for the request.", - "example": "HENSVVR4QOS7X1UGPY7JGUV444P10102202" + "description": "The generated Reference ID for the request." + }, + "upmsRegistration": { + "type": "object", + "properties": { + "duplicate": { + "required": [ + "code", + "message" + ], + "type": "object", + "properties": { + "code": { + "type": "string" + }, + "message": { + "type": "string" + }, + "refId": { + "type": "string", + "description": "The generated Reference ID for the request." + } + } + }, + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "example": "invalid-mandate" + }, + "message": { + "type": "string", + "example": "The mandate configuration is invalid" + } + }, + "description": "Present only when acknowledgement status for the registration is FAILED" + }, + "refId": { + "type": "string", + "description": "The reference ID for the UPMS registration", + "example": "HENSVVR4QOS7X1UGPY7JGUV444P10102202" + }, + "status": { + "type": "string", + "description": "Status of the registration request processing by our system", + "example": "PENDING", + "enum": [ + "PENDING", + "FAILED" + ] + } + }, + "description": "Present only when upmsRegistration was requested" } } }, @@ -2190,15 +2660,18 @@ "content": { "application/json": { "schema": { - "required": ["error", "success", "traceId"], + "required": [ + "error", + "success", + "traceId" + ], "type": "object", "properties": { - "traceId": { - "type": "string", - "example": "C3SFG0O6N88R6UI7EQ" - }, "error": { - "required": ["code", "message"], + "required": [ + "code", + "message" + ], "type": "object", "properties": { "code": { @@ -2214,6 +2687,10 @@ "success": { "type": "boolean", "example": false + }, + "traceId": { + "type": "string", + "example": "C3SFG0O6N88R6UI7EQ" } } } @@ -2223,13 +2700,19 @@ }, "security": [ { - "Production": ["bbps:partner"] + "Production": [ + "bbps:partner" + ] }, { - "Sandbox": ["bbps:partner"] + "Sandbox": [ + "bbps:partner" + ] }, { - "QA": ["bbps:partner"] + "QA": [ + "bbps:partner" + ] } ], "x-codegen-request-body-name": "CouAgentDisputeRequest" @@ -2262,7 +2745,9 @@ "content": { "application/json": { "schema": { - "required": ["refId"], + "required": [ + "refId" + ], "type": "object", "properties": { "refId": { @@ -2328,7 +2813,10 @@ "content": { "application/json": { "schema": { - "required": ["success", "traceId"], + "required": [ + "success", + "traceId" + ], "type": "object", "properties": { "data": { @@ -2339,6 +2827,19 @@ "type": "string", "example": "ICICI BOU" }, + "disposition": { + "type": "string", + "enum": [ + "D11", + "D12", + "D13", + "D21", + "D22", + "D23", + "D31", + "D32" + ] + }, "disputeId": { "type": "string", "example": "OP0121046567755" @@ -2352,6 +2853,10 @@ "type": "string", "example": "Resolved in favour of Biller" }, + "responseReason": { + "type": "string", + "example": "Ticket already IN-PROGRESS" + }, "status": { "type": "string", "description": "BBPS Complaint status", @@ -2360,7 +2865,23 @@ "ASSIGNED", "REJECTED", "RESOLVED", - "DEFAULT_RESOLVED" + "UNRESOLVED", + "REJECTED", + "DEFAULT_RESOLVED", + "REFUNDED", + "PENDING_REFUND" + ] + }, + "ticketTAT": { + "type": "string", + "format": "date", + "nullable": true + }, + "ticketType": { + "type": "string", + "enum": [ + "DISPUTE", + "COMPLAINT" ] } }, @@ -2386,7 +2907,11 @@ "content": { "application/json": { "schema": { - "required": ["error", "success", "traceId"], + "required": [ + "error", + "success", + "traceId" + ], "type": "object", "properties": { "traceId": { @@ -2394,7 +2919,10 @@ "example": "C3SFG0O6N88R6UI7EQ" }, "error": { - "required": ["code", "message"], + "required": [ + "code", + "message" + ], "type": "object", "properties": { "code": { @@ -2421,7 +2949,11 @@ "content": { "application/json": { "schema": { - "required": ["error", "success", "traceId"], + "required": [ + "error", + "success", + "traceId" + ], "type": "object", "properties": { "traceId": { @@ -2429,7 +2961,10 @@ "example": "C3SFG0O6N88R6UI7EQ" }, "error": { - "required": ["code", "message"], + "required": [ + "code", + "message" + ], "type": "object", "properties": { "code": { @@ -2454,23 +2989,30 @@ }, "security": [ { - "Production": ["bbps:partner"] + "Production": [ + "bbps:partner" + ] }, { - "Sandbox": ["bbps:partner"] + "Sandbox": [ + "bbps:partner" + ] }, { - "QA": ["bbps:partner"] + "QA": [ + "bbps:partner" + ] } ], "x-codegen-request-body-name": "CouAgentAsyncRequest" } }, - "/api/v2/bbps/disputes": { + "/api/v2/bbps/billers": { "get": { - "tags": ["List"], - "operationId": "getDisputes", - "description": "Returns the list of disputes.", + "tags": [ + "List" + ], + "description": "Returns the list of billers.", "parameters": [ { "name": "X-PARTNER-ID", @@ -2489,20 +3031,27 @@ "required": true }, { - "name": "status", + "name": "categoryName", + "in": "query", + "description": "Biller category. The query parameter follows a multi instance format. Usage: categoryName=category1&categoryName=category2", + "style": "form", + "explode": true, + "schema": { + "type": "array", + "items": { + "type": "string" + } + } + }, + { + "name": "ids", "in": "query", "style": "form", "explode": false, "schema": { "type": "array", "items": { - "type": "string", - "enum": [ - "ASSIGNED", - "REJECTED", - "RESOLVED", - "DEFAULT_RESOLVED" - ] + "type": "string" } } }, @@ -2511,158 +3060,140 @@ "in": "query", "description": "Limit", "schema": { - "maximum": 1000.0, + "maximum": 250.0, "minimum": 1.0, "type": "integer" } }, { - "name": "categories", + "name": "after", "in": "query", - "description": "Biller Category", - "style": "form", - "explode": false, "schema": { - "type": "array", - "items": { - "type": "string" - } + "type": "string" } }, { - "name": "months", + "name": "search", "in": "query", - "description": "Month ranges. A full-date notation as defined by 'RFC 3339, section 5.6' has to be provided but only month and year will be considered.", - "style": "form", - "explode": false, "schema": { - "type": "array", - "items": { - "type": "string", - "format": "date" - } + "type": "string" } }, { - "name": "after", + "name": "pincode", "in": "query", "schema": { "type": "string" } }, { - "name": "mobile", + "name": "city", "in": "query", - "description": "Mobile number with 6 to 22 digits are valid.", "schema": { - "maxLength": 22, - "minLength": 6, - "pattern": "^\\d{6,22}$", "type": "string" } }, { - "name": "customerId", + "name": "state", "in": "query", - "description": "Customer Identifier", "schema": { "type": "string" } }, { - "name": "transactionIds", + "name": "country", "in": "query", - "description": "Transaction IDs", - "style": "form", - "explode": false, "schema": { - "type": "array", - "items": { - "type": "string" - } + "type": "string" } }, { - "name": "paymentRefIds", + "name": "coverage", "in": "query", - "description": "Partner provided transaction Ids", - "style": "form", - "explode": false, "schema": { - "type": "array", - "items": { - "maxLength": 35, - "minLength": 6, - "type": "string" - } + "type": "string" } }, { - "name": "billerIds", + "name": "tags", + "in": "query", + "schema": { + "type": "string" + } + }, + { + "name": "paymentChannel", "in": "query", - "description": "The biller ID on BBPS", "style": "form", "explode": false, "schema": { "type": "array", "items": { - "type": "string" + "type": "string", + "enum": [ + "INT", + "INTB", + "MOB", + "BNKBRNCH", + "BSC", + "AGT", + "KIOSK", + "ATM", + "MOBB", + "POS", + "MPOS" + ] } } }, { - "name": "expand", + "name": "paymentMode", "in": "query", "style": "form", "explode": false, "schema": { - "uniqueItems": true, "type": "array", "items": { "type": "string", - "enum": ["BILLER", "TRANSACTION"] + "enum": [ + "Internet Banking", + "Debit Card", + "Credit Card", + "Prepaid Card", + "IMPS", + "Cash", + "UPI", + "Wallet", + "NEFT", + "AEPS", + "Account Transfer", + "Bharat QR", + "USSD" + ] } } + }, + { + "name": "updatedSince", + "in": "query", + "description": "Used to fetch billers updated since the given date-time in IST", + "schema": { + "type": "string", + "format": "date-time" + } + }, + { + "name": "upmsEnabled", + "in": "query", + "description": "Filter billers by UPMS enabled status", + "schema": { + "type": "boolean" + } } ], "responses": { - "500": { - "description": "Bad request", - "content": { - "application/json": { - "schema": { - "required": ["error", "success", "traceId"], - "type": "object", - "properties": { - "traceId": { - "type": "string", - "example": "C3SFG0O6N88R6UI7EQ" - }, - "error": { - "required": ["code", "message"], - "type": "object", - "properties": { - "code": { - "type": "string", - "example": "error-code-if-any" - }, - "message": { - "type": "string", - "example": "error-message-if-any" - } - } - }, - "success": { - "type": "boolean", - "example": false - } - } - } - } - } - }, "200": { - "description": "List of disputes", + "description": "List of billers", "headers": { "X-Frame-Options": { "description": "X Frame options", @@ -2710,1282 +3241,514 @@ "content": { "application/json": { "schema": { - "allOf": [ - { - "required": ["success", "traceId"], - "type": "object", - "properties": { - "success": { - "type": "boolean", - "example": true - }, - "traceId": { - "type": "string", - "example": "C3SFG0O6N88R6UI7EQ" - } - } - }, - { + "required": [ + "success", + "traceId" + ], + "type": "object", + "properties": { + "data": { + "required": [ + "billers" + ], "type": "object", "properties": { - "data": { - "required": ["disputes"], - "type": "object", - "properties": { - "disputes": { - "type": "array", - "items": { - "allOf": [ - { - "type": "object", - "properties": { - "lastModifiedAt": { - "type": "string", - "description": "Dispute's last modified timestamp", - "format": "date-time", - "example": "2020-12-12T13:12:00+05:30" - }, - "refId": { - "type": "string", - "description": "The generated BBPS Reference ID for the request.", - "example": "HENSVVR4QOS7X1UGPY7JGUV444P10102202" - }, - "responseCode": { - "type": "string", - "example": "ADIT00000NATRA" - }, - "transactionId": { - "type": "string", - "description": "Setu BillPay Transaction ID.", - "example": "AS01910192192192192" - }, - "assigned": { - "type": "string", - "example": "ADIT00000NATRA" - }, - "complaintStatus": { - "type": "string", - "description": "BBPS Complaint status", - "example": "ASSIGNED", - "enum": [ - "ASSIGNED", - "REJECTED", - "RESOLVED", - "DEFAULT_RESOLVED" - ] - }, - "createdAt": { - "type": "string", - "description": "Dispute's creation timestamp", - "format": "date-time", - "example": "2020-12-12T13:12:00+05:30" - }, - "customerId": { - "type": "string", - "description": "Customer Identifier", - "example": "4881317598" - }, - "remarks": { - "type": "string", - "example": "ADIT00000NATRA" - }, - "responseReason": { - "type": "string", - "example": "ADIT00000NATRA" - }, - "biller": { - "required": [ - "categoryName", - "customerParams", - "exactness", - "fetchApiType", - "id", - "name", - "payWithoutFetchAllowed", - "paymentChannels", - "paymentModes", - "supportsPendingStatus" - ], - "type": "object", - "properties": { - "country": { - "type": "string", - "example": "IND" - }, - "modifiedAt": { - "type": "string", - "format": "date-time", - "nullable": true, - "example": "2021-11-12T13:37:04.572+05:30", - "x-omitempty": false - }, - "responseType": { - "type": "string", - "nullable": true, - "example": "SINGLE", - "enum": [ - "SINGLE", - "LIST", - "SELECTIVE" - ], - "x-nullable": true, - "x-omitempty": false - }, - "subCategoryName": { - "type": "string", - "example": "DAIRY" - }, - "coverage": { - "type": "string", - "example": "IND-TEL-Hyderabad" - }, - "interchangeFee": { - "type": "array", - "items": { - "type": "object", - "properties": { - "feeCode": { - "type": "string", - "example": "CCF1" - }, - "feeDesc": { - "type": "string", - "example": "Customer Convenience Fee" - }, - "feeDirection": { - "type": "string", - "example": "C2B" - }, - "interchangeFeeDetails": { - "required": [ - "effctvFrom", - "effctvTo", - "flatFee", - "percentFee", - "tranAmtRangeMax", - "tranAmtRangeMin" - ], - "type": "object", - "properties": { - "percentFee": { - "type": "number", - "format": "decimal", - "example": 1.0 - }, - "tranAmtRangeMax": { - "type": "integer", - "format": "int64" - }, - "tranAmtRangeMin": { - "type": "integer", - "format": "int64" - }, - "effctvFrom": { - "type": "string", - "example": "2024-01-01" - }, - "effctvTo": { - "type": "string", - "example": "2024-12-31" - }, - "flatFee": { - "type": "number", - "format": "decimal", - "example": 0.0 - } - } - } - } - } - }, - "selectionType": { - "type": "string", - "description": "Defined only for billers with response type as LIST. SINGLE: User can pay only one of the bills in bill fetch response. MULTIPLE: User can pay any combination of bills in bill fetch response. ALL: User has to pay all the bills in bill fetch response.", - "nullable": true, - "example": "SINGLE", - "enum": [ - "SINGLE", - "MULTIPLE", - "ALL" - ], - "x-omitempty": false, - "x-nullable": true - }, - "pincode": { - "type": "string", - "example": "pincode" - }, - "supportsPendingStatus": { - "type": "boolean", - "description": "Flag indicating whether pending status is applicable for the biller or not", - "example": false - }, - "tags": { - "type": "string", - "example": "tags" - }, - "billerAdditionalInfoPayment": { - "type": "array", - "items": { - "required": [ - "dataType", - "optional", - "paramName" - ], - "type": "object", - "properties": { - "dataType": { - "type": "string", - "example": "ALPHANUMERIC", - "enum": [ - "ALPHANUMERIC", - "NUMERIC" - ] - }, - "optional": { - "type": "boolean", - "example": false - }, - "paramName": { - "type": "string", - "example": "Package Duration" - } - } - } - }, - "customerParams": { - "type": "array", - "items": { - "required": [ - "dataType", - "maxLength", - "minLength", - "optional", - "paramName", - "regex", - "values", - "visibility" - ], - "type": "object", - "properties": { - "paramName": { - "type": "string", - "example": "Loan Account Number" - }, - "regex": { - "type": "string", - "example": "^[a-zA-Z0-9]{7,15}" - }, - "values": { - "type": "string" - }, - "visibility": { - "type": "boolean", - "example": true - }, - "dataType": { - "type": "string", - "example": "ALPHANUMERIC" - }, - "maxLength": { - "type": "integer" - }, - "minLength": { - "type": "integer" - }, - "optional": { - "type": "boolean", - "example": false - } - } - } - }, - "customerParamsGroups": { - "type": "array", - "items": { - "type": "array", - "items": { - "type": "string", - "example": "Param 1" - } - } - }, - "id": { - "type": "string", - "description": "Identifier of the biller in BBPS.", - "example": "ADIT00000NAT0T" - }, - "createdAt": { - "type": "string", - "format": "date-time", - "nullable": true, - "example": "2021-11-12T13:37:04.572+05:30", - "x-omitempty": false - }, - "exactness": { - "type": "string", - "example": "Exact", - "enum": [ - "Exact", - "Exact and above", - "Exact and below", - "Any", - "RANGE" - ] - }, - "fetchApiType": { - "type": "string", - "enum": [ - "BILL_FETCH", - "BILL_VALIDATE", - "BILL_DIRECT" - ] - }, - "bbpsUpdateTimestamp": { - "type": "string", - "description": "Last updated date-time of the Biller accurate to the nearest day.", - "format": "date-time", - "nullable": true, - "example": "2021-11-12T13:37:04.572+05:30", - "x-omitempty": true - }, - "logo": { - "type": "string", - "example": "logo" - }, - "plans": { - "type": "array", - "nullable": true, - "items": { - "required": [ - "amount", - "categoryType", - "description", - "id", - "status" - ], - "type": "object", - "properties": { - "effectiveTo": { - "type": "string", - "description": "Effective to date of corresponding Plan.", - "format": "date", - "nullable": true, - "example": "2020-08-21", - "x-omitempty": false - }, - "amount": { - "type": "string", - "example": "22.0" - }, - "effectiveFrom": { - "type": "string", - "description": "Effective from date of corresponding Plan.", - "format": "date", - "nullable": true, - "example": "2017-07-21", - "x-omitempty": false - }, - "categoryType": { - "type": "string", - "description": "Plan category as defined by the Biller.", - "example": "VIP" - }, - "description": { - "type": "string", - "description": "Plan description as defined by the Biller.", - "example": "Unlimited Live Sports" - }, - "id": { - "type": "string", - "description": "Plan ID", - "example": "1.0" - }, - "status": { - "type": "string", - "description": "Effective to date of corresponding Plan.", - "example": "ACTIVE", - "enum": [ - "ACTIVE", - "DEACTIVATED" - ] - }, - "additionalInfo": { - "minItems": 1, - "type": "array", - "description": "Plan Additional information details provided by the Biller.", - "example": [ - { - "paramName": "Mobile Number", - "paramValue": "Text" - } - ], - "items": { - "type": "object", - "properties": { - "paramName": { - "type": "string", - "example": "Plan Additional information parameter name." - }, - "paramValue": { - "type": "string", - "example": "Plan Additional information parameter value." - } - }, - "example": { - "paramName": "Mobile Number", - "paramValue": "Text" - }, - "x-go-name": "PlanAdditionalInfoItem" - }, - "x-omitempty": true - }, - "categorySubType": { - "type": "object", - "properties": {}, - "description": "Plan sub category as defined by the Biller.", - "example": { - "subType": "1 Month" - }, - "x-omitempty": true - } - } - }, - "x-omitempty": true - }, - "paymentModes": { - "type": "array", - "items": { - "required": [ - "maxLimit", - "minLimit", - "paymentMode", - "supportsPendingStatus" - ], - "type": "object", - "properties": { - "maxLimit": { - "type": "integer" - }, - "minLimit": { - "type": "integer" - }, - "paymentMode": { - "type": "string", - "example": "Internet Banking", - "enum": [ - "Internet Banking", - "Debit Card", - "Credit Card", - "Prepaid Card", - "IMPS", - "Cash", - "UPI", - "Wallet", - "NEFT", - "AEPS", - "Account Transfer", - "Bharat QR", - "USSD" - ] - }, - "supportsPendingStatus": { - "type": "boolean", - "example": false - } - } - } - }, - "categoryName": { - "type": "string", - "description": "Biller Category", - "example": "loan-repayment" - }, - "city": { - "type": "string", - "example": "Hyderabad" - }, - "enforcesSameDayFetchPay": { - "type": "boolean", - "example": true, - "x-omitempty": false - }, - "name": { - "type": "string", - "description": "Name of the biller.", - "example": "John Doe" - }, - "billerAdditionalInfo": { - "type": "array", - "items": { - "required": [ - "dataType", - "optional", - "paramName" - ], - "type": "object", - "properties": { - "dataType": { - "type": "string", - "example": "ALPHANUMERIC", - "enum": [ - "ALPHANUMERIC", - "NUMERIC" - ] - }, - "optional": { - "type": "boolean", - "example": false - }, - "paramName": { - "type": "string", - "example": "Package Duration" - } - } - } - }, - "payWithoutFetchAllowed": { - "type": "boolean", - "description": "Flag indicating if the Biller accepts adhoc payment", - "example": true - }, - "paymentChannels": { - "type": "array", - "items": { - "required": [ - "maxLimit", - "minLimit", - "paymentChannel", - "supportsPendingStatus" - ], - "type": "object", - "properties": { - "paymentChannel": { - "type": "string", - "description": "This is the initiating channel.\n1. `AGT`: Offline agent.\n2. `BNKBRNCH`: Bank branch.\n3. `BSC`: Business correspondent\n4. `MOB`: Mobile application\n5. `INT`: Internet portal\n6. `INTB`: Internet banking\n7. `MOBB`: Mobile banking\n8. `ATM`: ATM\n9. `KIOSK`: KIOSK\n", - "example": "INT", - "enum": [ - "INT", - "INTB", - "MOB", - "BNKBRNCH", - "BSC", - "AGT", - "KIOSK", - "ATM", - "MOBB", - "POS", - "MPOS" - ] - }, - "supportsPendingStatus": { - "type": "boolean", - "example": false - }, - "maxLimit": { - "type": "integer" - }, - "minLimit": { - "type": "integer" - } - } - } - }, - "state": { - "type": "string", - "example": "TEL" - } - }, - "x-go-name": "CouBillerDetails" - }, - "billerId": { - "type": "string", - "description": "The biller ID on BBPS", - "example": "MAHI00000NATIC" - }, - "complaintId": { - "type": "string", - "example": "Loan Repayment" - } - } - }, - { - "type": "object", - "properties": { - "mobile": { - "maxLength": 22, - "minLength": 6, - "pattern": "^\\d{6,22}$", - "type": "string", - "description": "Mobile number with 6 to 22 digits are valid." - }, - "paymentRefID": { - "maxLength": 35, - "minLength": 6, - "type": "string", - "description": "Unique identifier provided by Partner for the payment request.", - "example": "BD019181220291" - }, - "transaction": { - "allOf": [ - { - "type": "object", - "properties": { - "customerId": { - "type": "string", - "description": "Customer Identifier", - "example": "4881317598" - }, - "refId": { - "type": "string", - "description": "The generated BBPS Reference ID for the request.", - "example": "HENSVVR4QOS7X1UGPY7JGUV444P10102202" - }, - "status": { - "type": "string", - "example": "Success", - "enum": [ - "Processing", - "Success", - "Error", - "Credit_Adjustment" - ] - }, - "amount": { - "type": "integer" - }, - "custConvFee": { - "type": "integer", - "description": "Customer convenience fee in paise" - }, - "customerParams": { - "type": "array", - "description": "The bill params for fetching the bill", - "items": { - "required": [ - "name", - "value" - ], - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "The display name of the parameter. This has to match what is sent in fields.", - "example": "John Doe" - }, - "value": { - "type": "string", - "description": "The value of the customer parameter", - "example": "1895159" - } - } - } - }, - "etherealTransaction": { - "required": [ - "amount", - "billRefId", - "refId", - "status", - "transactionId" - ], - "type": "object", - "properties": { - "amount": { - "type": "string", - "example": "100.00" - }, - "billRefId": { - "type": "string", - "description": "The BBPS Ref ID", - "example": "C3SFG0O6N88R6UI7EQ" - }, - "refId": { - "type": "string", - "example": "COUWL910192192192192" - }, - "status": { - "type": "string", - "enum": [ - "INIT", - "SUCCESS", - "FAILURE", - "PENDING", - "UNKNOWN" - ] - }, - "transactionId": { - "type": "string", - "example": "Q910192192192192" - } - } - }, - "refundStatus": { - "type": "string", - "enum": [ - "Required", - "Requested", - "Processed" - ] - }, - "timestamp": { - "type": "string", - "description": "Timestamp provided by partner while making payment request.", - "format": "date-time", - "example": "2020-12-12T13:12:00+05:30" - }, - "transactionId": { - "type": "string", - "description": "Setu BillPay Transaction ID.", - "example": "AS01910192192192192" - }, - "biller": { - "required": [ - "categoryName", - "customerParams", - "exactness", - "fetchApiType", - "id", - "name", - "payWithoutFetchAllowed", - "paymentChannels", - "paymentModes", - "supportsPendingStatus" - ], - "type": "object", - "properties": { - "country": { - "type": "string", - "example": "IND" - }, - "modifiedAt": { - "type": "string", - "format": "date-time", - "nullable": true, - "example": "2021-11-12T13:37:04.572+05:30", - "x-omitempty": false - }, - "responseType": { - "type": "string", - "nullable": true, - "example": "SINGLE", - "enum": [ - "SINGLE", - "LIST", - "SELECTIVE" - ], - "x-nullable": true, - "x-omitempty": false - }, - "subCategoryName": { - "type": "string", - "example": "DAIRY" - }, - "coverage": { - "type": "string", - "example": "IND-TEL-Hyderabad" - }, - "interchangeFee": { - "type": "array", - "items": { - "type": "object", - "properties": { - "feeCode": { - "type": "string", - "example": "CCF1" - }, - "feeDesc": { - "type": "string", - "example": "Customer Convenience Fee" - }, - "feeDirection": { - "type": "string", - "example": "C2B" - }, - "interchangeFeeDetails": { - "required": [ - "effctvFrom", - "effctvTo", - "flatFee", - "percentFee", - "tranAmtRangeMax", - "tranAmtRangeMin" - ], - "type": "object", - "properties": { - "percentFee": { - "type": "number", - "format": "decimal", - "example": 1.0 - }, - "tranAmtRangeMax": { - "type": "integer", - "format": "int64" - }, - "tranAmtRangeMin": { - "type": "integer", - "format": "int64" - }, - "effctvFrom": { - "type": "string", - "example": "2024-01-01" - }, - "effctvTo": { - "type": "string", - "example": "2024-12-31" - }, - "flatFee": { - "type": "number", - "format": "decimal", - "example": 0.0 - } - } - } - } - } - }, - "selectionType": { - "type": "string", - "description": "Defined only for billers with response type as LIST. SINGLE: User can pay only one of the bills in bill fetch response. MULTIPLE: User can pay any combination of bills in bill fetch response. ALL: User has to pay all the bills in bill fetch response.", - "nullable": true, - "example": "SINGLE", - "enum": [ - "SINGLE", - "MULTIPLE", - "ALL" - ], - "x-omitempty": false, - "x-nullable": true - }, - "pincode": { - "type": "string", - "example": "pincode" - }, - "supportsPendingStatus": { - "type": "boolean", - "description": "Flag indicating whether pending status is applicable for the biller or not", - "example": false - }, - "tags": { - "type": "string", - "example": "tags" - }, - "billerAdditionalInfoPayment": { - "type": "array", - "items": { - "required": [ - "dataType", - "optional", - "paramName" - ], - "type": "object", - "properties": { - "dataType": { - "type": "string", - "example": "ALPHANUMERIC", - "enum": [ - "ALPHANUMERIC", - "NUMERIC" - ] - }, - "optional": { - "type": "boolean", - "example": false - }, - "paramName": { - "type": "string", - "example": "Package Duration" - } - } - } - }, - "customerParams": { - "type": "array", - "items": { - "required": [ - "dataType", - "maxLength", - "minLength", - "optional", - "paramName", - "regex", - "values", - "visibility" - ], - "type": "object", - "properties": { - "paramName": { - "type": "string", - "example": "Loan Account Number" - }, - "regex": { - "type": "string", - "example": "^[a-zA-Z0-9]{7,15}" - }, - "values": { - "type": "string" - }, - "visibility": { - "type": "boolean", - "example": true - }, - "dataType": { - "type": "string", - "example": "ALPHANUMERIC" - }, - "maxLength": { - "type": "integer" - }, - "minLength": { - "type": "integer" - }, - "optional": { - "type": "boolean", - "example": false - } - } - } - }, - "customerParamsGroups": { - "type": "array", - "items": { - "type": "array", - "items": { - "type": "string", - "example": "Param 1" - } - } - }, - "id": { - "type": "string", - "description": "Identifier of the biller in BBPS.", - "example": "ADIT00000NAT0T" - }, - "createdAt": { - "type": "string", - "format": "date-time", - "nullable": true, - "example": "2021-11-12T13:37:04.572+05:30", - "x-omitempty": false - }, - "exactness": { - "type": "string", - "example": "Exact", - "enum": [ - "Exact", - "Exact and above", - "Exact and below", - "Any", - "RANGE" - ] - }, - "fetchApiType": { - "type": "string", - "enum": [ - "BILL_FETCH", - "BILL_VALIDATE", - "BILL_DIRECT" - ] - }, - "bbpsUpdateTimestamp": { - "type": "string", - "description": "Last updated date-time of the Biller accurate to the nearest day.", - "format": "date-time", - "nullable": true, - "example": "2021-11-12T13:37:04.572+05:30", - "x-omitempty": true - }, - "logo": { - "type": "string", - "example": "logo" - }, - "plans": { - "type": "array", - "nullable": true, - "items": { - "required": [ - "amount", - "categoryType", - "description", - "id", - "status" - ], - "type": "object", - "properties": { - "effectiveTo": { - "type": "string", - "description": "Effective to date of corresponding Plan.", - "format": "date", - "nullable": true, - "example": "2020-08-21", - "x-omitempty": false - }, - "amount": { - "type": "string", - "example": "22.0" - }, - "effectiveFrom": { - "type": "string", - "description": "Effective from date of corresponding Plan.", - "format": "date", - "nullable": true, - "example": "2017-07-21", - "x-omitempty": false - }, - "categoryType": { - "type": "string", - "description": "Plan category as defined by the Biller.", - "example": "VIP" - }, - "description": { - "type": "string", - "description": "Plan description as defined by the Biller.", - "example": "Unlimited Live Sports" - }, - "id": { - "type": "string", - "description": "Plan ID", - "example": "1.0" - }, - "status": { - "type": "string", - "description": "Effective to date of corresponding Plan.", - "example": "ACTIVE", - "enum": [ - "ACTIVE", - "DEACTIVATED" - ] - }, - "additionalInfo": { - "minItems": 1, - "type": "array", - "description": "Plan Additional information details provided by the Biller.", - "example": [ - { - "paramName": "Mobile Number", - "paramValue": "Text" - } - ], - "items": { - "type": "object", - "properties": { - "paramName": { - "type": "string", - "example": "Plan Additional information parameter name." - }, - "paramValue": { - "type": "string", - "example": "Plan Additional information parameter value." - } - }, - "example": { - "paramName": "Mobile Number", - "paramValue": "Text" - }, - "x-go-name": "PlanAdditionalInfoItem" - }, - "x-omitempty": true - }, - "categorySubType": { - "type": "object", - "properties": {}, - "description": "Plan sub category as defined by the Biller.", - "example": { - "subType": "1 Month" - }, - "x-omitempty": true - } - } - }, - "x-omitempty": true - }, - "paymentModes": { - "type": "array", - "items": { - "required": [ - "maxLimit", - "minLimit", - "paymentMode", - "supportsPendingStatus" - ], - "type": "object", - "properties": { - "maxLimit": { - "type": "integer" - }, - "minLimit": { - "type": "integer" - }, - "paymentMode": { - "type": "string", - "example": "Internet Banking", - "enum": [ - "Internet Banking", - "Debit Card", - "Credit Card", - "Prepaid Card", - "IMPS", - "Cash", - "UPI", - "Wallet", - "NEFT", - "AEPS", - "Account Transfer", - "Bharat QR", - "USSD" - ] - }, - "supportsPendingStatus": { - "type": "boolean", - "example": false - } - } - } - }, - "categoryName": { - "type": "string", - "description": "Biller Category", - "example": "loan-repayment" - }, - "city": { - "type": "string", - "example": "Hyderabad" - }, - "enforcesSameDayFetchPay": { - "type": "boolean", - "example": true, - "x-omitempty": false - }, - "name": { - "type": "string", - "description": "Name of the biller.", - "example": "John Doe" - }, - "billerAdditionalInfo": { - "type": "array", - "items": { - "required": [ - "dataType", - "optional", - "paramName" - ], - "type": "object", - "properties": { - "dataType": { - "type": "string", - "example": "ALPHANUMERIC", - "enum": [ - "ALPHANUMERIC", - "NUMERIC" - ] - }, - "optional": { - "type": "boolean", - "example": false - }, - "paramName": { - "type": "string", - "example": "Package Duration" - } - } - } - }, - "payWithoutFetchAllowed": { - "type": "boolean", - "description": "Flag indicating if the Biller accepts adhoc payment", - "example": true - }, - "paymentChannels": { - "type": "array", - "items": { - "required": [ - "maxLimit", - "minLimit", - "paymentChannel", - "supportsPendingStatus" - ], - "type": "object", - "properties": { - "paymentChannel": { - "type": "string", - "description": "This is the initiating channel.\n1. `AGT`: Offline agent.\n2. `BNKBRNCH`: Bank branch.\n3. `BSC`: Business correspondent\n4. `MOB`: Mobile application\n5. `INT`: Internet portal\n6. `INTB`: Internet banking\n7. `MOBB`: Mobile banking\n8. `ATM`: ATM\n9. `KIOSK`: KIOSK\n", - "example": "INT", - "enum": [ - "INT", - "INTB", - "MOB", - "BNKBRNCH", - "BSC", - "AGT", - "KIOSK", - "ATM", - "MOBB", - "POS", - "MPOS" - ] - }, - "supportsPendingStatus": { - "type": "boolean", - "example": false - }, - "maxLimit": { - "type": "integer" - }, - "minLimit": { - "type": "integer" - } - } - } - }, - "state": { - "type": "string", - "example": "TEL" - } - }, - "x-go-name": "CouBillerDetails" - }, - "billerId": { - "type": "string", - "description": "The biller ID on BBPS", - "example": "MAHI00000NATIC" - } - } - }, - { - "type": "object", - "properties": { - "mobile": { - "maxLength": 22, - "minLength": 6, - "pattern": "^\\d{6,22}$", - "type": "string", - "description": "Mobile number with 6 to 22 digits are valid." - }, - "paymentRefId": { - "maxLength": 35, - "minLength": 6, - "type": "string", - "description": "Unique identifier provided by Partner for the payment request.", - "example": "BD019181220291" - } - } - } - ] + "billers": { + "type": "array", + "items": { + "required": [ + "categoryName", + "customerParams", + "exactness", + "fetchApiType", + "id", + "name", + "payWithoutFetchAllowed", + "paymentChannels", + "paymentModes", + "supportsPendingStatus" + ], + "type": "object", + "properties": { + "bbpsUpdateTimestamp": { + "type": "string", + "description": "Last updated date-time of the Biller accurate to the nearest day.", + "format": "date-time", + "nullable": true, + "example": "2021-11-12T13:37:04.572+05:30", + "x-omitempty": true + }, + "billerAdditionalInfo": { + "type": "array", + "items": { + "required": [ + "dataType", + "optional", + "paramName" + ], + "type": "object", + "properties": { + "dataType": { + "type": "string", + "example": "ALPHANUMERIC", + "enum": [ + "ALPHANUMERIC", + "NUMERIC" + ] + }, + "optional": { + "type": "boolean", + "example": false + }, + "paramName": { + "type": "string", + "example": "Package Duration" + } + } + } + }, + "billerAdditionalInfoPayment": { + "type": "array", + "items": { + "required": [ + "dataType", + "optional", + "paramName" + ], + "type": "object", + "properties": { + "dataType": { + "type": "string", + "example": "ALPHANUMERIC", + "enum": [ + "ALPHANUMERIC", + "NUMERIC" + ] + }, + "optional": { + "type": "boolean", + "example": false + }, + "paramName": { + "type": "string", + "example": "Package Duration" + } + } + } + }, + "categoryName": { + "type": "string", + "description": "Biller Category", + "example": "loan-repayment" + }, + "city": { + "type": "string", + "example": "Hyderabad" + }, + "country": { + "type": "string", + "example": "IND" + }, + "coverage": { + "type": "string", + "example": "IND-TEL-Hyderabad" + }, + "createdAt": { + "type": "string", + "format": "date-time", + "nullable": true, + "example": "2021-11-12T13:37:04.572+05:30", + "x-omitempty": false + }, + "customerParams": { + "type": "array", + "items": { + "required": [ + "dataType", + "maxLength", + "minLength", + "optional", + "paramName", + "regex", + "values", + "visibility" + ], + "type": "object", + "properties": { + "dataType": { + "type": "string", + "example": "ALPHANUMERIC" + }, + "maxLength": { + "type": "integer" + }, + "minLength": { + "type": "integer" + }, + "optional": { + "type": "boolean", + "example": false + }, + "paramName": { + "type": "string", + "example": "Loan Account Number" + }, + "regex": { + "type": "string", + "example": "^[a-zA-Z0-9]{7,15}" + }, + "values": { + "type": "string", + "example": "CHOICE1,CHOICE2,CHOICE3" + }, + "visibility": { + "type": "boolean", + "example": true + } + } + } + }, + "customerParamsGroups": { + "type": "array", + "items": { + "type": "array", + "items": { + "type": "string", + "example": "Param 1" + } + } + }, + "enforcesSameDayFetchPay": { + "type": "boolean", + "example": true, + "x-omitempty": false + }, + "exactness": { + "type": "string", + "example": "Exact", + "enum": [ + "Exact", + "Exact and above", + "Exact and below", + "Any", + "RANGE" + ] + }, + "fetchApiType": { + "type": "string", + "enum": [ + "BILL_FETCH", + "BILL_VALIDATE", + "BILL_DIRECT" + ] + }, + "id": { + "type": "string", + "description": "Identifier of the biller in BBPS.", + "example": "ADIT00000NAT0T" + }, + "interchangeFee": { + "type": "array", + "items": { + "type": "object", + "properties": { + "feeCode": { + "type": "string", + "example": "CCF1" + }, + "feeDesc": { + "type": "string", + "example": "Customer Convenience Fee" + }, + "feeDirection": { + "type": "string", + "example": "C2B" + }, + "interchangeFeeDetails": { + "required": [ + "effctvFrom", + "effctvTo", + "flatFee", + "percentFee", + "tranAmtRangeMax", + "tranAmtRangeMin" + ], + "type": "object", + "properties": { + "effctvFrom": { + "type": "string", + "example": "2024-01-01" + }, + "effctvTo": { + "type": "string", + "example": "2024-12-31" + }, + "flatFee": { + "type": "number", + "format": "decimal", + "example": 0.0 + }, + "percentFee": { + "type": "number", + "format": "decimal", + "example": 1.0 + }, + "tranAmtRangeMax": { + "type": "integer", + "format": "int64" + }, + "tranAmtRangeMin": { + "type": "integer", + "format": "int64" + } } } } - ] + } + }, + "logo": { + "type": "string", + "example": "logo" + }, + "modifiedAt": { + "type": "string", + "format": "date-time", + "nullable": true, + "example": "2021-11-12T13:37:04.572+05:30", + "x-omitempty": false + }, + "name": { + "type": "string", + "description": "Name of the biller.", + "example": "Umbrella Corporation" + }, + "payWithoutFetchAllowed": { + "type": "boolean", + "description": "Flag indicating if the Biller accepts adhoc payment", + "example": true + }, + "paymentChannels": { + "type": "array", + "items": { + "required": [ + "maxLimit", + "minLimit", + "paymentChannel", + "supportsPendingStatus" + ], + "type": "object", + "properties": { + "maxLimit": { + "type": "integer" + }, + "minLimit": { + "type": "integer" + }, + "paymentChannel": { + "type": "string", + "description": "This is the initiating channel.\n1. `AGT`: Offline agent.\n2. `BNKBRNCH`: Bank branch.\n3. `BSC`: Business correspondent\n4. `MOB`: Mobile application\n5. `INT`: Internet portal\n6. `INTB`: Internet banking\n7. `MOBB`: Mobile banking\n8. `ATM`: ATM\n9. `KIOSK`: KIOSK\n", + "example": "INT", + "enum": [ + "INT", + "INTB", + "MOB", + "BNKBRNCH", + "BSC", + "AGT", + "KIOSK", + "ATM", + "MOBB", + "POS", + "MPOS" + ] + }, + "supportsPendingStatus": { + "type": "boolean", + "example": false + } + } + } + }, + "paymentModes": { + "type": "array", + "items": { + "required": [ + "maxLimit", + "minLimit", + "paymentMode", + "supportsPendingStatus" + ], + "type": "object", + "properties": { + "maxLimit": { + "type": "integer" + }, + "minLimit": { + "type": "integer" + }, + "paymentMode": { + "type": "string", + "example": "Internet Banking", + "enum": [ + "Internet Banking", + "Debit Card", + "Credit Card", + "Prepaid Card", + "IMPS", + "Cash", + "UPI", + "Wallet", + "NEFT", + "AEPS", + "Account Transfer", + "Bharat QR", + "USSD" + ] + }, + "supportsPendingStatus": { + "type": "boolean", + "example": false + } + } + } + }, + "planRequirement": { + "type": "string", + "description": "Indicates if plan selection is required for bill payments", + "example": "MANDATORY", + "enum": [ + "MANDATORY", + "OPTIONAL", + "CONDITIONAL" + ], + "x-omitempty": true + }, + "responseType": { + "type": "string", + "nullable": true, + "example": "SINGLE", + "enum": [ + "SINGLE", + "LIST", + "SELECTIVE" + ], + "x-nullable": true, + "x-omitempty": false + }, + "selectionType": { + "type": "string", + "description": "Defined only for billers with response type as LIST. SINGLE: User can pay only one of the bills in bill fetch response. MULTIPLE: User can pay any combination of bills in bill fetch response. ALL: User has to pay all the bills in bill fetch response.", + "nullable": true, + "example": "SINGLE", + "enum": [ + "SINGLE", + "MULTIPLE", + "ALL" + ], + "x-nullable": true, + "x-omitempty": false + }, + "state": { + "type": "string", + "example": "TEL" + }, + "subCategoryName": { + "type": "string", + "example": "DAIRY" + }, + "supportsPendingStatus": { + "type": "boolean", + "description": "Flag indicating whether pending status is applicable for the biller or not", + "example": false + }, + "tags": { + "type": "string", + "example": "tags" + }, + "upmsBillerParams": { + "type": "array", + "description": "UPMS-specific biller parameters", + "items": { + "required": [ + "name" + ], + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "UPMS parameter name", + "example": "mandateType" + }, + "value": { + "type": "string", + "description": "UPMS parameter value", + "example": "DEBIT", + "x-omitempty": true + } + } + }, + "x-omitempty": true + }, + "upmsBillerType": { + "type": "string", + "description": "Type of UPMS biller", + "nullable": true, + "example": "MULTIPLE", + "x-omitempty": true + }, + "upmsEnabled": { + "type": "boolean", + "description": "Indicates if UPMS is enabled for this biller", + "nullable": true, + "example": true, + "x-omitempty": true + }, + "upmsRegistrationOverridingRule": { + "type": "string", + "description": "Rule specifying how to handle UPMS registration conflicts", + "nullable": true, + "example": "NEWEST", + "x-omitempty": true } }, - "nextPage": { - "type": "string", - "example": "/api/bbps/disputes?search=Aditya&CategoryCode=Loan+Repayment&CategoryCode=Insurance&after=ABCC00000PTNNS" - } + "x-go-name": "CouBillerDetails" } + }, + "nextPage": { + "type": "string", + "example": "/api/bbps/billers?search=Aditya&CategoryCode=Loan+Repayment&CategoryCode=Insurance&after=ABCC00000PTNNS" + }, + "total": { + "type": "integer" + } + } + }, + "error": { + "required": [ + "code", + "message" + ], + "type": "object", + "properties": { + "code": { + "type": "string", + "example": "error-code-if-any" + }, + "message": { + "type": "string", + "example": "error-message-if-any" } } + }, + "success": { + "type": "boolean", + "example": true + }, + "traceId": { + "type": "string", + "example": "C3SFG0O6N88R6UI7EQ" } - ] + } } } } @@ -3995,7 +3758,11 @@ "content": { "application/json": { "schema": { - "required": ["error", "success", "traceId"], + "required": [ + "error", + "success", + "traceId" + ], "type": "object", "properties": { "traceId": { @@ -4003,7 +3770,52 @@ "example": "C3SFG0O6N88R6UI7EQ" }, "error": { - "required": ["code", "message"], + "required": [ + "code", + "message" + ], + "type": "object", + "properties": { + "code": { + "type": "string", + "example": "error-code-if-any" + }, + "message": { + "type": "string", + "example": "error-message-if-any" + } + } + }, + "success": { + "type": "boolean", + "example": false + } + } + } + } + } + }, + "500": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "required": [ + "error", + "success", + "traceId" + ], + "type": "object", + "properties": { + "traceId": { + "type": "string", + "example": "C3SFG0O6N88R6UI7EQ" + }, + "error": { + "required": [ + "code", + "message" + ], "type": "object", "properties": { "code": { @@ -4028,83 +3840,300 @@ }, "security": [ { - "Production": ["bbps:partner"] + "Production": [ + "bbps:partner" + ] }, { - "Sandbox": ["bbps:partner"] + "Sandbox": [ + "bbps:partner" + ] }, { - "QA": ["bbps:partner"] + "QA": [ + "bbps:partner" + ] } ] } }, - "/api/v2/health": { + "/api/v2/bbps/billers/plans": { "get": { - "tags": ["Health"], - "description": "Health check", - "operationId": "getHealth", + "tags": [ + "List" + ], + "description": "Returns the list of plans for a given set of billers", + "operationId": "getBillerPlans", + "parameters": [ + { + "name": "X-PARTNER-ID", + "in": "header", + "description": "The Partner ID provided by Setu.", + "required": true, + "schema": { + "type": "integer" + } + }, + { + "name": "billerIds", + "in": "query", + "description": "Biller IDs", + "required": true, + "style": "form", + "explode": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + } + }, + { + "name": "limit", + "in": "query", + "description": "Number of plans to return per page", + "schema": { + "maximum": 4000.0, + "minimum": 1.0, + "type": "integer" + } + }, + { + "name": "after", + "in": "query", + "schema": { + "type": "string" + } + }, + { + "name": "updatedSince", + "in": "query", + "description": "Used to fetch plans updated since the given date-time in IST", + "schema": { + "type": "string", + "format": "date-time" + } + } + ], "responses": { "200": { - "description": "Ok", + "description": "List of plans for the biller", + "headers": { + "X-Frame-Options": { + "description": "X Frame options", + "schema": { + "type": "string" + } + }, + "Strict-Transport-Security": { + "description": "Strict transport security", + "schema": { + "type": "string" + } + }, + "Cache-Control": { + "description": "Cache control", + "schema": { + "type": "string" + } + }, + "X-Content-Type-Options": { + "description": "X Content type options", + "schema": { + "type": "string" + } + }, + "Content-Security-Policy": { + "description": "Content security policy", + "schema": { + "type": "string" + } + }, + "Pragma": { + "description": "Pragma", + "schema": { + "type": "string" + } + }, + "X-XSS-Protection": { + "description": "X Xss Protection", + "schema": { + "type": "string" + } + } + }, "content": { "application/json": { "schema": { - "required": ["environment", "server", "version"], + "required": [ + "success", + "traceId" + ], "type": "object", "properties": { - "environment": { - "type": "string", - "example": "PROD" + "data": { + "required": [ + "plans" + ], + "type": "object", + "properties": { + "nextPage": { + "type": "string", + "example": "/api/bbps/billers/plans?biller_ids=BILLER_01&after=ABCC00000PTNNS" + }, + "plans": { + "type": "array", + "items": { + "required": [ + "Id", + "amountInRupees", + "categoryType", + "description", + "status" + ], + "type": "object", + "properties": { + "Id": { + "type": "string", + "description": "Plan ID", + "example": "1.0", + "x-order": 1.0 + }, + "additionalInfo": { + "minItems": 1, + "type": "array", + "description": "Plan Additional information details provided by the Biller.", + "example": [ + { + "paramName": "Mobile Number", + "paramValue": "Text" + } + ], + "items": { + "type": "object", + "properties": { + "paramName": { + "type": "string", + "example": "Plan Additional information parameter name." + }, + "paramValue": { + "type": "string", + "example": "Plan Additional information parameter value." + } + }, + "example": { + "paramName": "Mobile Number", + "paramValue": "Text" + }, + "x-go-name": "PlanAdditionalInfoItem" + }, + "x-omitempty": true + }, + "amountInRupees": { + "type": "string", + "example": "22.0", + "x-order": 2.0 + }, + "billerId": { + "type": "string", + "description": "Biller ID to which the plan belongs to", + "example": "1.0", + "x-order": 0.0 + }, + "categorySubType": { + "type": "object", + "properties": {}, + "description": "Plan sub category as defined by the Biller.", + "example": { + "subType": "1 Month" + }, + "x-omitempty": true, + "x-order": 4.0 + }, + "categoryType": { + "type": "string", + "description": "Plan category as defined by the Biller.", + "example": "VIP", + "x-order": 3.0 + }, + "description": { + "type": "string", + "description": "Plan description as defined by the Biller.", + "example": "Unlimited Live Sports" + }, + "effectiveFrom": { + "type": "string", + "description": "Effective from date of corresponding Plan.", + "format": "date", + "nullable": true, + "example": "2017-07-21", + "x-omitempty": false + }, + "effectiveTo": { + "type": "string", + "description": "Effective to date of corresponding Plan.", + "format": "date", + "nullable": true, + "example": "2020-08-21", + "x-omitempty": false + }, + "status": { + "type": "string", + "description": "Effective to date of corresponding Plan.", + "example": "ACTIVE", + "enum": [ + "ACTIVE", + "DEACTIVATED" + ] + } + } + } + }, + "total": { + "type": "integer" + } + } }, - "server": { - "type": "string", - "example": "mistborn" + "error": { + "required": [ + "code", + "message" + ], + "type": "object", + "properties": { + "code": { + "type": "string", + "example": "validation-error" + }, + "message": { + "type": "string", + "example": "Input is invalid" + } + } + }, + "success": { + "type": "boolean", + "example": true }, - "version": { + "traceId": { "type": "string", - "example": "db42717a829da9d3061e4f409f3c0ee9935b72a5" + "example": "C3SFG0O6N88R6UI7EQ" } - }, - "x-go-name": "HealthResponseParam", - "x-omitempty": true + } } } } - } - } - } - }, - "/api/v2/bbps/categories": { - "get": { - "tags": ["List"], - "operationId": "getCategories", - "description": "Returns the list of categories.", - "parameters": [ - { - "name": "X-PARTNER-ID", - "in": "header", - "description": "The Partner ID provided by Setu.", - "required": true, - "schema": { - "type": "integer" - } }, - { - "name": "Authorization", - "type": "string", - "description": "OAuth token. Required for authorization.", - "in": "header", - "required": true - } - ], - "responses": { "400": { "description": "Bad request", "content": { "application/json": { "schema": { - "required": ["error", "success", "traceId"], + "required": [ + "error", + "success", + "traceId" + ], "type": "object", "properties": { "traceId": { @@ -4112,7 +4141,10 @@ "example": "C3SFG0O6N88R6UI7EQ" }, "error": { - "required": ["code", "message"], + "required": [ + "code", + "message" + ], "type": "object", "properties": { "code": { @@ -4139,7 +4171,11 @@ "content": { "application/json": { "schema": { - "required": ["error", "success", "traceId"], + "required": [ + "error", + "success", + "traceId" + ], "type": "object", "properties": { "traceId": { @@ -4147,7 +4183,10 @@ "example": "C3SFG0O6N88R6UI7EQ" }, "error": { - "required": ["code", "message"], + "required": [ + "code", + "message" + ], "type": "object", "properties": { "code": { @@ -4168,7 +4207,45 @@ } } } + } + }, + "security": [ + { + "Production": [ + "bbps:partner" + ] + }, + { + "Sandbox": [ + "bbps:partner" + ] }, + { + "QA": [ + "bbps:partner" + ] + } + ] + } + }, + "/api/v2/bbps/categories": { + "get": { + "tags": [ + "List" + ], + "description": "Returns the list of categories.", + "parameters": [ + { + "name": "X-PARTNER-ID", + "in": "header", + "description": "The Partner ID provided by Setu.", + "required": true, + "schema": { + "type": "integer" + } + } + ], + "responses": { "200": { "description": "List of categories", "headers": { @@ -4218,11 +4295,16 @@ "content": { "application/json": { "schema": { - "required": ["success", "traceId"], + "required": [ + "success", + "traceId" + ], "type": "object", "properties": { "data": { - "required": ["categories"], + "required": [ + "categories" + ], "type": "object", "properties": { "categories": { @@ -4235,7 +4317,7 @@ }, "name": { "type": "string", - "example": "John Doe" + "example": "Loan Repayment" } } } @@ -4243,22 +4325,109 @@ } }, "error": { - "required": ["code", "message"], + "required": [ + "code", + "message" + ], + "type": "object", + "properties": { + "success": { + "type": "boolean", + "example": true + }, + "traceId": { + "type": "string", + "example": "C3SFG0O6N88R6UI7EQ" + } + } + }, + "success": { + "type": "boolean", + "example": true + }, + "traceId": { + "type": "string", + "example": "C3SFG0O6N88R6UI7EQ" + } + } + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "required": [ + "error", + "success", + "traceId" + ], + "type": "object", + "properties": { + "error": { + "required": [ + "code", + "message" + ], "type": "object", "properties": { "code": { "type": "string", - "example": "error-code-if-any" + "example": "validation-error" }, "message": { "type": "string", - "example": "error-message-if-any" + "example": "Input is invalid" } } }, "success": { "type": "boolean", - "example": true + "example": false + }, + "traceId": { + "type": "string", + "example": "C3SFG0O6N88R6UI7EQ" + } + } + } + } + } + }, + "500": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "required": [ + "error", + "success", + "traceId" + ], + "type": "object", + "properties": { + "error": { + "required": [ + "code", + "message" + ], + "type": "object", + "properties": { + "code": { + "type": "string", + "example": "validation-error" + }, + "message": { + "type": "string", + "example": "Input is invalid" + } + } + }, + "success": { + "type": "boolean", + "example": false }, "traceId": { "type": "string", @@ -4272,22 +4441,29 @@ }, "security": [ { - "Production": ["bbps:partner"] + "Production": [ + "bbps:partner" + ] }, { - "Sandbox": ["bbps:partner"] + "Sandbox": [ + "bbps:partner" + ] }, { - "QA": ["bbps:partner"] + "QA": [ + "bbps:partner" + ] } ] } }, - "/api/v2/bbps/billers": { + "/api/v2/bbps/disputes": { "get": { - "tags": ["List"], - "operationId": "getBillers", - "description": "Returns the list of billers.", + "tags": [ + "List" + ], + "description": "Returns the list of disputes.", "parameters": [ { "name": "X-PARTNER-ID", @@ -4299,34 +4475,20 @@ } }, { - "name": "Authorization", - "type": "string", - "description": "OAuth token. Required for authorization.", - "in": "header", - "required": true - }, - { - "name": "categoryName", - "in": "query", - "description": "Biller category. The query parameter follows a multi instance format. Usage: categoryName=category1&categoryName=category2", - "style": "form", - "explode": true, - "schema": { - "type": "array", - "items": { - "type": "string" - } - } - }, - { - "name": "ids", + "name": "status", "in": "query", "style": "form", "explode": false, "schema": { "type": "array", "items": { - "type": "string" + "type": "string", + "enum": [ + "ASSIGNED", + "REJECTED", + "RESOLVED", + "DEFAULT_RESOLVED" + ] } } }, @@ -4341,126 +4503,120 @@ } }, { - "name": "after", - "in": "query", - "schema": { - "type": "string" - } - }, - { - "name": "search", + "name": "categories", "in": "query", + "description": "Biller Category", + "style": "form", + "explode": false, "schema": { - "type": "string" + "type": "array", + "items": { + "type": "string" + } } }, { - "name": "pincode", + "name": "months", "in": "query", + "description": "Month ranges. A full-date notation as defined by 'RFC 3339, section 5.6' has to be provided but only month and year will be considered.", + "style": "form", + "explode": false, "schema": { - "type": "string" + "type": "array", + "items": { + "type": "string", + "format": "date" + } } }, { - "name": "city", + "name": "after", "in": "query", "schema": { "type": "string" } }, { - "name": "state", + "name": "mobile", "in": "query", + "description": "Mobile number with 6 to 22 digits are valid.", "schema": { + "maxLength": 22, + "minLength": 6, + "pattern": "^\\d{6,22}$", "type": "string" } }, { - "name": "country", + "name": "customerId", "in": "query", + "description": "Customer Identifier", "schema": { "type": "string" } }, { - "name": "coverage", + "name": "transactionIds", "in": "query", + "description": "Transaction IDs", + "style": "form", + "explode": false, "schema": { - "type": "string" + "type": "array", + "items": { + "type": "string" + } } }, { - "name": "tags", + "name": "paymentRefIds", "in": "query", + "description": "Partner provided transaction Ids", + "style": "form", + "explode": false, "schema": { - "type": "string" + "type": "array", + "items": { + "maxLength": 35, + "minLength": 6, + "type": "string" + } } }, { - "name": "paymentChannel", + "name": "billerIds", "in": "query", + "description": "The biller ID on BBPS", "style": "form", "explode": false, - "schema": { - "type": "array", - "items": { - "type": "string", - "enum": [ - "INT", - "INTB", - "MOB", - "BNKBRNCH", - "BSC", - "AGT", - "KIOSK", - "ATM", - "MOBB", - "POS", - "MPOS" - ] + "schema": { + "type": "array", + "items": { + "type": "string" } } }, { - "name": "paymentMode", + "name": "expand", "in": "query", "style": "form", "explode": false, "schema": { + "uniqueItems": true, "type": "array", "items": { "type": "string", "enum": [ - "Internet Banking", - "Debit Card", - "Credit Card", - "Prepaid Card", - "IMPS", - "Cash", - "UPI", - "Wallet", - "NEFT", - "AEPS", - "Account Transfer", - "Bharat QR", - "USSD" + "BILLER", + "TRANSACTION" ] } } - }, - { - "name": "updatedSince", - "in": "query", - "description": "Used to fetch billers updated since the given date-time in IST", - "schema": { - "type": "string", - "format": "date-time" - } } ], "responses": { "200": { - "description": "List of billers", + "description": "List of disputes", "headers": { "X-Frame-Options": { "description": "X Frame options", @@ -4508,427 +4664,1231 @@ "content": { "application/json": { "schema": { - "required": ["success", "traceId"], - "type": "object", - "properties": { - "data": { - "required": ["billers"], + "allOf": [ + { + "required": [ + "success", + "traceId" + ], "type": "object", "properties": { - "nextPage": { - "type": "string", - "example": "/api/bbps/billers?search=Aditya&CategoryCode=Loan+Repayment&CategoryCode=Insurance&after=ABCC00000PTNNS" - }, - "total": { - "type": "integer" + "success": { + "type": "boolean", + "example": true }, - "billers": { - "type": "array", - "items": { - "required": [ - "categoryName", - "customerParams", - "exactness", - "fetchApiType", - "id", - "name", - "payWithoutFetchAllowed", - "paymentChannels", - "paymentModes", - "supportsPendingStatus" - ], - "type": "object", - "properties": { - "country": { - "type": "string", - "example": "IND" - }, - "modifiedAt": { - "type": "string", - "format": "date-time", - "nullable": true, - "example": "2021-11-12T13:37:04.572+05:30", - "x-omitempty": false - }, - "responseType": { - "type": "string", - "nullable": true, - "example": "SINGLE", - "enum": ["SINGLE", "LIST", "SELECTIVE"], - "x-nullable": true, - "x-omitempty": false - }, - "subCategoryName": { - "type": "string", - "example": "DAIRY" - }, - "coverage": { - "type": "string", - "example": "IND-TEL-Hyderabad" - }, - "interchangeFee": { - "type": "array", - "items": { - "type": "object", - "properties": { - "feeCode": { - "type": "string", - "example": "CCF1" - }, - "feeDesc": { - "type": "string", - "example": "Customer Convenience Fee" - }, - "feeDirection": { - "type": "string", - "example": "C2B" - }, - "interchangeFeeDetails": { - "required": [ - "effctvFrom", - "effctvTo", - "flatFee", - "percentFee", - "tranAmtRangeMax", - "tranAmtRangeMin" - ], - "type": "object", - "properties": { - "percentFee": { - "type": "number", - "format": "decimal", - "example": 1.0 - }, - "tranAmtRangeMax": { - "type": "integer", - "format": "int64" - }, - "tranAmtRangeMin": { - "type": "integer", - "format": "int64" - }, - "effctvFrom": { - "type": "string", - "example": "2024-01-01" - }, - "effctvTo": { - "type": "string", - "example": "2024-12-31" + "traceId": { + "type": "string", + "example": "C3SFG0O6N88R6UI7EQ" + } + } + }, + { + "type": "object", + "properties": { + "data": { + "required": [ + "disputes" + ], + "type": "object", + "properties": { + "disputes": { + "type": "array", + "items": { + "allOf": [ + { + "type": "object", + "properties": { + "assigned": { + "type": "string", + "example": "ADIT00000NATRA" + }, + "biller": { + "required": [ + "categoryName", + "customerParams", + "exactness", + "fetchApiType", + "id", + "name", + "payWithoutFetchAllowed", + "paymentChannels", + "paymentModes", + "supportsPendingStatus" + ], + "type": "object", + "properties": { + "bbpsUpdateTimestamp": { + "type": "string", + "description": "Last updated date-time of the Biller accurate to the nearest day.", + "format": "date-time", + "nullable": true, + "example": "2021-11-12T13:37:04.572+05:30", + "x-omitempty": true + }, + "billerAdditionalInfo": { + "type": "array", + "items": { + "required": [ + "dataType", + "optional", + "paramName" + ], + "type": "object", + "properties": { + "dataType": { + "type": "string", + "example": "ALPHANUMERIC", + "enum": [ + "ALPHANUMERIC", + "NUMERIC" + ] + }, + "optional": { + "type": "boolean", + "example": false + }, + "paramName": { + "type": "string", + "example": "Package Duration" + } + } + } + }, + "billerAdditionalInfoPayment": { + "type": "array", + "items": { + "required": [ + "dataType", + "optional", + "paramName" + ], + "type": "object", + "properties": { + "dataType": { + "type": "string", + "example": "ALPHANUMERIC", + "enum": [ + "ALPHANUMERIC", + "NUMERIC" + ] + }, + "optional": { + "type": "boolean", + "example": false + }, + "paramName": { + "type": "string", + "example": "Package Duration" + } + } + } + }, + "categoryName": { + "type": "string", + "description": "Biller Category", + "example": "loan-repayment" + }, + "city": { + "type": "string", + "example": "Hyderabad" + }, + "country": { + "type": "string", + "example": "IND" + }, + "coverage": { + "type": "string", + "example": "IND-TEL-Hyderabad" + }, + "createdAt": { + "type": "string", + "format": "date-time", + "nullable": true, + "example": "2021-11-12T13:37:04.572+05:30", + "x-omitempty": false + }, + "customerParams": { + "type": "array", + "items": { + "required": [ + "dataType", + "maxLength", + "minLength", + "optional", + "paramName", + "regex", + "values", + "visibility" + ], + "type": "object", + "properties": { + "dataType": { + "type": "string", + "example": "ALPHANUMERIC" + }, + "maxLength": { + "type": "integer" + }, + "minLength": { + "type": "integer" + }, + "optional": { + "type": "boolean", + "example": false + }, + "paramName": { + "type": "string", + "example": "Loan Account Number" + }, + "regex": { + "type": "string", + "example": "^[a-zA-Z0-9]{7,15}" + }, + "values": { + "type": "string", + "example": "CHOICE1,CHOICE2,CHOICE3" + }, + "visibility": { + "type": "boolean", + "example": true + } + } + } + }, + "customerParamsGroups": { + "type": "array", + "items": { + "type": "array", + "items": { + "type": "string", + "example": "Param 1" + } + } + }, + "enforcesSameDayFetchPay": { + "type": "boolean", + "example": true, + "x-omitempty": false + }, + "exactness": { + "type": "string", + "example": "Exact", + "enum": [ + "Exact", + "Exact and above", + "Exact and below", + "Any", + "RANGE" + ] + }, + "fetchApiType": { + "type": "string", + "enum": [ + "BILL_FETCH", + "BILL_VALIDATE", + "BILL_DIRECT" + ] + }, + "id": { + "type": "string", + "description": "Identifier of the biller in BBPS.", + "example": "ADIT00000NAT0T" + }, + "interchangeFee": { + "type": "array", + "items": { + "type": "object", + "properties": { + "feeCode": { + "type": "string", + "example": "CCF1" + }, + "feeDesc": { + "type": "string", + "example": "Customer Convenience Fee" + }, + "feeDirection": { + "type": "string", + "example": "C2B" + }, + "interchangeFeeDetails": { + "required": [ + "effctvFrom", + "effctvTo", + "flatFee", + "percentFee", + "tranAmtRangeMax", + "tranAmtRangeMin" + ], + "type": "object", + "properties": { + "effctvFrom": { + "type": "string", + "example": "2024-01-01" + }, + "effctvTo": { + "type": "string", + "example": "2024-12-31" + }, + "flatFee": { + "type": "number", + "format": "decimal", + "example": 0.0 + }, + "percentFee": { + "type": "number", + "format": "decimal", + "example": 1.0 + }, + "tranAmtRangeMax": { + "type": "integer", + "format": "int64" + }, + "tranAmtRangeMin": { + "type": "integer", + "format": "int64" + } + } + } + } + } + }, + "logo": { + "type": "string", + "example": "logo" + }, + "modifiedAt": { + "type": "string", + "format": "date-time", + "nullable": true, + "example": "2021-11-12T13:37:04.572+05:30", + "x-omitempty": false + }, + "name": { + "type": "string", + "description": "Name of the biller.", + "example": "Umbrella Corporation" + }, + "payWithoutFetchAllowed": { + "type": "boolean", + "description": "Flag indicating if the Biller accepts adhoc payment", + "example": true + }, + "paymentChannels": { + "type": "array", + "items": { + "required": [ + "maxLimit", + "minLimit", + "paymentChannel", + "supportsPendingStatus" + ], + "type": "object", + "properties": { + "maxLimit": { + "type": "integer" + }, + "minLimit": { + "type": "integer" + }, + "paymentChannel": { + "type": "string", + "description": "This is the initiating channel.\n1. `AGT`: Offline agent.\n2. `BNKBRNCH`: Bank branch.\n3. `BSC`: Business correspondent\n4. `MOB`: Mobile application\n5. `INT`: Internet portal\n6. `INTB`: Internet banking\n7. `MOBB`: Mobile banking\n8. `ATM`: ATM\n9. `KIOSK`: KIOSK\n", + "example": "INT", + "enum": [ + "INT", + "INTB", + "MOB", + "BNKBRNCH", + "BSC", + "AGT", + "KIOSK", + "ATM", + "MOBB", + "POS", + "MPOS" + ] + }, + "supportsPendingStatus": { + "type": "boolean", + "example": false + } + } + } + }, + "paymentModes": { + "type": "array", + "items": { + "required": [ + "maxLimit", + "minLimit", + "paymentMode", + "supportsPendingStatus" + ], + "type": "object", + "properties": { + "maxLimit": { + "type": "integer" + }, + "minLimit": { + "type": "integer" + }, + "paymentMode": { + "type": "string", + "example": "Internet Banking", + "enum": [ + "Internet Banking", + "Debit Card", + "Credit Card", + "Prepaid Card", + "IMPS", + "Cash", + "UPI", + "Wallet", + "NEFT", + "AEPS", + "Account Transfer", + "Bharat QR", + "USSD" + ] + }, + "supportsPendingStatus": { + "type": "boolean", + "example": false + } + } + } + }, + "pincode": { + "type": "string", + "example": "pincode" + }, + "planRequirement": { + "type": "string", + "description": "Indicates if plan selection is required for bill payments", + "example": "MANDATORY", + "enum": [ + "MANDATORY", + "OPTIONAL", + "CONDITIONAL" + ], + "x-omitempty": true + }, + "responseType": { + "type": "string", + "nullable": true, + "example": "SINGLE", + "enum": [ + "SINGLE", + "LIST", + "SELECTIVE" + ], + "x-nullable": true, + "x-omitempty": false + }, + "selectionType": { + "type": "string", + "description": "Defined only for billers with response type as LIST. SINGLE: User can pay only one of the bills in bill fetch response. MULTIPLE: User can pay any combination of bills in bill fetch response. ALL: User has to pay all the bills in bill fetch response.", + "nullable": true, + "example": "SINGLE", + "enum": [ + "SINGLE", + "MULTIPLE", + "ALL" + ], + "x-nullable": true, + "x-omitempty": false + }, + "state": { + "type": "string", + "example": "TEL" + }, + "subCategoryName": { + "type": "string", + "example": "DAIRY" + }, + "supportsPendingStatus": { + "type": "boolean", + "description": "Flag indicating whether pending status is applicable for the biller or not", + "example": false + }, + "tags": { + "type": "string", + "example": "tags" + }, + "upmsBillerParams": { + "type": "array", + "description": "UPMS-specific biller parameters", + "items": { + "required": [ + "name" + ], + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "UPMS parameter name", + "example": "mandateType" + }, + "value": { + "type": "string", + "description": "UPMS parameter value", + "example": "DEBIT", + "x-omitempty": true + } + } + }, + "x-omitempty": true + }, + "upmsBillerType": { + "type": "string", + "description": "Type of UPMS biller", + "nullable": true, + "example": "MULTIPLE", + "x-omitempty": true + }, + "upmsEnabled": { + "type": "boolean", + "description": "Indicates if UPMS is enabled for this biller", + "nullable": true, + "example": true, + "x-omitempty": true + }, + "upmsRegistrationOverridingRule": { + "type": "string", + "description": "Rule specifying how to handle UPMS registration conflicts", + "nullable": true, + "example": "NEWEST", + "x-omitempty": true + } }, - "flatFee": { - "type": "number", - "format": "decimal", - "example": 0.0 - } + "x-go-name": "CouBillerDetails" + }, + "billerId": { + "type": "string", + "description": "The biller ID on BBPS", + "example": "MAHI00000NATIC" + }, + "complaintId": { + "type": "string", + "example": "Loan Repayment" + }, + "complaintStatus": { + "type": "string", + "description": "BBPS Complaint status", + "example": "ASSIGNED", + "enum": [ + "INITIALIZED", + "ASSIGNED", + "RE_ASSIGNED", + "ASSIGNED_TO_BOU", + "ASSIGNED_TO_COU", + "ASSIGNED_TO_OU", + "ESCALATED", + "RESOLVED", + "UNRESOLVED", + "REJECTED", + "DEFAULT_RESOLVED", + "REFUNDED", + "PENDING_REFUND" + ] + }, + "createdAt": { + "type": "string", + "description": "Dispute's creation timestamp", + "format": "date-time", + "example": "2020-12-12T13:12:00+05:30" + }, + "customerId": { + "type": "string", + "description": "Customer Identifier" + }, + "disposition": { + "type": "string", + "enum": [ + "D11", + "D12", + "D13", + "D21", + "D22", + "D23", + "D31", + "D32" + ] + }, + "lastModifiedAt": { + "type": "string", + "description": "Dispute's last modified timestamp", + "format": "date-time", + "example": "2020-12-12T13:12:00+05:30" + }, + "refId": { + "type": "string", + "description": "The generated Reference ID for the request." + }, + "remarks": { + "type": "string", + "example": "ADIT00000NATRA" + }, + "responseCode": { + "type": "string", + "example": "ADIT00000NATRA" + }, + "responseReason": { + "type": "string", + "example": "ADIT00000NATRA" + }, + "ticketTAT": { + "type": "string", + "format": "date", + "nullable": true + }, + "ticketType": { + "type": "string", + "enum": [ + "DISPUTE", + "COMPLAINT" + ] + }, + "transactionId": { + "type": "string", + "description": "Setu BillPay Transaction ID.", + "example": "AS01910192192192192" } } - } - } - }, - "selectionType": { - "type": "string", - "description": "Defined only for billers with response type as LIST. SINGLE: User can pay only one of the bills in bill fetch response. MULTIPLE: User can pay any combination of bills in bill fetch response. ALL: User has to pay all the bills in bill fetch response.", - "nullable": true, - "example": "SINGLE", - "enum": ["SINGLE", "MULTIPLE", "ALL"], - "x-omitempty": false, - "x-nullable": true - }, - "pincode": { - "type": "string", - "example": "pincode" - }, - "supportsPendingStatus": { - "type": "boolean", - "description": "Flag indicating whether pending status is applicable for the biller or not", - "example": false - }, - "tags": { - "type": "string", - "example": "tags" - }, - "billerAdditionalInfoPayment": { - "type": "array", - "items": { - "required": ["dataType", "optional", "paramName"], - "type": "object", - "properties": { - "dataType": { - "type": "string", - "example": "ALPHANUMERIC", - "enum": ["ALPHANUMERIC", "NUMERIC"] - }, - "optional": { - "type": "boolean", - "example": false - }, - "paramName": { - "type": "string", - "example": "Package Duration" - } - } - } - }, - "customerParams": { - "type": "array", - "items": { - "required": [ - "dataType", - "maxLength", - "minLength", - "optional", - "paramName", - "regex", - "values", - "visibility" - ], - "type": "object", - "properties": { - "paramName": { - "type": "string", - "example": "Loan Account Number" - }, - "regex": { - "type": "string", - "example": "^[a-zA-Z0-9]{7,15}" - }, - "values": { - "type": "string" - }, - "visibility": { - "type": "boolean", - "example": true - }, - "dataType": { - "type": "string", - "example": "ALPHANUMERIC" - }, - "maxLength": { - "type": "integer" - }, - "minLength": { - "type": "integer" - }, - "optional": { - "type": "boolean", - "example": false + }, + { + "type": "object", + "properties": { + "mobile": { + "maxLength": 22, + "minLength": 6, + "pattern": "^\\d{6,22}$", + "type": "string", + "description": "Mobile number with 6 to 22 digits are valid." + }, + "paymentRefID": { + "maxLength": 35, + "minLength": 6, + "type": "string", + "description": "Unique identifier provided by Partner for the payment request.", + "example": "BD019181220291" + }, + "transaction": { + "allOf": [ + { + "type": "object", + "properties": { + "amount": { + "type": "integer" + }, + "biller": { + "required": [ + "categoryName", + "customerParams", + "exactness", + "fetchApiType", + "id", + "name", + "payWithoutFetchAllowed", + "paymentChannels", + "paymentModes", + "supportsPendingStatus" + ], + "type": "object", + "properties": { + "bbpsUpdateTimestamp": { + "type": "string", + "description": "Last updated date-time of the Biller accurate to the nearest day.", + "format": "date-time", + "nullable": true, + "example": "2021-11-12T13:37:04.572+05:30", + "x-omitempty": true + }, + "billerAdditionalInfo": { + "type": "array", + "items": { + "required": [ + "dataType", + "optional", + "paramName" + ], + "type": "object", + "properties": { + "dataType": { + "type": "string", + "example": "ALPHANUMERIC", + "enum": [ + "ALPHANUMERIC", + "NUMERIC" + ] + }, + "optional": { + "type": "boolean", + "example": false + }, + "paramName": { + "type": "string", + "example": "Package Duration" + } + } + } + }, + "billerAdditionalInfoPayment": { + "type": "array", + "items": { + "required": [ + "dataType", + "optional", + "paramName" + ], + "type": "object", + "properties": { + "dataType": { + "type": "string", + "example": "ALPHANUMERIC", + "enum": [ + "ALPHANUMERIC", + "NUMERIC" + ] + }, + "optional": { + "type": "boolean", + "example": false + }, + "paramName": { + "type": "string", + "example": "Package Duration" + } + } + } + }, + "categoryName": { + "type": "string", + "description": "Biller Category", + "example": "loan-repayment" + }, + "city": { + "type": "string", + "example": "Hyderabad" + }, + "country": { + "type": "string", + "example": "IND" + }, + "coverage": { + "type": "string", + "example": "IND-TEL-Hyderabad" + }, + "createdAt": { + "type": "string", + "format": "date-time", + "nullable": true, + "example": "2021-11-12T13:37:04.572+05:30", + "x-omitempty": false + }, + "customerParams": { + "type": "array", + "items": { + "required": [ + "dataType", + "maxLength", + "minLength", + "optional", + "paramName", + "regex", + "values", + "visibility" + ], + "type": "object", + "properties": { + "dataType": { + "type": "string", + "example": "ALPHANUMERIC" + }, + "maxLength": { + "type": "integer" + }, + "minLength": { + "type": "integer" + }, + "optional": { + "type": "boolean", + "example": false + }, + "paramName": { + "type": "string", + "example": "Loan Account Number" + }, + "regex": { + "type": "string", + "example": "^[a-zA-Z0-9]{7,15}" + }, + "values": { + "type": "string", + "example": "CHOICE1,CHOICE2,CHOICE3" + }, + "visibility": { + "type": "boolean", + "example": true + } + } + } + }, + "customerParamsGroups": { + "type": "array", + "items": { + "type": "array", + "items": { + "type": "string", + "example": "Param 1" + } + } + }, + "enforcesSameDayFetchPay": { + "type": "boolean", + "example": true, + "x-omitempty": false + }, + "exactness": { + "type": "string", + "example": "Exact", + "enum": [ + "Exact", + "Exact and above", + "Exact and below", + "Any", + "RANGE" + ] + }, + "fetchApiType": { + "type": "string", + "enum": [ + "BILL_FETCH", + "BILL_VALIDATE", + "BILL_DIRECT" + ] + }, + "id": { + "type": "string", + "description": "Identifier of the biller in BBPS.", + "example": "ADIT00000NAT0T" + }, + "interchangeFee": { + "type": "array", + "items": { + "type": "object", + "properties": { + "feeCode": { + "type": "string", + "example": "CCF1" + }, + "feeDesc": { + "type": "string", + "example": "Customer Convenience Fee" + }, + "feeDirection": { + "type": "string", + "example": "C2B" + }, + "interchangeFeeDetails": { + "required": [ + "effctvFrom", + "effctvTo", + "flatFee", + "percentFee", + "tranAmtRangeMax", + "tranAmtRangeMin" + ], + "type": "object", + "properties": { + "effctvFrom": { + "type": "string", + "example": "2024-01-01" + }, + "effctvTo": { + "type": "string", + "example": "2024-12-31" + }, + "flatFee": { + "type": "number", + "format": "decimal", + "example": 0.0 + }, + "percentFee": { + "type": "number", + "format": "decimal", + "example": 1.0 + }, + "tranAmtRangeMax": { + "type": "integer", + "format": "int64" + }, + "tranAmtRangeMin": { + "type": "integer", + "format": "int64" + } + } + } + } + } + }, + "logo": { + "type": "string", + "example": "logo" + }, + "modifiedAt": { + "type": "string", + "format": "date-time", + "nullable": true, + "example": "2021-11-12T13:37:04.572+05:30", + "x-omitempty": false + }, + "name": { + "type": "string", + "description": "Name of the biller.", + "example": "Umbrella Corporation" + }, + "payWithoutFetchAllowed": { + "type": "boolean", + "description": "Flag indicating if the Biller accepts adhoc payment", + "example": true + }, + "paymentChannels": { + "type": "array", + "items": { + "required": [ + "maxLimit", + "minLimit", + "paymentChannel", + "supportsPendingStatus" + ], + "type": "object", + "properties": { + "maxLimit": { + "type": "integer" + }, + "minLimit": { + "type": "integer" + }, + "paymentChannel": { + "type": "string", + "description": "This is the initiating channel.\n1. `AGT`: Offline agent.\n2. `BNKBRNCH`: Bank branch.\n3. `BSC`: Business correspondent\n4. `MOB`: Mobile application\n5. `INT`: Internet portal\n6. `INTB`: Internet banking\n7. `MOBB`: Mobile banking\n8. `ATM`: ATM\n9. `KIOSK`: KIOSK\n", + "example": "INT", + "enum": [ + "INT", + "INTB", + "MOB", + "BNKBRNCH", + "BSC", + "AGT", + "KIOSK", + "ATM", + "MOBB", + "POS", + "MPOS" + ] + }, + "supportsPendingStatus": { + "type": "boolean", + "example": false + } + } + } + }, + "paymentModes": { + "type": "array", + "items": { + "required": [ + "maxLimit", + "minLimit", + "paymentMode", + "supportsPendingStatus" + ], + "type": "object", + "properties": { + "maxLimit": { + "type": "integer" + }, + "minLimit": { + "type": "integer" + }, + "paymentMode": { + "type": "string", + "example": "Internet Banking", + "enum": [ + "Internet Banking", + "Debit Card", + "Credit Card", + "Prepaid Card", + "IMPS", + "Cash", + "UPI", + "Wallet", + "NEFT", + "AEPS", + "Account Transfer", + "Bharat QR", + "USSD" + ] + }, + "supportsPendingStatus": { + "type": "boolean", + "example": false + } + } + } + }, + "pincode": { + "type": "string", + "example": "pincode" + }, + "planRequirement": { + "type": "string", + "description": "Indicates if plan selection is required for bill payments", + "example": "MANDATORY", + "enum": [ + "MANDATORY", + "OPTIONAL", + "CONDITIONAL" + ], + "x-omitempty": true + }, + "responseType": { + "type": "string", + "nullable": true, + "example": "SINGLE", + "enum": [ + "SINGLE", + "LIST", + "SELECTIVE" + ], + "x-nullable": true, + "x-omitempty": false + }, + "selectionType": { + "type": "string", + "description": "Defined only for billers with response type as LIST. SINGLE: User can pay only one of the bills in bill fetch response. MULTIPLE: User can pay any combination of bills in bill fetch response. ALL: User has to pay all the bills in bill fetch response.", + "nullable": true, + "example": "SINGLE", + "enum": [ + "SINGLE", + "MULTIPLE", + "ALL" + ], + "x-nullable": true, + "x-omitempty": false + }, + "state": { + "type": "string", + "example": "TEL" + }, + "subCategoryName": { + "type": "string", + "example": "DAIRY" + }, + "supportsPendingStatus": { + "type": "boolean", + "description": "Flag indicating whether pending status is applicable for the biller or not", + "example": false + }, + "tags": { + "type": "string", + "example": "tags" + }, + "upmsBillerParams": { + "type": "array", + "description": "UPMS-specific biller parameters", + "items": { + "required": [ + "name" + ], + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "UPMS parameter name", + "example": "mandateType" + }, + "value": { + "type": "string", + "description": "UPMS parameter value", + "example": "DEBIT", + "x-omitempty": true + } + } + }, + "x-omitempty": true + }, + "upmsBillerType": { + "type": "string", + "description": "Type of UPMS biller", + "nullable": true, + "example": "MULTIPLE", + "x-omitempty": true + }, + "upmsEnabled": { + "type": "boolean", + "description": "Indicates if UPMS is enabled for this biller", + "nullable": true, + "example": true, + "x-omitempty": true + }, + "upmsRegistrationOverridingRule": { + "type": "string", + "description": "Rule specifying how to handle UPMS registration conflicts", + "nullable": true, + "example": "NEWEST", + "x-omitempty": true + } + }, + "x-go-name": "CouBillerDetails" + }, + "billerId": { + "type": "string", + "description": "The biller ID on BBPS", + "example": "MAHI00000NATIC" + }, + "custConvFee": { + "type": "integer", + "description": "Customer convenience fee in paise" + }, + "customerId": { + "type": "string", + "description": "Customer Identifier" + }, + "customerParams": { + "type": "array", + "description": "The bill params for fetching the bill", + "items": { + "required": [ + "name", + "value" + ], + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "The display name of the parameter. This has to match what is sent in fields.", + "example": "Loan Number" + }, + "value": { + "type": "string", + "description": "The value of the customer parameter", + "example": "1895159" + } + } + } + }, + "etherealTransaction": { + "required": [ + "amount", + "billRefId", + "refId", + "status", + "transactionId" + ], + "type": "object", + "properties": { + "amount": { + "type": "string", + "example": "100.00" + }, + "billRefId": { + "type": "string", + "description": "The BBPS Ref ID", + "example": "C3SFG0O6N88R6UI7EQ" + }, + "refId": { + "type": "string", + "example": "COUWL910192192192192" + }, + "status": { + "type": "string", + "enum": [ + "INIT", + "SUCCESS", + "FAILURE", + "PENDING", + "UNKNOWN" + ] + }, + "transactionId": { + "type": "string", + "example": "Q910192192192192" + } + } + }, + "refId": { + "type": "string", + "description": "The generated Reference ID for the request." + }, + "refundStatus": { + "type": "string", + "enum": [ + "Required", + "Requested", + "Processed" + ] + }, + "status": { + "type": "string", + "example": "Success", + "enum": [ + "Processing", + "Success", + "Error", + "Credit_Adjustment" + ] + }, + "timestamp": { + "type": "string", + "description": "Timestamp provided by partner while making payment request.", + "format": "date-time", + "example": "2020-12-12T13:12:00+05:30" + }, + "transactionId": { + "type": "string", + "description": "Setu BillPay Transaction ID.", + "example": "AS01910192192192192" + } + } + }, + { + "type": "object", + "properties": { + "mobile": { + "maxLength": 22, + "minLength": 6, + "pattern": "^\\d{6,22}$", + "type": "string", + "description": "Mobile number with 6 to 22 digits are valid." + }, + "paymentRefId": { + "maxLength": 35, + "minLength": 6, + "type": "string", + "description": "Unique identifier provided by Partner for the payment request.", + "example": "BD019181220291" + } + } + } + ] + } } } - } - }, - "customerParamsGroups": { - "type": "array", - "items": { - "type": "array", - "items": { - "type": "string", - "example": "Param 1" - } - } - }, - "id": { - "type": "string", - "description": "Identifier of the biller in BBPS.", - "example": "ADIT00000NAT0T" - }, - "createdAt": { - "type": "string", - "format": "date-time", - "nullable": true, - "example": "2021-11-12T13:37:04.572+05:30", - "x-omitempty": false - }, - "exactness": { - "type": "string", - "example": "Exact", - "enum": [ - "Exact", - "Exact and above", - "Exact and below", - "Any", - "RANGE" ] - }, - "fetchApiType": { - "type": "string", - "enum": ["BILL_FETCH", "BILL_VALIDATE", "BILL_DIRECT"] - }, - "bbpsUpdateTimestamp": { - "type": "string", - "description": "Last updated date-time of the Biller accurate to the nearest day.", - "format": "date-time", - "nullable": true, - "example": "2021-11-12T13:37:04.572+05:30", - "x-omitempty": true - }, - "logo": { - "type": "string", - "example": "logo" - }, - "paymentModes": { - "type": "array", - "items": { - "required": [ - "maxLimit", - "minLimit", - "paymentMode", - "supportsPendingStatus" - ], - "type": "object", - "properties": { - "maxLimit": { - "type": "integer" - }, - "minLimit": { - "type": "integer" - }, - "paymentMode": { - "type": "string", - "example": "Internet Banking", - "enum": [ - "Internet Banking", - "Debit Card", - "Credit Card", - "Prepaid Card", - "IMPS", - "Cash", - "UPI", - "Wallet", - "NEFT", - "AEPS", - "Account Transfer", - "Bharat QR", - "USSD" - ] - }, - "supportsPendingStatus": { - "type": "boolean", - "example": false - } - } - } - }, - "categoryName": { - "type": "string", - "description": "Biller Category", - "example": "loan-repayment" - }, - "city": { - "type": "string", - "example": "Hyderabad" - }, - "enforcesSameDayFetchPay": { - "type": "boolean", - "example": true, - "x-omitempty": false - }, - "name": { - "type": "string", - "description": "Name of the biller.", - "example": "John Doe" - }, - "billerAdditionalInfo": { - "type": "array", - "items": { - "required": ["dataType", "optional", "paramName"], - "type": "object", - "properties": { - "dataType": { - "type": "string", - "example": "ALPHANUMERIC", - "enum": ["ALPHANUMERIC", "NUMERIC"] - }, - "optional": { - "type": "boolean", - "example": false - }, - "paramName": { - "type": "string", - "example": "Package Duration" - } - } - } - }, - "payWithoutFetchAllowed": { - "type": "boolean", - "description": "Flag indicating if the Biller accepts adhoc payment", - "example": true - }, - "paymentChannels": { - "type": "array", - "items": { - "required": [ - "maxLimit", - "minLimit", - "paymentChannel", - "supportsPendingStatus" - ], - "type": "object", - "properties": { - "paymentChannel": { - "type": "string", - "description": "This is the initiating channel.\n1. `AGT`: Offline agent.\n2. `BNKBRNCH`: Bank branch.\n3. `BSC`: Business correspondent\n4. `MOB`: Mobile application\n5. `INT`: Internet portal\n6. `INTB`: Internet banking\n7. `MOBB`: Mobile banking\n8. `ATM`: ATM\n9. `KIOSK`: KIOSK\n", - "example": "INT", - "enum": [ - "INT", - "INTB", - "MOB", - "BNKBRNCH", - "BSC", - "AGT", - "KIOSK", - "ATM", - "MOBB", - "POS", - "MPOS" - ] - }, - "supportsPendingStatus": { - "type": "boolean", - "example": false - }, - "maxLimit": { - "type": "integer" - }, - "minLimit": { - "type": "integer" - } - } - } - }, - "state": { - "type": "string", - "example": "TEL" - } - }, - "x-go-name": "CouBillerDetails" - } - } - } - }, - "error": { - "required": ["code", "message"], - "type": "object", - "properties": { - "code": { - "type": "string", - "example": "error-code-if-any" - }, - "message": { - "type": "string", - "example": "error-message-if-any" + } + }, + "nextPage": { + "type": "string", + "example": "/api/bbps/disputes?search=Aditya&CategoryCode=Loan+Repayment&CategoryCode=Insurance&after=ABCC00000PTNNS" + } + } } } - }, - "success": { - "type": "boolean", - "example": true - }, - "traceId": { - "type": "string", - "example": "C3SFG0O6N88R6UI7EQ" } - } + ] } } } @@ -4938,30 +5898,37 @@ "content": { "application/json": { "schema": { - "required": ["error", "success", "traceId"], + "required": [ + "error", + "success", + "traceId" + ], "type": "object", "properties": { - "traceId": { - "type": "string", - "example": "C3SFG0O6N88R6UI7EQ" - }, "error": { - "required": ["code", "message"], + "required": [ + "code", + "message" + ], "type": "object", "properties": { "code": { "type": "string", - "example": "error-code-if-any" + "example": "validation-error" }, "message": { "type": "string", - "example": "error-message-if-any" + "example": "Input is invalid" } } }, "success": { "type": "boolean", "example": false + }, + "traceId": { + "type": "string", + "example": "C3SFG0O6N88R6UI7EQ" } } } @@ -4973,30 +5940,37 @@ "content": { "application/json": { "schema": { - "required": ["error", "success", "traceId"], + "required": [ + "error", + "success", + "traceId" + ], "type": "object", "properties": { - "traceId": { - "type": "string", - "example": "C3SFG0O6N88R6UI7EQ" - }, "error": { - "required": ["code", "message"], + "required": [ + "code", + "message" + ], "type": "object", "properties": { "code": { "type": "string", - "example": "error-code-if-any" + "example": "validation-error" }, "message": { "type": "string", - "example": "error-message-if-any" + "example": "Input is invalid" } } }, "success": { "type": "boolean", "example": false + }, + "traceId": { + "type": "string", + "example": "C3SFG0O6N88R6UI7EQ" } } } @@ -5006,21 +5980,28 @@ }, "security": [ { - "Production": ["bbps:partner"] + "Production": [ + "bbps:partner" + ] }, { - "Sandbox": ["bbps:partner"] + "Sandbox": [ + "bbps:partner" + ] }, { - "QA": ["bbps:partner"] + "QA": [ + "bbps:partner" + ] } ] } }, "/api/v2/bbps/transactions": { "get": { - "tags": ["List"], - "operationId": "getTxns", + "tags": [ + "List" + ], "description": "Returns the list of transactions.", "parameters": [ { @@ -5032,13 +6013,6 @@ "type": "integer" } }, - { - "name": "Authorization", - "type": "string", - "description": "OAuth token. Required for authorization.", - "in": "header", - "required": true - }, { "name": "limit", "in": "query", @@ -5112,7 +6086,11 @@ "description": "Biller Fetch Api Type", "schema": { "type": "string", - "enum": ["BILL_FETCH", "BILL_VALIDATE", "BILL_DIRECT"] + "enum": [ + "BILL_FETCH", + "BILL_VALIDATE", + "BILL_DIRECT" + ] } }, { @@ -5139,7 +6117,11 @@ "type": "array", "items": { "type": "string", - "enum": ["Processing", "Success", "Error"] + "enum": [ + "Processing", + "Success", + "Error" + ] } } }, @@ -5172,7 +6154,10 @@ "type": "array", "items": { "type": "string", - "enum": ["BILLER", "ETHEREAL_TRANSACTION"] + "enum": [ + "BILLER", + "ETHEREAL_TRANSACTION" + ] } } }, @@ -5181,81 +6166,15 @@ "in": "query", "schema": { "type": "string", - "enum": ["Required", "Requested", "Processed"] + "enum": [ + "Required", + "Requested", + "Processed" + ] } } ], "responses": { - "400": { - "description": "Bad request", - "content": { - "application/json": { - "schema": { - "required": ["error", "success", "traceId"], - "type": "object", - "properties": { - "traceId": { - "type": "string", - "example": "C3SFG0O6N88R6UI7EQ" - }, - "error": { - "required": ["code", "message"], - "type": "object", - "properties": { - "code": { - "type": "string", - "example": "error-code-if-any" - }, - "message": { - "type": "string", - "example": "error-message-if-any" - } - } - }, - "success": { - "type": "boolean", - "example": false - } - } - } - } - } - }, - "500": { - "description": "Bad request", - "content": { - "application/json": { - "schema": { - "required": ["error", "success", "traceId"], - "type": "object", - "properties": { - "traceId": { - "type": "string", - "example": "C3SFG0O6N88R6UI7EQ" - }, - "error": { - "required": ["code", "message"], - "type": "object", - "properties": { - "code": { - "type": "string", - "example": "error-code-if-any" - }, - "message": { - "type": "string", - "example": "error-message-if-any" - } - } - }, - "success": { - "type": "boolean", - "example": false - } - } - } - } - } - }, "200": { "description": "List of Txns", "headers": { @@ -5307,7 +6226,10 @@ "schema": { "allOf": [ { - "required": ["success", "traceId"], + "required": [ + "success", + "traceId" + ], "type": "object", "properties": { "success": { @@ -5321,7 +6243,9 @@ } }, { - "required": ["data"], + "required": [ + "data" + ], "type": "object", "properties": { "data": { @@ -5345,114 +6269,9 @@ { "type": "object", "properties": { - "customerId": { - "type": "string", - "description": "Customer Identifier", - "example": "4881317598" - }, - "refId": { - "type": "string", - "description": "The generated BBPS Reference ID for the request.", - "example": "HENSVVR4QOS7X1UGPY7JGUV444P10102202" - }, - "status": { - "type": "string", - "example": "Success", - "enum": [ - "Processing", - "Success", - "Error", - "Credit_Adjustment" - ] - }, "amount": { "type": "integer" }, - "custConvFee": { - "type": "integer", - "description": "Customer convenience fee in paise" - }, - "customerParams": { - "type": "array", - "description": "The bill params for fetching the bill", - "items": { - "required": [ - "name", - "value" - ], - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "The display name of the parameter. This has to match what is sent in fields.", - "example": "John Doe" - }, - "value": { - "type": "string", - "description": "The value of the customer parameter", - "example": "1895159" - } - } - } - }, - "etherealTransaction": { - "required": [ - "amount", - "billRefId", - "refId", - "status", - "transactionId" - ], - "type": "object", - "properties": { - "amount": { - "type": "string", - "example": "100.00" - }, - "billRefId": { - "type": "string", - "description": "The BBPS Ref ID", - "example": "C3SFG0O6N88R6UI7EQ" - }, - "refId": { - "type": "string", - "example": "COUWL910192192192192" - }, - "status": { - "type": "string", - "enum": [ - "INIT", - "SUCCESS", - "FAILURE", - "PENDING", - "UNKNOWN" - ] - }, - "transactionId": { - "type": "string", - "example": "Q910192192192192" - } - } - }, - "refundStatus": { - "type": "string", - "enum": [ - "Required", - "Requested", - "Processed" - ] - }, - "timestamp": { - "type": "string", - "description": "Timestamp provided by partner while making payment request.", - "format": "date-time", - "example": "2020-12-12T13:12:00+05:30" - }, - "transactionId": { - "type": "string", - "description": "Setu BillPay Transaction ID.", - "example": "AS01910192192192192" - }, "biller": { "required": [ "categoryName", @@ -5468,122 +6287,43 @@ ], "type": "object", "properties": { - "country": { - "type": "string", - "example": "IND" - }, - "modifiedAt": { + "bbpsUpdateTimestamp": { "type": "string", + "description": "Last updated date-time of the Biller accurate to the nearest day.", "format": "date-time", "nullable": true, "example": "2021-11-12T13:37:04.572+05:30", - "x-omitempty": false - }, - "responseType": { - "type": "string", - "nullable": true, - "example": "SINGLE", - "enum": [ - "SINGLE", - "LIST", - "SELECTIVE" - ], - "x-nullable": true, - "x-omitempty": false - }, - "subCategoryName": { - "type": "string", - "example": "DAIRY" - }, - "coverage": { - "type": "string", - "example": "IND-TEL-Hyderabad" + "x-omitempty": true }, - "interchangeFee": { + "billerAdditionalInfo": { "type": "array", "items": { + "required": [ + "dataType", + "optional", + "paramName" + ], "type": "object", "properties": { - "feeCode": { + "dataType": { "type": "string", - "example": "CCF1" + "example": "ALPHANUMERIC", + "enum": [ + "ALPHANUMERIC", + "NUMERIC" + ] }, - "feeDesc": { - "type": "string", - "example": "Customer Convenience Fee" + "optional": { + "type": "boolean", + "example": false }, - "feeDirection": { + "paramName": { "type": "string", - "example": "C2B" - }, - "interchangeFeeDetails": { - "required": [ - "effctvFrom", - "effctvTo", - "flatFee", - "percentFee", - "tranAmtRangeMax", - "tranAmtRangeMin" - ], - "type": "object", - "properties": { - "percentFee": { - "type": "number", - "format": "decimal", - "example": 1.0 - }, - "tranAmtRangeMax": { - "type": "integer", - "format": "int64" - }, - "tranAmtRangeMin": { - "type": "integer", - "format": "int64" - }, - "effctvFrom": { - "type": "string", - "example": "2024-01-01" - }, - "effctvTo": { - "type": "string", - "example": "2024-12-31" - }, - "flatFee": { - "type": "number", - "format": "decimal", - "example": 0.0 - } - } + "example": "Package Duration" } } } }, - "selectionType": { - "type": "string", - "description": "Defined only for billers with response type as LIST. SINGLE: User can pay only one of the bills in bill fetch response. MULTIPLE: User can pay any combination of bills in bill fetch response. ALL: User has to pay all the bills in bill fetch response.", - "nullable": true, - "example": "SINGLE", - "enum": [ - "SINGLE", - "MULTIPLE", - "ALL" - ], - "x-omitempty": false, - "x-nullable": true - }, - "pincode": { - "type": "string", - "example": "pincode" - }, - "supportsPendingStatus": { - "type": "boolean", - "description": "Flag indicating whether pending status is applicable for the biller or not", - "example": false - }, - "tags": { - "type": "string", - "example": "tags" - }, "billerAdditionalInfoPayment": { "type": "array", "items": { @@ -5613,6 +6353,30 @@ } } }, + "categoryName": { + "type": "string", + "description": "Biller Category", + "example": "loan-repayment" + }, + "city": { + "type": "string", + "example": "Hyderabad" + }, + "country": { + "type": "string", + "example": "IND" + }, + "coverage": { + "type": "string", + "example": "IND-TEL-Hyderabad" + }, + "createdAt": { + "type": "string", + "format": "date-time", + "nullable": true, + "example": "2021-11-12T13:37:04.572+05:30", + "x-omitempty": false + }, "customerParams": { "type": "array", "items": { @@ -5628,21 +6392,6 @@ ], "type": "object", "properties": { - "paramName": { - "type": "string", - "example": "Loan Account Number" - }, - "regex": { - "type": "string", - "example": "^[a-zA-Z0-9]{7,15}" - }, - "values": { - "type": "string" - }, - "visibility": { - "type": "boolean", - "example": true - }, "dataType": { "type": "string", "example": "ALPHANUMERIC" @@ -5656,6 +6405,22 @@ "optional": { "type": "boolean", "example": false + }, + "paramName": { + "type": "string", + "example": "Loan Account Number" + }, + "regex": { + "type": "string", + "example": "^[a-zA-Z0-9]{7,15}" + }, + "values": { + "type": "string", + "example": "CHOICE1,CHOICE2,CHOICE3" + }, + "visibility": { + "type": "boolean", + "example": true } } } @@ -5670,16 +6435,9 @@ } } }, - "id": { - "type": "string", - "description": "Identifier of the biller in BBPS.", - "example": "ADIT00000NAT0T" - }, - "createdAt": { - "type": "string", - "format": "date-time", - "nullable": true, - "example": "2021-11-12T13:37:04.572+05:30", + "enforcesSameDayFetchPay": { + "type": "boolean", + "example": true, "x-omitempty": false }, "exactness": { @@ -5701,17 +6459,132 @@ "BILL_DIRECT" ] }, - "bbpsUpdateTimestamp": { + "id": { + "type": "string", + "description": "Identifier of the biller in BBPS.", + "example": "ADIT00000NAT0T" + }, + "interchangeFee": { + "type": "array", + "items": { + "type": "object", + "properties": { + "feeCode": { + "type": "string", + "example": "CCF1" + }, + "feeDesc": { + "type": "string", + "example": "Customer Convenience Fee" + }, + "feeDirection": { + "type": "string", + "example": "C2B" + }, + "interchangeFeeDetails": { + "required": [ + "effctvFrom", + "effctvTo", + "flatFee", + "percentFee", + "tranAmtRangeMax", + "tranAmtRangeMin" + ], + "type": "object", + "properties": { + "effctvFrom": { + "type": "string", + "example": "2024-01-01" + }, + "effctvTo": { + "type": "string", + "example": "2024-12-31" + }, + "flatFee": { + "type": "number", + "format": "decimal", + "example": 0.0 + }, + "percentFee": { + "type": "number", + "format": "decimal", + "example": 1.0 + }, + "tranAmtRangeMax": { + "type": "integer", + "format": "int64" + }, + "tranAmtRangeMin": { + "type": "integer", + "format": "int64" + } + } + } + } + } + }, + "logo": { + "type": "string", + "example": "logo" + }, + "modifiedAt": { "type": "string", - "description": "Last updated date-time of the Biller accurate to the nearest day.", "format": "date-time", "nullable": true, "example": "2021-11-12T13:37:04.572+05:30", - "x-omitempty": true + "x-omitempty": false }, - "logo": { + "name": { "type": "string", - "example": "logo" + "description": "Name of the biller.", + "example": "Umbrella Corporation" + }, + "payWithoutFetchAllowed": { + "type": "boolean", + "description": "Flag indicating if the Biller accepts adhoc payment", + "example": true + }, + "paymentChannels": { + "type": "array", + "items": { + "required": [ + "maxLimit", + "minLimit", + "paymentChannel", + "supportsPendingStatus" + ], + "type": "object", + "properties": { + "maxLimit": { + "type": "integer" + }, + "minLimit": { + "type": "integer" + }, + "paymentChannel": { + "type": "string", + "description": "This is the initiating channel.\n1. `AGT`: Offline agent.\n2. `BNKBRNCH`: Bank branch.\n3. `BSC`: Business correspondent\n4. `MOB`: Mobile application\n5. `INT`: Internet portal\n6. `INTB`: Internet banking\n7. `MOBB`: Mobile banking\n8. `ATM`: ATM\n9. `KIOSK`: KIOSK\n", + "example": "INT", + "enum": [ + "INT", + "INTB", + "MOB", + "BNKBRNCH", + "BSC", + "AGT", + "KIOSK", + "ATM", + "MOBB", + "POS", + "MPOS" + ] + }, + "supportsPendingStatus": { + "type": "boolean", + "example": false + } + } + } }, "paymentModes": { "type": "array", @@ -5756,104 +6629,107 @@ } } }, - "categoryName": { + "pincode": { "type": "string", - "description": "Biller Category", - "example": "loan-repayment" + "example": "pincode" }, - "city": { + "planRequirement": { "type": "string", - "example": "Hyderabad" + "description": "Indicates if plan selection is required for bill payments", + "example": "MANDATORY", + "enum": [ + "MANDATORY", + "OPTIONAL", + "CONDITIONAL" + ], + "x-omitempty": true }, - "enforcesSameDayFetchPay": { - "type": "boolean", - "example": true, + "responseType": { + "type": "string", + "nullable": true, + "example": "SINGLE", + "enum": [ + "SINGLE", + "LIST", + "SELECTIVE" + ], + "x-nullable": true, "x-omitempty": false }, - "name": { + "selectionType": { "type": "string", - "description": "Name of the biller.", - "example": "John Doe" + "description": "Defined only for billers with response type as LIST. SINGLE: User can pay only one of the bills in bill fetch response. MULTIPLE: User can pay any combination of bills in bill fetch response. ALL: User has to pay all the bills in bill fetch response.", + "nullable": true, + "example": "SINGLE", + "enum": [ + "SINGLE", + "MULTIPLE", + "ALL" + ], + "x-nullable": true, + "x-omitempty": false }, - "billerAdditionalInfo": { - "type": "array", - "items": { - "required": [ - "dataType", - "optional", - "paramName" - ], - "type": "object", - "properties": { - "dataType": { - "type": "string", - "example": "ALPHANUMERIC", - "enum": [ - "ALPHANUMERIC", - "NUMERIC" - ] - }, - "optional": { - "type": "boolean", - "example": false - }, - "paramName": { - "type": "string", - "example": "Package Duration" - } - } - } + "state": { + "type": "string", + "example": "TEL" }, - "payWithoutFetchAllowed": { + "subCategoryName": { + "type": "string", + "example": "DAIRY" + }, + "supportsPendingStatus": { "type": "boolean", - "description": "Flag indicating if the Biller accepts adhoc payment", - "example": true + "description": "Flag indicating whether pending status is applicable for the biller or not", + "example": false }, - "paymentChannels": { + "tags": { + "type": "string", + "example": "tags" + }, + "upmsBillerParams": { "type": "array", + "description": "UPMS-specific biller parameters", "items": { "required": [ - "maxLimit", - "minLimit", - "paymentChannel", - "supportsPendingStatus" + "name" ], "type": "object", "properties": { - "paymentChannel": { + "name": { "type": "string", - "description": "This is the initiating channel.\n1. `AGT`: Offline agent.\n2. `BNKBRNCH`: Bank branch.\n3. `BSC`: Business correspondent\n4. `MOB`: Mobile application\n5. `INT`: Internet portal\n6. `INTB`: Internet banking\n7. `MOBB`: Mobile banking\n8. `ATM`: ATM\n9. `KIOSK`: KIOSK\n", - "example": "INT", - "enum": [ - "INT", - "INTB", - "MOB", - "BNKBRNCH", - "BSC", - "AGT", - "KIOSK", - "ATM", - "MOBB", - "POS", - "MPOS" - ] - }, - "supportsPendingStatus": { - "type": "boolean", - "example": false - }, - "maxLimit": { - "type": "integer" + "description": "UPMS parameter name", + "example": "mandateType" }, - "minLimit": { - "type": "integer" + "value": { + "type": "string", + "description": "UPMS parameter value", + "example": "DEBIT", + "x-omitempty": true } } - } + }, + "x-omitempty": true }, - "state": { + "upmsBillerType": { "type": "string", - "example": "TEL" + "description": "Type of UPMS biller", + "nullable": true, + "example": "MULTIPLE", + "x-omitempty": true + }, + "upmsEnabled": { + "type": "boolean", + "description": "Indicates if UPMS is enabled for this biller", + "nullable": true, + "example": true, + "x-omitempty": true + }, + "upmsRegistrationOverridingRule": { + "type": "string", + "description": "Rule specifying how to handle UPMS registration conflicts", + "nullable": true, + "example": "NEWEST", + "x-omitempty": true } }, "x-go-name": "CouBillerDetails" @@ -5862,6 +6738,109 @@ "type": "string", "description": "The biller ID on BBPS", "example": "MAHI00000NATIC" + }, + "custConvFee": { + "type": "integer", + "description": "Customer convenience fee in paise" + }, + "customerId": { + "type": "string", + "description": "Customer Identifier" + }, + "customerParams": { + "type": "array", + "description": "The bill params for fetching the bill", + "items": { + "required": [ + "name", + "value" + ], + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "The display name of the parameter. This has to match what is sent in fields.", + "example": "Loan Number" + }, + "value": { + "type": "string", + "description": "The value of the customer parameter", + "example": "1895159" + } + } + } + }, + "etherealTransaction": { + "required": [ + "amount", + "billRefId", + "refId", + "status", + "transactionId" + ], + "type": "object", + "properties": { + "amount": { + "type": "string", + "example": "100.00" + }, + "billRefId": { + "type": "string", + "description": "The BBPS Ref ID", + "example": "C3SFG0O6N88R6UI7EQ" + }, + "refId": { + "type": "string", + "example": "COUWL910192192192192" + }, + "status": { + "type": "string", + "enum": [ + "INIT", + "SUCCESS", + "FAILURE", + "PENDING", + "UNKNOWN" + ] + }, + "transactionId": { + "type": "string", + "example": "Q910192192192192" + } + } + }, + "refId": { + "type": "string", + "description": "The generated Reference ID for the request." + }, + "refundStatus": { + "type": "string", + "enum": [ + "Required", + "Requested", + "Processed" + ] + }, + "status": { + "type": "string", + "example": "Success", + "enum": [ + "Processing", + "Success", + "Error", + "Credit_Adjustment" + ] + }, + "timestamp": { + "type": "string", + "description": "Timestamp provided by partner while making payment request.", + "format": "date-time", + "example": "2020-12-12T13:12:00+05:30" + }, + "transactionId": { + "type": "string", + "description": "Setu BillPay Transaction ID.", + "example": "AS01910192192192192" } } }, @@ -5887,14 +6866,1782 @@ ] } } - } + } + } + ] + } + } + } + ], + "x-go-name": "TransactionsResponse" + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "required": [ + "error", + "success", + "traceId" + ], + "type": "object", + "properties": { + "error": { + "required": [ + "code", + "message" + ], + "type": "object", + "properties": { + "code": { + "type": "string", + "example": "validation-error" + }, + "message": { + "type": "string", + "example": "Input is invalid" + } + } + }, + "success": { + "type": "boolean", + "example": false + }, + "traceId": { + "type": "string", + "example": "C3SFG0O6N88R6UI7EQ" + } + } + } + } + } + }, + "500": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "required": [ + "error", + "success", + "traceId" + ], + "type": "object", + "properties": { + "error": { + "required": [ + "code", + "message" + ], + "type": "object", + "properties": { + "code": { + "type": "string", + "example": "validation-error" + }, + "message": { + "type": "string", + "example": "Input is invalid" + } + } + }, + "success": { + "type": "boolean", + "example": false + }, + "traceId": { + "type": "string", + "example": "C3SFG0O6N88R6UI7EQ" + } + } + } + } + } + } + }, + "security": [ + { + "Production": [ + "bbps:partner" + ] + }, + { + "Sandbox": [ + "bbps:partner" + ] + }, + { + "QA": [ + "bbps:partner" + ] + } + ] + } + }, + "/api/v2/health": { + "get": { + "tags": [ + "Health" + ], + "description": "Health check", + "operationId": "getHealth", + "responses": { + "200": { + "description": "Ok", + "content": { + "application/json": { + "schema": { + "required": [ + "environment", + "server", + "version" + ], + "type": "object", + "properties": { + "environment": { + "type": "string", + "example": "PROD" + }, + "server": { + "type": "string", + "example": "mistborn" + }, + "version": { + "type": "string", + "example": "db42717a829da9d3061e4f409f3c0ee9935b72a5" + } + }, + "x-go-name": "HealthResponseParam", + "x-omitempty": true + } + } + } + } + } + } + }, + "/api/v2/upms/registrations/{upmsRegistrationRefID}": { + "get": { + "tags": [ + "UPMS" + ], + "description": "View registration", + "operationId": "ViewUPMSRegistration", + "parameters": [ + { + "name": "X-PARTNER-ID", + "in": "header", + "description": "The Partner ID provided by Setu.", + "required": true, + "schema": { + "type": "integer" + } + }, + { + "name": "upmsRegistrationRefID", + "in": "path", + "description": "The reference ID of the UPMS registration you want to view.", + "required": true, + "schema": { + "maxLength": 35, + "minLength": 35, + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "headers": { + "X-Frame-Options": { + "description": "X Frame options", + "schema": { + "type": "string" + } + }, + "Strict-Transport-Security": { + "description": "Strict transport security", + "schema": { + "type": "string" + } + }, + "Cache-Control": { + "description": "Cache control", + "schema": { + "type": "string" + } + }, + "X-Content-Type-Options": { + "description": "X Content type options", + "schema": { + "type": "string" + } + }, + "Content-Security-Policy": { + "description": "Content security policy", + "schema": { + "type": "string" + } + }, + "Pragma": { + "description": "Pragma", + "schema": { + "type": "string" + } + }, + "X-XSS-Protection": { + "description": "X Xss Protection", + "schema": { + "type": "string" + } + } + }, + "content": { + "application/json": { + "schema": { + "required": [ + "success", + "traceId" + ], + "type": "object", + "properties": { + "data": { + "required": [ + "biller", + "createdAt", + "customer", + "mandate", + "refId", + "status" + ], + "type": "object", + "properties": { + "biller": { + "required": [ + "id" + ], + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "The biller ID on BBPS", + "example": "MAHI00000NATIC" + } + }, + "x-go-gen-location": "models", + "x-go-name": "BillerDetails" + }, + "createdAt": { + "type": "string", + "description": "Timestamp when registration was created", + "format": "date-time", + "example": "2024-06-15T10:30:45+05:30" + }, + "customer": { + "required": [ + "customerParams", + "mobile" + ], + "type": "object", + "properties": { + "customerId": { + "type": "string", + "description": "Customer Identifier" + }, + "customerParams": { + "type": "array", + "items": { + "required": [ + "name", + "value" + ], + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "The display name of the parameter. This has to match what is sent in fields.", + "example": "Loan Number" + }, + "value": { + "type": "string", + "description": "The value of the customer parameter", + "example": "1895159" + } + } + } + }, + "mobile": { + "maxLength": 22, + "minLength": 6, + "pattern": "^\\d{6,22}$", + "type": "string", + "description": "Mobile number with 6 to 22 digits are valid." + }, + "name": { + "maxLength": 100, + "type": "string", + "description": "Customer name registered with the Biller.", + "example": "Manoj Chekuri" + } + } + }, + "mandate": { + "type": "object", + "properties": { + "billPeriod": { + "type": "string", + "description": "Mandatory for Validation & Pay billers. Allowed values: DAILY, WEEKLY, BIMONTHLY, MONTHLY, QUARTERLY, HALFYEARLY, YEARLY\nOptional for Fetch & Pay billers. Allowed values: ASPRESENTED\n", + "nullable": true, + "example": "MONTHLY", + "x-omitempty": true + }, + "billerParams": { + "type": "array", + "nullable": true, + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Captures the name of the biller parameter to be sent as part of UPMS registration.", + "example": "Low Balance Threshold" + }, + "value": { + "type": "string", + "description": "The value of the biller parameter to be sent as part of UPMS registration.", + "example": "500" + } + }, + "description": "Optional. Only some billers require this. Details of the biller parameter to be sent as part of UPMS registration." + }, + "x-omitempty": true + }, + "debitInfo": { + "type": "object", + "properties": { + "amount": { + "type": "integer", + "description": "The fixed or maximum amount set for auto-debit (value must be provided in paise).", + "example": 10000 + }, + "currency": { + "type": "integer", + "description": "The currency code. Use `356` for `INR`.", + "example": 356 + }, + "debitDate": { + "type": "string", + "description": "The preferred date format (`DD-MMM`) for attempting the auto-debit each cycle.", + "example": "10-Feb" + }, + "paymentMode": { + "type": "string", + "description": "The payment method intended for auto-debit, allowed values:\n - Internet Banking\n - Debit Card\n - Credit Card\n - Prepaid Card\n - IMPS\n - UPI\n - Wallet\n - NEFT\n - AEPS\n - Account Transfer\n - Bharat QR", + "example": "UPI" + }, + "type": { + "type": "string", + "description": "Specifies the debit rule. Can be `FIXED_AMOUNT` (pay the exact bill amount) or `MAX_AMOUNT` (pay up to this limit).", + "example": "FIXED_AMOUNT" + } + }, + "description": "Details for debit information (mandatory when registrationType is AUTO_PAY)" + }, + "registrationType": { + "type": "string", + "description": "The type of registration (AUTO_PAY or VIEW_N_PAY)", + "example": "AUTO_PAY" + }, + "toDate": { + "type": "string", + "description": "The UPMS registration is invalid after this date. Date format is YYYY-MM-DD", + "nullable": true, + "example": "2027-01-01", + "x-omitempty": true } + } + }, + "refId": { + "type": "string", + "description": "The generated Reference ID for the request." + }, + "status": { + "type": "string", + "description": "A UPMS registration progresses through various states. The status field captures the current state of the registration. The possible values are: - PENDING: Initial state after a registration request is accepted but before the registration is confirmed. - SUCCESS: Registration is active; bills will be presented via callbacks. - FAILED: Registration could not be completed (e.g., invalid details). - CANCELLED: Registration permanently cancelled by user or system. - DEACTIVATED: Registration has been deactivated.", + "enum": [ + "SUCCESS", + "FAILED", + "PENDING", + "CANCELLED", + "DEACTIVATED" ] + }, + "updatedAt": { + "type": "string", + "description": "Timestamp when registration was last updated", + "format": "date-time", + "example": "2024-06-16T11:22:33+05:30" + } + } + }, + "success": { + "type": "boolean", + "description": "Boolean value indicating the status of the request", + "example": true + }, + "traceId": { + "type": "string", + "description": "The unique traceId generated for the request", + "example": "CV4PE82LTNJE9O014OE0" + } + } + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "required": [ + "error", + "success", + "traceId" + ], + "type": "object", + "properties": { + "error": { + "required": [ + "code", + "message" + ], + "type": "object", + "properties": { + "code": { + "type": "string", + "example": "validation-error" + }, + "message": { + "type": "string", + "example": "Input is invalid" + } + } + }, + "success": { + "type": "boolean", + "example": false + }, + "traceId": { + "type": "string", + "example": "C3SFG0O6N88R6UI7EQ" + } + } + } + } + } + }, + "404": { + "description": "Registration not found", + "content": { + "application/json": { + "schema": { + "required": [ + "error", + "success", + "traceId" + ], + "type": "object", + "properties": { + "error": { + "required": [ + "code", + "message" + ], + "type": "object", + "properties": { + "code": { + "type": "string", + "example": "validation-error" + }, + "message": { + "type": "string", + "example": "Input is invalid" + } + } + }, + "success": { + "type": "boolean", + "example": false + }, + "traceId": { + "type": "string", + "example": "C3SFG0O6N88R6UI7EQ" + } + } + } + } + } + }, + "500": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "required": [ + "error", + "success", + "traceId" + ], + "type": "object", + "properties": { + "error": { + "required": [ + "code", + "message" + ], + "type": "object", + "properties": { + "code": { + "type": "string", + "example": "validation-error" + }, + "message": { + "type": "string", + "example": "Input is invalid" + } + } + }, + "success": { + "type": "boolean", + "example": false + }, + "traceId": { + "type": "string", + "example": "C3SFG0O6N88R6UI7EQ" + } + } + } + } + } + } + }, + "security": [ + { + "Production": [ + "bbps:partner" + ] + }, + { + "Sandbox": [ + "bbps:partner" + ] + }, + { + "QA": [ + "bbps:partner" + ] + } + ] + }, + "delete": { + "tags": [ + "UPMS" + ], + "description": "Cancel registration", + "operationId": "CancelUPMSRegistration", + "parameters": [ + { + "name": "X-PARTNER-ID", + "in": "header", + "description": "The Partner ID provided by Setu.", + "required": true, + "schema": { + "type": "integer" + } + }, + { + "name": "upmsRegistrationRefID", + "in": "path", + "description": "The reference ID of the UPMS registration you want to cancel.", + "required": true, + "schema": { + "maxLength": 35, + "minLength": 35, + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Success response", + "headers": { + "X-Frame-Options": { + "schema": { + "type": "string" + } + }, + "Strict-Transport-Security": { + "schema": { + "type": "string" + } + }, + "Cache-Control": { + "schema": { + "type": "string" + } + }, + "X-Content-Type-Options": { + "schema": { + "type": "string" + } + }, + "Content-Security-Policy": { + "schema": { + "type": "string" + } + }, + "Pragma": { + "schema": { + "type": "string" + } + }, + "X-XSS-Protection": { + "schema": { + "type": "string" + } + } + }, + "content": { + "*/*": { + "schema": { + "required": [ + "success", + "traceId" + ], + "type": "object", + "properties": { + "success": { + "type": "boolean", + "description": "Indicator to denote whether the request is successful.", + "example": true + }, + "traceId": { + "type": "string", + "description": "The traceId generated for the request.", + "example": "C3SFG0O6N88R6UI7EQ" + } + } + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "*/*": { + "schema": { + "required": [ + "error", + "success", + "traceId" + ], + "type": "object", + "properties": { + "error": { + "required": [ + "code", + "message" + ], + "type": "object", + "properties": { + "code": { + "type": "string", + "example": "validation-error" + }, + "message": { + "type": "string", + "example": "Input is invalid" + } + } + }, + "success": { + "type": "boolean", + "example": false + }, + "traceId": { + "type": "string", + "example": "C3SFG0O6N88R6UI7EQ" + } + } + } + } + } + }, + "404": { + "description": "Registration not found or unauthorized access", + "content": { + "*/*": { + "schema": { + "required": [ + "error", + "success", + "traceId" + ], + "type": "object", + "properties": { + "error": { + "required": [ + "code", + "message" + ], + "type": "object", + "properties": { + "code": { + "type": "string", + "example": "validation-error" + }, + "message": { + "type": "string", + "example": "Input is invalid" + } + } + }, + "success": { + "type": "boolean", + "example": false + }, + "traceId": { + "type": "string", + "example": "C3SFG0O6N88R6UI7EQ" + } + } + } + } + } + }, + "409": { + "description": "Registration status invalid for cancellation", + "content": { + "*/*": { + "schema": { + "required": [ + "error", + "success", + "traceId" + ], + "type": "object", + "properties": { + "error": { + "required": [ + "code", + "message" + ], + "type": "object", + "properties": { + "code": { + "type": "string", + "example": "validation-error" + }, + "message": { + "type": "string", + "example": "Input is invalid" + } + } + }, + "success": { + "type": "boolean", + "example": false + }, + "traceId": { + "type": "string", + "example": "C3SFG0O6N88R6UI7EQ" + } + } + } + } + } + }, + "500": { + "description": "Server error", + "content": { + "*/*": { + "schema": { + "required": [ + "error", + "success", + "traceId" + ], + "type": "object", + "properties": { + "error": { + "required": [ + "code", + "message" + ], + "type": "object", + "properties": { + "code": { + "type": "string", + "example": "validation-error" + }, + "message": { + "type": "string", + "example": "Input is invalid" + } + } + }, + "success": { + "type": "boolean", + "example": false + }, + "traceId": { + "type": "string", + "example": "C3SFG0O6N88R6UI7EQ" + } + } + } + } + } + } + }, + "security": [ + { + "Production": [ + "bbps:partner" + ] + }, + { + "Sandbox": [ + "bbps:partner" + ] + }, + { + "QA": [ + "bbps:partner" + ] + } + ] + }, + "patch": { + "tags": [ + "UPMS" + ], + "description": "Update registration", + "operationId": "UpdateUPMSRegistration", + "parameters": [ + { + "name": "X-PARTNER-ID", + "in": "header", + "description": "The Partner ID provided by Setu.", + "required": true, + "schema": { + "type": "integer" + } + }, + { + "name": "upmsRegistrationRefID", + "in": "path", + "description": "The reference ID of the UPMS registration you want to update.", + "required": true, + "schema": { + "maxLength": 35, + "minLength": 35, + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "required": [ + "mandate" + ], + "type": "object", + "properties": { + "mandate": { + "type": "object", + "properties": { + "billPeriod": { + "type": "string", + "description": "Desired frequency for bill presentation/payment. Valid only for billers with fetchApiType=BILL_VALIDATE, except ASPRESENTED.", + "enum": [ + "DAILY", + "WEEKLY", + "BIMONTHLY", + "MONTHLY", + "QUARTERLY", + "HALFYEARLY", + "YEARLY", + "ASPRESENTED" + ] + }, + "debitInfo": { + "type": "object", + "properties": { + "amount": { + "maximum": 999999999, + "minimum": 1, + "type": "integer", + "description": "The amount for FIXED_AMOUNT or maximum limit for MAX_AMOUNT.", + "nullable": true, + "x-omitempty": true + }, + "debitDate": { + "pattern": "^(0[1-9]|[12][0-9]|3[01])-(Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)$", + "type": "string", + "description": "Preferred date for debit (DD-MMM format). Valid only for billers with fetchApiType=BILL_VALIDATE.", + "example": "02-Jan" + }, + "type": { + "type": "string", + "description": "Type of debit limit.", + "example": "FIXED_AMOUNT", + "enum": [ + "FIXED_AMOUNT", + "MAX_AMOUNT" + ] + } + }, + "description": "Debit details for AUTO_PAY mandate updates. Only include fields that need changing." + }, + "registrationType": { + "type": "string", + "description": "Type of registration (AUTO_PAY or VIEW_N_PAY).", + "enum": [ + "AUTO_PAY", + "VIEW_N_PAY" + ] + }, + "toDate": { + "type": "string", + "description": "The date until which the mandate is valid (YYYY-MM-DD). Must be a future date.", + "format": "date", + "example": "2027-01-01" + } + }, + "description": "Details of the mandate to be updated. Only include fields that need changing." + } + }, + "x-go-name": "CouAgentUpdateUPMSRegistrationRequest", + "x-omitempty": true + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Update request acknowledged successfully.", + "headers": { + "X-Frame-Options": { + "schema": { + "type": "string" + } + }, + "Strict-Transport-Security": { + "schema": { + "type": "string" + } + }, + "Cache-Control": { + "schema": { + "type": "string" + } + }, + "X-Content-Type-Options": { + "schema": { + "type": "string" + } + }, + "Content-Security-Policy": { + "schema": { + "type": "string" + } + }, + "Pragma": { + "schema": { + "type": "string" + } + }, + "X-XSS-Protection": { + "schema": { + "type": "string" + } + } + }, + "content": { + "application/json": { + "schema": { + "required": [ + "success", + "traceId" + ], + "type": "object", + "properties": { + "success": { + "type": "boolean", + "description": "Indicator to denote whether the request is successful.", + "example": true + }, + "traceId": { + "type": "string", + "description": "The traceId generated for the request.", + "example": "C3SFG0O6N88R6UI7EQ" + } + } + } + } + } + }, + "400": { + "description": "Bad request (e.g., validation error)", + "content": { + "application/json": { + "schema": { + "required": [ + "error", + "success", + "traceId" + ], + "type": "object", + "properties": { + "error": { + "required": [ + "code", + "message" + ], + "type": "object", + "properties": { + "code": { + "type": "string", + "example": "validation-error" + }, + "message": { + "type": "string", + "example": "Input is invalid" + } + } + }, + "success": { + "type": "boolean", + "example": false + }, + "traceId": { + "type": "string", + "example": "C3SFG0O6N88R6UI7EQ" + } + } + } + } + } + }, + "404": { + "description": "Registration not found or unauthorized access", + "content": { + "application/json": { + "schema": { + "required": [ + "error", + "success", + "traceId" + ], + "type": "object", + "properties": { + "error": { + "required": [ + "code", + "message" + ], + "type": "object", + "properties": { + "code": { + "type": "string", + "example": "validation-error" + }, + "message": { + "type": "string", + "example": "Input is invalid" + } + } + }, + "success": { + "type": "boolean", + "example": false + }, + "traceId": { + "type": "string", + "example": "C3SFG0O6N88R6UI7EQ" + } + } + } + } + } + }, + "409": { + "description": "Conflict (e.g., trying to update a cancelled registration)", + "content": { + "application/json": { + "schema": { + "required": [ + "error", + "success", + "traceId" + ], + "type": "object", + "properties": { + "error": { + "required": [ + "code", + "message" + ], + "type": "object", + "properties": { + "code": { + "type": "string", + "example": "validation-error" + }, + "message": { + "type": "string", + "example": "Input is invalid" + } + } + }, + "success": { + "type": "boolean", + "example": false + }, + "traceId": { + "type": "string", + "example": "C3SFG0O6N88R6UI7EQ" + } + } + } + } + } + }, + "500": { + "description": "Internal server error", + "content": { + "application/json": { + "schema": { + "required": [ + "error", + "success", + "traceId" + ], + "type": "object", + "properties": { + "error": { + "required": [ + "code", + "message" + ], + "type": "object", + "properties": { + "code": { + "type": "string", + "example": "validation-error" + }, + "message": { + "type": "string", + "example": "Input is invalid" + } + } + }, + "success": { + "type": "boolean", + "example": false + }, + "traceId": { + "type": "string", + "example": "C3SFG0O6N88R6UI7EQ" + } + } + } + } + } + } + }, + "security": [ + { + "Production": [ + "bbps:partner" + ] + }, + { + "Sandbox": [ + "bbps:partner" + ] + }, + { + "QA": [ + "bbps:partner" + ] + } + ], + "x-codegen-request-body-name": "CouAgentUpdateUPMSRegistrationRequest" + } + }, + "/api/v2/upms/simulate/{billRefId}/callbacks/skip-payment": { + "post": { + "tags": [ + "UPMS" + ], + "description": "Simulate skip payment", + "operationId": "SimulateSkipPaymentNotification", + "parameters": [ + { + "name": "X-PARTNER-ID", + "in": "header", + "description": "The Partner ID provided by Setu.", + "required": true, + "schema": { + "type": "integer" + } + }, + { + "name": "billRefId", + "in": "path", + "description": "Reference ID of the Bill", + "required": true, + "schema": { + "maxLength": 35, + "minLength": 35, + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Request accepted and queued for processing", + "headers": { + "X-Frame-Options": { + "description": "X Frame options", + "schema": { + "type": "string" + } + }, + "Strict-Transport-Security": { + "description": "Strict transport security", + "schema": { + "type": "string" + } + }, + "Cache-Control": { + "description": "Cache control", + "schema": { + "type": "string" + } + }, + "X-Content-Type-Options": { + "description": "X Content type options", + "schema": { + "type": "string" + } + }, + "Content-Security-Policy": { + "description": "Content security policy", + "schema": { + "type": "string" + } + }, + "Pragma": { + "description": "Pragma", + "schema": { + "type": "string" + } + }, + "X-XSS-Protection": { + "description": "X Xss Protection", + "schema": { + "type": "string" + } + } + }, + "content": { + "application/json": { + "schema": { + "required": [ + "success", + "traceId" + ], + "type": "object", + "properties": { + "success": { + "type": "boolean", + "description": "Boolean value indicating the success of the request", + "example": true + }, + "traceId": { + "type": "string", + "description": "The traceId generated for the request", + "example": "CV4PE82LTNJE9O014OE0" + } + }, + "x-go-name": "SimulateCallbackResponse" + } + } + } + }, + "400": { + "description": "Bad request - validation failed", + "content": { + "application/json": { + "schema": { + "required": [ + "error", + "success", + "traceId" + ], + "type": "object", + "properties": { + "error": { + "required": [ + "code", + "message" + ], + "type": "object", + "properties": { + "code": { + "type": "string", + "example": "validation-error" + }, + "message": { + "type": "string", + "example": "Input is invalid" + } + } + }, + "success": { + "type": "boolean", + "example": false + }, + "traceId": { + "type": "string", + "example": "C3SFG0O6N88R6UI7EQ" + } + } + } + } + } + }, + "403": { + "description": "Forbidden - operation not allowed in current environment", + "content": { + "application/json": { + "schema": { + "required": [ + "error", + "success", + "traceId" + ], + "type": "object", + "properties": { + "error": { + "required": [ + "code", + "message" + ], + "type": "object", + "properties": { + "code": { + "type": "string", + "example": "validation-error" + }, + "message": { + "type": "string", + "example": "Input is invalid" + } + } + }, + "success": { + "type": "boolean", + "example": false + }, + "traceId": { + "type": "string", + "example": "C3SFG0O6N88R6UI7EQ" + } + } + } + } + } + }, + "404": { + "description": "Bill not found", + "content": { + "application/json": { + "schema": { + "required": [ + "error", + "success", + "traceId" + ], + "type": "object", + "properties": { + "error": { + "required": [ + "code", + "message" + ], + "type": "object", + "properties": { + "code": { + "type": "string", + "example": "validation-error" + }, + "message": { + "type": "string", + "example": "Input is invalid" + } + } + }, + "success": { + "type": "boolean", + "example": false + }, + "traceId": { + "type": "string", + "example": "C3SFG0O6N88R6UI7EQ" + } + } + } + } + } + }, + "500": { + "description": "Internal server error", + "content": { + "application/json": { + "schema": { + "required": [ + "error", + "success", + "traceId" + ], + "type": "object", + "properties": { + "error": { + "required": [ + "code", + "message" + ], + "type": "object", + "properties": { + "code": { + "type": "string", + "example": "validation-error" + }, + "message": { + "type": "string", + "example": "Input is invalid" } } + }, + "success": { + "type": "boolean", + "example": false + }, + "traceId": { + "type": "string", + "example": "C3SFG0O6N88R6UI7EQ" } + } + } + } + } + } + }, + "security": [ + { + "Production": [ + "bbps:partner" + ] + }, + { + "Sandbox": [ + "bbps:partner" + ] + }, + { + "QA": [ + "bbps:partner" + ] + } + ] + } + }, + "/api/v2/upms/simulate/{upmsRegistrationRefId}/callbacks/bill": { + "post": { + "tags": [ + "UPMS" + ], + "description": "Simulate bill notification", + "operationId": "SimulateBillNotification", + "parameters": [ + { + "name": "X-PARTNER-ID", + "in": "header", + "description": "The Partner ID provided by Setu.", + "required": true, + "schema": { + "type": "integer" + } + }, + { + "name": "upmsRegistrationRefId", + "in": "path", + "description": "Reference ID of the UPMS registration", + "required": true, + "schema": { + "maxLength": 35, + "minLength": 35, + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Request accepted and queued for processing", + "headers": { + "X-Frame-Options": { + "description": "X Frame options", + "schema": { + "type": "string" + } + }, + "Strict-Transport-Security": { + "description": "Strict transport security", + "schema": { + "type": "string" + } + }, + "Cache-Control": { + "description": "Cache control", + "schema": { + "type": "string" + } + }, + "X-Content-Type-Options": { + "description": "X Content type options", + "schema": { + "type": "string" + } + }, + "Content-Security-Policy": { + "description": "Content security policy", + "schema": { + "type": "string" + } + }, + "Pragma": { + "description": "Pragma", + "schema": { + "type": "string" + } + }, + "X-XSS-Protection": { + "description": "X Xss Protection", + "schema": { + "type": "string" + } + } + }, + "content": { + "application/json": { + "schema": { + "required": [ + "success", + "traceId" ], - "x-go-name": "TransactionsResponse" + "type": "object", + "properties": { + "success": { + "type": "boolean", + "description": "Boolean value indicating the success of the request", + "example": true + }, + "traceId": { + "type": "string", + "description": "The traceId generated for the request", + "example": "CV4PE82LTNJE9O014OE0" + } + }, + "x-go-name": "SimulateCallbackResponse" + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "required": [ + "error", + "success", + "traceId" + ], + "type": "object", + "properties": { + "error": { + "required": [ + "code", + "message" + ], + "type": "object", + "properties": { + "code": { + "type": "string", + "example": "validation-error" + }, + "message": { + "type": "string", + "example": "Input is invalid" + } + } + }, + "success": { + "type": "boolean", + "example": false + }, + "traceId": { + "type": "string", + "example": "C3SFG0O6N88R6UI7EQ" + } + } + } + } + } + }, + "403": { + "description": "Forbidden in current environment", + "content": { + "application/json": { + "schema": { + "required": [ + "error", + "success", + "traceId" + ], + "type": "object", + "properties": { + "error": { + "required": [ + "code", + "message" + ], + "type": "object", + "properties": { + "code": { + "type": "string", + "example": "validation-error" + }, + "message": { + "type": "string", + "example": "Input is invalid" + } + } + }, + "success": { + "type": "boolean", + "example": false + }, + "traceId": { + "type": "string", + "example": "C3SFG0O6N88R6UI7EQ" + } + } + } + } + } + }, + "404": { + "description": "Registration not found", + "content": { + "application/json": { + "schema": { + "required": [ + "error", + "success", + "traceId" + ], + "type": "object", + "properties": { + "error": { + "required": [ + "code", + "message" + ], + "type": "object", + "properties": { + "code": { + "type": "string", + "example": "validation-error" + }, + "message": { + "type": "string", + "example": "Input is invalid" + } + } + }, + "success": { + "type": "boolean", + "example": false + }, + "traceId": { + "type": "string", + "example": "C3SFG0O6N88R6UI7EQ" + } + } + } + } + } + }, + "500": { + "description": "Internal server error", + "content": { + "application/json": { + "schema": { + "required": [ + "error", + "success", + "traceId" + ], + "type": "object", + "properties": { + "error": { + "required": [ + "code", + "message" + ], + "type": "object", + "properties": { + "code": { + "type": "string", + "example": "validation-error" + }, + "message": { + "type": "string", + "example": "Input is invalid" + } + } + }, + "success": { + "type": "boolean", + "example": false + }, + "traceId": { + "type": "string", + "example": "C3SFG0O6N88R6UI7EQ" + } + } } } } @@ -5902,13 +8649,19 @@ }, "security": [ { - "Production": ["bbps:partner"] + "Production": [ + "bbps:partner" + ] }, { - "Sandbox": ["bbps:partner"] + "Sandbox": [ + "bbps:partner" + ] }, { - "QA": ["bbps:partner"] + "QA": [ + "bbps:partner" + ] } ] } @@ -5953,4 +8706,4 @@ } }, "x-original-swagger-version": "2.0" -} +} \ No newline at end of file diff --git a/content/menuItems.json b/content/menuItems.json index e0b743ed..b3413034 100644 --- a/content/menuItems.json +++ b/content/menuItems.json @@ -1 +1 @@ -{"home":[{"name":"Payments","path":"payments","order":0,"visible_in_sidebar":true,"api_reference":true,"children":[{"name":"BBPS BillCollect","path":"bbps","order":0,"visible_in_sidebar":true,"children":[{"name":"API reference","visible_in_sidebar":true,"page_title":"BBPS API reference","path":"api-reference","order":9},{"name":"Axis BBPS","visible_in_sidebar":false,"page_title":"Axis BBPS API Approach Document","path":"axis","order":10},{"name":"Bill Structure","visible_in_sidebar":true,"page_title":"BBPS - Bill Structure","path":"bill-structure","order":5,"children":[{"name":"Special cases","visible_in_sidebar":true,"page_title":"BBPS - Bill Structure special cases","path":"special-cases","order":1}]},{"name":"Go live","visible_in_sidebar":true,"page_title":"BBPS - Go live","path":"go-live","order":3},{"name":"Notifications","visible_in_sidebar":true,"page_title":"BBPS - Notifications","path":"notifications","order":4},{"name":"Overview","visible_in_sidebar":true,"page_title":"BBPS - Overview","path":"overview","order":1},{"name":"Quickstart","visible_in_sidebar":true,"page_title":"BBPS - Quickstart","path":"quickstart","order":2,"children":[{"name":"API integration","visible_in_sidebar":true,"page_title":"BBPS - API integration","path":"api-integration","order":2},{"name":"No-code CSV","visible_in_sidebar":true,"page_title":"BBPS - No-code CSV","path":"no-code-integration","order":1},{"name":"Share bills","visible_in_sidebar":false,"page_title":"BBPS - Share bills","path":"share-biils","order":1}]},{"name":"Reports API","visible_in_sidebar":true,"page_title":"BBPS - Reports API","path":"reports","order":6},{"name":"Additional resources","visible_in_sidebar":true,"page_title":"BBPS - Additional Resources","path":"resources","order":8,"children":[{"name":"Errors","visible_in_sidebar":true,"page_title":"BBPS error codes","path":"errors","order":4},{"name":"JWT authentication","visible_in_sidebar":true,"page_title":"UPI Deeplinks JWT authentication","path":"jwt","order":2},{"name":"OAuth 2.0","visible_in_sidebar":true,"page_title":"BBPS OAuth 2.0","path":"oauth","order":1},{"name":"Settlement object","visible_in_sidebar":true,"page_title":"UPI Deeplinks settlement object","path":"settlement-object","order":3}]}]},{"name":"BBPS BillPay","path":"billpay","order":1,"versions":["v1","v2"],"default_version":"v2","visible_in_sidebar":true,"children":[{"name":"API integration","visible_in_sidebar":true,"page_title":"BBPS Billpay API integration","path":"api-integration","order":1,"children":[{"name":"API reference","visible_in_sidebar":true,"page_title":"COU Direct Connectivity API reference","path":"api-reference","order":7},{"name":"List of APIs","visible_in_sidebar":true,"page_title":"BBPS COU - List of APIs","path":"apis","order":2},{"name":"Deprecated APIs","visible_in_sidebar":false,"page_title":"BBPS COU - API integration (deprecated)","path":"deprecated","order":4,"children":[{"name":"Mock environment","visible_in_sidebar":false,"page_title":"BBPS Billpay Mock environment","path":"mock-environment","order":2},{"name":"Polling","visible_in_sidebar":false,"page_title":"BBPS Billpay polling","path":"polling","order":2}]},{"name":"Objects","visible_in_sidebar":true,"page_title":"BBPS COU - Objects","path":"objects","order":3},{"name":"Quickstart","visible_in_sidebar":true,"page_title":"BBPS COU - API integration","path":"quickstart","order":1},{"name":"Remitter Details","visible_in_sidebar":true,"page_title":"Remitter Details For Bill Payments Integration Guide","path":"remittance_flows_guide","order":6},{"name":"Migration Guide to v2","visible_in_sidebar":true,"page_title":"BBPS COU - Migration Guide to v2","path":"v2-migration","order":5},{"name":"Webhooks","visible_in_sidebar":true,"page_title":"BBPS COU - Webhooks","path":"webhooks","order":4}]},{"name":"API reference","visible_in_sidebar":false,"page_title":"BillPay API reference","path":"api-reference","order":5},{"name":"Prepaid Recharge","visible_in_sidebar":true,"page_title":"BBPS Billpay Prepaid Recharge APIs","path":"mobile-prepaid-recharge","order":3,"children":[{"name":"API reference","visible_in_sidebar":true,"page_title":"Mobile Prepaid Recharge API reference","path":"api-reference","order":2},{"name":"Quickstart","visible_in_sidebar":true,"page_title":"Mobile Prepaid Recharge quickstart","path":"quickstart","order":1}]},{"name":"Overview","visible_in_sidebar":true,"page_title":"BBPS Billpay Overview","path":"overview","order":0},{"name":"Pre-built screens","visible_in_sidebar":true,"page_title":"BBPS Billpay pre-built screens","path":"pre-built-screens","order":2,"children":[{"name":"API reference","visible_in_sidebar":false,"page_title":"BBPS Billpay API reference","path":"api-reference-wl","order":4},{"name":"API reference","visible_in_sidebar":true,"page_title":"BBPS Billpay API reference","path":"api-reference","order":5},{"name":"Custom payment","visible_in_sidebar":true,"page_title":"BBPS Billpay custom payment","path":"custom-payment","order":2,"children":[{"name":"Android","visible_in_sidebar":true,"page_title":"BBPS Billpay android integration for custom payment","path":"android","order":3},{"name":"Required APIs","visible_in_sidebar":true,"page_title":"BBPS Billpay APIs for custom payment","path":"apis","order":1},{"name":"Cross platform","visible_in_sidebar":true,"page_title":"BBPS Billpay cross-platform integration for custom payment","path":"cross-platform","order":3},{"name":"iOS","visible_in_sidebar":true,"page_title":"BBPS Billpay iOS integration for custom payment","path":"iOS","order":4},{"name":"Website","visible_in_sidebar":true,"page_title":"BBPS Billpay website integration for custom payment","path":"website","order":2}]},{"name":"Quickstart","visible_in_sidebar":true,"page_title":"BBPS Billpay Quickstart","path":"quickstart","order":1,"children":[{"name":"Android","visible_in_sidebar":true,"page_title":"BBPS Billpay Android integration","path":"android","order":2},{"name":"API","visible_in_sidebar":false,"page_title":"BBPS Billpay API","path":"api","order":2},{"name":"Cross platform","visible_in_sidebar":true,"page_title":"BBPS Billpay cross platform integration","path":"cross-platform","order":4},{"name":"iOS","visible_in_sidebar":true,"page_title":"BBPS Billpay iOS integration","path":"iOS","order":3},{"name":"Website","visible_in_sidebar":true,"page_title":"BBPS Billpay website","path":"website","order":1}]},{"name":"Remitter Details","visible_in_sidebar":true,"page_title":"Remitter Details For Bill Payments Integration Guide","path":"remitter-details","order":4},{"name":"Webhooks","visible_in_sidebar":true,"page_title":"BBPS Billpay webhooks","path":"webhooks","order":2}]},{"path":"v1","children":[{"name":"API integration","visible_in_sidebar":true,"page_title":"BBPS Billpay API integration","path":"api-integration","order":1,"children":[{"name":"API reference","visible_in_sidebar":true,"page_title":"COU Direct Connectivity API reference","path":"api-reference","order":5},{"name":"List of APIs","visible_in_sidebar":true,"page_title":"BBPS COU - List of APIs","path":"apis","order":2},{"name":"Deprecated APIs","visible_in_sidebar":false,"page_title":"BBPS COU - API integration (deprecated)","path":"deprecated","order":4,"children":[{"name":"Mock environment","visible_in_sidebar":false,"page_title":"BBPS Billpay Mock environment","path":"mock-environment","order":2},{"name":"Polling","visible_in_sidebar":false,"page_title":"BBPS Billpay polling","path":"polling","order":2}]},{"name":"Objects","visible_in_sidebar":true,"page_title":"BBPS COU - Objects","path":"objects","order":3},{"name":"Quickstart","visible_in_sidebar":true,"page_title":"BBPS COU - API integration","path":"quickstart","order":1},{"name":"Webhooks","visible_in_sidebar":true,"page_title":"BBPS COU - Webhooks","path":"webhooks","order":4}]},{"name":"API reference","visible_in_sidebar":false,"page_title":"BillPay API reference","path":"api-reference","order":5},{"name":"Overview","visible_in_sidebar":true,"page_title":"BBPS Billpay Overview","path":"overview","order":0},{"name":"Pre-built screens","visible_in_sidebar":true,"page_title":"BBPS Billpay pre-built screens","path":"pre-built-screens","order":2,"children":[{"name":"API reference","visible_in_sidebar":false,"page_title":"BBPS Billpay API reference","path":"api-reference-wl","order":4},{"name":"API reference","visible_in_sidebar":true,"page_title":"BBPS Billpay API reference","path":"api-reference","order":4},{"name":"Custom payment","visible_in_sidebar":true,"page_title":"BBPS Billpay custom payment","path":"custom-payment","order":2,"children":[{"name":"Android","visible_in_sidebar":true,"page_title":"BBPS Billpay android integration for custom payment","path":"android","order":3},{"name":"Required APIs","visible_in_sidebar":true,"page_title":"BBPS Billpay APIs for custom payment","path":"apis","order":1},{"name":"Cross platform","visible_in_sidebar":true,"page_title":"BBPS Billpay cross-platform integration for custom payment","path":"cross-platform","order":3},{"name":"iOS","visible_in_sidebar":true,"page_title":"BBPS Billpay iOS integration for custom payment","path":"iOS","order":4},{"name":"Website","visible_in_sidebar":true,"page_title":"BBPS Billpay website integration for custom payment","path":"website","order":2}]},{"name":"Quickstart","visible_in_sidebar":true,"page_title":"BBPS Billpay Quickstart","path":"quickstart","order":1,"children":[{"name":"Android","visible_in_sidebar":true,"page_title":"BBPS Billpay Android integration","path":"android","order":2},{"name":"API","visible_in_sidebar":true,"page_title":"BBPS Billpay API","path":"api","order":2},{"name":"Cross platform","visible_in_sidebar":true,"page_title":"BBPS Billpay cross platform integration","path":"cross-platform","order":4},{"name":"iOS","visible_in_sidebar":true,"page_title":"BBPS Billpay iOS integration","path":"iOS","order":3},{"name":"Website","visible_in_sidebar":true,"page_title":"BBPS Billpay website","path":"website","order":1}]},{"name":"Webhooks","visible_in_sidebar":true,"page_title":"BBPS Billpay webhooks","path":"webhooks","order":2}]}]}]},{"name":"WhatsApp Collect","path":"whatsapp-collect","order":3,"visible_in_sidebar":true,"children":[{"name":"API Integration","visible_in_sidebar":true,"page_title":"WhatsApp Collect API Integration","path":"api-integration","order":3},{"name":"API reference","visible_in_sidebar":true,"page_title":"WhatsApp Collect API reference","path":"api-reference","order":5},{"name":"Error codes","visible_in_sidebar":true,"page_title":"WhatsApp Collect error codes","path":"errors","order":4},{"name":"Collection journey","visible_in_sidebar":true,"page_title":"WhatsApp Collect Journey","path":"journey","order":1},{"name":"Overview","visible_in_sidebar":true,"page_title":"WhatsApp Collect Overview","path":"overview","order":0},{"name":"Collection reminders","visible_in_sidebar":true,"page_title":"WhatsApp Collect reminders","path":"reminders","order":2}]},{"name":"UPI DeepLinks","path":"upi-deeplinks","order":4,"visible_in_sidebar":true,"children":[{"name":"API reference","visible_in_sidebar":true,"page_title":"UPI Deeplinks API reference","path":"api-reference","order":8},{"name":"Notifications","visible_in_sidebar":true,"page_title":"UPI Deeplinks Notifications","path":"notifications","order":6},{"name":"Overview","visible_in_sidebar":true,"page_title":"UPI Deeplinks Overview","path":"overview","order":0},{"name":"Quickstart","visible_in_sidebar":true,"page_title":"UPI Deeplinks quickstart","path":"quickstart","order":1,"children":[{"name":"Go Live","visible_in_sidebar":true,"page_title":"UPI Deeplinks go live","path":"go-live","order":1}]},{"name":"Refunds","visible_in_sidebar":true,"page_title":"UPI Deeplinks Refunds","path":"refunds","order":4},{"name":"Reports API","visible_in_sidebar":true,"page_title":"UPI Deeplinks Reports API","path":"reports","order":5},{"name":"Additional resources","visible_in_sidebar":true,"page_title":"UPI Deeplinks additonal resources","path":"resources","order":6,"children":[{"name":"JWT authentication","visible_in_sidebar":true,"page_title":"UPI Deeplinks JWT authentication","path":"jwt","order":2},{"name":"OAuth 2.0","visible_in_sidebar":true,"page_title":"UPI Deeplinks OAuth 2.0","path":"oauth","order":1},{"name":"Settlement object","visible_in_sidebar":true,"page_title":"UPI Deeplinks settlement object","path":"settlement-object","order":3}]},{"name":"SDKs","visible_in_sidebar":true,"page_title":"UPI Deeplinks SDKs","path":"sdks","order":3},{"name":"Third party verification","visible_in_sidebar":true,"page_title":"UPI Deeplinks third party verification","path":"third-party-verification","order":3}]},{"name":"UPI Setu","path":"umap","order":7,"visible_in_sidebar":true,"children":[{"name":"API integration","visible_in_sidebar":true,"page_title":"UPI Setu - API integration","path":"api-integration","order":2,"children":[{"name":"Aggregators","visible_in_sidebar":true,"page_title":"UPI Setu - API integration for aggregators","path":"aggregators","order":1},{"name":"Merchants","visible_in_sidebar":true,"page_title":"UPI Setu - API integration for merchants","path":"merchants","order":2}]},{"name":"API reference","visible_in_sidebar":true,"page_title":"UPI Setu - API reference","path":"api-reference","order":8},{"name":"UPI mandates","visible_in_sidebar":true,"page_title":"UPI mandates","path":"mandates","order":4,"children":[{"name":"Mandate operations","visible_in_sidebar":true,"page_title":"UPI Setu - Mandates - Mandate operations","path":"generic","order":5,"children":[{"name":"Pause","visible_in_sidebar":true,"page_title":"UPI Setu - Mandates - Pause","path":"pause","order":3},{"name":"Revoke","visible_in_sidebar":true,"page_title":"UPI Setu - Mandates - Revoke","path":"revoke","order":2},{"name":"Unpause","visible_in_sidebar":true,"page_title":"UPI Setu - Mandates - Unpause","path":"unpause","order":4},{"name":"Update","visible_in_sidebar":true,"page_title":"UPI Setu - Mandates - Update","path":"update","order":1}]},{"name":"OneShot","visible_in_sidebar":true,"page_title":"UPI Setu - Mandates - OneShot","path":"one-shot","order":1,"children":[{"name":"Check status","visible_in_sidebar":true,"page_title":"UPI Setu - Mandates - Check payment status","path":"check-status","order":4},{"name":"Create","visible_in_sidebar":true,"page_title":"UPI Setu - Mandates - Create One Time Mandate","path":"create","order":1},{"name":"Execute","visible_in_sidebar":true,"page_title":"UPI Setu - Mandates - Execute One Time Mandate","path":"execute","order":3},{"name":"Pre Debit Notify","visible_in_sidebar":true,"page_title":"UPI Setu - Mandates - Send One Time Mandate Pre Debit Notification","path":"pre-debit-notify","order":2}]},{"name":"Recur","visible_in_sidebar":true,"page_title":"UPI Setu - Mandates - Recur","path":"recur","order":3,"children":[{"name":"Check payment status","visible_in_sidebar":true,"page_title":"UPI Setu - Mandates - Check payment status","path":"check-status","order":4},{"name":"Create","visible_in_sidebar":true,"page_title":"UPI Setu - Mandates - Create recurring mandate","path":"create","order":1},{"name":"Execute","visible_in_sidebar":true,"page_title":"UPI Setu - Mandates - Execute mandate","path":"execute","order":3},{"name":"Pre Debit Notify","visible_in_sidebar":true,"page_title":"UPI Setu - Mandates - Send Recurring Mandate Pre Debit Notification","path":"pre-debit-notify","order":2}]},{"name":"Reserve","visible_in_sidebar":true,"page_title":"UPI Setu - Mandates - Reserve","path":"reserve","order":2,"children":[{"name":"Check status","visible_in_sidebar":true,"page_title":"UPI Setu - Mandates - Check payment status","path":"check-status","order":4},{"name":"Create","visible_in_sidebar":true,"page_title":"UPI Setu - Mandates - Create Reserve Mandate","path":"create","order":1},{"name":"Execute","visible_in_sidebar":true,"page_title":"UPI Setu - Mandates - Execute Reserve Mandate","path":"execute","order":3}]},{"name":"ReservePlus","visible_in_sidebar":true,"page_title":"UPI Setu - Mandates - ReservePlus","path":"reserve-plus","order":4,"children":[{"name":"Check status","visible_in_sidebar":true,"page_title":"UPI Setu - Mandates - Check payment status","path":"check-status","order":3},{"name":"Create","visible_in_sidebar":true,"page_title":"UPI Setu - Mandates - Create single block multi-debit","path":"create","order":1},{"name":"Execute","visible_in_sidebar":true,"page_title":"UPI Setu - Mandates - Execute single block multi-debit","path":"execute","order":2}]}]},{"name":"Merchant on-boarding","visible_in_sidebar":true,"page_title":"UPI Setu - Merchant onboarding","path":"merchant-onboarding","order":2,"children":[{"name":"Check VPA availability","visible_in_sidebar":true,"page_title":"UPI Setu - Merchant on-boarding - Check VPA availability","path":"check-vpa-availability-api","order":2},{"name":"Setup a merchant","visible_in_sidebar":true,"page_title":"UPI Setu - Merchant on-boarding - Setup merchant","path":"create-merchant-api","order":1},{"name":"Registering VPA","visible_in_sidebar":true,"page_title":"UPI Setu - Merchant on-boarding - Registering a VPA","path":"create-vpa-api","order":3}]},{"name":"Notifications and alerts","visible_in_sidebar":true,"page_title":"UPI Setu - Notifications and alerts","path":"notifications","order":7,"children":[{"name":"VPA verification","visible_in_sidebar":true,"page_title":"UPI Setu - Notifications and alerts - Customer VPA verification","path":"customer-vpa-verification","order":6},{"name":"Disputes","visible_in_sidebar":true,"page_title":"UPI Setu - Notifications and alerts - Disputes","path":"disputes","order":5},{"name":"Mandates","visible_in_sidebar":true,"page_title":"UPI Setu - Notifications and alerts - Mandates","path":"mandates","order":3,"children":[{"name":"Create","visible_in_sidebar":true,"page_title":"UPI Setu - Notifications and alerts - Creation of mandate","path":"create","order":1},{"name":"Execute","visible_in_sidebar":true,"page_title":"UPI Setu - Notifications and alerts - Mandate execution","path":"execute","order":7},{"name":"Notify","visible_in_sidebar":true,"page_title":"UPI Setu - Notifications and alerts - Mandate pre-debit notifications","path":"notify","order":6},{"name":"Pause","visible_in_sidebar":true,"page_title":"UPI Setu - Notifications and alerts - Pausing mandate","path":"pause","order":4},{"name":"Revoke","visible_in_sidebar":true,"page_title":"UPI Setu - Notifications and alerts - Revoking mandate","path":"revoke","order":3},{"name":"Unpause","visible_in_sidebar":true,"page_title":"UPI Setu - Notifications and alerts - Unpausing mandate","path":"unpause","order":5},{"name":"Update","visible_in_sidebar":true,"page_title":"UPI Setu - Notifications and alerts - Updating mandate","path":"update","order":2}]},{"name":"Payments","visible_in_sidebar":true,"page_title":"UPI Setu - Notifications and alerts - Payments","path":"payments","order":2},{"name":"Refunds","visible_in_sidebar":true,"page_title":"UPI Setu - Notifications and alerts - Refunds","path":"refunds","order":4},{"name":"Verify signature","visible_in_sidebar":true,"page_title":"UMAP - Events and notifications","path":"verify-signature","order":1}]},{"name":"Overview","visible_in_sidebar":true,"page_title":"UPI Setu - Overview","path":"overview","order":0},{"name":"UPI payments","visible_in_sidebar":true,"page_title":"UPI payments","path":"payments","order":3,"children":[{"name":"Collect","visible_in_sidebar":true,"page_title":"UPI payments - Collect","path":"collect","order":2,"children":[{"name":"Check status","visible_in_sidebar":true,"page_title":"UPI Setu payments - Collect request - Check payment status","path":"check-status","order":3},{"name":"Create","visible_in_sidebar":true,"page_title":"UPI Setu payments - Create collect request","path":"create-collect-request","order":2},{"name":"Verify customer VPA","visible_in_sidebar":true,"page_title":"UPI Setu payments - Verify customer VPA","path":"verify-customer-vpa-api","order":1}]},{"name":"Flash","visible_in_sidebar":true,"page_title":"UPI payments - Flash","path":"flash","order":1,"children":[{"name":"Check status","visible_in_sidebar":true,"page_title":"UPI Setu payments - Intent/QR - Check payment status","path":"check-status","order":2},{"name":"Dynamic QR","visible_in_sidebar":true,"page_title":"UPI Setu payments - Create Dynamic QR","path":"create-dqr","order":1},{"name":"Static QR","visible_in_sidebar":true,"page_title":"UPI Setu payments - Create Static QR","path":"create-sqr","order":1}]},{"name":"TPV","visible_in_sidebar":true,"page_title":"UPI payments - TPV","path":"tpv","order":3,"children":[{"name":"Check status","visible_in_sidebar":true,"page_title":"UPI Setu - Payments - TPV - Check payment status","path":"check-status","order":2},{"name":"Create","visible_in_sidebar":true,"page_title":"UPI Setu - Payments - Create TPV API","path":"create-tpv","order":1},{"name":"Payments","visible_in_sidebar":true,"page_title":"UMAP - Notifications and alerts - Payments","path":"life-cycle","order":1}]}]},{"name":"Quickstart","visible_in_sidebar":true,"page_title":"UPI Setu - Quickstart","path":"quickstart","order":1,"children":[{"name":"Aggregators","visible_in_sidebar":true,"page_title":"UPI Setu - Quickstart for aggregators","path":"aggregators","order":1},{"name":"Merchants","visible_in_sidebar":true,"page_title":"UPI Setu - Quickstart for merchants","path":"merchants","order":2}]},{"name":"Refunds and disputes","visible_in_sidebar":true,"page_title":"UPI Setu - Refunds and disputes","path":"refunds-disputes","order":6,"children":[{"name":"Check refund status","visible_in_sidebar":true,"page_title":"UPI Setu - Refunds and disputes - Check refund status API","path":"check-refund-status-api","order":2},{"name":"Create refund","visible_in_sidebar":true,"page_title":"UPI Setu - Refunds and disputes - Create refund API","path":"create-refund-api","order":1},{"name":"Fetch dispute","visible_in_sidebar":true,"page_title":"UPI Setu - Refunds and disputes - Fetch dispute API","path":"fetch-dispute-api","order":3}]},{"name":"Transaction Monitoring","visible_in_sidebar":false,"page_title":"UPI Setu - Transaction Monitoring","path":"transaction-monitoring","order":5,"children":[{"name":"Check status","visible_in_sidebar":true,"page_title":"UPI Setu - Transaction monitoring - Check status API","path":"check-status-api","order":1},{"name":"Check status history","visible_in_sidebar":true,"page_title":"UPI Setu - Transaction monitoring - Check status sistory API","path":"check-status-history-api","order":2},{"name":"Fetch payment","visible_in_sidebar":true,"page_title":"UPI Setu - Transaction monitoring - Fetch payment API","path":"fetch-payment-api","order":3}]}]}]},{"name":"Data","path":"data","order":1,"visible_in_sidebar":true,"children":[{"name":"KYC","path":"kyc","order":0,"visible_in_sidebar":true,"children":[{"name":"Secure Data Add-On","visible_in_sidebar":true,"page_title":"Setu Encrypted APIs","path":"encryption","order":2},{"name":"Overview","visible_in_sidebar":true,"page_title":"Setu KYC Overview","path":"overview","order":1}]},{"name":"PAN verification","path":"pan","order":0,"visible_in_sidebar":false,"children":[{"name":"API reference","visible_in_sidebar":true,"page_title":"PAN verification API reference","path":"api-reference","order":1},{"name":"Quickstart","visible_in_sidebar":true,"page_title":"PAN verification quickstart","path":"quickstart","order":0}]},{"name":"Aadhaar eSign","path":"esign","order":2,"visible_in_sidebar":true,"children":[{"name":"API reference","visible_in_sidebar":true,"page_title":"Aadhaar eSign API reference","path":"api-reference","order":9},{"name":"Error codes","visible_in_sidebar":true,"page_title":"Aadhaar eSign error codes","path":"error-codes","order":8},{"name":"eStamp overview","visible_in_sidebar":true,"page_title":"eStamp overview","path":"estamp","order":2},{"name":"Flexible eSign guide","visible_in_sidebar":true,"page_title":"Integration guide with flexible signature coordinates","path":"flexi-esign","order":4},{"name":"eSign Name Match","visible_in_sidebar":true,"page_title":"Aadhaar eSign Name Match","path":"name-match","order":6},{"name":"Notifications","visible_in_sidebar":true,"page_title":"Aadhaar eSign Notifications","path":"notifications","order":7},{"name":"Overview","visible_in_sidebar":true,"page_title":"Aadhaar eSign overview","path":"overview","order":1},{"name":"PDF templates","visible_in_sidebar":true,"page_title":"Integration guide with pdf templating API's","path":"pdf-templating","order":5},{"name":"Integration guide","visible_in_sidebar":true,"page_title":"Aadhaar eSign integration guide","path":"quickstart","order":3}]},{"name":"DigiLocker","path":"digilocker","order":3,"visible_in_sidebar":false,"children":[{"name":"API reference","visible_in_sidebar":true,"page_title":"Digilocker API reference","path":"api-reference","order":3},{"name":"Error codes","visible_in_sidebar":true,"page_title":"DigiLocker error codes","path":"error-codes","order":4},{"name":"Overview","visible_in_sidebar":true,"page_title":"Digilocker overview","path":"overview","order":0},{"name":"Pull Driving Licence","visible_in_sidebar":true,"page_title":"Digilocker Quickstart","path":"pulldrivinglicense","order":2},{"name":"Integration guide","visible_in_sidebar":true,"page_title":"Digilocker quickstart","path":"quickstart","order":1}]},{"name":"AA Gateway","path":"account-aggregator","order":4,"versions":["v1","v2"],"default_version":"v2","visible_in_sidebar":true,"children":[{"name":"API integration","visible_in_sidebar":true,"page_title":"Account Aggregator API integration","path":"api-integration","order":3,"children":[{"name":"Account Availability","visible_in_sidebar":true,"page_title":"Account Aggregator Account Availability","path":"account-availability-apis","order":5},{"name":"Consent flow","visible_in_sidebar":true,"page_title":"Account Aggregator Consent flow","path":"consent-flow","order":1},{"name":"Data flow","visible_in_sidebar":true,"page_title":"Account Aggregator Data flow","path":"data-apis","order":2},{"name":"Active FIPs","visible_in_sidebar":true,"page_title":"Account Aggregator Active FIPs","path":"fip-apis","order":4},{"name":"Notifications","visible_in_sidebar":true,"page_title":"Account Aggregator Notifications","path":"notifications","order":3}]},{"name":"API reference","visible_in_sidebar":true,"page_title":"Account Aggregator API reference","path":"api-reference","order":10},{"name":"Consent object","visible_in_sidebar":true,"page_title":"Account Aggregator consent object","path":"consent-object","order":4},{"name":"Embed Setu screens","visible_in_sidebar":true,"page_title":"Account Aggregator Embed Setu screens","path":"embed-setu-aa","order":7},{"name":"FI data types","visible_in_sidebar":true,"page_title":"Account Aggregator FI data types","path":"fi-data-types","order":5},{"name":"Licenses and go live","visible_in_sidebar":true,"page_title":"Account Aggregator license and go live process","path":"licenses-and-go-live","order":8,"children":[{"name":"Go live","visible_in_sidebar":true,"page_title":"FIU go live process","path":"go-live","order":2},{"name":"Licenses","visible_in_sidebar":true,"page_title":"Licenses required to participate in AA","path":"licenses","order":1},{"name":"Participants in AA","visible_in_sidebar":true,"page_title":"Participants in AA","path":"participants-in-aa","order":0}]},{"name":"Multi AA gateway","visible_in_sidebar":true,"page_title":"Account Aggregator multi-AA gateway","path":"multi-aa-gateway","order":2},{"name":"Overview","visible_in_sidebar":true,"page_title":"Account Aggregator overview","path":"overview","order":0},{"name":"Quickstart","visible_in_sidebar":true,"page_title":"Account Aggregator quickstart","path":"quickstart","order":1},{"path":"v1","children":[{"name":"API integration","visible_in_sidebar":true,"page_title":"Account Aggregator API integration","path":"api-integration","order":3,"children":[{"name":"Consent flow","visible_in_sidebar":true,"page_title":"Account Aggregator Consent flow","path":"consent-flow","order":1},{"name":"Data flow","visible_in_sidebar":true,"page_title":"Account Aggregator Data flow","path":"data-apis","order":2},{"name":"Active FIPs","visible_in_sidebar":true,"page_title":"Account Aggregator Active FIPs","path":"fip-apis","order":4},{"name":"Notifications","visible_in_sidebar":true,"page_title":"Account Aggregator Notifications","path":"notifications","order":3}]},{"name":"API reference","visible_in_sidebar":true,"page_title":"Account Aggregator API reference","path":"api-reference","order":10},{"name":"Consent object","visible_in_sidebar":true,"page_title":"Account Aggregator Consent object","path":"consent-object","order":4},{"name":"Embed Setu screens","visible_in_sidebar":true,"page_title":"Account Aggregator Embed Setu screens","path":"embed-setu-aa","order":7},{"name":"End-to-end encryption","visible_in_sidebar":false,"page_title":"Account Aggregator End-to-end encryption","path":"encryption","order":1},{"name":"FI data types","visible_in_sidebar":true,"page_title":"Account Aggregator FI data types","path":"fi-data-types","order":5},{"name":"Get started","visible_in_sidebar":false,"page_title":"Account Aggregator getting started","path":"get-started","order":0},{"name":"Licenses and go live","visible_in_sidebar":true,"page_title":"Account Aggregator license and go live process","path":"licenses-and-go-live","order":8,"children":[{"name":"Go live","visible_in_sidebar":true,"page_title":"FIU go live process","path":"go-live","order":2},{"name":"Licenses","visible_in_sidebar":true,"page_title":"Licenses required to participate in AA","path":"licenses","order":1},{"name":"Participants in AA","visible_in_sidebar":true,"page_title":"Participants in AA","path":"participants-in-aa","order":0}]},{"name":"Migration guide","visible_in_sidebar":true,"page_title":"Account Aggregator Migration Guide","path":"migration-guide","order":6,"children":[{"name":"Consent flow","visible_in_sidebar":true,"page_title":"Account Aggregator Consent flow","path":"consent-flow","order":1},{"name":"Data flow","visible_in_sidebar":true,"page_title":"Account Aggregator Data flow","path":"data-flow","order":2},{"name":"Notifications","visible_in_sidebar":true,"page_title":"Account Aggregator Notifications","path":"notifications","order":3}]},{"name":"Overview","visible_in_sidebar":true,"page_title":"Account Aggregator overview","path":"overview","order":0},{"name":"Postman integration","visible_in_sidebar":true,"page_title":"Account Aggregator Postman integration","path":"postman","order":2},{"name":"Quickstart","visible_in_sidebar":false,"page_title":"Account Aggregator quickstart","path":"quickstart-v1","order":1},{"name":"Quickstart","visible_in_sidebar":true,"page_title":"Account Aggregator quickstart","path":"quickstart","order":1},{"name":"Request signing","visible_in_sidebar":false,"page_title":"Account Aggregator Request signing","path":"request-signing","order":1}]}]},{"name":"Bank account verification","path":"bav","order":5,"visible_in_sidebar":false,"children":[{"name":"Penny drop","visible_in_sidebar":true,"page_title":"BAV using penny drop","path":"penny-drop","order":1,"children":[{"name":"API integration","visible_in_sidebar":true,"page_title":"BAV API integration","path":"api-integration","order":1,"children":[{"name":"Async API","visible_in_sidebar":true,"page_title":"BAV Async API integration","path":"async","order":2},{"path":"bav-codes"},{"name":"Sync API","visible_in_sidebar":true,"page_title":"BAV Sync API integration","path":"sync","order":1}]},{"name":"API reference","visible_in_sidebar":true,"page_title":"BAV API reference","path":"api-reference","order":3},{"name":"Notifications","visible_in_sidebar":true,"page_title":"BAV Async Penny drop Notifications","path":"notifications","order":2},{"name":"Quickstart","visible_in_sidebar":true,"page_title":"BAV quickstart","path":"quickstart","order":0}]},{"name":"Reverse Penny drop","visible_in_sidebar":true,"page_title":"BAV using reverse penny drop","path":"reverse-penny-drop","order":3,"children":[{"name":"API integration","visible_in_sidebar":true,"page_title":"RPD API integration","path":"api-integration","order":2},{"name":"API reference","visible_in_sidebar":true,"page_title":"BAV RPD API reference","path":"api-reference","order":4},{"name":"Quickstart","visible_in_sidebar":true,"page_title":"Quickstart for reverse penny drop","path":"quickstart","order":1},{"name":"Webhook Auth","visible_in_sidebar":true,"page_title":"Webhook Authentication","path":"webhook-authentication","order":3}]}]},{"name":"Insights","path":"insights","order":5,"versions":["v1","v2"],"default_version":"v2","visible_in_sidebar":true,"children":[{"name":"API reference","visible_in_sidebar":true,"page_title":"Setu Insights API reference","path":"api-reference","order":4},{"name":"List of insights","visible_in_sidebar":true,"page_title":"All Setu insights","path":"insights","order":2},{"name":"Notifications","visible_in_sidebar":true,"page_title":"Setu Insights notifications","path":"notifications","order":3},{"name":"Overview","visible_in_sidebar":true,"page_title":"Setu Insights overview","path":"overview","order":0},{"name":"Quickstart","visible_in_sidebar":true,"page_title":"Setu Insights quickstart","path":"quickstart","order":1,"children":[{"name":"API integration","visible_in_sidebar":true,"page_title":"Setu Insights Postman integration","path":"api-integration","order":1},{"name":"Postman integration","visible_in_sidebar":true,"page_title":"Setu Insights Postman integration","path":"postman","order":0}]},{"path":"v1","children":[{"name":"API reference","visible_in_sidebar":true,"page_title":"Setu Insights API reference","path":"api-reference","order":4},{"name":"List of insights","visible_in_sidebar":true,"page_title":"All Setu insights","path":"insights","order":2},{"name":"Notifications","visible_in_sidebar":true,"page_title":"Setu Insights notifications","path":"notifications","order":3},{"name":"Overview","visible_in_sidebar":true,"page_title":"Setu Insights overview","path":"overview","order":0},{"name":"Quickstart","visible_in_sidebar":true,"page_title":"Setu Insights quickstart","path":"quickstart","order":1,"children":[{"name":"API integration","visible_in_sidebar":true,"page_title":"Setu Insights Postman integration","path":"api-integration","order":1},{"name":"Postman integration","visible_in_sidebar":true,"page_title":"Setu Insights Postman integration","path":"postman","order":0}]}]}]},{"name":"ULI","path":"uli","order":6,"visible_in_sidebar":false,"children":[{"name":"API reference","visible_in_sidebar":true,"page_title":"GSTIN verification API reference","path":"api-reference","order":2},{"name":"Quickstart","visible_in_sidebar":true,"page_title":"GST Verification quickstart","path":"quickstart","order":1}]},{"name":"GST verification","path":"gst","order":6,"visible_in_sidebar":false,"children":[{"name":"API reference","visible_in_sidebar":true,"page_title":"GSTIN verification API reference","path":"api-reference","order":2},{"name":"Quickstart","visible_in_sidebar":true,"page_title":"GST Verification quickstart","path":"quickstart","order":1}]},{"name":"Match APIs","path":"match-apis","order":7,"visible_in_sidebar":false,"children":[{"name":"Name match","visible_in_sidebar":true,"page_title":"Name match APIs","path":"name-match","order":1,"children":[{"name":"API reference","visible_in_sidebar":true,"page_title":"Name Match API reference","path":"api-reference","order":4},{"name":"Examples","visible_in_sidebar":true,"page_title":"Name Match API response examples","path":"examples","order":3},{"name":"Overview","visible_in_sidebar":true,"page_title":"Name Match API overview","path":"overview","order":1},{"name":"Quickstart","visible_in_sidebar":true,"page_title":"Name Match API quickstart","path":"quickstart","order":2}]}]},{"name":"eKYC","path":"ekyc","order":8,"visible_in_sidebar":false,"children":[{"name":"API reference","visible_in_sidebar":true,"page_title":"eKYC API reference","path":"api-reference","order":2},{"name":"Quickstart","visible_in_sidebar":true,"page_title":"PAN verification quickstart","path":"quickstart","order":1}]}]},{"name":"Dev tools","path":"dev-tools","order":2,"visible_in_sidebar":true,"children":[{"name":"The Bridge","path":"bridge","order":0,"versions":["v1","v2"],"default_version":"v2","visible_in_sidebar":true,"children":[{"name":"Analytics and reports","visible_in_sidebar":true,"page_title":"Bridge analytics and reports","path":"analytics-and-reports","order":3},{"name":"Configure products","visible_in_sidebar":true,"page_title":"Bridge explore and configure products","path":"explore-and-configure-products","order":2},{"name":"Glossary","visible_in_sidebar":true,"page_title":"Bridge glossary","path":"glossary","order":1},{"name":"Overview","visible_in_sidebar":true,"page_title":"Bridge overview","path":"overview","order":0},{"name":"Settings","visible_in_sidebar":true,"page_title":"Bridge settings","path":"settings","order":4},{"name":"User profile","visible_in_sidebar":true,"page_title":"Bridge user profile","path":"user-profile","order":5},{"path":"v1","children":[{"name":"Bridge configuration","visible_in_sidebar":false,"page_title":"Bridge configuration","path":"configure","order":6},{"name":"Generate Token","visible_in_sidebar":false,"page_title":"Bridge generate token","path":"generate-token","order":4},{"name":"Org settings","visible_in_sidebar":true,"page_title":"Bridge org settings","path":"org-settings","order":3,"children":[{"name":"API keys","visible_in_sidebar":true,"page_title":"API keys","path":"api-keys","order":2,"children":[{"name":"JWT Auth","visible_in_sidebar":false,"page_title":"JWT Auth","path":"jwt-auth","order":3},{"name":"JWT","visible_in_sidebar":true,"page_title":"JWT","path":"jwt","order":1},{"name":"OAuth","visible_in_sidebar":true,"page_title":"OAuth","path":"oauth","order":2}]},{"name":"People","visible_in_sidebar":true,"page_title":"People","path":"people","order":1}]},{"name":"Overview","visible_in_sidebar":true,"page_title":"Bridge overview","path":"overview","order":0},{"name":"Reports","visible_in_sidebar":true,"page_title":"Bridge reports","path":"reports","order":1,"children":[{"name":"Types","visible_in_sidebar":false,"page_title":"Report types","path":"types","order":1}]},{"name":"Reports API","visible_in_sidebar":false,"page_title":"Reports API","path":"reports-api","order":5}]}]}]},{"name":"Sample Category","path":"sample-category","order":3,"visible_in_sidebar":false,"children":[{"name":"Sample Product","path":"sample-product","order":0,"visible_in_sidebar":false,"children":[{"name":"Sample Page","visible_in_sidebar":false,"page_title":"Docs sample page","path":"sample-page","order":0}]}]}]} \ No newline at end of file +{"home":[{"name":"Payments","path":"payments","order":0,"visible_in_sidebar":true,"api_reference":true,"children":[{"name":"BBPS BillCollect","path":"bbps","order":0,"visible_in_sidebar":true,"children":[{"name":"API reference","visible_in_sidebar":true,"page_title":"BBPS API reference","path":"api-reference","order":9},{"name":"Axis BBPS","visible_in_sidebar":false,"page_title":"Axis BBPS API Approach Document","path":"axis","order":10},{"name":"Bill Structure","visible_in_sidebar":true,"page_title":"BBPS - Bill Structure","path":"bill-structure","order":5,"children":[{"name":"Special cases","visible_in_sidebar":true,"page_title":"BBPS - Bill Structure special cases","path":"special-cases","order":1}]},{"name":"Go live","visible_in_sidebar":true,"page_title":"BBPS - Go live","path":"go-live","order":3},{"name":"Notifications","visible_in_sidebar":true,"page_title":"BBPS - Notifications","path":"notifications","order":4},{"name":"Overview","visible_in_sidebar":true,"page_title":"BBPS - Overview","path":"overview","order":1},{"name":"Quickstart","visible_in_sidebar":true,"page_title":"BBPS - Quickstart","path":"quickstart","order":2,"children":[{"name":"API integration","visible_in_sidebar":true,"page_title":"BBPS - API integration","path":"api-integration","order":2},{"name":"No-code CSV","visible_in_sidebar":true,"page_title":"BBPS - No-code CSV","path":"no-code-integration","order":1},{"name":"Share bills","visible_in_sidebar":false,"page_title":"BBPS - Share bills","path":"share-biils","order":1}]},{"name":"Reports API","visible_in_sidebar":true,"page_title":"BBPS - Reports API","path":"reports","order":6},{"name":"Additional resources","visible_in_sidebar":true,"page_title":"BBPS - Additional Resources","path":"resources","order":8,"children":[{"name":"Errors","visible_in_sidebar":true,"page_title":"BBPS error codes","path":"errors","order":4},{"name":"JWT authentication","visible_in_sidebar":true,"page_title":"UPI Deeplinks JWT authentication","path":"jwt","order":2},{"name":"OAuth 2.0","visible_in_sidebar":true,"page_title":"BBPS OAuth 2.0","path":"oauth","order":1},{"name":"Settlement object","visible_in_sidebar":true,"page_title":"UPI Deeplinks settlement object","path":"settlement-object","order":3}]}]},{"name":"BBPS BillPay","path":"billpay","order":1,"versions":["v1","v2"],"default_version":"v2","visible_in_sidebar":true,"children":[{"name":"API integration","visible_in_sidebar":true,"page_title":"BBPS Billpay API integration","path":"api-integration","order":1,"children":[{"name":"API reference","visible_in_sidebar":true,"page_title":"COU Direct Connectivity API reference","path":"api-reference","order":7},{"name":"List of APIs","visible_in_sidebar":true,"page_title":"BBPS COU - List of APIs","path":"apis","order":2},{"name":"Deprecated APIs","visible_in_sidebar":false,"page_title":"BBPS COU - API integration (deprecated)","path":"deprecated","order":4,"children":[{"name":"Mock environment","visible_in_sidebar":false,"page_title":"BBPS Billpay Mock environment","path":"mock-environment","order":2},{"name":"Polling","visible_in_sidebar":false,"page_title":"BBPS Billpay polling","path":"polling","order":2}]},{"name":"Objects","visible_in_sidebar":true,"page_title":"BBPS COU - Objects","path":"objects","order":3},{"name":"Quickstart","visible_in_sidebar":true,"page_title":"BBPS COU - API integration","path":"quickstart","order":1},{"name":"Remitter Details","visible_in_sidebar":true,"page_title":"Remitter Details For Bill Payments Integration Guide","path":"remittance_flows_guide","order":6},{"name":"Integrating with UPMS","visible_in_sidebar":true,"page_title":"BBPS COU - Integrating with UPMS","path":"upms","order":6},{"name":"Migration Guide to v2","visible_in_sidebar":true,"page_title":"BBPS COU - Migration Guide to v2","path":"v2-migration","order":5},{"name":"Webhooks","visible_in_sidebar":true,"page_title":"BBPS COU - Webhooks","path":"webhooks","order":4}]},{"name":"API reference","visible_in_sidebar":false,"page_title":"BillPay API reference","path":"api-reference","order":5},{"name":"Prepaid Recharge","visible_in_sidebar":true,"page_title":"BBPS Billpay Prepaid Recharge APIs","path":"mobile-prepaid-recharge","order":3,"children":[{"name":"API reference","visible_in_sidebar":true,"page_title":"Mobile Prepaid Recharge API reference","path":"api-reference","order":2},{"name":"Quickstart","visible_in_sidebar":true,"page_title":"Mobile Prepaid Recharge quickstart","path":"quickstart","order":1}]},{"name":"Overview","visible_in_sidebar":true,"page_title":"BBPS Billpay Overview","path":"overview","order":0},{"name":"Pre-built screens","visible_in_sidebar":true,"page_title":"BBPS Billpay pre-built screens","path":"pre-built-screens","order":2,"children":[{"name":"API reference","visible_in_sidebar":false,"page_title":"BBPS Billpay API reference","path":"api-reference-wl","order":4},{"name":"API reference","visible_in_sidebar":true,"page_title":"BBPS Billpay API reference","path":"api-reference","order":5},{"name":"Custom payment","visible_in_sidebar":true,"page_title":"BBPS Billpay custom payment","path":"custom-payment","order":2,"children":[{"name":"Android","visible_in_sidebar":true,"page_title":"BBPS Billpay android integration for custom payment","path":"android","order":3},{"name":"Required APIs","visible_in_sidebar":true,"page_title":"BBPS Billpay APIs for custom payment","path":"apis","order":1},{"name":"Cross platform","visible_in_sidebar":true,"page_title":"BBPS Billpay cross-platform integration for custom payment","path":"cross-platform","order":3},{"name":"iOS","visible_in_sidebar":true,"page_title":"BBPS Billpay iOS integration for custom payment","path":"iOS","order":4},{"name":"Website","visible_in_sidebar":true,"page_title":"BBPS Billpay website integration for custom payment","path":"website","order":2}]},{"name":"Quickstart","visible_in_sidebar":true,"page_title":"BBPS Billpay Quickstart","path":"quickstart","order":1,"children":[{"name":"Android","visible_in_sidebar":true,"page_title":"BBPS Billpay Android integration","path":"android","order":2},{"name":"API","visible_in_sidebar":false,"page_title":"BBPS Billpay API","path":"api","order":2},{"name":"Cross platform","visible_in_sidebar":true,"page_title":"BBPS Billpay cross platform integration","path":"cross-platform","order":4},{"name":"iOS","visible_in_sidebar":true,"page_title":"BBPS Billpay iOS integration","path":"iOS","order":3},{"name":"Website","visible_in_sidebar":true,"page_title":"BBPS Billpay website","path":"website","order":1}]},{"name":"Remitter Details","visible_in_sidebar":true,"page_title":"Remitter Details For Bill Payments Integration Guide","path":"remitter-details","order":4},{"name":"Webhooks","visible_in_sidebar":true,"page_title":"BBPS Billpay webhooks","path":"webhooks","order":2}]},{"path":"v1","children":[{"name":"API integration","visible_in_sidebar":true,"page_title":"BBPS Billpay API integration","path":"api-integration","order":1,"children":[{"name":"API reference","visible_in_sidebar":true,"page_title":"COU Direct Connectivity API reference","path":"api-reference","order":5},{"name":"List of APIs","visible_in_sidebar":true,"page_title":"BBPS COU - List of APIs","path":"apis","order":2},{"name":"Deprecated APIs","visible_in_sidebar":false,"page_title":"BBPS COU - API integration (deprecated)","path":"deprecated","order":4,"children":[{"name":"Mock environment","visible_in_sidebar":false,"page_title":"BBPS Billpay Mock environment","path":"mock-environment","order":2},{"name":"Polling","visible_in_sidebar":false,"page_title":"BBPS Billpay polling","path":"polling","order":2}]},{"name":"Objects","visible_in_sidebar":true,"page_title":"BBPS COU - Objects","path":"objects","order":3},{"name":"Quickstart","visible_in_sidebar":true,"page_title":"BBPS COU - API integration","path":"quickstart","order":1},{"name":"Webhooks","visible_in_sidebar":true,"page_title":"BBPS COU - Webhooks","path":"webhooks","order":4}]},{"name":"API reference","visible_in_sidebar":false,"page_title":"BillPay API reference","path":"api-reference","order":5},{"name":"Overview","visible_in_sidebar":true,"page_title":"BBPS Billpay Overview","path":"overview","order":0},{"name":"Pre-built screens","visible_in_sidebar":true,"page_title":"BBPS Billpay pre-built screens","path":"pre-built-screens","order":2,"children":[{"name":"API reference","visible_in_sidebar":false,"page_title":"BBPS Billpay API reference","path":"api-reference-wl","order":4},{"name":"API reference","visible_in_sidebar":true,"page_title":"BBPS Billpay API reference","path":"api-reference","order":4},{"name":"Custom payment","visible_in_sidebar":true,"page_title":"BBPS Billpay custom payment","path":"custom-payment","order":2,"children":[{"name":"Android","visible_in_sidebar":true,"page_title":"BBPS Billpay android integration for custom payment","path":"android","order":3},{"name":"Required APIs","visible_in_sidebar":true,"page_title":"BBPS Billpay APIs for custom payment","path":"apis","order":1},{"name":"Cross platform","visible_in_sidebar":true,"page_title":"BBPS Billpay cross-platform integration for custom payment","path":"cross-platform","order":3},{"name":"iOS","visible_in_sidebar":true,"page_title":"BBPS Billpay iOS integration for custom payment","path":"iOS","order":4},{"name":"Website","visible_in_sidebar":true,"page_title":"BBPS Billpay website integration for custom payment","path":"website","order":2}]},{"name":"Quickstart","visible_in_sidebar":true,"page_title":"BBPS Billpay Quickstart","path":"quickstart","order":1,"children":[{"name":"Android","visible_in_sidebar":true,"page_title":"BBPS Billpay Android integration","path":"android","order":2},{"name":"API","visible_in_sidebar":true,"page_title":"BBPS Billpay API","path":"api","order":2},{"name":"Cross platform","visible_in_sidebar":true,"page_title":"BBPS Billpay cross platform integration","path":"cross-platform","order":4},{"name":"iOS","visible_in_sidebar":true,"page_title":"BBPS Billpay iOS integration","path":"iOS","order":3},{"name":"Website","visible_in_sidebar":true,"page_title":"BBPS Billpay website","path":"website","order":1}]},{"name":"Webhooks","visible_in_sidebar":true,"page_title":"BBPS Billpay webhooks","path":"webhooks","order":2}]}]}]},{"name":"WhatsApp Collect","path":"whatsapp-collect","order":3,"visible_in_sidebar":true,"children":[{"name":"API Integration","visible_in_sidebar":true,"page_title":"WhatsApp Collect API Integration","path":"api-integration","order":3},{"name":"API reference","visible_in_sidebar":true,"page_title":"WhatsApp Collect API reference","path":"api-reference","order":5},{"name":"Error codes","visible_in_sidebar":true,"page_title":"WhatsApp Collect error codes","path":"errors","order":4},{"name":"Collection journey","visible_in_sidebar":true,"page_title":"WhatsApp Collect Journey","path":"journey","order":1},{"name":"Overview","visible_in_sidebar":true,"page_title":"WhatsApp Collect Overview","path":"overview","order":0},{"name":"Collection reminders","visible_in_sidebar":true,"page_title":"WhatsApp Collect reminders","path":"reminders","order":2}]},{"name":"UPI DeepLinks","path":"upi-deeplinks","order":4,"visible_in_sidebar":true,"children":[{"name":"API reference","visible_in_sidebar":true,"page_title":"UPI Deeplinks API reference","path":"api-reference","order":8},{"name":"Notifications","visible_in_sidebar":true,"page_title":"UPI Deeplinks Notifications","path":"notifications","order":6},{"name":"Overview","visible_in_sidebar":true,"page_title":"UPI Deeplinks Overview","path":"overview","order":0},{"name":"Quickstart","visible_in_sidebar":true,"page_title":"UPI Deeplinks quickstart","path":"quickstart","order":1,"children":[{"name":"Go Live","visible_in_sidebar":true,"page_title":"UPI Deeplinks go live","path":"go-live","order":1}]},{"name":"Refunds","visible_in_sidebar":true,"page_title":"UPI Deeplinks Refunds","path":"refunds","order":4},{"name":"Reports API","visible_in_sidebar":true,"page_title":"UPI Deeplinks Reports API","path":"reports","order":5},{"name":"Additional resources","visible_in_sidebar":true,"page_title":"UPI Deeplinks additonal resources","path":"resources","order":6,"children":[{"name":"JWT authentication","visible_in_sidebar":true,"page_title":"UPI Deeplinks JWT authentication","path":"jwt","order":2},{"name":"OAuth 2.0","visible_in_sidebar":true,"page_title":"UPI Deeplinks OAuth 2.0","path":"oauth","order":1},{"name":"Settlement object","visible_in_sidebar":true,"page_title":"UPI Deeplinks settlement object","path":"settlement-object","order":3}]},{"name":"SDKs","visible_in_sidebar":true,"page_title":"UPI Deeplinks SDKs","path":"sdks","order":3},{"name":"Third party verification","visible_in_sidebar":true,"page_title":"UPI Deeplinks third party verification","path":"third-party-verification","order":3}]},{"name":"UPI Setu","path":"umap","order":7,"visible_in_sidebar":true,"children":[{"name":"API integration","visible_in_sidebar":true,"page_title":"UPI Setu - API integration","path":"api-integration","order":2,"children":[{"name":"Aggregators","visible_in_sidebar":true,"page_title":"UPI Setu - API integration for aggregators","path":"aggregators","order":1},{"name":"Merchants","visible_in_sidebar":true,"page_title":"UPI Setu - API integration for merchants","path":"merchants","order":2}]},{"name":"API reference","visible_in_sidebar":true,"page_title":"UPI Setu - API reference","path":"api-reference","order":8},{"name":"UPI mandates","visible_in_sidebar":true,"page_title":"UPI mandates","path":"mandates","order":4,"children":[{"name":"Mandate operations","visible_in_sidebar":true,"page_title":"UPI Setu - Mandates - Mandate operations","path":"generic","order":5,"children":[{"name":"Pause","visible_in_sidebar":true,"page_title":"UPI Setu - Mandates - Pause","path":"pause","order":3},{"name":"Revoke","visible_in_sidebar":true,"page_title":"UPI Setu - Mandates - Revoke","path":"revoke","order":2},{"name":"Unpause","visible_in_sidebar":true,"page_title":"UPI Setu - Mandates - Unpause","path":"unpause","order":4},{"name":"Update","visible_in_sidebar":true,"page_title":"UPI Setu - Mandates - Update","path":"update","order":1}]},{"name":"OneShot","visible_in_sidebar":true,"page_title":"UPI Setu - Mandates - OneShot","path":"one-shot","order":1,"children":[{"name":"Check status","visible_in_sidebar":true,"page_title":"UPI Setu - Mandates - Check payment status","path":"check-status","order":4},{"name":"Create","visible_in_sidebar":true,"page_title":"UPI Setu - Mandates - Create One Time Mandate","path":"create","order":1},{"name":"Execute","visible_in_sidebar":true,"page_title":"UPI Setu - Mandates - Execute One Time Mandate","path":"execute","order":3},{"name":"Pre Debit Notify","visible_in_sidebar":true,"page_title":"UPI Setu - Mandates - Send One Time Mandate Pre Debit Notification","path":"pre-debit-notify","order":2}]},{"name":"Recur","visible_in_sidebar":true,"page_title":"UPI Setu - Mandates - Recur","path":"recur","order":3,"children":[{"name":"Check payment status","visible_in_sidebar":true,"page_title":"UPI Setu - Mandates - Check payment status","path":"check-status","order":4},{"name":"Create","visible_in_sidebar":true,"page_title":"UPI Setu - Mandates - Create recurring mandate","path":"create","order":1},{"name":"Execute","visible_in_sidebar":true,"page_title":"UPI Setu - Mandates - Execute mandate","path":"execute","order":3},{"name":"Pre Debit Notify","visible_in_sidebar":true,"page_title":"UPI Setu - Mandates - Send Recurring Mandate Pre Debit Notification","path":"pre-debit-notify","order":2}]},{"name":"Reserve","visible_in_sidebar":true,"page_title":"UPI Setu - Mandates - Reserve","path":"reserve","order":2,"children":[{"name":"Check status","visible_in_sidebar":true,"page_title":"UPI Setu - Mandates - Check payment status","path":"check-status","order":4},{"name":"Create","visible_in_sidebar":true,"page_title":"UPI Setu - Mandates - Create Reserve Mandate","path":"create","order":1},{"name":"Execute","visible_in_sidebar":true,"page_title":"UPI Setu - Mandates - Execute Reserve Mandate","path":"execute","order":3}]},{"name":"ReservePlus","visible_in_sidebar":true,"page_title":"UPI Setu - Mandates - ReservePlus","path":"reserve-plus","order":4,"children":[{"name":"Check status","visible_in_sidebar":true,"page_title":"UPI Setu - Mandates - Check payment status","path":"check-status","order":3},{"name":"Create","visible_in_sidebar":true,"page_title":"UPI Setu - Mandates - Create single block multi-debit","path":"create","order":1},{"name":"Execute","visible_in_sidebar":true,"page_title":"UPI Setu - Mandates - Execute single block multi-debit","path":"execute","order":2}]}]},{"name":"Merchant on-boarding","visible_in_sidebar":true,"page_title":"UPI Setu - Merchant onboarding","path":"merchant-onboarding","order":2,"children":[{"name":"Check VPA availability","visible_in_sidebar":true,"page_title":"UPI Setu - Merchant on-boarding - Check VPA availability","path":"check-vpa-availability-api","order":2},{"name":"Setup a merchant","visible_in_sidebar":true,"page_title":"UPI Setu - Merchant on-boarding - Setup merchant","path":"create-merchant-api","order":1},{"name":"Registering VPA","visible_in_sidebar":true,"page_title":"UPI Setu - Merchant on-boarding - Registering a VPA","path":"create-vpa-api","order":3}]},{"name":"Notifications and alerts","visible_in_sidebar":true,"page_title":"UPI Setu - Notifications and alerts","path":"notifications","order":7,"children":[{"name":"VPA verification","visible_in_sidebar":true,"page_title":"UPI Setu - Notifications and alerts - Customer VPA verification","path":"customer-vpa-verification","order":6},{"name":"Disputes","visible_in_sidebar":true,"page_title":"UPI Setu - Notifications and alerts - Disputes","path":"disputes","order":5},{"name":"Mandates","visible_in_sidebar":true,"page_title":"UPI Setu - Notifications and alerts - Mandates","path":"mandates","order":3,"children":[{"name":"Create","visible_in_sidebar":true,"page_title":"UPI Setu - Notifications and alerts - Creation of mandate","path":"create","order":1},{"name":"Execute","visible_in_sidebar":true,"page_title":"UPI Setu - Notifications and alerts - Mandate execution","path":"execute","order":7},{"name":"Notify","visible_in_sidebar":true,"page_title":"UPI Setu - Notifications and alerts - Mandate pre-debit notifications","path":"notify","order":6},{"name":"Pause","visible_in_sidebar":true,"page_title":"UPI Setu - Notifications and alerts - Pausing mandate","path":"pause","order":4},{"name":"Revoke","visible_in_sidebar":true,"page_title":"UPI Setu - Notifications and alerts - Revoking mandate","path":"revoke","order":3},{"name":"Unpause","visible_in_sidebar":true,"page_title":"UPI Setu - Notifications and alerts - Unpausing mandate","path":"unpause","order":5},{"name":"Update","visible_in_sidebar":true,"page_title":"UPI Setu - Notifications and alerts - Updating mandate","path":"update","order":2}]},{"name":"Payments","visible_in_sidebar":true,"page_title":"UPI Setu - Notifications and alerts - Payments","path":"payments","order":2},{"name":"Refunds","visible_in_sidebar":true,"page_title":"UPI Setu - Notifications and alerts - Refunds","path":"refunds","order":4},{"name":"Verify signature","visible_in_sidebar":true,"page_title":"UMAP - Events and notifications","path":"verify-signature","order":1}]},{"name":"Overview","visible_in_sidebar":true,"page_title":"UPI Setu - Overview","path":"overview","order":0},{"name":"UPI payments","visible_in_sidebar":true,"page_title":"UPI payments","path":"payments","order":3,"children":[{"name":"Collect","visible_in_sidebar":true,"page_title":"UPI payments - Collect","path":"collect","order":2,"children":[{"name":"Check status","visible_in_sidebar":true,"page_title":"UPI Setu payments - Collect request - Check payment status","path":"check-status","order":3},{"name":"Create","visible_in_sidebar":true,"page_title":"UPI Setu payments - Create collect request","path":"create-collect-request","order":2},{"name":"Verify customer VPA","visible_in_sidebar":true,"page_title":"UPI Setu payments - Verify customer VPA","path":"verify-customer-vpa-api","order":1}]},{"name":"Flash","visible_in_sidebar":true,"page_title":"UPI payments - Flash","path":"flash","order":1,"children":[{"name":"Check status","visible_in_sidebar":true,"page_title":"UPI Setu payments - Intent/QR - Check payment status","path":"check-status","order":2},{"name":"Dynamic QR","visible_in_sidebar":true,"page_title":"UPI Setu payments - Create Dynamic QR","path":"create-dqr","order":1},{"name":"Static QR","visible_in_sidebar":true,"page_title":"UPI Setu payments - Create Static QR","path":"create-sqr","order":1}]},{"name":"TPV","visible_in_sidebar":true,"page_title":"UPI payments - TPV","path":"tpv","order":3,"children":[{"name":"Check status","visible_in_sidebar":true,"page_title":"UPI Setu - Payments - TPV - Check payment status","path":"check-status","order":2},{"name":"Create","visible_in_sidebar":true,"page_title":"UPI Setu - Payments - Create TPV API","path":"create-tpv","order":1},{"name":"Payments","visible_in_sidebar":true,"page_title":"UMAP - Notifications and alerts - Payments","path":"life-cycle","order":1}]}]},{"name":"Quickstart","visible_in_sidebar":true,"page_title":"UPI Setu - Quickstart","path":"quickstart","order":1,"children":[{"name":"Aggregators","visible_in_sidebar":true,"page_title":"UPI Setu - Quickstart for aggregators","path":"aggregators","order":1},{"name":"Merchants","visible_in_sidebar":true,"page_title":"UPI Setu - Quickstart for merchants","path":"merchants","order":2}]},{"name":"Refunds and disputes","visible_in_sidebar":true,"page_title":"UPI Setu - Refunds and disputes","path":"refunds-disputes","order":6,"children":[{"name":"Check refund status","visible_in_sidebar":true,"page_title":"UPI Setu - Refunds and disputes - Check refund status API","path":"check-refund-status-api","order":2},{"name":"Create refund","visible_in_sidebar":true,"page_title":"UPI Setu - Refunds and disputes - Create refund API","path":"create-refund-api","order":1},{"name":"Fetch dispute","visible_in_sidebar":true,"page_title":"UPI Setu - Refunds and disputes - Fetch dispute API","path":"fetch-dispute-api","order":3}]},{"name":"Transaction Monitoring","visible_in_sidebar":false,"page_title":"UPI Setu - Transaction Monitoring","path":"transaction-monitoring","order":5,"children":[{"name":"Check status","visible_in_sidebar":true,"page_title":"UPI Setu - Transaction monitoring - Check status API","path":"check-status-api","order":1},{"name":"Check status history","visible_in_sidebar":true,"page_title":"UPI Setu - Transaction monitoring - Check status sistory API","path":"check-status-history-api","order":2},{"name":"Fetch payment","visible_in_sidebar":true,"page_title":"UPI Setu - Transaction monitoring - Fetch payment API","path":"fetch-payment-api","order":3}]}]}]},{"name":"Data","path":"data","order":1,"visible_in_sidebar":true,"children":[{"name":"KYC","path":"kyc","order":0,"visible_in_sidebar":true,"children":[{"name":"Secure Data Add-On","visible_in_sidebar":true,"page_title":"Setu Encrypted APIs","path":"encryption","order":2},{"name":"Overview","visible_in_sidebar":true,"page_title":"Setu KYC Overview","path":"overview","order":1}]},{"name":"PAN verification","path":"pan","order":0,"visible_in_sidebar":false,"children":[{"name":"API reference","visible_in_sidebar":true,"page_title":"PAN verification API reference","path":"api-reference","order":1},{"name":"Quickstart","visible_in_sidebar":true,"page_title":"PAN verification quickstart","path":"quickstart","order":0}]},{"name":"Aadhaar eSign","path":"esign","order":2,"visible_in_sidebar":true,"children":[{"name":"API reference","visible_in_sidebar":true,"page_title":"Aadhaar eSign API reference","path":"api-reference","order":9},{"name":"Error codes","visible_in_sidebar":true,"page_title":"Aadhaar eSign error codes","path":"error-codes","order":8},{"name":"eStamp overview","visible_in_sidebar":true,"page_title":"eStamp overview","path":"estamp","order":2},{"name":"Flexible eSign guide","visible_in_sidebar":true,"page_title":"Integration guide with flexible signature coordinates","path":"flexi-esign","order":4},{"name":"eSign Name Match","visible_in_sidebar":true,"page_title":"Aadhaar eSign Name Match","path":"name-match","order":6},{"name":"Notifications","visible_in_sidebar":true,"page_title":"Aadhaar eSign Notifications","path":"notifications","order":7},{"name":"Overview","visible_in_sidebar":true,"page_title":"Aadhaar eSign overview","path":"overview","order":1},{"name":"PDF templates","visible_in_sidebar":true,"page_title":"Integration guide with pdf templating API's","path":"pdf-templating","order":5},{"name":"Integration guide","visible_in_sidebar":true,"page_title":"Aadhaar eSign integration guide","path":"quickstart","order":3}]},{"name":"DigiLocker","path":"digilocker","order":3,"visible_in_sidebar":false,"children":[{"name":"API reference","visible_in_sidebar":true,"page_title":"Digilocker API reference","path":"api-reference","order":3},{"name":"Error codes","visible_in_sidebar":true,"page_title":"DigiLocker error codes","path":"error-codes","order":4},{"name":"Overview","visible_in_sidebar":true,"page_title":"Digilocker overview","path":"overview","order":0},{"name":"Pull Driving Licence","visible_in_sidebar":true,"page_title":"Digilocker Quickstart","path":"pulldrivinglicense","order":2},{"name":"Integration guide","visible_in_sidebar":true,"page_title":"Digilocker quickstart","path":"quickstart","order":1}]},{"name":"AA Gateway","path":"account-aggregator","order":4,"versions":["v1","v2"],"default_version":"v2","visible_in_sidebar":true,"children":[{"name":"API integration","visible_in_sidebar":true,"page_title":"Account Aggregator API integration","path":"api-integration","order":3,"children":[{"name":"Account Availability","visible_in_sidebar":true,"page_title":"Account Aggregator Account Availability","path":"account-availability-apis","order":5},{"name":"Consent flow","visible_in_sidebar":true,"page_title":"Account Aggregator Consent flow","path":"consent-flow","order":1},{"name":"Data flow","visible_in_sidebar":true,"page_title":"Account Aggregator Data flow","path":"data-apis","order":2},{"name":"Active FIPs","visible_in_sidebar":true,"page_title":"Account Aggregator Active FIPs","path":"fip-apis","order":4},{"name":"Notifications","visible_in_sidebar":true,"page_title":"Account Aggregator Notifications","path":"notifications","order":3}]},{"name":"API reference","visible_in_sidebar":true,"page_title":"Account Aggregator API reference","path":"api-reference","order":10},{"name":"Consent object","visible_in_sidebar":true,"page_title":"Account Aggregator consent object","path":"consent-object","order":4},{"name":"Embed Setu screens","visible_in_sidebar":true,"page_title":"Account Aggregator Embed Setu screens","path":"embed-setu-aa","order":7},{"name":"FI data types","visible_in_sidebar":true,"page_title":"Account Aggregator FI data types","path":"fi-data-types","order":5},{"name":"Licenses and go live","visible_in_sidebar":true,"page_title":"Account Aggregator license and go live process","path":"licenses-and-go-live","order":8,"children":[{"name":"Go live","visible_in_sidebar":true,"page_title":"FIU go live process","path":"go-live","order":2},{"name":"Licenses","visible_in_sidebar":true,"page_title":"Licenses required to participate in AA","path":"licenses","order":1},{"name":"Participants in AA","visible_in_sidebar":true,"page_title":"Participants in AA","path":"participants-in-aa","order":0}]},{"name":"Multi AA gateway","visible_in_sidebar":true,"page_title":"Account Aggregator multi-AA gateway","path":"multi-aa-gateway","order":2},{"name":"Overview","visible_in_sidebar":true,"page_title":"Account Aggregator overview","path":"overview","order":0},{"name":"Quickstart","visible_in_sidebar":true,"page_title":"Account Aggregator quickstart","path":"quickstart","order":1},{"path":"v1","children":[{"name":"API integration","visible_in_sidebar":true,"page_title":"Account Aggregator API integration","path":"api-integration","order":3,"children":[{"name":"Consent flow","visible_in_sidebar":true,"page_title":"Account Aggregator Consent flow","path":"consent-flow","order":1},{"name":"Data flow","visible_in_sidebar":true,"page_title":"Account Aggregator Data flow","path":"data-apis","order":2},{"name":"Active FIPs","visible_in_sidebar":true,"page_title":"Account Aggregator Active FIPs","path":"fip-apis","order":4},{"name":"Notifications","visible_in_sidebar":true,"page_title":"Account Aggregator Notifications","path":"notifications","order":3}]},{"name":"API reference","visible_in_sidebar":true,"page_title":"Account Aggregator API reference","path":"api-reference","order":10},{"name":"Consent object","visible_in_sidebar":true,"page_title":"Account Aggregator Consent object","path":"consent-object","order":4},{"name":"Embed Setu screens","visible_in_sidebar":true,"page_title":"Account Aggregator Embed Setu screens","path":"embed-setu-aa","order":7},{"name":"End-to-end encryption","visible_in_sidebar":false,"page_title":"Account Aggregator End-to-end encryption","path":"encryption","order":1},{"name":"FI data types","visible_in_sidebar":true,"page_title":"Account Aggregator FI data types","path":"fi-data-types","order":5},{"name":"Get started","visible_in_sidebar":false,"page_title":"Account Aggregator getting started","path":"get-started","order":0},{"name":"Licenses and go live","visible_in_sidebar":true,"page_title":"Account Aggregator license and go live process","path":"licenses-and-go-live","order":8,"children":[{"name":"Go live","visible_in_sidebar":true,"page_title":"FIU go live process","path":"go-live","order":2},{"name":"Licenses","visible_in_sidebar":true,"page_title":"Licenses required to participate in AA","path":"licenses","order":1},{"name":"Participants in AA","visible_in_sidebar":true,"page_title":"Participants in AA","path":"participants-in-aa","order":0}]},{"name":"Migration guide","visible_in_sidebar":true,"page_title":"Account Aggregator Migration Guide","path":"migration-guide","order":6,"children":[{"name":"Consent flow","visible_in_sidebar":true,"page_title":"Account Aggregator Consent flow","path":"consent-flow","order":1},{"name":"Data flow","visible_in_sidebar":true,"page_title":"Account Aggregator Data flow","path":"data-flow","order":2},{"name":"Notifications","visible_in_sidebar":true,"page_title":"Account Aggregator Notifications","path":"notifications","order":3}]},{"name":"Overview","visible_in_sidebar":true,"page_title":"Account Aggregator overview","path":"overview","order":0},{"name":"Postman integration","visible_in_sidebar":true,"page_title":"Account Aggregator Postman integration","path":"postman","order":2},{"name":"Quickstart","visible_in_sidebar":false,"page_title":"Account Aggregator quickstart","path":"quickstart-v1","order":1},{"name":"Quickstart","visible_in_sidebar":true,"page_title":"Account Aggregator quickstart","path":"quickstart","order":1},{"name":"Request signing","visible_in_sidebar":false,"page_title":"Account Aggregator Request signing","path":"request-signing","order":1}]}]},{"name":"Bank account verification","path":"bav","order":5,"visible_in_sidebar":false,"children":[{"name":"Penny drop","visible_in_sidebar":true,"page_title":"BAV using penny drop","path":"penny-drop","order":1,"children":[{"name":"API integration","visible_in_sidebar":true,"page_title":"BAV API integration","path":"api-integration","order":1,"children":[{"name":"Async API","visible_in_sidebar":true,"page_title":"BAV Async API integration","path":"async","order":2},{"path":"bav-codes"},{"name":"Sync API","visible_in_sidebar":true,"page_title":"BAV Sync API integration","path":"sync","order":1}]},{"name":"API reference","visible_in_sidebar":true,"page_title":"BAV API reference","path":"api-reference","order":3},{"name":"Notifications","visible_in_sidebar":true,"page_title":"BAV Async Penny drop Notifications","path":"notifications","order":2},{"name":"Quickstart","visible_in_sidebar":true,"page_title":"BAV quickstart","path":"quickstart","order":0}]},{"name":"Reverse Penny drop","visible_in_sidebar":true,"page_title":"BAV using reverse penny drop","path":"reverse-penny-drop","order":3,"children":[{"name":"API integration","visible_in_sidebar":true,"page_title":"RPD API integration","path":"api-integration","order":2},{"name":"API reference","visible_in_sidebar":true,"page_title":"BAV RPD API reference","path":"api-reference","order":4},{"name":"Quickstart","visible_in_sidebar":true,"page_title":"Quickstart for reverse penny drop","path":"quickstart","order":1},{"name":"Webhook Auth","visible_in_sidebar":true,"page_title":"Webhook Authentication","path":"webhook-authentication","order":3}]}]},{"name":"Insights","path":"insights","order":5,"versions":["v1","v2"],"default_version":"v2","visible_in_sidebar":true,"children":[{"name":"API reference","visible_in_sidebar":true,"page_title":"Setu Insights API reference","path":"api-reference","order":4},{"name":"List of insights","visible_in_sidebar":true,"page_title":"All Setu insights","path":"insights","order":2},{"name":"Notifications","visible_in_sidebar":true,"page_title":"Setu Insights notifications","path":"notifications","order":3},{"name":"Overview","visible_in_sidebar":true,"page_title":"Setu Insights overview","path":"overview","order":0},{"name":"Quickstart","visible_in_sidebar":true,"page_title":"Setu Insights quickstart","path":"quickstart","order":1,"children":[{"name":"API integration","visible_in_sidebar":true,"page_title":"Setu Insights Postman integration","path":"api-integration","order":1},{"name":"Postman integration","visible_in_sidebar":true,"page_title":"Setu Insights Postman integration","path":"postman","order":0}]},{"path":"v1","children":[{"name":"API reference","visible_in_sidebar":true,"page_title":"Setu Insights API reference","path":"api-reference","order":4},{"name":"List of insights","visible_in_sidebar":true,"page_title":"All Setu insights","path":"insights","order":2},{"name":"Notifications","visible_in_sidebar":true,"page_title":"Setu Insights notifications","path":"notifications","order":3},{"name":"Overview","visible_in_sidebar":true,"page_title":"Setu Insights overview","path":"overview","order":0},{"name":"Quickstart","visible_in_sidebar":true,"page_title":"Setu Insights quickstart","path":"quickstart","order":1,"children":[{"name":"API integration","visible_in_sidebar":true,"page_title":"Setu Insights Postman integration","path":"api-integration","order":1},{"name":"Postman integration","visible_in_sidebar":true,"page_title":"Setu Insights Postman integration","path":"postman","order":0}]}]}]},{"name":"ULI","path":"uli","order":6,"visible_in_sidebar":false,"children":[{"name":"API reference","visible_in_sidebar":true,"page_title":"GSTIN verification API reference","path":"api-reference","order":2},{"name":"Quickstart","visible_in_sidebar":true,"page_title":"GST Verification quickstart","path":"quickstart","order":1}]},{"name":"GST verification","path":"gst","order":6,"visible_in_sidebar":false,"children":[{"name":"API reference","visible_in_sidebar":true,"page_title":"GSTIN verification API reference","path":"api-reference","order":2},{"name":"Quickstart","visible_in_sidebar":true,"page_title":"GST Verification quickstart","path":"quickstart","order":1}]},{"name":"Match APIs","path":"match-apis","order":7,"visible_in_sidebar":false,"children":[{"name":"Name match","visible_in_sidebar":true,"page_title":"Name match APIs","path":"name-match","order":1,"children":[{"name":"API reference","visible_in_sidebar":true,"page_title":"Name Match API reference","path":"api-reference","order":4},{"name":"Examples","visible_in_sidebar":true,"page_title":"Name Match API response examples","path":"examples","order":3},{"name":"Overview","visible_in_sidebar":true,"page_title":"Name Match API overview","path":"overview","order":1},{"name":"Quickstart","visible_in_sidebar":true,"page_title":"Name Match API quickstart","path":"quickstart","order":2}]}]},{"name":"eKYC","path":"ekyc","order":8,"visible_in_sidebar":false,"children":[{"name":"API reference","visible_in_sidebar":true,"page_title":"eKYC API reference","path":"api-reference","order":2},{"name":"Quickstart","visible_in_sidebar":true,"page_title":"PAN verification quickstart","path":"quickstart","order":1}]}]},{"name":"Dev tools","path":"dev-tools","order":2,"visible_in_sidebar":true,"children":[{"name":"The Bridge","path":"bridge","order":0,"versions":["v1","v2"],"default_version":"v2","visible_in_sidebar":true,"children":[{"name":"Analytics and reports","visible_in_sidebar":true,"page_title":"Bridge analytics and reports","path":"analytics-and-reports","order":3},{"name":"Configure products","visible_in_sidebar":true,"page_title":"Bridge explore and configure products","path":"explore-and-configure-products","order":2},{"name":"Glossary","visible_in_sidebar":true,"page_title":"Bridge glossary","path":"glossary","order":1},{"name":"Overview","visible_in_sidebar":true,"page_title":"Bridge overview","path":"overview","order":0},{"name":"Settings","visible_in_sidebar":true,"page_title":"Bridge settings","path":"settings","order":4},{"name":"User profile","visible_in_sidebar":true,"page_title":"Bridge user profile","path":"user-profile","order":5},{"path":"v1","children":[{"name":"Bridge configuration","visible_in_sidebar":false,"page_title":"Bridge configuration","path":"configure","order":6},{"name":"Generate Token","visible_in_sidebar":false,"page_title":"Bridge generate token","path":"generate-token","order":4},{"name":"Org settings","visible_in_sidebar":true,"page_title":"Bridge org settings","path":"org-settings","order":3,"children":[{"name":"API keys","visible_in_sidebar":true,"page_title":"API keys","path":"api-keys","order":2,"children":[{"name":"JWT Auth","visible_in_sidebar":false,"page_title":"JWT Auth","path":"jwt-auth","order":3},{"name":"JWT","visible_in_sidebar":true,"page_title":"JWT","path":"jwt","order":1},{"name":"OAuth","visible_in_sidebar":true,"page_title":"OAuth","path":"oauth","order":2}]},{"name":"People","visible_in_sidebar":true,"page_title":"People","path":"people","order":1}]},{"name":"Overview","visible_in_sidebar":true,"page_title":"Bridge overview","path":"overview","order":0},{"name":"Reports","visible_in_sidebar":true,"page_title":"Bridge reports","path":"reports","order":1,"children":[{"name":"Types","visible_in_sidebar":false,"page_title":"Report types","path":"types","order":1}]},{"name":"Reports API","visible_in_sidebar":false,"page_title":"Reports API","path":"reports-api","order":5}]}]}]},{"name":"Sample Category","path":"sample-category","order":3,"visible_in_sidebar":false,"children":[{"name":"Sample Product","path":"sample-product","order":0,"visible_in_sidebar":false,"children":[{"name":"Sample Page","visible_in_sidebar":false,"page_title":"Docs sample page","path":"sample-page","order":0}]}]}]} \ No newline at end of file diff --git a/content/payments/billpay/api-integration/apis.mdx b/content/payments/billpay/api-integration/apis.mdx index 5790ca29..b2058626 100644 --- a/content/payments/billpay/api-integration/apis.mdx +++ b/content/payments/billpay/api-integration/apis.mdx @@ -23,84 +23,117 @@ For e.g., if your customer wants to pay their phone bill for Vodafone Postpaid, +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](upms.mdx)). +If you include the `mandate` object in the request, a registration will be initiated for the customer with the biller. + +
- Detailed sample request body + Sample Request {` - { - "customer": { - "mobile": "9505987798", - "billParameters": [ - { - "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" - } - } +{ + "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" + }, + "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. +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, - "error": null + "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. +In the response you either get the bill details, or "Processing" status if the bill fetch is still in progress.
@@ -130,32 +163,33 @@ In the response you either get the bill details, or “Processing” status if t "value": "Samuraipsychadelic" } ], - "bill": { // optional - selective present for SINGLE billers - "amount": 300000, - "billDate": "2021-09-13", - "billNumber": "8394852342371080869", - "billPeriod": "Monthly", - "customerName": "William Miller", - "dueDate": "2021-09-26", - "paymentOptions": [ - { - "name": "3 month EMI", - "amount": 900000, - "minAmount": 300000, - "maxAmount": 1500000, - "amountMultiple": 10000 - }, - { - "name": "6 month EMI", - "amount": 1800000, - "minAmount": 600000, - "maxAmount": 3000000, - "amountMultiple": 10000 - } - ] - }, - "billerResponseType": "SINGLE", - "billerSelectionType": null, + "bills": [ + { + "amount": 300000, + "billDate": "2021-09-13", + "billNumber": "8394852342371080869", + "billPeriod": "Monthly", + "customerName": "William Miller", + "dueDate": "2021-09-26", + "paymentOptions": [ + { + "name": "3 month EMI", + "amount": 900000, + "minAmount": 300000, + "maxAmount": 1500000, + "amountMultiple": 10000 + }, + { + "name": "6 month EMI", + "amount": 1800000, + "minAmount": 600000, + "maxAmount": 3000000, + "amountMultiple": 10000 + } + ] + } + ], + "billerResponseType": "SINGLE", "billerRefId": "4047076513", "exactness": "Exact", "paymentLimits": [ @@ -257,56 +291,197 @@ The - List categories - - —lists all categories on BBPS. -- - List billers - - —lists all billers on BBPS. -- - List disputes - - —lists all the raised disputes using the - Dispute API - . -- - List fetched Bills - - —lists all the fetched bills that were fetched using - Fetch API - . -- - List paid bills - - —lists all the bill pay transactions paid using - Pay API - . + + +
+ +### Managing Customer Registrations + +These APIs allow you to manage the lifecycle of UPMS (Unified Presentment Management Service) registrations for your customers. Refer to the [UPMS Integration Guide](upms.mdx) 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](/content/payments/billpay/api-integration/webhooks.mdx#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](/content/payments/billpay/api-integration/webhooks.mdx#cancel-upms-registration-webhook). + +**API Reference:** DELETE /api/v2/upms/registrations/{upmsRegistrationRefID} + + +
+ + + Sample Success Response + + + {` +{ + "success": true, + "traceId": "CV4PE82LTNJE9O014OE0" +} + `} +
+
diff --git a/content/payments/billpay/api-integration/objects.mdx b/content/payments/billpay/api-integration/objects.mdx index 12aee17a..08d9e747 100644 --- a/content/payments/billpay/api-integration/objects.mdx +++ b/content/payments/billpay/api-integration/objects.mdx @@ -49,14 +49,28 @@ Payment modes supported by a biller. ## Customer -Customer object holds the customer mobile number and the customer bill parameters. +Customer object holds the customer mobile number and the customer bill parameters. This object is used in the V1 API. -| parameter | type | description | -| ------------------------ | ---------------------------------- | -------------------------------------------------------------------------------------------------- | -| `mobile` | `string` (6, 10 and 20 digits) | Customer Mobile Number | -| `billParameters` | `{ name: string, value: string}[]` | Bill Parameters. The parameters to send is found in the biller details API. | -| `billParameters[].name` | `string` | Name of the bill parameter. name should match the parameter in biller details API. | -| `billParameters[].value` | `string` | Value of the bill parameter. Value is validate according to the regex found in the biller details. | +| parameter | type | description | +| -------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | +| `mobile` | `string` (6, 10 and 20 digits) | Customer Mobile Number | +| `billParameters` | `{ name: string, value: string}[]` | Bill Parameters used for standard bill fetch/payment. The parameters to send is found in the biller details API. | +| `billParameters[].name` | `string` | Name of the bill parameter. name should match the parameter in biller details API. | +| `billParameters[].value` | `string` | Value of the bill parameter. Value is validate according to the regex found in the biller details. | + +## CustomerV2 + +CustomerV2 object holds the customer mobile number and the customer bill parameters. This is a new object introduced in the V2 API. + +| parameter | type | description | +| -------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | +| `mobile` | `string` (6, 10 and 20 digits) | Customer Mobile Number | +| `customerParams` | `{ name: string, value: string}[]` | Customer Parameters used for standard bill fetch/payment. The parameters to send is found in the biller details API. | +| `customerParams[].name` | `string` | Name of the customer parameter. name should match the parameter in biller details API. | +| `customerParams[].value` | `string` | Value of the customer parameter. Value is validate according to the regex found in the biller details. | +| `name` | `string` (Optional) | Customer's name as registered with the biller. Only present in UPMS registration callbacks if provided by the biller's system. | + +Note: `customerParams` is a new field introduced in the V2 API in place of `billParameters`. ## Biller @@ -125,6 +139,16 @@ Details pertaining to the Agent which initiates the transaction. Values of the f | message | `string` | Error code description | | 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. | +## Error Object (Generic) + +A standard structure for representing errors in API responses or callbacks. + +| parameter | type | description | +| --------- | -------- | -------------------------------------------------------------------------------------------------------------- | +| `code` | `string` | A short code identifying the error category (e.g., `validation-error`, `biller-registration-failed`). | +| `message` | `string` | A human-readable description of the error. | + + ## Payment Details | parameter | type | description | @@ -185,6 +209,93 @@ The Payment Bill object contains information about a specific bill to be paid. | `ASPRESENTED` | | `NA` | +## UPMS Registration Type + +Indicates the type of UPMS registration. + +| type | description | +| -------------- | ------------------------------------------------------------------------------ | +| `VIEW_N_PAY` | Standard presentment. Bills are notified, user manually initiates payment. | +| `AUTO_PAY` | Auto-payment mandate. Bills are paid automatically using pre-configured info. | + +## UPMS Debit Type + +Specifies the debit rule for `AUTO_PAY` registrations. + +| type | description | +| -------------- | ------------------------------------------------------- | +| `FIXED_AMOUNT` | Pay the exact bill amount presented. | +| `MAX_AMOUNT` | Pay the bill amount, up to the specified maximum limit. | + +## UPMS Registration Status + +Represents the lifecycle state of a UPMS registration. + +| type | description | +| ------------- | -------------------------------------------------------------------------- | +| `PENDING` | Initial state after request, before confirmation. | +| `SUCCESS` | Registration active; bills will be presented via callbacks. | +| `FAILED` | Registration could not be completed (e.g., invalid details). | +| `CANCELLED` | Registration permanently cancelled by user or system. | +| `DEACTIVATED` | Registration is temporarily inactive (currently not used, future scope). | + +## UPMS Debit Info + +Contains details for automatic debit configuration, required only when `registrationType` is `AUTO_PAY`. + +| parameter | type | description | +| ------------- | ----------------------------------------------- | -------------------------------------------------------------------------------------- | +| `debitType` | [UPMS Debit Type](#upms-debit-type) (Mandatory) | The rule for auto-debit (`FIXED_AMOUNT` or `MAX_AMOUNT`). | +| `amount` | `integer` (Mandatory) | The fixed or maximum amount for auto-debit, in paise. | +| `currency` | `integer` (Mandatory) | Currency code (use `356` for INR). | +| `paymentMode` | [Payment Mode](#payment-mode) (Mandatory) | The payment method intended for auto-debit (e.g., `Internet Banking`, `UPI`). | +| `debitDate` | `string` (Optional) | Preferred date format (`DD-MMM`, e.g., `10-Feb`) for attempting auto-debit each cycle. | + +## UPMS Mandate + +Represents the customer's mandate details provided during UPMS registration creation or update. + +| parameter | type | description | +| ------------------ | ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | +| `registrationType` | [UPMS Registration Type](#upms-registration-type) (Mandatory) | `VIEW_N_PAY` or `AUTO_PAY`. | +| `billPeriod` | [Bill Period](#bill-period) (Conditional) | Frequency of expected bills (e.g., `MONTHLY`, `ASPRESENTED`). Mandatory for some billers. | +| `toDate` | `string` (YYYY-MM-DD) (Optional) | Expiry date of the registration. | +| `debitInfo` | [UPMS Debit Info](#upms-debit-info) (Optional) | Required only if `registrationType` is `AUTO_PAY`. Contains auto-debit parameters. | +| `billerParams` | `{ name: string, value: string}[]` (Optional) | Additional parameters specific to the biller for the mandate (e.g., "Low Balance Threshold"). Structure matches `billParameters`. | + +## UPMSRegistration + +Represents the complete details of a UPMS registration, typically received in webhook callbacks. + +| parameter | type | description | +| -------------- | ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | +| `refId` | `string` (Mandatory) | The unique reference ID for this specific UPMS registration instance. | +| `status` | [UPMS Registration Status](#upms-registration-status) (Mandatory) | The current status of the registration (e.g., `PENDING`, `SUCCESS`, `FAILED`, `CANCELLED`, `DEACTIVATED`). | +| `biller` | [Biller](#biller) (Mandatory) | Object containing the `id` of the associated biller. | +| `customer` | [CustomerV2](#customerv2) (Mandatory) | Object containing customer details (`customerParams`, `mobile`, optionally `name`) used for registration. | +| `mandate` | [UPMS Mandate](#upms-mandate) (Mandatory) | The mandate details associated with this registration. | +| `createdAt` | `string` (ISO 8601 datetime) (Mandatory) | Timestamp when the registration was created. | +| `updatedAt` | `string` (ISO 8601 datetime) (Mandatory) | Timestamp when the registration was last updated (status change, modification, cancellation). | + +## UPMS Duplicate Info + +Indicates that a UPMS registration attempt was a duplicate of an existing one. Received within the `data` object of a `CREATE_UPMS_REGISTRATION` callback. + +| parameter | type | description | +| --------- | -------- | ------------------------------------------------------------------------------ | +| `code` | `string` | Code indicating the duplicate situation (e.g., `duplicate-upms-registration`). | +| `message` | `string` | Description of the duplicate situation. | +| `refId` | `string` | The reference ID (`refId`) of the *existing* successful/pending registration. | + +## Skip Payment Data + +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. + +| parameter | type | description | +| --------------- | ---------------------------- | ----------------------------------------------------------------------------- | +| `billRefId` | `string` | The unique reference ID of the specific bill instance that was skipped/paid. | +| `dateOfPayment` | `string` (ISO 8601 datetime) | Timestamp indicating when the payment occurred on the external channel. | + ## Biller Selection Type | type | description | diff --git a/content/payments/billpay/api-integration/upms.mdx b/content/payments/billpay/api-integration/upms.mdx new file mode 100644 index 00000000..c983c1ed --- /dev/null +++ b/content/payments/billpay/api-integration/upms.mdx @@ -0,0 +1,1465 @@ +--- +sidebar_title: Integrating with UPMS +page_title: BBPS COU — Integrating with UPMS +order: 6 +visible_in_sidebar: true +--- + +# Part 1: Understanding UPMS + +This section introduces the core concepts of UPMS, its benefits, and the terminology you'll encounter while integrating. + +## 1. Introduction to UPMS + +### 1.1 What is UPMS? + +UPMS, or **Unified Presentment Management Service**, is a feature within the Bharat Bill Payment System (BBPS) designed to simplify how recurring bills are presented to customers. + +Think of it as a **subscription service for bills**. Instead of end-users manually fetching their bill details (like amount and due date) each cycle for various billers (electricity, phone, loan EMIs, etc.), UPMS allows them to register once through your app. + +Once a customer is registered for UPMS with a specific biller: + +1. The biller automatically pushes the bill details into the BBPS network when a new bill is generated. +2. BBPS makes this information available to us. +3. We then notify your app about the new bill via a webhook (callback). + +This enables a seamless, automated bill presentment experience right within your app. + +### 1.2 Why Integrate with UPMS? + +Integrating with UPMS offers significant advantages for both your app and your end-users: + +- **Improved End-User Experience**: Registered users see their bills automatically in your app, removing the need for them or you to fetch bills each cycle. This shifts bill management from a manual "pull" to an automated "push" model. +- **Timely Bill Awareness & Centralized View**: Proactive notifications about new bills and due dates help users avoid missed payments and late fees. Users can manage subscribed bills from different billers in one place—your app. +- **Increased Engagement**: Simplified bill discovery encourages users to pay digitally via your app, boosting engagement. + +### 1.3 How UPMS Works + +A simplified UPMS flow when using our APIs: + +1. **User Action**: An end-user on your app requests to register for automatic bill presentment for a specific biller (e.g., electricity provider). +2. **API Call (You → Us)**: Your app calls our **Fetch Bill and Create Registration** API with customer and mandate details. +3. **BBPS Interaction (Us → BBPS → Biller)**: We interact securely with BBPS central unit and the biller's system to validate and record the registration. +4. **Acknowledgement (Us → You)**: Our API returns a synchronous response (typically `PENDING`). +5. **Asynchronous Confirmation (Us → You)**: Final registration status (`SUCCESS` or `FAILED`) is communicated later via webhook. +6. **Bill Push (Biller → BBPS → Us)**: On a new bill cycle, the biller pushes bill details to BBPS. +7. **Bill Notification (Us → You)**: We send a callback to your configured endpoint with the bill details. +8. **Presentment (Your App)**: Your app parses the callback, identifies the user, and displays the bill. +9. **Payment (Optional)**: The user can then initiate payment for the presented bill. + +### 1.4 Who is this Guide For? + +This guide is intended for BBPS Agent Institutions integrating Setu's APIs to offer seamless recurring BBPS bill payment services, specifically leveraging UPMS features. It is valuable for individuals or teams seeking to understand the UPMS integration process. + +### 1.5 What this Guide Covers + +This document provides comprehensive information on: + +- Core UPMS concepts and terminology. +- Prerequisites and setup for integrating with Setu's UPMS APIs. +- Detailed explanations of each UPMS API endpoint. +- Handling webhook callbacks for managing registrations and bills. +- Error handling, testing procedures, and best practices. + +## 2. Key UPMS Concepts & Terminology + +### 2.1 UPMS Registration + +A UPMS registration represents an end-customer's mandate with a UPMS enabled biller for automatic bill presentment via your app. A successful registration authorizes the biller (with customer consent) to push bill details for that customer through BBPS to us, and subsequently, to you via callbacks. + + +UPMS is only available for billers who have the upmsEnabled flag set to true. You can check this flag using the List billers API, which also allows filtering by this flag. Trying to create a UPMS registration for billers without upmsEnabled set to true will fail. + + +### 2.2 Registration Lifecycle + +A UPMS registration progresses through various states: + +- **PENDING**: Initial state after a registration request is accepted but before the registration is confirmed. +- **SUCCESS**: Registration is active; bills will be presented via callbacks. +- **FAILED**: Registration could not be completed (e.g., invalid details). +- **CANCELLED**: Registration permanently cancelled by user or system. +- **DEACTIVATED**: Registration has been deactivated. + +### 2.3 Registration Types + +UPMS supports two primary registration types: + +- **VIEW_N_PAY**: Standard presentment; your app receives bill notifications, displays them, and the user manually initiates payment. +- **AUTO_PAY**: Auto-payment mandate already set up. When a bill is presented, your app initiates payment automatically using Setu's Payment APIs. + +### 2.4 Mandate (mandate) + +A JSON object provided when creating/updating a registration, containing: + +- `registrationType`: `VIEW_N_PAY` or `AUTO_PAY`. +- `billPeriod`: Frequency of expected bills (mandatory for some billers; optional for others). +- `toDate`: Expiry date of the registration. +- `debitInfo` (for `AUTO_PAY`): + - `debitType` (string): Specifies the debit rule. Can be `FIXED_AMOUNT` (pay the exact bill amount) or `MAX_AMOUNT` (pay up to this limit). + - `amount` (number): The fixed or maximum amount set for auto-debit (value must be provided in paise). + - `currency` (number): The currency code. Use `356` for `INR`. + - `paymentMode` (string): The payment method intended for auto-debit, like `Internet Banking` or `UPI`. + - `debitDate` (string): The preferred date format (`DD-MMM`, e.g., `10-Feb`) for attempting the auto-debit each cycle. + +### 2.5 Asynchronous Operations & Callbacks + +All UPMS operations (create, update, cancel) are asynchronous: + +- **Synchronous Response**: Immediate HTTP acknowledgment (`200 OK`) indicating `PENDING` status. +- **Asynchronous Outcome**: Final status sent via webhook callback to your server. + +Additionally, you'll receive a callback for each bill generated for the registered user. + +Ensure you implement a reliable webhook listener to receive and process these callbacks. + +# Part 2: Managing Customer Registrations + +## Prerequisite: Configure Your Registration Callback URL + +You must set up and provide us with a secure HTTPS webhook endpoint URL. This endpoint is crucial as it's where our system will send asynchronous notifications (via HTTP POST) regarding: + +- **UPMS Registration Status**: Updates for creation, modification, and cancellation (`CREATE_UPMS_REGISTRATION`, `UPDATE_UPMS_REGISTRATION`, `CANCEL_UPMS_REGISTRATION` events). + +## 3. UPMS Registration Management APIs + +### 3.1 Creating a Registration (Combined with Bill Fetch) + +This process leverages the existing **Bill Fetch API** endpoint. To initiate a UPMS registration alongside fetching the current bill (if available), you simply include the `mandate` object in the standard Bill Fetch request. + +**Endpoint:** `POST /api/v2/bbps/bills/fetch/request` (See API Reference) + +**Type:** Asynchronous + +**Purpose:** To fetch the current bill and, by adding `mandate`, simultaneously initiate customer registration for future automatic bill presentments (UPMS). + +**Request Structure:** +Note the added `mandate` block for UPMS registration. + + +
+ + + Sample Request + + + {` +{ + "agent": { /* ... agent details ... */ }, + "biller": { /* ... biller details ... */ }, + "customer": { /* ... customer identifiers ... */ }, ++ "mandate": { /* UPMS specific: details about the mandate as described in section 2.4 */ ++ "registrationType": "VIEW_N_PAY" | "AUTO_PAY", ++ "billPeriod": "MONTHLY" | "ASPRESENTED" | ..., ++ "toDate": "YYYY-MM-DD", ++ "debitInfo": { /* required for AUTO_PAY */ } ++ } +} + `} +
+ +
+ +**Synchronous Responses:** +- **200 OK** (Accepted): Both bill fetch and UPMS registration initiated. + + +
+ + + Sample Response + + + {` +{ + "success": true, + "data": { + // Your reference ID for tracking this specific bill fetch operation + "refId": "HENSVVR4QOS7X1UGPY7JGUV444P10102201", + "upmsRegistration": { + // Status of the registration request processing by our system + "status": "PENDING", + // The unique reference ID generated for this specific UPMS registration attempt. + // Use this ID to correlate with the registration callback. + "refId": "HENSVVR4QOS7X1UGPY7JGUV444P10102202" + } + }, + "traceId": "CV4PE82LTNJE9O014OE0" +} + `} +
+ +
+ +- **200 OK** (Invalid mandate): Bill fetch initiated, no UPMS registration. + + +
+ + + Sample Response + + + {` +{ + "success": true, + "data": { + "refId": "HENSVVR4QOS7X1UGPY7JGUV444P10102201", + // Status of the registration request processing by our system + "upmsRegistration": { + // No UPMS Registration will be initiated + "status": "FAILED", + // The error details + "error": { + "code": "invalid-debit-info", + "message": "Invalid amount in debit info" + } + } + }, + "traceId": "CV4PE82LTNJE9O014OE0" +} + `} +
+ +
+ +- **400 Bad Request** (Invalid Request): Neither bill fetch nor UPMS registration is initiated. + + +
+ + + Sample Response + + + {` +{ + "success": false, + "error": { + "code": "invalid-parameter", + "message": "Missing required field" + }, + "traceId": "CV4PE82LTNJE9O014OE1" +} + `} +
+ +
+ +- **500 Internal Server Error**: Neither bill fetch nor UPMS registration is initiated. + + +
+ + + Sample Response + + + {` +{ + "success": false, + "error": { + "code": "internal-error", + "message": "Internal Error" + }, + "traceId": "CV4PE82LTNJE9O014OE1" +} + `} +
+ +
+ +**Handling Asynchronous Callbacks for Creation:** + +Two independent callbacks can be triggered following this API call: + +- **Bill Fetch Callback (If Bill Found):** If a current bill exists for the customer, you will receive a `BILL_FETCH` callback containing the bill details. Handle this as described in Part 3. This callback is independent of the registration success/failure. + +- **Registration Status Callback:** For registrations with initial status as `PENDING`, you will receive a `CREATE_UPMS_REGISTRATION` callback to inform you of the final outcome of the registration attempt identified by `upmsRegistration.refId` from the synchronous response. + +**`CREATE_UPMS_REGISTRATION` Callback:** (See Webhook Reference) + +- **Event Type:** `event: "CREATE_UPMS_REGISTRATION"` +- **Timestamp:** `timeStamp` (ISO 8601 format) +- **Correlation:** `refId` (Matches the `upmsRegistration.refId` from the sync response, e.g., `HENSVVR4QOS7X1UGPY7JGUV444P10102202`) +- **Trace ID:** `traceId` (For logging/debugging) +- **Outcome:** Check the `data`, `duplicate`, and `error` fields within the callback payload: + + - **For successful registrations:** + - The `data` field will be present, and the `error` field will be absent. + - The `registration` object within `data` will contain the full details of the newly created registration. + + +
+ + + Sample Callback Payload + + + {` + // Example SUCCESS Callback Payload + { + "event": "CREATE_UPMS_REGISTRATION", + "traceId": "D07LJTJ71N0PUBJKS640", + "timeStamp": "2025-04-28T16:05:34.762+05:30", + "data": { + "registration": { + "refId": "D07LJTB71N0PGH5KG32G6dH2QjK51181605", // Unique reference ID for this registration + "status": "SUCCESS", // Final status of the registration + "biller": { // Same as the biller object in the request + "id": "ABLP01000ANP03" + }, + "customer": { // Same as the customer object in the request, except for the name field + "customerParams": [ + { + "name": "Roll No", + "value": "14989991" + } + ], + "mobile": "7378926241", + "name": "Anjali Desai" // NEW: Optional, only present if the biller shares the customer name + }, + "mandate": { // Same as the mandate object in the request + "billPeriod": "ASPRESENTED", + "billerParams": [ + { + "name": "Low Balance Threshold", + "value": "500" + } + ], + "debitInfo": { + "amount": 999999999, + "currency": 356, + "debitDate": "10-Feb", + "paymentMode": "Debit Card", + "type": "FIXED_AMOUNT" + }, + "registrationType": "AUTO_PAY", + "toDate": "2025-12-22" + }, + "createdAt": "2025-04-28T10:35:33Z", // Timestamp of the registration creation + "updatedAt": "2025-04-28T10:35:34Z" // Timestamp of the last registration modification + } + }, + "refId": "D07LJTB71N0PGH5KG32G6dH2QjK51181605" // Matches registration.refId + } + `} +
+ +
+ + - **For failed registration attempts:** + - The `error` object will be present, containing: + - `code` (string): The error code + - `message` (string): A description of the error + - The `data` object will be absent. + + +
+ + + Sample Callback Payload + + + {` + // Example FAILED Callback Payload + { + "event": "CREATE_UPMS_REGISTRATION", + "timeStamp": "2025-03-11T10:20:00.000+05:30", + "refId": "HENSVVR4QOS7X1UGPY7JGUV444P10102204", // Reference ID of the FAILED attempt from sync response + "error": { + "code": "biller-registration-failed", + "message": "Failed to register with Biller" + }, + "traceId": "D07LJTJ71N0PUBJKS640" // Trace ID for this callback + } + `} +
+ +
+ + - **For duplicate registrations:** + - The `data` field will be present, and the `error` field will be absent. + - The `duplicate` object within `data` indicates that a previous registration attempt was `SUCCESS`/`PENDING`. Details of the existing registration can be found here. + - `refId`: The reference ID of the existing successful/pending registration. + - `code`: Code indicating the duplicate situation (e.g., `duplicate-upms-registration`). + - `message`: Description of the duplicate situation. + + +
+ + + Sample Callback Payload + + + {` + // Example Duplicate Callback Payload + { + "event": "CREATE_UPMS_REGISTRATION", + "traceId": "CVVQVLN5STDFRUU0LLFG", + "timeStamp": "2025-04-16T18:55:42.758+05:30", + "data": { + "duplicate": { + "code": "duplicate-upms-registration", + "message": "Successful UPMS registration already exists", + "refId": "CVVQFN8BT5ONNAN3JCO059wmPQX51061821" // Ref ID of the EXISTING registration + } + }, + "refId": "CVVQVLGBT5ONNAN3JD90qXrHAWg51061855" // Ref ID of the DUPLICATE attempt from sync response + } + `} +
+ +
+ +**Action:** Update your internal registration record based on the callback status and response details (`registration`, `error`, or `duplicate`). + +### 3.2 Viewing Registration Details + +This synchronous endpoint allows you to retrieve the current status and details of a specific, existing UPMS registration immediately. + +**Endpoint:** `GET /api/v2/upms/registrations/{upmsRegistrationRefID}` (See API Reference) + +**Purpose:** To check the details and current status of a UPMS registration. + +**Endpoint Type:** Synchronous. The response contains the full, current details of the registration. + +**Request Breakdown:** + +- **Headers:** + - `X-PARTNER-ID: ` + - `Authorization: Bearer ` + - `Content-Type: application/json` +- **Path Parameter:** + - `upmsRegistrationRefID` (string): The unique reference ID of the UPMS registration you want to view (obtained from a successful `CREATE_UPMS_REGISTRATION` callback, e.g., `D07LJTB71N0PGH5KG32G6dH2QjK51181605`). + +**Response Breakdown:** + +- **On Success (Registration Found): HTTP 200 OK** + +
+ + + Sample 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", // Unique reference ID of the registration + "status": "SUCCESS", // Current status + "updatedAt": "2025-04-24T14:38:47.389Z" + }, + "success": true, + "traceId": "D055CNT3GMB863CND9LG" +} + `} +
+ +
+ +- **On Not Found: HTTP 404 Not Found** + +
+ + + Sample Response + + + {` +{ + "success": false, + "error": { + "code": "registration-not-found", + "message": "UPMS registration with the specified refId not found" + }, + "traceId": "CV4PE82LTNJE9O014OE2" +} + `} +
+ +
+ +- **On Bad Request: HTTP 400 Bad Request** (e.g., invalid format for `upmsRegistrationRefID`). + +
+ + + Sample Response + + + {` +{ + "success": false, + "traceId": "C3SFG0O6N88R6UI7EQ", + "error": { + "code": "invalid-ref-id", + "message": "Ref ID length must be 35 characters" + } +} + `} +
+ +
+ +- **On Server Error: HTTP 500 Internal Server Error** + +
+ + + Sample Response + + + {` +{ + "success": false, + "traceId": "C3SFG0O6N88R6UI7EQ", + "error": { + "code": "internal-error", + "message": "Internal Error" + } +} + `} +
+ +
+ +**Action:** Update your internal registration record based on the API response. + +### 3.3 Updating a Registration + +This asynchronous endpoint allows modification of certain fields of an active UPMS registration. + +**Endpoint:** `PATCH /api/v2/upms/registrations/{upmsRegistrationRefID}` (See API Reference) + +**Purpose:** To modify specific details of an existing, active UPMS registration. + +**Endpoint Type:** Asynchronous. The API call acknowledges the request, and the final result is delivered via callback. + +**Modifiable Mandate Details:** + +- `registrationType` +- `billPeriod` (restrictions may apply) +- `toDate` +- `debitInfo.debitType` +- `debitInfo.amount` +- `debitInfo.debitDate` (restrictions may apply) + +**Request Breakdown:** + +- **Headers:** + - `X-PARTNER-ID: ` + - `Authorization: Bearer ` + - `Content-Type: application/json` +- **Path Parameter:** + - `upmsRegistrationRefID` (string): The ID of the registration to update. +- **Body:** Include only the fields you want to modify within the `mandate` object. + + +
+ + + Example Request Body: Update Mandate + + + {` +// Example: Update expiry date and debit amount +{ + "mandate": { + "toDate": "2025-12-31", + "debitInfo": { + "amount": 750000 // 7500.00 INR + } + } +} + `} +
+ +
+ +**Synchronous Response (Acknowledgment):** + +Confirms receipt and basic validation of the update request. + +- **On Acceptance: HTTP 200 OK** + +
+ + + Sample Response + + + {` +{ + "success": true, + "traceId": "CV4PE82LTNJE9O014OE0" +} + `} +
+ +
+ +- **On Bad Request: HTTP 400 Bad Request** (Invalid field, invalid value, trying to update non-modifiable field). + +
+ + + Sample Response + + + {` +{ + "success": false, + "traceId": "C3SFG0O6N88R6UI7EQ", + "error": { + "code": "invalid-ref-id", // Example code, could vary + "message": "Ref ID length must be 35 characters" // Example message + } +} + `} +
+ +
+ +- **On Not Found: HTTP 404 Not Found** (Registration doesn't exist or is not in an updatable state). + +
+ + + Sample Response + + + {` +{ + "success": false, + "error": { + "code": "registration-not-found", + "message": "UPMS registration with the specified refId not found" + }, + "traceId": "CV4PE82LTNJE9O014OE2" +} + `} +
+ +
+ +- **On Server Error: HTTP 500 Internal Server Error** + +
+ + + Sample Response + + + {` +{ + "success": false, + "traceId": "C3SFG0O6N88R6UI7EQ", + "error": { + "code": "internal-error", + "message": "Internal Error" + } +} + `} +
+ +
+ +**Handling the Asynchronous Callback for Update:** + +You will receive an `UPDATE_UPMS_REGISTRATION` callback with the final outcome. + +**`UPDATE_UPMS_REGISTRATION` Callback:** (See Webhook Reference) + +- **Event Type:** `event: "UPDATE_UPMS_REGISTRATION"` +- **Timestamp:** `timeStamp` +- **Correlation:** `refId` (Matches the `upmsRegistrationRefID` from the PATCH request path). +- **Trace ID:** `traceId` +- **Outcome:** + + - **If the update was successful:** + - The `data` object will be present and the `error` object will be absent. + - The `registration` object in `data` will contain the complete, updated details of the registration. Use this to refresh your stored data. + + +
+ + + Sample Callback Payload + + + {` + { + "event": "UPDATE_UPMS_REGISTRATION", + "traceId": "D07MLCSRLASJ2P3SVAI0", + "timeStamp": "2025-04-28T17:16:59.941+05:30", + "data": { + "registration": { + "refId": "D07ML76AIQNN6974G200emsL9K451181716", + "status": "SUCCESS", + "biller": { + "id": "ABLP01000ANP03" + }, + "customer": { + "customerParams": [ + { + "name": "Roll No", + "value": "67d88976" + } + ], + "mobile": "9039403265", + "name": "Gautam Rajput" + }, + "mandate": { + "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" // Note: This was the updated value in the example + }, + "createdAt": "2025-04-28T11:46:36Z", + "updatedAt": "2025-04-28T11:46:59Z" // Reflects the update time + } + }, + "refId": "D07ML76AIQNN6974G200emsL9K451181716" + } + `} +
+ +
+ + - **If the update failed:** + - The `error` object will contain the `code` and `message` explaining the failure + - The `data` object will be absent. + + +
+ + + Sample Callback Payload + + + {` + { + "event": "UPDATE_UPMS_REGISTRATION", + "traceId": "D07N6PSRLASJ2P3SVAMG", + "timeStamp": "2025-04-28T17:54:07.062+05:30", + "refId": "D07N6M6AIQNN6974G9EGH18p7p051181753", // The refId of the attempted update + "error": { + "code": "biller-update-registration-failed", + "message": "Failed to update registration with Biller" + } + } + `} +
+ +
+ + +**Action:** Update your internal registration record based on the callback status and details. + +### 3.4 Cancelling a Registration + +This asynchronous endpoint permanently cancels an existing UPMS registration. + +**Endpoint:** `DELETE /api/v2/upms/registrations/{upmsRegistrationRefID}` (See API Reference) + +**Purpose:** + +- To permanently stop automatic bill presentments and any associated auto-debits for a specific UPMS registration. +- Once cancelled, the same registration cannot be reactivated. A new registration will need to be created if the user wishes to re-enable automatic presentment. + +**Endpoint Type:** Asynchronous. The API acknowledges the request, and confirmation comes via callback. + +**Request Breakdown:** + +- **Headers:** + - `X-PARTNER-ID: ` + - `Authorization: Bearer ` + - `Content-Type: application/json` +- **Path Parameter:** + - `upmsRegistrationRefID` (string): The ID of the registration to cancel. +- **Body:** None + +**Synchronous Response (Acknowledgment):** + +Confirms receipt of the cancellation request. + +- **On Acceptance: HTTP 200 OK** + +
+ + + Sample Response + + + {` +{ + "success": true, + "traceId": "CV4PE82LTNJE9O014OE0" +} + `} +
+ +
+ +- **On Bad Request: HTTP 400 Bad Request** (e.g., invalid `upmsRegistrationRefID` format). + +
+ + + Sample Response + + + {` +{ + "success": false, + "traceId": "C3SFG0O6N88R6UI7EQ", + "error": { + "code": "invalid-ref-id", + "message": "Ref ID length must be 35 characters" + } +} + `} +
+ +
+ +- **On Not Found: HTTP 404 Not Found** (Registration doesn't exist). + +
+ + + Sample Response + + + {` +{ + "success": false, + "error": { + "code": "registration-not-found", + "message": "UPMS registration with the specified refId not found" + }, + "traceId": "CV4PE82LTNJE9O014OE2" +} + `} +
+ +
+ +- **On Conflict: HTTP 409 Conflict** (e.g., registration is already cancelled or in a state that cannot be cancelled). + +
+ + + Sample Response + + + {` +{ + "success": false, + "error": { + "code": "invalid-state-transition", + "message": "Registration is already cancelled or in a state that cannot be cancelled" + }, + "traceId": "CV4PE82LTNJE9O014OE0" +} + `} +
+ +
+ +- **On Server Error: HTTP 500 Internal Server Error** + +
+ + + Sample Response + + + {` +{ + "success": false, + "traceId": "C3SFG0O6N88R6UI7EQ", + "error": { + "code": "internal-error", + "message": "Internal Error" + } +} + `} +
+ +
+ +**Handling the Asynchronous Callback for Cancellation:** + +You will receive a `CANCEL_UPMS_REGISTRATION` callback confirming the outcome. + +**`CANCEL_UPMS_REGISTRATION` Callback Details:** (See Webhook Reference) + +- **Event Type:** `event: "CANCEL_UPMS_REGISTRATION"` +- **Timestamp:** `timeStamp` +- **Correlation:** `refId` (Matches the `upmsRegistrationRefID` from the DELETE request path). +- **Trace ID:** `traceId` +- **Outcome:** + + - **If the cancellation was successful:** + - The `data` object will be present and the `error` object will be absent. + - The `registration` object in `data` will contain the details of the registration, now marked with `status: "CANCELLED"`. + + +
+ + + Sample Callback Payload + + + {` + { + "event": "CANCEL_UPMS_REGISTRATION", + "traceId": "D07MLCSRLASJ2P3SVAI0", // Example Trace ID + "timeStamp": "2025-04-28T17:16:59.941+05:30", // Example Timestamp + "data": { + "registration": { + "refId": "D07ML76AIQNN6974G200emsL9K451181716", + "status": "CANCELLED", + "biller": { /* ... biller details ... */ }, + "customer": { /* ... customer details ... */ }, + "mandate": { /* ... mandate details ... */ }, + "createdAt": "2025-04-28T11:46:36Z", + "updatedAt": "2025-04-28T11:46:59Z" // Time of cancellation + } + }, + "refId": "D07ML76AIQNN6974G200emsL9K451181716" + } + `} +
+ +
+ + - **If the cancellation failed:** + - The `error` object will contain the `code` and `message` explaining the failure + - The `data` object will be absent. + + +
+ + + Sample Callback Payload + + + {` + { + "event": "CANCEL_UPMS_REGISTRATION", + "traceId": "D07N6PSRLASJ2P3SVAMG", // Example Trace ID + "timeStamp": "2025-04-28T17:54:07.062+05:30", // Example Timestamp + "refId": "D07N6M6AIQNN6974G9EGH18p7p051181753", // The refId of the attempted cancellation + "error": { + "code": "registration-cancellation-failed", // Example Error Code + "message": "Failed to cancel registration with Biller" // Example Error Message + } + } + `} +
+ +
+ +**Action:** Update the status of the registration in your system to `CANCELLED` upon successful confirmation via the callback. + +# Part 3: Handling Bills and Payments + +Once a customer is successfully registered for UPMS (see Part 2), the core value proposition comes into play: receiving automatic bill presentments. This part guides you on how to handle these presented bills and integrate them into your payment flows. + +## Prerequisite: Configure Your Skip Payment Callback URL + +You must set up and provide us with a secure HTTPS webhook endpoint URL. This endpoint is crucial as it's where our system will send asynchronous notifications (via HTTP POST) regarding presented bills and skipped payments (`BILL_FETCH`, `SKIP_PAYMENT` events). + +## 4. Receiving Presented Bills + +The primary way you receive details about a newly generated bill for a registered customer is through the standard **Bill Notification callback** (`BILL_FETCH` event). This is the same event used for responses to manual bill fetches, but includes an identifier for UPMS. + +When a new bill is available for a registered customer, the flow is: + +1. **Bill Generation**: The biller generates a new bill for the customer. +2. **Push to BBPS**: The biller pushes the bill to the BBPS Central Unit. +3. **Notification to COU**: BBPS identifies the UPMS registration and notifies us. +4. **Callback to You**: We send a `BILL_FETCH` webhook with the bill details. (See Webhook Reference) +5. **Your Processing**: + - Acknowledge with HTTP `200 OK`. + - Parse the JSON payload. + - **Check for `upmsRegistrationRefId`**: Use this field to identify the UPMS registration associated with the bill. + - Extract the bill object(s) from `data.bills`. + - Store or update the bill in your system, associate with the user. + - Display bill details in your app. + +**Example `BILL_FETCH` Callback (for UPMS Presentment):** +Note the presence of `upmsRegistrationRefId` indicating this is for a registered subscription. + + +
+ + + Sample Callback Payload + + + {` +{ + "event": "BILL_FETCH", + "timeStamp": "2025-04-17T17:56:55.159+05:30", + "data": { + "additionalInfo": [ + { + "name": "Biller Unique Number", + "value": "Scaroasis" + } + ], + "billerResponseType": "SINGLE", + "billerSelectionType": null, + "bills": [ + { + "amount": 83400, + "billDate": "2025-04-17", + "billNumber": "BILL-226131", + "billPeriod": "MONTHLY", + "customerName": "Nitin Gupta", + "dueDate": "2025-05-02", + "paymentOptions": [ + { + "amount": 75060, + "name": "Early Payment Amount" + }, + { + "amount": 91740, + "name": "Late Payment Amount" + } + ] + } + ], + "exactness": "RANGE", + "refId": "D00F73QLFUHJFPQC2800HVDeelt51071756", // Ref ID for this specific bill fetch instance + "status": "Success", + "upmsRegistrationRefId": "D00EP9IJSBI05F06U9K0eBQWOq851071727" + } +} + `} +
+ +
+ +> **Note**: The same webhook endpoint receives notifications for both automatically presented bills (via UPMS) and bills retrieved through manual fetch requests (using separate Bill Fetch API). You can distinguish between these two scenarios by checking the `upmsRegistrationRefId` field within the callback's data object: +> - If `upmsRegistrationRefId` is present (not null), this callback represents an automatic bill presentment for a registered customer. +> - If `upmsRegistrationRefId` is absent or null, this callback is the result of a manual bill fetch request. + +## 5. Initiating Payment for Presented Bills + +When a user opts to pay a presented bill: + +1. **Invoke Payment API**: Construct and send a request to our BBPS Payment API endpoint. (See API Reference) +2. **Follow Payment Flow**: Handle the response and subsequent steps (e.g., status checks, notifications) as defined in the Payment API documentation. + +## 6. Handling Skipped Payments + +Sometimes, a user might pay a bill through a different channel (e.g., directly on the biller's website, via another app) after it has been presented to them in your application via UPMS. To avoid showing already-paid bills as pending, Setu provides a mechanism to notify you about such payments. + +### 6.1 SKIP_PAYMENT Callback Flow + +If a bill is paid elsewhere after presentation, you'll receive a `SKIP_PAYMENT` callback: (See Webhook Reference) + +1. **Payment Elsewhere**: User pays via another BBPS channel. +2. **Notification to Us**: BBPS detects external payment and informs us. +3. **Callback to You**: We send a `SKIP_PAYMENT` webhook to your configured endpoint. +4. **Your Processing**: + - Acknowledge with HTTP `200 OK`. + - Parse `data.billRefId` and `data.dateOfPayment`. (Note: `data.billRefId` of skip payment callback is the same as `data.refId` of the bill fetch callback, i.e. the reference id of the presented bill(s)) + - Locate and mark the bill as paid in your system. + +**Example `SKIP_PAYMENT` Callback:** + + +
+ + + Sample Callback Payload + + + {` +{ + "event": "SKIP_PAYMENT", + "traceId": "D0508DIBJFBLCSGI36RG", + "timeStamp": "2025-04-25T18:16:46.716+05:30", + "data": { + "billRefId": "D050862BJFBLCSGI36N0e3qv9Zu51151816", + "dateOfPayment": "2025-04-25T18:16:44+05:30" + } +} + `} +
+ +
+ +### 6.2 Why Handle SKIP_PAYMENT Callbacks? + +Handling SKIP_PAYMENT callbacks ensures data consistency and improves user experience: + + - **Accurate Bill Status**: Prevents users from seeing bills they've already paid elsewhere as still outstanding in your app. + - **Avoids Double Payments**: Reduces the risk of users accidentally attempting to pay the same bill twice. + - **Clean User Interface**: Keeps the list of pending bills relevant and actionable. + +# Part 4: Testing and Simulation + +This part covers the specialized APIs designed to help you test your integration, particularly your handling of asynchronous callbacks, in non-production environments. + +## 7. Introduction to Simulation APIs + +Integrating asynchronous flows, especially those involving callbacks (webhooks), requires thorough testing. Waiting for real bill generation cycles or actual skipped payments can be slow and unpredictable during development and testing phases. + +To facilitate this, we provide Simulation APIs that allow you to manually trigger specific callback events on demand. + +**Key Purposes:** + +- **Verify Callback Handling:** Ensure your webhook listener correctly receives, parses, and processes `BILL_FETCH` and `SKIP_PAYMENT` callbacks. +- **Test Business Logic:** Test the downstream logic in your application that gets triggered by these callbacks (e.g., displaying bills, marking bills as paid). +- **Accelerate Development:** Trigger events instantly without external dependencies in lower environments. + +**❗ Limitation:** + +- **These Simulation APIs are strictly for use in lower environments only**. They will not function in the Production environment. Attempting to use them in Production will result in an error. + +**Simulatable Events:** + +- `BILL_FETCH` (via Simulate Bill Notification Callback API) +- `SKIP_PAYMENT` (via Simulate Skip Payment Callback API) + +## 8. Simulating a Bill Notification Callback + +This asynchronous API allows you to manually trigger a `BILL_FETCH` callback for a specific, active UPMS registration. + +**Endpoint:** `POST /api/v2/upms/simulate/{upmsRegistrationRefID}/callbacks/bill` (See API Reference) + +**Purpose:** To trigger the delivery of a simulated `BILL_FETCH` callback to your configured webhook endpoint for the specified `upmsRegistrationRefID`. This helps test how your system handles incoming bill presentments. + +**Endpoint Type:** Asynchronous. The API call acknowledges the request to simulate, and the actual `BILL_FETCH` callback is delivered shortly after to your webhook listener. + +**Request Structure:** + +- **Headers:** + - `X-PARTNER-ID: ` + - `Authorization: Bearer ` + - `Content-Type: application/json` +- **Path Parameter:** + - `upmsRegistrationRefID` (string): The unique reference ID of the active UPMS registration for which you want to simulate a bill notification. This registration must exist and be in a state like `SUCCESS`. +- **Body:** None + +**Synchronous Response (Acknowledgment):** + +Confirms that the request to simulate the callback has been accepted. + +- **On Acceptance: HTTP 200 OK** + +
+ + + Sample Response + + + {` +{ + "success": true, + "traceId": "CV4PE82LTNJE9O014OE0" +} + `} +
+ +
+ +- **On Bad Request: HTTP 400 Bad Request** (e.g., Invalid `upmsRegistrationRefID` format). + +
+ + + Sample Response + + + {` +{ + "success": false, + "error": { + "code": "invalid-registration-ref-id", + "message": "Invalid format for upmsRegistrationRefID" + }, + "traceId": "CV4PE82LTNJE9O014OE1" +} + `} +
+ +
+ +- **On Forbidden: HTTP 403 Forbidden** - If attempted in the Production environment. + +
+ + + Sample Response + + + {` +{ + "success": false, + "error": { + "code": "forbidden-operation", + "message": "Simulation API not allowed in this environment" + }, + "traceId": "CV4PE82LTNJE9O014OE2" +} + `} +
+ +
+ +- **On Not Found: HTTP 404 Not Found** - If the specified `upmsRegistrationRefID` does not exist or is not active. + +
+ + + Sample Response + + + {` +{ + "success": false, + "error": { + "code": "registration-not-found", + "message": "UPMS registration with the specified refId not found or inactive" + }, + "traceId": "CV4PE82LTNJE9O014OE3" +} + `} +
+ +
+ +- **On Server Error: HTTP 500 Internal Server Error**. + +
+ + + Sample Response + + + {` +{ + "success": false, + "error": { + "code": "internal-error", + "message": "Internal Error" + }, + "traceId": "CV4PE82LTNJE9O014OE2" +} + `} +
+ +
+ +**Handling the Asynchronous Callback Outcome:** + +Shortly after receiving the 200 OK acknowledgment, your configured webhook listener endpoint should receive an HTTP POST request containing the `BILL_FETCH` callback (which shares the same `BILL_FETCH` event structure). + +- **Callback Payload:** The payload structure will follow the schema described for `BILL_FETCH` events (see Part 3, Section 4), including the `upmsRegistrationRefId` you specified in the simulation request. + +**Action:** Use this API in your test environment to verify that your webhook endpoint correctly receives, parses, and processes incoming bill notifications. Ensure you can link the received bill to the correct user based on the `upmsRegistrationRefId`. + +## 9. Simulating a Skip Payment Callback + +This asynchronous API allows you to manually trigger a `SKIP_PAYMENT` callback for a specific bill reference ID. + +**Endpoint:** `POST /api/v2/upms/simulate/{billRefId}/callbacks/skip-payment` (See API Reference) + +**Purpose:** To trigger the delivery of a simulated `SKIP_PAYMENT` callback to your configured webhook endpoint for the specified `billRefId`. This helps test how your system handles notifications that a bill, previously presented, was paid via another channel. + +**Endpoint Type:** Asynchronous. The API call acknowledges the request, and the actual `SKIP_PAYMENT` callback is delivered shortly after to your webhook listener. + +**Request Structure:** + +- **Headers:** + - `X-PARTNER-ID: ` + - `Authorization: Bearer ` + - `Content-Type: application/json` +- **Path Parameter:** + - `billRefId` (string): The unique reference ID of the specific bill instance for which you want to simulate a skip payment notification. This `billRefId` would typically have been received previously in a `BILL_FETCH` callback (either real or simulated). +- **Body:** None + +**Synchronous Response (Acknowledgment):** + +Confirms that the request to simulate the skip payment callback has been accepted. + +- **On Acceptance: HTTP 200 OK** + +
+ + + Sample Response + + + {` +{ + "success": true, + "traceId": "CV4PE82LTNJE9O014OE0" +} + `} +
+ +
+ +- **On Bad Request: HTTP 400 Bad Request** - e.g., Invalid `billRefId` format, or if the bill state is incompatible (e.g., already marked paid). May include specific codes like `invalid-bill`. + +
+ + + Sample Response + + + {` +{ + "success": false, + "error": { + "code": "invalid-bill", + "message": "Bill reference ID not found or inactive" + }, + "traceId": "SIM4PE82LTNJE9O014OE0" +} + `} +
+ +
+ +- **On Forbidden: HTTP 403 Forbidden** - If attempted in the Production environment. + +
+ + + Sample Response + + + {` +{ + "success": false, + "error": { + "code": "forbidden-operation", + "message": "Simulation API not allowed in this environment" + }, + "traceId": "CV4PE82LTNJE9O014OE2" +} + `} +
+ +
+ +- **On Not Found: HTTP 404 Not Found** - If the specified `billRefId` does not exist. + +
+ + + Sample Response + + + {` +{ + "success": false, + "error": { + "code": "bill-not-found", + "message": "Bill with the specified refId not found" + }, + "traceId": "CV4PE82LTNJE9O014OE4" +} + `} +
+ +
+ +- **On Server Error: HTTP 500 Internal Server Error**. + +
+ + + Sample Response + + + {` +{ + "success": false, + "error": { + "code": "internal-error", + "message": "Internal Error" + }, + "traceId": "CV4PE82LTNJE9O014OE2" +} + `} +
+ +
+ +**Handling the Asynchronous Callback Outcome:** + +Shortly after receiving the 200 OK acknowledgment, your configured webhook listener endpoint should receive an HTTP POST request containing the `SKIP_PAYMENT` callback. + +- **Callback Payload:** The payload structure will follow the schema described for `SKIP_PAYMENT` events (see Part 3, Section 6.1). It will include `event: "SKIP_PAYMENT"`, `timeStamp`, `traceId`, and a `data` object containing the `billRefId` you specified and a `dateOfPayment`. + +**Action:** Use this API in your test environment to verify that your webhook endpoint correctly receives `SKIP_PAYMENT` events and that your application logic correctly identifies the bill using `billRefId` and updates its status appropriately (e.g., marks it as paid, removes it from pending lists). + +## 10. General Testing Recommendations + +- **Webhook Listener:** Ensure you have a stable and publicly accessible webhook listener endpoint configured in our system for your Sandbox/UAT environment before using the simulation APIs. +- **Test Scenarios:** Use the simulation APIs to test various scenarios: + - Successful reception and processing of `BILL_FETCH`. + - Successful reception and processing of `SKIP_PAYMENT`. + - Handling potential errors if simulation is called with non-existent `upmsRegistrationRefId` or `billRefId`. +- **Correlation:** Pay attention to correlating the simulation API call with the resulting callback using `traceId` and the relevant reference IDs (`upmsRegistrationRefId`, `billRefId`). +- **Idempotency:** While simulating, ensure your webhook handler deals with potentially receiving the same callback event more than once. + +This concludes the guide on integrating with Setu's UPMS APIs. + + + + diff --git a/content/payments/billpay/api-integration/webhooks.mdx b/content/payments/billpay/api-integration/webhooks.mdx index 24c86af2..81629c70 100644 --- a/content/payments/billpay/api-integration/webhooks.mdx +++ b/content/payments/billpay/api-integration/webhooks.mdx @@ -9,22 +9,25 @@ visible_in_sidebar: true Here is the general structure of any webhook— -{` +{`{ "traceId" : "C3SFG0O6N88R6UI7EQ", "timeStamp" : "2021-11-12T00:12:29+05:30", "event" : "BILLER_UPDATES", - "data" : {...}`} + "data" : { /* Present on success */ }, + "error" : { /* Present on failure */ } +}`} 1. `traceId` is a unique ID assigned to the error and used by Setu to debug 2. `timeStamp` denotes the time when the webhook was triggered 3. `event` is a pre-defined list of event types used to define what the webhook was triggered for -4. `data` contains the webhook payload data +4. `data` contains the webhook payload data on successful completion of the event. +5. `error` contains details about the failure if the event could not be completed successfully. It typically includes `code` and `message` fields. One of `data` or `error` will be present.
### Bill fetch webhook -This webhook can be used to get details of outstanding bills on BBPS. It will only be triggered if the Fetch bill API is +This webhook can be used to get details of outstanding bills on BBPS. It will only be triggered if the Fetch bill API is consumed. If the bill does not exist then suitable error message will be sent. @@ -54,7 +57,62 @@ URL : To be provided by partner`} "billerRefId": "9540207519", "exactness": "Exact", "refId": "CJLJBQK91PA0FD9MPMK0W75BD9M32391709", - "status": "Success" + "status": "Success", + "upmsRegistrationRefId": "CJLJBQK91PA0FD9MPMK0W75BD9M32391709" + } +} +`} + +
+ + +> **Note**: When a bill is presented automatically for a registered customer, this callback will include an additional field `upmsRegistrationRefId` within the `data` object, linking the bill to the specific registration. +If this field is absent or null, the callback corresponds to a manual bill fetch request. See example below. + + +
+ + + Bill presentment sample request + + + + {`{ + "event": "BILL_FETCH", + "timeStamp": "2025-04-17T17:56:55.159+05:30", + "data": { + "additionalInfo": [ + { + "name": "Biller Unique Number", + "value": "Scaroasis" + } + ], + "billerResponseType": "SINGLE", + "billerSelectionType": null, + "bills": [ + { + "amount": 83400, + "billDate": "2025-04-17", + "billNumber": "BILL-226131", + "billPeriod": "MONTHLY", + "customerName": "Nitin Gupta", + "dueDate": "2025-05-02", + "paymentOptions": [ + { + "amount": 75060, + "name": "Early Payment Amount" + }, + { + "amount": 91740, + "name": "Late Payment Amount" + } + ] + } + ], + "exactness": "RANGE", + "refId": "D00F73QLFUHJFPQC2800HVDeelt51071756", // Ref ID for this specific generated bill. Use this to initiate a payment. + "status": "Success", + "upmsRegistrationRefId": "D00EP9IJSBI05F06U9K0eBQWOq851071727" // Links to the UPMS registration } } `} @@ -336,4 +394,301 @@ URL : To be provided by partner`}
+ +### Create UPMS Registration webhook + +This webhook informs you about the final status (Success, Failed, or Duplicate) of a UPMS registration request initiated via the [Fetch Bill and Create Registration API](/content/payments/billpay/api-integration/upms.mdx#31-creating-a-registration-combined-with-bill-fetch). The `refId` in the webhook payload matches the `upmsRegistration.refId` from the synchronous API response. + +{`Method : POST +URL : To be provided by partner (Registration Callback URL)`} + + +
+ + + Create UPMS Registration sample request (Success) + + + + {`{ + "event": "CREATE_UPMS_REGISTRATION", + "traceId": "D07LJTJ71N0PUBJKS640", + "timeStamp": "2025-04-28T16:05:34.762+05:30", + "data": { + "registration": { + "refId": "D07LJTB71N0PGH5KG32G6dH2QjK51181605", // Unique reference ID for this registration + "status": "SUCCESS", // Final status of the registration + "biller": { // Same as the biller object in the request + "id": "ABLP01000ANP03" + }, + "customer": { // Same as the customer object in the request, except for the name field + "customerParams": [ + { + "name": "Roll No", + "value": "14989991" + } + ], + "mobile": "7378926241", + "name": "Anjali Desai" // NEW: Optional, only present if the biller shares the customer name + }, + "mandate": { // Same as the mandate object in the request + "billPeriod": "ASPRESENTED", + "billerParams": [ + { + "name": "Low Balance Threshold", + "value": "500" + } + ], + "debitInfo": { + "amount": 999999999, + "currency": 356, + "debitDate": "10-Feb", + "paymentMode": "Debit Card", + "type": "FIXED_AMOUNT" + }, + "registrationType": "AUTO_PAY", + "toDate": "2025-12-22" + }, + "createdAt": "2025-04-28T10:35:33Z", // Timestamp of the registration creation + "updatedAt": "2025-04-28T10:35:34Z" // Timestamp of the last registration modification + } + }, + "refId": "D07LJTB71N0PGH5KG32G6dH2QjK51181605" // Matches registration.refId +}`} + +
+ + +
+ + +
+ + + Create UPMS Registration sample request (Failed) + + + + {`{ + "event": "CREATE_UPMS_REGISTRATION", + "timeStamp": "2025-03-11T10:20:00.000+05:30", + "refId": "HENSVVR4QOS7X1UGPY7JGUV444P10102204", // Reference ID of the FAILED attempt from sync response + "error": { + "code": "biller-registration-failed", + "message": "Failed to register with Biller" + }, + "traceId": "D07LJTJ71N0PUBJKS640" // Trace ID for this callback +}`} + +
+ + +
+ + +
+ + + Create UPMS Registration sample request (Duplicate) + + + + {`{ + "event": "CREATE_UPMS_REGISTRATION", + "traceId": "CVVQVLN5STDFRUU0LLFG", + "timeStamp": "2025-04-16T18:55:42.758+05:30", + "data": { + "duplicate": { + "code": "duplicate-upms-registration", + "message": "Successful UPMS registration already exists", + "refId": "CVVQFN8BT5ONNAN3JCO059wmPQX51061821" // Ref ID of the EXISTING registration + } + }, + "refId": "CVVQVLGBT5ONNAN3JD90qXrHAWg51061855" // Ref ID of the DUPLICATE attempt from sync response +}`} + +
+ + +
+ +### Update UPMS Registration webhook + +This webhook confirms the outcome (Success or Failed) of a request to update an existing customer registration using the [Update Registration API](/content/payments/billpay/api-integration/upms.mdx#33-updating-a-registration). The `refId` in the webhook payload matches the `upmsRegistrationRefID` used in the API request path. + +{`Method : POST +URL : To be provided by partner (Registration Callback URL)`} + + +
+ + + Update UPMS Registration sample request (Success) + + + + {`{ + "event": "UPDATE_UPMS_REGISTRATION", + "traceId": "D07MLCSRLASJ2P3SVAI0", + "timeStamp": "2025-04-28T17:16:59.941+05:30", + "data": { + "registration": { // Contains the full, updated registration details + "refId": "D07ML76AIQNN6974G200emsL9K451181716", + "status": "SUCCESS", + "biller": { + "id": "ABLP01000ANP03" + }, + "customer": { + "customerParams": [ + { + "name": "Roll No", + "value": "67d88976" + } + ], + "mobile": "9039403265", + "name": "Gautam Rajput" + }, + "mandate": { + "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" + }, + "createdAt": "2025-04-28T11:46:36Z", + "updatedAt": "2025-04-28T11:46:59Z" // Reflects the update time + } + }, + "refId": "D07ML76AIQNN6974G200emsL9K451181716" // Matches the updated registration's refId +}`} + +
+ + +
+ + +
+ + + Update UPMS Registration sample request (Failed) + + + + {`{ + "event": "UPDATE_UPMS_REGISTRATION", + "traceId": "D07N6PSRLASJ2P3SVAMG", + "timeStamp": "2025-04-28T17:54:07.062+05:30", + "refId": "D07N6M6AIQNN6974G9EGH18p7p051181753", // The refId of the attempted update + "error": { + "code": "biller-update-registration-failed", + "message": "Failed to update registration with Biller" + } +}`} + +
+ + +
+ +### Cancel UPMS Registration webhook + +This webhook confirms the outcome (Success or Failed) of a request to cancel an existing UPMS registration using the [Cancel Registration API](/content/payments/billpay/api-integration/upms.mdx#34-cancelling-a-registration). The `refId` in the webhook payload matches the `upmsRegistrationRefID` used in the API request path. + +{`Method : POST +URL : To be provided by partner (Registration Callback URL)`} + + +
+ + + Cancel UPMS Registration sample request (Success) + + + + {`{ + "event": "CANCEL_UPMS_REGISTRATION", + "traceId": "D07MLCSRLASJ2P3SVAI0", // Example Trace ID + "timeStamp": "2025-04-28T17:16:59.941+05:30", // Example Timestamp + "data": { + "registration": { // Contains details of the cancelled registration + "refId": "D07ML76AIQNN6974G200emsL9K451181716", + "status": "CANCELLED", + "biller": { /* ... biller details ... */ }, + "customer": { /* ... customer details ... */ }, + "mandate": { /* ... mandate details ... */ }, + "createdAt": "2025-04-28T11:46:36Z", + "updatedAt": "2025-04-28T11:46:59Z" // Time of cancellation + } + }, + "refId": "D07ML76AIQNN6974G200emsL9K451181716" // Matches the cancelled registration's refId +}`} + +
+ + +
+ + +
+ + + Cancel UPMS Registration sample request (Failed) + + + + {`{ + "event": "CANCEL_UPMS_REGISTRATION", + "traceId": "D07N6PSRLASJ2P3SVAMG", // Example Trace ID + "timeStamp": "2025-04-28T17:54:07.062+05:30", // Example Timestamp + "refId": "D07N6M6AIQNN6974G9EGH18p7p051181753", // The refId of the attempted cancellation + "error": { + "code": "registration-cancellation-failed", + "message": "Failed to cancel registration with Biller" + } +}`} + +
+ + +
+ +### Skip Payment webhook + +This webhook notifies you when a bill, previously presented via UPMS, has been paid through an external channel (e.g., directly on the biller's site, another app). Use this to update the bill's status in your system. + +{`Method : POST +URL : To be provided by partner (Skip Payment Callback URL)`} + + +
+ + + Skip Payment sample request + + + + {`{ + "event": "SKIP_PAYMENT", + "traceId": "D0508DIBJFBLCSGI36RG", + "timeStamp": "2025-04-25T18:16:46.716+05:30", + "data": { + "billRefId": "D050862BJFBLCSGI36N0e3qv9Zu51151816", // The refId of the bill that was paid externally + "dateOfPayment": "2025-04-25T18:16:44+05:30" // Timestamp of the external payment + } +}`} + +
+ +