Skip to content

docs(DATA-2829): RPD docs update #401

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
VarunSonava merged 2 commits into from
Jan 22, 2026
Merged

docs(DATA-2829): RPD docs update #401

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f9341b8
Remove debit attempt failure webhook, add addonschema example
VarunSonava Jan 22, 2026
f3c9cb1
add account type values, update upibillid alphanumeric
VarunSonava Jan 22, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
229 changes: 91 additions & 138 deletions content/data/bav/reverse-penny-drop/api-integration.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -140,14 +140,14 @@ If successful, you will get a JSON response. Two of the fields in the response w
"shortUrl": "https://sandbox.bills.pe/wh9kk4mwuktg",
"status": "BAV_REVERSE_PENNY_DROP_CREATED",
"traceId": "1-640f227f-784ece1c005e4f9e653947ca",
"upiBillId": "1114053970646533628",
"upiLink": "upi://pay?pa=bauvatest@kaypay&pn=BauvaTest&am=1.00&tr=1114053970646533628&tn=Account%20Verification&cu=INR&mode=04",
"upiBillId": "a6577bb0ae4d9301cf47c1",
"upiLink": "upi://pay?pa=bauvatest@kaypay&pn=BauvaTest&am=1.00&tr=a6577bb0ae4d9301cf47c1&tn=Account%20Verification&cu=INR&mode=04",
"validUpto": "2023-03-13T13:20:52.277688"
} `}
</CodeBlockWithCopy>
<Callout type="tip">
Note: This 'id' is your 'requestId'. Please use
this 'requestId' for rest the API reference.
this 'requestId' for rest of the API reference.
</Callout>
</>
),
Expand Down Expand Up @@ -265,9 +265,8 @@ This API lets you test the end to end flow without an actual payment. This will
{`POST /api/verify/ban/reverse/mock_payment/:requestId

{
"paymentStatus": "successful" // or 'expired'. Default = 'successful'
}

"paymentStatus": "successful" // or 'expired' or 'failed'
}
`}
</CodeBlockWithCopy>
<hr className="tertiary" />
Expand Down Expand Up @@ -383,7 +382,7 @@ Setu provides webhook authentication. For more details, refer to <a href="/data/

<hr className="tertiary" />

##### 1. RPD_VERIFICATION_UPDATE Webhook
##### RPD_VERIFICATION_UPDATE Webhook

This webhook is sent when the end user makes a payments.

Expand All @@ -404,7 +403,7 @@ _`accountType` can be `BANK_ACCOUNT`, `PPI` or `UNKNOWN`_
<br />

_`bankAccountType` is an optional data field, you may not receive the value always. (Please contact with Setu team to know more about this feature.)_
_The value can be `SAVINGS`, `CURRENT`, `NRO`, `NRE`_
_The value can be `SAVINGS`, `CURRENT`, `VIRTUAL_ACCOUNT`, `OVERDRAFT`, `UOD`, `SOD`, `PPIWALLET`

###### Examples

Expand All @@ -426,7 +425,7 @@ _The value can be `SAVINGS`, `CURRENT`, `NRO`, `NRE`_
"rpd" : {
"success" : true,
"id" : "7097e53a-ba29-48a2-983d-878433b4f33e", // the RPD request id
"upiBillId" : "907442106379798024",
"upiBillId" : "a6577bb0ae4d9301cf47c1",
"data" : {
"bankAccountName" : "Eve",
"bankAccountIfsc" : "SBIN0000001",
Expand All @@ -452,13 +451,17 @@ _The value can be `SAVINGS`, `CURRENT`, `NRO`, `NRE`_
"swift": "",
"upi": "true"
}
}
},
"additionalData": { // if you have specified while creating RPD request
"key1" : "value1",
"key2" : "value2"
}
},
"receiptId": "AXI75fc85a15ce6449491b79f8509c55a96",
"transactionId": "602185974626"
}
}
},
"status": "BAV_REVERSE_PENNY_DROP_PAYMENT_SUCCESSFUL",
"productInstanceId": "abcdefgh-c1b5-4219-a64b-abcabc123456",
"traceId" : "7097e53a-baq9-4122-9d3d-8s8433b4f33e",
}
`}
Expand All @@ -471,6 +474,73 @@ _The value can be `SAVINGS`, `CURRENT`, `NRO`, `NRE`_
Example 2
</Text>

<Card padding="nano" shape="rounded" marginBottom="micro">
<details>
<summary>
In case of successful bank verification, with add-on schema configured
</summary>
<hr className="tertiary" />
<CodeBlockWithCopy language="json">{`
{
"event" : "RPD_VERIFICATION_UPDATE",
"timeStamp" : "2021-11-12T00:12:29+05:30",
"data" : {
"rpd" : {
"success" : true,
"id" : "7097e53a-ba29-48a2-983d-878433b4f33e", // the RPD request id
"upiBillId" : "a6577bb0ae4d9301cf47c1",
"data" : {
"bankAccountName" : "Eve",
"bankAccountIfsc" : "SBIN0000001",
"bankAccountNumber" : "48097036412",
"payerVpa" : "test@upi",
"accountType" : "BANK_ACCOUNT", // or UNKNOWN or PPI
"bankAccountType" : "SAVINGS", // Optional, can be null
"ifscCrossCheck" : true,
"ifscDetails" : {
"address": "EXPRESS TOWERS,GROUND FLOOR,NARIMAN POINT,MUMBAI 400021",
"branch": "Development Bank of Singapore IMPS",
"center": "MUMBAI",
"city": "MUMBAI",
"contact": "+912266388888",
"district": "MUMBAI",
"imps": "true",
"iso3166": "IN-MH",
"micr": "400641002",
"name": "Development Bank of Singapore",
"neft": "true",
"rtgs": "true",
"state": "MAHARASHTRA",
"swift": "",
"upi": "true"
}
},
"additionalData": { // if you have specified while creating RPD request
"key1" : "value1",
"key2" : "value2"
},
"receiptId": "AXI75fc85a15ce6449491b79f8509c55a96",
"transactionId": "602185974626",
"addOnFields": {
"psp_app": "PayApp"
}
}
},
"status": "BAV_REVERSE_PENNY_DROP_PAYMENT_SUCCESSFUL",
"traceId" : "7097e53a-baq9-4122-9d3d-8s8433b4f33e",
"productInstanceId": "abcdefgh-c1b5-4219-a64b-abcabc123456",
}
`}
</CodeBlockWithCopy>

</details>
</Card>


<Text size="small" weight="600">
Example 3
</Text>

<Card padding="nano" shape="rounded" marginBottom="micro">
<details>
<summary>
Expand All @@ -486,7 +556,7 @@ _The value can be `SAVINGS`, `CURRENT`, `NRO`, `NRE`_
"rpd" : {
"success" : false,
"id" : "7097e53a-ba29-48a2-983d-878433b4f33e",
"upiBillId" : "907442106379798024",
"upiBillId" : "a6577bb0ae4d9301cf47c1",
"data" : null,
"error" : {
"code" : "BAV_REVERSE_PENNY_DROP_EXPIRED", // or BAV_REVERSE_PENNY_DROP_FAILED
Expand All @@ -502,7 +572,7 @@ _The value can be `SAVINGS`, `CURRENT`, `NRO`, `NRE`_
</Card>

<Text size="small" weight="600">
Example 3
Example 4
</Text>

<Card padding="nano" shape="rounded" marginBottom="micro">
Expand All @@ -517,7 +587,7 @@ _The value can be `SAVINGS`, `CURRENT`, `NRO`, `NRE`_
"rpd": {
"success": true,
"id": "1af36b4e-681e-48a2-a15c-3b92da00e4c4",
"upiBillId": "1005100812449350916",
"upiBillId": "a6577bb0ae4d9301cf47c1",
"data": null,
"additionalData": {
"key1": value1,
Expand All @@ -540,123 +610,6 @@ _The value can be `SAVINGS`, `CURRENT`, `NRO`, `NRE`_
</details>
</Card>

##### 2. RPD_DEBIT_ATTEMPT_FAILED Webhook

This webhook is sent when the end user tries to make a payments but the debit fails due to some reason.

<Card padding="nano" shape="rounded">
<details>
<summary>statusCode of this event can be one of the following:</summary>
<table>
<tr>
<th>statusCode</th>
<th>statusDescription</th>
</tr>
<tr>
<td>R01</td>
<td>The customer's debit attempt failed.</td>
</tr>
<tr>
<td>R02</td>
<td>Payment authorization took too long.</td>
</tr>
<tr>
<td>R03</td>
<td>The customer's bank is taking too long to respond.</td>
</tr>
<tr>
<td>R04</td>
<td>The debit process took too long.</td>
</tr>
<tr>
<td>R05</td>
<td>Connection timed out during the credit request process.</td>
</tr>
<tr>
<td>R06</td>
<td>The transaction exceeds the risk threshold.</td>
</tr>
<tr>
<td>R07</td>
<td>The customer's bank is unavailable.</td>
</tr>
<tr>
<td>R08</td>
<td>This transaction isn't permitted for the beneficiary.</td>
</tr>
<tr>
<td>R09</td>
<td>Connection timed out during the debit request process.</td>
</tr>
<tr>
<td>R12</td>
<td>Beneficiary bank response time is too high.</td>
</tr>
<tr>
<td>R13</td>
<td>The total debit amount exceeded the set limit.</td>
</tr>
<tr>
<td>R14</td>
<td>Transaction details mismatch.</td>
</tr>
<tr>
<td>R16</td>
<td>
The requested function is not supported for the beneficiary.
</td>
</tr>
<tr>
<td>R20</td>
<td>
Receiver/beneficiary is not available, causing a timeout.
</td>
</tr>
<tr>
<td>R22</td>
<td>The debit acknowledgement was not received.</td>
</tr>
<tr>
<td>R25</td>
<td>Duplicate transaction request.</td>
</tr>
<tr>
<td>R100</td>
<td>Any other upstream server error.</td>
</tr>
</table>
</details>
</Card>

###### Examples

<Text size="small" weight="600">
Example 1
</Text>

<Card padding="nano" shape="rounded" marginBottom="micro">
<details>
<summary>In case of customer's debit attempt failed</summary>
<hr className="tertiary" />
<CodeBlockWithCopy language="json">
{`
{
"data": {
"rpd": {
"id": "178ce32b-bf43-4797-9423-027d3722df08",
"additionalData": null, // customer's own data if they provided
"statusCode": "R01",
"statusDescription": "The customer's debit attempt failed."
}
},
"event": "RPD_DEBIT_ATTEMPT_FAILED",
"timeStamp": "2023-08-24T12:59:11.427233"
}
`}
</CodeBlockWithCopy>
</details>
</Card>

<hr class="tertiary" />

#### Get Details API
Expand Down Expand Up @@ -728,9 +681,9 @@ This is an optional API. This API lets you know the bank verification status.
"payerVpa": "customer@vpa"
},
"id": "1b740e7a-5a81-4b88-ad43-110a08935286",
"shortUrl": "https://sandbox.bills.pe/wh9kk4mwuktg",
"upiBillId": "1114053970646533628",
"upiLink": "upi://pay?pa=bauvatest@kaypay&pn=BauvaTest&am=1.00&tr=1114053970646533628&tn=Account%20Verification&cu=INR&mode=04",
"shortUrl": "https://sandbox.bills.pe/a6577bb0ae4d9301cf47c1",
"upiBillId": "a6577bb0ae4d9301cf47c1",
"upiLink": "upi://pay?pa=bauvatest@kaypay&pn=BauvaTest&am=1.00&tr=a6577bb0ae4d9301cf47c1&tn=Account%20Verification&cu=INR&mode=04",
"validUpto": "2023-03-13T13:20:52.277688"
"traceId": "1-640f228a-4dded97e470971343adae3da",
"additionalData": {
Expand Down Expand Up @@ -766,9 +719,9 @@ This is an optional API. This API lets you know the bank verification status.
"status": "BAV_REVERSE_PENNY_DROP_PII_PURGED",
"data": null,
"id": "1b740e7a-5a81-4b88-ad43-110a08935286",
"shortUrl": "https://sandbox.bills.pe/wh9kk4mwuktg",
"upiBillId": "1114053970646533628",
"upiLink": "upi://pay?pa=bauvatest@kaypay&pn=BauvaTest&am=1.00&tr=1114053970646533628&tn=Account%20Verification&cu=INR&mode=04",
"shortUrl": "https://sandbox.bills.pe/a6577bb0ae4d9301cf47c1",
"upiBillId": "a6577bb0ae4d9301cf47c1",
"upiLink": "upi://pay?pa=bauvatest@kaypay&pn=BauvaTest&am=1.00&tr=a6577bb0ae4d9301cf47c1&tn=Account%20Verification&cu=INR&mode=04",
"validUpto": "2023-03-13T13:20:52.277688"
"traceId": "1-640f228a-4dded97e470971343adae3da",
"additionalData": {
Expand Down