Skip to main content

Documentation Index

Fetch the complete documentation index at: https://www.cashfree.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

Integrate Cashfree’s merchant onboarding APIs and embedded link to collect KYC information and verify merchants directly within your platform. Businesses that onboard through your platform are registered as merchants in Cashfree’s system and linked to your partner account.

​
Prerequisites

Before integrating merchant onboarding with Cashfree, ensure the following:
  • Register as a partner: Register your platform as a partner with Cashfree. Contact Cashfree support to initiate the partnership process.
  • Obtain partner API key: Log in to the Partner Dashboard and navigate to Developers to generate your partner API key. You will use this key to authenticate all API requests.
  • Plan your data structure: Determine which KYC fields your platform will collect upfront and which will be completed via the embedded link.
  • Prepare your hosting environment: Ensure your platform can embed iframes or webviews to display the Cashfree onboarding link.
  • Configure webhook URL: Provide a valid webhook URL where Cashfree will send merchant status notifications.

​
Integration flow

Use the following steps to complete embedded merchant onboarding for your platform:
  1. Create a merchant profile in Cashfree
  2. Update merchant details as information becomes available
  3. Upload KYC documents for verification
  4. Generate and display the embeddable onboarding link
  5. Monitor merchant onboarding status through APIs
  6. Subscribe to onboarding webhooks for status updates

​
Step 1: Create a merchant

Create a merchant record in Cashfree using the Create Merchant API with the merchant’s core information. Store the merchant_id for use in subsequent API calls.

​
Step 2: Update merchant details

Use the Update Merchant API to update a sub-merchant account’s profile. You can update basic merchant details before the account is activated. Once active, most profile fields are locked and cannot be modified via API.

​
Step 3: Upload KYC documents

Upload KYC documents via the Upload KYC Documents API as they become available. The document_type field accepts the following values;
  • PAN
  • AADHAAR
  • GSTIN
  • CIN
  • BANK_STATEMENT
Generate an embeddable onboarding link for merchants to complete remaining KYC and Aadhaar verification using the Create Embeddable Onboarding Link API.
The onboarding_link expires after 1 hour. Embed it in an iframe or webview do not expose it to end users as a direct URL.
After the merchant completes onboarding, Cashfree redirects them to your configured return_url.

​
Step 5: Monitor merchant status

Query merchant status using the Get Merchant Status API: Use the onboarding_status field to track merchant onboarding progress:
  • CREATED: Onboarding started but not completed.
  • ACTIVE: Merchant can process payments.
  • REJECTED: Merchant onboarding rejected.
  • SUSPENDED: Merchant account suspended.

​
Step 6: Subscribe to merchant onboarding webhooks

Subscribe to merchant onboarding webhooks using the Merchant Onboarding Webhooks API to receive real-time notifications of status changes. Configure your webhook URL in the Partner Dashboard under Developers > Webhooks. The webhook event types include the following:
  • merchant.onboarding.completed: Merchant onboarding completed successfully.
  • merchant.onboarding.rejected: Merchant onboarding was rejected by Cashfree.
  • merchant.onboarding.status_changed: Merchant onboarding status has changed.
Verify webhook signatures using your partner API key before processing events. This prevents unauthorised requests from external sources.

​
Identify business type using PAN

The fourth letter of the Permanent Account Number (PAN) identifies the entity type of the account holder. For example, for the PAN: ABCPR1234A, the fourth letter is P, which identifies the account holder as an individual or proprietorship. PAN structure reference for ABCPR1234A: first three letters as series, fourth letter entity type with legend, fifth letter name or surname initial, next four digits sequential, tenth character check digit Use the following table to determine the correct business_type value for the merchant:
Fourth letter of the PANbusiness_type
PIndividual, Proprietorship
CPrivate Limited, Public Limited
FLLP, Partnership
TTrust
HHindu Undivided Family (HUF)
AAssociation of Persons (AOP)
BSociety
LLocal Authority
JArtificial Juridical Person
GGovernment

​
Test in sandbox

Use the following test credentials to test the onboarding flow end-to-end in the sandbox environment.
Use the following test credentials to validate the individual or proprietor onboarding flow in the sandbox environment:
FieldTest value
Business PANABCPV1234D
Business Legal NameJohn Doe
Business TypeIndividual
Business ModelB2C
Business CategoryEcommerce/Retail
Business SubcategoryOther goods
MCC5199
Non-GST DeclarationMy annual turnover is less than GST prescribed limit
Business AddressTrial Address
City/PIN/StateMumbai / 400067 / Maharashtra
Aadhaar Number655675523712
Aadhaar OTP111000
Bank Account026291800001191
Bank IFSCYESB0000262
Use the following test credentials to validate the private or public limited onboarding flow in the sandbox environment:
FieldTest value
Business PANABCCD8000T
Business Legal NameJohn Doe Industries
Owner PANABCPV1234D
Owner Name as per PANJohn Doe
Business TypePrivate Limited
Business DescriptionI want to use payment gateway to collect payments…
MCC5199
CountryIndia
Business Non-GST DeclarationMy business category is exempted from GST
CINU72900KA2015PTC082989
GSTIN29AAICP2912R1ZR
Business AddressTrial Address
City/PIN/StateMumbai / 400067 / Maharashtra
Aadhaar Number655675523712
Aadhaar OTP111000
Bank Account026291800001191
Bank IFSCYESB0000262

​
Production deployment

Before deploying to production, update your API endpoint and credentials:
EnvironmentAPI endpoint
Sandboxhttps://api-sandbox.cashfree.com
Productionhttps://api.cashfree.com