From 5163c07d74d23067c62b17c16dbd39bb2e8a055f Mon Sep 17 00:00:00 2001 From: Anindya Pandey Date: Mon, 20 Jul 2026 18:31:00 +0530 Subject: [PATCH] docs(UPIIS-57): register UPI Issuance in the API playground Add the two feeder inputs the playground consumes from this repo, so /payments/upi-issuance resolves there instead of 404ing behind the "Test in API playground" button the docs already render. - products.json: add UPI Issuance under Payments. - json/payments/upi-issuance/: 14 mock payloads, one per operation, named after the operationId per this folder's README. Bodies are the spec's existing examples. Each carries sim.plaintext in idempotencyKey, which exchanges the call outside the crypto envelope; an envelope body cannot be authored statically. requestBindingToken and verifyOTP add a scenario directive (sim.bind-ok, sim.otp-ok) for the outcomes that depend on an async event the playground cannot fire. Directives are honoured on sandbox deployments only. No credentials are committed: the sandbox plaintext path needs none. - upi-issuance.json: operationIds drop the "onboarding#" prefix. '#' is the URL fragment delimiter, so a payload file named after the old form truncates at the '#' and 404s when fetched. Also align three vpa request-body descriptions with the prose pages, which already say the prefix must start with the user's alias rather than their mobile number. set-alias stays undocumented, so it has no entry here. Closes UPIIS-57 --- .../payments/upi-issuance/blockPayeeVPA.json | 14 ++++++++ .../json/payments/upi-issuance/checkVPA.json | 15 ++++++++ .../payments/upi-issuance/createProgram.json | 16 +++++++++ .../json/payments/upi-issuance/createVPA.json | 22 ++++++++++++ .../payments/upi-issuance/deregisterVPA.json | 14 ++++++++ .../json/payments/upi-issuance/getVPA.json | 14 ++++++++ .../upi-issuance/listBlockedPayeeVPAs.json | 15 ++++++++ .../json/payments/upi-issuance/listVPAs.json | 15 ++++++++ .../upi-issuance/pollBindingStatus.json | 13 +++++++ .../upi-issuance/requestBindingToken.json | 15 ++++++++ .../payments/upi-issuance/requestOTP.json | 14 ++++++++ .../upi-issuance/unblockPayeeVPA.json | 14 ++++++++ .../payments/upi-issuance/updateProgram.json | 22 ++++++++++++ .../json/payments/upi-issuance/verifyOTP.json | 15 ++++++++ api-playground/products.json | 4 +++ api-references/payments/upi-issuance.json | 34 +++++++++---------- 16 files changed, 239 insertions(+), 17 deletions(-) create mode 100644 api-playground/json/payments/upi-issuance/blockPayeeVPA.json create mode 100644 api-playground/json/payments/upi-issuance/checkVPA.json create mode 100644 api-playground/json/payments/upi-issuance/createProgram.json create mode 100644 api-playground/json/payments/upi-issuance/createVPA.json create mode 100644 api-playground/json/payments/upi-issuance/deregisterVPA.json create mode 100644 api-playground/json/payments/upi-issuance/getVPA.json create mode 100644 api-playground/json/payments/upi-issuance/listBlockedPayeeVPAs.json create mode 100644 api-playground/json/payments/upi-issuance/listVPAs.json create mode 100644 api-playground/json/payments/upi-issuance/pollBindingStatus.json create mode 100644 api-playground/json/payments/upi-issuance/requestBindingToken.json create mode 100644 api-playground/json/payments/upi-issuance/requestOTP.json create mode 100644 api-playground/json/payments/upi-issuance/unblockPayeeVPA.json create mode 100644 api-playground/json/payments/upi-issuance/updateProgram.json create mode 100644 api-playground/json/payments/upi-issuance/verifyOTP.json diff --git a/api-playground/json/payments/upi-issuance/blockPayeeVPA.json b/api-playground/json/payments/upi-issuance/blockPayeeVPA.json new file mode 100644 index 00000000..107f3c45 --- /dev/null +++ b/api-playground/json/payments/upi-issuance/blockPayeeVPA.json @@ -0,0 +1,14 @@ +{ + "parameters": { + "header": [ + { + "idempotencyKey": "sim.plaintext" + } + ] + }, + "body": { + "deviceId": "device-abc-123", + "mobile": "919999999999", + "payeeVpa": "merchant@otherbank" + } +} diff --git a/api-playground/json/payments/upi-issuance/checkVPA.json b/api-playground/json/payments/upi-issuance/checkVPA.json new file mode 100644 index 00000000..250b8122 --- /dev/null +++ b/api-playground/json/payments/upi-issuance/checkVPA.json @@ -0,0 +1,15 @@ +{ + "parameters": { + "header": [ + { + "idempotencyKey": "sim.plaintext" + } + ] + }, + "body": { + "deviceId": "device-abc-123", + "mobile": "919999999999", + "programId": "01ARZ3NDEKTSV4RRFFQ69G5FAV", + "vpa": "919999999999-acme@setu" + } +} diff --git a/api-playground/json/payments/upi-issuance/createProgram.json b/api-playground/json/payments/upi-issuance/createProgram.json new file mode 100644 index 00000000..19b5bb0b --- /dev/null +++ b/api-playground/json/payments/upi-issuance/createProgram.json @@ -0,0 +1,16 @@ +{ + "parameters": { + "header": [ + { + "idempotencyKey": "sim.plaintext" + } + ] + }, + "body": { + "amountLimit": 500000, + "code": "ACME", + "isCreditAllowed": true, + "isDebitAllowed": true, + "name": "Acme Wallet" + } +} diff --git a/api-playground/json/payments/upi-issuance/createVPA.json b/api-playground/json/payments/upi-issuance/createVPA.json new file mode 100644 index 00000000..5ae00f12 --- /dev/null +++ b/api-playground/json/payments/upi-issuance/createVPA.json @@ -0,0 +1,22 @@ +{ + "parameters": { + "header": [ + { + "idempotencyKey": "sim.plaintext" + } + ] + }, + "body": { + "accountName": "Alice Doe", + "accountNo": "99887766554433", + "accountProviderId": "01ARZ3NDEKTSV4RRFFQ69G5FAV", + "defaultCredit": true, + "defaultDebit": true, + "deviceId": "device-abc-123", + "ifsc": "SETU0000001", + "mobile": "919999999999", + "otpRequired": false, + "programId": "01ARZ3NDEKTSV4RRFFQ69G5FAV", + "vpa": "919999999999-acme@setu" + } +} diff --git a/api-playground/json/payments/upi-issuance/deregisterVPA.json b/api-playground/json/payments/upi-issuance/deregisterVPA.json new file mode 100644 index 00000000..17b0f0b0 --- /dev/null +++ b/api-playground/json/payments/upi-issuance/deregisterVPA.json @@ -0,0 +1,14 @@ +{ + "parameters": { + "header": [ + { + "idempotencyKey": "sim.plaintext" + } + ] + }, + "body": { + "deviceId": "device-abc-123", + "mobile": "919999999999", + "vpa": "919999999999-acme@setu" + } +} diff --git a/api-playground/json/payments/upi-issuance/getVPA.json b/api-playground/json/payments/upi-issuance/getVPA.json new file mode 100644 index 00000000..17b0f0b0 --- /dev/null +++ b/api-playground/json/payments/upi-issuance/getVPA.json @@ -0,0 +1,14 @@ +{ + "parameters": { + "header": [ + { + "idempotencyKey": "sim.plaintext" + } + ] + }, + "body": { + "deviceId": "device-abc-123", + "mobile": "919999999999", + "vpa": "919999999999-acme@setu" + } +} diff --git a/api-playground/json/payments/upi-issuance/listBlockedPayeeVPAs.json b/api-playground/json/payments/upi-issuance/listBlockedPayeeVPAs.json new file mode 100644 index 00000000..4f660332 --- /dev/null +++ b/api-playground/json/payments/upi-issuance/listBlockedPayeeVPAs.json @@ -0,0 +1,15 @@ +{ + "parameters": { + "header": [ + { + "idempotencyKey": "sim.plaintext" + } + ] + }, + "body": { + "cursor": "01ARZ3NDEKTSV4RRFFQ69G5FAV", + "deviceId": "device-abc-123", + "limit": 20, + "mobile": "919999999999" + } +} diff --git a/api-playground/json/payments/upi-issuance/listVPAs.json b/api-playground/json/payments/upi-issuance/listVPAs.json new file mode 100644 index 00000000..4f660332 --- /dev/null +++ b/api-playground/json/payments/upi-issuance/listVPAs.json @@ -0,0 +1,15 @@ +{ + "parameters": { + "header": [ + { + "idempotencyKey": "sim.plaintext" + } + ] + }, + "body": { + "cursor": "01ARZ3NDEKTSV4RRFFQ69G5FAV", + "deviceId": "device-abc-123", + "limit": 20, + "mobile": "919999999999" + } +} diff --git a/api-playground/json/payments/upi-issuance/pollBindingStatus.json b/api-playground/json/payments/upi-issuance/pollBindingStatus.json new file mode 100644 index 00000000..7d7a99cd --- /dev/null +++ b/api-playground/json/payments/upi-issuance/pollBindingStatus.json @@ -0,0 +1,13 @@ +{ + "parameters": { + "header": [ + { + "idempotencyKey": "sim.plaintext" + } + ] + }, + "body": { + "deviceId": "device-abc-123", + "mobile": "919999999999" + } +} diff --git a/api-playground/json/payments/upi-issuance/requestBindingToken.json b/api-playground/json/payments/upi-issuance/requestBindingToken.json new file mode 100644 index 00000000..5b0530d3 --- /dev/null +++ b/api-playground/json/payments/upi-issuance/requestBindingToken.json @@ -0,0 +1,15 @@ +{ + "parameters": { + "header": [ + { + "idempotencyKey": "sim.plaintext,sim.bind-ok" + } + ] + }, + "body": { + "deviceId": "device-abc-123", + "mobile": "919999999999", + "os": "android", + "otpRequired": true + } +} diff --git a/api-playground/json/payments/upi-issuance/requestOTP.json b/api-playground/json/payments/upi-issuance/requestOTP.json new file mode 100644 index 00000000..17b0f0b0 --- /dev/null +++ b/api-playground/json/payments/upi-issuance/requestOTP.json @@ -0,0 +1,14 @@ +{ + "parameters": { + "header": [ + { + "idempotencyKey": "sim.plaintext" + } + ] + }, + "body": { + "deviceId": "device-abc-123", + "mobile": "919999999999", + "vpa": "919999999999-acme@setu" + } +} diff --git a/api-playground/json/payments/upi-issuance/unblockPayeeVPA.json b/api-playground/json/payments/upi-issuance/unblockPayeeVPA.json new file mode 100644 index 00000000..107f3c45 --- /dev/null +++ b/api-playground/json/payments/upi-issuance/unblockPayeeVPA.json @@ -0,0 +1,14 @@ +{ + "parameters": { + "header": [ + { + "idempotencyKey": "sim.plaintext" + } + ] + }, + "body": { + "deviceId": "device-abc-123", + "mobile": "919999999999", + "payeeVpa": "merchant@otherbank" + } +} diff --git a/api-playground/json/payments/upi-issuance/updateProgram.json b/api-playground/json/payments/upi-issuance/updateProgram.json new file mode 100644 index 00000000..d7553443 --- /dev/null +++ b/api-playground/json/payments/upi-issuance/updateProgram.json @@ -0,0 +1,22 @@ +{ + "parameters": { + "header": [ + { + "idempotencyKey": "sim.plaintext" + } + ], + "path": [ + { + "programId": "01ARZ3NDEKTSV4RRFFQ69G5FAV" + } + ] + }, + "body": { + "amountLimit": 500000, + "code": "ACME", + "isCreditAllowed": true, + "isDebitAllowed": false, + "name": "Acme Wallet", + "status": "inactive" + } +} diff --git a/api-playground/json/payments/upi-issuance/verifyOTP.json b/api-playground/json/payments/upi-issuance/verifyOTP.json new file mode 100644 index 00000000..125f3fed --- /dev/null +++ b/api-playground/json/payments/upi-issuance/verifyOTP.json @@ -0,0 +1,15 @@ +{ + "parameters": { + "header": [ + { + "idempotencyKey": "sim.plaintext,sim.otp-ok" + } + ] + }, + "body": { + "deviceId": "device-abc-123", + "mobile": "919999999999", + "otp": "123456", + "vpa": "919999999999-acme@setu" + } +} diff --git a/api-playground/products.json b/api-playground/products.json index b2df3a5f..97f3b252 100644 --- a/api-playground/products.json +++ b/api-playground/products.json @@ -19,6 +19,10 @@ { "name": "BBPS BillCollect", "path": "payments/bbps" + }, + { + "name": "UPI Issuance", + "path": "payments/upi-issuance" } ] }, diff --git a/api-references/payments/upi-issuance.json b/api-references/payments/upi-issuance.json index ab766fc3..42990bc2 100644 --- a/api-references/payments/upi-issuance.json +++ b/api-references/payments/upi-issuance.json @@ -18,7 +18,7 @@ ], "summary": "Generate a binding token", "description": "Generate a device-binding token: returns the VMN and the ready-to-send silent-SMS body, and starts onboarding for the user's mobile number.", - "operationId": "onboarding#requestBindingToken", + "operationId": "requestBindingToken", "parameters": [ { "name": "idempotencyKey", @@ -191,7 +191,7 @@ ], "summary": "Poll binding status", "description": "Poll a user's device-binding status. Returns the user object in its current state.", - "operationId": "onboarding#pollBindingStatus", + "operationId": "pollBindingStatus", "requestBody": { "required": true, "content": { @@ -351,7 +351,7 @@ ], "summary": "Request an OTP", "description": "Request the user-presence OTP SMS — include the vpa to verify a new VPA (new onboarding / new VPA); omit the vpa for a device change (SIM re-binding). Asynchronous: returns 202; the OTP SMS is sent shortly after.", - "operationId": "onboarding#requestOTP", + "operationId": "requestOTP", "parameters": [ { "name": "idempotencyKey", @@ -635,7 +635,7 @@ ], "summary": "Verify an OTP", "description": "Verify the OTP the user entered. Activates what it was requested for — a new VPA (new onboarding / new VPA, vpa in the body) or the user (a device change, no vpa).", - "operationId": "onboarding#verifyOTP", + "operationId": "verifyOTP", "parameters": [ { "name": "idempotencyKey", @@ -940,7 +940,7 @@ ], "summary": "Check VPA availability", "description": "Check whether a chosen VPA prefix is available. A taken prefix is not an error.", - "operationId": "onboarding#checkVPA", + "operationId": "checkVPA", "parameters": [ { "name": "idempotencyKey", @@ -1192,7 +1192,7 @@ ], "summary": "Create a VPA", "description": "Create a VPA over the user's chosen account. Requires an active user. With otpRequired, the VPA is created pending-verification until an OTP activates it.", - "operationId": "onboarding#createVPA", + "operationId": "createVPA", "parameters": [ { "name": "idempotencyKey", @@ -1463,7 +1463,7 @@ ], "summary": "Get a VPA", "description": "Fetch one of the user's VPAs by its VPA string.", - "operationId": "onboarding#getVPA", + "operationId": "getVPA", "parameters": [ { "name": "idempotencyKey", @@ -1724,7 +1724,7 @@ ], "summary": "List VPAs", "description": "List the user's live VPAs (active and pending-verification), newest-added first, keyset-paginated.", - "operationId": "onboarding#listVPAs", + "operationId": "listVPAs", "parameters": [ { "name": "idempotencyKey", @@ -1997,7 +1997,7 @@ ], "summary": "Deregister a VPA", "description": "Deregister one of the user's VPAs (soft delete; the entry is preserved for audit and re-registration). Idempotent for an already-deregistered VPA.", - "operationId": "onboarding#deregisterVPA", + "operationId": "deregisterVPA", "parameters": [ { "name": "idempotencyKey", @@ -2258,7 +2258,7 @@ ], "summary": "Create a program", "description": "Create a program — an engagement channel that VPAs are created under — and return its programId.", - "operationId": "onboarding#createProgram", + "operationId": "createProgram", "requestBody": { "required": true, "content": { @@ -2386,7 +2386,7 @@ ], "summary": "Update a program", "description": "Update a program's configuration. Only the fields supplied in the body are changed.", - "operationId": "onboarding#updateProgram", + "operationId": "updateProgram", "parameters": [ { "name": "programId", @@ -2568,7 +2568,7 @@ ], "summary": "Block a payee VPA", "description": "Block an external payee VPA for the user. Idempotent; requires an active user.", - "operationId": "onboarding#blockPayeeVPA", + "operationId": "blockPayeeVPA", "parameters": [ { "name": "idempotencyKey", @@ -2822,7 +2822,7 @@ ], "summary": "Unblock a payee VPA", "description": "Unblock a previously-blocked payee VPA (soft flip; the entry is preserved). Idempotent for an already-unblocked payee; requires an active user.", - "operationId": "onboarding#unblockPayeeVPA", + "operationId": "unblockPayeeVPA", "parameters": [ { "name": "idempotencyKey", @@ -3077,7 +3077,7 @@ ], "summary": "List blocked payee VPAs", "description": "List the user's currently-blocked payee VPAs, newest first, keyset-paginated.", - "operationId": "onboarding#listBlockedPayeeVPAs", + "operationId": "listBlockedPayeeVPAs", "parameters": [ { "name": "idempotencyKey", @@ -3618,7 +3618,7 @@ "pattern": "^([A-Za-z0-9.-]+)@([A-Za-z0-9.-]+)$", "minLength": 1, "maxLength": 255, - "description": "The full VPA to check (prefix@handle, e.g. 919999999999-acme@setu). Its prefix must start with the user's mobile number.", + "description": "The full VPA to check (prefix@handle, e.g. 919999999999-acme@setu). Its prefix must start with the user's alias (by default, their mobile number).", "example": "919999999999-acme@setu" } }, @@ -3751,7 +3751,7 @@ "pattern": "^([A-Za-z0-9.-]+)@([A-Za-z0-9.-]+)$", "minLength": 1, "maxLength": 255, - "description": "The full VPA to create (prefix@handle, e.g. 919999999999-acme@setu). Its prefix must start with the user's mobile number.", + "description": "The full VPA to create (prefix@handle, e.g. 919999999999-acme@setu). Its prefix must start with the user's alias (by default, their mobile number).", "example": "919999999999-acme@setu" } }, @@ -3829,7 +3829,7 @@ "pattern": "^([A-Za-z0-9.-]+)@([A-Za-z0-9.-]+)$", "minLength": 1, "maxLength": 255, - "description": "The full VPA to fetch (prefix@handle, e.g. 919999999999-acme@setu). Its prefix must start with the user's mobile number.", + "description": "The full VPA to fetch (prefix@handle, e.g. 919999999999-acme@setu). Its prefix must start with the user's alias (by default, their mobile number).", "example": "919999999999-acme@setu" } },