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

# Fetch Account Tests

> Test fetching sub-merchant accounts on Onboarding APIs in Test Mode, including list, filter and status scenarios.

Available in
🇮🇳 India

Fetch and list sub-merchant accounts in test mode, read their requirements and follow each product's status before you go live.

`GET /v1/accounts/{account_id}` returns the account, the `verification` of each element and each product's `status` and `requirements`. Fetch to see the account's current state at any time. Webhooks tell you when it changes.

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 fetching and listing behave in each mode:

| Behaviour | Live mode | Test mode |
| - | - | - |
| The fetch response | The account, its verifications and its requirements. | The same response as live mode, for accounts created in test mode. |
| Checks that run after the response | A check, such as the website check, can take much longer to settle. | The check settles a few seconds after the response. |
| Review after submission | A review can take hours or days. `under_review` can stay until a reviewer acts. | The outcome of a review arrives about 5 sec after submission. |
| Listing accounts | Lists the live accounts your app created. | Lists only the test accounts your app created. |

### What You Can Test

The table below lists the areas to test on these endpoints:

| Area | What to test | In test mode |
| - | - | - |
| Fetch an account | The account, its verifications and its requirements | Available |
| Requirements | `id`, `requirement_code`, `requirement_level`, `requirement_type`, `requirement_reason`, `field_path`, `value_type`, `options`, `fulfillment_criteria`, `sub_requirements` and `status`, recomputed on every fetch as in live mode | Available |
| Status changes | Checks that settle after the response, and the product's status after submission | Available |
| List and filter | `email`, `phone`, `product`, `from`, `to`, `count` and `skip` | Available |
| Identifiers | Identity numbers and account numbers in full, as in live mode | Available |

### Endpoint Coverage in Test Mode

The table below lists the endpoints this page uses:

| API | Endpoint | Available in test mode |
| - | - | - |
| [Fetch Accounts](https://razorpay.com/docs/api/partners/accounts/fetch.md) | `GET /v1/accounts` and `GET /v1/accounts/{account_id}` | Available |

## 2. Before You Begin

Prepare the following before you run the scenarios:

* Create an account, as in scenario 1 on [Create an Account](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/create-account.md).
* Poll with a timeout in automated tests. Checks and reviews settle a few seconds after the call.

### Fetch an Account

The response below is test business Individual A part-way through, sent step by step. The PAN is verified, the Central KYC Records Registry (CKYC) code was requested and the bank check failed on the name. The category, the description, the statement name and the terms are still due.

```bash Curl theme={null}
curl -X GET https://api.razorpay.com/v1/accounts/acc_TcdGEzmfKQzEl1 \
-u rzp_test_partner_[CLIENT_ID]:[CLIENT_SECRET]
```

> [accordion] Fetch Response: HTTP 200
>
> ```json Response theme={null}
> {
>   "id": "acc_TcdGEzmfKQzEl1",
>   "country": "IN",
>   "statement_descriptor": null,
>   "is_mfa_enabled": false,
>   "user": {
>     "role": "owner",
>     "email": "test.owner@example.com",
>     "phone": "+919876543210",
>     "name": "Rzp Test QA Merchant",
>     "is_email_verified": true,
>     "is_phone_verified": true
>   },
>   "business_profile": {
>     "business_type": "individual",
>     "business_name": "Rzp Test QA Merchant",
>     "date_of_establishment": null,
>     "identity_numbers": {},
>     "documents": {},
>     "business_category": null,
>     "authorized_person": {
>       "name": "Rzp Test QA Merchant",
>       "identity_numbers": {
>         "individual_pan": {
>           "type": "individual_pan",
>           "value": "ABCPD1234A",
>           "verification": {
>             "status": "verified",
>             "error_code": null,
>             "error_description": null,
>             "verified_at": 1793164860,
>             "metadata": {},
>             "created_at": 1793164858
>           },
>           "metadata": {},
>           "is_skipped": false,
>           "created_at": 1793164858,
>           "updated_at": 1793164860
>         }
>       },
>       "documents": {},
>       "address": null,
>       "date_of_birth": null,
>       "additional_data": {},
>       "created_at": 1793164858,
>       "updated_at": 1793164860
>     },
>     "stakeholders": {},
>     "addresses": [],
>     "metadata": {}
>   },
>   "bank_accounts": {
>     "settlements_primary": {
>       "type": "settlements_primary",
>       "account_number": "2100000011",
>       "routing_code": "HDFC0123456",
>       "routing_code_type": "IFSC",
>       "supporting_document": null,
>       "verification": {
>         "status": "rejected",
>         "error_code": "bank_name_mismatch",
>         "error_description": "The account must be in the name of your business. Please use a different account.",
>         "verified_at": null,
>         "metadata": {},
>         "created_at": 1793164868
>       }
>     }
>   },
>   "products": {
>     "payment_gateway": {
>       "type": "payment_gateway",
>       "status": "in_progress",
>       "status_reason": null,
>       "created_at": 1793164800,
>       "updated_at": 1793164875,
>       "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"
>         },
>         {
>           "id": "req_4Z9yuuKZQXabvX",
>           "requirement_code": "bank_account",
>           "requirement_level": "mandatory",
>           "requirement_type": "composite",
>           "description": "The account must be in the name of your business. Please use a different account.",
>           "requirement_reason": "The name on the bank account does not match the business name.",
>           "fulfillment_criteria": "one_of",
>           "sub_requirements": [
>             {
>               "id": "req_VgRHb7QJNtMyj2",
>               "requirement_code": "settlement_bank_account",
>               "requirement_level": "conditional",
>               "requirement_type": "composite",
>               "description": "The bank account that receives settlements, in the name on your PAN.",
>               "fulfillment_criteria": "all_of",
>               "sub_requirements": [
>                 {
>                   "id": "req_4rY5OIDnOHtA2z",
>                   "requirement_code": "bank_account_number",
>                   "requirement_level": "mandatory",
>                   "requirement_type": "input",
>                   "description": "The account number.",
>                   "field_path": "bank_accounts.settlements_primary.account_number",
>                   "value_type": "text",
>                   "status": "created"
>                 },
>                 {
>                   "id": "req_mOTextgE1uJfFK",
>                   "requirement_code": "bank_routing_code",
>                   "requirement_level": "mandatory",
>                   "requirement_type": "input",
>                   "description": "The bank's IFSC.",
>                   "field_path": "bank_accounts.settlements_primary.routing_code",
>                   "value_type": "text",
>                   "status": "created"
>                 },
>                 {
>                   "id": "req_GNDdQcckulAU4g",
>                   "requirement_code": "bank_routing_code_type",
>                   "requirement_level": "mandatory",
>                   "requirement_type": "input",
>                   "description": "The kind of routing code.",
>                   "field_path": "bank_accounts.settlements_primary.routing_code_type",
>                   "value_type": "enum",
>                   "options": [
>                     {
>                       "label": "IFSC",
>                       "value": "IFSC"
>                     }
>                   ],
>                   "status": "created"
>                 }
>               ],
>               "status": "created"
>             },
>             {
>               "id": "req_8mFTjW5RY4heOw",
>               "requirement_code": "create_upi_link",
>               "requirement_level": "conditional",
>               "requirement_type": "action",
>               "description": "Or verify the account with a ₹1 UPI payment from it, refunded at once.",
>               "status": "created"
>             }
>           ],
>           "status": "created"
>         },
>         {
>           "id": "req_A0YsNfe8Ldgifp",
>           "requirement_code": "payment_channels",
>           "requirement_level": "optional",
>           "requirement_type": "composite",
>           "description": "Where you take payments: a website, an Android app or an iOS app. Any one is enough.",
>           "fulfillment_criteria": "one_of",
>           "sub_requirements": [
>             {
>               "id": "req_N0fo3L9LVzHpZQ",
>               "requirement_code": "website_url",
>               "requirement_level": "conditional",
>               "requirement_type": "input",
>               "description": "Your website's address.",
>               "field_path": "products.payment_gateway.payment_channels.website.primary",
>               "value_type": "text",
>               "status": "created"
>             },
>             {
>               "id": "req_LaWQWFJKitHAow",
>               "requirement_code": "app_android_url",
>               "requirement_level": "conditional",
>               "requirement_type": "input",
>               "description": "Your Android app's link.",
>               "field_path": "products.payment_gateway.payment_channels.app_android.url",
>               "value_type": "text",
>               "status": "created"
>             },
>             {
>               "id": "req_y4V5UfDpr3azhi",
>               "requirement_code": "app_ios_url",
>               "requirement_level": "conditional",
>               "requirement_type": "input",
>               "description": "Your iOS app's link.",
>               "field_path": "products.payment_gateway.payment_channels.app_ios.url",
>               "value_type": "text",
>               "status": "created"
>             }
>           ],
>           "status": "created"
>         },
>         {
>           "id": "req_7zAE2YmS5MDUhG",
>           "requirement_code": "business_category",
>           "requirement_level": "mandatory",
>           "requirement_type": "input",
>           "description": "Select your business category, and send its subcategory with it.",
>           "field_path": "business_profile.business_category.category",
>           "value_type": "enum",
>           "options": [
>             {
>               "label": "Ecommerce",
>               "value": "ecommerce"
>             },
>             {
>               "label": "Food and beverage",
>               "value": "food"
>             }
>           ],
>           "status": "created"
>         },
>         {
>           "id": "req_bNeyy5msL1HUKX",
>           "requirement_code": "business_description",
>           "requirement_level": "mandatory",
>           "requirement_type": "input",
>           "description": "What your business sells, in under 100 characters.",
>           "field_path": "business_profile.business_category.business_description",
>           "value_type": "text",
>           "status": "created"
>         },
>         {
>           "id": "req_yD8JfNtIoWXmu4",
>           "requirement_code": "statement_descriptor",
>           "requirement_level": "mandatory",
>           "requirement_type": "input",
>           "description": "The name shown on customers' receipts and statements.",
>           "field_path": "statement_descriptor.value",
>           "value_type": "text",
>           "status": "created"
>         },
>         {
>           "id": "req_0HAQYzBrDRNnEM",
>           "requirement_code": "accept_terms_of_service",
>           "requirement_level": "mandatory",
>           "requirement_type": "composite",
>           "description": "Show the sub-merchant Razorpay's terms of service and record their acceptance.",
>           "fulfillment_criteria": "all_of",
>           "sub_requirements": [
>             {
>               "id": "req_CTW6xxsQmygIDU",
>               "requirement_code": "acceptance_ip",
>               "requirement_level": "mandatory",
>               "requirement_type": "input",
>               "description": "The IP address the terms were accepted from.",
>               "field_path": "products.payment_gateway.terms_of_service_acceptance.ip",
>               "value_type": "text",
>               "status": "created"
>             },
>             {
>               "id": "req_gXg6igx2STKrZA",
>               "requirement_code": "acceptance_device_fingerprint_id",
>               "requirement_level": "mandatory",
>               "requirement_type": "input",
>               "description": "The device fingerprint of the device the terms were accepted on.",
>               "field_path": "products.payment_gateway.terms_of_service_acceptance.device_fingerprint_id",
>               "value_type": "text",
>               "status": "created"
>             }
>           ],
>           "status": "created"
>         }
>       ],
>       "terms_of_service_acceptance": null,
>       "payment_channels": null
>     }
>   },
>   "notes": {
>     "shop_id": "60291847"
>   },
>   "created_at": 1793164800,
>   "updated_at": 1793164875
> }
> ```

### List Accounts

List your accounts, newest first, filtered by email, phone, product or time. Use the list to continue a sub-merchant's account instead of creating another. Filtered by the user's email, it returns the account above.

```bash Curl theme={null}
curl -X GET "https://api.razorpay.com/v1/accounts?email=test.owner%40example.com&count=10" \
-u rzp_test_partner_[CLIENT_ID]:[CLIENT_SECRET]
```

> [accordion] List Response: HTTP 200
>
> ```json Response theme={null}
> {
>   "entity": "collection",
>   "count": 1,
>   "items": [
>     {
>       "id": "acc_TcdGEzmfKQzEl1",
>       "country": "IN",
>       "statement_descriptor": null,
>       "is_mfa_enabled": false,
>       "user": {
>         "role": "owner",
>         "email": "test.owner@example.com",
>         "phone": "+919876543210",
>         "name": "Rzp Test QA Merchant",
>         "is_email_verified": true,
>         "is_phone_verified": true
>       },
>       "business_profile": {
>         "business_type": "individual",
>         "business_name": "Rzp Test QA Merchant",
>         "date_of_establishment": null,
>         "identity_numbers": {},
>         "documents": {},
>         "business_category": null,
>         "authorized_person": {
>           "name": "Rzp Test QA Merchant",
>           "identity_numbers": {
>             "individual_pan": {
>               "type": "individual_pan",
>               "value": "ABCPD1234A",
>               "verification": {
>                 "status": "verified",
>                 "error_code": null,
>                 "error_description": null,
>                 "verified_at": 1793164860,
>                 "metadata": {},
>                 "created_at": 1793164858
>               },
>               "metadata": {},
>               "is_skipped": false,
>               "created_at": 1793164858,
>               "updated_at": 1793164860
>             }
>           },
>           "documents": {},
>           "address": null,
>           "date_of_birth": null,
>           "additional_data": {},
>           "created_at": 1793164858,
>           "updated_at": 1793164860
>         },
>         "stakeholders": {},
>         "addresses": [],
>         "metadata": {}
>       },
>       "bank_accounts": {
>         "settlements_primary": {
>           "type": "settlements_primary",
>           "account_number": "2100000011",
>           "routing_code": "HDFC0123456",
>           "routing_code_type": "IFSC",
>           "supporting_document": null,
>           "verification": {
>             "status": "rejected",
>             "error_code": "bank_name_mismatch",
>             "error_description": "The account must be in the name of your business. Please use a different account.",
>             "verified_at": null,
>             "metadata": {},
>             "created_at": 1793164868
>           }
>         }
>       },
>       "products": {
>         "payment_gateway": {
>           "type": "payment_gateway",
>           "status": "in_progress",
>           "status_reason": null,
>           "created_at": 1793164800,
>           "updated_at": 1793164875,
>           "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"
>             },
>             {
>               "id": "req_4Z9yuuKZQXabvX",
>               "requirement_code": "bank_account",
>               "requirement_level": "mandatory",
>               "requirement_type": "composite",
>               "description": "The account must be in the name of your business. Please use a different account.",
>               "requirement_reason": "The name on the bank account does not match the business name.",
>               "fulfillment_criteria": "one_of",
>               "sub_requirements": [
>                 {
>                   "id": "req_VgRHb7QJNtMyj2",
>                   "requirement_code": "settlement_bank_account",
>                   "requirement_level": "conditional",
>                   "requirement_type": "composite",
>                   "description": "The bank account that receives settlements, in the name on your PAN.",
>                   "fulfillment_criteria": "all_of",
>                   "sub_requirements": [
>                     {
>                       "id": "req_4rY5OIDnOHtA2z",
>                       "requirement_code": "bank_account_number",
>                       "requirement_level": "mandatory",
>                       "requirement_type": "input",
>                       "description": "The account number.",
>                       "field_path": "bank_accounts.settlements_primary.account_number",
>                       "value_type": "text",
>                       "status": "created"
>                     },
>                     {
>                       "id": "req_mOTextgE1uJfFK",
>                       "requirement_code": "bank_routing_code",
>                       "requirement_level": "mandatory",
>                       "requirement_type": "input",
>                       "description": "The bank's IFSC.",
>                       "field_path": "bank_accounts.settlements_primary.routing_code",
>                       "value_type": "text",
>                       "status": "created"
>                     },
>                     {
>                       "id": "req_GNDdQcckulAU4g",
>                       "requirement_code": "bank_routing_code_type",
>                       "requirement_level": "mandatory",
>                       "requirement_type": "input",
>                       "description": "The kind of routing code.",
>                       "field_path": "bank_accounts.settlements_primary.routing_code_type",
>                       "value_type": "enum",
>                       "options": [
>                         {
>                           "label": "IFSC",
>                           "value": "IFSC"
>                         }
>                       ],
>                       "status": "created"
>                     }
>                   ],
>                   "status": "created"
>                 },
>                 {
>                   "id": "req_8mFTjW5RY4heOw",
>                   "requirement_code": "create_upi_link",
>                   "requirement_level": "conditional",
>                   "requirement_type": "action",
>                   "description": "Or verify the account with a ₹1 UPI payment from it, refunded at once.",
>                   "status": "created"
>                 }
>               ],
>               "status": "created"
>             },
>             {
>               "id": "req_A0YsNfe8Ldgifp",
>               "requirement_code": "payment_channels",
>               "requirement_level": "optional",
>               "requirement_type": "composite",
>               "description": "Where you take payments: a website, an Android app or an iOS app. Any one is enough.",
>               "fulfillment_criteria": "one_of",
>               "sub_requirements": [
>                 {
>                   "id": "req_N0fo3L9LVzHpZQ",
>                   "requirement_code": "website_url",
>                   "requirement_level": "conditional",
>                   "requirement_type": "input",
>                   "description": "Your website's address.",
>                   "field_path": "products.payment_gateway.payment_channels.website.primary",
>                   "value_type": "text",
>                   "status": "created"
>                 },
>                 {
>                   "id": "req_LaWQWFJKitHAow",
>                   "requirement_code": "app_android_url",
>                   "requirement_level": "conditional",
>                   "requirement_type": "input",
>                   "description": "Your Android app's link.",
>                   "field_path": "products.payment_gateway.payment_channels.app_android.url",
>                   "value_type": "text",
>                   "status": "created"
>                 },
>                 {
>                   "id": "req_y4V5UfDpr3azhi",
>                   "requirement_code": "app_ios_url",
>                   "requirement_level": "conditional",
>                   "requirement_type": "input",
>                   "description": "Your iOS app's link.",
>                   "field_path": "products.payment_gateway.payment_channels.app_ios.url",
>                   "value_type": "text",
>                   "status": "created"
>                 }
>               ],
>               "status": "created"
>             },
>             {
>               "id": "req_7zAE2YmS5MDUhG",
>               "requirement_code": "business_category",
>               "requirement_level": "mandatory",
>               "requirement_type": "input",
>               "description": "Select your business category, and send its subcategory with it.",
>               "field_path": "business_profile.business_category.category",
>               "value_type": "enum",
>               "options": [
>                 {
>                   "label": "Ecommerce",
>                   "value": "ecommerce"
>                 },
>                 {
>                   "label": "Food and beverage",
>                   "value": "food"
>                 }
>               ],
>               "status": "created"
>             },
>             {
>               "id": "req_bNeyy5msL1HUKX",
>               "requirement_code": "business_description",
>               "requirement_level": "mandatory",
>               "requirement_type": "input",
>               "description": "What your business sells, in under 100 characters.",
>               "field_path": "business_profile.business_category.business_description",
>               "value_type": "text",
>               "status": "created"
>             },
>             {
>               "id": "req_yD8JfNtIoWXmu4",
>               "requirement_code": "statement_descriptor",
>               "requirement_level": "mandatory",
>               "requirement_type": "input",
>               "description": "The name shown on customers' receipts and statements.",
>               "field_path": "statement_descriptor.value",
>               "value_type": "text",
>               "status": "created"
>             },
>             {
>               "id": "req_0HAQYzBrDRNnEM",
>               "requirement_code": "accept_terms_of_service",
>               "requirement_level": "mandatory",
>               "requirement_type": "composite",
>               "description": "Show the sub-merchant Razorpay's terms of service and record their acceptance.",
>               "fulfillment_criteria": "all_of",
>               "sub_requirements": [
>                 {
>                   "id": "req_CTW6xxsQmygIDU",
>                   "requirement_code": "acceptance_ip",
>                   "requirement_level": "mandatory",
>                   "requirement_type": "input",
>                   "description": "The IP address the terms were accepted from.",
>                   "field_path": "products.payment_gateway.terms_of_service_acceptance.ip",
>                   "value_type": "text",
>                   "status": "created"
>                 },
>                 {
>                   "id": "req_gXg6igx2STKrZA",
>                   "requirement_code": "acceptance_device_fingerprint_id",
>                   "requirement_level": "mandatory",
>                   "requirement_type": "input",
>                   "description": "The device fingerprint of the device the terms were accepted on.",
>                   "field_path": "products.payment_gateway.terms_of_service_acceptance.device_fingerprint_id",
>                   "value_type": "text",
>                   "status": "created"
>                 }
>               ],
>               "status": "created"
>             }
>           ],
>           "terms_of_service_acceptance": null,
>           "payment_channels": null
>         }
>       },
>       "notes": {
>         "shop_id": "60291847"
>       },
>       "created_at": 1793164800,
>       "updated_at": 1793164875
>     }
>   ]
> }
> ```

Know more about the [response parameters](https://razorpay.com/docs/api/partners/accounts/fetch.md).

## 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 9 scenarios. 1 is live and 8 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>Fetch the account Live</td><td>An account from scenario 1 on [Create an Account](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/create-account.md)</td><td>Call `GET /v1/accounts/{account_id}`. Confirm it matches the account-creation response.</td></tr>
    <tr><td>2</td><td>Read requirements Coming soon</td><td>The account in the [fetch response](#fetch-an-account)</td><td>For each item, read `requirement_code`, `requirement_type` and `requirement_level`. Read an input's `field_path`, `value_type` and `options`. Read a composite's `fulfillment_criteria` and `sub_requirements`. Render 1 form field per input and 1 button per action. Render a composite's sub-requirements by its criteria: 1 choice for `one_of`, at least one for `any_of` and every one for `all_of`.</td></tr>
    <tr><td>3</td><td>A check that settles later Coming soon</td><td>Website `https://curlec.com`</td><td>Send it, as in scenario 9 on [Update an Account](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/update-account.md). Fetch and confirm `in_progress`. Fetch after 5 sec and confirm `verified`. Confirm Razorpay sends `account.requirements.updated`.</td></tr>
    <tr><td>4</td><td>Follow the product after submission Coming soon</td><td>Settlement account `000000000002`</td><td>Submit, as on [Terms and Submission](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/terms-and-submission.md). Confirm the response is `under_review`. Poll every 2 sec, up to 60 sec. Confirm `rejected` after about 5 sec.</td></tr>
    <tr><td>5</td><td>Continue an existing account Coming soon</td><td>The user's email</td><td>Call `GET /v1/accounts?email=test.owner@example.com`. Confirm the account. Continue it instead of creating another.</td></tr>
    <tr><td>6</td><td>Filter errors Coming soon</td><td>`count=0`, `count=101`, `from` after `to` or `product=loans`</td><td>Confirm `400 invalid_format`, `invalid_request` and `invalid_option`.</td></tr>
    <tr><td>7</td><td>Unknown account Coming soon</td><td>`acc_DoesNotExist01`</td><td>Confirm `404 not_found` with `field: account_id`.</td></tr>
    <tr><td>8</td><td>Identifiers come back in full Coming soon</td><td>An account with a verified PAN and bank account</td><td>Confirm `individual_pan.value` is `ABCPD1234A` and the API returns the full account number. Confirm no holder name comes back.</td></tr>
    <tr><td>9</td><td>Requirements change with the checks Coming soon</td><td>PAN `ABCPD7891B` (no CKYC record)</td><td>Send the PAN. Confirm `ckyc_fetch` is not due, unlike for `ABCPD1234A`. Confirm `proof_of_address_for_individual` is due.</td></tr>
  </tbody>
</table>

### 3.2 Scenario Details

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

> [accordion] 2. Read Requirements
>
> **Before you begin:** Use test business Individual A with bank account `2100000011`, as in scenario 7 on [Update an Account](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/update-account.md).
>
> **How to test:** Fetch the account, as in the [fetch request](#fetch-an-account).
>
> **Expected result:** Each requirement is 1 thing to do. `requirement_type` says whether to send a value (`input`), run an action (`action`) or answer a composite. Answer a composite's `sub_requirements` as its `fulfillment_criteria` says. The response also shows the following:
>
> * The bank account's `verification` is `rejected` with `error_code: bank_name_mismatch`.
> * `bank_account` is due again as a `one_of`: the account (`settlement_bank_account`) or the ₹1 UPI link (`create_upi_link`). Its `requirement_reason` says the name on the account does not match.
> * `settlement_bank_account` is an `all_of` of the account number, the Indian Financial System Code (IFSC) and the routing code type.
> * `ckyc_otp` and `ckyc_request_id` are due, because `send_ckyc_otp` ran.
> * The optional `payment_channels` composite follows, as a `one_of` of a website, an Android app or an iOS app.
> * `business_category`, `business_description` and `statement_descriptor` follow. `statement_descriptor` has `value_type: text` and `field_path: statement_descriptor.value`.
> * `accept_terms_of_service` comes last, as an `all_of` of the `ip` and the `device_fingerprint_id`.
>
> **Your integration should:** Show the sub-requirements of a `one_of` composite as 1 choice. Show `description`. Branch on the element's `verification.error_code`.

> [accordion] 4. Follow the Product After Submission
>
> **Before you begin:** Get an account ready to submit, with settlement account `000000000002`.
>
> **How to test:**
>
> 1. Submit, then fetch straight away.
> 2. Poll `GET /v1/accounts/{account_id}` every 2 sec, up to 60 sec.
>
> **Expected result:** `under_review` first. About 5 sec later, `rejected`. Other test values reach `activated`, `edd_pending` or `needs_clarification` the same way. See [Terms and Submission](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/terms-and-submission.md).
>
> **Webhooks:** `account.product.under_review`, then `account.product.rejected`.
>
> **Your integration should:** Poll with a timeout in tests. In production, act on the webhook and fetch only when it is late.
>
> **Live mode differs:** A review can take hours or days. `under_review` can stay until a reviewer acts.

> [accordion] 8. Identifiers Come Back in Full
>
> **Before you begin:** Use an account with a verified PAN and bank account.
>
> **Expected result:** The PAN and the account number come back in full, as in the fetch response. The CKYC record shows `value: null`, with `ckyc_mobile` in its `metadata`. The holder's name from the bank is not returned. Addresses from registries are not returned. The PAN's name comes back as `business_name`.
>
> **Your integration should:** Show these values only to the sub-merchant. Delete what you collected once Razorpay has it, as your agreement sets. Fetch the account to show them again.

### 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 these endpoints return:

| Trigger | HTTP | `error.reason` | `error.field` |
| - | - | - | - |
| An account ID that is not yours, or does not exist | 404 | `not_found` | `account_id` |
| `email` not an email, `count` outside 1 to 100 or `skip` negative | 400 | `invalid_format` | The parameter |
| `from` after `to` | 400 | `invalid_request` | `from` |
| `product=loans` | 400 | `invalid_option` | `product` |

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

**Status and requirements**

The table below lists the gaps in reading status and requirements:

| Gap | What goes wrong in production | What to do | Test with |
| - | - | - | - |
| Asserting straight after a call | Automated tests fail because a check or review has not settled. | Poll with a timeout. | #3, #4 |
| Hard-coded requirements | A sub-merchant without a CKYC record is asked for a code that never arrives. | Read `requirements` after every response. | #9 |
| Relying only on webhooks | A missed webhook leaves the account looking stuck. | Fetch when a status has not changed in the time you expect. | #4 |

## 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 fetching and listing:

| Topic | What to know | On this page | Test it | Read more |
| - | - | - | - | - |
| Polling | Back off between fetches. Prefer webhooks, and fetch only to catch up. | Poll every 2 sec, up to 60 sec, in tests. | #4 | [Webhooks](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/webhooks.md) |
| Continuing an account | List by email or phone before creating, so a returning sub-merchant continues their account. | Use the [list request](#list-accounts). | #5 | Not applicable |

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