Available in🇮🇳 India
Run codes and links on a test account and pick each outcome on a hosted test page. Check the rate limits before you go live.
POST /v1/accounts/{account_id}/actions/{action} sends a code or mints a link. Run an action only when a requirement names it (requirement_type: action). status: failed is HTTP 200. The action ran, but the registry answered that it cannot be done, and error says why (#15).
Start with the overview for test credentials and headers.
1. Test Mode Coverage
Test Mode Differences
The table below lists how each action behaves in each mode:What You Can Test
The table below lists the areas to test on this endpoint:Endpoint Coverage in Test Mode
The table below lists the endpoints this page uses:2. Before You Begin
Prepare the following before you run the scenarios:- Get an account with an action due. The action appears in
requirementswithrequirement_type: action. - Keep the
urlfrom each link response. A requirement never carries the link.
metadata:
ckyc_mobile: Optional, withsend_ckyc_otp. The mobile on the CKYC record,+91followed by 10 digits. A mobile that is not the one on the record returnsstatus: failed.return_url: Required, withcreate_aadhaar_digilocker_link. Yourhttpspage the sub-merchant returns to.
Sample Request
The outputs come back in the response’smetadata. A code action returns sent_to and expires_at, and send_ckyc_otp also returns request_id. A link action returns url and expires_at. The request below sends the CKYC code.
Curl
Sample Response
What is due next is inrequirements. After a code, that is the code to send back. After a link, it is the same action. The action stays due until the sub-merchant completes the step. Run the action again for a new link.
Code Response: HTTP 200
Code Response: HTTP 200
Response
Link Response: HTTP 200
Link Response: HTTP 200
This is
create_video_kyc_link while the product is edd_pending. The link is in the response’s metadata (url and expires_at). create_video_kyc_link stays due in requirements, with no link on it.Response
Hosted Test Pages
In test mode, a video KYC, DigiLocker or ₹1 UPI link opens a hosted test page instead of the real step. Pick the outcome with a button. The account changes as it would in live mode, and Razorpay sends the matching webhook. The table below lists the buttons on each hosted test page:3. Test Scenarios
Work through these scenarios in order. Each row gives the trigger to send and what to confirm in the response.3.1 Scenarios
Live scenarios work in test mode today. Coming soon scenarios are not available in test mode yet. The table below lists 15 scenarios. 1 is live and 14 are coming soon:| # | Scenario | Trigger | What to confirm |
|---|---|---|---|
| 1 | Send the phone code Coming soon | An account with send_phone_otp due | Run send_phone_otp. Confirm completed, a masked sent_to and requirements listing phone_otp. Send 000007, as in scenario 2 on Update an Account. |
| 2 | Send the email code Coming soon | An account with send_email_otp due | Run send_email_otp. Confirm completed and email_otp in requirements. |
| 3 | A code for a verified contact Coming soon | A verified phone | Run send_phone_otp. Confirm 400 step_not_due. |
| 4 | Send the CKYC code Coming soon | PAN ABCPD1234A verified | Run send_ckyc_otp, as in the sample request. Confirm completed, with sent_to and request_id in metadata. Confirm ckyc_otp and ckyc_request_id in requirements. Send any 6 digits other than 000000 as individual_ckyc.otp, with the request_id as individual_ckyc.request_id. |
| 5 | CKYC code before the PAN Coming soon | No PAN yet | Run send_ckyc_otp. Confirm 400 step_not_due. |
| 6 | The registry does not answer Coming soon | PAN ABCPD1234W | Send the PAN. Run send_ckyc_otp. Confirm 503 provider_unavailable with Retry-After. |
| 7 | A mobile that is not on the CKYC record Coming soon | ckyc_mobile: "+919812345678", then 98123 | Run send_ckyc_otp with the first. Confirm HTTP 200 with status: failed, an error and ckyc_fetch still due. With the second, confirm 400 invalid_format. Leave ckyc_mobile out, or send +919845098450, to get completed. |
| 8 | Too many sends Coming soon | send_phone_otp 6 times in an hour | Confirm the 6th send returns 429 rate_limited with Retry-After. |
| 9 | An action that does not exist Live | send_sms_otp | Confirm 400 invalid_option. |
| 10 | Video KYC link while it is due Coming soon | A product in edd_pending | Run create_video_kyc_link. Confirm the link’s url and expires_at in the response’s metadata. Confirm create_video_kyc_link is still due, as in the link response. Open the url and pick Approved, as in scenario 5 on Terms and Submission. |
| 11 | Video KYC link when it is not due Coming soon | A product in in_progress | Confirm 400 step_not_due. |
| 12 | Fetch the Aadhaar through DigiLocker Coming soon | return_url, then Share Aadhaar on the hosted test page | Run create_aadhaar_digilocker_link. Open the url in its response’s metadata and pick Share Aadhaar. Confirm proof_of_address_for_individual cleared. |
| 13 | Verify the bank account with ₹1 Coming soon | Pay ₹1 on the hosted test page | Run create_upi_link. Open the url in its response’s metadata and pick Pay ₹1. Confirm bank_account cleared. |
| 14 | A link that expires Coming soon | Expire the link on the hosted test page | Run any link action and open its url. Pick Expire the link. Confirm the action is still due, and run it again for a new link. |
| 15 | An action the registry cannot do Coming soon | PAN ABCPD1234L | Send the PAN. It verifies, with ckyc_fetch due. Run send_ckyc_otp. Confirm HTTP 200 with status: failed and an error, and ckyc_fetch still due. |
3.2 Scenario Details
The details below expand the scenarios that need more than one step:4. Send the CKYC Code
4. Send the CKYC Code
Before you begin: Verify PAN
ABCPD1234A, as in scenario 4 on Update an Account.How to test: Send the sample request.Expected result: HTTP 200 with status: completed. The masked mobile XXXXXX8450 is in sent_to, with the request_id. ckyc_otp and ckyc_request_id are in requirements. The account’s requirements show them in place of ckyc_fetch.Your integration should: Ask for the code in your form. Send it as individual_ckyc.otp, with the request_id as individual_ckyc.request_id, as in scenario 5 on Update an Account. A resend replaces the open code and its request ID.6. The Registry Does Not Answer
6. The Registry Does Not Answer
Before you begin: Send PAN
ABCPD1234W. The PAN verifies, but the code cannot be sent.How to test: Run send_ckyc_otp.Expected result: HTTP 503 with reason: provider_unavailable and Retry-After. Nothing ran.Your integration should: Retry after Retry-After. Nothing ran, so the retry is safe.8. Too Many Sends
8. Too Many Sends
How to test: Run
send_phone_otp 6 times within an hour.Expected result: HTTP 429 with reason: rate_limited and Retry-After.Your integration should: Show when the sub-merchant can try again, from Retry-After. Every code send counts towards the limit of 5 an hour.10. Video KYC Link While It Is Due
10. Video KYC Link While It Is Due
Before you begin: Get a product to
edd_pending, as in scenario 4 on Terms and Submission.How to test: Run create_video_kyc_link.Expected result: HTTP 200, as in the link response. The link’s url and expires_at are in the response’s metadata. create_video_kyc_link stays due, with no link on the requirement. It clears by itself once the call is approved.Webhooks: account.requirements.updated when the outcome of the call arrives, then the product’s status event.Your integration should: Open the link inside your product, and fetch when the sub-merchant returns. If the link expired or the call did not verify, run the action again for a fresh link.12. Fetch the Aadhaar Through DigiLocker
12. Fetch the Aadhaar Through DigiLocker
Before you begin: Get
proof_of_address_for_individual due, with DigiLocker as one of its sub-requirements. Use test business Individual B, after you send its PAN. See Individual.How to test:- Run
create_aadhaar_digilocker_linkwith this body:
- Open the
urlin the response’smetadatato reach the hosted test page. Pick Share Aadhaar. The page returns to yourreturn_url.
proof_of_address_for_individual clears. The Aadhaar comes back in the authorised person’s documents, with metadata.source: digilocker. Decline leaves the composite due, with the action and the document uploads still offered. Run the action again, or upload a document.Webhooks: account.requirements.updated once the Aadhaar is fetched.Your integration should: Fetch the account when the sub-merchant returns. Do not assume the share succeeded.Errors to test: The table below lists the errors this scenario covers:13. Verify the Bank Account With ₹1
13. Verify the Bank Account With ₹1
Before you begin: Get
bank_account due after a failed bank check, with create_upi_link as one of its sub-requirements. See scenario 7 on Update an Account.How to test:- Run
create_upi_link. - Open the
urlin the response’smetadataand pick Pay ₹1.
bank_account clears and the settlement account is verified. Pay from another person’s account leaves bank_account due, with the account and the UPI link still offered. Run the action again, or send the account.Webhooks: account.requirements.updated once the account is verified.Your integration should: Open the link on the sub-merchant’s phone, where a UPI app is installed.15. An Action the Registry Cannot Do
15. An Action the Registry Cannot Do
Before you begin: Send PAN
ABCPD1234L. It verifies, and ckyc_fetch is due.How to test: Run send_ckyc_otp.Expected result: HTTP 200 with status: failed. The action ran, but the CKYC registry answered that it cannot send the code. error says why, and no code was sent. ckyc_fetch stays due.Your integration should: Offer skip_ckyc, the other sub-requirement of ckyc_fetch, instead of a retry. Skipping makes proof_of_address_for_individual due.3.3 Errors to Handle
Every error returns the same object. Branch onerror.reason and error.field, because the description can change. The overview lists the errors every operation shares.
The table below lists the errors this endpoint returns: