Available in🇮🇳 India
Create an Account always makes a new account, so a new sub-merchant takes one call. One owner can have several accounts on your platform, such as one per store. An earlier attempt may also have stopped partway.
Listing is optional. If you store the account IDs you create, fetch or update an account by its ID directly. To let the sub-merchant continue an account started earlier, find it first.
1.1 Find an Existing Account
Call Fetch Accounts with the owner’s email or phone. The list returns accounts mapped to your app, newest first. It includes accounts that are not activated yet and ones only partly filled in. Accounts on other platforms, or with Razorpay directly, never appear. An email or phone with no account returnscount: 0, not an error.
The sub-merchant then chooses one of these:
- Continue an existing account: Use its
id, fetch the account and update it against its requirements. - Start a new account: Create one.
GET /v1/accounts
Query Parameters
Query Parameters
Every query parameter is an optional filter. Send the owner’s
email or phone to find their accounts.email optional
: string Return only the accounts with this user email. For example, gaurav.kumar@example.com.phone optional
: string Return only the accounts with this user phone, +91 followed by 10 digits. For example, +919611752201.product optional
: string Return only accounts holding this product. Possible values: payment_gateway, pos, billing, business_banking, payroll, agent_studio and optimizer.from optional
: integer Return accounts created at or after this time, as a Unix timestamp in seconds.to optional
: integer Return accounts created at or before this time, as a Unix timestamp in seconds.count optional
: integer Number of accounts to return, from 1 to 100. Defaults to 10.skip optional
: integer Number of accounts to skip. Defaults to 0.1.2 Create an Account
Create the account with itscountry and its user’s email, phone and name. Name the product to onboard to in products, keyed by type.
Razorpay verifies the email and phone with a One-Time Password (OTP). Each unverified contact shows up straight away as a send_phone_otp or send_email_otp action requirement, next to business_type. Running the action returns the phone_otp or email_otp requirement, and you send the code back in an update. Know more about verification actions.
POST /v1/accounts
country and user are mandatory in this call. The KYC fields are optional here. Each one the product needs is due before submission, and the product’s requirements list them. A nested field marked mandatory applies only when you send its parent object.
Request Parameters
Request Parameters
country mandatory
: string The country of the business, as an ISO 3166-1 alpha-2 code. Possible value: IN.user mandatory
: object The person who creates and operates the account and signs in to the Razorpay Dashboard. One user can own several accounts.user.email mandatory
: string The user’s email address. For example, gaurav.kumar@example.com.user.phone mandatory
: string The user’s phone number, +91 followed by 10 digits. For example, +919611752201.user.name mandatory
: string The name of the person completing the onboarding. For example, Gaurav Kumar.is_mfa_enabled optional
: boolean Whether the owner must complete two-factor authentication on the Razorpay Dashboard.products optional
: object The products to onboard to, keyed by type. For example, "payment_gateway": { "payment_channels": {} }.notes optional
: object Key-value pairs to store your own references, such as a shop ID.1.3 Create With Everything (One-Shot)
When you already have the details, send them all in the same call. This covers the business profile with its addresses, documents, authorised person and stakeholders. It also covers the bank account, the statement descriptor and the product’s payment channels. Shape them all like the account itself. Razorpay applies the values in the order onboarding needs and verifies each one. The response comes back within 5 sec. Razorpay handles the values as follows:- Wrong format: A value in the wrong format fails the whole request with
400. Razorpay creates nothing. - Failed verification: Razorpay saves a well-formed value that fails verification, such as a bank name mismatch. Its
verificationshows the failure, and its requirement stays due. Fix it with an update. - KYC record found: A verified PAN with a Central KYC Records Registry (CKYC) record makes the
ckyc_fetchcomposite requirement due. This applies to an individual, a proprietorship or the authorised person of a private limited, public limited or Section 8 company. Runsend_ckyc_otpor skip CKYC. Know more about fetching KYC from CKYC. - Documents as links: Send each document as a pre-signed https link in
url, such as an S3 pre-signed URL. Razorpay downloads it once and keeps its own copy. Links to private or internal addresses return400 invalid_document_url. After Create, upload a document and send itsidinstead. Sending a link is coming soon. Until then, upload the file and send itsidwith Update an Account. - Checks still running: A check that has not finished when the response returns shows
in_progress. Its outcome follows on the account and in theaccount.requirements.updatedwebhook. - No submission: Create never submits the product. The sub-merchant accepts the terms once the account exists.
POST /v1/accounts
requirements holds only what Create could not carry: ckyc_fetch and accept_terms_of_service.
The business-model answer in this example covers the only question for the fashion_and_lifestyle subcategory, bmc_question_2. If you already know the questions for a subcategory, answer them in Create. Know more about business model questions. Any question left unanswered comes back as an input of the business_model_clarifications composite requirement. The updates that follow look the same as in a step-by-step integration.
Request Parameters
Request Parameters
The top-level fields below are optional in this call. Each is due before submission when the product’s
requirements list it. A nested field marked mandatory applies only when you send its parent object. The country and user fields are as in 1.2 Create an Account.statement_descriptor optional
: object The name customers see on their bank statements and receipts.statement_descriptor.value mandatory
: string The brand name shown on customer statements. Up to 255 characters. For example, Acme Corp.business_profile optional
: object The business’s KYC details.business_profile.business_type mandatory
: string The type of business. For example, individual or private_limited.business_profile.authorized_person optional
: object The authorised person.business_profile.authorized_person.identity_numbers mandatory
: object The authorised person’s identity numbers, keyed by type. For example, their PAN at individual_pan.business_profile.authorized_person.documents mandatory
: object The authorised person’s documents, keyed by type. For example, aadhaar_front sent as a url.business_profile.stakeholders optional
: object The people who own a share of the business, keyed by stakeholder ID. Each stakeholder takes the same fields as the authorised person, with percentage_ownership.business_profile.stakeholders.<stakeholder_id>.percentage_ownership mandatory
: number The stakeholder’s share of the business, as a decimal from 0 to 100. For example, 25.5.business_profile.addresses optional
: array The registered_address and the operational_address, each an object with its type. Each takes type, line1, line2, city, state, postal_code and country. All but line2 are mandatory in each address you send.business_profile.business_category optional
: object How the business is classified, with the mcc, the business_description and the business_model_clarifications keyed by question ID.business_profile.business_category.category mandatory
: string The business category. For example, ecommerce.business_profile.business_category.subcategory mandatory
: string The subcategory of the category. For example, fashion_and_lifestyle. Know more about business categories and subcategories.bank_accounts optional
: object The settlement bank account at settlements_primary.bank_accounts.settlements_primary.account_number mandatory
: string The settlement account number, 5 to 35 digits. For example, 001234567890.bank_accounts.settlements_primary.routing_code mandatory
: string The bank’s Indian Financial System Code (IFSC). For example, ICIC0000009.bank_accounts.settlements_primary.routing_code_type mandatory
: string The kind of routing code. Possible value: IFSC.products.payment_gateway.payment_channels mandatory
: object Where the business takes payments: website, app_android or app_ios.