> ## Documentation Index
> Fetch the complete documentation index at: https://razorpay.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Action Tests

> Test Onboarding APIs actions in Test Mode, including OTP, CKYC, DigiLocker, UPI and video KYC scenarios.

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](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration) for test credentials and headers.

## 1. Test Mode Coverage

### Test Mode Differences

The table below lists how each action behaves in each mode:

| Action | Live mode | Test mode |
| - | - | - |
| `send_phone_otp`, `send_email_otp` | The user receives real One-Time Password (OTP) codes. | No SMS or email is sent. The code `000007` verifies. |
| `send_ckyc_otp` | The code goes to the mobile on the Central KYC Records Registry (CKYC) record. | No code reaches a phone. Any 6 digits other than `000000` verify. |
| `create_video_kyc_link` | The sub-merchant joins a call with an agent. | The link opens a hosted test page where you pick the outcome. |
| `create_aadhaar_digilocker_link` | The sub-merchant signs in to DigiLocker. | The link opens a hosted test page where you share or decline. |
| `create_upi_link` | The sub-merchant pays ₹1 from their UPI app. | The link opens a hosted test page where you pay or fail the payment. No money moves. |

### What You Can Test

The table below lists the areas to test on this endpoint:

| Area | What to test | In test mode |
| - | - | - |
| `send_phone_otp`, `send_email_otp` | Send, resend and the rate limit | Available |
| `send_ckyc_otp` | Send, a mobile that is not on the record and the registry not answering | Available |
| `create_video_kyc_link` | The link and the outcome of the call | Available |
| `create_aadhaar_digilocker_link` | The Aadhaar fetch through DigiLocker | Available |
| `create_upi_link` | The ₹1 UPI check of the bank account | Available |
| Expired links | Any link action. Expire the link on the hosted test page. | Available |

### Endpoint Coverage in Test Mode

The table below lists the endpoints this page uses:

| API | Endpoint | Available in test mode |
| - | - | - |
| [Run an Action](https://razorpay.com/docs/api/partners/accounts/run-action.md) | `POST /v1/accounts/{account_id}/actions/{action}` | Available |
| [Update an Account](https://razorpay.com/docs/api/partners/accounts/update.md) | `PATCH /v1/accounts/{account_id}` | Available |

## 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.

```bash Curl theme={null}
curl -X POST https://api.razorpay.com/v1/accounts/acc_TcdGEzmfKQzEl1/actions/send_ckyc_otp \
-u rzp_test_partner_[CLIENT_ID]:[CLIENT_SECRET] \
-H "Content-Type: application/json" \
-H "X-Idempotency-Key: [UNIQUE_KEY]" \
-d '{}'
```

Know more about the [request parameters](https://razorpay.com/docs/api/partners/accounts/run-action.md).

### 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.

> [accordion] Code Response: HTTP 200
>
> ```json Response theme={null}
> {
>   "action": "send_ckyc_otp",
>   "status": "completed",
>   "metadata": [
>     {
>       "type": "sent_to",
>       "value": "XXXXXX8450"
>     },
>     {
>       "type": "expires_at",
>       "value": 1793165460
>     },
>     {
>       "type": "request_id",
>       "value": "CKYCREQ20261115000123"
>     }
>   ],
>   "requirements": [
>     {
>       "id": "req_57W5G6wcHziGOP",
>       "requirement_code": "ckyc_otp",
>       "requirement_level": "mandatory",
>       "requirement_type": "input",
>       "description": "Enter the code sent to the mobile on your CKYC record.",
>       "field_path": "business_profile.authorized_person.identity_numbers.individual_ckyc.otp",
>       "value_type": "text",
>       "status": "created"
>     },
>     {
>       "id": "req_mKVNnArZtTaL0M",
>       "requirement_code": "ckyc_request_id",
>       "requirement_level": "mandatory",
>       "requirement_type": "input",
>       "description": "The request ID that came with the code.",
>       "field_path": "business_profile.authorized_person.identity_numbers.individual_ckyc.request_id",
>       "value_type": "text",
>       "status": "created"
>     }
>   ],
>   "error": null
> }
> ```

> [accordion] 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.
>
> ```json Response theme={null}
> {
>   "action": "create_video_kyc_link",
>   "status": "completed",
>   "metadata": [
>     {
>       "type": "url",
>       "value": "https://vkyc.razorpay.com/start?session=vk_3Rt8Lq2Zp6Wn"
>     },
>     {
>       "type": "expires_at",
>       "value": 1793252400
>     }
>   ],
>   "requirements": [
>     {
>       "id": "req_bmOw79SOmj6jEj",
>       "requirement_code": "create_video_kyc_link",
>       "requirement_level": "mandatory",
>       "requirement_type": "action",
>       "description": "Complete a short video call with a Razorpay agent to verify your identity and address. Keep your PAN card on hand.",
>       "status": "created"
>     }
>   ],
>   "error": null
> }
> ```

### 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:

| Action | Button on the hosted test page | What happens |
| - | - | - |
| `create_video_kyc_link` | **Approved** | `under_review`, then `activated` about 5 sec later |
| `create_video_kyc_link` | **Rejected** | `under_review`, then `rejected` about 5 sec later |
| `create_video_kyc_link` | **Unable to verify** | The product stays `edd_pending`, and `create_video_kyc_link` stays due. Run it again for a new call. |
| `create_video_kyc_link` | **Expire the link** | `create_video_kyc_link` stays due. Run it again for a new link. |
| `create_aadhaar_digilocker_link` | **Share Aadhaar** | `proof_of_address_for_individual` clears. The Aadhaar comes back in `documents` with `metadata.source: digilocker`. |
| `create_aadhaar_digilocker_link` | **Decline** | `proof_of_address_for_individual` stays due, with the action and the document uploads. Run the action again, or upload a document. |
| `create_aadhaar_digilocker_link` | **Expire the link** | `create_aadhaar_digilocker_link` stays due. Run it again for a new link. |
| `create_upi_link` | **Pay ₹1** | `bank_account` clears, and the settlement account is verified. |
| `create_upi_link` | **Pay from another person's account** | `bank_account` stays due. Run `create_upi_link` again, or send the account. |
| `create_upi_link` | **Expire the link** | `create_upi_link` stays due. Run it again for a new link. |

## 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:

<table>
  <colgroup>
    <col width="6%" />

    <col width="22%" />

    <col width="24%" />

    <col width="48%" />
  </colgroup>

  <thead><tr><th>#</th><th>Scenario</th><th>Trigger</th><th>What to confirm</th></tr></thead>

  <tbody>
    <tr><td>1</td><td>Send the phone code Coming soon</td><td>An account with `send_phone_otp` due</td><td>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](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/update-account.md).</td></tr>
    <tr><td>2</td><td>Send the email code Coming soon</td><td>An account with `send_email_otp` due</td><td>Run `send_email_otp`. Confirm `completed` and `email_otp` in `requirements`.</td></tr>
    <tr><td>3</td><td>A code for a verified contact Coming soon</td><td>A verified phone</td><td>Run `send_phone_otp`. Confirm `400 step_not_due`.</td></tr>
    <tr><td>4</td><td>Send the CKYC code Coming soon</td><td>PAN `ABCPD1234A` verified</td><td>Run `send_ckyc_otp`, as in the [sample request](#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`.</td></tr>
    <tr><td>5</td><td>CKYC code before the PAN Coming soon</td><td>No PAN yet</td><td>Run `send_ckyc_otp`. Confirm `400 step_not_due`.</td></tr>
    <tr><td>6</td><td>The registry does not answer Coming soon</td><td>PAN `ABCPD1234W`</td><td>Send the PAN. Run `send_ckyc_otp`. Confirm `503 provider_unavailable` with `Retry-After`.</td></tr>
    <tr><td>7</td><td>A mobile that is not on the CKYC record Coming soon</td><td>`ckyc_mobile: "+919812345678"`, then `98123`</td><td>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`.</td></tr>
    <tr><td>8</td><td>Too many sends Coming soon</td><td>`send_phone_otp` 6 times in an hour</td><td>Confirm the 6th send returns `429 rate_limited` with `Retry-After`.</td></tr>
    <tr><td>9</td><td>An action that does not exist Live</td><td>`send_sms_otp`</td><td>Confirm `400 invalid_option`.</td></tr>
    <tr><td>10</td><td>Video KYC link while it is due Coming soon</td><td>A product in `edd_pending`</td><td>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](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/terms-and-submission.md).</td></tr>
    <tr><td>11</td><td>Video KYC link when it is not due Coming soon</td><td>A product in `in_progress`</td><td>Confirm `400 step_not_due`.</td></tr>
    <tr><td>12</td><td>Fetch the Aadhaar through DigiLocker Coming soon</td><td>`return_url`, then **Share Aadhaar** on the hosted test page</td><td>Run `create_aadhaar_digilocker_link`. Open the `url` in its response's `metadata` and pick **Share Aadhaar**. Confirm `proof_of_address_for_individual` cleared.</td></tr>
    <tr><td>13</td><td>Verify the bank account with ₹1 Coming soon</td><td>**Pay ₹1** on the hosted test page</td><td>Run `create_upi_link`. Open the `url` in its response's `metadata` and pick **Pay ₹1**. Confirm `bank_account` cleared.</td></tr>
    <tr><td>14</td><td>A link that expires Coming soon</td><td>**Expire the link** on the hosted test page</td><td>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.</td></tr>
    <tr><td>15</td><td>An action the registry cannot do Coming soon</td><td>PAN `ABCPD1234L`</td><td>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.</td></tr>
  </tbody>
</table>

### 3.2 Scenario Details

The details below expand the scenarios that need more than one step:

> [accordion] 4. Send the CKYC Code
>
> **Before you begin:** Verify PAN `ABCPD1234A`, as in scenario 4 on [Update an Account](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/update-account.md).
>
> **How to test:** Send the [sample request](#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](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/update-account.md). A resend replaces the open code and its request ID.

> [accordion] 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.

> [accordion] 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.

> [accordion] 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](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/terms-and-submission.md).
>
> **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.

> [accordion] 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](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/individual.md).
>
> **How to test:**
>
> 1. Run `create_aadhaar_digilocker_link` with this body:
>
> ```json theme={null}
> {
>   "metadata": {
>     "return_url": "https://shop.example.com/onboarding/return"
>   }
> }
> ```
>
> 2. 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:
>
> | Trigger | HTTP | `error.reason` | `error.field` | `error.description` |
> | - | - | - | - | - |
> | No `return_url` | 400 | `invalid_request` | `metadata.return_url` | `The request is missing a required field.` |
> | A `return_url` that uses `http` instead of `https` | 400 | `invalid_format` | `metadata.return_url` | `The value isn't in the right format.` |

> [accordion] 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](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/update-account.md).
>
> **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.

> [accordion] 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 on `error.reason` and `error.field`, because the description can change. The [overview](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration) lists the errors every operation shares.

The table below lists the errors this endpoint returns:

| Trigger | HTTP | `error.reason` | `error.field` |
| - | - | - | - |
| `send_sms_otp` | 400 | `invalid_option` | `action` |
| `create_aadhaar_digilocker_link` without `return_url` | 400 | `invalid_request` | `metadata.return_url` |
| `ckyc_mobile: "98123"` | 400 | `invalid_format` | `metadata.ckyc_mobile` |
| An action with nothing due | 400 | `step_not_due` | `action` |
| 6 sends of 1 action in an hour | 429 | `rate_limited` | Not applicable |
| CKYC code for PAN `ABCPD1234W` | 503 | `provider_unavailable` | Not applicable |

## 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:

| Gap | What goes wrong in production | What to do | Test with |
| - | - | - | - |
| Unlimited resend | Sub-merchants hit the hourly limit and are locked out. | Block the resend button for 30 sec. Show `Retry-After`. | #8 |
| Video KYC link shown too early | The call fails with `step_not_due`. | Show the link only when `create_video_kyc_link` is due. | #11 |
| Waiting on a link | Your page polls forever after the sub-merchant closes the link. | Fetch when they return. If the action is still due, run it again for a new link. | #10, #14 |

## 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:

| Topic | What to know | On this page | Test it | Read more |
| - | - | - | - | - |
| Actions follow requirements | Run an action only when a requirement names it. Its response lists what is due next. | Every action here returns `requirements`. | #3, #11 | [Collect Requirements](https://razorpay.com/docs/partners/aggregators/onboarding-api/collect-requirements.md) |
| Retry 503 only | HTTP 503 means nothing ran. HTTP 200 with `status: failed` means the registry answered that it cannot be done, so a retry does not help. | The CKYC registry can be down. | #6 | [Error Index](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/error-index.md) |

### Related Information

* [Test Your Integration](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration)
* [Create an Account](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/create-account.md)
* [Fetch an Account](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/fetch-account.md)
* [Update an Account](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/update-account.md)
* [Documents](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/documents.md)
* [Terms and Submission](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/terms-and-submission.md)
* [Needs Clarification](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/needs-clarification.md)
* [Webhooks](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/webhooks.md)
* [Test Values](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/test-values.md)
* [Error Index](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/error-index.md)
