Skip to main content
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 requirements with requirement_type: action.
  • Keep the url from each link response. A requirement never carries the link.
Some actions take inputs in metadata:
  • ckyc_mobile: Optional, with send_ckyc_otp. The mobile on the CKYC record, +91 followed by 10 digits. A mobile that is not the one on the record returns status: failed.
  • return_url: Required, with create_aadhaar_digilocker_link. Your https page the sub-merchant returns to.

Sample Request

The outputs come back in the response’s metadata. 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
Know more about the request parameters.

Sample Response

What is due next is in requirements. 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.
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:
#ScenarioTriggerWhat to confirm
1Send the phone code Coming soonAn account with send_phone_otp dueRun send_phone_otp. Confirm completed, a masked sent_to and requirements listing phone_otp. Send 000007, as in scenario 2 on Update an Account.
2Send the email code Coming soonAn account with send_email_otp dueRun send_email_otp. Confirm completed and email_otp in requirements.
3A code for a verified contact Coming soonA verified phoneRun send_phone_otp. Confirm 400 step_not_due.
4Send the CKYC code Coming soonPAN ABCPD1234A verifiedRun 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.
5CKYC code before the PAN Coming soonNo PAN yetRun send_ckyc_otp. Confirm 400 step_not_due.
6The registry does not answer Coming soonPAN ABCPD1234WSend the PAN. Run send_ckyc_otp. Confirm 503 provider_unavailable with Retry-After.
7A mobile that is not on the CKYC record Coming soonckyc_mobile: "+919812345678", then 98123Run 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.
8Too many sends Coming soonsend_phone_otp 6 times in an hourConfirm the 6th send returns 429 rate_limited with Retry-After.
9An action that does not exist Livesend_sms_otpConfirm 400 invalid_option.
10Video KYC link while it is due Coming soonA product in edd_pendingRun 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.
11Video KYC link when it is not due Coming soonA product in in_progressConfirm 400 step_not_due.
12Fetch the Aadhaar through DigiLocker Coming soonreturn_url, then Share Aadhaar on the hosted test pageRun create_aadhaar_digilocker_link. Open the url in its response’s metadata and pick Share Aadhaar. Confirm proof_of_address_for_individual cleared.
13Verify the bank account with ₹1 Coming soonPay ₹1 on the hosted test pageRun create_upi_link. Open the url in its response’s metadata and pick Pay ₹1. Confirm bank_account cleared.
14A link that expires Coming soonExpire the link on the hosted test pageRun 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.
15An action the registry cannot do Coming soonPAN ABCPD1234LSend 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:
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.
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.
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.
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:
  1. Run create_aadhaar_digilocker_link with this body:
  1. Open the url in the response’s metadata to reach the hosted test page. Pick Share Aadhaar. The page returns to your return_url.
Expected result: 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:
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:
  1. Run create_upi_link.
  2. Open the url in the response’s metadata and pick Pay ₹1.
Expected result: 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.
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 on error.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:

4. Common Integration Gaps

These mistakes most often stall an onboarding or leave an account in the wrong state after go-live. The Test with column points to the scenario that proves you have handled each one. Codes and links The table below lists the gaps in handling codes and links:

5. Best Integration Practices

These practices apply to every onboarding integration. The On this page column says what each one means here. The table below lists the practices for actions:
Last modified on November 18, 2026