# API Best Practices
Source: https://www.cashfree.com/docs/api-reference/api-best-practices

Recommended practices for building secure, reliable, and performant integrations with Cashfree APIs.

Building a reliable Cashfree API integration requires more than correct API calls. These practices cover security, error handling, performance, and testing the areas most likely to cause issues if overlooked.

## Security

Apply the following practices to protect your API credentials and ensure only legitimate requests reach your integration.

### Verify webhook signatures

Always verify the signature of every incoming webhook payload before processing it. Skipping this step exposes your integration to spoofed or tampered requests.

<Warning>
  Never process a webhook payload without first validating its signature. For step-by-step instructions and code examples, see the webhook signature verification page for your product.
</Warning>

### Secure your API keys

Exposed API keys (`x-client-id` and `x-client-secret`) can result in unauthorised transactions and data breaches. Apply the following controls to protect your keys.

* Never commit API keys to version control.
* Never expose API keys in client-side or browser-facing code.
* Store keys in environment variables or a dedicated secrets manager.
* Restrict key access to only the services and environments that require it.
* Rotate keys immediately if you suspect they have been compromised.

### Avoid logging sensitive data

Do not log raw API request or response bodies that contain sensitive fields such as card numbers, CVVs, bank account details, or authentication tokens. Logging this data creates a PCI DSS compliance risk and increases the potential impact of a security breach.

<Tip>
  Log only the fields required for debugging, such as order IDs, status codes, and timestamps.
</Tip>

## Reliability

Follow these practices to ensure your integration handles failures gracefully and maintains consistent behaviour under load.

### Use idempotency keys

Include a unique idempotency key in every mutating request (for example, payment creation or refund initiation) using the `x-idempotency-key` request header. If a request fails or times out, retrying with the same key prevents duplicate transactions.

```http theme={"dark"}
x-idempotency-key: <uuid>
```

Use a UUID as the key value. Generate a new UUID for each logical operation, and reuse the same key only when retrying that specific request.

### Subscribe to webhooks instead of polling

Subscribe to webhook events instead of polling the API for status updates. Polling consumes rate limit quota and introduces unnecessary latency into your integration.

For setup instructions, see [webhooks](/docs/payments/online/webhooks/overview) for further detailed information.

### Avoid concurrent requests

Do not send multiple simultaneous requests from the same account. Concurrent requests increase the likelihood of rate limit errors and can degrade integration performance.

<Note>
  If your use case requires high request volume, use a queue or a similar mechanism to process requests sequentially and manage throughput.
</Note>

### Include a request ID

Add a unique identifier to each request using the `x-request-id` header. This makes it easier to trace requests in logs, correlate errors, and collaborate with Cashfree support during troubleshooting.

## Performance

Apply the following practices to reduce latency, manage throughput, and make efficient use of your API quota.

### Handle rate limit errors

When your integration receives a rate limit error, pause all outgoing requests and apply the following logic before retrying.

* If the `x-ratelimit-retry` response header is present, wait the number of seconds it specifies before retrying.
* If the `x-ratelimit-remaining` header value is `0`, do not send another request until the time indicated by `x-ratelimit-reset` has passed.

When applying exponential backoff, start with a one-second delay and double the wait time with each subsequent attempt (2s, 4s, 8s). Add a small random jitter to each interval to prevent multiple clients from retrying simultaneously. Limit retries to three to five attempts.

<Note>
  To increase your rate limit or burst limit, raise a request through the [Merchant Dashboard](https://merchant.cashfree.com/merchants/pg/developers/rate-limits). For detailed steps, see the rate limits page for your product.
</Note>

### Optimise connections with keep-alive

Use HTTP keep-alive to reuse a single connection across multiple API requests. This reduces per-request latency and lowers resource usage on both client and server. Set the following header in all API requests.

```http theme={"dark"}
Connection: keep-alive
```

## Integration

Follow these practices to ensure your integration stays current, reduces manual effort, and aligns with Cashfree's supported conventions.

### Specify the API version

Always use the latest API version to access current features, performance improvements, and security updates. Cashfree APIs use a date-based versioning scheme. Specify the version in the `x-api-version` request header using the format `YYYY-MM-DD`.

```http theme={"dark"}
x-api-version: 2025-01-01
```

If you are on an older version, upgrade to the latest to benefit from new capabilities and bug fixes.

### Use Cashfree SDKs

Cashfree provides official SDKs in popular programming languages to reduce integration effort. The SDKs handle authentication, request and response formatting, response parsing, and error handling.

<Card title="Cashfree SDKs" icon="code" href="/docs/tools-ai/sdk">
  Access pre-built libraries for your preferred language and start integrating faster.
</Card>

## Testing

Complete all integration testing in the Cashfree sandbox environment before deploying to production. The sandbox replicates production behaviour without processing real transactions.

To retrieve your sandbox API keys, follow these steps.

1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and sign in with your credentials.
2. Navigate to your product under **Developers** > **API Keys**.
3. Copy the test mode keys and use them in your sandbox environment.

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/payments/overview">Payments Overview</a></li>
    <li><a href="/docs/api-reference/payments/errors">Payments API errors</a></li>
    <li><a href="/docs/payments/online/webhooks/webhook-indempotency">Webhook Idempotency</a></li>
    <li><a href="/docs/api-reference/integration-troubleshooting/payments-ts">Payments API troubleshooting</a></li>
  </ul>
</div>


# Authentication
Source: https://www.cashfree.com/docs/api-reference/authentication

Learn how to authenticate Cashfree APIs using API keys, generate sandbox and production credentials, and pass headers correctly across payments and payouts.

Almost all Cashfree APIs require authentication. There are some exceptions like the `/order/sessions` Payments API.

<Warning>
  Each Cashfree product requires its own unique client ID and client secret. For
  example, if you are using both the Payments API and the Payouts API, you must
  generate separate credentials for each. This means one set of keys for the
  Payments API and a different set of keys for the Payouts API.
</Warning>

## Merchant authentication

* The standard authentication for merchants uses two specific headers `x-client-id` and `x-client-secret`. Pass your `appId` and `secretKey` in these fields.

* Ensure that you place your secret key securely and that no one else can access it.

* Also never call any API which requires authentication from the client as that would require you to expose the secret key to the client.

Below is a curl request which shows how to send these headers in the API call.

```bash theme={"dark"}
curl --request {REQUEST-TYPE} \
  --url https://sandbox.cashfree.com/pg/{resource} \
  --header 'Content-Type: application/json' \
  --header 'x-api-version: 2025-01-01' \
  --header 'x-client-id: <YOUR_APP_ID>' \
  --header 'x-client-secret: <YOUR_SECRET_KEY>'
  ...
  ...
```

## Generate API keys

Each Cashfree product requires its own unique client ID and client secret. For example, if you are using both the Payments API and the Payouts API, you must generate separate credentials for each. This means one set of keys for the Payments API and a different set of keys for the Payouts API.

Follow the below steps to generate your API key for Payment Gateway.

1. Go to **Payment Gateway Dashboard** > and click on **Developers** icon in the right navigation or click **Developers** on the top right of the [Merchant Dashboard](https://merchant.cashfree.com/merchants).
2. Click **API Keys** under Payment Gateway.\
   In the test environment, Cashfree auto-generates your API keys. In the production environment, click **Generate API Keys** and complete the 2FA authentication to generate the keys. Cashfree uses separate credentials for each environment, so ensure you use the correct set for the environment you are working in.
3. Once generated, the dashboard shows the API keys in a masked format. To view the full set of keys, click the icon and select **View API Key**. In the production environment, you would be required to do 2FA authentication to view the keys. You must securely store your api keys at all times.

You can also navigate directly to your [Production API credentials](https://merchant.cashfree.com/merchants/pg/developers/api-keys?env=prod) in the Merchant Dashboard.

<img alt="View API Keys" />

<Note>
  You can only generate a single API key pair at a time. Once you generate the
  keys from the dashboard, keep them secure. If it is lost, you need to
  re-generate them from the dashboard.
</Note>

## Partner authentication

If you are building a platform and want to use the Payment APIs on behalf of your customers you can do so using by leveraging authentication for platforms. You should use the **x-partner-apikey** and **x-partner-merchantid** headers instead of the **x-client-id** and **x-client-secret** headers.

* **x-partner-apikey**: This is the common API Key generated and unique for each Partner
* **x-partner-merchantid**: This is the unique merchant ID for each merchant associated with the Partner.\
  To view the merchant ID for each merchant, login to your Cashfree Partner Dashboard with your partner login credentials > go to the **Merchants** section, and copy the **Merchant ID** of the respective merchant.

Click [here](/docs/partners/embedded/integration/gateway-integration#partner-api-keys) to know how to generate partner authentication keys.


# Troubleshooting
Source: https://www.cashfree.com/docs/api-reference/integration-troubleshooting/overview-ts

Resolve common Cashfree integration issues across payments, payouts, webhooks, SDKs, and Secure ID with quick fixes, error references, and debug steps.

Integration errors can occur due to incorrect configurations, missing features, or environment mismatches. This guide outlines the most common issues across Cashfree products and provides actionable steps to help you resolve them quickly and ensure a smooth integration experience.

<CardGroup>
  <Card title="Payments" href="/docs/api-reference/integration-troubleshooting/payments-ts">
    Resolve common integration issues related to accepting online and in-person payments.
  </Card>

  <Card title="Payouts" href="/docs/api-reference/integration-troubleshooting/payouts-ts">
    Troubleshoot payout failures, IP whitelisting errors, and other disbursal-related issues.
  </Card>

  <Card title="Secure ID" href="/docs/api-reference/integration-troubleshooting/secureid-ts">
    Diagnose and fix issues related to identity verification and document validation flows.
  </Card>

  <Card title="Webhooks" href="/docs/api-reference/integration-troubleshooting/webhooks-ts">
    Learn how to handle webhook delivery failures, signature mismatches, and response timeouts.
  </Card>

  <Card title="SDKs" href="/docs/api-reference/integration-troubleshooting/sdk-ts">
    Get help with integration errors and compatibility issues across Cashfree’s SDKs.
  </Card>
</CardGroup>


# Payments Troubleshooting
Source: https://www.cashfree.com/docs/api-reference/integration-troubleshooting/payments-ts

Troubleshoot Cashfree integration issues including authentication failures, order creation errors, UPI flow problems, and checkout configuration.

<Accordion title="Authentication failed">
  The Authentication fails when:

  * Test credentials are used in the production environment or vice versa.
  * Client ID and Client Secret are passed in the request body instead of as headers.
  * API keys from different environments are mixed (for example, a Sandbox App ID used with a Production Secret Key).
  * Incorrect API keys are used, such as keys copied incorrectly or taken from a different account.

  To troubleshoot this issue, follow these steps:

  * Ensure you are using the correct API keys displayed in the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
  * Use test credentials in the test environment and production credentials in the live environment. For example, use the Client ID and Client Secret generated for the Test/Sandbox environment when making requests to `https://sandbox.cashfree.com`.
  * When calling the production API, use the Production API Key and Secret Key with the Production endpoint (for example, `https://api.cashfree.com/pg/orders/{order_id}`). Do not mix Sandbox credentials with the Production endpoint, or vice versa.
  * Pass the Client ID and Client Secret as headers, not in the request body.
  * Ensure both keys are from the same environment.

  For more details, refer to the [authentication documentation](/docs/api-reference/authentication).
</Accordion>

<Accordion title="S2S_enabled_not_approved or POST/orders/pay is not enabled or approved">
  This scenario covers multiple concerns, such as server-to-server (S2S) feature is enabled for you, but it isn't approved for your account or vice versa.

  To troubleshoot this issue, follow these steps:

  * The prerequisite for S2S is that it requires PCI DSS compliance.
  * To enable it, contact your Account Manager or fill in the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1). Once your account is reviewed and approved, this feature will be enabled.
</Accordion>

<Accordion title="Payment mode not enabled for merchant">
  The payment mode that the merchant is trying to make the payment isn't enabled for the respective account.

  To troubleshoot this issue, follow these steps:

  * Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and go to **Settings > Payment Methods** to enable the mode.
  * Alternatively, contact your Account Manager or fill in the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1).
</Accordion>

<Accordion title="Unable to delink existing AmazonPay wallet and add a new one">
  To troubleshoot this issue, follow these steps:

  * The user needs to log out of the Amazon account from that system, clear the browser cache and try once again.
</Accordion>

<Accordion title="Null objects in Get Order / Payment API response">
  If you're encountering null or empty objects in the Get Order API response, please consider below cases.

  * When no payment is associated with the order yet. ie a payment has not yet been attempted against the Order.
  * If there's a delay in the payment being recorded due to bank or network delays.
  * You are hitting the Get payments for an order API before your end customer has tried to pay.

  To troubleshoot this issue, follow these steps:

  * Please Configure webhooks to receive real-time payment updates.
  * Use the Get Payments for Order API, as the Get Order Status API will only return the order's current state and not the payment specifics.
</Accordion>

<Accordion title="Why does the Get Payments for an Order API return an empty array?">
  The [Get Payments for an Order API](/docs/api-reference/payments/latest/payments/get-payments-for-an-order) (`GET /pg/orders/{order_id}/payments`) returns an empty array (`[]`) when no payment attempt exists for the order. This happens if the customer opens checkout and then exits, closes the page, or goes back without selecting a payment method such as UPI, card, or netbanking. Cashfree creates a payment object only after the customer selects a method and starts an attempt.

  Handle the response as follows:

  * Empty array (`[]`): no payment attempt. Do not treat this as `USER_DROPPED`. `USER_DROPPED` appears on a payment object after the customer selected a method and then left the flow.
  * One or more payment objects: use `payment_status` on each object. Possible values are `SUCCESS`, `FAILED`, `PENDING`, `NOT_ATTEMPTED`, `USER_DROPPED`, `VOID`, and `CANCELLED`.
</Accordion>

<Accordion title="Which headers does the Get Payments for an Order API require?">
  The [Get Payments for an Order API](/docs/api-reference/payments/latest/payments/get-payments-for-an-order) requires the following headers:

  * `x-api-version`: the API version you integrate with. Latest is `2026-01-01`.
  * `x-client-id`: your App ID.
  * `x-client-secret`: your Secret Key.

  Platforms that call the API on behalf of merchants use `x-partner-apikey` and `x-partner-merchantid` instead of `x-client-id` and `x-client-secret`. See [API authentication](/docs/api-reference/authentication).
</Accordion>

<Accordion title="How do I avoid storing payment instrument details during checkout?">
  Pass the dummy mobile number `9999999999` in the `customer_phone` field of your [Create Order API](/docs/api-reference/payments/latest/orders/create-order) request to avoid storing payment instrument details such as cards or UPI handles. Cashfree does not store instrument details against this dummy number.
</Accordion>

<Accordion title="Order Amount Invalid">
  If you're encountering this issue, please consider below cases.

  * More than two decimal places have been provided for the 'order\_amount' field. For example, `10.123` or `11089.360` are invalid; `11089.36` is valid.
  * Order Amount is 0 or negative.
  * You have exceeded the maximum amount limit set for your MID.

  To troubleshoot this issue, follow these steps:

  * Configure `order_amount` with a maximum of two decimal places.
  * A minimum amount of one rupee is required.
  * Kindly get the maximum amount limit raised for your Merchant ID. Please contact your Account Manager or fill in the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1)
</Accordion>

<Accordion title="UPI Intent not visible on checkout">
  If you're encountering this issue, please check if your Merchant Category Code (MCC) is under the blocked list for UPI Intent. This feature is not allowed for certain categories of business due to RBI regulations.

  To troubleshoot this issue, please contact your Account Manager or fill in the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1)
</Accordion>

<Accordion title="How does Cashfree handle invalid card details on the checkout page?">
  When a customer enters invalid card details, Cashfree checkout displays an error message so they can correct the details and retry.
</Accordion>

<Accordion title="Is customer_phone required during order creation?">
  For the standard Payment Gateway checkout, `customer_phone` is a required field during order creation. You cannot omit the phone number or pass an empty value. The standard checkout pre-fills the value you provide and allows the customer to edit it before completing the payment.

  The phone number does not directly affect the availability of UPI Intent or UPI QR. It is used for checkout personalisation and eligibility, including recommended payment methods, offers, Pay Later eligibility, card saving, and card linking.
</Accordion>

<Accordion title="Why does my API response show a failed payment status while the Merchant Dashboard shows the order as successful?">
  This mismatch can occur when multiple payment attempts are made against the same Order ID. One attempt may fail (for example, due to insufficient funds) while a subsequent attempt succeeds. The Merchant Dashboard reflects the final successful status of the order, but your API response may be capturing one of the earlier failed attempts.

  To see all payment attempts and their respective statuses for a specific order, use the [Get Payments for an Order API](/docs/api-reference/payments/latest/payments/get-payments-for-an-order).
</Accordion>

<Accordion title="How do I retrieve the cf_payment_id for an order?">
  To retrieve `cf_payment_id` values, use the [Get Payments for an Order API](/docs/api-reference/payments/latest/payments/get-payments-for-an-order). Pass the order ID as a path parameter. The response returns a list of all payment attempts made for that order, each containing its `cf_payment_id`.
</Accordion>

<Accordion title="Why does the Get Payment by ID API return NOT_ATTEMPTED even though the webhook reports SUCCESS?">
  If the [Get Payment by ID API](/docs/api-reference/payments/latest/payments/get-payment-by-id) returns `NOT_ATTEMPTED` while the webhook confirms `SUCCESS`, verify that you are passing the correct `cf_payment_id` in the API request path. Ensure you are not passing a phone number or any other session-derived value in the URL path where the API expects the `cf_payment_id` (for example, `/pg/orders/{order_id}/payments/{cf_payment_id}`). Always extract the `cf_payment_id` directly from the Cashfree webhook payload or the initial payment response.
</Accordion>

<Accordion title="Which API should I use to check the status of a payment for a specific order?">
  To check the status of a specific payment against an order, use the endpoint `https://api.cashfree.com/pg/orders/{order_id}/payments/{cf_payment_id}`. This API returns the details of the payment ID passed, including the `payment_status` field.
</Accordion>

<Accordion title="How can I see sample API responses for different payment modes?">
  You can generate sample API responses for various payment modes by referring to the [Order Pay documentation](/docs/api-reference/payments/latest/payments/order-pay). Within the documentation or testing environment, you can toggle between different payment modes to view their specific response structures.
</Accordion>


# Payouts Troubleshooting
Source: https://www.cashfree.com/docs/api-reference/integration-troubleshooting/payouts-ts

Troubleshoot Cashfree Payouts errors including IP whitelisting, beneficiary validation, transfer failures, balance checks, and signature verification flows.

<Accordion title="IP not whitelisted">
  This issue arises when the API requests are made from a non-whitelisted IP address.

  To troubleshoot this issue, follow this step:

  * Refer to the [Payouts documentation](/docs/api-reference/payouts/getting-started-with-payouts-apis#whitelist-your-ip-address) to whitelist your IP address.
</Accordion>

<Accordion title="520 Unknown Error Occurred">
  This issue arises due to intermittent downtimes at Cashfree's end.

  To troubleshoot this issue, please retry this API after 10 - 15 minutes.
</Accordion>


# SDK Troubleshooting
Source: https://www.cashfree.com/docs/api-reference/integration-troubleshooting/sdk-ts

Troubleshoot Cashfree SDK integration issues for Android, iOS, Flutter, React Native, and web JS, including build, initialisation, and checkout failures.

### Mobile SDKs

<Accordion title="Integration errors due to outdated SDK versions.">
  To troubleshoot this issue, follow this step:

  * Always use the latest SDK versions. Check the [Changelog](/docs/payments/developers/changelog/android) for updates.
</Accordion>

<Accordion title="NOT_AVAILABLE isn't a trusted source,  app should be installed from play store or another whitelisted app">
  When the user is trying to install apps from sources other than the Play Store / App Store and test them in a Production environment then Cashfree mobile SDK Android, React Native, Flutter, Cordova, Ionic, Capacitor will block the transaction.

  This error also occurs when the application package is not whitelisted by Cashfree or when you are using an outdated SDK version. Whitelist your app package or check the whitelisting status in the [Merchant Dashboard](https://merchant.cashfree.com/auth/login). See [Whitelist Your Website or App](/docs/payments/online/go-live/whitelist). Upgrade your Flutter SDK to the latest stable version (for example, 2.4.0+52 or higher). Test with a build uploaded to the Google Play Store (or as a Play Store tester) so the source is recognised as trusted.

  To troubleshoot this issue, follow these steps:

  * Provide the package name of your internal testing application to Cashfree support so they can add it to the approved list.
  * See the guidelines for testing apps in [production environments](/docs/payments/online/mobile/misc/cashfree_integrity_prod_testing).
</Accordion>

<Accordion title="NDK version mismatch error with flutter_cashfree_pg_sdk">
  This issue occurs when there is an NDK version mismatch between your local setup and the SDK requirements.\
  To troubleshoot this issue, follow these steps:

  * Update the ndk.dir path in your local.properties file:\
    `ndk.dir=/path/to/ndk/<required_version>`
  * Alternatively, open Android Studio > SDK Manager > SDK Tools, and install the required NDK version.
</Accordion>

<Accordion title="Gradle build error: Could not resolve com.cashfree.pg:api...">
  This issue occurs when Gradle cannot find the required Cashfree dependencies.\
  To troubleshoot this issue, follow these steps:

  * Add the following repositories inside android/build.gradle under allprojects > repositories:\
    `google()`\
    `mavenCentral()`\
    `maven { url "https://jitpack.io" }`
</Accordion>

<Accordion title="How to initialise payment using cashfree_pg_sdk">
  To initialise a payment, follow these steps:

  * Use the method:\
    `CashfreePGSDK.doPayment(orderId, setEnvironment, setPaymentSessionId);`
  * Ensure the following:
    * `orderId` and `paymentSessionId` are securely generated from your backend.
    * `setEnvironment` is either `SANDBOX` or `PRODUCTION`.
    * You specify the platform (for example, UPI, card, or netbanking).
</Accordion>

<Accordion title="Why don't UPI apps launch in test mode?">
  This issue occurs in the sandbox (test) environment. Real UPI apps don't launch because transactions are simulated.\
  To test UPI behaviour, follow these steps:

  * Use the Cashfree UPI simulator with sandbox credentials.
  * For end-to-end testing, use production mode with small payment amounts.
</Accordion>

<Accordion title="Is UPI Intent supported on desktop websites?">
  No. UPI Intent works only on supported mobile devices and mobile applications, because it opens an installed UPI app.

  On desktop websites, present UPI QR. Do not offer UPI Intent or UPI Collect on desktop, except where NPCI still allows Collect. See [UPI Collect Flow Deprecation](/docs/payments/manage/payment-methods/upi-collect) for QR setup, iOS support, and exemption details.
</Accordion>

<Accordion title="Why do I get a payment_session_id_invalid error in the React Native SDK?">
  The `payment_session_id_invalid` error means the payment session ID is missing or does not exist. Common causes include:

  1. **Modified session ID**: Don't trim the `payment_session_id` or add extra characters to it. Pass it exactly as received from the Create Order API response.
  2. **Environment mismatch**: Ensure the `payment_session_id` generated in one environment is not used in another. A Sandbox session ID cannot be used with the Production checkout environment.

  To resolve this error:

  1. Pass the `payment_session_id` exactly as received from the Create Order API.
  2. Create the order in the same environment that the app uses.
  3. Initialise `CFSession` with `CFEnvironment.PRODUCTION` for production orders, or `CFEnvironment.SANDBOX` for sandbox orders.
  4. Verify that your API credentials, endpoint, and checkout environment are all consistent.

  See [React Native Integration](/docs/payments/online/mobile/react-native) for the session setup.
</Accordion>

<Accordion title="SDK shows strange or inconsistent errors">
  To troubleshoot this issue, follow these steps:

  * Run:\
    `flutter clean`\
    `flutter pub get`
  * If issues persist, delete the following directories:\
    `.gradle/`\
    `.idea/`
</Accordion>

<Accordion title="How do I integrate the Cashfree Android SDK for UPI Intent payments?">
  To integrate the native UPI Intent flow on Android:

  1. Create a Cashfree order from your server to obtain a `payment_session_id` and `order_id`.
  2. Initialise the Cashfree Mobile SDK in your app.
  3. Create a `CFSession` using the payment session ID and order ID.
  4. Configure `CFUPIIntentCheckoutPayment`.
  5. Call `doPayment()` to launch the native UPI Intent flow.
  6. Handle the SDK callback and verify the final payment status from your backend.

  See [Android Integration](/docs/payments/online/mobile/android) for full setup details.
</Accordion>

<Accordion title="Does Cashfree offer an embedded UPI SDK for React Native where the customer never leaves the app?">
  No. Cashfree does not currently offer a UPI plugin or SDK for React Native that keeps the customer fully inside your app. The customer must still complete the payment through an external UPI application, such as Google Pay or PhonePe.
</Accordion>

### Server-Side SDKs

<Accordion title="Authentication failed in production when using the Cashfree Node.js SDK even though API keys are correct">
  If you use the Cashfree Node.js SDK (`cashfree-pg`), pass the environment as the `CFEnvironment.PRODUCTION` enum in the configuration constructor. Do not pass a plain string. A string value can cause the SDK to default to the sandbox host, which returns a 401 authentication error when you use live API keys.
</Accordion>

<Accordion title="Sample integration kits">
  Sample integration kits

  * [Python](https://github.com/cashfree/cashfree-pg-sdk-python)
  * [Java](https://github.com/cashfree/cashfree-pg-sdk-java)
  * [.NET](https://github.com/cashfree/cashfree-pg-sdk-dotnet)
  * [PHP](https://github.com/cashfree/cashfree-pg-sdk-php)
  * [Node.js](https://github.com/cashfree/cashfree-pg-sdk-nodejs)
  * [Go](https://github.com/cashfree/cashfree-pg)
</Accordion>


# Secure ID Troubleshooting
Source: https://www.cashfree.com/docs/api-reference/integration-troubleshooting/secureid-ts

Troubleshoot Cashfree Secure ID verification errors including bank account, PAN, GST, IFSC, and aadhaar APIs with checks for inputs, headers, and responses.

<Accordion title="Empty or invalid name at bank">
  This issue arises when the customer's name isn't accessible through IMPS rails from partner banks. This is a bank-side limitation. The name can't be retrieved in this case.
</Accordion>

<Accordion title="Invalid account">
  Bank account details are invalid across all partner banks. This is a limitation on the bank’s end.
</Accordion>

<Accordion title="Account blocked">
  The account is valid but currently blocked, so transactions can't be processed. As part of the penny drop validation, we attempted to deposit ₹1 into the account. However, the transaction failed due to the blocked status.

  To troubleshoot this issue, follow this step:

  * Coordinate with the customer to verify and reactivate the account via their bank.
</Accordion>

<Accordion title="UTR not generated">
  UTR generation usually occurs during penny drop validation. In this case, a different validation mechanism was used to improve the success rate, so a UTR wasn't generated.

  To troubleshoot this issue, follow this step:

  * If UTR generation is required for all validations, fill in the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) to enable this configuration for your account.
</Accordion>

<Accordion title="Bank Account Validation (BAV) Fraud">
  This issue arises when there are excessive penny drop attempts made (for example, more than 15 in 24 hours) to the same account and IFSC code.

  To troubleshoot this issue, follow this step:

  * Fill in the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) to unblock affected accounts.
</Accordion>

<Accordion title="Blocked by CORS policy">
  This issue arises when you call Cashfree's APIs through your frontend.

  To troubleshoot this issue, follow this step:

  * To avoid CORS errors while integrating Cashfree's API, route the API requests through your backend server. Your backend can handle the request and pass the response back to the frontend. This approach bypasses browser-imposed CORS restrictions, as the call is made server-side.
</Accordion>

<Accordion title="Do Penny Drop and Verification Suite work in the pre-production (test) environment?">
  In Secure ID, Penny Drop is a real transaction, so it is supported only in the Production environment. It does not perform a real verification in the Pre-Production (Test) environment. Instead, you will receive mock responses in the Test environment, which can be used to test and validate your integration before moving to Production.
</Accordion>

<Accordion title="Why am I getting a 422 Unprocessable Entity error when using the Bank Account Validation API?">
  A 422 Unprocessable Entity error in the Bank Account Validation API can occur for the following reasons:

  1. You are using the deprecated V1 endpoint (for example, `/payout/v1/validation/bankDetails`), which is being retired. Migrate to the [Bank Account Verification Sync V2 API](/docs/api-reference/vrs/v2/bav-v2/bank-account-verification-sync-v2).
  2. The required feature is not enabled for your account. Contact your Account Manager or fill in the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) to enable it.
  3. There are invalid or missing request parameters.
  4. The request does not meet the API's validation requirements.
</Accordion>

<Accordion title="Why does the bank account verification API return 'id_not_found' for a valid bank account?">
  The `id_not_found` status in the bank account verification API can occur for the following reasons:

  * The account is returned as invalid by available sources.
  * IMPS mode is not enabled for the specific bank account and IFSC combination. The verification process may rely on IMPS.

  Verify with the respective bank whether IMPS transactions are enabled for the account.
</Accordion>

<Accordion title="Why am I getting a 404 error or 'internal_error' when calling the [Geo Coding API](/api-reference/vrs/v2/geocoding/geocoding)?">
  A 404 error or `api_error` message can occur if you are using incorrect credentials. Ensure you are using API keys specifically generated from the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) rather than general Payment Gateway credentials. Secure ID Client IDs should start with `CF`.
</Accordion>


# Webhooks Troubleshooting
Source: https://www.cashfree.com/docs/api-reference/integration-troubleshooting/webhooks-ts

Troubleshoot Cashfree webhook delivery issues including signature verification, retries, missing events, payload parsing, and endpoint availability problems.

<Accordion title="Error: &#x22;Unable to proceed. Please retry after some time&#x22;">
  This issue may arise due to multiple reasons, such as:

  * High latency in response to the test payload.
  * Webhook endpoint didn't return HTTP 200 OK.

  To troubleshoot this issue, follow this step:
  Ensure your webhook endpoint returns a 200 OK response within 50 ms during configuration.
</Accordion>

<Accordion title="Signature verification mismatch">
  This issue may arise due to multiple reasons, such as:

  * Parsed payload is being used.
  * Timestamp provided in the ‘x-webhook-timestamp’ isn't used for creating the signed payload.

  To troubleshoot this issue, follow these steps:

  * Use the raw payload and x-webhook-timestamp to generate the signed payload.
  * Sign it using your client secret and HMAC SHA256.
  * Refer [here](/docs/payments/online/webhooks/overview#webhook-signature-verification) for the sample code.
</Accordion>

<Accordion title="Webhooks not received">
  This issue may arise due to multiple reasons, such as:

  * Endpoint not returning 200 OK.
  * Required events not selected.
  * Endpoint expects a non-JSON format.
  * Payment is still in an intermediate state.

  To troubleshoot this issue, follow these steps:

  * Ensure the endpoint returns 200 OK and can parse JSON.
  * Use the [Get Payment Status API](/docs/api-reference/payments/latest/payments/get-payments-for-an-order) to check the payment status.
</Accordion>

<Accordion title="VALIDATION_FAILED">
  This issue arises because HTTP (instead of HTTPS) webhook endpoint configured in production.

  To troubleshoot this issue, follow this step:

  * Use only HTTPS URLs for webhook endpoints in the production environment.
</Accordion>

<Accordion title="Error: &#x22;Merchant Key is not Present&#x22; when configuring production webhooks">
  This error occurs when production API keys are not generated for your merchant account. To generate them:

  1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
  2. Click **Switch to Prod** at the top right.
  3. Click **Developers** at the top right.
  4. Click **API Keys** under **Payment Gateway**.
  5. Click **Generate API Keys** and complete two-factor authentication.

  After the keys are generated, you can configure your production webhooks.
</Accordion>

<Accordion title="Why am I receiving duplicate successful payment webhook events?">
  Receiving duplicate webhook events for a single successful payment can occur when multiple webhook versions are enabled for your account. Identify which webhook version you intend to use, then raise a request through the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1). Cashfree disables the unused version. This control is not available in the Merchant Dashboard.

  For other causes, including retries and duplicate subscriptions, see [Receiving duplicate webhook events](/docs/payments/online/webhooks/troubleshooting#receiving-duplicate-webhook-events).
</Accordion>

<Info>
  For comprehensive security guidelines including IP whitelisting, signature verification, and SSL configuration, refer to the [Webhook Security Checklist](/docs/payments/online/webhooks/security-checklist).
</Info>


# Bill Fetch Request
Source: https://www.cashfree.com/docs/api-reference/other-apis/bbps-cou/bill-fetch/request

openapi/bbps/bbps-cou.yaml post /bbps/cou/v1/billers/request/bill-fetch
Use this API to initiate a bill fetch or bill validation request for a customer.
This is an **async** API. It returns only an acknowledgement with a `ref_id`.
The actual bill details must be retrieved separately by polling the Bill Fetch Response API using this `ref_id`.

<Note>
This API is only applicable for billers whose `fetch_requirement` or `support_bill_validation` is `MANDATORY` or `OPTIONAL`. For billers where both are `NOT_SUPPORTED` (i.e., `DIRECT_PAY` flow), calling this API will return a validation error. Proceed directly to the Bill Payment Request API for those billers.
</Note>

<Accordion title="Flow determination logic">

The flow is determined using `fetch_requirement` and `support_bill_validation` from the Fetch Billers Info API response, evaluated in the following priority order:

| Priority | `fetch_requirement` | `support_bill_validation` | Flow |
|---|---|---|---|
| 1 | `MANDATORY` | Any | `FETCH_AND_PAY` |
| 2 | `NOT_SUPPORTED` | `MANDATORY` or `OPTIONAL` | `VALIDATE_AND_PAY` |
| 3 | `NOT_SUPPORTED` | `NOT_SUPPORTED` | `DIRECT_PAY` |
| 4 | `OPTIONAL` | `MANDATORY` | `VALIDATE_AND_PAY` |
| 5 | `OPTIONAL` | Any other | `FETCH_AND_PAY` |

For `DIRECT_PAY`, skip the bill fetch step and proceed directly to the Bill Payment Request API.

</Accordion>

Store the `flow` field from the response. It determines which fields to expect in the Bill Fetch Response and whether a bill payment can proceed without a prior fetch.



# Bill Fetch Response
Source: https://www.cashfree.com/docs/api-reference/other-apis/bbps-cou/bill-fetch/response

openapi/bbps/bbps-cou.yaml post /bbps/cou/v1/billers/response/bill-fetch
Use this API to poll the result of a previously initiated Bill Fetch or Bill Validation request.
Use the `ref_id` from the Bill Fetch Request API to retrieve the status and bill details.

<Accordion title="Polling strategy">

Poll at increasing intervals until `message` is no longer `"Request is still being processed"`:

| Attempt | Wait before this poll |
|---|---|
| 1 | 5 seconds |
| 2 | 15 seconds |
| 3 | 30 seconds |
| 4 | 1 minute |
| 5+ | 3 minutes |

Stop polling when `message` is `"Bill details fetched successfully"` or `"Bill request failed"`. If the request remains in a processing state beyond your retry limit, treat it as a timeout and raise a support ticket.

</Accordion>

<Accordion title="Response fields by outcome">

- `bill_fetch_response` is present in every response, including success, failure, and pending states.
- For `FETCH_AND_PAY` success, the response includes `bill_fetch_response`, `bill_details`, `biller_response`, and `additional_info`.
- For `FETCH_AND_PAY` failure, the response includes only `bill_fetch_response`.
- For `VALIDATE_AND_PAY` success, the response includes `bill_fetch_response` and `additional_info`.
- For `VALIDATE_AND_PAY` failure, the response includes only `bill_fetch_response`.
- While the request is pending, the response includes only `bill_fetch_response`, with the processing status.

</Accordion>



# Bill Payment Request
Source: https://www.cashfree.com/docs/api-reference/other-apis/bbps-cou/bill-payment/request

openapi/bbps/bbps-cou.yaml post /bbps/cou/v1/billers/request/bill-payment
Use this API to initiate a bill payment against a previously fetched or validated bill. This is an **async** API. It returns only an acknowledgement with a `transaction_ref_id`. Poll the Bill Payment Response API using both `bill_fetch_ref_id` and `transaction_ref_id` to get the final payment status. The `bill_fetch_ref_id` is not required for the direct pay flow.




# Bill Payment Response
Source: https://www.cashfree.com/docs/api-reference/other-apis/bbps-cou/bill-payment/response

openapi/bbps/bbps-cou.yaml post /bbps/cou/v1/billers/response/bill-payment
Use this API to poll for the result of a previously submitted bill payment request.
Call this using both `bill_fetch_ref_id` and `transaction_ref_id` from the Bill Payment Request API. The `bill_fetch_ref_id` is not required for the direct pay flow.

<Accordion title="Polling strategy">

Poll at increasing intervals until `message` is no longer `"Payment is still being processed"`:

| Attempt | Wait before this poll |
|---|---|
| 1 | 5 seconds |
| 2 | 15 seconds |
| 3 | 30 seconds |
| 4 | 1 minute |
| 5+ | 3 minutes |

Stop polling when `message` is `"Payment successful"` or `"Payment failed"`. If the payment remains in a processing state beyond your retry limit, treat it as a timeout and raise a support ticket.

</Accordion>

<Accordion title="Response outcomes">

The outcome is conveyed by the top-level `message` and can be confirmed from `data.bill_payment_response.reason.response_code`:

<ul>
  <li><code>Payment is still being processed</code> (response_code <code>PENDING</code>): payment is still in progress. Continue polling.</li>
  <li><code>Payment successful</code> (response_code <code>000</code>): payment completed successfully.</li>
  <li><code>Payment failed</code>: payment failed. Read <code>reason.compliance_reason</code> for the cause.</li>
</ul>

</Accordion>



# Fetch Biller Categories
Source: https://www.cashfree.com/docs/api-reference/other-apis/bbps-cou/billers/categories

openapi/bbps/bbps-cou.yaml get /bbps/cou/v1/billers/categories
Use this API to fetch the list of all active biller categories available on the BBPS network. Agent Institutions can use this to populate category selection in their UI. Since this data changes infrequently, it is recommended to fetch and cache it at predefined intervals instead of calling the API on every user request.




# Fetch Billers Info
Source: https://www.cashfree.com/docs/api-reference/other-apis/bbps-cou/billers/info

openapi/bbps/bbps-cou.yaml post /bbps/cou/v1/billers/info
Use this API to fetch the complete catalog and MDM (Master Data Management) details of billers registered under BBPS. Use this to understand biller configuration, required customer input parameters, supported payment modes and channels, and fee structures. If the request body is omitted, all billers are returned.




# Data to Test Integration
Source: https://www.cashfree.com/docs/api-reference/other-apis/bbps-cou/data-to-test-integration

Use the sandbox credentials, test billers, and end-to-end flow on this page to validate your BBPS COU integration before going live.

Use the sandbox credentials and test flow on this page to validate your BBPS COU integration before going live. The sandbox environment supports end-to-end testing of the bill fetch and bill payment journey, including a built-in auto bill simulator for the Loan Repayment category.

<CardGroup>
  <Card title="Sandbox credentials" icon="key" href="#sandbox-credentials">
    Agent IDs and device block values for each supported initiating channel.
  </Card>

  <Card title="Test billers" icon="building-columns" href="#test-billers">
    How to identify customer input parameters for any biller and how to use the auto bill simulator.
  </Card>

  <Card title="End-to-end flow" icon="arrow-right-arrow-left" href="#end-to-end-sandbox-testing">
    Step-by-step instructions to complete a full bill payment cycle in the sandbox environment.
  </Card>
</CardGroup>

## Sandbox credentials

Use the agent IDs below when constructing sandbox requests. Each agent ID is pre-configured for a specific initiating channel.

| Initiating channel | Channel code | Sandbox agent ID |
| :- | :- | :- |
| Internet Banking (Post-login) | `INTB` | `CH01CH02INB516193127` |
| Mobile Banking (Post-login) | `MOBB` | `CH01CH02MBBPAL001085` |

### Device block values

The device block must match the tag requirements of the initiating channel. Use the values below when building sandbox requests.

<Tabs>
  <Tab title="INTB — Internet Banking (Post-login)">
    Pass the following tags in the `agent.device.tag` array for the `INTB` channel.

    | Tag name | Sandbox value |
    | :- | :- |
    | `INITIATING_CHANNEL` | `INTB` |
    | `IP` | `124.170.23.24` |
    | `MAC` | `01-23-45-67-89-ab` |
  </Tab>

  <Tab title="MOBB — Mobile Banking (Post-login)">
    Pass the following tags in the `agent.device.tag` array for the `MOBB` channel.

    | Tag name | Sandbox value |
    | :- | :- |
    | `INITIATING_CHANNEL` | `MOBB` |
    | `IP` | `124.170.23.24` |
    | `IMEI` | `123456789012345` |
    | `OS` | `IOS` |
    | `APP` | `AGENTAPP` |
  </Tab>
</Tabs>

<Note>
  For the Bill Fetch Request API, the same values apply but are passed as named fields directly under `agent_device_info` (for example, `init_channel`, `ip`, `mac`) rather than as a tag array. The tag array format applies to the Bill Payment Request API.
</Note>

## Test billers

### Finding customer input parameters

Each biller requires a specific set of customer identifiers to initiate a bill fetch. To find the correct parameters for a biller, call the [Fetch Billers Info API](/docs/api-reference/other-apis/bbps-cou/billers/info) and read the `biller_customer_params` field in the response. This field lists all the input parameter names and their expected formats that must be passed in the `input_params` block of the Bill Fetch Request.

### Auto bill simulator

For the Loan Repayment category, a built-in auto bill simulator is available in the sandbox environment. Instead of supplying real customer identifiers, pass `CF_AUTO_GENERATE` as the value for any input parameter. The system automatically generates a bill and returns a `ref_id` that you can use to poll the Bill Fetch Response API.

Use the following biller to test the auto bill simulator:

| Field | Value |
| :- | :- |
| Biller ID | `SWAR00027NAT2J` |
| Category | Loan Repayment |
| Input parameter value | `CF_AUTO_GENERATE` |

<Tip>
  The auto bill simulator eliminates the need for real loan account numbers during sandbox testing, making it straightforward to run a complete end-to-end flow without any production data.
</Tip>

## End-to-end sandbox testing

The following steps walk you through a complete BBPS COU bill payment cycle in the sandbox environment using the auto bill simulator.

<Steps>
  <Step title="Initiate a bill fetch">
    Call the [Bill Fetch Request API](/docs/api-reference/other-apis/bbps-cou/bill-fetch/request) using your sandbox credentials. Use biller ID `SWAR00027NAT2J` and pass `CF_AUTO_GENERATE` as the value for all input parameters in the `input_params` block.

    A successful request returns a `ref_id`. Store this value — you will need it to poll the bill fetch response and to submit the bill payment request.
  </Step>

  <Step title="Poll the bill fetch response">
    Call the [Bill Fetch Response API](/docs/api-reference/other-apis/bbps-cou/bill-fetch/response) using the `ref_id` from Step 1. Poll at regular intervals until the response returns a terminal status.

    Once successful, note the `biller_response` object and the `additional_info` field from the response. You must pass both of these fields exactly as received into the Bill Payment Request in Step 4.
  </Step>

  <Step title="Complete the payment transaction">
    Use [Cashfree DevStudio](https://www.cashfree.com/devstudio) to complete the payment leg of the transaction in the sandbox environment. Once the payment is complete, DevStudio returns a Cashfree payment ID (`cf_payment_id`). Store this value — it is required as the `pg_reference_id` in the next step.
  </Step>

  <Step title="Submit the bill payment request">
    Call the [Bill Payment Request API](/docs/api-reference/other-apis/bbps-cou/bill-payment/request) with the following data:

    * Under `head`, set `bill_fetch_ref_id` to the `ref_id` from Step 1 and set `pg_reference_id` to the `cf_payment_id` received from DevStudio in Step 3.
    * Pass the `biller_response` object exactly as received from the Bill Fetch Response in Step 2.
    * Pass the `additional_info` field exactly as received from the Bill Fetch Response in Step 2.

    A successful request returns a `transaction_ref_id`. Store this value along with the `bill_fetch_ref_id` to poll for the final payment status.
  </Step>

  <Step title="Poll the bill payment response">
    Call the [Bill Payment Response API](/docs/api-reference/other-apis/bbps-cou/bill-payment/response) using both the `bill_fetch_ref_id` from Step 1 and the `transaction_ref_id` from Step 4. Poll at regular intervals until `data.status` returns `success` or `failed`.

    A `success` status confirms that the end-to-end BBPS COU transaction completed successfully in the sandbox environment.
  </Step>
</Steps>

<Note>
  Complete all integration testing in the sandbox environment before deploying to production. For help with errors encountered during testing, refer to the [BBPS COU error codes](/docs/api-reference/other-apis/bbps-cou/error-codes) page.
</Note>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/other-apis/bbps-cou/overview">BBPS COU overview</a></li>
    <li><a href="/docs/api-reference/other-apis/bbps-cou/bill-fetch/request">Bill Fetch Request API</a></li>
    <li><a href="/docs/api-reference/other-apis/bbps-cou/bill-payment/request">Bill Payment Request API</a></li>
    <li><a href="/docs/api-reference/other-apis/bbps-cou/error-codes">BBPS COU error codes</a></li>
  </ul>
</div>


# Bill Fetch and Payment Error Codes
Source: https://www.cashfree.com/docs/api-reference/other-apis/bbps-cou/error-codes

Cashfree BBPS Customer Operating Unit (COU) compliance response codes for failed bill fetch, validation, and payment requests, with retry categories.

The Cashfree BBPS Customer Operating Unit (COU) API returns a compliance response code in `compliance_resp_cd` when a bill fetch, validation, or payment request fails. The accompanying `compliance_reason` gives the human-readable failure reason. Use these codes to identify the cause of a failure and to decide whether you can retry the request.

## Retry categories

Each error code maps to a retry category that tells you how to handle the failure. The following categories apply across all error groups:

* `NON_RETRIABLE`: the request will fail again with the same input. Do not retry the same request. Correct the customer details or inform the customer, as indicated by the reason.
* `RETRIABLE`: the failure is temporary, usually a biller or network issue. Retry the request after a short delay.
* `CONDITIONAL`: the outcome depends on inner error codes returned by the biller or the switch. Inspect the accompanying reason before you decide whether to retry.

<Note>
  Some reasons include additional timing guidance, such as retrying later or on the next day. Always honour the timing hint in the reason before you retry.
</Note>

## Bill fetch error codes

The [Bill Fetch Response API](/docs/api-reference/other-apis/bbps-cou/bill-fetch/response) returns these codes when a fetch request fails. Fetch codes use the `BFR` prefix.

| `compliance_resp_cd` | Reason | Category |
| - | - | - |
| `BFR001` | Incorrect or invalid customer account | `NON_RETRIABLE` |
| `BFR002` | Invalid combination of customer parameters | `NON_RETRIABLE` |
| `BFR003` | No bill data available | `NON_RETRIABLE` |
| `BFR004` | Payment received for the billing period, no bill due | `NON_RETRIABLE` |
| `BFR005` | Customer account is blocked or closed | `NON_RETRIABLE` |
| `BFR006` | Customer account is not activated | `NON_RETRIABLE` |
| `BFR007` | Bill due date has expired, bill details not available | `NON_RETRIABLE` |
| `BFR008` | Unable to get bill details from biller | `RETRIABLE` |
| `BFR009` | Scheduled downtime by biller, try again later | `RETRIABLE` |
| `BFR010` | Unscheduled downtime by biller, try again later | `RETRIABLE` |
| `BFR011` | Incomplete details in biller system, update customer profile | `NON_RETRIABLE` |
| `BFR012` | ePayment not enabled for the dealer | `NON_RETRIABLE` |
| `BFR013` | Maximum refill count reached | `NON_RETRIABLE` |
| `BFR014` | Consumer has reported loss of cylinder | `NON_RETRIABLE` |
| `BFR015` | Cannot take booking, consumer KYC not submitted | `NON_RETRIABLE` |
| `BFR016` | One prior booking is pending against this consumer | `NON_RETRIABLE` |
| `BFR017` | Price not yet set for nature or package code. Retry later. | `RETRIABLE` |
| `BFR018` | Day-end not done, try after some time | `RETRIABLE` |
| `BFR019` | Consumer number and distributor not matching | `NON_RETRIABLE` |
| `BFR020` | LPG ID not found | `NON_RETRIABLE` |
| `BFR021` | Vehicle registration number invalid or does not exist | `NON_RETRIABLE` |
| `BFR022` | FASTag inactive or blocked, recharge not allowed | `NON_RETRIABLE` |
| `BFR023` | FASTag exempted, recharge not allowed | `NON_RETRIABLE` |

## Bill validation error codes

The [Bill Fetch Response API](/docs/api-reference/other-apis/bbps-cou/bill-fetch/response) returns these codes when a bill validation request fails. Validation codes use the `BVR` prefix.

| `compliance_resp_cd` | Reason | Category |
| - | - | - |
| `BVR001` | Incorrect or invalid customer account | `NON_RETRIABLE` |
| `BVR002` | Invalid combination of customer parameters | `NON_RETRIABLE` |
| `BVR003` | Customer account is blocked or closed | `NON_RETRIABLE` |
| `BVR004` | Customer account is not activated | `NON_RETRIABLE` |
| `BVR005` | Invalid amount | `NON_RETRIABLE` |
| `BVR006` | Customer account deactivated, pay to activate | `NON_RETRIABLE` |
| `BVR007` | Incomplete details in biller system, update profile | `NON_RETRIABLE` |
| `BVR008` | Customer account valid but no bill due | `NON_RETRIABLE` |
| `BVR009` | Technical exception from biller | `RETRIABLE` |

## Payment posting error codes

The [Bill Payment Response API](/docs/api-reference/other-apis/bbps-cou/bill-payment/response) returns these codes when a payment fails at the biller. Payment codes use the `BPR` prefix.

| `compliance_resp_cd` | Reason | Category |
| - | - | - |
| `BPR001` | Incorrect or invalid customer account | `NON_RETRIABLE` |
| `BPR002` | Invalid combination of customer parameters | `NON_RETRIABLE` |
| `BPR003` | Customer account is blocked or closed | `NON_RETRIABLE` |
| `BPR004` | Customer account is not activated | `NON_RETRIABLE` |
| `BPR005` | Payment cannot be accepted at this time | `RETRIABLE` |
| `BPR006` | Payment request has been exceeded for the day. Retry the next day. | `NON_RETRIABLE` |
| `BPR007` | Repeat payment request | `NON_RETRIABLE` |
| `BPR008` | Due date expired, re-fetch to get current outstanding | `RETRIABLE` |
| `BPR009` | Scheduled downtime by biller, try again later | `RETRIABLE` |
| `BPR010` | Unscheduled downtime by biller, try again later | `RETRIABLE` |
| `BPR011` | Payment amount different from current outstanding | `RETRIABLE` |
| `BPR012` | FASTag top-up failed, try again later | `RETRIABLE` |

## Infrastructure error codes

These codes indicate a transport or switch-level failure between the operating units, rather than a biller decision. Codes with the `BOU` prefix relate to the Biller Operating Unit, and codes with the `COU` prefix relate to the Customer Operating Unit.

| `compliance_resp_cd` | Reason | Category |
| - | - | - |
| `BOU001` | Send failed to BOU | `RETRIABLE` |
| `BOU002` | Inner error codes from BOU negative acknowledgement | `CONDITIONAL` |
| `BOU003` | Timeout at BOU | `RETRIABLE` |
| `BOU004` | BOU reversal retry failure | `NON_RETRIABLE` |
| `BOU005` | BOU reversal response timeout | `NON_RETRIABLE` |
| `BOU006` | Connect timeout at BOU | `RETRIABLE` |
| `BOU007` | Read timeout at BOU | `RETRIABLE` |
| `BOU008` | Unable to connect to BOU | `RETRIABLE` |
| `BOU009` | Pending transaction timeout at BOU | `RETRIABLE` |
| `COU001` | Send failed to COU | `RETRIABLE` |
| `COU002` | Inner error codes from COU negative acknowledgement | `CONDITIONAL` |
| `COU003` | COU reversal retry failure | `NON_RETRIABLE` |
| `COU006` | Connect timeout at COU | `RETRIABLE` |
| `COU007` | Read timeout at COU | `RETRIABLE` |
| `COU008` | Unable to connect to COU | `RETRIABLE` |


# BBPS for Customers
Source: https://www.cashfree.com/docs/api-reference/other-apis/bbps-cou/overview

Cashfree BBPS for Customers APIs cover authentication, biller discovery, bill fetch, bill payment, ticket handling, and wallet operations for Agent Institutions.

The BBPS for Customers (Customer Operating Unit, or COU) APIs enable Agent Institutions, entities that onboard customers and offer BBPS services, to integrate with the Bharat Bill Payment System (BBPS) network operated by NPCI. Using these APIs, Agent Institutions can build complete bill payment experiences for their customers across all registered BBPS billers.

## Key features

Cashfree BBPS for Customers supports the following capabilities:

* **Biller discovery**: Retrieve all active biller categories and MDM details, including customer input parameters, supported payment modes, and fee structures, to present accurate biller information before initiating a payment.
* **Async bill fetch and payment**: Bill fetch and payment requests return a reference ID immediately. Poll the corresponding response endpoint at regular intervals until the operation returns a terminal status.
* **Flexible payment flows**: Supports `FETCH_AND_PAY`, `VALIDATE_AND_PAY`, and direct bill payment flows, determined automatically by biller configuration, across all BBPS categories. Direct bill payment is used for billers that do not require a prior fetch or validation step, such as donation billers.
* **Ticket management**: Raise a support ticket for any processed transaction and poll its status using the Ticket APIs.
* **Wallet management**: Check the agent institution wallet balance and retrieve paginated ledger history for reconciliation.

## Authentication

All APIs use header authentication. Pass both headers in every request:

```http theme={"dark"}
x-client-id: <your-client-id>
x-client-secret: <your-client-secret>
```

<Note>
  Credentials are issued per Agent Institution. Your `x-client-id` and `x-client-secret` are available in your [Merchant Dashboard](https://merchant.cashfree.com/verificationsuite/developers/api-keys) for both sandbox and production environments.
</Note>

## Versioning

All BBPS COU APIs require an `x-api-version` header in every request. The current supported version is `2025-01-01`.

```http theme={"dark"}
x-api-version: 2025-01-01
```

<Note>
  This value is pre-filled in the **Try It** playground on each API page.
</Note>

## Rate limits

All APIs are rate limited to 100 requests per 60 seconds. Exceeding the limit returns HTTP 429.

## API flow

A complete bill payment journey involves the following steps:

<Steps>
  <Step title="Fetch biller categories">
    Get the list of active biller categories, for example, ELECTRICITY, DTH, and GAS.
  </Step>

  <Step title="Fetch billers info">
    Get MDM details for billers in a category, including customer input parameters, supported payment modes, fetch requirements, and fee structures.
  </Step>

  <Step title="Bill fetch request">
    Initiate an async bill fetch, validation, or direct payment for the customer. Returns a `ref_id` immediately. The system determines the flow automatically based on biller configuration:

    * `FETCH_AND_PAY` returns bill details from the biller
    * `VALIDATE_AND_PAY` validates customer identity without fetching bill details
    * Direct bill payment skips the fetch step entirely and is used for billers such as donation billers
  </Step>

  <Step title="Poll bill fetch response">
    Poll using the `ref_id` at regular intervals until the response returns a terminal status. Refer to the polling strategy in the Bill fetch response API for recommended intervals and retry limits.
  </Step>

  <Step title="Bill payment request">
    Submit the payment using data from the fetch response. Returns `transaction_ref_id` immediately.
  </Step>

  <Step title="Poll bill payment response">
    Poll using `bill_fetch_ref_id` and `transaction_ref_id` at regular intervals until the response returns a terminal status. Refer to the polling strategy in the Bill payment response API for recommended intervals and retry limits.
  </Step>
</Steps>

<Note>
  To raise a support ticket for a processed payment, use the Raise Ticket Request API after a payment is complete. Poll the Ticket Status API using the returned `ref_id` to track progress.
</Note>

<Tabs>
  <Tab title="Billers">
    <div>
      <div>
        <div>
          <h4>Billers</h4>

          <div>
            <a href="/docs/api-reference/other-apis/bbps-cou/billers/categories">Fetch biller categories</a>

            <p>
              Get all active biller category codes, such as ELECTRICITY, DTH, and GAS. Cache this list because it changes infrequently.
            </p>
          </div>

          <hr />

          <div>
            <a href="/docs/api-reference/other-apis/bbps-cou/billers/info">Fetch billers info</a>

            <p>
              Get MDM details for billers in a category, including customer input parameters, supported payment modes, fetch requirements, and fee structures.
            </p>
          </div>
        </div>
      </div>
    </div>
  </Tab>

  <Tab title="Bill fetch and payment">
    <div>
      <div>
        <div>
          <h4>Bill fetch</h4>

          <div>
            <a href="/docs/api-reference/other-apis/bbps-cou/bill-fetch/request">Bill fetch request</a>

            <p>
              Initiate an async bill fetch or validation for the customer. Returns a <code>ref\_id</code> immediately. The system determines the flow based on biller configuration. It uses <code>FETCH\_AND\_PAY</code> or <code>VALIDATE\_AND\_PAY</code>.
            </p>
          </div>

          <hr />

          <div>
            <a href="/docs/api-reference/other-apis/bbps-cou/bill-fetch/response">Bill fetch response</a>

            <p>
              Poll for the bill fetch result using the <code>ref\_id</code> returned from the fetch request.
            </p>
          </div>
        </div>
      </div>

      <div>
        <div>
          <h4>Bill payment</h4>

          <div>
            <a href="/docs/api-reference/other-apis/bbps-cou/bill-payment/request">Bill payment request</a>

            <p>
              Initiate an async bill payment using data from the fetch response. Returns a <code>transaction\_ref\_id</code> immediately.
            </p>
          </div>

          <hr />

          <div>
            <a href="/docs/api-reference/other-apis/bbps-cou/bill-payment/response">Bill payment response</a>

            <p>
              Poll for the payment result using <code>bill\_fetch\_ref\_id</code> and <code>transaction\_ref\_id</code> until <code>data.status</code> is <code>success</code> or <code>failed</code>.
            </p>
          </div>
        </div>
      </div>
    </div>
  </Tab>

  <Tab title="Ticket and wallet">
    <div>
      <div>
        <div>
          <h4>Ticket management</h4>

          <div>
            <a href="/docs/api-reference/other-apis/bbps-cou/ticket/request">Raise ticket request</a>

            <p>
              Raise a support ticket for a processed bill payment transaction. Returns a <code>ref\_id</code> immediately.
            </p>
          </div>

          <hr />

          <div>
            <a href="/docs/api-reference/other-apis/bbps-cou/ticket/response">Poll ticket status</a>

            <p>
              Poll for the current status of a raised ticket using the <code>ref\_id</code> returned from the ticket request.
            </p>
          </div>
        </div>
      </div>

      <div>
        <div>
          <h4>Wallet</h4>

          <div>
            <a href="/docs/api-reference/other-apis/bbps-cou/wallet/balance">Wallet balance</a>

            <p>
              Get the current agent institution wallet balance.
            </p>
          </div>

          <hr />

          <div>
            <a href="/docs/api-reference/other-apis/bbps-cou/wallet/ledger">Wallet ledger</a>

            <p>
              Retrieve paginated wallet transaction history for reconciliation.
            </p>
          </div>
        </div>
      </div>
    </div>
  </Tab>
</Tabs>


# Raise a Ticket Request
Source: https://www.cashfree.com/docs/api-reference/other-apis/bbps-cou/ticket/request

openapi/bbps/bbps-cou.yaml post /bbps/cou/v1/billers/request/ticket
Use this API to raise a support ticket for a previously processed bill payment.
This is an **async** API. It returns an acknowledgement with a `ref_id`.
Poll the Ticket Status API using `ref_id` to get the current status of your ticket.

<Accordion title="Disposition codes">

Pass one of the following codes in the `disposition` field:

| Disposition code | Description | Type |
|---|---|---|
| `D11` | Transaction Successful, Amount Debited but services not received | Dispute |
| `D12` | Transaction Successful, Amount Debited but Service Disconnected or Service Stopped | Dispute |
| `D13` | Transaction Successful, Amount Debited but LPSC Late Payment Surcharge Charges added in next bill | Dispute |
| `D21` | Erroneously paid in wrong account | Dispute |
| `D22` | Duplicate Payment | Dispute |
| `D23` | Erroneously paid the wrong amount | Dispute |
| `D31` | Payment information not received from Biller or delay in receiving payment information from the Biller | Complaint |
| `D32` | Bill paid but amount not adjusted or still showing due amount | Complaint |

</Accordion>



# Poll Ticket Status Response
Source: https://www.cashfree.com/docs/api-reference/other-apis/bbps-cou/ticket/response

openapi/bbps/bbps-cou.yaml post /bbps/cou/v1/billers/response/ticket-status
Use this API to poll the status of a previously raised ticket.
Call this using the `ref_id` returned from the Raise Ticket Request API.

<Accordion title="Polling strategy">

Poll at increasing intervals until `message` is no longer `"Ticket request is still being processed"`:

| Attempt | Wait before this poll |
|---|---|
| 1 | 5 seconds |
| 2 | 15 seconds |
| 3 | 30 seconds |
| 4 | 1 minute |
| 5+ | 3 minutes |

Stop polling when `message` is `"Ticket details fetched successfully"` or `"Ticket request failed"`. If the ticket remains in a processing state beyond your retry limit, contact Cashfree support with the `ref_id`.

</Accordion>

<Accordion title="Response outcomes by `message`">

| `message` | Meaning |
|---|---|
| `"Ticket details fetched successfully"` | Completed. Check `data` for ticket details. |
| `"Ticket request failed"` | Terminal failure. Stop polling. |
| `"Ticket request is still being processed"` | Still processing. Continue polling. |

</Accordion>



# Fetch Agent Institution Wallet Balance
Source: https://www.cashfree.com/docs/api-reference/other-apis/bbps-cou/wallet/balance

openapi/bbps/bbps-cou.yaml get /bbps/cou/agent/{agentId}/wallet/balance
Use this API to fetch the current available wallet balance for a given Agent Institution.
This balance reflects funds available for BBPS bill payment transactions.

<Note>
The balance can be positive or negative, depending on the Agent Institution's funding model:
- Prefunding model: the Agent Institution funds the wallet in advance, and bill payments are debited from it. The balance is the remaining prefunded amount and does not go below zero.
- Shortfall (postfunding) model: bill payments are drawn against a Cashfree-funded credit line, so the balance can be negative. A negative balance represents the current shortfall, that is, the amount the Agent Institution has drawn and must repay.
</Note>



# Fetch Agent Institution Wallet Ledger
Source: https://www.cashfree.com/docs/api-reference/other-apis/bbps-cou/wallet/ledger

openapi/bbps/bbps-cou.yaml post /bbps/cou/agent/{agentId}/wallet/ledger
Use this API to fetch a paginated list of wallet ledger entries for a given Agent Institution.
Includes credits (recharges) and debits (bill payments).
Results can be filtered by date range, transaction type, or UTR.
All request body fields are optional. An empty body returns all entries.

<Note>
The ledger lists wallet credits (recharges) and debits (bill payments). On the prefunding model, each bill payment also produces freeze and unfreeze hold entries against the prefunded balance. On the shortfall (postfunding) model, debits can take the running balance negative, reflecting the amount drawn against the credit line.
</Note>



# APIs to Implement
Source: https://www.cashfree.com/docs/api-reference/other-apis/bbps/apis-to-implement

Reference for the APIs billers must expose to join the BBPS network, covering bill fetch, payment posting, and authentication requirements.

To join the BBPS network, billers must implement two APIs that Cashfree calls on behalf of the network during customer bill interactions. Both APIs must be built to the structure defined below and shared with Cashfree along with the authentication details and environment URLs.

<Note>
  Once you provide the API contracts and URLs for both test and production environments, Cashfree integrates your APIs within two working days, provided they meet the recommended standards.
</Note>

## APIs to implement

The following two APIs are required for BBPS network participation:

### Bill fetch

The bill fetch API is called when a customer initiates a bill lookup on a BBPS-enabled app such as PhonePe, Google Pay, or Paytm. It must return the outstanding bill details for the customer based on the input parameters passed by the network.

* **Method**: GET
* **Trigger**: Customer initiates a bill lookup on a BBPS-enabled app
* **Response**: Outstanding bill details for the customer

### Payment posting

The payment posting API is called after a customer completes a bill payment on a BBPS-enabled app. Your system must respond with an acceptance or rejection of the payment.

* **Method**: POST
* **Trigger**: Customer completes a payment on a BBPS-enabled app
* **Response**: Acceptance or rejection of the payment

## Authentication

Along with your API contracts and environment URLs, inform Cashfree of the authentication protocol your APIs use and provide credentials for both test and production environments.


# Check Transaction Status
Source: https://www.cashfree.com/docs/api-reference/other-apis/bbps/check-transaction-status

get /bbps/biller/bill/status/{bbps_transaction_id}
The check transaction status API allows billers to retrieve the current status of a transaction using the unique BBPS transaction ID associated with the bill. This endpoint serves as a reliable method for querying transaction details, providing merchants with real-time updates on payment status.



# Next Steps for Biller
Source: https://www.cashfree.com/docs/api-reference/other-apis/bbps/next-steps-for-biller

Follow these next steps after implementing the BBPS biller APIs, including sharing endpoints and credentials with Cashfree to complete onboarding and go live.

1. Once you are done implementing this APIs at your end, please create a document with the following details and send it over to [bbpsproduct@cashfree.com](mailto:bbpsproduct@cashfree.com):

* The API contracts that are finally implemented for both the APIs. Include the following:
  * Expected Sample Request
  * Sample Success Response
  * Sample Failure Response
  * Sample Error Response
* Describe the authentication mechanism you have implemented along with credentials for the same in
  * Test Environment
  * Production Environment
* Provide the base URL & the path to access both the APIs in
  * Test Environment
  * Production Environment
* Provide 7-8 data points in test environment through which bill fetch can be triggered.
* Confirm the Onboarding Configurations as defined in Section F and mention the same in the document.

2. Cashfree team will test the API functionality in test environment and then integrate with BBPS system if its working as expected.
3. The same would be sent for approval to NPCI along with the legal documentation. NPCI would take 1-2 weeks to approve the request if everything is correct.
4. NPCI would give a go-ahead and configure the production routing so transactions can be initiated. Biller would be live on BHIM initially and within 1 week would appear on GPay. Post that it would appear on PhonePe and other apps in 2 weeks.
5. Biller can use Cashfree Dashboard to see realtime reporting of transactions coming through BBPS.


# NPCI Onboarding Configurations
Source: https://www.cashfree.com/docs/api-reference/other-apis/bbps/npci-onboarding-configurations

Configure BBPS biller onboarding fields including customer input parameters, payment amount exactness, extra bill fetch response data, and acceptance rules.

In addition to legal and branding details, billers must submit the following technical configurations to NPCI as part of the onboarding process. Review each configuration and provide your decisions along with your API contracts.

## Customer input parameters

**Required**

Define the input parameters that customers must enter in the payment app to identify their account or bill. For each parameter, provide the following details:

| Field | Description |
| - | - |
| Name | Parameter identifier, for example, `phone_number`, `loan_number`, `policy_no` |
| Data type | `Alphanumeric`, `Numeric`, or `Date` |
| Special characters | Whether special characters are allowed in the value, and if so, which ones |
| Length | Minimum and maximum character length of the value, for example, 3 to 10 characters |

## Payment amount exactness

**Required**

Select the amount behaviour you want to apply to payments received through BBPS.

| Option | Description |
| - | - |
| `ADHOC` | Customer can enter any amount |
| `EXACT` | Amount is non-editable |
| `EXACT DOWN` | Customer can enter an amount equal to or less than the bill fetch amount |
| `EXACT UP` | Customer can enter an amount equal to or greater than the bill fetch amount |

## Additional bill fetch response fields

**Optional**

If your bill fetch response needs to return fields beyond the standard response, specify the additional parameters here. These become part of the `additional_info` object in the bill fetch response.

## Payment acceptance behaviour

**Optional**

Select whether your system should always accept payments, or accept and reject based on business logic.

* **Always accept**: Cashfree accepts all payments on your behalf, even if your systems are unavailable, and retries posting to your system later. Recommended if your system has no business logic for declining payments.
* **Accept or reject per transaction**: Your system evaluates and responds to each payment individually. Recommended if you have business logic that requires declining specific payments.


# BBPS for Business
Source: https://www.cashfree.com/docs/api-reference/other-apis/bbps/overview

API reference for Cashfree BBPS for Business covering NPCI-compliant biller API design, transaction status, complaint handling, and onboarding configuration.

The BBPS for Business (Biller Operating Unit, or BOU) APIs provide billers with a structured blueprint to build APIs that meet NPCI standards, enabling seamless onboarding onto the Bharat Bill Payment System (BBPS) network. By following this approach, billers can ensure their APIs align with Cashfree and NPCI requirements, improving workflow success rates and accelerating the onboarding process.

## Key features

Cashfree BBPS for Business supports the following capabilities:

* **NPCI-compliant API design**: Build bill fetch, validation, and payment APIs that meet NPCI standards, ensuring compatibility with the BBPS network.
* **Flexible bill flows**: Supports `FETCH_AND_PAY` and `VALIDATE_AND_PAY` flows based on your biller system's capability.
* **Transaction status checks**: Respond to status queries from the BBPS network to support reconciliation and dispute resolution.
* **Complaint handling**: Handle inbound complaint requests from the network for disputed or failed transactions.
* **Onboarding configuration guidance**: Access NPCI onboarding configurations to correctly set up your biller profile on the BBPS network.

<Tabs>
  <Tab title="Transaction status">
    <div>
      <div>
        <div>
          <h4>Transaction status</h4>

          <div>
            <a href="/docs/api-reference/other-apis/bbps/check-transaction-status">Check transaction status</a>

            <p>
              Check the status of a transaction on the BBPS network for reconciliation and dispute resolution.
            </p>
          </div>
        </div>
      </div>
    </div>
  </Tab>
</Tabs>

## Getting started

Use the following resources to begin your BBPS for Business integration:

<CardGroup>
  <Card title="Product Documentation" icon="book-open" href="/docs/payments/bbps-billers/overview">
    Learn about the BBPS for Business integration model, onboarding requirements, and API design guidelines.
  </Card>

  <Card title="APIs to implement" icon="code" href="/docs/api-reference/other-apis/bbps/apis-to-implement">
    Review the bill fetch and payment posting APIs your biller system must implement for BBPS integration.
  </Card>
</CardGroup>


# Allocate Funds to Virtual Account
Source: https://www.cashfree.com/docs/api-reference/other-apis/oneescrow/allocate-funds-to-virtual-account

post /v1/connected-wallet/recharge
Use this API to recharge the OneEscrow account (notional credit) using a payment instrument.



# Create Virtual Account
Source: https://www.cashfree.com/docs/api-reference/other-apis/oneescrow/create-virtual-account

post /fundsources/connected/virtual-account
Use this API to create a virtual account that helps streamline the management of funds, enhance tracking capabilities, and simplify the financial process.



# Get Fund Source Details
Source: https://www.cashfree.com/docs/api-reference/other-apis/oneescrow/fund-source/get-fund-source-details

get /v1/fundsources/{paymentInstrumentId}
Use this API to get the details of the fund source.



# Get Account Statement
Source: https://www.cashfree.com/docs/api-reference/other-apis/oneescrow/get-account-statement

get /v1/accountStatement
Use this API to fetch the account statement of the virtual account in a paginated format using cursor-based pagination.



# Overview
Source: https://www.cashfree.com/docs/api-reference/other-apis/oneescrow/payouts-v2-apis

Cashfree OneEscrow Payouts V2 APIs simplify endpoint selection, streamline transfers, and reduce integration effort across beneficiary, transfer, and reports.

The version 2 APIs simplifies the process of selecting the correct API for merchants, streamlines transfer APIs, and reduces integration issues:

| API | Description |
| :- | :- |
| [Standard Transfer V2](/docs/api-reference/payouts/v2/transfers-v2/standard-transfer-v2) | Use this API to initiate an amount transfer at Cashfree. It is an async request by default. |
| [Get Transfer Status V2](/docs/api-reference/payouts/v2/transfers-v2/get-transfer-status-v2) | Use this API to get the status of the initiated transfer. You can use either the transfer\_id or cf\_transfer\_id to fetch the details. |
| [Batch Transfer V2](/docs/api-reference/payouts/v2/transfers-v2/batch-transfer-v2) | Use this API to initiate a batch transfer request at Cashfree. You can transfer money to multiple beneficiaries. |
| [Get Batch Transfer Status V2](/docs/api-reference/payouts/v2/transfers-v2/get-batch-transfer-status-v2) | Use this API to get the status of the initiated batch transfer. You can use either the batch\_transfer\_id or cf\_batch\_transfer\_id to fetch the details. |


# Transfer Funds Between VAs
Source: https://www.cashfree.com/docs/api-reference/other-apis/oneescrow/transfer-funds-between-vas

post /v1.2/internalTransfer
Use this API to transfer funds between virtual accounts (VAs).



# Overview
Source: https://www.cashfree.com/docs/api-reference/overview

Browse the Cashfree API reference, covering payments, payouts, identity verification, and platform APIs with sandbox testing and language-specific examples.

Cashfree provides RESTful APIs for payments, transfers, identity verification, and financial solutions. APIs support sandbox testing and production environments determined by your credentials, with consistent authentication, error handling, and multi-language documentation examples.

<CardGroup>
  <Card title="Payments" icon="credit-card" href="/docs/api-reference/payments/overview">
    Accept payments from customers through digital and in-person channels.
  </Card>

  <Card title="Payouts" icon="building-columns" href="/docs/api-reference/payouts/overview">
    Manage company finances through a unified dashboard.
  </Card>

  <Card title="Secure ID" icon="shield-check" href="/docs/api-reference/vrs/overview">
    Verify customer identities using Cashfree's identity verification solutions (PAN, Aadhaar, and more).
  </Card>

  <Card title="Prepaid Payment Instruments" icon="wallet" href="/docs/api-reference/prepaid-payment-instruments/overview">
    Manage digital wallets, sub-wallets, gift cards, and prepaid cards with Cashfree’s PPI APIs.
  </Card>

  <Card title="Partners and Platforms" icon="handshake" href="/docs/api-reference/platforms/overview">
    Embed payments in SaaS applications with Cashfree's embedded payment solutions.
  </Card>

  <Card title="Additional APIs" icon="puzzle-piece" href="/docs/api-reference/other-apis/bbps/overview">
    Access specialised solutions for specific business needs, including BBPS bill payments.
  </Card>
</CardGroup>


# Data to Test Integration
Source: https://www.cashfree.com/docs/api-reference/payments/data-to-test-integration

Use the test card numbers, UPI IDs, netbanking credentials, and OTPs supplied here to validate your Cashfree integration in the sandbox environment.

Use the test data on this page to validate your Cashfree integration before going live. Check [Supported sandbox features](#supported-sandbox-features) to confirm availability before testing.

<CardGroup>
  <Card title="Core payment modes" icon="credit-card" href="#core-payment-modes">
    Test card numbers, netbanking credentials, and UPI VPAs for standard checkout flows.
  </Card>

  <Card title="Third-Party Verification (TPV)" icon="shield-check" href="#third-party-verification-tpv">
    Netbanking and UPI parameter configurations for TPV account validation testing.
  </Card>

  <Card title="Tokenisation and instalment programs" icon="lock" href="#tokenisation-and-instalment-programs">
    Token Vault BINs and credit and debit card EMI test credentials.
  </Card>

  <Card title="Alternative financing options" icon="hand-holding-dollar" href="#alternative-financing-options">
    Mobile numbers and PAN or OTP inputs for Paylater and Cardless EMI testing.
  </Card>
</CardGroup>

## Supported sandbox features

The following table lists the payment modes and functionality available for testing in the sandbox environment.

| Payment mode or feature | Sandbox support status |
| :- | :- |
| Card | Supported. Use the test card details provided below. |
| Netbanking | Supported. Use the test netbanking account provided below. |
| UPI | Supported. Use the test UPI Virtual Payment Addresses (VPAs). |
| Wallet | Supported through a single generic test wallet. Individual wallet providers, such as Paytm or AmazonPay, are not available for testing. |
| Credit and debit card EMI | Supported. Use the test EMI card details. |
| Paylater | Supported. Use the test details provided below. |
| Cardless EMI | Supported for transactions with a minimum amount of `1,000` (INR). |
| Pre-authorisation (API) | Supported for card and UPI modes via the Order Pay `link` channel. |

<Warning>
  The sandbox environment does not support PayPal or bank transfer payment modes at this time.
</Warning>

### Test a pre-authorisation transaction

To test a pre-authorisation transaction, complete the following steps.

1. Create an order with the `order_note` parameter set to `preauth_transaction`.
2. Capture or void the authorised funds using the [Pre-authorisation API](/docs/api-reference/payments/latest/payments/preauthorisation).

## Core payment modes

Use the test card credentials, netbanking simulation account, or UPI addresses below to validate standard checkout flows.

### Test card details

To test card transactions in the sandbox environment, select a card number from the tables below based on the transaction state you want to simulate.

#### Standard successful checkout testing

Use these configurations to simulate successful domestic card payments. For all cards in this table, use `111000` as the OTP, `03/2028` as the fixed expiry, `123` for CVV, and `Test` as the cardholder name.

<Accordion title="View standard successful checkout cards">
  | Scheme | Card type | Card sub-type | Card number 1 | Card number 2 |
  | :- | :- | :- | :- | :- |
  | Visa | Debit | Retail | `4706131211212123` | `4062288312345026` |
  | Visa | Credit | Retail | `4576238912771450` | `4444333322221111` |
  | Visa | Credit | Premium | `4466050254381183` | `4136880012657791` |
  | Visa | Credit | Corporate | `4074970084343075` | `4770355457382883` |
  | Mastercard | Debit | Retail | `5409162669381034` | `5445856839524391` |
  | Mastercard | Credit | Retail | `5105105105105100` | `5176539438527826` |
  | Mastercard | Credit | Premium | `5242535837492075` | `5203860658394375` |
  | Mastercard | Credit | Corporate | `5552190758372734` | `5506908329471983` |
  | Rupay | Debit | Retail | `6074825972083818` | `6074828163369590` |
  | Rupay | Credit | Retail | `6528591234543575` | `65292523412356` |
</Accordion>

#### International and USD scenario testing

Use these configurations to validate cross-border payment routing, currency conversion, subscription flows, and multi-factor bank authentication loops.

<Accordion title="View USD and international scenario cards">
  | Testing scenario | Card number | Expiry | CVV | Cardholder name |
  | :- | :- | :- | :- | :- |
  | Standard USD flow | `7000 0083 1380 6604` | `09/2027` | `581` | `Test` |
  | Standard USD flow | `7000 0091 5369 7715` | `12/2021` | `591` | `Test` |
  | Standard USD flow | `7000 0094 7240 2110` | `05/2024` | `204` | `Test` |
  | Standard USD flow | `7000 0055 0418 0328` | `08/2026` | `324` | `Test` |
  | Standard USD flow | `7000 0014 6659 2972` | `02/2026` | `153` | `Test` |
  | Native bank OTP loop | `4266 9020 7958 3702` | `09/2028` | `681` | `Test` |
  | Recurring subscriptions | `4138 6748 6000 0008` | `01/2027` | `123` | `Test` |
</Accordion>

### Test netbanking

To test netbanking integrations, use the default test bank identifier below.

| Bank name | Payment code | Bank API code |
| :- | :- | :- |
| TEST Bank | `3333` | `TESTR` |

### Test UPI Virtual Payment Addresses (VPAs)

Pass the following test VPAs in your payment request payload to simulate specific transaction outcomes and error states.

<Accordion title="View UPI test VPAs and simulated responses">
  | Virtual Payment Address (VPA) | Simulated transaction response |
  | :- | :- |
  | `testsuccess@gocash` | Simulates a successful transaction. |
  | `testfailure@gocash` | Simulates a failed transaction. |
  | `testinvalid@gocash` | Simulates an invalid VPA error. |
  | `testdeclineuser@gocash` | Simulates a cancellation by the user. The application prompts the user to retry. |
  | `testexpired@gocash` | Simulates a session timeout where the user does not complete the transaction in time. |
  | `testtimeoutbank@gocash` | Simulates an issuing bank timeout. |
  | `testremitterunavailable@gocash` | Simulates an unavailable remitter bank instance. |
  | `testinsufficientfunds@gocash` | Simulates insufficient account funds. |
  | `testbankdeclined@gocash` | Simulates a generic reject response from the user's bank. |
  | `testriskflagged@gocash` | Simulates a transaction rejected due to bank security and risk assessments. |
  | `testnetworkerror@gocash` | Simulates a core network infrastructure failure. |
  | `testinvalidpin@gocash` | Simulates an incorrect PIN entry error. |
  | `testremitterdispatchfailed@gocash` | Simulates a delivery dispatch failure from the remitter bank. |
  | `testbeneficiarytimeout@gocash` | Simulates a timeout failure at the destination beneficiary bank. |
  | `testuserdropped@gocash` | Simulates an unattempted transaction abandonment by the customer. |
  | `testtransactionrisk@gocash` | Simulates a customer risk rejection profile check. |
  | `testfingerprintmismatch@gocash` | Simulates a hardware device biometric or fingerprint mismatch. |
  | `testinvalidvpa@gocash` | Simulates an improperly configured payment instrument. |
  | `testbankriskrejected@gocash` | Simulates an internal banking security policy rejection. |
  | `testremittertimeout@gocash` | Simulates a delayed response from the remitter bank. |
  | `testfraud@gocash` | Simulates an automated anti-fraud block by the payment service provider. |
  | `testvalidationerror@gocash` | Simulates a Third-Party Verification (TPV) account mapping failure. |
  | `testdebitfailed@gocash` | Simulates a failure during the account debit process. |
  | `testpspunregistered@gocash` | Simulates a blocked network state on the client application. |
</Accordion>

<Tip>
  Use the VPA that matches the error state you want to handle in your integration. This helps you verify that your error handling covers each failure mode before going live.
</Tip>

## Third-Party Verification (TPV)

### Test TPV netbanking

Third-Party Verification (TPV) ensures that the funding bank account matches your database records. Use these parameters to simulate a validated netbanking setup.

| Bank parameter | Static testing value |
| :- | :- |
| `accountNumber` | `1111222233` |
| `ifsc` | `TEST0001234` |

### Test TPV UPI

Use these parameters to test account authorisation over the UPI rails.

<Accordion title="View TPV UPI configurations and parameter testing values">
  | Parameter | Testing value |
  | :- | :- |
  | `userVPA` (success) | `testtpvsuccess@gocash` |
  | `userVPA` (fail) | `testtpvfail@gocash` |
  | `accountNumber` | `1111222233` |
  | `ifsc` | `TEST0001234` |
</Accordion>

## Tokenisation and instalment programs

### Token Vault test cards

To build a test card number for Token Vault API configurations, append any random 10-digit sequence to the card BINs below. Expiry can be any future date and CVV any 3-digit number.

<Accordion title="View Token Vault supported card BIN groups">
  | Scheme | Supported card BIN |
  | :- | :- |
  | Visa | `470613, 457623, 436534, 415527, 466535` |
  | Mastercard | `559423, 544405, 533983, 555219, 524877` |
</Accordion>

### Credit card EMI test cards

Use the following credit cards to validate EMI calculations and processing endpoints. Expiry can be any future date and CVV any 3-digit number.

<Accordion title="View credit card EMI identifiers and testing credentials">
  | Issuing bank | Bank card parameter name (`card_bank_name`) | Card number |
  | :- | :- | :- |
  | Axis Bank | Axis | `4111 4647 7655 4152` |
  | Standard Chartered Bank | Standard Chartered | `4622 7185 3202 3725` |
  | ICICI Bank | ICICI | `4748 4661 2346 7526` |
  | Kotak Bank | Kotak | `4363 9070 5531 5237` |
  | HDFC Bank | HDFC | `5241 8100 0000 0000` |
  | RBL Bank | RBL | `4112 5597 3537 3674` |
  | Bank of Baroda | BOB | `4111 5638 8133 3699` |
  | AU Bank | AU | `4111 5849 6705 0056` |
  | Citi Bank | CITI | `4112 5229 6265 9579` |
  | Yes Bank | YES | `4111 6514 1790 3257` |
  | IndusInd Bank | INDUS | `4111 5351 6094 6904` |
  | HSBC Bank | HSBC | `4111 6668 0832 0291` |
  | Federal Bank | FED | `4111 5924 7037 2263` |
</Accordion>

### Debit card EMI test cards

Use this configuration to test debit card EMI processing.

| Issuing bank | Bank card parameter name (`card_bank_name`) | Card number |
| :- | :- | :- |
| HDFC Bank | HDFC | `4386 2412 2321 5159` |

## Alternative financing options

### Paylater integration details

To test standard Paylater partner platforms, use the registered mobile number below.

| Provider instance | Registered mobile number |
| :- | :- |
| Any | `8714268343` |

### Cardless EMI integration details

Use the following mobile number to simulate user registration states for Cardless EMI options.

| Provider instance | Registered mobile number | Required input parameters |
| :- | :- | :- |
| Any | `8714268343` | If prompted for **PAN**, use `1234`.<br />If prompted for **OTP**, use `777777`. |

<Note>
  Complete all integration testing in the sandbox environment before deploying to production. For broader recommendations on building reliable integrations, see [API best practices](/docs/api-reference/api-best-practices).
</Note>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/payments/overview">Payments Overview</a></li>
    <li><a href="/docs/api-reference/integration-troubleshooting/payments-ts">Payments API troubleshooting</a></li>
    <li><a href="/docs/api-reference/api-best-practices">API best practices</a></li>
  </ul>
</div>


# Enums Reference
Source: https://www.cashfree.com/docs/api-reference/payments/enums

Look up enum values in the Cashfree API, covering order states, payment states, net banking codes, wallet codes, and EMI codes.

An enum (enumeration) is a data type that restricts a field to a specific set of
predefined string values. The Cashfree API uses enums across requests and
responses to ensure that only valid, expected values are accepted or returned for a
given field.

The following are some examples of enum fields in the Cashfree API:

* The `order_status` field returns one of `ACTIVE`, `PAID`, `EXPIRED`, or
  `TERMINATED`, never a free-form string.
* The `payment_status` field returns one of `SUCCESS`, `FAILED`, `PENDING`,
  `CANCELLED`, and others.
* Net banking and wallet codes are fixed numeric identifiers mapped to specific
  providers.

Because enum values are fixed and predictable, you can use them directly in
conditional logic, error handling, and status checks without accounting for
unexpected values.

## Order states

Order states represent the current status of an order throughout its lifecycle,
from creation to a terminal state such as paid or expired. Use these values to
determine whether an order is still open for payment or has reached a final state.

<Accordion title="Order states">
  An order moves through the following states based on payment outcomes and
  merchant actions.

  | Order State | Description |
  | :- | :- |
  | ACTIVE | Orders are marked as **ACTIVE**, when an order is created by the merchant through an API request to Cashfree. |
  | PAID | Orders are marked **PAID** when the payment is verified by Cashfree and the payment is successful. |
  | EXPIRED | Orders are marked as **EXPIRED** when the order has exceeded `order_expiry_time` specified by merchant to complete the order. |
  | TERMINATED | This status is returned when you request order termination through the [Order Termination API](/docs/api-reference/payments/latest/orders/terminate-order). Once terminated, customers can no longer pay for this order. |
  | TERMINATION\_REQUESTED | This status is returned after you call the [Order Termination API](/docs/api-reference/payments/latest/orders/terminate-order) to end an order. The termination request is acknowledged but still processing. Orders can only be terminated when all transactions have reached terminal states. If a pending transaction completes successfully while termination is processing, the status will change from **TERMINATION\_REQUESTED** to **SUCCESS**. |
</Accordion>

## Payment states

Payment states indicate the status of an individual payment attempt within an
order. An order can have multiple payment attempts, and each attempt progresses
through its own states before reaching a terminal outcome such as `SUCCESS`
or `FAILED`.

<Accordion title="Payment states">
  Each payment attempt within an order has its own lifecycle. Use these states
  to handle granular payment scenarios.

  | Payment State | Description | Remarks |
  | :- | :- | :- |
  | SUCCESS | Transaction is successful and the amount is captured. | Terminal state. Once successful, the order moves to **PAID**. |
  | FAILED | Transaction failed due to bank, customer, or system issues. | Terminal state. Customers can initiate a new attempt. |
  | NOT\_ATTEMPTED | Transaction is created but acknowledgement from the bank is awaited. | Initial state for a payment attempt. |
  | PENDING | Request is sent to the bank and a response is awaited. | Non-terminal state. Do not fulfil orders in this state. |
  | FLAGGED | Transaction is identified as high-risk and requires review. | Merchant must manually approve or reject the payment. |
  | CANCELLED | Amount is reversed because a success response arrived after the time to live (TTL). | Automatic system reversal for late confirmations. |
  | VOID | Transaction amount is not captured by explicit request. | Typically used for pre-authorised card payments or UPI mandates. |
  | USER\_DROPPED | Customer abandoned the payment flow before completion. | Includes closing the app or OTP page without attempting payment. |
</Accordion>

## Net banking codes

Net banking codes identify the supported net banking providers. Pass the
**Bank Code** value in the `payment_method` parameter of your API request to
initiate a net banking transaction.

The **TPV Supported** column indicates whether the bank supports Third Party
Validation (TPV). When TPV is enabled, Cashfree verifies that the
customer completes the payment from the specific bank account provided during
order creation.

<Accordion title="Netbanking codes">
  The following table lists the supported banks and their corresponding codes
  for net banking integrations.

  | Bank name | Bank code | TPV supported |
  | - | - | - |
  | Airtel Payments Bank | 3123 | N |
  | Andhra Pragathi Grameena Bank | 3094 | N |
  | AU Small Finance Bank | 3087 | Y |
  | Axis Bank | 3003 | Y |
  | Axis Bank - Corporate | 3071 | N |
  | Bandhan Bank - Retail Banking | 3088 | Y |
  | Bank of Bahrain and Kuwait | 3095 | N |
  | Bank of Baroda - Corporate | 3060 | Y |
  | Bank of Baroda - Retail Banking | 3005 | Y |
  | Bank of India | 3006 | Y |
  | Bank of India - Corporate | 3061 | Y |
  | Bank of Maharashtra | 3007 | N |
  | Barclays - Corporate | 3080 | N |
  | Canara Bank | 3009 | Y |
  | Capital Small Finance Bank | 3098 | Y |
  | Central Bank of India | 3011 | N |
  | City Union Bank | 3012 | Y |
  | City Union Bank - Corporate | 3083 | Y |
  | Cosmos Bank | 3097 | Y |
  | CSB Bank Limited | 3010 | Y |
  | DBS Bank Ltd | 3017 | N |
  | DCB Bank - Retail | 3018 | Y |
  | Deutsche Bank | 3016 | Y |
  | Dhanlakshmi Bank | 3019 | Y |
  | Dhanlaxmi Bank - Corporate | 3072 | N |
  | Equitas Small Finance Bank | 3076 | N |
  | ESAF Small Finance Bank | 3100 | N |
  | Federal Bank | 3020 | Y |
  | Fincare Bank | 3101 | N |
  | Gujarat State Co-operative Bank Limited | 3091 | N |
  | HDFC Bank | 3021 | Y |
  | HDFC Corporate | 3084 | N |
  | HSBC Retail NetBanking | 3092 | Y |
  | ICICI Bank | 3022 | Y |
  | ICICI Bank - Corporate | 3073 | N |
  | IDBI Bank | 3023 | Y |
  | IDBI Bank - Corporate | 3124 | Y |
  | IDFC FIRST Bank | 3024 | Y |
  | Indian Bank | 3026 | Y |
  | Indian Overseas Bank | 3027 | Y |
  | Indian Overseas Bank - Corporate | 3081 | Y |
  | IndusInd Bank | 3028 | Y |
  | Jammu and Kashmir Bank | 3029 | Y |
  | Jana Small Finance Bank | 3102 | Y |
  | Janata Sahakari Bank Ltd Pune | 3104 | N |
  | Kalyan Janata Sahakari Bank | 3105 | N |
  | Karnataka Bank Ltd | 3030 | Y |
  | Karnataka Gramin Bank | 3113 | N |
  | Karnataka Vikas Grameena Bank | 3107 | N |
  | Karur Vysya Bank | 3031 | Y |
  | Kotak Mahindra Bank | 3032 | Y |
  | Kotak Mahindra Bank - Corporate | 3134 | Y |
  | Maharashtra Gramin Bank | 3108 | N |
  | Mehsana urban Co-op Bank | 3109 | N |
  | NKGSB Co-op Bank | 3111 | N |
  | Nutan Nagarik Sahakari Bank Limited | 3112 | N |
  | Punjab & Sind Bank | 3037 | Y |
  | Punjab National Bank - Corporate | 3065 | N |
  | Punjab National Bank - Retail Banking | 3038 | Y |
  | RBL Bank | 3039 | Y |
  | RBL Bank Limited - Corporate | 3114 | N |
  | Saraswat Bank | 3040 | Y |
  | SBM Bank India | 3115 | Y |
  | Shamrao Vithal Bank - Corporate | 3075 | N |
  | Shamrao Vitthal Co-operative Bank | 3041 | N |
  | Shivalik Small Finance Bank | 3086 | Y |
  | South Indian Bank | 3042 | Y |
  | Standard Chartered Bank | 3043 | Y |
  | State Bank Of India | 3044 | Y |
  | State Bank of India - Corporate | 3066 | Y |
  | Suryoday Small Finance Bank | 3116 | N |
  | Tamil Nadu State Co-operative Bank | 3051 | N |
  | Tamilnad Mercantile Bank Ltd | 3052 | Y |
  | Thane Bharat Sahakari Bank Ltd | 3118 | N |
  | The Kalupur Commercial Co-Operative Bank | 3106 | N |
  | The Surat Peoples Co-operative Bank Limited | 3090 | Y |
  | The Sutex Co-op Bank Ltd | 3117 | Y |
  | TJSB Bank | 3119 | N |
  | UCO Bank | 3054 | Y |
  | UCO Bank Corporate | 3122 | N |
  | Ujjivan Small Finance Bank | 3126 | Y |
  | Union Bank of India | 3055 | Y |
  | Union Bank of India - Corporate | 3067 | Y |
  | Utkarsh Small Finance Bank | 3089 | Y |
  | Varachha Co-operative Bank Limited | 3120 | N |
  | Yes Bank - Corporate | 3077 | N |
  | Yes Bank Ltd | 3058 | Y |
  | Zoroastrian Co-Operative Bank Ltd | 3121 | N |
</Accordion>

## Wallet codes

Wallet codes identify the supported digital wallet providers. Pass the
**Payment Code** value in your API request to collect payments via a
specific wallet.

<Accordion title="Wallet codes">
  The following table lists the available wallet providers and their
  corresponding payment codes.

  | S. No | Wallet name | Payment code |
  | :- | :- | :- |
  | 1 | FreeCharge | 4001 |
  | 2 | MobiKwik | 4002 |
  | 3 | Ola Money | 4003 |
  | 4 | Airtel Money | 4006 |
  | 5 | Amazon Pay | 4008 |
  | 6 | PayTM | 4007 |
  | 7 | PhonePe | 4009 |
  | 8 | Test Wallet (Sandbox) | 4010 |
</Accordion>

## EMI codes

Equated Monthly Instalment (EMI) codes specify the available instalment plans
for supported banks and card types. Use these values to present EMI options to
customers during checkout.

The following attributes apply across all EMI plan tables:

* **card\_bank\_name**: The bank identifier to pass in the API request parameter.
* **Tenure**: The duration of the instalment plan, expressed in months.
* **Annual interest rate**: The yearly interest rate applied to the
  transaction amount, expressed as a percentage.

<Tip>
  Verify that the transaction amount falls within the **Minimum amount** and
  **Maximum amount** range specified for the selected plan and tenure before
  making the API request.
</Tip>

<Tabs>
  <Tab title="Credit card EMI">
    Credit card EMI lets customers split a large payment into fixed monthly
    instalments charged to their credit card. This is the most widely supported
    EMI type and is available across major Indian banks.

    <Accordion title="Credit card EMI codes">
      The following table lists the supported banks, interest rates, and tenures
      available for credit card EMI.

      | Card type | Type of EMI | Bank | card\_bank\_name | Minimum amount | Maximum amount | Annual interest rate | Tenure |
      | - | - | - | - | - | - | - | - |
      | Credit | Standard | ICICI Bank | icici | 1500 | 9999999 | 15.99 | 3 |
      | Credit | Standard | ICICI Bank | icici | 1500 | 9999999 | 15.99 | 6 |
      | Credit | Standard | ICICI Bank | icici | 1500 | 9999999 | 15.99 | 9 |
      | Credit | Standard | ICICI Bank | icici | 1500 | 9999999 | 15.99 | 12 |
      | Credit | Standard | ICICI Bank | icici | 1500 | 9999999 | 15.99 | 18 |
      | Credit | Standard | ICICI Bank | icici | 1500 | 9999999 | 15.99 | 24 |
      | Credit | Standard | AU Small Finance Bank | au | 2000 | - | 14 | 3 |
      | Credit | Standard | AU Small Finance Bank | au | 2000 | - | 14 | 6 |
      | Credit | Standard | AU Small Finance Bank | au | 2000 | - | 14 | 9 |
      | Credit | Standard | AU Small Finance Bank | au | 2000 | - | 14 | 12 |
      | Credit | Standard | AU Small Finance Bank | au | 2000 | - | 14 | 18 |
      | Credit | Standard | AU Small Finance Bank | au | 2000 | - | 14 | 24 |
      | Credit | Standard | Axis Bank | axis | 2500 | 1000000 | 17 | 3 |
      | Credit | Standard | Axis Bank | axis | 2500 | 1000000 | 17 | 6 |
      | Credit | Standard | Axis Bank | axis | 2500 | 1000000 | 17 | 9 |
      | Credit | Standard | Axis Bank | axis | 2500 | 1000000 | 17 | 12 |
      | Credit | Standard | Axis Bank | axis | 2500 | 1000000 | 17 | 18 |
      | Credit | Standard | Axis Bank | axis | 2500 | 1000000 | 17 | 24 |
      | Credit | Standard | Bank of Baroda | bob | 2500 | - | 16 | 3 |
      | Credit | Standard | Bank of Baroda | bob | 2500 | - | 16 | 6 |
      | Credit | Standard | Bank of Baroda | bob | 2500 | - | 16 | 9 |
      | Credit | Standard | Bank of Baroda | bob | 2500 | - | 16 | 12 |
      | Credit | Standard | Bank of Baroda | bob | 2500 | - | 16 | 18 |
      | Credit | Standard | Bank of Baroda | bob | 2500 | - | 16 | 24 |
      | Credit | Standard | Bank of Baroda | bob | 2500 | - | 16 | 36 |
      | Credit | Standard | RBL Bank | rbl | 2500 | - | 14 | 3 |
      | Credit | Standard | RBL Bank | rbl | 2500 | - | 14 | 6 |
      | Credit | Standard | RBL Bank | rbl | 2500 | - | 15 | 9 |
      | Credit | Standard | RBL Bank | rbl | 2500 | - | 15 | 12 |
      | Credit | Standard | RBL Bank | rbl | 2500 | - | 15 | 18 |
      | Credit | Standard | RBL Bank | rbl | 2500 | - | 15 | 24 |
      | Credit | Standard | Standard Chartered | standard chartered | 2000 | - | 11.88 | 3 |
      | Credit | Standard | Standard Chartered | standard chartered | 2000 | - | 14 | 6 |
      | Credit | Standard | Standard Chartered | standard chartered | 2000 | - | 15 | 9 |
      | Credit | Standard | Standard Chartered | standard chartered | 2000 | - | 15 | 12 |
      | Credit | Standard | Standard Chartered | standard chartered | 2000 | - | 15 | 18 |
      | Credit | Standard | Standard Chartered | standard chartered | 2000 | - | 15 | 24 |
      | Credit | Standard | Yes Bank | yes | 1500 | 999999999 | 16 | 3 |
      | Credit | Standard | Yes Bank | yes | 1500 | 999999999 | 16 | 6 |
      | Credit | Standard | Yes Bank | yes | 1500 | 999999999 | 16 | 9 |
      | Credit | Standard | Yes Bank | yes | 1500 | 999999999 | 16 | 12 |
      | Credit | Standard | Yes Bank | yes | 1500 | 999999999 | 16 | 18 |
      | Credit | Standard | Yes Bank | yes | 1500 | 999999999 | 16 | 24 |
      | Credit | Standard | American Express | amex | 5000 | - | 14 | 3 |
      | Credit | Standard | American Express | amex | 5000 | - | 14 | 6 |
      | Credit | Standard | American Express | amex | 5000 | - | 14 | 9 |
      | Credit | Standard | American Express | amex | 5000 | - | 14 | 12 |
      | Credit | Standard | American Express | amex | 5000 | - | 15 | 18 |
      | Credit | Standard | American Express | amex | 5000 | - | 15 | 24 |
      | Credit | Standard | HDFC Bank | hdfc | 1000 | 999000 | 18 | 3 |
      | Credit | Standard | HDFC Bank | hdfc | 1000 | 999000 | 17 | 6 |
      | Credit | Standard | HDFC Bank | hdfc | 1000 | 999000 | 17 | 9 |
      | Credit | Standard | HDFC Bank | hdfc | 1000 | 999000 | 17 | 12 |
      | Credit | Standard | HDFC Bank | hdfc | 1000 | 999000 | 17 | 18 |
      | Credit | Standard | HDFC Bank | hdfc | 1000 | 999000 | 17 | 24 |
      | Credit | Standard | HDFC Bank | hdfc | 1000 | 999000 | 17 | 36 |
      | Credit | Standard | HDFC Bank | hdfc | 1000 | 999000 | 17 | 48 |
      | Credit | Standard | Kotak Mahindra Bank | kotak | 1000 | - | 16 | 3 |
      | Credit | Standard | Kotak Mahindra Bank | kotak | 2500 | - | 16 | 6 |
      | Credit | Standard | Kotak Mahindra Bank | kotak | 2500 | - | 16 | 9 |
      | Credit | Standard | Kotak Mahindra Bank | kotak | 2500 | - | 16 | 12 |
      | Credit | Standard | Kotak Mahindra Bank | kotak | 2500 | - | 16 | 18 |
      | Credit | Standard | Kotak Mahindra Bank | kotak | 2500 | - | 16 | 20 |
      | Credit | Standard | Kotak Mahindra Bank | kotak | 2500 | - | 16 | 24 |
      | Credit | Standard | Kotak Mahindra Bank | kotak | 2500 | - | 16 | 30 |
      | Credit | Standard | Kotak Mahindra Bank | kotak | 2500 | - | 16 | 36 |
      | Credit | Standard | SBI | sbi | 2500 | - | 17.25 | 3 |
      | Credit | Standard | SBI | sbi | 2500 | - | 17.00 | 6 |
      | Credit | Standard | SBI | sbi | 2500 | - | 17.00 | 9 |
      | Credit | Standard | SBI | sbi | 2500 | - | 17.00 | 12 |
      | Credit | Standard | SBI | sbi | 2500 | - | 17.00 | 18 |
      | Credit | Standard | SBI | sbi | 2500 | - | 17.00 | 24 |
      | Credit | Standard | IDFC Bank | idfc | 1500 | - | 16 | 3 |
      | Credit | Standard | IDFC Bank | idfc | 1500 | - | 16 | 6 |
      | Credit | Standard | IDFC Bank | idfc | 1500 | - | 16 | 9 |
      | Credit | Standard | IDFC Bank | idfc | 1500 | - | 16 | 12 |
      | Credit | Standard | IDFC Bank | idfc | 1500 | - | 16 | 18 |
      | Credit | Standard | IDFC Bank | idfc | 1500 | - | 16 | 24 |
      | Credit | Standard | IDFC Bank | idfc | 1500 | - | 16 | 36 |
      | Credit | Standard | IndusInd Bank | indus | 2000 | - | 17 | 3 |
      | Credit | Standard | IndusInd Bank | indus | 2000 | - | 16 | 6 |
      | Credit | Standard | IndusInd Bank | indus | 2000 | - | 16 | 9 |
      | Credit | Standard | IndusInd Bank | indus | 2000 | - | 16 | 12 |
      | Credit | Standard | IndusInd Bank | indus | 2000 | - | 16 | 18 |
      | Credit | Standard | IndusInd Bank | indus | 2000 | - | 16 | 24 |
      | Credit | Standard | IndusInd Bank | indus | 2000 | - | 16 | 36 |
    </Accordion>
  </Tab>

  <Tab title="Debit card EMI">
    Debit card EMI allows customers to pay in monthly instalments without a credit
    card. The bank determines eligibility based on the customer's account history.

    <Accordion title="Debit card EMI codes">
      The following bank and plans are currently supported for debit card EMI.
      The **Native OTP** column indicates whether the bank handles OTP
      verification directly.

      | Bank name | Native OTP |
      | :- | :- |
      | HDFC Bank | Yes |

      #### Debit card EMI plans

      | Card type | Type of EMI | Bank | card\_bank\_name | Minimum amount | Maximum amount | Annual interest rate | Tenure |
      | - | - | - | - | - | - | - | - |
      | Debit | Standard | HDFC Bank | hdfc | 3000 | 400000 | 16 | 3 |
      | Debit | Standard | HDFC Bank | hdfc | 3000 | 400000 | 16 | 6 |
      | Debit | Standard | HDFC Bank | hdfc | 3000 | 400000 | 16 | 9 |
      | Debit | Standard | HDFC Bank | hdfc | 3000 | 400000 | 16 | 12 |
      | Debit | Standard | HDFC Bank | hdfc | 3000 | 400000 | 16 | 18 |
      | Debit | Standard | HDFC Bank | hdfc | 3000 | 400000 | 16 | 24 |
      | Debit | Standard | HDFC Bank | hdfc | 3000 | 400000 | 16 | 36 |
      | Debit | Standard | HDFC Bank | hdfc | 3000 | 400000 | 16 | 48 |
    </Accordion>
  </Tab>

  <Tab title="Cardless EMI">
    Cardless EMI allows customers to pay in instalments without a physical card.
    Financing is provided by partner banks or Non-Banking Financial Companies (NBFCs).

    <Accordion title="Cardless EMI codes">
      The following table lists the supported cardless EMI providers, interest
      rates, and available tenures.

      | Card type | Type of EMI | Bank | provider | Minimum amount | Maximum amount | Annual interest rate | Tenure |
      | - | - | - | - | - | - | - | - |
      | Cardless | Standard | HDFC Bank | hdfc | 3000 | 500000 | 16 | 3 |
      | Cardless | Standard | HDFC Bank | hdfc | 5000 | 500000 | 16 | 6 |
      | Cardless | Standard | HDFC Bank | hdfc | 5000 | 500000 | 16 | 9 |
      | Cardless | Standard | HDFC Bank | hdfc | 5000 | 500000 | 16 | 12 |
      | Cardless | Standard | HDFC Bank | hdfc | 5000 | 500000 | 16 | 18 |
      | Cardless | Standard | HDFC Bank | hdfc | 5000 | 500000 | 16 | 24 |
      | Cardless | Standard | ICICI Bank | icici | 7000 | 500000 | 18 | 3 |
      | Cardless | Standard | ICICI Bank | icici | 7000 | 500000 | 18 | 6 |
      | Cardless | Standard | ICICI Bank | icici | 7000 | 500000 | 18 | 9 |
      | Cardless | Standard | ICICI Bank | icici | 7000 | 500000 | 18 | 12 |
      | Cardless | Standard | IDFC Bank | idfc | 5000 | 60000 | 24 | 3 |
      | Cardless | Standard | IDFC Bank | idfc | 5000 | 60000 | 24 | 6 |
      | Cardless | Standard | IDFC Bank | idfc | 5000 | 60000 | 24 | 9 |
      | Cardless | Standard | IDFC Bank | idfc | 5000 | 60000 | 24 | 12 |
      | Cardless | Standard | LazyPay | lazypay | 3000 | 100000 | 20 | 3 |
      | Cardless | Standard | LazyPay | lazypay | 3000 | 100000 | 20 | 6 |
      | Cardless | Standard | LazyPay | lazypay | 3000 | 100000 | 20 | 9 |
      | Cardless | Standard | LazyPay | lazypay | 3000 | 100000 | 20 | 12 |
      | Cardless | Standard | TVS Credit | tvs | 3000 | 50000 | 22 | 3 |
      | Cardless | Standard | TVS Credit | tvs | 3000 | 50000 | 22 | 6 |
      | Cardless | Standard | TVS Credit | tvs | 3000 | 50000 | 27 | 9 |
      | Cardless | Standard | TVS Credit | tvs | 3000 | 50000 | 27 | 12 |
      | Cardless | Standard | TVS Credit | tvs | 3000 | 50000 | 27 | 15 |
      | Cardless | Standard | TVS Credit | tvs | 3000 | 50000 | 27 | 18 |
      | Cardless | Standard | TVS Credit | tvs | 3000 | 50000 | 27 | 24 |
      | Cardless | Standard | Home Credit | homecredit | 4000 | 75000 | 25 | 3 |
      | Cardless | Standard | Home Credit | homecredit | 4000 | 75000 | 25 | 6 |
      | Cardless | Standard | ZestMoney | zestmoney | 3000 | 200000 | 20 | 3 |
      | Cardless | Standard | ZestMoney | zestmoney | 3000 | 200000 | 24.90 | 6 |
      | Cardless | Standard | ZestMoney | zestmoney | 3000 | 200000 | 24.90 | 9 |
    </Accordion>
  </Tab>

  <Tab title="Pay later">
    Pay later providers extend a short-term line of credit to customers, allowing
    them to complete a purchase immediately and pay the amount, in full or in
    instalments, at a later date.

    <Accordion title="Pay later codes">
      The following table lists the supported pay later providers and the
      corresponding parameter values to use in API requests.

      | Provider parameter | Name of the provider |
      | :- | :- |
      | lazypay | LazyPay (applicable for orders with a minimum value of ₹100 and a maximum value of ₹5,000) |
    </Accordion>
  </Tab>
</Tabs>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/payments/latest/orders/create-order">Create Order API</a></li>
    <li><a href="/docs/api-reference/payments/latest/orders/get-order">Get Order API</a></li>
    <li><a href="/docs/api-reference/payments/latest/payments/get">Get Payment API</a></li>
    <li><a href="/docs/payments/webhooks">Webhooks</a></li>
  </ul>
</div>


# Errors
Source: https://www.cashfree.com/docs/api-reference/payments/errors

Understand the Cashfree API error structure, common HTTP status codes, and merchant-specific error codes you can handle programmatically.

## Error structure

The Payment Gateway response in case of an error includes the following:

* **error\_code**: Code associated with every error.
* **error\_description**: Description of the error.
* **error\_source**: Source of the error.
* **error\_reason**: Failure reason.

**Sample error response from API**:

```json theme={"dark"}
{
  "message": "bad URL, please check API documentation",
  "help": "Check latest errors and resolution from Merchant Dashboard API logs: https://bit.ly/4glEd0W Help Document: https://bit.ly/4eeZYO9",
  "code": "request_failed",
  "type": "invalid_request_error"
}
```

**Sample error response from webhook**:

```json theme={"dark"}
{
    "auth_id": null,
    "authorization": null,
    "bank_reference": "306118259130",
    "cf_payment_id": 1636676360,
    "entity": "payment",
    "error_details": {
        "error_code": "TRANSACTION_DECLINED",
        "error_description": "transaction is rejected at the remitter bank end. Please reach out to issuer bank",
        "error_reason": "bank_rejected",
        "error_source": "bank"
    },
    "is_captured": false,
    "order_amount": 1.00,
    "order_id": "order_18482MSWq8prPMOW0jTeGsx0B1JmPC1",
    "payment_amount": 1.00,
    "payment_completion_time": "2023-03-02T18:24:51+05:30",
    "payment_currency": "INR",
    "payment_group": "upi",
    "payment_message": "01::REJECTED",
    "payment_method": {
        "upi": {
            "channel": "collect",
            "upi_id": "8XXXXXXXX2@upi"
        }
    },
    "payment_status": "FAILED",
    "payment_time": "2023-03-02T18:24:18+05:30"
}
```

***

## List of error types and error codes

Below are the error types and error codes with their descriptions.

### Error types

| error\_type | description |
| - | - |
| `api_connection_error` | Network communication issue with API server. |
| `api_error` | General server error during request processing. |
| `authentication_error` | Invalid or missing authentication credentials. |
| `invalid_request_error` | Request is malformed or has invalid parameters. |
| `feature_not_enabled` | Requested feature is not enabled for the account. |
| `rate_limit_error` | Too many requests sent in a short time. |
| `validation_error` | Request failed validation checks. |
| `idempotency_error` | Repeated request with same idempotency key caused conflict. |
| `bad_gateway_error` | Received invalid response from upstream server. |

### Error codes

| error\_code | description |
| - | - |
| `card_unsupported` | Card type not supported by payment system. |
| `payment_method_unsupported` | Payment method not accepted for this transaction. |
| `surcharge_invalid` | Surcharge amount is missing, incorrect, or not allowed. |
| `payment_gateway_unsupported` | Selected payment gateway is not supported. |
| `card_submission_disabled` | Card submission is currently disabled or blocked. |
| `order_amount_invalid` | Order amount is missing, negative, or exceeds limits. |
| `order_inactive` | Order is no longer active or has expired. |
| `customer_email_invalid` | Customer email is missing or incorrectly formatted. |
| `version_invalid` | Provided API version is not supported or malformed. |
| `order_token_invalid` | Order token is missing, expired, or incorrect. |
| `sub_session_id_invalid` | Sub-session ID is missing or invalid. |
| `payment_session_id_invalid` | Payment session ID is missing or does not exist. |
| `native_otp_session_id_invalid` | Native OTP session ID is invalid or expired. |
| `flash_upi_auth_token_invalid` | Flash UPI auth token is invalid or expired. |
| `cookie_invalid` | Session cookie is missing, expired, or malformed. |
| `order_id_invalid` | Order ID is incorrect, missing, or unrecognised. |
| `order_expiry_time_invalid` | Order expiry time is missing, invalid, or in past. |
| `order_id_not_paid` | Order ID exists, but payment was not completed. |
| `order_id_voided` | Order was voided and cannot be processed further. |
| `refund_amount_invalid` | Refund amount is missing, invalid, or exceeds original payment. |
| `refund_id_invalid` | Refund ID is missing, incorrect, or unrecognised. |
| `netbanking_bank_code_invalid` | Invalid or unsupported netbanking bank code provided. |
| `payment_method_invalid` | Specified payment method is invalid or not recognised. |
| `refund_invalid` | Refund cannot be processed due to invalid conditions. |
| `vendor_id_invalid` | Vendor ID is missing, malformed, or not recognised. |
| `payment_gateway_inactive` | Payment gateway is inactive or unavailable. |
| `customer_phone_invalid` | Customer phone number is missing or incorrectly formatted. |
| `partner_apikey_invalid` | Partner API key is missing, invalid, or unauthorised. |
| `payment_amount_invalid` | Payment amount is missing, negative, or incorrectly formatted. |
| `refund_unsupported` | Refund operation is unsupported for this payment type. |
| `order_already_paid` | Order has already been paid successfully. |
| `bank_processing_failure` | Bank failed to process the payment request. |
| `api_request_timeout` | API request timed out before completion. |
| `sdk_token_invalid` | SDK token is invalid or malformed. |
| `sdk_token_unknown` | Unknown SDK token provided in the request. |
| `simulation_id_invalid` | Simulation ID is invalid or does not exist. |
| `entity_id_invalid` | Entity ID is incorrect, missing, or unrecognised. |
| `entity_unsupported` | Entity type is not supported for this operation. |
| `simulation_id_missing` | Simulation ID is required but missing in request. |
| `subscription_id_missing` | Subscription ID is required but missing. |
| `payment_id_missing` | Payment ID is missing or not found. |
| `plan_id_missing` | Plan ID is missing, invalid, or not found. |
| `refund_id_missing` | Refund ID is required but missing. |
| `PaymentForm_form_creation_failed` | Failed to create payment form due to internal error. |
| `PaymentForm_link_creation_failed` | Failed to create payment link due to system issue. |
| `order_already_exists` | Order already exists with the given ID or details. |
| `orderpay_already_exists` | OrderPay object already exists for this order. |
| `order_id_already_exists` | Order ID already exists and cannot be duplicated. |
| `domain_name_refererString` | Invalid or unapproved domain name in referer header. |
| `android_package_{xRequestedWith}` | Invalid or unrecognised Android package name in request. |
| `refType_not_approved` | Referenced entity is not approved for this operation. |
| `refType_ineligible` | Referenced entity is not eligible for this operation. |
| `payment_gateway_inactive_request_failed` | Payment gateway inactive; request could not be completed. |
| `subscription_id_missing_request_failed_failed` | Subscription ID missing; request failed. |
| `simulation_id_missing_request_failed_failed` | Simulation ID missing; request failed. |
| `cod_eligibility_failed` | COD eligibility check failed for this order. |
| `Paymentlink_create_failed` | Failed to create payment link due to internal issue. |
| `headless_otp_submit_request_failed` | OTP submission failed during headless authentication flow. |
| `order_creation_faied` | Order creation failed due to validation or server error. |
| `pan_submit_failed` | PAN submission failed due to invalid data or server error. |
| `gstin_submit_failed` | GSTIN submission failed due to incorrect or missing data. |
| `cin_submit_failed` | CIN submission failed due to invalid or missing data. |
| `risk_data_ip_address_request_failed` | IP address risk check failed during request processing. |
| `cart_create_failed` | Cart creation failed due to invalid input or server issue. |
| `order_create_failed` | Order creation failed; please retry or check input data. |
| `order_pay_failed` | Order payment attempt failed due to processing error. |
| `refund_post_failed` | Refund request failed to post due to system error. |
| `link_post_failed` | Failed to post link request to server. |
| `api_request_failed` | API request failed due to timeout or internal error. |
| `form_post_failed` | Form submission failed due to validation or processing error. |
| `aadhar_otp_generation_failed` | Aadhaar OTP generation failed during identity verification. |
| `aadhar_otp_verification_failed` | Aadhaar OTP verification failed or expired. |
| `pan_verification_failed` | PAN verification failed due to a mismatch or system error. |
| `bank_account_verification_failed` | Bank account verification failed due to invalid input. |
| `otp_generation_failed` | OTP generation failed due to rate limits or server error. |
| `otp_expired_failed` | OTP has expired; please request a new one. |
| `otp_invalid_failed` | OTP is invalid or does not match. |
| `ref_id_invalid_failed` | Reference ID is invalid or not found. |
| `shipping_fetch_failed` | Shipping info fetch failed due to network or service error. |
| `entity_simulation_payment_error_code_failed` | Entity simulation failed during payment processing. |
| `gst_verification_failed` | GST verification failed due to incorrect or unverified GSTIN. |
| `offer_not_found` | Offer not found or does not exist. |
| `customer_get_not_found` | Customer not found with given details. |
| `payment_not_found` | Payment record not found for provided ID. |
| `payment_post_not_found` | Payment request failed; resource not found. |
| `entityId_not_found` | Entity ID not found or unrecognised. |
| `order_get_not_found` | Order not found for given ID. |
| `cart_get_not_found` | Cart not found for current session or ID. |
| `orderpay_post_not_found` | OrderPay request not found or already processed. |
| `card_alias_not_found` | Card alias not found or invalid. |
| `cardbin_details_not_found` | Card BIN details not available or missing. |
| `card_not_found` | Card not found or does not exist. |
| `order_id_post_not_found` | Order ID not found in post request. |
| `modeRates_get_not_found` | Mode rate information not available or missing. |
| `refund_get_not_found` | Refund information not found for provided ID. |
| `transaction_get_not_found` | Transaction details not found or unavailable. |
| `settlement_get_not_found` | Settlement not found for provided identifier. |
| `link_get_not_found` | Payment link not found or deleted. |
| `merchant_get_not_found` | Merchant account not found or unregistered. |
| `terminal_id_post_not_found` | Terminal ID not found in post request. |
| `resource_post_not_found` | Resource not found during post request. |
| `terminal_post_not_found` | Terminal not found or inactive. |
| `order_request_not_found` | Order request not found or expired. |
| `payment_request_not_found` | Payment request not found or invalid. |
| `dispute_request_not_found` | Dispute request not found or missing. |
| `document_request_not_found` | Document request not found or expired. |
| `resource_get_not_found` | Requested resource not found or unavailable. |
| `form_get_not_found` | Form not found or has been removed. |
| `authentication_error` | Authentication failed due to invalid or missing credentials. |
| `customer_instruments_authentication_error` | Customer instruments request failed authentication. |
| `integrity_token_not_found` | Integrity token not found or expired. |
| `checkout_config_not_found` | Checkout configuration not found or misconfigured. |
| `api_error_not_found` | API error: requested resource not found. |
| `payment_instrument_not_found` | Payment instrument not found or unsupported. |
| `order_not_found` | Order does not exist or was deleted. |
| `instrument_not_found` | Instrument not found for current customer or request. |
| `request_failed` | Request failed due to server or network error. |
| `cryptogram_request_failed` | Cryptogram generation failed or request is invalid. |
| `authorize_only_invalid` | Authorise-only is not allowed for this transaction. |
| `card_number_invalid` | Card number is invalid or incorrectly formatted. |
| `emi_tenure_invalid` | EMI tenure is invalid or unsupported for selection. |

## List of errors for payments

Download the list of errors along with their explanation.

<a href="https://gocashassets.s3.ap-south-1.amazonaws.com/repostmancollection/Error+List.xlsx">Payment Error List</a>

<Note>
  Error details will be shown for every failed transaction in the payload of the following APIs and webhooks:

  * [Get Payments for an Order](/docs/api-reference/payments/latest/payments/get-payments-for-an-order)
  * [Get Payment by ID](/docs/api-reference/payments/latest/payments/get-payment-by-id)
  * [Payment Failed Webhook](/docs/api-reference/payments/latest/payments/webhooks#payment-failed-webhook)
</Note>


# Order Pay Authorise Only
Source: https://www.cashfree.com/docs/api-reference/payments/latest/apple-pay/payments/authorize-payment-for-an-order

post /orders/sessions/authorize
Use this API when an order has already been created and you want Cashfree to process the payment for authorisation only. To use this API, the 'AUTHORIZE_ONLY' flag must be enabled for your account. Submit [Support Form](https://merchant.cashfree.com/auth/login) to enable this feature.



# Create Customer at Cashfree
Source: https://www.cashfree.com/docs/api-reference/payments/latest/customers/create-customer-at-cashfree

openapi/payments/v2026-01-01.yaml post /customers
Use this API to register a customer in Cashfree's system before initiating payments, subscriptions, tokenisation, or other customer-linked actions. It creates a reusable *customer profile* and returns a unique identifier for future transactions.



# Accept Dispute by Dispute ID
Source: https://www.cashfree.com/docs/api-reference/payments/latest/disputes/accept-dispute-by-dispute-id

openapi/payments/v2026-01-01.yaml put /disputes/{dispute_id}/accept
Use this API to get accept the Dispute by specifying the Dispute ID.



# Contest Arbitration by Dispute ID
Source: https://www.cashfree.com/docs/api-reference/payments/latest/disputes/contest-arbitration-by-dispute-id

openapi/payments/v2026-01-01.yaml put /disputes/{dispute_id}/contest-arbitration
Use this API to contest an ARBITRATION dispute without uploading documents.

NPCI (National Payments Corporation of India) does not allow document upload at the `ARBITRATION` stage. Cashfree forwards the evidence you submitted at the pre-arbitration stage to the card network or NPCI for a final decision.

To contest a dispute at an earlier stage by uploading documents, use the [Submit Evidence API](/docs/api-reference/payments/latest/disputes/submit-evidence-to-contest-the-dispute-by-dispute-id) instead.

Use this API only when `dispute_type` is `ARBITRATION` and `dispute_status` is one of the following:

* `ARBITRATION_CREATED`
* `ARBITRATION_DOCS_RECEIVED`
* `ARBITRATION_INSUFFICIENT_EVIDENCE`


# Dispute Webhooks
Source: https://www.cashfree.com/docs/api-reference/payments/latest/disputes/dispute-webhooks

Configure Cashfree dispute webhooks to receive automated notifications when disputes are created, updated, contested, or closed against your transactions.

Dispute webhooks can be configured to receive automated notifications when disputes are created, updated and closed.

The webhook notification will be sent on all the URLs added and enabled under the dispute webhook. Merchants can add new URLs and enable or disable existing URLs for refund webhook at any point in time and it will be reflected instantaneously.

| Webhook | Description |
| :- | :- |
| DISPUTE\_CREATED | Dispute\_created webhook will be triggered when a new dispute is created. |
| DISPUTE\_UPDATED | Dispute\_updated webhook will be triggered when a dispute is updated, for example when a comment is added by the Cashfree team, when the dispute moves into further stages like Pre-arbitration, Arbitration, or when the status of the dispute changes. |
| DISPUTE\_CLOSED | This webhook will be triggered when a dispute is closed. |

Click [here](/docs/payments/online/webhooks/overview) to know how to configure webhooks.

## Dispute created

**Sample Payload**

<Tabs>
  <Tab title="Version (2025-01-01)">
    ```javascript Version 2025-01-01 theme={"dark"}

    {
      "data": {
        "dispute": {
          "dispute_id": "433475258",
          "dispute_type": "DISPUTE",
          "reason_code": "1402",
          "reason_description": "Duplicate Processing",
          "dispute_amount": 3,
          "created_at": "2023-06-15T21:49:48+05:30",
          "updated_at": "2023-06-15T21:49:48+05:30",
          "respond_by": "2023-06-18T23:59:59+05:30",
          "dispute_status": ""DISPUTE_CREATED"",
          "cf_dispute_remarks": "Dispute is created, please take action",
          "dispute_action_on": "MERCHANT",
          "dispute_amount_currency": "INR"
        },
        "order_details": {
          "order_id": "order_1944392DR1kMTFYdIf8bI2awAcC3i9FTa",
          "order_amount": 3,
          "order_currency": "INR",
          "cf_payment_id": 885473311,
          "payment_amount": 3,
          "payment_currency": "INR"
        },
        "customer_details": {
          "customer_name": "Dileep Kumar s",
          "customer_phone": "8000000000",
          "customer_email": "dileep@gmail.com"
        }
      },
      "event_time": "2023-06-15T21:50:04+05:30",
      "type": "DISPUTE_CREATED"
    }
    ```
  </Tab>

  <Tab title="Version (2023-08-01)">
    ```javascript Version 2023-08-01 theme={"dark"}

    {
      "data": {
        "dispute": {
          "dispute_id": "433475258",
          "dispute_type": "DISPUTE",
          "reason_code": "1402",
          "reason_description": "Duplicate Processing",
          "dispute_amount": 3,
          "created_at": "2023-06-15T21:49:48+05:30",
          "updated_at": "2023-06-15T21:49:48+05:30",
          "respond_by": "2023-06-18T23:59:59+05:30",
          "dispute_status": ""DISPUTE_CREATED"",
          "cf_dispute_remarks": "Dispute is created, please take action",
          "dispute_action_on": "MERCHANT"
        },
        "order_details": {
          "order_id": "order_1944392DR1kMTFYdIf8bI2awAcC3i9FTa",
          "order_amount": 3,
          "order_currency": "INR",
          "cf_payment_id": 885473311,
          "payment_amount": 3,
          "payment_currency": "INR"
        },
        "customer_details": {
          "customer_name": "Dileep Kumar s",
          "customer_phone": "8000000000",
          "customer_email": "dileep@gmail.com"
        }
      },
      "event_time": ""2023-06-15T21:50:04+05:30",
      "type": "DISPUTE_CREATED"
    }
    ```
  </Tab>
</Tabs>

## Dispute updated

**Sample Payload**

<Tabs>
  <Tab title="Version (2025-01-01)">
    ```javascript Version 2025-01-01 theme={"dark"}
    {
      "data": {
        "dispute": {
          "dispute_id": "433475257",
          "dispute_type": "PRE_ARBITRATION",
          "reason_code": "13.1",
          "reason_description": "Merchandise / Services Not Received",
          "dispute_amount": 40000,
          "created_at": "2023-06-15T21:16:03+05:30",
          "updated_at": "2023-06-15T21:19:15+05:30",
          "respond_by": "2023-06-19T23:59:59+05:30",
          "dispute_status": "PRE_ARBITRATION_CREATED",
          "cf_dispute_remarks": "Pre Arbitration request has been raised for this case.\nTarget Date :: 2023-06-18T00:00 -> 2023-06-19T23:59:59.",
          "dispute_update": "TYPE_UPDATE",
          "dispute_action_on": "MERCHANT",
          "dispute_amount_currency": "INR"
        },
        "order_details": {
          "order_id": "order_1944392D4jHtCeVPPdTXkaUwg5cfnujQe",
          "order_amount": 40000,
          "order_currency": "INR",
          "cf_payment_id": 885457437,
          "payment_amount": 40000,
          "payment_currency": "INR"
        },
        "customer_details": {
          "customer_name": "Dileep Kumar s",
          "customer_phone": "8000000000",
          "customer_email": "dileep@gmail.com"
        }
      },
      "event_time": "2023-06-15T21:20:24+05:30",
      "type": "DISPUTE_UPDATED"
    }
    ```
  </Tab>

  <Tab title="Version (2023-08-01)">
    ```javascript Version 2023-08-01 theme={"dark"}
    {
      "data": {
        "dispute": {
          "dispute_id": "433475257",
          "dispute_type": "PRE_ARBITRATION",
          "reason_code": "13.1",
          "reason_description": "Merchandise / Services Not Received",
          "dispute_amount": 40000,
          "created_at": "2023-06-15T21:16:03+05:30",
          "updated_at": "2023-06-15T21:19:15+05:30",
          "respond_by": "2023-06-19T23:59:59+05:30",
          "dispute_status": "PRE_ARBITRATION_CREATED",
          "cf_dispute_remarks": "Pre Arbitration request has been raised for this case.\nTarget Date :: 2023-06-18T00:00 -> 2023-06-19T23:59:59.",
          "dispute_update": "TYPE_UPDATE",
          "dispute_action_on": "MERCHANT"
        },
        "order_details": {
          "order_id": "order_1944392D4jHtCeVPPdTXkaUwg5cfnujQe",
          "order_amount": 40000,
          "order_currency": "INR",
          "cf_payment_id": 885457437,
          "payment_amount": 40000,
          "payment_currency": "INR"
        },
        "customer_details": {
          "customer_name": "Dileep Kumar s",
          "customer_phone": "8000000000",
          "customer_email": "dileep@gmail.com"
        }
      },
      "event_time": "2023-06-15T21:20:24+05:30",
      "type": "DISPUTE_UPDATED"
    }
    ```
  </Tab>
</Tabs>

## Dispute closed

**Sample Payload**

<Tabs>
  <Tab title="Version (2025-01-01)">
    ```javascript Version 2025-01-01 theme={"dark"}
    {
      "data": {
        "dispute": {
          "dispute_id": "433475257",
          "dispute_type": "CHARGEBACK",
          "reason_code": "4855",
          "reason_description": "Goods or Services Not Provided",
          "dispute_amount": 4500,
          "created_at": "2023-06-15T21:16:03+05:30",
          "updated_at": "2023-06-15T21:16:51+05:30",
          "respond_by": "2023-06-18T00:00:00+05:30",
          "resolved_at": "2023-06-15T21:16:51.682836678+05:30",
          "dispute_status": "CHARGEBACK_MERCHANT_WON",
          "cf_dispute_remarks": "Chargeback won by merchant",
          "dispute_amount_currency": "INR"
        },
        "order_details": {
          "order_id": "order_1944392D4jHtCeVPPdTXkaUwg5cfnujQe",
          "order_amount": 4500,
          "order_currency": "INR",
          "cf_payment_id": 885457437,
          "payment_amount": 4500,
          "payment_currency": "INR"
        },
        "customer_details": {
          "customer_name": "Dileep Kumar s",
          "customer_phone": "8000000000",
          "customer_email": "dileep@gmail.com"
        }
      },
      "event_time": "2023-06-15T21:17:14+05:30",
      "type": "DISPUTE_CLOSED"
    }
    ```
  </Tab>

  <Tab title="Version (2023-08-01)">
    ```javascript Version 2023-08-01 theme={"dark"}
    {
      "data": {
        "dispute": {
          "dispute_id": "433475257",
          "dispute_type": "CHARGEBACK",
          "reason_code": "4855",
          "reason_description": "Goods or Services Not Provided",
          "dispute_amount": 4500,
          "created_at": "2023-06-15T21:16:03+05:30",
          "updated_at": "2023-06-15T21:16:51+05:30",
          "respond_by": "2023-06-18T00:00:00+05:30",
          "resolved_at": "2023-06-15T21:16:51.682836678+05:30",
          "dispute_status": "CHARGEBACK_MERCHANT_WON",
          "cf_dispute_remarks": "Chargeback won by merchant"
        },
        "order_details": {
          "order_id": "order_1944392D4jHtCeVPPdTXkaUwg5cfnujQe",
          "order_amount": 4500,
          "order_currency": "INR",
          "cf_payment_id": 885457437,
          "payment_amount": 4500,
          "payment_currency": "INR"
        },
        "customer_details": {
          "customer_name": "Dileep Kumar s",
          "customer_phone": "8000000000",
          "customer_email": "dileep@gmail.com"
        }
      },
      "event_time": "2023-06-15T21:17:14+05:30",
      "type": "DISPUTE_CLOSED"
    }
    ```
  </Tab>
</Tabs>

## Payload field description

| Field | Description | Example | Type |
| - | - | - | - |
| dispute\_id | Cashfree’s unique ID to identify a dispute. | 433475257 | Long |
| dispute\_type | Type of dispute created. Possible values:  <br />- DISPUTE<br />- RETRIEVAL<br />- CHARGEBACK<br />- PRE\_ARBITRATION<br />- ARBITRATION | Chargeback | String |
| reason\_code | Condition for which the customer is filing the case. See [dispute reason codes](/docs/payments/manage/disputes/reason-codes) to know more. | 13.6 | String |
| reason\_description | Description of the reason code. Codes for Chargeback cases are specified by Card networks/NPCI. | Credit not processed | String |
| dispute\_amount | The amount for which the dispute has been created. | 4500 | BigDecimal |
| created\_at | Time on which the dispute was registered on Cashfree’s system. | 2023-06-15T21:16:03+05:30 | LocalDateTime |
| updated\_at | Time on which the dispute was updated. | 2023-06-15T21:16:51+05:30 | LocalDateTime |
| respond\_by | Time by which the merchant is expected to respond to the dispute. | 2023-06-18T00:00:00+05:30 | LocalDateTime |
| dispute\_status | Status of Dispute. All possible values are listed in the table below. | CHARGEBACK\_CREATED | String |
| cf\_dispute\_remarks | Any remarks specified by Cashfree on the dispute. | Please submit documents. | String |
| dispute\_update | Specifies what has been updated on the dispute. Possible Values:  <br />- STATUS\_UPDATE<br />- TYPE\_UPDATE<br />- COMMENT\_UPDATE | TYPE\_UPDATE | String |
| dispute\_action\_on | Specifies whether the action is on Cashfree or Merchant at a time. Possible Values:  <br />- MERCHANT<br />- CASHFREE | MERCHANT | String |
| resolved\_at | Time on which the dispute was resolved/closed. | 2023-06-15T21:16:51.682836678+05:30 | LocalDateTime |
| event\_time | Time at which dispute webhook was initiated. | 2023-06-15T21:16:51+05:30 | LocalDateTime |
| type | Type of webhook. Possible Values:  <br />- DISPUTE\_CREATED<br />- DISPUTE\_UPDATED<br />- DISPUTE\_CLOSED | DISPUTE\_CREATED | String |

| List of dispute status |
| :- |
| DISPUTE\_CREATED |
| DISPUTE\_DOCS\_RECEIVED |
| DISPUTE\_UNDER\_REVIEW |
| DISPUTE\_MERCHANT\_WON |
| DISPUTE\_MERCHANT\_LOST |
| DISPUTE\_MERCHANT\_ACCEPTED |
| DISPUTE\_INSUFFICIENT\_EVIDENCE |
| RETRIEVAL\_CREATED |
| RETRIEVAL\_DOCS\_RECEIVED |
| RETRIEVAL\_UNDER\_REVIEW |
| RETRIEVAL\_MERCHANT\_WON |
| RETRIEVAL\_MERCHANT\_LOST |
| RETRIEVAL\_MERCHANT\_ACCEPTED |
| RETRIEVAL\_INSUFFICIENT\_EVIDENCE |
| CHARGEBACK\_CREATED |
| CHARGEBACK\_DOCS\_RECEIVED |
| CHARGEBACK\_UNDER\_REVIEW |
| CHARGEBACK\_MERCHANT\_WON |
| CHARGEBACK\_MERCHANT\_LOST |
| CHARGEBACK\_MERCHANT\_ACCEPTED |
| CHARGEBACK\_INSUFFICIENT\_EVIDENCE |
| PRE\_ARBITRATION\_CREATED |
| PRE\_ARBITRATION\_DOCS\_RECEIVED |
| PRE\_ARBITRATION\_UNDER\_REVIEW |
| PRE\_ARBITRATION\_MERCHANT\_WON |
| PRE\_ARBITRATION\_MERCHANT\_LOST |
| PRE\_ARBITRATION\_MERCHANT\_ACCEPTED |
| PRE\_ARBITRATION\_INSUFFICIENT\_EVIDENCE |
| ARBITRATION\_CREATED |
| ARBITRATION\_DOCS\_RECEIVED |
| ARBITRATION\_CONTEST\_REQUESTED |
| ARBITRATION\_UNDER\_REVIEW |
| ARBITRATION\_MERCHANT\_WON |
| ARBITRATION\_MERCHANT\_LOST |
| ARBITRATION\_MERCHANT\_ACCEPTED |
| ARBITRATION\_INSUFFICIENT\_EVIDENCE |

## Compute signature and verify

The signature must be used to verify if the request has not been tampered with. To verify the signature at your end, you will need your Cashfree PG secret key along with the payload. Timestamp is present in the header x-webhook-timestamp

````bash theme={"dark"}
timestamp := 1617695238078;  
signedPayload := $timestamp.$payload;
expectedSignature := Base64Encode(HMACSHA256($signedPayload, $merchantSecretKey));```
````

## Sample code

### Verify Signature using SDK

<CodeGroup>
  ```node Node (express) theme={"dark"}

  var express = require('express')
  import { Cashfree } from "cashfree-pg"; 
  var app = express()

  Cashfree.XClientId = "<x-client-id>";
  Cashfree.XClientSecret = "<x-client-secret>";
  Cashfree.XEnvironment = Cashfree.Environment.SANDBOX;

  app.post('/webhook', function (req, res) {
      try {
          Cashfree.PGVerifyWebhookSignature(req.headers["x-webhook-signature"], req.rawBody, req.headers["x-webhook-timestamp"]))
      } catch (err) {
          console.log(err.message)
      }
  })
  ```

  ```go Go theme={"dark"}
  var express = require('express')
  import { Cashfree } from "cashfree-pg"; 
  var app = express()

  Cashfree.XClientId = "<x-client-id>";
  Cashfree.XClientSecret = "<x-client-secret>";
  Cashfree.XEnvironment = Cashfree.Environment.SANDBOX;

  app.post('/webhook', function (req, res) {
      try {
          Cashfree.PGVerifyWebhookSignature(req.headers["x-webhook-signature"], req.rawBody, req.headers["x-webhook-timestamp"]))
      } catch (err) {
          console.log(err.message)
      }
  })
  ```

  ```php PHP theme={"dark"}

  <?php

  $inputJSON = file_get_contents('php://input');

  $expectedSig = getallheaders()['x-webhook-signature'];
  $ts = getallheaders()['x-webhook-timestamp'];

  if(!isset($expectedSig) || !isset($ts)){
      echo "Bad Request";
      die();
  }

  \Cashfree\Cashfree::$XClientId = "<x-client-id>";
  \Cashfree\Cashfree::$XClientSecret = "<x-client-secret>";
  $cashfree = new \Cashfree\Cashfree();

  try {
   $response =  cashfree->PGVerifyWebhookSignature($expectedSig, $inputJSON, $ts);
  } catch(Exception $e) {
    // Error if signature verification fails
  }
  ?>

  ```

  ```python Python theme={"dark"}
  from cashfree_pg.api_client import Cashfree

  @app.route('/webhook', methods = ['POST'])
  def disp():
  		# Get the raw body from the request
      raw_body = request.data
    
      # Decode the raw body bytes into a string
      decoded_body = raw_body.decode('utf-8')

      #verify_signature
      timestamp = request.headers['x-webhook-timestamp']
      signature = request.headers['x-webhook-signature'
  		
  		cashfree = Cashfree()
  		cashfree.XClientId = "<app_id>"
  		cashfree.XClientSecret = "<secret_key>"
  		try:
  			cashfreeWebhookResponse = cashfree.PGVerifyWebhookSignature(signature, decoded_body, timestamp)
  		except:
  			# If Signature mis-match

  ```

  ```java Java theme={"dark"}
  import com.cashfree.*;

  @PostMapping("/my-endpoint")
  public String handlePost(HttpServletRequest request) throws IOException {      
      Cashfree.XClientId = "<x-client-id>";
  		Cashfree.XClientSecret = "<x-client-secret>";
  		Cashfree.XEnvironment = Cashfree.SANDBOX;
    
    	StringBuilder stringBuilder = new StringBuilder();
      BufferedReader bufferedReader = null;

      try {           
        bufferedReader = request.getReader();
        String line;
        while ((line = bufferedReader.readLine()) != null) {
                stringBuilder.append(line).append('\n');
        }
          
          
        String rawBody = stringBuilder.toString();
        String signature = request.getHeader("x-webhook-signature");
        String timestamp = request.getHeader("x-webhook-timestamp");
          
        Cashfree cashfree = new Cashfree();
        PGWebhookEvent webhook = cashfree.PGVerifyWebhookSignature(signature, rawBody, timestamp);
            
      } catch (Exception e) {
              // Error if verification fails
      } finally {
           if (bufferedReader != null) {
              bufferedReader.close();
  		}
  	}
        
  }
  ```

  ```c C# theme={"dark"}
  using cashfree_pg.Client;
  using cashfree_pg.Model;


  		[Route("api/[controller]")]
      [ApiController]
      public class YourController : ControllerBase
      {
          [HttpPost]
          public async Task<IActionResult> Post()
          {
              // Read the raw body of the POST request
              using (StreamReader reader = new StreamReader(Request.Body, Encoding.UTF8))
              {
                  string requestBody = await reader.ReadToEndAsync();
                  var headers = Request.Headers;
                  var signature = headers["x-webhook-signature"];
                  var timestamp = headers["x-webhook-timestamp"];
                  
                  Cashfree.XClientId = "<x-client-id>";
                  Cashfree.XClientSecret = "<x-client-secret>";
                  Cashfree.XEnvironment = Cashfree.SANDBOX;
  								var cashfree = new Cashfree();
                  
                  try {
                  var response = cashfree.PGVerifyWebhookSignature(signature, requestBody, timestamp);
                  } catch(Exception e) {
                  // Error if signature mis matches
                  }
              }
          }
      }
  ```
</CodeGroup>

### Compute signature and verify manually

<CodeGroup>
  ```node Node (express) theme={"dark"}

  function verify(ts, rawBody){
      const body = req.headers["x-webhook-timestamp"] + req.rawBody;
      const secretKey = "<your secret key>";
      let genSignature = crypto.createHmac('sha256',secretKey).update(body).digest("base64");
      return genSignature
  }
  ```

  ```go Go theme={"dark"}
  func VerifySignature(expectedSig string, ts string, body string) (string, error) {
  	t := time.Now()
  	currentTS := t.Unix()
  	if currentTS-ts > 1000*300 {
  		return "", errors.New("webhook delivered too late")
  	}
  	signStr := strconv.FormatInt(ts, 10) + body
  	fmt.Println("signing String: ", signStr)
  	key := ""
  	h := hmac.New(sha256.New, []byte(key))
  	h.Write([]byte(signStr))
  	b := h.Sum(nil)
  	return base64.StdEncoding.EncodeToString(b), nil
  }

  timestamp := c.Request().Header.Get("x-webhook-timestamp")
  body, _ := ioutil.ReadAll(c.Request().Body)
  rawBody := string(body)
  signature := c.Request().Header.Get("x-webhook-signature")

  VerifySignature(signature, timestamp, rawBody)func VerifySignature(expectedSig string, ts string, body string) (string, error) {
  	t := time.Now()
  	currentTS := t.Unix()
  	if currentTS-ts > 1000*300 {
  		return "", errors.New("webhook delivered too late")
  	}
  	signStr := strconv.FormatInt(ts, 10) + body
  	fmt.Println("signing String: ", signStr)
  	key := ""
  	h := hmac.New(sha256.New, []byte(key))
  	h.Write([]byte(signStr))
  	b := h.Sum(nil)
  	return base64.StdEncoding.EncodeToString(b), nil
  }

  timestamp := c.Request().Header.Get("x-webhook-timestamp")
  body, _ := ioutil.ReadAll(c.Request().Body)
  rawBody := string(body)
  signature := c.Request().Header.Get("x-webhook-signature")

  VerifySignature(signature, timestamp, rawBody)
  ```

  ```php PHP theme={"dark"}

  function computeSignature($ts, $rawBody){
      $rawBody = file_get_contents('php://input');
  		$ts = getallheaders()['x-webhook-timestamp'];
    
      $signStr = $ts . $rawBody;
      $key = "";
      $computeSig = base64_encode(hash_hmac('sha256', $signStr, $key, true));
      return $computeSig;
  }

  ```

  ```java Java theme={"dark"}
  public String generateSignature() {

  	bufferedReader = request.getReader();
    String line;
    while ((line = bufferedReader.readLine()) != null) {
       stringBuilder.append(line).append('\n');
    }      
    String payload = stringBuilder.toString();
    String timestamp = request.getHeader("x-webhook-timestamp");
        
    String data = timestamp+payload;

    String secretKey = "SECRET-KEY"; // Get secret key from Cashfree Merchant Dashboard;
    Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
    SecretKeySpec secret_key_spec = new SecretKeySpec(secretKey.getBytes(),"HmacSHA256");
    sha256_HMAC.init(secret_key_spec);
    String computed_signature = Base64.getEncoder().encodeToString(sha256_HMAC.doFinal(data.getBytes()));
    return computed_signature; // compare with "x-webhook-signature"
  }

  ```

  ```python Python theme={"dark"}
  import base64
  import hashlib
  import hmac

  def generateSignature():    
      # Get the raw body from the request
      raw_body = request.data
    
      # Decode the raw body bytes into a string
      payload = raw_body.decode('utf-8')

      #verify_signature
      timestamp = request.headers['x-webhook-timestamp']
      
      signatureData = timestamp+payload
      message = bytes(signatureData, 'utf-8')
      secretkey=bytes("Secret_Key",'utf-8') #Get Secret_Key from Cashfree Merchant Dashboard.
      signature = base64.b64encode(hmac.new(secretkey, message, digestmod=hashlib.sha256).digest())
      computed_signature = str(signature, encoding='utf8')
      return computed_signature #compare with "x-webhook-signature"

  ```
</CodeGroup>


# Get Disputes by Dispute ID
Source: https://www.cashfree.com/docs/api-reference/payments/latest/disputes/get-disputes-by-dispute-id

openapi/payments/v2026-01-01.yaml get /disputes/{dispute_id}
Use this API to get Dispute details by specifying the Dispute ID.



# Get Disputes by Order ID
Source: https://www.cashfree.com/docs/api-reference/payments/latest/disputes/get-disputes-by-order-id

openapi/payments/v2026-01-01.yaml get /orders/{order_id}/disputes
Use this API to get all Dispute details by specifying the Order ID.



# Get Disputes by Payment ID
Source: https://www.cashfree.com/docs/api-reference/payments/latest/disputes/get-disputes-by-payment-id

openapi/payments/v2026-01-01.yaml get /payments/{cf_payment_id}/disputes
Use this API to get all Dispute details by specifying the Payment ID.



# Submit Evidence to contest the Dispute by Dispute ID
Source: https://www.cashfree.com/docs/api-reference/payments/latest/disputes/submit-evidence-to-contest-the-dispute-by-dispute-id

openapi/payments/v2026-01-01.yaml post /disputes/{dispute_id}/documents
Use this API to submit evidence to contest a dispute by specifying the dispute ID. This API does not apply to ARBITRATION disputes. Use the [Contest Arbitration API](/docs/api-reference/payments/latest/disputes/contest-arbitration-by-dispute-id) instead.

<Note>
  As per NPCI (National Payments Corporation of India) guidelines, document upload is not allowed at the ARBITRATION stage. If the dispute has reached the ARBITRATION stage, use the [Contest Arbitration API](/docs/api-reference/payments/latest/disputes/contest-arbitration-by-dispute-id) instead. All evidence submitted during the pre-arbitration stage is automatically carried forward for further processing.
</Note>


# Fetch All Downtimes
Source: https://www.cashfree.com/docs/api-reference/payments/latest/downtime/fetch-all-downtimes

openapi/payments/v2026-01-01.yaml get /incident
Fetches active downtimes across various payment methods based on filters. Gives all active downtimes when no filters are applied.



# Create Adjustment
Source: https://www.cashfree.com/docs/api-reference/payments/latest/easy-split/create-adjustment

openapi/payments/v2026-01-01.yaml post /easy-split/vendors/{vendor_id}/adjustment
The Create Adjustment API will create a adjustment request either from vendor to the merchant or from merchant to the vendor.



# Create On Demand Transfer
Source: https://www.cashfree.com/docs/api-reference/payments/latest/easy-split/create-on-demand-transfer

openapi/payments/v2026-01-01.yaml post /easy-split/vendors/{vendor_id}/transfer
The Create On Demand Transfer API will create a new on-demand request either from to the merchant or from to the vendor.



# Create Static Split Configuration
Source: https://www.cashfree.com/docs/api-reference/payments/latest/easy-split/create-static-split-configuration

openapi/payments/v2026-01-01.yaml post /easy-split/static-split
This API will create a static split scheme wherein you can define the split type and the vendor-wise split percentage.



# Create Vendor
Source: https://www.cashfree.com/docs/api-reference/payments/latest/easy-split/create-vendor

openapi/payments/v2026-01-01.yaml post /easy-split/vendors
Use this API to create a new vendor to your EasySplit account along with the KYC details. Provide KYC details such as account_type, business_type, gst, cin, pan, passport number and so on.

<Tip>
  Keep the following points in mind when you create a vendor:

  * Use [test account details](/docs/payments/split/data-to-test#sample-bank-account-numbers-upi-and-vpa) in Sandbox mode.
  * Use test GST and PAN numbers from the [test details](/docs/payments/split/data-to-test#test-details) page.
  * Vendors that you create in the Sandbox environment with test bank account and KYC details move to `ACTIVE` status automatically after 10 minutes.
  * If a vendor doesn't move to `ACTIVE` status within 24 hours in Production mode, fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1).
</Tip>


# Download Vendor Documents
Source: https://www.cashfree.com/docs/api-reference/payments/latest/easy-split/download-vendor-documents

openapi/payments/v2026-01-01.yaml get /easy-split/vendor-docs/{vendor_id}/download/{doc_type}
Use this API to download the uploaded KYC documents of that particular vendor. Provide the document type. Click the link from the sample request to download the KYC document.



# Get On Demand Balance
Source: https://www.cashfree.com/docs/api-reference/payments/latest/easy-split/get-on-demand-balance

openapi/payments/v2026-01-01.yaml get /easy-split/vendors/{vendor_id}/balances
This API fetches the available amount with the merchant, vendor, and the unsettled amount for the merchant as well as the vendor.



# Get Split and Settlement Details by OrderID
Source: https://www.cashfree.com/docs/api-reference/payments/latest/easy-split/get-split-and-settlement-details-by-orderid

openapi/payments/v2026-01-01.yaml get /easy-split/orders/{order_id}
Use this API to get all the split details, settled and unsettled transactions details of each vendor who were part of a particular order by providing order Id or start date and end date.



# Get Split and Settlement Details by OrderID v2.0
Source: https://www.cashfree.com/docs/api-reference/payments/latest/easy-split/get-split-and-settlement-details-by-orderid-v20

openapi/payments/v2026-01-01.yaml post /split/order/vendor/recon
Use this API to get all the split details, settled and unsettled transactions details of each vendor who were part of a particular order by providing order Id or start date and end date.



# Get Vendor All Details
Source: https://www.cashfree.com/docs/api-reference/payments/latest/easy-split/get-vendor-all-details

openapi/payments/v2026-01-01.yaml get /easy-split/vendors/{vendor_id}
Use this API to get the details of a specific vendor associated with your Easy Split account.



# Get Vendor All Documents Status
Source: https://www.cashfree.com/docs/api-reference/payments/latest/easy-split/get-vendor-all-documents-status

openapi/payments/v2026-01-01.yaml get /easy-split/vendor-docs/{vendor_id}
Use this API to fetch the details of all the KYC details of a particular vendor.



# Get Vendor Balance Transfer Charges
Source: https://www.cashfree.com/docs/api-reference/payments/latest/easy-split/get-vendor-balance-transfer-charges

openapi/payments/v2026-01-01.yaml get /easy-split/amount/{amount}/charges
This API returns the applicable service charge and service tax for a vendor balance transfer, based on the provided amount and rate type.



# Split After Payment
Source: https://www.cashfree.com/docs/api-reference/payments/latest/easy-split/split-after-payment

openapi/payments/v2026-01-01.yaml post /easy-split/orders/{order_id}/split
The Split After Payment API splits payments to vendors after customers successfully complete a payment. After you receive a successful payment confirmation, wait 2 minutes before you call this API endpoint.



# Update Vendor Details
Source: https://www.cashfree.com/docs/api-reference/payments/latest/easy-split/update-vendor-details

openapi/payments/v2026-01-01.yaml patch /easy-split/vendors/{vendor_id}
Use this API to edit the existing vendor details added to your EasySplit account. You can edit vendor details such as name, email, phone number, upi details, and any of the KYC details.



# Upload Vendor Docs
Source: https://www.cashfree.com/docs/api-reference/payments/latest/easy-split/upload-vendor-docs

openapi/payments/v2026-01-01.yaml post /easy-split/vendor-docs/{vendor_id}
Use this API to upload KYC documents of a specific vendor.



# Get Eligible Cardless EMI Payment Methods for a customer on an order
Source: https://www.cashfree.com/docs/api-reference/payments/latest/eligibility/get-eligible-cardless-emi-payment-methods-for-a-customer-on-an-order

openapi/payments/v2026-01-01.yaml post /eligibility/cardlessemi
Use this API to get eligible Cardless EMI Payment Methods available for a customer on an order basis their phone number.



# Get Eligible Offers for an Order
Source: https://www.cashfree.com/docs/api-reference/payments/latest/eligibility/get-eligible-offers-for-an-order

openapi/payments/v2026-01-01.yaml post /eligibility/offers
Use this API to get eligible offers for an order_id or order amount.



# Get Eligible Paylater for a customer on an order
Source: https://www.cashfree.com/docs/api-reference/payments/latest/eligibility/get-eligible-paylater-for-a-customer-on-an-order

openapi/payments/v2026-01-01.yaml post /eligibility/paylater
Use this API to get eligible Paylater Payment Methods for a customer on an order.



# Get Eligible Payment Methods for Orders
Source: https://www.cashfree.com/docs/api-reference/payments/latest/eligibility/get-eligible-payment-methods

openapi/payments/v2026-01-01.yaml post /eligibility/payment_methods
Fetch the payment instruments a Cashfree order is eligible to use, including UPI, cards, netbanking, wallets, and EMI rails for personalised checkouts.

<a href="https://www.postman.com/cashfreedevelopers/workspace/cashfree-apis-v2025-01-01/request/40140981-8e018a91-9f37-49f8-aa44-d6aa9855c0b5">
  <span aria-label="Postman" />

  Run in Postman: You can also try this API in our Postman Collection.
</a>

## Client environment headers

Cashfree requires information about the customer's device environment to enforce NPCI rules. You must include the following headers in your [Order Pay API](/docs/api-reference/payments/latest/payments/order-pay) and Get Eligible Payment Methods request:

<Accordion title="Client environment headers">
  | Header | Accepted values | Requirement | Description |
  | - | - | - | - |
  | `x-client-device` | `mobile`, `desktop`, `tablet` | Required | Type of device used by customer |
  | `x-client-os` | `android`, `ios`, `windows`, `macos`, `linux`, `others` | Required | Operating system of customer's device |
  | `x-client-rendering-type` | `mweb`, `webview`, `native` | Required when `x-client-device` is mobile | Rendering method used for the checkout experience |
  | `x-client-browser` | `safari`, `chrome`, `firefox`, `edge`, `others` | Required | Browser used by the customer |
</Accordion>

<Note>`x-client-rendering-type` is required only when `x-client-device` is set to mobile. For desktop and tablet devices, this header is optional.</Note>


# Fetch Downtime by ID
Source: https://www.cashfree.com/docs/api-reference/payments/latest/intellisense/fetch-downtime-by-id

openapi/payments/v2026-01-01.yaml get /incident/{id}
Fetches details of a specific downtime using its unique ID.



# Get Import Settlement Details for an Order
Source: https://www.cashfree.com/docs/api-reference/payments/latest/international-payments/collect-from-india/get-import-settlement-details

openapi/cb-imports/v2026-01-01.yaml get /import/orders/{order_id}/settlements
This API is used to get ICA settlement details using PG Order ID.



# Get Import Settlement Recon Details
Source: https://www.cashfree.com/docs/api-reference/payments/latest/international-payments/collect-from-india/get-import-settlement-recon-details

openapi/cb-imports/v2026-01-01.yaml post /import/settlements/recon
This API is used to fetch all events for the provided Settlement IDs.



# Get Payment Verification Details
Source: https://www.cashfree.com/docs/api-reference/payments/latest/international-payments/collect-from-india/get-payment-verification-details

get /import/transactions/{cf_payment_id}
This API is used to get the verification status of the payment.



# Webhooks
Source: https://www.cashfree.com/docs/api-reference/payments/latest/international-payments/collect-from-india/import-webhooks

Set up Cashfree Collect from India import webhooks to receive event-based notifications about incoming international payments and reconciliation status.

Webhooks are server callbacks to your server from Cashfree. Webhooks are event-based and are sent when specific events related to the transaction happen.

For instructions on configuring webhooks, see [Configure Webhooks](/docs/payments/online/webhooks/configure).

<Tabs>
  <Tab title="Payment Verification">
    ## Payment Verification details webhook version (2025-01-01)

    The payment verification details update webhook notifies you about the payment details verification, and it give you comprehensive information about verification details update.

    A notification is sent to your backend from cashfree when there is any new update for payment verification. These notification are useful in cases when the internet connection is unstable or slow while the payment is getting processed. This will allow you to reconcile all the payment verification update at your end. Notifications will be sent to **notifyUrl** which is a part of the request parameter specified while creating an order request.

    ### Sample payload

    ```json Json theme={"dark"}
    {
    	"data": {
    	    "order_id": "e145c994-5899-4466-804d-b90c625b2c1b",
    		"cf_payment_id": 5114910634577,
    		"payment_status": "SUCCESS",
    		"payment_verification_status": "ACTION_REQUIRED",
    		"payment_verification_expiry": "2024-07-12T15:19:42+05:30",
    		"remarks": null,
    		"required_details": [
                {
                    "doc_name": "goods_description",
                    "doc_type": "VALUE",
                    "doc_status": "ACTION_REQUIRED",
                    "remarks": null
                },
                {
                    "doc_name": "invoice_number",
                    "doc_type": "VALUE",
                    "doc_status": "IN_REVIEW",
                    "remarks": null
                },
                {
                    "doc_name": "importer_name",
                    "doc_type": "VALUE",
                    "doc_status": "IN_REVIEW",
                    "remarks": null
                },
                {
                    "doc_name": "importer_address",
                    "doc_type": "VALUE",
                    "doc_status": "IN_REVIEW",
                    "remarks": null
                },
                {
                    "doc_name": "country_of_origin",
                    "doc_type": "VALUE",
                    "doc_status": "IN_REVIEW",
                    "remarks": null
                },
                {
                    "doc_name": "invoice_file",
                    "doc_type": "DOCUMENT",
                    "doc_status": "IN_REVIEW",
                    "remarks": null
                },
                {
                    "doc_name": "ecommerce_order_serial_number", //Required for Physical Goods and Digital Goods
                    "doc_type": "VALUE",
                    "doc_status": "ACTION_REQUIRED",
                    "remarks": null
                },
                {
                    "doc_name": "hs_code", //Required for Physical Goods and Digital Goods
                    "doc_type": "VALUE",
                    "doc_status": "IN_REVIEW",
                    "remarks": null
                },
                {
                    "doc_name": "shipment_date", //Required for Physical Goods
                    "doc_type": "VALUE",
                    "doc_status": "ACTION_REQUIRED",
                    "remarks": null
                },
                {
                    "doc_name": "port_of_loading",//Required for Physical Goods
                    "doc_type": "VALUE",
                    "doc_status": "IN_REVIEW",
                    "remarks": null
                },
                    {
                    "doc_name": "awb_number",//Required for Physical Goods
                    "doc_type": "VALUE",
                    "doc_status": "IN_REVIEW",
                    "remarks": null
                }
    		]
    	},
    	"event_time": "2024-07-12T13:39:42+05:30",
    	"type": "PAYMENT_VERIFICATION_UPDATE"
    }
    ```
  </Tab>

  <Tab title="Settlement Details">
    ## ICA Settlement details webhook version 1 (2022-09-01)

    The ICA Settlement Details Update webhook notifies you about the ica settlement.

    A notification is sent to your backend from cashfree when there is any new update for ica settlement. These notification are useful in cases when the internet connection is unstable or slow while the payment is getting processed. This will allow you to reconcile all the ica settlement update at your end. Notifications will be sent to **notifyUrl** which is a part of the request parameter specified while creating an order request.

    ### Sample payload

    <br />

    ```json Json theme={"dark"}
    {
    	"data": {
    		"adjustment_amount_inr": -347641.22,
    		"collection_amount_inr": 604854.0,
    		"initiated_on": null,
    		"payment_from": "2024-09-26T15:43:55",
    		"payment_till": "2024-09-26T16:43:13",
    		"service_charge_inr": null,
    		"service_tax_inr": 2068.59,
    		"settled_on": null,
    		"settlement_amount_inr": 243651.95,
    		"settlement_charges_inr": 0.0,
    		"settlement_foreign_currency_details": {
    			"settlement_amount_fcy": null,
    			"settlement_currency": "USD",
    			"settlement_forex_rate": null
    		},
    		"cf_ica_settlement_id": 12,
    		"settlement_tax_inr": 0.0,
    		"settlement_utr": null,
    		"status": "NOT_INITIATED"
    	},
    	"event_time": "2024-10-03T13:27:36+05:30",
    	"type": "ICA_SETTLEMENT_UPDATE"
    }
    ```

    ## ICA settlement details webhook for LRS travel

    The ICA settlement details update webhook for Liberalised Remittance Scheme (LRS) travel notifies you about ICA settlements for LRS travel collections. This payload includes the `tcs_amount_inr` field, which reports the tax collected at source (TCS) on the settlement.

    ### Sample payload

    <br />

    ```json Json theme={"dark"}
    {
    	"data": {
    		"cf_ica_settlement_id": 10683,
    		"status": "SETTLED",
    		"collection_amount_inr": 34653.0000,
    		"service_charge_inr": 658.4400,
    		"service_tax_inr": 118.5100,
    		"tcs_amount_inr": 4053.5000,
    		"adjustment_amount_inr": 0.0000,
    		"settlement_charges_inr": 0.0000,
    		"settlement_tax_inr": 0.0000,
    		"settlement_amount_inr": 30599.5000,
    		"settlement_foreign_currency_details": {
    			"settlement_currency": "USD",
    			"settlement_forex_rate": 94.5398,
    			"settlement_amount": 323.6679
    		},
    		"payment_from": "2026-06-05T19:33:59+05:30",
    		"payment_till": "2026-06-08T13:22:48+05:30",
    		"settlement_utr": "8503c728-a7e5-4cec-9e87-4284ee3a235c",
    		"initiated_on": "2026-06-10T10:28:33+05:30",
    		"settled_on": "2026-06-30T06:29:21+05:30"
    	},
    	"event_time": "2026-06-30T06:29:21+05:30",
    	"type": "ICA_SETTLEMENT_UPDATE"
    }
    ```
  </Tab>

  <Tab title="Signature Verification">
    ## Signature verification

    The signature must be used to verify if the request has not been tampered with. To verify the signature at your end, you will need your Cashfree PG secret key along with the payload.

    timestamp is present in the header x-webhook-timestamp\
    Actual signature is present in the header x-webhook-signature

    ```
    timestamp := 1617695238078;
    signedPayload := $timestamp.$payload;
    expectedSignature := Base64Encode(HMACSHA256($signedPayload, $merchantSecretKey));
    ```
  </Tab>

  <Tab title="Sample Code">
    ## Sample code

    ### Verify Signature using SDK

    <CodeGroup>
      ```node Node(express) theme={"dark"}
      using cashfree_pg.Client;
      using cashfree_pg.Model;

          	[Route("api/[controller]")]
          [ApiController]
          public class YourController : ControllerBase
          {
              [HttpPost]
              public async Task<IActionResult> Post()
              {
                  // Read the raw body of the POST request
                  using (StreamReader reader = new StreamReader(Request.Body, Encoding.UTF8))
                  {
                      string requestBody = await reader.ReadToEndAsync();
                      var headers = Request.Headers;
                      var signature = headers["x-webhook-signature"];
                      var timestamp = headers["x-webhook-timestamp"];

                      Cashfree.XClientId = "<x-client-id>";
                      Cashfree.XClientSecret = "<x-client-secret>";
                      Cashfree.XEnvironment = Cashfree.SANDBOX;
          							var cashfree = new Cashfree();

                      try {
                      var response = cashfree.PGVerifyWebhookSignature(signature, requestBody, timestamp);
                      } catch(Exception e) {
                      // Error if signature mis matches
                      }
                  }
              }
          }

      ```

      ```go Go theme={"dark"}
      import (
        cashfree "github.com/cashfree/cashfree-pg/v4"
      )

      // Route
      e.POST("/webhook", _this.Webhook)

      // Controller
      func (_this *WebhookRoute) Webhook(c echo.Context) error {
        	clientId := "<x-client-id>"
      		clientSecret := "<x-client-secret>"
      		cashfree.XClientId = &clientId
      		cashfree.XClientSecret = &clientSecret
      		cashfree.XEnvironment = cashfree.SANDBOX

          signature := c.Request().Header.Get("x-webhook-signature")
          timestamp := c.Request().Header.Get("x-webhook-timestamp")

          body, _ := ioutil.ReadAll(c.Request().Body)
          rawBody := string(body)
          webhookEvent, err := cashfree.PGVerifyWebhookSignature(signature, rawBody, timestamp)
          if err != nil {
      		fmt.Println(err.Error())
      	} else {
      		fmt.Println(webhookEvent.Object)
      	}
      }
      ```

      ```php PHP theme={"dark"}
      <?php

      $inputJSON = file_get_contents('php://input');

      $expectedSig = getallheaders()['x-webhook-signature'];
      $ts = getallheaders()['x-webhook-timestamp'];

      if(!isset($expectedSig) || !isset($ts)){
          echo "Bad Request";
          die();
      }

      \Cashfree\Cashfree::$XClientId = "<x-client-id>";
      \Cashfree\Cashfree::$XClientSecret = "<x-client-secret>";
      $cashfree = new \Cashfree\Cashfree();

      try {
       $response =  cashfree->PGVerifyWebhookSignature($expectedSig, $inputJSON, $ts);
      } catch(Exception $e) {
        // Error if signature verification fails
      }
      ?>
      ```

      ```python Python theme={"dark"}
      from cashfree_pg.api_client import Cashfree

      @app.route('/webhook', methods = ['POST'])
      def disp():
      		# Get the raw body from the request
          raw_body = request.data

          # Decode the raw body bytes into a string
          decoded_body = raw_body.decode('utf-8')

          #verify_signature
          timestamp = request.headers['x-webhook-timestamp']
          signature = request.headers['x-webhook-signature'

      		cashfree = Cashfree()
      		cashfree.XClientId = "<app_id>"
      		cashfree.XClientSecret = "<secret_key>"
      		try:
      			cashfreeWebhookResponse = cashfree.PGVerifyWebhookSignature(signature, decoded_body, timestamp)
      		except:
      			# If Signature mis-match
      ```

      ```java Java theme={"dark"}
      import com.cashfree.*;

      @PostMapping("/my-endpoint")
      public String handlePost(HttpServletRequest request) throws IOException {
          Cashfree.XClientId = "<x-client-id>";
      		Cashfree.XClientSecret = "<x-client-secret>";
      		Cashfree.XEnvironment = Cashfree.SANDBOX;

        	StringBuilder stringBuilder = new StringBuilder();
          BufferedReader bufferedReader = null;

          try {
            bufferedReader = request.getReader();
            String line;
            while ((line = bufferedReader.readLine()) != null) {
                    stringBuilder.append(line).append('\n');
            }


            String rawBody = stringBuilder.toString();
            String signature = request.getHeader("x-webhook-signature");
            String timestamp = request.getHeader("x-webhook-timestamp");

            Cashfree cashfree = new Cashfree();
            PGWebhookEvent webhook = cashfree.PGVerifyWebhookSignature(signature, rawBody, timestamp);

          } catch (Exception e) {
                  // Error if verification fails
          } finally {
               if (bufferedReader != null) {
                  bufferedReader.close();
      		}
      	}

      }
      ```

      ```c C# theme={"dark"}
      using cashfree_pg.Client;
      using cashfree_pg.Model;


      		[Route("api/[controller]")]
          [ApiController]
          public class YourController : ControllerBase
          {
              [HttpPost]
              public async Task<IActionResult> Post()
              {
                  // Read the raw body of the POST request
                  using (StreamReader reader = new StreamReader(Request.Body, Encoding.UTF8))
                  {
                      string requestBody = await reader.ReadToEndAsync();
                      var headers = Request.Headers;
                      var signature = headers["x-webhook-signature"];
                      var timestamp = headers["x-webhook-timestamp"];

                      Cashfree.XClientId = "<x-client-id>";
                      Cashfree.XClientSecret = "<x-client-secret>";
                      Cashfree.XEnvironment = Cashfree.SANDBOX;
      								var cashfree = new Cashfree();

                      try {
                      var response = cashfree.PGVerifyWebhookSignature(signature, requestBody, timestamp);
                      } catch(Exception e) {
                      // Error if signature mis matches
                      }
                  }
              }
          }
      ```
    </CodeGroup>

    ### Compute signature and verify manually

    <CodeGroup>
      ```node Node(express) theme={"dark"}
      function verify(ts, rawBody){
          const body = req.headers["x-webhook-timestamp"] + req.rawBody;
          const secretKey = "<your secret key>";
          let genSignature = crypto.createHmac('sha256',secretKey).update(body).digest("base64");
          return genSignature
      }

      ```

      ```go Go theme={"dark"}
      func VerifySignature(expectedSig string, ts string, body string) (string, error) {
      	t := time.Now()
      	currentTS := t.Unix()
      	if currentTS-ts > 1000*300 {
      		return "", errors.New("webhook delivered too late")
      	}
      	signStr := strconv.FormatInt(ts, 10) + body
      	fmt.Println("signing String: ", signStr)
      	key := ""
      	h := hmac.New(sha256.New, []byte(key))
      	h.Write([]byte(signStr))
      	b := h.Sum(nil)
      	return base64.StdEncoding.EncodeToString(b), nil
      }

      timestamp := c.Request().Header.Get("x-webhook-timestamp")
      body, _ := ioutil.ReadAll(c.Request().Body)
      rawBody := string(body)
      signature := c.Request().Header.Get("x-webhook-signature")

      VerifySignature(signature, timestamp, rawBody)
      ```

      ```php PHP theme={"dark"}
      function computeSignature($ts, $rawBody){
          $rawBody = file_get_contents('php://input');
      		$ts = getallheaders()['x-webhook-timestamp'];

          $signStr = $ts . $rawBody;
          $key = "";
          $computeSig = base64_encode(hash_hmac('sha256', $signStr, $key, true));
          return $computeSig;
      }
      ```

      ```java Java theme={"dark"}
      public String generateSignature() {

      	bufferedReader = request.getReader();
        String line;
        while ((line = bufferedReader.readLine()) != null) {
           stringBuilder.append(line).append('\n');
        }
        String payload = stringBuilder.toString();
        String timestamp = request.getHeader("x-webhook-timestamp");

        String data = timestamp+payload;

        String secretKey = "SECRET-KEY"; // Get secret key from Cashfree Merchant Dashboard;
        Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
        SecretKeySpec secret_key_spec = new SecretKeySpec(secretKey.getBytes(),"HmacSHA256");
        sha256_HMAC.init(secret_key_spec);
        String computed_signature = Base64.getEncoder().encodeToString(sha256_HMAC.doFinal(data.getBytes()));
        return computed_signature; // compare with "x-webhook-signature"
      }
      ```

      ```python Python theme={"dark"}
      import base64
      import hashlib
      import hmac

      def generateSignature():
          # Get the raw body from the request
          raw_body = request.data

          # Decode the raw body bytes into a string
          payload = raw_body.decode('utf-8')

          #verify_signature
          timestamp = request.headers['x-webhook-timestamp']

          signatureData = timestamp+payload
          message = bytes(signatureData, 'utf-8')
          secretkey=bytes("Secret_Key",'utf-8') #Get Secret_Key from Cashfree Merchant Dashboard.
          signature = base64.b64encode(hmac.new(secretkey, message, digestmod=hashlib.sha256).digest())
          computed_signature = str(signature, encoding='utf8')
          return computed_signature #compare with "x-webhook-signature"
      ```
    </CodeGroup>
  </Tab>
</Tabs>


# Mark Sandbox Settlement Processed
Source: https://www.cashfree.com/docs/api-reference/payments/latest/international-payments/collect-from-india/mark-sandbox-settlement-processed

put /import/settlements/emulate
This API is used to mark settlement as processed in sandbox environment.



# Overview
Source: https://www.cashfree.com/docs/api-reference/payments/latest/international-payments/collect-from-india/overview

Cashfree Collect from India helps overseas merchants, payment aggregators, and marketplaces accept payments from Indian customers in INR with full compliance.

**Getting Started**

Follow the steps mentioned below to get started with Collect from India APIs

* Fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) for onboarding assistance
* If you are a Merchant, generate your keys using this method [Link](/docs/api-reference/authentication#generate-api-keys)
* Register your webhook URL for updates and subscribe to the required events. For more information, refer to the [Webhook documentation](/docs/api-reference/payments/latest/international-payments/collect-from-india/import-webhooks).

Once these setup is completed, we can use the below mentioned collection of APIs to create import transactions.

**Collect from India - List of APIs**

| API name | Description |
| :- | :- |
| [Create Order](/docs/api-reference/payments/latest/orders/create-order) | This API will create an order to collect payment |
| [Order Pay](/docs/api-reference/payments/latest/payments/order-pay) | This API is used to pay the created payment |
| [Get Payment by ID](/docs/api-reference/payments/latest/payments/get-payment-by-id) | This API is used to view payment details of an order for a payment ID |
| [Upload Payment Verification Details](/docs/api-reference/payments/latest/international-payments/collect-from-india/upload-payment-verification-details) | This API is used to upload the required payment verification details |
| [Get Payment Verification Details](/docs/api-reference/payments/latest/international-payments/collect-from-india/get-payment-verification-details) | This API is used to Get the verification status of the payment |
| [Get Import Settlement Details for an Order](/docs/api-reference/payments/latest/international-payments/collect-from-india/get-import-settlement-details) | This API is used to get ICA settlement details using PG Order ID |
| [Get Import Settlement Recon Details](/docs/api-reference/payments/latest/international-payments/collect-from-india/get-import-settlement-recon-details) | This API is used to fetch all events happened for provided Settlement IDs |


# Overview
Source: https://www.cashfree.com/docs/api-reference/payments/latest/international-payments/collect-from-india/sandbox-simulation

Learn how to simulate transaction verification and settlement processes in the sandbox environment for payments from India-based customers to overseas merchants

## Transaction verification simulation

In the sandbox environment, you can simulate transaction verification using predefined test values that are automatically approved. For file-type content, the system approves PDF files while rejecting other file formats.

You can submit verification details either through the [Upload Payment Verification Details](/docs/api-reference/payments/latest/international-payments/collect-from-india/upload-payment-verification-details) or the dashboard.

### Test values for transaction verification

| Field name | Value |
| - | - |
| importer\_name | John |
| importer\_address | 321 Elm Street, Suite 3, Los Angeles, CA 90401, USA |
| goods\_description | This is a test product for test purpose |
| country\_of\_origin | USA |
| ecommerce\_order\_serial\_number | 123123 |
| invoice\_number | 234234 |
| hs\_code | 3456 |
| shipment\_date | 01/01/2027 |
| port\_of\_loading | Houston |
| importer\_address\_postal\_code | 560034 |

## Settlement simulation

The sandbox environment provides APIs to simulate the settlement process. This includes triggering settlements and updating their status.

### Trigger settlement

Use the [Trigger Settlement API](/docs/api-reference/payments/latest/international-payments/collect-from-india/trigger-sandbox-settlement) to initiate a settlement. This is an asynchronous process, with settlement entries typically created within one second.

### Mark settlement as processed

To update a settlement's status to "Processed", use the [Mark Settlement as Processed](/docs/api-reference/payments/latest/international-payments/collect-from-india/mark-sandbox-settlement-processed).

<Note>
  The settlement forex rate shown is notional and may differ from actual foreign exchange rates.
</Note>

#### Simulating skipped settlements

A settlement will be skipped if the settlement amount is between 0 and 1 INR, or if it is negative, the amount will be adjusted in the next settlement.

Example of how to simulate a skipped settlement:

1. Create a transaction
2. Refund the transaction
3. Trigger settlement using the API
   The settlement will be skipped since the total collection amount will be less than 0.


# Trigger Sandbox Settlement
Source: https://www.cashfree.com/docs/api-reference/payments/latest/international-payments/collect-from-india/trigger-sandbox-settlement

post /import/settlements/emulate
This API is used to trigger settlement in sandbox environment.



# Upload Payment Verification Details
Source: https://www.cashfree.com/docs/api-reference/payments/latest/international-payments/collect-from-india/upload-payment-verification-details

openapi/cb-imports/v2025-01-01.yaml post /import/transactions/{cf_payment_id}
This API is used to upload the required payment verification details.



# End Points
Source: https://www.cashfree.com/docs/api-reference/payments/latest/international-payments/global-collections/endpoints

Reference base URLs and endpoints for the Cashfree Global Collections APIs across the sandbox testing environment and the production processing environment.

## Global collections gateway end points

| Environment | Base URL |
| :- | :- |
| Test | [https://sandbox.cashfree.com/](https://sandbox.cashfree.com/) |
| Production | [https://api.cashfree.com/](https://api.cashfree.com/) |


# Overview
Source: https://www.cashfree.com/docs/api-reference/payments/latest/international-payments/global-collections/overview

Use Cashfree Global Collections to accept cross-border collections in multiple currencies through virtual accounts that settle to your home bank account.

To start using Global Collection APIs, generate your API credentials by following these steps:

1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
2. Go to **Developers**.
3. Click **API Keys** under the respective product card.
4. Select **Generate API Keys** and click **Download**.

In the test environment, keys are auto-generated. In production, click **Generate API Keys** and complete two-factor authentication.
View keys by clicking the icon and selecting **View API Key**.

<Tabs>
  <Tab title="Partner">
    <img />

    <img />
  </Tab>

  <Tab title="Merchant">
    <img />
  </Tab>
</Tabs>

***

Based on who you are, consider the below values in the API requests

<Note>
  | Cashfree Merchant | Cashfree Partner |
  | :- | :- |
  | x-client-id | x-partner-api-key |
  | x-client-secret | x-partner-merchantid |
</Note>

**Global Collections List of APIs**

| API name | Description |
| :- | :- |
| [Get Token](/docs/api-reference/payments/latest/international-payments/global-collections/partner/auth-get-token) | This API generates a new token. |
| [Verify Token](/docs/api-reference/payments/latest/international-payments/global-collections/partner/auth-verify-token) | Verify the authentication token generated. The response will be ‘Token is not valid’ if the token does not exist, invalid or has been expired. |
| [Get Collection Accounts](/docs/api-reference/payments/latest/international-payments/global-collections/partner/get-collection-accounts) | This API fetches all the virtual accounts that are linked with this account. |
| [Get Transactions](/docs/api-reference/payments/latest/international-payments/global-collections/partner/get-transactions) | Use this API to get all the transaction details within a time interval. |
| [Add Transaction Details](/docs/api-reference/payments/latest/international-payments/global-collections/partner/add-transaction-details) | Use this API to add transaction details to upload multiple invoices until the cumulative total of all invoice amounts matches the transaction amount. |
| [Simulate Transaction](/docs/api-reference/payments/latest/international-payments/global-collections/partner/simulate-transaction) | Use this API to simulate funding to any of the virtual accounts of your merchants. |


# Add Transaction Details
Source: https://www.cashfree.com/docs/api-reference/payments/latest/international-payments/global-collections/partner/add-transaction-details

post /gc/transactions/{referenceId}/invoice-details
Use this API to input invoice details for a specific transaction. You have the flexibility to upload multiple invoices until the cumulative total of all invoice amounts matches the transaction amount.

Based on who you are, consider the below values in the API requests

<Note>
  | Cashfree Merchant | Cashfree Partner |
  | :- | :- |
  | x-client-id | x-partner-api-key |
  | x-client-secret | x-partner-merchantid |
</Note>


# Get Auth Token
Source: https://www.cashfree.com/docs/api-reference/payments/latest/international-payments/global-collections/partner/auth-get-token

post /gc/authorize
Use this API to authenticate with the Cashfree system and obtain the authorization bearer token.

Based on who you are, consider the below values in the API requests

<Note>
  | Cashfree Merchant | Cashfree Partner |
  | :- | :- |
  | x-client-id | x-partner-api-key |
  | x-client-secret | x-partner-merchantid |
</Note>


# Overview
Source: https://www.cashfree.com/docs/api-reference/payments/latest/international-payments/global-collections/partner/auth-overview

Authenticate Global Collections partner API calls by generating bearer tokens, verifying token validity, and refreshing credentials before each request.

* [Get Token](/docs/api-reference/payments/previous/v2023-08-01/international-payments/global-collections/partner/auth-get-token) - Use the Get Token API to authenticate with the Cashfree system and obtain the authorization bearer token, call the authorize API.
* [Verify Token](/docs/api-reference/payments/previous/v2023-08-01/international-payments/global-collections/partner/auth-verify-token) - Verify the authentication token generated. The response will be 'Token is not valid' if the token does not exist, invalid or has been expired.


# Verify Auth Token
Source: https://www.cashfree.com/docs/api-reference/payments/latest/international-payments/global-collections/partner/auth-verify-token

get /gc/token/verify
Verify the authentication token generated by the user.



# Get Collection Accounts
Source: https://www.cashfree.com/docs/api-reference/payments/latest/international-payments/global-collections/partner/get-collection-accounts

get /gc/virtual-accounts
This API fetches all the virtual accounts that is linked with the given merchant ID.

Based on who you are, consider the below values in the API requests

<Note>
  | Cashfree Merchant | Cashfree Partner |
  | :- | :- |
  | x-client-id | x-partner-api-key |
  | x-client-secret | x-partner-merchantid |
</Note>


# Get Transactions
Source: https://www.cashfree.com/docs/api-reference/payments/latest/international-payments/global-collections/partner/get-transactions

get /gc/transactions
Use this API to get all the transaction details within a time interval.

Based on who you are, consider the below values in the API requests

<Note>
  | Cashfree Merchant | Cashfree Partner |
  | :- | :- |
  | x-client-id | x-partner-api-key |
  | x-client-secret | x-partner-merchantid |
</Note>


# Overview
Source: https://www.cashfree.com/docs/api-reference/payments/latest/international-payments/global-collections/partner/overview

Browse Cashfree Global Collections partner APIs to fetch merchant transactions, simulate funding events, and manage virtual collection accounts at scale.

* [Get All Transactions Details](/docs/api-reference/payments/latest/international-payments/global-collections/partner/get-transactions) - Use this to fetch all the transactions for a particular merchant.
* [Emulate Funding](/docs/api-reference/payments/latest/international-payments/global-collections/partner/simulate-transaction) - Use this to emulate a transaction for a specific merchant.
* [Get All Collection Accounts for Partner Merchants](/docs/api-reference/payments/latest/international-payments/global-collections/partner/get-collection-accounts) - Use this to get all VAs for a specific merchant.
* [Add Invoice Details for Partner Merchants](/docs/api-reference/payments/latest/international-payments/global-collections/partner/add-transaction-details) - Use this API to input invoice details for a specific transaction for a specific merchant.
* [Merchant Webhook Configs](/docs/api-reference/payments/latest/international-payments/global-collections/partner/webhooks) - Use this document to understand the webhooks payload events and verification.


# Simulate Transaction
Source: https://www.cashfree.com/docs/api-reference/payments/latest/international-payments/global-collections/partner/simulate-transaction

post /gc/transactions/emulate
Use this API to simulate a funding in test environment.

Based on who you are, consider the below values in the API requests

<Note>
  | Cashfree Merchant | Cashfree Partner |
  | :- | :- |
  | x-client-id | x-partner-api-key |
  | x-client-secret | x-partner-merchantid |
</Note>


# Webhook - Partner
Source: https://www.cashfree.com/docs/api-reference/payments/latest/international-payments/global-collections/partner/webhooks

Configure Global Collections partner webhooks in the Cashfree partner dashboard to receive transaction, settlement, and virtual account notifications.

### Guide to subscribe webhook events

1. Visit [https://partner.cashfree.com](https://partner.cashfree.com) login with your partner credentials
2. On the landing page click on developers section and select webhook, you will be redirected to a page to add webhook URL and subscribe events or once logged in you can use this URL [Webhook Page](https://partner.cashfree.com/partner-ui/dashboard/developers/webhook)
3. Add your webhook URL and subscribe events Global Collect Transaction, Global Collect Settlement & Global Collect Virtual Account
4. To validate the webhook signature follow [Adding webhook and signature verification guide](/docs/api-reference/platforms/latest/merchant-onboarding/webhooks#verify-signature)

### Screenshots:

<Frame>
  <img />
</Frame>

Landing page to add the webhook URL and subscribe the events

<Frame>
  <img />
</Frame>

<Note>
  We can add multiple webhook URLs for the different type of events. For testing, Switch to test and follow the same step in sandbox environment.
</Note>

## Transaction status

Active Event needs to be subscribed: **Global Collect Transaction**

```json Json theme={"dark"}
{
	"amount": "4.50",
	"currency": "GBP",
	"cmsProfileId": 123,
	"event": "INTERNATIONAL_PAYMENT_COLLECTED",
	"merchant": {
		"merchant_id": "CF_7644f46b-ad82-472c-8d97-609d1a429eac"
	},
	"paymentTime": "2022-12-29 13:42:54",
	"referenceId": 63,
	"remarks": "",
	"remitterAccount": "1223456789",
	"remitterAddress": "Dummy Address",
	"remitterBic": "TRWIBEB1XXX",
	"remitterCountry": "GB",
	"remitterName": "Dummy Sender",
	"remitterRoutingCode": "TLG0123",
	"status": "COMPLETED",
	"utr": "5347f52a-9851-4fe9-8618-32eb085590ce",
	"updatedStatusTime": "2022-12-29 13:50:35",
	"vAccountId": "97836",
	"vAccountNumber": "GB38TCCL12345687997836"
}
```

### Possible events and corresponding transaction status mapping

| Event name | Payment status | Description |
| :- | :- | :- |
| INTERNATIONAL\_PAYMENT\_COLLECTED | COMPLETED | Received payment |
| INTERNATIONAL\_PAYMENT\_BLOCKED | BLOCKED | The transaction has been blocked due to the specified reason in the designated field. |
| INTERNATIONAL\_PAYMENT\_AWAITING\_DETAILS | COMPLETED | Waiting for the details of the transaction |

### Payload field description

| Field | Description | Example |
| :- | :- | :- |
| amount | The foreign currency amount sent | 4.50 |
| currency | Three character ISO code. View list of supported currencies [here](/docs/payments/global-collections/collection-accounts#supported-currencies). | GBP |
| cmsProfileId | Merchant identifier | 123 |
| event | Webhook event | INTERNATIONAL\_AMOUNT\_COLLECTED |
| paymentTime | The time at which the payment was initiated. | 2022-12-29 13:42:54 |
| referenceId | Cashfree transaction identifier | 63 |
| remarks | Remarks passed by the sender. | Sample Remark |
| reason | Reason regarding the transaction being blocked. | Transaction value below the allowed limit |
| remitterAccount | The bank account number of the person who sends the money. | 1223456789 |
| remitterAddress | The address of the person who sends the money. | Dummy Address |
| remitterBic | Bank identifier code for the remitter. | TRWIBEB1XXX |
| remitterCountry | The country from which the money is sent. | GB |
| remitterName | The name of the remitter who is sending the money. | John Doe |
| remitterRoutingCode | The routing code of the remitter's bank. | TLG0123 |
| status | Status of FCY (foreign currency leg) of transaction. | COMPLETED, FAILED, AWAITING\_DETAILS |
| updatedStatusTime | The time of the last status update. | 2022-12-29 13:50:35 |
| vAccountId | Identifier of the virtual account. | 97836 |
| vAccountNumber | Account number to which the payment was done. | GB38TCCL12345687997836 |
| merchant | Object contains merchant\_id used while creating merchant | CF\_7644f46b-ad82-472c-8d97-609d1a429eac |

## Reversal status

```Text JSON theme={"dark"}
{
  "amount": "1000000.00",
  "cmsProfileId": 123,
  "currency": "USD",
  "event": "INTERNATIONAL_PAYMENT_REVERSAL_INITIATED",
  "merchant": {
    "merchant_id": "CF_7644f46b-ad82-472c-8d97-609d1a429eac"
  },
  "paymentTime": "2024-02-28 16:17:48",
  "referenceId": 63,
  "remitterAccount": "9919391193",
  "remitterAddress": "Dummy Address",
  "remarks": "",
  "remitterBic": "",
  "remitterCountry": "IN",
  "remitterName": "Dummy Sender",
  "remitterRoutingCode": "TLG0123",
  "reversal": {
    "reason": "Transaction value higher than the compliant limit",
    "status": "INITIATED"
  },
  "signature": "F8raBNGcGjMUvbh2t/7t/9C4zU0Snqa/iXf9XzvOq0Y=",
  "status": "REVERSAL_INITIATED",
  "updatedStatusTime": "2024-02-28 16:17:54",
  "utr": "IF-20240228-KT9ZFA",
  "vAccountId": "GB75T",
  "vAccountNumber": "GB75TCCL12345654108280"
}

```

### Possible events and corresponding transaction status mapping

| Event name | Reversal status | Transaction status | Description |
| :- | :- | :- | :- |
| INTERNATIONAL\_PAYMENT\_REVERSAL\_INITIATED | INITIATED | REVERSAL\_INITIATED | Reversal for the transaction is initiated. |
| INTERNATIONAL\_PAYMENT\_REVERSAL\_DONE | DONE | REVERSAL\_DONE | Reversal for the transaction is completed. The funds have been successfully returned to the sender. |

### Payload field description

***

## Settlement status

Active Event needs to be subscribed: **Global Collect Settlement**

```json theme={"dark"}
{
	"amount": "3500.00",
	"cmsProfileId": 23853384,
	"currency": "USD",
	"event": "INR_SETTLEMENT_INITIATED",
	"merchant": {
		"merchant_id": "CF_7644f46b-ad82-472c-8d97-609d1a429eac"
	},
	"paymentRail": "ACH",
	"paymentTime": "2024-02-06 11:11:42",
	"referenceId": 312620,
	"remarks": "EMULATE GC INCOMING FUNDS",
	"remitterAccount": "7337377781",
	"remitterAddress": "Dummy Address",
	"remitterBic": "TLG0123",
	"remitterCountry": "GB",
	"remitterName": "Dummy Sender",
	"remitterRoutingCode": "TLG0123",
	"settlement": {
		"expectedSettlementDate": "2024-02-06",
		"fxRate": 85.12,
		"id": "f16581f5-344c-40e8-be4b-e63cb5714a88",
		"inrAmount": 16219.65,
		"netPartnerCommission": 2106.72,
		"settlementCharge": 4213.44,
		"settlementChargeTax": 758.42,
		"status": "INITIATED"
	},
	"status": "READY_FOR_SETTLEMENT",
	"updatedStatusTime": "2024-02-05 18:39:42",
	"utr": "f185d0f5-abf5-492b-9149-d45eacfeaca7",
	"vAccountId": "03314",
	"vAccountNumber": "0331496070"
}
```

<Note>
  The firaFileDownloadUrl field will only be included in the webhook response
  after it has been updated.
</Note>

### Possible events and corresponding settlement status mapping

| Event name | Settlement status | Description |
| :- | :- | :- |
| INR\_SETTLEMENT\_INITIATED | INITIATED | The settlement is initiated. |
| INR\_SETTLEMENT\_APPROVED | SETTLED | The settlement is settled. |
| INR\_SETTLEMENT\_REJECTED | REJECTED | The settlement is rejected. |
| FIRA\_FILE\_RECEIVED | SETTLED | FIRA file received for the settlement. |

### Payload field description

| Field | Description | Example |
| :- | :- | :- |
| amount | The foreign currency amount sent | 4.50 |
| currency | Three character ISO code. View list of [supported currencies](/docs/payments/international-payments/global-collections/collection-accounts#supported-currencies). | GBP |
| cmsProfileId | Merchant identifier | 123 |
| event | Webhook event | INTERNATIONAL\_AMOUNT\_COLLECTED |
| merchant | Object contains the merchant\_id to map the merchant created. | CF\_7644f46b-ad82-472c-8d97-609d1a429eac |
| paymentTime | The time at which the payment was initiated. | 2022-12-29 13:42:54 |
| referenceId | Cashfree transaction identifier | 63 |
| remarks | Remarks passed by the sender. | Sample Remark |
| remitterAccount | The bank account number of the person who sends the money. | 1223456789 |
| remitterAddress | The address of the person who sends the money. | Dummy Address |
| remitterBic | Bank identifier code for the remitter. | TRWIBEB1XXX |
| remitterCountry | The country from which the money is sent. | GB |
| remitterName | The name of the remitter who is sending the money. | John Doe |
| remitterRoutingCode | The routing code of the remitter's bank. | TLG0123 |
| status | Status of FCY (foreign currency leg) of transaction. | COMPLETED, FAILED |
| updatedStatusTime | The time of the last status update. | 2022-12-29 13:50:35 |
| vAccountId | Identifier of the virtual account. | 97836 |
| vAccountNumber | Account number to which the payment was made. | GB38TCCL12345687997836 |
| paymentRail | Payment Network used to make the payment | ACH,EFT,FPS,SEPA,SWIFT,FEDWIRE |
| settlement.id | Unique reference ID for the settlement since the payment can have multiple settlements. | b84a7c4c-2ce0-48ca-9b86-2a2c9ad5a35d |
| settlement.fxRate | The foreign exchange rate used for currency conversion between the transaction currency and settlement currency | 85.12 |
| settlement.netPartnerCommission | The final commission amount payable to the partner after deducting all applicable fees and charge | 2106.72 |
| settlement.settlementCharge | Service fees charged for facilitating the settlement | 4213.44 |
| settlement.settlementChargeTax | Applicable tax amount levied on the settlement service charges | 758.42 |
| settlement.inrAmount | Settlement amount in rupees (INR). | 16219.65 |
| settlement.firafileDownloadUrl | Download link to FIRA file | fileDownloadUrl |
| settlement.status | Current status of the settlement. | INITIATED |

## Virtual account details

Active Event needs to be subscribed: **Global Collect Virtual Account**

```json Json theme={"dark"}
{
	"cmsProfileId": 260559,
	"event": "VIRTUAL_ACCOUNT_DETAILS",
	"merchant": {
		"merchant_id": "CF_7644f46b-ad82-472c-8d97-609d1a429eac"
	},
	"vAccounts": [
		{
			"accountName": "John Doe",
			"accountNumber": "GB11TCCL12345638242754",
			"accountType": "iban",
			"paymentType": "priority",
			"bankName": "The Currency Cloud Limited",
			"bankAddress": "12 Steward Street, The Steward Building, London, E1 6FQ, GB",
			"bankCountry": "GB",
			"currency": "AUD",
			"routingCode": "TCCLGB3L",
			"routingCodeType": "bic_swift",
			"addedOn": "2023-03-28 14:43:30",
			"vaccountId": "GB11T"
		},
		{
			"accountName": "John Doe",
			"accountNumber": "GB11TCCL12345638242754",
			"accountType": "iban",
			"paymentType": "priority",
			"bankName": "The Currency Cloud Limited",
			"bankAddress": "12 Steward Street, The Steward Building, London, E1 6FQ, GB",
			"bankCountry": "GB",
			"currency": "BHD",
			"routingCode": "TCCLGB3L",
			"routingCodeType": "bic_swift",
			"addedOn": "2023-03-28 14:43:30",
			"vaccountId": "GB11T"
		}
	]
}
```

### Possible events and corresponding virtual account mapping

| Event name | Virtual account status | Description |
| - | - | - |
| VIRTUAL\_ACCOUNTS\_ACTIVATED | ACTIVE | Virtual account is activated |
| VIRTUAL\_ACCOUNTS\_CREATED | INACTIVE / ACTIVE | If all the business required details are passed in the first go, VAs are created in ACTIVE state or INACTIVE |
| VIRTUAL\_ACCOUNT\_DETAILS | ACTIVE | Will contain all the details of the VA |

#### Description

Sometimes there is mere might be a slight delay in creating some virtual accounts during onboarding and as a result, some of them might be missing in the Get All Collection Accounts API. Hence, when these missing account details are added, this webhook is triggered with all virtual account details (including the ones that were present before). This webhook contains information for all virtual account associated with a merchant along with cmsProfileId , signature and event.

### Payload field description

| Field | Description | Example |
| :- | :- | :- |
| cmsProfileId | Merchant identifier | 123 |
| event | Webhook Event | VIRTUAL\_ACCOUNT\_DETAILS |
| merchant | Object contains the merchant\_id to map the merchant created. | CF\_7644f46b-ad82-472c-8d97-609d1a429eac |
| vAccounts.accountName | Account Name | John Doe |
| vAccounts.accountNumber | Account Number | GB11TCCL12345638242754 |
| vAccounts.accountType | Account Type | iban |
| vAccounts.paymentType | Type of Payment | priority |
| vAccounts.bankName | Bank Name | The Currency Cloud Limited |
| vAccounts.bankAddress | Bank Address | 12 Steward Street, The Steward Building, London, E1 6FQ, GB |
| vAccounts.bankCountry | Bank Country | GB |
| vAccounts.currency | Currency Code | BHD |
| vAccounts.routingCode | Routing Code | TCCLGB3L |
| vAccounts.routingCodeType | Routing Code Type | bic\_swift |
| vAccounts.addedOn | The time when this virtual account was created | 2023-03-28 14:43:30 |
| vAccounts.vaccountId | Virtual Account Id | GB11T |


# Purpose Codes
Source: https://www.cashfree.com/docs/api-reference/payments/latest/international-payments/global-collections/purpose-codes

Reference FEMA-compliant purpose codes used with Cashfree Global Collections to declare the nature of inward remittances from overseas customers.

| Purpose code | Description |
| - | - |
| P0103 | Advance receipts against export contracts, which will be covered later by GR/PP/SOFTEX/ SDF - other than Nepal and Bhutan |
| P1004 | Legal services |
| P1005 | Accounting, auditing, bookkeeping services |
| P1006 | Business and management consultancy and public relations |
| P1007 | Advertising, trade fair service |
| P1008 | Research & Development services |
| P1009 | Architectural services |
| P0802 | Software consultancy / implementation (other than those covered in SOFTEX form) |
| P0807 | For Export of Software covered under softex (advance payment) |
| P1020 | Wholesale and retailing trade services |
| P1002 | Trade related services - commission on exports / imports |
| P1104 | Entertainment services |
| P1099 | Other services not included elsewhere, for export of services |
| P1015 | Tax consulting services |
| P1016 | Market research and public opinion polling service |
| P1017 | Publishing and printing services |
| P1019 | Commission agent services |
| P1107 | Educational services |
| P1109 | Other Personal, Cultural & Recreational services |
| P1701 | Receipts on account of processing of goods |
| P0301 | Purchases towards travel (Includes purchases of foreign TCs, currency notes etc over the counter, by hotels, Emporiums, institutions etc. as well as amount received by TT/SWIFT transfers or debit to Non-Resident account). |
| P0302 | Business travel |
| P0304 | Travel for medical treatment including TC purchased by hospitals |
| P0305 | Travel for education including TCs purchased by educational institutions |
| P0306 | Other travel receipts |
| P0801 | Hardware consultancy/implementation |
| P0803 | Data base, data processing charges |
| P0804 | Repair and maintenance of computer and software |
| P0805 | News agency services |
| P0806 | Other information services- Subscription to newspapers, periodicals, etc. |
| P0808 | Telecommunication services including electronic mail services and voice mail services |
| P1013 | Environmental Services |
| P1014 | Engineering Services |
| P1101 | Audio-visual & related service:Motion picture & video tape production, distribution & projection service |
| P1103 | Radio & TV production,distribution & transmission service |
| P1105 | Museums, library and archival services |
| P1106 | Recreation and sporting activity services |
| P1108 | Health Service provided by Indian hospitals,doctors,nurses,paramedical remotely/on-site) |


# Overview
Source: https://www.cashfree.com/docs/api-reference/payments/latest/international-payments/overview

Explore the Cashfree International Payments APIs that help businesses accept and disburse cross-border transactions in multiple currencies and regions.

You can use the Cashfree API in test mode, which doesn't affect your live data or interact with the banking networks. The API key you use to authenticate the request determines whether the request is live mode or test mode.

<CardGroup>
  <Card title="Collect from India" href="/docs/api-reference/payments/latest/international-payments/collect-from-india/overview">
    For overseas businesses to collect payments from Indian customers
  </Card>

  <Card title="Collect from the World" href="/docs/api-reference/payments/latest/international-payments/global-collections/overview">
    For Indian businesses to collect payments from customers worldwide
  </Card>
</CardGroup>


# Create Offer
Source: https://www.cashfree.com/docs/api-reference/payments/latest/offers/create-offer

openapi/payments/v2026-01-01.yaml post /offers
Use this API to create offers with Cashfree from your backend.



# Get Offer by ID
Source: https://www.cashfree.com/docs/api-reference/payments/latest/offers/get-offer-by-id

openapi/payments/v2026-01-01.yaml get /offers/{offer_id}
Use this API to get offer by offer_id.



# Create Terminal
Source: https://www.cashfree.com/docs/api-reference/payments/latest/offline-payments/create-terminal

openapi/payments/v2026-01-01.yaml post /terminal
Use this API to create new terminals to use softPOS.



# Create Terminal Transaction
Source: https://www.cashfree.com/docs/api-reference/payments/latest/offline-payments/create-terminal-transaction

openapi/payments/v2026-01-01.yaml post /terminal/transactions
Use this API to create a new terminal transaction. To use this API you should first create an order using the Create Order API. Also, you need to enter the terminal details while creating the order and pass the same terminal information while creating a transaction using the below mentioned API.



# Demap Soundbox VPA
Source: https://www.cashfree.com/docs/api-reference/payments/latest/offline-payments/demap-soundbox-vpa

openapi/payments/v2026-01-01.yaml post /terminal/demap/soundbox
Use this API to demap a device from soundbox.



# Fetch Terminal QR Codes
Source: https://www.cashfree.com/docs/api-reference/payments/latest/offline-payments/fetch-terminal-qr-codes

openapi/payments/v2026-01-01.yaml get /terminal/qrcodes
You can fetch all the StaticQRs corresponding to given terminal id or phone number. Provide either the terminal_phone_no or terminal_id in the request.



# Fetch Terminal Soundbox VPA
Source: https://www.cashfree.com/docs/api-reference/payments/latest/offline-payments/fetch-terminal-soundbox-vpa

openapi/payments/v2026-01-01.yaml get /terminal/soundbox/qrcodes
You can fetch all the active and mapped SoundboxVpa corresponding to given terminal id or deviceSerialNo. Provide either the device_serial_no or cf_terminal_id in the request.



# Get list of terminal transactions
Source: https://www.cashfree.com/docs/api-reference/payments/latest/offline-payments/get-list-of-terminal-transactions

openapi/payments/v2026-01-01.yaml post /terminal/payments
Use this API to fetch a paginated list of terminal payment transactions. You can filter results by date range, terminal details, payment status, and other criteria.



# Get Terminal Status using Phone Number
Source: https://www.cashfree.com/docs/api-reference/payments/latest/offline-payments/get-terminal-status-using-phone-number

openapi/payments/v2026-01-01.yaml get /terminal/{terminal_phone_no}
Use this API to view all details of a terminal.



# Get Terminal Transaction
Source: https://www.cashfree.com/docs/api-reference/payments/latest/offline-payments/get-terminal-transaction

openapi/payments/v2026-01-01.yaml get /terminal/{cf_terminal_id}/payments
Use this API to get  terminal transaction.



# Onboard Soundbox VPA
Source: https://www.cashfree.com/docs/api-reference/payments/latest/offline-payments/onboard-soundbox-vpa

openapi/payments/v2026-01-01.yaml post /terminal/soundbox
Use this API to onboard a terminal Vpa to soundbox.



# Offline Payments Webhooks
Source: https://www.cashfree.com/docs/api-reference/payments/latest/offline-payments/softpos-webhooks

Receive Cashfree Offline Payments webhooks for in-person card and UPI transactions so your servers learn about completions, failures, and refunds.

Configure an endpoint to receive instant notifications when your terminal's status changes through Cashfree Offline Payments.

## Terminal status update webhook

The terminal status update webhook is triggered when a terminal's status changes. The payload includes the updated terminal details and the event timestamp.

```java theme={"dark"}
{
    "data": {
        "added_on": "2024-03-07 15:11:02",
        "cf_terminal_id": 1234,
        "last_updated_on": "2024-04-26 12:16:08",
        "terminal_id": 1233,
        "terminal_name": "ABC",
        "terminal_phone": "9696969696",
        "terminal_status": "PROVISIONALLY_ACTIVE",
        "terminal_type": "STOREFRONT",
        "review_remarks": "approved"
    },
    "event_time": "2024-04-26T12:16:08+05:30",
    "type": "TERMINAL_STATUS_UPDATE"
}
```


# Update Soundbox VPA
Source: https://www.cashfree.com/docs/api-reference/payments/latest/offline-payments/update-soundbox-vpa

openapi/payments/v2026-01-01.yaml patch /terminal/{cf_terminal_id}/soundbox
Use this API to update a terminal Vpa to soundbox.



# Update Terminal
Source: https://www.cashfree.com/docs/api-reference/payments/latest/offline-payments/update-terminal

openapi/payments/v2026-01-01.yaml patch /terminal/{cf_terminal_id}
Use this API to update the terminal details. Email, Phone Number, and Terminal Meta are updatable for "Storefront". Only account status change is possible in case of "Agent".



# Update Terminal Status
Source: https://www.cashfree.com/docs/api-reference/payments/latest/offline-payments/update-terminal-status

openapi/payments/v2026-01-01.yaml patch /terminal/{cf_terminal_id}/status
Use this API to update the terminal status.



# Upload Terminal Docs
Source: https://www.cashfree.com/docs/api-reference/payments/latest/offline-payments/upload-terminal-docs

openapi/payments/v2026-01-01.yaml post /terminal/{cf_terminal_id}/docs
Use this API to upload the terminal documents.



# Create Order
Source: https://www.cashfree.com/docs/api-reference/payments/latest/orders/create-order

openapi/payments/v2026-01-01.yaml post /orders


An order is an entity which has a amount and currency associated with it. It is something for which you want to collect payment for.
Use this API to create orders with Cashfree from your backend to get a `payment_sessions_id`. 
You can use the `payment_sessions_id` to create a transaction for the order.




# Get Order
Source: https://www.cashfree.com/docs/api-reference/payments/latest/orders/get-order

openapi/payments/v2026-01-01.yaml get /orders/{order_id}
Use this API to fetch the order that was created at Cashfree's using the `order_id`. 
## When to use this API
- To check the status of your order


<Note>This API allows you to retrieve order data for the current and previous financial years. To access data older than this period, log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login)</Note>


# Get Order Extended
Source: https://www.cashfree.com/docs/api-reference/payments/latest/orders/get-order-extended

openapi/payments/v2026-01-01.yaml get /orders/{order_id}/extended
Use this API to fetch the order related data like address,cart,offers,customer details etc using the Cashfree's `order_id`.
## When to use this API
- To get the extended data associated with order.


<Note>This API allows you to retrieve order data for the current and previous financial years. To access data older than this period, log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login)</Note>


# Terminate Order
Source: https://www.cashfree.com/docs/api-reference/payments/latest/orders/terminate-order

openapi/payments/v2026-01-01.yaml patch /orders/{order_id}
Use this API to terminate the order that was created at Cashfree's using the `order_id`.



# Update Order Extended
Source: https://www.cashfree.com/docs/api-reference/payments/latest/orders/update-order-extended

openapi/payments/v2026-01-01.yaml put /orders/{order_id}/extended
Use this api to update the order related data like shipment details,order delivery status etc.
## When to use this API
- To provide/update the shipment details or order delivery status.
- Once the order is PAID.




# Overview
Source: https://www.cashfree.com/docs/api-reference/payments/latest/overview

Learn details about the 2026-01-01 version of our Payment APIs.

## Payment Gateway endpoints

Use the following base URLs depending on whether you are testing or processing live payments.

| Environment | Base URL |
| :- | :- |
| Test | `https://sandbox.cashfree.com/pg` |
| Production | `https://api.cashfree.com/pg` |
| Latest version | v6, 2026-01-01  <br />The previous versions were 2025-01-01, 2023-08-01, 2021-05-21, 2022-01-01, and 2022-09-01 |

## Authentication

All APIs require authentication except `POST /orders/sessions`, which does not require credentials and can be called directly from the browser.

For authentication details for merchants and partners, see [API authentication](/docs/api-reference/authentication).

## Payment gateway APIs

The following sections list all available APIs grouped by function.

### Orders

Use these APIs to create and manage payment orders.

| API | Description |
| :- | :- |
| [Create Order](/docs/api-reference/payments/latest/orders/create-order) | Use this API to create orders with Cashfree from your backend and get the payment link. |
| [Order Pay](/docs/api-reference/payments/latest/payments/order-pay) | Use this API when you have already created the orders and want Cashfree to process the payment. |
| [Preauthorization](/docs/api-reference/payments/latest/payments/preauthorisation) | Use this API to capture or void a preauthorized payment. |
| [Get Order](/docs/api-reference/payments/latest/orders/get-order) | Use this API to view all details of an order. |

### Authentication

Use this API to submit or resend an OTP during a payment flow.

| API | Description |
| :- | :- |
| [Submit or Resend OTP](/docs/api-reference/payments/latest/payments/submit-or-resend-otp) | Use the submit or resend OTP API to send OTP to Cashfree. |

### Payments

Use these APIs to retrieve payment details for an order.

| API | Description |
| :- | :- |
| [Get Payments for an Order](/docs/api-reference/payments/latest/payments/get-payments-for-an-order) | Use this API to view all payment details for an order. |
| [Get Payment by ID](/docs/api-reference/payments/latest/payments/get-payment-by-id) | Use this API to view payment details of an order for a payment ID. |

### Settlements

Use these APIs to fetch settlement details for individual orders or across a date range.

| API | Description |
| :- | :- |
| [Get Settlements by Order ID](/docs/api-reference/payments/latest/settlements/get-settlements-by-order-id) | Use this API to view all the settlements of a particular order. |
| [Get All Settlements](/docs/api-reference/payments/latest/settlement-reconciliation/get-all-settlements) | Use this API to get all settlement details by specifying the settlement ID, settlement UTR or date range. |

### Payment links

Use these APIs to create, retrieve, and manage payment links.

| API | Description |
| :- | :- |
| [Create Payment Link](/docs/api-reference/payments/latest/payment-links/create-payment-link) | Use this API to create a new payment link. The created payment link url will be available in the API response parameter link\_url. |
| [Fetch Payment Link Details](/docs/api-reference/payments/latest/payment-links/fetch-payment-link-details) | Use this API to view all details and status of a payment link. |
| [Get Orders for a Payment Link](/docs/api-reference/payments/latest/payment-links/get-orders-for-a-payment-link) | Use this API to view all order details for a payment link. |
| [Cancel Payment Link](/docs/api-reference/payments/latest/payment-links/cancel-payment-link) | Use this API to cancel a payment link. No further payments can be done against a cancelled link. Only a link in ACTIVE status can be cancelled. |

### Token vault

Use these APIs to manage saved payment instruments for a customer.

| API | Description |
| :- | :- |
| [Fetch All Saved Instruments](/docs/api-reference/payments/latest/token-vault/fetch-all-saved-card-instrument) | Use this API to get all saved instruments for a customer ID. |
| [Fetch Single Saved Instrument](/docs/api-reference/payments/latest/token-vault/fetch-specific-saved-card-instrument) | Use this API to get specific saved instrument for a customer id and instrument ID. |
| [Delete Saved Instrument](/docs/api-reference/payments/latest/token-vault/delete-saved-card-instrument) | Use this API to delete a saved instrument for a customer id and instrument ID. |
| [Fetch Cryptogram for Saved Instrument](/docs/api-reference/payments/latest/token-vault/fetch-cryptogram-for-a-saved-card-instrument) | Use this API to get the card network token, token expiry and cryptogram for a saved instrument using instrument ID. |

### Reconciliation

Use these APIs to fetch reconciliation reports for settlements and payment gateway transactions.

| API | Description |
| :- | :- |
| [Settlement Reconciliation](/docs/api-reference/payments/latest/settlement-reconciliation/settlement-reconciliation) | Use this API to get settlement reconciliation details using Settlement ID, settlement UTR or date range. |
| [PG Reconciliation](/docs/api-reference/payments/latest/pg-reconciliation/pg-reconciliation) | Use this API to get the payment gateway reconciliation details with date range. |


# Cancel Payment Link
Source: https://www.cashfree.com/docs/api-reference/payments/latest/payment-links/cancel-payment-link

openapi/payments/v2026-01-01.yaml post /links/{link_id}/cancel
Use this API to cancel a payment link. No further payments can be done against a cancelled link. Only a link in ACTIVE status can be cancelled.



# Create Payment Link
Source: https://www.cashfree.com/docs/api-reference/payments/latest/payment-links/create-payment-link

openapi/payments/v2026-01-01.yaml post /links
Use this API to create a new payment link. The created payment link url will be available in the API response parameter link_url.

<Note>
  SMS notifications are sent only in the production environment. In the sandbox environment, only email notifications are sent if enabled.
</Note>


# Fetch Payment Link Details
Source: https://www.cashfree.com/docs/api-reference/payments/latest/payment-links/fetch-payment-link-details

openapi/payments/v2026-01-01.yaml get /links/{link_id}
Use this API to view all details and status of a payment link.



# Get Orders for a Payment Link
Source: https://www.cashfree.com/docs/api-reference/payments/latest/payment-links/get-orders-for-a-payment-link

openapi/payments/v2026-01-01.yaml get /links/{link_id}/orders
Use this API to view all order details for a payment link.



# Payment Link Webhooks
Source: https://www.cashfree.com/docs/api-reference/payments/latest/payment-links/webhooks

Receive Cashfree Payment Link webhook events when customers pay, partially pay, cancel, or expire links, so your backend can update orders automatically.

## Webhook Schema

Payment Link webhook will be triggered when your customer makes a complete or partial payment using the payment link you shared. You will also be notified via the same webhook when the payment link gets cancelled or expired.

```json theme={"dark"}
{
	"data": {
		"cf_link_id": 1576977,
		"link_id": "payment_ps11",
		"link_status": "PARTIALLY_PAID",
		"link_currency": "INR",
		"link_amount": "200.12",
		"link_amount_paid": "55.00",
		"link_partial_payments": true,
		"link_minimum_partial_amount": "11.00",
		"link_purpose": "Payment for order 10",
		"link_created_at": "2021-08-18T07:13:41",
		"customer_details": {
			"customer_phone": "9000000000",
			"customer_email": "john@gmail.com",
			"customer_name": "John "
		},
		"link_meta": {
			"notify_url": "https://ee08e626ecd88c61c85f5c69c0418cb5.m.pipedream.net"
		},
		"link_url": "https://payments-test.cashfree.com/links//U1mgll3c0e9g",
		"link_expiry_time": "2021-11-28T21:46:20",
		"link_notes": {
			"note_key_1": "note_value_1"
		},
		"link_auto_reminders": true,
		"link_notify": {
			"send_sms": true,
			"send_email": true
		},
		"order": {
			"order_amount": "22.00",
			"order_id": "CFPay_U1mgll3c0e9g_ehdcjjbtckf",
			"order_expiry_time": "2021-08-18T07:34:50",
			"order_hash": "Gb2gC7z0tILhGbZUIeds",
			"transaction_id": 1021206,
			"transaction_status": "SUCCESS"
		}
	},
	"type": "PAYMENT_LINK_EVENT",
	"version": 1,
	"event_time": "2021-08-18T12:55:06+05:30"
}
```

***

## Payload

| Field | Description | Example |
| :- | :- | :- |
| `cf_link_id` | Unique Identifier (generated by Cashfree) for this Link. | 1543566 |
| `link_id` | Unique Identifier (provided by merchant) for the Link. Only for merchant reference. | payment\_1psw |
| `link_status` | Current status of the payment link. Possible values: PAID, PARTIALLY\_PAID, EXPIRED, CANCELLED. | PARTIALLY\_PAID |
| `link_currency` | Default is INR. International currencies are supported. | INR |
| `link_amount` | The amount which merchant wants to collect for the order. | 500.00 |
| `link_amount_paid` | The amount paid by the customer. | 250.00 |
| `link_partial_payments` | Indicates if partial payments are allowed or not. Default value is false. | true |
| `link_minimum_partial_amount` | The minimum amount which must be paid by customer as the first payment. | 200.00 |
| `link_purpose` | A brief description for which payment must be collected. This is shown to the customer. | Payment for order 10 |
| `link_created_at` | Time at which the link was created. | 2021-08-18T07:13:41 |
| `customer_details` | Customer object, it contains customer details. | |
| `customer_name` | Name of the customer | John |
| `customer_phone` | Phone number of the customer | 9000000000 |
| `customer_email` | Email ID of the customer | [john@gmail.com](mailto:john@gmail.com) |
| `notify_url` | Payment notification URL | [https://payment1notify.net](https://payment1notify.net) |
| `link_url` | Payment link URL | [https://website.com/payments](https://website.com/payments) |
| `link_expiry_time` | The date till which the link will be valid, and then it will be expired. Default is 30 days. | 2021-11-28T21:46:20 |
| `link_notes` | Link notes object where you can provide any key-value pairs for your internal reference. | |
| `note_key_1` | | note\_value\_1 |
| `link_auto_reminders` | Default is false. Reminders will be sent to customers based on defined settings. | true |
| `link_notify` | Link notify object, used to notify customers via SMS or an email. | |
| `send_sms` | Default is true. If true, Cashfree will send the link to customer via SMS. | true |
| `send_email` | Default is true. If true and `customer_email` is provided, Cashfree will send the link via Email. | true |
| `order` | Order object, contains the order details. Will be null for cancelled and expired link statuses. | |
| `order_amount` | Order amount that the customer must pay. | 700 |
| `order_id` | The order ID generated. | order\_10 |
| `order_expiry_time` | The date till which the order will be valid. Default is 30 days. | 2021-08-18T07:34:50 |
| `transaction_id` | Transaction ID | id45466ye |
| `transaction_status` | Status of the transaction. Possible values: SUCCESS. | SUCCESS |
| `type` | Type of the webhook. `PAYMENT_LINK_EVENT` | PAYMENT\_LINK\_EVENT |
| `version` | The version of webhook. Build parsing logic with respect to this version. | 1 |
| `event_time` | Time when this webhook was created. | 2021-08-18T12:55:06+05:30 |

***

## Signature generation

The signature must be used to verify if the request has not been tampered with. To verify the signature at your end, you will need your Cashfree Payment Gateway secret key along with the payload.

```javascript theme={"dark"}
// The payload here refers to the raw request sent by
// Cashfree to your endpoint. No modifications need to be made to this payload.
{
    "data": {
        "cf_link_id": 1576977,
        "link_id": "payment_ps11",
        "link_status": "PARTIALLY_PAID",
        "link_currency": "INR",
        "link_amount": "200.12",
        "link_amount_paid": "55.00",
        "link_partial_payments": true,
        "link_minimum_partial_amount": "11.00",
        "link_purpose": "Hello my friend how are you",
        "link_created_at": "2021-08-18T07:13:41",
        "customer_details": {
            "customer_phone": "9905736722",
            "customer_email": "customer@example.com",
            "customer_name": "Supal "
        },
        "link_meta": { ... }
    }
}
```

<Note>We send the webhook response in a form data format.</Note>


# Get Payment by ID
Source: https://www.cashfree.com/docs/api-reference/payments/latest/payments/get-payment-by-id

openapi/payments/v2026-01-01.yaml get /orders/{order_id}/payments/{cf_payment_id}
Use this API to view payment details of an order for a payment ID.

## Error codes

The following table lists the error codes you may encounter when retrieving payment details for an order using a payment ID:

<Accordion title="Error codes">
  | Code | Description | Type | Status |
  | :- | :- | :- | :- |
  | `order_id_invalid` | The `order_id` field contains a value in an invalid format. Provide a correctly formatted order ID and try again. Value received: `#INVALID` | `invalid_request_error` | 400 |
  | `order_id_missing` | The `order_id` field is required but was not included in the request. | `invalid_request_error` | 400 |
  | `version_missing` | The `version` field is required but was not included in the request header. | `invalid_request_error` | 400 |
  | `payment_id_invalid` | The `payment_id` field must be a numeric value. Value received: `INVALID` | `invalid_request_error` | 400 |
  | `payment_get_failed` | The `payment_id` value is out of the supported integer range and cannot be processed. Value received: `100000000000000000000000000000000000000` | `invalid_request_error` | 400 |
  | `payment_id_missing` | The `payment_id` field is required but was not included in the request. | `invalid_request_error` | 400 |
  | `payment_not_found` | No transaction was found for the specified payment ID. Verify the payment ID and try again. | `invalid_request_error` | 404 |
  | `order_not_found` | No order was found for the specified order reference ID. Verify the order ID and try again. | `invalid_request_error` | 404 |
</Accordion>

<Note>This API allows you to retrieve payment data for the current and previous financial years. To access data older than this period, log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login)</Note>


# Get Payments for an Order
Source: https://www.cashfree.com/docs/api-reference/payments/latest/payments/get-payments-for-an-order

openapi/payments/v2026-01-01.yaml get /orders/{order_id}/payments
Use this API to view all payment details for an order.

<Note>This API allows you to retrieve payment data for the current and previous financial years. To access data older than this period, log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login)</Note>


# Order Pay
Source: https://www.cashfree.com/docs/api-reference/payments/latest/payments/order-pay

openapi/payments/v2026-01-01.yaml post /orders/sessions
Use this API when you have already created the order using [Create Order API](https://www.cashfree.com/docs/api-reference/payments/latest/orders/create) and want Cashfree to process the payment. To use this API S2S flag needs to be enabled from the backend. In case you want to use this API for plain cards payments also, the PCI DSS flag is required, for more information fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod&raise_issue=1).


<Note>
  **S2S enablement required**: To call the Seamless Payment Creation API, make sure the required S2S flag is enabled for your account. To enable it, submit a request through the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1).

  * **S2S card flag**: To enable card payments, share your PCI DSS compliance certificate through the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1).
  * **Main S2S flag for other payment modes**: To enable seamless payments for modes other than cards, submit a GST return showing an annual turnover of more than Rs. 1 crore. After the document is verified, Cashfree enables the seamless flow.
</Note>

## Client environment headers

Cashfree requires information about the customer's device environment to enforce NPCI rules. You must include the following headers in your Order Pay API and [Get Eligible Payment Methods](/docs/api-reference/payments/latest/eligibility/get-eligible-payment-methods) request:

<Accordion title="Client environment headers">
  | Header | Accepted values | Requirement | Description |
  | - | - | - | - |
  | `x-client-device` | `mobile`, `desktop`, `tablet` | Required | Type of device used by customer |
  | `x-client-os` | `android`, `ios`, `windows`, `macos`, `linux`, `others` | Required | Operating system of customer's device |
  | `x-client-rendering-type` | `mweb`, `webview`, `native` | Required when `x-client-device` is mobile | Rendering method used for the checkout experience |
  | `x-client-browser` | `safari`, `chrome`, `firefox`, `edge`, `others` | Required | Browser used by the customer |
</Accordion>

<Note>`x-client-rendering-type` is required only when `x-client-device` is set to mobile. For desktop and tablet devices, this header is optional.</Note>

## Error codes

The following table lists the error codes, descriptions, and types you may encounter when initiating a payment:

<Accordion title="Error codes">
  | Code | Description | Type | Status |
  | :- | :- | :- | :- |
  | `channel_missing` | The `channel` field is required but was not included in the request. | `invalid_request_error` | 400 |
  | `phone_invalid` | The `phone` field must contain a valid 10-digit Indian phone number (for example, `9090407368`). Value received: `1234567890` | `invalid_request_error` | 400 |
  | `phone_missing` | The `phone` field is required but was not included in the request. | `invalid_request_error` | 400 |
  | `provider_missing` | The `provider` field is required but was not included in the request. | `invalid_request_error` | 400 |
  | `version_missing` | The `version` field must be one of the following supported values: `2021-05-21`, `2022-01-01`, `2022-09-01`, `2023-08-01`, `2025-01-01`, or `2026-01-01`. | `invalid_request_error` | 400 |
  | `card_cvv_invalid` | The `card_cvv` field must be at least 3 characters long. Value received: `12` | `invalid_request_error` | 400 |
  | `card_cvv_missing` | The `card_cvv` field is required but was not included in the request. | `invalid_request_error` | 400 |
  | `card_invalid` | The `card` field is invalid. Provide payment details using one of the following: card details, `card_alias`, `instrument_id`, or `cryptogram`. | `invalid_request_error` | 400 |
  | `bank_processing_failure` | The transaction could not be created at the banking partner. Retry the request or contact support if the issue persists. | `api_error` | 502 |
  | `request_invalid` | Cards issued in India cannot be used for transactions where the order currency is non-INR. Value received: `AUD` | `invalid_request_error` | 400 |
  | `orderpay_not_found` | The specified order is no longer active and cannot be used to initiate a payment. | `invalid_request_error` | 404 |
  | `card_bank_name_missing` | The `card_bank_name` field is required but was not included in the request. | `invalid_request_error` | 400 |
  | `card_bank_name_invalid` | The `card_bank_name` field contains an unrecognised value. Accepted values are: `hdfc`, `icici`, `kotak`, `rbl`, `bob`, `axis`, `standard chartered`, `au`, `yes`, `indus`, `fed`, `hsbc`, `citi`, `sbi`, `amex`, `onecard`, or `idfc`. Value received: `INVALID$BANK` | `invalid_request_error` | 400 |
  | `card_expiry_yy_missing` | The `card_expiry_yy` field is required but was not included in the request. | `invalid_request_error` | 400 |
  | `card_expiry_yy_invalid` | The `card_expiry_yy` field must be at least 2 characters long. Value received: `0` | `invalid_request_error` | 400 |
  | `card_expiry_mm_missing` | The `card_expiry_mm` field is required but was not included in the request. | `invalid_request_error` | 400 |
  | `card_expiry_mm_invalid` | The `card_expiry_mm` field must be at least 2 characters long. Value received: `0` | `invalid_request_error` | 400 |
  | `card_number_invalid` | The `card_number` field contains an invalid card number. Verify the card number and try again. Value received: `INVALID` | `invalid_request_error` | 400 |
  | `card_number_missing` | The `card_number` field is required but was not included in the request. | `invalid_request_error` | 400 |
  | `card_not_found` | The card details could not be retrieved. Verify the card information and try again. | `invalid_request_error` | 404 |
  | `emi_tenure_missing` | The `emi_tenure` field is required but was not included in the request. | `invalid_request_error` | 400 |
  | `order_amount_invalid` | The order amount exceeds the maximum allowed value. The amount must be less than `1,000,000`. | `invalid_request_error` | 400 |
  | `netbanking_account_number_invalid` | The `netbanking_account_number` field must be at least 9 characters long. Value received: `test` | `invalid_request_error` | 400 |
  | `netbanking_bank_code_invalid` | The `netbanking_bank_code` field contains an invalid value. Provide a supported bank code and try again. | `invalid_request_error` | 400 |
  | `netbanking_ifsc_invalid` | The `netbanking_ifsc` field contains an invalid IFSC code. Verify the IFSC and try again. Value received: `INVALID` | `invalid_request_error` | 400 |
  | `request_failed` | The selected payment mode is not configured for this account. Enable the payment mode or contact support. | `invalid_request_error` | 400 |
  | `currency_invalid` | The `currency` field does not accept `INR` for this request. Use a supported non-INR currency. Value received: `INR` | `invalid_request_error` | 400 |
  | `currency_missing` | The `currency` field is required but was not included in the request. | `invalid_request_error` | 400 |
  | `risk_data.customer_ip_invalid` | The `risk_data.customer_ip` field contains an invalid IP address. Provide a valid IPv4 or IPv6 address. Value received: `1.1.1` | `invalid_request_error` | 400 |
  | `risk_data_ip_address_request_failed` | The IP address could not be resolved. Verify the IP address and try again. | `invalid_request_error` | 400 |
  | `order_token_missing` | The `order_token` field is required but was not included in the request. | `invalid_request_error` | 400 |
  | `payment_method_invalid` | The `payment_method` field contains an unrecognised value. Provide a valid payment method and try again. | `invalid_request_error` | 400 |
  | `payment_method_missing` | The `payment_method` field is required but was not included in the request. | `invalid_request_error` | 400 |
  | `payment_method_unsupported` | The specified payment method is not supported for this request. Use a supported payment method and try again. | `invalid_request_error` | 400 |
</Accordion>


# Order Pay Authorise Only
Source: https://www.cashfree.com/docs/api-reference/payments/latest/payments/order-pay-authorise-only

openapi/payments/v2026-01-01.yaml post /orders/sessions/authorize
Use this API when an order has already been created and you want Cashfree to process the payment for authorisation only. To use this API, the 'AUTHORIZE_ONLY' flag must be enabled for your account. Submit [Support Form](https://merchant.cashfree.com/auth/login) to enable this feature.



# Preauthorisation
Source: https://www.cashfree.com/docs/api-reference/payments/latest/payments/preauthorisation

openapi/payments/v2026-01-01.yaml post /orders/{order_id}/authorization
Use this API to capture or void a [pre-authorised](/docs/payments/features/pre-authorisation) payment.



# Submit or Resend OTP
Source: https://www.cashfree.com/docs/api-reference/payments/latest/payments/submit-or-resend-otp

openapi/payments/v2026-01-01.yaml post /orders/pay/authenticate/{cf_payment_id}
Use this API to submit or resend OTP if you use [Native OTP](https://www.cashfree.com/docs/payments/features/native-otp) for authentication of card payments.

Refer to the sample responses below:

<AccordionGroup>
  <Accordion title="Submit_OTP">
    Submit OTP Success and Transaction Successful – 200 OK

    ```json theme={"dark"}
    {
      "action": "SUBMIT_OTP",
      "authenticate_status": "SUCCESS",
      "cf_payment_id": "3991872901",
      "payment_message": "payment successful"
    }
    ```

    Submit OTP Success but Invalid OTP – 200 OK

    ```json theme={"dark"}
    {
      "action": "SUBMIT_OTP",
      "authenticate_status": "FAILED",
      "cf_payment_id": "5114916442998",
      "payment_message": "otp is invalid"
    }
    ```

    Max OTP Submit Limit Exceeded – 400 Bad Request

    ```json theme={"dark"}
    {
      "message": "Exceeded retry attempts. Check latest errors and resolution from Merchant Dashboard API logs: https://bit.ly/4glEd0W Help Document: https://bit.ly/4eeZYO9",
      "code": "request_invalid",
      "type": "invalid_request_error"
    }
    ```

    Transaction Already Completed – 400 Bad Request

    ```json theme={"dark"}
    {
      "message": "Transaction is already processed. Check latest errors and resolution from Merchant Dashboard API logs: https://bit.ly/4glEd0W Help Document: https://bit.ly/4eeZYO9",
      "code": "request_invalid",
      "type": "invalid_request_error"
    }
    ```

    Invalid Request – 404 Not Found

    ```json theme={"dark"}
    {
      "message": "transaction not found. Check latest errors and resolution from Merchant Dashboard API logs: https://bit.ly/4glEd0W Help Document: https://bit.ly/4eeZYO9",
      "code": "payment_not_found",
      "type": "invalid_request_error"
    }
    ```

    Submit OTP Success but Transaction Failed – 502 Bad Gateway

    ```json theme={"dark"}
    {
      "message": "transaction failed",
      "code": "bank_processing_failure",
      "type": "api_error"
    }
    ```

    Submit OTP Success but Transaction Pending – 502 Bad Gateway

    ```json theme={"dark"}
    {
      "message": "transaction incomplete",
      "code": "bank_processing_failure",
      "type": "api_error"
    }
    ```
  </Accordion>

  <Accordion title="Resend_OTP">
    Resend OTP Success – 200 OK

    ```json theme={"dark"}
    {
      "action": "RESEND_OTP",
      "authenticate_status": "SUCCESS",
      "cf_payment_id": "5114916574918",
      "payment_message": "otp sent successfully"
    }
    ```
  </Accordion>
</AccordionGroup>

## Error codes

The following table lists the error codes you may encounter when submitting an OTP:

<Accordion title="Error codes">
  | Code | Description | Type | Status |
  | :- | :- | :- | :- |
  | `action_missing` | The `action` field is required but was not included in the request. | `invalid_request_error` | 400 |
  | `cf_payment_id_missing` | The `cf_payment_id` field is required but was not included in the request. | `invalid_request_error` | 400 |
</Accordion>


# Payment Webhooks
Source: https://www.cashfree.com/docs/api-reference/payments/latest/payments/webhooks

Subscribe to Cashfree webhooks to receive asynchronous events for payment success, failure, refunds, and dispute updates on each order attempt.

Webhooks are server callbacks from Cashfree to your server. Cashfree sends webhooks for the following events for a `payment`:

* Payment success webhook
* Payment failed webhook
* Payment user dropped webhook
* Payment charges webhook

## Webhook signature

The merchant will receive the Webhook signature in the Webhook Header part. Below is a sample header that merchants can expect in the Webhook request. For best practices on securing your webhook endpoints, refer to the [Webhook Security Checklist](/docs/payments/online/webhooks/security-checklist).

<Tabs>
  <Tab title="Version (2026-01-01)">
    | Header name | Header value |
    | - | :-: |
    | content-length | 1681 |
    | x-webhook-attempt | 1 |
    | content-type | application/json |
    | x-webhook-signature | BUl8l3gElw9rlWUg0u3diRQMDzp1RysuTvxca2J5qOk= |
    | x-idempotency-key | A5UkesCnpkM4gGG+RpMLQ9coTGyN56UWXPoQjfYeuII= |
    | x-webhook-timestamp | 1785401067911 |
    | x-webhook-version | 2026-01-01 |
  </Tab>

  <Tab title="Version (2025-01-01)">
    | Header name | Header value |
    | - | :-: |
    | content-length | 1099 |
    | x-webhook-attempt | 1 |
    | content-type | application/json |
    | x-webhook-signature | 07r5C3VMwsGYeldGOCYxe5zoHhIN1zLfa8O0U/yngHI= |
    | x-idempotency-key | n9rn7079wqXcse3GEDEXCYle9ajXmU0SUQY8zrUNAlc= |
    | x-webhook-timestamp | 1746427759733 |
    | x-webhook-version | 2025-01-01 |
  </Tab>

  <Tab title="Version (2023-08-01)">
    | Header name | Header value |
    | - | :-: |
    | content-length | 1002 |
    | x-webhook-attempt | 1 |
    | content-type | application/json |
    | x-webhook-signature | 0s9zgYXyUYrQaadF5oTYzpxzHmPBMmGDSjbAKZTleL4= |
    | x-webhook-timestamp | 1746426425612 |
    | x-webhook-version | 2023-08-01 |
  </Tab>
</Tabs>

<Tip> Ensure that the webhook payload is received in raw text format. Converting the webhook into a JSON object can lead to automatic transformation of decimal values—such as the payment\_amount—into integers. This alteration (e.g., payment\_amount: 170 instead of payment\_amount: 170.00) can cause a webhook signature mismatch.<br /><br />**Correct format: payment\_amount: 170.00** ✅ <br />**Incorrect format: payment\_amount: 170** ❌</Tip>

## Payment success webhook

A payment success webhook triggers when a payment completes successfully. Use this webhook to:

* Update the order status
* Trigger fulfilment
* Send a confirmation to the customer

<Note>
  If you have migrated from Autocollect to PG VBA, use the [2022 version VBA payment webhooks](/docs/payments/vba/webhooks) to receive payment updates for VBA transactions.
</Note>

<Tabs>
  <Tab title="Version (2026-01-01)">
    ```javascript Version (2026-01-01) theme={"dark"}
    {
    "data": {
    "order": {
      "order_id": "order_1112353JRZPMsx42lOnAuXiz0vddwovDk",
      "order_amount": 1,
      "order_currency": "INR",
      "order_tags": {
        "GST": "364JPAYTM0312",
        "Merchant_ID": "123456",
        "Merchant_Note": "99month Incl GST for 12 MonthsJPAYTMTJMMO_0003"
      },
      "order_note": "testing Terminate Order Flow"
    },
    "payment": {
      "cf_payment_id": "1453995084705707520",
      "payment_status": "SUCCESS",
      "payment_amount": 1,
      "payment_currency": "INR",
      "payment_message": "Simulated response message",
      "payment_time": "2026-09-17T11:47:22+05:30",
      "bank_reference": "1453995084705707520",
      "auth_id": null,
      "payment_method": {
        "netbanking": {
          "channel": null,
          "netbanking_bank_code": "3032",
          "netbanking_bank_name": "Kotak Mahindra Bank"
        }
      },
      "payment_group": "net_banking",
      "international_payment": null,
      "payment_surcharge": {
        "payment_surcharge_service_charge": 0,
        "payment_surcharge_service_tax": 0
      }
    },
    "customer_details": {
      "customer_name": "ABC co",
      "customer_id": "Customer_123",
      "customer_email": null,
      "customer_phone": "8971520300"
    },
    "payment_gateway_details": {
      "gateway_name": "CASHFREE",
      "gateway_order_id": "1453994974886245888",
      "gateway_payment_id": "1453995084705707520",
      "gateway_status_code": null,
      "gateway_order_reference_id": null,
      "gateway_settlement": "CASHFREE",
      "gateway_reference_name": null
    },
    "payment_offers": null,
    "terminal_details": null
    },
    "event_time": "2026-09-17T11:47:29+05:30",
    "type": "PAYMENT_SUCCESS_WEBHOOK"
    }
    ```
  </Tab>

  <Tab title="Version (2025-01-01)">
    ```javascript Version (2025-01-01) theme={"dark"}
    {
    "data":{
      "order":{
         "order_id":"order_OFR_2",
         "order_amount":2,
         "order_currency":"INR",
         "order_tags":null
      },
      "payment":{
         "cf_payment_id":"1453002795",
         "payment_status":"SUCCESS",
         "payment_amount":1,
         "payment_currency":"INR",
         "payment_message":"00::Transaction success",
         "payment_time":"2025-01-15T12:20:29+05:30",
         "bank_reference":"234928698581",
         "auth_id":null,
         "payment_method":{
            "upi":{
               "channel":"collect",
               "upi_id":"rishab@ybl",
               "upi_instrument":"UPI_CREDIT_CARD",
               "upi_instrument_number":"masked card number",
               "upi_payer_ifsc":"SBI0025434",
               "upi_payer_account_number":"XXXXX0231"
            }
         },
         "payment_group":"upi",
         "international_payment":{
            "international":false
         },
         "payment_surcharge":{
            "payment_surcharge_service_charge":0.36,
            "payment_surcharge_service_tax":0.06
         }
      },
      "customer_details":{
         "customer_name":null,
         "customer_id":"7112AAA812234",
         "customer_email":"test@gmail.com",
         "customer_phone":"9908734801"
      },
      "payment_gateway_details":{
         "gateway_name":"CASHFREE",
         "gateway_order_id":"1634766330",
         "gateway_payment_id":"1504280029",
         "gateway_order_reference_id":"abc_124",
         "gateway_settlement":"CASHFREE",
         "gateway_status_code":null
      },
      "payment_offers":[
         {
            "offer_id":"0f05e1d0-fbf8-4c9c-a1f0-814c7b2abdba",
            "offer_type":"DISCOUNT",
            "offer_meta":{
               "offer_title":"50% off on UPI",
               "offer_description":"50% off for testing",
               "offer_code":"UPI50",
               "offer_start_time":"2022-11-09T06:23:25.972Z",
               "offer_end_time":"2025-02-27T18:30:00Z"
            },
            "offer_redemption":{
               "redemption_status":"SUCCESS",
               "discount_amount":1,
               "cashback_amount":0
            }
         }
      ],
      "terminal_details":{
        "cf_terminal_id":17269,
        "terminal_phone":"8971520311"
      }
    },
    "event_time":"2025-01-15T11:16:10+05:30",
    "type":"PAYMENT_SUCCESS_WEBHOOK"
    }
    ```
  </Tab>

  <Tab title="Version (2023-08-01)">
    ```javascript Version (2023-08-01) theme={"dark"}
    {
    "data":{
      "order":{
         "order_id":"order_OFR_2",
         "order_amount":2,
         "order_currency":"INR",
         "order_tags":null
      },
      "payment":{
         "cf_payment_id":"1453002795",
         "payment_status":"SUCCESS",
         "payment_amount":1,
         "payment_currency":"INR",
         "payment_message":"00::Transaction success",
         "payment_time":"2022-12-15T12:20:29+05:30",
         "bank_reference":"234928698581",
         "auth_id":null,
         "payment_method":{
            "upi":{
               "channel":"collect",
               "upi_id":"suhasg6@ybl",
            }
         },
         "payment_group":"upi"
      },
      "customer_details":{
         "customer_name":null,
         "customer_id":"7112AAA812234",
         "customer_email":"test@gmail.com",
         "customer_phone":"9908734801"
      },
      "payment_gateway_details":{
         "gateway_name":"CASHFREE",
         "gateway_order_id":"1634766330",
         "gateway_payment_id":"1504280029",
         "gateway_order_reference_id":"abc_124",
         "gateway_settlement":"CASHFREE",
         "gateway_status_code":null
      },
      "payment_offers":[
         {
            "offer_id":"0f05e1d0-fbf8-4c9c-a1f0-814c7b2abdba",
            "offer_type":"DISCOUNT",
            "offer_meta":{
               "offer_title":"50% off on UPI",
               "offer_description":"50% off for testing",
               "offer_code":"UPI50",
               "offer_start_time":"2022-11-09T06:23:25.972Z",
               "offer_end_time":"2023-02-27T18:30:00Z"
            },
            "offer_redemption":{
               "redemption_status":"SUCCESS",
               "discount_amount":1,
               "cashback_amount":0
            }
         }
      ]
    },
    "event_time":"2023-08-01T11:16:10+05:30",
    "type":"PAYMENT_SUCCESS_WEBHOOK"
    }
    ```
  </Tab>
</Tabs>

## Payment failed webhook

The payment failed webhook notifies you when a payment attempt fails, and we receive a failed response from the bank. Use case: Update order status, notify customer, initiate retry flow

<Tabs>
  <Tab title="Version 2026-01-01">
    ```javascript Version 2026-01-01 theme={"dark"}
    {  
    "data": {  
        "order": {  
            "order_id": "CFPay_g47u3888d0k0_tblfm766qc",  
            "order_amount": 1.8,  
            "order_currency": "INR",  
            "order_tags": {  
                "cf_link_id": "13746255",
                "link_id": "7f0efd36-23f3-4213-95dc-3c32ba1a27e2"
            },
            "order_note": "Sample Order Note"
        },  
        "payment": {  
            "cf_payment_id": "1504280029",  
            "payment_status": "FAILED",  
            "payment_amount": 1.8,  
            "payment_currency": "INR",  
            "payment_message": "AMOUNT SHOULD BE WITHIN RANGE BETWEEN 20.00 TO 500000.00.",  
            "payment_time": "2023-01-06T20:00:11+05:30",  
            "bank_reference": "NA",  
            "auth_id": "null",  
            "payment_method": {  
                "netbanking": {  
                    "channel": null,  
                    "netbanking_bank_code": "3054",  
                    "netbanking_bank_name": "UCO Bank"  
                }  
            },  
            "payment_group": "net_banking",
            "international_payment":{
                "international":false
            },
            "payment_surcharge":{
                "payment_surcharge_service_charge":0,
                "payment_surcharge_service_tax":0
            }
        },  
        "customer_details": {  
            "customer_name": null,  
            "customer_id": null,  
            "customer_email": "test@gmail.com",  
            "customer_phone": "9611199227"  
        },  
        "error_details": {  
            "error_code": "GATEWAY_ERROR",  
            "error_description": "AMOUNT SHOULD BE WITHIN RANGE BETWEEN 20.00 TO 500000.00. for this bank",  
            "error_reason": "invalid_amount",  
            "error_source": "cashfree",
            "error_code_raw": null,
            "error_description_raw": null,
            "error_subcode_raw": "U09"
        },  
        "payment_gateway_details": {
            "gateway_name": "CASHFREE",
            "gateway_order_id": "1634766330",
            "gateway_payment_id": "1504280029",
            "gateway_settlement": "CASHFREE",
            "gateway_order_reference_id": null,
            "gateway_reference_name": null,
            "gateway_status_code": null
        }, 
        "payment_offers": null,
        "terminal_details":{
            "cf_terminal_id":17269,
            "terminal_phone":"8971520311"
        }
    },  
    "event_time": "2023-08-01T20:00:12+05:30",  
    "type": "PAYMENT_FAILED_WEBHOOK"  
    }
    ```
  </Tab>

  <Tab title="Version 2025-01-01">
    ```javascript Version 2025-01-01 theme={"dark"}
    {  
    "data": {  
        "order": {  
            "order_id": "CFPay_g47u3888d0k0_tblfm766qc",  
            "order_amount": 1.8,  
            "order_currency": "INR",  
            "order_tags": {  
                "cf_link_id": "13746255",
                "link_id": "7f0efd36-23f3-4213-95dc-3c32ba1a27e2"
            }  
        },  
        "payment": {  
            "cf_payment_id": "1504280029",  
            "payment_status": "FAILED",  
            "payment_amount": 1.8,  
            "payment_currency": "INR",  
            "payment_message": "AMOUNT SHOULD BE WITHIN RANGE BETWEEN 20.00 TO 500000.00.",  
            "payment_time": "2023-01-06T20:00:11+05:30",  
            "bank_reference": "NA",  
            "auth_id": "null",  
            "payment_method": {  
                "netbanking": {  
                    "channel": null,  
                    "netbanking_bank_code": "3054",  
                    "netbanking_bank_name": "UCO Bank"  
                }  
            },  
            "payment_group": "net_banking",
            "international_payment":{
                "international":false
            },
            "payment_surcharge":{
                "payment_surcharge_service_charge":0,
                "payment_surcharge_service_tax":0
            }
        },  
        "customer_details": {  
            "customer_name": null,  
            "customer_id": null,  
            "customer_email": "test@gmail.com",  
            "customer_phone": "9611199227"  
        },  
        "error_details": {  
            "error_code": "GATEWAY_ERROR",  
            "error_description": "AMOUNT SHOULD BE WITHIN RANGE BETWEEN 20.00 TO 500000.00. for this bank",  
            "error_reason": "invalid_amount",  
            "error_source": "cashfree",
            "error_code_raw": null,
            "error_description_raw": null,
            "error_subcode_raw": "U09"
        },  
        "payment_gateway_details": {
            "gateway_name": "CASHFREE",
            "gateway_order_id": "1634766330",
            "gateway_payment_id": "1504280029",
            "gateway_settlement": "CASHFREE",
            "gateway_order_reference_id": null,
            "gateway_reference_name": null,
            "gateway_status_code": null
        }, 
        "payment_offers": null,
        "terminal_details":{
            "cf_terminal_id":17269,
            "terminal_phone":"8971520311"
        }
    },  
    "event_time": "2023-08-01T20:00:12+05:30",  
    "type": "PAYMENT_FAILED_WEBHOOK"  
    }
    ```
  </Tab>

  <Tab title="Version 2023-08-01">
    ```javascript Version 2023-08-01 theme={"dark"}
    {
    "data": {
        "order": {
            "order_id": "CFPay_g47u3888d0k0_tblfm766qc",
            "order_amount": 1.8,
            "order_currency": "INR",
            "order_tags": {
                "cf_link_id": "13746255"
            }
        },
        "payment": {
            "cf_payment_id": "1504280029",
            "payment_status": "FAILED",
            "payment_amount": 1.8,
            "payment_currency": "INR",
            "payment_message": "AMOUNT SHOULD BE WITHIN RANGE BETWEEN 20.00 TO 500000.00.",
            "payment_time": "2023-01-06T20:00:11+05:30",
            "bank_reference": "NA",
            "auth_id": "null",
            "payment_method": {
                "netbanking": {
                    "channel": null,
                    "netbanking_bank_code": "3054",
                    "netbanking_bank_name": "UCO Bank"
                }
            },
            "payment_group": "net_banking"
        },
        "customer_details": {
            "customer_name": null,
            "customer_id": null,
            "customer_email": "test@gmail.com",
            "customer_phone": "9611199227"
        },
        "error_details": {
            "error_code": "GATEWAY_ERROR",
            "error_description": "AMOUNT SHOULD BE WITHIN RANGE BETWEEN 20.00 TO 500000.00. for this bank",
            "error_reason": "invalid_amount",
            "error_source": "cashfree",
            "error_subcode_raw": "U09"
        },
        "payment_gateway_details": {
            "gateway_name": "CASHFREE",
            "gateway_order_id": "1634766330",
            "gateway_payment_id": "1504280029",
            "gateway_settlement": "CASHFREE",
            "gateway_status_code": null
        },
        "payment_offers": null
    },
    "event_time": "2023-08-01T20:00:12+05:30",
    "type": "PAYMENT_FAILED_WEBHOOK"
    }
    ```
  </Tab>
</Tabs>

## Payment user dropped webhook

The User Dropped Webhook notifies you when your customer abandons the payment flow. It will help you understand if customers attempted to pay or not. Some common scenarios where the transaction will be marked as USER\_DROPPED are:

* User was redirected to the bank's OTP page, but never entered the OTP.
* User was redirected to open the UPI app, but never entered the UPI PIN.
* User was shown the 3ds OTP modal, but did not enter the OTP.

<Tabs>
  <Tab title="Version 2026-01-01">
    ```javascript Version 2026-01-01 theme={"dark"}
    {
    "data": {
    "order": {
      "order_id": "order_02",
      "order_amount": 2,
      "order_currency": "INR",
      "order_tags": null,
      "order_note": "Sample Order Note"
    },
    "payment": {
      "cf_payment_id": "975672265",
      "payment_status": "USER_DROPPED",
      "payment_amount": 2,
      "payment_currency": "INR",
      "payment_message": "User dropped and did not complete the two factor authentication",
      "payment_time": "2022-05-25T14:25:34+05:30",
      "bank_reference": "1803592531",
      "auth_id": "2980",
      "payment_method": {
        "netbanking": {
          "channel": null,
          "netbanking_bank_code": "3044",
          "netbanking_bank_name": "State Bank Of India"
        }
      },
      "payment_group": "net_banking",
      "international_payment":{
        "international":false
      },
      "payment_surcharge":{
        "payment_surcharge_service_charge":0,
        "payment_surcharge_service_tax":0
      }
    },
    "customer_details": {
      "customer_name": null,
      "customer_id": "7112AAA812234",
      "customer_email": "test@gmail.com",
      "customer_phone": "9611199227"
    },
    "terminal_details":{
      "cf_terminal_id":17269,
      "terminal_phone":"8971520311"
    }
    },
    "event_time": "2022-05-25T14:35:38+05:30",
    "type": "PAYMENT_USER_DROPPED_WEBHOOK"
    }
    ```
  </Tab>

  <Tab title="Version 2025-01-01">
    ```javascript Version 2025-01-01 theme={"dark"}
    {
    "data": {
    "order": {
      "order_id": "order_02",
      "order_amount": 2,
      "order_currency": "INR",
      "order_tags": null
    },
    "payment": {
      "cf_payment_id": "975672265",
      "payment_status": "USER_DROPPED",
      "payment_amount": 2,
      "payment_currency": "INR",
      "payment_message": "User dropped and did not complete the two factor authentication",
      "payment_time": "2022-05-25T14:25:34+05:30",
      "bank_reference": "1803592531",
      "auth_id": "2980",
      "payment_method": {
        "netbanking": {
          "channel": null,
          "netbanking_bank_code": "3044",
          "netbanking_bank_name": "State Bank Of India"
        }
      },
      "payment_group": "net_banking",
      "international_payment":{
        "international":false
      },
      "payment_surcharge":{
        "payment_surcharge_service_charge":0,
        "payment_surcharge_service_tax":0
      }
    },
    "customer_details": {
      "customer_name": null,
      "customer_id": "7112AAA812234",
      "customer_email": "test@gmail.com",
      "customer_phone": "9611199227"
    },
    "terminal_details":{
      "cf_terminal_id":17269,
      "terminal_phone":"8971520311"
    }
    },
    "event_time": "2022-05-25T14:35:38+05:30",
    "type": "PAYMENT_USER_DROPPED_WEBHOOK"
    }
    ```
  </Tab>

  <Tab title="Version 2023-08-01">
    ```javascript Version 2023-08-01 theme={"dark"}
    {
    "data": {
    "order": {
      "order_id": "order_02",
      "order_amount": 2,
      "order_currency": "INR",
      "order_tags": null
    },
    "payment": {
      "cf_payment_id": "975672265",
      "payment_status": "USER_DROPPED",
      "payment_amount": 2,
      "payment_currency": "INR",
      "payment_message": "User dropped and did not complete the two factor authentication",
      "payment_time": "2022-05-25T14:25:34+05:30",
      "bank_reference": "1803592531",
      "auth_id": "2980",
      "payment_method": {
        "netbanking": {
          "channel": null,
          "netbanking_bank_code": "3044",
          "netbanking_bank_name": "State Bank Of India"
        }
      },
      "payment_group": "net_banking"
    },
    "customer_details": {
      "customer_name": null,
      "customer_id": "7112AAA812234",
      "customer_email": "test@gmail.com",
      "customer_phone": "9611199227"
    }
    },
    "event_time": "2022-05-25T14:35:38+05:30",
    "type": "PAYMENT_USER_DROPPED_WEBHOOK"
    }
    ```
  </Tab>
</Tabs>

## Payment charges webhook

A payment charges webhook is triggered after a successful payment when Cashfree finalises the Transaction Discount Rate (TDR) and related charges for that payment. The event time can be later than the payment time. Use this webhook to reconcile per-payment charges and the net settlement amount.

To receive this event, subscribe to **Success Payment TDR** when you [configure webhooks](/docs/payments/online/webhooks/configure) in the Merchant Dashboard. The webhook `type` in the payload is `PAYMENT_CHARGES_WEBHOOK`.

<Note>
  The `payment_method` object in this webhook can be empty (`{}`). This is expected for the payment charges event.
</Note>

For background on TDR, see [What is TDR?](/docs/help/account/pricing#what-is-tdr).

### `charges_details` fields

| Field | Description | Example |
| - | - | - |
| `service_charge` | Service charge (TDR) applicable for the payment. | `0.12` |
| `service_tax` | Service tax applicable on the service charge. | `0.02` |
| `settlement_amount` | Net amount for the payment after deducting the service charge and service tax. | `5.86` |
| `settlement_currency` | Currency of the settlement amount. | `INR` |
| `service_charge_discount` | Discount applied on the service charge, if any. Returns `null` when no discount applies. | `null` |

<Tabs>
  <Tab title="Version 2026-01-01">
    ```javascript Version 2026-01-01 theme={"dark"}
    {
    "data": {
    "order": {
      "order_id": "14508_73_1783668483731",
      "order_amount": 6.00,
      "order_currency": "INR",
      "order_tags": null
    },
    "payment": {
      "cf_payment_id": 5979305158,
      "payment_status": "SUCCESS",
      "payment_amount": 6.00,
      "payment_currency": "INR",
      "payment_message": "SUCCESS",
      "payment_time": "2026-07-10T12:58:04+05:30",
      "bank_reference": "841754751916",
      "auth_id": null,
      "payment_method": {},
      "payment_group": "sbc_upi"
    },
    "customer_details": {
      "customer_name": null,
      "customer_id": null,
      "customer_email": "rfeef@gmail.com",
      "customer_phone": "9876543211"
    },
    "charges_details": {
      "service_charge": 0.12,
      "service_tax": 0.02,
      "settlement_amount": 5.86,
      "settlement_currency": "INR",
      "service_charge_discount": null
    }
    },
    "event_time": "2026-07-15T08:00:05+05:30",
    "type": "PAYMENT_CHARGES_WEBHOOK"
    }
    ```
  </Tab>

  <Tab title="Version 2025-01-01">
    ```javascript Version 2025-01-01 theme={"dark"}
    {
    "data": {
    "order": {
      "order_id": "14508_73_1783668483731",
      "order_amount": 6.00,
      "order_currency": "INR",
      "order_tags": null
    },
    "payment": {
      "cf_payment_id": 5979305158,
      "payment_status": "SUCCESS",
      "payment_amount": 6.00,
      "payment_currency": "INR",
      "payment_message": "SUCCESS",
      "payment_time": "2026-07-10T12:58:04+05:30",
      "bank_reference": "841754751916",
      "auth_id": null,
      "payment_method": {},
      "payment_group": "sbc_upi"
    },
    "customer_details": {
      "customer_name": null,
      "customer_id": null,
      "customer_email": "rfeef@gmail.com",
      "customer_phone": "9876543211"
    },
    "charges_details": {
      "service_charge": 0.12,
      "service_tax": 0.02,
      "settlement_amount": 5.86,
      "settlement_currency": "INR",
      "service_charge_discount": null
    }
    },
    "event_time": "2026-07-15T08:00:05+05:30",
    "type": "PAYMENT_CHARGES_WEBHOOK"
    }
    ```
  </Tab>

  <Tab title="Version 2023-08-01">
    ```javascript Version 2023-08-01 theme={"dark"}
    {
    "data": {
    "order": {
      "order_id": "14508_73_1783668483731",
      "order_amount": 6.00,
      "order_currency": "INR",
      "order_tags": null
    },
    "payment": {
      "cf_payment_id": 5979305158,
      "payment_status": "SUCCESS",
      "payment_amount": 6.00,
      "payment_currency": "INR",
      "payment_message": "SUCCESS",
      "payment_time": "2026-07-10T12:58:04+05:30",
      "bank_reference": "841754751916",
      "auth_id": null,
      "payment_method": {},
      "payment_group": "sbc_upi"
    },
    "customer_details": {
      "customer_name": null,
      "customer_id": null,
      "customer_email": "rfeef@gmail.com",
      "customer_phone": "9876543211"
    },
    "charges_details": {
      "service_charge": 0.12,
      "service_tax": 0.02,
      "settlement_amount": 5.86,
      "settlement_currency": "INR",
      "service_charge_discount": null
    }
    },
    "event_time": "2026-07-15T08:00:05+05:30",
    "type": "PAYMENT_CHARGES_WEBHOOK"
    }
    ```
  </Tab>
</Tabs>

## Sample payload by payment method

The instrument used for making a payment will vary by the payment methods used by the customer. Details of the payload by payment method are documented for reference.

<Tabs>
  <Tab title="Card">
    ```javascript theme={"dark"}
    {
      ...,
      "payment_method": {  
        "card": {  
          "channel": "link",  
          "card_number": "XXXXXXXXXXXX4738",  
          "card_network": "visa",  
          "card_type": "credit_card",  
          "card_sub_type": "R",  
          "card_country": "IN",  
          "card_bank_name": "HDFC Bank",
          "card_network_reference_id": "100212023061200000001014824849",
          "instrument_id":"8e9cc167-4fe2-4ece-be8d-c1b224e50a23",
          "par": "V0010014623022637739353641436"
        }  
      },  
      "payment_group": "credit_card",
      ...
    }

    ```
  </Tab>

  <Tab title="Net Banking">
    ```javascript theme={"dark"}
    {
      ...,
      "payment_method": {  
        "netbanking": {  
          "channel":null,  
          "netbanking_bank_code":"3022",  
          "netbanking_bank_name":"ICICI Bank"  
        }  
      },  
      "payment_group":"net_banking",
      ...
    }

    ```
  </Tab>

  <Tab title="UPI">
    ```javascript theme={"dark"}
    {
      ...,
      "payment_method": {  
        "upi": {
                "channel": "collect",
                "upi_id": "rishabtated@ybl",
                "upi_instrument" : "UPI_CREDIT_CARD", 
                "upi_instrument_number" : "masked card number", 
                "upi_payer_ifsc" : "SBI0025434",
                "upi_payer_account_number" : "XXXXX0231"
            }  
      },
      "payment_group":"upi",
      ...
    }

    ```
  </Tab>

  <Tab title="Wallet">
    ```javascript theme={"dark"}
    {
      ...,
      "payment_method": {  
        "app": {  
          "channel":"AmazonPay",  
          "upi_id":null,
          "provider": "AmazonPay"
        }  
      },  
      "payment_group":"wallet",
      ...
    }

    ```
  </Tab>

  <Tab title="Credit Card EMI">
    ```javascript theme={"dark"}
    {
      ...,
      "payment_method":{  
        "card":{  
          "channel":null,  
          "card_number":"XXXXXXXXXX8952",  
          "card_network":null,  
          "card_type":"credit_card_emi",  
          "card_country":null,  
          "card_bank_name":"HDFC BANK",  
          "emi_details":{  
            "emi_amount":1167,  
            "emi_tenure":3,  
            "emi_interest":16.00  
          },
          "card_network_reference_id":null
        }  
      },  
      "payment_group":"credit_card_emi",
      ...
    }

    ```
  </Tab>

  <Tab title="Debit Card EMI">
    ```javascript theme={"dark"}
    {
      ...,
      "payment_method":{  
        "card":{  
          "channel":null,  
          "card_number":"XXXXXXXXXX8952",  
          "card_network":null,  
          "card_type":"debit_card_emi",  
          "card_country":null,  
          "card_bank_name":"HDFC BANK",  
          "emi_details":{  
            "emi_amount":1167,  
            "emi_tenure":3,  
            "emi_interest":16.00  
          }  
        }  
      },  
      "payment_group":"debit_card_emi",
      ...
    }

    ```
  </Tab>

  <Tab title="Cardless EMI">
    ```javascript theme={"dark"}
    {
      ...,
      "payment_method":{  
        "cardless_emi":{  
          "channel":null,  
          "provider":"flexmoney",  
          "phone":"9731117102",  
          "emi_details":null  
        }  
      },  
      "payment_group":"cardless_emi",
      ...
    }

    ```
  </Tab>

  <Tab title="Pay Later">
    ```javascript theme={"dark"}
    {
      ...,
      "payment_method":{  
        "pay_later":{  
            "channel":null,
            "provider":"olapostpaid",
            "phone":"9731117102"
        }  
      },  
      "payment_group":"pay_later",
      ...
    }

    ```
  </Tab>

  <Tab title="VBA Transfer">
    ```javascript theme={"dark"}
    {
      ...,
     "payment_method":{
         "vba_transfer":{
             "utr":"MerchantID_utr",
             "credit_ref_no":"NA",
             "remitter_account":"808081pxqp242614HW",
             "remitter_name":"Test",
             "remitter_ifsc":"IFSC",
             "email":"rishabtated@gmail.com",
             "phone":"9999999999",
             "vaccount_id":"123499",
             "vaccount_number":"94260000123400"
         }
     },
     "payment_group":"vba_transfer",
      ...
    }

    ```
  </Tab>

  <Tab title="Bank Transfer">
    ```javascript theme={"dark"}
    {
      ...,
     "payment_method":{
         "bank_transfer":{
             "transfer_type":"NEFT",
             "bank":"UNION BANK OF INDIA"
         }
     },
     "payment_group":"bank_transfer",
      ...
    }

    ```
  </Tab>
</Tabs>

## Webhook FAQs

<div>
  <a href="/docs/payments/online/webhooks/configure">
    Configure webhooks
  </a>
</div>

<AccordionGroup>
  <Accordion title="How do I add or configure webhook URLs for different event types (e.g., success, failed)?">
    You can configure webhook URLs for each notification type in your merchant dashboard. To receive notifications, subscribe to specific events, such as PAYMENT\_SUCCESS or PAYMENT\_FAILED. For step-by-step instructions, go through the [official documentation](/docs/payments/online/webhooks/overview).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Why am I not receiving failed webhooks?">
    This may occur if the PAYMENT\_FAILED webhook event is not subscribed. To resolve this, open your dashboard, navigate to the webhook configuration, and ensure that the `PAYMENT_FAILED` event is selected.

    <Note>
      This applies to all webhook events. Make sure relevant events are enabled as needed.
    </Note>

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="I’m getting an error while adding the webhook endpoint. What could be wrong?">
    Ensure that your endpoint is reachable and returns a 2xx status code. Also, verify that it is properly configured to accept webhook requests.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Why is my webhook not received?">
    There could be multiple reasons:

    * The webhook URL was not included in the notify\_url parameter during order creation.
    * Make sure you have done the webhook configuration for the notification type as needed.
    * The endpoint URL is returning a 4xx or 5xx error.

    Actions to take:

    * Verify that your webhook is correctly configured. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and go to **Payment Gateway > Developers > Webhook Configuration**.
    * Ensure that the endpoint is accessible and able to accept requests from Cashfree.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How do I enable or disable specific webhook types?">
    You can enable or disable specific webhook types directly from the [Merchant Dashboard](https://merchant.cashfree.com/auth/login). For detailed instructions, refer to the
    **Payment Gateway > Developers > Webhook Configuration** section.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How to enable the latest webhook version (e.g., 2026-01-01)?">
    Once the feature is rolled out in Production, the new version will appear in the version drop-down under Webhook Configuration.

    <Warning>
      If you do not see the new version, the rollout may still be in progress. Please check back later or contact support for assistance.
    </Warning>

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Webhook is configured, but no real-time data is received. Why?">
    This may happen if the webhook URL is configured, but no events are selected. Ensure:

    * Webhook types are enabled.
    * Your endpoint is healthy and accessible to accept the requests from Cashfree.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Why did the webhook trigger multiple times?">
    Duplicate webhook triggers may occur due to misconfiguration or retry logic. This can happen if multiple webhook versions are configured using the same or different endpoint URLs.

    ✅ Actions to take:

    * The Merchant can revisit and delete the duplicate configured endpoint URL. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and go to **Payment Gateway > Developers > Webhook Configuration**.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What if I don't pass a notify_url and only use return URLs?">
    Notify URLs are necessary for webhook delivery. Return URLs only redirect the user after the transaction. Ensure you pass both as different URLs, especially if you need server-side notifications.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How can I improve webhook issue handling and reduce to raise of support tickets?">
    * Always subscribe to the necessary webhook event types (`SUCCESS`, `FAILED`, `USER_DROPPED`, and **Success Payment TDR** for payment charges).
    * Test your webhook integration in Sandbox before going live.
    * Use publicly accessible HTTPS URLs that return 200 OK responses.
    * Regularly review and update webhook configurations in the merchant dashboard to avoid outdated or incorrect entries.

    <iframe title="FAQs feedback component" />
  </Accordion>
</AccordionGroup>


# PG Reconciliation
Source: https://www.cashfree.com/docs/api-reference/payments/latest/pg-reconciliation/pg-reconciliation

openapi/payments/v2026-01-01.yaml post /recon
- Use this API to get the payment gateway reconciliation details with date range.
- It will have events for your payment account




# Create VBA
Source: https://www.cashfree.com/docs/api-reference/payments/latest/pgvba/create-vba

openapi/pgvba/pgvba.yaml post /pg/vba
Use this API to create a virtual bank account. It allows you to receive payments just like a regular bank account.



# Create VBA Notification Group
Source: https://www.cashfree.com/docs/api-reference/payments/latest/pgvba/create-vba-notification-group

openapi/pgvba/pgvba.yaml post /pg/vba/notificationgroup
Use this API to create a notification group. The recipients in the group will receive notifications regarding the payment details.



# Edit VBA
Source: https://www.cashfree.com/docs/api-reference/payments/latest/pgvba/edit-vba

openapi/pgvba/pgvba.yaml put /pg/vba/{virtual_account_id}
Use this API to edit the details of the created virtual bank account.



# Edit VBA Notification Group
Source: https://www.cashfree.com/docs/api-reference/payments/latest/pgvba/edit-vba-notification-group

openapi/pgvba/pgvba.yaml put /pg/vba/notificationgroup/{notification_group_name}
Use this API to edit the details of the created notification group.



# Get VBA
Source: https://www.cashfree.com/docs/api-reference/payments/latest/pgvba/get-vba

openapi/pgvba/pgvba.yaml get /pg/vba/{virtual_account_id}
Use this API to get the details of the created virtual bank account by entering the virtual account ID.



# Get VBA Notification Group
Source: https://www.cashfree.com/docs/api-reference/payments/latest/pgvba/get-vba-notification-group

openapi/pgvba/pgvba.yaml get /pg/vba/notificationgroup/{notification_group_name}
Use this API to get the details of the created notification group.



# Get VBA Payments
Source: https://www.cashfree.com/docs/api-reference/payments/latest/pgvba/get-vba-payments

openapi/pgvba/pgvba.yaml post /pg/vba/payments
Use this API to get all the payment details regarding a virtual bank account.



# Get VBA Payments By UTR
Source: https://www.cashfree.com/docs/api-reference/payments/latest/pgvba/get-vba-payments-by-utr

openapi/pgvba/pgvba.yaml get /pg/vba/payments/{utr}
Use this API to get the payment details by entering the unique transaction reference (UTR).



# Manage VBA
Source: https://www.cashfree.com/docs/api-reference/payments/latest/pgvba/manage-vba

openapi/pgvba/pgvba.yaml patch /pg/vba/{virtual_account_id}
Use this API to manage the status of the created virtual bank account.



# Manage VBA Notification Group Status
Source: https://www.cashfree.com/docs/api-reference/payments/latest/pgvba/manage-vba-notification-group-status

openapi/pgvba/pgvba.yaml patch /pg/vba/notificationgroup/{notification_group_name}
Use this API to modify the status of the created notification group.



# Vendor Reconciliation API
Source: https://www.cashfree.com/docs/api-reference/payments/latest/reconciliation/vendor-reconciliation-api

openapi/payments/v2026-01-01.yaml post /recon/vendor
This API allows you to fetch vendor reconciliation details by using different filters. Use the appropriate filters based on your requirements. After you receive a VENDOR_SETTLEMENT_SUCCESS webhook confirmation, wait 15 minutes before you call this API endpoint.
 - **View Split Order Details Using Settlement ID**: Retrieve details of split orders within a settlement by Settlement ID.
 - **Vendor Recon for a Time Period**: Fetch reconciliation details for all vendors within a specific time interval.
 - **Vendor Recon Using Vendor ID & Time Interval**: Get reconciliation details for a specific vendor within a given time interval.


<Warning>
  **Vendor Recon API usage**

  When you use the Vendor Recon API, follow these guidelines:

  * Don't call the API with a failed `settlement_id`. If a settlement has failed and the amount remains unsettled, the API returns no data.
  * If the amount is later settled under a new (successful) `settlement_id`, the API returns data for the successful settlement instead.
  * To retrieve records older than six months, include a date range in your request. Searches using `settlement_id` return data from the last six months only.
</Warning>


# Create Refund
Source: https://www.cashfree.com/docs/api-reference/payments/latest/refunds/create-refund

openapi/payments/v2026-01-01.yaml post /orders/{order_id}/refunds
Use this API to initiate refunds. <Note> You can initiate refunds only within six months of the original successful transaction's date and time.</Note>



# Get All Refunds for an Order
Source: https://www.cashfree.com/docs/api-reference/payments/latest/refunds/get-all-refunds-for-an-order

openapi/payments/v2026-01-01.yaml get /orders/{order_id}/refunds
Use this API to fetch all refunds processed against an order.



# Get Refund
Source: https://www.cashfree.com/docs/api-reference/payments/latest/refunds/get-refund

openapi/payments/v2026-01-01.yaml get /orders/{order_id}/refunds/{refund_id}
Use this API to fetch a specific refund processed on your Cashfree Account.



# Update Refund
Source: https://www.cashfree.com/docs/api-reference/payments/latest/refunds/update-refund

openapi/payments/v2026-01-01.yaml put /orders/{order_id}/refunds/{refund_id}
Use this API to Update refunds.



# Refund Webhooks
Source: https://www.cashfree.com/docs/api-reference/payments/latest/refunds/webhooks

Subscribe to Cashfree refund webhook events for successful refunds, cancelled refunds after retries, and automatic auto-refunds triggered for failed orders.

Webhooks are server callbacks to your server from Cashfree. We send refund webhooks for three different events for a payment.

1. Refund is successfully processed
2. Refund is cancelled by Cashfree - we were unable to successfully refund to customer even after multiple attempts.
3. For successful Auto-refunds - Read more about Auto-Refunds [here](/docs/payments/manage/refunds/overview#auto-refunds)

## Refund webhook payload

<Tabs>
  <Tab title="Version (2025-01-01)">
    ```javascript Version 2025-01-01 theme={"dark"}
    {
    "data":{
        "refund":{
             "cf_refund_id":11325632,
             "cf_payment_id":789727431,
             "refund_id":"refund_sampleorder0413",
             "order_id":"sampleorder0413",
             "refund_amount":2.00,
             "refund_currency":"INR",
             "entity":"Refund",
             "refund_type":"MERCHANT_INITIATED",
             "refund_arn":"205907014017",
             "refund_status":"SUCCESS",
             "status_description":"Refund processed successfully",
             "created_at":"2022-02-28T12:54:25+05:30",
             "processed_at":"2022-02-28T13:04:27+05:30",
             "refund_note":"Test",
             "refund_splits":[
                {
                   "merchantVendorId":"sampleID12345",
                   "amount":1,
                   "percentage":null
                },
                {
                   "merchantVendorId":"otherVendor",
                   "amount":1,
                   "percentage":null
                }
             ],
             "metadata":null,
             "requested_speed":"STANDARD",
             "processed_speed":"STANDARD",
             "service_charge":0.00,
             "service_tax":0.00,
             "forex_conversion_handling_charge":null,
             "forex_conversion_handling_tax":null,
             "forex_conversion_rate":null,
             "charges_currency":null
          },
          terminalDetails:{
             "cf_terminal_id":17269,
             "terminal_phone":"8971520311"
          }
       },
       "event_time":"2022-02-28T13:04:28+05:30",
       "type":"REFUND_STATUS_WEBHOOK"
    }
    ```
  </Tab>

  <Tab title="Version (2023-08-01)">
    ```javascript Version 2023-08-01 theme={"dark"}
    {
    "data":{
        "refund":{
             "cf_refund_id":11325632,
             "cf_payment_id":789727431,
             "refund_id":"refund_sampleorder0413",
             "order_id":"sampleorder0413",
             "refund_amount":2.00,
             "refund_currency":"INR",
             "entity":"Refund",
             "refund_type":"MERCHANT_INITIATED",
             "refund_arn":"205907014017",
             "refund_status":"SUCCESS",
             "status_description":"Refund processed successfully",
             "created_at":"2022-02-28T12:54:25+05:30",
             "processed_at":"2022-02-28T13:04:27+05:30",
             "refund_note":"Test",
             "refund_splits":[
                {
                   "merchantVendorId":"sampleID12345",
                   "amount":1,
                   "percentage":null
                },
                {
                   "merchantVendorId":"otherVendor",
                   "amount":1,
                   "percentage":null
                }
             ],
             "metadata":null,
             "requested_speed":"STANDARD",
             "processed_speed":"STANDARD",
             "service_charge":0.00,
             "service_tax":0.00
        }
       },
       "event_time":"2022-02-28T13:04:28+05:30",
       "type":"REFUND_STATUS_WEBHOOK"
    }
    ```
  </Tab>
</Tabs>

## Auto refund webhook payload

Auto-refund webhooks differ from standard refund webhooks because they handle refunds that occur automatically (like failed payment attempts) rather than manual refunds tied to specific orders. Since these automatic refunds may happen before an order is created, they don't contain the usual order-related data fields that are mandatory in standard refund webhooks,

<Tabs>
  <Tab title="Version 2025-01-01">
    ```javascript Version 2025-01-01 theme={"dark"}
    {
      "data": {
        "auto_refund": {
          "event": "AUTO-REFUND",
          "cf_refund_id": 1243460973,
          "cf_payment_id": "2148333968",
          "bank_reference": "234928698581",
          "order_id": "order_1944392Tpba8y2fHcHVx0SwREojp51Jgr",
          "refund_amount": 39,
          "refund_currency": "INR",
          "refund_type": "PAYMENT_AUTO_REFUND",
          "refund_arn": "205907014017",
          "refund_status": "SUCCESS",
          "status_description": "Auto-Refund processed successfully",
          "refund_reason": "Multiple payments were performed against same order.",
          "created_at": "2023-08-11T14:08:28+05:30",
          "processed_at": null,
          "refund_charge": 0,
          "refund_splits": null,
          "metadata": null,
          "forex_conversion_handling_charge": null,
          "forex_conversion_handling_tax": null,
          "forex_conversion_rate": null,
          "charges_currency": null
        },
        terminalDetails:{
          "cf_terminal_id":17269,
          "terminal_phone":"8971520311"
        }
      },
      "event_time": "2023-08-11T14:10:21+05:30",
      "type": "AUTO_REFUND_STATUS_WEBHOOK"
    }
    ```
  </Tab>

  <Tab title="Version 2023-08-01">
    ```javascript Version 2023-08-01 theme={"dark"}
    {
      "data": {
        "auto_refund": {
          "event": "AUTO-REFUND",
          "cf_refund_id": 1243460973,
          "cf_payment_id": "2148333968",
          "bank_reference": "234928698581",
          "order_id": "order_1944392Tpba8y2fHcHVx0SwREojp51Jgr",
          "refund_amount": 39,
          "refund_currency": "INR",
          "refund_type": "PAYMENT_AUTO_REFUND",
          "refund_arn": "205907014017",
          "refund_status": "SUCCESS",
          "status_description": "Auto-Refund processed successfully",
          "refund_reason": "Multiple payments were performed against same order.",
          "created_at": "2023-08-11T14:08:28+05:30",
          "processed_at": null,
          "refund_charge": 0,
          "refund_splits": null,
          "metadata": null
        }
      },
      "event_time": "2023-08-11T14:10:21+05:30",
      "type": "AUTO_REFUND_STATUS_WEBHOOK"
    }
    ```
  </Tab>
</Tabs>


# Submit Risk Details
Source: https://www.cashfree.com/docs/api-reference/payments/latest/risk/submit-risk-details

openapi/payments/risk-details.yaml post /risk-details
Use this API to submit comprehensive risk assessment data for an order to Cashfree's risk management system. The API accepts customer details, device information, and industry-specific transaction data for enhanced fraud detection and risk analysis.




# Get All Settlements
Source: https://www.cashfree.com/docs/api-reference/payments/latest/settlement-reconciliation/get-all-settlements

openapi/payments/v2026-01-01.yaml post /settlements
Use this API to get all settlement details by specifying the settlement ID, settlement UTR, settlement status or date range. Returns settlements of all statuses including SUCCESS, PENDING, PENDING_WITH_CASHFREE, PENDING_WITH_BANK and FAILED.



# Settlement Reconciliation
Source: https://www.cashfree.com/docs/api-reference/payments/latest/settlement-reconciliation/settlement-reconciliation

openapi/payments/v2026-01-01.yaml post /settlement/recon
- Use this API to get settlement reconciliation details using Settlement ID, settlement UTR or date range.
- This API will return events for the settlement IDs you want




# Get Settlements by Order ID
Source: https://www.cashfree.com/docs/api-reference/payments/latest/settlements/get-settlements-by-order-id

openapi/payments/v2026-01-01.yaml get /orders/{order_id}/settlements
Use this API to view the latest linked settlement details for a particular order, including pending and failed settlements.



# Mark Order For Settlement
Source: https://www.cashfree.com/docs/api-reference/payments/latest/settlements/mark-order-for-settlement

openapi/payments/v2026-01-01.yaml post /orders/settlements
Use this API to pass the CBRIKS ID to Cashfree and mark an order for settlement.

<Note>This API supports only merchants linked with the National Stock Exchange (NSE) or Bombay Stock Exchange (BSE).</Note>


# Settlement Webhooks
Source: https://www.cashfree.com/docs/api-reference/payments/latest/settlements/settlement-webhooks

Get notified about Cashfree merchant and vendor settlements via webhooks that fire when payouts to bank accounts are initiated, succeeded, or failed.

We broadly send two types of notifications when a payout happens.

1. Payout to Merchant account
2. Payout to Vendor account (if you are using Easy Split)

## Settlement Webhook

This webhook is triggered whenever there is a payout to your merchant account. The settlement webhooks will notify you about instant settlements in addition to the standard settlement webhooks.  We send webhooks for four different events for a `settlement`.

| Webhook event | Description |
| - | - |
| SETTLEMENT\_INITIATED | This webhook will be triggered when a settlement is initiated. |
| SETTLEMENT\_SUCCESS | This webhook will be triggered when a settlement is successful. |
| SETTLEMENT\_FAILED | This webhook will be triggered when a settlement has failed. |
| SETTLEMENT\_REVERSED | This webhook will be triggered when a settlement has been reversed. |

The following webhook is sent for other types of settlements as well: instant settlement or an on-demand settlement.

<Tabs>
  <Tab title="Version 2025-01-01">
    ```javascript 2025-01-01 theme={"dark"}
    {
        "data": {
            "settlement": {
                "adjustment": 0,
                "amount_settled": 97.94,
                "payment_amount": 100,
                "payment_from": "2025-02-14 12:00:00",
                "payment_till": "2025-02-14 12:15:00",
                "reason": null,
                "service_charge": 1.75,
                "service_tax": 0.31,
                "settled_on": "2025-02-14T12:35:19+05:30",
                "settlement_type": "STANDARD",   //settlement type //
                "settlement_amount": 97.94,
                "settlement_id": 738,
                "settlement_initiated_on": "2025-02-14T12:35:17+05:30",
                "status": "SUCCESS",
                "utr": 1644822317781212,
                "settlement_charge": 0,    // applicable for instant settlement //
                "settlement_tax": 0,       // applicable for instant settlement //
                "remarks": null,           // applicable for instant settlement //
                "forex_conversion_handling_charge":null,
                "forex_conversion_handling_tax":null,
                "forex_conversion_rate":null,
                "charges_currency":null
            }
        },
        "event_time": "2022-02-08T13:37:34+05:30",
        "type": "SETTLEMENT_SUCCESS"
    }
    ```
  </Tab>

  <Tab title="Version 2023-08-01">
    ```javascript 2023-08-01 theme={"dark"}
    {
        "data": {
            "settlement": {
                "adjustment": 0,
                "amount_settled": 97.94,
                "payment_amount": 100,
                "payment_from": "2022-02-14 12:00:00",
                "payment_till": "2022-02-14 12:15:00",
                "reason": null,
                "service_charge": 1.75,
                "service_tax": 0.31,
                "settled_on": "2022-02-14T12:35:19+05:30",
                "settlement_type": "STANDARD",   //settlement type //
                "settlement_amount": 97.94,
                "settlement_id": 738,
                "settlement_initiated_on": "2022-02-14T12:35:17+05:30",
                "status": "SUCCESS",
                "utr": 1644822317781212,
                "settlement_charge": 0,    // applicable for instant settlement //
                "settlement_tax": 0,       // applicable for instant settlement //
                "remarks": null.           // applicable for instant settlement //
            }
        },
        "event_time": "2022-02-08T13:37:34+05:30",
        "type": "SETTLEMENT_SUCCESS"
    }
    ```
  </Tab>
</Tabs>

<Accordion title="Understand these fields in detail">
  ## Payload field description

  | Field | Description | Example |
  | - | - | - |
  | adjustment | Sum of refunds, disputes, and chargebacks included in this settlement. | 0 |
  | amount\_settled | Total amount settled in this schedule. | 15 |
  | payment\_amount | Total transaction amount considered for settlement. | 15 |
  | payment\_from | Start date and time from which payments are considered for settlement. | 2022-02-14 12:00:00 |
  | payment\_till | End date and time till which payments are considered for settlement. | 2022-02-23 12:00:00 |
  | reason | Reason for failed or reversed settlements. | Transfer mode not valid for beneficiary. |
  | service\_charge | Service charges applicable to the payments included in this settlement. | 2 |
  | service\_tax | Service tax applicable to the payments included in this settlement. | 0 |
  | settled\_on | Date and time when the settlement was processed. | 2022-03-17T14:21:18+05:30 |
  | settlement\_type | Type of settlement (e.g., INSTANT). | INSTANT |
  | settlement\_amount | Net settlement amount for the payments included in this settlement. | 13 |
  | settlement\_id | Unique settlement ID generated by Cashfree. | 1155353 |
  | settlement\_initiated\_on | Date on which settlement was initiated. | 2022-03-17T14:29:21+05:30 |
  | status | Status of the settlement (INITIATED, SUCCESS, FAILED, or REVERSED). | SUCCESS |
  | utr | Unique transaction reference number provided by the bank for the settlement. | N076221079016329 |
  | settlement\_charge | Additional charge applicable for instant settlement. | 10.10 |
  | settlement\_tax | Settlement tax applicable for instant settlement. | 01.97 |
  | remarks | Any remarks specified by the merchant. | Settlement Initiated |
  | event\_time | Time when the settlement webhook was triggered. | 2022-03-17T14:29:23+05:30 |
  | type | Type of webhook event (SETTLEMENT\_INITIATED, SETTLEMENT\_SUCCESS, SETTLEMENT\_FAILED, or SETTLEMENT\_REVERSED). | SETTLEMENT\_SUCCESS |
</Accordion>

## Vendor Settlement Webhook

<Warning>This section only applies to merchants using our Easy Split product </Warning>

These settlement webhooks automate notifications when vendor settlements are initiated, successfully processed, failed, or reversed.

| Webhook event | Description |
| :- | :- |
| VENDOR\_SETTLEMENT\_INITIATED | This webhook will be triggered when a vendor settlement is initiated. |
| VENDOR\_SETTLEMENT\_SUCCESS | This webhook will be triggered when a vendor settlement is successful. |
| VENDOR\_SETTLEMENT\_FAILED | This webhook will be triggered when a vendor settlement has failed. |
| VENDOR\_SETTLEMENT\_REVERSED | This webhook will be triggered when a vendor settlement has been reversed. |

```javascript Vendor Settlement Webhook theme={"dark"}
{
    "data": {
        "settlement": {
            "adjustment": 0,
            "amount_settled": 10,
            "payment_amount": null,
            "payment_from": "2022-05-26",
            "payment_till": "2022-05-26",
            "reason": null,
            "service_charge": 0.05,
            "service_tax": 0.01,
            "settled_on": "2022-05-26T15: 06: 14+05: 30",
            "settled_orders_count": 2,
            "settlement_amount": 10,
            "settlement_id": 6151,
            "settlement_initiated_on": "2022-05-26T15: 06: 09+05: 30",
            "settlement_type": null,
            "status": "CREATED",
            "utr": null,
            "vendor_id": "Vendor_123adj4dr4osn23fn",
            "vendor_transaction_amount": 10,
            "account_mode": "BANK",
            "account_number": "XXXXXXX1234",
            "ifsc": "HDFC0000001",
            "vpa": null
        },
        "event_time": "2022-05-26T15:06:15+05:30",
        "type": "VENDOR_SETTLEMENT_INITIATED"
    }
}
```

## Transaction wise settlement webhook

<Warning>This section only applies to merchants using our Transaction Wise Settlement model</Warning>

These TWS(Transaction Wise Settlement) webhooks are triggered when settlement are initiated, successfully processed, failed, or reversed.

| Webhook event | Description |
| :- | :- |
| TRANSACTION\_WISE\_SETTLEMENT\_INITIATED | This webhook will be triggered when a TWS is initiated. |
| TRANSACTION\_WISE\_SETTLEMENT\_SUCCESS | This webhook will be triggered when a TWS is successful. |
| TRANSACTION\_WISE\_SETTLEMENT\_FAILED | This webhook will be triggered when a TWS has failed. |
| TRANSACTION\_WISE\_SETTLEMENT\_REVERSED | This webhook will be triggered when a TWS has been reversed. |

```javascript Transaction Wise Settlement Webhook theme={"dark"}
{
    "data":{
         "order":{
            "order_id":"order_OFR_2",
            "order_amount":2,
            "order_currency":"INR",
            "order_tags":null
         },
         "payment":{
            "cf_payment_id":"1453002795",
            "payment_status":"SUCCESS",
            "payment_amount":1,
            "payment_currency":"INR",
            "payment_message":"00::Transaction success",
            "payment_time":"2022-12-15T12:20:29+05:30",
            "bank_reference":"234928698581",
            "auth_id":null,
            "payment_method":{
               "upi":{
                  "channel":"collect",
                  "upi_id":"suhasg6@ybl",
                  "upi_instrument":"UPI_CREDIT_CARD",
                  "upi_instrument_number":"masked card number",
                  "upi_payer_ifsc":"SBI0025434",
                  "upi_payer_account_number":"XXXXX0231"
               }
            },
            "payment_group":"upi"
         },
         "customer_details":{
            "customer_name":null,
            "customer_id":"7112AAA812234",
            "customer_email":"test@gmail.com",
            "customer_phone":"9908734801"
         },
         "payment_gateway_details":null,
         "payment_offers":null,
         "settlement": {
             "settlement_id": "1639789947",
             "status": "SUCCESS",
             "utr": "1212743972438575",
             "payment_amount": 500.00,
             "settlement_initiated_on": "2025-03-15T22:21:29+05:30",
             "settled_on": "2025-03-15T22:22:30+05:30",
             "reason": "Transfer completed successfully",
             "adjustment": 0.00,
             "settlement_amount": 441.00,
             "service_charge": 50.00,
             "service_tax": 9.00,
             "amount_settled": 441.00,
             "payment_from": "2025-03-15T22:21:29+05:30",
             "payment_till": "2025-03-15T22:21:29+05:30",
             "settlement_type": "NORMAL_SETTLEMENT",
             "remarks": null,
             "settlement_charge": 0.00,
             "settlement_tax": 0.00
         }
       },
         "event_time": "2025-04-10T22:22:06+05:30",
         "type": "TRANSACTION_WISE_SETTLEMENT_SUCCESS"
       }
}
```


# Fetch Settlement Simulation
Source: https://www.cashfree.com/docs/api-reference/payments/latest/simulation/fetch-settlement-simulation

openapi/payments/v2026-01-01.yaml get /simulate/settlement/{simulation_id}
Use this API to fetch the details of a simulated settlement.



# Fetch Simulation
Source: https://www.cashfree.com/docs/api-reference/payments/latest/simulation/fetch-simulation

openapi/payments/v2026-01-01.yaml get /simulate/{simulation_id}
Use this API to fetch simulated payment details.



# Simulate Payment
Source: https://www.cashfree.com/docs/api-reference/payments/latest/simulation/simulate-payment

openapi/payments/v2026-01-01.yaml post /simulate
Use this API to simulate payment. To use this API you should first create an order using the Create Order API. Also, you need to create a payment with the same order.



# Simulate Settlement Payment
Source: https://www.cashfree.com/docs/api-reference/payments/latest/simulation/simulate-settlement-payment

openapi/payments/v2026-01-01.yaml post /simulate/settlement
Use this API to simulate a settlement in the sandbox environment. First, create a successful order, and then call this API with the order ID to simulate the settlement for that order.



# Easy Split Overview
Source: https://www.cashfree.com/docs/api-reference/payments/latest/split/easy-split-overview

Use Cashfree Easy Split to share each order amount across multiple vendors and settle their share automatically when the parent transaction is captured.

Easy Split automates the splitting of payments with vendors and partners on time. Collect payments from customers, and set up a flexible schedule options to disburse payments to your vendors. Get detailed reports on the transactions, settlements, refunds, vendor payments and adjustments.

**How does Easy Split work?**

<img alt="" />

**You can perform the following tasks using Easy Split:**

* Add and manage all your vendors efficiently
* Split payments and settle them into multiple vendor accounts using the available schedule options cycles
* Check on-demand vendor balance and settle the money into the vendor accounts instantly
* Vendor reconciliation

The table below provides the list of Easy Split APIs along with their description:

**Vendor APIs**

| API name | Description |
| :- | :- |
| [Create Vendor](/docs/api-reference/payments/latest/easy-split/create-vendor) | Create Vendor API creates a new vendor in your Easy Split account. |
| [Update Vendor Details](/docs/api-reference/payments/latest/easy-split/update-vendor-details) | Update Vendor Details API updates the existing vendor details. |
| [Get All Vendor Details](/docs/api-reference/payments/latest/easy-split/get-vendor-all-details) | Get All Vendor Details API gets the details of all the vendors associated with that Easy Split account. |
| [Create On Demand Transfer](/docs/api-reference/payments/latest/easy-split/create-on-demand-transfer) | Create On Demand Transfer API initiates a balance transfer request between merchant and vendor. |
| [Create Refund](/docs/api-reference/payments/latest/refunds/create-refund) | Create Refund API creates a new refund. |

**Split Order APIs**

| API name | Description |
| :- | :- |
| [Create Static Split](/docs/api-reference/payments/latest/easy-split/create-static-split-configuration) | Use this API to create a split at order level. |
| [Split After Payment](/docs/api-reference/payments/latest/easy-split/split-after-payment) | Split After Payment API creates a split after the payment is completed. |
| [Get Split and Settlement Details by Order ID](/docs/api-reference/payments/latest/easy-split/get-split-and-settlement-details-by-orderid) | Get Split and Settlement Details by Order ID API gets details of the split, settled and unsettled transactions of each vendor using the Order ID. |

**Settlement APIs**

| API name | Description |
| :- | :- |
| [Get Vendor Settlement Details](/docs/api-reference/payments/latest/easy-split/get-split-and-settlement-details-by-orderid) | Get Vendor Settlement Details (same endpoint as split-order recon; specify a settlement ID to filter results or leave blank for all) |

**On Demand Settlement APIs**

| API name | Description |
| :- | :- |
| [Get On Demand Balance](/docs/api-reference/payments/latest/easy-split/get-on-demand-balance) | Get On Demand Balance API fetches the available merchant and vendor balances. |
| [Create On Demand Transfer](/docs/api-reference/payments/latest/easy-split/create-on-demand-transfer) | Create On Demand Transfer API initiates a balance transfer request between merchant and vendor. |

**Reconciliation APIs**

| API name | Description |
| :- | :- |
| [Vendor Reconciliation](/docs/api-reference/payments/latest/reconciliation/vendor-reconciliation-api) | Vendor Reconciliation API fetches vendor recon details; supports split-order lookups by settlement ID, time-period queries, and vendor-specific intervals. |


# Easy Split - Postman Collection
Source: https://www.cashfree.com/docs/api-reference/payments/latest/split/easy-split-postman-collection

Download the Easy Split Postman collection to explore Cashfree marketplace endpoints for vendor creation, splits, on-demand transfers, and settlements.

Get started quickly with Cashfree's Easy Split APIs by downloading the collection and importing it in Postman.

<a href="https://gocashassets.s3.ap-south-1.amazonaws.com/postmancollection/Easy_Split_Postman_Collection.zip">Download Cashfree Easy Split Postman Collection</a>

Watch the video below to learn how to setup API

<iframe title="YouTube video player" />


# End Points
Source: https://www.cashfree.com/docs/api-reference/payments/latest/split/end-points

Reference base URLs for the Cashfree Easy Split sandbox and production environments along with authentication headers required for every API call.

Cashfree uses API keys to allow access to the API. Once you have signed up at our merchant site, you can see your AppId and SecretKey.

Cashfree expects the API key to be included in all API requests to the server. Use the endpoint /api/v1/credentials/verify to verify your credentials.

| Environment | Base URL |
| :- | :- |
| Production | [https://api.cashfree.com/pg](https://api.cashfree.com/pg) |
| Test | [https://sandbox.cashfree.com/pg](https://sandbox.cashfree.com/pg) |


# Overview
Source: https://www.cashfree.com/docs/api-reference/payments/latest/split/vendors/overview

Use Cashfree's Vendor 2.0 APIs to create vendors, update KYC and bank details, upload documents, and fetch vendor status for Easy-Split payouts.

This section consists of the new set of Vendor KYC APIs. Use these APIs to perform actions such as creating a vendor, updating vendor details, get vendor details, upload vendor KYC documents, get all vendor documents and so on.

**Vendors 2.0 APIs**

| API Name | Description |
| :- | :- |
| [Create Vendor v2.0](/docs/api-reference/payments/latest/easy-split/create-vendor) | This API creates a new vendor in Cashfree system. |
| [Update Vendor Details v2.0](/docs/api-reference/payments/latest/easy-split/update-vendor-details) | This API updates the existing vendor details such as name, email, phone number, UPI details, and any of the KYC details. |
| [Get Vendor All Details](/docs/api-reference/payments/latest/easy-split/get-vendor-all-details) | This API fetches all the details of a specific vendor by sharing the vendor ID. |
| [Upload Vendor Docs](/docs/api-reference/payments/latest/easy-split/upload-vendor-docs) | This API uploads the vendor KYC docs. |
| [Get Vendor All Document Status](/docs/api-reference/payments/latest/easy-split/get-vendor-all-documents-status) | This API fetches the submitted vendor KYC document status. |
| [Get Vendor Document Download URL](/docs/api-reference/payments/latest/easy-split/download-vendor-documents) | This API downloads the uploaded KYC documents. Provide the vendor ID and the document type. |


# Overview
Source: https://www.cashfree.com/docs/api-reference/payments/latest/split/webhooks/overview

Subscribe to Cashfree Easy Split webhooks to receive event-based notifications about vendor settlements, vendor status changes, and split payment activity.

Webhooks are server callbacks to your server from Cashfree. Webhooks are event-based and are sent when specific events happen.

The table below lists the various webhook events:

| Webhook name | Description |
| :- | :- |
| [Vendor Settlement Webhook](/docs/api-reference/payments/latest/split/webhooks/vendor-settlement-webhooks) | Configure vendor settlement webhooks to receive automated notifications when vendor settlements are initiated, successfully processed, failed, or reversed. |
| [Vendor Status Change Webhook](/docs/api-reference/payments/latest/split/webhooks/vendor-status-change-webhooks) | Configure vendor status change webhooks to receive automated notifications when vendor status is changed. |


# Vendor Settlement Webhook
Source: https://www.cashfree.com/docs/api-reference/payments/latest/split/webhooks/vendor-settlement-webhooks

Receive Cashfree vendor settlement webhooks when vendor payouts are initiated, successfully processed, failed, or reversed, so you can keep ledgers in sync.

Configure vendor settlement webhooks to receive automated notifications when vendor settlements are initiated, successfully processed, failed, or reversed.

The webhook notifications are sent on all the URLs added and enabled in the settlement webhook. You can add new URLs and enable or disable existing URLs for settlement webhook at any time and it will reflect instantaneously.

The table below lists the webhook events available for settlements.

| Webhook event | Description |
| :- | :- |
| VENDOR\_SETTLEMENT\_INITIATED | This webhook will be triggered when a vendor settlement is initiated. |
| VENDOR\_SETTLEMENT\_SUCCESS | This webhook will be triggered when a vendor settlement is successful. |
| VENDOR\_SETTLEMENT\_FAILED | This webhook will be triggered when a vendor settlement has failed. |
| VENDOR\_SETTLEMENT\_REVERSED | This webhook will be triggered when a vendor settlement has been reversed. |

## Vendor settlement initiated

SETTLEMENT\_INITIATED webhook is triggered when a settlement has been initiated by Cashfree.

```
{
    "data": {
        "settlement": {
            "settlement_id": 49703,
            "status": "CREATED",
            "utr": "1686217237243457",
            "payment_amount": null,
            "settlement_initiated_on": "2023-06-08T15:10:35+05:30",
            "settlement_type": null,
            "settled_on": "null",
            "reason": null,
            "adjustment": 100.00,
            "settlement_amount": 600.00,
            "service_charge": 0.50,
            "service_tax": 0.09,
            "amount_settled": null,
            "payment_from": "2023-06-08",
            "payment_till": "2023-06-08",
            "vendor_id": "esSettlementsAutomationVendor",
            "vendor_transaction_amount": 500.00,
            "account_mode": "BANK",
            "settled_orders_count": 1,
            "account_number": "XXXXXXX1234",
            "ifsc": "HDFC0000001",
            "vpa": null
        }
    },
    "event_time": "2023-06-08T15:10:37+05:30",
    "type": "VENDOR_SETTLEMENT_CREATED"
}
```

## Vendor settlement success

```
{
    "data": {
        "settlement": {
            "settlement_id": 49703,
            "status": "SUCCESS",
            "utr": "1686217237243457",
            "payment_amount": null,
            "settlement_initiated_on": "2023-06-08T15:10:35+05:30",
            "settlement_type": null,
            "settled_on": "2023-06-08T15:10:37+05:30",
            "reason": null,
            "adjustment": 100.00,
            "settlement_amount": 600.00,
            "service_charge": 0.50,
            "service_tax": 0.09,
            "amount_settled": 600.00,
            "payment_from": "2023-06-08",
            "payment_till": "2023-06-08",
            "vendor_id": "esSettlementsAutomationVendor",
            "vendor_transaction_amount": 500.00,
            "account_mode": "UPI",
            "settled_orders_count": 1,
            "account_number": null,
            "ifsc": null,
            "vpa": "9898989898@ybl"
        }
    },
    "event_time": "2023-06-08T15:10:37+05:30",
    "type": "VENDOR_SETTLEMENT_SUCCESS"
}
```

***

## Vendor settlement failed

```
{
    "data": {
        "settlement": {
            "settlement_id": 49703,
            "status": "FAILED",
            "utr": "1686217237243457",
            "payment_amount": null,
            "settlement_initiated_on": "2023-06-08T15:10:35+05:30",
            "settlement_type": null,
            "settled_on": "null",
            "reason": null,
            "adjustment": 100.00,
            "settlement_amount": 600.00,
            "service_charge": 0.50,
            "service_tax": 0.09,
            "amount_settled": null,
            "payment_from": "2023-06-08",
            "payment_till": "2023-06-08",
            "vendor_id": "esSettlementsAutomationVendor",
            "vendor_transaction_amount": 500.00,
            "account_mode": "BANK",
            "settled_orders_count": 1,
            "account_number": "XXXXXXX1234",
            "ifsc": "HDFC0000001",
            "vpa": null
        }
    },
    "event_time": "2023-06-08T15:10:37+05:30",
    "type": "VENDOR_SETTLEMENT_FAILED"
}
```

***

## Vendor settlement reversed

```
{
    "data": {
        "settlement": {
            "settlement_id": 49703,
            "status": "REVERSED",
            "utr": "1686217237243457",
            "payment_amount": null,
            "settlement_initiated_on": "2023-06-08T15:10:35+05:30",
            "settlement_type": null,
            "settled_on": "null",
            "reason": Failed from bank end,
            "adjustment": 100.00,
            "settlement_amount": 600.00,
            "service_charge": 0.50,
            "service_tax": 0.09,
            "amount_settled": null,
            "payment_from": "2023-06-08",
            "payment_till": "2023-06-08",
            "vendor_id": "esSettlementsAutomationVendor",
            "vendor_transaction_amount": 500.00,
            "account_mode": "BANK",
            "settled_orders_count": 1,
            "account_number": "XXXXXXX1234",
            "ifsc": "HDFC0000001",
            "vpa": null
        }
    },
    "event_time": "2023-06-08T15:10:37+05:30",
    "type": "VENDOR_SETTLEMENT_REVERSED"
}
```

***

## Payload field description

| Field | Description | Example |
| - | - | - |
| adjustment | The sum of refunds, disputes, and chargeback part of this settlement is displayed here. | 0 |
| amount\_settled | The total amount that is settled in this schedule option. | 50 |
| payment\_amount | Total transaction amount considered for settlement. | 100 |
| payment\_from | Start date from which the payments are considered for settlement. | 2022-03-15 |
| payment\_till | End date till which the payments are considered for settlement. | 2022-03-23 |
| reason | Reason for failed and reversed settlements. | Transfer mode is not valid for beneficiary. |
| service\_charge | Service charges are applicable for the payments that are included in this settlement. | 2 |
| service\_tax | Service tax is applicable for the payments that are included in this settlement. | 0.50 |
| settled\_on | Date and time at which the settlement was processed. | 2022-03-17T14:21:18+05:30 |
| settlement\_amount | The sum of net settlement amount for the payments part of this settlement. | 13 |
| settlement\_id | Cashfree settlement ID | 1155353 |
| settlement\_initiated\_on | The date on which settlement was initiated. | 2022-03-17T14:29:21+05:30 |
| status | Status of the settlement (either INITIATED, SUCCESS, FAILED, or REVERSED) | SUCCESS |
| utr | The unique transaction reference number is given by the bank for the settlement. | N076221079016329 |
| vendor\_id | Reference ID as shared by you when onboarding the vendor. | IS\_1hour\_Upi |
| vendor\_transaction\_amount | Transaction amount split of vendor | 50 |
| event\_time | Time at which settlement webhook was initiated. | 2022-03-17T14:29:23+05:30 |
| type | Type of webhook - VENDOR\_SETTLEMENT\_INITIATED, VENDOR\_SETTLEMENT\_SUCCESS, VENDOR\_SETTLEMENT\_FAILED, or VENDOR\_SETTLEMENT\_REVERSED. | VENDOR\_SETTLEMENT\_SUCCESS |

## Reasons for failed and reversed settlements

| Reason | Category | Description |
| :- | :- | :- |
| BANK\_GATEWAY\_ERROR | Bank | Technical error at the bank |
| BENE\_BANK\_DECLINED | Bank | Rejected by Beneficiary bank due to business reasons |
| FAILED | Bank | No explicit failure reason from the bank |
| INVALID\_IFSC\_FAIL | Customer | Invalid ifsc code provided for bank account |
| INVALID\_ACCOUNT\_FAIL | Customer | Bank account is invalid |
| RETURNED\_FROM\_BENEFICIARY | Bank | Immediate reversal from the beneficiary bank |
| INSUFFICIENT\_BALANCE | Vendor | Your balance is exhausted, need to add funds |
| IMPS\_MODE\_FAIL | Bank | IMPS mode not supported for the beneficiary |
| RTGS\_MODE\_FAIL | Bank | RTGS mode not supported (only for RTGS) |
| REINITIALIZE\_TRANSFER\_LATER | Bank | Technical error at the bank, retry later |
| NRE\_ACCOUNT\_FAIL | Customer | Customer bank account is an NRE account |
| ACCOUNT\_BLOCKED | Customer | Customer bank account is blocked |
| DEST\_LIMIT\_REACHED | Bank | Transfer limit to beneficiary exceeded |
| INVALID\_MODE\_FAIL | Bank | Transfer mode not valid for beneficiary |
| NPCI\_UNAVAILABLE | Bank | NPCI in unavailable |
| BENEFICIARY\_BANK\_OFFLINE | Bank | Beneficiary bank is offline |
| INVALID\_AMOUNT\_FAIL | Vendor | Amount is invalid for the given transfer mode |
| SUSPECTED\_TRANSFER | Customer | Suspicious transfer identified |
| BENE\_NAME\_DIFFERS | Customer | Beneficiary name not matching with bank records |
| DISABLED\_MODE | Vendor | Transfer mode not enabled for the account |
| AMAZON\_AMOUNT\_EXCEED | Vendor | Amount should be less than 10000 for Amazon Pay mode |
| BENEFICIARY\_BLACKLISTED | Vendor | Beneficiary is blacklisted |
| PAYOUT\_INACTIVE | Vendor | Payout account is not active |
| INVALID\_TRANSFER\_AMOUNT | Vendor | Transfer amount is invalid |
| BENEFICIARY\_NOT\_EXIST | Vendor | Beneficiary does not exist |
| BENEFICIARY\_INVALID\_MODE | Vendor | Mode Not valid for Beneficiary |
| INVALID\_BENE\_ACCOUNT\_OR\_IFSC | Vendor | Invalid bank account number or ifsc provided |
| BENEFICIARY\_NAME\_DIFFERS | Customer | Beneficiary name not matching with bank records |
| ANY\_OTHER\_REASON | Bank | No reason provided for the failure/reversal |
| INVALID\_OR\_NO\_SUCH\_ACCOUNT\_TYPE | Customer | Invalid account |

***

## Signature verification

The signature must be used to verify if the request has not been tampered with. To verify the signature at your end, you will need your Cashfree PG secret key along with the payload.

timestamp is present in the header x-webhook-timestamp\
Actual signature is present in the header x-webhook-signature

```
"headers": {
        "host": "gamma.cashfree.com",
        "x-request-id": "ad4dc1e65f8901302455b247237a667a",
        "x-real-ip": "172.0.57.13",
        "x-forwarded-for": "172.0.57.13",
        "x-forwarded-host": "gamma.cashfree.com",
        "x-forwarded-port": "80",
        "x-forwarded-proto": "http",
        "x-forwarded-scheme": "http",
        "x-scheme": "http",
        "x-original-forwarded-for": "52.66.25.127",
        "content-length": "592",
        "accept": "_/_",
        "content-type": "application/json",
        "user-agent": "ReactorNetty/1.0.30",
        "x-datadog-parent-id": "4281924148563621550",
        "x-datadog-sampling-priority": "1",
        "x-datadog-trace-id": "228569355002181270",
        "x-webhook-signature": "Xm0YzEJCRsh0XvIEK12D4FqpmC60cReKoqPBn424kV0=",
        "x-webhook-timestamp": "1686217237543",
        "x-webhook-version": "2022-09-01"
    }
```

Watch this video to learn more on Vendor Webhooks:

<div>
  <iframe title="YouTube video player" />
</div>


# Vendor Status Change Webhook
Source: https://www.cashfree.com/docs/api-reference/payments/latest/split/webhooks/vendor-status-change-webhooks

Set up Cashfree vendor status change webhooks to receive automated notifications whenever a vendor in your Easy Split program is activated, blocked, or updated.

Configure vendor status change webhooks to receive automated notifications when vendor status is changed.

The webhook notifications are sent on all the URLs added and enabled in the vendor status change webhook. You can add new URLs and enable or disable existing URLs for vendor status change webhook at any time and it will reflect instantaneously.

The table below lists the webhook events available for vendor status change.

| Webhook event | Description |
| :- | :- |
| VENDOR\_STATUS\_UPDATE | This webhook will be triggered whenever there is a change in the status of the vendor. |

# Vendor Status Update

<Tabs>
  <Tab title="Version (2025-01-01)">
    ```javascript 2025-01-01 theme={"dark"}
    {
      "data": {
        "merchant_id": 152707,
        "merchant_vendor_id": "status002",
        "email": "[john.doe@cashfree.com]()",
        "updated_status": "ACTION_REQUIRED",
        "past_status": "IN_BENE_CREATION",
        "account_holder": "JOHN DOE",
        "phone": "9876554927",
        "name": "BOB HOPE",
        "product_type": "PG",
        "max_split": 100,
        "account_number": null,
        "ifsc": null,
        "dashboard_access": false,
        "vpa": "success@upi",
        "account_type": "Individual",
        "business_type": "Travel and Hospitality",
        "updated_by": "AUTOMATED",
        "document_status": {
          "PAN": "VERIFIED",
          "GSTIN": "DUE_CURRENTLY"
        }
      },
      "event_time": "2023-06-08T15:10:37+05:30",
      "type": "VENDOR_STATUS_UPDATE"
    }
    ```
  </Tab>

  <Tab title="Version (2023-08-01)">
    ```javascript Version 2023-08-01 theme={"dark"}
    {
      "data": {
        "merchant_id": 152707,
        "merchant_vendor_id": "status002",
        "email": "[john.doe@cashfree.com]()",
        "updated_status": "ACTION_REQUIRED",
        "past_status": "IN_BENE_CREATION",
        "account_holder": "JOHN DOE",
        "phone": "9876554927",
        "name": "BOB HOPE",
        "product_type": "PG",
        "max_split": 100,
        "account_number": null,
        "ifsc": null,
        "dashboard_access": false,
        "vpa": "success@upi",
        "account_type": "Individual",
        "business_type": "Travel and Hospitality",
        "updated_by": "AUTOMATED",
        "document_status": {
          "PAN": "VERIFIED",
          "GSTIN": "DUE_CURRENTLY"
        }
      },
      "event_time": "2023-06-08T15:10:37+05:30",
      "type": "VENDOR_STATUS_UPDATE"
    }
    ```
  </Tab>
</Tabs>

***

# Payload Field Description

| Field | Description | Example |
| - | - | - |
| merchant\_id | Cashfree Merchant ID. | 152707 |
| merchant\_vendor\_id | Reference ID as shared by you when onboarding the vendor. | IS\_1hour\_Upi |
| email | Email of the vendor. | [test@gmail.com](mailto:test@gmail.com) |
| updated\_status | Current status of the vendor. | ACTIVE |
| past\_status | Previous status of the vendor. | ACTION\_REQUIRED |
| account\_holder | Name of the account holder associated with the vendor. | John Doe |
| phone | Contact phone number of the vendor. | 9876554927 |
| name | Name of the vendor. | BOB HOPE |
| product\_type | Type of product offered to the vendor | PG |
| max\_split | The maximum percentage of the amount shared with a vendor in any order. | 100 |
| account\_number | Vendor's bank account number. | 12345678909 |
| ifsc | IFSC (Indian Financial System Code) associated with the vendor's bank. | SBIN1231935 |
| dashboard\_access | Access level to the dashboard for the vendor (if applicable). | FALSE |
| vpa | VPA of the vendor for UPI transactions. | success\@upi |
| account\_type | Type of the vendor's account. | Individual |
| business\_type | Type of business conducted by the vendor. | Travel and Hospitality |
| updated\_by | Entity or process that initiated the status update. | AUTOMATED |
| document\_status | Status of any associated documents for the vendor. | "PAN": "VERIFIED" "GSTIN": "DUE\_CURRENTLY" |

***

# Signature Verification

The signature must be used to verify if the request has not been tampered with. To verify the signature at your end, you will need your Cashfree PG secret key along with the payload.

timestamp is present in the header x-webhook-timestamp\
Actual signature is present in the header x-webhook-signature

```
"headers": {
        "host": "gamma.cashfree.com",
        "x-request-id": "ad4dc1e65f8901302455b247237a667a",
        "x-real-ip": "172.0.57.13",
        "x-forwarded-for": "172.0.57.13",
        "x-forwarded-host": "gamma.cashfree.com",
        "x-forwarded-port": "80",
        "x-forwarded-proto": "http",
        "x-forwarded-scheme": "http",
        "x-scheme": "http",
        "x-original-forwarded-for": "52.66.25.127",
        "content-length": "592",
        "accept": "_/_",
        "content-type": "application/json",
        "user-agent": "ReactorNetty/1.0.30",
        "x-datadog-parent-id": "4281924148563621550",
        "x-datadog-sampling-priority": "1",
        "x-datadog-trace-id": "228569355002181270",
        "x-webhook-signature": "Xm0YzEJCRsh0XvIEK12D4FqpmC60cReKoqPBn424kV0=",
        "x-webhook-timestamp": "1686217237543",
        "x-webhook-version": "2022-09-01"
    }

```

Watch this video to learn more on Vendor Webhooks


# Create a Plan
Source: https://www.cashfree.com/docs/api-reference/payments/latest/subscription/create-a-plan

openapi/payments/v2026-01-01.yaml post /plans
A plan allows your customer to identify the features you offer along with your pricing. You can create plans as per the pricing you support for your services. For each plan, you can set a pre-decided frequency and amount with which they’ll be charged.
Example: Netflix Plans : Premium, Basic, Standard, Mobile. Each plan differs and caters for a particular set of audiences.



# Create a Refund
Source: https://www.cashfree.com/docs/api-reference/payments/latest/subscription/create-a-refund

openapi/payments/v2026-01-01.yaml post /subscriptions/{subscription_id}/refunds
This API allows you to create refund on a successful payment. Refund amount can be partial or the full amount of the payment. 



# Create Subscription
Source: https://www.cashfree.com/docs/api-reference/payments/latest/subscription/create-subscription

openapi/payments/v2026-01-01.yaml post /subscriptions
Use this API to create a new subscription.



# End Points
Source: https://www.cashfree.com/docs/api-reference/payments/latest/subscription/endpoints

Reference base URLs and authentication headers required to call the Cashfree Subscriptions APIs across the sandbox and production environments.

Cashfree uses API keys to control access to the API. After you sign up on the merchant site, you'll receive your `AppId` and `SecretKey`.

Include your API key in all requests to the server. Use the endpoint **`/api/v1/credentials/verify`** to verify your credentials.

All API responses are in JSON format. POST requests must include the header `Content-Type: application/json`.

| Environment | Base URL |
| - | - |
| Test | `https://sandbox.cashfree.com/pg` |
| Production | `https://api.cashfree.com/pg` |
| Latest version | v6, 2026-01-01<br />Previous versions: 2025-01-01, 2023-08-01, 2021-05-21, 2022-01-01, 2022-09-01 |


# Error Codes and Reasons
Source: https://www.cashfree.com/docs/api-reference/payments/latest/subscription/error-codes

Reference the most common Cashfree Subscriptions API error codes, their failure reasons, and recommended resolutions to debug mandate and charge issues quickly.

## Error codes

The following are the common error codes returned by the Subscription APIs:

| Error code | Description | Resolution |
| - | - | - |
| `subscription_id_missing` | Subscription ID is required but missing in the request | Ensure the subscription ID is included in your API request |
| `plan_id_missing` | Plan ID is missing, invalid, or not found | Verify the plan ID exists and is correctly specified |
| `payment_id_missing` | Payment ID is missing or not found | Include a valid payment ID in your request |
| `subscription_id_missing_request_failed_failed` | Subscription ID missing; request failed | Add the required subscription ID parameter |
| `invalid_payment_type` | Invalid payment type specified | Use supported payment types: 'E\_MANDATE', 'UPI', or 'CARD' |
| `subscription_does_not_exist` | Subscription doesn't exist for the provided reference ID | Verify the subscription reference ID is correct |
| `authorization_payment_info_mismatch` | Authorisation payment info doesn't match subscription creation info | Ensure payment details match between subscription creation and authorisation |
| `tpv_not_supported` | TPV currently not allowed for Intent and QR auth flow | Use alternative auth flows when TPV is enabled |

## Transaction failure reasons

The following are the detailed failure reasons categorised by their nature:

* [Account issues](#account-issues)
* [Balance and limit issues](#balance-and-limit-issues)
* [Mandate issues](#mandate-issues)
* [Fraud and security](#fraud-and-security)
* [Technical issues](#technical-issues)
* [Customer action required](#customer-action-required)
* [Invalid data and validation](#invalid-data-and-validation)
* [Know your customer and documentation](#know-your-customer-and-documentation)
* [System and processing status](#system-and-processing-status)
* [Notification issues](#notification-issues)

### Account issues

The following are the account-related error codes:

| Error | Description | Resolution |
| - | - | - |
| `ACCOUNT CLOSED` | The account has been closed and all associated mandates were deactivated | Create a new mandate with a different account for the customer |
| `Account Blocked or frozen` | Account is temporarily blocked (for example, KYC not updated) | Customer needs to contact their bank to unblock the account |
| `DEBIT HAS BEEN FAILED \| ACCOUNT DOES NOT EXIST (REMITTER)` | Account verification failed due to incorrect account details | Verify and update correct account information |
| `Not a CBS act no.or old act no.representwithCBS no` | Account given for debit is old/non CBS/wrong/invalid | Use a valid CBS-enabled account number |
| `DEBIT HAS BEEN FAILED \| REMITTER CBS OFFLINE` | Core Banking System is offline | Wait for CBS to come online and retry |
| `U30\|DEBIT HAS BEEN FAILED\|YE\|REMITTING ACCOUNT BLOCKED/FROZEN` | Remitting account is blocked or frozen | Customer should contact their bank to resolve account issues |

### Balance and limit issues

The following are the balance and limit-related error codes:

| Error | Description | Resolution |
| - | - | - |
| `Balance Insufficient` | Insufficient funds in customer account | Customer should add funds or retry when balance is available |
| `DEBIT HAS BEEN FAILED \| INSUFFICIENT FUNDS IN CUSTOMER (REMITTER) ACCOUNT` | Insufficient balance in customer account | Recommend customer to maintain sufficient balance before retry |
| `U30\|DEBIT HAS BEEN FAILED\|Z9\|INSUFFICIENT FUNDS IN CUSTOMER (REMITTER) ACCOUNT` | Insufficient funds in remitter account | Customer needs to ensure adequate balance |
| `Amount Exceeds E-mandate Limit` | Transaction amount exceeds the e-mandate limit | Reduce amount or increase mandate limit if supported |
| `DEBIT HAS BEEN FAILED \| PER TRANSACTION LIMIT EXCEEDED AS SET BY REMITTING MEMBER` | Per transaction limit exceeded | Use amount within the set transaction limits |
| `U29\|ADDRESS RESOLUTION IS FAILED\|QL\|MANDATE DEBIT IS BEYOND PSP SPECIFIED AMOUNT CAP` | Amount limit is breached | Ensure amount is within PSP specified limits |
| `DEBIT HAS BEEN FAILED \| MANDATE REQUEST LIMIT HAS BREACHED` | Mandate request limit has been breached | Wait for limit reset or contact support |
| `U30\|DEBIT HAS BEEN FAILED\|QK\|MANDATE REQUEST LIMIT HAS BREACHED` | Mandate request limit exceeded | Review and adjust mandate limits |
| `Not Arranged For` | Bank account isn't set up to facilitate debit transaction | Customer should contact bank to set up debit facility |

### Mandate issues

The following are the mandate-related error codes:

| Error | Description | Resolution |
| - | - | - |
| `Invalid UMRN or Inactive Mandate` | Mandate has been deactivated by NPCI or cancelled by customer/merchant | Create a new mandate for the customer |
| `Mandate Cancelled` | Mandate has been cancelled by customer or merchant | Create a new mandate to continue debits |
| `Record Level Error: Invalid Mandate Info` | Mandate cancelled by customer from bank | Create a new mandate with updated information |
| `DEBIT HAS BEEN FAILED \| MANDATE HAS BEEN REVOKED` | Mandate has been revoked | Create a new mandate for the customer |
| `DEBIT HAS BEEN FAILED \| MANDATE SIGNATURE IS TAMPERED OR CORRUPT (REMITTER)` | Mandate signature is corrupted | Customer should contact issuing bank |
| `DUPLICATE MANDATE REQUEST FOR SAME ITEM` | Duplicate mandate request submitted | Avoid duplicate requests or check existing mandates |
| `Mandate Qr tampered` | Mandate QR code has been tampered with | Generate a new mandate with fresh QR code |
| `U29\|ADDRESS RESOLUTION IS FAILED\|QB\|MANDATE IS ALREADY HONOURED` | Duplicate transaction attempt | Ensure transaction isn't a duplicate of a previously successful one |
| `Invalid frequency` | Invalid frequency specified for LOAN category | Use appropriate frequency as per NPCI guidelines |

### Fraud and security

The following are the fraud and security-related error codes:

| Error | Description | Resolution |
| - | - | - |
| `DEBIT HAS BEEN FAILED \| SUSPECTED FRAUD` | Transaction flagged as suspected fraud | Customer should contact their bank for clearance |
| `U30\|DEBIT HAS BEEN FAILED\|K1\|SUSPECTED FRAUD, DECLINE / TRANSACTIONS DECLINED BASED ON RISK SCORE BY REMITTER` | Risk-based decline by remitter bank | Customer may retry or contact bank |
| `ADDRESS RESOLUTION IS FAILED \| TRANSACTION CANNOT BE COMPLETED. COMPLIANCE VIOLATION (REMITTER)` | Compliance violation detected | Ensure transaction complies with regulatory requirements |
| `DEBIT HAS BEEN FAILED \| DO NOT HONOUR (REMITTER)` | Debit transaction rejected by issuing bank | Customer should contact their bank |

### Technical issues

The following are the technical error codes:

| Error | Description | Resolution |
| - | - | - |
| `REMITTER BANK NOT AVAILABLE` | Remitter bank system is unavailable | Retry the transaction after some time |
| `DEBIT TIMEOUT \| REMITTER/ISSUER UNAVAILABLE (TIMEOUT)` | Bank system timeout occurred | Retry the transaction when bank systems are stable |
| `U67\|DEBIT TIMEOUT\|UT\|REMITTER/ISSUER UNAVAILABLE (TIMEOUT)` | Timeout from remitter or issuer | Retry during stable network conditions |
| `REMITTER BANK DEEMED HIGH RESPONSE TIME CHECK DECLINE` | Bank system experiencing high traffic or technical issues | Retry during off-peak hours |
| `U90\|REMITTER BANK DEEMED HIGH RESPONSE TIME CHECK DECLINE` | High response time from remitter bank | Retry when bank systems are more responsive |
| `U91\|BENEFICIARY BANK DEEMED HIGH RESPONSE TIME CHECK DECLINE` | Beneficiary bank system issues | Retry when bank systems are stable |
| `No response received from bank within the prescribed API time limit` | Bank API timeout | Retry the transaction |
| `ADD_RESLN_DISPATCH_FAILED` | Address resolution dispatch failure | Contact support for technical assistance |

### Customer action required

The following are the error codes that require customer action:

| Error | Description | Resolution |
| - | - | - |
| `No action performed by customer` | Customer didn't complete the authorisation process | Customer needs to complete the payment flow |
| `COLLECT EXPIRED` | Customer didn't complete auth after entering VPA | Customer should complete the transaction within time limit |
| `RESPMANDATE TIMEOUT AT REMITTER END` | Customer didn't honour the mandate within time | Customer should respond to mandate requests |
| `RESPMANDATE DECLINED BY REMITTER BANK` | Remitter bank declined the mandate | Customer should contact their bank |
| `RESPAUTHMANDATE EXPIRED` | No action performed on collect request and it expired | Customer should complete authorisation within time limit |
| `RESPAUTHMANDATE DECLINED BY PSP` | PSP declined the authorisation mandate | Contact support for assistance |
| `Transaction Open Status` | Customer closed transaction page before completion or retried failed transaction | Complete the transaction without closing the page |
| `No Details available for Requested MandateReqID` | Customer cancelled mandate before reaching NPCI page | Reinitiate the mandate creation process |

### Invalid data and validation

The following are the data validation error codes:

| Error | Description | Resolution |
| - | - | - |
| `U29\|ADDRESS RESOLUTION IS FAILED\|ZH\|INVALID VIRTUAL ADDRESS` | Invalid VPA used in transaction | Use a valid and verified VPA |
| `ADDRESS RESOLUTION IS FAILED \| INVALID VIRTUAL ADDRESS` | Invalid Virtual Address during VPA validation | Verify and use correct VPA |
| `DEBIT HAS BEEN FAILED \| INVALID TRANSACTION OR IF MEMBER IS NOT ABLE TO FIND ANY APPROPRIATE RESPONSE CODE (REMITTER)` | Invalid transaction or unrecognised response | Retry with valid transaction details |
| `U30\|DEBIT HAS BEEN FAILED\|XB\|INVALID TRANSACTION OR IF MEMBER IS NOT ABLE TO FIND ANY APPROPRIATE RESPONSE CODE (REMITTER)` | Invalid transaction from remitter | Verify transaction details and retry |
| `DEBIT HAS BEEN FAILED \| INVALID RESPONSE CODE` | Invalid response received from bank | Retry the transaction |
| `U30\|DEBIT HAS BEEN FAILED\|XD\|INVALID AMOUNT (REMITTER)` | Invalid amount specified | Use valid amount format and value |
| `DEBIT HAS BEEN FAILED \| RegIdDetails must be present` | Required registration details missing | Ensure all required details are provided |
| `U30\|DEBIT HAS BEEN FAILED\|V1\|RegIdDetails must be present` | Registration details missing | Include all required registration information |
| `DEBIT HAS BEEN FAILED \| Id name must be present` | Required ID name field missing | Include the ID name field in the request |

### Know your customer and documentation

The following are the KYC and documentation-related error codes:

| Error | Description | Resolution |
| - | - | - |
| `Aadhaar number does not have mobile number registered with uidai` | Mobile number not linked with Aadhaar | Customer should link mobile number with Aadhaar |
| `Payer Account Validation Failure` | TPV verification failed | Ensure correct account details for TPV verification |

### System and processing status

The following are the system and processing status error codes:

| Error | Description | Resolution |
| - | - | - |
| `Internal Payment Failed` | Internal system error during payment processing | Retry the transaction or contact support |
| `Charge couldn't happen on time` | Previous charge was in progress, preventing next charge | Wait for previous charge to complete |
| `Previous request in progress` | Previous request for same action is still being processed | Wait for previous request to complete before retrying |
| `debit has been failed` | Bank didn't send any failure reason | Check with bank for specific failure details |

### Notification issues

The following are the notification-related error codes:

| Error | Description | Resolution |
| - | - | - |
| `Notification couldn't be sent to the customer` | Pre-debit notification failed to send | Ensure customer contact details are correct |
| `DEBIT HAS BEEN FAILED \| Unable to Notify the Customer` | Pre-debit notification delivery failed | Update customer contact information |

## Error response structure

Subscription API errors follow this structure:

```json theme={"dark"}
{
  "status": "ERROR",
  "subCode": "400",
  "message": "Error description",
  "reason": "Detailed error reason"
}
```

## Best practices for error handling

The following are the recommended practices for handling subscription errors:

**Implement retry logic**:

* For timeout and temporary errors, implement exponential backoff retry logic.
* Start with a 1-second delay, double the delay for each subsequent retry.
* Use a maximum of 3-5 retry attempts.
* Apply different retry strategies for different error types.

**Customer communication**:

* Provide clear, actionable error messages to customers.
* Include specific steps they need to take for resolution.
* Avoid technical jargon in customer-facing messages.

**Mandate management**:

* Monitor mandate status.
* Proactively create new mandates when existing ones are cancelled or expired.
* Implement mandate renewal work flows before expiration.

**Balance monitoring**:

* Advise customers to maintain sufficient balance before scheduled debits.
* Send pre-debit notifications to remind customers.
* Implement balance check APIs where available.

**Error logging and monitoring**:

* Log all errors with timestamps and request details.
* Set up alerts for critical error patterns.
* Analyse error trends to identify systemic issues.

**Graceful degradation**:

* Provide alternative payment methods when subscription payment fails.
* Implement fallback mechanisms for critical payment flows.
* Maintain service availability despite individual payment failures.

**Security considerations**:

* Handle fraud-related errors with additional verification steps.
* Implement risk scoring for suspicious transaction patterns.
* Maintain compliance with regulatory requirements.

<Note>
  For additional API error codes and web hook error structures, refer to the [Payment Errors documentation](/docs/api-reference/payments/errors).
</Note>


# Fetch Details of a Refund
Source: https://www.cashfree.com/docs/api-reference/payments/latest/subscription/fetch-details-of-a-refund

openapi/payments/v2026-01-01.yaml get /subscriptions/{subscription_id}/refunds/{refund_id}
Use this API to fetch details of a refund of a subscription payment.



# Fetch Details of a Single Payment
Source: https://www.cashfree.com/docs/api-reference/payments/latest/subscription/fetch-details-of-a-single-payment

openapi/payments/v2026-01-01.yaml get /subscriptions/{subscription_id}/payments/{payment_id}
Use this API to fetch details of a single payment of a subscription.



# Fetch Details of All Payments of a Subscription
Source: https://www.cashfree.com/docs/api-reference/payments/latest/subscription/fetch-details-of-all-payments-of-a-subscription

openapi/payments/v2026-01-01.yaml get /subscriptions/{subscription_id}/payments
Use this API to fetch all payments of a subscription.



# Fetch Plan
Source: https://www.cashfree.com/docs/api-reference/payments/latest/subscription/fetch-plan

openapi/payments/v2026-01-01.yaml get /plans/{plan_id}
Use this API to fetch plan details.



# Fetch Subscription
Source: https://www.cashfree.com/docs/api-reference/payments/latest/subscription/fetch-subscription

openapi/payments/v2026-01-01.yaml get /subscriptions/{subscription_id}
Use this API to fetch subscription details.



# Generate Transaction Return Summary
Source: https://www.cashfree.com/docs/api-reference/payments/latest/subscription/generate-transaction-return-summary

openapi/payments/v2026-01-01.yaml post /subscriptions/charge/{payment_id}/transaction-return-summary/generate
Use this API to generate transaction return summary for failed transactions (insufficient balance).



# Get All the Payment Method Details Available for Subscription Payments
Source: https://www.cashfree.com/docs/api-reference/payments/latest/subscription/get-all-the-payment-method-details-available-for-subscription-payments

openapi/payments/v2026-01-01.yaml post /subscriptions/eligibility/payment_methods
Use this API to check if a payment method is enabled for your account.



# Manage a Single Payment
Source: https://www.cashfree.com/docs/api-reference/payments/latest/subscription/manage-a-single-payment

openapi/payments/v2026-01-01.yaml post /subscriptions/{subscription_id}/payments/{payment_id}/manage
Use this API to manage a payment of a subscription. A payment can be cancelled or retried with this API.



# Manage Subscription
Source: https://www.cashfree.com/docs/api-reference/payments/latest/subscription/manage-subscription

openapi/payments/v2026-01-01.yaml post /subscriptions/{subscription_id}/manage
Use this API to manage subscriptions. You can cancel, pause, activate, or change the plan associated with a subscription.
To update the recurring amount for a periodic subscription: 1. Create a new plan with the revised amount. 2. Use the Manage Subscription API to associate the subscription with the new plan. 3. Include the `CHANGE_PLAN` action and the new `plan_id` in the request body.

<Note>
  * Customers won't be notified about plan changes. The charge amount can't exceed the maximum amount defined in the original plan.
  * The `CHANGE_PLAN` and `PAUSE` actions aren't supported for On-Demand Subscriptions.
</Note>


# Overview
Source: https://www.cashfree.com/docs/api-reference/payments/latest/subscription/overview

Use the Cashfree Subscriptions APIs to manage recurring payments, mandate authorisation, charge schedules, and payment instruments at scale across India.

The Subscription APIs provide RESTful endpoints for managing recurring payments, customer mandates, and automated billing schedules. These APIs support both sandbox testing and production environments with consistent authentication and error handling across all endpoints. Real-time webhooks ensure seamless integration for subscription lifecycle events, payment notifications, and mandate status updates.

## API endpoints

| Environment | Base URL |
| :- | :- |
| Test | [https://sandbox.cashfree.com/pg](https://sandbox.cashfree.com/pg) |
| Production | [https://api.cashfree.com/pg](https://api.cashfree.com/pg) |
| Latest version | v6, 2026-01-01  <br />The previous versions were 2025-01-01, 2023-08-01, 2021-05-21, 2022-01-01, and 2022-09-01 |

## Authentication

All Subscription APIs require authentication. Refer to the [Authentication](/docs/api-reference/authentication) guide for detailed information on API authentication for merchants and partners.

## Subscription APIs

<Tabs>
  <Tab title="Plans and mandates">
    <div>
      <div>
        <div>
          <h4>Plan management</h4>

          <div>
            <div>
              <a href="/docs/api-reference/payments/latest/subscription/create-a-plan">Create Plan</a>

              <p>
                Define subscription terms including billing frequency, amount, and recurring payment parameters.
              </p>
            </div>
          </div>

          ***

          <div>
            <div>
              <a href="/docs/api-reference/payments/latest/subscription/fetch-plan">Fetch Plan</a>

              <p>
                Retrieve details of an existing subscription plan using plan ID.
              </p>
            </div>
          </div>
        </div>
      </div>

      <div>
        <div>
          <h4>Mandate (Subscription) management</h4>

          <div>
            <div>
              <a href="/docs/api-reference/payments/latest/subscription/create-subscription">Create Subscription</a>

              <p>
                Create a subscription mandate with customer details and payment method authorisation.
              </p>
            </div>
          </div>

          ***

          <div>
            <div>
              <a href="/docs/api-reference/payments/latest/subscription/fetch-subscription">Fetch Subscription</a>

              <p>
                Retrieve subscription details using subscription ID or subscription reference ID.
              </p>
            </div>
          </div>

          ***

          <div>
            <div>
              <a href="/docs/api-reference/payments/latest/subscription/manage-subscription">Manage Subscription</a>

              <p>
                Update subscription status to activate, pause, or cancel a customer mandate.
              </p>
            </div>
          </div>

          ***

          <div>
            <div>
              <a href="/docs/api-reference/payments/latest/subscription/upload-file-for-physical-nach-authorisation">Upload Physical NACH Form</a>

              <p>
                Upload physical NACH registration forms for signature-based mandate creation.
              </p>
            </div>
          </div>

          ***

          <div>
            <div>
              <a href="/docs/api-reference/payments/latest/subscription/get-all-the-payment-method-details-available-for-subscription-payments">Get Payment Methods</a>

              <p>
                Fetch available payment methods and configurations for subscription creation.
              </p>
            </div>
          </div>

          ***

          <div>
            <div>
              <a href="/docs/api-reference/payments/latest/subscription/generate-transaction-return-summary">Generate Transaction Summary</a>

              <p>
                Generate downloadable transaction summary reports for a subscription.
              </p>
            </div>
          </div>
        </div>
      </div>
    </div>
  </Tab>

  <Tab title="Payments and refunds">
    <div>
      <div>
        <div>
          <h4>Payment management</h4>

          <div>
            <div>
              <a href="/docs/api-reference/payments/latest/subscription/raise-a-charge-or-create-an-auth">Raise Payment</a>

              <p>
                Initiate a recurring payment charge against an active subscription mandate.
              </p>
            </div>
          </div>

          ***

          <div>
            <div>
              <a href="/docs/api-reference/payments/latest/subscription/payment/controlled/create-controlled-notification">Create Controlled Notification</a>

              <p>
                Initiate a merchant-controlled payment notification for an on-demand subscription mandate.
              </p>
            </div>
          </div>

          ***

          <div>
            <div>
              <a href="/docs/api-reference/payments/latest/subscription/payment/controlled/fetch-controlled-notification">Fetch Controlled Notification</a>

              <p>
                Retrieve the latest status and identifiers for a controlled payment notification attempt.
              </p>
            </div>
          </div>

          ***

          <div>
            <div>
              <a href="/docs/api-reference/payments/latest/subscription/payment/controlled/fetch-controlled-notifications">Fetch All Controlled Notifications</a>

              <p>
                Retrieve status, timestamps, and identifiers for all controlled payment notification attempts for a subscription payment.
              </p>
            </div>
          </div>

          ***

          <div>
            <div>
              <a href="/docs/api-reference/payments/latest/subscription/payment/controlled/create-controlled-execution">Create Controlled Execution</a>

              <p>
                Trigger a merchant-controlled charge execution after a successful controlled notification.
              </p>
            </div>
          </div>

          ***

          <div>
            <div>
              <a href="/docs/api-reference/payments/latest/subscription/payment/controlled/fetch-controlled-execution">Fetch Controlled Execution</a>

              <p>
                Retrieve execution status, attempt timestamps, and failure details for a controlled charge.
              </p>
            </div>
          </div>

          ***

          <div>
            <div>
              <a href="/docs/api-reference/payments/latest/subscription/payment/controlled/fetch-controlled-executions">Fetch All Controlled Executions</a>

              <p>
                Retrieve status, attempt timestamps, and failure details for all controlled execution attempts for a subscription payment.
              </p>
            </div>
          </div>

          ***

          <div>
            <div>
              <a href="/docs/api-reference/payments/latest/subscription/fetch-details-of-a-single-payment">Fetch Payment</a>

              <p>
                Retrieve details of a specific subscription payment using payment ID.
              </p>
            </div>
          </div>

          ***

          <div>
            <div>
              <a href="/docs/api-reference/payments/latest/subscription/manage-a-single-payment">Manage Payment</a>

              <p>
                Retry failed payments or update payment status for subscription charges.
              </p>
            </div>
          </div>

          ***

          <div>
            <div>
              <a href="/docs/api-reference/payments/latest/subscription/fetch-details-of-all-payments-of-a-subscription">Fetch Payments for Mandate</a>

              <p>
                Retrieve all payment transactions associated with a specific subscription.
              </p>
            </div>
          </div>
        </div>
      </div>

      <div>
        <div>
          <h4>Refund management</h4>

          <div>
            <div>
              <a href="/docs/api-reference/payments/latest/subscription/refund/refund-apis-overview">Refund Overview</a>

              <p>
                Learn about the refund process and workflow for subscription payments.
              </p>
            </div>
          </div>

          ***

          <div>
            <div>
              <a href="/docs/api-reference/payments/latest/subscription/create-a-refund">Create Refund</a>

              <p>
                Initiate full or partial refunds for subscription payments using payment ID.
              </p>
            </div>
          </div>

          ***

          <div>
            <div>
              <a href="/docs/api-reference/payments/latest/subscription/fetch-details-of-a-refund">Fetch Refund</a>

              <p>
                Retrieve refund details and status using refund ID or payment ID.
              </p>
            </div>
          </div>
        </div>
      </div>
    </div>
  </Tab>
</Tabs>

## Supported payment methods

Cashfree Subscriptions supports the following payment methods for recurring payments:

* **Bank account (e-Mandate)**: Net banking, debit card, or Aadhaar-based authorisation with up to ₹1,00,00,000 mandate amount
* **Bank account (Physical mandate)**: Signature-based NACH mandate for accounts without digital access
* **UPI Autopay**: Recurring payments via UPI applications with ₹15,000-₹1,00,000 limits based on authentication
* **Standing Instructions (SI) on cards**: Credit or debit cards (Indian and International) with flexible amount limits

For detailed payment method information, refer to the [Supported Payment Methods](/docs/payments/subscription/payment-modes) guide.

## Getting started

Complete the following steps to set up subscriptions using Cashfree APIs:

1. **Create a Plan** (optional): Define your subscription terms including billing frequency and amount
2. **Create a Subscription**: Set up a mandate with customer details and payment method
3. **Customer Authorisation**: Customer authorises the recurring payment through their chosen method
4. **Raise Payments**: Initiate recurring charges as per the subscription schedule
5. **Manage Subscriptions**: Update subscription status, handle payment retries, and process refunds

For a comprehensive integration guide, visit the [Subscription Introduction](/docs/payments/subscription/introduction) page.

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/payments/subscription/introduction">Subscription Introduction</a></li>
    <li><a href="/docs/payments/subscription/payment-modes">Supported Payment Methods</a></li>
    <li><a href="/docs/payments/subscription/create">Create Subscription Guide</a></li>
    <li><a href="/docs/payments/subscription/faq">Subscription FAQs</a></li>
  </ul>
</div>


# Create Controlled Execution
Source: https://www.cashfree.com/docs/api-reference/payments/latest/subscription/payment/controlled/create-controlled-execution

openapi/payments/v2026-01-01.yaml post /subscriptions/pay/controlled/execute-mandate
Use this API to create a controlled charge execution for an on-demand subscription mandate after a successful notification.

<Warning>This API supports UPI mandates only. eNACH and Physical NACH (PNACH) mandates are not supported. Card support is planned for a future release.</Warning>

<Note>The debit amount cannot change after the pre-debit notification (PDN) is initiated. If the executed debit amount differs from the amount notified in the PDN, the transaction is declined by the issuing bank due to the amount-match logic enforced at the issuing bank.</Note>


# Create Controlled Notification
Source: https://www.cashfree.com/docs/api-reference/payments/latest/subscription/payment/controlled/create-controlled-notification

openapi/payments/v2026-01-01.yaml post /subscriptions/pay/controlled/notify-mandate
Use this API to initiate a controlled payment notification (PDN) for an on-demand subscription mandate.

<Warning>This API supports UPI mandates only. eNACH and Physical NACH (PNACH) mandates are not supported. Card support is planned for a future release.</Warning>


# Fetch Controlled Execution
Source: https://www.cashfree.com/docs/api-reference/payments/latest/subscription/payment/controlled/fetch-controlled-execution

openapi/payments/v2026-01-01.yaml get /subscriptions/payments/{payment_id}/controlled/executions/{execution_id}
Use this API to fetch the details of a controlled execution for a subscription mandate.

<Warning>This API supports UPI mandates only. eNACH and Physical NACH (PNACH) mandates are not supported. Card support is planned for a future release.</Warning>


# Fetch All Controlled Executions
Source: https://www.cashfree.com/docs/api-reference/payments/latest/subscription/payment/controlled/fetch-controlled-executions

openapi/payments/v2026-01-01.yaml get /subscriptions/payments/{payment_id}/controlled/executions
Use this API to fetch all controlled payment executions for a subscription payment.

<Warning>This API supports UPI mandates only. eNACH and Physical NACH (PNACH) mandates are not supported. Card support is planned for a future release.</Warning>


# Fetch Controlled Notification
Source: https://www.cashfree.com/docs/api-reference/payments/latest/subscription/payment/controlled/fetch-controlled-notification

openapi/payments/v2026-01-01.yaml get /subscriptions/payments/{payment_id}/controlled/notifications/{notification_id}
Use this API to fetch the details of a controlled payment notification for a subscription mandate.

<Warning>This API supports UPI mandates only. eNACH and Physical NACH (PNACH) mandates are not supported. Card support is planned for a future release.</Warning>


# Fetch All Controlled Notifications
Source: https://www.cashfree.com/docs/api-reference/payments/latest/subscription/payment/controlled/fetch-controlled-notifications

openapi/payments/v2026-01-01.yaml get /subscriptions/payments/{payment_id}/controlled/notifications
Use this API to fetch all controlled payment notifications for a subscription payment.

<Warning>This API supports UPI mandates only. eNACH and Physical NACH (PNACH) mandates are not supported. Card support is planned for a future release.</Warning>


# Controlled Subscription Payments
Source: https://www.cashfree.com/docs/api-reference/payments/latest/subscription/payment/controlled/overview

Drive pre-debit notification and charge execution yourself with the controlled subscription payment APIs for UPI Autopay and card mandates.

v2026-01-01 introduces a controlled payment flow for UPI Autopay and card mandate subscriptions, giving you explicit control over when to notify your customers and when to execute the debit. This is a significant change if you need to comply with pre-debit notification rules for UPI Autopay and card mandates.

<Note>The controlled flow supports UPI Autopay and card mandates. eNACH and Physical NACH (PNACH) mandates are not supported.</Note>

## How it works

The controlled flow replaces the automatic charge trigger with a two-step process you drive:

1. **Send a pre-debit notification**: Notify your customer of the upcoming charge amount before the debit window opens.
2. **Execute the charge**: Trigger the mandate debit after the compliance window elapses. The debit amount must exactly match the notified amount; a mismatch causes the issuing bank to decline the transaction.

<Warning>
  Controlled charging is a two-step flow in which you send the pre-debit notification and trigger the debit. Cashfree does not automatically retry a failed attempt. You must trigger each attempt yourself.
</Warning>

## API endpoints

The following endpoints support the controlled notification and execution flow:

| API | Method | Description |
| - | - | - |
| [Create Controlled Notification](/docs/api-reference/payments/latest/subscription/payment/controlled/create-controlled-notification) | `POST /subscriptions/pay/controlled/notify-mandate` | Send a pre-debit notification to the customer |
| [Fetch Controlled Notification](/docs/api-reference/payments/latest/subscription/payment/controlled/fetch-controlled-notification) | `GET /subscriptions/payments/{payment_id}/controlled/notifications/{notification_id}` | Retrieve a single notification |
| [Fetch All Controlled Notifications](/docs/api-reference/payments/latest/subscription/payment/controlled/fetch-controlled-notifications) | `GET /subscriptions/payments/{payment_id}/controlled/notifications` | List all notifications for a payment |
| [Create Controlled Execution](/docs/api-reference/payments/latest/subscription/payment/controlled/create-controlled-execution) | `POST /subscriptions/pay/controlled/execute-mandate` | Trigger the mandate debit after the notification window |
| [Fetch Controlled Execution](/docs/api-reference/payments/latest/subscription/payment/controlled/fetch-controlled-execution) | `GET /subscriptions/payments/{payment_id}/controlled/executions/{execution_id}` | Retrieve a single execution |
| [Fetch All Controlled Executions](/docs/api-reference/payments/latest/subscription/payment/controlled/fetch-controlled-executions) | `GET /subscriptions/payments/{payment_id}/controlled/executions` | List all execution attempts for a payment |

For UPI Autopay mandates, NPCI enforces blackout windows during which attempts are rejected. When this happens, the error response tells you the next permitted timestamp. Use this timestamp to schedule your next attempt instead of retrying immediately.

## Webhooks

Subscribe to both events rather than polling:

* `SUBSCRIPTION_PAYMENT_CONTROLLED_NOTIFICATION_STATUS`: A notification attempt reached a terminal state.
* `SUBSCRIPTION_PAYMENT_CONTROLLED_EXECUTION_STATUS`: A charge attempt reached a terminal state.


# Physical Mandates
Source: https://www.cashfree.com/docs/api-reference/payments/latest/subscription/physical-mandates

Use Cashfree Subscriptions Physical Mandate APIs to authorise customers with only signature and bank details, without a debit card or netbanking.

Physical mandate is the process of authorisation where the customer requires only their signature and bank account details. There is no requirement to have a Debit Card or Netbanking enabled to set up the mandate. Read more about [Physical Mandates](/docs/payments/subscription/payment-modes#bank-account-physical-mandate).

List of Physical Mandates APIs

| API name | Description |
| :- | :- |
| [Create Subscription API](/docs/api-reference/payments/latest/subscription/create-subscription) | Use this API to create a subscription by providing a custom payment experience to your customers by specifying the plan ID and the customer details. You can also specify the bank account information when you create the subscription to ensure that mandates are created via the specified bank account only. Make sure to choose the payment mode as PNACH to enable Physical NACH flow. TPV is applicable only for eNACH and UPI. |
| [Create an Auth API](/docs/api-reference/payments/latest/subscription/raise-a-charge-or-create-an-auth) | Use this API to create an authorisation request for your customer. For Physical mandates (PNACH), you must include the payment\_method with "pnach" details in the request payload. Upon creation, the authorisation status will be set to "DOCUMENT\_PENDING". To move the status to "INITIALIZED", use the Upload File API to upload the required documents. |
| [Upload File](/docs/api-reference/payments/latest/subscription/upload-file-for-physical-nach-authorisation) | Use this API to upload the Physical Nach registration forms that contain your customer’s bank account details and signature. Use the paymentId you get in the response in the "Create Auth API" and set action as "SUBMIT\_DOCUMENT". |
| [Simulate Payment api](/docs/api-reference/payments/latest/simulation/simulate-payment) | Use this API to update the authorisation status from INITIALIZED to either SUCCESS or FAILED. You must provide the payment\_id (obtained from the upload file API) along with the desired payment status. This functionality is available only in the test environment. |


# Raise a Charge or Create an Auth
Source: https://www.cashfree.com/docs/api-reference/payments/latest/subscription/raise-a-charge-or-create-an-auth

openapi/payments/v2026-01-01.yaml post /subscriptions/pay
Use this API to create an auth or to raise a charge.

<Warning>In the sandbox environment, authorisation-related responses for eNACH, card, and UPI differ from those in production.</Warning>

<Warning>UPI AutoPay Collect flow for recurring mandates is being deprecated across desktop and Android as per NPCI guidelines. To ensure uninterrupted payment acceptance, merchants are advised to migrate to UPI AutoPay Intent and UPI AutoPay QR flows. For integration changes and more details, refer to the [UPI AutoPay Collect Deprecation](/docs/payments/manage/payment-methods/upi-collect) document.</Warning>

You must generate the URL in production by concatenating it with the payload data in JSON format. The following are example responses for all Seamless Auth modes in the production environment.

<AccordionGroup>
  <Accordion title="Card method">
    ```
    {
      "action": "custom",
      "cf_payment_id": "39394805",
      "channel": "link",
      "data": {
        "url": "https://centinelapi.cardinalcommerce.com/V2/Cruise/StepUp",
        "payload": {
          "JWT": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiI4MjcxZmJlMS1mOTU5LTQwMTgtOTc1OC01MzZkMWRkNzM2NjIiLCJpYXQiOjE3NDc2NDI4NjIsImlzcyI6IjYxNDIwNjg4OTMzODI1Njc1MDg0ZGI2ZiIsImV4cCI6MTc0NzY0NjQ2MiwiT3JnVW5pdElkIjoiNjRkNjA3ZGFmZjUzNDk2MWYxNjk0YWZjIiwiUGF5bG9hZCI6eyJBQ1NVcmwiOiJodHRwczovL3NlY3VyZWljaWNpLWNyMS5pY2ljaWJhbmsuY29tL3YxL2Fjcy9zZXJ2aWNlcy9icm93c2VyL2NyZXEvTC84MTEyLzMzNzAxNTBlLTM0OGEtMTFmMC05NTliLTJiYjZmODk2ZjIzOCIsIlBheWxvYWQiOiJleUp0WlhOellXZGxWSGx3WlNJNklrTlNaWEVpTENKdFpYTnpZV2RsVm1WeWMybHZiaUk2SWpJdU1pNHdJaXdpZEdoeVpXVkVVMU5sY25abGNsUnlZVzV6U1VRaU9pSTRZV1ZtT1RCaU15MW1ZakU0TFRRME5qa3RPREF3TVMwMk1tVm1ZakEwWW1RMk56TWlMQ0poWTNOVWNtRnVjMGxFSWpvaU16TTNNREUxTUdVdE16UTRZUzB4TVdZd0xUazFPV0l0TW1KaU5tWTRPVFptTWpNNElpd2lZMmhoYkd4bGJtZGxWMmx1Wkc5M1UybDZaU0k2SWpBeUluMCIsIlRyYW5zYWN0aW9uSWQiOiJUNGVtNEdidnBubGwzQWViakNKMSJ9LCJPYmplY3RpZnlQYXlsb2FkIjp0cnVlLCJSZXR1cm5VcmwiOiJodHRwczovL3d3dy5jYXNoZnJlZS5jb20vc3Vic2NyaXB0aW9uL2NhcmRfcmV0dXJuLzE1MTk5NzA3P3NiY2RhdGE9bHM5SmlOMUl6VUlKaU9pY0diaEpDTGlRMVZLSmlPaUFYZTBKeWUualY5MTNOd2NUTzVFVE54b2pJa2xFYTBWWFlpc25PaXdrVVY5bFRTVkZWRkoxWEhCMVhJUlZWQkp5ZS5CM2txOWhMeXdvY2hlV1U3QV9yT2tmQ2tTVl9TUEw3NzZxcl9mVHY2RG85MmwifQ.BeWYE8vslkOLZVWJd4mJ4MU1eu682fpp2Va7IvzdL9U",
          "MD": "3881717951"
        },
        "content_type": "application/json",
        "method": "post"
      },
      "payment_amount": 1,
      "payment_currency": "INR",
      "payment_id": "test12343234887",
      "payment_method": "card",
      "payment_status": "PENDING",
      "payment_type": "AUTH",
      "subscription_id": "jd-rupay-test106"
    }
    ```
  </Accordion>

  <Accordion title="Enach Seamless Auth">
    ```
    {
      "action": "custom",
      "cf_payment_id": "39394843",
      "channel": "link",
      "data": {
        "url": "https://enach.npci.org.in/onmags/sendRequest",
        "payload": {
          "AuthMode": "NetBanking",
          "BankID": "ICIC",
          "CheckSumVal": "Ril5otPjBl/Y44z3a0HAsSce2NlDqO1iEpP3pIBuKGYJplXVLuIQ1azxNB2aSJkx7...",
          "MandateReqDoc": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><Document xmlns=\"http://npci.org/onmags/schema\">...</Document>"
        },
        "content_type": "application/json",
        "method": "post"
      },
      "payment_amount": 1,
      "payment_currency": "INR",
      "payment_id": "test12343234888",
      "payment_method": "enach",
      "payment_status": "PENDING",
      "payment_type": "AUTH",
      "subscription_id": "jd-enach-test107"
    }
    ```
  </Accordion>

  <Accordion title="UPI Link">
    ```
    {
      "action": "custom",
      "cf_payment_id": "40756575",
      "channel": "link",
      "data": {
        "url": "https://payments.cashfree.com/subscriptions/checkout/timer",
        "payload": {
          "paymentType": "UPI",
          "upiIntentData": {
            "androidAuthAppLinks": {
              "AMAZONPAY": "intent://mandate?pa=branchautopay.cf@icici&pn=Branch&tr=EZM2025060413545205666653&am=10.00&cu=INR&orgid=400011&mc=7322&purpose=14&tn=Cashfree%20Payments&validitystart=04062025&validityend=04062055&amrule=MAX&recur=ASPRESENTED&rev=N&share=Y&block=N&txnType=CREATE&mode=13&fam=10.00#Intent;scheme=upi;package=in.amazon.mShop.android.shopping;end",
              "BHIM": "intent://mandate?pa=branchautopay.cf@icici&pn=Branch&tr=EZM2025060413545205666653&am=10.00&cu=INR&orgid=400011&mc=7322&purpose=14&tn=Cashfree%20Payments&validitystart=04062025&validityend=04062055&amrule=MAX&recur=ASPRESENTED&rev=N&share=Y&block=N&txnType=CREATE&mode=13&fam=10.00#Intent;scheme=upi;package=in.org.npci.upiapp;end",
              "DEFAULT": "upi://mandate?pa=branchautopay.cf@icici&pn=Branch&tr=EZM2025060413545205666653&am=10.00&cu=INR&orgid=400011&mc=7322&purpose=14&tn=Cashfree%20Payments&validitystart=04062025&validityend=04062055&amrule=MAX&recur=ASPRESENTED&rev=N&share=Y&block=N&txnType=CREATE&mode=13&fam=10.00",
              "GPAY": "gpay://upi/mandate?pa=branchautopay.cf@icici&pn=Branch&tr=EZM2025060413545205666653&am=10.00&cu=INR&orgid=400011&mc=7322&purpose=14&tn=Cashfree%20Payments&validitystart=04062025&validityend=04062055&amrule=MAX&recur=ASPRESENTED&rev=N&share=Y&block=N&txnType=CREATE&mode=13&fam=10.00#Intent;scheme=upi;package=com.google.android.apps.nbu.paisa.user;end",
              "PAYTM": "paytmmp://mandate?pa=branchautopay.cf@icici&pn=Branch&tr=EZM2025060413545205666653&am=10.00&cu=INR&orgid=400011&mc=7322&purpose=14&tn=Cashfree%20Payments&validitystart=04062025&validityend=04062055&amrule=MAX&recur=ASPRESENTED&rev=N&share=Y&block=N&txnType=CREATE&mode=13&fam=10.00#Intent;scheme=upi;package=net.one97.paytm;end",
              "PHONEPE": "phonepe://mandate?pa=branchautopay.cf@icici&pn=Branch&tr=EZM2025060413545205666653&am=10.00&cu=INR&orgid=400011&mc=7322&purpose=14&tn=Cashfree%20Payments&validitystart=04062025&validityend=04062055&amrule=MAX&recur=ASPRESENTED&rev=N&share=Y&block=N&txnType=CREATE&mode=13&fam=10.00#Intent;scheme=upi;package=com.phonepe.app;end"
            },
            "iosAuthAppLinks": {
              "BHIM": "bhim://upi://mandate?pa=branchautopay.cf@icici&pn=Branch&tr=EZM2025060413545205666653&am=10.00&cu=INR&orgid=400011&mc=7322&purpose=14&tn=Cashfree%20Payments&validitystart=04062025&validityend=04062055&amrule=MAX&recur=ASPRESENTED&rev=N&share=Y&block=N&txnType=CREATE&mode=13&fam=10.00",
              "GPAY": "tez://upi/mandate?pa=branchautopay.cf@icici&pn=Branch&tr=EZM2025060413545205666653&am=10.00&cu=INR&orgid=400011&mc=7322&purpose=14&tn=Cashfree%20Payments&validitystart=04062025&validityend=04062055&amrule=MAX&recur=ASPRESENTED&rev=N&share=Y&block=N&txnType=CREATE&mode=13&fam=10.00",
              "PAYTM": "paytmmp://mandate?pa=branchautopay.cf@icici&pn=Branch&tr=EZM2025060413545205666653&am=10.00&cu=INR&orgid=400011&mc=7322&purpose=14&tn=Cashfree%20Payments&validitystart=04062025&validityend=04062055&amrule=MAX&recur=ASPRESENTED&rev=N&share=Y&block=N&txnType=CREATE&mode=13&fam=10.00",
              "PHONEPE": "phonepe://mandate?pa=branchautopay.cf@icici&pn=Branch&tr=EZM2025060413545205666653&am=10.00&cu=INR&orgid=400011&mc=7322&purpose=14&tn=Cashfree%20Payments&validitystart=04062025&validityend=04062055&amrule=MAX&recur=ASPRESENTED&rev=N&share=Y&block=N&txnType=CREATE&mode=13&fam=10.00"
            }
          }
        },
        "content_type": "application/json",
        "method": "post"
      },
      "payment_amount": 10,
      "payment_id": "PAY-1749025491584-4289ae9a",
      "payment_method": "upi",
      "payment_status": "PENDING",
      "payment_type": "AUTH",
      "subscription_id": "SUB_TEST_1749025465390"
    }

    ```
  </Accordion>

  <Accordion title="UPI Collect">
    ```
    {
      "action": "custom",
      "cf_payment_id": "40756761",
      "channel": "collect",
      "data": {
        "url": "https://payments.cashfree.com/subscriptions/checkout/timer",
        "payload": {
          "paymentType": "UPI"
        },
        "content_type": "application/json",
        "method": ""
      },
      "payment_amount": 10,
      "payment_id": "PAY-1749025606422-791be52e",
      "payment_method": "upi",
      "payment_status": "PENDING",
      "payment_type": "AUTH",
      "subscription_id": "SUB_TEST_1749025465390"
    }

    ```
  </Accordion>

  <Accordion title="UPI QR code">
    ```
    {
      "action": "custom",
      "cf_payment_id": "40757018",
      "channel": "qrcode",
      "data": {
        "url": "",
        "payload": {
          "paymentType": "UPI",
          "qrData": "upi://mandate?pa=branchautopay.cf@icici&pn=Branch&tr=EZM2025060413592105685824&am=10.00&cu=INR&orgid=400011&mc=7322&purpose=14&tn=Cashfree%20Payments&validitystart=04062025&validityend=04062055&amrule=MAX&recur=ASPRESENTED&rev=N&share=Y&block=N&txnType=CREATE&mode=13&fam=10.00"
        },
        "content_type": "application/json",
        "method": "post"
      },
      "payment_amount": 10,
      "payment_id": "PAY-1749025760541-4c158190",
      "payment_method": "upi",
      "payment_status": "PENDING",
      "payment_type": "AUTH",
      "subscription_id": "SUB_TEST_1749025465390"
    }
    ```
  </Accordion>

  <Accordion title="Physical Nach Auth">
    ```
    {
    	"action": "post",
    	"cf_payment_id": "47720375",
    	"channel": "post",
    	"data": {
    		"url": "https://api.cashfree.com/pg/view/gateway/subscriptions/testkriti12upi12ANUG5689TFVNB357123",
    		"payload": null,
    		"content_type": "",
    		"method": null
    	},
    	"payment_amount": 0,
    	"payment_currency": "INR",
    	"payment_id": "PAY-1749025760541-4c158190",
    	"payment_method": "pnach",
    	"payment_status": "PENDING",
    	"payment_tags": null,
    	"payment_type": "AUTH",
    	"subscription_id": "SUB_TEST_1749025465390"
    }
    ```
  </Accordion>
</AccordionGroup>


# Rate Limits
Source: https://www.cashfree.com/docs/api-reference/payments/latest/subscription/rate-limits

Reference the per-minute rate limits applied to the Cashfree Subscriptions APIs and learn how to handle throttling for create, charge, and management endpoints.

The rate limit value shows the number of API calls that were made in a minute. For example, if the rate limit is 400 - it means you can call a maximum of 400 API calls in a minute.

**Rate Limits in Sandbox & Production:**\
We use rate limiting for all endpoints. Rate limiting is based on your IP and your account Id. By default, the following rate limits are applied per minute.

| API | Rate limit value per minute | Rate limit type |
| :- | :- | :- |
| [Create Plan](/docs/api-reference/payments/latest/subscription/create-a-plan) | 60 | Account |
| [Create Subscription](/docs/api-reference/payments/latest/subscription/create-subscription) | 60 | Account |
| [Create Seamless Subscription](/docs/api-reference/payments/previous/subscriptionsv1/seamless-apis/create-seamless-subscription-with-plan-id) | 60 | Account |
| [Get Subscription Details](/docs/api-reference/payments/latest/subscription/fetch-subscription) | 60 | Account |
| [Get All Subscription Payments](/docs/api-reference/payments/previous/subscriptionsv1/subscription/fetch-subscription-payments) | 60 | Account |
| [Get Single Subscription Payment](/docs/api-reference/payments/previous/subscriptionsv1/subscription/fetch-single-subscription-payment) | 60 | Account |
| [Cancel Charge](/docs/api-reference/payments/previous/subscriptionsv1/subscription/cancel-subscription) | 60 | Account |
| [Charge Subscription](/docs/api-reference/payments/previous/subscriptionsv1/subscription/charge-subscription) | 60 | Account |
| [Charge Retry](/docs/api-reference/payments/previous/subscriptionsv1/subscription/retry-subscription-charge) | 60 | Account |
| [Activate Subscription](/docs/api-reference/payments/previous/subscriptionsv1/subscription/activate-subscription) | 60 | Account |
| [Get Payment Details using Merchant Txn ID](/docs/api-reference/payments/previous/subscriptionsv1/subscription/fetch-payment-by-merchant-transaction-id) | 60 | Account |
| [Update Recurring-amount](/docs/api-reference/payments/previous/subscriptionsv1/subscription/update-recurring-amount) | 60 | Account |


# Redirection Payload After Authorisation
Source: https://www.cashfree.com/docs/api-reference/payments/latest/subscription/redirection-payload-after-authorization

Understand the POST parameters Cashfree sends to your subscription return URL after the customer authorises a mandate, covering status confirmation and flow finalisation.

## Parameters

The POST request to the return URL includes the following parameters:

| Parameter | Type | Description |
| - | - | - |
| cf\_subReferenceId | Long | Unique numeric ID generated when the subscription was created. |
| cf\_subscriptionId | String | ID of the subscription. |
| cf\_authAmount | Float | The amount charged to authorise the subscription. |
| cf\_referenceId | Long | The reference ID or transaction ID of authorisation in PG. |
| cf\_status | String | Status of the subscription. In the returnUrl, the response should be `ACTIVE` or `BANK_APPROVAL_PENDING` if the authorisation was successful, or `INITIALIZED` if the authorisation failed. |
| cf\_message | String | A brief note about the payment. |
| signature | String | The hash of all parameters in the request generated using Secret Key. |
| cf\_umrn | String | The unique identifier associated with a mandate. Applicable if the payment mode is eMandate. |
| cf\_checkoutStatus | String | The subscription checkout status. The status can be `SUCCESS`, `FAILED`, `SUCCESS_DEBIT_PENDING`, or `SUCCESS_TOKENIZATION_PENDING`. |
| cf\_mode | String | The checkout payment mode. Modes: `NPCI_SBC`, `SBC_UPI`, `SBC_CREDIT_CARD`, `SBC_DEBIT_CARD`. |
| cf\_subscriptionPaymentId | String | The subscription payment ID. |
| cf\_umn | String | The unique identifier associated with a mandate. Applicable if the payment mode is **UPI**. |

## Sample Payload

Once the authorisation is complete, Cashfree will send a POST request to your `return_url` with the following payload:

```json theme={"dark"}
{
  "cf_subReferenceId": 1234567,
  "cf_subscriptionId": "sub_test_123",
  "cf_authAmount": 1.00,
  "cf_referenceId": 987654321,
  "cf_status": "ACTIVE",
  "cf_message": "Subscription authorised successfully",
  "signature": "calculated_signature_here",
  "cf_umrn": "UMRN1234567890",
  "cf_checkoutStatus": "SUCCESS",
  "cf_mode": "SBC_UPI",
  "cf_subscriptionPaymentId": "pay_test_123",
  "cf_umn": "UMN1234567890"
}
```

## Sample Code

Below are examples of how to receive and process the redirection payload in your backend.

<CodeGroup>
  ```javascript Node.js theme={"dark"}
  const express = require('express');
  const app = express();

  // Middleware to parse POST bodies
  app.use(express.urlencoded({ extended: true }));

  app.post('/return-url', (req, res) => {
    const payload = req.body;
    
    console.log('Received Redirection Payload:', payload);

    const status = payload.cf_status;
    if (status === 'ACTIVE' || status === 'BANK_APPROVAL_PENDING') {
      // Handle success
      res.send('Subscription Authorised Successfully');
    } else {
      // Handle failure
      res.send('Authorization Failed');
    }
  });
  ```

  ```python Python theme={"dark"}
  from flask import Flask, request

  app = Flask(__name__)

  @app.route('/return-url', methods=['POST'])
  def return_url():
      # Capture the POST payload
      payload = request.form.to_dict()
      
      print("Received Redirection Payload:", payload)
      
      status = payload.get('cf_status')
      if status in ['ACTIVE', 'BANK_APPROVAL_PENDING']:
          return "Subscription Authorised Successfully", 200
      else:
          return "Authorisation Failed", 400
  ```

  ```java Java theme={"dark"}
  import javax.servlet.http.HttpServletRequest;
  import org.springframework.web.bind.annotation.PostMapping;
  import org.springframework.web.bind.annotation.RestController;
  import java.util.Map;

  @RestController
  public class SubscriptionController {

      @PostMapping("/return-url")
      public String handleRedirection(HttpServletRequest request) {
          // Collect parameters from the POST request
          Map<String, String[]> parameterMap = request.getParameterMap();
          
          String status = request.getParameter("cf_status");
          
          if ("ACTIVE".equals(status) || "BANK_APPROVAL_PENDING".equals(status)) {
              return "Subscription Authorised Successfully";
          } else {
              return "Authorisation Failed";
          }
      }
  }
  ```

  ```go Go theme={"dark"}
  package main

  import (
  	"fmt"
  	"net/http"
  )

  func returnURLHandler(w http.ResponseWriter, r *http.Request) {
  	if r.Method != http.MethodPost {
  		http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
  		return
  	}

  	// Parse the POST form
  	r.ParseForm()
  	
  	status := r.FormValue("cf_status")
  	fmt.Printf("Subscription Status: %s\n", status)

  	if status == "ACTIVE" || status == "BANK_APPROVAL_PENDING" {
  		fmt.Fprint(w, "Subscription Authorised Successfully")
  	} else {
  		fmt.Fprint(w, "Authorisation Failed")
  	}
  }

  func main() {
  	http.HandleFunc("/return-url", returnURLHandler)
  	http.ListenAndServe(":8080", nil)
  }
  ```

  ```php PHP theme={"dark"}
  <?php
  // Receive the POST data from Cashfree redirection
  $payload = $_POST;

  $status = $payload['cf_status'] ?? '';

  if ($status === 'ACTIVE' || $status === 'BANK_APPROVAL_PENDING') {
      echo "Subscription Authorised Successfully";
  } else {
      echo "Authorisation Failed";
  }
  ?>
  ```
</CodeGroup>

<Warning>
  **Return URL**

  * After the customer completes the checkout on the OTP page, they are redirected to your `return_url`. This redirection is link-based. For example, if you provide a `return_url` in the format `https://b8af79f41056.eu.ngrok.io?order_id={order_id}`, the customer is redirected to `https://b8af79f41056.eu.ngrok.io?order_id=order_271vfuhh1o4h6bQIigqyOx74YiJ1T`.

  * In production, `cf_status` and `cf_message` may not be included in the `return_url` response, even though they are present in the sandbox.\
    The `return_url` is intended only to redirect customers back to your site after payment. It should not be used to retrieve complete subscription details.

  For accurate and complete data, use webhooks.

  * Configure your webhook URL in the Cashfree Dashboard.
  * Enable the relevant events, such as `SUBSCRIPTION_AUTH_STATUS` and `SUBSCRIPTION_PAYMENT_SUCCESS`.

  Always validate the subscription status through webhook notifications for production-grade reliability.
</Warning>


# Refund APIs Overview
Source: https://www.cashfree.com/docs/api-reference/payments/latest/subscription/refund/refund-apis-overview

Browse the Cashfree Subscriptions refund APIs that let you create refunds against subscription charges and fetch the latest refund status from your backend.

# List of Subscription Refund APIs

| API name | Description |
| :- | :- |
| [Create Refund](/docs/api-reference/payments/latest/subscription/create-a-refund) | Use this API to create a refund for the payment of a Subscription. |
| [Get Refund](/docs/api-reference/payments/latest/subscription/fetch-details-of-a-refund) | Use this API to fetch the status of the refund of a Subscription. |


# Postman Collection
Source: https://www.cashfree.com/docs/api-reference/payments/latest/subscription/subscription-postman-collection

Download the Cashfree Subscriptions Postman collection to test mandate creation, charge, refund, and plan APIs against the sandbox before going live.

Get started with Cashfree's subscription APIs by downloading the collection and importing it in Postman.

<a href="https://www.postman.com/cashfreedevelopers/cashfree-apis-v2026-01-01/folder/ekp0m3l/subscriptions?action=share&source=copy-link&creator=43686653&ctx=documentation">Download Cashfree subscription Postman collection</a>

## Error codes and reasons

For comprehensive error codes, failure reasons, and troubleshooting guidance when working with subscription APIs, refer to the [Error codes and reasons](/docs/api-reference/payments/latest/subscription/error-codes) documentation.


# Upload file for Physical Nach Authorisation
Source: https://www.cashfree.com/docs/api-reference/payments/latest/subscription/upload-file-for-physical-nach-authorisation

openapi/payments/v2026-01-01.yaml post /subscriptions/pay/documents/{payment_id}
Use this API to upload file for Physical Nach Authorization.



# Signature Verification
Source: https://www.cashfree.com/docs/api-reference/payments/latest/subscription/webhook-signature

Verify Cashfree Subscriptions webhook signatures to confirm authenticity, prevent spoofing, and validate payload integrity before processing recurring events.

Webhook signature verification validates that webhook notifications are sent by Cashfree and haven't been tampered with during transmission. This cryptographic verification protects your server from accepting malicious or forged webhook requests.

Each webhook request sent by Cashfree includes the following:

| Parameter | Description |
| - | - |
| `x-webhook-signature` | HMAC SHA256 signature generated by Cashfree. |
| `x-webhook-timestamp` | Timestamp of when the webhook was generated. |
| Request body | The actual webhook payload. |

To validate the webhook, verify the signature using your webhook secret key.

## Verification flow

To validate the webhook:

<Steps>
  <Step title="Capture headers and raw payload">
    * Read `x-webhook-signature` from request headers.
    * Read `x-webhook-timestamp` from request headers.
    * Capture the raw request body.

    <Warning>
      Don't modify, parse, or reformat the request body before verification.
    </Warning>
  </Step>

  <Step title="Create signature data">
    Concatenate the timestamp and raw request body:

    ```text theme={"dark"}
    signatureData = timestamp + rawBody
    ```
  </Step>

  <Step title="Generate HMAC SHA256 signature">
    * Use your secret key.
    * Apply HMAC SHA256 hashing on `signatureData`.

    <Warning>
      Please note that the Partner API key should be used for partner level webhooks.
    </Warning>
  </Step>

  <Step title="Encode signature">
    Encode the hash as a Base64 string.
  </Step>

  <Step title="Compare signatures">
    Compare the computed signature with the received signature:

    ```text theme={"dark"}
    computed_signature == x-webhook-signature
    ```

    * If matched: Webhook is valid.
    * If not matched: Reject the request.
  </Step>
</Steps>

## Sample implementations

Select your language or framework to view a sample implementation.

<Accordion title="Node.js (Express)">
  ```javascript Node.js theme={"dark"}
  const express = require("express");
  const crypto = require("crypto");

  const app = express();

  // Capture raw body
  app.use(express.json({
    verify: (req, res, buf) => {
      req.rawBody = buf.toString();
    }
  }));

  function verifyWebhook(req) {
    const signature = req.headers["x-webhook-signature"];
    const timestamp = req.headers["x-webhook-timestamp"];
    const rawBody = req.rawBody;

    const secretKey = process.env.CASHFREE_WEBHOOK_SECRET;

    const computedSignature = crypto
      .createHmac("sha256", secretKey)
      .update(timestamp + rawBody)
      .digest("base64");

    return computedSignature === signature;
  }

  app.post("/webhook", (req, res) => {
    if (!verifyWebhook(req)) {
      return res.status(400).send("Invalid signature");
    }

    res.send("Webhook received");
  });
  ```
</Accordion>

<Accordion title="Python (Flask)">
  ```python Python theme={"dark"}
  import hmac
  import hashlib
  import base64
  from flask import request

  def verify_webhook(secret_key):
      webhook_signature = request.headers.get("x-webhook-signature")
      timestamp = request.headers.get("x-webhook-timestamp")

      raw_body = request.get_data(as_text=True)

      signature_data = timestamp + raw_body

      dig = hmac.new(
          secret_key.encode('utf-8'),
          msg=signature_data.encode('utf-8'),
          digestmod=hashlib.sha256
      ).digest()

      computed_signature = base64.b64encode(dig).decode()

      return computed_signature == webhook_signature
  ```
</Accordion>

<Accordion title="Go">
  ```go Go theme={"dark"}
  import (
  	"crypto/hmac"
  	"crypto/sha256"
  	"encoding/base64"
  	"io/ioutil"
  	"net/http"
  )

  func verifyWebhook(r *http.Request, secretKey string) bool {
  	signature := r.Header.Get("x-webhook-signature")
  	timestamp := r.Header.Get("x-webhook-timestamp")

  	bodyBytes, _ := ioutil.ReadAll(r.Body)
  	rawBody := string(bodyBytes)

  	h := hmac.New(sha256.New, []byte(secretKey))
  	h.Write([]byte(timestamp + rawBody))
  	computed := base64.StdEncoding.EncodeToString(h.Sum(nil))

  	return computed == signature
  }
  ```
</Accordion>

<Accordion title="PHP">
  ```php PHP theme={"dark"}
  <?php

  function verifyWebhook($secretKey) {
      $rawBody = file_get_contents("php://input");
      $timestamp = $_SERVER['HTTP_X_WEBHOOK_TIMESTAMP'];
      $signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'];

      $computed = base64_encode(
          hash_hmac('sha256', $timestamp . $rawBody, $secretKey, true)
      );

      return $computed === $signature;
  }
  ?>
  ```
</Accordion>

<Accordion title="Java">
  ```java Java theme={"dark"}
  import javax.crypto.Mac;
  import javax.crypto.spec.SecretKeySpec;
  import java.util.Base64;

  public class WebhookValidator {

      public static boolean verify(String rawBody, String timestamp, String signature, String secretKey) {
          try {
              String data = timestamp + rawBody;

              Mac mac = Mac.getInstance("HmacSHA256");
              mac.init(new SecretKeySpec(secretKey.getBytes(), "HmacSHA256"));

              byte[] hash = mac.doFinal(data.getBytes());
              String computed = Base64.getEncoder().encodeToString(hash);

              return computed.equals(signature);

          } catch (Exception e) {
              return false;
          }
      }
  }
  ```
</Accordion>

<Accordion title="C# (.NET)">
  ```csharp C# theme={"dark"}
  using System;
  using System.Security.Cryptography;
  using System.Text;

  public class WebhookValidator
  {
      public static bool Verify(string rawBody, string timestamp, string signature, string secretKey)
      {
          var data = timestamp + rawBody;

          using (var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secretKey)))
          {
              var hash = hmac.ComputeHash(Encoding.UTF8.GetBytes(data));
              var computed = Convert.ToBase64String(hash);

              return computed == signature;
          }
      }
  }
  ```
</Accordion>

## Security requirements

Keep the following requirements in mind when implementing webhook signature verification.

* Always use the raw request body for signature computation.
* Don't modify, parse, or reformat the payload before verification.
* Store your webhook secret key securely. Use environment variables.
* Reject webhook requests if signature mismatch occurs or required headers are missing.

## Best practices

Use these practices to improve the security and reliability of your webhook implementation.

* Validate timestamp to prevent replay attacks (recommended window: 5 minutes).
* Log invalid webhook attempts for debugging and monitoring.
* Process webhook events only after successful signature verification.

## Summary

The verification process covers the following steps:

1. Capture the `x-webhook-signature` and `x-webhook-timestamp` headers along with the raw request body.
2. Concatenate the timestamp and raw body to form the signature data.
3. Generate an HMAC SHA256 hash using your webhook secret key.
4. Encode the hash as a Base64 string.
5. Compare the computed signature with `x-webhook-signature`. If they match, the webhook is valid. If they don't match, reject the request.


# Events
Source: https://www.cashfree.com/docs/api-reference/payments/latest/subscription/webhooks

Subscribe to Cashfree Subscriptions webhooks for mandate authorisation, recurring charges, payment status changes, and subscription lifecycle updates.

Cashfree sends webhook notifications to your server whenever significant events occur during the lifecycle of a subscription, enabling you to track subscription status changes, payment outcomes, authorisation updates, and refund status in real-time without polling the API. By listening to these webhooks, you can automate your business workflows, update your database, and keep your customers informed about their subscription status.

Below are the various events that can be sent to your webhook endpoint. These webhooks will be triggered if you have integrated the Subscription API.

<Note>
  * If the merchant added the webhook under the 2025-01-01 version, they will receive the same version of the webhook for older subscriptions as well.
  * While filling the UPI payment methods, `upi_instrument` and `upi_instrument_number` will remain empty for webhook versions before 2025. This will be implemented in later versions.
  * While filling the UPI payment methods, `upi_payer_account_number` and `upi_payer_ifsc` will be applicable only for TPV customers who have passed TPV details while creating the subscription.
</Note>

* [`SUBSCRIPTION_STATUS_CHANGED`](/docs/api-reference/payments/latest/subscription/webhooks#subscription_status_changed)
* [`SUBSCRIPTION_AUTH_STATUS`](/docs/api-reference/payments/latest/subscription/webhooks#subscription_auth_status)
* [`SUBSCRIPTION_PAYMENT_NOTIFICATION_INITIATED`](/docs/api-reference/payments/latest/subscription/webhooks#subscription_payment_notification_initiated)
* [`SUBSCRIPTION_PAYMENT_SUCCESS`](/docs/api-reference/payments/latest/subscription/webhooks#subscription_payment_success)
* [`SUBSCRIPTION_PAYMENT_FAILED`](/docs/api-reference/payments/latest/subscription/webhooks#subscription_payment_failed)
* [`SUBSCRIPTION_PAYMENT_CANCELLED`](/docs/api-reference/payments/latest/subscription/webhooks#subscription_payment_cancelled)
* [`SUBSCRIPTION_REFUND_STATUS`](/docs/api-reference/payments/latest/subscription/webhooks#subscription_refund_status)
* [`SUBSCRIPTION_CARD_EXPIRY_REMINDER`](/docs/api-reference/payments/latest/subscription/webhooks#subscription_card_expiry_reminder)
* [`SUBSCRIPTION_CONTROLLED_NOTIFICATION_STATUS`](/docs/api-reference/payments/latest/subscription/webhooks#subscription_controlled_notification_status)
* [`SUBSCRIPTION_CONTROLLED_EXECUTION_STATUS`](/docs/api-reference/payments/latest/subscription/webhooks#subscription_controlled_execution_status)

Payment method object attributes:

<CodeGroup>
  ```javascript UPI theme={"dark"}
  "payment_method": {
        "upi": {
          "channel": "collect",
          "upi_id": "8709228804@ybl",
          "upi_instrument": "",
          "upi_instrument_number": "",
          "upi_payer_account_number": "",
          "upi_payer_ifsc": ""
        }
  },
  "payment_group": "upi"
  ```

  ```javascript ENACH theme={"dark"}
  "payment_method": {
      "enach": {
        "channel": "link",
        "auth_mode": "aadhar",
        "account_type": "",
        "account_number": "",
        "account_ifsc": "",
        "account_holder_name": "",
        "account_bank_code": ""
      }
  },
  "payment_group": "enach"
  ```

  ```javascript PNACH theme={"dark"}
  "payment_method": {
      "pnach": {
        "channel": "link",
        "mandate_creation_date": "",
        "mandate_start_date": "",
        "account_type": "",
        "account_number": "",
        "account_ifsc": "",
        "account_holder_name": "",
        "account_bank_code": ""
      }
  },
  "payment_group": "pnach"
  ```

  ```javascript Debit/Credit card theme={"dark"}
  {
    "payment_method": {
      "card": {
        "channel": null,
        "card_number": "XXXXXXXXXXXX2123",
        "card_network": "visa",
        "card_type": "debit_card",
        "card_sub_type": "R",
        "card_country": "IN",
        "card_bank_name": "KOTAK MAHINDRA BANK",
        "card_network_reference_id": null,
        "instrument_id": "8e9cc167-4fe2-4ece-be8d-c1b224e50a23"
      }
    },
    "payment_group": "debit_card"
  }
  ```
</CodeGroup>

## SUBSCRIPTION\_STATUS\_CHANGED

Whenever a subscription is created it goes to initialised state and customer is expected to authorise it. The list of statuses where this webhook will get triggered are:

* ACTIVE
* ON\_HOLD
* COMPLETED
* CUSTOMER\_CANCELLED
* CUSTOMER\_PAUSED
* EXPIRED
* LINK\_EXPIRED
* BANK\_APPROVAL\_PENDING
* CANCELLED
* CARD\_EXPIRED

<Tabs>
  <Tab title="Version (2025-01-01)">
    ```javascript theme={"dark"}
    {
    "data": {
    "subscription_details": {
      "cf_subscription_id": "23639356",
      "subscription_id": "mozuyYwUCbWEfJVVRLi",
      "subscription_status": "BANK_APPROVAL_PENDING",
      "subscription_expiry_time": "2055-08-07T10:30:46",
      "subscription_first_charge_time": null,
      "subscription_tags": null,
      "next_schedule_date": null
    },
    "customer_details": {
      "customer_name": null,
      "customer_email": "john@dummy.com",
      "customer_phone": "9900000000"
    },
    "plan_details": {
      "plan_id": "mozuyYwUCbWEfJVVRLi",
      "plan_name": "6Msuj2mttuf2F5P1FYVSet",
      "plan_type": "ON_DEMAND",
      "plan_max_cycles": 0,
      "plan_recurring_amount": null,
      "plan_max_amount": 399.00,
      "plan_interval_type": null,
      "plan_intervals": null,
      "plan_currency": "INR",
      "plan_note": null,
      "plan_status": null
    },
    "authorization_details": {
      "authorization_amount": 2.00,
      "authorization_amount_refund": false,
      "approve_by_time": "2025-09-06T10:30:47",
      "authorization_reference": "6ba74ac2b047424da95591xxxxx[at]xxxx",
      "authorization_time": "2025-08-07T10:31:36",
      "authorization_status": "PENDING",
      "payment_id": "49988270",
      "payment_method": {
        "upi": {
          "channel": "link",
          "upi_id": "9910000000@ybl",
          "upi_instrument": "",
          "upi_instrument_number": "",
          "upi_payer_account_number": "",
          "upi_payer_ifsc": ""
        }
      },
      "payment_group": "upi"
    },
    "payment_gateway_details": {
      "gateway_name": "CASHFREE",
      "gateway_subscription_id": "23639356",
      "gateway_plan_id": "mozuyYwUCbWEfJVVRLi",
      "gateway_auth_id": "6ba74ac2b047424da95591xxxxx[at]xxxx"
    }
    },
    "event_time": "2025-08-07T10:31:35+05:30",
    "type": "SUBSCRIPTION_STATUS_CHANGED"
    }
    ```
  </Tab>

  <Tab title="Version (2023-08-01)">
    ```javascript theme={"dark"}
    {
    "data": {
        "subscription_details": {
            "cf_subscription_id": "123456",
            "subscription_id": "Demo_Subscription",
            "subscription_status": "ACTIVE",
            "subscription_expiry_time": "2024-01-14T23:00:08+05:30",
            "subscription_first_charge_time": "2024-01-10T23:00:08+05:30"
        },
        "customer_details": {
            "customer_name": "john",
            "customer_email": "john@dummy.com",
            "customer_phone": "9900000000"
        },
        "plan_details": {
            "plan_id": "plan12345",
            "plan_name": "Plan Name",
            "plan_type": "ON_DEMAND",
            "plan_max_cycles": 10,
            "plan_recurring_amount": 100.00,
            "plan_max_amount": 1000.00,
            "plan_currency": "INR",
            "plan_note": "Note",
            "plan_status": "ACTIVE"
        },
        "authorization_details": {
            "authorizationAmount": 1.00,
            "authorizationAmountRefund": true,
            "approveByTime": "2025-09-06T16:44:48",
            "authorizationReference": "544edde057f34ce588627axxxxx[at]xxxx",
            "authorizationTime": "2025-08-07T16:46:06",
            "authorizationStatus": "PENDING",
            "paymentId": "50088288",
            "paymentMethod": "upi",
            "instrumentId": "xxxxx@xxxx"
        },
        "payment_gateway_details": {
            "gateway_name": "CASHFREE",
            "gateway_subscription_id": "Demo_Subscription",
            "gateway_plan_id": "plan12345",
            "gateway_auth_id": "6595231908096894505959"
        }
    },
    "event_time": "2023-01-03T11:16:10+05:30",
    "type": "SUBSCRIPTION_STATUS_CHANGED"
    }
    ```
  </Tab>
</Tabs>

## SUBSCRIPTION\_AUTH\_STATUS

The event is triggered when the checkout is completed by the customer for success and failed cases.

<Tabs>
  <Tab title="Version (2026-01-01)">
    ```javascript theme={"dark"}
    {
     "data": {
       "payment_id": "ab-SUBV2ODRFhdJuHlcQYyFw-1",
       "cf_payment_id": "49988825",
       "cf_txn_id": "4213159266",
       "cf_order_id": "4519691525",
       "subscription_id": "mozth7smWGCCqPRaSv7",
       "cf_subscription_id": "23639858",
       "payment_type": "AUTH",
       "subscription_details": {
         "cf_subscription_id": "23639858",
         "subscription_id": "mozth7smWGCCqPRaSv7",
         "subscription_status": "ACTIVE",
         "subscription_expiry_time": "2047-07-30T13:24:54",
         "subscription_first_charge_time": null,
         "subscription_tags": {
           "company": "Cashfree",
           "name": "Payment link"
         },
         "next_schedule_date": null
       },
       "authorization_details": {
         "authorization_amount": 2.00,
         "authorization_amount_refund": false,
         "approve_by_time": "",
         "authorization_reference": "cce92d335be0467693c020xxxxx[at]xxxx",
         "authorization_time": "2025-08-07T10:34:23+05:30",
         "authorization_status": "FAILED",
         "payment_id": "ab-SUBV2ODRFhdJuHlcQYyFw-1",
         "payment_method": {
           "upi": {
             "channel": "link",
             "upi_id": "9910000000@ybl",
             "upi_instrument": "",
             "upi_instrument_number": "",
             "upi_payer_account_number": "",
             "upi_payer_ifsc": ""
           }
         },
         "payment_group": "upi"
       },
       "payment_amount": 2.00,
       "payment_currency": "INR",
       "payment_schedule_date": "",
       "payment_initiated_date": "2025-08-07T10:33:56+05:30",
       "payment_remarks": "auth payment",
       "retry_attempts": 0,
       "failure_details": {
         "failure_reason": "DEBIT HAS BEEN FAILED"
       },
       "payment_status": "FAILED",
       "payment_gateway_details": {
         "gateway_name": "CASHFREE",
         "gateway_subscription_id": "23639858",
         "gateway_payment_id": "49988825"
       }
     },
     "event_time": "2025-08-07T10:34:23+05:30",
     "type": "SUBSCRIPTION_AUTH_STATUS"
    }
    ```
  </Tab>

  <Tab title="Version (2025-01-01)">
    ```javascript theme={"dark"}
    {
     "data": {
       "payment_id": "ab-SUBV2ODRFhdJuHlcQYyFw-1",
       "cf_payment_id": "49988825",
       "cf_txn_id": "4213159266",
       "cf_order_id": "4519691525",
       "subscription_id": "mozth7smWGCCqPRaSv7",
       "cf_subscription_id": "23639858",
       "payment_type": "AUTH",
       "authorization_details": {
         "authorization_amount": 2.00,
         "authorization_amount_refund": false,
         "approve_by_time": "",
         "authorization_reference": "cce92d335be0467693c020xxxxx[at]xxxx",
         "authorization_time": "2025-08-07T10:34:23+05:30",
         "authorization_status": "FAILED",
         "payment_id": "ab-SUBV2ODRFhdJuHlcQYyFw-1",
         "payment_method": {
           "upi": {
             "channel": "link",
             "upi_id": "9910000000@ybl",
             "upi_instrument": "",
             "upi_instrument_number": "",
             "upi_payer_account_number": "",
             "upi_payer_ifsc": ""
           }
         },
         "payment_group": "upi"
       },
       "payment_amount": 2.00,
       "payment_currency": "INR",
       "payment_schedule_date": "",
       "payment_initiated_date": "2025-08-07T10:33:56+05:30",
       "payment_remarks": "auth payment",
       "retry_attempts": 0,
       "failure_details": {
         "failure_reason": "DEBIT HAS BEEN FAILED"
       },
       "payment_status": "FAILED",
       "payment_gateway_details": {
         "gateway_name": "CASHFREE",
         "gateway_subscription_id": "23639858",
         "gateway_payment_id": "49988825"
       }
     },
     "event_time": "2025-08-07T10:34:23+05:30",
     "type": "SUBSCRIPTION_AUTH_STATUS"
    }
    ```
  </Tab>

  <Tab title="Version (2023-08-01)">
    ```javascript theme={"dark"}
    {
    "data": {
        "payment_id": "12345",
        "cf_payment_id": "67890",
        "cf_txn_id": "789012",
        "cf_order_id": "98765",
        "subscription_id": "sub12345",
        "cf_subscription_id": "sub67890",
        "payment_type": "DEBIT_CARD",
        "authorization_details": {
            "authorization_amount": 100,
            "authorization_amount_refund": true,
            "approve_by_time": "2024-07-20T16:09:50+05:30",
            "authorization_reference": "6595231908096894505959",
            "authorization_time": "2024-07-20T16:09:51",
            "authorization_status": "ACTIVE",
            "payment_id": "123",
            "payment_method": "DEBIT_CARD",
            "instrument_id": "hsdg9"
        },
        "payment_amount": 200.75,
        "payment_schedule_date": "2024-07-20",
        "payment_initiated_date": "2024-07-20",
        "payment_remarks": "auth payment",
        "retry_attempts": 0,
        "failureDetails": null,
        "payment_status": "SUCCESS",
        "payment_gateway_details": {
            "gateway_name": "CASHFREE",
            "gateway_subscription_id": "Demo_Subscription",
            "gateway_payment_id": "payment12345"
        }
    },
    "event_time": "2024-07-20T11:16:10+05:30",
    "type": "SUBSCRIPTION_AUTH_STATUS"
    }
    ```
  </Tab>
</Tabs>

## SUBSCRIPTION\_PAYMENT\_NOTIFICATION\_INITIATED

This webhook is used to inform the merchant that we have sent a notification of payment to the customer.

<Tabs>
  <Tab title="Version (2026-01-01)">
    ```javascript Version (2026-01-01) theme={"dark"}
    {
    "data": {
    "payment_id": "ab-SUBV2ODR683gV1CXF85ev-1",
    "cf_payment_id": "49970855",
    "cf_txn_id": null,
    "cf_order_id": "",
    "subscription_id": "moziva9hyjiLtCuGN74",
    "cf_subscription_id": "22390006",
    "payment_type": "CHARGE",
    "subscription_details": {
      "cf_subscription_id": "22390006",
      "subscription_id": "moziva9hyjiLtCuGN74",
      "subscription_status": "ACTIVE",
      "subscription_expiry_time": "2047-07-30T13:24:54",
      "subscription_first_charge_time": null,
      "subscription_tags": {
        "company": "Cashfree",
        "name": "Payment link"
      },
      "next_schedule_date": null
    },
    "authorization_details": {
      "authorization_amount": 399.00,
      "authorization_amount_refund": false,
      "approve_by_time": "",
      "authorization_reference": null,
      "authorization_time": "",
      "authorization_status": null,
      "payment_id": "ab-SUBV2ODR683gV1CXF85ev-1",
      "payment_method": null,
      "payment_group": null
    },
    "payment_amount": 399.00,
    "payment_currency": "INR",
    "payment_schedule_date": "2025-08-08T12:00:00+05:30",
    "payment_initiated_date": "2025-08-07T09:08:09+05:30",
    "payment_remarks": null,
    "retry_attempts": 0,
    "failure_details": {
      "failure_reason": null
    },
    "payment_status": "INITIALIZED",
    "payment_gateway_details": {
      "gateway_name": "CASHFREE",
      "gateway_subscription_id": "22390006",
      "gateway_payment_id": "49970855"
    }
    },
    "event_time": "2025-08-07T09:51:07+05:30",
    "type": "SUBSCRIPTION_PAYMENT_NOTIFICATION_INITIATED"
    }
    ```
  </Tab>

  <Tab title="Version (2025-01-01)">
    ```javascript Version (2025-01-01) theme={"dark"}
    {
    "data": {
    "payment_id": "ab-SUBV2ODR683gV1CXF85ev-1",
    "cf_payment_id": "49970855",
    "cf_txn_id": null,
    "cf_order_id": "",
    "subscription_id": "moziva9hyjiLtCuGN74",
    "cf_subscription_id": "22390006",
    "payment_type": "CHARGE",
    "authorization_details": {
      "authorization_amount": 399.00,
      "authorization_amount_refund": false,
      "approve_by_time": "",
      "authorization_reference": null,
      "authorization_time": "",
      "authorization_status": null,
      "payment_id": "ab-SUBV2ODR683gV1CXF85ev-1",
      "payment_method": null,
      "payment_group": null
    },
    "payment_amount": 399.00,
    "payment_currency": "INR",
    "payment_schedule_date": "2025-08-08T12:00:00+05:30",
    "payment_initiated_date": "2025-08-07T09:08:09+05:30",
    "payment_remarks": null,
    "retry_attempts": 0,
    "failure_details": {
      "failure_reason": null
    },
    "payment_status": "INITIALIZED",
    "payment_gateway_details": {
      "gateway_name": "CASHFREE",
      "gateway_subscription_id": "22390006",
      "gateway_payment_id": "49970855"
    }
    },
    "event_time": "2025-08-07T09:51:07+05:30",
    "type": "SUBSCRIPTION_PAYMENT_NOTIFICATION_INITIATED"
    }
    ```
  </Tab>

  <Tab title="Version (2023-08-01)">
    ```javascript theme={"dark"}
    {
    "data": {
        "payment_id": "12345",
        "cf_payment_id": "67890",
        "cf_txn_id": "789012",
        "cf_order_id": "98765",
        "subscription_id": "sub12345",
        "cf_subscription_id": "sub67890",
        "payment_type": "DEBIT_CARD",
        "authorization_details": {
            "authorization_amount": 100,
            "authorization_amount_refund": true,
            "approve_by_time": "2024-07-20T16:09:50+05:30",
            "authorization_reference": "6595231908096894505959",
            "authorization_time": "2024-07-20T16:09:51",
            "authorization_status": "PENDING",
            "payment_id": "123",
            "payment_method": "DEBIT_CARD",
            "instrument_id": "hsdg9"
        },
        "payment_amount": 200,
        "payment_schedule_date": "2024-07-20",
        "payment_initiated_date": "2024-07-20",
        "payment_remarks": "payment",
        "retry_attempts": 0,
        "failureDetails": null,
        "payment_status": "INITIALIZED",
        "payment_gateway_details": {
            "gateway_name": "CASHFREE",
            "gateway_subscription_id": "Demo_Subscription",
            "gateway_payment_id": "payment12345"
        }
    },
    "event_time": "2024-07-20T11:16:10+05:30",
    "type": "SUBSCRIPTION_PAYMENT_NOTIFICATION_INITIATED"
    }
    ```
  </Tab>
</Tabs>

## SUBSCRIPTION\_PAYMENT\_SUCCESS

This notification is sent whenever a successful payment is processed for an active subscription.

<Tabs>
  <Tab title="Version (2026-01-01)">
    ```javascript Version (2026-01-01) theme={"dark"}
    {
    "data": {
    "payment_id": "ab-SUBV2ODRc5Dl2meCr7Iui-1",
    "cf_payment_id": "49914526",
    "cf_txn_id": "4212435861",
    "cf_order_id": "4518936510",
    "subscription_id": "moznV33AssPd6vXsSm2",
    "cf_subscription_id": "23601811",
    "payment_type": "AUTH",
    "subscription_details": {
      "cf_subscription_id": "23601811",
      "subscription_id": "moznV33AssPd6vXsSm2",
      "subscription_status": "ACTIVE",
      "subscription_expiry_time": "2047-07-30T13:24:54",
      "subscription_first_charge_time": null,
      "subscription_tags": {
        "company": "Cashfree",
        "name": "Payment link"
      },
      "next_schedule_date": null
    },
    "authorization_details": {
      "authorization_amount": 2.00,
      "authorization_amount_refund": false,
      "approve_by_time": "",
      "authorization_reference": "427b608f83ad4cbdb6d472xxxxx[at]xxxx",
      "authorization_time": "2025-08-07T05:53:22+05:30",
      "authorization_status": "ACTIVE",
      "payment_id": "ab-SUBV2ODRc5Dl2meCr7Iui-1",
      "payment_method": {
        "upi": {
          "channel": "link",
          "upi_id": "8100000000@ybl",
          "upi_instrument": "",
          "upi_instrument_number": "",
          "upi_payer_account_number": "",
          "upi_payer_ifsc": ""
        }
      },
      "payment_group": "upi"
    },
    "payment_amount": 2.00,
    "payment_currency": "INR",
    "payment_schedule_date": "",
    "payment_initiated_date": "2025-08-07T05:52:21+05:30",
    "payment_remarks": "auth payment",
    "retry_attempts": 0,
    "failure_details": {
      "failure_reason": null
    },
    "payment_status": "SUCCESS",
    "payment_gateway_details": {
      "gateway_name": "CASHFREE",
      "gateway_subscription_id": "23601811",
      "gateway_payment_id": "49914526"
    }
    },
    "event_time": "2025-08-07T05:53:21+05:30",
    "type": "SUBSCRIPTION_PAYMENT_SUCCESS"
    }

    ```
  </Tab>

  <Tab title="Version (2025-01-01)">
    ```javascript Version (2025-01-01) theme={"dark"}
    {
    "data": {
    "payment_id": "ab-SUBV2ODRc5Dl2meCr7Iui-1",
    "cf_payment_id": "49914526",
    "cf_txn_id": "4212435861",
    "cf_order_id": "4518936510",
    "subscription_id": "moznV33AssPd6vXsSm2",
    "cf_subscription_id": "23601811",
    "payment_type": "AUTH",
    "authorization_details": {
      "authorization_amount": 2.00,
      "authorization_amount_refund": false,
      "approve_by_time": "",
      "authorization_reference": "427b608f83ad4cbdb6d472xxxxx[at]xxxx",
      "authorization_time": "2025-08-07T05:53:22+05:30",
      "authorization_status": "ACTIVE",
      "payment_id": "ab-SUBV2ODRc5Dl2meCr7Iui-1",
      "payment_method": {
        "upi": {
          "channel": "link",
          "upi_id": "8100000000@ybl",
          "upi_instrument": "",
          "upi_instrument_number": "",
          "upi_payer_account_number": "",
          "upi_payer_ifsc": ""
        }
      },
      "payment_group": "upi"
    },
    "payment_amount": 2.00,
    "payment_currency": "INR",
    "payment_schedule_date": "",
    "payment_initiated_date": "2025-08-07T05:52:21+05:30",
    "payment_remarks": "auth payment",
    "retry_attempts": 0,
    "failure_details": {
      "failure_reason": null
    },
    "payment_status": "SUCCESS",
    "payment_gateway_details": {
      "gateway_name": "CASHFREE",
      "gateway_subscription_id": "23601811",
      "gateway_payment_id": "49914526"
    }
    },
    "event_time": "2025-08-07T05:53:21+05:30",
    "type": "SUBSCRIPTION_PAYMENT_SUCCESS"
    }

    ```
  </Tab>

  <Tab title="Version (2023-08-01)">
    ```javascript theme={"dark"}
    {
    "data": {
        "payment_id": "12345",
        "cf_payment_id": "67890",
        "cf_txn_id": "789012",
        "cf_order_id": "98765",
        "subscription_id": "sub12345",
        "cf_subscription_id": "sub67890",
        "payment_type": "DEBIT_CARD",
        "authorization_details": {
            "authorization_amount": 100,
            "authorization_amount_refund": true,
            "approve_by_time": "2024-07-20T16:09:50+05:30",
            "authorization_reference": "6595231908096894505959",
            "authorization_time": "2024-07-20T16:09:51",
            "authorization_status": "ACTIVE",
            "payment_id": "123",
            "payment_method": "DEBIT_CARD",
            "instrument_id": "hsdg9"
        },
        "payment_amount": 200,
        "payment_schedule_date": "2024-07-20",
        "payment_initiated_date": "2024-07-20",
        "payment_remarks": "payment",
        "retry_attempts": 0,
        "failureDetails": null,
        "payment_status": "SUCCESS",
        "payment_gateway_details": {
            "gateway_name": "CASHFREE",
            "gateway_subscription_id": "Demo_Subscription",
            "gateway_payment_id": "payment12345"
        }
    },
    "event_time": "2024-07-20T11:16:10+05:30",
    "type": "SUBSCRIPTION_PAYMENT_SUCCESS"
    }
    ```
  </Tab>
</Tabs>

## SUBSCRIPTION\_PAYMENT\_FAILED

This notification is sent whenever payment processing fails for an active subscription.

<Tabs>
  <Tab title="Version (2026-01-01)">
    ```javascript theme={"dark"}
    {
    "data": {
    "payment_id": "ab-SUBV2ODRIeYlFEhMHfS0M-1",
    "cf_payment_id": "49585655",
    "cf_txn_id": "4212555720",
    "cf_order_id": "4519061918",
    "subscription_id": "mozh4iRHSsjre7GkDNz",
    "cf_subscription_id": "22393526",
    "payment_type": "CHARGE",
    "subscription_details": {
      "cf_subscription_id": "22393526",
      "subscription_id": "mozh4iRHSsjre7GkDNz",
      "subscription_status": "ACTIVE",
      "subscription_expiry_time": "2047-07-30T13:24:54",
      "subscription_first_charge_time": null,
      "subscription_tags": {
        "company": "Cashfree",
        "name": "Payment link"
      },
      "next_schedule_date": null
    },
    "authorization_details": {
      "authorization_amount": 399.00,
      "authorization_amount_refund": false,
      "approve_by_time": "",
      "authorization_reference": "a7d6101a7d9340269f070dxxxxx[at]xxxx",
      "authorization_time": "2025-07-25T22:37:53+05:30",
      "authorization_status": "ACTIVE",
      "payment_id": "ab-SUBV2ODRIeYlFEhMHfS0M-1",
      "payment_method": {
        "upi": {
          "channel": "link",
          "upi_id": "9910000000@ybl",
          "upi_instrument": "",
          "upi_instrument_number": "",
          "upi_payer_account_number": "",
          "upi_payer_ifsc": ""
        }
      },
      "payment_group": "upi"
    },
    "payment_amount": 399.00,
    "payment_currency": "INR",
    "payment_schedule_date": "2025-08-07T12:00:00+05:30",
    "payment_initiated_date": "2025-08-06T05:02:41+05:30",
    "payment_remarks": null,
    "retry_attempts": 0,
    "failure_details": {
      "failure_reason": "DEBIT FAILED | Insufficient Funds In Customer (Remitter) Account"
    },
    "payment_status": "FAILED",
    "payment_gateway_details": {
      "gateway_name": "CASHFREE",
      "gateway_subscription_id": "22393526",
      "gateway_payment_id": "49585655"
    }
    },
    "event_time": "2025-08-07T10:24:45+05:30",
    "type": "SUBSCRIPTION_PAYMENT_FAILED"
    }


    ```
  </Tab>

  <Tab title="Version (2025-01-01)">
    ```javascript theme={"dark"}
    {
    "data": {
    "payment_id": "ab-SUBV2ODRIeYlFEhMHfS0M-1",
    "cf_payment_id": "49585655",
    "cf_txn_id": "4212555720",
    "cf_order_id": "4519061918",
    "subscription_id": "mozh4iRHSsjre7GkDNz",
    "cf_subscription_id": "22393526",
    "payment_type": "CHARGE",
    "authorization_details": {
      "authorization_amount": 399.00,
      "authorization_amount_refund": false,
      "approve_by_time": "",
      "authorization_reference": "a7d6101a7d9340269f070dxxxxx[at]xxxx",
      "authorization_time": "2025-07-25T22:37:53+05:30",
      "authorization_status": "ACTIVE",
      "payment_id": "ab-SUBV2ODRIeYlFEhMHfS0M-1",
      "payment_method": {
        "upi": {
          "channel": "link",
          "upi_id": "9910000000@ybl",
          "upi_instrument": "",
          "upi_instrument_number": "",
          "upi_payer_account_number": "",
          "upi_payer_ifsc": ""
        }
      },
      "payment_group": "upi"
    },
    "payment_amount": 399.00,
    "payment_currency": "INR",
    "payment_schedule_date": "2025-08-07T12:00:00+05:30",
    "payment_initiated_date": "2025-08-06T05:02:41+05:30",
    "payment_remarks": null,
    "retry_attempts": 0,
    "failure_details": {
      "failure_reason": "DEBIT FAILED | Insufficient Funds In Customer (Remitter) Account"
    },
    "payment_status": "FAILED",
    "payment_gateway_details": {
      "gateway_name": "CASHFREE",
      "gateway_subscription_id": "22393526",
      "gateway_payment_id": "49585655"
    }
    },
    "event_time": "2025-08-07T10:24:45+05:30",
    "type": "SUBSCRIPTION_PAYMENT_FAILED"
    }


    ```
  </Tab>

  <Tab title="Version (2023-08-01)">
    ```javascript theme={"dark"}
    {
    "data": {
        "payment_id": "12345",
        "cf_payment_id": "67890",
        "cf_txn_id": "789012",
        "cf_order_id": "98765",
        "subscription_id": "sub12345",
        "cf_subscription_id": "sub67890",
        "payment_type": "DEBIT_CARD",
        "authorization_details": {
            "authorization_amount": 100,
            "authorization_amount_refund": true,
            "approve_by_time": "2024-07-18T16:09:50+05:30",
            "authorization_reference": "6595231908096894505959",
            "authorization_time": "2024-07-18T16:09:51",
            "authorization_status": "ACTIVE",
            "payment_id": "123",
            "payment_method": "DEBIT_CARD",
            "instrument_id": "hsdg9"
        },
        "payment_amount": 200,
        "payment_schedule_date": "2024-07-20",
        "payment_initiated_date": "2024-07-20",
        "payment_remarks": "payment",
        "retry_attempts": 0,
        "failureDetails": {
            "failureReason": "Insufficient balance"
        },
        "payment_status": "FAILED",
        "payment_gateway_details": {
            "gateway_name": "CASHFREE",
            "gateway_subscription_id": "Demo_Subscription",
            "gateway_payment_id": "payment12345"
        }
    },
    "event_time": "2024-07-20T11:16:10+05:30",
    "type": "SUBSCRIPTION_PAYMENT_FAILED"
    }
    ```
  </Tab>
</Tabs>

## SUBSCRIPTION\_PAYMENT\_CANCELLED

This notification is sent whenever payment processing is cancelled by user for an active subscription.

<Tabs>
  <Tab title="Version (2026-01-01)">
    ```javascript Version (2026-01-01) theme={"dark"}
    {
    "data": {
    "payment_id": "433563_33_1754492527395",
    "cf_payment_id": "2011332",
    "cf_txn_id": null,
    "cf_order_id": "",
    "subscription_id": "subTestIdOndemand_2025080615020470",
    "cf_subscription_id": "1220385",
    "payment_type": "CHARGE",
    "subscription_details": {
      "cf_subscription_id": "1220385",
      "subscription_id": "subTestIdOndemand_2025080615020470",
      "subscription_status": "ACTIVE",
      "subscription_expiry_time": "2047-07-30T13:24:54",
      "subscription_first_charge_time": null,
      "subscription_tags": {
        "company": "Cashfree",
        "name": "Payment link"
      },
      "next_schedule_date": null
    },
    "authorization_details": {
      "authorization_amount": 1.00,
      "authorization_amount_refund": false,
      "approve_by_time": "",
      "authorization_reference": null,
      "authorization_time": "",
      "authorization_status": null,
      "payment_id": "433563_33_1754492527395",
      "payment_method": null,
      "payment_group": null
    },
    "payment_amount": 1.00,
    "payment_currency": "INR",
    "payment_schedule_date": "2025-08-08T12:00:00+05:30",
    "payment_initiated_date": "2025-08-06T20:32:07+05:30",
    "payment_remarks": null,
    "retry_attempts": 0,
    "failure_details": {
      "failure_reason": null
    },
    "payment_status": "CANCELLED",
    "payment_gateway_details": {
      "gateway_name": "CASHFREE",
      "gateway_subscription_id": "1220385",
      "gateway_payment_id": "2011332"
    }
    },
    "event_time": "2025-08-06T20:32:07+05:30",
    "type": "SUBSCRIPTION_PAYMENT_CANCELLED"
    }
    ```
  </Tab>

  <Tab title="Version (2025-01-01)">
    ```javascript Version (2025-01-01) theme={"dark"}
    {
    "data": {
    "payment_id": "433563_33_1754492527395",
    "cf_payment_id": "2011332",
    "cf_txn_id": null,
    "cf_order_id": "",
    "subscription_id": "subTestIdOndemand_2025080615020470",
    "cf_subscription_id": "1220385",
    "payment_type": "CHARGE",
    "authorization_details": {
      "authorization_amount": 1.00,
      "authorization_amount_refund": false,
      "approve_by_time": "",
      "authorization_reference": null,
      "authorization_time": "",
      "authorization_status": null,
      "payment_id": "433563_33_1754492527395",
      "payment_method": null,
      "payment_group": null
    },
    "payment_amount": 1.00,
    "payment_currency": "INR",
    "payment_schedule_date": "2025-08-08T12:00:00+05:30",
    "payment_initiated_date": "2025-08-06T20:32:07+05:30",
    "payment_remarks": null,
    "retry_attempts": 0,
    "failure_details": {
      "failure_reason": null
    },
    "payment_status": "CANCELLED",
    "payment_gateway_details": {
      "gateway_name": "CASHFREE",
      "gateway_subscription_id": "1220385",
      "gateway_payment_id": "2011332"
    }
    },
    "event_time": "2025-08-06T20:32:07+05:30",
    "type": "SUBSCRIPTION_PAYMENT_CANCELLED"
    }
    ```
  </Tab>

  <Tab title="Version (2023-08-01)">
    ```javascript theme={"dark"}
    {
    "data": {
        "payment_id": "12345",
        "cf_payment_id": "67890",
        "cf_txn_id": "789012",
        "cf_order_id": "98765",
        "subscription_id": "sub12345",
        "cf_subscription_id": "sub67890",
        "payment_type": "DEBIT_CARD",
        "authorization_details": {
            "authorization_amount": 100,
            "authorization_amount_refund": true,
            "approve_by_time": "2024-07-18T16:09:50+05:30",
            "authorization_reference": "6595231908096894505959",
            "authorization_time": "2024-07-18T16:09:51",
            "authorization_status": "ACTIVE",
            "payment_id": "123",
            "payment_method": "DEBIT_CARD",
            "instrument_id": "hsdg9"
        },
        "payment_amount": 200,
        "payment_schedule_date": "2024-07-20",
        "payment_initiated_date": "2024-07-20",
        "payment_remarks": "payment",
        "retry_attempts": 0,
        "failureDetails": {
            "failureReason": "Subscription is not active"
        },
        "payment_status": "CANCELLED",
        "payment_gateway_details": {
            "gateway_name": "CASHFREE",
            "gateway_subscription_id": "Demo_Subscription",
            "gateway_payment_id": "payment12345"
        }
    },
    "event_time": "2024-07-20T11:16:10+05:30",
    "type": "SUBSCRIPTION_PAYMENT_CANCELLED"
    }
    ```
  </Tab>
</Tabs>

## SUBSCRIPTION\_REFUND\_STATUS

This event is triggered whenever a refund status of a transaction will be success, failed, or cancelled.

<Tabs>
  <Tab title="Version (2025-01-01)">
    ```javascript theme={"dark"}
    {
    "data": {
    "payment_id": "yCzJxeT2aXDqI",
    "cf_payment_id": "49778199",
    "refund_id": "WHOqiwy05P1l0",
    "cf_refund_id": "SUB_21ebb4bf-e84f-4afa-bb09-07aac433abe4",
    "refund_amount": 1000.00,
    "refund_speed": "STANDARD",
    "refund_note": "Tesg Refund",
    "refund_status": "SUCCESS",
    "failure_details": "",
    "refund_gateway_details": {
      "gateway_name": "CASHFREE",
      "gateway_payment_id": "49778199",
      "gateway_refund_id": "SUB_21ebb4bf-e84f-4afa-bb09-07aac433abe4"
    }
    },
    "event_time": "2025-08-06T17:20:02+05:30",
    "type": "SUBSCRIPTION_REFUND_STATUS"
    }
    ```
  </Tab>

  <Tab title="Version (2023-08-01)">
    ```javascript theme={"dark"}
    {
    "data": {
        "payment_id": "pay8643",
        "cf_payment_id": "863782648",
        "refund_id": "refund2",
        "cf_refund_id": "ref_212",
        "refund_amount": 100,
        "refund_note": "test",
        "refund_speed": "INSTANT",
        "refund_status": "SUCCESS",
        "failure_details": null,
        "payment_gateway_details": {
            "gateway_name": "CASHFREE",
            "gateway_payment_id": "pay8643",
            "gateway_refund_id": "refund2"
        }
    },
    "event_time": "2023-01-03T11:16:10+05:30",
    "type": "SUBSCRIPTION_REFUND_STATUS"
    }
    ```
  </Tab>
</Tabs>

## SUBSCRIPTION\_CARD\_EXPIRY\_REMINDER

This event is triggered 7 days prior to the card’s expiry date for active card subscriptions.

<Tabs>
  <Tab title="Version (2025-01-01)">
    ```javascript theme={"dark"}
    {
    "data": {
        "subscription_status_webhook": {
            "subscription_details": {
                "cf_subscription_id": "23661347",
                "subscription_id": "SUB_TEST_1754550382119",
                "subscription_status": "ACTIVE",
                "subscription_expiry_time": "2050-12-31T00:00:00",
                "subscription_first_charge_time": "2025-09-30T00:00:00",
                "subscription_tags": {
                    "next_schedule_date": "2025-09-30T00:10:00"
                }
            },
            "customer_details": {
                "customer_name": "John Doe",
                "customer_email": "john@cashfree.com",
                "customer_phone": "9090909090"
            },
            "plan_details": {
                "plan_id": "PLAN_1754550139964",
                "plan_name": "MY_PLAN",
                "plan_type": "PERIODIC",
                "plan_max_cycles": 2,
                "plan_recurring_amount": 5,
                "plan_max_amount": 1000,
                "plan_interval_type": "MONTH",
                "plan_intervals": 1,
                "plan_currency": null,
                "plan_note": null,
                "plan_status": null
            },
            "authorization_details": {
                "authorizationAmount": 1,
                "authorizationAmountRefund": false,
                "approveByTime": "2025-09-06T12:36:22",
                "authorizationReference": null,
                "authorizationTime": "2025-08-07T13:14:18",
                "authorizationStatus": "ACTIVE",
                "paymentId": "160594_178_1754552533131",
                "paymentMethod": "card",
                "instrumentId": null
            },
            "payment_gateway_details": {
                "gateway_name": "CASHFREE",
                "gateway_subscription_id": "23661347",
                "gateway_plan_id": "PLAN_1754550139964",
                "gateway_auth_id": null
            }
        },
        "card_expiry_date": "2025-09-30"
    },
    "event_time": "2025-09-24T02:00:09+05:30",
    "type": "SUBSCRIPTION_CARD_EXPIRY_REMINDER"
    }
    ```
  </Tab>
</Tabs>

<Note>
  The following webhooks are only relevant if you are using Controlled API endpoints for notification and charge.
</Note>

## SUBSCRIPTION\_CONTROLLED\_NOTIFICATION\_STATUS

Cashfree sends this webhook when the status of a merchant-controlled payment notification attempt changes (for example, SUCCESS or FAILED).

<Tabs>
  <Tab title="Version (2025-01-01)">
    ```javascript theme={"dark"}
    {
    "data": {
    "cf_notification_id": "3333",
    "cf_order_id": "123456",
    "cf_payment_id": "123456",
    "cf_subscription_id": "7891011",
    "cf_txn_id": "123456",
    "notification_attempted_time": "2025-06-01T22:14:59+05:30",
    "notification_completed_time": "2025-06-01T22:15:59+05:30",
    "notification_failure_details": {
      "failure_reason": "",
      "failure_error_code": "",
      "failure_sub_error_code": ""
    },
    "notification_id": "notification-001",
    "notification_initiated_time": "2025-06-01T22:14:58+05:30",
    "notification_status": "SUCCESS",
    "payment_amount": 1,
    "payment_id": "test-payment-id",
    "payment_remarks": "monthly charge",
    "payment_status": "INITIALIZED",
    "subscription_id": "test-subscription-id"
    },
    "event_time": "2025-06-01T22:15:59+05:30",
    "type": "SUBSCRIPTION_CONTROLLED_NOTIFICATION_STATUS"
    }
    ```
  </Tab>
</Tabs>

## SUBSCRIPTION\_CONTROLLED\_EXECUTION\_STATUS

Cashfree sends this webhook when the status of a merchant-controlled charge execution attempt changes (for example, SUCCESS or FAILED).

<Tabs>
  <Tab title="Version (2025-01-01)">
    ```javascript theme={"dark"}
    {
    "data": {
    "cf_execution_id": "3333",
    "cf_order_id": "123456",
    "cf_payment_id": "123456",
    "cf_subscription_id": "7891011",
    "cf_txn_id": "123456",
    "execution_attempted_time": "2025-06-01T22:14:59+05:30",
    "execution_completed_time": "2025-06-01T22:15:59+05:30",
    "execution_id": "execution-001",
    "execution_initiated_time": "2025-06-01T22:14:58+05:30",
    "execution_status": "SUCCESS",
    "failure_details": {
      "failure_reason": "",
      "failure_error_code": "",
      "failure_sub_error_code": ""
    },
    "payment_amount": 1,
    "payment_id": "test-payment-id",
    "payment_remarks": "",
    "payment_status": "SUCCESS",
    "subscription_id": "test-subscription-id"
    },
    "event_time": "2025-06-01T22:15:59+05:30",
    "type": "SUBSCRIPTION_CONTROLLED_EXECUTION_STATUS"
    }
    ```
  </Tab>
</Tabs>


# Delete Saved Card Instrument
Source: https://www.cashfree.com/docs/api-reference/payments/latest/token-vault/delete-saved-card-instrument

openapi/payments/v2026-01-01.yaml delete /customers/{customer_id}/instruments/{instrument_id}
Use this API to delete a specific saved card stored for the customer in Cashfree’s [Token Vault](https://www.cashfree.com/docs/payments/features/token-vault).



# Fetch All Saved Card Instrument
Source: https://www.cashfree.com/docs/api-reference/payments/latest/token-vault/fetch-all-saved-card-instrument

openapi/payments/v2026-01-01.yaml get /customers/{customer_id}/instruments?instrument_type=card
Use this API to fetch all saved cards stored for the customer in Cashfree’s [Token Vault](https://www.cashfree.com/docs/payments/features/token-vault).



# Fetch Cryptogram for a Saved Card Instrument
Source: https://www.cashfree.com/docs/api-reference/payments/latest/token-vault/fetch-cryptogram-for-a-saved-card-instrument

openapi/payments/v2026-01-01.yaml get /customers/{customer_id}/instruments/{instrument_id}/cryptogram
Use this API to retrieve the token and cryptogram for a specific saved card stored in Cashfree's [Token Vault](https://www.cashfree.com/docs/payments/features/token-vault). 



# Fetch Specific Saved Card Instrument
Source: https://www.cashfree.com/docs/api-reference/payments/latest/token-vault/fetch-specific-saved-card-instrument

openapi/payments/v2026-01-01.yaml get /customers/{customer_id}/instruments/{instrument_id}
Use this API to fetch a specific saved card stored for the customer in Cashfree’s [Token Vault](https://www.cashfree.com/docs/payments/features/token-vault).



# Card Token Webhook
Source: https://www.cashfree.com/docs/api-reference/payments/latest/token-vault/webhooks

Receive Cashfree Token Vault webhooks for asynchronous updates on saved card instruments including tokenisation success, failure, and expiry events.

| Event | Description |
| - | - |
| INSTRUMENT\_ACTIVE\_WEBHOOK | This webhook is triggered when the card is successfully tokenised. |
| INSTRUMENT\_FAILED\_WEBHOOK | This webhook is triggered when the card tokenisation fails. |

For more information on how to configure webhooks, see [Webhook configuration](/docs/payments/online/webhooks/configure).

## Instrument active webhook

<Tabs>
  <Tab title="Version (2026-01-01)">
    ```javascript Instrument active webhook theme={"dark"}
    {
       "data": {
          "instrument": {
             "customer_id": "siddhesh199721",
             "afa_reference": "887316963",
             "instrument_id": "af250dc5-e5e5-4e7d-a7cf-3f446741fa54",
             "instrument_type": "card",
             "instrument_uid": "680cd7171583f9f64b426983d4501d6941b462932ce5f626be78392d5ec42660",
             "instrument_display": "XXXXXXXXXXXX6854",
             "instrument_status": "ACTIVE",
             "added_at": "2022-04-14T10:42:59+05:30",
             "instrument_meta": {
                "card_network": "visa",
                "card_bank_name": "HDFC BANK",
                "card_country": "IN",
                "card_type": "credit",
                "sub_type": "R",
                "card_token_type": "PG_CASHFREE",
                "card_par": "50012ADWQZJKHCLXLT61QTYD5QNX1",
                "card_token_details": null
             }
          }
       },
       "event_time": "2026-09-07T15:16:48+05:30",
       "type": "INSTRUMENT_ACTIVE_WEBHOOK"
    }
    ```
  </Tab>

  <Tab title="Version (2025-01-01)">
    ```javascript Instrument active webhook theme={"dark"}
    {
       "data": {
          "instrument": {
             "customer_id": "siddhesh199721",
             "afa_reference": "887316963",
             "instrument_id": "af250dc5-e5e5-4e7d-a7cf-3f446741fa54",
             "instrument_type": "card",
             "instrument_uid": "680cd7171583f9f64b426983d4501d6941b462932ce5f626be78392d5ec42660",
             "instrument_display": "XXXXXXXXXXXX6854",
             "instrument_status": "ACTIVE",
             "added_at": "2022-04-14T10:42:59+05:30",
             "instrument_meta": {
                "card_network": "visa",
                "card_bank_name": "HDFC BANK",
                "card_country": "IN",
                "card_type": "credit",
                "sub_type": "R",
                "card_par": "50012ADWQZJKHCLXLT61QTYD5QNX1",
                "card_token_details": null
             }
          }
       },
       "event_time": "2022-04-14T10:44:14+05:30",
       "type": "INSTRUMENT_ACTIVE_WEBHOOK"
    }
    ```
  </Tab>
</Tabs>

## Instrument failed Webhook

<Tabs>
  <Tab title="Version (2026-01-01)">
    ```javascript Instrument failed webhook theme={"dark"}
    {
       "data": {
          "instrument": {
             "customer_id": "siddhesh199721",
             "afa_reference": "887316963",
             "instrument_id": "af250dc5-e5e5-4e7d-a7cf-3f446741fa54",
             "instrument_type": "card",
             "instrument_uid": "680cd7171583f9f64b426983d4501d6941b462932ce5f626be78392d5ec42660",
             "instrument_display": "XXXXXXXXXXXX6854",
             "instrument_status": "FAILED",
             "added_at": "2022-04-14T10:42:59+05:30",
             "instrument_meta": {
                "card_network": "visa",
                "card_bank_name": "HDFC BANK",
                "card_country": "IN",
                "card_type": "credit",
                "sub_type": "R",
                "card_token_type": "PG_CASHFREE",
                "card_par": null,
                "card_token_details": null
             }
          },
          "error_details": {
             "error_code": "NETWORK_ERROR",
             "error_description": "Error while processing the request",
             "error_source": "NETWORK"
          }
       },
       "event_time": "2026-09-29T20:10:51+05:30",
       "type": "INSTRUMENT_FAILED_WEBHOOK"
    }
    ```
  </Tab>

  <Tab title="Version (2025-01-01)">
    ```javascript Instrument failed webhook theme={"dark"}
    {
       "data": {
          "instrument": {
             "customer_id": "siddhesh199721",
             "afa_reference": "887316963",
             "instrument_id": "af250dc5-e5e5-4e7d-a7cf-3f446741fa54",
             "instrument_type": "card",
             "instrument_uid": "680cd7171583f9f64b426983d4501d6941b462932ce5f626be78392d5ec42660",
             "instrument_display": "XXXXXXXXXXXX6854",
             "instrument_status": "FAILED",
             "added_at": "2022-04-14T10:42:59+05:30",
             "instrument_meta": {
                "card_network": "visa",
                "card_bank_name": "HDFC BANK",
                "card_country": "IN",
                "card_type": "credit",
                "sub_type": "R",
                "card_par": null,
                "card_token_details": null
             }
          },
          "error_details": {
             "error_code": "NETWORK_ERROR",
             "error_description": "Error while processing the request",
             "error_source": "NETWORK"
          }
       },
       "event_time": "2022-04-14T10:44:14+05:30",
       "type": "INSTRUMENT_FAILED_WEBHOOK"
    }
    ```
  </Tab>
</Tabs>

<Accordion title="Understanding the payload">
  ## Payload field description

  | Field | Description | Type |
  | - | - | - |
  | customer\_id | For checkout, this is the customer phone number and for seamless this is the customer ID provided by the merchant during the [Create Order API](/docs/api-reference/payments/latest/orders/create-order) call, which is used to save cards for the customer. | `string` |
  | afa\_reference | Represents the `cf_payment_id` of the successful transaction done while saving the instrument. | `string` |
  | instrument\_id | Represents the identifier for the card saved at Cashfree. | `string` |
  | instrument\_type | Specifies the type of instrument. Available options: `card`. | `enum<string>` |
  | instrument\_uid | Represents the unique identifier for the card, used to identify a specific card. | `string` |
  | instrument\_display | Shows the last 4 digits of the actual card number. | `string` |
  | instrument\_status | Shows the status of the saved instrument. It is `ACTIVE` when the card is successfully tokenised, else `FAILED`. Available options: `ACTIVE`, `FAILED`. | `enum<string>` |
  | added\_at | Shows the timestamp at which the instrument was attempted to be saved. | `string` |
  | card\_network | Specifies the card scheme or network. Available options: `visa`, `mastercard`, `rupay`, `amex`, `diners`. | `string` |
  | card\_bank\_name | Shows the issuing bank name of the card. Examples: `HDFC BANK`, `ICICI BANK`, `AXIS BANK`. | `string` |
  | card\_country | Shows the issuing country of the card. Example: `IN`. | `string` |
  | card\_type | Specifies the type of card. Available options: `credit`, `debit`, `prepaid`. | `string` |
  | sub\_type | Specifies the sub-type of card. `R` = Retail, `P` = Premium, `C` = Corporate. Available options: `R`, `P`, `C`. | `string` |
  | card\_par | Represents the [PAR](/docs/payments/features/payment-account-reference) for the plain card. Appears only in instrument active webhook when the card is tokenised successfully. | `string` |
  | card\_token\_details | Always passed as null. | `object` |
  | event\_time | Shows the time at which the webhook is initiated. | `string` |
  | type | Specifies the type of the instrument webhook. Available options: `INSTRUMENT_ACTIVE_WEBHOOK`, `INSTRUMENT_FAILED_WEBHOOK`. | `string` |
</Accordion>


# Get Card BIN Details
Source: https://www.cashfree.com/docs/api-reference/payments/latest/utilities/get-card-bin-details

openapi/payments/v2026-01-01.yaml post /utilities/cardbin
Use this API to get [Card BIN](https://www.cashfree.com/docs/payments/features/utility-apis) (Bank Identification Number) details.



# Get PAR
Source: https://www.cashfree.com/docs/api-reference/payments/latest/utilities/get-par

openapi/payments/v2026-01-01.yaml post /utilities/pars
Use this API to get [Payment Account Reference (PAR)](https://www.cashfree.com/docs/payments/features/payment-account-reference) by providing plain card details.



# Incident Service Webhook
Source: https://www.cashfree.com/docs/api-reference/payments/latest/utilities/incidents/incident-webhook

Subscribe to Cashfree Incident Service webhooks so your checkout learns when payment rails go down, recover, or change scope across banks and networks.

Cashfree will notify you whenever we create an incident at our end. An incident implies that the issuing bank is facing high failure rates or has scheduled a maintenance activity during that time. The former could be due to many reasons and until the failure rates go down, we would recommend customers to use alternative payment instruments.

There are two channels through which we notify. You can subscribe to either of the channels by adding your email address and webhook endpoint in the merchant dashboard.
Email - Cashfree will send an email alert when an issuer is facing downtime or a scheduled incident.
Webhooks - Cashfree will invoke a server to server call whenever an incident is created. You can use this webhook and update your payment page accordingly.

## Webhook schema of incident service webhook

### Sample payload for creation of incident

<Tabs>
  <Tab title="Version (2025-01-01)">
    ```javascript Version (2025-01-01) theme={"dark"}
    {
      "data": {
        "incident": {
          "end_time": "2025-04-29T09:11:48+05:30",
          "id": "x77rkd7phl5dobr94k1s",
          "impact": "HIGH",
          "message": "Payment mode up",
          "start_time": "2025-04-22T09:11:48+05:30",
          "status": "RESOLVED",
          "type": "SCHEDULED"
        },
        "instruments": {
          "upi": {
            "issuers": [
              "DEUTSCHE BANK"
            ]
          }
        }
      },
      "event_time": "2025-04-22T14:42:08+05:30",
      "type": "HEALTH_ALERT"
    }
    ```
  </Tab>

  <Tab title="Version (2023-08-01)">
    ```javascript Version (2023-08-01) theme={"dark"}
    {
      "data": {
        "incident": {
          "end_time": "2025-04-29T09:11:48+05:30",
          "id": "x77rkd7phl5dobr94k1s",
          "impact": "HIGH",
          "message": "Payment mode up",
          "start_time": "2025-04-22T09:11:48+05:30",
          "status": "RESOLVED",
          "type": "SCHEDULED"
        },
        "instruments": {
          "upi": {
            "issuers": [
              "DEUTSCHE BANK"
            ]
          }
        }
      },
      "event_time": "2025-04-22T14:42:08+05:30",
      "type": "HEALTH_ALERT"
    }
    ```
  </Tab>
</Tabs>

### Sample payload when incident is resolved

<Tabs>
  <Tab title="Version (2025-01-01)">
    ```javascript Version (2025-01-01) theme={"dark"}
    {
        "data": {
          "incident": {
            "end_time": "2025-04-29T09:11:48+05:30",
            "id": "x77rkd7phl5dobr94k1s",
            "impact": "HIGH",
            "message": "Payment mode up",
            "start_time": "2025-04-22T09:11:48+05:30",
            "status": "RESOLVED",
            "type": "SCHEDULED"
          },
          "instruments": {
            "upi": {
              "issuers": [
                "DEUTSCHE BANK"
              ]
            }
          }
        },
        "event_time": "2025-04-22T14:42:08+05:30",
        "type": "HEALTH_ALERT"
    }
    ```
  </Tab>

  <Tab title="Version (2023-08-01)">
    ```javascript Version (2023-08-01) theme={"dark"}
    {
        "data": {
          "incident": {
            "end_time": "2025-04-29T09:11:48+05:30",
            "id": "x77rkd7phl5dobr94k1s",
            "impact": "HIGH",
            "message": "Payment mode up",
            "start_time": "2025-04-22T09:11:48+05:30",
            "status": "RESOLVED",
            "type": "SCHEDULED"
          },
          "instruments": {
            "upi": {
              "issuers": [
                "DEUTSCHE BANK"
              ]
            }
          }
        },
        "event_time": "2025-04-22T14:42:08+05:30",
        "type": "HEALTH_ALERT"
    }
    ```
  </Tab>
</Tabs>

### Payload

| Field | Description | Example | Mandatory |
| - | - | - | - |
| end\_time | Null when an incident is created. Or end time when incident is resolved | 2021-04-16T15:10:36+05:30 | No |
| start\_time | Time since we have seen this incident | 2021-04-16T14:10:36+05:30 | Yes |
| id | Incident id | Alphanumeric with \_,- | Yes |
| impact | Impact of the downtime | HIGH, MEDIUM, LOW | Yes |
| message | Human readable message | | No |
| status | Status of the incident. OPEN when created, RESOLVED when resolved, UPDATE when updated with details | OPEN, UPDATE, RESOLVED | Yes |
| type | Is this a scheduled or an unscheduled downtime? | SCHEDULED, UNSCHEDULED | Yes |
| instruments | Refers to the payment mode. This will contain a nested object | | Yes |
| upi.issuers | Issuers which are impacted | Array | No |
| net\_banking.issuers | Net banking banks which are impacted | Array | No |
| wallet.issuers | Wallets which are impacted | Array | No |
| card.type | Card types which are impacted | CREDIT\_CARD, DEBIT\_CARD, ALL | No |
| card.scheme | Card schemes which are impacted | MASTER, VISA, RUPAY, MAESTRO, AMEX, Multiple Schemes | No |
| card.issuers | Banks which are impacted | Array | No |
| event\_time | Time when this webhook was created | | Yes |
| type | Type of webhook | HEALTH\_ALERT | Yes |
| version | Version of webhook. You should build your parsing logic with respect to this version | | Yes |

| Children | Optional | Type | Possible values |
| - | - | - | - |
| wallet | Y\* | Child attributes | Available below |
| net\_banking | Y\* | Child attributes | Available below |
| upi | Y\* | Child attributes | Available below |
| card | Y\* | Child attributes | Available below |

> At least one of the children needs to be present

### Wallet

| Children | Optional | Type | Possible values |
| - | - | - | - |
| issuers | N | Text | See list of wallet issuers below. |

### Net Banking

| Children | Optional | Type | Possible values |
| - | - | - | - |
| issuers | N | Array | See list of issuers below. |

### UPI

| Children | Optional | Type | Possible values |
| - | - | - | - |
| issuers | N | Array | See list of issuers below. |

### Card

| Children | Optional | Type | Possible values |
| - | - | - | - |
| type | N | Text | CREDIT\_CARD, DEBIT\_CARD, ALL |
| scheme | N | Text | MASTER, VISA, RUPAY, MAESTRO, AMEX, Multiple Schemes |
| issuers | N | Array | See list of issuers below. |

### Payload Headers

Cashfree will send two custom headers for every webhook being invoked by our system.

| Name | Description | Example |
| - | - | - |
| x-cashfree-timestamp | Timestamp for this event. Used to generate signature | 1618562436364 |
| x-cashfree-signature | Cashfree signature for this webhook | ke+K3gR8GssH9AMfJm+0+8jGIL1Mq7hOheP9w36/hL0= |

## Signature Generation

The signature must be used to verify if the request has not been tampered with. To verify the signature at your end, you will need your Cashfree Payment Gateway secret key along with the payload.

```
//The payload here refers to the raw request sent by 
Cashfree to your endpoint. No modifications need to be 
done to this payload.

payload := {"data":{"bank_name":"Test Bank",
"card_type":"Visa","health":"DEGRADED",
"incident_end_time":"2021-04-07T00:20:30",
"incident_id":"INCIDENT_HIGH_Test Bank_954b95zz-f11a-test-abcd-0eb0e8608847",
"incident_impact":"High",
"incident_start_time":"2021-04-06T00:20",
"incident_type":"Scheduled",
"is_resolved":false,
"issuers":[],
"message":"We are facing high failure issues in Payment gateway at the moment and will keep you updated about the issue.",
"payment_gateway":null,"payment_mode":"DEBIT_CARD",
"scope":"PaymentMode"},
"type":"HEALTH_ALERT","version":1}

# timestamp is present in the header x-cashfree-timestamp
timestamp := 1617695238078

signedPayload := $timestamp.$payload

expectedSignature := Base64Encode(HMACSHA256($signedPayload, $merchantSecretKey))
```

## Bank Names

* Axis Bank
* Bank of Baroda - Retail Banking
* Bank of India
* Bank of Maharashtra
* Canara Bank
* Catholic Syrian Bank
* Central Bank of India
* City Union Bank
* Deutsche Bank
* DBS Bank Ltd
* DCB Bank - Personal
* Dhanlakshmi Bank
* Federal Bank
* HDFC Bank
* ICICI Bank
* IDBI Bank
* IDFC Bank
* Indian Bank
* Indian Overseas Bank
* IndusInd Bank
* Jammu and Kashmir Bank
* Karnataka Bank Ltd
* Karur Vysya Bank
* Kotak Mahindra Bank
* Laxmi Vilas Bank - Retail Net Banking
* Punjab & Sind Bank
* Punjab National Bank - Retail Net Banking
* RBL Bank
* Saraswat Bank
* South Indian Bank
* Standard Chartered Bank
* State Bank Of India
* Tamilnad Mercantile Bank Ltd
* UCO Bank
* Union Bank of India
* Yes Bank Ltd
* Bank of Baroda - Corporate
* Bank of India - Corporate
* DCB Bank - Corporate
* Lakshmi Vilas Bank - Corporate
* Punjab National Bank - Corporate
* State Bank of India - Corporate
* Union Bank of India - Corporate
* Axis Bank Corporate
* Dhanlaxmi Bank Corporate
* ICICI Corporate Netbanking
* Ratnakar Corporate Banking
* Shamrao Vithal Bank Corporate
* Equitas Small Finance Bank
* Yes Bank Corporate
* Bandhan Bank- Corporate banking
* Barclays Corporate- Corporate Banking - Corporate
* Indian Overseas Bank Corporate
* City Union Bank of Corporate
* HDFC Corporate
* Shivalik Bank
* AU Small Finance
* Bandhan Bank - Retail Net Banking
* Shamrao Vitthal Co-operative Bank
* Tamil Nadu State Co-operative Bank

All Banks (Note: This parameter will be sent when all banks are having a downtime)

## Wallet Names

* FreeCharge
* MobiKwik
* Ola Money
* Reliance Jio Money
* Airtel Money
* Paytm
* Amazon Pay
* PhonePe

## Compute signature and verify

#### Sample code

#### Verify Signature using SDK

<CodeGroup>
  ```javascript Node(express) theme={"dark"}
  var express = require('express')
  import { Cashfree } from "cashfree-pg"; 
  var app = express()

  Cashfree.XClientId = "<x-client-id>";
  Cashfree.XClientSecret = "<x-client-secret>";
  Cashfree.XEnvironment = Cashfree.Environment.SANDBOX;

  app.post('/webhook', function (req, res) {
      try {
          Cashfree.PGVerifyWebhookSignature(req.headers["x-webhook-signature"], req.rawBody, req.headers["x-webhook-timestamp"]))
      } catch (err) {
          console.log(err.message)
      }
  })
  ```

  ```go Go theme={"dark"}
  import (
    cashfree "github.com/cashfree/cashfree-pg/v4"
  )

  // Route
  e.POST("/webhook", _this.Webhook)

  // Controller
  func (_this *WebhookRoute) Webhook(c echo.Context) error {
    	clientId := "<x-client-id>"
  		clientSecret := "<x-client-secret>"
  		cashfree.XClientId = &clientId
  		cashfree.XClientSecret = &clientSecret
  		cashfree.XEnvironment = cashfree.SANDBOX
    
      signature := c.Request().Header.Get("x-webhook-signature")
      timestamp := c.Request().Header.Get("x-webhook-timestamp")
      
      body, _ := ioutil.ReadAll(c.Request().Body)
      rawBody := string(body)
      webhookEvent, err := cashfree.PGVerifyWebhookSignature(signature, rawBody, timestamp)
      if err != nil {
  		fmt.Println(err.Error())
  	} else {
  		fmt.Println(webhookEvent.Object)
  	}
  }
  ```

  ```php PHP theme={"dark"}
  <?php

  $inputJSON = file_get_contents('php://input');

  $expectedSig = getallheaders()['x-webhook-signature'];
  $ts = getallheaders()['x-webhook-timestamp'];

  if(!isset($expectedSig) || !isset($ts)){
      echo "Bad Request";
      die();
  }

  \Cashfree\Cashfree::$XClientId = "<x-client-id>";
  \Cashfree\Cashfree::$XClientSecret = "<x-client-secret>";
  $cashfree = new \Cashfree\Cashfree();

  try {
   $response =  cashfree->PGVerifyWebhookSignature($expectedSig, $inputJSON, $ts);
  } catch(Exception $e) {
    // Error if signature verification fails
  }
  ?>
  ```

  ```python Python theme={"dark"}
  from cashfree_pg.api_client import Cashfree

  @app.route('/webhook', methods = ['POST'])
  def disp():
  		# Get the raw body from the request
      raw_body = request.data
    
      # Decode the raw body bytes into a string
      decoded_body = raw_body.decode('utf-8')

      #verify_signature
      timestamp = request.headers['x-webhook-timestamp']
      signature = request.headers['x-webhook-signature']
  		
  		cashfree = Cashfree()
  		cashfree.XClientId = "<app_id>"
  		cashfree.XClientSecret = "<secret_key>"
  		try:
  			cashfreeWebhookResponse = cashfree.PGVerifyWebhookSignature(signature, decoded_body, timestamp)
  		except:
  			# If Signature mis-match
  ```

  ```java Java theme={"dark"}
  import com.cashfree.*;

  @PostMapping("/my-endpoint")
  public String handlePost(HttpServletRequest request) throws IOException {      
      Cashfree.XClientId = "<x-client-id>";
  		Cashfree.XClientSecret = "<x-client-secret>";
  		Cashfree.XEnvironment = Cashfree.SANDBOX;
    
    	StringBuilder stringBuilder = new StringBuilder();
      BufferedReader bufferedReader = null;

      try {           
        bufferedReader = request.getReader();
        String line;
        while ((line = bufferedReader.readLine()) != null) {
                stringBuilder.append(line).append('\n');
        }
          
          
        String rawBody = stringBuilder.toString();
        String signature = request.getHeader("x-webhook-signature");
        String timestamp = request.getHeader("x-webhook-timestamp");
          
        Cashfree cashfree = new Cashfree();
        PGWebhookEvent webhook = cashfree.PGVerifyWebhookSignature(signature, rawBody, timestamp);
            
      } catch (Exception e) {
              // Error if verification fails
      } finally {
           if (bufferedReader != null) {
              bufferedReader.close();
  		}
  	}
        
  }
  ```

  ```csharp C# theme={"dark"}
  import com.cashfree.*;

  @PostMapping("/my-endpoint")
  public String handlePost(HttpServletRequest request) throws IOException {      
      Cashfree.XClientId = "<x-client-id>";
  		Cashfree.XClientSecret = "<x-client-secret>";
  		Cashfree.XEnvironment = Cashfree.SANDBOX;
    
    	StringBuilder stringBuilder = new StringBuilder();
      BufferedReader bufferedReader = null;

      try {           
        bufferedReader = request.getReader();
        String line;
        while ((line = bufferedReader.readLine()) != null) {
                stringBuilder.append(line).append('\n');
        }
          
          
        String rawBody = stringBuilder.toString();
        String signature = request.getHeader("x-webhook-signature");
        String timestamp = request.getHeader("x-webhook-timestamp");
          
        Cashfree cashfree = new Cashfree();
        PGWebhookEvent webhook = cashfree.PGVerifyWebhookSignature(signature, rawBody, timestamp);
            
      } catch (Exception e) {
              // Error if verification fails
      } finally {
           if (bufferedReader != null) {
              bufferedReader.close();
  		}
  	}
        
  }
  ```
</CodeGroup>

### Compute signature and verify manually

<CodeGroup>
  ```javascript Node(express) theme={"dark"}
  function verify(ts, rawBody){
      const body = req.headers["x-webhook-timestamp"] + req.rawBody;
      const secretKey = "<your secret key>";
      let genSignature = crypto.createHmac('sha256',secretKey).update(body).digest("base64");
      return genSignature
  }
  ```

  ```go Go theme={"dark"}
  func VerifySignature(expectedSig string, ts string, body string) (string, error) {
  	t := time.Now()
  	currentTS := t.Unix()
  	if currentTS-ts > 1000*300 {
  		return "", errors.New("webhook delivered too late")
  	}
  	signStr := strconv.FormatInt(ts, 10) + body
  	fmt.Println("signing String: ", signStr)
  	key := ""
  	h := hmac.New(sha256.New, []byte(key))
  	h.Write([]byte(signStr))
  	b := h.Sum(nil)
  	return base64.StdEncoding.EncodeToString(b), nil
  }

  timestamp := c.Request().Header.Get("x-webhook-timestamp")
  body, _ := ioutil.ReadAll(c.Request().Body)
  rawBody := string(body)
  signature := c.Request().Header.Get("x-webhook-signature")

  VerifySignature(signature, timestamp, rawBody)
  ```

  ```php PHP theme={"dark"}
  function computeSignature($ts, $rawBody){
      $rawBody = file_get_contents('php://input');
  		$ts = getallheaders()['x-webhook-timestamp'];
    
      $signStr = $ts . $rawBody;
      $key = "";
      $computeSig = base64_encode(hash_hmac('sha256', $signStr, $key, true));
      return $computeSig;
  }
  ```

  ```java Java theme={"dark"}
  public String generateSignature() {

  	bufferedReader = request.getReader();
    String line;
    while ((line = bufferedReader.readLine()) != null) {
       stringBuilder.append(line).append('\n');
    }      
    String payload = stringBuilder.toString();
    String timestamp = request.getHeader("x-webhook-timestamp");
        
    String data = timestamp+payload;

    String secretKey = "SECRET-KEY"; // Get secret key from Cashfree Merchant Dashboard;
    Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
    SecretKeySpec secret_key_spec = new SecretKeySpec(secretKey.getBytes(),"HmacSHA256");
    sha256_HMAC.init(secret_key_spec);
    String computed_signature = Base64.getEncoder().encodeToString(sha256_HMAC.doFinal(data.getBytes()));
    return computed_signature; // compare with "x-webhook-signature"
  }
  ```

  ```python Python theme={"dark"}
  import base64
  import hashlib
  import hmac

  def generateSignature():    
      # Get the raw body from the request
      raw_body = request.data
    
      # Decode the raw body bytes into a string
      payload = raw_body.decode('utf-8')

      #verify_signature
      timestamp = request.headers['x-webhook-timestamp']
      
      signatureData = timestamp+payload
      message = bytes(signatureData, 'utf-8')
      secretkey=bytes("Secret_Key",'utf-8') #Get Secret_Key from Cashfree Merchant Dashboard.
      signature = base64.b64encode(hmac.new(secretkey, message, digestmod=hashlib.sha256).digest())
      computed_signature = str(signature, encoding='utf8')
      return computed_signature #compare with "x-webhook-signature"
  ```
</CodeGroup>


# Webhook Configuration
Source: https://www.cashfree.com/docs/api-reference/payments/latest/webhooks/configure

Add, test, and edit Payment Gateway webhook endpoints in the Merchant Dashboard, then review delivery logs and analytics for your integration.

Add and define webhooks for Payment Gateway, Payment Links, Payment Forms, and Subscriptions. Get notified for each action on the URLs you configure.

## Add a webhook endpoint

To add a new webhook:

1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
2. Go to **Payment Gateway** > **Developers** or select **Developers** from the homepage.
3. Select **Add Webhook Endpoint** to create a new webhook. Enter the endpoint URL and select the webhook version from the drop-down menu.
4. Select **Test** to verify if the webhook endpoint returns a response and select **Next**.

<Note>
  In the sandbox environment, both http\:// and https\:// endpoints are supported. In the production environment, only https\:// endpoints are supported.
</Note>

5. Select the events for which you want to configure the webhooks and select **Add Webhook**.

<Accordion title="View available webhook events">
  * Dispute Closed
  * Dispute Created
  * Dispute Updated
  * Failed Payment
  * Incident
  * Instrument Active
  * Instrument Failed
  * Refund
  * Settlement Failed
  * Settlement Initiated
  * Settlement Reversed
  * Success Payment
  * Success Payment TDR (Payment Charges webhook — `PAYMENT_CHARGES_WEBHOOK`)
  * User Dropped Payment
  * Vendor Settlement Failed
  * Vendor Settlement Initiated
  * Vendor Settlement Reversed
  * Vendor Settlement Success
</Accordion>

<Frame>
  <img />
</Frame>

You have successfully created a webhook for the required event. You can view all your webhooks from the **Webhook Endpoints** homepage. Details such as **URL**, **Webhook Version**, **Event**, and **Actions** are available.

## Test a webhook endpoint

You can test the URL at any time using the **Test** option.

1. Select **Test** on the webhook you want to verify.
2. In the **Test Webhook Endpoint** pop-up, select **Test**.
3. Select **Done** after you receive a success response.

<Frame>
  <img />
</Frame>

## Edit a webhook endpoint

To edit a webhook:

1. Select **Edit** on the webhook you want to modify.
2. Select the events you want to add or remove.
3. Select **Save**.

<Frame>
  <img />
</Frame>

## Logs

The **Logs** section displays all webhook logs (successful or failed) on your Merchant Dashboard. You can access the logs directly at [merchant.cashfree.com/merchants/pg/developers/webhooks/logs?env=prod](https://merchant.cashfree.com/merchants/pg/developers/webhooks/logs?env=prod).

<Frame>
  <img />
</Frame>

To view logs:

1. Specify the date range to view logs for a particular period.
2. Use the **Search and Filter** option to view specific logs. Enter the **URL** and select the required webhook type from the drop-down menu.
3. Select a request to view details such as **Message**, **Time**, **Version**, **Header Details**, and **Payload**.
4. To view only **Success** or **Failed** logs, navigate to the respective tabs.

Watch the video below to learn how logs work.

<iframe />

***

## Analytics

The webhook analytics feature provides contextual information on webhook metrics that help you track, monitor, and assess the success or failure of your webhooks. Metrics such as success rate and latency are available.

To view analytics:

1. Specify the date range to view metrics for a particular period.
2. Use the **Search and Filter** option to filter results. Enter the URL and select the required webhook type from the drop-down menu.

<Frame>
  <img />
</Frame>

***

### Success rate

The success rate chart displays the webhook delivery status over time. The chart shows the following metrics:

* **Total Attempts**: The total number of webhook delivery attempts.
* **Successful**: The count of webhooks delivered successfully on the first attempt.
* **Retried Successful**: The count of webhooks that succeeded after retry attempts.
* **Failed**: The count of webhooks that failed to deliver.

Hover over individual bars to view the breakdown for a specific date.

### Latency

Latency is the time taken to respond to webhooks. Hover over individual bars to view the latency for a specific date. The average latency value is also displayed.

## Webhook configuration across accounts

Webhook configurations are managed at the merchant/MID level and are not automatically replicated across different accounts. You must configure the required webhook endpoint directly from the Cashfree Merchant Dashboard for each MID and select the relevant events you wish to receive.

The webhook options in the Partner Dashboard are limited to partner-level events supported by the platform. Payment Link-specific webhook events are not available at the Partner level and can only be configured at the individual merchant account level via the Merchant Dashboard.

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/payments/online/webhooks/security-checklist">Webhook Security Checklist</a></li>
    <li><a href="/docs/payments/online/webhooks/overview">Webhooks Overview</a></li>
    <li><a href="/docs/payments/online/webhooks/signature-verification">Signature Verification</a></li>
  </ul>
</div>


# Webhook Idempotency
Source: https://www.cashfree.com/docs/api-reference/payments/latest/webhooks/idempotency

Handle duplicate Cashfree Payment Gateway webhook deliveries safely: deduplicate by cf_payment_id and treat only SUCCESS as terminal.

When integrating with Cashfree Payment Gateway, it's crucial to implement webhook idempotency to ensure your application processes only final and unique payment events. Below are the core principles and practices to follow.

## Key concepts

The following are the key concepts:

* **Multiple payment attempts per order\_id**: For a single `order_id`, Cashfree allows multiple payment attempts until one succeeds. Each attempt generates a unique `cf_payment_id`.

* **Unique payment\_id per attempt**: Every retry—whether triggered by the user or automatically—will have a distinct `cf_payment_id` but the same `order_id`.

* **Terminal status**: Only consider webhook events where `payment_status = SUCCESS` as the final confirmation of payment for an order.

<Note> Statuses such as `FAILED`, `NOT_ATTEMPTED`, or `PENDING` are transitional and should not be treated as final.</Note>

<Frame>
  <img />
</Frame>

## Best practices

The following are the recommended best practices:

* **De-duplicate using cf\_payment\_id**: Track `cf_payment_id` in your database and process each payment only once, regardless of how many webhook retries you receive.

* **Order-level validation**: Update the order status **only when** you receive a webhook that meets **all** of the following conditions:
  * The `order_id` matches the one you created.
  * The `payment_status` is `SUCCESS`.
  * The order has **not already** been marked as paid.

* **Handle retried payments**: Users may retry failed payments. As a result, you may receive multiple webhook events in the sequence: `FAILED → PENDING → SUCCESS`.\
  Implement logic to update the order status only upon receiving the `SUCCESS` webhook.

* **Ignore duplicate FAILED webhooks**: Webhook events with a `FAILED` status may be sent multiple times. Do not trigger any final actions for these statuses unless you are tracking them for logging or metrics.

* **Store payment attempts**: Keep a log of all `cf_payment_id` for a given `order_id` to support reporting, reconciliation, or dispute management.

* **Use HTTPS endpoints**: Your webhook URL must be publicly reachable from Cashfree. Production endpoints must use HTTPS.

* **Respond immediately**: Your endpoint must return a successful HTTP 200 response immediately after receiving the webhook payload.

* **Verify signatures**: Verify the webhook signature using the `x-webhook-signature` header before processing the payload to authenticate the request. For implementation details, see [Webhook signature verification](/docs/payments/online/webhooks/signature-verification).

<Note>
  Do not mark the order as PAID on receiving `FAILED` or `PENDING` statuses.
  Always wait for a `SUCCESS` webhook before finalising the payment status.
</Note>

## Webhooks as the source of truth

Cashfree webhooks provide server-to-server communication. This means your server receives the payment status even if the customer closes the browser or application before being redirected back to your site. Webhooks are the recommended source of truth for your internal systems. You can monitor webhook delivery and retry history in the **Logs** section. See [Webhook configuration](/docs/payments/online/webhooks/configure).


# Webhook Overview
Source: https://www.cashfree.com/docs/api-reference/payments/latest/webhooks/overview

Understand Cashfree Payment Gateway webhooks: event references, verification, retries, resends, and version migration for your integration.

When building Cashfree integrations, you might want your applications to receive events as they occur in your Cashfree account so that your back-end systems can execute actions accordingly.

To enable real-time event notifications, register your webhook endpoints with Cashfree at **Developers > Webhooks**. These endpoints receive HTTP POST requests containing JSON payloads whenever specific events happen in your Cashfree account. This allows your application to react promptly to changes such as successful payments, failed transactions, or new chargebacks.

<Tip>Install [Cashfree Agent Skills](/docs/tools-ai/cashfree-agent-skills) to bring Cashfree product knowledge into your AI coding assistant (Claude Code, Cursor, VS Code Copilot, Gemini CLI, and more) to answer integration questions and generate accurate code without leaving your editor.</Tip>

<CardGroup>
  <Card title="Payment webhooks" icon="credit-card" href="/docs/api-reference/payments/latest/payments/webhooks">
    Headers and payload samples for payment status notifications.
  </Card>

  <Card title="Refund webhooks" icon="rotate-left" href="/docs/api-reference/payments/latest/refunds/webhooks">
    Payload samples for refund status notifications.
  </Card>

  <Card title="Settlement webhooks" icon="building" href="/docs/api-reference/payments/latest/settlements/settlement-webhooks">
    Settlement status notifications and payout objects.
  </Card>

  <Card title="Subscription webhooks" icon="repeat" href="/docs/api-reference/payments/latest/subscription/webhooks">
    Subscription lifecycle and payment status notifications for recurring billing.
  </Card>

  <Card title="Payment Link webhooks" icon="link" href="/docs/api-reference/payments/latest/payment-links/webhooks">
    Payload samples for payment link status notifications.
  </Card>

  <Card title="Payment Form webhooks" icon="file-lines" href="/docs/payments/no-code/payment-forms/webhooks">
    Payment status notifications for no-code payment forms.
  </Card>

  <Card title="Card token webhooks" icon="layer-group" href="/docs/api-reference/payments/latest/token-vault/webhooks">
    Instrument payloads for saved card token status notifications.
  </Card>

  <Card title="Dispute webhooks" icon="triangle-exclamation" href="/docs/api-reference/payments/latest/disputes/dispute-webhooks">
    Chargeback and dispute status notifications.
  </Card>

  <Card title="SoftPOS webhooks" icon="mobile" href="/docs/api-reference/payments/latest/offline-payments/softpos-webhooks">
    Terminal and SoftPOS transaction status notifications.
  </Card>

  <Card title="Easy Split webhooks" icon="users" href="/docs/api-reference/payments/latest/split/webhooks/overview">
    Vendor settlement and vendor status change notifications for Easy Split.
  </Card>

  <Card title="Global collections partner webhooks" icon="globe" href="/docs/api-reference/payments/latest/international-payments/global-collections/partner/webhooks">
    Partner-facing notifications for international collections transactions.
  </Card>
</CardGroup>

### Verify webhooks

Verify webhooks to prevent tampering and ensure you process only legitimate notifications from Cashfree. Without verification, your application is vulnerable to fraudulent payment confirmations and security threats.

Use [webhook signatures](/docs/payments/online/webhooks/signature-verification) to authenticate Cashfree webhooks, and proceed with further actions only after successful verification.

<Warning>
  Cashfree generates the webhook signature based on the raw payload, not the
  parsed payload. You can refer to how the popular JavaScript framework
  [NestJS](https://docs.nestjs.com/faq/raw-body) provides a hook for accessing
  the raw body.
</Warning>

### Test webhooks

Before going live, test your webhooks in the sandbox environment to verify payloads and integration behaviour. Configure your webhooks from the dashboard in the test environment. Events triggered by test transactions send webhooks to your configured endpoint.

<Info>
  You can create endpoint URLs and test webhooks using tools like
  [webhook.site](https://webhook.site) or create a tunnel to your localhost
  using tools like [ngrok](https://ngrok.com).
</Info>

### Duplicate webhook processing

<Note>
  Cashfree uses **at-least-once** delivery to prevent missed webhook
  notifications.
</Note>

In case of inadvertent downtimes at Cashfree or your end, Cashfree may attempt
duplicate webhook delivery to ensure fulfilment. <br />

<br />

To prevent business processing of duplicate events at your end, you are strongly
recommended to validate `x-idempotency-header` in each webhook header. This hashed
value will always be unique for each unique webhook payload.

<Note>
  This feature is available on webhook versions starting 2025-01-01. To migrate
  to this new version, refer to [Webhook Migration](#webhook-migration) section
  below.
</Note>

### Retry webhooks policy

You can define a custom retry policy for webhooks that do not receive a **200 response**. To configure the retry policy, log in to the **[Merchant Dashboard](https://merchant.cashfree.com/auth/login)** and go to **Payment Gateway > Developers > Webhooks**. Cashfree retries delivery to your URLs based on the defined policy until it receives a **200 response**.

You will see two types of URLs listed -

1. `NOTIFY_URL` - This is the default configuration added to your account and configurations here cannot be edited or deleted. This configuration will apply to only the URLs sent in the notify\_url param of [Create Order API](/docs/api-reference/payments/latest/orders/create-order) within the order\_meta object
2. Your custom configured URLs - You can click on 'Edit' and follow the steps on the screen to define a custom retry policy. A default policy is applied to all URLs

The following webhook policy types are available:

* **Default**: The system retries up to three times at 2, 10, and 30-minute intervals.
* **Fixed**: You can specify the number of retries (maximum of 10) and the interval between retries.
* **Exponential**: You can specify the number of retries (maximum of 10), the interval, and a multiplier. For example, if the number of retries is 5, the interval is 15 minutes, and the multiplier is 2, retries occur at 15, 17, 19, 23, and 31-minute intervals.
* **Custom**: You can specify the number of retries (maximum of 10) and define custom intervals.

### Resend webhooks

<Note>
  This feature is only available for [`payment`
  webhooks](/docs/api-reference/payments/latest/payments/webhooks)
</Note>

There are various reasons why you might need to resend a webhook response to your endpoint, such as service-level downtime or failure to register a webhook payload. With Cashfree, you can resend previously triggered webhooks. Log in to your dashboard and follow the steps below:

1. Go to Webhooks under the Developer section and go to **Logs**.
2. On the top right, click the **Batch Resend** button.

<img />

3. You will see three options here:
   * **Text**: Enter transaction IDs (comma separated) in the text box and click **Resend**. Transaction IDs are the same as Entity IDs listed on the logs dashboard.
   * **File**: Upload the file in the required format (downloadable from the dashboard) with the required Transaction IDs and click **Resend**.
   * **Time Duration**: Select the time period (max. allowed duration is 24 hours) and click **Resend**.

### Webhook signature verification

<Warning>
  Cashfree generates the webhook signature based on the raw payload, not the
  parsed payload. You can refer to how the popular JavaScript framework
  [NestJS](https://docs.nestjs.com/faq/raw-body) provides a hook for accessing
  the raw body.
</Warning>

Use the signature to verify that the request has not been tampered with. To verify the signature, you need your Cashfree PG secret key and the payload.

* The timestamp is present in the header `x-webhook-timestamp`.
* The actual signature is present in the header `x-webhook-signature`.

```bash signature-verification theme={"dark"}
timestamp := 1617695238078;
signedPayload := $timestamp.$payload;
expectedSignature := Base64Encode(HMACSHA256($signedPayload, $merchantSecretKey));
```

### SDK verification (built-in approach)

<CodeGroup>
  ```javascript Node (express) theme={"dark"}
  var express = require('express')
  const { Cashfree, CFEnvironment } = require("cashfree-pg");

  var app = express()

  const cashfree = new Cashfree(
  CFEnvironment.SANDBOX,
  "{Client ID}",
  "{Client Secret Key}"
  );

  app.post('/webhook', function (req, res) {
  try {
  cashfree.PGVerifyWebhookSignature(req.headers["x-webhook-signature"], req.rawBody, req.headers["x-webhook-timestamp"])
  } catch (err) {
  console.log(err.message)
  }
  })

  ```

  ```go golang theme={"dark"}
  import (
    cashfree "github.com/cashfree/cashfree-pg/v4"
  )

  // Route
  e.POST("/webhook", _this.Webhook)

  // Controller
  func (_this *WebhookRoute) Webhook(c echo.Context) error {
    	clientId := "<x-client-id>"
  		clientSecret := "<x-client-secret>"
  		cashfree.XClientId = &clientId
  		cashfree.XClientSecret = &clientSecret
  		cashfree.XEnvironment = cashfree.SANDBOX

      signature := c.Request().Header.Get("x-webhook-signature")
      timestamp := c.Request().Header.Get("x-webhook-timestamp")

      body, _ := ioutil.ReadAll(c.Request().Body)
      rawBody := string(body)
      webhookEvent, err := cashfree.PGVerifyWebhookSignature(signature, rawBody, timestamp)
      if err != nil {
  		fmt.Println(err.Error())
  	} else {
  		fmt.Println(webhookEvent.Object)
  	}
  }
  ```

  ```php PHP theme={"dark"}
  <?php

  $inputJSON = file_get_contents('php://input');

  $expectedSig = getallheaders()['x-webhook-signature'];
  $ts = getallheaders()['x-webhook-timestamp'];

  if(!isset($expectedSig) || !isset($ts)){
      echo "Bad Request";
      die();
  }

  \Cashfree\Cashfree::$XClientId = "<x-client-id>";
  \Cashfree\Cashfree::$XClientSecret = "<x-client-secret>";
  $cashfree = new \Cashfree\Cashfree();

  try {
   $response =  cashfree->PGVerifyWebhookSignature($expectedSig, $inputJSON, $ts);
  } catch(Exception $e) {
    // Error if signature verification fails
  }
  ?>
  ```

  ```python Python theme={"dark"}
  from cashfree_pg.api_client import Cashfree

  @app.route('/webhook', methods = ['POST'])
  def disp():
  		# Get the raw body from the request
      raw_body = request.data

      # Decode the raw body bytes into a string
      decoded_body = raw_body.decode('utf-8')

      #verify_signature
      timestamp = request.headers['x-webhook-timestamp']
      signature = request.headers['x-webhook-signature']

  		cashfree = Cashfree()
  		cashfree.XClientId = "<app_id>"
  		cashfree.XClientSecret = "<secret_key>"
  		try:
  			cashfreeWebhookResponse = cashfree.PGVerifyWebhookSignature(signature, decoded_body, timestamp)
  		except:
  			# If Signature mis-match
  ```

  ```java Java theme={"dark"}
  import com.cashfree.*;

  @PostMapping("/my-endpoint")
  public String handlePost(HttpServletRequest request) throws IOException {
      Cashfree.XClientId = "<x-client-id>";
  		Cashfree.XClientSecret = "<x-client-secret>";
  		Cashfree.XEnvironment = Cashfree.SANDBOX;

    	StringBuilder stringBuilder = new StringBuilder();
      BufferedReader bufferedReader = null;

      try {
        bufferedReader = request.getReader();
        String line;
        while ((line = bufferedReader.readLine()) != null) {
                stringBuilder.append(line).append('\n');
        }


        String rawBody = stringBuilder.toString();
        String signature = request.getHeader("x-webhook-signature");
        String timestamp = request.getHeader("x-webhook-timestamp");

        Cashfree cashfree = new Cashfree();
        PGWebhookEvent webhook = cashfree.PGVerifyWebhookSignature(signature, rawBody, timestamp);

      } catch (Exception e) {
              // Error if verification fails
      } finally {
           if (bufferedReader != null) {
              bufferedReader.close();
  		}
  	}

  }
  ```

  ```csharp csharp theme={"dark"}
  using cashfree_pg.Client;
  using cashfree_pg.Model;


  		[Route("api/[controller]")]
      [ApiController]
      public class YourController : ControllerBase
      {
          [HttpPost]
          public async Task<IActionResult> Post()
          {
              // Read the raw body of the POST request
              using (StreamReader reader = new StreamReader(Request.Body, Encoding.UTF8))
              {
                  string requestBody = await reader.ReadToEndAsync();
                  var headers = Request.Headers;
                  var signature = headers["x-webhook-signature"];
                  var timestamp = headers["x-webhook-timestamp"];

                  Cashfree.XClientId = "<x-client-id>";
                  Cashfree.XClientSecret = "<x-client-secret>";
                  Cashfree.XEnvironment = Cashfree.SANDBOX;
  								var cashfree = new Cashfree();

                  try {
                  var response = cashfree.PGVerifyWebhookSignature(signature, requestBody, timestamp);
                  } catch(Exception e) {
                  // Error if signature mis matches
                  }
              }
          }
      }
  ```
</CodeGroup>

### Manual verification (custom approach)

<CodeGroup>
  ```javascript Node (Express) theme={"dark"}
  function verify(ts, request){
      const body = request.headers['x-webhook-timestamp'] + request.rawBody
      const secretKey = <client secret>;
      let generatedSignature = crypto.createHmac('sha256', secretKey).update(body).digest("base64");
      const signature = request.headers['x-webhook-signature']
      if(generatedSignature === signature) {
          let jsonObject = JSON.parse(rawBody)
          return jsonObject
      }
      throw new Error("Generated signature and received signature did not match.");
  }
  ```

  ```go golang theme={"dark"}
  func VerifySignature(expectedSig string, ts string, body string) (string, error) {
          clientSecret := "<client-secret>"
  	signatureString := ts + rawBody
  	hmacInstance := hmac.New(sha256.New, []byte(*clientSecret))
  	hmacInstance.Write([]byte(signatureString))
  	bytesData := hmacInstance.Sum(nil)
  	generatedSignature := base64.StdEncoding.EncodeToString(bytesData)
  	if generatedSignature == expectedSig {
  		var object interface{}
  		err := json.Unmarshal([]byte(rawBody), &object)
  		if err != nil {
  			return nil, errors.New("something went wrong when unmarshalling raw body")
  		}
  		if objectAsMapInterface, ok := object.(map[string]interface{}); ok {
  			if webhookType, ok := objectAsMapInterface["type"].(string); ok {
  				return "signatures match", nil
  			}
  		}
  		return "", nil
  	}
  	return nil, errors.New("generated signature and received signature did not match")
  }

  timestamp := c.Request().Header.Get("x-webhook-timestamp")
  body, _ := ioutil.ReadAll(c.Request().Body)
  rawBody := string(body)
  signature := c.Request().Header.Get("x-webhook-signature")

  VerifySignature(signature, timestamp, rawBody)
  ```

  ```php PHP theme={"dark"}
  function computeSignature($ts, $rawBody){
      $rawBody = file_get_contents('php://input');
      $timestamp = getallheaders()['x-webhook-timestamp'];
      $signature = getallheaders()['x-webhook-signature'];

      $body = $timestamp . $rawBody;
      $secretKey = "<client-secret>";
      $genSignature = hash_hmac('sha256', $body, $secretKey, true);
      $genSignatureBase64 = base64_encode($genSignature);
      if($genSignatureBase64 == $signature) {
          $jsonResponse = json_decode($rawBody);
          return $jsonResponse;
      }
      throw new Exception("Generated signature and received signature did not match.");
  }
  ```

  ```java Java theme={"dark"}
  public Object generateSignature() {
    try {
        String data = headers.get("x-webhook-timestamp") + rawBody;
        String secretKey = "<client-secret>";
        Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
        SecretKeySpec secret_key_spec = new SecretKeySpec(secretKey.getBytes(), "HmacSHA256");
        sha256_HMAC.init(secret_key_spec);
        String computed_signature = Base64.getEncoder().encodeToString(sha256_HMAC.doFinal(data.getBytes()));
        String signature = headers.get("x-webhook-signature")
        if(computed_signature.equals(signature)) {
          Gson g = new Gson();
          Object response = g.fromJson(rawBody, Object.class);
          return response;
        }
        throw new Exception("Generated signature and received signature did not match.");
    } catch (Exception e) {
      throw e;
    }
  }
  ```

  ```python Python theme={"dark"}
  import base64
  import hashlib
  import hmac

  def generateSignature():
      raw_body = request.data
      timestamp = request.headers['x-webhook-timestamp']
      signature = request.headers['x-webhook-signature']
      signatureData = timestamp+rawBody
      message = bytes(signatureData, 'utf-8')
      secretkey=bytes("<client-signature>",'utf-8')
      generatedSignature = base64.b64encode(hmac.new(secretkey, message, digestmod=hashlib.sha256).digest())
      computed_signature = str(generatedSignature, encoding='utf8')
      if computed_signature == signature:
          json_response = json.loads(rawBody)
          return json_response
      raise Exception("Generated signature and received signature did not match.")
  ```
</CodeGroup>

### Webhook migration

Webhook endpoints have a specific API version set, for example, `2023-08-01`. To migrate from an older version to a newer version, follow these steps:

<Steps>
  <Step title="Add webhook for new version">
    Create a new webhook endpoint with the new URL and new version. Subscribe to
    the events you want to consume.
  </Step>

  <Step title="Update your code to return 200 for new webhooks">
    Update your event processing code and return a 200 response to prevent
    delivery retries. Next, enable the new webhook endpoint that you created in
    the previous step. At this point, every event is sent twice: once with the
    old API version and once with the new one.
  </Step>

  <Step title="Update your webhook code to process events for the new endpoint">
    Update your code to ensure you can process the version of your new webhook
    endpoint. Make sure you read the changelog and handle any breaking changes.
  </Step>

  <Step title="Disable old webhook endpoint">
    If events aren’t being correctly handled by your new code, first temporarily
    disable the new webhook endpoint. After monitoring for some time, you can
    permanently delete the old webhook endpoint.
  </Step>
</Steps>

<snippet>snippets/related-topics-loader.mdx</snippet>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/payments/online/webhooks/security-checklist">Webhook Security Checklist</a></li>
    <li><a href="/docs/api-reference/payments/latest/payments/webhooks">Payment Webhooks</a></li>
    <li><a href="/docs/api-reference/payments/latest/refunds/webhooks">Refund Webhooks</a></li>
    <li><a href="/docs/api-reference/payments/latest/token-vault/webhooks">Token Vault Webhooks</a></li>
    <li><a href="/docs/api-reference/payments/latest/payment-links/webhooks">Payment Link Webhooks</a></li>
  </ul>
</div>


# Webhook Security Checklist
Source: https://www.cashfree.com/docs/api-reference/payments/latest/webhooks/security-checklist

Harden Payment Gateway webhook endpoints with HTTPS, IP whitelisting, signature verification, SSL whitelisting, and authentication validation.

Secure webhook integration requires multiple layers of protection to safeguard your systems from unauthorised access and data tampering. This guide outlines the recommended security measures for your webhook endpoints.

The following table summarises the security controls and their implementation priority:

| Security control | Priority | Description |
| - | - | - |
| [Public endpoint URL](#public-endpoint-url) | Mandatory | Ensure your endpoint is publicly accessible over HTTPS. |
| [IP whitelisting](#ip-whitelisting) | Highly recommended | Restrict traffic to Cashfree's IP ranges. |
| [Signature verification](#signature-verification) | Highly recommended | Verify HMAC signature for each request. |
| [Secure Sockets Layer (SSL) whitelisting](#ssl-whitelisting) | Optional | Configure mutual TLS for enhanced security. |
| [Authentication validation](#authentication-validation) | Optional | Add custom authentication for additional protection. |

## Public endpoint URL

Your webhook endpoint must be publicly accessible over the internet for Cashfree to deliver notifications. Use this as your foundation and apply the security controls described in the following sections to protect the integration.

<Note>
  Ensure your endpoint URL uses HTTPS to encrypt data during transmission.
</Note>

For instructions on adding and configuring webhook endpoints, refer to [Webhook configuration](/docs/payments/online/webhooks/configure).

## IP whitelisting

Restrict inbound traffic to accept requests only from Cashfree's known IP ranges. This control ensures your endpoint receives webhooks exclusively from legitimate Cashfree sources.

To configure IP whitelisting, complete the following steps:

1. Allow inbound traffic from the IP addresses listed below.
2. Configure your firewall rules to allow requests only from these IP ranges.
3. Block all other inbound traffic to your webhook endpoint.

Whitelist the following IP addresses on port 443:

**Production**

* 52.66.101.190
* 3.109.102.144
* 18.60.134.245
* 18.60.183.142

**Test/Sandbox (UAT)**

* 52.66.25.127
* 15.206.45.168

<Tip>
  Cashfree may update its IP ranges periodically. Monitor the documentation for changes and update your firewall rules accordingly.
</Tip>

## Signature verification

All webhook notifications include a cryptographic signature using HMAC-based validation. Verify this signature to confirm the authenticity and integrity of each request.

To implement signature verification, follow these guidelines:

* Serve your webhook endpoint over **HTTPS** to protect data during transmission.
* Extract the signature from the webhook request headers.
* Verify the signature against the raw request body using your secret key.
* Receive the payload as **raw data** to prevent modifications before verification.

<Tip>
  For partner webhooks, use the partner API key.
</Tip>

### Required headers

Validate the following mandatory headers in each webhook request:

| Header | Description |
| - | - |
| `x-webhook-signature` | The cryptographic signature for payload verification. |
| `x-webhook-timestamp` | The timestamp when the webhook was generated. |
| `x-webhook-version` | The API version of the webhook payload. |

<Info>
  For detailed implementation examples with SDK and manual verification code samples, refer to [Webhook signature verification](/docs/payments/online/webhooks/signature-verification).
</Info>

## SSL whitelisting

For enhanced transport-level security, configure mutual TLS (mTLS) authentication between your systems and Cashfree.

To enable SSL whitelisting, you can:

* Provide your SSL certificate to Cashfree for addition to their trusted certificate sources.
* Add Cashfree's certificate to your system's trusted certificates.

This configuration ensures only mutually authenticated communication occurs between your systems and Cashfree.

<Note>
  SSL whitelisting is an optional security layer. Contact [Cashfree support](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) to configure mutual TLS authentication for your account.
</Note>

## Authentication validation

If your endpoint requires custom authentication, configure Cashfree to include the necessary credentials in webhook requests.

Cashfree supports the following authentication methods:

* **Basic authentication**: Username and password credentials
* **Bearer tokens**: Token-based authentication
* **Custom headers**: Application-specific authentication parameters

To configure authentication for webhooks:

1. Share the required authentication parameters with Cashfree.
2. Implement server-side validation to verify the authentication fields in request headers.
3. Reject requests that fail authentication checks.

For more information on API authentication methods, refer to [Authentication](/docs/api-reference/authentication).

<Tip>
  Implement signature verification at minimum to prevent payload manipulation through man-in-the-middle attacks.
</Tip>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/payments/online/webhooks/overview">Webhooks overview</a></li>
    <li><a href="/docs/payments/online/webhooks/configure">Webhook configuration</a></li>
    <li><a href="/docs/payments/online/webhooks/signature-verification">Signature verification</a></li>
    <li><a href="/docs/api-reference/authentication">API authentication</a></li>
  </ul>
</div>


# Webhook Signature Verification
Source: https://www.cashfree.com/docs/api-reference/payments/latest/webhooks/signature-verification

Verify Cashfree Payment Gateway webhook signatures with HMAC on the raw payload using the SDK or a manual implementation in six languages.

Verify webhook signatures to ensure payloads from Cashfree haven't been tampered with. This security measure prevents fraudulent notifications and protects your application from malicious attacks.

**Essential for production environments**: all merchants processing live payments, subscriptions, or marketplace transactions must implement signature verification to maintain security and prevent financial losses.

<Warning>
  Cashfree generates the webhook signature based on the raw payload, not the parsed payload. For an example of accessing the raw body in a JavaScript framework, see the [NestJS raw-body documentation](https://docs.nestjs.com/faq/raw-body). Even minor changes to the payload structure or parameter sequence result in a signature mismatch. Use the exact raw webhook body as received at your server, without parsing, re-serialisation, formatting, or modification.
</Warning>

Use the signature to verify that the request hasn't been tampered with. You need your Cashfree PG secret key and the payload to verify the signature.

<Tip>
  For partner webhooks, use the partner API key.
</Tip>

* The timestamp is present in the header `x-webhook-timestamp`.
* The actual signature is present in the header `x-webhook-signature`.

```bash signature-verification theme={"dark"}
timestamp := 1617695238078;
signedPayload := $timestamp.$payload;
expectedSignature := Base64Encode(HMACSHA256($signedPayload, $merchantSecretKey));
```

Cashfree recommends verifying webhook signatures to protect against payload manipulation.

You can use the [Webhook Verification tool in Dev Studio](https://www.cashfree.com/devstudio/preview/pg/tools/webhookVerification) to manually verify whether a payload and signature are valid before implementing verification in your code.

## SDK verification (built-in approach)

<CodeGroup>
  ```javascript Node (express) theme={"dark"}
  var express = require('express')
  const { Cashfree, CFEnvironment } = require("cashfree-pg");

  var app = express()

  const cashfree = new Cashfree(
  CFEnvironment.SANDBOX,
  "{Client ID}",
  "{Client Secret Key}"
  );

  app.post('/webhook', function (req, res) {
  try {
  cashfree.PGVerifyWebhookSignature(req.headers["x-webhook-signature"], req.rawBody, req.headers["x-webhook-timestamp"])
  } catch (err) {
  console.log(err.message)
  }
  })

  ```

  ```go golang theme={"dark"}
  import (
    cashfree "github.com/cashfree/cashfree-pg/v4"
  )

  // Route
  e.POST("/webhook", _this.Webhook)

  // Controller
  func (_this *WebhookRoute) Webhook(c echo.Context) error {
    	clientId := "<x-client-id>"
  		clientSecret := "<x-client-secret>"
  		cashfree.XClientId = &clientId
  		cashfree.XClientSecret = &clientSecret
  		cashfree.XEnvironment = cashfree.SANDBOX

      signature := c.Request().Header.Get("x-webhook-signature")
      timestamp := c.Request().Header.Get("x-webhook-timestamp")

      body, _ := ioutil.ReadAll(c.Request().Body)
      rawBody := string(body)
      webhookEvent, err := cashfree.PGVerifyWebhookSignature(signature, rawBody, timestamp)
      if err != nil {
  		fmt.Println(err.Error())
  	} else {
  		fmt.Println(webhookEvent.Object)
  	}
  }
  ```

  ```php PHP theme={"dark"}
  <?php

  $inputJSON = file_get_contents('php://input');

  $expectedSig = getallheaders()['x-webhook-signature'];
  $ts = getallheaders()['x-webhook-timestamp'];

  if(!isset($expectedSig) || !isset($ts)){
      echo "Bad Request";
      die();
  }

  \Cashfree\Cashfree::$XClientId = "<x-client-id>";
  \Cashfree\Cashfree::$XClientSecret = "<x-client-secret>";
  $cashfree = new \Cashfree\Cashfree();

  try {
   $response =  cashfree->PGVerifyWebhookSignature($expectedSig, $inputJSON, $ts);
  } catch(Exception $e) {
    // Error if signature verification fails
  }
  ?>
  ```

  ```python Python theme={"dark"}
  from cashfree_pg.api_client import Cashfree

  @app.route('/webhook', methods = ['POST'])
  def disp():
  		# Get the raw body from the request
      raw_body = request.data

      # Decode the raw body bytes into a string
      decoded_body = raw_body.decode('utf-8')

      #verify_signature
      timestamp = request.headers['x-webhook-timestamp']
      signature = request.headers['x-webhook-signature']

  		cashfree = Cashfree()
  		cashfree.XClientId = "<app_id>"
  		cashfree.XClientSecret = "<secret_key>"
  		try:
  			cashfreeWebhookResponse = cashfree.PGVerifyWebhookSignature(signature, decoded_body, timestamp)
  		except:
  			# If Signature mis-match
  ```

  ```java Java theme={"dark"}
  import com.cashfree.*;

  @PostMapping("/my-endpoint")
  public String handlePost(HttpServletRequest request) throws IOException {
      Cashfree.XClientId = "<x-client-id>";
  		Cashfree.XClientSecret = "<x-client-secret>";
  		Cashfree.XEnvironment = Cashfree.SANDBOX;

    	StringBuilder stringBuilder = new StringBuilder();
      BufferedReader bufferedReader = null;

      try {
        bufferedReader = request.getReader();
        String line;
        while ((line = bufferedReader.readLine()) != null) {
                stringBuilder.append(line).append('\n');
        }


        String rawBody = stringBuilder.toString();
        String signature = request.getHeader("x-webhook-signature");
        String timestamp = request.getHeader("x-webhook-timestamp");

        Cashfree cashfree = new Cashfree();
        PGWebhookEvent webhook = cashfree.PGVerifyWebhookSignature(signature, rawBody, timestamp);

      } catch (Exception e) {
              // Error if verification fails
      } finally {
           if (bufferedReader != null) {
              bufferedReader.close();
  		}
  	}

  }
  ```

  ```csharp csharp theme={"dark"}
  using cashfree_pg.Client;
  using cashfree_pg.Model;


  		[Route("api/[controller]")]
      [ApiController]
      public class YourController : ControllerBase
      {
          [HttpPost]
          public async Task<IActionResult> Post()
          {
              // Read the raw body of the POST request
              using (StreamReader reader = new StreamReader(Request.Body, Encoding.UTF8))
              {
                  string requestBody = await reader.ReadToEndAsync();
                  var headers = Request.Headers;
                  var signature = headers["x-webhook-signature"];
                  var timestamp = headers["x-webhook-timestamp"];

                  Cashfree.XClientId = "<x-client-id>";
                  Cashfree.XClientSecret = "<x-client-secret>";
                  Cashfree.XEnvironment = Cashfree.SANDBOX;
  								var cashfree = new Cashfree();

                  try {
                  var response = cashfree.PGVerifyWebhookSignature(signature, requestBody, timestamp);
                  } catch(Exception e) {
                  // Error if signature mis matches
                  }
              }
          }
      }
  ```
</CodeGroup>

## Manual verification (custom approach)

<CodeGroup>
  ```javascript Node (Express) theme={"dark"}
  function verify(ts, request){
      const body = request.headers['x-webhook-timestamp'] + request.rawBody
      const secretKey = <client secret>;
      let generatedSignature = crypto.createHmac('sha256', secretKey).update(body).digest("base64");
      const signature = request.headers['x-webhook-signature']
      if(generatedSignature === signature) {
          let jsonObject = JSON.parse(rawBody)
          return jsonObject
      }
      throw new Error("Generated signature and received signature did not match.");
  }
  ```

  ```go golang theme={"dark"}
  func VerifySignature(expectedSig string, ts string, body string) (string, error) {
          clientSecret := "<client-secret>"
  	signatureString := ts + rawBody
  	hmacInstance := hmac.New(sha256.New, []byte(*clientSecret))
  	hmacInstance.Write([]byte(signatureString))
  	bytesData := hmacInstance.Sum(nil)
  	generatedSignature := base64.StdEncoding.EncodeToString(bytesData)
  	if generatedSignature == expectedSig {
  		var object interface{}
  		err := json.Unmarshal([]byte(rawBody), &object)
  		if err != nil {
  			return nil, errors.New("something went wrong when unmarshalling raw body")
  		}
  		if objectAsMapInterface, ok := object.(map[string]interface{}); ok {
  			if webhookType, ok := objectAsMapInterface["type"].(string); ok {
  				return "signatures match", nil
  			}
  		}
  		return "", nil
  	}
  	return nil, errors.New("generated signature and received signature did not match")
  }

  timestamp := c.Request().Header.Get("x-webhook-timestamp")
  body, _ := ioutil.ReadAll(c.Request().Body)
  rawBody := string(body)
  signature := c.Request().Header.Get("x-webhook-signature")

  VerifySignature(signature, timestamp, rawBody)
  ```

  ```php PHP theme={"dark"}
  function computeSignature($ts, $rawBody){
      $rawBody = file_get_contents('php://input');
      $timestamp = getallheaders()['x-webhook-timestamp'];
      $signature = getallheaders()['x-webhook-signature'];

      $body = $timestamp . $rawBody;
      $secretKey = "<client-secret>";
      $genSignature = hash_hmac('sha256', $body, $secretKey, true);
      $genSignatureBase64 = base64_encode($genSignature);
      if($genSignatureBase64 == $signature) {
          $jsonResponse = json_decode($rawBody);
          return $jsonResponse;
      }
      throw new Exception("Generated signature and received signature did not match.");
  }
  ```

  ```java Java theme={"dark"}
  public Object generateSignature() {
    try {
        String data = headers.get("x-webhook-timestamp") + rawBody;
        String secretKey = "<client-secret>";
        Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
        SecretKeySpec secret_key_spec = new SecretKeySpec(secretKey.getBytes(), "HmacSHA256");
        sha256_HMAC.init(secret_key_spec);
        String computed_signature = Base64.getEncoder().encodeToString(sha256_HMAC.doFinal(data.getBytes()));
        String signature = headers.get("x-webhook-signature")
        if(computed_signature.equals(signature)) {
          Gson g = new Gson();
          Object response = g.fromJson(rawBody, Object.class);
          return response;
        }
        throw new Exception("Generated signature and received signature did not match.");
    } catch (Exception e) {
      throw e;
    }
  }
  ```

  ```python Python theme={"dark"}
  import base64
  import hashlib
  import hmac

  def generateSignature():
      raw_body = request.data
      timestamp = request.headers['x-webhook-timestamp']
      signature = request.headers['x-webhook-signature']
      signatureData = timestamp+rawBody
      message = bytes(signatureData, 'utf-8')
      secretkey=bytes("<client-signature>",'utf-8')
      generatedSignature = base64.b64encode(hmac.new(secretkey, message, digestmod=hashlib.sha256).digest())
      computed_signature = str(generatedSignature, encoding='utf8')
      if computed_signature == signature:
          json_response = json.loads(rawBody)
          return json_response
      raise Exception("Generated signature and received signature did not match.")
  ```
</CodeGroup>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/payments/online/webhooks/security-checklist">Webhook Security Checklist</a></li>
    <li><a href="/docs/payments/online/webhooks/overview">Webhooks Overview</a></li>
    <li><a href="/docs/payments/online/webhooks/configure">Configure Webhooks</a></li>
    <li><a href="/docs/api-reference/payments/latest/payments/webhooks">Payment Webhooks API</a></li>
  </ul>
</div>


# Webhook Troubleshooting
Source: https://www.cashfree.com/docs/api-reference/payments/latest/webhooks/troubleshooting

Diagnose missing triggers, failed endpoint additions, and duplicate deliveries for Cashfree Payment Gateway webhooks using dashboard logs and resends.

## Webhook did not trigger

If a webhook does not trigger for the specified endpoint:

1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).

2. Navigate to **Developer > Webhooks** under **Payment Gateway**, and select the **Logs** tab to check for failures and take necessary action.
   Common reasons for webhook failure are:
   * The endpoint returns a **500 error** or does not respond.
   * The required event is not configured in the webhook settings.

3. Select **Batch Resend** to resend missed webhook events.

4. Select the **Batch Source** and enter **Entity IDs** in the **Batch Resend** modal.

5. Select **Resend**. Refer to the screenshot below:

<img />

## Cannot add a payment gateway webhook

To add a webhook endpoint URL:

1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).

2. Navigate to **Developer > Webhooks** under **Payment Gateway**, and select **Add Webhook Endpoint** in the **Configuration** tab.

3. Add the following details in the **Add Webhook Endpoint** modal:

   * **Endpoint Details**: Enter the endpoint URL for the webhook and select the latest webhook version from the drop-down list.

   <Note>
     **Note**:
     When you add the endpoint URL, Cashfree sends a test `POST` request to check if it is valid and responsive. If the endpoint does not respond, select **Continue** and manually select the required events.
   </Note>

   * **Add Policy**: Customise the retry policy and select the webhook events you want to subscribe to.
   * **Summary**: Review and confirm your selections.

4. Select **Save** to complete the setup. Refer to the screenshot below:

<img />

## Receiving duplicate webhook events

If you receive duplicate webhook events, check for the following issues:

* **Multiple subscriptions to the same event**
  * You may have subscribed to the same event multiple times across different webhook versions or for different URLs.
  * Check each **URL Configuration** and remove duplicate subscriptions.

* **Retries due to downtime**
  * If **Cashfree** or your server experiences downtime, Cashfree retries webhook deliveries to ensure event completion.

* **Prevent duplicate processing**
  * Validate the **x-idempotency-header** in the webhook header.
    * This header contains a unique hashed value for each webhook payload.
    * Webhook versions from **2025-01-01** support this feature.
    * To upgrade, see the [Webhook Migration](/docs/payments/online/webhooks/overview#webhook-migration) section.

## Configure webhooks for non-payment gateway products

To configure webhooks for products such as **Payouts**, **Subscriptions**, **Payments**, **Payment Links**, or **Secure ID**, go to the respective product webhook section on the Merchant Dashboard and add the required webhook endpoint URL.

<img />

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/payments/online/webhooks/security-checklist">Webhook Security Checklist</a></li>
    <li><a href="/docs/payments/online/webhooks/overview">Webhooks Overview</a></li>
    <li><a href="/docs/payments/online/webhooks/configure">Webhook Configuration</a></li>
  </ul>
</div>


# Overview
Source: https://www.cashfree.com/docs/api-reference/payments/overview

Explore Cashfree Payment Gateway APIs for orders, payments, refunds, and more.

Cashfree's RESTful Payment Gateway API provides a robust and flexible interface for integrating payment solutions into your applications. The API uses predictable resource-oriented URLs, accepts JSON request bodies, returns JSON-encoded responses, and supports standard HTTP response codes and authentication. SDKs in popular programming languages help you integrate faster with pre-built handling for authentication, request or response formatting, and error handling.

<Tip>
  We strongly recommend using [SDKs](/docs/api-reference/payments/sdk) to streamline the integration process and ensure optimal performance and security.
</Tip>

## What's new in v2026-01-01

Cashfree API v2026-01-01 is now available. This release includes the following changes:

* A new [Order Pay Authorise Only](/docs/api-reference/payments/latest/payments/order-pay-authorise-only) endpoint for authorising card payments without immediate capture.
* A new controlled subscription payment flow for UPI Autopay and card mandates, with six dedicated APIs for pre-debit notification and charge execution.
* New fields and parameters on Create Order, Order Pay, Create Payment Link, and Get All Settlements.
* A restructured Create Subscription request body, two new fields, and one removed field.
* Updated example payloads for all three Payment webhooks and five subscription webhook events, reflecting the v2026-01-01 response format.
* Breaking response schema changes to settlement endpoints and a removed field on Create Order. Review your integration before upgrading.
* Partner and PA Partner authentication on Collect from India import settlement APIs.
* A new NuGet package ID for the .NET SDK: `cashfree-dotnet-pg` from v6.0.7. The previous `cashfree_pg` package is no longer updated.

Expand the sections below for more details:

<AccordionGroup>
  <Accordion title="New endpoint: Order Pay Authorise Only">
    A new endpoint, [Order Pay Authorise Only](/docs/api-reference/payments/latest/payments/order-pay-authorise-only), is available for merchants with the `AUTHORIZE_ONLY` flag enabled on their account. Use it to authorise a card payment without capturing it immediately.

    The request requires a `payment_session_id` and an `authorization_data` object containing the following 3DS authentication fields:

    | Field | Description |
    | - | - |
    | `authentication_token` | 3DS authentication token |
    | `directory_server_transaction_id` | Directory server transaction ID from the 3DS flow |
    | `three_ds_server_transaction_id` | 3DS server transaction ID |
    | `eci` | Electronic Commerce Indicator value |
    | `token_number` | Network token number |
    | `token_expiry_year` | Token expiry year |
    | `token_expiry_month` | Token expiry month |
    | `token_cryptogram` | Cryptogram for the token |
    | `transaction_type` | One of `ALT_ID`, `TOKEN`, or `APPLE_PAY` |

    The endpoint returns a `PaymentEntity` on success and requires no authentication (`security: []`).
  </Accordion>

  <Accordion title="New: controlled subscription payment flow">
    v2026-01-01 introduces a controlled payment flow for UPI Autopay and card mandate subscriptions, giving you explicit control over when to notify your customers and when to execute the debit. This is a significant change if you need to comply with pre-debit notification rules for UPI Autopay and card mandates. See [Controlled Subscription Payments](/docs/api-reference/payments/latest/subscription/payment/controlled/overview) for the two-step flow, endpoints, and webhooks.

    <Note>The controlled flow supports UPI Autopay and card mandates. eNACH and Physical NACH (PNACH) mandates are not supported.</Note>

    **How it works**

    The controlled flow replaces the automatic charge trigger with a two-step process you drive:

    1. **Send a pre-debit notification**: Notify your customer of the upcoming charge amount before the debit window opens.
    2. **Execute the charge**: Trigger the mandate debit after the compliance window elapses. The debit amount must exactly match the notified amount; a mismatch causes the issuing bank to decline the transaction.

    **APIs**

    | API | Method | Description |
    | - | - | - |
    | [Create Controlled Notification](/docs/api-reference/payments/latest/subscription/payment/controlled/create-controlled-notification) | `POST /subscriptions/pay/controlled/notify-mandate` | Send a pre-debit notification to the customer |
    | [Fetch Controlled Notification](/docs/api-reference/payments/latest/subscription/payment/controlled/fetch-controlled-notification) | `GET /subscriptions/payments/{payment_id}/controlled/notifications/{notification_id}` | Retrieve a single notification |
    | [Fetch All Controlled Notifications](/docs/api-reference/payments/latest/subscription/payment/controlled/fetch-controlled-notifications) | `GET /subscriptions/payments/{payment_id}/controlled/notifications` | List all notifications for a payment |
    | [Create Controlled Execution](/docs/api-reference/payments/latest/subscription/payment/controlled/create-controlled-execution) | `POST /subscriptions/pay/controlled/execute-mandate` | Trigger the mandate debit after the notification window |
    | [Fetch Controlled Execution](/docs/api-reference/payments/latest/subscription/payment/controlled/fetch-controlled-execution) | `GET /subscriptions/payments/{payment_id}/controlled/executions/{execution_id}` | Retrieve a single execution |
    | [Fetch All Controlled Executions](/docs/api-reference/payments/latest/subscription/payment/controlled/fetch-controlled-executions) | `GET /subscriptions/payments/{payment_id}/controlled/executions` | List all execution attempts for a payment |
  </Accordion>

  <Accordion title="New features on existing endpoints">
    **Client environment headers: Order Pay and Get Eligible Payment Methods**

    [Order Pay](/docs/api-reference/payments/latest/payments/order-pay) and [Get Eligible Payment Methods](/docs/api-reference/payments/latest/eligibility/get-eligible-payment-methods) now formally accept four optional device-context headers required for NPCI compliance. These headers were required in practice; they are now part of the spec with full validation.

    | Header | Accepted values | Requirement |
    | - | - | - |
    | `x-client-device` | `mobile`, `desktop`, `tablet` | Required |
    | `x-client-os` | `android`, `ios`, `windows`, `macos`, `linux`, `others` | Required |
    | `x-client-browser` | `safari`, `chrome`, `firefox`, `edge`, `others` | Required |
    | `x-client-rendering-type` | `mweb`, `webview`, `native` | Required when `x-client-device` is `mobile` |

    ***

    **Offer filters and UPI app priority: Create Order**

    Two new optional fields are available on `order_meta` in [Create Order](/docs/api-reference/payments/latest/orders/create-order):

    * `offer_filters`: explicitly allow or deny specific offers for an order. Set `action` to `ALLOW` or `DENY` and provide a list of up to 25 offer values.
    * `upi_app_priority`: control the display order of UPI apps on your checkout page. Accepted values: `gpay`, `phonepe`, `paytm`, `navi`, `cred`, `supermoney`, `amazonpay`, `bhim`, `mobikwik`, `airtel`, `popclub`, `kiwi`.

    ***

    **Settlement status filter: Get All Settlements**

    [Get All Settlements](/docs/api-reference/payments/latest/settlement-reconciliation/get-all-settlements) now accepts a new optional filter field `filters.settlement_status`. Pass an array of one or more of the following values to retrieve settlements by processing state:

    * `SUCCESS`
    * `PENDING`
    * `PENDING_WITH_CASHFREE`
    * `PENDING_WITH_BANK`
    * `FAILED`

    ***

    **Subscription support: Payment Links**

    [Create Payment Link](/docs/api-reference/payments/latest/payment-links/create-payment-link) now accepts an optional `subscription` field to create recurring payment links backed by a plan. The plan is defined inline with the following fields:

    | Field | Required | Description |
    | - | - | - |
    | `plan_id` | Yes | Unique identifier for the plan |
    | `plan_name` | Yes | Display name of the plan |
    | `plan_type` | Yes | Type of plan |
    | `plan_max_amount` | Yes | Maximum charge amount per cycle |
    | `plan_currency` | No | Currency code (default: INR) |
    | `plan_amount` | No | Fixed amount per cycle |
    | `plan_max_cycles` | No | Maximum number of billing cycles |
    | `plan_intervals` | No | Number of intervals per cycle |
    | `plan_interval_type` | No | Interval unit (day, week, month, year) |
    | `plan_note` | No | Internal note for the plan |

    Additional subscription-level fields: `authorization_amount`, `authorization_amount_refund` (boolean), `subscription_expiry_time`, and `subscription_first_charge_time`.

    ***

    **PAR field: card payments**

    `PayOrderRequest.payment_method.card` now accepts a `par` field (Payment Account Reference received from the card network). This is relevant for token-based and network-tokenised card flows.
  </Accordion>

  <Accordion title="Webhook payload examples for v2026-01-01">
    v2026-01-01 introduces updated payload examples for the following webhook events, reflecting the new response fields introduced in this release.

    | Webhook page | Events updated |
    | - | - |
    | [Payment webhooks](/docs/api-reference/payments/latest/payments/webhooks) | `PAYMENT_SUCCESS_WEBHOOK`, `PAYMENT_FAILED_WEBHOOK`, `PAYMENT_USER_DROPPED_WEBHOOK` |
    | [Subscription webhooks](/docs/api-reference/payments/latest/subscription/webhooks) | `SUBSCRIPTION_AUTH_STATUS`, `SUBSCRIPTION_PAYMENT_NOTIFICATION_INITIATED`, `SUBSCRIPTION_PAYMENT_SUCCESS`, `SUBSCRIPTION_PAYMENT_FAILED`, `SUBSCRIPTION_PAYMENT_CANCELLED` |

    <Note>
      Payload examples for the remaining subscription webhook events will be updated to v2026-01-01 soon.
    </Note>
  </Accordion>

  <Accordion title="Breaking changes: response schema updates">
    The following endpoints return a different response schema in v2026-01-01. Review and update your integration before switching to this version.

    <Warning>
      These are breaking changes. Existing code that reads from the previous response structure will fail silently or throw errors after upgrading to `x-api-version: 2026-01-01`.
    </Warning>

    **[Get Settlements by Order ID](/docs/api-reference/payments/latest/settlements/get-settlements-by-order-id): nested response object**

    Previously returned a flat `SettlementEntity` object. Now returns `OrderSettlementEntity`, a nested object structured as follows:

    | Sub-object | Key fields |
    | - | - |
    | `order_details` | `order_id`, `order_amount`, `order_currency` |
    | `payment_details` | `cf_payment_id`, `payment_amount`, `service_charge`, `service_tax`, `charge_type`, `charged_to` |
    | `customer_details` | `customer_id`, `customer_email`, `customer_phone` |
    | `settlement_details` | `cf_settlement_id`, `settlement_amount`, `settlement_utr`, `settlement_status`, `settled_on` |

    Update any code that reads `cf_payment_id`, `service_charge`, `settlement_amount`, or other fields directly from the response root.

    ***

    **[Get All Settlements](/docs/api-reference/payments/latest/settlement-reconciliation/get-all-settlements): paginated response**

    Previously returned a single flat settlement record. Now returns a paginated `GetAllSettlementsResponse`:

    ```json theme={"dark"}
    {
      "cursor": "string",
      "limit": 10,
      "data": [
        {
          "cf_settlement_id": "string",
          "status": "SUCCESS | PENDING | PENDING_WITH_CASHFREE | PENDING_WITH_BANK | FAILED",
          "settlement_utr": "string",
          "payment_from": "date",
          "payment_till": "date",
          "settlement_initiated_on": "date",
          "settlement_processed_on": "date",
          "payment_amount": 0,
          "pg_service_charge": 0,
          "pg_service_tax": 0,
          "adjustment": 0,
          "settlement_charge": 0,
          "settlement_tax": 0,
          "split_service_charge": 0,
          "split_service_tax": 0,
          "vendor_commission": 0,
          "amount_settled": 0,
          "charge_type": "PREPAID | POSTPAID | SURCHARGE | PREPAID_SURCHARGE | POSTPAID_SURCHARGE",
          "settlement_type": "string"
        }
      ]
    }
    ```

    Update any code that reads from the flat settlement response to iterate over `data` and handle pagination using `cursor`.

    ***

    **[Mark Order for Settlement](/docs/api-reference/payments/latest/settlements/mark-order-for-settlement): HTTP status code and response body changed**

    Previously returned HTTP `202` with an empty `{}` body. Now returns HTTP `200` with the following body:

    ```json theme={"dark"}
    {
      "order_id": "string",
      "meta_data": {
        "cbriks_id": "string",
        "settlement_date": "date"
      }
    }
    ```

    Update any code that checks for a `202` status or expects an empty response body.

    ***

    **[Get Order Extended](/docs/api-reference/payments/latest/orders/get-order-extended): `offer` renamed to `offers` (array)**

    The `offer` field (a single object of type `OfferExtendedDetails`) in `OrderExtendedDataEntity` is now `offers` (an array of `OfferExtendedDetails` objects). Update field references from `offer` to `offers` and handle the array structure.
  </Accordion>

  <Accordion title="Removed fields">
    The following fields have been removed in v2026-01-01. Requests that include these fields will either be ignored or return a validation error.

    | Field | Endpoint | Reason |
    | - | - | - |
    | `CreateOrderRequest.bbps` | [Create Order](/docs/api-reference/payments/latest/orders/create-order) | The BBPS-specific fields `bill_fetch_ref_id`, `biller_id`, and `agent_id` are no longer accepted on the Create Order request body. |
  </Accordion>

  <Accordion title=".NET SDK: new NuGet package">
    The .NET SDK is now published under a new NuGet package ID starting from version 6.0.7.

    **Install the new package:**

    ```bash theme={"dark"}
    dotnet add package cashfree-dotnet-pg
    ```

    | | Package | Version |
    | - | - | - |
    | **New** | `cashfree-dotnet-pg` | 6.0.7 and above |
    | **Previous** | `cashfree_pg` | Final version: 5.0.6 (no longer updated) |

    No code changes are required beyond updating the package reference. All future .NET SDK releases will be published only under `cashfree-dotnet-pg`. For the full version history, see the [.NET SDK changelog](/docs/payments/developers/changelog/dotnet).
  </Accordion>

  <Accordion title="Updates to Subscription APIs">
    The [Subscription APIs](/docs/api-reference/payments/latest/subscription/overview) in v2026-01-01 include a restructured request body, two new request fields, and one removed field on [Create Subscription](/docs/api-reference/payments/latest/subscription/create-subscription).

    **Restructured request body**

    The `CreateSubscriptionRequest` previously used a flat structure where all fields were at the top level. In v2026-01-01, fields are grouped into four nested objects for clarity and consistency:

    | Object | Fields |
    | - | - |
    | `customer_details` | `customer_name`, `customer_email`, `customer_phone`, bank account fields |
    | `plan_details` | `plan_id`, `plan_name`, `plan_type`, `plan_amount`, `plan_max_amount`, `plan_currency`, and related plan configuration |
    | `authorization_details` | `authorization_amount`, `authorization_amount_refund`, `payment_methods` |
    | `subscription_meta` | `return_url`, `notification_channel`, `session_id_expiry` |

    <Warning>
      This is a breaking change. Update your Create Subscription integration to use the new nested structure before switching to `x-api-version: 2026-01-01`.
    </Warning>

    ***

    **New field: `subscription_tags`**

    `CreateSubscriptionRequest` now accepts `subscription_tags`, a free-form object for attaching up to 10 custom key-value string entries to a subscription. A commonly used key is `psp_note`, which sets the note displayed to the customer in their payment service provider app or on their bank statement. When using `psp_note`, the value must be between 1 and 255 characters.

    ***

    **New field: `subscription_payment_splits`**

    `CreateSubscriptionRequest` now accepts `subscription_payment_splits`, an array of vendor split items. Each item specifies a `vendor_id` and a `percentage`, allowing subscription charges to be distributed across multiple vendors at the time of collection.

    ***

    **Removed field: `customer_bank_account_holder_name`**

    The `customer_bank_account_holder_name` field has been removed from `CreateSubscriptionRequest`. This field is no longer accepted in v2026-01-01.

    ***

    **New: webhook signature verification**

    A dedicated [Signature Verification](/docs/api-reference/payments/latest/subscription/webhook-signature) page is now available for subscription webhooks, covering how to validate the `x-webhook-signature` header to confirm event authenticity before processing.

    For the controlled subscription payment flow, see the [New: controlled subscription payment flow](#) section above.
  </Accordion>

  <Accordion title="Partner and PA Partner authentication: Import Settlement APIs">
    The following Collect from India import settlement endpoints in v2026-01-01 now support Partner and PA Partner authentication, in addition to standard merchant authentication:

    | API | Method |
    | - | - |
    | [Get Import Settlement Details for an Order](/docs/api-reference/payments/latest/international-payments/collect-from-india/get-import-settlement-details) | `GET /import/orders/{order_id}/settlements` |
    | [Get Import Settlement Recon Details](/docs/api-reference/payments/latest/international-payments/collect-from-india/get-import-settlement-recon-details) | `POST /import/settlements/recon` |

    Use Partner authentication when calling these APIs on behalf of a merchant. For Payment Aggregator (PA) flows, select the PA Partner option and pass `x-partner-type` with the value `PA`.

    For more information on partner headers, see [Partner authentication](/docs/api-reference/authentication#partner-authentication).
  </Accordion>
</AccordionGroup>

<Note>
  To use this version, set `x-api-version: 2026-01-01` in all request headers. If you are using the previous version, see the [v2025-01-01 API reference](/docs/api-reference/payments/previous/v2025-01-01/overview).
</Note>

<Tabs>
  <Tab title="Orders and payments">
    <div>
      <div>
        <div>
          <h4>Orders</h4>

          <div>
            <div>
              <a href="/docs/api-reference/payments/latest/orders/create-order">Create Order</a>

              <p>
                Create an order to collect payments from your customers.
              </p>
            </div>
          </div>

          <hr />

          <div>
            <div>
              <a href="/docs/api-reference/payments/latest/orders/get-order">Get Order</a>

              <p>
                Get status and details of an order.
              </p>
            </div>
          </div>

          <hr />

          <div>
            <div>
              <a href="/docs/api-reference/payments/latest/orders/terminate-order">Terminate Order</a>

              <p>
                Terminate an order that's no longer needed.
              </p>
            </div>
          </div>

          <hr />

          <div>
            <div>
              <a href="/docs/api-reference/payments/latest/orders/get-order-extended">Get Order Extended</a>

              <p>
                Fetch extended data for an order.
              </p>
            </div>
          </div>

          <hr />

          <div>
            <div>
              <a href="/docs/api-reference/payments/latest/orders/update-order-extended">Update Order Extended</a>

              <p>
                Update extended data for an order.
              </p>
            </div>
          </div>

          <hr />

          <h4>Customers</h4>

          <div>
            <div>
              <a href="/docs/api-reference/payments/latest/customers/create-customer-at-cashfree">Create Customer</a>

              <p>
                Create a customer for Token Vault and saved instruments.
              </p>
            </div>
          </div>
        </div>
      </div>

      <div>
        <div>
          <h4>Payments</h4>

          <div>
            <div>
              <a href="/docs/api-reference/payments/latest/payments/order-pay">Pay</a>

              <p>
                Initiate a payment for an order using the chosen payment method.
              </p>
            </div>
          </div>

          <hr />

          <div>
            <div>
              <a href="/docs/api-reference/payments/latest/payments/submit-or-resend-otp">Authenticate</a>

              <p>
                Submit or resend OTP in the native OTP flow for card payments.
              </p>
            </div>
          </div>

          <hr />

          <div>
            <div>
              <a href="/docs/api-reference/payments/latest/payments/preauthorisation"> Authorise</a>

              <p>
                Capture or void a pre-authorised transaction.
              </p>
            </div>
          </div>

          <hr />

          <div>
            <div>
              <a href="/docs/api-reference/payments/latest/payments/get-payment-by-id">Get Payment</a>

              <p>
                Get status and details of a single payment.
              </p>
            </div>
          </div>

          <hr />

          <div>
            <div>
              <a href="/docs/api-reference/payments/latest/payments/get-payments-for-an-order">Get Payments for Order</a>

              <p>
                Get status and details of all payments for an order.
              </p>
            </div>
          </div>
        </div>
      </div>
    </div>
  </Tab>

  <Tab title="Links and refunds">
    <div>
      <div>
        <div>
          <h4>Payment links</h4>

          <div>
            <div>
              <a href="/docs/api-reference/payments/latest/payment-links/create-payment-link">Create Payment Link</a>

              <p>
                Create a shareable payment link for collecting payments.
              </p>
            </div>
          </div>

          <hr />

          <div>
            <div>
              <a href="/docs/api-reference/payments/latest/payment-links/fetch-payment-link-details">Get Payment Link</a>

              <p>
                Get details of a payment link.
              </p>
            </div>
          </div>

          <hr />

          <div>
            <div>
              <a href="/docs/api-reference/payments/latest/payment-links/cancel-payment-link">Cancel Payment Link</a>

              <p>
                Cancel an active payment link.
              </p>
            </div>
          </div>

          <hr />

          <div>
            <div>
              <a href="/docs/api-reference/payments/latest/payment-links/get-orders-for-a-payment-link">Get Orders for Link</a>

              <p>
                Fetch orders associated with a payment link.
              </p>
            </div>
          </div>
        </div>
      </div>

      <div>
        <div>
          <h4>Refunds</h4>

          <div>
            <div>
              <a href="/docs/api-reference/payments/latest/refunds/create-refund">Create Refund</a>

              <p>
                Create a refund for a payment (full or partial).
              </p>
            </div>
          </div>

          <hr />

          <div>
            <div>
              <a href="/docs/api-reference/payments/latest/refunds/get-refund">Get Refund</a>

              <p>
                Get status and details of a refund.
              </p>
            </div>
          </div>

          <hr />

          <div>
            <div>
              <a href="/docs/api-reference/payments/latest/refunds/get-all-refunds-for-an-order">Get Refunds for Order</a>

              <p>
                Get all refunds for an order.
              </p>
            </div>
          </div>

          <hr />

          <div>
            <div>
              <a href="/docs/api-reference/payments/latest/refunds/update-refund">Update Refund</a>

              <p>
                Update refund details or speed.
              </p>
            </div>
          </div>
        </div>
      </div>
    </div>
  </Tab>

  <Tab title="Vault and offers">
    <div>
      <div>
        <div>
          <h4>Token Vault</h4>

          <div>
            <div>
              <a href="/docs/api-reference/payments/latest/token-vault/fetch-cryptogram-for-a-saved-card-instrument">Generate Cryptogram</a>

              <p>
                Generate a cryptogram for a saved card to process a payment.
              </p>
            </div>
          </div>

          <hr />

          <div>
            <div>
              <a href="/docs/api-reference/payments/latest/token-vault/fetch-all-saved-card-instrument">Get All Saved Cards</a>

              <p>
                Fetch all saved card instruments for a customer.
              </p>
            </div>
          </div>

          <hr />

          <div>
            <div>
              <a href="/docs/api-reference/payments/latest/token-vault/fetch-specific-saved-card-instrument">Get Saved Card</a>

              <p>
                Get details of a single saved card instrument.
              </p>
            </div>
          </div>

          <hr />

          <div>
            <div>
              <a href="/docs/api-reference/payments/latest/token-vault/delete-saved-card-instrument">Delete Saved Card</a>

              <p>
                Delete a saved card instrument for a customer.
              </p>
            </div>
          </div>
        </div>
      </div>

      <div>
        <div>
          <h4>Eligibility and offers</h4>

          <div>
            <div>
              <a href="/docs/api-reference/payments/latest/eligibility/get-eligible-payment-methods">Get Eligible Payment Methods</a>

              <p>
                Fetch payment methods eligible for an order and account.
              </p>
            </div>
          </div>

          <hr />

          <div>
            <div>
              <a href="/docs/api-reference/payments/latest/eligibility/get-eligible-cardless-emi-payment-methods-for-a-customer-on-an-order">Get Eligible Cardless EMI</a>

              <p>
                Get eligible cardless EMI options for a customer and order.
              </p>
            </div>
          </div>

          <hr />

          <div>
            <div>
              <a href="/docs/api-reference/payments/latest/eligibility/get-eligible-paylater-for-a-customer-on-an-order">Get Eligible Paylater</a>

              <p>
                Get eligible paylater options for a customer and order.
              </p>
            </div>
          </div>

          <hr />

          <div>
            <div>
              <a href="/docs/api-reference/payments/latest/eligibility/get-eligible-offers-for-an-order">Get Eligible Offers</a>

              <p>
                Get offers applicable to an order (for example, no-cost EMI).
              </p>
            </div>
          </div>

          <hr />

          <div>
            <div>
              <a href="/docs/api-reference/payments/latest/offers/create-offer">Create Offer</a>

              <p>
                Create a new offer (card, netbanking, EMI, etc.).
              </p>
            </div>
          </div>

          <hr />

          <div>
            <div>
              <a href="/docs/api-reference/payments/latest/offers/get-offer-by-id">Get Offer</a>

              <p>
                Get details of an offer.
              </p>
            </div>
          </div>
        </div>
      </div>
    </div>
  </Tab>

  <Tab title="Split and settlements">
    <div>
      <div>
        <div>
          <h4>Easy-Split</h4>

          <div>
            <div>
              <a href="/docs/api-reference/payments/latest/split/easy-split-overview">Easy-Split Overview</a>

              <p>
                Overview of split payments and vendor settlements.
              </p>
            </div>
          </div>

          <hr />

          <div>
            <div>
              <a href="/docs/api-reference/payments/latest/split/end-points">Easy-Split Endpoints</a>

              <p>
                API reference for split and vendor operations.
              </p>
            </div>
          </div>

          <hr />

          <div>
            <div>
              <a href="/docs/api-reference/payments/latest/easy-split/create-vendor">Create Vendor</a>

              <p>
                Create a vendor for receiving split payments.
              </p>
            </div>
          </div>

          <hr />

          <div>
            <div>
              <a href="/docs/api-reference/payments/latest/easy-split/create-static-split-configuration">Static Split</a>

              <p>
                Configure static split rules for orders.
              </p>
            </div>
          </div>

          <hr />

          <div>
            <div>
              <a href="/docs/api-reference/payments/latest/easy-split/split-after-payment">Split After Payment</a>

              <p>
                Create split for an order after payment is received.
              </p>
            </div>
          </div>

          <hr />

          <div>
            <div>
              <a href="/docs/api-reference/payments/latest/easy-split/create-on-demand-transfer">On-Demand Transfer</a>

              <p>
                Transfer vendor share on demand.
              </p>
            </div>
          </div>
        </div>
      </div>

      <div>
        <div>
          <h4>Settlements and more</h4>

          <div>
            <div>
              <a href="/docs/api-reference/payments/latest/settlement-reconciliation/get-all-settlements">Get Settlements</a>

              <p>
                Fetch settlement details and history.
              </p>
            </div>
          </div>

          <hr />

          <div>
            <div>
              <a href="/docs/api-reference/payments/latest/settlements/mark-order-for-settlement">Mark Order for Settlement</a>

              <p>
                Mark an order for instant settlement.
              </p>
            </div>
          </div>

          <hr />

          <div>
            <div>
              <a href="/docs/api-reference/payments/latest/disputes/get-disputes-by-order-id">Get Disputes by Order</a>

              <p>
                Fetch disputes associated with an order.
              </p>
            </div>
          </div>

          <hr />

          <div>
            <div>
              <a href="/docs/api-reference/payments/latest/subscription/overview">Subscription Overview</a>

              <p>
                Recurring payments: plans, mandates, and payment flows.
              </p>
            </div>
          </div>

          <hr />

          <div>
            <div>
              <a href="/docs/api-reference/payments/latest/subscription/create-subscription">Create Subscription</a>

              <p>
                Create a subscription with mandate (UPI, card, E-Mandate).
              </p>
            </div>
          </div>

          <hr />

          <div>
            <div>
              <a href="/docs/api-reference/payments/latest/offline-payments/create-terminal">softPOS: Create Terminal</a>

              <p>
                Create a softPOS terminal for in-person card acceptance.
              </p>
            </div>
          </div>
        </div>
      </div>
    </div>
  </Tab>
</Tabs>

The videos below walk through testing Payment Gateway APIs in Postman and using this API reference.

<Columns>
  <div>
    <Frame>
      <iframe title="Testing in Postman" />
    </Frame>

    <p>
      Testing APIs in Postman
    </p>
  </div>

  <div>
    <Frame>
      <iframe title="Documentation walkthrough" />
    </Frame>

    <p>
      Documentation Walkthrough
    </p>
  </div>
</Columns>

## Getting started

Use the following resources to begin implementing Payment Gateway APIs:

<CardGroup>
  <Card title="Payment SDK" href="/docs/api-reference/payments/sdk" icon="puzzle-piece">
    Integrate the Payment Gateway with web, mobile, and server SDKs for orders, checkout, and tokenisation
  </Card>

  <Card title="API rate limits" href="/docs/api-reference/payments/rate-limits" icon="gauge-high">
    View default limits per minute, monitor usage on the dashboard, and request higher limits when needed
  </Card>
</CardGroup>


# Preauthorisation
Source: https://www.cashfree.com/docs/api-reference/payments/preauth-journey

Run the Cashfree preauthorisation flow in sandbox: create an order, hold funds on cards or UPI, and capture or void the authorised amount.

You can run through the full preauthorisation lifecycle in the **sandbox** environment using the same APIs as in production. For product behaviour, supported instruments, and capture or void rules, refer to [Preauthorisation](/docs/payments/features/pre-authorisation).

<Warning>
  In the **sandbox** environment, preauthorisation for API-driven flows works only for **card** and **UPI** when you use the seamless **link** channel on the [Order Pay](/docs/api-reference/payments/latest/payments/order-pay) API. Other payment modes are not supported in this sandbox preauthorisation path.
</Warning>

## Prerequisites

Ensure the following are in place before you start the sandbox flow:

* Use the sandbox base URL: `https://sandbox.cashfree.com/pg`.
* Send a supported API version in `x-api-version` (for example, `2025-01-01`), consistent with your integration.
* Use `x-client-id` and `x-client-secret` to authenticate calls to the [Create Order](/docs/api-reference/payments/latest/orders/create-order) API and the [Preauthorisation](/docs/api-reference/payments/latest/payments/preauthorisation) API. The [Order Pay](/docs/api-reference/payments/latest/payments/order-pay) API does not require these headers. You can call it directly from the client.

## Preauthorisation flow

Complete a preauthorisation transaction in the sandbox by following the three stages below.

### Create an order

For sandbox preauthorisation testing, set `order_note` to **`preauth_transaction`** in your [Create Order](/docs/api-reference/payments/latest/orders/create-order) API request. If this value is missing or incorrect, Cashfree may not recognise the order as a sandbox preauthorisation transaction.

```bash CURL highlight={16} theme={"dark"}
curl --request POST 'https://sandbox.cashfree.com/pg/orders' \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'x-api-version: 2025-01-01' \
  --header 'x-client-id: <your_client_id>' \
  --header 'x-client-secret: <your_client_secret>' \
  --data-raw '{
    "customer_details": {
      "customer_email": "customer@example.com",
      "customer_phone": "9999999999",
      "customer_name": "Test Customer",
      "customer_id": "customer_001"
    },
    "order_amount": 100,
    "order_currency": "INR",
    "order_note": "preauth_transaction",
    "order_meta": {
      "return_url": "https://example.com/return",
      "notify_url": "https://example.com/webhooks/cashfree"
    }
  }'
```

Save the **`order_id`** and **`payment_session_id`** from the response. You will need both values for the [Order Pay](/docs/api-reference/payments/latest/payments/order-pay) API.

<Note>
  `order_tags`, `order_meta`, and customer fields follow the usual [Create Order](/docs/api-reference/payments/latest/orders/create-order) API rules. Use a valid `notify_url` if you rely on [Payment Webhooks](/docs/api-reference/payments/latest/payments/webhooks) for payment status.
</Note>

### Initiate payment with Order Pay API

Send the [Order Pay](/docs/api-reference/payments/latest/payments/order-pay) API request (**`POST /orders/sessions`**) with the `payment_session_id` from the [Create Order](/docs/api-reference/payments/latest/orders/create-order) API. Set **`channel`** to **`link`** so the response returns a redirect URL for the customer.

#### Card payments (link channel)

Use the following request to initiate a card preauthorisation payment. Replace the placeholder card details with values from the [Data to Test Integration](/docs/api-reference/payments/data-to-test-integration) page.

```bash CURL theme={"dark"}
curl --request POST 'https://sandbox.cashfree.com/pg/orders/sessions' \
  --header 'Content-Type: application/json' \
  --header 'x-api-version: 2025-01-01' \
  --data '{
    "payment_session_id": "<payment_session_id_from_create_order>",
    "payment_method": {
      "card": {
        "channel": "link",
        "card_number": "4111111111111111",
        "card_expiry_mm": "06",
        "card_expiry_yy": "27",
        "card_cvv": "900",
        "card_holder_name": "Test User"
      }
    },
    "save_instrument": true
  }'
```

Open the URL returned under `data.url` (when `action` is `link`) to complete the payment in the browser.

#### UPI payments (link channel)

For UPI preauthorisation, set **`authorize_only`** to **`true`** and pass an **`authorization`** object with the following fields:

| Field | Description |
| :- | :- |
| `approve_by` | The deadline by which the customer must approve the request (ISO 8601 with offset, for example `2025-12-20T19:20:12+05:30`). |
| `start_time` | The time at which the hold or mandate window starts (ISO 8601, UTC `Z` allowed). |
| `end_time` | The time until which the hold applies (ISO 8601). You can capture or void using the [Preauthorisation](/docs/api-reference/payments/latest/payments/preauthorisation) API while the authorisation is valid, subject to [Preauthorisation](/docs/payments/features/pre-authorisation) product rules. |

```bash CURL theme={"dark"}
curl --request POST 'https://sandbox.cashfree.com/pg/orders/sessions' \
  --header 'Content-Type: application/json' \
  --header 'x-api-version: 2025-01-01' \
  --data '{
    "payment_session_id": "<payment_session_id_from_create_order>",
    "payment_method": {
      "upi": {
        "channel": "link",
        "authorize_only": true,
        "authorization": {
          "approve_by": "2025-12-20T19:20:12+05:30",
          "start_time": "2025-12-19T12:34:34Z",
          "end_time": "2026-01-01T12:34:34Z"
        }
      }
    }
  }'
```

Complete the UPI approval flow in sandbox using the test UPI VPA values from the [Data to Test Integration](/docs/api-reference/payments/data-to-test-integration) page.

### Capture or void the payment

Once you simulate the payment as successfully authorised in sandbox, call the [Preauthorisation](/docs/api-reference/payments/latest/payments/preauthorisation) API (`POST /orders/{order_id}/authorization`) with the same **`order_id`** you received when you created the order. Use either action below depending on whether you want to collect or release the funds:

<CodeGroup>
  ```bash Capture theme={"dark"}
  curl --request POST 'https://sandbox.cashfree.com/pg/orders/<order_id>/authorization' \
    --header 'Content-Type: application/json' \
    --header 'x-api-version: 2025-01-01' \
    --header 'x-client-id: <your_client_id>' \
    --header 'x-client-secret: <your_client_secret>' \
    --data '{
      "action": "CAPTURE",
      "amount": 100
    }'
  ```

  ```bash Void theme={"dark"}
  curl --request POST 'https://sandbox.cashfree.com/pg/orders/<order_id>/authorization' \
    --header 'Content-Type: application/json' \
    --header 'x-api-version: 2025-01-01' \
    --header 'x-client-id: <your_client_id>' \
    --header 'x-client-secret: <your_client_secret>' \
    --data '{
      "action": "VOID"
    }'
  ```
</CodeGroup>

You can send `amount` as a number or as a decimal string such as `"100.00"`. The amount must not exceed the authorised order amount. Cashfree supports partial capture. A void request does not require an amount.

You can capture or void each authorisation only once. For business rules such as time limits, refer to [Preauthorisation](/docs/payments/features/pre-authorisation).

## Go live

The sandbox flow above and the production flow use the same APIs. Two things change when you go live:

* **Base URL**: Replace `https://sandbox.cashfree.com/pg` with `https://api.cashfree.com/pg`.
* **`order_note`**: The value `preauth_transaction` is a **sandbox-only** flag that tells Cashfree to treat the order as a preauth test. In production, `order_note` follows your account configuration. Check with your integration or support. Contact if you already use this field for other purposes.

Before you process live transactions, ensure preauthorisation is enabled on your account. Submit a request through the [Preauthorisation feature request](/docs/payments/features/pre-authorisation#preauthorisation-feature-request) form.

## Best practices

Follow these practices when integrating preauthorisation in sandbox and production:

* **Confirm authorisation before capturing or voiding:** Do not call capture or void based on a client-side redirect alone. Set `order_meta.notify_url` in the [Create Order](/docs/api-reference/payments/latest/orders/create-order) API and wait for the authorisation-success event via [Payment Webhooks](/docs/api-reference/payments/latest/payments/webhooks) on your server before you proceed.

* **Use idempotency keys for capture and void requests:** Each authorisation can be captured or voided only once. If a network error leaves the outcome uncertain, resend the same request with the **`x-idempotency-key`** header so Cashfree returns the original result instead of rejecting a duplicate. Refer to [API Best Practices](/docs/api-reference/api-best-practices) for usage details.

* **Capture within the time limit:** If you do not capture or void an authorisation within seven days, the hold expires and the funds are released to the customer automatically. Build a reminder or scheduled job so authorised orders do not go unresolved. Refer to [Preauthorisation](/docs/payments/features/pre-authorisation) for the full set of timing rules.


# End Points
Source: https://www.cashfree.com/docs/api-reference/payments/previous/subscriptionsv1/endpoints

Get the production and test base URLs for the legacy Subscriptions v1 APIs, plus the API key authentication details you need to send requests.

Cashfree uses API keys to allow access to the API. Once you have signed up at our merchant site, you will see your AppId and SecretKey.

Cashfree expects the API key to be included in all API requests to the server. Use the endpoint **/api/v1/credentials/verify** to verify your credentials.

All API responses are in JSON format. POST requests should include ContentType: application/json

| Environment | Base URL |
| :- | :- |
| Production | [https://api.cashfree.com/](https://api.cashfree.com/) |
| Test | [https://test.cashfree.com/](https://test.cashfree.com/) |


# Physical Mandates
Source: https://www.cashfree.com/docs/api-reference/payments/previous/subscriptionsv1/physical-mandates

Use the Cashfree Subscriptions v1 APIs to create and manage physical NACH mandates using customer signature and bank account details.

Physical mandate is the process of authorisation where the customer requires only their signature and bank account details. There is no requirement to have a Debit Card or Netbanking enabled to set up the mandate. Read more about [Physical Mandates](/docs/payments/subscription/payment-modes#bank-account-physical-mandate).

List of Physical Mandates APIs

| API name | Description |
| :- | :- |
| [Create Seamless Subscription API](/docs/api-reference/payments/previous/subscriptionsv1/seamless-apis/create-seamless-subscription-with-plan-id) | Use this API to create a subscription by providing a custom payment experience to your customers by specifying the plan ID and the customer details. You can also specify the bank account information when you create the subscription to ensure that mandates are created via the specified bank account only. TPV is applicable only for eNACH and UPI. |
| [Upload File](/docs/api-reference/payments/previous/subscriptionsv1/seamless-apis/create-authorization-request) | Use this API to upload the Physical Nach registration forms that contain your customer’s bank account details and signature. Use the fileId you get in the response in the "Create Auth Seamless PhysicalMandate API". |
| [Create Auth Seamless Physical Mandate](/docs/api-reference/payments/previous/subscriptionsv1/seamless-apis/get-authorization-status) | Use this API to create an Authorisation request for your customer. For Physical mandates, this API lets Cashfree know that the nach form is to be raised to the bank for successfully registering the mandate in production. |
| [Update Authorisation Status](/docs/api-reference/payments/previous/subscriptionsv1/seamless-apis/update-authorization-status) | Use this API to update the status of the authorisation from INITIALIZED to SUCCESS or FAILED. Provide the authID and the payment status. This is applicable only in the test environment. |


# Rate Limits
Source: https://www.cashfree.com/docs/api-reference/payments/previous/subscriptionsv1/rate-limits

Understand the per-minute rate limits for Cashfree Subscriptions v1 APIs and how to avoid throttling on recurring payment calls.

The rate limit value shows the number of API calls that were made in a minute. For example, if the rate limit is 400 - it means you can call a maximum of 400 API calls in a minute.

**Rate Limits in Sandbox & Production:**\
We use rate limiting for all endpoints. Rate limiting is based on your IP and your account Id. By default, the following rate limits are applied per minute.

| API | Rate limit value per minute | Rate limit type |
| :- | :- | :- |
| [Create Plan](/docs/api-reference/payments/latest/subscription/create-a-plan) | 60 | Account |
| [Create Subscription](/docs/api-reference/payments/previous/subscriptionsv1/subscription/create-a-subscription) | 60 | Account |
| [Create Seamless Subscription](/docs/api-reference/payments/previous/subscriptionsv1/seamless-apis/create-seamless-subscription-with-plan-id) | 60 | Account |
| [Get Subscription Details](/docs/api-reference/payments/previous/subscriptionsv1/subscription/get-subscription-details) | 60 | Account |
| [Get All Subscription Payments](/docs/api-reference/payments/previous/subscriptionsv1/subscription/fetch-subscription-payments) | 60 | Account |
| [Get Single Subscription Payment](/docs/api-reference/payments/previous/subscriptionsv1/subscription/fetch-single-subscription-payment) | 60 | Account |
| [Cancel Charge](/docs/api-reference/payments/previous/subscriptionsv1/subscription/cancel-subscription-charge) | 60 | Account |
| [Charge Subscription](/docs/api-reference/payments/previous/subscriptionsv1/subscription/charge-subscription) | 60 | Account |
| [Charge Retry](/docs/api-reference/payments/previous/subscriptionsv1/subscription/retry-subscription-charge) | 60 | Account |
| [Activate Subscription](/docs/api-reference/payments/previous/subscriptionsv1/subscription/activate-subscription) | 60 | Account |
| [Get Payment Details using Merchant Txn ID](/docs/api-reference/payments/previous/subscriptionsv1/subscription/fetch-payment-by-merchant-transaction-id) | 60 | Account |
| [Update Recurring-amount](/docs/api-reference/payments/previous/subscriptionsv1/subscription/update-recurring-amount) | 60 | Account |


# Redirection Payload After Authorisation
Source: https://www.cashfree.com/docs/api-reference/payments/previous/subscriptionsv1/redirection-payload-after-authorization

Understand the POST parameters Cashfree returns to your subscription `returnUrl` once the customer authorises on Subscriptions v1 APIs.

## Request configuration

| Method | Parameter type | URL |
| - | - | - |
| cf\_subReferenceId | Long | Unique Id which was generated when the subscription was created (Numeric) |
| cf\_subscriptionId | String | Checksum used to authenticate the transaction |
| cf\_authAmount | Float | The money that was charged to authorise the subscription |
| cf\_referenceId | Long | The referenceId/transactionId of authorisation in PG |
| cf\_status | String | Status of the subscription. In the returnUrl, the response should be ACTIVE or BANK\_APPROVAL\_PENDING if the authorisation was successful or INITIALIZED if the authorisation failed. |
| cf\_message | String | A brief note about the payment. |
| signature | String | The hash of all parameters in the request generated using secretKey. |
| cf\_umrn | String | The unique identifier associated with a mandate. Applicable if the payment mode is eMandate. |
| cf\_checkoutStatus | String | The subscription checkout status. The status can be SUCCESS, FAILED, SUCCESS\_DEBIT\_PENDING, SUCCESS\_TOKENIZATION\_PENDING. (This parameter will be sent from the 1st of November onwards, by default. It is available in the test environment.) |
| cf\_mode | String | The checkout payment mode. Modes - NPCI\_SBC, SBC\_UPI, SBC\_CREDIT\_CARD, SBC\_DEBIT\_CARD. (This parameter will be sent from the 1st of November onwards, by default. It is available in the test environment.) |
| cf\_subscriptionPaymentId | String | The subscription payment ID. (This parameter will be sent from the 1st of November onwards, by default. It is available in the test environment.) |
| cf\_umn | String | The unique identifier is associated with a mandate. This is applicable if the payment mode is **UPI**. |

<Warning> 🚧 **Return URL**
Once your customer has completed the checkout on the OTP page, we will redirect them back to your `return_url`. This will be a link-based redirection, so if you have provided a return\_url of the format - `https://b8af79f41056.eu.ngrok.io?order_id={order_id}` - your customer will be redirected to the URL - `https://b8af79f41056.eu.ngrok.io?order_id=order_271vfuhh1o4h6bQIigqyOx74YiJ1T`. </Warning>


# Create Authorization Request
Source: https://www.cashfree.com/docs/api-reference/payments/previous/subscriptionsv1/seamless-apis/create-authorization-request

post /api/v2/subscriptions/seamless/authorization
Use this API to create an authorisation request for a particular subscription. This API is applicable only if you have created a subscription via Create Seamless Subscription API. Use the response of the Create Seamless Subscription API to get the supported banks for E_MANDATE and supported UPI handles.



# Create Seamless Subscription with Plan ID
Source: https://www.cashfree.com/docs/api-reference/payments/previous/subscriptionsv1/seamless-apis/create-seamless-subscription-with-plan-id

post /api/v2/subscriptions/seamless/subscription
Use this API to create a subscription by providing a custom payment experience to your customers by specifying the plan ID and the customer details. You can also specify the bank account information when you create the subscription to ensure that mandates are created via the specified bank account only. TPV is applicable only for eNACH and UPI.



# Get Authorization Status
Source: https://www.cashfree.com/docs/api-reference/payments/previous/subscriptionsv1/seamless-apis/get-authorization-status

get /api/v2/subscriptions/seamless/authorization/{authId}/poll
Use this API to fetch the status of the authorisation request. Provide the authID that is available in the Create Auth API response. This API is applicable only if you have created a subscription using the Create Seamless Subscription API



# Update Authorization Status
Source: https://www.cashfree.com/docs/api-reference/payments/previous/subscriptionsv1/seamless-apis/update-authorization-status

post /api/v2/subscriptions/seamless/authorization/simulate
Use this API to update the status of the authorisation from INITIALIZED to SUCCESS or FAILED. Provide the authID and the payment status. This is applicable only in the test environment.



# Postman Collection
Source: https://www.cashfree.com/docs/api-reference/payments/previous/subscriptionsv1/subscription-postman-collection

Download the ready-made Postman collection for the legacy Subscriptions v1 APIs and start testing mandate, charge, and refund calls in minutes.

Get started quickly with Cashfree's Subscription APIs by downloading the collection and importing it in Postman.

<a href="https://documenter.getpostman.com/view/21543638/2s93sf3rJB">Download Cashfree Subscription Postman Collection</a>


# Create Subscription Refund
Source: https://www.cashfree.com/docs/api-reference/payments/previous/subscriptionsv1/subscription-refund/create-subscription-refund

post /api/v2/subscriptions/create-refund
Use this API to create a refund for the payment of a Subscription. Only one of paymentId or merchantTxnId should be passed. If both are passed then the request will be rejected.



# Get Subscription Refund Details
Source: https://www.cashfree.com/docs/api-reference/payments/previous/subscriptionsv1/subscription-refund/get-subscription-refund-details

get /api/v2/subscriptions/refund-details
Use this API to fetch the status of the refund of a Subscription. Only one of paymentId or merchantRefundId should be passed as query parameter. If both are passed then the request will be rejected.



# Overview
Source: https://www.cashfree.com/docs/api-reference/payments/previous/subscriptionsv1/subscription-refund/refund-apis-overview

Use the Cashfree Subscriptions v1 APIs to initiate, retrieve, and reconcile refunds on recurring payments.

## List of subscription refund APIs

| API name | Description |
| :- | :- |
| [Create Refund](/docs/api-reference/payments/previous/subscriptionsv1/subscription-refund/create-subscription-refund) | Use this API to create a refund for the payment of a Subscription. |
| [Get Refund](/docs/api-reference/payments/previous/subscriptionsv1/subscription-refund/get-subscription-refund-details) | Use this API to fetch the status of the refund of a Subscription. |


# Activate Subscription
Source: https://www.cashfree.com/docs/api-reference/payments/previous/subscriptionsv1/subscription/activate-subscription

post /api/v2/subscriptions/{subReferenceId}/activate
Use this API to activate a subscription that is in ONHOLD state. For periodic subscriptions, the next charge date is calculated for the next cycle.



# Cancel Subscription
Source: https://www.cashfree.com/docs/api-reference/payments/previous/subscriptionsv1/subscription/cancel-subscription

post /api/v2/subscriptions/{subReferenceId}/cancel
Use this API to cancel the subscription. After a successful cancellation, the subscription status will move to "CANCELLED", and the customer will no longer be charged. Subscription, once cancelled, cannot be reactivated.



# Cancel Subscription Charge
Source: https://www.cashfree.com/docs/api-reference/payments/previous/subscriptionsv1/subscription/cancel-subscription-charge

post /api/v2/subscription/{subReferenceId}/charge/{chargeId}/cancel
Use this API to cancel a transaction that is in the INITIALIZED state.



# Charge Subscription
Source: https://www.cashfree.com/docs/api-reference/payments/previous/subscriptionsv1/subscription/charge-subscription

post /api/v2/subscriptions/{subReferenceId}/charge
Charge a specific subscription using the provided subscription reference ID.



# Create a Subscription
Source: https://www.cashfree.com/docs/api-reference/payments/previous/subscriptionsv1/subscription/create-a-subscription

post /api/v2/subscriptions/nonSeamless/subscription
Use this API to create a subscription by specifying the plan ID or plan Info and customer details.You can also specify the bank account information when you create the subscription to ensure that mandates are created via the specified bank account only. TPV is applicable only for eNACH and UPI Autopay. The Auth Link received in the response will be redirected to a link hosted on cashfree.com. Once the authorization is complete, your customer will be redirected to returnUrl. Store the subReferenceId as this is the unique ID generated by Cashfree for the subscription and will be required for subsequent operations.



# Create a Subscription Plan
Source: https://www.cashfree.com/docs/api-reference/payments/previous/subscriptionsv1/subscription/create-a-subscription-plan

post /api/v2/subscription-plans
Use this API to create a new plan. Provide the planId, planName, and the plan type(PERIODIC/ON_DEMAND).



# Fetch Payment by Merchant Transaction ID
Source: https://www.cashfree.com/docs/api-reference/payments/previous/subscriptionsv1/subscription/fetch-payment-by-merchant-transaction-id

get /api/v2/subscriptions/payments/merchantTxnId/{merchantTxnId}
Fetch details of a specific payment associated with a given merchant transaction ID.



# Fetch Single Subscription Payment
Source: https://www.cashfree.com/docs/api-reference/payments/previous/subscriptionsv1/subscription/fetch-single-subscription-payment

get /api/v2/subscriptions/{subReferenceId}/payments/{paymentId}
Fetch details of a specific payment associated with a subscription reference ID.



# Fetch Subscription Payments
Source: https://www.cashfree.com/docs/api-reference/payments/previous/subscriptionsv1/subscription/fetch-subscription-payments

get /api/v2/subscriptions/{subReferenceId}/payments
Fetch all payments associated with a specific subscription reference ID.



# Generate Transaction Return Summary
Source: https://www.cashfree.com/docs/api-reference/payments/previous/subscriptionsv1/subscription/generate-transaction-return-summary

post /api/v2/subscriptions/charge/{paymentId}/transaction-return-summary/generate
Use this API to generate transaction return summary for failed transactions (insufficient balance). You will have to hit the API again to check the status of the transaction return summary, or go to the [Merchant Dashboard](https://merchant.cashfree.com/merchants) and download the same.



# Get Subscription Details
Source: https://www.cashfree.com/docs/api-reference/payments/previous/subscriptionsv1/subscription/get-subscription-details

get /api/v2/subscriptions/{subReferenceId}
Fetch the details of a subscription for a specific subscription reference ID.



# Pause Subscription
Source: https://www.cashfree.com/docs/api-reference/payments/previous/subscriptionsv1/subscription/pause-subscription

put /api/v2/subscriptions/{subReferenceId}/pause-subscription
Use this API to temporarily pause a subscription. Once this API is called, the subscription status will be updated to "PAUSED". Only a periodic subscription can be paused. To reactivate the subscription, you can use the Activate Subscription API.



# Port Mandate
Source: https://www.cashfree.com/docs/api-reference/payments/previous/subscriptionsv1/subscription/port-mandate

post /api/v2/subscriptions/mandate/port
Use this API to import an existing mandate into the Cashfree subscription system. This is applicable where mandates are already created with another provider or system. By porting the mandate, you can manage the subscription within Cashfree's ecosystem.



# Retry Subscription Charge
Source: https://www.cashfree.com/docs/api-reference/payments/previous/subscriptionsv1/subscription/retry-subscription-charge

post /api/v2/subscriptions/{subReferenceId}/charge-retry
Applicable only for Periodic Subscriptions. Use this API to retry the last failed payment for a subscription in ON HOLD state. On a successful retry, the subscription gets activated. Use the Retry API when the subscription debit has failed at your customer's end. Only one retry attempt is allowed per day and 3 retry attempts are allowed for a failed transaction within the cycle. Retry is not allowed if the current cycle expires.



# Update Charge Status
Source: https://www.cashfree.com/docs/api-reference/payments/previous/subscriptionsv1/subscription/update-charge-status

put /api/v2/subscriptions/charge/{paymentId}/simulate
Use this API to update the status of the charge from PENDING to SUCCESS or FAILED. This is applicable only in the test environment.



# Update Recurring Amount
Source: https://www.cashfree.com/docs/api-reference/payments/previous/subscriptionsv1/subscription/update-recurring-amount

put /api/v2/subscriptions/{subReferenceId}/recurring-amount
Update the recurring amount for a specific subscription reference ID.



# Upload Physical Mandate File
Source: https://www.cashfree.com/docs/api-reference/payments/previous/subscriptionsv1/subscription/upload-physical-mandate-file

post /api/v2/subscriptions/physical-mandate-file/upload
Use this API to upload the Physical Nach registration forms that contain your customer’s bank account details and signature. Use the fileId you get in the response in the "Create Auth Seamless PhysicalMandate API".



# Webhooks
Source: https://www.cashfree.com/docs/api-reference/payments/previous/subscriptionsv1/webhooks

Learn how Cashfree sends server callbacks for Subscriptions v1 events so you can react to mandate, charge, and refund status changes in real time.

## Configure webhook

* You can now configure webhooks from the [Merchant Dashboard](https://merchant.cashfree.com/auth/login). See [Configure webhooks](/docs/payments/online/webhooks/configure) to know how to add a new webhook.
* Ensure you do not process duplicate events.

Webhooks will be sent to your configured endpoint as a POST request with the body containing the various parameters specifying the details of each event. Each request contains an event parameter that identifies its type.

Below are the various events that can be sent to your webhook endpoint.

* SUBSCRIPTION\_STATUS\_CHANGE
* SUBSCRIPTION\_NEW\_PAYMENT
* SUBSCRIPTION\_PAYMENT\_CANCELLED
* SUBSCRIPTION\_PAYMENT\_DECLINED
* SUBSCRIPTION\_AUTH\_STATUS
* REFUND\_STATUS

## SUBSCRIPTION\_STATUS\_CHANGE

<Note> The parameters "cf\_subscriptionId" will be available from 31st July 2023 onwards. </Note>

| Parameter | Type | Description |
| :- | :- | :- |
| cf\_event | String | This event is triggered whenever the subscription status changes. The value for this event is SUBSCRIPTION\_STATUS\_CHANGE. |
| cf\_subReferenceId | Integer | A unique Id which was generated when the subscription was created. |
| cf\_status | String | The new status of the subscription. See [Subscription lifecycle](/docs/payments/subscription/create#subscription-lifecycle) for information on subscription statuses. |
| cf\_lastStatus | String | The old status of the subscription. See [Subscription lifecycle](/docs/payments/subscription/create#subscription-lifecycle) for information on subscription statuses. |
| cf\_eventTime | String \[format - yyyy-MM-dd HH:mm:ss] | The time when the event was dispatched. |
| cf\_subscriptionId | String | The subscription Id passed by the merchant while creating the subscription |
| signature | String | A unique string which helps distinguish that the request is genuine and initiated by Cashfree. See [Verify signature](#verify-signature) for more information. |

***

## SUBSCRIPTION\_NEW\_PAYMENT

<Note> The parameters "cf\_subscriptionId" and "cf\_merchantTxnId" will be available from 31st July 2023 onwards. </Note>

| Parameter | Type | Description |
| :- | :- | :- |
| cf\_event | String | This event is triggered whenever there is a successful new payment for an authorised subscription. The value for this event is SUBSCRIPTION\_NEW\_PAYMENT. |
| cf\_subReferenceId | Integer | A unique Id which was generated when the subscription was created. |
| cf\_eventTime | String \[format - yyyy-MM-dd HH:mm:ss] | The time when the event was dispatched. |
| cf\_orderId | String | The unique order ID against which the payment is made. |
| cf\_paymentId | Integer | The unique paymentId for the payment. |
| cf\_amount | Float | The amount charged for payment. |
| cf\_subscriptionId | String | The subscription Id passed by the merchant while creating the subscription |
| cf\_merchantTxnId | String | An id unique to the transaction that merchant passed while raising a transaction for a subscription. |
| cf\_referenceId | Integer | The unique txnId for the payment. |
| cf\_retryAttempts | Integer | The number of payment retries. This is applicable for failed payments. |
| signature | String | A unique string which helps distinguish that the request is genuine and initiated by Cashfree. See [Verify signature](#verify-signature) for more information. |

***

## SUBSCRIPTION\_PAYMENT\_CANCELLED

<Note> The parameters "cf\_subscriptionId" and "cf\_merchantTxnId" will be available from 31st July 2023 onwards.</Note>

| Parameter | Type | Description |
| :- | :- | :- |
| cf\_event | String | This webhook is triggered when the charge is cancelled. The value for this event is PAYMENT\_CANCELLED\_WEBHOOK. |
| cf\_subReferenceId | Integer | A unique ID which was generated when the subscription was created. |
| cf\_eventTime | String \[format - yyyy-MM-dd HH:mm:ss] | The time when the event was dispatched. |
| orderId | String | The unique order ID against which the payment is made. |
| paymentId | Integer | The unique paymentId for the payment. |
| amount | Float | The amount charged for payment. |
| subscriptionId | String | The subscription Id passed by the merchant while creating the subscription |
| merchantTxnId | String | An id unique to the transaction that the merchant passed while raising a transaction for a subscription. |
| referenceId | Integer | The unique txnId for the payment. |
| retryAttempts | Integer | The number of payment retries. This is applicable for failed payments. |
| reasons | String | Failure reason |
| signature | String | A unique string which helps distinguish that the request is genuine and initiated by Cashfree. See [Verify signature](#verify-signature) for more information. |

***

## SUBSCRIPTION\_PAYMENT\_DECLINED

<Note> The parameters "cf\_subscriptionId" and "cf\_merchantTxnId" will be available from 31st July 2023 onwards.</Note>

| Parameter | Type | Description |
| :- | :- | :- |
| cf\_event | String | This event is triggered whenever a payment fails for an authorised subscription. The value for this event is SUBSCRIPTION\_PAYMENT\_DECLINED. |
| cf\_subReferenceId | Integer | A unique Id which was generated when the subscription was created. |
| cf\_eventTime | String \[format - yyyy-MM-dd HH:mm:ss] | The time when the event was dispatched. |
| cf\_paymentId | Integer | The unique paymentId for the payment. |
| cf\_amount | Float | The amount charged for payment. |
| cf\_subscriptionId | String | The subscription Id passed by the merchant while creating the subscription |
| cf\_merchantTxnId | String | An id unique to the transaction that merchant passed while raising a transaction for a subscription. |
| cf\_referenceId | Integer | The unique txnId for the payment. |
| cf\_retryAttempts | Integer | The number of payment retries. This is applicable for failed payments. |
| cf\_reasons | String | A possible reason for failure. |
| signature | String | A unique string which helps distinguish that the request is genuine and initiated by Cashfree. See [Verify signature](#verify-signature) for more information. |

***

## SUBSCRIPTION\_AUTH\_STATUS

<Note> The parameters "cf\_subscriptionId" and "cf\_merchantTxnId" will be available from 31st July 2023 onwards.</Note>

The event is triggered when the checkout is completed by the customer for success and failed cases.

| Parameter | Type | Description |
| :- | :- | :- |
| cf\_event | String | The event is triggered when the checkout fails The value for this event is SUBSCRIPTION\_AUTH\_STATUS. |
| cf\_subReferenceId | Integer | A unique Id which was generated when the subscription was created. |
| cf\_eventTime | String \[format - yyyy-MM-dd HH:mm:ss] | The time when the event was dispatched. |
| cf\_subscriptionStatus | String | The status of the subscription. See [Subscription lifecycle](/docs/payments/subscription/create#subscription-lifecycle) for information on subscription statuses. |
| cf\_authStatus | String | Checkout status. Allowed value: FAILED |
| cf\_subscriptionId | String | The subscription Id passed by the merchant while creating the subscription |
| cf\_merchantTxnId | String | An id unique to the transaction that merchant passed while raising a transaction for a subscription. |
| cf\_authTimestamp | String \[format - yyyy-MM-dd HH:mm:ss] | Checkout initiated timestamp. |
| cf\_authFailureReason | String | Possible checkout failure. It will be empty for successFul authStatus change. |
| signature | String | A unique string which helps distinguish that the request is genuine and initiated by Cashfree. See [Verify signature](#verify-signature) for more information. |

***

## REFUND\_STATUS

| Parameter | Type | Description |
| :- | :- | :- |
| cf\_event | String | This event is triggered whenever a refundStatus of a transaction will be success or failed or cancelled. The value for this event is REFUND\_STATUS\_WEBHOOK. |
| cf\_subReferenceId | Integer | A unique Id that was generated when the subscription was created. |
| cf\_eventTime | String \[format - yyyy-MM-dd HH:mm:ss] | The time when the event was dispatched. |
| cf\_sub\_refund\_id | String | A unique ID that is generated for every refund at the initialisation of refund state. |
| cf\_payment\_id | Integer | The unique payment ID for the payment. |
| cf\_refund\_amount | BigDecimal | The amount that is to be refunded |
| cf\_refund\_id | Integer | The refund ID is a unique ID generated when processing a refund. |
| cf\_merchant\_refund\_id | String | A unique ID for the transaction that merchant passed while raising a refund. |
| cf\_refund\_status | String | Refund status of the transaction. |
| signature | String | A unique string which helps distinguish that the request is genuine and initiated by Cashfree. See [Verify signature](#verify-signature) for more information |

***

## Verify signature

Verifying the signature (passed along with the POST parameters) is mandatory before you process any response. We also recommend whitelisting only our IP address on your webhook endpoint.

Follow the steps below to calculate & verify the signature on the webhook payload:

1. Please sort the webhook payload in alphabetical order based on fields which are starting with field cf\_.
2. Append the key-value pair w/o using any delimiter and create a string.
3. Hash the string using the secret key which will be provided to you.
4. Encode the hashed string using base64 and generate the signature.

**Example** :

1. Sample web hook payload -
   ```
   {
      "cf_retryAttempts":0,
      "cf_amount":1,
      "cf_event":"SUBSCRIPTION_NEW_PAYMENT",
      "cf_eventTime":"2022-01-10 10:03:50",
      "cf_paymentId":1,
      "cf_referenceId":2,
      "cf_subReferenceId":3,
      "signature":"tT9pXZkT2LuDzXacYDUaur7EX3dJgNKcITHQng44tns="
   }
   ```

2. Sorted web hook payload - <pre><code>cf\_amount1cf\_eventSUBSCRIPTION\_NEW\_PAYMENTcf\_eventTime2022-01-10 10:51:02cf\_paymentId1cf\_referenceId2cf\_retryAttempts0cf\_subReferenceId3</code></pre>

3. Signature generated using encoding with secret key - <pre><code>tT9pXZkT2LuDzXacYDUaur7EX3dJgNKcITHQng44tns=</code></pre>

4. Generated signature should match the signature present in the webhook payload.

Following code snippets show you how to generate and verify the signature. This should not be assumed production-ready, kindly consider adding necessary validation before processing.

<CodeGroup>
  ```java Java theme={"dark"}
  import javax.crypto.Mac;
  import javax.crypto.spec.SecretKeySpec;
  import java.util.*;
  public class SignatureVerification {
      private static final String MAC_SHA256_ALGO = "HmacSHA256";
      private static final String SECRET_KEY = "ac7960e7995536f0177fd210f3b3937fc2d974a4"; // Merchant secret key
      public boolean verifySignature(Map<String, Object> payload) {
          String signature = String.valueOf(payload.get("signature"));
          String computedSignature = generateSignature(payload);
          return signature != null && signature.equals(computedSignature);
      }
      public String generateSignature(Map<String, Object> payload) {
          try {
              StringBuilder data = new StringBuilder();
              SortedSet<String> keys = new TreeSet<>(payload.keySet());
              for (String key : keys) {
                  if (key.startsWith("cf_")) {
                      data.append(key).append(String.valueOf(payload.get(key)));
                  }
              }
              Mac mac = Mac.getInstance(MAC_SHA256_ALGO);
              SecretKeySpec secretKeySpec = new SecretKeySpec(SECRET_KEY.getBytes(), MAC_SHA256_ALGO);
              mac.init(secretKeySpec);
              byte[] encrypted = mac.doFinal(data.toString().getBytes());
              return Base64.getEncoder().encodeToString(encrypted);
          } catch (Exception ex) {
              // handle
          }
      }

  }
  ```

  ```php PHP theme={"dark"}
  <?php
  class SignatureVerification {
      private const MAC_SHA256_ALGO = 'sha256';
      private const SECRET_KEY = 'ac7960e7995536f0177fd210f3b3937fc2d974a4'; // Merchant secret key
      public function verifySignature(array $payload): bool {
          $signature = $payload['signature'] ?? '';
          $computedSignature = $this->generateSignature($payload);   
          return !empty($signature) && $signature === $computedSignature;
      }
      public function generateSignature(array $payload): string {
          try {
              $data = '';
              ksort($payload);

              foreach ($payload as $key => $value) {
                  if (strpos($key, 'cf_') === 0) {
                      $data .= $key . strval($value);
                  }
              }
              $hmac = hash_hmac(self::MAC_SHA256_ALGO, $data, self::SECRET_KEY, true);
              return base64_encode($hmac);
          } catch (Exception $ex) {
              // Handle exception (log it, throw error, etc.)
              return '';
          }
      }
  }
  ?>
  ```

  ```python Python theme={"dark"}
  import hmac
  import hashlib
  import base64
  from collections import OrderedDict
  class SignatureVerification:
      MAC_SHA256_ALGO = "sha256"
      SECRET_KEY = "ac7960e7995536f0177fd210f3b3937fc2d974a4"  # Merchant secret key
      def verify_signature(self, payload: dict) -> bool:
          signature = str(payload.get("signature", ""))
          computed_signature = self.generate_signature(payload)
          return signature == computed_signature
      def generate_signature(self, payload: dict) -> str:
          try:
              data = "".join(f"{key}{payload[key]}" for key in sorted(payload.keys()) if key.startswith("cf_"))  
              mac = hmac.new(self.SECRET_KEY.encode(), data.encode(), hashlib.sha256)
              return base64.b64encode(mac.digest()).decode()
          except Exception as ex:
              print(f"Error generating signature: {ex}")
              return ""
  ```
</CodeGroup>

**Failure Reasons**

| Code | Reason |
| :- | :- |
| AP01 | Account Blocked |
| AP02 | Account Closed |
| AP03 | Account Frozen |
| AP04 | Account Inoperative |
| AP05 | No Such Account |
| AP06 | Not a SBS account number or old account number represent with CBS number |
| AP07 | Refer to the branch KYC not completed |
| AP11 | Authentication Failed |
| AP14 | Invalid user credentials |
| AP15 | Mandate not registered\_ not maintaining required balance |
| AP16 | Mandate not registered\_ minor account |
| AP17 | Mandate not registered\_ NRE Account |
| AP18 | Mandate registration not allowed for CC account |
| AP19 | Mandate registration not allowed for PF account |
| AP20 | Mandate registration not allowed for PPF account |
| AP23 | Transaction rejected or cancelled by customer |
| AP24 | Account not in regular Status |
| AP25 | Withdrawal stopped due to insolvency of account |
| AP28 | Mandate registration failed. Please contact your home branch |
| AP29 | Technical errors or connectivity issues as bank |
| AP30 | Browser closed by customer in mid-transaction |
| AP31 | Mandate registration not allowed for joint account |
| AP32 | Mandate registration not allowed for wallet account |
| AP33 | User rejected the transaction on pre-login page |
| AP34 | Account number not registered with net-banking facility |
| AP35 | Debit card validation failed due to\_ Invalid card number |
| AP36 | Debit card validation failed due to\_ Invalid expiry date |
| AP37 | Debit card validation failed due to\_ Invalid PIN |
| AP38 | Debit card validation failed due to\_ Invalid CVV |
| AP39 | OTP invalid |
| AP40 | Maximum retries exceeded for OTP |
| AP41 | Time expired for OTP |
| AP42 | Debit card not activated |
| AP43 | Debit card blocked |
| AP44 | Debit card hot listed |
| AP45 | Debit card expired |
| AP46 | No response received from customer while performing transaction |
| AP47 | Account number registered for only view rights in net banking facility. |

<Note> We send the webhook response in a form data format.</Note>


# Get Eligible Cardless EMI
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2022-09-01/eligibility/get-eligible-cardless-emi

openapi/payments/v2022-09-01.yaml post /eligibility/cardlessemi
Use this API to get eligible Cardless EMI Payment Methods available for a customer on an order basis their phone number.



# Get Eligible Offers
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2022-09-01/eligibility/get-eligible-offers

openapi/payments/v2022-09-01.yaml post /eligibility/offers
Use this API to get eligible offers for an order_id or order amount.



# Get Eligible Paylater
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2022-09-01/eligibility/get-eligible-paylater

openapi/payments/v2022-09-01.yaml post /eligibility/paylater
Use this API to get eligible Paylater Payment Methods for a customer on an order.



# Get Eligible Payment Methods
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2022-09-01/eligibility/get-eligible-payment-methods

openapi/payments/v2022-09-01.yaml post /eligibility/payment_methods
Use this API to get eligible Payment Methods



# Create Offer
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2022-09-01/offers/create-offer

openapi/payments/v2022-09-01.yaml post /offers
Use this API to create offers with Cashfree from your backend



# Get Offer by ID
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2022-09-01/offers/get-offer-by-id

openapi/payments/v2022-09-01.yaml get /offers/{offer_id}
Use this API to get offer by offer_id



# Create Order
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2022-09-01/orders/create-order

openapi/payments/v2022-09-01.yaml post /orders
### Order
An order is an entity which has a amount and currency associated with it. It is something for which you want to collect payment for.
Use this API to create orders with Cashfree from your backend to get a `payment_sessions_id`. 
You can use the `payment_sessions_id` to create a transaction for the order.




# Get Order
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2022-09-01/orders/get-order

openapi/payments/v2022-09-01.yaml get /orders/{order_id}
Use this API to fetch the order that was created at Cashfree's using the `order_id`. 
## When to use this API
- To check the status of your order
- Once the order is PAID
- Once your customer returns to `return_url`




# Overview
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2022-09-01/overview

Explore the 2022-09-01 version of the Cashfree Payment Gateway APIs, including orders, payments, refunds, settlements, and reconciliation endpoints.

<Note>
  Use the latest version of our APIs [v2026-01-01](/docs/api-reference/payments/latest/overview) for any new integrations.
</Note>

## Payment Gateway end points

| Environment | Base URL |
| :- | :- |
| Test | [https://sandbox.cashfree.com/pg](https://sandbox.cashfree.com/pg) |
| Production | [https://api.cashfree.com/pg](https://api.cashfree.com/pg) |
| Latest Version | v3, 2022-09-01 <br /> The previous versions were 2021-05-21,2022-01-01 |

## Authentication

All the APIs require authentication, except the /orders/sessions API, which does not require any authentication and can be safely done from the browser as well.

Click [here](/docs/api-reference/authentication) for detailed information on API Authentication for Merchants and Partners.

## Payment Gateway APIs

### Orders

| API | Description |
| :- | :- |
| [Create Order](/docs/api-reference/payments/previous/v2022-09-01/orders/create-order) | Use this API to create orders with Cashfree from your backend and get the payment link. |
| [Order Pay](/docs/api-reference/payments/previous/v2022-09-01/payments/order-pay) | Use this API when you have already created the orders and want Cashfree to process the payment. |
| [Preauthorization](/docs/api-reference/payments/previous/v2022-09-01/payments/preauthorization) | Use this API to capture or void a preauthorized payment. |
| [Get Order](/docs/api-reference/payments/previous/v2022-09-01/orders/get-order) | Use this API to view all details of an order. |

### Authentication

| API | Description |
| :- | :- |
| [Submit or Resend OTP](/docs/api-reference/payments/previous/v2022-09-01/payments/submit-or-resend-otp) | Use the submit or resend OTP API to send OTP to Cashfree. |

### Payments

| API | Description |
| :- | :- |
| [Get Payments for an Order](/docs/api-reference/payments/previous/v2022-09-01/payments/get-payments-for-an-order) | Use this API to view all payment details for an order. |
| [Get Payment by ID](/docs/api-reference/payments/previous/v2022-09-01/payments/get-payment-by-id) | Use this API to view payment details of an order for a payment ID. |

### Settlements

| API | Description |
| :- | :- |
| [Get Settlements by Order ID](/docs/api-reference/payments/previous/v2022-09-01/settlements/get-settlements-by-order-id) | Use this API to view all the settlements of a particular order. |
| [Get All Settlements](/docs/api-reference/payments/previous/v2022-09-01/settlement-reconciliation/get-all-settlements) | Use this API to get all settlement details by specifying the settlement ID, settlement UTR or date range. |

### Payment links

| API | Description |
| :- | :- |
| [Create Payment Link](/docs/api-reference/payments/previous/v2022-09-01/payment-links/create-payment-link) | Use this API to create a new payment link. The created payment link url will be available in the API response parameter link\_url. |
| [Fetch Payment Link Details](/docs/api-reference/payments/previous/v2022-09-01/payment-links/fetch-payment-link-details) | Use this API to view all details and status of a payment link. |
| [Get Orders for a Payment Link](/docs/api-reference/payments/previous/v2022-09-01/payment-links/get-orders-for-a-payment-link) | Use this API to view all order details for a payment link. |
| [Cancel Payment Link](/docs/api-reference/payments/previous/v2022-09-01/payment-links/cancel-payment-link) | Use this API to cancel a payment link. No further payments can be done against a cancelled link. Only a link in ACTIVE status can be cancelled. |

### Token vault

| API | Description |
| :- | :- |
| [Fetch All Saved Instruments](/docs/api-reference/payments/previous/v2022-09-01/token-vault/fetch-all-saved-card-instrument) | Use this API to get all saved instruments for a customer ID. |
| [Fetch Single Saved Instrument](/docs/api-reference/payments/previous/v2022-09-01/token-vault/fetch-specific-saved-card-instrument) | Use this API to get specific saved instrument for a customer id and instrument ID. |
| [Delete Saved Instrument](/docs/api-reference/payments/previous/v2022-09-01/token-vault/delete-saved-card-instrument) | Use this API to delete a saved instrument for a customer id and instrument ID. |
| [Fetch Cryptogram for Saved Instrument](/docs/api-reference/payments/previous/v2022-09-01/token-vault/fetch-cryptogram-for-a-saved-card-instrument) | Use this API to get the card network token, token expiry and cryptogram for a saved instrument using instrument ID. |

### Reconciliation

| API | Description |
| :- | :- |
| [Settlement Reconciliation](/docs/api-reference/payments/previous/v2022-09-01/settlement-reconciliation/settlement-reconciliation) | Use this API to get settlement reconciliation details using Settlement ID, settlement UTR or date range. |
| [PG Reconciliation](/docs/api-reference/payments/previous/v2022-09-01/pg-reconciliation/pg-reconciliation) | Use this API to get the payment gateway reconciliation details with date range. |


# Cancel Payment Link
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2022-09-01/payment-links/cancel-payment-link

openapi/payments/v2022-09-01.yaml post /links/{link_id}/cancel
Use this API to cancel a payment link. No further payments can be done against a cancelled link. Only a link in ACTIVE status can be cancelled.



# Create Payment Link
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2022-09-01/payment-links/create-payment-link

openapi/payments/v2022-09-01.yaml post /links
Use this API to create a new payment link. The created payment link url will be available in the API response parameter link_url.



# Fetch Payment Link Details
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2022-09-01/payment-links/fetch-payment-link-details

openapi/payments/v2022-09-01.yaml get /links/{link_id}
Use this API to view all details and status of a payment link.



# Get Orders for a Payment Link
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2022-09-01/payment-links/get-orders-for-a-payment-link

openapi/payments/v2022-09-01.yaml get /links/{link_id}/orders
Use this API to view all order details for a payment link.



# Get Payment by ID
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2022-09-01/payments/get-payment-by-id

openapi/payments/v2022-09-01.yaml get /orders/{order_id}/payments/{cf_payment_id}
Use this API to view payment details of an order for a payment ID.



# Get Payments for an Order
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2022-09-01/payments/get-payments-for-an-order

openapi/payments/v2022-09-01.yaml get /orders/{order_id}/payments
Use this API to view all payment details for an order.



# Order Pay
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2022-09-01/payments/order-pay

openapi/payments/v2022-09-01.yaml post /orders/sessions
Use this API when you have already created the orders and want Cashfree to process the payment. To use this API S2S flag needs to be enabled
from the backend. In case you want to use the cards payment option the PCI
DSS flag is required, for more information reach out to us by filling out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod&raise_issue=1).




# Preauthorization
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2022-09-01/payments/preauthorization

openapi/payments/v2022-09-01.yaml post /orders/{order_id}/authorization
Use this API to capture or void a preauthorized payment



# Submit or Resend OTP
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2022-09-01/payments/submit-or-resend-otp

openapi/payments/v2022-09-01.yaml post /orders/pay/authenticate/{cf_payment_id}
If you accept OTP on your own page, you can use the below API to send OTP to Cashfree.



# PG Reconciliation
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2022-09-01/pg-reconciliation/pg-reconciliation

openapi/payments/v2022-09-01.yaml post /recon
- Use this API to get the payment gateway reconciliation details with date range.
- It will have events for your payment account




# Create Refund
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2022-09-01/refunds/create-refund

openapi/payments/v2022-09-01.yaml post /orders/{order_id}/refunds
Use this API to initiate refunds.



# Get All Refunds for an Order
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2022-09-01/refunds/get-all-refunds-for-an-order

openapi/payments/v2022-09-01.yaml get /orders/{order_id}/refunds
Use this API to fetch all refunds processed against an order.



# Get Refund
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2022-09-01/refunds/get-refund

openapi/payments/v2022-09-01.yaml get /orders/{order_id}/refunds/{refund_id}
Use this API to fetch a specific refund processed on your Cashfree Account.



# Get All Settlements
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2022-09-01/settlement-reconciliation/get-all-settlements

openapi/payments/v2022-09-01.yaml post /settlements
Use this API to get all settlement details by specifying the settlement ID, settlement UTR or date range.



# Settlement Reconciliation
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2022-09-01/settlement-reconciliation/settlement-reconciliation

openapi/payments/v2022-09-01.yaml post /settlement/recon
- Use this API to get settlement reconciliation details using Settlement ID, settlement UTR or date range.
- This API will return events for the settlement IDs you want




# Get Settlements by Order ID
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2022-09-01/settlements/get-settlements-by-order-id

openapi/payments/v2022-09-01.yaml get /orders/{order_id}/settlements
Use this API to view all the settlements of a particular order.



# Create Terminal
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2022-09-01/softpos/create-terminal

openapi/payments/v2022-09-01.yaml post /terminal
Use this API to create new terminals to use softPOS.



# Create Terminal
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2022-09-01/softpos/create-terminal-1

openapi/payments/v2022-09-01.yaml post /terminal/transactions
Use this API to create a new terminal transaction. To use this API you should first create an order using the Create Order API. Also, you need to enter the terminal details while creating the order and pass the same terminal information while creating a transaction using the below mentioned API.



# Fetch Terminal QR Codes
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2022-09-01/softpos/fetch-terminal-qr-codes

openapi/payments/v2022-09-01.yaml get /terminal/qrcodes
You can fetch all the StaticQRs corresponding to given terminal id or phone number. Provide either the terminal_phone_no or terminal_id in the request.



# Get terminal status using phone number
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2022-09-01/softpos/get-terminal-status-using-phone-number

openapi/payments/v2022-09-01.yaml get /terminal/{terminal_phone_no}
Use this API to view all details of a terminal.



# Offline Payments Webhooks
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2022-09-01/softpos/softpos-webhooks

Subscribe to Cashfree softPOS webhooks on the 2022-09-01 API to track terminal onboarding, status, and transaction events for in-person payments.

Webhooks are server callbacks to your server from Cashfree. Webhooks are event-based and are sent when specific events related to the transaction happen.

Cashfree sends the following webhooks for softPOS:

* [Payment Success](/docs/api-reference/payments/previous/v2022-09-01/softpos/softpos-webhooks#payment-success-webhook-version-2022-09-01)
* [Payment Failed](/docs/api-reference/payments/previous/v2022-09-01/softpos/softpos-webhooks#payment-failed-webhook-version-2022-09-01)
* [User Dropped](/docs/api-reference/payments/previous/v2022-09-01/softpos/softpos-webhooks#user-dropped-webhook-version-2022-09-01)
* [Refunds](/docs/api-reference/payments/previous/v2022-09-01/softpos/softpos-webhooks#refund-webhook-version-2022-09-01)
* [Auto Refund](/docs/api-reference/payments/previous/v2022-09-01/softpos/softpos-webhooks#auto-refund-webhook-version-2022-09-01)
* [Disputes](/docs/api-reference/payments/previous/v2022-09-01/softpos/softpos-webhooks#dispute-webhooks-version-2022-09-01)

## Payment success webhook version: (2022-09-01)

The new payment success webhook notifies you about the payment, and gives you comprehensive information about successful payments. A notification is sent to your backend from Cashfree when payments are successful. These notifications are useful in cases when the internet connection is unstable or slow while the payment is being processed. This will allow you to reconcile all the successful orders at your end. Notifications will be sent to **notifyUrl** which is a part of the request parameter specified while creating an order request as well as endpoints configured on the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).

#### Sample payload

```{ theme={"dark"}
  "data": {
        "order": {
            "order_id": "order_OFR_2",
            "order_amount": 2,
            "order_currency": "INR",
            "order_tags": null
        },
        "payment": {
            "cf_payment_id": 1453002795,
            "payment_status": "SUCCESS",
            "payment_amount": 1,
            "payment_currency": "INR",
            "payment_message": "00::Transaction success",
            "payment_time": "2022-12-15T12:20:29+05:30",
            "bank_reference": "234928698581",
            "auth_id": null,
            "payment_method": {
                "upi": {
                    "channel": null,
                    "upi_id": "9611199227@paytm"
                }
            },
            "payment_group": "upi"
        },
        "customer_details": {
            "customer_name": null,
            "customer_id": "7112AAA812234",
            "customer_email": "[miglaniyogesh7@gmail.com]()",
            "customer_phone": "9908734801"
        },
        "payment_gateway_details": {
            "gateway_name": "CASHFREE",
            "gateway_order_id": "1580762800",
            "gateway_payment_id": "1453002795",
            "gateway_status_code": null
        },
        "payment_offers": [  
            {  
                "offer_id": "0f05e1d0-fbf8-4c9c-a1f0-814c7b2abdba",  
                "offer_type": "DISCOUNT",  
                "offer_meta": {  
                    "offer_title": "50% off on UPI",  
                    "offer_description": "50% off for testing",  
                    "offer_code": "UPI50",  
                    "offer_start_time": "2022-11-09T06:23:25.972Z",  
                    "offer_end_time": "2023-02-27T18:30:00Z"  
                },  
                "offer_redemption": {  
                    "redemption_status": "SUCCESS",  
                    "discount_amount": 1,  
                    "cashback_amount": 0  
                }  
            }  
        ],
        "terminal_details": {
        "cf_terminal_id": 989876,
        "terminal_phone": "9773769999"
    }
    },
    "event_time": "2023-01-03T11:16:10+05:30",
    "type": "PAYMENT_SUCCESS_WEBHOOK"
}

```

## Payment failed webhook version: (2022-09-01)

The payment failed webhook notifies you when transactions fail and we receive a failed response from the bank.

```{ theme={"dark"}
    "data": {
    "order": {
        "order_id": "CFPay_g47u3888d0k0_tblfm766qc",
        "order_amount": 1.8,
        "order_currency": "INR",
        "order_tags": {
            "cf_link_id": "13746255"
        }
    },
    "payment": {
        "cf_payment_id": 1504280029,
        "payment_status": "FAILED",
        "payment_amount": 1.8,
        "payment_currency": "INR",
        "payment_message": "AMOUNT SHOULD BE WITHIN RANGE BETWEEN 20.00 TO 500000.00.",
        "payment_time": "2023-01-06T20:00:11+05:30",
        "bank_reference": "NA",
        "auth_id": "null",
        "payment_method": {
            "netbanking": {
                "channel": null,
                "netbanking_bank_code": "3054",
                "netbanking_bank_name": "UCO Bank"
            }
        },
        "payment_group": "net_banking"
    },
    "customer_details": {
        "customer_name": null,
        "customer_id": null,
        "customer_email": null,
        "customer_phone": "9611199227"
    },
    "error_details": {
        "error_code": "GATEWAY_ERROR",
        "error_description": "AMOUNT SHOULD BE WITHIN RANGE BETWEEN 20.00 TO 500000.00. for this bank",
        "error_reason": "invalid_amount",
        "error_source": "cashfree"
    },
    "payment_gateway_details": {
        "gateway_name": "CASHFREE",
        "gateway_order_id": "1634766330",
        "gateway_payment_id": "1504280029",
        "gateway_status_code": null
    },
    "payment_offers": null,
    "terminal_details": {
        "cf_terminal_id": 989876,
        "terminal_phone": "9773769999"
    }
},
"event_time": "2023-01-06T20:00:12+05:30",
"type": "PAYMENT_FAILED_WEBHOOK"
}
```

## User dropped webhook version: (2022-09-01)

The User Dropped Webhook notifies you when customers drop out of the payment flow without completing the transaction. It will help you understand if customers attempted to pay or not.

Some common scenarios where the transaction will be marked as USER\_DROPPED are:

* Android UPI Intent Payments - when a user clicks on the back button in the UPI app without making any payment attempt.
* Card Payments - when a user drops out of the payment flow by closing the OTP verification page.
* UPI Collect Transactions - when a user does not enter the UPI PIN and closes the transaction screen

```{ theme={"dark"}
    "data": {
        "order": {
            "order_id": "testspos83",
            "order_amount": 1.00,
            "order_currency": "INR",
            "order_tags": null
        },
        "payment": {
            "cf_payment_id": 2150264295,
            "payment_status": "USER_DROPPED",
            "payment_amount": 1.00,
            "payment_currency": "INR",
            "payment_message": null,
            "payment_time": "2023-11-03T12:37:32+05:30",
            "bank_reference": null,
            "auth_id": null,
            "payment_method": {
                "upi": {
                    "channel": null,
                    "upi_id": "testsuccess@gocash"
                }
            },
            "payment_group": "upi"
        },
        "customer_details": {
            "customer_name": "johndoe",
            "customer_id": "9112",
            "customer_email": "[johndoe@cashfree.com]()",
            "customer_phone": "9876543210"
        },
        "payment_gateway_details": {
            "gateway_name": null,
            "gateway_order_id": null,
            "gateway_payment_id": null,
            "gateway_status_code": null,
            "gateway_settlement": null
        },
        "payment_offers": null,
        "terminal_details": {
            "cf_terminal_id": 20532321,
            "terminal_phone": "9876543210"
        }
    },
    "event_time": "2023-11-03T12:37:44+05:30",
    "type": "PAYMENT_USER_DROPPED_WEBHOOK"
}
```

## Refund webhook version: (2022-09-01)

Refund webhooks can be configured to receive automated notifications for refunds when either they are successfully processed or are cancelled. Merchants can build their own downstream systems like auto-updating their refund status, and sending a communication to customers by consuming refund webhooks.

The webhook notification will be sent on all the URLs added and enabled under the refund webhook. Merchants can add new URLs and enable or disable existing URLs for refund webhook at any point in time and it will be reflected instantaneously.

#### Sample payload

```
{
 "data": {
    "refund": {
        "cf_refund_id": 11325632,
        "cf_payment_id": 789727431,
        "refund_id": "refund_sampleorder0413",
        "order_id": "sampleorder0413",
        "refund_amount": 2.00,
        "refund_currency": "INR",
        "entity": "Refund",
        "refund_type": "MERCHANT_INITIATED",
        "refund_arn": "205907014017",
        "refund_status": "SUCCESS",
        "status_description": "Refund processed successfully",
        "created_at": "2022-02-28T12:54:25+05:30",
        "processed_at": "2022-02-28T13:04:27+05:30",
        "refund_charge": 0,
        "refund_note": "Test",
        "refund_splits": [  
            {  
                "merchantVendorId": "sampleID12345",  
                "amount": 1,  
                "percentage": null  
            },  
            {  
                "merchantVendorId": "otherVendor",  
                "amount": 1,  
                "percentage": null  
            }  
        ],
        "metadata": null,
        "refund_mode": "STANDARD",
        "terminal_details": {
            "cf_terminal_id": 911876,
            "terminal_phone": "9876543210"
        }
    }
},
"event_time": "2022-02-28T13:04:28+05:30",
"type": "REFUND_STATUS_WEBHOOK"
}
```

#### Payload field description

| Field | Description | Example |
| :- | :- | :- |
| cf\_refund\_id | Cashfree ID for a refund. | 11325632 |
| cf\_payment\_id | Cashfree ID of the payment for which refund is initiated. | 789727431 |
| cf\_terminal\_id | Cashfree Terminal ID of the payment for which refund is initiated. | 21345 |
| terminal\_phone | The phone number of the corresponding terminal. | 9876543212 |
| refund\_id | Merchant’s refund ID of the refund | refund\_sampleorder0413 |
| order\_id | Merchant’s order Id of the order for which refund is initiated. | sampleorder0413 |
| refund\_amount | Amount that was refunded | 2.00 |
| refund\_currency | Currency of the refund amount. | INR |
| entity | Type of object (refund always) | Refund |
| refund\_type | Type of refund (for webhook it will always be MERCHANT\_INITIATED) | MERCHANT\_INITIATED |
| refund\_arn | The bank reference number for refund | 205907014017 |
| refund\_status | Status of the refund (either SUCCESS or CANCELLED in refund webhook) | SUCCESS |
| status\_description | Description of refund status | Refund processed successfully |
| created\_at | Time of refund creation | 2022-02-28T12:54:25+05:30 |
| processed\_at | Time when refund was processed successfully | 2022-02-28T13:04:27+05:30 |
| refund\_charge | Charges in INR for processing refund | 0 |
| refund\_note | Note added by merchant for the refund | Cancelled Order |
| refund\_splits | Refund split details | \[] |
| metadata | Additional refund metadata | null |
| refund\_mode | Method or speed of processing refund (INSTANT or STANDARD) | STANDARD |
| event\_time | Time at which refund webhook was initiated. | 2022-02-28T13:04:28+05:30 |
| type | Type of webhook. REFUND\_STATUS\_WEBHOOK always | REFUND\_STATUS\_WEBHOOK |

## Auto refund webhook version: (2022-09-01)

Auto-refund webhooks can be configured to receive automated notifications when auto-refunds are initiated, processed and delayed. Auto-refunds are refunds triggered automatically for unsuccessful payments, disputes, duplicate payments; or instances where payments are received directly to your VPA, regardless of whether an order has been generated.

Cashfree sends webhook notifications to every URL added and enabled under **Auto-refund Webhooks**. You can add new URLs and enable or disable existing ones for auto-refund webhooks at any point in time. The changes take effect immediately.

#### Sample payload

```Text Auto-Refund Webhook Sample Payload theme={"dark"}
{
    "data": {
        "auto_refund": {
            "event": "AUTO-REFUND",
            "cf_refund_id": 1243460973,
            "cf_payment_id": "2148333968",
            "bank_reference": "234928698581",
            "order_id": "order_1944392Tpba8y2fHcHVx0SwREojp51Jgr",
            "refund_amount": 39,
            "refund_currency": "INR",
            "refund_type": "PAYMENT_AUTO_REFUND",
            "refund_arn": "205907014017",
            "refund_status": "SUCCESS",
            "status_description": "Auto-Refund processed successfully",
            "refund_reason": "Multiple payments were performed against same order.",
            "created_at": "2023-08-11T14:08:28+05:30",
            "processed_at": null,
            "refund_charge": 0,
            "refund_splits": null,
            "metadata": null
        },
        "terminal_details": {
            "cf_terminal_id": 989876,
            "terminal_phone": "9773769999"
        }
    },
    "event_time": "2023-08-11T14:10:21+05:30",
    "type": "AUTO_REFUND_STATUS_WEBHOOK"
}
```

Find the description for each field of the payload below:

| Field | Description | Example |
| - | - | - |
| cf\_refund\_id | It represents the ID created by Cashfree to identify the refund. | 1243460973 |
| cf\_payment\_id | It represents the ID created by Cashfree to identify the payment for the initiated refund. | 2148333968 |
| cf\_terminal\_id | Cashfree Terminal ID of the payment for which refund is initiated. | 21345 |
| terminal\_phone | The phone number of the corresponding terminal. | 9876543212 |
| order\_id | It represents the ID created by you to identify the order for which the refund is initiated. | sampleorder0413 |
| bank\_reference | It represents the bank reference number for the transaction. | 234928698581 |
| refund\_currency | It represents the currency of the refund amount. | INR |
| refund\_amount | It represents the refunded amount. | 2 |
| refund\_type | It represents the refund type. The value will always be PAYMENT\_AUTO\_REFUND. | PAYMENT\_AUTO\_REFUND |
| refund\_arn | It represents the bank reference number for the refund. | 205907014017 |
| refund\_status | It represents the status of the refund (either SUCCESS or INITIATED). | SUCCESS |
| status\_description | It represents the description of the refund status.  <br />(Two possible values:  <br />Auto-Refund initiated successfully or  <br />Auto-Refund processed successfully). | Auto-Refund initiated successfully |
| created\_at | It represents the time of auto-refund creation. | 2022-02-28T12:54:25+05:30 |
| processed\_at | It represents when the auto-refund was processed successfully. | 2022-02-28T13:04:27+05:30 |
| refund\_reason | It represents the reason of initiation of Auto-refund.  <br />(Possible values:  <br />Credit was received for an incomplete payment.  <br />Refunded to customer for Dispute.  <br />Payment made directly to your VPA without order creation.  <br />Multiple payments were performed against same order.  <br />Payment details (amount, bank, etc.) do not match with created order or the payment was made after TTL.) | Multiple payments were performed against same order |
| refund\_charge | It represents the charges for processing refund in INR. | 0 |
| refund\_splits | It represents the refund split details. | \[] |
| metadata | It represents the additional metadata. | null |
| event\_time | It represents when the refund webhook was initiated. | 2022-02-28T13:04:28+05:30 |
| type | It represents the webhook type. The value will always be AUTO\_REFUND\_STATUS\_WEBHOOK. | AUTO\_REFUND\_STATUS\_WEBHOOK |

## Dispute webhooks version: (2022-09-01)

Dispute webhooks can be configured to receive automated notifications when disputes are created, updated and closed.

The webhook notification will be sent on all the URLs added and enabled under the dispute webhook. Merchants can add new URLs and enable or disable existing URLs for refund webhook at any point in time and it will be reflected instantaneously.

| Webhook | Description |
| :- | :- |
| DISPUTE\_CREATED | Dispute\_created webhook will be triggered when a new dispute is created. |
| DISPUTE\_UPDATED | Dispute\_updated webhook will be triggered when a dispute is updated, for example when a comment is added by the Cashfree team, when the dispute moves into further stages like Pre-arbitration, Arbitration, or when the status of the dispute changes. |
| DISPUTE\_CLOSED | This webhook will be triggered when a dispute is closed. |

#### Dispute created

**Sample Payload**

```{ theme={"dark"}
    "data": {
        "dispute": {
            "dispute_id": "433475258",
            "dispute_type": "DISPUTE",
            "reason_code": "1402",
            "reason_description": "Duplicate Processing",
            "dispute_amount": 3,
            "created_at": "2023-06-15T21:49:48+05:30",
            "updated_at": "2023-06-15T21:49:48+05:30",
            "respond_by": "2023-06-18T23:59:59+05:30",
            "dispute_status": "DISPUTE_CREATED",
            "cf_dispute_remarks": "Dispute is created, please take action",
            "dispute_action_on": "MERCHANT"
        },
        "order_details": {
            "order_id": "order_1944392DR1kMTFYdIf8bI2awAcC3i9FTa",
            "order_amount": 3,
            "order_currency": "INR",
            "cf_payment_id": 885473311,
            "payment_amount": 3,
            "payment_currency": "INR"
        },
        "customer_details": {
            "customer_name": "Dileep Kumar s",
            "customer_phone": "8000000000",
            "customer_email": "dileep@gmail.com"
        },
        "terminal_details": {
            "cf_terminal_id": 989876,
            "terminal_phone": "9876543212"
        }
    },
    "event_time": "2023-06-15T21: 50: 04+05: 30",
    "type": "DISPUTE_CREATED"
}
```

#### Dispute updated

**Sample Payload**

```{ theme={"dark"}
    "data": {
        "dispute": {
            "dispute_id": "433475257",
            "dispute_type": "PRE_ARBITRATION",
            "reason_code": "13.1",
            "reason_description": "Merchandise / Services Not Received",
            "dispute_amount": 40000,
            "created_at": "2023-06-15T21:16:03+05:30",
            "updated_at": "2023-06-15T21:19:15+05:30",
            "respond_by": "2023-06-19T23:59:59+05:30",
            "dispute_status": "PRE_ARBITRATION_CREATED",
            "cf_dispute_remarks": "Pre Arbitration request has been raised for this case.\\nTarget Date :: 2023-06-18T00:00 -> 2023-06-19T23:59:59.",
            "dispute_update": "TYPE_UPDATE",
            "dispute_action_on": "MERCHANT"
        },
        "order_details": {
            "order_id": "order_1944392D4jHtCeVPPdTXkaUwg5cfnujQe",
            "order_amount": 40000,
            "order_currency": "INR",
            "cf_payment_id": 885457437,
            "payment_amount": 40000,
            "payment_currency": "INR"
        },
        "customer_details": {
            "customer_name": "Dileep Kumar s",
            "customer_phone": "8000000000",
            "customer_email": "dileep@gmail.com"
        },
        "terminal_details": {
            "cf_terminal_id": 989876,
            "terminal_phone": "9876543212"
        }
    },
    "event_time": "2023-06-15T21:20:24+05:30",
    "type": "DISPUTE_UPDATED"
}
```

#### Dispute closed

**Sample Payload**

```{ theme={"dark"}
    "data": {
        "dispute": {
            "dispute_id": "433475257",
            "dispute_type": "CHARGEBACK",
            "reason_code": "4855",
            "reason_description": "Goods or Services Not Provided",
            "dispute_amount": 4500,
            "created_at": "2023-06-15T21:16:03+05:30",
            "updated_at": "2023-06-15T21:16:51+05:30",
            "respond_by": "2023-06-18T00:00:00+05:30",
            "resolved_at": "2023-06-15T21:16:51.682836678+05:30",
            "dispute_status": "CHARGEBACK_MERCHANT_WON",
            "cf_dispute_remarks": "Chargeback won by merchant"
        },
        "order_details": {
            "order_id": "order_1944392D4jHtCeVPPdTXkaUwg5cfnujQe",
            "order_amount": 4500,
            "order_currency": "INR",
            "cf_payment_id": 885457437,
            "payment_amount": 4500,
            "payment_currency": "INR"
        },
        "customer_details": {
            "customer_name": "Dileep Kumar s",
            "customer_phone": "8000000000",
            "customer_email": "dileep@gmail.com"
        },
        "terminal_details": {
            "cf_terminal_id": 989876,
            "terminal_phone": "9876543212"
        }
    },
    "event_time": "2023-06-15T21:17:14+05:30",
    "type": "DISPUTE_CLOSED"
}
```

#### Payload field description

| Field | Description | Example | Type |
| - | - | - | - |
| dispute\_id | Cashfree’s unique ID to identify a dispute. | 433475257 | Long |
| dispute\_type | Type of dispute created. Possible values:  <br />  <br />- DISPUTE<br />- RETRIEVAL<br />- CHARGEBACK<br />- PRE\_ARBITRATION<br />- ARBITRATION | Chargeback | String |
| cf\_terminal\_id | Cashfree Terminal ID of the payment for which refund is initiated. | 989876 | Long |
| terminal\_phone | The phone number of the corresponding terminal. | 9876543212 | String |
| reason\_code | Condition for which the customer is filing the case. See [dispute reason codes](/docs/payments/manage/disputes/reason-codes) to know more. | 13.6 | String |
| reason\_description | Description of the reason code. Codes for Chargeback cases are specified by Card networks/NPCI. | Credit not processed | String |
| dispute\_amount | The amount for which the dispute has been created. | 4500 | BigDecimal |
| created\_at | Time on which the dispute was registered on Cashfree’s system. | 2023-06-15T21:16:03+05:30 | LocalDateTime |
| updated\_at | Time on which the dispute was updated. | 2023-06-15T21:16:51+05:30 | LocalDateTime |
| respond\_by | Time by which the merchant is expected to respond to the dispute. | 2023-06-18T00:00:00+05:30 | LocalDateTime |
| dispute\_status | Status of Dispute. All possible values are listed in the table below. | CHARGEBACK\_CREATED | String |
| cf\_dispute\_remarks | Any remarks specified by Cashfree on the dispute. | Please submit documents. | String |
| dispute\_update | Specifies what has been updated on the dispute. Possible Values:  <br />  <br />- STATUS\_UPDATE<br />- TYPE\_UPDATE<br />- COMMENT\_UPDATE | TYPE\_UPDATE | String |
| dispute\_action\_on | Specifies whether the action is on Cashfree or Merchant at a time.  <br />Possible Values:  <br />  <br />- MERCHANT<br />- CASHFREE | MERCHANT | String |
| resolved\_at | Time on which the dispute was resolved/closed. | 2023-06-15T21:16:51.682836678+05:30 | LocalDateTime |
| event\_time | Time at which dispute webhook was initiated. | 2023-06-15T21:16:51+05:30 | LocalDateTime |
| type | Type of webhook. Possible Values:  <br />  <br />- DISPUTE\_CREATED<br />- DISPUTE\_UPDATED<br />- DISPUTE\_CLOSED | DISPUTE\_CREATED | String |


# Delete Saved Card Instrument
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2022-09-01/token-vault/delete-saved-card-instrument

openapi/payments/v2022-09-01.yaml delete /customers/{customer_id}/instruments/{instrument_id}
Use this API to delete a saved card instrument for a customer_id and instrument_id



# Fetch All Saved Card Instrument
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2022-09-01/token-vault/fetch-all-saved-card-instrument

openapi/payments/v2022-09-01.yaml get /customers/{customer_id}/instruments
Use this API to fetch saved cards for a customer_id 



# Fetch cryptogram for a saved card instrument
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2022-09-01/token-vault/fetch-cryptogram-for-a-saved-card-instrument

openapi/payments/v2022-09-01.yaml get /customers/{customer_id}/instruments/{instrument_id}/cryptogram
Use this API To get the card network token, token expiry and cryptogram for a saved card instrument using instrument id



# Fetch Specific Saved Card Instrument
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2022-09-01/token-vault/fetch-specific-saved-card-instrument

openapi/payments/v2022-09-01.yaml get /customers/{customer_id}/instruments/{instrument_id}
Use this API to fetch a single specific saved card for a customer_id by it's instrument_id



# Create Customer
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/customers/create

openapi/payments/v2023-08-01.yaml post /customers
Create Customer at Cashfree



# Accept Dispute by Dispute ID
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/dispute/dispute-accept

openapi/payments/v2023-08-01.yaml put /disputes/{dispute_id}/accept
Use this API to get accept the Dispute by specifying the Dispute ID.



# Submit Evidence to contest the Dispute by Dispute ID
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/dispute/dispute-submission

openapi/payments/v2023-08-01.yaml post /disputes/{dispute_id}/documents
Use this API to Submit the Evidences to contest the Dispute by specifying the Dispute ID.



# Dispute Webhooks
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/dispute/dispute-webhooks

Subscribe to Cashfree dispute webhooks to receive asynchronous updates whenever a chargeback or pre-arbitration changes state on your account.

Dispute webhooks can be configured to receive automated notifications when disputes are created, updated and closed.

The webhook notification will be sent on all the URLs added and enabled under the dispute webhook. Merchants can add new URLs and enable or disable existing URLs for refund webhook at any point in time and it will be reflected instantaneously.

| Webhook | Description |
| :- | :- |
| DISPUTE\_CREATED | Dispute\_created webhook will be triggered when a new dispute is created. |
| DISPUTE\_UPDATED | Dispute\_updated webhook will be triggered when a dispute is updated, for example when a comment is added by the Cashfree team, when the dispute moves into further stages like Pre-arbitration, Arbitration, or when the status of the dispute changes. |
| DISPUTE\_CLOSED | This webhook will be triggered when a dispute is closed. |

Click [here](/docs/payments/online/webhooks/overview) to know how to configure webhooks.

## Dispute created

**Sample Payload**

```json theme={"dark"}
"{
  "data": {
    "dispute": {
      "dispute_id": "433475258",
      "dispute_type": "DISPUTE",
      "reason_code": "1402",
      "reason_description": "Duplicate Processing",
      "dispute_amount": 3,
      "created_at": "2023-06-15T21:49:48+05:30",
      "updated_at": "2023-06-15T21:49:48+05:30",
      "respond_by": "2023-06-18T23:59:59+05:30",
      "dispute_status": ""DISPUTE_CREATED"",
      "cf_dispute_remarks": "Dispute is created, please take action",
      "dispute_action_on": "MERCHANT"
    },
    "order_details": {
      "order_id": "order_1944392DR1kMTFYdIf8bI2awAcC3i9FTa",
      "order_amount": 3,
      "order_currency": "INR",
      "cf_payment_id": 885473311,
      "payment_amount": 3,
      "payment_currency": "INR"
    },
    "customer_details": {
      "customer_name": "Dileep Kumar s",
      "customer_phone": "8000000000",
      "customer_email": "dileep@gmail.com"
    }
  },
  "event_time": ""2023-06-15T21:50:04+05:30",
  "type": "DISPUTE_CREATED"
}"
```

## Dispute updated

**Sample Payload**

```json theme={"dark"}
"{
  "data": {
    "dispute": {
      "dispute_id": "433475257",
      "dispute_type": "PRE_ARBITRATION",
      "reason_code": "13.1",
      "reason_description": "Merchandise / Services Not Received",
      "dispute_amount": 40000,
      "created_at": "2023-06-15T21:16:03+05:30",
      "updated_at": "2023-06-15T21:19:15+05:30",
      "respond_by": "2023-06-19T23:59:59+05:30",
      "dispute_status": "PRE_ARBITRATION_CREATED",
      "cf_dispute_remarks": "Pre Arbitration request has been raised for this case.\nTarget Date :: 2023-06-18T00:00 -> 2023-06-19T23:59:59.",
      "dispute_update": "TYPE_UPDATE",
      "dispute_action_on": "MERCHANT"
    },
    "order_details": {
      "order_id": "order_1944392D4jHtCeVPPdTXkaUwg5cfnujQe",
      "order_amount": 40000,
      "order_currency": "INR",
      "cf_payment_id": 885457437,
      "payment_amount": 40000,
      "payment_currency": "INR"
    },
    "customer_details": {
      "customer_name": "Dileep Kumar s",
      "customer_phone": "8000000000",
      "customer_email": "dileep@gmail.com"
    }
  },
  "event_time": "2023-06-15T21:20:24+05:30",
  "type": "DISPUTE_UPDATED"
}"
```

## Dispute closed

**Sample Payload**

```json theme={"dark"}
"{
  "data": {
    "dispute": {
      "dispute_id": "433475257",
      "dispute_type": "CHARGEBACK",
      "reason_code": "4855",
      "reason_description": "Goods or Services Not Provided",
      "dispute_amount": 4500,
      "created_at": "2023-06-15T21:16:03+05:30",
      "updated_at": "2023-06-15T21:16:51+05:30",
      "respond_by": "2023-06-18T00:00:00+05:30",
      "resolved_at": "2023-06-15T21:16:51.682836678+05:30",
      "dispute_status": "CHARGEBACK_MERCHANT_WON",
      "cf_dispute_remarks": "Chargeback won by merchant"
    },
    "order_details": {
      "order_id": "order_1944392D4jHtCeVPPdTXkaUwg5cfnujQe",
      "order_amount": 4500,
      "order_currency": "INR",
      "cf_payment_id": 885457437,
      "payment_amount": 4500,
      "payment_currency": "INR"
    },
    "customer_details": {
      "customer_name": "Dileep Kumar s",
      "customer_phone": "8000000000",
      "customer_email": "dileep@gmail.com"
    }
  },
  "event_time": "2023-06-15T21:17:14+05:30",
  "type": "DISPUTE_CLOSED"
}"
```

## Payload field description

| Field | Description | Example | Type |
| - | - | - | - |
| dispute\_id | Cashfree’s unique ID to identify a dispute. | 433475257 | Long |
| dispute\_type | Type of dispute created. Possible values:  <br />- DISPUTE<br />- RETRIEVAL<br />- CHARGEBACK<br />- PRE\_ARBITRATION<br />- ARBITRATION | Chargeback | String |
| reason\_code | Condition for which the customer is filing the case. See [dispute reason codes](/docs/payments/manage/disputes/reason-codes) to know more. | 13.6 | String |
| reason\_description | Description of the reason code. Codes for Chargeback cases are specified by Card networks/NPCI. | Credit not processed | String |
| dispute\_amount | The amount for which the dispute has been created. | 4500 | BigDecimal |
| created\_at | Time on which the dispute was registered on Cashfree’s system. | 2023-06-15T21:16:03+05:30 | LocalDateTime |
| updated\_at | Time on which the dispute was updated. | 2023-06-15T21:16:51+05:30 | LocalDateTime |
| respond\_by | Time by which the merchant is expected to respond to the dispute. | 2023-06-18T00:00:00+05:30 | LocalDateTime |
| dispute\_status | Status of Dispute. All possible values are listed in the table below. | CHARGEBACK\_CREATED | String |
| cf\_dispute\_remarks | Any remarks specified by Cashfree on the dispute. | Please submit documents. | String |
| dispute\_update | Specifies what has been updated on the dispute. Possible Values:  <br />- STATUS\_UPDATE<br />- TYPE\_UPDATE<br />- COMMENT\_UPDATE | TYPE\_UPDATE | String |
| dispute\_action\_on | Specifies whether the action is on Cashfree or Merchant at a time. Possible Values:  <br />- MERCHANT<br />- CASHFREE | MERCHANT | String |
| resolved\_at | Time on which the dispute was resolved/closed. | 2023-06-15T21:16:51.682836678+05:30 | LocalDateTime |
| event\_time | Time at which dispute webhook was initiated. | 2023-06-15T21:16:51+05:30 | LocalDateTime |
| type | Type of webhook. Possible Values:  <br />- DISPUTE\_CREATED<br />- DISPUTE\_UPDATED<br />- DISPUTE\_CLOSED | DISPUTE\_CREATED | String |

| List of dispute status |
| :- |
| DISPUTE\_CREATED |
| DISPUTE\_DOCS\_RECEIVED |
| DISPUTE\_UNDER\_REVIEW |
| DISPUTE\_MERCHANT\_WON |
| DISPUTE\_MERCHANT\_LOST |
| DISPUTE\_MERCHANT\_ACCEPTED |
| DISPUTE\_INSUFFICIENT\_EVIDENCE |
| RETRIEVAL\_CREATED |
| RETRIEVAL\_DOCS\_RECEIVED |
| RETRIEVAL\_UNDER\_REVIEW |
| RETRIEVAL\_MERCHANT\_WON |
| RETRIEVAL\_MERCHANT\_LOST |
| RETRIEVAL\_MERCHANT\_ACCEPTED |
| RETRIEVAL\_INSUFFICIENT\_EVIDENCE |
| CHARGEBACK\_CREATED |
| CHARGEBACK\_DOCS\_RECEIVED |
| CHARGEBACK\_UNDER\_REVIEW |
| CHARGEBACK\_MERCHANT\_WON |
| CHARGEBACK\_MERCHANT\_LOST |
| CHARGEBACK\_MERCHANT\_ACCEPTED |
| CHARGEBACK\_INSUFFICIENT\_EVIDENCE |
| PRE\_ARBITRATION\_CREATED |
| PRE\_ARBITRATION\_DOCS\_RECEIVED |
| PRE\_ARBITRATION\_UNDER\_REVIEW |
| PRE\_ARBITRATION\_MERCHANT\_WON |
| PRE\_ARBITRATION\_MERCHANT\_LOST |
| PRE\_ARBITRATION\_MERCHANT\_ACCEPTED |
| PRE\_ARBITRATION\_INSUFFICIENT\_EVIDENCE |
| ARBITRATION\_CREATED |
| ARBITRATION\_DOCS\_RECEIVED |
| ARBITRATION\_UNDER\_REVIEW |
| ARBITRATION\_MERCHANT\_WON |
| ARBITRATION\_MERCHANT\_LOST |
| ARBITRATION\_MERCHANT\_ACCEPTED |
| ARBITRATION\_INSUFFICIENT\_EVIDENCE |

## Compute Signature and Verify

The signature must be used to verify if the request has not been tampered with. To verify the signature at your end, you will need your Cashfree PG secret key along with the payload. Timestamp is present in the header x-webhook-timestamp

````bash theme={"dark"}
timestamp := 1617695238078;  
signedPayload := $timestamp.$payload;
expectedSignature := Base64Encode(HMACSHA256($signedPayload, $merchantSecretKey));```
````

## Sample code

### Verify Signature using SDK

<CodeGroup>
  ```node Node (express) theme={"dark"}

  var express = require('express')
  import { Cashfree } from "cashfree-pg"; 
  var app = express()

  Cashfree.XClientId = "<x-client-id>";
  Cashfree.XClientSecret = "<x-client-secret>";
  Cashfree.XEnvironment = Cashfree.Environment.SANDBOX;

  app.post('/webhook', function (req, res) {
      try {
          Cashfree.PGVerifyWebhookSignature(req.headers["x-webhook-signature"], req.rawBody, req.headers["x-webhook-timestamp"]))
      } catch (err) {
          console.log(err.message)
      }
  })
  ```

  ```go Go theme={"dark"}
  var express = require('express')
  import { Cashfree } from "cashfree-pg"; 
  var app = express()

  Cashfree.XClientId = "<x-client-id>";
  Cashfree.XClientSecret = "<x-client-secret>";
  Cashfree.XEnvironment = Cashfree.Environment.SANDBOX;

  app.post('/webhook', function (req, res) {
      try {
          Cashfree.PGVerifyWebhookSignature(req.headers["x-webhook-signature"], req.rawBody, req.headers["x-webhook-timestamp"]))
      } catch (err) {
          console.log(err.message)
      }
  })
  ```

  ```php PHP theme={"dark"}

  <?php

  $inputJSON = file_get_contents('php://input');

  $expectedSig = getallheaders()['x-webhook-signature'];
  $ts = getallheaders()['x-webhook-timestamp'];

  if(!isset($expectedSig) || !isset($ts)){
      echo "Bad Request";
      die();
  }

  \Cashfree\Cashfree::$XClientId = "<x-client-id>";
  \Cashfree\Cashfree::$XClientSecret = "<x-client-secret>";
  $cashfree = new \Cashfree\Cashfree();

  try {
   $response =  cashfree->PGVerifyWebhookSignature($expectedSig, $inputJSON, $ts);
  } catch(Exception $e) {
    // Error if signature verification fails
  }
  ?>

  ```

  ```python Python theme={"dark"}
  from cashfree_pg.api_client import Cashfree

  @app.route('/webhook', methods = ['POST'])
  def disp():
  		# Get the raw body from the request
      raw_body = request.data
    
      # Decode the raw body bytes into a string
      decoded_body = raw_body.decode('utf-8')

      #verify_signature
      timestamp = request.headers['x-webhook-timestamp']
      signature = request.headers['x-webhook-signature'
  		
  		cashfree = Cashfree()
  		cashfree.XClientId = "<app_id>"
  		cashfree.XClientSecret = "<secret_key>"
  		try:
  			cashfreeWebhookResponse = cashfree.PGVerifyWebhookSignature(signature, decoded_body, timestamp)
  		except:
  			# If Signature mis-match

  ```

  ```java Java theme={"dark"}
  import com.cashfree.*;

  @PostMapping("/my-endpoint")
  public String handlePost(HttpServletRequest request) throws IOException {      
      Cashfree.XClientId = "<x-client-id>";
  		Cashfree.XClientSecret = "<x-client-secret>";
  		Cashfree.XEnvironment = Cashfree.SANDBOX;
    
    	StringBuilder stringBuilder = new StringBuilder();
      BufferedReader bufferedReader = null;

      try {           
        bufferedReader = request.getReader();
        String line;
        while ((line = bufferedReader.readLine()) != null) {
                stringBuilder.append(line).append('\n');
        }
          
          
        String rawBody = stringBuilder.toString();
        String signature = request.getHeader("x-webhook-signature");
        String timestamp = request.getHeader("x-webhook-timestamp");
          
        Cashfree cashfree = new Cashfree();
        PGWebhookEvent webhook = cashfree.PGVerifyWebhookSignature(signature, rawBody, timestamp);
            
      } catch (Exception e) {
              // Error if verification fails
      } finally {
           if (bufferedReader != null) {
              bufferedReader.close();
  		}
  	}
        
  }
  ```

  ```c C# theme={"dark"}
  using cashfree_pg.Client;
  using cashfree_pg.Model;


  		[Route("api/[controller]")]
      [ApiController]
      public class YourController : ControllerBase
      {
          [HttpPost]
          public async Task<IActionResult> Post()
          {
              // Read the raw body of the POST request
              using (StreamReader reader = new StreamReader(Request.Body, Encoding.UTF8))
              {
                  string requestBody = await reader.ReadToEndAsync();
                  var headers = Request.Headers;
                  var signature = headers["x-webhook-signature"];
                  var timestamp = headers["x-webhook-timestamp"];
                  
                  Cashfree.XClientId = "<x-client-id>";
                  Cashfree.XClientSecret = "<x-client-secret>";
                  Cashfree.XEnvironment = Cashfree.SANDBOX;
  								var cashfree = new Cashfree();
                  
                  try {
                  var response = cashfree.PGVerifyWebhookSignature(signature, requestBody, timestamp);
                  } catch(Exception e) {
                  // Error if signature mis matches
                  }
              }
          }
      }
  ```
</CodeGroup>

### Compute Signature and Verify manually

<CodeGroup>
  ```node Node (express) theme={"dark"}

  function verify(ts, rawBody){
      const body = req.headers["x-webhook-timestamp"] + req.rawBody;
      const secretKey = "<your secret key>";
      let genSignature = crypto.createHmac('sha256',secretKey).update(body).digest("base64");
      return genSignature
  }
  ```

  ```go Go theme={"dark"}
  func VerifySignature(expectedSig string, ts string, body string) (string, error) {
  	t := time.Now()
  	currentTS := t.Unix()
  	if currentTS-ts > 1000*300 {
  		return "", errors.New("webhook delivered too late")
  	}
  	signStr := strconv.FormatInt(ts, 10) + body
  	fmt.Println("signing String: ", signStr)
  	key := ""
  	h := hmac.New(sha256.New, []byte(key))
  	h.Write([]byte(signStr))
  	b := h.Sum(nil)
  	return base64.StdEncoding.EncodeToString(b), nil
  }

  timestamp := c.Request().Header.Get("x-webhook-timestamp")
  body, _ := ioutil.ReadAll(c.Request().Body)
  rawBody := string(body)
  signature := c.Request().Header.Get("x-webhook-signature")

  VerifySignature(signature, timestamp, rawBody)func VerifySignature(expectedSig string, ts string, body string) (string, error) {
  	t := time.Now()
  	currentTS := t.Unix()
  	if currentTS-ts > 1000*300 {
  		return "", errors.New("webhook delivered too late")
  	}
  	signStr := strconv.FormatInt(ts, 10) + body
  	fmt.Println("signing String: ", signStr)
  	key := ""
  	h := hmac.New(sha256.New, []byte(key))
  	h.Write([]byte(signStr))
  	b := h.Sum(nil)
  	return base64.StdEncoding.EncodeToString(b), nil
  }

  timestamp := c.Request().Header.Get("x-webhook-timestamp")
  body, _ := ioutil.ReadAll(c.Request().Body)
  rawBody := string(body)
  signature := c.Request().Header.Get("x-webhook-signature")

  VerifySignature(signature, timestamp, rawBody)
  ```

  ```php PHP theme={"dark"}

  function computeSignature($ts, $rawBody){
      $rawBody = file_get_contents('php://input');
  		$ts = getallheaders()['x-webhook-timestamp'];
    
      $signStr = $ts . $rawBody;
      $key = "";
      $computeSig = base64_encode(hash_hmac('sha256', $signStr, $key, true));
      return $computeSig;
  }

  ```

  ```java Java theme={"dark"}
  public String generateSignature() {

  	bufferedReader = request.getReader();
    String line;
    while ((line = bufferedReader.readLine()) != null) {
       stringBuilder.append(line).append('\n');
    }      
    String payload = stringBuilder.toString();
    String timestamp = request.getHeader("x-webhook-timestamp");
        
    String data = timestamp+payload;

    String secretKey = "SECRET-KEY"; // Get secret key from Cashfree Merchant Dashboard;
    Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
    SecretKeySpec secret_key_spec = new SecretKeySpec(secretKey.getBytes(),"HmacSHA256");
    sha256_HMAC.init(secret_key_spec);
    String computed_signature = Base64.getEncoder().encodeToString(sha256_HMAC.doFinal(data.getBytes()));
    return computed_signature; // compare with "x-webhook-signature"
  }

  ```

  ```python Python theme={"dark"}
  import base64
  import hashlib
  import hmac

  def generateSignature():    
      # Get the raw body from the request
      raw_body = request.data
    
      # Decode the raw body bytes into a string
      payload = raw_body.decode('utf-8')

      #verify_signature
      timestamp = request.headers['x-webhook-timestamp']
      
      signatureData = timestamp+payload
      message = bytes(signatureData, 'utf-8')
      secretkey=bytes("Secret_Key",'utf-8') #Get Secret_Key from Cashfree Merchant Dashboard.
      signature = base64.b64encode(hmac.new(secretkey, message, digestmod=hashlib.sha256).digest())
      computed_signature = str(signature, encoding='utf8')
      return computed_signature #compare with "x-webhook-signature"

  ```
</CodeGroup>


# Get Disputes by Dispute ID
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/dispute/disputes

openapi/payments/v2023-08-01.yaml get /disputes/{dispute_id}
Use this API to get Dispute details by specifying the Dispute ID.



# Get Disputes by Order ID
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/dispute/disputes-for-order

openapi/payments/v2023-08-01.yaml get /orders/{order_id}/disputes
Use this API to get all Dispute details by specifying the Order ID.



# Get Disputes by Payment ID
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/dispute/disputes-for-payment

openapi/payments/v2023-08-01.yaml get /payments/{cf_payment_id}/disputes
Use this API to get all Dispute details by specifying the Payment ID.



# Get Import Settlement Details for an Order
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/international-payments/collect-from-india/get-import-settlement-details

openapi/cb-imports/merchant-spec.json get /import/orders/{order_id}/settlements
This API is used to get ICA settlement details using PG Order ID.



# Get Import Settlement Recon Details
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/international-payments/collect-from-india/get-import-settlement-recon-details

openapi/cb-imports/merchant-spec.json post /import/settlements/recon
This API is used to fetch all events happened for provided Settlement IDs.



# Get Payment Verification Details
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/international-payments/collect-from-india/get-payment-verification-details

get /import/transactions/{cf_payment_id}
Use this API to get the status of the payment verification.



# Overview
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/international-payments/collect-from-india/import-settlement-apis-overview

Browse the Cashfree Collect from India settlement APIs that fetch import settlement details and run reconciliation reports for cross-border payments.

This page is the parent folder for all the APIs required for obtaining ICA settlement details related to orders that have been remitted.

* [Get Import Settlement Details for an Order](/docs/api-reference/payments/previous/v2023-08-01/international-payments/collect-from-india/get-import-settlement-details) - Use this to fetch ICA settlements.
* [Get Import Settlement Recon Details](/docs/api-reference/payments/previous/v2023-08-01/international-payments/collect-from-india/get-import-settlement-recon-details) - Use this to fetch recon events of ICA settlements.


# Overview
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/international-payments/collect-from-india/import-verification-apis-overview

Browse the Cashfree Collect from India verification APIs used to upload and fetch payment documents required for cross-border compliance checks.

This page is the parent folder for all the APIs required for processing the transactions need to be remitted abroad.

<br />

* [Upload Payment Verification Details](/docs/api-reference/payments/previous/v2023-08-01/international-payments/collect-from-india/upload-payment-verification-details) - Use this to submit verification details
* [Get Payment Verification Details](/docs/api-reference/payments/previous/v2023-08-01/international-payments/collect-from-india/get-payment-verification-details) - Use this to fetch payment verification details


# Webhooks
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/international-payments/collect-from-india/import-webhooks

Enable merchants, payment aggregators, and marketplaces outside India to accept payments from customers in India, covering import webhooks, event types, payloads, and signature verification.

Webhooks are server callbacks to your server from Cashfree. Webhooks are event-based and are sent when specific events related to the transaction happen.

Click [here](/docs/payments/online/webhooks/configure) to know how to configure webhooks.

<Tabs>
  <Tab title="Payment Verification">
    ## Payment Verification details webhook version 1 (2022-09-01)

    The payment verification details update webhook notifies you about the payment details verification, and it give you comprehensive information about verification details update.

    A notification is sent to your backend from cashfree when there is any new update for payment verification. These notification are useful in cases when the internet connection is unstable or slow while the payment is getting processed. This will allow you to reconcile all the payment verification update at your end. Notifications will be sent to **notifyUrl** which is a part of the request parameter specified while creating an order request.

    ### Sample payload

    ```json Json theme={"dark"}
    {
    	"data": {
    		"cf_payment_id": 5114910634577,
    		"payment_status": "SUCCESS",
    		"payment_verification_status": "ACTION_REQUIRED",
    		"payment_verification_expiry": "2024-07-12T15:19:42+05:30",
    		"remarks": null,
    		"required_details": [
    			{
                    "doc_name": "shop_or_brand_name",
                    "doc_type": "VALUE",
                    "doc_status": "ACTION_REQUIRED",
                    "remarks": null
                },
                {
                    "doc_name": "partner_order_number",
                    "doc_type": "VALUE",
                    "doc_status": "ACTION_REQUIRED",
                    "remarks": null
                },
                {
                    "doc_name": "goods_description",
                    "doc_type": "VALUE",
                    "doc_status": "ACTION_REQUIRED",
                    "remarks": null
                },
                {
                    "doc_name": "invoice_number",
                    "doc_type": "VALUE",
                    "doc_status": "IN_REVIEW",
                    "remarks": null
                },
                {
                    "doc_name": "importer_name",
                    "doc_type": "VALUE",
                    "doc_status": "IN_REVIEW",
                    "remarks": null
                },
                {
                    "doc_name": "importer_address",
                    "doc_type": "VALUE",
                    "doc_status": "IN_REVIEW",
                    "remarks": null
                },
                {
                    "doc_name": "country_of_origin",
                    "doc_type": "VALUE",
                    "doc_status": "IN_REVIEW",
                    "remarks": null
                },
                {
                    "doc_name": "invoice_file",
                    "doc_type": "DOCUMENT",
                    "doc_status": "IN_REVIEW",
                    "remarks": null
                },
                {
                    "doc_name": "ecommerce_order_serial_number", //Required for Physical Goods and Digital Goods
                    "doc_type": "VALUE",
                    "doc_status": "ACTION_REQUIRED",
                    "remarks": null
                },
                {
                    "doc_name": "hs_code", //Required for Physical Goods and Digital Goods
                    "doc_type": "VALUE",
                    "doc_status": "IN_REVIEW",
                    "remarks": null
                },
                {
                    "doc_name": "shipment_date", //Required for Physical Goods
                    "doc_type": "VALUE",
                    "doc_status": "ACTION_REQUIRED",
                    "remarks": null
                },
                {
                    "doc_name": "port_of_loading",//Required for Physical Goods
                    "doc_type": "VALUE",
                    "doc_status": "IN_REVIEW",
                    "remarks": null
                },
                    {
                    "doc_name": "awb_number",//Required for Physical Goods
                    "doc_type": "VALUE",
                    "doc_status": "IN_REVIEW",
                    "remarks": null
                }
    		]
    	},
    	"event_time": "2024-07-12T13:39:42+05:30",
    	"type": "PAYMENT_VERIFICATION_UPDATE"
    }
    ```
  </Tab>

  <Tab title="Settlement Details">
    ## ICA Settlement details webhook version 1 (2022-09-01)

    The ICA Settlement Details Update webhook notifies you about the ica settlement.

    A notification is sent to your backend from cashfree when there is any new update for ica settlement. These notification are useful in cases when the internet connection is unstable or slow while the payment is getting processed. This will allow you to reconcile all the ica settlement update at your end. Notifications will be sent to **notifyUrl** which is a part of the request parameter specified while creating an order request.

    ### Sample payload

    <br />

    ```json Json theme={"dark"}
    {
    	"data": {
    		"adjustment_amount_inr": -347641.22,
    		"collection_amount_inr": 604854.0,
    		"initiated_on": null,
    		"payment_from": "2024-09-26T15:43:55",
    		"payment_till": "2024-09-26T16:43:13",
    		"service_charge_inr": null,
    		"service_tax_inr": 2068.59,
    		"settled_on": null,
    		"settlement_amount_inr": 243651.95,
    		"settlement_charges_inr": 0.0,
    		"settlement_foreign_currency_details": {
    			"settlement_amount_fcy": null,
    			"settlement_currency": "USD",
    			"settlement_forex_rate": null
    		},
    		"settlement_id": 12,
    		"settlement_tax_inr": 0.0,
    		"settlement_utr": null,
    		"status": "NOT_INITIATED"
    	},
    	"event_time": "2024-10-03T13:27:36+05:30",
    	"type": "ICA_SETTLEMENT_UPDATE"
    }
    ```
  </Tab>

  <Tab title="Signature Verification">
    ## Signature verification

    The signature must be used to verify if the request has not been tampered with. To verify the signature at your end, you will need your Cashfree PG secret key along with the payload.

    timestamp is present in the header x-webhook-timestamp\
    Actual signature is present in the header x-webhook-signature

    ```
    timestamp := 1617695238078;
    signedPayload := $timestamp.$payload;
    expectedSignature := Base64Encode(HMACSHA256($signedPayload, $merchantSecretKey));
    ```
  </Tab>

  <Tab title="Sample Code">
    ## Sample code

    ### Verify Signature using SDK

    <CodeGroup>
      ```node Node(express) theme={"dark"}
      using cashfree_pg.Client;
      using cashfree_pg.Model;

          	[Route("api/[controller]")]
          [ApiController]
          public class YourController : ControllerBase
          {
              [HttpPost]
              public async Task<IActionResult> Post()
              {
                  // Read the raw body of the POST request
                  using (StreamReader reader = new StreamReader(Request.Body, Encoding.UTF8))
                  {
                      string requestBody = await reader.ReadToEndAsync();
                      var headers = Request.Headers;
                      var signature = headers["x-webhook-signature"];
                      var timestamp = headers["x-webhook-timestamp"];

                      Cashfree.XClientId = "<x-client-id>";
                      Cashfree.XClientSecret = "<x-client-secret>";
                      Cashfree.XEnvironment = Cashfree.SANDBOX;
          							var cashfree = new Cashfree();

                      try {
                      var response = cashfree.PGVerifyWebhookSignature(signature, requestBody, timestamp);
                      } catch(Exception e) {
                      // Error if signature mis matches
                      }
                  }
              }
          }

      ```

      ```go Go theme={"dark"}
      import (
        cashfree "github.com/cashfree/cashfree-pg/v4"
      )

      // Route
      e.POST("/webhook", _this.Webhook)

      // Controller
      func (_this *WebhookRoute) Webhook(c echo.Context) error {
        	clientId := "<x-client-id>"
      		clientSecret := "<x-client-secret>"
      		cashfree.XClientId = &clientId
      		cashfree.XClientSecret = &clientSecret
      		cashfree.XEnvironment = cashfree.SANDBOX

          signature := c.Request().Header.Get("x-webhook-signature")
          timestamp := c.Request().Header.Get("x-webhook-timestamp")

          body, _ := ioutil.ReadAll(c.Request().Body)
          rawBody := string(body)
          webhookEvent, err := cashfree.PGVerifyWebhookSignature(signature, rawBody, timestamp)
          if err != nil {
      		fmt.Println(err.Error())
      	} else {
      		fmt.Println(webhookEvent.Object)
      	}
      }
      ```

      ```php PHP theme={"dark"}
      <?php

      $inputJSON = file_get_contents('php://input');

      $expectedSig = getallheaders()['x-webhook-signature'];
      $ts = getallheaders()['x-webhook-timestamp'];

      if(!isset($expectedSig) || !isset($ts)){
          echo "Bad Request";
          die();
      }

      \Cashfree\Cashfree::$XClientId = "<x-client-id>";
      \Cashfree\Cashfree::$XClientSecret = "<x-client-secret>";
      $cashfree = new \Cashfree\Cashfree();

      try {
       $response =  cashfree->PGVerifyWebhookSignature($expectedSig, $inputJSON, $ts);
      } catch(Exception $e) {
        // Error if signature verification fails
      }
      ?>
      ```

      ```python Python theme={"dark"}
      from cashfree_pg.api_client import Cashfree

      @app.route('/webhook', methods = ['POST'])
      def disp():
      		# Get the raw body from the request
          raw_body = request.data

          # Decode the raw body bytes into a string
          decoded_body = raw_body.decode('utf-8')

          #verify_signature
          timestamp = request.headers['x-webhook-timestamp']
          signature = request.headers['x-webhook-signature'

      		cashfree = Cashfree()
      		cashfree.XClientId = "<app_id>"
      		cashfree.XClientSecret = "<secret_key>"
      		try:
      			cashfreeWebhookResponse = cashfree.PGVerifyWebhookSignature(signature, decoded_body, timestamp)
      		except:
      			# If Signature mis-match
      ```

      ```java Java theme={"dark"}
      import com.cashfree.*;

      @PostMapping("/my-endpoint")
      public String handlePost(HttpServletRequest request) throws IOException {
          Cashfree.XClientId = "<x-client-id>";
      		Cashfree.XClientSecret = "<x-client-secret>";
      		Cashfree.XEnvironment = Cashfree.SANDBOX;

        	StringBuilder stringBuilder = new StringBuilder();
          BufferedReader bufferedReader = null;

          try {
            bufferedReader = request.getReader();
            String line;
            while ((line = bufferedReader.readLine()) != null) {
                    stringBuilder.append(line).append('\n');
            }


            String rawBody = stringBuilder.toString();
            String signature = request.getHeader("x-webhook-signature");
            String timestamp = request.getHeader("x-webhook-timestamp");

            Cashfree cashfree = new Cashfree();
            PGWebhookEvent webhook = cashfree.PGVerifyWebhookSignature(signature, rawBody, timestamp);

          } catch (Exception e) {
                  // Error if verification fails
          } finally {
               if (bufferedReader != null) {
                  bufferedReader.close();
      		}
      	}

      }
      ```

      ```c C# theme={"dark"}
      using cashfree_pg.Client;
      using cashfree_pg.Model;


      		[Route("api/[controller]")]
          [ApiController]
          public class YourController : ControllerBase
          {
              [HttpPost]
              public async Task<IActionResult> Post()
              {
                  // Read the raw body of the POST request
                  using (StreamReader reader = new StreamReader(Request.Body, Encoding.UTF8))
                  {
                      string requestBody = await reader.ReadToEndAsync();
                      var headers = Request.Headers;
                      var signature = headers["x-webhook-signature"];
                      var timestamp = headers["x-webhook-timestamp"];

                      Cashfree.XClientId = "<x-client-id>";
                      Cashfree.XClientSecret = "<x-client-secret>";
                      Cashfree.XEnvironment = Cashfree.SANDBOX;
      								var cashfree = new Cashfree();

                      try {
                      var response = cashfree.PGVerifyWebhookSignature(signature, requestBody, timestamp);
                      } catch(Exception e) {
                      // Error if signature mis matches
                      }
                  }
              }
          }
      ```
    </CodeGroup>

    ### Compute Signature and Verify manually

    <CodeGroup>
      ```node Node(express) theme={"dark"}
      function verify(ts, rawBody){
          const body = req.headers["x-webhook-timestamp"] + req.rawBody;
          const secretKey = "<your secret key>";
          let genSignature = crypto.createHmac('sha256',secretKey).update(body).digest("base64");
          return genSignature
      }

      ```

      ```go Go theme={"dark"}
      func VerifySignature(expectedSig string, ts string, body string) (string, error) {
      	t := time.Now()
      	currentTS := t.Unix()
      	if currentTS-ts > 1000*300 {
      		return "", errors.New("webhook delivered too late")
      	}
      	signStr := strconv.FormatInt(ts, 10) + body
      	fmt.Println("signing String: ", signStr)
      	key := ""
      	h := hmac.New(sha256.New, []byte(key))
      	h.Write([]byte(signStr))
      	b := h.Sum(nil)
      	return base64.StdEncoding.EncodeToString(b), nil
      }

      timestamp := c.Request().Header.Get("x-webhook-timestamp")
      body, _ := ioutil.ReadAll(c.Request().Body)
      rawBody := string(body)
      signature := c.Request().Header.Get("x-webhook-signature")

      VerifySignature(signature, timestamp, rawBody)
      ```

      ```php PHP theme={"dark"}
      function computeSignature($ts, $rawBody){
          $rawBody = file_get_contents('php://input');
      		$ts = getallheaders()['x-webhook-timestamp'];

          $signStr = $ts . $rawBody;
          $key = "";
          $computeSig = base64_encode(hash_hmac('sha256', $signStr, $key, true));
          return $computeSig;
      }
      ```

      ```java Java theme={"dark"}
      public String generateSignature() {

      	bufferedReader = request.getReader();
        String line;
        while ((line = bufferedReader.readLine()) != null) {
           stringBuilder.append(line).append('\n');
        }
        String payload = stringBuilder.toString();
        String timestamp = request.getHeader("x-webhook-timestamp");

        String data = timestamp+payload;

        String secretKey = "SECRET-KEY"; // Get secret key from Cashfree Merchant Dashboard;
        Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
        SecretKeySpec secret_key_spec = new SecretKeySpec(secretKey.getBytes(),"HmacSHA256");
        sha256_HMAC.init(secret_key_spec);
        String computed_signature = Base64.getEncoder().encodeToString(sha256_HMAC.doFinal(data.getBytes()));
        return computed_signature; // compare with "x-webhook-signature"
      }
      ```

      ```python Python theme={"dark"}
      import base64
      import hashlib
      import hmac

      def generateSignature():
          # Get the raw body from the request
          raw_body = request.data

          # Decode the raw body bytes into a string
          payload = raw_body.decode('utf-8')

          #verify_signature
          timestamp = request.headers['x-webhook-timestamp']

          signatureData = timestamp+payload
          message = bytes(signatureData, 'utf-8')
          secretkey=bytes("Secret_Key",'utf-8') #Get Secret_Key from Cashfree Merchant Dashboard.
          signature = base64.b64encode(hmac.new(secretkey, message, digestmod=hashlib.sha256).digest())
          computed_signature = str(signature, encoding='utf8')
          return computed_signature #compare with "x-webhook-signature"
      ```
    </CodeGroup>
  </Tab>
</Tabs>


# Overview
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/international-payments/collect-from-india/overview

Use the Collect from India APIs to accept payments from customers in India, designed for overseas merchants, aggregators, and marketplaces.

**Getting Started**

Follow the steps mentioned below to get started with Collect from India APIs

* Fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) for onboarding assistance
* If you are a Merchant, generate your keys using this method [Link](/docs/api-reference/authentication#generate-api-keys)
* Register your webhook URL for updates and subscribe to the required events. For more information, refer to the [Webhook documentation](/docs/api-reference/payments/previous/v2023-08-01/international-payments/collect-from-india/import-webhooks).

Once these setup is completed, we can use the below mentioned collection of APIs to create import transactions

**Collect from India - List of APIs**

| API name | Description |
| :- | :- |
| [Create Order](/docs/api-reference/payments/previous/v2023-08-01/orders/create) | This API will create a order to collect payment |
| [Order Pay](/docs/api-reference/payments/previous/v2023-08-01/payments/pay) | This API is used to pay the created payment |
| [Get Payment by ID](/docs/api-reference/payments/previous/v2023-08-01/payments/get) | This API is used to double verify the payment status |
| [Upload Payment Details](/docs/api-reference/payments/previous/v2023-08-01/international-payments/collect-from-india/upload-payment-verification-details) | This API is used to upload the required payment verification details |
| [Payment Verification Details](/docs/api-reference/payments/previous/v2023-08-01/international-payments/collect-from-india/get-payment-verification-details) | This API is used to Get the verification status of the payment |
| [Payment Settlement Details](/docs/api-reference/payments/previous/v2023-08-01/international-payments/collect-from-india/get-import-settlement-details) | This API is used to get ICA settlement details using PG Order ID |
| [Payment Settlement Recon Details](/docs/api-reference/payments/previous/v2023-08-01/international-payments/collect-from-india/get-import-settlement-recon-details) | This API is used to fetch all events happened for provided Settlement IDs |


# Upload Payment Verification Details
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/international-payments/collect-from-india/upload-payment-verification-details

openapi/cb-imports/merchant-spec.json post /import/transactions/{cf_payment_id}
This API is used to upload the required payment details for theverification.



# End Points
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/international-payments/global-collections/endpoints

Review the production and sandbox base URLs and authentication headers you need to call the Cashfree Global Collections APIs for cross-border payouts.

## Global Collections Gateway End Points

| Environment | Base URL |
| :- | :- |
| Test | [https://sandbox.cashfree.com/](https://sandbox.cashfree.com/) |
| Production | [https://api.cashfree.com/](https://api.cashfree.com/) |


# Overview
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/international-payments/global-collections/overview

Use Cashfree Global Collections to receive international payments into virtual accounts in multiple currencies and settle funds to your Indian bank account.

**Getting Started**

To start using Global Collection APIs,

You can generate your API credentials using the below steps, as applicable.

<Tabs>
  <Tab title="Partner">
    <img />

    <img />
  </Tab>

  <Tab title="Merchant">
    <img />
  </Tab>
</Tabs>

***

Based on who you are, consider the below values in the API requests

<Note>
  | Cashfree Merchant | Cashfree Partner |
  | :- | :- |
  | x-client-id | x-partner-api-key |
  | x-client-secret | x-partner-merchantid |
</Note>

**Global Collections List of APIs**

| API name | Description |
| :- | :- |
| [Get Token](/docs/api-reference/payments/previous/v2023-08-01/international-payments/global-collections/partner/auth-get-token) | This API generates a new token. |
| [Verify Token](/docs/api-reference/payments/previous/v2023-08-01/international-payments/global-collections/partner/auth-verify-token) | Verify the authentication token generated. The response will be ‘Token is not valid’ if the token does not exist, invalid or has been expired. |
| [Get Collection Accounts](/docs/api-reference/payments/previous/v2023-08-01/international-payments/global-collections/partner/get-collection-accounts) | This API fetches all the virtual accounts that are linked with this account. |
| [Get Transactions](/docs/api-reference/payments/previous/v2023-08-01/international-payments/global-collections/partner/get-transactions) | Use this API to get all the transaction details within a time interval. |
| [Add Transaction Details](/docs/api-reference/payments/previous/v2023-08-01/international-payments/global-collections/partner/add-transaction-details) | Use this API to add transaction details to upload multiple invoices until the cumulative total of all invoice amounts matches the transaction amount. |
| [Simulate Transaction](/docs/api-reference/payments/previous/v2023-08-01/international-payments/global-collections/partner/simulate-transaction) | Use this API to simulate funding to any of the virtual accounts of your merchants. |


# Add Transaction Details
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/international-payments/global-collections/partner/add-transaction-details

post /gc/transactions/{referenceId}/invoice-details
Use this API to input invoice details for a specific transaction. You have the flexibility to upload multiple invoices until the cumulative total of all invoice amounts matches the transaction amount.

Based on who you are, consider the below values in the API requests

<Note>
  | Cashfree Merchant | Cashfree Partner |
  | :- | :- |
  | x-client-id | x-partner-api-key |
  | x-client-secret | x-partner-merchantid |
</Note>


# Get Auth Token
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/international-payments/global-collections/partner/auth-get-token

post /gc/authorize
Use this API to authenticate with the Cashfree system and obtain the authorization bearer token.

Based on who you are, consider the below values in the API requests

<Note>
  | Cashfree Merchant | Cashfree Partner |
  | :- | :- |
  | x-client-id | x-partner-api-key |
  | x-client-secret | x-partner-merchantid |
</Note>


# Overview
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/international-payments/global-collections/partner/auth-overview

Learn how Cashfree partners authenticate against the Global Collections APIs by exchanging credentials for a short-lived bearer token before each call.

* [Get Token](/docs/api-reference/payments/previous/v2023-08-01/international-payments/global-collections/partner/auth-get-token) - Use the Get Token API to authenticate with the Cashfree system and obtain the authorisation bearer token, call the authorize API.
* [Verify Token](/docs/api-reference/payments/previous/v2023-08-01/international-payments/global-collections/partner/auth-verify-token) - Verify the authentication token generated. The response will be ‘Token is not valid’ if the token does not exist, invalid or has been expired.


# Verify Auth Token
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/international-payments/global-collections/partner/auth-verify-token

get /gc/token/verify
Verify the authentication token generated by the user.



# Get Collection Accounts
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/international-payments/global-collections/partner/get-collection-accounts

get /gc/virtual-accounts
This API fetches all the virtual accounts that is linked with the given merchant ID.

Based on who you are, consider the below values in the API requests

<Note>
  | Cashfree Merchant | Cashfree Partner |
  | :- | :- |
  | x-client-id | x-partner-api-key |
  | x-client-secret | x-partner-merchantid |
</Note>


# Get Transactions
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/international-payments/global-collections/partner/get-transactions

get /gc/transactions
Use this API to get all the transaction details within a time interval.

Based on who you are, consider the below values in the API requests

<Note>
  | Cashfree Merchant | Cashfree Partner |
  | :- | :- |
  | x-client-id | x-partner-api-key |
  | x-client-secret | x-partner-merchantid |
</Note>


# Overview
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/international-payments/global-collections/partner/overview

Browse the Cashfree Global Collections partner APIs that fetch virtual accounts, list transactions, simulate funding, and manage invoice details at scale.

* [Get All Transactions Details](/docs/api-reference/payments/previous/v2023-08-01/international-payments/global-collections/partner/get-transactions) - Use this to fetch all the transactions for a particular merchant.
* [Emulate Funding](/docs/api-reference/payments/previous/v2023-08-01/international-payments/global-collections/partner/simulate-transaction) - Use this to emulate a transaction for a specific merchant.
* [Get All Collection Accounts for Partner Merchants](/docs/api-reference/payments/previous/v2023-08-01/international-payments/global-collections/partner/get-collection-accounts) - Use this to get all VAs for a specific merchant.
* [Add Invoice Details for Partner Merchants](/docs/api-reference/payments/previous/v2023-08-01/international-payments/global-collections/partner/add-transaction-details) - Use this API to input invoice details for a specific transaction for a specific merchant.
* [Merchant Webhook Configs](/docs/api-reference/payments/previous/v2023-08-01/international-payments/global-collections/partner/webhooks) - Use this document to understand the webhooks payload events and verification.


# Simulate Transaction
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/international-payments/global-collections/partner/simulate-transaction

post /gc/transactions/emulate
Use this API to simulate a funding in test environment.

Based on who you are, consider the below values in the API requests

<Note>
  | Cashfree Merchant | Cashfree Partner |
  | :- | :- |
  | x-client-id | x-partner-api-key |
  | x-client-secret | x-partner-merchantid |
</Note>


# Webhook - Partner
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/international-payments/global-collections/partner/webhooks

Subscribe to Cashfree Global Collections partner webhooks to receive real-time updates whenever international funds arrive in a merchant virtual account.

### Guide to Subscribe Webhook Events

1. Visit [https://partner.cashfree.com](https://partner.cashfree.com) login with your partner credentials
2. On the landing page click on developers section and select webhook, you will be redirected to a page to add webhook URL and subscribe events or once logged in you can use this URL [Webhook Page](https://partner.cashfree.com/partner-ui/dashboard/developers/webhook)
3. Add your webhook URL and subscribe events Global Collect Transaction, Global Collect Settlement & Global Collect Virtual Account
4. To validate the webhook signature follow [Adding webhook and signature verification guide](/docs/api-reference/platforms/latest/merchant-onboarding/webhooks#verify-signature)

### Screenshots:

<Frame>
  <img />
</Frame>

Landing page to add the webhook URL and subscribe the events

<Frame>
  <img />
</Frame>

<Note>
  We can add multiple webhook URLs for the different type of events. For testing, Switch to test and follow the same step in sandbox environment.
</Note>

## Transaction status

Active Event needs to be subscribed: **Global Collect Transaction**

```json Json theme={"dark"}
{
	"amount": "4.50",
	"currency": "GBP",
	"cmsProfileId": 123,
	"event": "INTERNATIONAL_PAYMENT_COLLECTED",
	"merchant": {
		"merchant_id": "CF_7644f46b-ad82-472c-8d97-609d1a429eac"
	},
	"paymentTime": "2022-12-29 13:42:54",
	"referenceId": 63,
	"remarks": "",
	"remitterAccount": "1223456789",
	"remitterAddress": "Dummy Address",
	"remitterBic": "TRWIBEB1XXX",
	"remitterCountry": "GB",
	"remitterName": "Dummy Sender",
	"remitterRoutingCode": "TLG0123",
	"status": "COMPLETED",
	"utr": "5347f52a-9851-4fe9-8618-32eb085590ce",
	"updatedStatusTime": "2022-12-29 13:50:35",
	"vAccountId": "97836",
	"vAccountNumber": "GB38TCCL12345687997836"
}
```

### Possible Events and Corresponding Transaction Status Mapping

| Event name | Payment status | Description |
| :- | :- | :- |
| INTERNATIONAL\_PAYMENT\_COLLECTED | COMPLETED | Received payment |
| INTERNATIONAL\_PAYMENT\_BLOCKED | BLOCKED | The transaction has been blocked due to the specified reason in the designated field. |
| INTERNATIONAL\_PAYMENT\_AWAITING\_DETAILS | COMPLETED | Waiting for the details of the transaction |

### Payload field description

| Field | Description | Example |
| :- | :- | :- |
| amount | The foreign currency amount sent | 4.50 |
| currency | Three character ISO code. View list of supported currencies [here](/docs/payments/global-collections/collection-accounts#supported-currencies). | GBP |
| cmsProfileId | Merchant identifier | 123 |
| event | Webhook event | INTERNATIONAL\_AMOUNT\_COLLECTED |
| paymentTime | The time at which the payment was initiated. | 2022-12-29 13:42:54 |
| referenceId | Cashfree transaction identifier | 63 |
| remarks | Remarks passed by the sender. | Sample Remark |
| reason | Reason regarding the transaction being blocked. | Transaction value below the allowed limit |
| remitterAccount | The bank account number of the person who sends the money. | 1223456789 |
| remitterAddress | The address of the person who sends the money. | Dummy Address |
| remitterBic | Bank identifier code for the remitter. | TRWIBEB1XXX |
| remitterCountry | The country from which the money is sent. | GB |
| remitterName | The name of the remitter who is sending the money. | John Doe |
| remitterRoutingCode | The routing code of the remitter's bank. | TLG0123 |
| status | Status of FCY (foreign currency leg) of transaction. | COMPLETED, FAILED, AWAITING\_DETAILS |
| updatedStatusTime | The time of the last status update. | 2022-12-29 13:50:35 |
| vAccountId | Identifier of the virtual account. | 97836 |
| vAccountNumber | Account number to which the payment was done. | GB38TCCL12345687997836 |
| merchant | Object contains merchant\_id used while creating merchant | CF\_7644f46b-ad82-472c-8d97-609d1a429eac |

***

## Reversal status

```Text JSON theme={"dark"}
{
  "amount": "1000000.00",
  "cmsProfileId": 123,
  "currency": "USD",
  "event": "INTERNATIONAL_PAYMENT_REVERSAL_INITIATED",
  "merchant": {
    "merchant_id": "CF_7644f46b-ad82-472c-8d97-609d1a429eac"
  },
  "paymentTime": "2024-02-28 16:17:48",
  "referenceId": 63,
  "remitterAccount": "9919391193",
  "remitterAddress": "Dummy Address",
  "remarks": "",
  "remitterBic": "",
  "remitterCountry": "IN",
  "remitterName": "Dummy Sender",
  "remitterRoutingCode": "TLG0123",
  "reversal": {
    "reason": "Transaction value higher than the compliant limit",
    "status": "INITIATED"
  },
  "signature": "F8raBNGcGjMUvbh2t/7t/9C4zU0Snqa/iXf9XzvOq0Y=",
  "status": "REVERSAL_INITIATED",
  "updatedStatusTime": "2024-02-28 16:17:54",
  "utr": "IF-20240228-KT9ZFA",
  "vAccountId": "GB75T",
  "vAccountNumber": "GB75TCCL12345654108280"
}

```

### Possible Events and Corresponding Transaction Status Mapping

| Event name | Reversal status | Transaction status | Description |
| :- | :- | :- | :- |
| INTERNATIONAL\_PAYMENT\_REVERSAL\_INITIATED | INITIATED | REVERSAL\_INITIATED | Reversal for the transaction is initiated. |
| INTERNATIONAL\_PAYMENT\_REVERSAL\_DONE | DONE | REVERSAL\_DONE | Reversal for the transaction is completed. The funds have been successfully returned to the sender. |

### Payload field description

***

## Settlement status

Active Event needs to be subscribed: **Global Collect Settlement**

```json theme={"dark"}
{
	"amount": "3500.00",
	"cmsProfileId": 23853384,
	"currency": "USD",
	"event": "INR_SETTLEMENT_INITIATED",
	"merchant": {
		"merchant_id": "CF_7644f46b-ad82-472c-8d97-609d1a429eac"
	},
	"paymentRail": "ACH",
	"paymentTime": "2024-02-06 11:11:42",
	"referenceId": 312620,
	"remarks": "EMULATE GC INCOMING FUNDS",
	"remitterAccount": "7337377781",
	"remitterAddress": "Dummy Address",
	"remitterBic": "TLG0123",
	"remitterCountry": "GB",
	"remitterName": "Dummy Sender",
	"remitterRoutingCode": "TLG0123",
	"settlement": {
		"expectedSettlementDate": "2024-02-06",
		"id": "f16581f5-344c-40e8-be4b-e63cb5714a88",
		"inrAmount": 16219.65,
		"status": "INITIATED"
	},
	"status": "SETTLED",
	"updatedStatusTime": "2024-02-05 18:39:42",
	"utr": "f185d0f5-abf5-492b-9149-d45eacfeaca7",
	"vAccountId": "03314",
	"vAccountNumber": "0331496070"
}
```

<Note>
  The firaFileDownloadUrl field will only be included in the webhook response
  after it has been updated.
</Note>

### Possible Events and Corresponding Settlement Status Mapping

| Event name | Settlement status | Description |
| :- | :- | :- |
| INR\_SETTLEMENT\_INITIATED | INITIATED | The settlement is initiated. |
| INR\_SETTLEMENT\_APPROVED | SETTLED | The settlement is settled. |
| INR\_SETTLEMENT\_REJECTED | REJECTED | The settlement is rejected. |
| FIRA\_FILE\_RECEIVED | SETTLED | FIRA file received for the settlement. |

### Payload field description

| Field | Description | Example |
| :- | :- | :- |
| amount | The foreign currency amount sent | 4.50 |
| currency | Three character ISO code. View list of [supported currencies](/docs/payments/international-payments/global-collections/collection-accounts#supported-currencies). | GBP |
| cmsProfileId | Merchant identifier | 123 |
| event | Webhook event | INTERNATIONAL\_AMOUNT\_COLLECTED |
| merchant | Object contains the merchant\_id to map the merchant created. | CF\_7644f46b-ad82-472c-8d97-609d1a429eac |
| paymentTime | The time at which the payment was initiated. | 2022-12-29 13:42:54 |
| referenceId | Cashfree transaction identifier | 63 |
| remarks | Remarks passed by the sender. | Sample Remark |
| remitterAccount | The bank account number of the person who sends the money. | 1223456789 |
| remitterAddress | The address of the person who sends the money. | Dummy Address |
| remitterBic | Bank identifier code for the remitter. | TRWIBEB1XXX |
| remitterCountry | The country from which the money is sent. | GB |
| remitterName | The name of the remitter who is sending the money. | John Doe |
| remitterRoutingCode | The routing code of the remitter's bank. | TLG0123 |
| status | Status of FCY (foreign currency leg) of transaction. | COMPLETED, FAILED |
| updatedStatusTime | The time of the last status update. | 2022-12-29 13:50:35 |
| vAccountId | Identifier of the virtual account. | 97836 |
| vAccountNumber | Account number to which the payment was made. | GB38TCCL12345687997836 |
| paymentRail | Payment Network used to make the payment | ACH,EFT,FPS,SEPA,SWIFT,FEDWIRE |
| settlement.id | Unique reference ID for the settlement since the payment can have multiple settlements. | b84a7c4c-2ce0-48ca-9b86-2a2c9ad5a35d |
| settlement.firafileDownloadUrl | Download link to FIRA file | fileDownloadUrl |
| settlement.expectedSettlementDate | Expected date of settlement. | 2023-08-30 |
| settlement.inrAmount | Settlement amount in rupees (INR). | 16219.65 |
| settlement.status | Current status of the settlement. | INITIATED |

***

## Virtual account details

Active Event needs to be subscribed: **Global Collect Virtual Account**

```json Json theme={"dark"}
{
	"cmsProfileId": 260559,
	"event": "VIRTUAL_ACCOUNT_DETAILS",
	"merchant": {
		"merchant_id": "CF_7644f46b-ad82-472c-8d97-609d1a429eac"
	},
	"vAccounts": [
		{
			"accountNumber": "GB11TCCL12345638242754",
			"accountType": "iban",
			"paymentType": "priority",
			"bankName": "The Currency Cloud Limited",
			"bankAddress": "12 Steward Street, The Steward Building, London, E1 6FQ, GB",
			"bankCountry": "GB",
			"currency": "AUD",
			"routingCode": "TCCLGB3L",
			"routingCodeType": "bic_swift",
			"addedOn": "2023-03-28 14:43:30",
			"vaccountId": "GB11T"
		},
		{
			"accountNumber": "GB11TCCL12345638242754",
			"accountType": "iban",
			"paymentType": "priority",
			"bankName": "The Currency Cloud Limited",
			"bankAddress": "12 Steward Street, The Steward Building, London, E1 6FQ, GB",
			"bankCountry": "GB",
			"currency": "BHD",
			"routingCode": "TCCLGB3L",
			"routingCodeType": "bic_swift",
			"addedOn": "2023-03-28 14:43:30",
			"vaccountId": "GB11T"
		}
	]
}
```

### Possible Events and Corresponding Virtual Account Mapping

| Event name | Virtual account status | Description |
| - | - | - |
| VIRTUAL\_ACCOUNTS\_ACTIVATED | ACTIVE | Virtual account is activated |
| VIRTUAL\_ACCOUNTS\_CREATED | INACTIVE / ACTIVE | If all the business required details are passed in the first go, VAs are created in ACTIVE state or INACTIVE |
| VIRTUAL\_ACCOUNT\_DETAILS | ACTIVE | Will contain all the details of the VA |

#### Description

Sometimes there is mere might be a slight delay in creating some virtual accounts during onboarding and as a result, some of them might be missing in the Get All Collection Accounts API. Hence, when these missing account details are added, this webhook is triggered with all virtual account details (including the ones that were present before). This webhook contains information for all virtual account associated with a merchant along with cmsProfileId , signature and event.

### Payload field description

| Field | Description | Example |
| :- | :- | :- |
| cmsProfileId | Merchant identifier | 123 |
| event | Webhook Event | VIRTUAL\_ACCOUNT\_DETAILS |
| merchant | Object contains the merchant\_id to map the merchant created. | CF\_7644f46b-ad82-472c-8d97-609d1a429eac |
| vAccounts.accountNumber | Account Number | GB11TCCL12345638242754 |
| vAccounts.accountType | Account Type | iban |
| vAccounts.paymentType | Type of Payment | priority |
| vAccounts.bankName | Bank Name | The Currency Cloud Limited |
| vAccounts.bankAddress | Bank Address | 12 Steward Street, The Steward Building, London, E1 6FQ, GB |
| vAccounts.bankCountry | Bank Country | GB |
| vAccounts.currency | Currency Code | BHD |
| vAccounts.routingCode | Routing Code | TCCLGB3L |
| vAccounts.routingCodeType | Routing Code Type | bic\_swift |
| vAccounts.addedOn | The time when this virtual account was created | 2023-03-28 14:43:30 |
| vAccounts.vaccountId | Virtual Account Id | GB11T |


# Purpose Codes
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/international-payments/global-collections/purpose-codes

Look up the FEMA purpose codes accepted by Cashfree Global Collections so you can classify each cross-border receipt against the correct business reason.

| Purpose code | Description |
| - | - |
| P0103 | Advance receipts against export contracts, which will be covered later by GR/PP/SOFTEX/ SDF - other than Nepal and Bhutan |
| P1004 | Legal services |
| P1005 | Accounting, auditing, bookkeeping services |
| P1006 | Business and management consultancy and public relations |
| P1007 | Advertising, trade fair service |
| P1008 | Research & Development services |
| P1009 | Architectural services |
| P0802 | Software consultancy / implementation (other than those covered in SOFTEX form) |
| P0807 | For Export of Software covered under softex (advance payment) |
| P1020 | Wholesale and retailing trade services |
| P1002 | Trade related services - commission on exports / imports |
| P1104 | Entertainment services |
| P1099 | Other services not included elsewhere, for export of services |
| P1015 | Tax consulting services |
| P1016 | Market research and public opinion polling service |
| P1017 | Publishing and printing services |
| P1019 | Commission agent services |
| P1107 | Educational services |
| P1109 | Other Personal, Cultural & Recreational services |
| P1701 | Receipts on account of processing of goods |
| P0301 | Purchases towards travel (Includes purchases of foreign TCs, currency notes etc over the counter, by hotels, Emporiums, institutions etc. as well as amount received by TT/SWIFT transfers or debit to Non-Resident account). |
| P0302 | Business travel |
| P0304 | Travel for medical treatment including TC purchased by hospitals |
| P0305 | Travel for education including TCs purchased by educational institutions |
| P0306 | Other travel receipts |
| P0801 | Hardware consultancy/implementation |
| P0803 | Data base, data processing charges |
| P0804 | Repair and maintenance of computer and software |
| P0805 | News agency services |
| P0806 | Other information services- Subscription to newspapers, periodicals, etc. |
| P0808 | Telecommunication services including electronic mail services and voice mail services |
| P1013 | Environmental Services |
| P1014 | Engineering Services |
| P1101 | Audio-visual & related service:Motion picture & video tape production, distribution & projection service |
| P1103 | Radio & TV production,distribution & transmission service |
| P1105 | Museums, library and archival services |
| P1106 | Recreation and sporting activity services |
| P1108 | Health Service provided by Indian hospitals,doctors,nurses,paramedical remotely/on-site) |


# Overview
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/international-payments/overview

Discover the Cashfree APIs that power international payments, from accepting payments from India to collecting through global virtual accounts.

You can use the Cashfree API in test mode, which doesn't affect your live data or interact with the banking networks. The API key you use to authenticate the request determines whether the request is live mode or test mode.

<CardGroup>
  <Card title="Collect from India" href="/docs/api-reference/payments/previous/v2023-08-01/international-payments/collect-from-india/overview">
    For overseas businesses to collect payments from Indian customers
  </Card>

  <Card title="Collect from the World" href="/docs/api-reference/payments/previous/v2023-08-01/international-payments/global-collections/overview">
    For Indian businesses to collect payments from customers worldwide
  </Card>
</CardGroup>


# Create Offer
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/offers/create

openapi/payments/v2023-08-01.yaml post /offers
Use this API to create offers with Cashfree from your backend



# Get Offer by ID
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/offers/get

openapi/payments/v2023-08-01.yaml get /offers/{offer_id}
Use this API to get offer by offer_id



# Create Order
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/orders/create

openapi/payments/v2023-08-01.yaml post /orders
### Order
An order is an entity which has a amount and currency associated with it. It is something for which you want to collect payment for.
Use this API to create orders with Cashfree from your backend to get a `payment_sessions_id`. 
You can use the `payment_sessions_id` to create a transaction for the order.




# Get Order
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/orders/get

openapi/payments/v2023-08-01.yaml get /orders/{order_id}
Use this API to fetch the order that was created at Cashfree's using the `order_id`. 
## When to use this API
- To check the status of your order
- Once the order is PAID
- Once your customer returns to `return_url`




# Get Order Extended
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/orders/get-order-extended

openapi/payments/v2023-08-01.yaml get /orders/{order_id}/extended
Use this API to fetch the order related data like address,cart,offers,customer details etc using the Cashfree's `order_id`.
## When to use Get Order Extended API
- To get the extended data associated with order.
- Once the order is PAID
- Once your customer returns to `return_url`


<Note>This API allows you to retrieve payment data for the current and previous financial years. To access data older than this period, log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login)</Note>


# Terminate Order
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/orders/terminate

openapi/payments/v2023-08-01.yaml patch /orders/{order_id}
Use this API to terminate the order that was created at Cashfree's using the `order_id`.



# Update Order Extended
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/orders/update-order-extended

openapi/payments/v2023-08-01.yaml put /orders/{order_id}/extended
Use this api to update the order related data like shipment details,order delivery status etc.
## When to use this API
- To provide/update the shipment details or order delivery status.
- Once the order is PAID.




# End Points
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/overview

Review the production and sandbox base URLs and the authentication headers you need to call the 2023-08-01 Cashfree API endpoints.

<Note>
  Use the latest version of our APIs [v2026-01-01](/docs/api-reference/payments/latest/overview) for any new integrations.
</Note>

## Payment Gateway end points

| Environment | Base URL |
| :- | :- |
| Test | [https://sandbox.cashfree.com/pg](https://sandbox.cashfree.com/pg) |
| Production | [https://api.cashfree.com/pg](https://api.cashfree.com/pg) |
| Latest Version | v4, 2023-08-01 <br /> The previous versions were 2021-05-21, 2022-01-01, 2022-09-01 |

## Authentication

All the APIs require authentication, except the /orders/sessions API, which does not require any authentication and can be safely done from the browser as well.

Click [here](/docs/api-reference/authentication) for detailed information on API Authentication for Merchants and Partners.

***

## Payment Gateway APIs

### Orders

| API | Description |
| :- | :- |
| [Create Order](/docs/api-reference/payments/previous/v2023-08-01/orders/create) | Use this API to create orders with Cashfree from your backend and get the payment link. |
| [Order Pay](/docs/api-reference/payments/previous/v2023-08-01/payments/pay) | Use this API when you have already created the orders and want Cashfree to process the payment. |
| [Preauthorization](/docs/api-reference/payments/previous/v2023-08-01/payments/authorize) | Use this API to capture or void a preauthorized payment. |
| [Get Order](/docs/api-reference/payments/previous/v2023-08-01/orders/get) | Use this API to view all details of an order. |

***

### Authentication

| API | Description |
| :- | :- |
| [Submit or Resend OTP](/docs/api-reference/payments/previous/v2023-08-01/payments/authenticate) | Use the submit or resend OTP API to send OTP to Cashfree. |

***

### Payments

| API | Description |
| :- | :- |
| [Get Payments for an Order](/docs/api-reference/payments/previous/v2023-08-01/payments/get-payments-for-order) | Use this API to view all payment details for an order. |
| [Get Payment by ID](/docs/api-reference/payments/previous/v2023-08-01/payments/get) | Use this API to view payment details of an order for a payment ID. |

***

### Settlements

| API | Description |
| :- | :- |
| [Get Settlements by Order ID](/docs/api-reference/payments/previous/v2023-08-01/settlements/settlements-for-order) | Use this API to view all the settlements of a particular order. |
| [Get All Settlements](/docs/api-reference/payments/previous/v2023-08-01/settlements/settlements) | Use this API to get all settlement details by specifying the settlement ID, settlement UTR or date range. |

***

### Payment links

| API | Description |
| :- | :- |
| [Create Payment Link](/docs/api-reference/payments/previous/v2023-08-01/payment-links/create) | Use this API to create a new payment link. The created payment link url will be available in the API response parameter link\_url. |
| [Fetch Payment Link Details](/docs/api-reference/payments/previous/v2023-08-01/payment-links/get) | Use this API to view all details and status of a payment link. |
| [Get Orders for a Payment Link](/docs/api-reference/payments/previous/v2023-08-01/payment-links/get-orders-for-link) | Use this API to view all order details for a payment link. |
| [Cancel Payment Link](/docs/api-reference/payments/previous/v2023-08-01/payment-links/cancel) | Use this API to cancel a payment link. No further payments can be done against a cancelled link. Only a link in ACTIVE status can be cancelled. |

### Token vault

| API | Description |
| :- | :- |
| [Fetch All Saved Instruments](/docs/api-reference/payments/previous/v2023-08-01/token-vault/get-all) | Use this API to get all saved instruments for a customer ID. |
| [Fetch Single Saved Instrument](/docs/api-reference/payments/previous/v2023-08-01/token-vault/fetch-specific-saved-card-instrument) | Use this API to get specific saved instrument for a customer id and instrument ID. |
| [Delete Saved Instrument](/docs/api-reference/payments/previous/v2023-08-01/token-vault/delete) | Use this API to delete a saved instrument for a customer id and instrument ID. |
| [Fetch Cryptogram for Saved Instrument](/docs/api-reference/payments/previous/v2023-08-01/token-vault/generate-cryptogram) | Use this API to get the card network token, token expiry and cryptogram for a saved instrument using instrument ID. |

***

### Reconciliation

| API | Description |
| :- | :- |
| [Settlement Reconciliation](/docs/api-reference/payments/previous/v2023-08-01/settlements/settlement-reconciliation) | Use this API to get settlement reconciliation details using Settlement ID, settlement UTR or date range. |
| [PG Reconciliation](/docs/api-reference/payments/previous/v2023-08-01/settlements/reconcile) | Use this API to get the payment gateway reconciliation details with date range. |


# Create Pre-Activated Vpas for partner
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/partners/create-pre-activated-vpas-for-partner

openapi/payments/v2023-08-01.yaml post /partners/merchant/qrcodes
Use this API to create a pre-activated vpa for partner.



# Get Pre-Activated Vpas for partner
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/partners/get-pre-activated-vpas-for-partner

openapi/payments/v2023-08-01.yaml get /partners/merchant/qrcodes
Use this API to get a pre-activated vpa for partner.



# Cancel Payment Link
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/payment-links/cancel

openapi/payments/v2023-08-01.yaml post /links/{link_id}/cancel
Use this API to cancel a payment link. No further payments can be done against a cancelled link. Only a link in ACTIVE status can be cancelled.



# Create Payment Link
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/payment-links/create

openapi/payments/v2023-08-01.yaml post /links
Use this API to create a new payment link. The created payment link url will be available in the API response parameter link_url.



# Get Orders for a Payment Link
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/payment-links/get

openapi/payments/v2023-08-01.yaml get /links/{link_id}/orders
Use this API to view all order details for a payment link.



# Fetch Payment Link Details
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/payment-links/get-orders-for-link

openapi/payments/v2023-08-01.yaml get /links/{link_id}
Use this API to view all details and status of a payment link.



# Payment Link Webhooks
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/payment-links/webhooks

Subscribe to Cashfree Payment Link webhooks so your server is notified whenever a link is paid, expires, or moves to a new status in real time.

## Webhook Schema

Payment Link webhook will be triggered when your customer makes a complete or partial payment using the payment link you shared. You will also be notified via the same webhook when the payment link gets cancelled or expired.

```json theme={"dark"}
{
	"data": {
		"cf_link_id": 1576977,
		"link_id": "payment_ps11",
		"link_status": "PARTIALLY_PAID",
		"link_currency": "INR",
		"link_amount": "200.12",
		"link_amount_paid": "55.00",
		"link_partial_payments": true,
		"link_minimum_partial_amount": "11.00",
		"link_purpose": "Payment for order 10",
		"link_created_at": "2021-08-18T07:13:41",
		"customer_details": {
			"customer_phone": "9000000000",
			"customer_email": "john@gmail.com",
			"customer_name": "John "
		},
		"link_meta": {
			"notify_url": "https://ee08e626ecd88c61c85f5c69c0418cb5.m.pipedream.net"
		},
		"link_url": "https://payments-test.cashfree.com/links//U1mgll3c0e9g",
		"link_expiry_time": "2021-11-28T21:46:20",
		"link_notes": {
			"note_key_1": "note_value_1"
		},
		"link_auto_reminders": true,
		"link_notify": {
			"send_sms": true,
			"send_email": true
		},
		"order": {
			"order_amount": "22.00",
			"order_id": "CFPay_U1mgll3c0e9g_ehdcjjbtckf",
			"order_expiry_time": "2021-08-18T07:34:50",
			"order_hash": "Gb2gC7z0tILhGbZUIeds",
			"transaction_id": 1021206,
			"transaction_status": "SUCCESS"
		}
	},
	"type": "PAYMENT_LINK_EVENT",
	"version": 1,
	"event_time": "2021-08-18T12:55:06+05:30"
}
```

***

## Payload

| Field | Description | Example |
| :- | :- | :- |
| `cf_link_id` | Unique Identifier (generated by Cashfree) for this Link. | 1543566 |
| `link_id` | Unique Identifier (provided by merchant) for the Link. Only for merchant reference. | payment\_1psw |
| `link_status` | Current status of the payment link. Possible values: PAID, PARTIALLY\_PAID, EXPIRED, CANCELLED. | PARTIALLY\_PAID |
| `link_currency` | Default is INR. International currencies are supported. | INR |
| `link_amount` | The amount which merchant wants to collect for the order. | 500.00 |
| `link_amount_paid` | The amount paid by the customer. | 250.00 |
| `link_partial_payments` | Indicates if partial payments are allowed or not. Default value is false. | true |
| `link_minimum_partial_amount` | The minimum amount which must be paid by customer as the first payment. | 200.00 |
| `link_purpose` | A brief description for which payment must be collected. This is shown to the customer. | Payment for order 10 |
| `link_created_at` | Time at which the link was created. | 2021-08-18T07:13:41 |
| `customer_details` | Customer object, it contains customer details. | |
| `customer_name` | Name of the customer | John |
| `customer_phone` | Phone number of the customer | 9000000000 |
| `customer_email` | Email ID of the customer | [john@gmail.com](mailto:john@gmail.com) |
| `notify_url` | Payment notification URL | [https://payment1notify.net](https://payment1notify.net) |
| `link_url` | Payment link URL | [https://website.com/payments](https://website.com/payments) |
| `link_expiry_time` | The date till which the link will be valid, and then it will be expired. Default is 30 days. | 2021-11-28T21:46:20 |
| `link_notes` | Link notes object where you can provide any key-value pairs for your internal reference. | |
| `note_key_1` | | note\_value\_1 |
| `link_auto_reminders` | Default is false. Reminders will be sent to customers based on defined settings. | true |
| `link_notify` | Link notify object, used to notify customers via SMS or an email. | |
| `send_sms` | Default is true. If true, Cashfree will send the link to customer via SMS. | true |
| `send_email` | Default is true. If true and `customer_email` is provided, Cashfree will send the link via Email. | true |
| `order` | Order object, contains the order details. Will be null for cancelled and expired link statuses. | |
| `order_amount` | Order amount that the customer must pay. | 700 |
| `order_id` | The order ID generated. | order\_10 |
| `order_expiry_time` | The date till which the order will be valid. Default is 30 days. | 2021-08-18T07:34:50 |
| `transaction_id` | Transaction ID | id45466ye |
| `transaction_status` | Status of the transaction. Possible values: SUCCESS. | SUCCESS |
| `type` | Type of the webhook. `PAYMENT_LINK_EVENT` | PAYMENT\_LINK\_EVENT |
| `version` | The version of webhook. Build parsing logic with respect to this version. | 1 |
| `event_time` | Time when this webhook was created. | 2021-08-18T12:55:06+05:30 |

***

## Signature generation

The signature must be used to verify if the request has not been tampered with. To verify the signature at your end, you will need your Cashfree Payment Gateway secret key along with the payload.

```javascript theme={"dark"}
// The payload here refers to the raw request sent by
// Cashfree to your endpoint. No modifications need to be made to this payload.
{
    "data": {
        "cf_link_id": 1576977,
        "link_id": "payment_ps11",
        "link_status": "PARTIALLY_PAID",
        "link_currency": "INR",
        "link_amount": "200.12",
        "link_amount_paid": "55.00",
        "link_partial_payments": true,
        "link_minimum_partial_amount": "11.00",
        "link_purpose": "Hello my friend how are you",
        "link_created_at": "2021-08-18T07:13:41",
        "customer_details": {
            "customer_phone": "9905736722",
            "customer_email": "customer@example.com",
            "customer_name": "Supal "
        },
        "link_meta": { ... }
    }
}
```

<Note>We send the webhook response in a form data format.</Note>


# Get Eligible Cardless EMI Payment Methods for a customer on an order
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/payment-methods/get-emi-for-customer-order

openapi/payments/v2023-08-01.yaml post /eligibility/cardlessemi
Use this API to get eligible Cardless EMI Payment Methods available for a customer on an order basis their phone number.



# Get Eligible Offers for an Order
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/payment-methods/get-offers-for-order

openapi/payments/v2023-08-01.yaml post /eligibility/offers
Use this API to get eligible offers for an order_id or order amount.



# Get Eligible Paylater for a customer on an order
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/payment-methods/get-paylater-for-customer-order

openapi/payments/v2023-08-01.yaml post /eligibility/paylater
Use this API to get eligible Paylater Payment Methods for a customer on an order.



# Get eligible Payment Methods
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/payment-methods/get-payment-methods

openapi/payments/v2023-08-01.yaml post /eligibility/payment_methods
Use this API to get eligible Payment Methods



# Submit or Resend OTP
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/payments/authenticate

openapi/payments/v2023-08-01.yaml post /orders/pay/authenticate/{cf_payment_id}
If you accept OTP on your own page, you can use the below API to send OTP to Cashfree.



# Preauthorization
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/payments/authorize

openapi/payments/v2023-08-01.yaml post /orders/{order_id}/authorization
Use this API to capture or void a preauthorized payment



# Get Payment by ID
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/payments/get

openapi/payments/v2023-08-01.yaml get /orders/{order_id}/payments/{cf_payment_id}
Use this API to view payment details of an order for a payment ID.



# Get Payments for an Order
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/payments/get-payments-for-order

openapi/payments/v2023-08-01.yaml get /orders/{order_id}/payments
Use this API to view all payment details for an order.



# Order Pay
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/payments/pay

openapi/payments/v2023-08-01.yaml post /orders/sessions
Use this API when you have already created the orders and want Cashfree to process the payment. To use this API S2S flag needs to be enabled
from the backend. In case you want to use the cards payment option the PCI
DSS flag is required, reach out to us by filling out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod&raise_issue=1)".




# Payment Webhooks
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/payments/webhooks

Subscribe to Cashfree payment webhooks to receive asynchronous events for successful, failed, and user-dropped payment attempts on your orders.

Webhooks are server callbacks to your server from Cashfree. Cashfree sends webhooks for the following events for a `payment`:

* [Payment success webhook](/docs/api-reference/payments/previous/v2023-08-01/payments/webhooks#payment-success-webhook)
* [Payment failed webhook](/docs/api-reference/payments/previous/v2023-08-01/payments/webhooks#payment-failed-webhook)
* [Payment user dropped webhook](/docs/api-reference/payments/previous/v2023-08-01/payments/webhooks#payment-user-dropped-webhook)
* [Payment charges webhook](/docs/api-reference/payments/previous/v2023-08-01/payments/webhooks#payment-charges-webhook)

## Payment success webhook

A payment success webhook is triggered when a payment is successfully completed. You can use this for: Updating order status, triggering fulfilment, send confirmation to customer.

<Note>Some parameters in the API response may return null values depending on the flow type. In the Flowwise flow, all actual parameter values are returned. However, in other flows, some fields in the response may contain null.</Note>

<Tabs>
  <Tab title="Version (2023-08-01)">
    ```javascript Version (2023-08-01) theme={"dark"}
    {
    "data": {
    "order": {
      "order_id": "order_OFR_2",
      "order_amount": 2,
      "order_currency": "INR",
      "order_tags": null
    },
    "payment": {
      "cf_payment_id": "1453002795",
      "payment_status": "SUCCESS",
      "payment_amount": 1,
      "payment_currency": "INR",
      "payment_message": "00::Transaction success",
      "payment_time": "2022-12-15T12:20:29+05:30",
      "bank_reference": "234928698581",
      "auth_id": null,
      "payment_method": {
        "upi": {
          "channel": "collect",
          "upi_id": "suhasg6@ybl"
        }
      },
      "payment_group": "upi"
    },
    "customer_details": {
      "customer_name": null,
      "customer_id": "7112AAA812234",
      "customer_email": "test@gmail.com",
      "customer_phone": "9908734801"
    },
    "payment_gateway_details": {
      "gateway_name": "CASHFREE",
      "gateway_order_id": "1634766330",
      "gateway_payment_id": "1504280029",
      "gateway_order_reference_id": "abc_124",
      "gateway_settlement": "CASHFREE",
      "gateway_status_code": null
    },
    "payment_offers": [
      {
        "offer_id": "0f05e1d0-fbf8-4c9c-a1f0-814c7b2abdba",
        "offer_type": "DISCOUNT",
        "offer_meta": {
          "offer_title": "50% off on UPI",
          "offer_description": "50% off for testing",
          "offer_code": "UPI50",
          "offer_start_time": "2022-11-09T06:23:25.972Z",
          "offer_end_time": "2023-02-27T18:30:00Z"
        },
        "offer_redemption": {
          "redemption_status": "SUCCESS",
          "discount_amount": 1,
          "cashback_amount": 0
        }
      }
    ]
    },
    "event_time": "2023-08-01T11:16:10+05:30",
    "type": "PAYMENT_SUCCESS_WEBHOOK"
    }
    ```
  </Tab>
</Tabs>

## Payment failed webhook

The payment failed webhook notifies you when a payment attempt fails and we receive a failed response from the bank. Use case: Update order status, notify customer, initiate retry flow

<Tabs>
  <Tab title="Version 2023-08-01">
    ```javascript Version 2023-08-01 theme={"dark"}
    {
    "data": {
    "order": {
      "order_id": "CFPay_d8bjgga36hmg_gc2pgapl4t",
      "order_amount": 1924,
      "order_currency": "INR",
      "order_tags": {
        "cf_link_id": "6420634"
      }
    },
    "payment": {
      "cf_payment_id": "5114917126974",
      "payment_status": "FAILED",
      "payment_amount": 1924,
      "payment_currency": "INR",
      "payment_message": "Internal Server Error",
      "payment_time": "2025-04-03T14:57:38+05:30",
      "bank_reference": null,
      "auth_id": null,
      "payment_method": {
        "cardless_emi": {
          "channel": null,
          "provider": "flexmoney",
          "phone": "+919611199227",
          "emi_details": null
        }
      },
      "payment_group": "cardless_emi"
    },
    "customer_details": {
      "customer_name": null,
      "customer_id": null,
      "customer_email": null,
      "customer_phone": "+919611199227"
    },
    "error_details": {
      "error_code": "TRANSACTION_DECLINED",
      "error_description": "payment has been declined",
      "error_reason": "debit_failed",
      "error_source": "bank",
      "error_code_raw": null,
      "error_description_raw": null,
      "error_subcode_raw": null
    },
    "payment_gateway_details": {
      "gateway_name": "CASHFREE",
      "gateway_order_id": "2191827274",
      "gateway_payment_id": "5114917126974",
      "gateway_status_code": null,
      "gateway_order_reference_id": "null",
      "gateway_settlement": null,
      "gateway_reference_name": null
    },
    "payment_offers": null
    },
    "event_time": "2025-04-03T14:57:38+05:30",
    "type": "PAYMENT_FAILED_WEBHOOK"
    }
    ```
  </Tab>
</Tabs>

## Payment user dropped webhook

The User Dropped Webhook notifies you when your customer abandons the payment flow. It will help you understand if customers attempted to pay or not. Some common scenarios where the transaction will be marked as USER\_DROPPED are:

* User was redirected to the bank's OTP page, but never entered the OTP.
* User was redirected to open the UPI app, but never entered the UPI PIN.
* User was shown the 3ds OTP modal, but did not enter the OTP.

<Tabs>
  <Tab title="Version 2023-08-01">
    ```javascript Version 2023-08-01 theme={"dark"}
    {
    "data": {
    "order": {
      "order_id": "order_02",
      "order_amount": 2,
      "order_currency": "INR",
      "order_tags": null
    },
    "payment": {
      "cf_payment_id": "975672265",
      "payment_status": "USER_DROPPED",
      "payment_amount": 2,
      "payment_currency": "INR",
      "payment_message": "User dropped and did not complete the two factor authentication",
      "payment_time": "2022-05-25T14:25:34+05:30",
      "bank_reference": "1803592531",
      "auth_id": "2980",
      "payment_method": {
        "netbanking": {
          "channel": null,
          "netbanking_bank_code": "3044",
          "netbanking_bank_name": "State Bank Of India"
        }
      },
      "payment_group": "net_banking"
    },
    "customer_details": {
      "customer_name": null,
      "customer_id": "7112AAA812234",
      "customer_email": "test@gmail.com",
      "customer_phone": "9611199227"
    }
    },
    "event_time": "2022-05-25T14:35:38+05:30",
    "type": "PAYMENT_USER_DROPPED_WEBHOOK"
    }
    ```
  </Tab>
</Tabs>

## Payment charges webhook

A payment charges webhook is triggered after a successful payment when Cashfree finalises the Transaction Discount Rate (TDR) and related charges for that payment. The event time can be later than the payment time. Use this webhook to reconcile per-payment charges and the net settlement amount.

To receive this event, subscribe to **Success Payment TDR** when you [configure webhooks](/docs/payments/online/webhooks/configure) in the Merchant Dashboard. The webhook `type` in the payload is `PAYMENT_CHARGES_WEBHOOK`.

<Note>
  The `payment_method` object in this webhook can be empty (`{}`). This is expected for the payment charges event.
</Note>

For background on TDR, see [What is TDR?](/docs/help/account/pricing#what-is-tdr).

### `charges_details` fields

| Field | Description | Example |
| - | - | - |
| `service_charge` | Service charge (TDR) applicable for the payment. | `0.12` |
| `service_tax` | Service tax applicable on the service charge. | `0.02` |
| `settlement_amount` | Net amount for the payment after deducting the service charge and service tax. | `5.86` |
| `settlement_currency` | Currency of the settlement amount. | `INR` |
| `service_charge_discount` | Discount applied on the service charge, if any. Returns `null` when no discount applies. | `null` |

<Tabs>
  <Tab title="Version 2023-08-01">
    ```javascript Version 2023-08-01 theme={"dark"}
    {
    "data": {
    "order": {
      "order_id": "14508_73_1783668483731",
      "order_amount": 6.00,
      "order_currency": "INR",
      "order_tags": null
    },
    "payment": {
      "cf_payment_id": 5979305158,
      "payment_status": "SUCCESS",
      "payment_amount": 6.00,
      "payment_currency": "INR",
      "payment_message": "SUCCESS",
      "payment_time": "2026-07-10T12:58:04+05:30",
      "bank_reference": "841754751916",
      "auth_id": null,
      "payment_method": {},
      "payment_group": "sbc_upi"
    },
    "customer_details": {
      "customer_name": null,
      "customer_id": null,
      "customer_email": "rfeef@gmail.com",
      "customer_phone": "9876543211"
    },
    "charges_details": {
      "service_charge": 0.12,
      "service_tax": 0.02,
      "settlement_amount": 5.86,
      "settlement_currency": "INR",
      "service_charge_discount": null
    }
    },
    "event_time": "2026-07-15T08:00:05+05:30",
    "type": "PAYMENT_CHARGES_WEBHOOK"
    }
    ```
  </Tab>
</Tabs>

## Sample payload by payment method

The instrument used for making a payment will vary by the payment methods used by the customer. Details of the payload by payment method are documented for reference.

<Tabs>
  <Tab title="Card">
    ```javascript theme={"dark"}
    {
      ...,
      "payment_method": {  
        "card": {  
          "channel": null,  
          "card_number": "470613XXXXXX2123",  
          "card_network": "visa",  
          "card_type": "credit_card",  
          "card_sub_type": "C",  
          "card_country": "IN",  
          "card_bank_name": "TEST Bank"  ,  
          "card_network_reference_id": "100212023061200000001014824849"  
        }  
      },  
      "payment_group": "credit_card",
      ...
    }

    ```
  </Tab>

  <Tab title="Net Banking">
    ```javascript theme={"dark"}
    {
      ...,
      "payment_method": {  
        "netbanking": {  
          "channel":null,  
          "netbanking_bank_code":"3022",  
          "netbanking_bank_name":"ICICI Bank"  
        }  
      },  
      "payment_group":"net_banking",
      ...
    }

    ```
  </Tab>

  <Tab title="UPI">
    ```javascript theme={"dark"}
    {
      ...,
      "payment_method": {  
        "upi": {
                "channel": "collect",
                "upi_id": "suhasg6@ybl",
            }  
      },
      "payment_group":"upi",
      ...
    }

    ```
  </Tab>

  <Tab title="Wallet">
    ```javascript theme={"dark"}
    {
      ...,
      "payment_method": {  
        "app": {  
          "channel":"AmazonPay",  
          "upi_id":null  
        }  
      },  
      "payment_group":"wallet",
      ...
    }

    ```
  </Tab>

  <Tab title="Credit Card EMI">
    ```javascript theme={"dark"}
    {
      ...,
      "payment_method":{  
        "card":{  
          "channel":null,  
          "card_number":"XXXXXXXXXX8952",  
          "card_network":null,  
          "card_type":"credit_card_emi",  
          "card_country":null,  
          "card_bank_name":"HDFC BANK",  
          "emi_details":{  
            "emi_amount":1167,  
            "emi_tenure":3,  
            "emi_interest":16.00  
          }  
        }  
      },  
      "payment_group":"credit_card_emi",
      ...
    }

    ```
  </Tab>

  <Tab title="Debit Card EMI">
    ```javascript theme={"dark"}
    {
      ...,
      "payment_method":{  
        "card":{  
          "channel":null,  
          "card_number":"XXXXXXXXXX8952",  
          "card_network":null,  
          "card_type":"debit_card_emi",  
          "card_country":null,  
          "card_bank_name":"HDFC BANK",  
          "emi_details":{  
            "emi_amount":1167,  
            "emi_tenure":3,  
            "emi_interest":16.00  
          }  
        }  
      },  
      "payment_group":"debit_card_emi",
      ...
    }

    ```
  </Tab>

  <Tab title="Cardless EMI">
    ```javascript theme={"dark"}
    {
      ...,
      "payment_method":{  
        "cardless_emi":{  
          "channel":null,  
          "provider":"flexmoney",  
          "phone":"9731117102",  
          "emi_details":null  
        }  
      },  
      "payment_group":"cardless_emi",
      ...
    }

    ```
  </Tab>

  <Tab title="Pay Later">
    ```javascript theme={"dark"}
    {
      ...,
      "payment_method":{  
        "pay_later":{  
        "channel":null,  
        "provider":"olapostpaid",  
        "phone":"9731117102"  
        }  
      },  
      "payment_group":"pay_later",
      ...
    }

    ```
  </Tab>
</Tabs>


# Create VBA
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/pgvba/create-vba

openapi/pgvba/pgvba.yaml post /pg/vba
Use this API to create a virtual bank account. It allows you to receive payments just like a regular bank account.



# Create VBA Notification Group
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/pgvba/create-vba-notification-group

openapi/pgvba/pgvba.yaml post /pg/vba/notificationgroup
Use this API to create a notification group. The recipients in the group will receive notifications regarding the payment details.



# Edit VBA
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/pgvba/edit-vba

openapi/pgvba/pgvba.yaml put /pg/vba/{virtual_account_id}
Use this API to edit the details of the created virtual bank account.



# Edit VBA Notification Group
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/pgvba/edit-vba-notification-group

openapi/pgvba/pgvba.yaml put /pg/vba/notificationgroup/{notification_group_name}
Use this API to edit the details of the created notification group.



# Get VBA
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/pgvba/get-vba

openapi/pgvba/pgvba.yaml get /pg/vba/{virtual_account_id}
Use this API to get the details of the created virtual bank account by entering the virtual account ID.



# Get VBA Notification Group
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/pgvba/get-vba-notification-group

openapi/pgvba/pgvba.yaml get /pg/vba/notificationgroup/{notification_group_name}
Use this API to get the details of the created notification group.



# Get VBA Payments
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/pgvba/get-vba-payments

openapi/pgvba/pgvba.yaml get /pg/vba/{virtual_account_id}
Use this API to get the details of the created virtual bank account by entering the virtual account ID.



# Get VBA Payments By UTR
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/pgvba/get-vba-payments-by-utr

openapi/pgvba/pgvba.yaml get /pg/vba/payments/{utr}
Use this API to get the payment details by entering the unique transaction reference (UTR).



# Manage VBA
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/pgvba/manage-vba

openapi/pgvba/pgvba.yaml patch /pg/vba/{virtual_account_id}
Use this API to manage the status of the created virtual bank account.



# Manage VBA Notification Group Status
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/pgvba/manage-vba-notification-group-status

openapi/pgvba/pgvba.yaml patch /pg/vba/notificationgroup/{notification_group_name}
Use this API to modify the status of the created notification group.



# Create Refund
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/refunds/create

openapi/payments/v2023-08-01.yaml post /orders/{order_id}/refunds
Use this API to initiate refunds.



# Get Refund
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/refunds/get

openapi/payments/v2023-08-01.yaml get /orders/{order_id}/refunds/{refund_id}
Use this API to fetch a specific refund processed on your Cashfree Account.



# Get All Refunds for an Order
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/refunds/get-refunds-for-order

openapi/payments/v2023-08-01.yaml get /orders/{order_id}/refunds
Use this API to fetch all refunds processed against an order.



# Refund Webhooks
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/refunds/webhooks

Subscribe to Cashfree refund webhooks to track when a refund is initiated, succeeds, or fails so you can keep your records and customers in sync.

Webhooks are server callbacks to your server from Cashfree. We send refund webhooks for three different events for a payment.

1. Refund is successfully processed
2. Refund is cancelled by Cashfree - we were unable to successfully refund to customer even after multiple attempts.
3. For successful Auto-refunds - Read more about Auto-Refunds [here](/docs/payments/manage/refunds/overview#auto-refunds)

## Refund Webhook Payload

```javascript Refund Webhook Payload theme={"dark"}
{
"data":{
    "refund":{
         "cf_refund_id":11325632,
         "cf_payment_id":789727431,
         "refund_id":"refund_sampleorder0413",
         "order_id":"sampleorder0413",
         "refund_amount":2.00,
         "refund_currency":"INR",
         "entity":"Refund",
         "refund_type":"MERCHANT_INITIATED",
         "refund_arn":"205907014017",
         "refund_status":"SUCCESS",
         "status_description":"Refund processed successfully",
         "created_at":"2022-02-28T12:54:25+05:30",
         "processed_at":"2022-02-28T13:04:27+05:30",
         "refund_charge":0,
         "refund_note":"Test",
         "refund_splits":[
            {
               "merchantVendorId":"sampleID12345",
               "amount":1,
               "percentage":null
            },
            {
               "merchantVendorId":"otherVendor",
               "amount":1,
               "percentage":null
            }
         ],
         "metadata":null,
         "refund_mode":"STANDARD"
      }
   },
   "event_time":"2022-02-28T13:04:28+05:30",
   "type":"REFUND_STATUS_WEBHOOK"
}
```

## Auto Refund Webhook Payload

Auto-refund webhooks differ from standard refund webhooks because they handle refunds that occur automatically (like failed payment attempts) rather than manual refunds tied to specific orders. Since these automatic refunds may happen before an order is created, they don't contain the usual order-related data fields that are mandatory in standard refund webhooks,

```javascript Auto-refund webhook payload theme={"dark"}
{
  "data": {
    "auto_refund": {
      "event": "AUTO-REFUND",
      "cf_refund_id": 1243460973,
      "cf_payment_id": "2148333968",
      "bank_reference": "234928698581",
      "order_id": "order_1944392Tpba8y2fHcHVx0SwREojp51Jgr",
      "refund_amount": 39,
      "refund_currency": "INR",
      "refund_type": "PAYMENT_AUTO_REFUND",
      "refund_arn": "205907014017",
      "refund_status": "SUCCESS",
      "status_description": "Auto-Refund processed successfully",
      "refund_reason": "Multiple payments were performed against same order.",
      "created_at": "2023-08-11T14:08:28+05:30",
      "processed_at": null,
      "refund_charge": 0,
      "refund_splits": null,
      "metadata": null
    }
  },
  "event_time": "2023-08-11T14:10:21+05:30",
  "type": "AUTO_REFUND_STATUS_WEBHOOK"
}

```


# Release Notes for v2023-08-01
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/release-notes

Explore key changes in the Cashfree API version 2023-08-01 release, covering breaking updates, new headers, and entity changes.

Following are the key changes made in the version 2023-08-01:

<Steps>
  <Step title="New header in API Response">
    New header "x-deprecated-at" is added in the API response which will let you
    know the date when the used version is going to get deprecated.
  </Step>

  <Step title="Cashfree IDs type change [BREAKING]">
    All cashfree IDs like `cf_order_id`, `cf_payment_id`, `cf_refund_id` etc are
    now in **string** format instead of **integer** (in older versions).
  </Step>

  <Step title="Order Entity Changes">
    1. We have removed payments, refunds, settlements urls from order entity. 2.
       `customer_uid` part of customer\_details in order entity. This is the unique
       identifier of the customer created at Cashfree. You can create customer at
       cashfree using [Create Customer API](/docs/api-reference/payments/previous/v2023-08-01/customers/create) 3.
       `order_status` can have two more values - "TERMINATED" and
       "TERMINATION\_REQUESTED". Find the complete list of order statuses
       [here](/docs/payments/online/resources/payment-lifecycle#order-states) 4. No longer
       support for `notify_url` in Create Order API. You can [configure
       webhooks](/docs/api-reference/payments/previous/v2023-08-01/payments/webhooks) from dashboard instead.
  </Step>

  <Step title="New Order Termination API">
    We have released a new API to terminate an Order. Find API details - [Order
    Termination API.](/docs/v4/reference/pgterminateorder)
  </Step>

  <Step title="New Customer APIs">
    We have released Customer APIs to let merchants create and manager their
    customers. Find more about this here - [Customer
    Management](/docs/api-reference/payments/previous/v2023-08-01/customers/create)
  </Step>

  <Step title="New SPOS APIs">
    Find newly released [SPOS APIs](/docs/api-reference/payments/previous/v2023-08-01/softpos/create-terminal-transaction)
  </Step>

  <Step title="CF Refund IDs">
    Earlier cf\_refund\_id used to start with a prefix "refund\_". In this
    version, you will not get that prefix and cf\_refund\_id will be directly be
    the id without any prefix. Example - OLD cf\_refund\_id = "refund\_41805719" ,
    NEW cf\_refund\_id = "41805719"
  </Step>
</Steps>


# Mark Order For Settlement
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/settlements/mark-order-for-settlement

openapi/payments/v2023-08-01.yaml post /orders/settlements
Use this API to pass the CBRICS ID to Cashfree and mark an order for settlement.



# PG Reconciliation
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/settlements/reconcile

openapi/payments/v2023-08-01.yaml post /recon
- Use this API to get the payment gateway reconciliation details with date range.
- It will have events for your payment account




# Settlement Reconciliation
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/settlements/settlement-reconciliation

openapi/payments/v2023-08-01.yaml post /settlement/recon
- Use this API to get settlement reconciliation details using Settlement ID, settlement UTR or date range.
- This API will return events for the settlement IDs you want




# Settlement Webhooks
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/settlements/settlement-webhooks

Subscribe to Cashfree settlement webhooks so your reconciliation system is alerted whenever a payout to your merchant or vendor account completes.

We broadly send two types of notifications when a payout happens.

1. Payout to Merchant account
2. Payout to Vendor account (if you are using Easy Split)

## Settlement Webhook

This webhook is triggered whenever there is a payout to your merchant account. The settlement webhooks will notify you about instant settlements in addition to the standard settlement webhooks.  We send webhooks for four different events for a `settlement`.

| Webhook event | Description |
| - | - |
| SETTLEMENT\_INITIATED | This webhook will be triggered when a settlement is initiated. |
| SETTLEMENT\_SUCCESS | This webhook will be triggered when a settlement is successful. |
| SETTLEMENT\_FAILED | This webhook will be triggered when a settlement has failed. |
| SETTLEMENT\_REVERSED | This webhook will be triggered when a settlement has been reversed. |

The following webhook is sent for other types of settlements as well: instant settlement or an on-demand settlement.

```javascript Settlement webhook  theme={"dark"}
{
    "data": {
        "settlement": {
            "adjustment": 0,
            "amount_settled": 97.94,
            "payment_amount": 100,
            "payment_from": "2022-02-14 12:00:00",
            "payment_till": "2022-02-14 12:15:00",
            "reason": null,
            "service_charge": 1.75,
            "service_tax": 0.31,
            "settled_on": "2022-02-14T12:35:19+05:30",
            "settlement_type": "STANDARD",   //settlement type //
            "settlement_amount": 97.94,
            "settlement_id": 738,
            "settlement_initiated_on": "2022-02-14T12:35:17+05:30",
            "status": "SUCCESS",
            "utr": 1644822317781212,
            "settlement_charge": 0,    // applicable for instant settlement //
            "settlement_tax": 0,       // applicable for instant settlement //
            "remarks": null.           // applicable for instant settlement //
        }
    },
    "event_time": "2022-02-08T13:37:34+05:30",
    "type": "SETTLEMENT_SUCCESS"
}
```

<Accordion title="Understand these fields in detail">
  ## Payload field description

  | Field | Description | Example |
  | - | - | - |
  | adjustment | Sum of refunds, disputes, and chargebacks included in this settlement. | 0 |
  | amount\_settled | Total amount settled in this schedule. | 15 |
  | payment\_amount | Total transaction amount considered for settlement. | 15 |
  | payment\_from | Start date and time from which payments are considered for settlement. | 2022-02-14 12:00:00 |
  | payment\_till | End date and time till which payments are considered for settlement. | 2022-02-23 12:00:00 |
  | reason | Reason for failed or reversed settlements. | Transfer mode not valid for beneficiary. |
  | service\_charge | Service charges applicable to the payments included in this settlement. | 2 |
  | service\_tax | Service tax applicable to the payments included in this settlement. | 0 |
  | settled\_on | Date and time when the settlement was processed. | 2022-03-17T14:21:18+05:30 |
  | settlement\_type | Type of settlement (e.g., INSTANT). | INSTANT |
  | settlement\_amount | Net settlement amount for the payments included in this settlement. | 13 |
  | settlement\_id | Unique settlement ID generated by Cashfree. | 1155353 |
  | settlement\_initiated\_on | Date on which settlement was initiated. | 2022-03-17T14:29:21+05:30 |
  | status | Status of the settlement (INITIATED, SUCCESS, FAILED, or REVERSED). | SUCCESS |
  | utr | Unique transaction reference number provided by the bank for the settlement. | N076221079016329 |
  | settlement\_charge | Additional charge applicable for instant settlement. | 10.10 |
  | settlement\_tax | Settlement tax applicable for instant settlement. | 01.97 |
  | remarks | Any remarks specified by the merchant. | Settlement Initiated |
  | event\_time | Time when the settlement webhook was triggered. | 2022-03-17T14:29:23+05:30 |
  | type | Type of webhook event (SETTLEMENT\_INITIATED, SETTLEMENT\_SUCCESS, SETTLEMENT\_FAILED, or SETTLEMENT\_REVERSED). | SETTLEMENT\_SUCCESS |
</Accordion>

## Vendor Settlement Webhook

<Warning>This section only applies to merchants using our Easy Split product </Warning>

These settlement webhooks automate notifications when vendor settlements are initiated, successfully processed, failed, or reversed.

| Webhook event | Description |
| :- | :- |
| VENDOR\_SETTLEMENT\_INITIATED | This webhook will be triggered when a vendor settlement is initiated. |
| VENDOR\_SETTLEMENT\_SUCCESS | This webhook will be triggered when a vendor settlement is successful. |
| VENDOR\_SETTLEMENT\_FAILED | This webhook will be triggered when a vendor settlement has failed. |
| VENDOR\_SETTLEMENT\_REVERSED | This webhook will be triggered when a vendor settlement has been reversed. |

```javascript Vendor Settlement Webhook theme={"dark"}
{
    "data": {
        "settlement": {
            "adjustment": 0,
            "amount_settled": 10,
            "payment_amount": null,
            "payment_from": "2022-05-26",
            "payment_till": "2022-05-26",
            "reason": null,
            "service_charge": 0.05,
            "service_tax": 0.01,
            "settled_on": "2022-05-26T15: 06: 14+05: 30",
            "settled_orders_count": null,
            "settlement_amount": 10,
            "settlement_id": 6151,
            "settlement_initiated_on": "2022-05-26T15: 06: 09+05: 30",
            "settlement_type": null,
            "status": "CREATED",
            "utr": null,
            "vendor_id": IS_1hour_Upi,
            "vendor_transaction_amount": 10
        },
        "event_time": "2022-05-26T15:06:15+05:30",
        "type": "VENDOR_SETTLEMENT_INITIATED"
    }
}
```


# Get All Settlements
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/settlements/settlements

openapi/payments/v2023-08-01.yaml post /settlements
Use this API to get all settlement details by specifying the settlement ID, settlement UTR or date range.



# Get Settlements by Order ID
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/settlements/settlements-for-order

openapi/payments/v2023-08-01.yaml get /orders/{order_id}/settlements
Use this API to view all the settlements of a particular order.



# Fetch Simulation
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/simulation/fetch-simulation

openapi/payments/v2023-08-01.yaml get /simulate/{simulation_id}
Use this API to fetch simulated payment details.



# Simulate Payment
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/simulation/simulate-payment

openapi/payments/v2023-08-01.yaml post /simulate
Use this API to simulate payment. To use this API you should first create an order using the Create Order API. Also, you need to create a payment with the same order.



# Create Terminal
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/softpos/create-terminal

openapi/payments/v2023-08-01.yaml post /terminal
Use this API to create new terminals to use softPOS.



# Create Terminal Transaction
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/softpos/create-terminal-transaction

openapi/payments/v2023-08-01.yaml post /terminal/transactions
Use this API to create a new terminal transaction. To use this API you should first create an order using the Create Order API. Also, you need to enter the terminal details while creating the order and pass the same terminal information while creating a transaction using the below mentioned API.



# Demap Soundbox Vpa
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/softpos/demap-soundbox-vpa

openapi/payments/v2023-08-01.yaml post /terminal/demap/soundbox
Use this API to demap a device from soundbox.



# Fetch Terminal QR Codes
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/softpos/fetch-terminal-qr-codes

openapi/payments/v2023-08-01.yaml get /terminal/qrcodes
You can fetch all the StaticQRs corresponding to given terminal id or phone number. Provide either the terminal_phone_no or terminal_id in the request.



# Fetch Terminal Soundbox vpa
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/softpos/fetch-terminal-soundbox-vpa

openapi/payments/v2023-08-01.yaml get /terminal/soundbox/qrcodes
You can fetch all the active and mapped SoundboxVpa corresponding to given terminal id or deviceSerialNo. Provide either the device_serial_no or cf_terminal_id in the request.



# Get Terminal Status using Phone Number
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/softpos/get-terminal-status-using-phone-number

openapi/payments/v2023-08-01.yaml get /terminal/{terminal_phone_no}
Use this API to view all details of a terminal.



# Get Terminal Transaction
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/softpos/get-terminal-transaction

openapi/payments/v2023-08-01.yaml get /terminal/{cf_terminal_id}/payments
Use this API to get  terminal transaction.



# Onboard Soundbox Vpa
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/softpos/onboard-soundbox-vpa

openapi/payments/v2023-08-01.yaml post /terminal/soundbox
Use this API to onboard a terminal Vpa to soundbox.



# Offline Payments Webhooks
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/softpos/softpos-webhooks

Subscribe to Cashfree softPOS webhooks to track terminal onboarding, status, and transaction events for in-person card and UPI payments in real time.

Webhooks are server callbacks to your server from Cashfree. Webhooks are event-based and are sent when specific events related to the transaction happen.

Cashfree sends the following webhooks for softPOS:

* [Payment Success](/docs/api-reference/payments/previous/v2023-08-01/softpos/softpos-webhooks#payment-success-webhook-version-2022-09-01)
* [Payment Failed](/docs/api-reference/payments/previous/v2023-08-01/softpos/softpos-webhooks#payment-failed-webhook-version-2022-09-01)
* [User Dropped](/docs/api-reference/payments/previous/v2023-08-01/softpos/softpos-webhooks#user-dropped-webhook-version-2022-09-01)
* [Refunds](/docs/api-reference/payments/previous/v2023-08-01/softpos/softpos-webhooks#refund-webhook-version-2022-09-01)
* [Auto Refund](/docs/api-reference/payments/previous/v2023-08-01/softpos/softpos-webhooks#auto-refund-webhook-version-2022-09-01)
* [Disputes](/docs/api-reference/payments/previous/v2023-08-01/softpos/softpos-webhooks#dispute-created)
* [Settlements](/docs/payments/split/webhooks)
* [Terminal](/docs/api-reference/payments/previous/v2023-08-01/softpos/softpos-webhooks#terminal-status-update-webhook-version-2022-09-01)

***

## Payment Success Webhook Version: (2022-09-01)

The new payment success webhook notifies you about the payment, and gives you comprehensive information about successful payments. A notification is sent to your backend from Cashfree when payments are successful. These notifications are useful in cases when the internet connection is unstable or slow while the payment is being processed. This will allow you to reconcile all the successful orders at your end. Notifications will be sent to **notifyUrl** which is a part of the request parameter specified while creating an order request as well as endpoints configured on the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).

### Sample payload

```java theme={"dark"}
 {  
  "data": {
        "order": {
            "order_id": "order_OFR_2",
            "order_amount": 2,
            "order_currency": "INR",
            "order_tags": null
        },
        "payment": {
            "cf_payment_id": 1453002795,
            "payment_status": "SUCCESS",
            "payment_amount": 1,
            "payment_currency": "INR",
            "payment_message": "00::Transaction success",
            "payment_time": "2022-12-15T12:20:29+05:30",
            "bank_reference": "234928698581",
            "auth_id": null,
            "payment_method": {
                "upi": {
                    "channel": null,
                    "upi_id": "9611199227@paytm"
                }
            },
            "payment_group": "upi"
        },
        "customer_details": {
            "customer_name": null,
            "customer_id": "7112AAA812234",
            "customer_email": "[miglaniyogesh7@gmail.com]()",
            "customer_phone": "9908734801"
        },
        "payment_gateway_details": {
            "gateway_name": "CASHFREE",
            "gateway_order_id": "1580762800",
            "gateway_payment_id": "1453002795",
            "gateway_status_code": null
        },
        "payment_offers": [  
            {  
                "offer_id": "0f05e1d0-fbf8-4c9c-a1f0-814c7b2abdba",  
                "offer_type": "DISCOUNT",  
                "offer_meta": {  
                    "offer_title": "50% off on UPI",  
                    "offer_description": "50% off for testing",  
                    "offer_code": "UPI50",  
                    "offer_start_time": "2022-11-09T06:23:25.972Z",  
                    "offer_end_time": "2023-02-27T18:30:00Z"  
                },  
                "offer_redemption": {  
                    "redemption_status": "SUCCESS",  
                    "discount_amount": 1,  
                    "cashback_amount": 0  
                }  
            }  
        ],
        "terminal_details": {
        "cf_terminal_id": 989876,
        "terminal_phone": "9773769999"
    }
    },
    "event_time": "2023-01-03T11:16:10+05:30",
    "type": "PAYMENT_SUCCESS_WEBHOOK"
}

```

***

## Payment Failed Webhook Version: (2022-09-01)

The payment failed webhook notifies you when transactions fail and we receive a failed response from the bank.

```java theme={"dark"}
{  
    "data": {
    "order": {
        "order_id": "CFPay_g47u3888d0k0_tblfm766qc",
        "order_amount": 1.8,
        "order_currency": "INR",
        "order_tags": {
            "cf_link_id": "13746255"
        }
    },
    "payment": {
        "cf_payment_id": 1504280029,
        "payment_status": "FAILED",
        "payment_amount": 1.8,
        "payment_currency": "INR",
        "payment_message": "AMOUNT SHOULD BE WITHIN RANGE BETWEEN 20.00 TO 500000.00.",
        "payment_time": "2023-01-06T20:00:11+05:30",
        "bank_reference": "NA",
        "auth_id": "null",
        "payment_method": {
            "netbanking": {
                "channel": null,
                "netbanking_bank_code": "3054",
                "netbanking_bank_name": "UCO Bank"
            }
        },
        "payment_group": "net_banking"
    },
    "customer_details": {
        "customer_name": null,
        "customer_id": null,
        "customer_email": null,
        "customer_phone": "9611199227"
    },
    "error_details": {
        "error_code": "GATEWAY_ERROR",
        "error_description": "AMOUNT SHOULD BE WITHIN RANGE BETWEEN 20.00 TO 500000.00. for this bank",
        "error_reason": "invalid_amount",
        "error_source": "cashfree"
    },
    "payment_gateway_details": {
        "gateway_name": "CASHFREE",
        "gateway_order_id": "1634766330",
        "gateway_payment_id": "1504280029",
        "gateway_status_code": null
    },
    "payment_offers": null,
    "terminal_details": {
        "cf_terminal_id": 989876,
        "terminal_phone": "9773769999"
    }
},
"event_time": "2023-01-06T20:00:12+05:30",
"type": "PAYMENT_FAILED_WEBHOOK"
}
```

***

## User Dropped Webhook Version: (2022-09-01)

The User Dropped Webhook notifies you when customers drop out of the payment flow without completing the transaction. It will help you understand if customers attempted to pay or not.

Some common scenarios where the transaction will be marked as USER\_DROPPED are:

* Android UPI Intent Payments - when a user clicks on the back button in the UPI app without making any payment attempt.
* Card Payments - when a user drops out of the payment flow by closing the OTP verification page.
* UPI Collect Transactions - when a user does not enter the UPI PIN and closes the transaction screen

```java theme={"dark"}
{  
    "data": {
        "order": {
            "order_id": "testspos83",
            "order_amount": 1.00,
            "order_currency": "INR",
            "order_tags": null
        },
        "payment": {
            "cf_payment_id": 2150264295,
            "payment_status": "USER_DROPPED",
            "payment_amount": 1.00,
            "payment_currency": "INR",
            "payment_message": null,
            "payment_time": "2023-11-03T12:37:32+05:30",
            "bank_reference": null,
            "auth_id": null,
            "payment_method": {
                "upi": {
                    "channel": null,
                    "upi_id": "testsuccess@gocash"
                }
            },
            "payment_group": "upi"
        },
        "customer_details": {
            "customer_name": "johndoe",
            "customer_id": "9112",
            "customer_email": "[johndoe@cashfree.com]()",
            "customer_phone": "9876543210"
        },
        "payment_gateway_details": {
            "gateway_name": null,
            "gateway_order_id": null,
            "gateway_payment_id": null,
            "gateway_status_code": null,
            "gateway_settlement": null
        },
        "payment_offers": null,
        "terminal_details": {
            "cf_terminal_id": 20532321,
            "terminal_phone": "9876543210"
        }
    },
    "event_time": "2023-11-03T12:37:44+05:30",
    "type": "PAYMENT_USER_DROPPED_WEBHOOK"
}
```

***

## Refund Webhook Version: (2022-09-01)

Refund webhooks can be configured to receive automated notifications for refunds when either they are successfully processed or are cancelled. Merchants can build their own downstream systems like auto-updating their refund status, and sending a communication to customers by consuming refund webhooks.

The webhook notification will be sent on all the URLs added and enabled under the refund webhook. Merchants can add new URLs and enable or disable existing URLs for refund webhook at any point in time and it will be reflected instantaneously.

### Sample payload

```java theme={"dark"}
{
 "data": {
    "refund": {
        "cf_refund_id": 11325632,
        "cf_payment_id": 789727431,
        "refund_id": "refund_sampleorder0413",
        "order_id": "sampleorder0413",
        "refund_amount": 2.00,
        "refund_currency": "INR",
        "entity": "Refund",
        "refund_type": "MERCHANT_INITIATED",
        "refund_arn": "205907014017",
        "refund_status": "SUCCESS",
        "status_description": "Refund processed successfully",
        "created_at": "2022-02-28T12:54:25+05:30",
        "processed_at": "2022-02-28T13:04:27+05:30",
        "refund_charge": 0,
        "refund_note": "Test",
        "refund_splits": [  
            {  
                "merchantVendorId": "sampleID12345",  
                "amount": 1,  
                "percentage": null  
            },  
            {  
                "merchantVendorId": "otherVendor",  
                "amount": 1,  
                "percentage": null  
            }  
        ],
        "metadata": null,
        "refund_mode": "STANDARD",
        "terminal_details": {
            "cf_terminal_id": 911876,
            "terminal_phone": "9876543210"
        }
    }
},
"event_time": "2022-02-28T13:04:28+05:30",
"type": "REFUND_STATUS_WEBHOOK"
}
```

### Payload field description

| Field | Description | Example |
| - | - | - |
| cf\_refund\_id | Cashfree ID for a refund. | 11325632 |
| cf\_payment\_id | Cashfree ID of the payment for which refund is initiated. | 789727431 |
| cf\_terminal\_id | Cashfree Terminal ID of the payment for which refund is initiated. | 21345 |
| terminal\_phone | The phone number of the corresponding terminal. | 9876543212 |
| refund\_id | Merchant’s refund ID of the refund | refund\_sampleorder0413 |
| order\_id | Merchant’s order ID of the order for which refund is initiated. | sampleorder0413 |
| refund\_amount | Amount that was refunded | 2.00 |
| refund\_currency | Currency of the refund amount. | INR |
| entity | Type of object (refund always) | Refund |
| refund\_type | Type of refund (for webhook it will always be MERCHANT\_INITIATED) | MERCHANT\_INITIATED |
| refund\_arn | The bank reference number for refund | 205907014017 |
| refund\_status | Status of the refund (either SUCCESS or CANCELLED in refund webhook) | SUCCESS |
| status\_description | Description of refund status | Refund processed successfully |
| created\_at | Time of refund creation | 2022-02-28T12:54:25+05:30 |
| processed\_at | Time when refund was processed successfully | 2022-02-28T13:04:27+05:30 |
| refund\_charge | Charges in INR for processing refund | 0 |
| refund\_note | Note added by merchant for the refund | Cancelled Order |
| refund\_splits | Refund split details | \[] |
| metadata | Additional refund metadata | null |
| refund\_mode | Method or speed of processing refund (INSTANT or STANDARD) | STANDARD |
| event\_time | Time at which refund webhook was initiated. | 2022-02-28T13:04:28+05:30 |
| type | Type of webhook. REFUND\_STATUS\_WEBHOOK always | REFUND\_STATUS\_WEBHOOK |

***

## Auto Refund Webhook Version: (2022-09-01)

Auto-refund webhooks can be configured to receive automated notifications when auto-refunds are initiated, processed and delayed. Auto-refunds are refunds triggered automatically for unsuccessful payments, disputes, duplicate payments; or instances where payments are received directly to your VPA, regardless of whether an order has been generated.

Webhook notifications are sent to every URL added and enabled under **Auto-refund Webhooks**. Merchants can add new URLs and enable or disable existing ones for auto-refund webhooks at any point in time. The changes are reflected instantaneously.

### Sample payload

###

```java theme={"dark"}
{
    "data": {
        "auto_refund": {
            "event": "AUTO-REFUND",
            "cf_refund_id": 1243460973,
            "cf_payment_id": "2148333968",
            "bank_reference": "234928698581",
            "order_id": "order_1944392Tpba8y2fHcHVx0SwREojp51Jgr",
            "refund_amount": 39,
            "refund_currency": "INR",
            "refund_type": "PAYMENT_AUTO_REFUND",
            "refund_arn": "205907014017",
            "refund_status": "SUCCESS",
            "status_description": "Auto-Refund processed successfully",
            "refund_reason": "Multiple payments were performed against same order.",
            "created_at": "2023-08-11T14:08:28+05:30",
            "processed_at": null,
            "refund_charge": 0,
            "refund_splits": null,
            "metadata": null
        },
        "terminal_details": {
            "cf_terminal_id": 989876,
            "terminal_phone": "9773769999"
        }
    },
    "event_time": "2023-08-11T14:10:21+05:30",
    "type": "AUTO_REFUND_STATUS_WEBHOOK"
}
```

Find the description for each field of the payload below:

| Field | Description | Example |
| - | - | - |
| cf\_refund\_id | It represents the ID created by Cashfree to identify the refund. | 1243460973 |
| cf\_payment\_id | It represents the ID created by Cashfree to identify the payment for the initiated refund. | 2148333968 |
| cf\_terminal\_id | Cashfree Terminal ID of the payment for which refund is initiated. | 21345 |
| terminal\_phone | The phone number of the corresponding terminal. | 9876543212 |
| order\_id | It represents the ID created by you to identify the order for which the refund is initiated. | sampleorder0413 |
| bank\_reference | It represents the bank reference number for the transaction. | 234928698581 |
| refund\_currency | It represents the currency of the refund amount. | INR |
| refund\_amount | It represents the refunded amount. | 2 |
| refund\_type | It represents the refund type. The value will always be PAYMENT\_AUTO\_REFUND. | PAYMENT\_AUTO\_REFUND |
| refund\_arn | It represents the bank reference number for the refund. | 205907014017 |
| refund\_status | It represents the status of the refund (either SUCCESS or INITIATED) | SUCCESS |
| status\_description | It represents the description of the refund status  (Two possible values:  Auto-Refund initiated successfully or  Auto-Refund processed successfully). | Auto-Refund initiated successfully |
| created\_at | It represents the time of auto-refund creation. | 2022-02-28T12:54:25+05:30 |
| processed\_at | It represents when the auto-refund was processed successfully. | 2022-02-28T13:04:27+05:30 |
| refund\_reason | It represents the reason of initiation of Auto-refund (Possible values:  Credit was received for an incomplete payment.  Refunded to customer for Dispute.  Payment made directly to your VPA without order creation.  Multiple payments were performed against same order.  Payment details (amount, bank, etc.) do not match with created order or the payment was made after TTL.) | Multiple payments were performed against same order |
| refund\_charge | It represents the charges for processing refund in INR. | 0 |
| refund\_splits | It represents the refund split details. | \[] |
| metadata | It represents the additional metadata. | null |
| event\_time | It represents when the refund webhook was initiated. | 2022-02-28T13:04:28+05:30 |
| type | It represents the webhook type. The value will always be AUTO\_REFUND\_STATUS\_WEBHOOK. | AUTO\_REFUND\_STATUS\_WEBHOOK |

***

## Terminal Status Update Webhook Version: (2022-09-01)

The new terminal status update webhook notifies you about the terminal status update, and gives you comprehensive information about terminal updates.

```java theme={"dark"}
{
"data":{
"added_on":string"2024-03-07 15:11:02"
"cf_terminal_id":int1234
"last_updated_on":string"2024-04-26 12:16:08"
"terminal_id":int1233
"terminal_name":string"ABC"
"terminal_phone":string"9696969696"
"terminal_status":string"PROVISIONALLY_ACTIVE"
"terminal_type":string"STOREFRONT"
"review_remarks":string"approved"
}
"event_time":string"2024-04-26T12:16:08+05:30"
"type":string"TERMINAL_STATUS_UPDATE"
}
```

***

## Dispute Webhooks Version: (2022-09-01)

Dispute webhooks can be configured to receive automated notifications when disputes are created, updated and closed.

The webhook notification will be sent on all the URLs added and enabled under the dispute webhook. Merchants can add new URLs and enable or disable existing URLs for refund webhook at any point in time and it will be reflected instantaneously.

| Webhook | Description |
| :- | :- |
| DISPUTE\_CREATED | Dispute\_created webhook will be triggered when a new dispute is created. |
| DISPUTE\_UPDATED | Dispute\_updated webhook will be triggered when a dispute is updated, for example when a comment is added by the Cashfree team, when the dispute moves into further stages like Pre-arbitration, Arbitration, or when the status of the dispute changes. |
| DISPUTE\_CLOSED | This webhook will be triggered when a dispute is closed. |

### Dispute created

**Sample Payload**

```java theme={"dark"}
{
    "data": {
        "dispute": {
            "dispute_id": "433475258",
            "dispute_type": "DISPUTE",
            "reason_code": "1402",
            "reason_description": "Duplicate Processing",
            "dispute_amount": 3,
            "created_at": "2023-06-15T21:49:48+05:30",
            "updated_at": "2023-06-15T21:49:48+05:30",
            "respond_by": "2023-06-18T23:59:59+05:30",
            "dispute_status": "DISPUTE_CREATED",
            "cf_dispute_remarks": "Dispute is created, please take action",
            "dispute_action_on": "MERCHANT"
        },
        "order_details": {
            "order_id": "order_1944392DR1kMTFYdIf8bI2awAcC3i9FTa",
            "order_amount": 3,
            "order_currency": "INR",
            "cf_payment_id": 885473311,
            "payment_amount": 3,
            "payment_currency": "INR"
        },
        "customer_details": {
            "customer_name": "Dileep Kumar s",
            "customer_phone": "8000000000",
            "customer_email": "dileep@gmail.com"
        },
        "terminal_details": {
            "cf_terminal_id": 989876,
            "terminal_phone": "9876543212"
        }
    },
    "event_time": "2023-06-15T21: 50: 04+05: 30",
    "type": "DISPUTE_CREATED"
}
```

***

### Dispute updated

**Sample Payload**

```java theme={"dark"}
{
    "data": {
        "dispute": {
            "dispute_id": "433475257",
            "dispute_type": "PRE_ARBITRATION",
            "reason_code": "13.1",
            "reason_description": "Merchandise / Services Not Received",
            "dispute_amount": 40000,
            "created_at": "2023-06-15T21:16:03+05:30",
            "updated_at": "2023-06-15T21:19:15+05:30",
            "respond_by": "2023-06-19T23:59:59+05:30",
            "dispute_status": "PRE_ARBITRATION_CREATED",
            "cf_dispute_remarks": "Pre Arbitration request has been raised for this case.\\nTarget Date :: 2023-06-18T00:00 -> 2023-06-19T23:59:59.",
            "dispute_update": "TYPE_UPDATE",
            "dispute_action_on": "MERCHANT"
        },
        "order_details": {
            "order_id": "order_1944392D4jHtCeVPPdTXkaUwg5cfnujQe",
            "order_amount": 40000,
            "order_currency": "INR",
            "cf_payment_id": 885457437,
            "payment_amount": 40000,
            "payment_currency": "INR"
        },
        "customer_details": {
            "customer_name": "Dileep Kumar s",
            "customer_phone": "8000000000",
            "customer_email": "dileep@gmail.com"
        },
        "terminal_details": {
            "cf_terminal_id": 989876,
            "terminal_phone": "9876543212"
        }
    },
    "event_time": "2023-06-15T21:20:24+05:30",
    "type": "DISPUTE_UPDATED"
}
```

***

### Dispute closed

**Sample Payload**

```java theme={"dark"}
{
    "data": {
        "dispute": {
            "dispute_id": "433475257",
            "dispute_type": "CHARGEBACK",
            "reason_code": "4855",
            "reason_description": "Goods or Services Not Provided",
            "dispute_amount": 4500,
            "created_at": "2023-06-15T21:16:03+05:30",
            "updated_at": "2023-06-15T21:16:51+05:30",
            "respond_by": "2023-06-18T00:00:00+05:30",
            "resolved_at": "2023-06-15T21:16:51.682836678+05:30",
            "dispute_status": "CHARGEBACK_MERCHANT_WON",
            "cf_dispute_remarks": "Chargeback won by merchant"
        },
        "order_details": {
            "order_id": "order_1944392D4jHtCeVPPdTXkaUwg5cfnujQe",
            "order_amount": 4500,
            "order_currency": "INR",
            "cf_payment_id": 885457437,
            "payment_amount": 4500,
            "payment_currency": "INR"
        },
        "customer_details": {
            "customer_name": "Dileep Kumar s",
            "customer_phone": "8000000000",
            "customer_email": "dileep@gmail.com"
        },
        "terminal_details": {
            "cf_terminal_id": 989876,
            "terminal_phone": "9876543212"
        }
    },
    "event_time": "2023-06-15T21:17:14+05:30",
    "type": "DISPUTE_CLOSED"
}
```

### Payload field description

| Field | Description | Example | Type |
| - | - | - | - |
| dispute\_id | Cashfree’s unique ID to identify a dispute. | 433475257 | Long |
| dispute\_type | Type of dispute created. Possible values:  \n- DISPUTE  \n- RETRIEVAL  \n- CHARGEBACK  \n- PRE\_ARBITRATION  \n- ARBITRATION | Chargeback | String |
| cf\_terminal\_id | Cashfree Terminal ID of the payment for which refund is initiated. | 989876 | Long |
| terminal\_phone | The phone number of the corresponding terminal. | 9876543212 | String |
| reason\_code | Condition for which the customer is filing the case. See [dispute reason codes](/docs/payments/manage/disputes/reason-codes) to know more. | 13.6 | String |
| reason\_description | Description of the reason code. Codes for Chargeback cases are specified by Card networks/NPCI. | Credit not processed | String |
| dispute\_amount | The amount for which the dispute has been created. | 4500 | BigDecimal |
| created\_at | Time on which the dispute was registered on Cashfree’s system. | 2023-06-15T21:16:03+05:30 | LocalDateTime |
| updated\_at | Time on which the dispute was updated. | 2023-06-15T21:16:51+05:30 | LocalDateTime |
| respond\_by | Time by which the merchant is expected to respond to the dispute. | 2023-06-18T00:00:00+05:30 | LocalDateTime |
| dispute\_status | Status of Dispute. All possible values are listed in the table below. | CHARGEBACK\_CREATED | String |
| cf\_dispute\_remarks | Any remarks specified by Cashfree on the dispute. | Please submit documents. | String |
| dispute\_update | Specifies what has been updated on the dispute. Possible Values:  \n- STATUS\_UPDATE  \n- TYPE\_UPDATE  \n- COMMENT\_UPDATE | TYPE\_UPDATE | String |
| dispute\_action\_on | Specifies whether the action is on Cashfree or Merchant at a time. Possible Values:  \n- MERCHANT  \n- CASHFREE | MERCHANT | String |
| resolved\_at | Time on which the dispute was resolved/closed. | 2023-06-15T21:16:51.682836678+05:30 | LocalDateTime |
| event\_time | Time at which dispute webhook was initiated. | 2023-06-15T21:16:51+05:30 | LocalDateTime |
| type | Type of webhook. Possible Values:   DISPUTE\_CREATED, DISPUTE\_UPDATED, and DISPUTE\_CLOSED | DISPUTE\_CREATED | String |


# Update Soundbox Vpa
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/softpos/update-soundbox-vpa

openapi/payments/v2023-08-01.yaml patch /terminal/{cf_terminal_id}/soundbox
Use this API to update a terminal Vpa to soundbox.



# Update Terminal
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/softpos/update-terminal

openapi/payments/v2023-08-01.yaml patch /terminal/{cf_terminal_id}
Use this API to update the terminal details. Email, Phone Number, and Terminal Meta are updatable for "Storefront". Only account status change is possible in case of "Agent".



# Update Terminal Status
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/softpos/update-terminal-status

openapi/payments/v2023-08-01.yaml patch /terminal/{cf_terminal_id}/status
Use this API to update the terminal status.



# Upload Terminal Docs
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/softpos/upload-terminal-docs

openapi/payments/v2023-08-01.yaml post /terminal/{cf_terminal_id}/docs
Use this API to upload the terminal documents.



# Get Vendor Balance Transfer Charges
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/split/billing/balance-transfer-charges

openapi/payments/v2023-08-01.yaml get /easy-split/amount/{amount}/charges
This API returns the applicable service charge and service tax for a vendor balance transfer, based on the provided amount and rate type.



# Create Adjustment
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/split/configuration/create-adjustment

openapi/payments/v2023-08-01.yaml post /easy-split/vendors/{vendor_id}/adjustment
The Create Adjustment API will create a adjustment request either from vendor to the merchant or from merchant to the vendor.



# Split After Payment
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/split/configuration/split-after-payment

openapi/payments/v2023-08-01.yaml post /easy-split/orders/{order_id}/split
Split After Payment API splits the payments to vendors after successful payment from the customers.



# Create Static Split Configuration
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/split/configuration/static-split

openapi/payments/v2023-08-01.yaml post /easy-split/static-split
This API will create a static split scheme wherein you can define the split type and the vendor-wise split percentage.



# Easy Split Overview
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/split/easy-split-overview

Use Cashfree Easy Split to share each customer payment between vendors at checkout, automate vendor settlements, and reconcile splits from one place.

Easy Split automates the splitting of payments with vendors and partners on time. Collect payments from customers, and set up a flexible schedule options to disburse payments to your vendors. Get detailed reports on the transactions, settlements, refunds, vendor payments and adjustments.

**How does Easy Split Work?**

<img alt="" />

**You can perform the following tasks using Easy Split:**

* Add and manage all your vendors efficiently
* Split payments and settle them into multiple vendor accounts using the available schedule options cycles
* Check on-demand vendor balance and settle the money into the vendor accounts instantly
* Vendor reconciliation

The table below provides the list of Easy Split APIs along with their description:

**Vendor APIs**

| API name | Description |
| :- | :- |
| [Create Vendor](/docs/api-reference/payments/previous/v2023-08-01/split/vendors/create) | Create Vendor API creates a new vendor in your Easy Split account. |
| [Update Vendor Details](/docs/api-reference/payments/previous/v2023-08-01/split/vendors/update) | Update Vendor Details API updates the existing vendor details. |
| [Get Specific Vendor Details](/docs/api-reference/payments/previous/v2023-08-01/split/vendors/download-documents) | Get Specific Vendor Details API gets the details of a specific vendor. |
| [Get All Vendor Details](/docs/api-reference/payments/previous/v2023-08-01/split/vendors/get) | Get All Vendor Details API gets the details of all the vendors associated with that Easy Split account. |
| [Transfer Vendor Balance](/docs/api-reference/payments/previous/v2023-08-01/split/configuration/create-adjustment) | Transfer Vendor Balance API adjusts the vendor balances. |
| [Create Refund](/docs/api-reference/payments/previous/v2023-08-01/refunds/create) | Create Refund API creates a new refund. |

**Split Order APIs**

| API name | Description |
| :- | :- |
| [Split at Order Level](/docs/api-reference/payments/previous/v2023-08-01/split/configuration/create-adjustment) | Use this API to create a split at order level. |
| [Split After Payment](/docs/api-reference/payments/previous/v2023-08-01/split/configuration/split-after-payment) | Split After Payment API created a split after the payment is completed. |
| [Get Split and Settlement Details by OrderId](/docs/api-reference/payments/previous/v2023-08-01/split/settlements/get-split-and-settlement-details) | Get Split and Settlement Details by OrderId API gets details of the split, settled and unsettled transactions of each vendor using the OrderID. |

**Settlement APIs**

| API name | Description |
| :- | :- |
| [Get Settlement Cycle Details]() | Get Settlement Cycle Details API gets the schedule option details. |
| [Get All Vendor Settlement Details]() | Get All Vendor Settlement Details API gets all the vendor settlement details. |
| [Get Vendor Settlement Details by Settlement ID]() | Get Vendor Settlement Details by Settlement ID API gets the Vendor Settlement of each vendor by SettlementID. |

**On Demand Settlement APIs**

| API name | Description |
| :- | :- |
| [Get On Demand Vendor Balance]() | Get On Demand Vendor Balance API gets the on-demand vendor balance. |
| [Settle On Demand Vendor Balance]() | Settle On Demand Vendor Balance API settles the balance to a vendor on-demand immediately. |
| [Get On Demand Settlement Status]() | Get On Demand Settlement Status API gets the on-demand settlement status. |

**Deferred Settlement APIs**

| API name | Description |
| :- | :- |
| [Set Vendor Settlement Eligibility Date for Orders]() | Set Vendor Settlement Eligibility Date for Orders API assigns a settlement eligibility date for an order and vendor combination. |

**Reconciliation APIs**

| API name | Description |
| :- | :- |
| [View Split Order Details Using Settlement ID]() | View Split Order Details Using Settlement ID API gets the details of the split order processed in a settlement using Settlement ID. |
| [Vendor Recon for a Time Period]() | Vendor Recon for a Time Period API gets the on demand settlement status by providing the on-demand request ID. |
| [Vendor Recon Using Vendor ID & Time Interval]() | Vendor Recon Using Vendor ID & Time Interval API gets the details of all events for a specific vendor within an interval. |


# Easy Split - Postman Collection
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/split/easy-split-postman-collection

Download the ready-made Postman collection for the Cashfree Easy Split APIs to test vendor, split, and settlement endpoints with sample requests.

Get started quickly with Cashfree's Easy Split APIs by downloading the collection and importing it in Postman.

<a href="https://gocashassets.s3.ap-south-1.amazonaws.com/postmancollection/Easy_Split_Postman_Collection.zip">Download Cashfree Easy Split Postman Collection</a>

Watch the video below to learn how to setup API

<iframe title="YouTube video player" />


# End Points
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/split/end-points

Review the production and sandbox base URLs and authentication headers you need to call the Cashfree Easy Split APIs for vendor and split operations.

Cashfree uses API keys to allow access to the API. Once you have signed up at our merchant site, you can see your AppId and SecretKey.

Cashfree expects the API key to be included in all API requests to the server. Use the endpoint /api/v1/credentials/verify to verify your credentials.

| Environment | Base URL |
| :- | :- |
| Production | [https://api.cashfree.com/](https://api.cashfree.com/) |
| Test | [https://test.cashfree.com/](https://test.cashfree.com/) |

**Auto Collect End Points**

For Auto Collect pass the Authorization token. Use the [Authorize API](/docs/api-reference/payouts/v1/authorize) to generate the token for Auto Collect APIs.

| Environment | Base URL |
| :- | :- |
| Production | [https://api.cashfree.com/](https://api.cashfree.com/) |
| Test | [https://sandbox.cashfree.com/](https://sandbox.cashfree.com/) |


# Vendor Reconciliation API
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/split/reconciliation/vendor-recon

openapi/payments/v2023-08-01.yaml post /recon/vendor
This API allows users to fetch vendor reconciliation details using different filters. Use the appropriate filters based on your requirements.
- **View Split Order Details Using Settlement ID**: Retrieve details of split orders within a settlement by Settlement ID.
- **Vendor Recon for a Time Period**: Fetch reconciliation details for all vendors within a specific time interval.
- **Vendor Recon Using Vendor ID & Time Interval**: Get reconciliation details for a specific vendor within a given time interval.




# Get Split and Settlement Details by OrderID v2.0
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/split/settlements/get-split-and-settlement-details

openapi/payments/v2023-08-01.yaml post /split/order/vendor/recon
Use this API to get all the split details, settled and unsettled transactions details of each vendor who were part of a particular order by providing order Id or start date and end date.



# Create On Demand Balance Transfer
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/split/settlements/on-demand-transfer

openapi/payments/v2023-08-01.yaml post /easy-split/vendors/{vendor_id}/transfer
The Create On Demand Transfer API will create a new on-demand request either from the merchant ledger or from the vendor ledger to the vendor bank account.



# Settlements Overview
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/split/settlements/overview

Explore the Cashfree Easy Split settlement APIs that fetch payout details for vendors, run on-demand transfers, and reconcile each settled order.

Once you have created an order and your customer pays for the order, the amount is received by Cashfree and processes the settlement into your bank account.

With the settlement APIs, you can fetch the settlement details by providing the Order ID.

Apart from this, you can settle the payments instantly using the On-demand settlements option. This option allows you to receive the unsettled amount to your bank account instantly 24x7 including holidays.

#### Settlement APIs

| API name | Description |
| :- | :- |
| [Create On Demand Balance Transfer](/docs/api-reference/payments/previous/v2023-08-01/split/settlements/on-demand-transfer) | Create a new on-demand request either from the merchant ledger or from the vendor ledger to the vendor bank account. |
| [Get Split and Settlement Details by OrderID](/docs/api-reference/payments/previous/v2023-08-01/split/settlements/split-details) | Get all the split details, settled and unsettled transactions details of each vendor. |
| [Get Split and Settlement Details by OrderID v2.0](/docs/api-reference/payments/previous/v2023-08-01/split/settlements/get-split-and-settlement-details) | Get all the split details, settled and unsettled transactions details of each vendor. |


# Get Split and Settlement Details by OrderID
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/split/settlements/split-details

openapi/payments/v2023-08-01.yaml get /easy-split/orders/{order_id}
Use this API to get all the split details, settled and unsettled transactions details of each vendor who were part of a particular order by providing order Id or start date and end date.



# Upload Vendor Docs
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/split/vendors/add-document

openapi/payments/v2023-08-01.yaml post /easy-split/vendor-docs/{vendor_id}
Use this API to upload KYC documents of a specific vendor.



# Create vendor
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/split/vendors/create

openapi/payments/v2023-08-01.yaml post /easy-split/vendors
Use this API to create a new vendor to your EasySplit account along with the KYC details. Provide KYC details such as account_type, business_type, gst, cin, pan, passport number and so on.



# Download Vendor Documents
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/split/vendors/download-documents

openapi/payments/v2023-08-01.yaml get /easy-split/vendor-docs/{vendor_id}/download/{doc_type}
Use this API to download the uploaded KYC documents of that particular vendor. Provide the document type. Click the link from the sample request to download the KYC document.



# Get Vendor All Details
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/split/vendors/get

openapi/payments/v2023-08-01.yaml get /easy-split/vendors/{vendor_id}
Use this API to get the details of a specific vendor associated with your Easy Split account.



# Get Vendor All Documents Status
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/split/vendors/get-document

openapi/payments/v2023-08-01.yaml get /easy-split/vendor-docs/{vendor_id}
Use this API to fetch the details of all the KYC details of a particular vendor.



# Get On Demand Balance
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/split/vendors/get-on-demand-balance

openapi/payments/v2023-08-01.yaml get /easy-split/vendors/{vendor_id}/balances
This API fetches the available amount with the merchant, vendor, and the unsettled amount for the merchant as well as the vendor.



# Overview
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/split/vendors/overview

Browse every Cashfree Easy Split vendor API, including endpoints to onboard a vendor, upload KYC documents, fetch balances, and update vendor details.

This section consists of the new set of Vendor KYC APIs. Use these APIs to perform actions such as creating a vendor, updating vendor details, get vendor details, upload vendor KYC documents, get all vendor documents and so on.

**Vendors 2.0 APIs**

| API name | Description |
| :- | :- |
| [Create Vendor v2.0](/docs/api-reference/payments/previous/v2023-08-01/split/vendors/create) | This API creates a new vendor in Cashfree system. |
| [Update Vendor Details v2.0](/docs/api-reference/payments/previous/v2023-08-01/split/vendors/update) | This API updates the existing vendor details such as name, email, phone number, UPI details, and any of the KYC details. |
| [Get Vendor All Details](/docs/api-reference/payments/previous/v2023-08-01/split/vendors/get) | This API fetches all the details of a specific vendor by sharing the vendor ID. |
| [Upload Vendor Docs](/docs/api-reference/payments/previous/v2023-08-01/split/vendors/add-document) | This API uploads the vendor KYC docs. |
| [Get Vendor All Document Status](/docs/api-reference/payments/previous/v2023-08-01/split/vendors/get-document) | This API fetches the submitted vendor KYC document status. |
| [Get Vendor Document Download URL](/docs/api-reference/payments/previous/v2023-08-01/split/vendors/download-documents) | This API downloads the uploaded KYC documents. Provide the vendor ID and the document type. |


# Update vendor Details
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/split/vendors/update

openapi/payments/v2023-08-01.yaml patch /easy-split/vendors/{vendor_id}
Use this API to edit the existing vendor details added to your EasySplit account. You can edit vendor details such as name, email, phone number, upi details, and any of the KYC details.



# Overview
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/split/webhooks/overview

Subscribe to Cashfree Easy Split webhooks so your platform is notified whenever a vendor is updated or a vendor settlement is paid out by Cashfree.

Webhooks are server callbacks to your server from Cashfree. Webhooks are event-based and are sent when specific events happen.

The table below lists the various webhook events:

| Webhook name | Description |
| :- | :- |
| [Vendor Settlement Webhook](/docs/api-reference/payments/previous/v2023-08-01/split/webhooks/vendor-settlement-webhooks) | Configure vendor settlement webhooks to receive automated notifications when vendor settlements are initiated, successfully processed, failed, or reversed. |
| [Vendor Status Change Webhook](/docs/api-reference/payments/previous/v2023-08-01/split/webhooks/vendor-status-change-webhooks) | Configure vendor status change webhooks to receive automated notifications when vendor status is changed. |


# Vendor Settlement Webhook
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/split/webhooks/vendor-settlement-webhooks

Receive a Cashfree webhook every time a vendor settlement payout is processed, so you can reconcile vendor balances and notify partners in real time.

Configure vendor settlement webhooks to receive automated notifications when vendor settlements are initiated, successfully processed, failed, or reversed.

The webhook notifications are sent on all the URLs added and enabled in the settlement webhook. You can add new URLs and enable or disable existing URLs for settlement webhook at any time and it will reflect instantaneously.

The table below lists the webhook events available for settlements.

| Webhook event | Description |
| :- | :- |
| VENDOR\_SETTLEMENT\_INITIATED | This webhook will be triggered when a vendor settlement is initiated. |
| VENDOR\_SETTLEMENT\_SUCCESS | This webhook will be triggered when a vendor settlement is successful. |
| VENDOR\_SETTLEMENT\_FAILED | This webhook will be triggered when a vendor settlement has failed. |
| VENDOR\_SETTLEMENT\_REVERSED | This webhook will be triggered when a vendor settlement has been reversed. |

***

### Vendor settlement initiated

SETTLEMENT\_INITIATED webhook is triggered when a settlement has been initiated by Cashfree.

```json theme={"dark"}
{
	"data": {
		"settlement": {
			"settlement_id": 49703,
			"status": "CREATED",
			"utr": "1686217237243457",
			"payment_amount": null,
			"settlement_initiated_on": "2023-06-08T15:10:35+05:30",
			"settled_on": "null",
			"reason": null,
			"adjustment": 100.0,
			"settlement_amount": 600.0,
			"service_charge": 0.5,
			"service_tax": 0.09,
			"amount_settled": null,
			"payment_from": "2023-06-08",
			"payment_till": "2023-06-08",
			"settlement_type": null,
			"remarks": null,
			"settlement_charge": null,
			"settlement_tax": null
		}
	},
	"event_time": "2023-06-08T15:10:37+05:30",
	"type": "VENDOR_SETTLEMENT_INITIATED"
}
```

### Vendor settlement success

```json theme={"dark"}
{
	"data": {
		"settlement": {
			"settlement_id": 49703,
			"status": "SUCCESS",
			"utr": "1686217237243457",
			"payment_amount": null,
			"settlement_initiated_on": "2023-06-08T15:10:35+05:30",
			"settled_on": "2023-06-08T15:10:37+05:30",
			"reason": null,
			"adjustment": 100.0,
			"settlement_amount": 600.0,
			"service_charge": 0.5,
			"service_tax": 0.09,
			"amount_settled": 600.0,
			"payment_from": "2023-06-08",
			"payment_till": "2023-06-08",
			"settlement_type": null,
			"remarks": null,
			"settlement_charge": null,
			"settlement_tax": null
		}
	},
	"event_time": "2023-06-08T15:10:37+05:30",
	"type": "VENDOR_SETTLEMENT_SUCCESS"
}
```

***

### Vendor settlement failed

```json theme={"dark"}
{
	"data": {
		"settlement": {
			"settlement_id": 49703,
			"status": "FAILED",
			"utr": "1686217237243457",
			"payment_amount": null,
			"settlement_initiated_on": "2023-06-08T15:10:35+05:30",
			"settled_on": "null",
			"reason": null,
			"adjustment": 100.0,
			"settlement_amount": 600.0,
			"service_charge": 0.5,
			"service_tax": 0.09,
			"amount_settled": null,
			"payment_from": "2023-06-08",
			"payment_till": "2023-06-08",
			"settlement_type": null,
			"remarks": null,
			"settlement_charge": null,
			"settlement_tax": null
		}
	},
	"event_time": "2023-06-08T15:10:37+05:30",
	"type": "VENDOR_SETTLEMENT_FAILED"
}
```

***

### Vendor settlement reversed

```json theme={"dark"}
{
    "data": {
        "settlement": {
            "settlement_id": 49703,
            "status": "REVERSED",
            "utr": "1686217237243457",
            "payment_amount": null,
            "settlement_initiated_on": "2023-06-08T15:10:35+05:30",
            "settled_on": "null",
            "reason": Failed from bank end,
            "adjustment": 100.00,
            "settlement_amount": 600.00,
            "service_charge": 0.50,
            "service_tax": 0.09,
            "amount_settled": null,
            "payment_from": "2023-06-08",
            "payment_till": "2023-06-08",
            "settlement_type": null,
			"remarks": null,
			"settlement_charge": null,
			"settlement_tax": null
        }
    },
    "event_time": "2023-06-08T15:10:37+05:30",
    "type": "VENDOR_SETTLEMENT_REVERSED"
}
```

***

### Payload field description

| Field | Description | Example |
| - | - | - |
| adjustment | The sum of refunds, disputes, and chargeback part of this settlement is displayed here. | 0 |
| amount\_settled | The total amount that is settled in this schedule option. | 50 |
| payment\_amount | Total transaction amount considered for settlement. | 100 |
| payment\_from | Start date from which the payments are considered for settlement. | 2022-03-15 |
| payment\_till | End date till which the payments are considered for settlement. | 2022-03-23 |
| reason | Reason for failed and reversed settlements. Click [here](/docs/payments/split/webhooks#reasons-for-failed-and-reversed-settlements) to know more. | Transfer mode is not valid for beneficiary. |
| service\_charge | Service charges are applicable for the payments that are included in this settlement. | 2 |
| service\_tax | Service tax is applicable for the payments that are included in this settlement. | 0.50 |
| settled\_on | Date and time at which the settlement was processed. | 2022-03-17T14:21:18+05:30 |
| settlement\_amount | The sum of net settlement amount for the payments part of this settlement. | 13 |
| settlement\_id | Cashfree settlement ID | 1155353 |
| settlement\_initiated\_on | The date on which settlement was initiated. | 2022-03-17T14:29:21+05:30 |
| status | Status of the settlement (either INITIATED, SUCCESS, FAILED, or REVERSED) | SUCCESS |
| utr | The unique transaction reference number is given by the bank for the settlement. | N076221079016329 |
| vendor\_id | Reference ID as shared by you when onboarding the vendor. | IS\_1hour\_Upi |
| vendor\_transaction\_amount | Transaction amount split of vendor | 50 |
| event\_time | Time at which settlement webhook was initiated. | 2022-03-17T14:29:23+05:30 |
| type | Type of webhook - VENDOR\_SETTLEMENT\_INITIATED, VENDOR\_SETTLEMENT\_SUCCESS, VENDOR\_SETTLEMENT\_FAILED, or VENDOR\_SETTLEMENT\_REVERSED. | VENDOR\_SETTLEMENT\_SUCCESS |

### Reasons for failed and reversed settlements

| Reason | Category | Description |
| :- | :- | :- |
| BANK\_GATEWAY\_ERROR | Bank | Technical error at the bank |
| BENE\_BANK\_DECLINED | Bank | Rejected by Beneficiary bank due to business reasons |
| FAILED | Bank | No explicit failure reason from the bank |
| INVALID\_IFSC\_FAIL | Customer | Invalid ifsc code provided for bank account |
| INVALID\_ACCOUNT\_FAIL | Customer | Bank account is invalid |
| RETURNED\_FROM\_BENEFICIARY | Bank | Immediate reversal from the beneficiary bank |
| INSUFFICIENT\_BALANCE | Vendor | Your balance is exhausted, need to add funds |
| IMPS\_MODE\_FAIL | Bank | IMPS mode not supported for the beneficiary |
| RTGS\_MODE\_FAIL | Bank | RTGS mode not supported (only for RTGS) |
| REINITIALIZE\_TRANSFER\_LATER | Bank | Technical error at the bank, retry later |
| NRE\_ACCOUNT\_FAIL | Customer | Customer bank account is an NRE account |
| ACCOUNT\_BLOCKED | Customer | Customer bank account is blocked |
| DEST\_LIMIT\_REACHED | Bank | Transfer limit to beneficiary exceeded |
| INVALID\_MODE\_FAIL | Bank | Transfer mode not valid for beneficiary |
| NPCI\_UNAVAILABLE | Bank | NPCI in unavailable |
| BENEFICIARY\_BANK\_OFFLINE | Bank | Beneficiary bank is offline |
| INVALID\_AMOUNT\_FAIL | Vendor | Amount is invalid for the given transfer mode |
| SUSPECTED\_TRANSFER | Customer | Suspicious transfer identified |
| BENE\_NAME\_DIFFERS | Customer | Beneficiary name not matching with bank records |
| DISABLED\_MODE | Vendor | Transfer mode not enabled for the account |
| AMAZON\_AMOUNT\_EXCEED | Vendor | Amount should be less than 10000 for Amazon Pay mode |
| BENEFICIARY\_BLACKLISTED | Vendor | Beneficiary is blacklisted |
| PAYOUT\_INACTIVE | Vendor | Payout account is not active |
| INVALID\_TRANSFER\_AMOUNT | Vendor | Transfer amount is invalid |
| BENEFICIARY\_NOT\_EXIST | Vendor | Beneficiary does not exist |
| BENEFICIARY\_INVALID\_MODE | Vendor | Mode Not valid for Beneficiary |
| INVALID\_BENE\_ACCOUNT\_OR\_IFSC | Vendor | Invalid bank account number or ifsc provided |
| BENEFICIARY\_NAME\_DIFFERS | Customer | Beneficiary name not matching with bank records |
| ANY\_OTHER\_REASON | Bank | No reason provided for the failure/reversal |
| INVALID\_OR\_NO\_SUCH\_ACCOUNT\_TYPE | Customer | Invalid account |

***

### Signature verification

The signature must be used to verify if the request has not been tampered with. To verify the signature at your end, you will need your Cashfree PG secret key along with the payload.

timestamp is present in the header x-webhook-timestamp\
Actual signature is present in the header x-webhook-signature

```json theme={"dark"}
"headers": {
        "host": "gamma.cashfree.com",
        "x-request-id": "ad4dc1e65f8901302455b247237a667a",
        "x-real-ip": "172.0.57.13",
        "x-forwarded-for": "172.0.57.13",
        "x-forwarded-host": "gamma.cashfree.com",
        "x-forwarded-port": "80",
        "x-forwarded-proto": "http",
        "x-forwarded-scheme": "http",
        "x-scheme": "http",
        "x-original-forwarded-for": "52.66.25.127",
        "content-length": "592",
        "accept": "_/_",
        "content-type": "application/json",
        "user-agent": "ReactorNetty/1.0.30",
        "x-datadog-parent-id": "4281924148563621550",
        "x-datadog-sampling-priority": "1",
        "x-datadog-trace-id": "228569355002181270",
        "x-webhook-signature": "Xm0YzEJCRsh0XvIEK12D4FqpmC60cReKoqPBn424kV0=",
        "x-webhook-timestamp": "1686217237543",
        "x-webhook-version": "2022-09-01"
    }
```

<div>
  <iframe title="Easy Split by Cashfree | 2-step integration to split incoming payments" />
</div>


# Vendor Status Change Webhook
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/split/webhooks/vendor-status-change-webhooks

Receive a Cashfree webhook whenever a vendor's KYC or activation status changes, so your platform always shows accurate Easy Split vendor states.

Configure vendor status change webhooks to receive automated notifications when vendor status is changed.

The webhook notifications are sent on all the URLs added and enabled in the vendor status change webhook. You can add new URLs and enable or disable existing URLs for vendor status change webhook at any time and it will reflect instantaneously.

The table below lists the webhook events available for vendor status change.

| Webhook event | Description |
| :- | :- |
| VENDOR\_STATUS\_UPDATE | This webhook will be triggered whenever there is a change in the status of the vendor. |

## Vendor status update

```json theme={"dark"}
{
	"data": {
		"merchant_vendor_id": "status002",
		"email": "john.doe@cashfree.com",
		"updated_status": "ACTION_REQUIRED",
		"past_status": "IN_BENE_CREATION",
		"account_holder": "JOHN DOE",
		"phone": "9876554927",
		"name": "BOB HOPE",
		"product_type": "PG",
		"max_split": 100,
		"account_number": "890289871772",
		"ifsc": "SCBL0036078",
		"dashboard_access": false,
		"vpa": "success@upi",
		"account_type": "Individual",
		"business_type": "Travel and Hospitality",
		"updated_by": "AUTOMATED",
		"document_status": {
			"PAN": "VERIFIED",
			"GSTIN": "ACTION_REQUIRED"
		}
	},
	"event_time": "2023-06-08T15:10:37+05:30",
	"type": "VENDOR_STATUS_UPDATE"
}
```

***

## Payload field description

| Field | Description | Example |
| - | - | - |
| merchant\_vendor\_id | Reference ID as shared by you when onboarding the vendor. | IS\_1hour\_Upi |
| email | Email of the vendor. | [test@gmail.com](mailto:test@gmail.com) |
| updated\_status | Current status of the vendor. | ACTIVE |
| past\_status | Previous status of the vendor. | ACTION\_REQUIRED |
| account\_holder | Name of the account holder associated with the vendor. | John Doe |
| phone | Contact phone number of the vendor. | 9876554927 |
| name | Name of the vendor. | BOB HOPE |
| product\_type | Type of product offered to the vendor | PG |
| max\_split | The maximum percentage of the amount shared with a vendor in any order. | 100 |
| account\_number | Vendor's bank account number. | 12345678909 |
| ifsc | IFSC (Indian Financial System Code) associated with the vendor's bank. | SBIN1231935 |
| dashboard\_access | Access level to the dashboard for the vendor (if applicable). | FALSE |
| vpa | VPA of the vendor for UPI transactions. | success\@upi |
| account\_type | Type of the vendor's account. | Individual |
| business\_type | Type of business conducted by the vendor. | Travel and Hospitality |
| updated\_by | Entity or process that initiated the status update. | AUTOMATED |
| document\_status | Status of any associated documents for the vendor. | "PAN": "VERIFIED" "GSTIN": "ACTION\_REQUIRED" |

***

## Signature verification

The signature must be used to verify if the request has not been tampered with. To verify the signature at your end, you will need your Cashfree PG secret key along with the payload.

timestamp is present in the header x-webhook-timestamp\
Actual signature is present in the header x-webhook-signature

```json theme={"dark"}
"headers": {
        "host": "gamma.cashfree.com",
        "x-request-id": "ad4dc1e65f8901302455b247237a667a",
        "x-real-ip": "172.0.57.13",
        "x-forwarded-for": "172.0.57.13",
        "x-forwarded-host": "gamma.cashfree.com",
        "x-forwarded-port": "80",
        "x-forwarded-proto": "http",
        "x-forwarded-scheme": "http",
        "x-scheme": "http",
        "x-original-forwarded-for": "52.66.25.127",
        "content-length": "592",
        "accept": "_/_",
        "content-type": "application/json",
        "user-agent": "ReactorNetty/1.0.30",
        "x-datadog-parent-id": "4281924148563621550",
        "x-datadog-sampling-priority": "1",
        "x-datadog-trace-id": "228569355002181270",
        "x-webhook-signature": "Xm0YzEJCRsh0XvIEK12D4FqpmC60cReKoqPBn424kV0=",
        "x-webhook-timestamp": "1686217237543",
        "x-webhook-version": "2022-09-01"
    }

```


# End Points
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/subscription/endpoints

Review the production and sandbox base URLs and authentication headers you need to call the v2023-08-01 Cashfree Subscriptions API endpoints.

Cashfree uses API keys to allow access to the API. Once you have signed up at our merchant site, you will see your AppId and SecretKey.

Cashfree expects the API key to be included in all API requests to the server. Use the endpoint **/api/v1/credentials/verify** to verify your credentials.

All API responses are in JSON format. POST requests should include ContentType: application/json

| Environment | Base URL |
| :- | :- |
| Production | [https://api.cashfree.com/](https://api.cashfree.com/) |
| Test | [https://test.cashfree.com/](https://test.cashfree.com/) |


# Create Subscription
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/subscription/mandate/create

openapi/payments/v2023-08-01.yaml post /subscriptions
Use this API to create a new subscription.



# Fetch Subscription
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/subscription/mandate/fetch

openapi/payments/v2023-08-01.yaml get /subscriptions/{subscription_id}
Use this API to fetch subscription details.



# Generate Transaction Return Summary
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/subscription/mandate/generate-transaction-summary

openapi/payments/v2023-08-01.yaml post /subscriptions/charge/{payment_id}/transaction-return-summary/generate
Use this API to generate transaction return summary for failed transactions (insufficient balance).



# Manage a subscription.
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/subscription/mandate/manage

openapi/payments/v2023-08-01.yaml post /subscriptions/{subscription_id}/manage
Use this API to manage subscriptions. You can cancel, pause, activate, or change the plan associated with a subscription.  To update the recurring amount for a periodic subscription, create a new plan with the revised amount, and then use the Manage Subscription API to associate the subscription with the new plan. Include the CHANGE_PLAN action and the new plan ID in the request body.<br/> <Note>Customers will not be notified about the restructuring. The charge amount cannot exceed the maximum amount defined in the original plan.</Note> <Note>Please note that the CHANGE_PLAN and PAUSE actions are not supported for On-Demand Subscriptions.</Note>



# API to get all the payment method details available for subscription payments.
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/subscription/mandate/payment-methods

openapi/payments/v2023-08-01.yaml post /subscriptions/eligibility/payment_methods
Use this API to check if a payment method is enabled for your account.



# API to upload file for Physical Nach Authorization.
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/subscription/mandate/physical-nach-mandate

openapi/payments/v2023-08-01.yaml post /subscriptions/pay/documents/{payment_id}
Use this API to upload file for Physical Nach Authorization.



# Fetch details of a single payment.
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/subscription/payment/fetch

openapi/payments/v2023-08-01.yaml get /subscriptions/{subscription_id}/payments/{payment_id}
Use this API to fetch details of a single payment of a subscription.



# Fetch details of all payments of a subscription.
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/subscription/payment/fetch-payments-for-mandate

openapi/payments/v2023-08-01.yaml get /subscriptions/{subscription_id}/payments
Use this API to fetch all payments of a subscription.



# Manage a single payment.
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/subscription/payment/manage

openapi/payments/v2023-08-01.yaml post /subscriptions/{subscription_id}/payments/{payment_id}/manage
Use this API to manage a payment of a subscription. A payment can be cancelled or retried with this API.



# Raise a charge or create an auth.
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/subscription/payment/raise

openapi/payments/v2023-08-01.yaml post /subscriptions/pay
Use this API to create an auth or to raise a charge.



# Physical Mandates
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/subscription/physical-mandates

Create, authorise, and manage NACH physical mandates using Cashfree Subscriptions APIs, covering customer signatures and bank details.

Physical mandate is the process of authorisation where the customer requires only their signature and bank account details. There is no requirement to have a Debit Card or Netbanking enabled to set up the mandate. Read more about [Physical Mandates](/docs/payments/subscription/payment-modes#bank-account-physical-mandate).

List of Physical Mandates APIs

| API name | Description |
| :- | :- |
| [Create Seamless Subscription API](/docs/api-reference/payments/previous/subscriptionsv1/seamless-apis/create-seamless-subscription-with-plan-id) | Use this API to create a subscription by providing a custom payment experience to your customers by specifying the plan ID and the customer details. You can also specify the bank account information when you create the subscription to ensure that mandates are created via the specified bank account only. TPV is applicable only for eNACH and UPI. |
| [Upload File](/docs/api-reference/payments/previous/subscriptionsv1/subscription/upload-physical-mandate-file) | Use this API to upload the Physical Nach registration forms that contain your customer’s bank account details and signature. Use the fileId you get in the response in the "Create Auth Seamless PhysicalMandate API". |
| [Create Auth Seamless Physical Mandate](/docs/api-reference/payments/previous/subscriptionsv1/seamless-apis/create-authorization-request) | Use this API to create an Authorization request for your customer. For Physical mandates, this API lets Cashfree know that the nach form is to be raised to the bank for successfully registering the mandate in production. |
| [Update Authorisation Status](/docs/api-reference/payments/previous/subscriptionsv1/seamless-apis/update-authorization-status) | Use this API to update the status of the authorisation from INITIALIZED to SUCCESS or FAILED. Provide the authID and the payment status. This is applicable only in the test environment. |


# Create a plan.
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/subscription/plans/create

openapi/payments/v2023-08-01.yaml post /plans
A plan allows your customer to identify the features you offer along with your pricing. You can create plans as per the pricing you support for your services. For each plan, you can set a pre-decided frequency and amount with which they’ll be charged.
Example: Netflix Plans - Premium, Basic, Standard, Mobile. Each plan differs and caters for a particular set of audiences.



# Fetch Plan
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/subscription/plans/fetch

openapi/payments/v2023-08-01.yaml get /plans/{plan_id}
Use this API to fetch plan details.



# Rate Limits
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/subscription/rate-limits

Understand the per-minute rate limits on Cashfree Subscriptions APIs and how to handle throttling on recurring payments.

The rate limit value shows the number of API calls that were made in a minute. For example, if the rate limit is 400 - it means you can call a maximum of 400 API calls in a minute.

**Rate Limits in Sandbox & Production:**\
We use rate limiting for all endpoints. Rate limiting is based on your IP and your account Id. By default, the following rate limits are applied per minute.

| API | Rate limit value per minute | Rate limit type |
| :- | :- | :- |
| [Create Plan](/docs/api-reference/payments/previous/v2023-08-01/subscription/plans/create) | 60 | Account |
| [Create Subscription](/docs/api-reference/payments/previous/v2023-08-01/subscription/mandate/create) | 60 | Account |
| [Create Seamless Subscription](/docs/api-reference/payments/previous/subscriptionsv1/seamless-apis/create-seamless-subscription-with-plan-id) | 60 | Account |
| [Get Subscription Details](/docs/api-reference/payments/previous/v2023-08-01/subscription/mandate/fetch) | 60 | Account |
| [Get All Subscription Payments](/docs/api-reference/payments/previous/subscriptionsv1/subscription/fetch-subscription-payments) | 60 | Account |
| [Get Single Subscription Payment](/docs/api-reference/payments/previous/subscriptionsv1/subscription/fetch-single-subscription-payment) | 60 | Account |
| [Cancel Charge](/docs/api-reference/payments/previous/subscriptionsv1/subscription/cancel-subscription) | 60 | Account |
| [Charge Subscription](/docs/api-reference/payments/previous/subscriptionsv1/subscription/charge-subscription) | 60 | Account |
| [Charge Retry](/docs/api-reference/payments/previous/subscriptionsv1/subscription/retry-subscription-charge) | 60 | Account |
| [Activate Subscription](/docs/api-reference/payments/previous/subscriptionsv1/subscription/activate-subscription) | 60 | Account |
| [Get Payment Details using Merchant Txn ID](/docs/api-reference/payments/previous/subscriptionsv1/subscription/fetch-payment-by-merchant-transaction-id) | 60 | Account |
| [Update Recurring-amount](/docs/api-reference/payments/previous/subscriptionsv1/subscription/update-recurring-amount) | 60 | Account |


# Redirection Payload After Authorisation
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/subscription/redirection-payload-after-authorization

Understand the POST parameters Cashfree sends to your subscription returnUrl after the customer authorises the payment on the Subscriptions API.

## Request configuration

| Method | Parameter type | URL |
| - | - | - |
| cf\_subReferenceId | Long | Unique Id which was generated when the subscription was created (Numeric) |
| cf\_subscriptionId | String | Checksum used to authenticate the transaction |
| cf\_authAmount | Float | The money that was charged to authorise the subscription |
| cf\_referenceId | Long | The referenceId/transactionId of authorisation in PG |
| cf\_status | String | Status of the subscription. In the returnUrl, the response should be ACTIVE or BANK\_APPROVAL\_PENDING if the authorisation was successful or INITIALIZED if the authorisation failed. |
| cf\_message | String | A brief note about the payment. |
| signature | String | The hash of all parameters in the request generated using secretKey. |
| cf\_umrn | String | The unique identifier associated with a mandate. Applicable if the payment mode is eMandate. |
| cf\_checkoutStatus | String | The subscription checkout status. The status can be SUCCESS, FAILED, SUCCESS\_DEBIT\_PENDING, SUCCESS\_TOKENIZATION\_PENDING. (This parameter will be sent from the 1st of November onwards, by default. It is available in the test environment.) |
| cf\_mode | String | The checkout payment mode. Modes - NPCI\_SBC, SBC\_UPI, SBC\_CREDIT\_CARD, SBC\_DEBIT\_CARD. (This parameter will be sent from the 1st of November onwards, by default. It is available in the test environment.) |
| cf\_subscriptionPaymentId | String | The subscription payment ID. (This parameter will be sent from the 1st of November onwards, by default. It is available in the test environment.) |
| cf\_umn | String | The unique identifier is associated with a mandate. This is applicable if the payment mode is **UPI**. |

<Warning> 🚧 **Return URL**
Once your customer has completed the checkout on the OTP page, we will redirect them back to your `return_url`. This will be a link-based redirection, so if you have provided a return\_url of the format - `https://b8af79f41056.eu.ngrok.io?order_id={order_id}` - your customer will be redirected to the URL - `https://b8af79f41056.eu.ngrok.io?order_id=order_271vfuhh1o4h6bQIigqyOx74YiJ1T`. </Warning>


# Create a refund.
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/subscription/refund/create

openapi/payments/v2023-08-01.yaml post /subscriptions/{subscription_id}/refunds
This API allows you to create refund on a successful payment. Refund amount can be partial or the full amount of the payment.



# Fetch details of a refund.
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/subscription/refund/fetch

openapi/payments/v2023-08-01.yaml get /subscriptions/{subscription_id}/refunds/{refund_id}
Use this API to fetch details of a refund of a subscription payment.



# Overview
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/subscription/refund/refund-apis-overview

Manage subscription refunds through Cashfree APIs, covering how to initiate, fetch, and reconcile refunds on recurring payments.

# List of Subscription Refund APIs

| API name | Description |
| :- | :- |
| [Create Refund](/docs/api-reference/payments/previous/v2023-08-01/subscription/refund/create) | Use this API to create a refund for the payment of a Subscription. |
| [Get Refund](/docs/api-reference/payments/previous/v2023-08-01/subscription/refund/fetch) | Use this API to fetch the status of the refund of a Subscription. |


# Postman Collection
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/subscription/subscription-postman-collection

Download the ready-made Postman collection for the v2023-08-01 Cashfree Subscriptions APIs and start testing mandate and charge calls in minutes.

Get started quickly with Cashfree's Subscription APIs by downloading the collection and importing it in Postman.

<a href="https://documenter.getpostman.com/view/39865626/2sAYk7R3jf#a9bb718c-14fd-4f79-bde4-24253164af5a">
  Download Cashfree Subscription Postman Collection
</a>


# Subscription Webhooks
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/subscription/webhooks

Subscribe to Cashfree Subscription webhooks so your server reacts whenever a mandate is authorised, a charge succeeds, or a refund is processed.

Below are the various events that can be sent to your webhook endpoint. These webhooks will be triggered if the merchant has integrated our newer Subscription API.

<Note>
  If the merchant added the webhook under the 2023-08-01 version, they will receive the same version of the webhook for older subscriptions as well.
</Note>

* `SUBSCRIPTION_STATUS_CHANGE`
* `SUBSCRIPTION_AUTH_STATUS`
* `SUBSCRIPTION_PAYMENT_NOTIFICATION_INITIATED`
* `SUBSCRIPTION_PAYMENT_SUCCESS`
* `SUBSCRIPTION_PAYMENT_FAILED`
* `SUBSCRIPTION_PAYMENT_CANCELLED`
* `SUBSCRIPTION_REFUND_STATUS`

## `SUBSCRIPTION_STATUS_CHANGE`

Whenever a subscription is created it goes to initialised state and customer is expected to authorise it. The list of statuses where this webhook will get triggered are:

* ACTIVE
* ON\_HOLD
* COMPLETED
* CUSTOMER\_CANCELLED
* CUSTOMER\_PAUSED
* EXPIRED
* LINK\_EXPIRED
* BANK\_APPROVAL\_PENDING

<Accordion title="SUBSCRIPTION_STATUS_CHANGE Event Payload">
  ```javascript theme={"dark"}
  {
      "data": {
          "subscription_details": {
              "cf_subscription_id": "123456",
              "subscription_id": "Demo_Subscription",
              "subscription_status": "ACTIVE",
              "subscription_expiry_time": "2024-01-14T23:00:08+05:30",
              "subscription_first_charge_time": "2024-01-10T23:00:08+05:30"
          },
          "customer_details": {
              "customer_name": "john",
              "customer_email": "john@dummy.com",
              "customer_phone": "9908730221"
          },
          "plan_details": {
              "plan_id": "plan12345",
              "plan_name": "Plan Name",
              "plan_type": "ON_DEMAND",
              "plan_max_cycles": 10,
              "plan_recurring_amount": 100.00,
              "plan_max_amount": 1000.00,
              "plan_currency": "INR",
              "plan_note": "Note",
              "plan_status": "ACTIVE"
          },
          "authorization_details": {
              "authorizationAmount": 100,
              "authorizationAmountRefund": true,
              "approveByTime": "2022-02-09T18:04:34+05:30",
              "authorizationReference": "6595231908096894505959",
              "authorizationTime": "2022-08-03T16:09:51",
              "authorizationStatus": "SUCCESS",
              "paymentId": "123",
              "paymentMethod": "DEBIT_CARD",
              "instrumentId": "hsdg9"
          },
          "payment_gateway_details": {
              "gateway_name": "CASHFREE",
              "gateway_subscription_id": "Demo_Subscription",
              "gateway_plan_id": "plan12345",
              "gateway_auth_id": "6595231908096894505959"
          }
      },
      "event_time": "2023-01-03T11:16:10+05:30",
      "type": "SUBSCRIPTION_STATUS_CHANGE"
  }
  ```
</Accordion>

## SUBSCRIPTION\_AUTH\_STATUS

The event is triggered when the checkout is completed by the customer for success and failed cases.

<Accordion title="SUBSCRIPTION_STATUS_CHANGE Event Payload">
  ```javascript theme={"dark"}
  {
      "data": {
          "payment_id": "12345",
          "cf_payment_id": "67890",
          "cf_txn_id": "789012",
          "cf_order_id": 98765,
          "subscription_id": "sub12345",
          "cf_subscription_id": "sub67890",
          "payment_type": "DEBIT_CARD",
          "authorization_details": {
              "authorization_amount": 100,
              "authorization_amount_refund": true,
              "approve_by_time": "2024-07-20T16:09:50+05:30",
              "authorization_reference": "6595231908096894505959",
              "authorization_time": "2024-07-20T16:09:51",
              "authorization_status": "ACTIVE",
              "payment_id": "123",
              "payment_method": "DEBIT_CARD",
              "instrument_id": "hsdg9"
          },
          "payment_amount": 200.75,
          "payment_schedule_date": "2024-07-20",
          "payment_initiated_date": "2024-07-20",
          "payment_remarks": "auth payment",
          "retry_attempts": 0,
          "failureDetails": null,
          "payment_status": "SUCCESS",
          "payment_gateway_details": {
              "gateway_name": "CASHFREE",
              "gateway_subscription_id": "Demo_Subscription",
              "gateway_payment_id": "payment12345"
          }
      },
      "event_time": "2024-07-20T11:16:10+05:30",
      "type": "SUBSCRIPTION_AUTH_STATUS"
  }
  ```
</Accordion>

## SUBSCRIPTION\_PAYMENT\_NOTIFICATION\_INITIATED

This webhook is used to inform the merchant that we have sent a notification of payment to the customer.

<Accordion title="SUBSCRIPTION_PAYMENT_NOTIFICATION_INITIATED event payload">
  ```javascript theme={"dark"}
  {
      "data": {
          "payment_id": "12345",
          "cf_payment_id": "67890",
          "cf_txn_id": "789012",
          "cf_order_id": 98765,
          "subscription_id": "sub12345",
          "cf_subscription_id": "sub67890",
          "payment_type": "DEBIT_CARD",
          "authorization_details": {
              "authorization_amount": 100,
              "authorization_amount_refund": true,
              "approve_by_time": "2024-07-20T16:09:50+05:30",
              "authorization_reference": "6595231908096894505959",
              "authorization_time": "2024-07-20T16:09:51",
              "authorization_status": "PENDING",
              "payment_id": "123",
              "payment_method": "DEBIT_CARD",
              "instrument_id": "hsdg9"
          },
          "payment_amount": 200,
          "payment_schedule_date": "2024-07-20",
          "payment_initiated_date": "2024-07-20",
          "payment_remarks": "payment",
          "retry_attempts": 0,
          "failureDetails": null,
          "payment_status": "INITIALIZED",
          "payment_gateway_details": {
              "gateway_name": "CASHFREE",
              "gateway_subscription_id": "Demo_Subscription",
              "gateway_payment_id": "payment12345"
          }
      },
      "event_time": "2024-07-20T11:16:10+05:30",
      "type": "SUBSCRIPTION_PAYMENT_NOTIFICATION_INITIATED"
  }
  ```
</Accordion>

## SUBSCRIPTION\_PAYMENT\_SUCCESS

This notification is sent whenever a successful payment is processed for an active subscription.

<Accordion title="SUBSCRIPTION_PAYMENT_SUCCESS event payload">
  ```javascript theme={"dark"}
  {
      "data": {
          "payment_id": "12345",
          "cf_payment_id": "67890",
          "cf_txn_id": "789012",
          "cf_order_id": 98765,
          "subscription_id": "sub12345",
          "cf_subscription_id": "sub67890",
          "payment_type": "DEBIT_CARD",
          "authorization_details": {
              "authorization_amount": 100,
              "authorization_amount_refund": true,
              "approve_by_time": "2024-07-20T16:09:50+05:30",
              "authorization_reference": "6595231908096894505959",
              "authorization_time": "2024-07-20T16:09:51",
              "authorization_status": "ACTIVE",
              "payment_id": "123",
              "payment_method": "DEBIT_CARD",
              "instrument_id": "hsdg9"
          },
          "payment_amount": 200,
          "payment_schedule_date": "2024-07-20",
          "payment_initiated_date": "2024-07-20",
          "payment_remarks": "payment",
          "retry_attempts": 0,
          "failureDetails": null,
          "payment_status": "SUCCESS",
          "payment_gateway_details": {
              "gateway_name": "CASHFREE",
              "gateway_subscription_id": "Demo_Subscription",
              "gateway_payment_id": "payment12345"
          }
      },
      "event_time": "2024-07-20T11:16:10+05:30",
      "type": "SUBSCRIPTION_PAYMENT_SUCCESS"
  }
  ```
</Accordion>

## SUBSCRIPTION\_PAYMENT\_FAILED

This notification is sent whenever payment processing fails for an active subscription.

<Accordion title="SUBSCRIPTION_PAYMENT_FAILED event payload">
  ```javascript theme={"dark"}
  {
      "data": {
          "payment_id": "12345",
          "cf_payment_id": "67890",
          "cf_txn_id": "789012",
          "cf_order_id": 98765,
          "subscription_id": "sub12345",
          "cf_subscription_id": "sub67890",
          "payment_type": "DEBIT_CARD",
          "authorization_details": {
              "authorization_amount": 100,
              "authorization_amount_refund": true,
              "approve_by_time": "2024-07-18T16:09:50+05:30",
              "authorization_reference": "6595231908096894505959",
              "authorization_time": "2024-07-18T16:09:51",
              "authorization_status": "ACTIVE",
              "payment_id": "123",
              "payment_method": "DEBIT_CARD",
              "instrument_id": "hsdg9"
          },
          "payment_amount": 200,
          "payment_schedule_date": "2024-07-20",
          "payment_initiated_date": "2024-07-20",
          "payment_remarks": "payment",
          "retry_attempts": 0,
          "failureDetails": {
              "failureReason": "Insufficient balance"
          },
          "payment_status": "FAILED",
          "payment_gateway_details": {
              "gateway_name": "CASHFREE",
              "gateway_subscription_id": "Demo_Subscription",
              "gateway_payment_id": "payment12345"
          }
      },
      "event_time": "2024-07-20T11:16:10+05:30",
      "type": "SUBSCRIPTION_PAYMENT_FAILED"
  }
  ```
</Accordion>

## SUBSCRIPTION\_PAYMENT\_CANCELLED

This notification is sent whenever payment processing is cancelled by user for an active subscription.

<Accordion title="SUBSCRIPTION_PAYMENT_CANCELLED event payload">
  ```javascript theme={"dark"}
  {
      "data": {
          "payment_id": "12345",
          "cf_payment_id": "67890",
          "cf_txn_id": "789012",
          "cf_order_id": 98765,
          "subscription_id": "sub12345",
          "cf_subscription_id": "sub67890",
          "payment_type": "DEBIT_CARD",
          "authorization_details": {
              "authorization_amount": 100,
              "authorization_amount_refund": true,
              "approve_by_time": "2024-07-18T16:09:50+05:30",
              "authorization_reference": "6595231908096894505959",
              "authorization_time": "2024-07-18T16:09:51",
              "authorization_status": "ACTIVE",
              "payment_id": "123",
              "payment_method": "DEBIT_CARD",
              "instrument_id": "hsdg9"
          },
          "payment_amount": 200,
          "payment_schedule_date": "2024-07-20",
          "payment_initiated_date": "2024-07-20",
          "payment_remarks": "payment",
          "retry_attempts": 0,
          "failureDetails": {
              "failureReason": "Subscription is not active"
          },
          "payment_status": "CANCELLED",
          "payment_gateway_details": {
              "gateway_name": "CASHFREE",
              "gateway_subscription_id": "Demo_Subscription",
              "gateway_payment_id": "payment12345"
          }
      },
      "event_time": "2024-07-20T11:16:10+05:30",
      "type": "SUBSCRIPTION_PAYMENT_CANCELLED"
  }
  ```
</Accordion>

## SUBSCRIPTION\_REFUND\_STATUS

This event is triggered whenever a refund status of a transaction will be success, failed, or cancelled.

<Accordion title="SUBSCRIPTION_REFUND_STATUS event payload">
  ```javascript theme={"dark"}
  {
      "data": {
          "payment_id": "pay8643",
          "cf_payment_id": "863782648",
          "refund_id": "refund2",
          "cf_refund_id": "ref_212",
          "refund_amount": 100,
          "refund_note": "test",
          "refund_speed": "INSTANT",
          "refund_status": "SUCCESS",
          "failure_details": null,
          "payment_gateway_details": {
              "gateway_name": "CASHFREE",
              "gateway_payment_id": "pay8643",
              "gateway_refund_id": "refund2"
          }
      },
      "event_time": "2023-01-03T11:16:10+05:30",
      "type": "SUBSCRIPTION_REFUND_STATUS"
  }
  ```
</Accordion>


# Delete Saved Card Instrument
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/token-vault/delete

openapi/payments/v2023-08-01.yaml delete /customers/{customer_id}/instruments/{instrument_id}
Use this API to delete a saved card instrument for a customer_id and instrument_id



# Fetch Specific Saved Card Instrument
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/token-vault/fetch-specific-saved-card-instrument

openapi/payments/v2023-08-01.yaml get /customers/{customer_id}/instruments/{instrument_id}
Use this API to fetch a single specific saved card for a customer_id by it's instrument_id



# Fetch cryptogram for a saved card instrument
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/token-vault/generate-cryptogram

openapi/payments/v2023-08-01.yaml get /customers/{customer_id}/instruments/{instrument_id}/cryptogram
Use this API To get the card network token, token expiry and cryptogram for a saved card instrument using instrument id



# Fetch All Saved Card Instrument
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/token-vault/get-all

openapi/payments/v2023-08-01.yaml get /customers/{customer_id}/instruments
Use this API to fetch saved cards for a customer_id 



# Card Token Webhook
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2023-08-01/token-vault/webhooks

Subscribe to Cashfree card token webhooks to receive asynchronous notifications whenever a saved card instrument is created, updated, or deleted.

| Event | Description |
| - | - |
| INSTRUMENT\_ACTIVE\_WEBHOOK | This webhook is triggered when the card is successfully tokenised. |
| INSTRUMENT\_FAILED\_WEBHOOK | This webhook is triggered when the card tokenisation fails. |

## Instrument active webhook

An instrument active webhook is triggered when a card is tokenised successfully from the networks like visa, mastercard, etc.

<Tabs>
  <Tab title="Version (2023-08-01)">
    ```javascript Instrument Active Webhook theme={"dark"}
    {
       "data": {
          "instrument": {
             "customer_id": "siddhesh199721",
             "afa_reference": "887316963",
             "instrument_id": "af250dc5-e5e5-4e7d-a7cf-3f446741fa54",
             "instrument_type": "card",
             "instrument_uid": "680cd7171583f9f64b426983d4501d6941b462932ce5f626be78392d5ec42660",
             "instrument_display": "XXXXXXXXXXXX6854",
             "instrument_status": "ACTIVE",
             "added_at": "2022-04-14T10:42:59+05:30",
             "instrument_meta": {
                "card_network": "visa",
                "card_bank_name": "HDFC BANK",
                "card_country": "IN",
                "card_type": "credit",
                "sub_type": "R",
                "card_par": "50012ADWQZJKHCLXLT61QTYD5QNX1",
                "card_token_details": null
             }
          }
       },
       "event_time": "2022-04-14T10:44:14+05:30",
       "type": "INSTRUMENT_ACTIVE_WEBHOOK"
    }
    ```
  </Tab>
</Tabs>

## Instrument failed webhook

An instrument failed webhook is triggered when a card was not tokenised from the networks like visa, mastercard, etc.

<Tabs>
  <Tab title="Version (2023-08-01)">
    ```javascript Instrument Failed Webhook theme={"dark"}
    {
       "data": {
          "instrument": {
             "customer_id": "siddhesh199721",
             "afa_reference": "887316963",
             "instrument_id": "af250dc5-e5e5-4e7d-a7cf-3f446741fa54",
             "instrument_type": "card",
             "instrument_uid": "680cd7171583f9f64b426983d4501d6941b462932ce5f626be78392d5ec42660",
             "instrument_display": "XXXXXXXXXXXX6854",
             "instrument_status": "FAILED",
             "added_at": "2022-04-14T10:42:59+05:30",
             "instrument_meta": {
                "card_network": "visa",
                "card_bank_name": "HDFC BANK",
                "card_country": "IN",
                "card_type": "credit",
                "sub_type": "R",
                "card_par": null,
                "card_token_details": null
             }
          },
          "error_details": {
             "error_code": "NETWORK_ERROR",
             "error_description": "Error while processing the request",
             "error_source": "NETWORK"
          }
       },
       "event_time": "2022-04-14T10:44:14+05:30",
       "type": "INSTRUMENT_FAILED_WEBHOOK"
    }
    ```
  </Tab>
</Tabs>

<Accordion title="Understanding the payload">
  ## Payload field description

  | Field | Description | Example |
  | :- | :- | :- |
  | customer\_id (String) | The customer ID associated with the save instrument request. It is sent by the merchant as a part of create order request in the customer ID field. | user199721 |
  | afa\_reference (String) | cf\_payment\_id of the successful transaction done while saving instrument. | 887316963 |
  | instrument\_id (String) | The reference ID of the saved instrument. Unique for a save instrument request but not unique for a particular instrument like card number. | af250dc5-e5e5-4e7d-a7cf-3f446741fa54 |
  | instrument\_type (String) | Type of instrument - card | card |
  | instrument\_uid (String) | Unique identifier for the instrument. For example, if a same card is saved by 2 different customers the instrument\_uid would be same for both the cards. | 680cd7171583f9f64b426983d4501d6941b462932ce5f626be78392d5ec42660 |
  | instrument\_display (String) | The display text for the saved instrument. For example, in case of saved cards the first 12 digits would be masked and only the last 4 digits would be visible in the instrument display string. It can be displayed to the customer for selecting a saved instrument for payment. | XXXXXXXXXXXX6854 |
  | instrument\_status (String) | The status of saved instrument - INACTIVE, ACTIVE | ACTIVE |
  | added\_at (String) | Timestamp at which instrument was saved. | 2022-04-14T10:42:59+05:30 |
  | card\_network (String) | The card network to which the saved card belongs. Visa, Mastercard, Rupay, etc. | visa |
  | card\_bank\_name (String) | Card issuing bank name. | HDFC BANK |
  | card\_country (String) | Card issuing country code. | IN |
  | card\_type (String) | debit, credit, prepaid, etc. | debit |
  | card\_token\_details (Object) | Additional card token details like card token expiry, card token would be passed in this object. Note: Currently, the field is always passed as null. | null |
  | event\_time (String) | Time at which webhook was initiated. | 2022-02-28T13:04:28+05:30 |
  | type (String) | Type of the instrument webhook. | INSTRUMENT\_ACTIVE\_WEBHOOK |
</Accordion>


# Order Pay Authorise Only
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/apple-pay/payments/authorize-payment-for-an-order

post /orders/sessions/authorize
Use this API when an order has already been created and you want Cashfree to process the payment for authorisation only. To use this API, the 'AUTHORIZE_ONLY' flag must be enabled for your account. Submit [Support Form](https://merchant.cashfree.com/auth/login) to enable this feature.



# Create Customer at Cashfree
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/customers/create

openapi/payments/v2025-01-01.yaml post /customers
Use this API to register a customer in Cashfree's system before initiating payments, subscriptions, tokenisation, or other customer-linked actions. It creates a reusable *customer profile* and returns a unique identifier for future transactions.



# Accept Dispute by Dispute ID
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/disputes/accept-dispute-by-dispute-id

openapi/payments/v2025-01-01.yaml put /disputes/{dispute_id}/accept
Use this API to get accept the Dispute by specifying the Dispute ID.



# Contest Arbitration by Dispute ID
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/disputes/contest-arbitration-by-dispute-id

openapi/payments/v2025-01-01.yaml put /disputes/{dispute_id}/contest-arbitration
Use this API to contest an ARBITRATION dispute without uploading documents.

NPCI (National Payments Corporation of India) does not allow document upload at the `ARBITRATION` stage. Cashfree forwards the evidence you submitted at the pre-arbitration stage to the card network or NPCI for a final decision.

To contest a dispute at an earlier stage by uploading documents, use the [Submit Evidence API](/docs/api-reference/payments/previous/v2025-01-01/disputes/submit-evidence-to-contest-the-dispute-by-dispute-id) instead.

Use this API only when `dispute_type` is `ARBITRATION` and `dispute_status` is one of the following:

* `ARBITRATION_CREATED`
* `ARBITRATION_DOCS_RECEIVED`
* `ARBITRATION_INSUFFICIENT_EVIDENCE`


# Dispute Webhooks
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/disputes/dispute-webhooks

Learn in detail about dispute webhooks.

Dispute webhooks can be configured to receive automated notifications when disputes are created, updated and closed.

The webhook notification will be sent on all the URLs added and enabled under the dispute webhook. Merchants can add new URLs and enable or disable existing URLs for refund webhook at any point in time and it will be reflected instantaneously.

| Webhook | Description |
| :- | :- |
| DISPUTE\_CREATED | Dispute\_created webhook will be triggered when a new dispute is created. |
| DISPUTE\_UPDATED | Dispute\_updated webhook will be triggered when a dispute is updated, for example when a comment is added by the Cashfree team, when the dispute moves into further stages like Pre-arbitration, Arbitration, or when the status of the dispute changes. |
| DISPUTE\_CLOSED | This webhook will be triggered when a dispute is closed. |

Click [here](/docs/payments/online/webhooks/overview) to know how to configure webhooks.

## Dispute created

**Sample Payload**

<Tabs>
  <Tab title="Version (2025-01-01)">
    ```javascript Version 2025-01-01 theme={"dark"}

    {
      "data": {
        "dispute": {
          "dispute_id": "433475258",
          "dispute_type": "DISPUTE",
          "reason_code": "1402",
          "reason_description": "Duplicate Processing",
          "dispute_amount": 3,
          "created_at": "2023-06-15T21:49:48+05:30",
          "updated_at": "2023-06-15T21:49:48+05:30",
          "respond_by": "2023-06-18T23:59:59+05:30",
          "dispute_status": ""DISPUTE_CREATED"",
          "cf_dispute_remarks": "Dispute is created, please take action",
          "dispute_action_on": "MERCHANT",
          "dispute_amount_currency": "INR"
        },
        "order_details": {
          "order_id": "order_1944392DR1kMTFYdIf8bI2awAcC3i9FTa",
          "order_amount": 3,
          "order_currency": "INR",
          "cf_payment_id": 885473311,
          "payment_amount": 3,
          "payment_currency": "INR"
        },
        "customer_details": {
          "customer_name": "Dileep Kumar s",
          "customer_phone": "8000000000",
          "customer_email": "dileep@gmail.com"
        }
      },
      "event_time": "2023-06-15T21:50:04+05:30",
      "type": "DISPUTE_CREATED"
    }
    ```
  </Tab>

  <Tab title="Version (2023-08-01)">
    ```javascript Version 2023-08-01 theme={"dark"}

    {
      "data": {
        "dispute": {
          "dispute_id": "433475258",
          "dispute_type": "DISPUTE",
          "reason_code": "1402",
          "reason_description": "Duplicate Processing",
          "dispute_amount": 3,
          "created_at": "2023-06-15T21:49:48+05:30",
          "updated_at": "2023-06-15T21:49:48+05:30",
          "respond_by": "2023-06-18T23:59:59+05:30",
          "dispute_status": ""DISPUTE_CREATED"",
          "cf_dispute_remarks": "Dispute is created, please take action",
          "dispute_action_on": "MERCHANT"
        },
        "order_details": {
          "order_id": "order_1944392DR1kMTFYdIf8bI2awAcC3i9FTa",
          "order_amount": 3,
          "order_currency": "INR",
          "cf_payment_id": 885473311,
          "payment_amount": 3,
          "payment_currency": "INR"
        },
        "customer_details": {
          "customer_name": "Dileep Kumar s",
          "customer_phone": "8000000000",
          "customer_email": "dileep@gmail.com"
        }
      },
      "event_time": ""2023-06-15T21:50:04+05:30",
      "type": "DISPUTE_CREATED"
    }
    ```
  </Tab>
</Tabs>

## Dispute updated

**Sample Payload**

<Tabs>
  <Tab title="Version (2025-01-01)">
    ```javascript Version 2025-01-01 theme={"dark"}
    {
      "data": {
        "dispute": {
          "dispute_id": "433475257",
          "dispute_type": "PRE_ARBITRATION",
          "reason_code": "13.1",
          "reason_description": "Merchandise / Services Not Received",
          "dispute_amount": 40000,
          "created_at": "2023-06-15T21:16:03+05:30",
          "updated_at": "2023-06-15T21:19:15+05:30",
          "respond_by": "2023-06-19T23:59:59+05:30",
          "dispute_status": "PRE_ARBITRATION_CREATED",
          "cf_dispute_remarks": "Pre Arbitration request has been raised for this case.\nTarget Date :: 2023-06-18T00:00 -> 2023-06-19T23:59:59.",
          "dispute_update": "TYPE_UPDATE",
          "dispute_action_on": "MERCHANT",
          "dispute_amount_currency": "INR"
        },
        "order_details": {
          "order_id": "order_1944392D4jHtCeVPPdTXkaUwg5cfnujQe",
          "order_amount": 40000,
          "order_currency": "INR",
          "cf_payment_id": 885457437,
          "payment_amount": 40000,
          "payment_currency": "INR"
        },
        "customer_details": {
          "customer_name": "Dileep Kumar s",
          "customer_phone": "8000000000",
          "customer_email": "dileep@gmail.com"
        }
      },
      "event_time": "2023-06-15T21:20:24+05:30",
      "type": "DISPUTE_UPDATED"
    }
    ```
  </Tab>

  <Tab title="Version (2023-08-01)">
    ```javascript Version 2023-08-01 theme={"dark"}
    {
      "data": {
        "dispute": {
          "dispute_id": "433475257",
          "dispute_type": "PRE_ARBITRATION",
          "reason_code": "13.1",
          "reason_description": "Merchandise / Services Not Received",
          "dispute_amount": 40000,
          "created_at": "2023-06-15T21:16:03+05:30",
          "updated_at": "2023-06-15T21:19:15+05:30",
          "respond_by": "2023-06-19T23:59:59+05:30",
          "dispute_status": "PRE_ARBITRATION_CREATED",
          "cf_dispute_remarks": "Pre Arbitration request has been raised for this case.\nTarget Date :: 2023-06-18T00:00 -> 2023-06-19T23:59:59.",
          "dispute_update": "TYPE_UPDATE",
          "dispute_action_on": "MERCHANT"
        },
        "order_details": {
          "order_id": "order_1944392D4jHtCeVPPdTXkaUwg5cfnujQe",
          "order_amount": 40000,
          "order_currency": "INR",
          "cf_payment_id": 885457437,
          "payment_amount": 40000,
          "payment_currency": "INR"
        },
        "customer_details": {
          "customer_name": "Dileep Kumar s",
          "customer_phone": "8000000000",
          "customer_email": "dileep@gmail.com"
        }
      },
      "event_time": "2023-06-15T21:20:24+05:30",
      "type": "DISPUTE_UPDATED"
    }
    ```
  </Tab>
</Tabs>

## Dispute closed

**Sample Payload**

<Tabs>
  <Tab title="Version (2025-01-01)">
    ```javascript Version 2025-01-01 theme={"dark"}
    {
      "data": {
        "dispute": {
          "dispute_id": "433475257",
          "dispute_type": "CHARGEBACK",
          "reason_code": "4855",
          "reason_description": "Goods or Services Not Provided",
          "dispute_amount": 4500,
          "created_at": "2023-06-15T21:16:03+05:30",
          "updated_at": "2023-06-15T21:16:51+05:30",
          "respond_by": "2023-06-18T00:00:00+05:30",
          "resolved_at": "2023-06-15T21:16:51.682836678+05:30",
          "dispute_status": "CHARGEBACK_MERCHANT_WON",
          "cf_dispute_remarks": "Chargeback won by merchant",
          "dispute_amount_currency": "INR"
        },
        "order_details": {
          "order_id": "order_1944392D4jHtCeVPPdTXkaUwg5cfnujQe",
          "order_amount": 4500,
          "order_currency": "INR",
          "cf_payment_id": 885457437,
          "payment_amount": 4500,
          "payment_currency": "INR"
        },
        "customer_details": {
          "customer_name": "Dileep Kumar s",
          "customer_phone": "8000000000",
          "customer_email": "dileep@gmail.com"
        }
      },
      "event_time": "2023-06-15T21:17:14+05:30",
      "type": "DISPUTE_CLOSED"
    }
    ```
  </Tab>

  <Tab title="Version (2023-08-01)">
    ```javascript Version 2023-08-01 theme={"dark"}
    {
      "data": {
        "dispute": {
          "dispute_id": "433475257",
          "dispute_type": "CHARGEBACK",
          "reason_code": "4855",
          "reason_description": "Goods or Services Not Provided",
          "dispute_amount": 4500,
          "created_at": "2023-06-15T21:16:03+05:30",
          "updated_at": "2023-06-15T21:16:51+05:30",
          "respond_by": "2023-06-18T00:00:00+05:30",
          "resolved_at": "2023-06-15T21:16:51.682836678+05:30",
          "dispute_status": "CHARGEBACK_MERCHANT_WON",
          "cf_dispute_remarks": "Chargeback won by merchant"
        },
        "order_details": {
          "order_id": "order_1944392D4jHtCeVPPdTXkaUwg5cfnujQe",
          "order_amount": 4500,
          "order_currency": "INR",
          "cf_payment_id": 885457437,
          "payment_amount": 4500,
          "payment_currency": "INR"
        },
        "customer_details": {
          "customer_name": "Dileep Kumar s",
          "customer_phone": "8000000000",
          "customer_email": "dileep@gmail.com"
        }
      },
      "event_time": "2023-06-15T21:17:14+05:30",
      "type": "DISPUTE_CLOSED"
    }
    ```
  </Tab>
</Tabs>

## Payload field description

| Field | Description | Example | Type |
| - | - | - | - |
| dispute\_id | Cashfree’s unique ID to identify a dispute. | 433475257 | Long |
| dispute\_type | Type of dispute created. Possible values:  <br />- DISPUTE<br />- RETRIEVAL<br />- CHARGEBACK<br />- PRE\_ARBITRATION<br />- ARBITRATION | Chargeback | String |
| reason\_code | Condition for which the customer is filing the case. Click [here]() to know more about dispute reason codes. | 13.6 | String |
| reason\_description | Description of the reason code. Codes for Chargeback cases are specified by Card networks/NPCI. | Credit not processed | String |
| dispute\_amount | The amount for which the dispute has been created. | 4500 | BigDecimal |
| created\_at | Time on which the dispute was registered on Cashfree’s system. | 2023-06-15T21:16:03+05:30 | LocalDateTime |
| updated\_at | Time on which the dispute was updated. | 2023-06-15T21:16:51+05:30 | LocalDateTime |
| respond\_by | Time by which the merchant is expected to respond to the dispute. | 2023-06-18T00:00:00+05:30 | LocalDateTime |
| dispute\_status | Status of Dispute. All possible values are listed in the table below. | CHARGEBACK\_CREATED | String |
| cf\_dispute\_remarks | Any remarks specified by Cashfree on the dispute. | Please submit documents. | String |
| dispute\_update | Specifies what has been updated on the dispute. Possible Values:  <br />- STATUS\_UPDATE<br />- TYPE\_UPDATE<br />- COMMENT\_UPDATE | TYPE\_UPDATE | String |
| dispute\_action\_on | Specifies whether the action is on Cashfree or Merchant at a time. Possible Values:  <br />- MERCHANT<br />- CASHFREE | MERCHANT | String |
| resolved\_at | Time on which the dispute was resolved/closed. | 2023-06-15T21:16:51.682836678+05:30 | LocalDateTime |
| event\_time | Time at which dispute webhook was initiated. | 2023-06-15T21:16:51+05:30 | LocalDateTime |
| type | Type of webhook. Possible Values:  <br />- DISPUTE\_CREATED<br />- DISPUTE\_UPDATED<br />- DISPUTE\_CLOSED | DISPUTE\_CREATED | String |

| List of Dispute Status |
| :- |
| DISPUTE\_CREATED |
| DISPUTE\_DOCS\_RECEIVED |
| DISPUTE\_UNDER\_REVIEW |
| DISPUTE\_MERCHANT\_WON |
| DISPUTE\_MERCHANT\_LOST |
| DISPUTE\_MERCHANT\_ACCEPTED |
| DISPUTE\_INSUFFICIENT\_EVIDENCE |
| RETRIEVAL\_CREATED |
| RETRIEVAL\_DOCS\_RECEIVED |
| RETRIEVAL\_UNDER\_REVIEW |
| RETRIEVAL\_MERCHANT\_WON |
| RETRIEVAL\_MERCHANT\_LOST |
| RETRIEVAL\_MERCHANT\_ACCEPTED |
| RETRIEVAL\_INSUFFICIENT\_EVIDENCE |
| CHARGEBACK\_CREATED |
| CHARGEBACK\_DOCS\_RECEIVED |
| CHARGEBACK\_UNDER\_REVIEW |
| CHARGEBACK\_MERCHANT\_WON |
| CHARGEBACK\_MERCHANT\_LOST |
| CHARGEBACK\_MERCHANT\_ACCEPTED |
| CHARGEBACK\_INSUFFICIENT\_EVIDENCE |
| PRE\_ARBITRATION\_CREATED |
| PRE\_ARBITRATION\_DOCS\_RECEIVED |
| PRE\_ARBITRATION\_UNDER\_REVIEW |
| PRE\_ARBITRATION\_MERCHANT\_WON |
| PRE\_ARBITRATION\_MERCHANT\_LOST |
| PRE\_ARBITRATION\_MERCHANT\_ACCEPTED |
| PRE\_ARBITRATION\_INSUFFICIENT\_EVIDENCE |
| ARBITRATION\_CREATED |
| ARBITRATION\_DOCS\_RECEIVED |
| ARBITRATION\_CONTEST\_REQUESTED |
| ARBITRATION\_UNDER\_REVIEW |
| ARBITRATION\_MERCHANT\_WON |
| ARBITRATION\_MERCHANT\_LOST |
| ARBITRATION\_MERCHANT\_ACCEPTED |
| ARBITRATION\_INSUFFICIENT\_EVIDENCE |

## Compute signature and verify

The signature must be used to verify if the request has not been tampered with. To verify the signature at your end, you will need your Cashfree PG secret key along with the payload. Timestamp is present in the header x-webhook-timestamp

````bash theme={"dark"}
timestamp := 1617695238078;  
signedPayload := $timestamp.$payload;
expectedSignature := Base64Encode(HMACSHA256($signedPayload, $merchantSecretKey));```
````

## Sample code

### Verify Signature using SDK

<CodeGroup>
  ```node Node (express) theme={"dark"}

  var express = require('express')
  import { Cashfree } from "cashfree-pg"; 
  var app = express()

  Cashfree.XClientId = "<x-client-id>";
  Cashfree.XClientSecret = "<x-client-secret>";
  Cashfree.XEnvironment = Cashfree.Environment.SANDBOX;

  app.post('/webhook', function (req, res) {
      try {
          Cashfree.PGVerifyWebhookSignature(req.headers["x-webhook-signature"], req.rawBody, req.headers["x-webhook-timestamp"]))
      } catch (err) {
          console.log(err.message)
      }
  })
  ```

  ```go Go theme={"dark"}
  var express = require('express')
  import { Cashfree } from "cashfree-pg"; 
  var app = express()

  Cashfree.XClientId = "<x-client-id>";
  Cashfree.XClientSecret = "<x-client-secret>";
  Cashfree.XEnvironment = Cashfree.Environment.SANDBOX;

  app.post('/webhook', function (req, res) {
      try {
          Cashfree.PGVerifyWebhookSignature(req.headers["x-webhook-signature"], req.rawBody, req.headers["x-webhook-timestamp"]))
      } catch (err) {
          console.log(err.message)
      }
  })
  ```

  ```php PHP theme={"dark"}

  <?php

  $inputJSON = file_get_contents('php://input');

  $expectedSig = getallheaders()['x-webhook-signature'];
  $ts = getallheaders()['x-webhook-timestamp'];

  if(!isset($expectedSig) || !isset($ts)){
      echo "Bad Request";
      die();
  }

  \Cashfree\Cashfree::$XClientId = "<x-client-id>";
  \Cashfree\Cashfree::$XClientSecret = "<x-client-secret>";
  $cashfree = new \Cashfree\Cashfree();

  try {
   $response =  cashfree->PGVerifyWebhookSignature($expectedSig, $inputJSON, $ts);
  } catch(Exception $e) {
    // Error if signature verification fails
  }
  ?>

  ```

  ```python Python theme={"dark"}
  from cashfree_pg.api_client import Cashfree

  @app.route('/webhook', methods = ['POST'])
  def disp():
  		# Get the raw body from the request
      raw_body = request.data
    
      # Decode the raw body bytes into a string
      decoded_body = raw_body.decode('utf-8')

      #verify_signature
      timestamp = request.headers['x-webhook-timestamp']
      signature = request.headers['x-webhook-signature'
  		
  		cashfree = Cashfree()
  		cashfree.XClientId = "<app_id>"
  		cashfree.XClientSecret = "<secret_key>"
  		try:
  			cashfreeWebhookResponse = cashfree.PGVerifyWebhookSignature(signature, decoded_body, timestamp)
  		except:
  			# If Signature mis-match

  ```

  ```java Java theme={"dark"}
  import com.cashfree.*;

  @PostMapping("/my-endpoint")
  public String handlePost(HttpServletRequest request) throws IOException {      
      Cashfree.XClientId = "<x-client-id>";
  		Cashfree.XClientSecret = "<x-client-secret>";
  		Cashfree.XEnvironment = Cashfree.SANDBOX;
    
    	StringBuilder stringBuilder = new StringBuilder();
      BufferedReader bufferedReader = null;

      try {           
        bufferedReader = request.getReader();
        String line;
        while ((line = bufferedReader.readLine()) != null) {
                stringBuilder.append(line).append('\n');
        }
          
          
        String rawBody = stringBuilder.toString();
        String signature = request.getHeader("x-webhook-signature");
        String timestamp = request.getHeader("x-webhook-timestamp");
          
        Cashfree cashfree = new Cashfree();
        PGWebhookEvent webhook = cashfree.PGVerifyWebhookSignature(signature, rawBody, timestamp);
            
      } catch (Exception e) {
              // Error if verification fails
      } finally {
           if (bufferedReader != null) {
              bufferedReader.close();
  		}
  	}
        
  }
  ```

  ```c C# theme={"dark"}
  using cashfree_pg.Client;
  using cashfree_pg.Model;


  		[Route("api/[controller]")]
      [ApiController]
      public class YourController : ControllerBase
      {
          [HttpPost]
          public async Task<IActionResult> Post()
          {
              // Read the raw body of the POST request
              using (StreamReader reader = new StreamReader(Request.Body, Encoding.UTF8))
              {
                  string requestBody = await reader.ReadToEndAsync();
                  var headers = Request.Headers;
                  var signature = headers["x-webhook-signature"];
                  var timestamp = headers["x-webhook-timestamp"];
                  
                  Cashfree.XClientId = "<x-client-id>";
                  Cashfree.XClientSecret = "<x-client-secret>";
                  Cashfree.XEnvironment = Cashfree.SANDBOX;
  								var cashfree = new Cashfree();
                  
                  try {
                  var response = cashfree.PGVerifyWebhookSignature(signature, requestBody, timestamp);
                  } catch(Exception e) {
                  // Error if signature mis matches
                  }
              }
          }
      }
  ```
</CodeGroup>

### Compute signature and verify manually

<CodeGroup>
  ```node Node (express) theme={"dark"}

  function verify(ts, rawBody){
      const body = req.headers["x-webhook-timestamp"] + req.rawBody;
      const secretKey = "<your secret key>";
      let genSignature = crypto.createHmac('sha256',secretKey).update(body).digest("base64");
      return genSignature
  }
  ```

  ```go Go theme={"dark"}
  func VerifySignature(expectedSig string, ts string, body string) (string, error) {
  	t := time.Now()
  	currentTS := t.Unix()
  	if currentTS-ts > 1000*300 {
  		return "", errors.New("webhook delivered too late")
  	}
  	signStr := strconv.FormatInt(ts, 10) + body
  	fmt.Println("signing String: ", signStr)
  	key := ""
  	h := hmac.New(sha256.New, []byte(key))
  	h.Write([]byte(signStr))
  	b := h.Sum(nil)
  	return base64.StdEncoding.EncodeToString(b), nil
  }

  timestamp := c.Request().Header.Get("x-webhook-timestamp")
  body, _ := ioutil.ReadAll(c.Request().Body)
  rawBody := string(body)
  signature := c.Request().Header.Get("x-webhook-signature")

  VerifySignature(signature, timestamp, rawBody)func VerifySignature(expectedSig string, ts string, body string) (string, error) {
  	t := time.Now()
  	currentTS := t.Unix()
  	if currentTS-ts > 1000*300 {
  		return "", errors.New("webhook delivered too late")
  	}
  	signStr := strconv.FormatInt(ts, 10) + body
  	fmt.Println("signing String: ", signStr)
  	key := ""
  	h := hmac.New(sha256.New, []byte(key))
  	h.Write([]byte(signStr))
  	b := h.Sum(nil)
  	return base64.StdEncoding.EncodeToString(b), nil
  }

  timestamp := c.Request().Header.Get("x-webhook-timestamp")
  body, _ := ioutil.ReadAll(c.Request().Body)
  rawBody := string(body)
  signature := c.Request().Header.Get("x-webhook-signature")

  VerifySignature(signature, timestamp, rawBody)
  ```

  ```php PHP theme={"dark"}

  function computeSignature($ts, $rawBody){
      $rawBody = file_get_contents('php://input');
  		$ts = getallheaders()['x-webhook-timestamp'];
    
      $signStr = $ts . $rawBody;
      $key = "";
      $computeSig = base64_encode(hash_hmac('sha256', $signStr, $key, true));
      return $computeSig;
  }

  ```

  ```java Java theme={"dark"}
  public String generateSignature() {

  	bufferedReader = request.getReader();
    String line;
    while ((line = bufferedReader.readLine()) != null) {
       stringBuilder.append(line).append('\n');
    }      
    String payload = stringBuilder.toString();
    String timestamp = request.getHeader("x-webhook-timestamp");
        
    String data = timestamp+payload;

    String secretKey = "SECRET-KEY"; // Get secret key from Cashfree Merchant Dashboard;
    Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
    SecretKeySpec secret_key_spec = new SecretKeySpec(secretKey.getBytes(),"HmacSHA256");
    sha256_HMAC.init(secret_key_spec);
    String computed_signature = Base64.getEncoder().encodeToString(sha256_HMAC.doFinal(data.getBytes()));
    return computed_signature; // compare with "x-webhook-signature"
  }

  ```

  ```python Python theme={"dark"}
  import base64
  import hashlib
  import hmac

  def generateSignature():    
      # Get the raw body from the request
      raw_body = request.data
    
      # Decode the raw body bytes into a string
      payload = raw_body.decode('utf-8')

      #verify_signature
      timestamp = request.headers['x-webhook-timestamp']
      
      signatureData = timestamp+payload
      message = bytes(signatureData, 'utf-8')
      secretkey=bytes("Secret_Key",'utf-8') #Get Secret_Key from Cashfree Merchant Dashboard.
      signature = base64.b64encode(hmac.new(secretkey, message, digestmod=hashlib.sha256).digest())
      computed_signature = str(signature, encoding='utf8')
      return computed_signature #compare with "x-webhook-signature"

  ```
</CodeGroup>


# Get Disputes by Dispute ID
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/disputes/get-disputes-by-dispute-id

openapi/payments/v2025-01-01.yaml get /disputes/{dispute_id}
Use this API to get Dispute details by specifying the Dispute ID.



# Get Disputes by Order ID
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/disputes/get-disputes-by-order-id

openapi/payments/v2025-01-01.yaml get /orders/{order_id}/disputes
Use this API to get all Dispute details by specifying the Order ID.



# Get Disputes by Payment ID
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/disputes/get-disputes-by-payment-id

openapi/payments/v2025-01-01.yaml get /payments/{cf_payment_id}/disputes
Use this API to get all Dispute details by specifying the Payment ID.



# Submit Evidence to contest the Dispute by Dispute ID
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/disputes/submit-evidence-to-contest-the-dispute-by-dispute-id

openapi/payments/v2025-01-01.yaml post /disputes/{dispute_id}/documents
Use this API to submit evidence to contest a dispute by specifying the dispute ID. This API does not apply to ARBITRATION disputes. Use the [Contest Arbitration API](/docs/api-reference/payments/previous/v2025-01-01/disputes/contest-arbitration-by-dispute-id) instead.

<Note>
  As per NPCI (National Payments Corporation of India) guidelines, document upload is not allowed at the ARBITRATION stage. If the dispute has reached the ARBITRATION stage, use the [Contest Arbitration API](/docs/api-reference/payments/previous/v2025-01-01/disputes/contest-arbitration-by-dispute-id) instead. All evidence submitted during the pre-arbitration stage is automatically carried forward for further processing.
</Note>


# Get Eligible Cardless EMI Payment Methods for a customer on an order
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/eligibility/get-eligible-cardless-emi-payment-methods-for-a-customer-on-an-order

openapi/payments/v2025-01-01.yaml post /eligibility/cardlessemi
Use this API to get eligible Cardless EMI Payment Methods available for a customer on an order basis their phone number.



# Get Eligible Offers for an Order
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/eligibility/get-eligible-offers-for-an-order

openapi/payments/v2025-01-01.yaml post /eligibility/offers
Use this API to get eligible offers for an order_id or order amount.



# Get Eligible Paylater for a customer on an order
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/eligibility/get-eligible-paylater-for-a-customer-on-an-order

openapi/payments/v2025-01-01.yaml post /eligibility/paylater
Use this API to get eligible Paylater Payment Methods for a customer on an order.



# Get eligible Payment Methods
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/eligibility/get-eligible-payment-methods

openapi/payments/v2025-01-01.yaml post /eligibility/payment_methods
Use this API to get eligible Payment Methods.

<a href="https://www.postman.com/cashfreedevelopers/workspace/cashfree-apis-v2025-01-01/request/40140981-8e018a91-9f37-49f8-aa44-d6aa9855c0b5">
  <span aria-label="Postman" />

  Run in Postman: You can also try this API in our Postman Collection.
</a>


# Get Import Settlement Details for an Order
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/international-payments/collect-from-india/get-import-settlement-details

openapi/cb-imports/merchant-spec.json get /import/orders/{order_id}/settlements
This API is used to get ICA settlement details using PG Order ID.



# Get Import Settlement Recon Details
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/international-payments/collect-from-india/get-import-settlement-recon-details

openapi/cb-imports/merchant-spec.json post /import/settlements/recon
This API is used to fetch all events happened for provided Settlement IDs.



# Get Payment Verification Details
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/international-payments/collect-from-india/get-payment-verification-details

get /import/transactions/{cf_payment_id}
Use this API to get the status of the payment verification.



# Webhooks
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/international-payments/collect-from-india/import-webhooks

This product helps Merchants/Payment Aggregators/Market Places who are based outside India to collect payments from customers based out of India

Webhooks are server callbacks to your server from Cashfree. Webhooks are event-based and are sent when specific events related to the transaction happen.

Click [here](/docs/payments/online/webhooks/configure) to know how to configure webhooks.

<Tabs>
  <Tab title="Payment Verification">
    ## Payment Verification details webhook version (2025-01-01)

    The payment verification details update webhook notifies you about the payment details verification, and it give you comprehensive information about verification details update.

    A notification is sent to your backend from cashfree when there is any new update for payment verification. These notification are useful in cases when the internet connection is unstable or slow while the payment is getting processed. This will allow you to reconcile all the payment verification update at your end. Notifications will be sent to **notifyUrl** which is a part of the request parameter specified while creating an order request.

    ### Sample payload

    ```json Json theme={"dark"}
    {
    	"data": {
    	    "order_id": "e145c994-5899-4466-804d-b90c625b2c1b",
    		"cf_payment_id": 5114910634577,
    		"payment_status": "SUCCESS",
    		"payment_verification_status": "ACTION_REQUIRED",
    		"payment_verification_expiry": "2024-07-12T15:19:42+05:30",
    		"remarks": null,
    		"required_details": [
                {
                    "doc_name": "goods_description",
                    "doc_type": "VALUE",
                    "doc_status": "ACTION_REQUIRED",
                    "remarks": null
                },
                {
                    "doc_name": "invoice_number",
                    "doc_type": "VALUE",
                    "doc_status": "IN_REVIEW",
                    "remarks": null
                },
                {
                    "doc_name": "importer_name",
                    "doc_type": "VALUE",
                    "doc_status": "IN_REVIEW",
                    "remarks": null
                },
                {
                    "doc_name": "importer_address",
                    "doc_type": "VALUE",
                    "doc_status": "IN_REVIEW",
                    "remarks": null
                },
                {
                    "doc_name": "country_of_origin",
                    "doc_type": "VALUE",
                    "doc_status": "IN_REVIEW",
                    "remarks": null
                },
                {
                    "doc_name": "invoice_file",
                    "doc_type": "DOCUMENT",
                    "doc_status": "IN_REVIEW",
                    "remarks": null
                },
                {
                    "doc_name": "ecommerce_order_serial_number", //Required for Physical Goods and Digital Goods
                    "doc_type": "VALUE",
                    "doc_status": "ACTION_REQUIRED",
                    "remarks": null
                },
                {
                    "doc_name": "hs_code", //Required for Physical Goods and Digital Goods
                    "doc_type": "VALUE",
                    "doc_status": "IN_REVIEW",
                    "remarks": null
                },
                {
                    "doc_name": "shipment_date", //Required for Physical Goods
                    "doc_type": "VALUE",
                    "doc_status": "ACTION_REQUIRED",
                    "remarks": null
                },
                {
                    "doc_name": "port_of_loading",//Required for Physical Goods
                    "doc_type": "VALUE",
                    "doc_status": "IN_REVIEW",
                    "remarks": null
                },
                    {
                    "doc_name": "awb_number",//Required for Physical Goods
                    "doc_type": "VALUE",
                    "doc_status": "IN_REVIEW",
                    "remarks": null
                }
    		]
    	},
    	"event_time": "2024-07-12T13:39:42+05:30",
    	"type": "PAYMENT_VERIFICATION_UPDATE"
    }
    ```
  </Tab>

  <Tab title="Settlement Details">
    ## ICA Settlement details webhook version 1 (2022-09-01)

    The ICA Settlement Details Update webhook notifies you about the ica settlement.

    A notification is sent to your backend from cashfree when there is any new update for ica settlement. These notification are useful in cases when the internet connection is unstable or slow while the payment is getting processed. This will allow you to reconcile all the ica settlement update at your end. Notifications will be sent to **notifyUrl** which is a part of the request parameter specified while creating an order request.

    ### Sample payload

    <br />

    ```json Json theme={"dark"}
    {
    	"data": {
    		"adjustment_amount_inr": -347641.22,
    		"collection_amount_inr": 604854.0,
    		"initiated_on": null,
    		"payment_from": "2024-09-26T15:43:55",
    		"payment_till": "2024-09-26T16:43:13",
    		"service_charge_inr": null,
    		"service_tax_inr": 2068.59,
    		"settled_on": null,
    		"settlement_amount_inr": 243651.95,
    		"settlement_charges_inr": 0.0,
    		"settlement_foreign_currency_details": {
    			"settlement_amount_fcy": null,
    			"settlement_currency": "USD",
    			"settlement_forex_rate": null
    		},
    		"cf_ica_settlement_id": 12,
    		"settlement_tax_inr": 0.0,
    		"settlement_utr": null,
    		"status": "NOT_INITIATED"
    	},
    	"event_time": "2024-10-03T13:27:36+05:30",
    	"type": "ICA_SETTLEMENT_UPDATE"
    }
    ```
  </Tab>

  <Tab title="Signature Verification">
    ## Signature verification

    The signature must be used to verify if the request has not been tampered with. To verify the signature at your end, you will need your Cashfree PG secret key along with the payload.

    timestamp is present in the header x-webhook-timestamp\
    Actual signature is present in the header x-webhook-signature

    ```
    timestamp := 1617695238078;
    signedPayload := $timestamp.$payload;
    expectedSignature := Base64Encode(HMACSHA256($signedPayload, $merchantSecretKey));
    ```
  </Tab>

  <Tab title="Sample Code">
    ## Sample code

    ### Verify Signature using SDK

    <CodeGroup>
      ```node Node(express) theme={"dark"}
      using cashfree_pg.Client;
      using cashfree_pg.Model;

          	[Route("api/[controller]")]
          [ApiController]
          public class YourController : ControllerBase
          {
              [HttpPost]
              public async Task<IActionResult> Post()
              {
                  // Read the raw body of the POST request
                  using (StreamReader reader = new StreamReader(Request.Body, Encoding.UTF8))
                  {
                      string requestBody = await reader.ReadToEndAsync();
                      var headers = Request.Headers;
                      var signature = headers["x-webhook-signature"];
                      var timestamp = headers["x-webhook-timestamp"];

                      Cashfree.XClientId = "<x-client-id>";
                      Cashfree.XClientSecret = "<x-client-secret>";
                      Cashfree.XEnvironment = Cashfree.SANDBOX;
          							var cashfree = new Cashfree();

                      try {
                      var response = cashfree.PGVerifyWebhookSignature(signature, requestBody, timestamp);
                      } catch(Exception e) {
                      // Error if signature mis matches
                      }
                  }
              }
          }

      ```

      ```go Go theme={"dark"}
      import (
        cashfree "github.com/cashfree/cashfree-pg/v4"
      )

      // Route
      e.POST("/webhook", _this.Webhook)

      // Controller
      func (_this *WebhookRoute) Webhook(c echo.Context) error {
        	clientId := "<x-client-id>"
      		clientSecret := "<x-client-secret>"
      		cashfree.XClientId = &clientId
      		cashfree.XClientSecret = &clientSecret
      		cashfree.XEnvironment = cashfree.SANDBOX

          signature := c.Request().Header.Get("x-webhook-signature")
          timestamp := c.Request().Header.Get("x-webhook-timestamp")

          body, _ := ioutil.ReadAll(c.Request().Body)
          rawBody := string(body)
          webhookEvent, err := cashfree.PGVerifyWebhookSignature(signature, rawBody, timestamp)
          if err != nil {
      		fmt.Println(err.Error())
      	} else {
      		fmt.Println(webhookEvent.Object)
      	}
      }
      ```

      ```php PHP theme={"dark"}
      <?php

      $inputJSON = file_get_contents('php://input');

      $expectedSig = getallheaders()['x-webhook-signature'];
      $ts = getallheaders()['x-webhook-timestamp'];

      if(!isset($expectedSig) || !isset($ts)){
          echo "Bad Request";
          die();
      }

      \Cashfree\Cashfree::$XClientId = "<x-client-id>";
      \Cashfree\Cashfree::$XClientSecret = "<x-client-secret>";
      $cashfree = new \Cashfree\Cashfree();

      try {
       $response =  cashfree->PGVerifyWebhookSignature($expectedSig, $inputJSON, $ts);
      } catch(Exception $e) {
        // Error if signature verification fails
      }
      ?>
      ```

      ```python Python theme={"dark"}
      from cashfree_pg.api_client import Cashfree

      @app.route('/webhook', methods = ['POST'])
      def disp():
      		# Get the raw body from the request
          raw_body = request.data

          # Decode the raw body bytes into a string
          decoded_body = raw_body.decode('utf-8')

          #verify_signature
          timestamp = request.headers['x-webhook-timestamp']
          signature = request.headers['x-webhook-signature'

      		cashfree = Cashfree()
      		cashfree.XClientId = "<app_id>"
      		cashfree.XClientSecret = "<secret_key>"
      		try:
      			cashfreeWebhookResponse = cashfree.PGVerifyWebhookSignature(signature, decoded_body, timestamp)
      		except:
      			# If Signature mis-match
      ```

      ```java Java theme={"dark"}
      import com.cashfree.*;

      @PostMapping("/my-endpoint")
      public String handlePost(HttpServletRequest request) throws IOException {
          Cashfree.XClientId = "<x-client-id>";
      		Cashfree.XClientSecret = "<x-client-secret>";
      		Cashfree.XEnvironment = Cashfree.SANDBOX;

        	StringBuilder stringBuilder = new StringBuilder();
          BufferedReader bufferedReader = null;

          try {
            bufferedReader = request.getReader();
            String line;
            while ((line = bufferedReader.readLine()) != null) {
                    stringBuilder.append(line).append('\n');
            }


            String rawBody = stringBuilder.toString();
            String signature = request.getHeader("x-webhook-signature");
            String timestamp = request.getHeader("x-webhook-timestamp");

            Cashfree cashfree = new Cashfree();
            PGWebhookEvent webhook = cashfree.PGVerifyWebhookSignature(signature, rawBody, timestamp);

          } catch (Exception e) {
                  // Error if verification fails
          } finally {
               if (bufferedReader != null) {
                  bufferedReader.close();
      		}
      	}

      }
      ```

      ```c C# theme={"dark"}
      using cashfree_pg.Client;
      using cashfree_pg.Model;


      		[Route("api/[controller]")]
          [ApiController]
          public class YourController : ControllerBase
          {
              [HttpPost]
              public async Task<IActionResult> Post()
              {
                  // Read the raw body of the POST request
                  using (StreamReader reader = new StreamReader(Request.Body, Encoding.UTF8))
                  {
                      string requestBody = await reader.ReadToEndAsync();
                      var headers = Request.Headers;
                      var signature = headers["x-webhook-signature"];
                      var timestamp = headers["x-webhook-timestamp"];

                      Cashfree.XClientId = "<x-client-id>";
                      Cashfree.XClientSecret = "<x-client-secret>";
                      Cashfree.XEnvironment = Cashfree.SANDBOX;
      								var cashfree = new Cashfree();

                      try {
                      var response = cashfree.PGVerifyWebhookSignature(signature, requestBody, timestamp);
                      } catch(Exception e) {
                      // Error if signature mis matches
                      }
                  }
              }
          }
      ```
    </CodeGroup>

    ### Compute signature and verify manually

    <CodeGroup>
      ```node Node(express) theme={"dark"}
      function verify(ts, rawBody){
          const body = req.headers["x-webhook-timestamp"] + req.rawBody;
          const secretKey = "<your secret key>";
          let genSignature = crypto.createHmac('sha256',secretKey).update(body).digest("base64");
          return genSignature
      }

      ```

      ```go Go theme={"dark"}
      func VerifySignature(expectedSig string, ts string, body string) (string, error) {
      	t := time.Now()
      	currentTS := t.Unix()
      	if currentTS-ts > 1000*300 {
      		return "", errors.New("webhook delivered too late")
      	}
      	signStr := strconv.FormatInt(ts, 10) + body
      	fmt.Println("signing String: ", signStr)
      	key := ""
      	h := hmac.New(sha256.New, []byte(key))
      	h.Write([]byte(signStr))
      	b := h.Sum(nil)
      	return base64.StdEncoding.EncodeToString(b), nil
      }

      timestamp := c.Request().Header.Get("x-webhook-timestamp")
      body, _ := ioutil.ReadAll(c.Request().Body)
      rawBody := string(body)
      signature := c.Request().Header.Get("x-webhook-signature")

      VerifySignature(signature, timestamp, rawBody)
      ```

      ```php PHP theme={"dark"}
      function computeSignature($ts, $rawBody){
          $rawBody = file_get_contents('php://input');
      		$ts = getallheaders()['x-webhook-timestamp'];

          $signStr = $ts . $rawBody;
          $key = "";
          $computeSig = base64_encode(hash_hmac('sha256', $signStr, $key, true));
          return $computeSig;
      }
      ```

      ```java Java theme={"dark"}
      public String generateSignature() {

      	bufferedReader = request.getReader();
        String line;
        while ((line = bufferedReader.readLine()) != null) {
           stringBuilder.append(line).append('\n');
        }
        String payload = stringBuilder.toString();
        String timestamp = request.getHeader("x-webhook-timestamp");

        String data = timestamp+payload;

        String secretKey = "SECRET-KEY"; // Get secret key from Cashfree Merchant Dashboard;
        Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
        SecretKeySpec secret_key_spec = new SecretKeySpec(secretKey.getBytes(),"HmacSHA256");
        sha256_HMAC.init(secret_key_spec);
        String computed_signature = Base64.getEncoder().encodeToString(sha256_HMAC.doFinal(data.getBytes()));
        return computed_signature; // compare with "x-webhook-signature"
      }
      ```

      ```python Python theme={"dark"}
      import base64
      import hashlib
      import hmac

      def generateSignature():
          # Get the raw body from the request
          raw_body = request.data

          # Decode the raw body bytes into a string
          payload = raw_body.decode('utf-8')

          #verify_signature
          timestamp = request.headers['x-webhook-timestamp']

          signatureData = timestamp+payload
          message = bytes(signatureData, 'utf-8')
          secretkey=bytes("Secret_Key",'utf-8') #Get Secret_Key from Cashfree Merchant Dashboard.
          signature = base64.b64encode(hmac.new(secretkey, message, digestmod=hashlib.sha256).digest())
          computed_signature = str(signature, encoding='utf8')
          return computed_signature #compare with "x-webhook-signature"
      ```
    </CodeGroup>
  </Tab>
</Tabs>


# Mark Sandbox Settlement Processed
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/international-payments/collect-from-india/mark-sandbox-settlement-processed

put /import/settlements/emulate
This API is used to mark settlement as processed in sandbox environment.



# Overview
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/international-payments/collect-from-india/overview

This product helps Merchants/Payment Aggregators/Market Places who are based outside India to collect payments from customers based out of India

**Getting Started**

Follow the steps mentioned below to get started with Collect from India APIs

* Fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) for onboarding assistance
* If you are a Merchant, generate your keys using this method [Link](/docs/api-reference/authentication#generate-api-keys)
* Register your webhook URL for updates and subscribe to the required events. For more information, refer to the [Webhook documentation](/docs/api-reference/payments/previous/v2025-01-01/international-payments/collect-from-india/import-webhooks).

Once these setup is completed, we can use the below mentioned collection of APIs to create import transactions

**Collect from India - List of APIs**

| API Name | Description |
| :- | :- |
| [Create Order](/docs/api-reference/payments/previous/v2025-01-01/orders/create) | This API will create a order to collect payment |
| [Order Pay](/docs/api-reference/payments/previous/v2025-01-01/payments/pay) | This API is used to pay the created payment |
| [Get Payment by ID](/docs/api-reference/payments/previous/v2025-01-01/payments/get) | This API is used to view payment details of an order for a payment ID |
| [Upload Payment Verification Details](/docs/api-reference/payments/previous/v2025-01-01/international-payments/collect-from-india/upload-payment-verification-details) | This API is used to upload the required payment verification details |
| [Get Payment Verification Details](/docs/api-reference/payments/previous/v2025-01-01/international-payments/collect-from-india/get-payment-verification-details) | This API is used to Get the verification status of the payment |
| [Get Import Settlement Details for an Order](/docs/api-reference/payments/previous/v2025-01-01/international-payments/collect-from-india/get-import-settlement-details) | This API is used to get ICA settlement details using PG Order ID |
| [Get Import Settlement Recon Details](/docs/api-reference/payments/previous/v2025-01-01/international-payments/collect-from-india/get-import-settlement-recon-details) | This API is used to fetch all events happened for provided Settlement IDs |


# Overview
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/international-payments/collect-from-india/sandbox-simulation

Learn how to simulate transaction verification and settlement processes in the sandbox environment for payments from India-based customers to overseas merchants

## Transaction verification simulation

In the sandbox environment, you can simulate transaction verification using predefined test values that are automatically approved. For file-type content, the system approves PDF files while rejecting other file formats.

You can submit verification details either through the [Upload Payment Verification Details](/docs/api-reference/payments/previous/v2025-01-01/international-payments/collect-from-india/upload-payment-verification-details) or the dashboard.

### Test values for transaction verification

| Field Name | Value |
| - | - |
| importer\_name | John |
| importer\_address | 321 Elm Street, Suite 3, Los Angeles, CA 90401, USA |
| goods\_description | This is a test product for test purpose |
| country\_of\_origin | USA |
| ecommerce\_order\_serial\_number | 123123 |
| invoice\_number | 234234 |
| hs\_code | 3456 |
| shipment\_date | 01/01/2027 |
| port\_of\_loading | Houston |
| importer\_address\_postal\_code | 560034 |

## Settlement simulation

The sandbox environment provides APIs to simulate the settlement process. This includes triggering settlements and updating their status.

### Trigger settlement

Use the [Trigger Settlement API](/docs/api-reference/payments/previous/v2025-01-01/international-payments/collect-from-india/trigger-sandbox-settlement) to initiate a settlement. This is an asynchronous process, with settlement entries typically created within one second.

### Mark settlement as processed

To update a settlement's status to "Processed", use the [Mark Settlement as Processed](/docs/api-reference/payments/previous/v2025-01-01/international-payments/collect-from-india/mark-sandbox-settlement-processed).

<Note>
  The settlement forex rate shown is notional and may differ from actual foreign exchange rates.
</Note>

#### Simulating skipped settlements

A settlement will be skipped if the settlement amount is between 0 and 1 INR, or if it is negative, the amount will be adjusted in the next settlement.

Example of how to simulate a skipped settlement:

1. Create a transaction
2. Refund the transaction
3. Trigger settlement using the API
   The settlement will be skipped since the total collection amount will be less than 0.


# Trigger Sandbox Settlement
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/international-payments/collect-from-india/trigger-sandbox-settlement

post /import/settlements/emulate
This API is used to trigger settlement in sandbox environment.



# Upload Payment Verification Details
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/international-payments/collect-from-india/upload-payment-verification-details

openapi/cb-imports/v2025-01-01.yaml post /import/transactions/{cf_payment_id}
This API is used to upload all the required payment details for the verification



# End Points
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/international-payments/global-collections/endpoints

This document provides you with the Global Collection end points.

## Global collections gateway end points

| Environment | Base URL |
| :- | :- |
| Test | [https://sandbox.cashfree.com/](https://sandbox.cashfree.com/) |
| Production | [https://api.cashfree.com/](https://api.cashfree.com/) |


# Overview
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/international-payments/global-collections/overview

Generate API credentials for Cashfree Global Collections (v2025-01-01) as a partner or merchant, with test and production key setup steps.

To start using Global Collection APIs, generate your API credentials by following these steps:

1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
2. Go to **Developers**.
3. Click **API Keys** under the respective product card.
4. Select **Generate API Keys** and click **Download**.

In the test environment, keys are auto-generated. In production, click **Generate API Keys** and complete two-factor authentication.
View keys by clicking the icon and selecting **View API Key**.

<Tabs>
  <Tab title="Partner">
    <img />

    <img />
  </Tab>

  <Tab title="Merchant">
    <img />
  </Tab>
</Tabs>

***

Based on who you are, consider the below values in the API requests

<Note>
  | Cashfree Merchant | Cashfree Partner |
  | :- | :- |
  | x-client-id | x-partner-api-key |
  | x-client-secret | x-partner-merchantid |
</Note>

**Global Collections List of APIs**

| API Name | Description |
| :- | :- |
| [Get Token](/docs/api-reference/payments/previous/v2025-01-01/international-payments/global-collections/partner/auth-get-token) | This API generates a new token. |
| [Verify Token](/docs/api-reference/payments/previous/v2025-01-01/international-payments/global-collections/partner/auth-verify-token) | Verify the authentication token generated. The response will be ‘Token is not valid’ if the token does not exist, invalid or has been expired. |
| [Get Collection Accounts](/docs/api-reference/payments/previous/v2025-01-01/international-payments/global-collections/partner/get-collection-accounts) | This API fetches all the virtual accounts that are linked with this account. |
| [Get Transactions](/docs/api-reference/payments/previous/v2025-01-01/international-payments/global-collections/partner/get-transactions) | Use this API to get all the transaction details within a time interval. |
| [Add Transaction Details](/docs/api-reference/payments/previous/v2025-01-01/international-payments/global-collections/partner/add-transaction-details) | Use this API to add transaction details to upload multiple invoices until the cumulative total of all invoice amounts matches the transaction amount. |
| [Simulate Transaction](/docs/api-reference/payments/previous/v2025-01-01/international-payments/global-collections/partner/simulate-transaction) | Use this API to simulate funding to any of the virtual accounts of your merchants. |


# Add Transaction Details
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/international-payments/global-collections/partner/add-transaction-details

post /gc/transactions/{referenceId}/invoice-details
Use this API to input invoice details for a specific transaction. You have the flexibility to upload multiple invoices until the cumulative total of all invoice amounts matches the transaction amount.

Based on who you are, consider the below values in the API requests

<Note>
  | Cashfree Merchant | Cashfree Partner |
  | :- | :- |
  | x-client-id | x-partner-api-key |
  | x-client-secret | x-partner-merchantid |
</Note>


# Get Auth Token
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/international-payments/global-collections/partner/auth-get-token

post /gc/authorize
Use this API to authenticate with the Cashfree system and obtain the authorization bearer token.

Based on who you are, consider the below values in the API requests

<Note>
  | Cashfree Merchant | Cashfree Partner |
  | :- | :- |
  | x-client-id | x-partner-api-key |
  | x-client-secret | x-partner-merchantid |
</Note>


# Overview
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/international-payments/global-collections/partner/auth-overview

Global Collection APIs

* [Get Token](/docs/api-reference/payments/previous/v2023-08-01/international-payments/global-collections/partner/auth-get-token) - Use the Get Token API to authenticate with the Cashfree system and obtain the authorization bearer token, call the authorize API.
* [Verify Token](/docs/api-reference/payments/previous/v2023-08-01/international-payments/global-collections/partner/auth-verify-token) - Verify the authentication token generated. The response will be ‘Token is not valid’ if the token does not exist, invalid or has been expired.


# Verify Auth Token
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/international-payments/global-collections/partner/auth-verify-token

get /gc/token/verify
Verify the authentication token generated by the user.



# Get Collection Accounts
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/international-payments/global-collections/partner/get-collection-accounts

get /gc/virtual-accounts
This API fetches all the virtual accounts that is linked with the given merchant ID.

Based on who you are, consider the below values in the API requests

<Note>
  | Cashfree Merchant | Cashfree Partner |
  | :- | :- |
  | x-client-id | x-partner-api-key |
  | x-client-secret | x-partner-merchantid |
</Note>


# Get Transactions
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/international-payments/global-collections/partner/get-transactions

get /gc/transactions
Use this API to get all the transaction details within a time interval.

Based on who you are, consider the below values in the API requests

<Note>
  | Cashfree Merchant | Cashfree Partner |
  | :- | :- |
  | x-client-id | x-partner-api-key |
  | x-client-secret | x-partner-merchantid |
</Note>


# Overview
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/international-payments/global-collections/partner/overview

Global Collection APIs for partners

* [Get All Transactions Details](/docs/api-reference/payments/previous/v2025-01-01/international-payments/global-collections/partner/get-transactions) - Use this to fetch all the transactions for a particular merchant.
* [Emulate Funding](/docs/api-reference/payments/previous/v2025-01-01/international-payments/global-collections/partner/simulate-transaction) - Use this to emulate a transaction for a specific merchant.
* [Get All Collection Accounts for Partner Merchants](/docs/api-reference/payments/previous/v2025-01-01/international-payments/global-collections/partner/get-collection-accounts) - Use this to get all VAs for a specific merchant.
* [Add Invoice Details for Partner Merchants](/docs/api-reference/payments/previous/v2025-01-01/international-payments/global-collections/partner/add-transaction-details) - Use this API to input invoice details for a specific transaction for a specific merchant.
* [Merchant Webhook Configs](/docs/api-reference/payments/previous/v2025-01-01/international-payments/global-collections/partner/webhooks) - Use this document to understand the webhooks payload events and verification.


# Simulate Transaction
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/international-payments/global-collections/partner/simulate-transaction

post /gc/transactions/emulate
Use this API to simulate a funding in test environment.

Based on who you are, consider the below values in the API requests

<Note>
  | Cashfree Merchant | Cashfree Partner |
  | :- | :- |
  | x-client-id | x-partner-api-key |
  | x-client-secret | x-partner-merchantid |
</Note>


# Webhook - Partner
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/international-payments/global-collections/partner/webhooks

This chapter explains the Global Collections Webhooks.

### Guide to subscribe webhook events

1. Visit [https://partner.cashfree.com](https://partner.cashfree.com) login with your partner credentials
2. On the landing page click on developers section and select webhook, you will be redirected to a page to add webhook URL and subscribe events or once logged in you can use this URL [Webhook Page](https://partner.cashfree.com/partner-ui/dashboard/developers/webhook)
3. Add your webhook URL and subscribe events Global Collect Transaction, Global Collect Settlement & Global Collect Virtual Account
4. To validate the webhook signature follow [Adding webhook and signature verification guide](/docs/api-reference/platforms/latest/merchant-onboarding/webhooks#verify-signature)

### Screenshots:

<Frame>
  <img />
</Frame>

Landing page to add the webhook URL and subscribe the events

<Frame>
  <img />
</Frame>

<Note>
  We can add multiple webhook URLs for the different type of events. For testing, Switch to test and follow the same step in sandbox environment.
</Note>

## Transaction status

Active Event needs to be subscribed: **Global Collect Transaction**

```json Json theme={"dark"}
{
	"amount": "4.50",
	"currency": "GBP",
	"cmsProfileId": 123,
	"event": "INTERNATIONAL_PAYMENT_COLLECTED",
	"merchant": {
		"merchant_id": "CF_7644f46b-ad82-472c-8d97-609d1a429eac"
	},
	"paymentTime": "2022-12-29 13:42:54",
	"referenceId": 63,
	"remarks": "",
	"remitterAccount": "1223456789",
	"remitterAddress": "Dummy Address",
	"remitterBic": "TRWIBEB1XXX",
	"remitterCountry": "GB",
	"remitterName": "Dummy Sender",
	"remitterRoutingCode": "TLG0123",
	"status": "COMPLETED",
	"utr": "5347f52a-9851-4fe9-8618-32eb085590ce",
	"updatedStatusTime": "2022-12-29 13:50:35",
	"vAccountId": "97836",
	"vAccountNumber": "GB38TCCL12345687997836"
}
```

### Possible events and corresponding transaction status mapping

| Event Name | Payment Status | Description |
| :- | :- | :- |
| INTERNATIONAL\_PAYMENT\_COLLECTED | COMPLETED | Received payment |
| INTERNATIONAL\_PAYMENT\_BLOCKED | BLOCKED | The transaction has been blocked due to the specified reason in the designated field. |
| INTERNATIONAL\_PAYMENT\_AWAITING\_DETAILS | COMPLETED | Waiting for the details of the transaction |

### Payload field description

| Field | Description | Example |
| :- | :- | :- |
| amount | The foreign currency amount sent | 4.50 |
| currency | Three character ISO code. View list of supported currencies [here](/docs/payments/global-collections/collection-accounts#supported-currencies). | GBP |
| cmsProfileId | Merchant identifier | 123 |
| event | Webhook event | INTERNATIONAL\_AMOUNT\_COLLECTED |
| paymentTime | The time at which the payment was initiated. | 2022-12-29 13:42:54 |
| referenceId | Cashfree transaction identifier | 63 |
| remarks | Remarks passed by the sender. | Sample Remark |
| reason | Reason regarding the transaction being blocked. | Transaction value below the allowed limit |
| remitterAccount | The bank account number of the person who sends the money. | 1223456789 |
| remitterAddress | The address of the person who sends the money. | Dummy Address |
| remitterBic | Bank identifier code for the remitter. | TRWIBEB1XXX |
| remitterCountry | The country from which the money is sent. | GB |
| remitterName | The name of the remitter who is sending the money. | John Doe |
| remitterRoutingCode | The routing code of the remitter's bank. | TLG0123 |
| status | Status of FCY (foreign currency leg) of transaction. | COMPLETED, FAILED, AWAITING\_DETAILS |
| updatedStatusTime | The time of the last status update. | 2022-12-29 13:50:35 |
| vAccountId | Identifier of the virtual account. | 97836 |
| vAccountNumber | Account number to which the payment was done. | GB38TCCL12345687997836 |
| merchant | Object contains merchant\_id used while creating merchant | CF\_7644f46b-ad82-472c-8d97-609d1a429eac |

## Reversal status

```Text JSON theme={"dark"}
{
  "amount": "1000000.00",
  "cmsProfileId": 123,
  "currency": "USD",
  "event": "INTERNATIONAL_PAYMENT_REVERSAL_INITIATED",
  "merchant": {
    "merchant_id": "CF_7644f46b-ad82-472c-8d97-609d1a429eac"
  },
  "paymentTime": "2024-02-28 16:17:48",
  "referenceId": 63,
  "remitterAccount": "9919391193",
  "remitterAddress": "Dummy Address",
  "remarks": "",
  "remitterBic": "",
  "remitterCountry": "IN",
  "remitterName": "Dummy Sender",
  "remitterRoutingCode": "TLG0123",
  "reversal": {
    "reason": "Transaction value higher than the compliant limit",
    "status": "INITIATED"
  },
  "signature": "F8raBNGcGjMUvbh2t/7t/9C4zU0Snqa/iXf9XzvOq0Y=",
  "status": "REVERSAL_INITIATED",
  "updatedStatusTime": "2024-02-28 16:17:54",
  "utr": "IF-20240228-KT9ZFA",
  "vAccountId": "GB75T",
  "vAccountNumber": "GB75TCCL12345654108280"
}

```

### Possible events and corresponding transaction status mapping

| Event Name | Reversal Status | Transaction Status | Description |
| :- | :- | :- | :- |
| INTERNATIONAL\_PAYMENT\_REVERSAL\_INITIATED | INITIATED | REVERSAL\_INITIATED | Reversal for the transaction is initiated. |
| INTERNATIONAL\_PAYMENT\_REVERSAL\_DONE | DONE | REVERSAL\_DONE | Reversal for the transaction is completed. The funds have been successfully returned to the sender. |

### Payload field description

***

## Settlement status

Active Event needs to be subscribed: **Global Collect Settlement**

```json theme={"dark"}
{
	"amount": "3500.00",
	"cmsProfileId": 23853384,
	"currency": "USD",
	"event": "INR_SETTLEMENT_INITIATED",
	"merchant": {
		"merchant_id": "CF_7644f46b-ad82-472c-8d97-609d1a429eac"
	},
	"paymentRail": "ACH",
	"paymentTime": "2024-02-06 11:11:42",
	"referenceId": 312620,
	"remarks": "EMULATE GC INCOMING FUNDS",
	"remitterAccount": "7337377781",
	"remitterAddress": "Dummy Address",
	"remitterBic": "TLG0123",
	"remitterCountry": "GB",
	"remitterName": "Dummy Sender",
	"remitterRoutingCode": "TLG0123",
	"settlement": {
		"expectedSettlementDate": "2024-02-06",
		"fxRate": 85.12,
		"id": "f16581f5-344c-40e8-be4b-e63cb5714a88",
		"inrAmount": 16219.65,
		"netPartnerCommission": 2106.72,
		"settlementCharge": 4213.44,
		"settlementChargeTax": 758.42,
		"status": "INITIATED"
	},
	"status": "READY_FOR_SETTLEMENT",
	"updatedStatusTime": "2024-02-05 18:39:42",
	"utr": "f185d0f5-abf5-492b-9149-d45eacfeaca7",
	"vAccountId": "03314",
	"vAccountNumber": "0331496070"
}
```

<Note>
  The firaFileDownloadUrl field will only be included in the webhook response
  after it has been updated.
</Note>

### Possible events and corresponding settlement status mapping

| Event Name | Settlement Status | Description |
| :- | :- | :- |
| INR\_SETTLEMENT\_INITIATED | INITIATED | The settlement is initiated. |
| INR\_SETTLEMENT\_APPROVED | SETTLED | The settlement is settled. |
| INR\_SETTLEMENT\_REJECTED | REJECTED | The settlement is rejected. |
| FIRA\_FILE\_RECEIVED | SETTLED | FIRA file received for the settlement. |

### Payload field description

| Field | Description | Example |
| :- | :- | :- |
| amount | The foreign currency amount sent | 4.50 |
| currency | Three character ISO code. View list of supported currencies [here](doc:global-collections-collection-accounts#supported-currencies). | GBP |
| cmsProfileId | Merchant identifier | 123 |
| event | Webhook event | INTERNATIONAL\_AMOUNT\_COLLECTED |
| merchant | Object contains the merchant\_id to map the merchant created. | CF\_7644f46b-ad82-472c-8d97-609d1a429eac |
| paymentTime | The time at which the payment was initiated. | 2022-12-29 13:42:54 |
| referenceId | Cashfree transaction identifier | 63 |
| remarks | Remarks passed by the sender. | Sample Remark |
| remitterAccount | The bank account number of the person who sends the money. | 1223456789 |
| remitterAddress | The address of the person who sends the money. | Dummy Address |
| remitterBic | Bank identifier code for the remitter. | TRWIBEB1XXX |
| remitterCountry | The country from which the money is sent. | GB |
| remitterName | The name of the remitter who is sending the money. | John Doe |
| remitterRoutingCode | The routing code of the remitter's bank. | TLG0123 |
| status | Status of FCY (foreign currency leg) of transaction. | COMPLETED, FAILED |
| updatedStatusTime | The time of the last status update. | 2022-12-29 13:50:35 |
| vAccountId | Identifier of the virtual account. | 97836 |
| vAccountNumber | Account number to which the payment was made. | GB38TCCL12345687997836 |
| paymentRail | Payment Network used to make the payment | ACH,EFT,FPS,SEPA,SWIFT,FEDWIRE |
| settlement.id | Unique reference ID for the settlement since the payment can have multiple settlements. | b84a7c4c-2ce0-48ca-9b86-2a2c9ad5a35d |
| settlement.fxRate | The foreign exchange rate used for currency conversion between the transaction currency and settlement currency | 85.12 |
| settlement.netPartnerCommission | The final commission amount payable to the partner after deducting all applicable fees and charge | 2106.72 |
| settlement.settlementCharge | Service fees charged for facilitating the settlement | 4213.44 |
| settlement.settlementChargeTax | Applicable tax amount levied on the settlement service charges | 758.42 |
| settlement.inrAmount | Settlement amount in rupees (INR). | 16219.65 |
| settlement.firafileDownloadUrl | Download link to FIRA file | fileDownloadUrl |
| settlement.status | Current status of the settlement. | INITIATED |

## Virtual account details

Active Event needs to be subscribed: **Global Collect Virtual Account**

```json Json theme={"dark"}
{
	"cmsProfileId": 260559,
	"event": "VIRTUAL_ACCOUNT_DETAILS",
	"merchant": {
		"merchant_id": "CF_7644f46b-ad82-472c-8d97-609d1a429eac"
	},
	"vAccounts": [
		{
			"accountName": "John Doe",
			"accountNumber": "GB11TCCL12345638242754",
			"accountType": "iban",
			"paymentType": "priority",
			"bankName": "The Currency Cloud Limited",
			"bankAddress": "12 Steward Street, The Steward Building, London, E1 6FQ, GB",
			"bankCountry": "GB",
			"currency": "AUD",
			"routingCode": "TCCLGB3L",
			"routingCodeType": "bic_swift",
			"addedOn": "2023-03-28 14:43:30",
			"vaccountId": "GB11T"
		},
		{
			"accountName": "John Doe",
			"accountNumber": "GB11TCCL12345638242754",
			"accountType": "iban",
			"paymentType": "priority",
			"bankName": "The Currency Cloud Limited",
			"bankAddress": "12 Steward Street, The Steward Building, London, E1 6FQ, GB",
			"bankCountry": "GB",
			"currency": "BHD",
			"routingCode": "TCCLGB3L",
			"routingCodeType": "bic_swift",
			"addedOn": "2023-03-28 14:43:30",
			"vaccountId": "GB11T"
		}
	]
}
```

### Possible events and corresponding virtual account mapping

| Event Name | Virtual Account Status | Description |
| - | - | - |
| VIRTUAL\_ACCOUNTS\_ACTIVATED | ACTIVE | Virtual account is activated |
| VIRTUAL\_ACCOUNTS\_CREATED | INACTIVE / ACTIVE | If all the business required details are passed in the first go, VAs are created in ACTIVE state or INACTIVE |
| VIRTUAL\_ACCOUNT\_DETAILS | ACTIVE | Will contain all the details of the VA |

#### Description

Sometimes there is mere might be a slight delay in creating some virtual accounts during onboarding and as a result, some of them might be missing in the Get All Collection Accounts API. Hence, when these missing account details are added, this webhook is triggered with all virtual account details (including the ones that were present before). This webhook contains information for all virtual account associated with a merchant along with cmsProfileId , signature and event.

### Payload field description

| Field | Description | Example |
| :- | :- | :- |
| cmsProfileId | Merchant identifier | 123 |
| event | Webhook Event | VIRTUAL\_ACCOUNT\_DETAILS |
| merchant | Object contains the merchant\_id to map the merchant created. | CF\_7644f46b-ad82-472c-8d97-609d1a429eac |
| vAccounts.accountName | Account Name | John Doe |
| vAccounts.accountNumber | Account Number | GB11TCCL12345638242754 |
| vAccounts.accountType | Account Type | iban |
| vAccounts.paymentType | Type of Payment | priority |
| vAccounts.bankName | Bank Name | The Currency Cloud Limited |
| vAccounts.bankAddress | Bank Address | 12 Steward Street, The Steward Building, London, E1 6FQ, GB |
| vAccounts.bankCountry | Bank Country | GB |
| vAccounts.currency | Currency Code | BHD |
| vAccounts.routingCode | Routing Code | TCCLGB3L |
| vAccounts.routingCodeType | Routing Code Type | bic\_swift |
| vAccounts.addedOn | The time when this virtual account was created | 2023-03-28 14:43:30 |
| vAccounts.vaccountId | Virtual Account Id | GB11T |


# Purpose Codes
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/international-payments/global-collections/purpose-codes

This page contains the purpose codes for Global Collect

| Purpose Code | Description |
| - | - |
| P0103 | Advance receipts against export contracts, which will be covered later by GR/PP/SOFTEX/ SDF - other than Nepal and Bhutan |
| P1004 | Legal services |
| P1005 | Accounting, auditing, bookkeeping services |
| P1006 | Business and management consultancy and public relations |
| P1007 | Advertising, trade fair service |
| P1008 | Research & Development services |
| P1009 | Architectural services |
| P0802 | Software consultancy / implementation (other than those covered in SOFTEX form) |
| P0807 | For Export of Software covered under softex (advance payment) |
| P1020 | Wholesale and retailing trade services |
| P1002 | Trade related services - commission on exports / imports |
| P1104 | Entertainment services |
| P1099 | Other services not included elsewhere, for export of services |
| P1015 | Tax consulting services |
| P1016 | Market research and public opinion polling service |
| P1017 | Publishing and printing services |
| P1019 | Commission agent services |
| P1107 | Educational services |
| P1109 | Other Personal, Cultural & Recreational services |
| P1701 | Receipts on account of processing of goods |
| P0301 | Purchases towards travel (Includes purchases of foreign TCs, currency notes etc over the counter, by hotels, Emporiums, institutions etc. as well as amount received by TT/SWIFT transfers or debit to Non-Resident account). |
| P0302 | Business travel |
| P0304 | Travel for medical treatment including TC purchased by hospitals |
| P0305 | Travel for education including TCs purchased by educational institutions |
| P0306 | Other travel receipts |
| P0801 | Hardware consultancy/implementation |
| P0803 | Data base, data processing charges |
| P0804 | Repair and maintenance of computer and software |
| P0805 | News agency services |
| P0806 | Other information services- Subscription to newspapers, periodicals, etc. |
| P0808 | Telecommunication services including electronic mail services and voice mail services |
| P1013 | Environmental Services |
| P1014 | Engineering Services |
| P1101 | Audio-visual & related service:Motion picture & video tape production, distribution & projection service |
| P1103 | Radio & TV production,distribution & transmission service |
| P1105 | Museums, library and archival services |
| P1106 | Recreation and sporting activity services |
| P1108 | Health Service provided by Indian hospitals,doctors,nurses,paramedical remotely/on-site) |


# Overview
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/international-payments/overview

Learn about Cashfree APIs suitable for International Payments

You can use the Cashfree API in test mode, which doesn't affect your live data or interact with the banking networks. The API key you use to authenticate the request determines whether the request is live mode or test mode.

<CardGroup>
  <Card title="Collect from India" href="/docs/api-reference/payments/previous/v2025-01-01/international-payments/collect-from-india/overview">
    For overseas businesses to collect payments from Indian customers
  </Card>

  <Card title="Collect from the World" href="/docs/api-reference/payments/previous/v2025-01-01/international-payments/global-collections/overview">
    For Indian businesses to collect payments from customers worldwide
  </Card>
</CardGroup>


# Create Offer
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/offers/create

openapi/payments/v2025-01-01.yaml post /offers
Use this API to create offers with Cashfree from your backend.

<a href="https://www.postman.com/cashfreedevelopers/workspace/cashfree-apis-v2025-01-01/request/40140981-30b65b93-8e39-4151-afa3-82c9ea20f825">
  <span aria-label="Postman" />

  Run in Postman: You can also try this API in our Postman Collection.
</a>


# Get Offer by ID
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/offers/get

openapi/payments/v2025-01-01.yaml get /offers/{offer_id}
Use this API to get offer by offer_id.

<a href="https://www.postman.com/cashfreedevelopers/workspace/cashfree-apis-v2025-01-01/request/40140981-2d3cf8df-5419-4538-a3a4-77f83bc04b63">
  <span aria-label="Postman" />

  Run in Postman: You can also try this API in our Postman Collection.
</a>


# Create Order
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/orders/create

openapi/payments/v2025-01-01.yaml post /orders


An order is an entity which has a amount and currency associated with it. It is something for which you want to collect payment for.
Use this API to create orders with Cashfree from your backend to get a `payment_sessions_id`. 
You can use the `payment_sessions_id` to create a transaction for the order.


<a href="https://www.postman.com/cashfreedevelopers/workspace/cashfree-apis-v2025-01-01/request/40140981-853f8d3b-ad14-4481-a429-5d0972b8bea0">
  <span aria-label="Postman" />

  Run in Postman: You can also try this API in our Postman Collection.
</a>


# Get Order
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/orders/get

openapi/payments/v2025-01-01.yaml get /orders/{order_id}
Use this API to fetch the order that was created at Cashfree's using the `order_id`. 
## When to use this API
- To check the status of your order


<a href="https://www.postman.com/cashfreedevelopers/workspace/cashfree-apis-v2025-01-01/request/40140981-7717c469-8960-451c-aa16-0bdbdb4c3a88">
  <span aria-label="Postman" />

  Run in Postman: You can also try this API in our Postman Collection.
</a>

<Note>This API allows you to retrieve order data for the current and previous financial years. To access data older than this period, log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login)</Note>


# Get Order Extended
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/orders/get-order-extended

openapi/payments/v2025-01-01.yaml get /orders/{order_id}/extended
Use this API to fetch the order related data like address,cart,offers,customer details etc using the Cashfree's `order_id`.
## When to use this API
- To get the extended data associated with order.


<a href="https://www.postman.com/cashfreedevelopers/workspace/cashfree-apis-v2025-01-01/request/40140981-30a37636-529a-4056-82dd-ee8d34639885">
  <span aria-label="Postman" />

  Run in Postman: You can also try this API in our Postman Collection.
</a>

<Note>This API allows you to retrieve order data for the current and previous financial years. To access data older than this period, log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login)</Note>


# Terminate Order
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/orders/terminate

openapi/payments/v2025-01-01.yaml patch /orders/{order_id}
Use this API to terminate the order that was created at Cashfree's using the `order_id`.

<a href="https://www.postman.com/cashfreedevelopers/workspace/cashfree-apis-v2025-01-01/request/40140981-dc459872-0a42-4931-b11d-8601976cfb3d">
  <span aria-label="Postman" />

  Run in Postman: You can also try this API in our Postman Collection.
</a>


# Update Order Extended
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/orders/update-order-extended

openapi/payments/v2025-01-01.yaml put /orders/{order_id}/extended
Use this api to update the order related data like shipment details,order delivery status etc.
## When to use this API
- To provide/update the shipment details or order delivery status.
- Once the order is PAID.


<a href="https://www.postman.com/cashfreedevelopers/workspace/cashfree-apis-v2025-01-01/request/40140981-c8ecbfba-de79-43bc-b347-d5854e1a0b43">
  <span aria-label="Postman" />

  Run in Postman: You can also try this API in our Postman Collection.
</a>


# Overview
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/overview

Learn details about the 2025-01-01 version of our Payment APIs.

<Note>
  Use the latest version of our APIs [v2026-01-01](/docs/api-reference/payments/latest/overview) for any new integrations.
</Note>

## Payment Gateway end points

| Environment | Base URL |
| :- | :- |
| Test | [https://sandbox.cashfree.com/pg](https://sandbox.cashfree.com/pg) |
| Production | [https://api.cashfree.com/pg](https://api.cashfree.com/pg) |
| Latest version | v5, 2025-01-01  <br />The previous versions were 2023-08-01, 2021-05-21, 2022-01-01, and 2022-09-01 |

## Authentication

All the APIs require authentication, except the /orders/sessions API, which does not require any authentication and can be safely done from the browser as well.

Click [here](/docs/api-reference/authentication) for detailed information on API Authentication for Merchants and Partners.

## Payment Gateway APIs

### Orders

| API | Description |
| :- | :- |
| [Create Order](/docs/api-reference/payments/previous/v2025-01-01/orders/create) | Use this API to create orders with Cashfree from your backend and get the payment link. |
| [Order Pay](/docs/api-reference/payments/previous/v2025-01-01/payments/pay) | Use this API when you have already created the orders and want Cashfree to process the payment. |
| [Preauthorization](/docs/api-reference/payments/previous/v2025-01-01/payments/authorize) | Use this API to capture or void a preauthorized payment. |
| [Get Order](/docs/api-reference/payments/previous/v2025-01-01/orders/get) | Use this API to view all details of an order. |

### Authentication

| API | Description |
| :- | :- |
| [Submit or Resend OTP](/docs/api-reference/payments/previous/v2025-01-01/payments/authenticate) | Use the submit or resend OTP API to send OTP to Cashfree. |

### Payments

| API | Description |
| :- | :- |
| [Get Payments for an Order](/docs/api-reference/payments/previous/v2025-01-01/payments/get-payments-for-order) | Use this API to view all payment details for an order. |
| [Get Payment by ID](/docs/api-reference/payments/previous/v2025-01-01/payments/get) | Use this API to view payment details of an order for a payment ID. |

### Settlements

| API | Description |
| :- | :- |
| [Get Settlements by Order ID](/docs/api-reference/payments/previous/v2025-01-01/settlements/get-settlements-for-order) | Use this API to view all the settlements of a particular order. |
| [Get All Settlements](/docs/api-reference/payments/previous/v2025-01-01/settlements/get-settlements) | Use this API to get all settlement details by specifying the settlement ID, settlement UTR or date range. |

### Payment links

| API | Description |
| :- | :- |
| [Create Payment Link](/docs/api-reference/payments/previous/v2025-01-01/payment-links/create) | Use this API to create a new payment link. The created payment link url will be available in the API response parameter link\_url. |
| [Fetch Payment Link Details](/docs/api-reference/payments/previous/v2025-01-01/payment-links/get) | Use this API to view all details and status of a payment link. |
| [Get Orders for a Payment Link](/docs/api-reference/payments/previous/v2025-01-01/payment-links/get-orders-for-link) | Use this API to view all order details for a payment link. |
| [Cancel Payment Link](/docs/api-reference/payments/previous/v2025-01-01/payment-links/cancel) | Use this API to cancel a payment link. No further payments can be done against a cancelled link. Only a link in ACTIVE status can be cancelled. |

### Token vault

| API | Description |
| :- | :- |
| [Fetch All Saved Instruments](/docs/api-reference/payments/previous/v2025-01-01/token-vault/get-all) | Use this API to get all saved instruments for a customer ID. |
| [Fetch Single Saved Instrument](/docs/api-reference/payments/previous/v2025-01-01/token-vault/get) | Use this API to get specific saved instrument for a customer id and instrument ID. |
| [Delete Saved Instrument](/docs/api-reference/payments/previous/v2025-01-01/token-vault/delete) | Use this API to delete a saved instrument for a customer id and instrument ID. |
| [Fetch Cryptogram for Saved Instrument](/docs/api-reference/payments/previous/v2025-01-01/token-vault/generate-cryptogram) | Use this API to get the card network token, token expiry and cryptogram for a saved instrument using instrument ID. |

### Reconciliation

| API | Description |
| :- | :- |
| [Settlement Reconciliation](/docs/api-reference/payments/previous/v2025-01-01/settlements/settlement-reconciliation) | Use this API to get settlement reconciliation details using Settlement ID, settlement UTR or date range. |
| [PG Reconciliation](/docs/api-reference/payments/previous/v2025-01-01/settlements/reconcile) | Use this API to get the payment gateway reconciliation details with date range. |


# Cancel Payment Link
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/payment-links/cancel

openapi/payments/v2025-01-01.yaml post /links/{link_id}/cancel
Use this API to cancel a payment link. No further payments can be done against a cancelled link. Only a link in ACTIVE status can be cancelled.

<a href="https://www.postman.com/cashfreedevelopers/workspace/cashfree-apis-v2025-01-01/request/40140981-c7863c38-d6bf-4359-8692-f484bc572155">
  <span aria-label="Postman" />

  Run in Postman: You can also try this API in our Postman Collection.
</a>


# Create Payment Link
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/payment-links/create

openapi/payments/v2025-01-01.yaml post /links
Use this API to create a new payment link. The created payment link url will be available in the API response parameter link_url.

<a href="https://www.postman.com/cashfreedevelopers/workspace/cashfree-apis-v2025-01-01/request/40140981-2c1f86cf-4340-4012-afdb-64daa850af6b">
  <span aria-label="Postman" />

  Run in Postman: You can also try this API in our Postman Collection.
</a>

<Note>
  SMS notifications are sent only in the production environment. In the sandbox environment, only email notifications are sent if enabled.
</Note>


# Fetch Payment Link Details
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/payment-links/get

openapi/payments/v2025-01-01.yaml get /links/{link_id}
Use this API to view all details and status of a payment link.

<a href="https://www.postman.com/cashfreedevelopers/workspace/cashfree-apis-v2025-01-01/request/40140981-a446ca95-caa8-4bf6-8943-291054412615">
  <span aria-label="Postman" />

  Run in Postman: You can also try this API in our Postman Collection.
</a>


# Get Orders for a Payment Link
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/payment-links/get-orders-for-link

openapi/payments/v2025-01-01.yaml get /links/{link_id}/orders
Use this API to view all order details for a payment link.



# Payment Link Webhooks
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/payment-links/webhooks

Learn about webhooks triggered when payments made through Payment Links.

## Webhook Schema

Payment Link webhook will be triggered when your customer makes a complete or partial payment using the payment link you shared. You will also be notified via the same webhook when the payment link gets cancelled or expired.

```json theme={"dark"}
{
	"data": {
		"cf_link_id": 1576977,
		"link_id": "payment_ps11",
		"link_status": "PARTIALLY_PAID",
		"link_currency": "INR",
		"link_amount": "200.12",
		"link_amount_paid": "55.00",
		"link_partial_payments": true,
		"link_minimum_partial_amount": "11.00",
		"link_purpose": "Payment for order 10",
		"link_created_at": "2021-08-18T07:13:41",
		"customer_details": {
			"customer_phone": "9000000000",
			"customer_email": "john@gmail.com",
			"customer_name": "John "
		},
		"link_meta": {
			"notify_url": "https://ee08e626ecd88c61c85f5c69c0418cb5.m.pipedream.net"
		},
		"link_url": "https://payments-test.cashfree.com/links//U1mgll3c0e9g",
		"link_expiry_time": "2021-11-28T21:46:20",
		"link_notes": {
			"note_key_1": "note_value_1"
		},
		"link_auto_reminders": true,
		"link_notify": {
			"send_sms": true,
			"send_email": true
		},
		"order": {
			"order_amount": "22.00",
			"order_id": "CFPay_U1mgll3c0e9g_ehdcjjbtckf",
			"order_expiry_time": "2021-08-18T07:34:50",
			"order_hash": "Gb2gC7z0tILhGbZUIeds",
			"transaction_id": 1021206,
			"transaction_status": "SUCCESS"
		}
	},
	"type": "PAYMENT_LINK_EVENT",
	"version": 1,
	"event_time": "2021-08-18T12:55:06+05:30"
}
```

***

## Payload

| Field | Description | Example |
| :- | :- | :- |
| `cf_link_id` | Unique Identifier (generated by Cashfree) for this Link. | 1543566 |
| `link_id` | Unique Identifier (provided by merchant) for the Link. Only for merchant reference. | payment\_1psw |
| `link_status` | Current status of the payment link. Possible values: PAID, PARTIALLY\_PAID, EXPIRED, CANCELLED. | PARTIALLY\_PAID |
| `link_currency` | Default is INR. International currencies are supported. | INR |
| `link_amount` | The amount which merchant wants to collect for the order. | 500.00 |
| `link_amount_paid` | The amount paid by the customer. | 250.00 |
| `link_partial_payments` | Indicates if partial payments are allowed or not. Default value is false. | true |
| `link_minimum_partial_amount` | The minimum amount which must be paid by customer as the first payment. | 200.00 |
| `link_purpose` | A brief description for which payment must be collected. This is shown to the customer. | Payment for order 10 |
| `link_created_at` | Time at which the link was created. | 2021-08-18T07:13:41 |
| `customer_details` | Customer object, it contains customer details. | |
| `customer_name` | Name of the customer | John |
| `customer_phone` | Phone number of the customer | 9000000000 |
| `customer_email` | Email ID of the customer | [john@gmail.com](mailto:john@gmail.com) |
| `notify_url` | Payment notification URL | [https://payment1notify.net](https://payment1notify.net) |
| `link_url` | Payment link URL | [https://website.com/payments](https://website.com/payments) |
| `link_expiry_time` | The date till which the link will be valid, and then it will be expired. Default is 30 days. | 2021-11-28T21:46:20 |
| `link_notes` | Link notes object where you can provide any key-value pairs for your internal reference. | |
| `note_key_1` | | note\_value\_1 |
| `link_auto_reminders` | Default is false. Reminders will be sent to customers based on defined settings. | true |
| `link_notify` | Link notify object, used to notify customers via SMS or an email. | |
| `send_sms` | Default is true. If true, Cashfree will send the link to customer via SMS. | true |
| `send_email` | Default is true. If true and `customer_email` is provided, Cashfree will send the link via Email. | true |
| `order` | Order object, contains the order details. Will be null for cancelled and expired link statuses. | |
| `order_amount` | Order amount that the customer must pay. | 700 |
| `order_id` | The order ID generated. | order\_10 |
| `order_expiry_time` | The date till which the order will be valid. Default is 30 days. | 2021-08-18T07:34:50 |
| `transaction_id` | Transaction ID | id45466ye |
| `transaction_status` | Status of the transaction. Possible values: SUCCESS. | SUCCESS |
| `type` | Type of the webhook. `PAYMENT_LINK_EVENT` | PAYMENT\_LINK\_EVENT |
| `version` | The version of webhook. Build parsing logic with respect to this version. | 1 |
| `event_time` | Time when this webhook was created. | 2021-08-18T12:55:06+05:30 |

***

## Signature generation

The signature must be used to verify if the request has not been tampered with. To verify the signature at your end, you will need your Cashfree Payment Gateway secret key along with the payload.

```javascript theme={"dark"}
// The payload here refers to the raw request sent by
// Cashfree to your endpoint. No modifications need to be made to this payload.
{
    "data": {
        "cf_link_id": 1576977,
        "link_id": "payment_ps11",
        "link_status": "PARTIALLY_PAID",
        "link_currency": "INR",
        "link_amount": "200.12",
        "link_amount_paid": "55.00",
        "link_partial_payments": true,
        "link_minimum_partial_amount": "11.00",
        "link_purpose": "Hello my friend how are you",
        "link_created_at": "2021-08-18T07:13:41",
        "customer_details": {
            "customer_phone": "9905736722",
            "customer_email": "supal.dubey@cashfree.com",
            "customer_name": "Supal "
        },
        "link_meta": { ... }
    }
}
```

<Note>We send the webhook response in a form data format.</Note>


# Submit or Resend OTP
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/payments/authenticate

openapi/payments/v2025-01-01.yaml post /orders/pay/authenticate/{cf_payment_id}
Use this API to submit or resend OTP if you use [Native OTP](https://www.cashfree.com/docs/payments/features/native-otp) for authentication of card payments.

<a href="https://www.postman.com/cashfreedevelopers/workspace/cashfree-apis-v2025-01-01/request/40140981-210de516-f764-4b34-a5f0-9ef76e5e5762">
  <span aria-label="Postman" />

  Run in Postman: You can also try this API in our Postman Collection.
</a>

Refer to the sample responses below:

<AccordionGroup>
  <Accordion title="Submit_OTP">
    Submit OTP Success and Transaction Successful – 200 OK

    ```json theme={"dark"}
    {
      "action": "SUBMIT_OTP",
      "authenticate_status": "SUCCESS",
      "cf_payment_id": "3991872901",
      "payment_message": "payment successful"
    }
    ```

    Submit OTP Success but Invalid OTP – 200 OK

    ```json theme={"dark"}
    {
      "action": "SUBMIT_OTP",
      "authenticate_status": "FAILED",
      "cf_payment_id": "5114916442998",
      "payment_message": "otp is invalid"
    }
    ```

    Max OTP Submit Limit Exceeded – 400 Bad Request

    ```json theme={"dark"}
    {
      "message": "Exceeded retry attempts. Check latest errors and resolution from Merchant Dashboard API logs: https://bit.ly/4glEd0W Help Document: https://bit.ly/4eeZYO9",
      "code": "request_invalid",
      "type": "invalid_request_error"
    }
    ```

    Transaction Already Completed – 400 Bad Request

    ```json theme={"dark"}
    {
      "message": "Transaction is already processed. Check latest errors and resolution from Merchant Dashboard API logs: https://bit.ly/4glEd0W Help Document: https://bit.ly/4eeZYO9",
      "code": "request_invalid",
      "type": "invalid_request_error"
    }
    ```

    Invalid Request – 404 Not Found

    ```json theme={"dark"}
    {
      "message": "transaction not found. Check latest errors and resolution from Merchant Dashboard API logs: https://bit.ly/4glEd0W Help Document: https://bit.ly/4eeZYO9",
      "code": "payment_not_found",
      "type": "invalid_request_error"
    }
    ```

    Submit OTP Success but Transaction Failed – 502 Bad Gateway

    ```json theme={"dark"}
    {
      "message": "transaction failed",
      "code": "bank_processing_failure",
      "type": "api_error"
    }
    ```

    Submit OTP Success but Transaction Pending – 502 Bad Gateway

    ```json theme={"dark"}
    {
      "message": "transaction incomplete",
      "code": "bank_processing_failure",
      "type": "api_error"
    }
    ```
  </Accordion>

  <Accordion title="Resend_OTP">
    Resend OTP Success – 200 OK

    ```json theme={"dark"}
    {
      "action": "RESEND_OTP",
      "authenticate_status": "SUCCESS",
      "cf_payment_id": "5114916574918",
      "payment_message": "otp sent successfully"
    }
    ```
  </Accordion>
</AccordionGroup>

## Error codes

The following table lists the error codes you may encounter when submitting an OTP:

<Accordion title="Error codes">
  | Code | Description | Type | Status |
  | :- | :- | :- | :- |
  | `action_missing` | The `action` field is required but was not included in the request. | `invalid_request_error` | 400 |
  | `cf_payment_id_missing` | The `cf_payment_id` field is required but was not included in the request. | `invalid_request_error` | 400 |
</Accordion>


# Preauthorisation
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/payments/authorize

openapi/payments/v2025-01-01.yaml post /orders/{order_id}/authorization
Use this API to capture or void a [pre-authorised](/docs/payments/features/pre-authorisation) payment.

<a href="https://www.postman.com/cashfreedevelopers/workspace/cashfree-apis-v2025-01-01/request/40140981-3690d91b-c294-466f-a8a2-11d4d075258d">
  <span aria-label="Postman" />

  Run in Postman: You can also try this API in our Postman Collection.
</a>


# Get Payment by ID
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/payments/get

openapi/payments/v2025-01-01.yaml get /orders/{order_id}/payments/{cf_payment_id}
Use this API to view payment details of an order for a payment ID.

<a href="https://www.postman.com/cashfreedevelopers/workspace/cashfree-apis-v2025-01-01/request/40140981-2796fe72-dc6f-4333-921e-7c42ea5de3b7">
  <span aria-label="Postman" />

  Run in Postman: You can also try this API in our Postman Collection.
</a>

## Error codes

The following table lists the error codes you may encounter when retrieving payment details for an order using a payment ID:

<Accordion title="Error codes">
  | Code | Description | Type | Status |
  | :- | :- | :- | :- |
  | `order_id_invalid` | The `order_id` field contains a value in an invalid format. Provide a correctly formatted order ID and try again. Value received: `#INVALID` | `invalid_request_error` | 400 |
  | `order_id_missing` | The `order_id` field is required but was not included in the request. | `invalid_request_error` | 400 |
  | `version_missing` | The `version` field is required but was not included in the request header. | `invalid_request_error` | 400 |
  | `payment_id_invalid` | The `payment_id` field must be a numeric value. Value received: `INVALID` | `invalid_request_error` | 400 |
  | `payment_get_failed` | The `payment_id` value is out of the supported integer range and cannot be processed. Value received: `100000000000000000000000000000000000000` | `invalid_request_error` | 400 |
  | `payment_id_missing` | The `payment_id` field is required but was not included in the request. | `invalid_request_error` | 400 |
  | `payment_not_found` | No transaction was found for the specified payment ID. Verify the payment ID and try again. | `invalid_request_error` | 404 |
  | `order_not_found` | No order was found for the specified order reference ID. Verify the order ID and try again. | `invalid_request_error` | 404 |
</Accordion>

<Note>This API allows you to retrieve payment data for the current and previous financial years. To access data older than this period, log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login)</Note>


# Get Payments for an Order
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/payments/get-payments-for-order

openapi/payments/v2025-01-01.yaml get /orders/{order_id}/payments
Use this API to view all payment details for an order.

<Note>This API allows you to retrieve payment data for the current and previous financial years. To access data older than this period, log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login)</Note>

<a href="https://www.postman.com/cashfreedevelopers/workspace/cashfree-apis-v2025-01-01/request/40140981-6548d3d4-dd09-4018-ae2a-25e2748a5f7a">
  <span aria-label="Postman" />

  Run in Postman: You can also try this API in our Postman Collection.
</a>


# Order Pay
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/payments/pay

openapi/payments/v2025-01-01.yaml post /orders/sessions
Initiate a payment for an order using the Order Pay API with support for multiple payment methods and NPCI-compliant device headers.

<a href="https://www.postman.com/cashfreedevelopers/workspace/cashfree-apis-v2025-01-01/request/40140981-62c46e50-a046-45ae-a497-0242a5cb511d">
  <span aria-label="Postman" />

  Run in Postman: You can also try this API in our Postman Collection.
</a>

<Note>
  **S2S enablement required**: To call the Seamless Payment Creation API, make sure the required S2S flag is enabled for your account. To enable it, submit a request through the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1).

  * **S2S card flag**: To enable card payments, share your PCI DSS compliance certificate through the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1).
  * **Main S2S flag for other payment modes**: To enable seamless payments for modes other than cards, submit a GST return showing an annual turnover of more than Rs. 1 crore. After the document is verified, Cashfree enables the seamless flow.
</Note>

## Client environment headers

Cashfree requires information about the customer's device environment to enforce NPCI rules. You must include the following headers in your Order Pay API and [Get Eligible Payment Methods](/docs/api-reference/payments/latest/eligibility/get-eligible-payment-methods) request:

<Accordion title="Client environment headers">
  | Header | Accepted values | Requirement | Description |
  | - | - | - | - |
  | `x-client-device` | `mobile`, `desktop`, `tablet` | Required | Type of device used by customer |
  | `x-client-os` | `android`, `ios`, `windows`, `macos`, `linux`, `others` | Required | Operating system of customer's device |
  | `x-client-rendering-type` | `mweb`, `webview`, `native` | Required when `x-client-device` is mobile | Rendering method used for the checkout experience |
  | `x-client-browser` | `safari`, `chrome`, `firefox`, `edge`, `others` | Required | Browser used by the customer |
</Accordion>

<Note>`x-client-rendering-type` is required only when `x-client-device` is set to mobile. For desktop and tablet devices, this header is optional.</Note>

## Error codes

The following table lists the error codes, descriptions, and types you may encounter when initiating a payment:

<Accordion title="Error codes">
  | Code | Description | Type | Status |
  | :- | :- | :- | :- |
  | `channel_missing` | The `channel` field is required but was not included in the request. | `invalid_request_error` | 400 |
  | `phone_invalid` | The `phone` field must contain a valid 10-digit Indian phone number (for example, `9090407368`). Value received: `1234567890` | `invalid_request_error` | 400 |
  | `phone_missing` | The `phone` field is required but was not included in the request. | `invalid_request_error` | 400 |
  | `provider_missing` | The `provider` field is required but was not included in the request. | `invalid_request_error` | 400 |
  | `version_missing` | The `version` field must be one of the following supported values: `2021-05-21`, `2022-01-01`, `2022-09-01`, `2023-08-01`, `2025-01-01`, or `2026-01-01`. | `invalid_request_error` | 400 |
  | `card_cvv_invalid` | The `card_cvv` field must be at least 3 characters long. Value received: `12` | `invalid_request_error` | 400 |
  | `card_cvv_missing` | The `card_cvv` field is required but was not included in the request. | `invalid_request_error` | 400 |
  | `card_invalid` | The `card` field is invalid. Provide payment details using one of the following: card details, `card_alias`, `instrument_id`, or `cryptogram`. | `invalid_request_error` | 400 |
  | `bank_processing_failure` | The transaction could not be created at the banking partner. Retry the request or contact support if the issue persists. | `api_error` | 502 |
  | `request_invalid` | Cards issued in India cannot be used for transactions where the order currency is non-INR. Value received: `AUD` | `invalid_request_error` | 400 |
  | `orderpay_not_found` | The specified order is no longer active and cannot be used to initiate a payment. | `invalid_request_error` | 404 |
  | `card_bank_name_missing` | The `card_bank_name` field is required but was not included in the request. | `invalid_request_error` | 400 |
  | `card_bank_name_invalid` | The `card_bank_name` field contains an unrecognised value. Accepted values are: `hdfc`, `icici`, `kotak`, `rbl`, `bob`, `axis`, `standard chartered`, `au`, `yes`, `indus`, `fed`, `hsbc`, `citi`, `sbi`, `amex`, `onecard`, or `idfc`. Value received: `INVALID$BANK` | `invalid_request_error` | 400 |
  | `card_expiry_yy_missing` | The `card_expiry_yy` field is required but was not included in the request. | `invalid_request_error` | 400 |
  | `card_expiry_yy_invalid` | The `card_expiry_yy` field must be at least 2 characters long. Value received: `0` | `invalid_request_error` | 400 |
  | `card_expiry_mm_missing` | The `card_expiry_mm` field is required but was not included in the request. | `invalid_request_error` | 400 |
  | `card_expiry_mm_invalid` | The `card_expiry_mm` field must be at least 2 characters long. Value received: `0` | `invalid_request_error` | 400 |
  | `card_number_invalid` | The `card_number` field contains an invalid card number. Verify the card number and try again. Value received: `INVALID` | `invalid_request_error` | 400 |
  | `card_number_missing` | The `card_number` field is required but was not included in the request. | `invalid_request_error` | 400 |
  | `card_not_found` | The card details could not be retrieved. Verify the card information and try again. | `invalid_request_error` | 404 |
  | `emi_tenure_missing` | The `emi_tenure` field is required but was not included in the request. | `invalid_request_error` | 400 |
  | `order_amount_invalid` | The order amount exceeds the maximum allowed value. The amount must be less than `1,000,000`. | `invalid_request_error` | 400 |
  | `netbanking_account_number_invalid` | The `netbanking_account_number` field must be at least 9 characters long. Value received: `test` | `invalid_request_error` | 400 |
  | `netbanking_bank_code_invalid` | The `netbanking_bank_code` field contains an invalid value. Provide a supported bank code and try again. | `invalid_request_error` | 400 |
  | `netbanking_ifsc_invalid` | The `netbanking_ifsc` field contains an invalid IFSC code. Verify the IFSC and try again. Value received: `INVALID` | `invalid_request_error` | 400 |
  | `request_failed` | The selected payment mode is not configured for this account. Enable the payment mode or contact support. | `invalid_request_error` | 400 |
  | `currency_invalid` | The `currency` field does not accept `INR` for this request. Use a supported non-INR currency. Value received: `INR` | `invalid_request_error` | 400 |
  | `currency_missing` | The `currency` field is required but was not included in the request. | `invalid_request_error` | 400 |
  | `risk_data.customer_ip_invalid` | The `risk_data.customer_ip` field contains an invalid IP address. Provide a valid IPv4 or IPv6 address. Value received: `1.1.1` | `invalid_request_error` | 400 |
  | `risk_data_ip_address_request_failed` | The IP address could not be resolved. Verify the IP address and try again. | `invalid_request_error` | 400 |
  | `order_token_missing` | The `order_token` field is required but was not included in the request. | `invalid_request_error` | 400 |
  | `payment_method_invalid` | The `payment_method` field contains an unrecognised value. Provide a valid payment method and try again. | `invalid_request_error` | 400 |
  | `payment_method_missing` | The `payment_method` field is required but was not included in the request. | `invalid_request_error` | 400 |
  | `payment_method_unsupported` | The specified payment method is not supported for this request. Use a supported payment method and try again. | `invalid_request_error` | 400 |
</Accordion>


# Payment Webhooks
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/payments/webhooks

Read about all asynchronous events initiated by Cashfree for this entity

Webhooks are server callbacks from Cashfree to your server. Cashfree sends webhooks for the following events for a `payment`:

* Payment success webhook
* Payment failed webhook
* Payment user dropped webhook
* Payment charges webhook

## Webhook signature

The merchant will receive the Webhook signature in the Webhook Header part. Below is a sample header that merchants can expect in the Webhook request. For best practices on securing your webhook endpoints, refer to the [Webhook Security Checklist](/docs/payments/online/webhooks/security-checklist).

<Tabs>
  <Tab title="Version (2025-01-01)">
    | Header Name | Header Value |
    | - | :-: |
    | content-length | 1099 |
    | x-webhook-attempt | 1 |
    | content-type | application/json |
    | x-webhook-signature | 07r5C3VMwsGYeldGOCYxe5zoHhIN1zLfa8O0U/yngHI= |
    | x-idempotency-key | n9rn7079wqXcse3GEDEXCYle9ajXmU0SUQY8zrUNAlc= |
    | x-webhook-timestamp | 1746427759733 |
    | x-webhook-version | 2025-01-01 |
  </Tab>

  <Tab title="Version (2023-08-01)">
    | Header Name | Header Value |
    | - | :-: |
    | content-length | 1002 |
    | x-webhook-attempt | 1 |
    | content-type | application/json |
    | x-webhook-signature | 0s9zgYXyUYrQaadF5oTYzpxzHmPBMmGDSjbAKZTleL4= |
    | x-webhook-timestamp | 1746426425612 |
    | x-webhook-version | 2023-08-01 |
  </Tab>
</Tabs>

<Tip> Ensure that the webhook payload is received in raw text format. Converting the webhook into a JSON object can lead to automatic transformation of decimal values—such as the payment\_amount—into integers. This alteration (e.g., payment\_amount: 170 instead of payment\_amount: 170.00) can cause a webhook signature mismatch.<br /><br />**Correct format: payment\_amount: 170.00** ✅ <br />**Incorrect format: payment\_amount: 170** ❌</Tip>

## Payment success webhook

A payment success webhook is triggered when a payment is successfully completed. You can use this for: Updating order status, triggering fulfilment, and sending confirmation to the customer.

<Tabs>
  <Tab title="Version (2025-01-01)">
    ```javascript Version (2025-01-01) theme={"dark"}
    {
    "data":{
      "order":{
         "order_id":"order_OFR_2",
         "order_amount":2,
         "order_currency":"INR",
         "order_tags":null
      },
      "payment":{
         "cf_payment_id":"1453002795",
         "payment_status":"SUCCESS",
         "payment_amount":1,
         "payment_currency":"INR",
         "payment_message":"00::Transaction success",
         "payment_time":"2025-01-15T12:20:29+05:30",
         "bank_reference":"234928698581",
         "auth_id":null,
         "payment_method":{
            "upi":{
               "channel":"collect",
               "upi_id":"rishab@ybl",
               "upi_instrument":"UPI_CREDIT_CARD",
               "upi_instrument_number":"masked card number",
               "upi_payer_ifsc":"SBI0025434",
               "upi_payer_account_number":"XXXXX0231"
            }
         },
         "payment_group":"upi",
         "international_payment":{
            "international":false
         },
         "payment_surcharge":{
            "payment_surcharge_service_charge":0.36,
            "payment_surcharge_service_tax":0.06
         }
      },
      "customer_details":{
         "customer_name":null,
         "customer_id":"7112AAA812234",
         "customer_email":"test@gmail.com",
         "customer_phone":"9908734801"
      },
      "payment_gateway_details":{
         "gateway_name":"CASHFREE",
         "gateway_order_id":"1634766330",
         "gateway_payment_id":"1504280029",
         "gateway_order_reference_id":"abc_124",
         "gateway_settlement":"CASHFREE",
         "gateway_status_code":null
      },
      "payment_offers":[
         {
            "offer_id":"0f05e1d0-fbf8-4c9c-a1f0-814c7b2abdba",
            "offer_type":"DISCOUNT",
            "offer_meta":{
               "offer_title":"50% off on UPI",
               "offer_description":"50% off for testing",
               "offer_code":"UPI50",
               "offer_start_time":"2022-11-09T06:23:25.972Z",
               "offer_end_time":"2025-02-27T18:30:00Z"
            },
            "offer_redemption":{
               "redemption_status":"SUCCESS",
               "discount_amount":1,
               "cashback_amount":0
            }
         }
      ],
      "terminal_details":{
        "cf_terminal_id":17269,
        "terminal_phone":"8971520311"
      }
    },
    "event_time":"2025-01-15T11:16:10+05:30",
    "type":"PAYMENT_SUCCESS_WEBHOOK"
    }
    ```
  </Tab>

  <Tab title="Version (2023-08-01)">
    ```javascript Version (2023-08-01) theme={"dark"}
    {
    "data":{
      "order":{
         "order_id":"order_OFR_2",
         "order_amount":2,
         "order_currency":"INR",
         "order_tags":null
      },
      "payment":{
         "cf_payment_id":"1453002795",
         "payment_status":"SUCCESS",
         "payment_amount":1,
         "payment_currency":"INR",
         "payment_message":"00::Transaction success",
         "payment_time":"2022-12-15T12:20:29+05:30",
         "bank_reference":"234928698581",
         "auth_id":null,
         "payment_method":{
            "upi":{
               "channel":"collect",
               "upi_id":"suhasg6@ybl",
            }
         },
         "payment_group":"upi"
      },
      "customer_details":{
         "customer_name":null,
         "customer_id":"7112AAA812234",
         "customer_email":"test@gmail.com",
         "customer_phone":"9908734801"
      },
      "payment_gateway_details":{
         "gateway_name":"CASHFREE",
         "gateway_order_id":"1634766330",
         "gateway_payment_id":"1504280029",
         "gateway_order_reference_id":"abc_124",
         "gateway_settlement":"CASHFREE",
         "gateway_status_code":null
      },
      "payment_offers":[
         {
            "offer_id":"0f05e1d0-fbf8-4c9c-a1f0-814c7b2abdba",
            "offer_type":"DISCOUNT",
            "offer_meta":{
               "offer_title":"50% off on UPI",
               "offer_description":"50% off for testing",
               "offer_code":"UPI50",
               "offer_start_time":"2022-11-09T06:23:25.972Z",
               "offer_end_time":"2023-02-27T18:30:00Z"
            },
            "offer_redemption":{
               "redemption_status":"SUCCESS",
               "discount_amount":1,
               "cashback_amount":0
            }
         }
      ]
    },
    "event_time":"2023-08-01T11:16:10+05:30",
    "type":"PAYMENT_SUCCESS_WEBHOOK"
    }
    ```
  </Tab>
</Tabs>

## Payment failed webhook

The payment failed webhook notifies you when a payment attempt fails, and we receive a failed response from the bank. Use case: Update order status, notify customer, initiate retry flow

<Tabs>
  <Tab title="Version 2025-01-01">
    ```javascript Version 2025-01-01 theme={"dark"}
    {  
    "data": {  
        "order": {  
            "order_id": "CFPay_g47u3888d0k0_tblfm766qc",  
            "order_amount": 1.8,  
            "order_currency": "INR",  
            "order_tags": {  
                "cf_link_id": "13746255"  
            }  
        },  
        "payment": {  
            "cf_payment_id": "1504280029",  
            "payment_status": "FAILED",  
            "payment_amount": 1.8,  
            "payment_currency": "INR",  
            "payment_message": "AMOUNT SHOULD BE WITHIN RANGE BETWEEN 20.00 TO 500000.00.",  
            "payment_time": "2023-01-06T20:00:11+05:30",  
            "bank_reference": "NA",  
            "auth_id": "null",  
            "payment_method": {  
                "netbanking": {  
                    "channel": null,  
                    "netbanking_bank_code": "3054",  
                    "netbanking_bank_name": "UCO Bank"  
                }  
            },  
            "payment_group": "net_banking",
            "international_payment":{
                "international":false
            },
            "payment_surcharge":{
                "payment_surcharge_service_charge":0,
                "payment_surcharge_service_tax":0
            }
        },  
        "customer_details": {  
            "customer_name": null,  
            "customer_id": null,  
            "customer_email": "test@gmail.com",  
            "customer_phone": "9611199227"  
        },  
        "error_details": {  
            "error_code": "GATEWAY_ERROR",  
            "error_description": "AMOUNT SHOULD BE WITHIN RANGE BETWEEN 20.00 TO 500000.00. for this bank",  
            "error_reason": "invalid_amount",  
            "error_source": "cashfree",
            "error_subcode_raw": "U09"
        },  
        "payment_gateway_details": {
            "gateway_name": "CASHFREE",
            "gateway_order_id": "1634766330",
            "gateway_payment_id": "1504280029",
            "gateway_settlement": "CASHFREE",
            "gateway_status_code": null
        }, 
        "payment_offers": null,
        "terminal_details":{
            "cf_terminal_id":17269,
            "terminal_phone":"8971520311"
        }
    },  
    "event_time": "2023-08-01T20:00:12+05:30",  
    "type": "PAYMENT_FAILED_WEBHOOK"  
    }
    ```
  </Tab>

  <Tab title="Version 2023-08-01">
    ```javascript Version 2023-08-01 theme={"dark"}
    {
    "data": {
        "order": {
            "order_id": "CFPay_g47u3888d0k0_tblfm766qc",
            "order_amount": 1.8,
            "order_currency": "INR",
            "order_tags": {
                "cf_link_id": "13746255"
            }
        },
        "payment": {
            "cf_payment_id": "1504280029",
            "payment_status": "FAILED",
            "payment_amount": 1.8,
            "payment_currency": "INR",
            "payment_message": "AMOUNT SHOULD BE WITHIN RANGE BETWEEN 20.00 TO 500000.00.",
            "payment_time": "2023-01-06T20:00:11+05:30",
            "bank_reference": "NA",
            "auth_id": "null",
            "payment_method": {
                "netbanking": {
                    "channel": null,
                    "netbanking_bank_code": "3054",
                    "netbanking_bank_name": "UCO Bank"
                }
            },
            "payment_group": "net_banking"
        },
        "customer_details": {
            "customer_name": null,
            "customer_id": null,
            "customer_email": "test@gmail.com",
            "customer_phone": "9611199227"
        },
        "error_details": {
            "error_code": "GATEWAY_ERROR",
            "error_description": "AMOUNT SHOULD BE WITHIN RANGE BETWEEN 20.00 TO 500000.00. for this bank",
            "error_reason": "invalid_amount",
            "error_source": "cashfree",
            "error_subcode_raw": "U09"
        },
        "payment_gateway_details": {
            "gateway_name": "CASHFREE",
            "gateway_order_id": "1634766330",
            "gateway_payment_id": "1504280029",
            "gateway_settlement": "CASHFREE",
            "gateway_status_code": null
        },
        "payment_offers": null
    },
    "event_time": "2023-08-01T20:00:12+05:30",
    "type": "PAYMENT_FAILED_WEBHOOK"
    }
    ```
  </Tab>
</Tabs>

## Payment user dropped webhook

The User Dropped Webhook notifies you when your customer abandons the payment flow. It will help you understand if customers attempted to pay or not. Some common scenarios where the transaction will be marked as USER\_DROPPED are:

* User was redirected to the bank's OTP page, but never entered the OTP.
* User was redirected to open the UPI app, but never entered the UPI PIN.
* User was shown the 3ds OTP modal, but did not enter the OTP.

<Tabs>
  <Tab title="Version 2025-01-01">
    ```javascript Version 2025-01-01 theme={"dark"}
    {
    "data": {
    "order": {
      "order_id": "order_02",
      "order_amount": 2,
      "order_currency": "INR",
      "order_tags": null
    },
    "payment": {
      "cf_payment_id": "975672265",
      "payment_status": "USER_DROPPED",
      "payment_amount": 2,
      "payment_currency": "INR",
      "payment_message": "User dropped and did not complete the two factor authentication",
      "payment_time": "2022-05-25T14:25:34+05:30",
      "bank_reference": "1803592531",
      "auth_id": "2980",
      "payment_method": {
        "netbanking": {
          "channel": null,
          "netbanking_bank_code": "3044",
          "netbanking_bank_name": "State Bank Of India"
        }
      },
      "payment_group": "net_banking",
      "international_payment":{
        "international":false
      },
      "payment_surcharge":{
        "payment_surcharge_service_charge":0,
        "payment_surcharge_service_tax":0
      }
    },
    "customer_details": {
      "customer_name": null,
      "customer_id": "7112AAA812234",
      "customer_email": "test@gmail.com",
      "customer_phone": "9611199227"
    },
    "terminal_details":{
      "cf_terminal_id":17269,
      "terminal_phone":"8971520311"
    }
    },
    "event_time": "2022-05-25T14:35:38+05:30",
    "type": "PAYMENT_USER_DROPPED_WEBHOOK"
    }
    ```
  </Tab>

  <Tab title="Version 2023-08-01">
    ```javascript Version 2023-08-01 theme={"dark"}
    {
    "data": {
    "order": {
      "order_id": "order_02",
      "order_amount": 2,
      "order_currency": "INR",
      "order_tags": null
    },
    "payment": {
      "cf_payment_id": "975672265",
      "payment_status": "USER_DROPPED",
      "payment_amount": 2,
      "payment_currency": "INR",
      "payment_message": "User dropped and did not complete the two factor authentication",
      "payment_time": "2022-05-25T14:25:34+05:30",
      "bank_reference": "1803592531",
      "auth_id": "2980",
      "payment_method": {
        "netbanking": {
          "channel": null,
          "netbanking_bank_code": "3044",
          "netbanking_bank_name": "State Bank Of India"
        }
      },
      "payment_group": "net_banking"
    },
    "customer_details": {
      "customer_name": null,
      "customer_id": "7112AAA812234",
      "customer_email": "test@gmail.com",
      "customer_phone": "9611199227"
    }
    },
    "event_time": "2022-05-25T14:35:38+05:30",
    "type": "PAYMENT_USER_DROPPED_WEBHOOK"
    }
    ```
  </Tab>
</Tabs>

## Payment charges webhook

A payment charges webhook is triggered after a successful payment when Cashfree finalises the Transaction Discount Rate (TDR) and related charges for that payment. The event time can be later than the payment time. Use this webhook to reconcile per-payment charges and the net settlement amount.

To receive this event, subscribe to **Success Payment TDR** when you [configure webhooks](/docs/payments/online/webhooks/configure) in the Merchant Dashboard. The webhook `type` in the payload is `PAYMENT_CHARGES_WEBHOOK`.

<Note>
  The `payment_method` object in this webhook can be empty (`{}`). This is expected for the payment charges event.
</Note>

For background on TDR, see [What is TDR?](/docs/help/account/pricing#what-is-tdr).

### `charges_details` fields

| Field | Description | Example |
| - | - | - |
| `service_charge` | Service charge (TDR) applicable for the payment. | `0.12` |
| `service_tax` | Service tax applicable on the service charge. | `0.02` |
| `settlement_amount` | Net amount for the payment after deducting the service charge and service tax. | `5.86` |
| `settlement_currency` | Currency of the settlement amount. | `INR` |
| `service_charge_discount` | Discount applied on the service charge, if any. Returns `null` when no discount applies. | `null` |

<Tabs>
  <Tab title="Version 2025-01-01">
    ```javascript Version 2025-01-01 theme={"dark"}
    {
    "data": {
    "order": {
      "order_id": "14508_73_1783668483731",
      "order_amount": 6.00,
      "order_currency": "INR",
      "order_tags": null
    },
    "payment": {
      "cf_payment_id": 5979305158,
      "payment_status": "SUCCESS",
      "payment_amount": 6.00,
      "payment_currency": "INR",
      "payment_message": "SUCCESS",
      "payment_time": "2026-07-10T12:58:04+05:30",
      "bank_reference": "841754751916",
      "auth_id": null,
      "payment_method": {},
      "payment_group": "sbc_upi"
    },
    "customer_details": {
      "customer_name": null,
      "customer_id": null,
      "customer_email": "rfeef@gmail.com",
      "customer_phone": "9876543211"
    },
    "charges_details": {
      "service_charge": 0.12,
      "service_tax": 0.02,
      "settlement_amount": 5.86,
      "settlement_currency": "INR",
      "service_charge_discount": null
    }
    },
    "event_time": "2026-07-15T08:00:05+05:30",
    "type": "PAYMENT_CHARGES_WEBHOOK"
    }
    ```
  </Tab>

  <Tab title="Version 2023-08-01">
    ```javascript Version 2023-08-01 theme={"dark"}
    {
    "data": {
    "order": {
      "order_id": "14508_73_1783668483731",
      "order_amount": 6.00,
      "order_currency": "INR",
      "order_tags": null
    },
    "payment": {
      "cf_payment_id": 5979305158,
      "payment_status": "SUCCESS",
      "payment_amount": 6.00,
      "payment_currency": "INR",
      "payment_message": "SUCCESS",
      "payment_time": "2026-07-10T12:58:04+05:30",
      "bank_reference": "841754751916",
      "auth_id": null,
      "payment_method": {},
      "payment_group": "sbc_upi"
    },
    "customer_details": {
      "customer_name": null,
      "customer_id": null,
      "customer_email": "rfeef@gmail.com",
      "customer_phone": "9876543211"
    },
    "charges_details": {
      "service_charge": 0.12,
      "service_tax": 0.02,
      "settlement_amount": 5.86,
      "settlement_currency": "INR",
      "service_charge_discount": null
    }
    },
    "event_time": "2026-07-15T08:00:05+05:30",
    "type": "PAYMENT_CHARGES_WEBHOOK"
    }
    ```
  </Tab>
</Tabs>

## Sample payload by payment method

The instrument used for making a payment will vary by the payment methods used by the customer. Details of the payload by payment method are documented for reference.

<Tabs>
  <Tab title="Card">
    ```javascript theme={"dark"}
    {
      ...,
      "payment_method": {  
        "card": {  
          "channel": "link",  
          "card_number": "XXXXXXXXXXXX4738",  
          "card_network": "visa",  
          "card_type": "credit_card",  
          "card_sub_type": "R",  
          "card_country": "IN",  
          "card_bank_name": "HDFC Bank",
          "card_network_reference_id": "100212023061200000001014824849",
          "instrument_id":"8e9cc167-4fe2-4ece-be8d-c1b224e50a23",
          "par": "V0010014623022637739353641436"
        }  
      },  
      "payment_group": "credit_card",
      ...
    }

    ```
  </Tab>

  <Tab title="Net Banking">
    ```javascript theme={"dark"}
    {
      ...,
      "payment_method": {  
        "netbanking": {  
          "channel":null,  
          "netbanking_bank_code":"3022",  
          "netbanking_bank_name":"ICICI Bank"  
        }  
      },  
      "payment_group":"net_banking",
      ...
    }

    ```
  </Tab>

  <Tab title="UPI">
    ```javascript theme={"dark"}
    {
      ...,
      "payment_method": {  
        "upi": {
                "channel": "collect",
                "upi_id": "rishabtated@ybl",
                "upi_instrument" : "UPI_CREDIT_CARD", 
                "upi_instrument_number" : "masked card number", 
                "upi_payer_ifsc" : "SBI0025434",
                "upi_payer_account_number" : "XXXXX0231"
            }  
      },
      "payment_group":"upi",
      ...
    }

    ```
  </Tab>

  <Tab title="Wallet">
    ```javascript theme={"dark"}
    {
      ...,
      "payment_method": {  
        "app": {  
          "channel":"AmazonPay",  
          "upi_id":null  
        }  
      },  
      "payment_group":"wallet",
      ...
    }

    ```
  </Tab>

  <Tab title="Credit Card EMI">
    ```javascript theme={"dark"}
    {
      ...,
      "payment_method":{  
        "card":{  
          "channel":null,  
          "card_number":"XXXXXXXXXX8952",  
          "card_network":null,  
          "card_type":"credit_card_emi",  
          "card_country":null,  
          "card_bank_name":"HDFC BANK",  
          "emi_details":{  
            "emi_amount":1167,  
            "emi_tenure":3,  
            "emi_interest":16.00  
          },
          "card_network_reference_id":null
        }  
      },  
      "payment_group":"credit_card_emi",
      ...
    }

    ```
  </Tab>

  <Tab title="Debit Card EMI">
    ```javascript theme={"dark"}
    {
      ...,
      "payment_method":{  
        "card":{  
          "channel":null,  
          "card_number":"XXXXXXXXXX8952",  
          "card_network":null,  
          "card_type":"debit_card_emi",  
          "card_country":null,  
          "card_bank_name":"HDFC BANK",  
          "emi_details":{  
            "emi_amount":1167,  
            "emi_tenure":3,  
            "emi_interest":16.00  
          }  
        }  
      },  
      "payment_group":"debit_card_emi",
      ...
    }

    ```
  </Tab>

  <Tab title="Cardless EMI">
    ```javascript theme={"dark"}
    {
      ...,
      "payment_method":{  
        "cardless_emi":{  
          "channel":null,  
          "provider":"flexmoney",  
          "phone":"9731117102",  
          "emi_details":null  
        }  
      },  
      "payment_group":"cardless_emi",
      ...
    }

    ```
  </Tab>

  <Tab title="Pay Later">
    ```javascript theme={"dark"}
    {
      ...,
      "payment_method":{  
        "pay_later":{  
            "channel":null,
            "provider":"olapostpaid",
            "phone":"9731117102"
        }  
      },  
      "payment_group":"pay_later",
      ...
    }

    ```
  </Tab>

  <Tab title="VBA Transfer">
    ```javascript theme={"dark"}
    {
      ...,
     "payment_method":{
         "vba_transfer":{
             "utr":"MerchantID_utr",
             "credit_ref_no":"NA",
             "remitter_account":"808081pxqp242614HW",
             "remitter_name":"Test",
             "remitter_ifsc":"IFSC",
             "email":"rishabtated@gmail.com",
             "phone":"9999999999",
             "vaccount_id":"123499",
             "vaccount_number":"94260000123400"
         }
     },
     "payment_group":"vba_transfer",
      ...
    }

    ```
  </Tab>

  <Tab title="Bank Transfer">
    ```javascript theme={"dark"}
    {
      ...,
     "payment_method":{
         "bank_transfer":{
             "transfer_type":"NEFT",
             "bank":"UNION BANK OF INDIA"
         }
     },
     "payment_group":"bank_transfer",
      ...
    }

    ```
  </Tab>
</Tabs>

## Webhook FAQs

<div>
  <a href="/docs/payments/online/webhooks/configure">
    Configure webhooks
  </a>
</div>

<AccordionGroup>
  <Accordion title="How do I add or configure webhook URLs for different event types (e.g., success, failed)?">
    You can configure webhook URLs for each notification type in your merchant dashboard. To receive notifications, subscribe to specific events, such as PAYMENT\_SUCCESS or PAYMENT\_FAILED. For step-by-step instructions, go through the [official documentation](/docs/payments/online/webhooks/overview).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Why am I not receiving failed webhooks?">
    This may occur if the PAYMENT\_FAILED webhook event is not subscribed. To resolve this, open your dashboard, navigate to the webhook configuration, and ensure that the `PAYMENT_FAILED` event       is selected.

    <Note>
      This applies to all webhook events. Make sure relevant events are enabled as needed.
    </Note>

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="I’m getting an error while adding the webhook endpoint. What could be wrong?">
    Ensure that your endpoint is reachable and returns a 2xx status code. Also, verify that it is properly configured to accept webhook requests.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Why is my webhook not received?">
    There could be multiple reasons:

    * The webhook URL was not included in the notify\_url parameter during order creation.
    * Make sure you have done the webhook configuration for the notification type as needed.
    * The endpoint URL is returning a 4xx or 5xx error.

    Actions to take:

    * Verify that your webhook is correctly configured. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and go to **Payment Gateway > Developers > Webhook Configuration**.
    * Ensure that the endpoint is accessible and able to accept requests from Cashfree.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How do I enable or disable specific webhook types?">
    You can enable or disable specific webhook types directly from the [Merchant Dashboard](https://merchant.cashfree.com/auth/login). For detailed instructions, refer to the
    **Payment Gateway > Developers > Webhook Configuration** section.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How to enable the latest webhook version (e.g., 2025-01-01)?">
    Once the feature is rolled out in Production, the new version will appear in the version drop-down under Webhook Configuration.

    <Warning>
      If you do not see the new version, the rollout may still be in progress. Please check back later or contact support for assistance.
    </Warning>

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Webhook is configured, but no real-time data is received. Why?">
    This may happen if the webhook URL is configured, but no events are selected. Ensure:

    * Webhook types are enabled.
    * Your endpoint is healthy and accessible to accept the requests from Cashfree.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Why did the webhook trigger multiple times?">
    Duplicate webhook triggers may occur due to misconfiguration or retry logic. This can happen if multiple webhook versions are configured using the same or different endpoint URLs.

    ✅ Actions to take:

    * The Merchant can revisit and delete the duplicate configured endpoint URL. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and go to **Payment Gateway > Developers > Webhook Configuration**.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What if I don't pass a notify_url and only use return URLs?">
    Notify URLs are necessary for webhook delivery. Return URLs only redirect the user after the transaction. Ensure you pass both as different URLs, especially if you need server-side notifications.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How can I improve webhook issue handling and reduce to raise of support tickets?">
    * Always subscribe to the necessary webhook event types (`SUCCESS`, `FAILED`, `USER_DROPPED`, and **Success Payment TDR** for payment charges).
    * Test your webhook integration in Sandbox before going live.
    * Use publicly accessible HTTPS URLs that return 200 OK responses.
    * Regularly review and update webhook configurations in the merchant dashboard to avoid outdated or incorrect entries.

    <iframe title="FAQs feedback component" />
  </Accordion>
</AccordionGroup>


# Create VBA
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/pgvba/create-vba

openapi/pgvba/pgvba.yaml post /pg/vba
Use this API to create a virtual bank account. It allows you to receive payments just like a regular bank account.



# Create VBA Notification Group
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/pgvba/create-vba-notification-group

openapi/pgvba/pgvba.yaml post /pg/vba/notificationgroup
Use this API to create a notification group. The recipients in the group will receive notifications regarding the payment details.



# Edit VBA
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/pgvba/edit-vba

openapi/pgvba/pgvba.yaml put /pg/vba/{virtual_account_id}
Use this API to edit the details of the created virtual bank account.



# Edit VBA Notification Group
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/pgvba/edit-vba-notification-group

openapi/pgvba/pgvba.yaml put /pg/vba/notificationgroup/{notification_group_name}
Use this API to edit the details of the created notification group.



# Get VBA
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/pgvba/get-vba

openapi/pgvba/pgvba.yaml get /pg/vba/{virtual_account_id}
Use this API to get the details of the created virtual bank account by entering the virtual account ID.



# Get VBA Notification Group
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/pgvba/get-vba-notification-group

openapi/pgvba/pgvba.yaml get /pg/vba/notificationgroup/{notification_group_name}
Use this API to get the details of the created notification group.



# Get VBA Payments
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/pgvba/get-vba-payments

openapi/pgvba/pgvba.yaml post /pg/vba/payments
Use this API to get all the payment details regarding a virtual bank account.



# Get VBA Payments By UTR
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/pgvba/get-vba-payments-by-utr

openapi/pgvba/pgvba.yaml get /pg/vba/payments/{utr}
Use this API to get the payment details by entering the unique transaction reference (UTR).



# Manage VBA
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/pgvba/manage-vba

openapi/pgvba/pgvba.yaml patch /pg/vba/{virtual_account_id}
Use this API to manage the status of the created virtual bank account.



# Manage VBA Notification Group Status
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/pgvba/manage-vba-notification-group-status

openapi/pgvba/pgvba.yaml patch /pg/vba/notificationgroup/{notification_group_name}
Use this API to modify the status of the created notification group.



# Vendor Reconciliation API
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/reconciliation/vendor-recon

openapi/payments/v2025-01-01.yaml post /recon/vendor
This API allows you to fetch vendor reconciliation details by using different filters. Use the appropriate filters based on your requirements. After you receive a VENDOR_SETTLEMENT_SUCCESS webhook confirmation, wait 15 minutes before you call this API endpoint.
 - **View Split Order Details Using Settlement ID**: Retrieve details of split orders within a settlement by Settlement ID.
 - **Vendor Recon for a Time Period**: Fetch reconciliation details for all vendors within a specific time interval.
 - **Vendor Recon Using Vendor ID & Time Interval**: Get reconciliation details for a specific vendor within a given time interval.


<Warning>
  **Vendor Recon API usage**

  When you use the Vendor Recon API, follow these guidelines:

  * Don't call the API with a failed `settlement_id`. If a settlement has failed and the amount remains unsettled, the API returns no data.
  * If the amount is later settled under a new (successful) `settlement_id`, the API returns data for the successful settlement instead.
  * To retrieve records older than six months, include a date range in your request. Searches using `settlement_id` return data from the last six months only.
</Warning>


# Create Refund
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/refunds/create

openapi/payments/v2025-01-01.yaml post /orders/{order_id}/refunds
Use this API to initiate refunds. <Note> You can initiate refunds only within six months of the original successful transaction's date and time.</Note>.

<a href="https://www.postman.com/cashfreedevelopers/workspace/cashfree-apis-v2025-01-01/request/40140981-79245292-c087-42af-9fce-a1b91a5ce5b2">
  <span aria-label="Postman" />

  Run in Postman: You can also try this API in our Postman Collection.
</a>


# Get Refund
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/refunds/get

openapi/payments/v2025-01-01.yaml get /orders/{order_id}/refunds/{refund_id}
Use this API to fetch a specific refund processed on your Cashfree Account.

<a href="https://www.postman.com/cashfreedevelopers/workspace/cashfree-apis-v2025-01-01/request/40140981-e275aca4-3b95-41ee-89bf-efef3ffcd262">
  <span aria-label="Postman" />

  Run in Postman: You can also try this API in our Postman Collection.
</a>


# Get All Refunds for an Order
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/refunds/get-refunds-for-order

openapi/payments/v2025-01-01.yaml get /orders/{order_id}/refunds
Use this API to fetch all refunds processed against an order.

<a href="https://www.postman.com/cashfreedevelopers/workspace/cashfree-apis-v2025-01-01/request/40140981-9c071097-0b45-4952-a03e-3b2abf3246cc">
  <span aria-label="Postman" />

  Run in Postman: You can also try this API in our Postman Collection.
</a>


# Update Refund
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/refunds/update-refund

openapi/payments/v2025-01-01.yaml put /orders/{order_id}/refunds/{refund_id}
Use this API to Update refunds.



# Refund Webhooks
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/refunds/webhooks

Learn about the async events sent for refunds

Webhooks are server callbacks to your server from Cashfree. We send refund webhooks for three different events for a payment.

1. Refund is successfully processed
2. Refund is cancelled by Cashfree - we were unable to successfully refund to customer even after multiple attempts.
3. For successful Auto-refunds - Read more about Auto-Refunds [here](/docs/payments/manage/refunds/overview#auto-refunds)

## Refund webhook payload

<Tabs>
  <Tab title="Version (2025-01-01)">
    ```javascript Version 2025-01-01 theme={"dark"}
    {
    "data":{
        "refund":{
             "cf_refund_id":11325632,
             "cf_payment_id":789727431,
             "refund_id":"refund_sampleorder0413",
             "order_id":"sampleorder0413",
             "refund_amount":2.00,
             "refund_currency":"INR",
             "entity":"Refund",
             "refund_type":"MERCHANT_INITIATED",
             "refund_arn":"205907014017",
             "refund_status":"SUCCESS",
             "status_description":"Refund processed successfully",
             "created_at":"2022-02-28T12:54:25+05:30",
             "processed_at":"2022-02-28T13:04:27+05:30",
             "refund_note":"Test",
             "refund_splits":[
                {
                   "merchantVendorId":"sampleID12345",
                   "amount":1,
                   "percentage":null
                },
                {
                   "merchantVendorId":"otherVendor",
                   "amount":1,
                   "percentage":null
                }
             ],
             "metadata":null,
             "requested_speed":"STANDARD",
             "processed_speed":"STANDARD",
             "service_charge":0.00,
             "service_tax":0.00,
             "forex_conversion_handling_charge":null,
             "forex_conversion_handling_tax":null,
             "forex_conversion_rate":null,
             "charges_currency":null
          },
          terminalDetails:{
             "cf_terminal_id":17269,
             "terminal_phone":"8971520311"
          }
       },
       "event_time":"2022-02-28T13:04:28+05:30",
       "type":"REFUND_STATUS_WEBHOOK"
    }
    ```
  </Tab>

  <Tab title="Version (2023-08-01)">
    ```javascript Version 2023-08-01 theme={"dark"}
    {
    "data":{
        "refund":{
             "cf_refund_id":11325632,
             "cf_payment_id":789727431,
             "refund_id":"refund_sampleorder0413",
             "order_id":"sampleorder0413",
             "refund_amount":2.00,
             "refund_currency":"INR",
             "entity":"Refund",
             "refund_type":"MERCHANT_INITIATED",
             "refund_arn":"205907014017",
             "refund_status":"SUCCESS",
             "status_description":"Refund processed successfully",
             "created_at":"2022-02-28T12:54:25+05:30",
             "processed_at":"2022-02-28T13:04:27+05:30",
             "refund_note":"Test",
             "refund_splits":[
                {
                   "merchantVendorId":"sampleID12345",
                   "amount":1,
                   "percentage":null
                },
                {
                   "merchantVendorId":"otherVendor",
                   "amount":1,
                   "percentage":null
                }
             ],
             "metadata":null,
             "requested_speed":"STANDARD",
             "processed_speed":"STANDARD",
             "service_charge":0.00,
             "service_tax":0.00
        }
       },
       "event_time":"2022-02-28T13:04:28+05:30",
       "type":"REFUND_STATUS_WEBHOOK"
    }
    ```
  </Tab>
</Tabs>

## Auto refund webhook payload

Auto-refund webhooks differ from standard refund webhooks because they handle refunds that occur automatically (like failed payment attempts) rather than manual refunds tied to specific orders. Since these automatic refunds may happen before an order is created, they don't contain the usual order-related data fields that are mandatory in standard refund webhooks,

<Tabs>
  <Tab title="Version 2025-01-01">
    ```javascript Version 2025-01-01 theme={"dark"}
    {
      "data": {
        "auto_refund": {
          "event": "AUTO-REFUND",
          "cf_refund_id": 1243460973,
          "cf_payment_id": "2148333968",
          "bank_reference": "234928698581",
          "order_id": "order_1944392Tpba8y2fHcHVx0SwREojp51Jgr",
          "refund_amount": 39,
          "refund_currency": "INR",
          "refund_type": "PAYMENT_AUTO_REFUND",
          "refund_arn": "205907014017",
          "refund_status": "SUCCESS",
          "status_description": "Auto-Refund processed successfully",
          "refund_reason": "Multiple payments were performed against same order.",
          "created_at": "2023-08-11T14:08:28+05:30",
          "processed_at": null,
          "refund_charge": 0,
          "refund_splits": null,
          "metadata": null,
          "forex_conversion_handling_charge": null,
          "forex_conversion_handling_tax": null,
          "forex_conversion_rate": null,
          "charges_currency": null
        },
        terminalDetails:{
          "cf_terminal_id":17269,
          "terminal_phone":"8971520311"
        }
      },
      "event_time": "2023-08-11T14:10:21+05:30",
      "type": "AUTO_REFUND_STATUS_WEBHOOK"
    }
    ```
  </Tab>

  <Tab title="Version 2023-08-01">
    ```javascript Version 2023-08-01 theme={"dark"}
    {
      "data": {
        "auto_refund": {
          "event": "AUTO-REFUND",
          "cf_refund_id": 1243460973,
          "cf_payment_id": "2148333968",
          "bank_reference": "234928698581",
          "order_id": "order_1944392Tpba8y2fHcHVx0SwREojp51Jgr",
          "refund_amount": 39,
          "refund_currency": "INR",
          "refund_type": "PAYMENT_AUTO_REFUND",
          "refund_arn": "205907014017",
          "refund_status": "SUCCESS",
          "status_description": "Auto-Refund processed successfully",
          "refund_reason": "Multiple payments were performed against same order.",
          "created_at": "2023-08-11T14:08:28+05:30",
          "processed_at": null,
          "refund_charge": 0,
          "refund_splits": null,
          "metadata": null
        }
      },
      "event_time": "2023-08-11T14:10:21+05:30",
      "type": "AUTO_REFUND_STATUS_WEBHOOK"
    }
    ```
  </Tab>
</Tabs>


# Submit Risk Details
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/risk/submit-risk-details

openapi/payments/risk-details.yaml post /risk-details
Use this API to submit comprehensive risk assessment data for an order to Cashfree's risk management system. The API accepts customer details, device information, and industry-specific transaction data for enhanced fraud detection and risk analysis.




# Get All Settlements
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/settlements/get-settlements

openapi/payments/v2025-01-01.yaml post /settlements
Use this API to get all settlement details by specifying the settlement ID, settlement UTR or date range.

<a href="https://www.postman.com/cashfreedevelopers/workspace/cashfree-apis-v2025-01-01/request/40140981-a84ac7e2-d96f-4359-b3c0-94fee322be8b">
  <span aria-label="Postman" />

  Run in Postman: You can also try this API in our Postman Collection.
</a>


# Get Settlements by Order ID
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/settlements/get-settlements-for-order

openapi/payments/v2025-01-01.yaml get /orders/{order_id}/settlements
Use this API to view all the settlements of a particular order.



# Mark Order For Settlement
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/settlements/mark-order-for-settlement

openapi/payments/v2025-01-01.yaml post /orders/settlements
Use this API to pass the CBRICS ID to Cashfree and mark an order for settlement.

<Note>This API supports only merchants linked with the National Stock Exchange (NSE) or Bombay Stock Exchange (BSE).</Note>


# PG Reconciliation
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/settlements/reconcile

openapi/payments/v2025-01-01.yaml post /recon
- Use this API to get the payment gateway reconciliation details with date range.
- It will have events for your payment account




# Settlement Reconciliation
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/settlements/settlement-reconciliation

openapi/payments/v2025-01-01.yaml post /settlement/recon
- Use this API to get settlement reconciliation details using Settlement ID, settlement UTR or date range.
- This API will return events for the settlement IDs you want




# Settlement Webhooks
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/settlements/settlement-webhooks

Learn more about webhooks triggered when a payout to merchant or vendor account happens

We broadly send two types of notifications when a payout happens.

1. Payout to Merchant account
2. Payout to Vendor account (if you are using Easy Split)

## Settlement Webhook

This webhook is triggered whenever there is a payout to your merchant account. The settlement webhooks will notify you about instant settlements in addition to the standard settlement webhooks.  We send webhooks for four different events for a `settlement`.

| Webhook Event | Description |
| - | - |
| SETTLEMENT\_INITIATED | This webhook will be triggered when a settlement is initiated. |
| SETTLEMENT\_SUCCESS | This webhook will be triggered when a settlement is successful. |
| SETTLEMENT\_FAILED | This webhook will be triggered when a settlement has failed. |
| SETTLEMENT\_REVERSED | This webhook will be triggered when a settlement has been reversed. |

The following webhook is sent for other types of settlements as well: instant settlement or an on-demand settlement.

<Tabs>
  <Tab title="Version 2025-01-01">
    ```javascript 2025-01-01 theme={"dark"}
    {
        "data": {
            "settlement": {
                "adjustment": 0,
                "amount_settled": 97.94,
                "payment_amount": 100,
                "payment_from": "2025-02-14 12:00:00",
                "payment_till": "2025-02-14 12:15:00",
                "reason": null,
                "service_charge": 1.75,
                "service_tax": 0.31,
                "settled_on": "2025-02-14T12:35:19+05:30",
                "settlement_type": "STANDARD",   //settlement type //
                "settlement_amount": 97.94,
                "settlement_id": 738,
                "settlement_initiated_on": "2025-02-14T12:35:17+05:30",
                "status": "SUCCESS",
                "utr": 1644822317781212,
                "settlement_charge": 0,    // applicable for instant settlement //
                "settlement_tax": 0,       // applicable for instant settlement //
                "remarks": null,           // applicable for instant settlement //
                "forex_conversion_handling_charge":null,
                "forex_conversion_handling_tax":null,
                "forex_conversion_rate":null,
                "charges_currency":null
            }
        },
        "event_time": "2022-02-08T13:37:34+05:30",
        "type": "SETTLEMENT_SUCCESS"
    }
    ```
  </Tab>

  <Tab title="Version 2023-08-01">
    ```javascript 2023-08-01 theme={"dark"}
    {
        "data": {
            "settlement": {
                "adjustment": 0,
                "amount_settled": 97.94,
                "payment_amount": 100,
                "payment_from": "2022-02-14 12:00:00",
                "payment_till": "2022-02-14 12:15:00",
                "reason": null,
                "service_charge": 1.75,
                "service_tax": 0.31,
                "settled_on": "2022-02-14T12:35:19+05:30",
                "settlement_type": "STANDARD",   //settlement type //
                "settlement_amount": 97.94,
                "settlement_id": 738,
                "settlement_initiated_on": "2022-02-14T12:35:17+05:30",
                "status": "SUCCESS",
                "utr": 1644822317781212,
                "settlement_charge": 0,    // applicable for instant settlement //
                "settlement_tax": 0,       // applicable for instant settlement //
                "remarks": null.           // applicable for instant settlement //
            }
        },
        "event_time": "2022-02-08T13:37:34+05:30",
        "type": "SETTLEMENT_SUCCESS"
    }
    ```
  </Tab>
</Tabs>

<Accordion title="Understand these fields in detail">
  ## Payload field description

  | Field | Description | Example |
  | - | - | - |
  | adjustment | Sum of refunds, disputes, and chargebacks included in this settlement. | 0 |
  | amount\_settled | Total amount settled in this schedule. | 15 |
  | payment\_amount | Total transaction amount considered for settlement. | 15 |
  | payment\_from | Start date and time from which payments are considered for settlement. | 2022-02-14 12:00:00 |
  | payment\_till | End date and time till which payments are considered for settlement. | 2022-02-23 12:00:00 |
  | reason | Reason for failed or reversed settlements. | Transfer mode not valid for beneficiary. |
  | service\_charge | Service charges applicable to the payments included in this settlement. | 2 |
  | service\_tax | Service tax applicable to the payments included in this settlement. | 0 |
  | settled\_on | Date and time when the settlement was processed. | 2022-03-17T14:21:18+05:30 |
  | settlement\_type | Type of settlement (e.g., INSTANT). | INSTANT |
  | settlement\_amount | Net settlement amount for the payments included in this settlement. | 13 |
  | settlement\_id | Unique settlement ID generated by Cashfree. | 1155353 |
  | settlement\_initiated\_on | Date on which settlement was initiated. | 2022-03-17T14:29:21+05:30 |
  | status | Status of the settlement (INITIATED, SUCCESS, FAILED, or REVERSED). | SUCCESS |
  | utr | Unique transaction reference number provided by the bank for the settlement. | N076221079016329 |
  | settlement\_charge | Additional charge applicable for instant settlement. | 10.10 |
  | settlement\_tax | Settlement tax applicable for instant settlement. | 01.97 |
  | remarks | Any remarks specified by the merchant. | Settlement Initiated |
  | event\_time | Time when the settlement webhook was triggered. | 2022-03-17T14:29:23+05:30 |
  | type | Type of webhook event (SETTLEMENT\_INITIATED, SETTLEMENT\_SUCCESS, SETTLEMENT\_FAILED, or SETTLEMENT\_REVERSED). | SETTLEMENT\_SUCCESS |
</Accordion>

## Vendor Settlement Webhook

<Warning>This section only applies to merchants using our Easy Split product </Warning>

These settlement webhooks automate notifications when vendor settlements are initiated, successfully processed, failed, or reversed.

| Webhook Event | Description |
| :- | :- |
| VENDOR\_SETTLEMENT\_INITIATED | This webhook will be triggered when a vendor settlement is initiated. |
| VENDOR\_SETTLEMENT\_SUCCESS | This webhook will be triggered when a vendor settlement is successful. |
| VENDOR\_SETTLEMENT\_FAILED | This webhook will be triggered when a vendor settlement has failed. |
| VENDOR\_SETTLEMENT\_REVERSED | This webhook will be triggered when a vendor settlement has been reversed. |

```javascript Vendor Settlement Webhook theme={"dark"}
{
    "data": {
        "settlement": {
            "adjustment": 0,
            "amount_settled": 10,
            "payment_amount": null,
            "payment_from": "2022-05-26",
            "payment_till": "2022-05-26",
            "reason": null,
            "service_charge": 0.05,
            "service_tax": 0.01,
            "settled_on": "2022-05-26T15: 06: 14+05: 30",
            "settled_orders_count": 2,
            "settlement_amount": 10,
            "settlement_id": 6151,
            "settlement_initiated_on": "2022-05-26T15: 06: 09+05: 30",
            "settlement_type": null,
            "status": "CREATED",
            "utr": null,
            "vendor_id": "Vendor_123adj4dr4osn23fn",
            "vendor_transaction_amount": 10,
            "account_mode": "BANK",
            "account_number": "XXXXXXX1234",
            "ifsc": "HDFC0000001",
            "vpa": null
        },
        "event_time": "2022-05-26T15:06:15+05:30",
        "type": "VENDOR_SETTLEMENT_INITIATED"
    }
}
```

## Transaction Wise Settlement Webhook

<Warning>This section only applies to merchants using our Transaction Wise Settlement model</Warning>

These TWS(Transaction Wise Settlement) webhooks are triggered when settlement are initiated, successfully processed, failed, or reversed.

| Webhook Event | Description |
| :- | :- |
| TRANSACTION\_WISE\_SETTLEMENT\_INITIATED | This webhook will be triggered when a TWS is initiated. |
| TRANSACTION\_WISE\_SETTLEMENT\_SUCCESS | This webhook will be triggered when a TWS is successful. |
| TRANSACTION\_WISE\_SETTLEMENT\_FAILED | This webhook will be triggered when a TWS has failed. |
| TRANSACTION\_WISE\_SETTLEMENT\_REVERSED | This webhook will be triggered when a TWS has been reversed. |

```javascript Transaction Wise Settlement Webhook theme={"dark"}
{
    "data":{
         "order":{
            "order_id":"order_OFR_2",
            "order_amount":2,
            "order_currency":"INR",
            "order_tags":null
         },
         "payment":{
            "cf_payment_id":"1453002795",
            "payment_status":"SUCCESS",
            "payment_amount":1,
            "payment_currency":"INR",
            "payment_message":"00::Transaction success",
            "payment_time":"2022-12-15T12:20:29+05:30",
            "bank_reference":"234928698581",
            "auth_id":null,
            "payment_method":{
               "upi":{
                  "channel":"collect",
                  "upi_id":"suhasg6@ybl",
                  "upi_instrument":"UPI_CREDIT_CARD",
                  "upi_instrument_number":"masked card number",
                  "upi_payer_ifsc":"SBI0025434",
                  "upi_payer_account_number":"XXXXX0231"
               }
            },
            "payment_group":"upi"
         },
         "customer_details":{
            "customer_name":null,
            "customer_id":"7112AAA812234",
            "customer_email":"test@gmail.com",
            "customer_phone":"9908734801"
         },
         "payment_gateway_details":null,
         "payment_offers":null,
         "settlement": {
             "settlement_id": "1639789947",
             "status": "SUCCESS",
             "utr": "1212743972438575",
             "payment_amount": 500.00,
             "settlement_initiated_on": "2025-03-15T22:21:29+05:30",
             "settled_on": "2025-03-15T22:22:30+05:30",
             "reason": "Transfer completed successfully",
             "adjustment": 0.00,
             "settlement_amount": 441.00,
             "service_charge": 50.00,
             "service_tax": 9.00,
             "amount_settled": 441.00,
             "payment_from": "2025-03-15T22:21:29+05:30",
             "payment_till": "2025-03-15T22:21:29+05:30",
             "settlement_type": "NORMAL_SETTLEMENT",
             "remarks": null,
             "settlement_charge": 0.00,
             "settlement_tax": 0.00
         }
       },
         "event_time": "2025-04-10T22:22:06+05:30",
         "type": "TRANSACTION_WISE_SETTLEMENT_SUCCESS"
       }
}
```


# Fetch Settlement Simulation
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/simulation/fetch-settlement-simulation

openapi/payments/v2025-01-01.yaml get /simulate/settlement/{simulation_id}
Use this API to fetch the details of a simulated settlement.



# Fetch Simulation
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/simulation/fetch-simulation

openapi/payments/v2025-01-01.yaml get /simulate/{simulation_id}
Use this API to fetch simulated payment details.



# Simulate Payment
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/simulation/simulate-payment

openapi/payments/v2025-01-01.yaml post /simulate
Use this API to simulate payment. To use this API you should first create an order using the Create Order API. Also, you need to create a payment with the same order.



# Simulate Settlement Payment
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/simulation/simulate-settlement

openapi/payments/v2025-01-01.yaml post /simulate/settlement
Use this API to simulate a settlement in the sandbox environment. First, create a successful order, and then call this API with the order ID to simulate the settlement for that order.



# Create Terminal
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/softpos/create-terminal

openapi/payments/v2025-01-01.yaml post /terminal
Use this API to create new terminals to use softPOS.



# Create Terminal Transaction
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/softpos/create-terminal-transaction

openapi/payments/v2025-01-01.yaml post /terminal/transactions
Use this API to create a new terminal transaction. To use this API you should first create an order using the Create Order API. Also, you need to enter the terminal details while creating the order and pass the same terminal information while creating a transaction using the below mentioned API.



# Demap Soundbox Vpa
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/softpos/demap-soundbox-vpa

openapi/payments/v2025-01-01.yaml post /terminal/demap/soundbox
Use this API to demap a device from soundbox.



# Fetch Terminal QR Codes
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/softpos/fetch-terminal-qr-codes

openapi/payments/v2025-01-01.yaml get /terminal/qrcodes
You can fetch all the StaticQRs corresponding to given terminal id or phone number. Provide either the terminal_phone_no or terminal_id in the request.



# Fetch Terminal Soundbox vpa
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/softpos/fetch-terminal-soundbox-vpa

openapi/payments/v2025-01-01.yaml get /terminal/soundbox/qrcodes
You can fetch all the active and mapped SoundboxVpa corresponding to given terminal id or deviceSerialNo. Provide either the device_serial_no or cf_terminal_id in the request.



# Get Terminal Payments
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/softpos/get-terminal-payments

openapi/payments/v2025-01-01.yaml post /terminal/payments
Use this API to fetch a paginated list of terminal payment transactions. You can filter results by date range, terminal details, payment status, and other criteria.

<snippet>snippets/related-topics-loader.mdx</snippet>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/payments/previous/v2025-01-01/softpos/get-terminal-transaction">Get Terminal Transaction API</a></li>
    <li><a href="/docs/api-reference/payments/previous/v2025-01-01/softpos/create-terminal-transaction">Create Terminal Transaction API</a></li>
    <li><a href="/docs/payments/softpos/introduction">softPOS Overview</a></li>
  </ul>
</div>


# Get Terminal Status using Phone Number
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/softpos/get-terminal-status-using-phone-number

openapi/payments/v2025-01-01.yaml get /terminal/{terminal_phone_no}
Use this API to view all details of a terminal.



# Get Terminal Transaction
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/softpos/get-terminal-transaction

openapi/payments/v2025-01-01.yaml get /terminal/{cf_terminal_id}/payments
Use this API to get  terminal transaction.



# Onboard Soundbox Vpa
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/softpos/onboard-soundbox-vpa

openapi/payments/v2025-01-01.yaml post /terminal/soundbox
Use this API to onboard a terminal Vpa to soundbox.



# SoftPOS Webhooks
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/softpos/softpos-webhooks

Learn in detail about softPOS webhooks.

Webhooks are server callbacks to your server from Cashfree. Webhooks are event-based and are sent when specific events related to the transaction happen.

## Terminal Status Update Webhook

The new terminal status update webhook notifies you about the terminal status update, and gives you comprehensive information about terminal updates.

```java theme={"dark"}
{
    "data":{
        "added_on":"2024-03-07 15:11:02"
        "cf_terminal_id":1234
        "last_updated_on":"2024-04-26 12:16:08"
        "terminal_id":1233
        "terminal_name":"ABC"
        "terminal_phone":"9696969696"
        "terminal_status":"PROVISIONALLY_ACTIVE"
        "terminal_type":"STOREFRONT"
        "review_remarks":"approved"
    }
    "event_time":"2024-04-26T12:16:08+05:30"
    "type":"TERMINAL_STATUS_UPDATE"
}
```

***


# Update Soundbox Vpa
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/softpos/update-soundbox-vpa

openapi/payments/v2025-01-01.yaml patch /terminal/{cf_terminal_id}/soundbox
Use this API to update a terminal Vpa to soundbox.



# Update Terminal
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/softpos/update-terminal

openapi/payments/v2025-01-01.yaml patch /terminal/{cf_terminal_id}
Use this API to update the terminal details. Email, Phone Number, and Terminal Meta are updatable for "Storefront". Only account status change is possible in case of "Agent".



# Update Terminal Status
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/softpos/update-terminal-status

openapi/payments/v2025-01-01.yaml patch /terminal/{cf_terminal_id}/status
Use this API to update the terminal status.



# Upload Terminal Docs
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/softpos/upload-terminal-docs

openapi/payments/v2025-01-01.yaml post /terminal/{cf_terminal_id}/docs
Use this API to upload the terminal documents.



# Get Vendor Balance Transfer Charges
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/split/billing/balance-transfer-charges

openapi/payments/v2025-01-01.yaml get /easy-split/amount/{amount}/charges
This API returns the applicable service charge and service tax for a vendor balance transfer, based on the provided amount and rate type.



# Split After Payment
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/split/configuration/split-after-payment

openapi/payments/v2025-01-01.yaml post /easy-split/orders/{order_id}/split
The Split After Payment API splits payments to vendors after customers successfully complete a payment. After you receive a successful payment confirmation, wait 2 minutes before you call this API endpoint.



# Create Static Split Configuration
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/split/configuration/static-split

openapi/payments/v2025-01-01.yaml post /easy-split/static-split
This API will create a static split scheme wherein you can define the split type and the vendor-wise split percentage.



# Easy Split Overview
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/split/easy-split-overview

Explore Cashfree's Easy Split APIs (v2025-01-01) to split payments across vendors, manage vendor accounts, and reconcile settlements automatically.

Easy Split automates the splitting of payments with vendors and partners on time. Collect payments from customers, and set up a flexible schedule options to disburse payments to your vendors. Get detailed reports on the transactions, settlements, refunds, vendor payments and adjustments.

**How does Easy Split work?**

<img alt="" />

**You can perform the following tasks using Easy Split:**

* Add and manage all your vendors efficiently
* Split payments and settle them into multiple vendor accounts using the available schedule options cycles
* Check on-demand vendor balance and settle the money into the vendor accounts instantly
* Vendor reconciliation

The table below provides the list of Easy Split APIs along with their description:

**Vendor APIs**

| API Name | Description |
| :- | :- |
| [Create Vendor](/docs/api-reference/payments/previous/v2025-01-01/split/vendors/create) | Create Vendor API creates a new vendor in your Easy Split account. |
| [Update Vendor Details](/docs/api-reference/payments/previous/v2025-01-01/split/vendors/update) | Update Vendor Details API updates the existing vendor details. |
| [Get All Vendor Details](/docs/api-reference/payments/previous/v2025-01-01/split/vendors/get) | Get All Vendor Details API gets the details of all the vendors associated with that Easy Split account. |
| [Create On Demand Transfer](/docs/api-reference/payments/previous/v2025-01-01/split/settlements/on-demand-transfer) | Create On Demand Transfer API initiates a balance transfer request between merchant and vendor. |
| [Create Refund](/docs/api-reference/payments/previous/v2025-01-01/refunds/create) | Create Refund API creates a new refund. |

**Split Order APIs**

| API Name | Description |
| :- | :- |
| [Create Static Split](/docs/api-reference/payments/previous/v2025-01-01/split/configuration/static-split) | Use this API to create a split at order level. |
| [Split After Payment](/docs/api-reference/payments/previous/v2025-01-01/split/configuration/split-after-payment) | Split After Payment API creates a split after the payment is completed. |
| [Get Split and Settlement Details by Order ID](/docs/api-reference/payments/previous/v2025-01-01/split/settlements/split-details) | Get Split and Settlement Details by Order ID API gets details of the split, settled and unsettled transactions of each vendor using the Order ID. |

**Settlement APIs**

| API Name | Description |
| :- | :- |
| [Get Vendor Settlement Details](/docs/api-reference/payments/previous/v2025-01-01/split/settlements/split-details) | Get Vendor Settlement Details (same endpoint as split-order recon; specify a settlement ID to filter results or leave blank for all) |

**On Demand Settlement APIs**

| API Name | Description |
| :- | :- |
| [Get On Demand Balance](/docs/api-reference/payments/previous/v2025-01-01/split/vendors/get-on-demand-balance) | Get On Demand Balance API fetches the available merchant and vendor balances. |
| [Create On Demand Transfer](/docs/api-reference/payments/previous/v2025-01-01/split/settlements/on-demand-transfer) | Create On Demand Transfer API initiates a balance transfer request between merchant and vendor. |

**Reconciliation APIs**

| API Name | Description |
| :- | :- |
| [Vendor Reconciliation](/docs/api-reference/payments/previous/v2025-01-01/reconciliation/vendor-recon) | Vendor Reconciliation API fetches vendor recon details; supports split-order lookups by settlement ID, time-period queries, and vendor-specific intervals. |


# Easy Split - Postman Collection
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/split/easy-split-postman-collection

Download the Cashfree Easy Split Postman collection for v2025-01-01 and watch a walkthrough video to quickly test vendor split payment APIs.

Get started quickly with Cashfree's Easy Split APIs by downloading the collection and importing it in Postman.

<a href="https://gocashassets.s3.ap-south-1.amazonaws.com/postmancollection/Easy_Split_Postman_Collection.zip">Download Cashfree Easy Split Postman Collection</a>

Watch the video below to learn how to setup API

<iframe title="YouTube video player" />


# End Points
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/split/end-points

Find the Cashfree Payment Gateway API base URLs for test and production (v2025-01-01), and learn how to verify your API key credentials.

Cashfree uses API keys to allow access to the API. Once you have signed up at our merchant site, you can see your AppId and SecretKey.

Cashfree expects the API key to be included in all API requests to the server. Use the endpoint /api/v1/credentials/verify to verify your credentials.

| Environment | Base URL |
| :- | :- |
| Production | [https://api.cashfree.com/pg](https://api.cashfree.com/pg) |
| Test | [https://sandbox.cashfree.com/pg](https://sandbox.cashfree.com/pg) |


# Create On Demand Transfer
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/split/settlements/on-demand-transfer

openapi/payments/v2025-01-01.yaml post /easy-split/vendors/{vendor_id}/transfer
The Create On Demand Transfer API will create a new on-demand request either from to the merchant or from to the vendor.



# Get Split and Settlement Details by OrderID v2.0
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/split/settlements/split-details

openapi/payments/v2025-01-01.yaml post /split/order/vendor/recon
Use this API to get all the split details, settled and unsettled transactions details of each vendor who were part of a particular order by providing order Id or start date and end date.



# Upload Vendor Docs
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/split/vendors/add-document

openapi/payments/v2025-01-01.yaml post /easy-split/vendor-docs/{vendor_id}
Use this API to upload KYC documents of a specific vendor.



# Create vendor
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/split/vendors/create

openapi/payments/v2025-01-01.yaml post /easy-split/vendors
Use this API to create a new vendor to your EasySplit account along with the KYC details. Provide KYC details such as account_type, business_type, gst, cin, pan, passport number and so on.

<Tip>
  Keep the following points in mind when you create a vendor:

  * Use [test account details](/docs/payments/split/data-to-test#sample-bank-account-numbers-upi-and-vpa) in Sandbox mode.
  * Use test GST and PAN numbers from the [test details](/docs/payments/split/data-to-test#test-details) page.
  * Vendors that you create in the Sandbox environment with test bank account and KYC details move to `ACTIVE` status automatically after 10 minutes.
  * If a vendor doesn't move to `ACTIVE` status within 24 hours in Production mode, fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1).
</Tip>


# Download Vendor Documents
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/split/vendors/download-documents

openapi/payments/v2025-01-01.yaml get /easy-split/vendor-docs/{vendor_id}/download/{doc_type}
Use this API to download the uploaded KYC documents of that particular vendor. Provide the document type. Click the link from the sample request to download the KYC document.



# Get Vendor All Details
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/split/vendors/get

openapi/payments/v2025-01-01.yaml get /easy-split/vendors/{vendor_id}
Use this API to get the details of a specific vendor associated with your Easy Split account.



# Get Vendor All Documents Status
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/split/vendors/get-document

openapi/payments/v2025-01-01.yaml get /easy-split/vendor-docs/{vendor_id}
Use this API to fetch the details of all the KYC details of a particular vendor.



# Get On Demand Balance
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/split/vendors/get-on-demand-balance

openapi/payments/v2025-01-01.yaml get /easy-split/vendors/{vendor_id}/balances
This API fetches the available amount with the merchant, vendor, and the unsettled amount for the merchant as well as the vendor.



# Update vendor Details
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/split/vendors/update

openapi/payments/v2025-01-01.yaml patch /easy-split/vendors/{vendor_id}
Use this API to edit the existing vendor details added to your EasySplit account. You can edit vendor details such as name, email, phone number, upi details, and any of the KYC details.



# Overview
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/split/webhooks/overview

This section consists of the Easy Split Webhooks.

Webhooks are server callbacks to your server from Cashfree. Webhooks are event-based and are sent when specific events happen.

The table below lists the various webhook events:

| Webhook Name | Description |
| :- | :- |
| [Vendor Settlement Webhook](/docs/api-reference/payments/previous/v2025-01-01/split/webhooks/vendor-settlement-webhooks) | Configure vendor settlement webhooks to receive automated notifications when vendor settlements are initiated, successfully processed, failed, or reversed. |
| [Vendor Status Change Webhook](/docs/api-reference/payments/previous/v2025-01-01/split/webhooks/vendor-status-change-webhooks) | Configure vendor status change webhooks to receive automated notifications when vendor status is changed. |


# Vendor Settlement Webhook
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/split/webhooks/vendor-settlement-webhooks

This chapter explains the vendor settlement webhooks.

Configure vendor settlement webhooks to receive automated notifications when vendor settlements are initiated, successfully processed, failed, or reversed.

The webhook notifications are sent on all the URLs added and enabled in the settlement webhook. You can add new URLs and enable or disable existing URLs for settlement webhook at any time and it will reflect instantaneously.

The table below lists the webhook events available for settlements.

| Webhook Event | Description |
| :- | :- |
| VENDOR\_SETTLEMENT\_INITIATED | This webhook will be triggered when a vendor settlement is initiated. |
| VENDOR\_SETTLEMENT\_SUCCESS | This webhook will be triggered when a vendor settlement is successful. |
| VENDOR\_SETTLEMENT\_FAILED | This webhook will be triggered when a vendor settlement has failed. |
| VENDOR\_SETTLEMENT\_REVERSED | This webhook will be triggered when a vendor settlement has been reversed. |

## Vendor settlement initiated

SETTLEMENT\_INITIATED webhook is triggered when a settlement has been initiated by Cashfree.

```
{
    "data": {
        "settlement": {
            "settlement_id": 49703,
            "status": "CREATED",
            "utr": "1686217237243457",
            "payment_amount": null,
            "settlement_initiated_on": "2023-06-08T15:10:35+05:30",
            "settlement_type": null,
            "settled_on": "null",
            "reason": null,
            "adjustment": 100.00,
            "settlement_amount": 600.00,
            "service_charge": 0.50,
            "service_tax": 0.09,
            "amount_settled": null,
            "payment_from": "2023-06-08",
            "payment_till": "2023-06-08",
            "vendor_id": "esSettlementsAutomationVendor",
            "vendor_transaction_amount": 500.00,
            "account_mode": "BANK",
            "settled_orders_count": 1,
            "account_number": "XXXXXXX1234",
            "ifsc": "HDFC0000001",
            "vpa": null
        }
    },
    "event_time": "2023-06-08T15:10:37+05:30",
    "type": "VENDOR_SETTLEMENT_CREATED"
}
```

## Vendor settlement success

```
{
    "data": {
        "settlement": {
            "settlement_id": 49703,
            "status": "SUCCESS",
            "utr": "1686217237243457",
            "payment_amount": null,
            "settlement_initiated_on": "2023-06-08T15:10:35+05:30",
            "settlement_type": null,
            "settled_on": "2023-06-08T15:10:37+05:30",
            "reason": null,
            "adjustment": 100.00,
            "settlement_amount": 600.00,
            "service_charge": 0.50,
            "service_tax": 0.09,
            "amount_settled": 600.00,
            "payment_from": "2023-06-08",
            "payment_till": "2023-06-08",
            "vendor_id": "esSettlementsAutomationVendor",
            "vendor_transaction_amount": 500.00,
            "account_mode": "UPI",
            "settled_orders_count": 1,
            "account_number": null,
            "ifsc": null,
            "vpa": "9898989898@ybl"
        }
    },
    "event_time": "2023-06-08T15:10:37+05:30",
    "type": "VENDOR_SETTLEMENT_SUCCESS"
}
```

***

## Vendor settlement failed

```
{
    "data": {
        "settlement": {
            "settlement_id": 49703,
            "status": "FAILED",
            "utr": "1686217237243457",
            "payment_amount": null,
            "settlement_initiated_on": "2023-06-08T15:10:35+05:30",
            "settlement_type": null,
            "settled_on": "null",
            "reason": null,
            "adjustment": 100.00,
            "settlement_amount": 600.00,
            "service_charge": 0.50,
            "service_tax": 0.09,
            "amount_settled": null,
            "payment_from": "2023-06-08",
            "payment_till": "2023-06-08",
            "vendor_id": "esSettlementsAutomationVendor",
            "vendor_transaction_amount": 500.00,
            "account_mode": "BANK",
            "settled_orders_count": 1,
            "account_number": "XXXXXXX1234",
            "ifsc": "HDFC0000001",
            "vpa": null
        }
    },
    "event_time": "2023-06-08T15:10:37+05:30",
    "type": "VENDOR_SETTLEMENT_FAILED"
}
```

***

## Vendor settlement reversed

```
{
    "data": {
        "settlement": {
            "settlement_id": 49703,
            "status": "REVERSED",
            "utr": "1686217237243457",
            "payment_amount": null,
            "settlement_initiated_on": "2023-06-08T15:10:35+05:30",
            "settlement_type": null,
            "settled_on": "null",
            "reason": Failed from bank end,
            "adjustment": 100.00,
            "settlement_amount": 600.00,
            "service_charge": 0.50,
            "service_tax": 0.09,
            "amount_settled": null,
            "payment_from": "2023-06-08",
            "payment_till": "2023-06-08",
            "vendor_id": "esSettlementsAutomationVendor",
            "vendor_transaction_amount": 500.00,
            "account_mode": "BANK",
            "settled_orders_count": 1,
            "account_number": "XXXXXXX1234",
            "ifsc": "HDFC0000001",
            "vpa": null
        }
    },
    "event_time": "2023-06-08T15:10:37+05:30",
    "type": "VENDOR_SETTLEMENT_REVERSED"
}
```

***

## Payload field description

| Field | Description | Example |
| - | - | - |
| adjustment | The sum of refunds, disputes, and chargeback part of this settlement is displayed here. | 0 |
| amount\_settled | The total amount that is settled in this schedule option. | 50 |
| payment\_amount | Total transaction amount considered for settlement. | 100 |
| payment\_from | Start date from which the payments are considered for settlement. | 2022-03-15 |
| payment\_till | End date till which the payments are considered for settlement. | 2022-03-23 |
| reason | Reason for failed and reversed settlements. | Transfer mode is not valid for beneficiary. |
| service\_charge | Service charges are applicable for the payments that are included in this settlement. | 2 |
| service\_tax | Service tax is applicable for the payments that are included in this settlement. | 0.50 |
| settled\_on | Date and time at which the settlement was processed. | 2022-03-17T14:21:18+05:30 |
| settlement\_amount | The sum of net settlement amount for the payments part of this settlement. | 13 |
| settlement\_id | Cashfree settlement ID | 1155353 |
| settlement\_initiated\_on | The date on which settlement was initiated. | 2022-03-17T14:29:21+05:30 |
| status | Status of the settlement (either INITIATED, SUCCESS, FAILED, or REVERSED) | SUCCESS |
| utr | The unique transaction reference number is given by the bank for the settlement. | N076221079016329 |
| vendor\_id | Reference ID as shared by you when onboarding the vendor. | IS\_1hour\_Upi |
| vendor\_transaction\_amount | Transaction amount split of vendor | 50 |
| event\_time | Time at which settlement webhook was initiated. | 2022-03-17T14:29:23+05:30 |
| type | Type of webhook - VENDOR\_SETTLEMENT\_INITIATED, VENDOR\_SETTLEMENT\_SUCCESS, VENDOR\_SETTLEMENT\_FAILED, or VENDOR\_SETTLEMENT\_REVERSED. | VENDOR\_SETTLEMENT\_SUCCESS |

## Reasons for failed and reversed settlements

| Reason | Category | Description |
| :- | :- | :- |
| BANK\_GATEWAY\_ERROR | Bank | Technical error at the bank |
| BENE\_BANK\_DECLINED | Bank | Rejected by Beneficiary bank due to business reasons |
| FAILED | Bank | No explicit failure reason from the bank |
| INVALID\_IFSC\_FAIL | Customer | Invalid ifsc code provided for bank account |
| INVALID\_ACCOUNT\_FAIL | Customer | Bank account is invalid |
| RETURNED\_FROM\_BENEFICIARY | Bank | Immediate reversal from the beneficiary bank |
| INSUFFICIENT\_BALANCE | Vendor | Your balance is exhausted, need to add funds |
| IMPS\_MODE\_FAIL | Bank | IMPS mode not supported for the beneficiary |
| RTGS\_MODE\_FAIL | Bank | RTGS mode not supported (only for RTGS) |
| REINITIALIZE\_TRANSFER\_LATER | Bank | Technical error at the bank, retry later |
| NRE\_ACCOUNT\_FAIL | Customer | Customer bank account is an NRE account |
| ACCOUNT\_BLOCKED | Customer | Customer bank account is blocked |
| DEST\_LIMIT\_REACHED | Bank | Transfer limit to beneficiary exceeded |
| INVALID\_MODE\_FAIL | Bank | Transfer mode not valid for beneficiary |
| NPCI\_UNAVAILABLE | Bank | NPCI in unavailable |
| BENEFICIARY\_BANK\_OFFLINE | Bank | Beneficiary bank is offline |
| INVALID\_AMOUNT\_FAIL | Vendor | Amount is invalid for the given transfer mode |
| SUSPECTED\_TRANSFER | Customer | Suspicious transfer identified |
| BENE\_NAME\_DIFFERS | Customer | Beneficiary name not matching with bank records |
| DISABLED\_MODE | Vendor | Transfer mode not enabled for the account |
| AMAZON\_AMOUNT\_EXCEED | Vendor | Amount should be less than 10000 for Amazon Pay mode |
| BENEFICIARY\_BLACKLISTED | Vendor | Beneficiary is blacklisted |
| PAYOUT\_INACTIVE | Vendor | Payout account is not active |
| INVALID\_TRANSFER\_AMOUNT | Vendor | Transfer amount is invalid |
| BENEFICIARY\_NOT\_EXIST | Vendor | Beneficiary does not exist |
| BENEFICIARY\_INVALID\_MODE | Vendor | Mode Not valid for Beneficiary |
| INVALID\_BENE\_ACCOUNT\_OR\_IFSC | Vendor | Invalid bank account number or ifsc provided |
| BENEFICIARY\_NAME\_DIFFERS | Customer | Beneficiary name not matching with bank records |
| ANY\_OTHER\_REASON | Bank | No reason provided for the failure/reversal |
| INVALID\_OR\_NO\_SUCH\_ACCOUNT\_TYPE | Customer | Invalid account |

***

## Signature verification

The signature must be used to verify if the request has not been tampered with. To verify the signature at your end, you will need your Cashfree PG secret key along with the payload.

timestamp is present in the header x-webhook-timestamp\
Actual signature is present in the header x-webhook-signature

```
"headers": {
        "host": "gamma.cashfree.com",
        "x-request-id": "ad4dc1e65f8901302455b247237a667a",
        "x-real-ip": "172.0.57.13",
        "x-forwarded-for": "172.0.57.13",
        "x-forwarded-host": "gamma.cashfree.com",
        "x-forwarded-port": "80",
        "x-forwarded-proto": "http",
        "x-forwarded-scheme": "http",
        "x-scheme": "http",
        "x-original-forwarded-for": "52.66.25.127",
        "content-length": "592",
        "accept": "_/_",
        "content-type": "application/json",
        "user-agent": "ReactorNetty/1.0.30",
        "x-datadog-parent-id": "4281924148563621550",
        "x-datadog-sampling-priority": "1",
        "x-datadog-trace-id": "228569355002181270",
        "x-webhook-signature": "Xm0YzEJCRsh0XvIEK12D4FqpmC60cReKoqPBn424kV0=",
        "x-webhook-timestamp": "1686217237543",
        "x-webhook-version": "2022-09-01"
    }
```

Watch this video to learn more on Vendor Webhooks:

<div>
  <iframe title="YouTube video player" />
</div>


# Vendor Status Change Webhook
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/split/webhooks/vendor-status-change-webhooks

This chapter explains the vendor status change webhook.

Configure vendor status change webhooks to receive automated notifications when vendor status is changed.

The webhook notifications are sent on all the URLs added and enabled in the vendor status change webhook. You can add new URLs and enable or disable existing URLs for vendor status change webhook at any time and it will reflect instantaneously.

The table below lists the webhook events available for vendor status change.

| Webhook Event | Description |
| :- | :- |
| VENDOR\_STATUS\_UPDATE | This webhook will be triggered whenever there is a change in the status of the vendor. |

# Vendor Status Update

<Tabs>
  <Tab title="Version (2025-01-01)">
    ```javascript 2025-01-01 theme={"dark"}
    {
      "data": {
        "merchant_id": 152707,
        "merchant_vendor_id": "status002",
        "email": "[john.doe@cashfree.com]()",
        "updated_status": "ACTION_REQUIRED",
        "past_status": "IN_BENE_CREATION",
        "account_holder": "JOHN DOE",
        "phone": "9876554927",
        "name": "BOB HOPE",
        "product_type": "PG",
        "max_split": 100,
        "account_number": null,
        "ifsc": null,
        "dashboard_access": false,
        "vpa": "success@upi",
        "account_type": "Individual",
        "business_type": "Travel and Hospitality",
        "updated_by": "AUTOMATED",
        "document_status": {
          "PAN": "VERIFIED",
          "GSTIN": "DUE_CURRENTLY"
        }
      },
      "event_time": "2023-06-08T15:10:37+05:30",
      "type": "VENDOR_STATUS_UPDATE"
    }
    ```
  </Tab>

  <Tab title="Version (2023-08-01)">
    ```javascript Version 2023-08-01 theme={"dark"}
    {
      "data": {
        "merchant_id": 152707,
        "merchant_vendor_id": "status002",
        "email": "[john.doe@cashfree.com]()",
        "updated_status": "ACTION_REQUIRED",
        "past_status": "IN_BENE_CREATION",
        "account_holder": "JOHN DOE",
        "phone": "9876554927",
        "name": "BOB HOPE",
        "product_type": "PG",
        "max_split": 100,
        "account_number": null,
        "ifsc": null,
        "dashboard_access": false,
        "vpa": "success@upi",
        "account_type": "Individual",
        "business_type": "Travel and Hospitality",
        "updated_by": "AUTOMATED",
        "document_status": {
          "PAN": "VERIFIED",
          "GSTIN": "DUE_CURRENTLY"
        }
      },
      "event_time": "2023-06-08T15:10:37+05:30",
      "type": "VENDOR_STATUS_UPDATE"
    }
    ```
  </Tab>
</Tabs>

***

# Payload Field Description

| Field | Description | Example |
| - | - | - |
| merchant\_id | Cashfree Merchant ID. | 152707 |
| merchant\_vendor\_id | Reference ID as shared by you when onboarding the vendor. | IS\_1hour\_Upi |
| email | Email of the vendor. | [test@gmail.com](mailto:test@gmail.com) |
| updated\_status | Current status of the vendor. | ACTIVE |
| past\_status | Previous status of the vendor. | ACTION\_REQUIRED |
| account\_holder | Name of the account holder associated with the vendor. | John Doe |
| phone | Contact phone number of the vendor. | 9876554927 |
| name | Name of the vendor. | BOB HOPE |
| product\_type | Type of product offered to the vendor | PG |
| max\_split | The maximum percentage of the amount shared with a vendor in any order. | 100 |
| account\_number | Vendor's bank account number. | 12345678909 |
| ifsc | IFSC (Indian Financial System Code) associated with the vendor's bank. | SBIN1231935 |
| dashboard\_access | Access level to the dashboard for the vendor (if applicable). | FALSE |
| vpa | VPA of the vendor for UPI transactions. | success\@upi |
| account\_type | Type of the vendor's account. | Individual |
| business\_type | Type of business conducted by the vendor. | Travel and Hospitality |
| updated\_by | Entity or process that initiated the status update. | AUTOMATED |
| document\_status | Status of any associated documents for the vendor. | "PAN": "VERIFIED" "GSTIN": "DUE\_CURRENTLY" |

***

# Signature Verification

The signature must be used to verify if the request has not been tampered with. To verify the signature at your end, you will need your Cashfree PG secret key along with the payload.

timestamp is present in the header x-webhook-timestamp\
Actual signature is present in the header x-webhook-signature

```
"headers": {
        "host": "gamma.cashfree.com",
        "x-request-id": "ad4dc1e65f8901302455b247237a667a",
        "x-real-ip": "172.0.57.13",
        "x-forwarded-for": "172.0.57.13",
        "x-forwarded-host": "gamma.cashfree.com",
        "x-forwarded-port": "80",
        "x-forwarded-proto": "http",
        "x-forwarded-scheme": "http",
        "x-scheme": "http",
        "x-original-forwarded-for": "52.66.25.127",
        "content-length": "592",
        "accept": "_/_",
        "content-type": "application/json",
        "user-agent": "ReactorNetty/1.0.30",
        "x-datadog-parent-id": "4281924148563621550",
        "x-datadog-sampling-priority": "1",
        "x-datadog-trace-id": "228569355002181270",
        "x-webhook-signature": "Xm0YzEJCRsh0XvIEK12D4FqpmC60cReKoqPBn424kV0=",
        "x-webhook-timestamp": "1686217237543",
        "x-webhook-version": "2022-09-01"
    }

```

Watch this video to learn more on Vendor Webhooks


# End Points
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/subscription/endpoints

Find the Cashfree Subscriptions API base URLs for test and production environments (v2025-01-01), plus supported API versions and key usage.

Cashfree uses API keys to control access to the API. After you sign up on the merchant site, you'll receive your `AppId` and `SecretKey`.

Include your API key in all requests to the server. Use the endpoint **`/api/v1/credentials/verify`** to verify your credentials.

All API responses are in JSON format. POST requests must include the header `Content-Type: application/json`.

| Environment | Base URL |
| - | - |
| Test | `https://sandbox.cashfree.com/pg` |
| Production | `https://api.cashfree.com/pg` |
| Latest version | v5, 2025-01-01<br />Previous versions: 2023-08-01, 2021-05-21, 2022-01-01, 2022-09-01 |


# Error Codes and Reasons
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/subscription/error-codes

Learn more about subscription error codes, failure reasons, and their resolutions

## Error codes

The following are the common error codes returned by the Subscription APIs:

| Error Code | Description | Resolution |
| - | - | - |
| `subscription_id_missing` | Subscription ID is required but missing in the request | Ensure the subscription ID is included in your API request |
| `plan_id_missing` | Plan ID is missing, invalid, or not found | Verify the plan ID exists and is correctly specified |
| `payment_id_missing` | Payment ID is missing or not found | Include a valid payment ID in your request |
| `subscription_id_missing_request_failed_failed` | Subscription ID missing; request failed | Add the required subscription ID parameter |
| `invalid_payment_type` | Invalid payment type specified | Use supported payment types: 'E\_MANDATE', 'UPI', or 'CARD' |
| `subscription_does_not_exist` | Subscription doesn't exist for the provided reference ID | Verify the subscription reference ID is correct |
| `authorization_payment_info_mismatch` | Authorization payment info doesn't match subscription creation info | Ensure payment details match between subscription creation and authorization |
| `tpv_not_supported` | TPV currently not allowed for Intent and QR auth flow | Use alternative auth flows when TPV is enabled |

## Transaction failure reasons

The following are the detailed failure reasons categorised by their nature:

* [Account issues](#account-issues)
* [Balance and limit issues](#balance-and-limit-issues)
* [Mandate issues](#mandate-issues)
* [Fraud and security](#fraud-and-security)
* [Technical issues](#technical-issues)
* [Customer action required](#customer-action-required)
* [Invalid data and validation](#invalid-data-and-validation)
* [Know your customer and documentation](#know-your-customer-and-documentation)
* [System and processing status](#system-and-processing-status)
* [Notification issues](#notification-issues)

### Account issues

The following are the account-related error codes:

| Error | Description | Resolution |
| - | - | - |
| `ACCOUNT CLOSED` | The account has been closed and all associated mandates were deactivated | Create a new mandate with a different account for the customer |
| `Account Blocked or frozen` | Account is temporarily blocked (for example, KYC not updated) | Customer needs to contact their bank to unblock the account |
| `DEBIT HAS BEEN FAILED \| ACCOUNT DOES NOT EXIST (REMITTER)` | Account verification failed due to incorrect account details | Verify and update correct account information |
| `Not a CBS act no.or old act no.representwithCBS no` | Account given for debit is old/non CBS/wrong/invalid | Use a valid CBS-enabled account number |
| `DEBIT HAS BEEN FAILED \| REMITTER CBS OFFLINE` | Core Banking System is offline | Wait for CBS to come online and retry |
| `U30\|DEBIT HAS BEEN FAILED\|YE\|REMITTING ACCOUNT BLOCKED/FROZEN` | Remitting account is blocked or frozen | Customer should contact their bank to resolve account issues |

### Balance and limit issues

The following are the balance and limit-related error codes:

| Error | Description | Resolution |
| - | - | - |
| `Balance Insufficient` | Insufficient funds in customer account | Customer should add funds or retry when balance is available |
| `DEBIT HAS BEEN FAILED \| INSUFFICIENT FUNDS IN CUSTOMER (REMITTER) ACCOUNT` | Insufficient balance in customer account | Recommend customer to maintain sufficient balance before retry |
| `U30\|DEBIT HAS BEEN FAILED\|Z9\|INSUFFICIENT FUNDS IN CUSTOMER (REMITTER) ACCOUNT` | Insufficient funds in remitter account | Customer needs to ensure adequate balance |
| `Amount Exceeds E-mandate Limit` | Transaction amount exceeds the e-mandate limit | Reduce amount or increase mandate limit if supported |
| `DEBIT HAS BEEN FAILED \| PER TRANSACTION LIMIT EXCEEDED AS SET BY REMITTING MEMBER` | Per transaction limit exceeded | Use amount within the set transaction limits |
| `U29\|ADDRESS RESOLUTION IS FAILED\|QL\|MANDATE DEBIT IS BEYOND PSP SPECIFIED AMOUNT CAP` | Amount limit is breached | Ensure amount is within PSP specified limits |
| `DEBIT HAS BEEN FAILED \| MANDATE REQUEST LIMIT HAS BREACHED` | Mandate request limit has been breached | Wait for limit reset or contact support |
| `U30\|DEBIT HAS BEEN FAILED\|QK\|MANDATE REQUEST LIMIT HAS BREACHED` | Mandate request limit exceeded | Review and adjust mandate limits |
| `Not Arranged For` | Bank account isn't set up to facilitate debit transaction | Customer should contact bank to set up debit facility |

### Mandate issues

The following are the mandate-related error codes:

| Error | Description | Resolution |
| - | - | - |
| `Invalid UMRN or Inactive Mandate` | Mandate has been deactivated by NPCI or cancelled by customer/merchant | Create a new mandate for the customer |
| `Mandate Cancelled` | Mandate has been cancelled by customer or merchant | Create a new mandate to continue debits |
| `Record Level Error: Invalid Mandate Info` | Mandate cancelled by customer from bank | Create a new mandate with updated information |
| `DEBIT HAS BEEN FAILED \| MANDATE HAS BEEN REVOKED` | Mandate has been revoked | Create a new mandate for the customer |
| `DEBIT HAS BEEN FAILED \| MANDATE SIGNATURE IS TAMPERED OR CORRUPT (REMITTER)` | Mandate signature is corrupted | Customer should contact issuing bank |
| `DUPLICATE MANDATE REQUEST FOR SAME ITEM` | Duplicate mandate request submitted | Avoid duplicate requests or check existing mandates |
| `Mandate Qr tampered` | Mandate QR code has been tampered with | Generate a new mandate with fresh QR code |
| `U29\|ADDRESS RESOLUTION IS FAILED\|QB\|MANDATE IS ALREADY HONOURED` | Duplicate transaction attempt | Ensure transaction isn't a duplicate of a previously successful one |
| `Invalid frequency` | Invalid frequency specified for LOAN category | Use appropriate frequency as per NPCI guidelines |

### Fraud and security

The following are the fraud and security-related error codes:

| Error | Description | Resolution |
| - | - | - |
| `DEBIT HAS BEEN FAILED \| SUSPECTED FRAUD` | Transaction flagged as suspected fraud | Customer should contact their bank for clearance |
| `U30\|DEBIT HAS BEEN FAILED\|K1\|SUSPECTED FRAUD, DECLINE / TRANSACTIONS DECLINED BASED ON RISK SCORE BY REMITTER` | Risk-based decline by remitter bank | Customer may retry or contact bank |
| `ADDRESS RESOLUTION IS FAILED \| TRANSACTION CANNOT BE COMPLETED. COMPLIANCE VIOLATION (REMITTER)` | Compliance violation detected | Ensure transaction complies with regulatory requirements |
| `DEBIT HAS BEEN FAILED \| DO NOT HONOUR (REMITTER)` | Debit transaction rejected by issuing bank | Customer should contact their bank |

### Technical issues

The following are the technical error codes:

| Error | Description | Resolution |
| - | - | - |
| `REMITTER BANK NOT AVAILABLE` | Remitter bank system is unavailable | Retry the transaction after some time |
| `DEBIT TIMEOUT \| REMITTER/ISSUER UNAVAILABLE (TIMEOUT)` | Bank system timeout occurred | Retry the transaction when bank systems are stable |
| `U67\|DEBIT TIMEOUT\|UT\|REMITTER/ISSUER UNAVAILABLE (TIMEOUT)` | Timeout from remitter or issuer | Retry during stable network conditions |
| `REMITTER BANK DEEMED HIGH RESPONSE TIME CHECK DECLINE` | Bank system experiencing high traffic or technical issues | Retry during off-peak hours |
| `U90\|REMITTER BANK DEEMED HIGH RESPONSE TIME CHECK DECLINE` | High response time from remitter bank | Retry when bank systems are more responsive |
| `U91\|BENEFICIARY BANK DEEMED HIGH RESPONSE TIME CHECK DECLINE` | Beneficiary bank system issues | Retry when bank systems are stable |
| `No response received from bank within the prescribed API time limit` | Bank API timeout | Retry the transaction |
| `ADD_RESLN_DISPATCH_FAILED` | Address resolution dispatch failure | Contact support for technical assistance |

### Customer action required

The following are the error codes that require customer action:

| Error | Description | Resolution |
| - | - | - |
| `No action performed by customer` | Customer didn't complete the authorization process | Customer needs to complete the payment flow |
| `COLLECT EXPIRED` | Customer didn't complete auth after entering VPA | Customer should complete the transaction within time limit |
| `RESPMANDATE TIMEOUT AT REMITTER END` | Customer didn't honor the mandate within time | Customer should respond to mandate requests |
| `RESPMANDATE DECLINED BY REMITTER BANK` | Remitter bank declined the mandate | Customer should contact their bank |
| `RESPAUTHMANDATE EXPIRED` | No action performed on collect request and it expired | Customer should complete authorization within time limit |
| `RESPAUTHMANDATE DECLINED BY PSP` | PSP declined the authorization mandate | Contact support for assistance |
| `Transaction Open Status` | Customer closed transaction page before completion or retried failed transaction | Complete the transaction without closing the page |
| `No Details available for Requested MandateReqID` | Customer cancelled mandate before reaching NPCI page | Reinitiate the mandate creation process |

### Invalid data and validation

The following are the data validation error codes:

| Error | Description | Resolution |
| - | - | - |
| `U29\|ADDRESS RESOLUTION IS FAILED\|ZH\|INVALID VIRTUAL ADDRESS` | Invalid VPA used in transaction | Use a valid and verified VPA |
| `ADDRESS RESOLUTION IS FAILED \| INVALID VIRTUAL ADDRESS` | Invalid Virtual Address during VPA validation | Verify and use correct VPA |
| `DEBIT HAS BEEN FAILED \| INVALID TRANSACTION OR IF MEMBER IS NOT ABLE TO FIND ANY APPROPRIATE RESPONSE CODE (REMITTER)` | Invalid transaction or unrecognized response | Retry with valid transaction details |
| `U30\|DEBIT HAS BEEN FAILED\|XB\|INVALID TRANSACTION OR IF MEMBER IS NOT ABLE TO FIND ANY APPROPRIATE RESPONSE CODE (REMITTER)` | Invalid transaction from remitter | Verify transaction details and retry |
| `DEBIT HAS BEEN FAILED \| INVALID RESPONSE CODE` | Invalid response received from bank | Retry the transaction |
| `U30\|DEBIT HAS BEEN FAILED\|XD\|INVALID AMOUNT (REMITTER)` | Invalid amount specified | Use valid amount format and value |
| `DEBIT HAS BEEN FAILED \| RegIdDetails must be present` | Required registration details missing | Ensure all required details are provided |
| `U30\|DEBIT HAS BEEN FAILED\|V1\|RegIdDetails must be present` | Registration details missing | Include all required registration information |
| `DEBIT HAS BEEN FAILED \| Id name must be present` | Required ID name field missing | Include the ID name field in the request |

### Know your customer and documentation

The following are the KYC and documentation-related error codes:

| Error | Description | Resolution |
| - | - | - |
| `Aadhaar number does not have mobile number registered with uidai` | Mobile number not linked with Aadhaar | Customer should link mobile number with Aadhaar |
| `Payer Account Validation Failure` | TPV verification failed | Ensure correct account details for TPV verification |

### System and processing status

The following are the system and processing status error codes:

| Error | Description | Resolution |
| - | - | - |
| `Internal Payment Failed` | Internal system error during payment processing | Retry the transaction or contact support |
| `Charge couldn't happen on time` | Previous charge was in progress, preventing next charge | Wait for previous charge to complete |
| `Previous request in progress` | Previous request for same action is still being processed | Wait for previous request to complete before retrying |
| `debit has been failed` | Bank didn't send any failure reason | Check with bank for specific failure details |

### Notification issues

The following are the notification-related error codes:

| Error | Description | Resolution |
| - | - | - |
| `Notification couldn't be sent to the customer` | Pre-debit notification failed to send | Ensure customer contact details are correct |
| `DEBIT HAS BEEN FAILED \| Unable to Notify the Customer` | Pre-debit notification delivery failed | Update customer contact information |

## Error response structure

Subscription API errors follow this structure:

```json theme={"dark"}
{
  "status": "ERROR",
  "subCode": "400",
  "message": "Error description",
  "reason": "Detailed error reason"
}
```

## Best practices for error handling

The following are the recommended practices for handling subscription errors:

**Implement retry logic**:

* For timeout and temporary errors, implement exponential backoff retry logic.
* Start with a 1-second delay, double the delay for each subsequent retry.
* Use a maximum of 3-5 retry attempts.
* Apply different retry strategies for different error types.

**Customer communication**:

* Provide clear, actionable error messages to customers.
* Include specific steps they need to take for resolution.
* Avoid technical jargon in customer-facing messages.

**Mandate management**:

* Monitor mandate status.
* Proactively create new mandates when existing ones are cancelled or expired.
* Implement mandate renewal work flows before expiration.

**Balance monitoring**:

* Advise customers to maintain sufficient balance before scheduled debits.
* Send pre-debit notifications to remind customers.
* Implement balance check APIs where available.

**Error logging and monitoring**:

* Log all errors with timestamps and request details.
* Set up alerts for critical error patterns.
* Analyse error trends to identify systemic issues.

**Graceful degradation**:

* Provide alternative payment methods when subscription payment fails.
* Implement fallback mechanisms for critical payment flows.
* Maintain service availability despite individual payment failures.

**Security considerations**:

* Handle fraud-related errors with additional verification steps.
* Implement risk scoring for suspicious transaction patterns.
* Maintain compliance with regulatory requirements.

<Note>
  For additional API error codes and web hook error structures, refer to the [Payment Errors documentation](/docs/api-reference/payments/errors).
</Note>


# Create Subscription
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/subscription/mandate/create

openapi/payments/v2025-01-01.yaml post /subscriptions
Use this API to create a new subscription.



# Fetch Subscription
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/subscription/mandate/fetch

openapi/payments/v2025-01-01.yaml get /subscriptions/{subscription_id}
Use this API to fetch subscription details.



# Generate Transaction Return Summary
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/subscription/mandate/generate-transaction-summary

openapi/payments/v2025-01-01.yaml post /subscriptions/charge/{payment_id}/transaction-return-summary/generate
Use this API to generate transaction return summary for failed transactions (insufficient balance).



# Manage Subscription
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/subscription/mandate/manage

openapi/payments/v2025-01-01.yaml post /subscriptions/{subscription_id}/manage
Use this API to manage subscriptions. You can cancel, pause, activate, or change the plan associated with a subscription.
To update the recurring amount for a periodic subscription: 1. Create a new plan with the revised amount. 2. Use the Manage Subscription API to associate the subscription with the new plan. 3. Include the `CHANGE_PLAN` action and the new `plan_id` in the request body.

<Note>
  * Customers won't be notified about plan changes. The charge amount can't exceed the maximum amount defined in the original plan.
  * The `CHANGE_PLAN` and `PAUSE` actions aren't supported for On-Demand Subscriptions.
</Note>


# Get All the Payment Method Details Available for Subscription Payments
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/subscription/mandate/payment-methods

openapi/payments/v2025-01-01.yaml post /subscriptions/eligibility/payment_methods
Use this API to check if a payment method is enabled for your account.



# Upload file for Physical Nach Authorisation
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/subscription/mandate/physical-nach-mandate

openapi/payments/v2025-01-01.yaml post /subscriptions/pay/documents/{payment_id}
Use this API to upload file for Physical Nach Authorization.



# Overview
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/subscription/overview

Learn details about subscription APIs to manage recurring payments, mandates, and payment schedules.

The Subscription APIs provide RESTful endpoints for managing recurring payments, customer mandates, and automated billing schedules. These APIs support both sandbox testing and production environments with consistent authentication and error handling across all endpoints. Real-time webhooks ensure seamless integration for subscription lifecycle events, payment notifications, and mandate status updates.

## API endpoints

| Environment | Base URL |
| :- | :- |
| Test | [https://sandbox.cashfree.com/pg](https://sandbox.cashfree.com/pg) |
| Production | [https://api.cashfree.com/pg](https://api.cashfree.com/pg) |
| Latest version | v5, 2025-01-01 |

## Authentication

All Subscription APIs require authentication. Refer to the [Authentication](/docs/api-reference/authentication) guide for detailed information on API authentication for merchants and partners.

## Subscription APIs

<Tabs>
  <Tab title="Plans and mandates">
    <div>
      <div>
        <div>
          <h4>Plan management</h4>

          <div>
            <div>
              <a href="/docs/api-reference/payments/previous/v2025-01-01/subscription/plans/create">Create Plan</a>

              <p>
                Define subscription terms including billing frequency, amount, and recurring payment parameters.
              </p>
            </div>
          </div>

          ***

          <div>
            <div>
              <a href="/docs/api-reference/payments/previous/v2025-01-01/subscription/plans/fetch">Fetch Plan</a>

              <p>
                Retrieve details of an existing subscription plan using plan ID.
              </p>
            </div>
          </div>
        </div>
      </div>

      <div>
        <div>
          <h4>Mandate (Subscription) management</h4>

          <div>
            <div>
              <a href="/docs/api-reference/payments/previous/v2025-01-01/subscription/mandate/create">Create Subscription</a>

              <p>
                Create a subscription mandate with customer details and payment method authorization.
              </p>
            </div>
          </div>

          ***

          <div>
            <div>
              <a href="/docs/api-reference/payments/previous/v2025-01-01/subscription/mandate/fetch">Fetch Subscription</a>

              <p>
                Retrieve subscription details using subscription ID or subscription reference ID.
              </p>
            </div>
          </div>

          ***

          <div>
            <div>
              <a href="/docs/api-reference/payments/previous/v2025-01-01/subscription/mandate/manage">Manage Subscription</a>

              <p>
                Update subscription status to activate, pause, or cancel a customer mandate.
              </p>
            </div>
          </div>

          ***

          <div>
            <div>
              <a href="/docs/api-reference/payments/previous/v2025-01-01/subscription/mandate/physical-nach-mandate">Upload Physical NACH Form</a>

              <p>
                Upload physical NACH registration forms for signature-based mandate creation.
              </p>
            </div>
          </div>

          ***

          <div>
            <div>
              <a href="/docs/api-reference/payments/previous/v2025-01-01/subscription/mandate/payment-methods">Get Payment Methods</a>

              <p>
                Fetch available payment methods and configurations for subscription creation.
              </p>
            </div>
          </div>

          ***

          <div>
            <div>
              <a href="/docs/api-reference/payments/previous/v2025-01-01/subscription/mandate/generate-transaction-summary">Generate Transaction Summary</a>

              <p>
                Generate downloadable transaction summary reports for a subscription.
              </p>
            </div>
          </div>
        </div>
      </div>
    </div>
  </Tab>

  <Tab title="Payments and refunds">
    <div>
      <div>
        <div>
          <h4>Payment management</h4>

          <div>
            <div>
              <a href="/docs/api-reference/payments/previous/v2025-01-01/subscription/payment/raise">Raise Payment</a>

              <p>
                Initiate a recurring payment charge against an active subscription mandate.
              </p>
            </div>
          </div>

          ***

          <div>
            <div>
              <a href="/docs/api-reference/payments/previous/v2025-01-01/subscription/payment/controlled/create-controlled-notification">Create Controlled Notification</a>

              <p>
                Initiate a merchant-controlled payment notification for an on-demand subscription mandate.
              </p>
            </div>
          </div>

          ***

          <div>
            <div>
              <a href="/docs/api-reference/payments/previous/v2025-01-01/subscription/payment/controlled/fetch-controlled-notification">Fetch Controlled Notification</a>

              <p>
                Retrieve the latest status and identifiers for a controlled payment notification attempt.
              </p>
            </div>
          </div>

          ***

          <div>
            <div>
              <a href="/docs/api-reference/payments/previous/v2025-01-01/subscription/payment/controlled/fetch-controlled-notifications">Fetch All Controlled Notifications</a>

              <p>
                Retrieve status, timestamps, and identifiers for all controlled payment notification attempts for a subscription payment.
              </p>
            </div>
          </div>

          ***

          <div>
            <div>
              <a href="/docs/api-reference/payments/previous/v2025-01-01/subscription/payment/controlled/create-controlled-execution">Create Controlled Execution</a>

              <p>
                Trigger a merchant-controlled charge execution after a successful controlled notification.
              </p>
            </div>
          </div>

          ***

          <div>
            <div>
              <a href="/docs/api-reference/payments/previous/v2025-01-01/subscription/payment/controlled/fetch-controlled-execution">Fetch Controlled Execution</a>

              <p>
                Retrieve execution status, attempt timestamps, and failure details for a controlled charge.
              </p>
            </div>
          </div>

          ***

          <div>
            <div>
              <a href="/docs/api-reference/payments/previous/v2025-01-01/subscription/payment/controlled/fetch-controlled-executions">Fetch All Controlled Executions</a>

              <p>
                Retrieve status, attempt timestamps, and failure details for all controlled execution attempts for a subscription payment.
              </p>
            </div>
          </div>

          ***

          <div>
            <div>
              <a href="/docs/api-reference/payments/previous/v2025-01-01/subscription/payment/fetch">Fetch Payment</a>

              <p>
                Retrieve details of a specific subscription payment using payment ID.
              </p>
            </div>
          </div>

          ***

          <div>
            <div>
              <a href="/docs/api-reference/payments/previous/v2025-01-01/subscription/payment/manage">Manage Payment</a>

              <p>
                Retry failed payments or update payment status for subscription charges.
              </p>
            </div>
          </div>

          ***

          <div>
            <div>
              <a href="/docs/api-reference/payments/previous/v2025-01-01/subscription/payment/fetch-payments-for-mandate">Fetch Payments for Mandate</a>

              <p>
                Retrieve all payment transactions associated with a specific subscription.
              </p>
            </div>
          </div>
        </div>
      </div>

      <div>
        <div>
          <h4>Refund management</h4>

          <div>
            <div>
              <a href="/docs/api-reference/payments/previous/v2025-01-01/subscription/refund/refund-apis-overview">Refund Overview</a>

              <p>
                Learn about the refund process and workflow for subscription payments.
              </p>
            </div>
          </div>

          ***

          <div>
            <div>
              <a href="/docs/api-reference/payments/previous/v2025-01-01/subscription/refund/create">Create Refund</a>

              <p>
                Initiate full or partial refunds for subscription payments using payment ID.
              </p>
            </div>
          </div>

          ***

          <div>
            <div>
              <a href="/docs/api-reference/payments/previous/v2025-01-01/subscription/refund/fetch">Fetch Refund</a>

              <p>
                Retrieve refund details and status using refund ID or payment ID.
              </p>
            </div>
          </div>
        </div>
      </div>
    </div>
  </Tab>
</Tabs>

## Supported payment methods

Cashfree Subscriptions supports the following payment methods for recurring payments:

* **Bank account (e-Mandate)**: Net banking, debit card, or Aadhaar-based authorization with up to ₹1,00,00,000 mandate amount
* **Bank account (Physical mandate)**: Signature-based NACH mandate for accounts without digital access
* **UPI Autopay**: Recurring payments via UPI applications with ₹15,000-₹1,00,000 limits based on authentication
* **Standing Instructions (SI) on cards**: Credit or debit cards (Indian and International) with flexible amount limits

For detailed payment method information, refer to the [Supported Payment Methods](/docs/payments/subscription/payment-modes) guide.

## Getting started

Complete the following steps to set up subscriptions using Cashfree APIs:

1. **Create a Plan** (optional): Define your subscription terms including billing frequency and amount
2. **Create a Subscription**: Set up a mandate with customer details and payment method
3. **Customer Authorization**: Customer authorizes the recurring payment through their chosen method
4. **Raise Payments**: Initiate recurring charges as per the subscription schedule
5. **Manage Subscriptions**: Update subscription status, handle payment retries, and process refunds

For a comprehensive integration guide, visit the [Subscription Introduction](/docs/payments/subscription/introduction) page.

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/payments/subscription/introduction">Subscription Introduction</a></li>
    <li><a href="/docs/payments/subscription/payment-modes">Supported Payment Methods</a></li>
    <li><a href="/docs/payments/subscription/create">Create Subscription Guide</a></li>
    <li><a href="/docs/help/subscriptions/faqs/faqs">Subscription FAQs</a></li>
  </ul>
</div>


# Create Controlled Execution
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/subscription/payment/controlled/create-controlled-execution

openapi/payments/v2025-01-01.yaml post /subscriptions/pay/controlled/execute-mandate
Use this API to create a controlled charge execution for an on-demand subscription mandate after a successful notification.

<Warning>This API supports UPI mandates only. eNACH and Physical NACH (PNACH) mandates are not supported. Card support is planned for a future release.</Warning>

<Note>The debit amount cannot change after the pre-debit notification (PDN) is initiated. If the executed debit amount differs from the amount notified in the PDN, the transaction is declined by the issuing bank due to the amount-match logic enforced at the issuing bank.</Note>


# Create Controlled Notification
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/subscription/payment/controlled/create-controlled-notification

openapi/payments/v2025-01-01.yaml post /subscriptions/pay/controlled/notify-mandate
Use this API to initiate a controlled payment notification (PDN) for an on-demand subscription mandate.

<Warning>This API supports UPI mandates only. eNACH and Physical NACH (PNACH) mandates are not supported. Card support is planned for a future release.</Warning>


# Fetch Controlled Execution
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/subscription/payment/controlled/fetch-controlled-execution

openapi/payments/v2025-01-01.yaml get /subscriptions/payments/{payment_id}/controlled/executions/{execution_id}
Use this API to fetch the details of a controlled execution for a subscription mandate.

<Warning>This API supports UPI mandates only. eNACH and Physical NACH (PNACH) mandates are not supported. Card support is planned for a future release.</Warning>


# Fetch All Controlled Executions
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/subscription/payment/controlled/fetch-controlled-executions

openapi/payments/v2025-01-01.yaml get /subscriptions/payments/{payment_id}/controlled/executions
Use this API to fetch all controlled payment executions for a subscription payment.

<Warning>This API supports UPI mandates only. eNACH and Physical NACH (PNACH) mandates are not supported. Card support is planned for a future release.</Warning>


# Fetch Controlled Notification
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/subscription/payment/controlled/fetch-controlled-notification

openapi/payments/v2025-01-01.yaml get /subscriptions/payments/{payment_id}/controlled/notifications/{notification_id}
Use this API to fetch the details of a controlled payment notification for a subscription mandate.

<Warning>This API supports UPI mandates only. eNACH and Physical NACH (PNACH) mandates are not supported. Card support is planned for a future release.</Warning>


# Fetch All Controlled Notifications
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/subscription/payment/controlled/fetch-controlled-notifications

openapi/payments/v2025-01-01.yaml get /subscriptions/payments/{payment_id}/controlled/notifications
Use this API to fetch all controlled payment notifications for a subscription payment.

<Warning>This API supports UPI mandates only. eNACH and Physical NACH (PNACH) mandates are not supported. Card support is planned for a future release.</Warning>


# Controlled Subscription Payments
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/subscription/payment/controlled/overview

Drive pre-debit notification and charge execution yourself with the controlled subscription payment APIs for UPI Autopay and card mandates.

The controlled payment flow for UPI Autopay and card mandate subscriptions gives you explicit control over when to notify your customers and when to execute the debit. This is a significant change if you need to comply with pre-debit notification rules for UPI Autopay and card mandates.

<Note>The controlled flow supports UPI Autopay and card mandates. eNACH and Physical NACH (PNACH) mandates are not supported.</Note>

## How it works

The controlled flow replaces the automatic charge trigger with a two-step process you drive:

1. **Send a pre-debit notification**: Notify your customer of the upcoming charge amount before the debit window opens.
2. **Execute the charge**: Trigger the mandate debit after the compliance window elapses. The debit amount must exactly match the notified amount; a mismatch causes the issuing bank to decline the transaction.

<Warning>
  Controlled charging is a two-step flow in which you send the pre-debit notification and trigger the debit. Cashfree does not automatically retry a failed attempt. You must trigger each attempt yourself.
</Warning>

## API endpoints

The following endpoints support the controlled notification and execution flow:

| API | Method | Description |
| - | - | - |
| [Create Controlled Notification](/docs/api-reference/payments/previous/v2025-01-01/subscription/payment/controlled/create-controlled-notification) | `POST /subscriptions/pay/controlled/notify-mandate` | Send a pre-debit notification to the customer |
| [Fetch Controlled Notification](/docs/api-reference/payments/previous/v2025-01-01/subscription/payment/controlled/fetch-controlled-notification) | `GET /subscriptions/payments/{payment_id}/controlled/notifications/{notification_id}` | Retrieve a single notification |
| [Fetch All Controlled Notifications](/docs/api-reference/payments/previous/v2025-01-01/subscription/payment/controlled/fetch-controlled-notifications) | `GET /subscriptions/payments/{payment_id}/controlled/notifications` | List all notifications for a payment |
| [Create Controlled Execution](/docs/api-reference/payments/previous/v2025-01-01/subscription/payment/controlled/create-controlled-execution) | `POST /subscriptions/pay/controlled/execute-mandate` | Trigger the mandate debit after the notification window |
| [Fetch Controlled Execution](/docs/api-reference/payments/previous/v2025-01-01/subscription/payment/controlled/fetch-controlled-execution) | `GET /subscriptions/payments/{payment_id}/controlled/executions/{execution_id}` | Retrieve a single execution |
| [Fetch All Controlled Executions](/docs/api-reference/payments/previous/v2025-01-01/subscription/payment/controlled/fetch-controlled-executions) | `GET /subscriptions/payments/{payment_id}/controlled/executions` | List all execution attempts for a payment |

For UPI Autopay mandates, NPCI enforces blackout windows during which attempts are rejected. When this happens, the error response tells you the next permitted timestamp. Use this timestamp to schedule your next attempt instead of retrying immediately.

## Webhooks

Subscribe to both events rather than polling:

* [`SUBSCRIPTION_CONTROLLED_NOTIFICATION_STATUS`](/docs/api-reference/payments/previous/v2025-01-01/subscription/webhooks#subscription_controlled_notification_status): A notification attempt reached a terminal state.
* [`SUBSCRIPTION_CONTROLLED_EXECUTION_STATUS`](/docs/api-reference/payments/previous/v2025-01-01/subscription/webhooks#subscription_controlled_execution_status): A charge attempt reached a terminal state.


# Create Controlled Execution
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/subscription/payment/create-controlled-execution

openapi/payments/v2025-01-01.yaml post /subscriptions/pay/controlled/execute-mandate
Use this API to create a controlled charge execution for an on-demand subscription mandate after a successful notification.

<Warning>This API supports UPI mandates only. eNACH and Physical NACH (PNACH) mandates are not supported. Card support is planned for a future release.</Warning>

<Note>The debit amount cannot change after the pre-debit notification (PDN) is initiated. If the executed debit amount differs from the amount notified in the PDN, the transaction is declined by the issuing bank due to the amount-match logic enforced at the issuing bank.</Note>


# Create Controlled Notification
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/subscription/payment/create-controlled-notification

openapi/payments/v2025-01-01.yaml post /subscriptions/pay/controlled/notify-mandate
Use this API to initiate a controlled payment notification (PDN) for an on-demand subscription mandate.

<Warning>This API supports UPI mandates only. eNACH and Physical NACH (PNACH) mandates are not supported. Card support is planned for a future release.</Warning>


# Fetch Details of a Single Payment
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/subscription/payment/fetch

openapi/payments/v2025-01-01.yaml get /subscriptions/{subscription_id}/payments/{payment_id}
Use this API to fetch details of a single payment of a subscription.



# Fetch Controlled Execution
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/subscription/payment/fetch-controlled-execution

openapi/payments/v2025-01-01.yaml get /subscriptions/payments/{payment_id}/controlled/executions/{execution_id}
Use this API to fetch the details of a controlled execution for a subscription mandate.

<Warning>This API supports UPI mandates only. eNACH and Physical NACH (PNACH) mandates are not supported. Card support is planned for a future release.</Warning>


# Fetch All Controlled Executions
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/subscription/payment/fetch-controlled-executions

openapi/payments/v2025-01-01.yaml get /subscriptions/payments/{payment_id}/controlled/executions
Use this API to fetch all controlled payment executions for a subscription payment.

<Warning>This API supports UPI mandates only. eNACH and Physical NACH (PNACH) mandates are not supported. Card support is planned for a future release.</Warning>


# Fetch Controlled Notification
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/subscription/payment/fetch-controlled-notification

openapi/payments/v2025-01-01.yaml get /subscriptions/payments/{payment_id}/controlled/notifications/{notification_id}
Use this API to fetch the details of a controlled payment notification for a subscription mandate.

<Warning>This API supports UPI mandates only. eNACH and Physical NACH (PNACH) mandates are not supported. Card support is planned for a future release.</Warning>


# Fetch All Controlled Notifications
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/subscription/payment/fetch-controlled-notifications

openapi/payments/v2025-01-01.yaml get /subscriptions/payments/{payment_id}/controlled/notifications
Use this API to fetch all controlled payment notifications for a subscription payment.

<Warning>This API supports UPI mandates only. eNACH and Physical NACH (PNACH) mandates are not supported. Card support is planned for a future release.</Warning>


# Fetch Details of All Payments of a Subscription
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/subscription/payment/fetch-payments-for-mandate

openapi/payments/v2025-01-01.yaml get /subscriptions/{subscription_id}/payments
Use this API to fetch all payments of a subscription.



# Manage a Single Payment
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/subscription/payment/manage

openapi/payments/v2025-01-01.yaml post /subscriptions/{subscription_id}/payments/{payment_id}/manage
Use this API to manage a payment of a subscription. A payment can be cancelled or retried with this API.



# Raise a Charge or Create an Auth
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/subscription/payment/raise

openapi/payments/v2025-01-01.yaml post /subscriptions/pay
Use this API to create an auth or to raise a charge.

<Warning>In the sandbox environment, authorisation-related responses for eNACH, card, and UPI differ from those in production.</Warning>

You must generate the URL in production by concatenating it with the payload data in JSON format. The following are example responses for all Seamless Auth modes in the production environment.

<AccordionGroup>
  <Accordion title="Card method">
    ```
    {
      "action": "custom",
      "cf_payment_id": "39394805",
      "channel": "link",
      "data": {
        "url": "https://centinelapi.cardinalcommerce.com/V2/Cruise/StepUp",
        "payload": {
          "JWT": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiI4MjcxZmJlMS1mOTU5LTQwMTgtOTc1OC01MzZkMWRkNzM2NjIiLCJpYXQiOjE3NDc2NDI4NjIsImlzcyI6IjYxNDIwNjg4OTMzODI1Njc1MDg0ZGI2ZiIsImV4cCI6MTc0NzY0NjQ2MiwiT3JnVW5pdElkIjoiNjRkNjA3ZGFmZjUzNDk2MWYxNjk0YWZjIiwiUGF5bG9hZCI6eyJBQ1NVcmwiOiJodHRwczovL3NlY3VyZWljaWNpLWNyMS5pY2ljaWJhbmsuY29tL3YxL2Fjcy9zZXJ2aWNlcy9icm93c2VyL2NyZXEvTC84MTEyLzMzNzAxNTBlLTM0OGEtMTFmMC05NTliLTJiYjZmODk2ZjIzOCIsIlBheWxvYWQiOiJleUp0WlhOellXZGxWSGx3WlNJNklrTlNaWEVpTENKdFpYTnpZV2RsVm1WeWMybHZiaUk2SWpJdU1pNHdJaXdpZEdoeVpXVkVVMU5sY25abGNsUnlZVzV6U1VRaU9pSTRZV1ZtT1RCaU15MW1ZakU0TFRRME5qa3RPREF3TVMwMk1tVm1ZakEwWW1RMk56TWlMQ0poWTNOVWNtRnVjMGxFSWpvaU16TTNNREUxTUdVdE16UTRZUzB4TVdZd0xUazFPV0l0TW1KaU5tWTRPVFptTWpNNElpd2lZMmhoYkd4bGJtZGxWMmx1Wkc5M1UybDZaU0k2SWpBeUluMCIsIlRyYW5zYWN0aW9uSWQiOiJUNGVtNEdidnBubGwzQWViakNKMSJ9LCJPYmplY3RpZnlQYXlsb2FkIjp0cnVlLCJSZXR1cm5VcmwiOiJodHRwczovL3d3dy5jYXNoZnJlZS5jb20vc3Vic2NyaXB0aW9uL2NhcmRfcmV0dXJuLzE1MTk5NzA3P3NiY2RhdGE9bHM5SmlOMUl6VUlKaU9pY0diaEpDTGlRMVZLSmlPaUFYZTBKeWUualY5MTNOd2NUTzVFVE54b2pJa2xFYTBWWFlpc25PaXdrVVY5bFRTVkZWRkoxWEhCMVhJUlZWQkp5ZS5CM2txOWhMeXdvY2hlV1U3QV9yT2tmQ2tTVl9TUEw3NzZxcl9mVHY2RG85MmwifQ.BeWYE8vslkOLZVWJd4mJ4MU1eu682fpp2Va7IvzdL9U",
          "MD": "3881717951"
        },
        "content_type": "application/json",
        "method": "post"
      },
      "payment_amount": 1,
      "payment_currency": "INR",
      "payment_id": "test12343234887",
      "payment_method": "card",
      "payment_status": "PENDING",
      "payment_type": "AUTH",
      "subscription_id": "jd-rupay-test106"
    }
    ```
  </Accordion>

  <Accordion title="Enach Seamless Auth">
    ```
    {
      "action": "custom",
      "cf_payment_id": "39394843",
      "channel": "link",
      "data": {
        "url": "https://enach.npci.org.in/onmags/sendRequest",
        "payload": {
          "AuthMode": "NetBanking",
          "BankID": "ICIC",
          "CheckSumVal": "Ril5otPjBl/Y44z3a0HAsSce2NlDqO1iEpP3pIBuKGYJplXVLuIQ1azxNB2aSJkx7...",
          "MandateReqDoc": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><Document xmlns=\"http://npci.org/onmags/schema\">...</Document>"
        },
        "content_type": "application/json",
        "method": "post"
      },
      "payment_amount": 1,
      "payment_currency": "INR",
      "payment_id": "test12343234888",
      "payment_method": "enach",
      "payment_status": "PENDING",
      "payment_type": "AUTH",
      "subscription_id": "jd-enach-test107"
    }
    ```
  </Accordion>

  <Accordion title="UPI Link">
    ```
    {
      "action": "custom",
      "cf_payment_id": "40756575",
      "channel": "link",
      "data": {
        "url": "https://payments.cashfree.com/subscriptions/checkout/timer",
        "payload": {
          "paymentType": "UPI",
          "upiIntentData": {
            "androidAuthAppLinks": {
              "AMAZONPAY": "intent://mandate?pa=branchautopay.cf@icici&pn=Branch&tr=EZM2025060413545205666653&am=10.00&cu=INR&orgid=400011&mc=7322&purpose=14&tn=Cashfree%20Payments&validitystart=04062025&validityend=04062055&amrule=MAX&recur=ASPRESENTED&rev=N&share=Y&block=N&txnType=CREATE&mode=13&fam=10.00#Intent;scheme=upi;package=in.amazon.mShop.android.shopping;end",
              "BHIM": "intent://mandate?pa=branchautopay.cf@icici&pn=Branch&tr=EZM2025060413545205666653&am=10.00&cu=INR&orgid=400011&mc=7322&purpose=14&tn=Cashfree%20Payments&validitystart=04062025&validityend=04062055&amrule=MAX&recur=ASPRESENTED&rev=N&share=Y&block=N&txnType=CREATE&mode=13&fam=10.00#Intent;scheme=upi;package=in.org.npci.upiapp;end",
              "DEFAULT": "upi://mandate?pa=branchautopay.cf@icici&pn=Branch&tr=EZM2025060413545205666653&am=10.00&cu=INR&orgid=400011&mc=7322&purpose=14&tn=Cashfree%20Payments&validitystart=04062025&validityend=04062055&amrule=MAX&recur=ASPRESENTED&rev=N&share=Y&block=N&txnType=CREATE&mode=13&fam=10.00",
              "GPAY": "gpay://upi/mandate?pa=branchautopay.cf@icici&pn=Branch&tr=EZM2025060413545205666653&am=10.00&cu=INR&orgid=400011&mc=7322&purpose=14&tn=Cashfree%20Payments&validitystart=04062025&validityend=04062055&amrule=MAX&recur=ASPRESENTED&rev=N&share=Y&block=N&txnType=CREATE&mode=13&fam=10.00#Intent;scheme=upi;package=com.google.android.apps.nbu.paisa.user;end",
              "PAYTM": "paytmmp://mandate?pa=branchautopay.cf@icici&pn=Branch&tr=EZM2025060413545205666653&am=10.00&cu=INR&orgid=400011&mc=7322&purpose=14&tn=Cashfree%20Payments&validitystart=04062025&validityend=04062055&amrule=MAX&recur=ASPRESENTED&rev=N&share=Y&block=N&txnType=CREATE&mode=13&fam=10.00#Intent;scheme=upi;package=net.one97.paytm;end",
              "PHONEPE": "phonepe://mandate?pa=branchautopay.cf@icici&pn=Branch&tr=EZM2025060413545205666653&am=10.00&cu=INR&orgid=400011&mc=7322&purpose=14&tn=Cashfree%20Payments&validitystart=04062025&validityend=04062055&amrule=MAX&recur=ASPRESENTED&rev=N&share=Y&block=N&txnType=CREATE&mode=13&fam=10.00#Intent;scheme=upi;package=com.phonepe.app;end"
            },
            "iosAuthAppLinks": {
              "BHIM": "bhim://upi://mandate?pa=branchautopay.cf@icici&pn=Branch&tr=EZM2025060413545205666653&am=10.00&cu=INR&orgid=400011&mc=7322&purpose=14&tn=Cashfree%20Payments&validitystart=04062025&validityend=04062055&amrule=MAX&recur=ASPRESENTED&rev=N&share=Y&block=N&txnType=CREATE&mode=13&fam=10.00",
              "GPAY": "tez://upi/mandate?pa=branchautopay.cf@icici&pn=Branch&tr=EZM2025060413545205666653&am=10.00&cu=INR&orgid=400011&mc=7322&purpose=14&tn=Cashfree%20Payments&validitystart=04062025&validityend=04062055&amrule=MAX&recur=ASPRESENTED&rev=N&share=Y&block=N&txnType=CREATE&mode=13&fam=10.00",
              "PAYTM": "paytmmp://mandate?pa=branchautopay.cf@icici&pn=Branch&tr=EZM2025060413545205666653&am=10.00&cu=INR&orgid=400011&mc=7322&purpose=14&tn=Cashfree%20Payments&validitystart=04062025&validityend=04062055&amrule=MAX&recur=ASPRESENTED&rev=N&share=Y&block=N&txnType=CREATE&mode=13&fam=10.00",
              "PHONEPE": "phonepe://mandate?pa=branchautopay.cf@icici&pn=Branch&tr=EZM2025060413545205666653&am=10.00&cu=INR&orgid=400011&mc=7322&purpose=14&tn=Cashfree%20Payments&validitystart=04062025&validityend=04062055&amrule=MAX&recur=ASPRESENTED&rev=N&share=Y&block=N&txnType=CREATE&mode=13&fam=10.00"
            }
          }
        },
        "content_type": "application/json",
        "method": "post"
      },
      "payment_amount": 10,
      "payment_id": "PAY-1749025491584-4289ae9a",
      "payment_method": "upi",
      "payment_status": "PENDING",
      "payment_type": "AUTH",
      "subscription_id": "SUB_TEST_1749025465390"
    }

    ```
  </Accordion>

  <Accordion title="UPI Collect">
    ```
    {
      "action": "custom",
      "cf_payment_id": "40756761",
      "channel": "collect",
      "data": {
        "url": "https://payments.cashfree.com/subscriptions/checkout/timer",
        "payload": {
          "paymentType": "UPI"
        },
        "content_type": "application/json",
        "method": ""
      },
      "payment_amount": 10,
      "payment_id": "PAY-1749025606422-791be52e",
      "payment_method": "upi",
      "payment_status": "PENDING",
      "payment_type": "AUTH",
      "subscription_id": "SUB_TEST_1749025465390"
    }

    ```
  </Accordion>

  <Accordion title="UPI QR code">
    ```
    {
      "action": "custom",
      "cf_payment_id": "40757018",
      "channel": "qrcode",
      "data": {
        "url": "",
        "payload": {
          "paymentType": "UPI",
          "qrData": "upi://mandate?pa=branchautopay.cf@icici&pn=Branch&tr=EZM2025060413592105685824&am=10.00&cu=INR&orgid=400011&mc=7322&purpose=14&tn=Cashfree%20Payments&validitystart=04062025&validityend=04062055&amrule=MAX&recur=ASPRESENTED&rev=N&share=Y&block=N&txnType=CREATE&mode=13&fam=10.00"
        },
        "content_type": "application/json",
        "method": "post"
      },
      "payment_amount": 10,
      "payment_id": "PAY-1749025760541-4c158190",
      "payment_method": "upi",
      "payment_status": "PENDING",
      "payment_type": "AUTH",
      "subscription_id": "SUB_TEST_1749025465390"
    }
    ```
  </Accordion>

  <Accordion title="Physical Nach Auth">
    ```
    {
    	"action": "post",
    	"cf_payment_id": "47720375",
    	"channel": "post",
    	"data": {
    		"url": "https://api.cashfree.com/pg/view/gateway/subscriptions/testkriti12upi12ANUG5689TFVNB357123",
    		"payload": null,
    		"content_type": "",
    		"method": null
    	},
    	"payment_amount": 0,
    	"payment_currency": "INR",
    	"payment_id": "PAY-1749025760541-4c158190",
    	"payment_method": "pnach",
    	"payment_status": "PENDING",
    	"payment_tags": null,
    	"payment_type": "AUTH",
    	"subscription_id": "SUB_TEST_1749025465390"
    }
    ```
  </Accordion>
</AccordionGroup>


# Physical Mandates
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/subscription/physical-mandates

In this chapter, you will learn in detail about the APIs related to Physical Mandates.

Physical mandate is the process of authorization where the customer requires only his signature and bank account details. There is no requirement to have a Debit Card/Netbanking enabled to set up the mandate. Click [here](/docs/payments/subscription/payment-modes#bank-account-physical-mandate) to read more on Physical Mandates.

List of Physical Mandates APIs

| API Name | Description |
| :- | :- |
| [Create Subscription API](/docs/api-reference/payments/previous/v2025-01-01/subscription/mandate/create) | Use this API to create a subscription by providing a custom payment experience to your customers by specifying the plan ID and the customer details. You can also specify the bank account information when you create the subscription to ensure that mandates are created via the specified bank account only. Make sure to choose the payment mode as PNACH to enable Physical NACH flow. TPV is applicable only for eNACH and UPI. |
| [Create an Auth API](/docs/api-reference/payments/previous/v2025-01-01/subscription/payment/raise) | Use this API to create an authorization request for your customer. For Physical mandates (PNACH), you must include the payment\_method with "pnach" details in the request payload. Upon creation, the authorization status will be set to "DOCUMENT\_PENDING". To move the status to "INITIALIZED", use the Upload File API to upload the required documents. |
| [Upload File](/docs/api-reference/payments/previous/v2025-01-01/subscription/mandate/physical-nach-mandate) | Use this API to upload the Physical Nach registration forms that contain your customer’s bank account details and signature. Use the paymentId you get in the response in the "Create Auth API" and set action as "SUBMIT\_DOCUMENT". |
| [Simulate Payment api](/docs/api-reference/payments/previous/v2025-01-01/simulation/simulate-payment) | Use this API to update the authorisation status from INITIALIZED to either SUCCESS or FAILED. You must provide the payment\_id (obtained from the upload file API) along with the desired payment status. This functionality is available only in the test environment. |


# Create a Plan
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/subscription/plans/create

openapi/payments/v2025-01-01.yaml post /plans
A plan allows your customer to identify the features you offer along with your pricing. You can create plans as per the pricing you support for your services. For each plan, you can set a pre-decided frequency and amount with which they’ll be charged.
Example: Netflix Plans : Premium, Basic, Standard, Mobile. Each plan differs and caters for a particular set of audiences.



# Fetch Plan
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/subscription/plans/fetch

openapi/payments/v2025-01-01.yaml get /plans/{plan_id}
Use this API to fetch plan details.



# Rate Limits
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/subscription/rate-limits

This chapter explains the default rate limit applied by the Subscriptions APIs per minute.

The rate limit value shows the number of API calls that were made in a minute. For example, if the rate limit is 400 - it means you can call a maximum of 400 API calls in a minute.

**Rate Limits in Sandbox & Production:**\
We use rate limiting for all endpoints. Rate limiting is based on your IP and your account Id. By default, the following rate limits are applied per minute.

| API | Rate Limit Value Per Minute | Rate Limit Type |
| :- | :- | :- |
| [Create Plan](/docs/api-reference/payments/previous/v2025-01-01/subscription/plans/create) | 60 | Account |
| [Create Subscription](/docs/api-reference/payments/previous/v2025-01-01/subscription/mandate/create) | 60 | Account |
| [Create Seamless Subscription](/docs/api-reference/payments/previous/subscriptionsv1/seamless-apis/create-seamless-subscription-with-plan-id) | 60 | Account |
| [Get Subscription Details](/docs/api-reference/payments/previous/v2025-01-01/subscription/mandate/fetch) | 60 | Account |
| [Get All Subscription Payments](/docs/api-reference/payments/previous/subscriptionsv1/subscription/fetch-subscription-payments) | 60 | Account |
| [Get Single Subscription Payment](/docs/api-reference/payments/previous/subscriptionsv1/subscription/fetch-single-subscription-payment) | 60 | Account |
| [Cancel Charge](/docs/api-reference/payments/previous/subscriptionsv1/subscription/cancel-subscription) | 60 | Account |
| [Charge Subscription](/docs/api-reference/payments/previous/subscriptionsv1/subscription/charge-subscription) | 60 | Account |
| [Charge Retry](/docs/api-reference/payments/previous/subscriptionsv1/subscription/retry-subscription-charge) | 60 | Account |
| [Activate Subscription](/docs/api-reference/payments/previous/subscriptionsv1/subscription/activate-subscription) | 60 | Account |
| [Get Payment Details using Merchant Txn ID](/docs/api-reference/payments/previous/subscriptionsv1/subscription/fetch-payment-by-merchant-transaction-id) | 60 | Account |
| [Update Recurring-amount](/docs/api-reference/payments/previous/subscriptionsv1/subscription/update-recurring-amount) | 60 | Account |


# Redirection Payload After Authorisation
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/subscription/redirection-payload-after-authorization

When a subscription is created, a return URL is provided as part of the request. When the customer authorises the payment, they are redirected to this URL via a POST request containing the parameters listed below.

## Parameters

The POST request to the return URL includes the following parameters:

| Parameter | Type | Description |
| - | - | - |
| cf\_subReferenceId | Long | Unique numeric ID generated when the subscription was created. |
| cf\_subscriptionId | String | ID of the subscription. |
| cf\_authAmount | Float | The amount charged to authorise the subscription. |
| cf\_referenceId | Long | The reference ID or transaction ID of authorisation in PG. |
| cf\_status | String | Status of the subscription. In the returnUrl, the response should be `ACTIVE` or `BANK_APPROVAL_PENDING` if the authorisation was successful, or `INITIALIZED` if the authorisation failed. |
| cf\_message | String | A brief note about the payment. |
| signature | String | The hash of all parameters in the request generated using Secret Key. |
| cf\_umrn | String | The unique identifier associated with a mandate. Applicable if the payment mode is eMandate. |
| cf\_checkoutStatus | String | The subscription checkout status. The status can be `SUCCESS`, `FAILED`, `SUCCESS_DEBIT_PENDING`, or `SUCCESS_TOKENIZATION_PENDING`. |
| cf\_mode | String | The checkout payment mode. Modes: `NPCI_SBC`, `SBC_UPI`, `SBC_CREDIT_CARD`, `SBC_DEBIT_CARD`. |
| cf\_subscriptionPaymentId | String | The subscription payment ID. |
| cf\_umn | String | The unique identifier associated with a mandate. Applicable if the payment mode is **UPI**. |

## Sample Payload

Once the authorisation is complete, Cashfree will send a POST request to your `return_url` with the following payload:

```json theme={"dark"}
{
  "cf_subReferenceId": 1234567,
  "cf_subscriptionId": "sub_test_123",
  "cf_authAmount": 1.00,
  "cf_referenceId": 987654321,
  "cf_status": "ACTIVE",
  "cf_message": "Subscription authorised successfully",
  "signature": "calculated_signature_here",
  "cf_umrn": "UMRN1234567890",
  "cf_checkoutStatus": "SUCCESS",
  "cf_mode": "SBC_UPI",
  "cf_subscriptionPaymentId": "pay_test_123",
  "cf_umn": "UMN1234567890"
}
```

## Sample Code

Below are examples of how to receive and process the redirection payload in your backend.

<CodeGroup>
  ```javascript Node.js theme={"dark"}
  const express = require('express');
  const app = express();

  // Middleware to parse POST bodies
  app.use(express.urlencoded({ extended: true }));

  app.post('/return-url', (req, res) => {
    const payload = req.body;
    
    console.log('Received Redirection Payload:', payload);

    const status = payload.cf_status;
    if (status === 'ACTIVE' || status === 'BANK_APPROVAL_PENDING') {
      // Handle success
      res.send('Subscription Authorised Successfully');
    } else {
      // Handle failure
      res.send('Authorization Failed');
    }
  });
  ```

  ```python Python theme={"dark"}
  from flask import Flask, request

  app = Flask(__name__)

  @app.route('/return-url', methods=['POST'])
  def return_url():
      # Capture the POST payload
      payload = request.form.to_dict()
      
      print("Received Redirection Payload:", payload)
      
      status = payload.get('cf_status')
      if status in ['ACTIVE', 'BANK_APPROVAL_PENDING']:
          return "Subscription Authorised Successfully", 200
      else:
          return "Authorisation Failed", 400
  ```

  ```java Java theme={"dark"}
  import javax.servlet.http.HttpServletRequest;
  import org.springframework.web.bind.annotation.PostMapping;
  import org.springframework.web.bind.annotation.RestController;
  import java.util.Map;

  @RestController
  public class SubscriptionController {

      @PostMapping("/return-url")
      public String handleRedirection(HttpServletRequest request) {
          // Collect parameters from the POST request
          Map<String, String[]> parameterMap = request.getParameterMap();
          
          String status = request.getParameter("cf_status");
          
          if ("ACTIVE".equals(status) || "BANK_APPROVAL_PENDING".equals(status)) {
              return "Subscription Authorised Successfully";
          } else {
              return "Authorisation Failed";
          }
      }
  }
  ```

  ```go Go theme={"dark"}
  package main

  import (
  	"fmt"
  	"net/http"
  )

  func returnURLHandler(w http.ResponseWriter, r *http.Request) {
  	if r.Method != http.MethodPost {
  		http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
  		return
  	}

  	// Parse the POST form
  	r.ParseForm()
  	
  	status := r.FormValue("cf_status")
  	fmt.Printf("Subscription Status: %s\n", status)

  	if status == "ACTIVE" || status == "BANK_APPROVAL_PENDING" {
  		fmt.Fprint(w, "Subscription Authorised Successfully")
  	} else {
  		fmt.Fprint(w, "Authorisation Failed")
  	}
  }

  func main() {
  	http.HandleFunc("/return-url", returnURLHandler)
  	http.ListenAndServe(":8080", nil)
  }
  ```

  ```php PHP theme={"dark"}
  <?php
  // Receive the POST data from Cashfree redirection
  $payload = $_POST;

  $status = $payload['cf_status'] ?? '';

  if ($status === 'ACTIVE' || $status === 'BANK_APPROVAL_PENDING') {
      echo "Subscription Authorised Successfully";
  } else {
      echo "Authorisation Failed";
  }
  ?>
  ```
</CodeGroup>

<Warning>
  **Return URL**

  * After the customer completes the checkout on the OTP page, they are redirected to your `return_url`. This redirection is link-based. For example, if you provide a `return_url` in the format `https://b8af79f41056.eu.ngrok.io?order_id={order_id}`, the customer is redirected to `https://b8af79f41056.eu.ngrok.io?order_id=order_271vfuhh1o4h6bQIigqyOx74YiJ1T`.

  * In production, `cf_status` and `cf_message` may not be included in the `return_url` response, even though they are present in the sandbox.\
    The `return_url` is intended only to redirect customers back to your site after payment. It should not be used to retrieve complete subscription details.

  For accurate and complete data, use webhooks.

  * Configure your webhook URL in the Cashfree Dashboard.
  * Enable the relevant events, such as `SUBSCRIPTION_AUTH_STATUS` and `SUBSCRIPTION_PAYMENT_SUCCESS`.

  Always validate the subscription status through webhook notifications for production-grade reliability.
</Warning>


# Create a Refund
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/subscription/refund/create

openapi/payments/v2025-01-01.yaml post /subscriptions/{subscription_id}/refunds
This API allows you to create refund on a successful payment. Refund amount can be partial or the full amount of the payment. 



# Fetch Details of a Refund
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/subscription/refund/fetch

openapi/payments/v2025-01-01.yaml get /subscriptions/{subscription_id}/refunds/{refund_id}
Use this API to fetch details of a refund of a subscription payment.



# Refund APIs Overview
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/subscription/refund/refund-apis-overview

In this section, you will learn about all the APIs related to subscription refunds.

# List of Subscription Refund APIs

| API Name | Description |
| :- | :- |
| [Create Refund](/docs/api-reference/payments/previous/v2025-01-01/subscription/refund/create) | Use this API to create a refund for the payment of a Subscription. |
| [Get Refund](/docs/api-reference/payments/previous/v2025-01-01/subscription/refund/fetch) | Use this API to fetch the status of the refund of a Subscription. |


# Postman Collection
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/subscription/subscription-postman-collection

Download Cashfree's subscription APIs Postman collection to get started with testing and integration.

Get started with Cashfree's subscription APIs by downloading the collection and importing it in Postman.

<a href="https://www.postman.com/cashfreedevelopers/cashfree-apis-v2025-01-01/folder/ekp0m3l/subscriptions?action=share&source=copy-link&creator=43686653&ctx=documentation">Download Cashfree subscription Postman collection</a>

## Error codes and reasons

For comprehensive error codes, failure reasons, and troubleshooting guidance when working with subscription APIs, refer to the [Error codes and reasons](/docs/api-reference/payments/previous/v2025-01-01/subscription/error-codes) documentation.


# Subscription Webhooks
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/subscription/webhooks

Learn about the various Subscription webhooks sent by Cashfree

Below are the various events that can be sent to your webhook endpoint. These webhooks will be triggered if the merchant has integrated our newer Subscription API.

<Note>
  * If the merchant added the webhook under the 2025-01-01 version, they will receive the same version of the webhook for older subscriptions as well.
  * While filling the UPI payment methods, `upi_instrument` and `upi_instrument_number` will remain empty for webhook versions before 2025. This will be implemented in later versions.
  * While filling the UPI payment methods, `upi_payer_account_number` and `upi_payer_ifsc` will be applicable only for TPV customers who have passed TPV details while creating the subscription.
</Note>

* [`SUBSCRIPTION_STATUS_CHANGED`](/docs/api-reference/payments/previous/v2025-01-01/subscription/webhooks#subscription_status_changed)
* [`SUBSCRIPTION_AUTH_STATUS`](/docs/api-reference/payments/previous/v2025-01-01/subscription/webhooks#subscription_auth_status)
* [`SUBSCRIPTION_PAYMENT_NOTIFICATION_INITIATED`](/docs/api-reference/payments/previous/v2025-01-01/subscription/webhooks#subscription_payment_notification_initiated)
* [`SUBSCRIPTION_PAYMENT_SUCCESS`](/docs/api-reference/payments/previous/v2025-01-01/subscription/webhooks#subscription_payment_success)
* [`SUBSCRIPTION_PAYMENT_FAILED`](/docs/api-reference/payments/previous/v2025-01-01/subscription/webhooks#subscription_payment_failed)
* [`SUBSCRIPTION_PAYMENT_CANCELLED`](/docs/api-reference/payments/previous/v2025-01-01/subscription/webhooks#subscription_payment_cancelled)
* [`SUBSCRIPTION_REFUND_STATUS`](/docs/api-reference/payments/previous/v2025-01-01/subscription/webhooks#subscription_refund_status)
* [`SUBSCRIPTION_CARD_EXPIRY_REMINDER`](/docs/api-reference/payments/previous/v2025-01-01/subscription/webhooks#subscription_card_expiry_reminder)
* [`SUBSCRIPTION_CONTROLLED_NOTIFICATION_STATUS`](/docs/api-reference/payments/previous/v2025-01-01/subscription/webhooks#subscription_controlled_notification_status)
* [`SUBSCRIPTION_CONTROLLED_EXECUTION_STATUS`](/docs/api-reference/payments/previous/v2025-01-01/subscription/webhooks#subscription_controlled_execution_status)

Payment method object attributes:

<CodeGroup>
  ```javascript UPI theme={"dark"}
  "payment_method": {
        "upi": {
          "channel": "collect",
          "upi_id": "8709228804@ybl",
          "upi_instrument": "",
          "upi_instrument_number": "",
          "upi_payer_account_number": "",
          "upi_payer_ifsc": ""
        }
  },
  "payment_group": "upi"
  ```

  ```javascript ENACH theme={"dark"}
  "payment_method": {
      "enach": {
        "channel": "link",
        "auth_mode": "aadhar",
        "account_type": "",
        "account_number": "",
        "account_ifsc": "",
        "account_holder_name": "",
        "account_bank_code": ""
      }
  },
  "payment_group": "enach"
  ```

  ```javascript PNACH theme={"dark"}
  "payment_method": {
      "pnach": {
        "channel": "link",
        "mandate_creation_date": "",
        "mandate_start_date": "",
        "account_type": "",
        "account_number": "",
        "account_ifsc": "",
        "account_holder_name": "",
        "account_bank_code": ""
      }
  },
  "payment_group": "pnach"
  ```

  ```javascript Debit/Credit card theme={"dark"}
  {
    "payment_method": {
      "card": {
        "channel": null,
        "card_number": "XXXXXXXXXXXX2123",
        "card_network": "visa",
        "card_type": "debit_card",
        "card_sub_type": "R",
        "card_country": "IN",
        "card_bank_name": "KOTAK MAHINDRA BANK",
        "card_network_reference_id": null,
        "instrument_id": "8e9cc167-4fe2-4ece-be8d-c1b224e50a23"
      }
    },
    "payment_group": "debit_card"
  }
  ```
</CodeGroup>

## SUBSCRIPTION\_STATUS\_CHANGED

Whenever a subscription is created it goes to initialised state and customer is expected to authorise it. The list of statuses where this webhook will get triggered are:

* ACTIVE
* ON\_HOLD
* COMPLETED
* CUSTOMER\_CANCELLED
* CUSTOMER\_PAUSED
* EXPIRED
* LINK\_EXPIRED
* BANK\_APPROVAL\_PENDING
* CANCELLED
* CARD\_EXPIRED

<Tabs>
  <Tab title="Version (2025-01-01)">
    ```javascript theme={"dark"}
    {
    "data": {
    "subscription_details": {
      "cf_subscription_id": "23639356",
      "subscription_id": "mozuyYwUCbWEfJVVRLi",
      "subscription_status": "BANK_APPROVAL_PENDING",
      "subscription_expiry_time": "2055-08-07T10:30:46",
      "subscription_first_charge_time": null,
      "subscription_tags": null,
      "next_schedule_date": null
    },
    "customer_details": {
      "customer_name": null,
      "customer_email": "john@dummy.com",
      "customer_phone": "9900000000"
    },
    "plan_details": {
      "plan_id": "mozuyYwUCbWEfJVVRLi",
      "plan_name": "6Msuj2mttuf2F5P1FYVSet",
      "plan_type": "ON_DEMAND",
      "plan_max_cycles": 0,
      "plan_recurring_amount": null,
      "plan_max_amount": 399.00,
      "plan_interval_type": null,
      "plan_intervals": null,
      "plan_currency": "INR",
      "plan_note": null,
      "plan_status": null
    },
    "authorization_details": {
      "authorization_amount": 2.00,
      "authorization_amount_refund": false,
      "approve_by_time": "2025-09-06T10:30:47",
      "authorization_reference": "6ba74ac2b047424da95591xxxxx[at]xxxx",
      "authorization_time": "2025-08-07T10:31:36",
      "authorization_status": "PENDING",
      "payment_id": "49988270",
      "payment_method": {
        "upi": {
          "channel": "link",
          "upi_id": "9910000000@ybl",
          "upi_instrument": "",
          "upi_instrument_number": "",
          "upi_payer_account_number": "",
          "upi_payer_ifsc": ""
        }
      },
      "payment_group": "upi"
    },
    "payment_gateway_details": {
      "gateway_name": "CASHFREE",
      "gateway_subscription_id": "23639356",
      "gateway_plan_id": "mozuyYwUCbWEfJVVRLi",
      "gateway_auth_id": "6ba74ac2b047424da95591xxxxx[at]xxxx"
    }
    },
    "event_time": "2025-08-07T10:31:35+05:30",
    "type": "SUBSCRIPTION_STATUS_CHANGED"
    }
    ```
  </Tab>

  <Tab title="Version (2023-08-01)">
    ```javascript theme={"dark"}
    {
    "data": {
        "subscription_details": {
            "cf_subscription_id": "123456",
            "subscription_id": "Demo_Subscription",
            "subscription_status": "ACTIVE",
            "subscription_expiry_time": "2024-01-14T23:00:08+05:30",
            "subscription_first_charge_time": "2024-01-10T23:00:08+05:30"
        },
        "customer_details": {
            "customer_name": "john",
            "customer_email": "john@dummy.com",
            "customer_phone": "9900000000"
        },
        "plan_details": {
            "plan_id": "plan12345",
            "plan_name": "Plan Name",
            "plan_type": "ON_DEMAND",
            "plan_max_cycles": 10,
            "plan_recurring_amount": 100.00,
            "plan_max_amount": 1000.00,
            "plan_currency": "INR",
            "plan_note": "Note",
            "plan_status": "ACTIVE"
        },
        "authorization_details": {
            "authorizationAmount": 1.00,
            "authorizationAmountRefund": true,
            "approveByTime": "2025-09-06T16:44:48",
            "authorizationReference": "544edde057f34ce588627axxxxx[at]xxxx",
            "authorizationTime": "2025-08-07T16:46:06",
            "authorizationStatus": "PENDING",
            "paymentId": "50088288",
            "paymentMethod": "upi",
            "instrumentId": "xxxxx@xxxx"
        },
        "payment_gateway_details": {
            "gateway_name": "CASHFREE",
            "gateway_subscription_id": "Demo_Subscription",
            "gateway_plan_id": "plan12345",
            "gateway_auth_id": "6595231908096894505959"
        }
    },
    "event_time": "2023-01-03T11:16:10+05:30",
    "type": "SUBSCRIPTION_STATUS_CHANGED"
    }
    ```
  </Tab>
</Tabs>

## SUBSCRIPTION\_AUTH\_STATUS

The event is triggered when the checkout is completed by the customer for success and failed cases.

<Tabs>
  <Tab title="Version (2025-01-01)">
    ```javascript theme={"dark"}
    {
     "data": {
       "payment_id": "ab-SUBV2ODRFhdJuHlcQYyFw-1",
       "cf_payment_id": "49988825",
       "cf_txn_id": "4213159266",
       "cf_order_id": "4519691525",
       "subscription_id": "mozth7smWGCCqPRaSv7",
       "cf_subscription_id": "23639858",
       "payment_type": "AUTH",
       "authorization_details": {
         "authorization_amount": 2.00,
         "authorization_amount_refund": false,
         "approve_by_time": "",
         "authorization_reference": "cce92d335be0467693c020xxxxx[at]xxxx",
         "authorization_time": "2025-08-07T10:34:23+05:30",
         "authorization_status": "FAILED",
         "payment_id": "ab-SUBV2ODRFhdJuHlcQYyFw-1",
         "payment_method": {
           "upi": {
             "channel": "link",
             "upi_id": "9910000000@ybl",
             "upi_instrument": "",
             "upi_instrument_number": "",
             "upi_payer_account_number": "",
             "upi_payer_ifsc": ""
           }
         },
         "payment_group": "upi"
       },
       "payment_amount": 2.00,
       "payment_currency": "INR",
       "payment_schedule_date": "",
       "payment_initiated_date": "2025-08-07T10:33:56+05:30",
       "payment_remarks": "auth payment",
       "retry_attempts": 0,
       "failure_details": {
         "failure_reason": "DEBIT HAS BEEN FAILED"
       },
       "payment_status": "FAILED",
       "payment_gateway_details": {
         "gateway_name": "CASHFREE",
         "gateway_subscription_id": "23639858",
         "gateway_payment_id": "49988825"
       }
     },
     "event_time": "2025-08-07T10:34:23+05:30",
     "type": "SUBSCRIPTION_AUTH_STATUS"
    }
    ```
  </Tab>

  <Tab title="Version (2023-08-01)">
    ```javascript theme={"dark"}
    {
    "data": {
        "payment_id": "12345",
        "cf_payment_id": "67890",
        "cf_txn_id": "789012",
        "cf_order_id": "98765",
        "subscription_id": "sub12345",
        "cf_subscription_id": "sub67890",
        "payment_type": "DEBIT_CARD",
        "authorization_details": {
            "authorization_amount": 100,
            "authorization_amount_refund": true,
            "approve_by_time": "2024-07-20T16:09:50+05:30",
            "authorization_reference": "6595231908096894505959",
            "authorization_time": "2024-07-20T16:09:51",
            "authorization_status": "ACTIVE",
            "payment_id": "123",
            "payment_method": "DEBIT_CARD",
            "instrument_id": "hsdg9"
        },
        "payment_amount": 200.75,
        "payment_schedule_date": "2024-07-20",
        "payment_initiated_date": "2024-07-20",
        "payment_remarks": "auth payment",
        "retry_attempts": 0,
        "failureDetails": null,
        "payment_status": "SUCCESS",
        "payment_gateway_details": {
            "gateway_name": "CASHFREE",
            "gateway_subscription_id": "Demo_Subscription",
            "gateway_payment_id": "payment12345"
        }
    },
    "event_time": "2024-07-20T11:16:10+05:30",
    "type": "SUBSCRIPTION_AUTH_STATUS"
    }
    ```
  </Tab>
</Tabs>

## SUBSCRIPTION\_PAYMENT\_NOTIFICATION\_INITIATED

This webhook is used to inform the merchant that we have sent a notification of payment to the customer.

<Tabs>
  <Tab title="Version (2025-01-01)">
    ```javascript Version (2025-01-01) theme={"dark"}
    {
    "data": {
    "payment_id": "ab-SUBV2ODR683gV1CXF85ev-1",
    "cf_payment_id": "49970855",
    "cf_txn_id": null,
    "cf_order_id": "",
    "subscription_id": "moziva9hyjiLtCuGN74",
    "cf_subscription_id": "22390006",
    "payment_type": "CHARGE",
    "authorization_details": {
      "authorization_amount": 399.00,
      "authorization_amount_refund": false,
      "approve_by_time": "",
      "authorization_reference": null,
      "authorization_time": "",
      "authorization_status": null,
      "payment_id": "ab-SUBV2ODR683gV1CXF85ev-1",
      "payment_method": null,
      "payment_group": null
    },
    "payment_amount": 399.00,
    "payment_currency": "INR",
    "payment_schedule_date": "2025-08-08T12:00:00+05:30",
    "payment_initiated_date": "2025-08-07T09:08:09+05:30",
    "payment_remarks": null,
    "retry_attempts": 0,
    "failure_details": {
      "failure_reason": null
    },
    "payment_status": "INITIALIZED",
    "payment_gateway_details": {
      "gateway_name": "CASHFREE",
      "gateway_subscription_id": "22390006",
      "gateway_payment_id": "49970855"
    }
    },
    "event_time": "2025-08-07T09:51:07+05:30",
    "type": "SUBSCRIPTION_PAYMENT_NOTIFICATION_INITIATED"
    }
    ```
  </Tab>

  <Tab title="Version (2023-08-01)">
    ```javascript theme={"dark"}
    {
    "data": {
        "payment_id": "12345",
        "cf_payment_id": "67890",
        "cf_txn_id": "789012",
        "cf_order_id": "98765",
        "subscription_id": "sub12345",
        "cf_subscription_id": "sub67890",
        "payment_type": "DEBIT_CARD",
        "authorization_details": {
            "authorization_amount": 100,
            "authorization_amount_refund": true,
            "approve_by_time": "2024-07-20T16:09:50+05:30",
            "authorization_reference": "6595231908096894505959",
            "authorization_time": "2024-07-20T16:09:51",
            "authorization_status": "PENDING",
            "payment_id": "123",
            "payment_method": "DEBIT_CARD",
            "instrument_id": "hsdg9"
        },
        "payment_amount": 200,
        "payment_schedule_date": "2024-07-20",
        "payment_initiated_date": "2024-07-20",
        "payment_remarks": "payment",
        "retry_attempts": 0,
        "failureDetails": null,
        "payment_status": "INITIALIZED",
        "payment_gateway_details": {
            "gateway_name": "CASHFREE",
            "gateway_subscription_id": "Demo_Subscription",
            "gateway_payment_id": "payment12345"
        }
    },
    "event_time": "2024-07-20T11:16:10+05:30",
    "type": "SUBSCRIPTION_PAYMENT_NOTIFICATION_INITIATED"
    }
    ```
  </Tab>
</Tabs>

## SUBSCRIPTION\_PAYMENT\_SUCCESS

This notification is sent whenever a successful payment is processed for an active subscription.

<Tabs>
  <Tab title="Version (2025-01-01)">
    ```javascript Version (2025-01-01) theme={"dark"}
    {
    "data": {
    "payment_id": "ab-SUBV2ODRc5Dl2meCr7Iui-1",
    "cf_payment_id": "49914526",
    "cf_txn_id": "4212435861",
    "cf_order_id": "4518936510",
    "subscription_id": "moznV33AssPd6vXsSm2",
    "cf_subscription_id": "23601811",
    "payment_type": "AUTH",
    "authorization_details": {
      "authorization_amount": 2.00,
      "authorization_amount_refund": false,
      "approve_by_time": "",
      "authorization_reference": "427b608f83ad4cbdb6d472xxxxx[at]xxxx",
      "authorization_time": "2025-08-07T05:53:22+05:30",
      "authorization_status": "ACTIVE",
      "payment_id": "ab-SUBV2ODRc5Dl2meCr7Iui-1",
      "payment_method": {
        "upi": {
          "channel": "link",
          "upi_id": "8100000000@ybl",
          "upi_instrument": "",
          "upi_instrument_number": "",
          "upi_payer_account_number": "",
          "upi_payer_ifsc": ""
        }
      },
      "payment_group": "upi"
    },
    "payment_amount": 2.00,
    "payment_currency": "INR",
    "payment_schedule_date": "",
    "payment_initiated_date": "2025-08-07T05:52:21+05:30",
    "payment_remarks": "auth payment",
    "retry_attempts": 0,
    "failure_details": {
      "failure_reason": null
    },
    "payment_status": "SUCCESS",
    "payment_gateway_details": {
      "gateway_name": "CASHFREE",
      "gateway_subscription_id": "23601811",
      "gateway_payment_id": "49914526"
    }
    },
    "event_time": "2025-08-07T05:53:21+05:30",
    "type": "SUBSCRIPTION_PAYMENT_SUCCESS"
    }

    ```
  </Tab>

  <Tab title="Version (2023-08-01)">
    ```javascript theme={"dark"}
    {
    "data": {
        "payment_id": "12345",
        "cf_payment_id": "67890",
        "cf_txn_id": "789012",
        "cf_order_id": "98765",
        "subscription_id": "sub12345",
        "cf_subscription_id": "sub67890",
        "payment_type": "DEBIT_CARD",
        "authorization_details": {
            "authorization_amount": 100,
            "authorization_amount_refund": true,
            "approve_by_time": "2024-07-20T16:09:50+05:30",
            "authorization_reference": "6595231908096894505959",
            "authorization_time": "2024-07-20T16:09:51",
            "authorization_status": "ACTIVE",
            "payment_id": "123",
            "payment_method": "DEBIT_CARD",
            "instrument_id": "hsdg9"
        },
        "payment_amount": 200,
        "payment_schedule_date": "2024-07-20",
        "payment_initiated_date": "2024-07-20",
        "payment_remarks": "payment",
        "retry_attempts": 0,
        "failureDetails": null,
        "payment_status": "SUCCESS",
        "payment_gateway_details": {
            "gateway_name": "CASHFREE",
            "gateway_subscription_id": "Demo_Subscription",
            "gateway_payment_id": "payment12345"
        }
    },
    "event_time": "2024-07-20T11:16:10+05:30",
    "type": "SUBSCRIPTION_PAYMENT_SUCCESS"
    }
    ```
  </Tab>
</Tabs>

## SUBSCRIPTION\_PAYMENT\_FAILED

This notification is sent whenever payment processing fails for an active subscription.

<Tabs>
  <Tab title="Version (2025-01-01)">
    ```javascript theme={"dark"}
    {
    "data": {
    "payment_id": "ab-SUBV2ODRIeYlFEhMHfS0M-1",
    "cf_payment_id": "49585655",
    "cf_txn_id": "4212555720",
    "cf_order_id": "4519061918",
    "subscription_id": "mozh4iRHSsjre7GkDNz",
    "cf_subscription_id": "22393526",
    "payment_type": "CHARGE",
    "authorization_details": {
      "authorization_amount": 399.00,
      "authorization_amount_refund": false,
      "approve_by_time": "",
      "authorization_reference": "a7d6101a7d9340269f070dxxxxx[at]xxxx",
      "authorization_time": "2025-07-25T22:37:53+05:30",
      "authorization_status": "ACTIVE",
      "payment_id": "ab-SUBV2ODRIeYlFEhMHfS0M-1",
      "payment_method": {
        "upi": {
          "channel": "link",
          "upi_id": "9910000000@ybl",
          "upi_instrument": "",
          "upi_instrument_number": "",
          "upi_payer_account_number": "",
          "upi_payer_ifsc": ""
        }
      },
      "payment_group": "upi"
    },
    "payment_amount": 399.00,
    "payment_currency": "INR",
    "payment_schedule_date": "2025-08-07T12:00:00+05:30",
    "payment_initiated_date": "2025-08-06T05:02:41+05:30",
    "payment_remarks": null,
    "retry_attempts": 0,
    "failure_details": {
      "failure_reason": "DEBIT FAILED | Insufficient Funds In Customer (Remitter) Account"
    },
    "payment_status": "FAILED",
    "payment_gateway_details": {
      "gateway_name": "CASHFREE",
      "gateway_subscription_id": "22393526",
      "gateway_payment_id": "49585655"
    }
    },
    "event_time": "2025-08-07T10:24:45+05:30",
    "type": "SUBSCRIPTION_PAYMENT_FAILED"
    }
    ```
  </Tab>

  <Tab title="Version (2023-08-01)">
    ```javascript theme={"dark"}
    {
    "data": {
        "payment_id": "12345",
        "cf_payment_id": "67890",
        "cf_txn_id": "789012",
        "cf_order_id": "98765",
        "subscription_id": "sub12345",
        "cf_subscription_id": "sub67890",
        "payment_type": "DEBIT_CARD",
        "authorization_details": {
            "authorization_amount": 100,
            "authorization_amount_refund": true,
            "approve_by_time": "2024-07-18T16:09:50+05:30",
            "authorization_reference": "6595231908096894505959",
            "authorization_time": "2024-07-18T16:09:51",
            "authorization_status": "ACTIVE",
            "payment_id": "123",
            "payment_method": "DEBIT_CARD",
            "instrument_id": "hsdg9"
        },
        "payment_amount": 200,
        "payment_schedule_date": "2024-07-20",
        "payment_initiated_date": "2024-07-20",
        "payment_remarks": "payment",
        "retry_attempts": 0,
        "failureDetails": {
            "failureReason": "Insufficient balance"
        },
        "payment_status": "FAILED",
        "payment_gateway_details": {
            "gateway_name": "CASHFREE",
            "gateway_subscription_id": "Demo_Subscription",
            "gateway_payment_id": "payment12345"
        }
    },
    "event_time": "2024-07-20T11:16:10+05:30",
    "type": "SUBSCRIPTION_PAYMENT_FAILED"
    }
    ```
  </Tab>
</Tabs>

## SUBSCRIPTION\_PAYMENT\_CANCELLED

This notification is sent whenever payment processing is cancelled by user for an active subscription.

<Tabs>
  <Tab title="Version (2025-01-01)">
    ```javascript Version (2025-01-01) theme={"dark"}
    {
    "data": {
    "payment_id": "433563_33_1754492527395",
    "cf_payment_id": "2011332",
    "cf_txn_id": null,
    "cf_order_id": "",
    "subscription_id": "subTestIdOndemand_2025080615020470",
    "cf_subscription_id": "1220385",
    "payment_type": "CHARGE",
    "authorization_details": {
      "authorization_amount": 1.00,
      "authorization_amount_refund": false,
      "approve_by_time": "",
      "authorization_reference": null,
      "authorization_time": "",
      "authorization_status": null,
      "payment_id": "433563_33_1754492527395",
      "payment_method": null,
      "payment_group": null
    },
    "payment_amount": 1.00,
    "payment_currency": "INR",
    "payment_schedule_date": "2025-08-08T12:00:00+05:30",
    "payment_initiated_date": "2025-08-06T20:32:07+05:30",
    "payment_remarks": null,
    "retry_attempts": 0,
    "failure_details": {
      "failure_reason": null
    },
    "payment_status": "CANCELLED",
    "payment_gateway_details": {
      "gateway_name": "CASHFREE",
      "gateway_subscription_id": "1220385",
      "gateway_payment_id": "2011332"
    }
    },
    "event_time": "2025-08-06T20:32:07+05:30",
    "type": "SUBSCRIPTION_PAYMENT_CANCELLED"
    }
    ```
  </Tab>

  <Tab title="Version (2023-08-01)">
    ```javascript theme={"dark"}
    {
    "data": {
        "payment_id": "12345",
        "cf_payment_id": "67890",
        "cf_txn_id": "789012",
        "cf_order_id": "98765",
        "subscription_id": "sub12345",
        "cf_subscription_id": "sub67890",
        "payment_type": "DEBIT_CARD",
        "authorization_details": {
            "authorization_amount": 100,
            "authorization_amount_refund": true,
            "approve_by_time": "2024-07-18T16:09:50+05:30",
            "authorization_reference": "6595231908096894505959",
            "authorization_time": "2024-07-18T16:09:51",
            "authorization_status": "ACTIVE",
            "payment_id": "123",
            "payment_method": "DEBIT_CARD",
            "instrument_id": "hsdg9"
        },
        "payment_amount": 200,
        "payment_schedule_date": "2024-07-20",
        "payment_initiated_date": "2024-07-20",
        "payment_remarks": "payment",
        "retry_attempts": 0,
        "failureDetails": {
            "failureReason": "Subscription is not active"
        },
        "payment_status": "CANCELLED",
        "payment_gateway_details": {
            "gateway_name": "CASHFREE",
            "gateway_subscription_id": "Demo_Subscription",
            "gateway_payment_id": "payment12345"
        }
    },
    "event_time": "2024-07-20T11:16:10+05:30",
    "type": "SUBSCRIPTION_PAYMENT_CANCELLED"
    }
    ```
  </Tab>
</Tabs>

## SUBSCRIPTION\_REFUND\_STATUS

This event is triggered whenever a refund status of a transaction will be success, failed, or cancelled.

<Tabs>
  <Tab title="Version (2025-01-01)">
    ```javascript theme={"dark"}
    {
    "data": {
    "payment_id": "yCzJxeT2aXDqI",
    "cf_payment_id": "49778199",
    "refund_id": "WHOqiwy05P1l0",
    "cf_refund_id": "SUB_21ebb4bf-e84f-4afa-bb09-07aac433abe4",
    "refund_amount": 1000.00,
    "refund_speed": "STANDARD",
    "refund_note": "Tesg Refund",
    "refund_status": "SUCCESS",
    "failure_details": "",
    "refund_gateway_details": {
      "gateway_name": "CASHFREE",
      "gateway_payment_id": "49778199",
      "gateway_refund_id": "SUB_21ebb4bf-e84f-4afa-bb09-07aac433abe4"
    }
    },
    "event_time": "2025-08-06T17:20:02+05:30",
    "type": "SUBSCRIPTION_REFUND_STATUS"
    }
    ```
  </Tab>

  <Tab title="Version (2023-08-01)">
    ```javascript theme={"dark"}
    {
    "data": {
        "payment_id": "pay8643",
        "cf_payment_id": "863782648",
        "refund_id": "refund2",
        "cf_refund_id": "ref_212",
        "refund_amount": 100,
        "refund_note": "test",
        "refund_speed": "INSTANT",
        "refund_status": "SUCCESS",
        "failure_details": null,
        "payment_gateway_details": {
            "gateway_name": "CASHFREE",
            "gateway_payment_id": "pay8643",
            "gateway_refund_id": "refund2"
        }
    },
    "event_time": "2023-01-03T11:16:10+05:30",
    "type": "SUBSCRIPTION_REFUND_STATUS"
    }
    ```
  </Tab>
</Tabs>

## SUBSCRIPTION\_CARD\_EXPIRY\_REMINDER

This event is triggered 7 days prior to the card’s expiry date for active card subscriptions.

<Tabs>
  <Tab title="Version (2025-01-01)">
    ```javascript theme={"dark"}
    {
    "data": {
        "subscription_status_webhook": {
            "subscription_details": {
                "cf_subscription_id": "23661347",
                "subscription_id": "SUB_TEST_1754550382119",
                "subscription_status": "ACTIVE",
                "subscription_expiry_time": "2050-12-31T00:00:00",
                "subscription_first_charge_time": "2025-09-30T00:00:00",
                "subscription_tags": {
                    "next_schedule_date": "2025-09-30T00:10:00"
                }
            },
            "customer_details": {
                "customer_name": "John Doe",
                "customer_email": "john@cashfree.com",
                "customer_phone": "9090909090"
            },
            "plan_details": {
                "plan_id": "PLAN_1754550139964",
                "plan_name": "MY_PLAN",
                "plan_type": "PERIODIC",
                "plan_max_cycles": 2,
                "plan_recurring_amount": 5,
                "plan_max_amount": 1000,
                "plan_interval_type": "MONTH",
                "plan_intervals": 1,
                "plan_currency": null,
                "plan_note": null,
                "plan_status": null
            },
            "authorization_details": {
                "authorizationAmount": 1,
                "authorizationAmountRefund": false,
                "approveByTime": "2025-09-06T12:36:22",
                "authorizationReference": null,
                "authorizationTime": "2025-08-07T13:14:18",
                "authorizationStatus": "ACTIVE",
                "paymentId": "160594_178_1754552533131",
                "paymentMethod": "card",
                "instrumentId": null
            },
            "payment_gateway_details": {
                "gateway_name": "CASHFREE",
                "gateway_subscription_id": "23661347",
                "gateway_plan_id": "PLAN_1754550139964",
                "gateway_auth_id": null
            }
        },
        "card_expiry_date": "2025-09-30"
    },
    "event_time": "2025-09-24T02:00:09+05:30",
    "type": "SUBSCRIPTION_CARD_EXPIRY_REMINDER"
    }
    ```
  </Tab>
</Tabs>

<Note>
  The following webhooks are only relevant if you are using Controlled API endpoints for notification and charge.
</Note>

## SUBSCRIPTION\_CONTROLLED\_NOTIFICATION\_STATUS

Cashfree sends this webhook when the status of a merchant-controlled payment notification attempt changes (for example, SUCCESS or FAILED).

<Tabs>
  <Tab title="Version (2025-01-01)">
    ```javascript theme={"dark"}
    {
    "data": {
    "cf_notification_id": "3333",
    "cf_order_id": "123456",
    "cf_payment_id": "123456",
    "cf_subscription_id": "7891011",
    "cf_txn_id": "123456",
    "notification_attempted_time": "2025-06-01T22:14:59+05:30",
    "notification_completed_time": "2025-06-01T22:15:59+05:30",
    "notification_failure_details": {
      "failure_reason": "",
      "failure_error_code": "",
      "failure_sub_error_code": ""
    },
    "notification_id": "notification-001",
    "notification_initiated_time": "2025-06-01T22:14:58+05:30",
    "notification_status": "SUCCESS",
    "payment_amount": 1,
    "payment_id": "test-payment-id",
    "payment_remarks": "monthly charge",
    "payment_status": "INITIALIZED",
    "subscription_id": "test-subscription-id"
    },
    "event_time": "2025-06-01T22:15:59+05:30",
    "type": "SUBSCRIPTION_CONTROLLED_NOTIFICATION_STATUS"
    }
    ```
  </Tab>
</Tabs>

## SUBSCRIPTION\_CONTROLLED\_EXECUTION\_STATUS

Cashfree sends this webhook when the status of a merchant-controlled charge execution attempt changes (for example, SUCCESS or FAILED).

<Tabs>
  <Tab title="Version (2025-01-01)">
    ```javascript theme={"dark"}
    {
    "data": {
    "cf_execution_id": "3333",
    "cf_order_id": "123456",
    "cf_payment_id": "123456",
    "cf_subscription_id": "7891011",
    "cf_txn_id": "123456",
    "execution_attempted_time": "2025-06-01T22:14:59+05:30",
    "execution_completed_time": "2025-06-01T22:15:59+05:30",
    "execution_id": "execution-001",
    "execution_initiated_time": "2025-06-01T22:14:58+05:30",
    "execution_status": "SUCCESS",
    "failure_details": {
      "failure_reason": "",
      "failure_error_code": "",
      "failure_sub_error_code": ""
    },
    "payment_amount": 1,
    "payment_id": "test-payment-id",
    "payment_remarks": "",
    "payment_status": "SUCCESS",
    "subscription_id": "test-subscription-id"
    },
    "event_time": "2025-06-01T22:15:59+05:30",
    "type": "SUBSCRIPTION_CONTROLLED_EXECUTION_STATUS"
    }
    ```
  </Tab>
</Tabs>


# Delete Saved Card Instrument
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/token-vault/delete

openapi/payments/v2025-01-01.yaml delete /customers/{customer_id}/instruments/{instrument_id}
Use this API to delete a specific saved card stored for the customer in Cashfree’s [Token Vault](https://www.cashfree.com/docs/payments/features/token-vault).



# Get Cryptogram for a Saved Card Instrument
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/token-vault/generate-cryptogram

openapi/payments/v2025-01-01.yaml get /customers/{customer_id}/instruments/{instrument_id}/cryptogram
Use this API to retrieve the token and cryptogram for a specific saved card stored in Cashfree's [Token Vault](https://www.cashfree.com/docs/payments/features/token-vault). 



# Get Specific Saved Card Instrument
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/token-vault/get

openapi/payments/v2025-01-01.yaml get /customers/{customer_id}/instruments/{instrument_id}
Use this API to fetch a specific saved card stored for the customer in Cashfree’s [Token Vault](https://www.cashfree.com/docs/payments/features/token-vault).



# Get All Saved Card Instrument
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/token-vault/get-all

openapi/payments/v2025-01-01.yaml get /customers/{customer_id}/instruments?instrument_type=card
Use this API to fetch all saved cards stored for the customer in Cashfree’s [Token Vault](https://www.cashfree.com/docs/payments/features/token-vault).



# Card Token Webhook
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/token-vault/webhooks

Receive asynchronous notification for updates on a card instrument, which is requested to be tokenised.

| Event | Description |
| - | - |
| INSTRUMENT\_ACTIVE\_WEBHOOK | This webhook is triggered when the card is successfully tokenised. |
| INSTRUMENT\_FAILED\_WEBHOOK | This webhook is triggered when the card tokenisation fails. |

For more information on how to configure webhooks, see [Webhook configuration](/docs/payments/online/webhooks/configure).

## Instrument active webhook

<Tabs>
  <Tab title="Version (2025-01-01)">
    ```javascript Instrument active webhook theme={"dark"}
    {
       "data": {
          "instrument": {
             "customer_id": "siddhesh199721",
             "afa_reference": "887316963",
             "instrument_id": "af250dc5-e5e5-4e7d-a7cf-3f446741fa54",
             "instrument_type": "card",
             "instrument_uid": "680cd7171583f9f64b426983d4501d6941b462932ce5f626be78392d5ec42660",
             "instrument_display": "XXXXXXXXXXXX6854",
             "instrument_status": "ACTIVE",
             "added_at": "2022-04-14T10:42:59+05:30",
             "instrument_meta": {
                "card_network": "visa",
                "card_bank_name": "HDFC BANK",
                "card_country": "IN",
                "card_type": "credit",
                "sub_type": "R",
                "card_par": "50012ADWQZJKHCLXLT61QTYD5QNX1",
                "card_token_details": null
             }
          }
       },
       "event_time": "2022-04-14T10:44:14+05:30",
       "type": "INSTRUMENT_ACTIVE_WEBHOOK"
    }
    ```
  </Tab>
</Tabs>

## Instrument failed Webhook

<Tabs>
  <Tab title="Version (2025-01-01)">
    ```javascript Instrument failed webhook theme={"dark"}
    {
       "data": {
          "instrument": {
             "customer_id": "siddhesh199721",
             "afa_reference": "887316963",
             "instrument_id": "af250dc5-e5e5-4e7d-a7cf-3f446741fa54",
             "instrument_type": "card",
             "instrument_uid": "680cd7171583f9f64b426983d4501d6941b462932ce5f626be78392d5ec42660",
             "instrument_display": "XXXXXXXXXXXX6854",
             "instrument_status": "FAILED",
             "added_at": "2022-04-14T10:42:59+05:30",
             "instrument_meta": {
                "card_network": "visa",
                "card_bank_name": "HDFC BANK",
                "card_country": "IN",
                "card_type": "credit",
                "sub_type": "R",
                "card_par": null,
                "card_token_details": null
             }
          },
          "error_details": {
             "error_code": "NETWORK_ERROR",
             "error_description": "Error while processing the request",
             "error_source": "NETWORK"
          }
       },
       "event_time": "2022-04-14T10:44:14+05:30",
       "type": "INSTRUMENT_FAILED_WEBHOOK"
    }
    ```
  </Tab>
</Tabs>

<Accordion title="Understanding the payload">
  ## Payload field description

  | Field | Description | Type |
  | - | - | - |
  | customer\_id | For checkout, this is the customer phone number and for seamless this is the customer ID provided by the merchant during the [Create Order API](/docs/api-reference/payments/previous/v2025-01-01/orders/create) call, which is used to save cards for the customer. | `string` |
  | afa\_reference | Represents the `cf_payment_id` of the successful transaction done while saving the instrument. | `string` |
  | instrument\_id | Represents the identifier for the card saved at Cashfree. | `string` |
  | instrument\_type | Specifies the type of instrument. Available options: `card`. | `enum<string>` |
  | instrument\_uid | Represents the unique identifier for the card, used to identify a specific card. | `string` |
  | instrument\_display | Shows the last 4 digits of the actual card number. | `string` |
  | instrument\_status | Shows the status of the saved instrument. It is `ACTIVE` when the card is successfully tokenised, else `FAILED`. Available options: `ACTIVE`, `FAILED`. | `enum<string>` |
  | added\_at | Shows the timestamp at which the instrument was attempted to be saved. | `string` |
  | card\_network | Specifies the card scheme or network. Available options: `visa`, `mastercard`, `rupay`, `amex`, `diners`. | `string` |
  | card\_bank\_name | Shows the issuing bank name of the card. Examples: `HDFC BANK`, `ICICI BANK`, `AXIS BANK`. | `string` |
  | card\_country | Shows the issuing country of the card. Example: `IN`. | `string` |
  | card\_type | Specifies the type of card. Available options: `credit`, `debit`, `prepaid`. | `string` |
  | sub\_type | Specifies the sub-type of card. `R` = Retail, `P` = Premium, `C` = Corporate. Available options: `R`, `P`, `C`. | `string` |
  | card\_par | Represents the [PAR](/docs/payments/features/payment-account-reference) for the plain card. Appears only in instrument active webhook when the card is tokenised successfully. | `string` |
  | card\_token\_details | Always passed as null. | `object` |
  | event\_time | Shows the time at which the webhook is initiated. | `string` |
  | type | Specifies the type of the instrument webhook. Available options: `INSTRUMENT_ACTIVE_WEBHOOK`, `INSTRUMENT_FAILED_WEBHOOK`. | `string` |
</Accordion>


# Get Card BIN Details
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/utilities/get-card-bin

post /utilities/cardbin
Use this API to get [Card BIN](https://www.cashfree.com/docs/payments/features/utility-apis) (Bank Identification Number) details.



# Get PAR
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/utilities/get-par

post /utilities/pars
Use this API to get [Payment Account Reference (PAR)](https://www.cashfree.com/docs/payments/features/payment-account-reference) by providing plain card details.



# Fetch All Downtimes
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/utilities/incidents/fetch-all-downtimes

get /incident
Fetches active downtimes across various payment methods based on filters. Gives all active downtimes when no filters are applied.



# Fetch Downtime by ID
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/utilities/incidents/fetch-downtime-by-id

get /incident/{id}
Fetches details of a specific downtime using its unique ID.



# Incident Service Webhook
Source: https://www.cashfree.com/docs/api-reference/payments/previous/v2025-01-01/utilities/incidents/incident-webhook

Subscribe to Cashfree's Incident Service Webhook to get notified by email or server callback when an issuing bank has high failures or maintenance.

Cashfree will notify you whenever we create an incident at our end. An incident implies that the issuing bank is facing high failure rates or has scheduled a maintenance activity during that time. The former could be due to many reasons and until the failure rates go down, we would recommend customers to use alternative payment instruments.

There are two channels through which we notify. You can subscribe to either of the channels by adding your email address and webhook endpoint in the merchant dashboard.
Email - Cashfree will send an email alert when an issuer is facing downtime or a scheduled incident.
Webhooks - Cashfree will invoke a server to server call whenever an incident is created. You can use this webhook and update your payment page accordingly.

## Webhook Schema of Incident Service Webhook

### Sample Payload for Creation of Incident

<Tabs>
  <Tab title="Version (2025-01-01)">
    ```javascript Version (2025-01-01) theme={"dark"}
    {
      "data": {
        "incident": {
          "end_time": "2025-04-29T09:11:48+05:30",
          "id": "x77rkd7phl5dobr94k1s",
          "impact": "HIGH",
          "message": "Payment mode up",
          "start_time": "2025-04-22T09:11:48+05:30",
          "status": "RESOLVED",
          "type": "SCHEDULED"
        },
        "instruments": {
          "upi": {
            "issuers": [
              "DEUTSCHE BANK"
            ]
          }
        }
      },
      "event_time": "2025-04-22T14:42:08+05:30",
      "type": "HEALTH_ALERT"
    }
    ```
  </Tab>

  <Tab title="Version (2023-08-01)">
    ```javascript Version (2023-08-01) theme={"dark"}
    {
      "data": {
        "incident": {
          "end_time": "2025-04-29T09:11:48+05:30",
          "id": "x77rkd7phl5dobr94k1s",
          "impact": "HIGH",
          "message": "Payment mode up",
          "start_time": "2025-04-22T09:11:48+05:30",
          "status": "RESOLVED",
          "type": "SCHEDULED"
        },
        "instruments": {
          "upi": {
            "issuers": [
              "DEUTSCHE BANK"
            ]
          }
        }
      },
      "event_time": "2025-04-22T14:42:08+05:30",
      "type": "HEALTH_ALERT"
    }
    ```
  </Tab>
</Tabs>

### Sample Payload When Incident is Resolved

<Tabs>
  <Tab title="Version (2025-01-01)">
    ```javascript Version (2025-01-01) theme={"dark"}
    {
        "data": {
          "incident": {
            "end_time": "2025-04-29T09:11:48+05:30",
            "id": "x77rkd7phl5dobr94k1s",
            "impact": "HIGH",
            "message": "Payment mode up",
            "start_time": "2025-04-22T09:11:48+05:30",
            "status": "RESOLVED",
            "type": "SCHEDULED"
          },
          "instruments": {
            "upi": {
              "issuers": [
                "DEUTSCHE BANK"
              ]
            }
          }
        },
        "event_time": "2025-04-22T14:42:08+05:30",
        "type": "HEALTH_ALERT"
    }
    ```
  </Tab>

  <Tab title="Version (2023-08-01)">
    ```javascript Version (2023-08-01) theme={"dark"}
    {
        "data": {
          "incident": {
            "end_time": "2025-04-29T09:11:48+05:30",
            "id": "x77rkd7phl5dobr94k1s",
            "impact": "HIGH",
            "message": "Payment mode up",
            "start_time": "2025-04-22T09:11:48+05:30",
            "status": "RESOLVED",
            "type": "SCHEDULED"
          },
          "instruments": {
            "upi": {
              "issuers": [
                "DEUTSCHE BANK"
              ]
            }
          }
        },
        "event_time": "2025-04-22T14:42:08+05:30",
        "type": "HEALTH_ALERT"
    }
    ```
  </Tab>
</Tabs>

### Payload

| Field | Description | Example | Mandatory |
| - | - | - | - |
| end\_time | Null when an incident is created. Or end time when incident is resolved | 2021-04-16T15:10:36+05:30 | No |
| start\_time | Time since we have seen this incident | 2021-04-16T14:10:36+05:30 | Yes |
| id | Incident id | Alphanumeric with \_,- | Yes |
| impact | Impact of the downtime | HIGH, MEDIUM, LOW | Yes |
| message | Human readable message | | No |
| status | Status of the incident. OPEN when created, RESOLVED when resolved, UPDATE when updated with details | OPEN, UPDATE, RESOLVED | Yes |
| type | Is this a scheduled or an unscheduled downtime? | SCHEDULED, UNSCHEDULED | Yes |
| instruments | Refers to the payment mode. This will contain a nested object | | Yes |
| upi.issuers | Issuers which are impacted | Array | No |
| net\_banking.issuers | Net banking banks which are impacted | Array | No |
| wallet.issuers | Wallets which are impacted | Array | No |
| card.type | Card types which are impacted | CREDIT\_CARD, DEBIT\_CARD, ALL | No |
| card.scheme | Card schemes which are impacted | MASTER, VISA, RUPAY, MAESTRO, AMEX, Multiple Schemes | No |
| card.issuers | Banks which are impacted | Array | No |
| event\_time | Time when this webhook was created | | Yes |
| type | Type of webhook | HEALTH\_ALERT | Yes |
| version | Version of webhook. You should build your parsing logic with respect to this version | | Yes |

| Children | Optional | Type | Possible Values |
| - | - | - | - |
| wallet | Y\* | Child attributes | Available below |
| net\_banking | Y\* | Child attributes | Available below |
| upi | Y\* | Child attributes | Available below |
| card | Y\* | Child attributes | Available below |

> At least one of the children needs to be present

### Wallet

| Children | Optional | Type | Possible Values |
| - | - | - | - |
| issuers | N | Text | See list of wallet issuers below. |

### Net Banking

| Children | Optional | Type | Possible Values |
| - | - | - | - |
| issuers | N | Array | See list of issuers below. |

### UPI

| Children | Optional | Type | Possible Values |
| - | - | - | - |
| issuers | N | Array | See list of issuers below. |

### Card

| Children | Optional | Type | Possible Values |
| - | - | - | - |
| type | N | Text | CREDIT\_CARD, DEBIT\_CARD, ALL |
| scheme | N | Text | MASTER, VISA, RUPAY, MAESTRO, AMEX, Multiple Schemes |
| issuers | N | Array | See list of issuers below. |

### Payload Headers

Cashfree will send two custom headers for every webhook being invoked by our system.

| Name | Description | Example |
| - | - | - |
| x-cashfree-timestamp | Timestamp for this event. Used to generate signature | 1618562436364 |
| x-cashfree-signature | Cashfree signature for this webhook | ke+K3gR8GssH9AMfJm+0+8jGIL1Mq7hOheP9w36/hL0= |

## Signature Generation

The signature must be used to verify if the request has not been tampered with. To verify the signature at your end, you will need your Cashfree Payment Gateway secret key along with the payload.

```
//The payload here refers to the raw request sent by 
Cashfree to your endpoint. No modifications need to be 
done to this payload.

payload := {"data":{"bank_name":"Test Bank",
"card_type":"Visa","health":"DEGRADED",
"incident_end_time":"2021-04-07T00:20:30",
"incident_id":"INCIDENT_HIGH_Test Bank_954b95zz-f11a-test-abcd-0eb0e8608847",
"incident_impact":"High",
"incident_start_time":"2021-04-06T00:20",
"incident_type":"Scheduled",
"is_resolved":false,
"issuers":[],
"message":"We are facing high failure issues in Payment gateway at the moment and will keep you updated about the issue.",
"payment_gateway":null,"payment_mode":"DEBIT_CARD",
"scope":"PaymentMode"},
"type":"HEALTH_ALERT","version":1}

# timestamp is present in the header x-cashfree-timestamp
timestamp := 1617695238078

signedPayload := $timestamp.$payload

expectedSignature := Base64Encode(HMACSHA256($signedPayload, $merchantSecretKey))
```

## Bank Names

* Axis Bank
* Bank of Baroda - Retail Banking
* Bank of India
* Bank of Maharashtra
* Canara Bank
* Catholic Syrian Bank
* Central Bank of India
* City Union Bank
* Deutsche Bank
* DBS Bank Ltd
* DCB Bank - Personal
* Dhanlakshmi Bank
* Federal Bank
* HDFC Bank
* ICICI Bank
* IDBI Bank
* IDFC Bank
* Indian Bank
* Indian Overseas Bank
* IndusInd Bank
* Jammu and Kashmir Bank
* Karnataka Bank Ltd
* Karur Vysya Bank
* Kotak Mahindra Bank
* Laxmi Vilas Bank - Retail Net Banking
* Punjab & Sind Bank
* Punjab National Bank - Retail Net Banking
* RBL Bank
* Saraswat Bank
* South Indian Bank
* Standard Chartered Bank
* State Bank Of India
* Tamilnad Mercantile Bank Ltd
* UCO Bank
* Union Bank of India
* Yes Bank Ltd
* Bank of Baroda - Corporate
* Bank of India - Corporate
* DCB Bank - Corporate
* Lakshmi Vilas Bank - Corporate
* Punjab National Bank - Corporate
* State Bank of India - Corporate
* Union Bank of India - Corporate
* Axis Bank Corporate
* Dhanlaxmi Bank Corporate
* ICICI Corporate Netbanking
* Ratnakar Corporate Banking
* Shamrao Vithal Bank Corporate
* Equitas Small Finance Bank
* Yes Bank Corporate
* Bandhan Bank- Corporate banking
* Barclays Corporate- Corporate Banking - Corporate
* Indian Overseas Bank Corporate
* City Union Bank of Corporate
* HDFC Corporate
* Shivalik Bank
* AU Small Finance
* Bandhan Bank - Retail Net Banking
* Shamrao Vitthal Co-operative Bank
* Tamil Nadu State Co-operative Bank

All Banks (Note: This parameter will be sent when all banks are having a downtime)

## Wallet Names

* FreeCharge
* MobiKwik
* Ola Money
* Reliance Jio Money
* Airtel Money
* Paytm
* Amazon Pay
* PhonePe

## Compute Signature and Verify

#### Sample code

#### Verify Signature using SDK

<CodeGroup>
  ```javascript Node(express) theme={"dark"}
  var express = require('express')
  import { Cashfree } from "cashfree-pg"; 
  var app = express()

  Cashfree.XClientId = "<x-client-id>";
  Cashfree.XClientSecret = "<x-client-secret>";
  Cashfree.XEnvironment = Cashfree.Environment.SANDBOX;

  app.post('/webhook', function (req, res) {
      try {
          Cashfree.PGVerifyWebhookSignature(req.headers["x-webhook-signature"], req.rawBody, req.headers["x-webhook-timestamp"]))
      } catch (err) {
          console.log(err.message)
      }
  })
  ```

  ```go Go theme={"dark"}
  import (
    cashfree "github.com/cashfree/cashfree-pg/v4"
  )

  // Route
  e.POST("/webhook", _this.Webhook)

  // Controller
  func (_this *WebhookRoute) Webhook(c echo.Context) error {
    	clientId := "<x-client-id>"
  		clientSecret := "<x-client-secret>"
  		cashfree.XClientId = &clientId
  		cashfree.XClientSecret = &clientSecret
  		cashfree.XEnvironment = cashfree.SANDBOX
    
      signature := c.Request().Header.Get("x-webhook-signature")
      timestamp := c.Request().Header.Get("x-webhook-timestamp")
      
      body, _ := ioutil.ReadAll(c.Request().Body)
      rawBody := string(body)
      webhookEvent, err := cashfree.PGVerifyWebhookSignature(signature, rawBody, timestamp)
      if err != nil {
  		fmt.Println(err.Error())
  	} else {
  		fmt.Println(webhookEvent.Object)
  	}
  }
  ```

  ```php PHP theme={"dark"}
  <?php

  $inputJSON = file_get_contents('php://input');

  $expectedSig = getallheaders()['x-webhook-signature'];
  $ts = getallheaders()['x-webhook-timestamp'];

  if(!isset($expectedSig) || !isset($ts)){
      echo "Bad Request";
      die();
  }

  \Cashfree\Cashfree::$XClientId = "<x-client-id>";
  \Cashfree\Cashfree::$XClientSecret = "<x-client-secret>";
  $cashfree = new \Cashfree\Cashfree();

  try {
   $response =  cashfree->PGVerifyWebhookSignature($expectedSig, $inputJSON, $ts);
  } catch(Exception $e) {
    // Error if signature verification fails
  }
  ?>
  ```

  ```python Python theme={"dark"}
  from cashfree_pg.api_client import Cashfree

  @app.route('/webhook', methods = ['POST'])
  def disp():
  		# Get the raw body from the request
      raw_body = request.data
    
      # Decode the raw body bytes into a string
      decoded_body = raw_body.decode('utf-8')

      #verify_signature
      timestamp = request.headers['x-webhook-timestamp']
      signature = request.headers['x-webhook-signature']
  		
  		cashfree = Cashfree()
  		cashfree.XClientId = "<app_id>"
  		cashfree.XClientSecret = "<secret_key>"
  		try:
  			cashfreeWebhookResponse = cashfree.PGVerifyWebhookSignature(signature, decoded_body, timestamp)
  		except:
  			# If Signature mis-match
  ```

  ```java Java theme={"dark"}
  import com.cashfree.*;

  @PostMapping("/my-endpoint")
  public String handlePost(HttpServletRequest request) throws IOException {      
      Cashfree.XClientId = "<x-client-id>";
  		Cashfree.XClientSecret = "<x-client-secret>";
  		Cashfree.XEnvironment = Cashfree.SANDBOX;
    
    	StringBuilder stringBuilder = new StringBuilder();
      BufferedReader bufferedReader = null;

      try {           
        bufferedReader = request.getReader();
        String line;
        while ((line = bufferedReader.readLine()) != null) {
                stringBuilder.append(line).append('\n');
        }
          
          
        String rawBody = stringBuilder.toString();
        String signature = request.getHeader("x-webhook-signature");
        String timestamp = request.getHeader("x-webhook-timestamp");
          
        Cashfree cashfree = new Cashfree();
        PGWebhookEvent webhook = cashfree.PGVerifyWebhookSignature(signature, rawBody, timestamp);
            
      } catch (Exception e) {
              // Error if verification fails
      } finally {
           if (bufferedReader != null) {
              bufferedReader.close();
  		}
  	}
        
  }
  ```

  ```csharp C# theme={"dark"}
  import com.cashfree.*;

  @PostMapping("/my-endpoint")
  public String handlePost(HttpServletRequest request) throws IOException {      
      Cashfree.XClientId = "<x-client-id>";
  		Cashfree.XClientSecret = "<x-client-secret>";
  		Cashfree.XEnvironment = Cashfree.SANDBOX;
    
    	StringBuilder stringBuilder = new StringBuilder();
      BufferedReader bufferedReader = null;

      try {           
        bufferedReader = request.getReader();
        String line;
        while ((line = bufferedReader.readLine()) != null) {
                stringBuilder.append(line).append('\n');
        }
          
          
        String rawBody = stringBuilder.toString();
        String signature = request.getHeader("x-webhook-signature");
        String timestamp = request.getHeader("x-webhook-timestamp");
          
        Cashfree cashfree = new Cashfree();
        PGWebhookEvent webhook = cashfree.PGVerifyWebhookSignature(signature, rawBody, timestamp);
            
      } catch (Exception e) {
              // Error if verification fails
      } finally {
           if (bufferedReader != null) {
              bufferedReader.close();
  		}
  	}
        
  }
  ```
</CodeGroup>

### Compute Signature and Verify manually

<CodeGroup>
  ```javascript Node(express) theme={"dark"}
  function verify(ts, rawBody){
      const body = req.headers["x-webhook-timestamp"] + req.rawBody;
      const secretKey = "<your secret key>";
      let genSignature = crypto.createHmac('sha256',secretKey).update(body).digest("base64");
      return genSignature
  }
  ```

  ```go Go theme={"dark"}
  func VerifySignature(expectedSig string, ts string, body string) (string, error) {
  	t := time.Now()
  	currentTS := t.Unix()
  	if currentTS-ts > 1000*300 {
  		return "", errors.New("webhook delivered too late")
  	}
  	signStr := strconv.FormatInt(ts, 10) + body
  	fmt.Println("signing String: ", signStr)
  	key := ""
  	h := hmac.New(sha256.New, []byte(key))
  	h.Write([]byte(signStr))
  	b := h.Sum(nil)
  	return base64.StdEncoding.EncodeToString(b), nil
  }

  timestamp := c.Request().Header.Get("x-webhook-timestamp")
  body, _ := ioutil.ReadAll(c.Request().Body)
  rawBody := string(body)
  signature := c.Request().Header.Get("x-webhook-signature")

  VerifySignature(signature, timestamp, rawBody)
  ```

  ```php PHP theme={"dark"}
  function computeSignature($ts, $rawBody){
      $rawBody = file_get_contents('php://input');
  		$ts = getallheaders()['x-webhook-timestamp'];
    
      $signStr = $ts . $rawBody;
      $key = "";
      $computeSig = base64_encode(hash_hmac('sha256', $signStr, $key, true));
      return $computeSig;
  }
  ```

  ```java Java theme={"dark"}
  public String generateSignature() {

  	bufferedReader = request.getReader();
    String line;
    while ((line = bufferedReader.readLine()) != null) {
       stringBuilder.append(line).append('\n');
    }      
    String payload = stringBuilder.toString();
    String timestamp = request.getHeader("x-webhook-timestamp");
        
    String data = timestamp+payload;

    String secretKey = "SECRET-KEY"; // Get secret key from Cashfree Merchant Dashboard;
    Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
    SecretKeySpec secret_key_spec = new SecretKeySpec(secretKey.getBytes(),"HmacSHA256");
    sha256_HMAC.init(secret_key_spec);
    String computed_signature = Base64.getEncoder().encodeToString(sha256_HMAC.doFinal(data.getBytes()));
    return computed_signature; // compare with "x-webhook-signature"
  }
  ```

  ```python Python theme={"dark"}
  import base64
  import hashlib
  import hmac

  def generateSignature():    
      # Get the raw body from the request
      raw_body = request.data
    
      # Decode the raw body bytes into a string
      payload = raw_body.decode('utf-8')

      #verify_signature
      timestamp = request.headers['x-webhook-timestamp']
      
      signatureData = timestamp+payload
      message = bytes(signatureData, 'utf-8')
      secretkey=bytes("Secret_Key",'utf-8') #Get Secret_Key from Cashfree Merchant Dashboard.
      signature = base64.b64encode(hmac.new(secretkey, message, digestmod=hashlib.sha256).digest())
      computed_signature = str(signature, encoding='utf8')
      return computed_signature #compare with "x-webhook-signature"
  ```
</CodeGroup>


# Rate Limits
Source: https://www.cashfree.com/docs/api-reference/payments/rate-limits

Review the per-minute rate limits applied to Cashfree API endpoints and learn how to detect throttling using response headers.

<Note>
  You can view your API usage and rate limits on your dashboard. Go to **Developers** > **Rate Limits** to view various metrics such as: `Rate Limit`, `Latest Usage`, `Average Usage`, `Burst limit`, `Request Count` and `Violation Count`.
</Note>

## Rate limiting

We use rate limiting for all endpoints. Rate limiting is based on your IP and your account Id. By default, the following rate limits are applied per minute. You can also view your rate limits in the response headers.

<Tabs>
  <Tab title="Production">
    ### Rate limit in Production

    | API | Rate limit value per minute | Rate limit type |
    | :- | :- | :- |
    | Create Order | 200 | Account |
    | Get Order | 400 | Account |
    | Get Payments | 100 | Account |
    | Get Payments by ID | 130 | Account |
    | Pay Order | 100 | IP |
    | Get Settlements | 30 | Account |
    | Initiate Refund | 100 | Account |
    | Get Refund | 30 | Account |
  </Tab>

  <Tab title="Sandbox">
    ### Rate limits in Sandbox

    | API | Rate limit value per minute | Rate limit type |
    | :- | :- | :- |
    | Create Order | 30 | Account |
    | Get Order | 60 | Account |
    | Get Payments | 30 | Account |
    | Pay Order | 30 | IP |
    | Get Settlements | 20 | Account |
    | Initiate Refund | 30 | Account |
    | Get refund | 60 | Account |
  </Tab>
</Tabs>

## Rate limiting headers

All responses will have the following headers to help you understand rate limiting.

| Header name | Example | Description |
| :- | :- | :- |
| x-ratelimit-limit | 100 | Max number of calls that can be made in a minute |
| x-ratelimit-remaining | 30 | Remaining number of calls that can be made in a minute |
| x-ratelimit-retry | 0 | Number of seconds you will have to wait to make the next call |
| x-ratelimit-type | `app_id` or `ip` | Type of rate limiting applied |

## Upgrading limits

You can increase rate limits or burst limits at an API level through the Merchant Dashboard.

To request a limit increase:

1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).

2. Go to **Payment Gateway > Developers > Rate Limits**.

   <img alt="API rate limits dashboard showing list of APIs with their current limits" />

   *Rate Limits page showing all APIs with current limits*

3. Select **Request new limit** for the API you want to change the limit for.

   <img alt="Request new limit form with fields for rate limit and burst limit" />

   *Request form for increasing rate or burst limits*

4. Enter the new rate or burst limit you require. For burst limit, enter the time duration.

   <Note>The total limit is the sum of the rate limit and burst limits.</Note>

5. Provide the reason for the request and click **Submit**.

After you submit the request, it will be reviewed and approved within 1-2 business days. Once approved, the new rate limits will be applied to your account.


# Payment SDK
Source: https://www.cashfree.com/docs/api-reference/payments/sdk

Integrate the Cashfree SDKs for server-side languages and mobile platforms to accept payments without writing low-level REST code.

Cashfree server-side SDKs reduce the amount of work required to use Cashfree's REST APIs. Below are the links for these libraries in a variety of popular server-side programming languages.

## Server SDK

<CardGroup>
  <Card title="Python SDK" icon="python" href="https://github.com/cashfree/cashfree-pg-sdk-python">
    Version **5.0.5**. Server-side SDK for Python applications with comprehensive payment gateway integration.
  </Card>

  <Card title="Node.js SDK" icon="node-js" href="https://github.com/cashfree/cashfree-pg-sdk-nodejs">
    Version **5.1.0**. JavaScript/TypeScript SDK for Node.js applications and serverless functions.
  </Card>

  <Card title="Java SDK" icon="java" href="https://github.com/cashfree/cashfree-pg-sdk-java">
    Version **5.0.1**. Enterprise-grade SDK for Java applications and Spring Boot projects.
  </Card>

  <Card title="PHP SDK" icon="php" href="https://github.com/cashfree/cashfree-pg-sdk-php">
    Version **5.0.3**. Lightweight SDK for PHP applications and Laravel projects.
  </Card>

  <Card title=".NET SDK" icon="microsoft" href="https://github.com/cashfree/cashfree-pg-sdk-dotnet">
    Version **6.0.7**. Cross-platform SDK for .NET Core and .NET Framework applications. Install via NuGet: `cashfree-dotnet-pg`.
  </Card>

  <Card title="Go SDK" icon="golang" href="https://github.com/cashfree/cashfree-pg">
    Version **5.1.9**. High-performance SDK for Go applications and microservices.
  </Card>
</CardGroup>


# Getting Started
Source: https://www.cashfree.com/docs/api-reference/payouts/getting-started-with-payouts-apis

Review the prerequisites, sandbox credentials, IP whitelisting, and signature setup you need before testing Cashfree Payouts APIs in your integration.

<div>
  <iframe title="YouTube video player" />
</div>

<Note>
  Version 2 APIs: Cashfree has new [version 2 APIs for Payouts](/docs/api-reference/payouts/v2/payouts-api-v2-new). The v2 APIs represent a significant leap forward in payouts integration, offering enhanced versioning, standardised requests and responses, efficient troubleshooting, standardisation across products, and simplified transfer APIs.
</Note>

This article covers the following topics:

* [Download Postman collection](#download-postman-collection)
* [View endpoints](#view-endpoints)
* [Generate API keys](#generate-api-keys)
* [Whitelist IP address](#whitelist-your-ip-address) or [Generate signature](#generate-signature)
* [Contact support](#any-queries-contact-support)

## Download Postman collection

This collection can save you time because of easy access to different requests.

<a href="https://gocashassets.s3.ap-south-1.amazonaws.com/repostmancollection/Cashfree_Payouts_Collection.json.zip">
  Download Cashfree Payouts Postman Collection
</a>

## View endpoints

For [Payout v2 APIs](/docs/api-reference/payouts/v2/payouts-api-v2-new): \[NEW]

| Environment | Base address |
| :- | :- |
| Production | [https://api.cashfree.com/payout](https://api.cashfree.com/payout) |
| Test | [https://sandbox.cashfree.com/payout](https://sandbox.cashfree.com/payout) |

For Payout v1 and v1.2 APIs:

| Environment | Base address |
| :- | :- |
| Production | [https://payout-api.cashfree.com](https://payout-api.cashfree.com) |
| Test | [https://payout-gamma.cashfree.com](https://payout-gamma.cashfree.com) |

Cashfree uses unique identifiers to allow access to the API. After you sign up at the merchant site, you can see your **AppId** and **SecretKey**. Each API request to the server requires these credentials.

Use this endpoint to verify your credentials: **/api/v1/credentials/verify**

## Generate API keys

To generate API keys:

1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
2. From the Payouts dashboard, click **Developers** on the navigation panel.
3. Click **API Keys**.
4. Click **Generate API Keys** from the API Keys screen.
5. The New API Keys popup displays with the client ID and client secret information.
6. Click **Download API Keys** to download the information and save them in your local system folder. Don't share the keys with anyone because they're confidential. You can generate a maximum of 10 API keys.

   <Frame>
     <img />
   </Frame>

<Note>
  API Keys - Production Environment: You need to perform an OTP authentication
  to generate API keys for the production environment.
</Note>

## Identity verification

Whitelisting the IP address or generating a signature provides a layer of authentication. These cybersecurity techniques prevent anonymous or unknown disbursement requests and allow only verified requests.

### Whitelist your IP address

Your IP address needs to be whitelisted in the Cashfree production server or it rejects all incoming requests.

<Note>
  Only the production environment needs approval from Cashfree and not
  for the test environment.
</Note>

To whitelist your IP:

1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
2. From the Payouts dashboard, click **Developers** > **Two-Factor Authentication**.
3. Choose **IP Whitelist** from the **Select 2FA Method** drop-down.
4. Click **Add IP Address**.
5. Enter the IP address you want to whitelist in the respective field and click **Add IP Address** to save the details. Note that the IPv4 has to be whitelisted, and not IPv6. The whitelisted IPs display in the grid as shown below. You can whitelist a maximum of 25 IPs.

   <Frame>
     <img />
   </Frame>

### Generate signature

To generate a signature, you need to generate the public key. You then use the generated public key to generate the signature.

#### Generating a public key

1. From the **Payouts** dashboard, click **Developers** > **Two-Factor Authentication**.
2. Select **Public Key** from the **Select 2FA Method** drop-down.
3. Click **Generate Public Key**.
4. The public key is downloaded to your computer. Use your registered email ID to access the key.

   <Frame>
     <img />
   </Frame>

#### Generating a signature

To generate your signature:

1. Retrieve your clientId (one which you're passing through the header X-Client-Id).
2. Append this with CURRENT UNIX timestamp separated by a period (.).
3. Encrypt this data using RSA encrypt with public key you received—this is the signature.
4. Pass this signature through the header X-Cf-Signature.

When using the Cashfree library, go through the libraries section. During the initialisation process, you need to pass the key as a parameter.

<CodeGroup>
  ```php PHP theme={"dark"}
  <?php
  public static function getSignature() {
      $clientId = "<your clientId here>";
      $publicKey =
  openssl_pkey_get_public(file_get_contents("/path/to/certificate/public
  _key.pem"));
      $encodedData = $clientId.".".strtotime("now");
      return static::encrypt_RSA($encodedData, $publicKey);
    }
  private static function encrypt_RSA($plainData, $publicKey) { if (openssl_public_encrypt($plainData, $encrypted, $publicKey,
  OPENSSL_PKCS1_OAEP_PADDING))
        $encryptedData = base64_encode($encrypted);
      else return NULL;
      return $encryptedData;
    }
  ?>
  ```

  ```java Java theme={"dark"}
  private static String generateEncryptedSignature(String clientIdWithEpochTimestamp) {
      // String clientIdWithEpochTimeStamp = clientId+"."+Instant.now().getEpochSecond();
      String encrytedSignature = "";
      try {
          byte[] keyBytes = Files
              .readAllBytes(new File("/Users/sameera/Downloads/payout_test_public_key.pem").toPath()); // Absolute Path to be replaced
          String publicKeyContent = new String(keyBytes);
          System.out.println(publicKeyContent);
          publicKeyContent = publicKeyContent.replaceAll("[\\t\\n\\r]", "")
              .replace("-----BEGIN PUBLIC KEY-----", "").replace("-----END PUBLIC KEY-----", "");
          KeyFactory kf = KeyFactory.getInstance("RSA");
          System.out.println(publicKeyContent);
          X509EncodedKeySpec keySpecX509 = new X509EncodedKeySpec(
              Base64.getDecoder().decode(publicKeyContent));
          RSAPublicKey pubKey = (RSAPublicKey) kf.generatePublic(keySpecX509);
          final Cipher cipher = Cipher.getInstance("RSA/ECB/OAEPWithSHA-1AndMGF1Padding");
          cipher.init(Cipher.ENCRYPT_MODE, pubKey);
          encrytedSignature = Base64.getEncoder().encodeToString(cipher.doFinal(clientIdWithEpochTimestamp.getBytes()));
          System.out.println(encrytedSignature);
      } catch (Exception e) {
          e.printStackTrace();
      }
      return encrytedSignature;
  }
  ```

  ```python Python theme={"dark"}
  from cashfree_sdk.payouts import Payouts
  // Initialise the SDK, pass public key for dynamic IP
  Payouts.init("<client_id>", "<client_secret>", "PROD", public_key= b'public key')
  ```

  ```javascript Node theme={"dark"}
  //require CashfreeSDK
  const cfSdk = require("cashfree-sdk");

  //access the PayoutsSdk from CashfreeSDK
  const { Payouts } = cfSdk;

  // Instantiate Cashfree Payouts
  const payoutsInstance = new Payouts({
  	env: "TEST",
  	clientId: "<CLIENT_ID>",
  	clientSecret: "<CLIENT_SECRET>",
  	pathToPublicKey: "/path/to/your/public/key/file.pem",
  	//"publicKey": "ALTERNATIVE TO SPECIFYING PATH (DIRECTLY PASTE PublicKey)"
  });
  ```
</CodeGroup>

<Note>
  **Getting the “IP not whitelisted” error on the Postman web app?**\
  If you're using the Postman web app, API requests may fail because Postman uses dynamic cloud IPs, which can't be whitelisted.

  **How to fix it**: Use the Postman desktop app. It sends requests from your local IP address, which can be whitelisted.

  Signature verification works correctly with both web and desktop apps. Only **IP-based whitelisting** is affected.
</Note>

## Any queries: Contact support

For API or integration issues, fill the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) or email Cashfree Support with the details below.

To identify, diagnose, and resolve problems related to API requests, ensure the following information is communicated when contacting support:

* Share the API request and response details along with only **x-client-ID**.
* Mention the registered email ID and environment in the email.
* Use your registered email address (with Cashfree) to send the email or mention the registered email address.
* Include your account manager in the CC of the email request.

<Note>
  For dashboard queries, share the screenshot and .har file of the screen.
</Note>


# Overview
Source: https://www.cashfree.com/docs/api-reference/payouts/overview

Explore the Cashfree Payouts APIs that disburse funds to bank accounts, UPI IDs, and cards with sandbox endpoints, authentication, and webhooks.

The **Payouts APIs** by Cashfree provide secure, scalable RESTful endpoints for instant fund transfers. These APIs enable businesses to disburse payments directly to **bank accounts**, **UPI IDs**, or **cards** without manual intervention. With high success rates, consistent authentication, and robust error handling, Payouts ensure reliable and real-time disbursal operations across a range of business use cases.

The Payouts APIs are available for both **sandbox testing** and **production** environments, supporting webhook notifications, reconciliation capabilities, and multiple payout modes.

## Key features

The key features offered by Cashfree’s **Payouts APIs** are:

* **Instant fund transfers**: Process payouts to bank accounts, UPI, and cards 24×7.
* **Multi-mode disbursals**: Choose from IMPS, NEFT, RTGS, UPI, and card-based transfers.
* **Bulk payouts**: Automate thousands of payments in a single API call.
* **Dynamic beneficiary management**: Add, verify, and manage beneficiaries securely.
* **Advanced reconciliation**: Track transaction statuses with webhooks and detailed reporting.
* **Enhanced security and compliance**: PCI DSS-certified infrastructure with real-time fraud prevention through Payout Protect.

<Tabs>
  <Tab title="Core APIs">
    <div>
      <div>
        <h4>Fund transfer operations</h4>

        <a href="/docs/api-reference/payouts/v2/transfers-v2/standard-transfer-v2">Standard Transfer V2</a>
        <p>Initiate single fund transfers to bank accounts, UPI, or cards with instant status updates.</p>

        <a href="/docs/api-reference/payouts/v2/transfers-v2/batch-transfer-v2">Batch Transfer V2</a>
        <p>Automate large-scale disbursals using a single API request for multiple beneficiaries.</p>

        <a href="/docs/api-reference/payouts/v2/transfers-v2/get-transfer-status-v2">Get Transfer Status V2</a>
        <p>Track and retrieve detailed status, failure reasons, and reconciliation data for transfers.</p>

        <a href="/docs/api-reference/payouts/v2/validate-payout-v2">Validate Payout V2</a>
        <p>Validate a UPI VPA or phone number and obtain a single-use transfer token for Verify and Pay.</p>

        <a href="/docs/api-reference/payouts/v2/verify-and-pay-transfers-v2">Process Validated Payout V2</a>
        <p>Initiate a UPI payout using the transfer token from Validate Payout V2.</p>
      </div>

      <div>
        <h4>Beneficiary management</h4>

        <a href="/docs/api-reference/payouts/v2/beneficiary-v2/create-beneficiary-v2">Create Beneficiary V2</a>
        <p>Add and verify new beneficiaries securely before you initiate payouts.</p>

        <a href="/docs/api-reference/payouts/v2/beneficiary-v2/get-beneficiary-v2">Get Beneficiary V2</a>
        <p>Retrieve beneficiary details and transaction history for reconciliation.</p>

        <a href="/docs/api-reference/payouts/v2/beneficiary-v2/remove-beneficiary-v2">Remove Beneficiary V2</a>
        <p>Securely delete beneficiary records when they are no longer needed.</p>
      </div>
    </div>
  </Tab>

  <Tab title="Extended modules">
    <div>
      <div>
        <h4>Alternative payout methods</h4>

        <a href="/docs/api-reference/payouts/v2/create-cashgram">Cashgram</a>
        <p>Generate one-time payout links to allow users to claim funds through their preferred mode such as UPI or bank transfer.</p>

        <a href="/docs/api-reference/payouts/v2/cardpay">Card Payouts</a>
        <p>Send money directly to debit and credit cards for instant fund access.</p>

        <h4>Verify and pay (legacy V1)</h4>

        <p>Version 1: <a href="/docs/api-reference/payouts/v1/validate-payout-v1">Validate Payout V1</a> and <a href="/docs/api-reference/payouts/v1/verify-and-pay-direct-transfer-v1">Process Validated Payout V1</a>.</p>

        <p>Version 1.2: <a href="/docs/api-reference/payouts/v1/validate-payout-v1-2">Validate Payout V1.2</a> and <a href="/docs/api-reference/payouts/v1/verify-and-pay-direct-transfer-v1-2">Process Validated Payout V1.2</a>.</p>
      </div>

      <div>
        <h4>Business solutions</h4>

        <a href="/docs/api-reference/payouts/v1/oneescrow/create-virtual-account">One Escrow</a>
        <p>Manage escrow accounts and automate settlements across buyers, sellers, and partners.</p>

        <h4>Real-time updates</h4>

        <a href="/docs/api-reference/payouts/v2/webhooks/webhooks-v2">Webhooks V2</a>
        <p>Receive real-time notifications on payout success, failure, or reversal events.</p>
      </div>
    </div>
  </Tab>
</Tabs>

## Get started

Use the following resources to begin implementing Cashfree Payouts:

<CardGroup>
  <Card title="Product Documentation" href="/docs/payouts/payouts/introduction" icon="book-open">
    Learn about Payouts features, sub-products, and setup process.
  </Card>

  <Card title="API Setup and Authentication" href="/docs/api-reference/payouts/getting-started-with-payouts-apis" icon="code">
    Configure API keys, Postman collection, and security requirements.
  </Card>
</CardGroup>


# Add Beneficiary
Source: https://www.cashfree.com/docs/api-reference/payouts/v1/add-beneficiary

post /payout/v1/addBeneficiary
Use this API to add a beneficiary to your Cashfree account by providing the bank account number, IFSC, and other required details. Before you request a transfer, ensure the account has been successfully added as a beneficiary.

<Warning> This API will be retired soon. Please plan to migrate to the latest version, [Beneficiary V2](/docs/api-reference/payouts/v2/beneficiary-v2/get-beneficiary-v2). </Warning>

Please use this Authorization token in headers to call any payout API (Refresh this page if the token is expired)

<iframe />

<Accordion title="Click to view the response codes.">
  | Sub code | Status | Message | Next action |
  | :- | :- | :- | :- |
  | 200 | SUCCESS | Beneficiary added successfully | - |
  | 400 | ERROR | Please provide a valid VPA | Enter a valid VPA in the API request. |
  | 403 | ERROR | Token is not valid | Enter a valid token in the request. |
  | 403 | ERROR | IP not whitelisted | Whitelist the API. |
  | 403 | ERROR | APIs not enabled. Fill out the details in the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) | [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) |
  | 409 | ERROR | Beneficiary Id already exists | Enter a unique ID for the beneficiary. |
  | 409 | ERROR | Entered bank Account is already registered | Enter different bank account information. |
  | 412 | ERROR | Token missing in the request | Enter a valid token in the request. |
  | 412 | ERROR | Beneficiary group is not an active group | |
  | 412 | ERROR | Bank account and VPA are both provided in the request. Please add either of them to add the beneficiary. | Enter any of the information in the request. |
  | 412 | ERROR | Cannot add yourself as a beneficiary | Enter an individual's information apart from yours to add a beneficiary. |
  | 422 | ERROR | Please provide a valid Beneficiary Id | Enter a valid beneficiary ID. |
  | 422 | ERROR | Please provide a valid email | Enter a valid email address. |
  | 422 | ERROR | Please provide a valid name | Enter a valid name. |
  | 422 | ERROR | Please provide a valid Phone Number | Enter a valid phone number. |
  | 422 | ERROR | Please provide a valid Bank Account | Enter valid bank account information. |
  | 422 | ERROR | Please provide a valid Bank IFSC code | Enter a valid IFSC. |
  | 422 | ERROR | Please provide a valid Virtual Payee Address | Enter a valid VPA. |
  | 422 | ERROR | Please provide a valid Address | Enter a valid address. |
  | 422 | ERROR | Please provide a valid City Name | Enter a valid city name. |
  | 422 | ERROR | Please provide a valid State Name | Enter a valid state name. |
  | 422 | ERROR | Please provide a valid Pin code | Enter a valid PIN code. |
  | 422 | ERROR | Cashfree VBA/VPA cannot be added as a beneficiary | Enter a different VBA/VPA to add the beneficiary. |
  | 422 | ERROR | Please provide a valid MasterCard or Visa card number | Enter a valid MasterCard or Visa card number. |
  | 422 | ERROR | Please provide a masked card number of a valid MasterCard or Visa card | Enter a masked card number of a valid MasterCard or Visa card. |
  | 422 | ERROR | Invalid details provided | Enter valid details of the beneficiary to add the beneficiary in the system. |
  | 520 | ERROR | Adding beneficiary Failed | Re-enter the details or try again after some time. |

  **Note**: If you are attempting to create a transfer in the Sandbox environment, you can obtain the test data details from the [test data page](/docs/payouts/payouts/integrations/data-to-test).
</Accordion>


# Authorize
Source: https://www.cashfree.com/docs/api-reference/payouts/v1/authorize

post /payout/v1/authorize
Use this API to authenticate with the Cashfree system and obtain the authorization bearer token. All other API calls must have this token as Authorization header in the format 'Bearer <token>' (without quotes) for them to get processed.

<Note>
  **URLs** <br />

  * Production/Live: [https://payout-api.cashfree.com/payout/v1/authorize](https://payout-api.cashfree.com/payout/v1/authorize)
  * Sandbox/Test: [https://payout-gamma.cashfree.com/payout/v1/authorize](https://payout-gamma.cashfree.com/payout/v1/authorize)
</Note>

<Accordion title="Click to view the steps to generate a public key and the signature.">
  If you do not have a static IP, you can generate a public key and pass it with the API request.
  To generate a public key,

  1. Go Payouts Dashboard > **Developers** section on the left-side navigation > **Payouts** > **Two-Factor Authentication** > **Public Key**.
  2. Click **Generate Public Key**. The public key will be downloaded to your computer and the password to access it will be your email ID registered with Cashfree. Only one Public Key can be generated at a time.

  <img />

  Below are the steps to generate your signature:

  1. Retrieve your clientId (one which you are passing through the header X-Client-Id )
  2. Append this with CURRENT UNIX timestamp separated by a period (.)
  3. Encrypt this data using RSA encrypt with Public key you received - this is the signature.
  4. Pass this signature through the header X-Cf-Signature.
     In the case of using our library, go through the libraries section. During the initialization process, you need to pass the key as a parameter.

  <CodeGroup>
    ```php PHP theme={"dark"}
    <?php
    public static function getSignature() {
        $clientId = "<your clientId here>";
        $publicKey =
    openssl_pkey_get_public(file_get_contents("/path/to/certificate/public
    _key.pem"));
        $encodedData = $clientId.".".strtotime("now");
        return static::encrypt_RSA($encodedData, $publicKey);
    }
    private static function encrypt_RSA($plainData, $publicKey) { if (openssl_public_encrypt($plainData, $encrypted, $publicKey,
    OPENSSL_PKCS1_OAEP_PADDING))
        $encryptedData = base64_encode($encrypted);
        else return NULL;
        return $encryptedData;
    }
    ?>
    ```

    ```java Java theme={"dark"}
    private static String generateEncryptedSignature(String clientIdWithEpochTimestamp) {
        // String clientIdWithEpochTimeStamp = clientId+"."+Instant.now().getEpochSecond();
        String encrytedSignature = "";
        try {
            byte[] keyBytes = Files
                .readAllBytes(new File("/Users/sameera/Downloads/payout_test_public_key.pem").toPath()); // Absolute Path to be replaced
            String publicKeyContent = new String(keyBytes);
            System.out.println(publicKeyContent);
            publicKeyContent = publicKeyContent.replaceAll("[\\t\\n\\r]", "")
                .replace("-----BEGIN PUBLIC KEY-----", "").replace("-----END PUBLIC KEY-----", "");
            KeyFactory kf = KeyFactory.getInstance("RSA");
            System.out.println(publicKeyContent);
            X509EncodedKeySpec keySpecX509 = new X509EncodedKeySpec(
                Base64.getDecoder().decode(publicKeyContent));
            RSAPublicKey pubKey = (RSAPublicKey) kf.generatePublic(keySpecX509);
            final Cipher cipher = Cipher.getInstance("RSA/ECB/OAEPWithSHA-1AndMGF1Padding");
            cipher.init(Cipher.ENCRYPT_MODE, pubKey);
            encrytedSignature = Base64.getEncoder().encodeToString(cipher.doFinal(clientIdWithEpochTimestamp.getBytes()));
            System.out.println(encrytedSignature);
        } catch (Exception e) {
            e.printStackTrace();
        }
        return encrytedSignature;
    }
    ```

    ```python Python theme={"dark"}
    from cashfree_sdk.payouts import Payouts
    // Initialise the SDK, pass public key for dynamic IP
    Payouts.init("<client_id>", "<client_secret>", "PROD", public_key= b'public key')
    ```

    ```javascript Node theme={"dark"}
    //require CashfreeSDK
    const cfSdk = require('cashfree-sdk');
    //access the PayoutsSdk from CashfreeSDK
    const {Payouts} = cfSdk;
    // Instantiate Cashfree Payouts
    const payoutsInstance = new Payouts({
    env: 'TEST',
    clientId: '<CLIENT_ID>',
    clientSecret: '<CLIENT_SECRET>',
    pathToPublicKey: '/path/to/your/public/key/file.pem',
    //"publicKey": "ALTERNATIVE TO SPECIFYING PATH (DIRECTLY PASTE PublicKey)"
    });
    ```
  </CodeGroup>
</Accordion>


# Batch Transfer
Source: https://www.cashfree.com/docs/api-reference/payouts/v1/batch-transfer

post /payout/v1/requestBatchTransfer
Use this API to create multiple transfers to multiple beneficiaries. This API accepts an array of transfer objects under the batch field.

<Warning> This API will be retired soon. Please plan to migrate to the latest version, [Transfers V2](/docs/api-reference/payouts/v2/transfers-v2/get-transfer-status-v2). </Warning>

Please use this Authorization token in headers to call any payout API (Refresh this page if the token is expired)

<iframe />

<Note>
  Get Batch Transfer Status
  Use the [Get Batch Transfer Status](https://docs.cashfree.com/reference/get-batch-transfer-status) API to get the status of the batch transfer request. The Get Transfer Status API does not give you the status of the batch transfer requests. Read the [batch transfer document](https://docs.cashfree.com/docs/batch-transfer-1) to understand the flow of the API.
</Note>

<Accordion title="Click to view the batch format.">
  | Value | Description |
  | :- | :- |
  | BENEFICIARY\_ID | With this value, beneId and transferMode must be passed in the transfer object within the batch array alphanumeric and underscore allowed (60 character limit) If batchFormat is set to any of the below values, transfers will only be processed via specified mode. |
  | BANK\_ACCOUNT | With this value, Additional details such as bankAccount, ifsc, name, email, phone must be passed in the transfer object within the batch array |
  | UPI | With this value, Additional details such as vpa, name, email, phone must be passed in the transfer object within the batch array |
  | PAYTM | With this value, Additional details such as name, email, phone must be passed in the transfer object within the batch array |
  | AMAZONPAY | With this value, Additional details such as name, email, phone must be passed in the transfer object within the batch array |
</Accordion>

<Accordion title="Click to view the transfer objects and its description.">
  | **Field name** | **Description** |
  | - | - |
  | transferId | A unique transfer id. |
  | amount | Amount to be transferred. |
  | beneId | The ID of the beneficiary. This field must be passed if the batch format option is BENEFICIARY\_ID. |
  | transferMode | Required only when batchFormat is set to BENEFICIARY\_ID, mode of transfer for each transfer in batch needs to be set. Allowed values are: banktransfer, upi, paytm, and amazonpay |
  | bankAccount | Bank account number for payout. This field must be passed if the batch format option is BANK\_ACCOUNT. |
  | ifsc | IFSC of the corresponding bank account. This field must be passed if the batch format option is BANK\_ACCOUNT. |
  | vpa \[optional] | VPA of the corresponding user. This field must be passed if the batch format option is UPI. |
  | name | Name of the account holder. This field must be passed if the batch format option is BANK\_ACCOUNT. |
  | email \[optional] | Email of the beneficiary. This field must be passed if the batch format option is BANK\_ACCOUNT. |
  | phone | The phone of the beneficiary. This field must be passed if the batch format option is BANK\_ACCOUNT/PAYTM/AMAZONPAY. |
  | remarks \[optional] | Remarks, if any. |

  Currently, batch transfer supports transfers to bank accounts, UPI, Paytm, and Amazon Pay. If the beneficiary object does not have valid details attached to it, the transfer fails.
</Accordion>

<Accordion title="Click to view the response codes.">
  | Sub code | Status | Message | Solution |
  | :- | :- | :- | :- |
  | 200 | SUCCESS | Batch Transfer requested successfully. Please check later for processing status. | |
  | 202 | PENDING | Request received. Please check status after some time. | |
  | 403 | ERROR | Token is not valid | Verify the generated token. |
  | 403 | ERROR | Permission Denied | |
  | 409 | ERROR | Invalid Batch Format | Enter a valid batch transfer ID. |
  | 409 | ERROR | Batch TransferId already exists | Enter a different batch transfer ID. |
  | 412 | ERROR | Token missing in the request | Enter a valid token in the request. |
  | 422 | ERROR | Batch transfer id is missing | Enter a valid batch transfer ID. |
  | 422 | ERROR | Invalid Batch Transfer Id provided | Enter a valid batch transfer ID. |
  | 422 | ERROR | The maximum number of entries allowed per file is 500, please try again. | Enter only a maximum of 500 entries per file. |
  | 422 | ERROR | Batch format is missing | Enter valid batch format details. |
  | 422 | ERROR | Transfer Parameters  missing in the request | |
  | 422 | ERROR | Please provide at least one transfer entry | Enter at least one transfer entry. |
  | 520 | ERROR | Unknown error occurred at batchTransfer | |
  | 520 | ERROR | Batch Transfer request failed | |
  | 520 | ERROR | Error in batch transfer | |
  | 520 | ERROR | Unknown error occurred | |
</Accordion>


# Batch Transfer V1.2
Source: https://www.cashfree.com/docs/api-reference/payouts/v1/batch-transfer-v12

post /payout/v1.2/requestBatchTransfer
Use this API to create transfers to multiple beneficiaries. This API accepts an array of transfer objects under the batch field.

<Warning> This API will be retired soon. Please plan to migrate to the latest version, [Transfers V2](/docs/api-reference/payouts/v2/transfers-v2/get-transfer-status-v2). </Warning>

Please use this Authorization token in headers to call any payout API (Refresh this page if the token is expired)

<iframe />

<Note>
  **Get Batch Transfer Status**
  Use the [Get Batch Transfer Status V1.2](https://docs.cashfree.com/reference/get-batch-transfer-status-v1-2) API to get the status of the batch transfer request. The Get Transfer Status V1.2 API does not give you the status of the batch transfer requests. Read the [batch transfer document](https://docs.cashfree.com/docs/batch-transfer-1) to understand the flow of the API.
</Note>

<Accordion title="Click to view details about batch format.">
  | Value | Description |
  | :- | :- |
  | BENEFICIARY\_ID | With this value, beneId and transferMode must be passed in the transfer object within the batch array alphanumeric and underscore allowed (60 character limit) If batchFormat is set to any of the below values, transfers will only be processed via specified mode. |
  | BANK\_ACCOUNT | With this value, Additional details such as bankAccount, ifsc, name, email, phone must be passed in the transfer object within the batch array |
  | UPI | With this value, Additional details such as vpa, name, email, phone must be passed in the transfer object within the batch array |
  | PAYTM | With this value, Additional details such as name, email, phone must be passed in the transfer object within the batch array |
  | AMAZONPAY | With this value, Additional details such as name, email, phone must be passed in the transfer object within the batch array |
</Accordion>

<Accordion title="Click to view the details of transfer objects.">
  | Field name | Description |
  | - | - |
  | transferId | A unique transfer id. |
  | amount | Amount to be transferred. |
  | beneId | The ID of the beneficiary. This field must be passed if the batch format option is BENEFICIARY\_ID. |
  | transferMode | Required only when batchFormat is set to BENEFICIARY\_ID, mode of transfer for each transfer in batch needs to be set. |
  | | Allowed values are: banktransfer, upi, paytm, and amazonpay. |
  | bankAccount | Bank account number for payout. This field must be passed if the batch format option is BANK\_ACCOUNT. |
  | ifsc | IFSC of the corresponding bank account. This field must be passed if the batch format option is BANK\_ACCOUNT. |
  | vpa \[optional] | VPA of the corresponding user. This field must be passed if the batch format option is UPI. |
  | name | Name of the account holder. This field must be passed if the batch format option is BANK\_ACCOUNT. |
  | email \[optional] | Email of the beneficiary. This field must be passed if the batch format option is BANK\_ACCOUNT. |
  | phone | The phone of the beneficiary. This field must be passed if the batch format option is BANK\_ACCOUNT/PAYTM/AMAZONPAY. |
  | remarks \[optional] | Remarks, if any. |

  Currently, batch transfer supports transfers to bank accounts, UPI, Paytm, and Amazon Pay. If the beneficiary object does not have valid details attached to it, the transfer fails.
</Accordion>

<Accordion title="Click to view the response codes.">
  | Sub code | Status | Message | Next action |
  | :- | :- | :- | :- |
  | 200 | SUCCESS | Batch Transfer requested successfully. Please check later for processing status. | - |
  | 200 | SUCCESS | beneficiary already exists with a different name. Please delete | |
  | 202 | PENDING | Request received. Please check status after some time. | - |
  | 403 | ERROR | Token is not valid | Verify the generated token. |
  | 403 | ERROR | Permission Denied | |
  | 409 | ERROR | Invalid Batch Format | Enter valid batch format details. |
  | 409 | ERROR | Batch TransferId already exists | Enter a valid batch transfer ID. |
  | 412 | ERROR | Token missing in the request | Enter a valid token in the request. |
  | 422 | ERROR | Batch transfer id is missing | Enter a valid batch transfer ID. |
  | 422 | ERROR | Batch format is missing | Enter valid batch format details. |
  | 422 | ERROR | Invalid Batch Transfer Id provided | Enter a valid batch transfer ID. |
  | 422 | ERROR | Please provide at least one transfer entry | Enter at least one transfer entry. |
  | 422 | ERROR | The maximum number of entries allowed per file is 500, please try again. | Enter only a maximum of 500 entries per file. |
  | 422 | ERROR | Transfer Parameters  missing in the request | Enter all the required transfer parameters in the request. |
  | 520 | ERROR | Unknown error occurred at batchTransfer | |
  | 520 | ERROR | Batch Transfer request failed | |
  | 520 | ERROR | Error in batch transfer | |
  | 520 | ERROR | Unknown error occurred | |
</Accordion>


# CardPay
Source: https://www.cashfree.com/docs/api-reference/payouts/v1/cardpay

post /payout/v1/cardpay
Use this API to transfer money to beneficiary cards. Provide details such as beneficiary name, card type, network type, and transfer ID.

You need to pass the tokenised card number or card token for this transfer.

Please use this Authorization token in headers to call any payout API (Refresh this page if the token is expired)

<iframe />

<Accordion title="Click to view the tokens to test CardPay integration.">
  | Test token | Response in UAT |
  | :- | :- |
  | 4895379990484220 | SUCCESS |
  | 5480981500100002 | SUCCESS |
  | 5480981500100003 | FAILURE |
  | 4895379990484221 | FAILURE |
</Accordion>

<Accordion title="Click to view the response codes.">
  | Sub code | Status | Message | Next action |
  | :- | :- | :- | :- |
  | 200 | SUCCESS | Transfer completed successfully | None |
  | 201 | PENDING | Transfer request pending at the bank | None |
  | 400 | ERROR | Transfer Id already exists | Provide a different transfer ID |
  | 403 | ERROR | Token is not valid | Validate the token |
  | 403 | ERROR | APIs not enabled. Please fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) | Please fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) |
  | 412 | ERROR | Not enough available balance in the account | Try again with sufficient account balance |
  | 422 | ERROR | Please provide valid token details | Provide a valid token |
  | 422 | ERROR | amount should be at least 1.0 | Enter a transfer amount that is equal to or more than Rs. 1. |
  | 422 | ERROR | Invalid bank account number or ifsc provided | Provide valid bank account details |
  | 422 | ERROR | Please provide a valid Name | Provide a valid name |
  | 422 | ERROR | Please provide a valid networkType | Provide a valid network type |
  | 422 | ERROR | cardType is invalid | Provide a valid card type |
  | 422 | ERROR | transferId can contain only alphabets, numbers, hyphen and underscore | Provide a valid transfer ID |
</Accordion>


# Postman Collection
Source: https://www.cashfree.com/docs/api-reference/payouts/v1/cashgram-postman-collection

Download the Cashfree Cashgram Postman collection, import it into Postman, and start trying Cashgram API requests against sandbox without writing code.

Get started quickly with Cashfree's Cashgram APIs by downloading the collection and importing it in Postman.

[Download Cashfree Cashgram Postman Collection](https://gocashassets.s3.ap-south-1.amazonaws.com/repostmancollection/Cashfree_Cashgram_Collection.json.zip)


# Create Cashgram
Source: https://www.cashfree.com/docs/api-reference/payouts/v1/create-cashgram

post /payout/v1/createCashgram
Use this API to create a Cashgram.



# Deactivate Cashgram
Source: https://www.cashfree.com/docs/api-reference/payouts/v1/deactivate-cashgram

post /payout/v1/deactivateCashgram



# Direct Transfer
Source: https://www.cashfree.com/docs/api-reference/payouts/v1/direct-transfer

post /payout/v1/directTransfer
Use this API to initiate amount transfers directly to the beneficiary account via a bank transfer or UPI. You can add the beneficiary details in the same API request.

<Warning> This API will be retired soon. Please plan to migrate to the latest version, [Transfers V2](/docs/api-reference/payouts/v2/transfers-v2/get-transfer-status-v2). </Warning>

Please use this Authorization token in headers to call any payout API (Refresh this page if the token is expired)

<iframe />

<Accordion title="Click to view the response codes.">
  | Sub code | Status | Message | Next action |
  | :- | :- | :- | :- |
  | 200 | SUCCESS | Transfer completed successfully. | - |
  | 201 | SUCCESS | Transfer Scheduled for next working day. | - |
  | 201 | PENDING | Awaiting confirmation from beneficiary bank. | - |
  | 201 | PENDING | Transfer request pending at the bank. | - |
  | 202 | PENDING | Request received. Please check status after some time. | - |
  | 400/520 | ERROR | Transfer attempt failed at the bank. | - |
  | 403 | ERROR | Token is not valid | Verify the generated token. |
  | 403 | ERROR | IP not whitelisted | Whitelist the IP address. |
  | 403 | ERROR | This feature is not available for your account. | - |
  | 403 | ERROR | Transfer mode is not available for your account. | Enter a different transfer mode. |
  | 403 | ERROR | Transfer to this beneficiary not allowed. | Enter different beneficiary details. |
  | 404 | ERROR | Beneficiary does not exist. | Enter a valid beneficiary ID. |
  | 409 | ERROR | Transfer Id already exists. | Enter a different transfer ID. |
  | 412 | ERROR | Token missing in the request. | Enter a valid token in the API request. |
  | 412 | ERROR | BeneId missing in the request. | Enter a valid beneficiary ID. |
  | 412 | ERROR | Amount missing in the request. | Enter a valid transfer amount. |
  | 412 | ERROR | TransferId missing in the request. | Enter a valid transfer ID. |
  | 412 | ERROR | Invalid Tag passed in the request. | |
  | 412 | ERROR | Invalid transfer mode passed in the request. | |
  | 412 | ERROR | Transfer mode not enabled for the account. | |
  | 412 | ERROR | Transfer limit for your account exceeded. | |
  | 412 | ERROR | Transfer limit for beneficiary exceeded. | |
  | 412 | ERROR | Not enough available balance in the account. | Retry with sufficient balance in your account. |
  | 412 | ERROR | Please wait 30 minutes after adding the beneficiary. | - |
  | 412 | ERROR | Transfer amount is less than minimum amount of Rs. 100. | Enter a transfer amount that is equal to or more than Rs. 100. |
  | 412 | ERROR | Transfer amount is greater than the maximum amount of Rs.100000. | Enter a transfer amount that is equal to or less than Rs. 100000. |
  | 422 | ERROR | Invalid IFSC code provided for bank account. | Enter a valid IFSC for the provided bank account details. |
  | 422 | ERROR | Invalid bank account number or IFSC provided. | Enter valid bank account details. |
  | 422 | ERROR | Transfer request to paytm wallet failed. | |
  | 422 | ERROR | No Bank account or IFSC associated with the beneficiary. | Enter valid bank account details of the beneficiary. |
  | 422 | ERROR | Invalid transferId passed. | Enter a valid transferId. |
  | 422 | ERROR | Beneficiary details not valid. | Enter valid beneficiary details. |
  | 422 | ERROR | Remarks can have only numbers, alphabets and whitespaces. | - |
  | 422 | ERROR | Invalid amount passed. | Enter a valid transfer amount. |
  | 422 | ERROR | No Payee Virtual Address associated with the beneficiary. | |
  | 520 | ERROR | Transfer request triggered. No response from bank. | |
</Accordion>


# Direct Transfer V1.2
Source: https://www.cashfree.com/docs/api-reference/payouts/v1/direct-transfer-v12

post /payout/v1.2/directTransfer
Use this API to initiate amount transfers directly to the beneficiary account via a bank transfer or UPI. You can add the beneficiary details in the same API request.

<Warning> This API will be retired soon. Please plan to migrate to the latest version, [Transfers V2](/docs/api-reference/payouts/v2/transfers-v2/get-transfer-status-v2). </Warning>

Please use this Authorization token in headers to call any payout API (Refresh this page if the token is expired)

<iframe />

<Accordion title="Click to view the response codes.">
  | Sub code | Status | Message | Next action |
  | :- | :- | :- | :- |
  | 200 | SUCCESS | Transfer completed successfully. | - |
  | 201 | SUCCESS | Transfer Scheduled for next working day. | - |
  | 201 | PENDING | Awaiting confirmation from beneficiary bank. | - |
  | 201 | PENDING | Transfer request pending at the bank. | - |
  | 202 | PENDING | Request received. Please check status after some time. | - |
  | 400 | ERROR | Multiple PaymentInstruments available for this payment mode. | - |
  | 400 | ERROR | Specified paymentInstrumentId not valid for this payment mode. | - |
  | 400 | ERROR | Specified paymentInstrumentId not available. | Enter a different paymentInstrumentId. |
  | 400 | ERROR | Transfer attempt failed at the bank. | - |
  | 403 | ERROR | Token is not valid | Verify the generated token |
  | 403 | ERROR | IP not whitelisted | Whitelist the IP address |
  | 403 | ERROR | Transfer to this beneficiary not allowed. | Enter different beneficiary details |
  | 403 | ERROR | This feature is not available for your account. | |
  | 403 | ERROR | Transfer mode is not available for your account. | Enter a different transfer mode. |
  | 404 | ERROR | Beneficiary does not exist. | Enter a valid beneficiary ID. |
  | 409 | ERROR | Transfer Id already exists. | Enter a different transfer ID. |
  | 412 | ERROR | Token missing in the request. | Enter a valid token in the API request. |
  | 412 | ERROR | BeneId missing in the request. | Enter a valid beneficiary ID. |
  | 412 | ERROR | Amount missing in the request. | Enter a valid transfer amount. |
  | 412 | ERROR | TransferId missing in the request. | Enter a valid transfer ID. |
  | 412 | ERROR | Please wait 30 minutes after adding the beneficiary. | - |
  | 412 | ERROR | Transfer amount is less than minimum amount of Rs. 100. | Enter a transfer amount that is equal to or more than Rs. 100. |
  | 412 | ERROR | Transfer amount is greater than the maximum amount of Rs.100000. | Enter a transfer amount that is equal to or less than Rs. 100000. |
  | 412 | ERROR | Transfer limit for beneficiary exceeded. | |
  | 412 | ERROR | Transfer limit for your account exceeded. | |
  | 412 | ERROR | Not enough available balance in the account. | Retry with sufficient balance in your account. |
  | 412 | ERROR | Invalid Tag passed in the request. | |
  | 412 | ERROR | Transfer mode not enabled for the account. | |
  | 412 | ERROR | Invalid transfer mode passed in the request. | |
  | 422 | ERROR | Invalid amount passed. | Enter a valid transfer amount. |
  | 422 | ERROR | Invalid transferId passed. | Enter a valid transferId. |
  | 422 | ERROR | No Payee Virtual Address associated with the beneficiary. | |
  | 422 | ERROR | Remarks can have only numbers, alphabets and whitespaces. | |
  | 422 | ERROR | Beneficiary details not valid. | Enter valid beneficiary details. |
  | 422 | ERROR | No Bank account or IFSC associated with the beneficiary. | Enter valid bank account details of the beneficiary. |
  | 422 | ERROR | Transfer request to paytm wallet failed. | |
  | 422 | ERROR | Invalid IFSC code provided for bank account. | Enter a valid IFSC for the provided bank account details. |
  | 422 | ERROR | Invalid bank account number or IFSC provided. | Enter valid bank account details. |
  | 520 | ERROR | Transfer request triggered. No response from bank. | |
</Accordion>


# End Points
Source: https://www.cashfree.com/docs/api-reference/payouts/v1/end-points

Find the production and sandbox base URLs for Cashfree Payouts v1 APIs, plus the credentials verification endpoint you use to validate your AppId and SecretKey.

Cashfree uses API keys to allow access to the API. Once you have signed up at our merchant site, you will be able to see your AppId and SecretKey.

Cashfree expects API key to be included in all API requests to the server. Use the endpoint **/api/v1/credentials/verify** to verify your credentials.

| Environment | Base URL |
| :- | :- |
| Production | [https://payout-api.cashfree.com](https://payout-api.cashfree.com) |
| Test | [https://payout-gamma.cashfree.com](https://payout-gamma.cashfree.com) |


# Get Balance
Source: https://www.cashfree.com/docs/api-reference/payouts/v1/get-balance

get /payout/v1/getBalance
Use this API to get the ledger balance and available balance of your account. Available balance is ledger balance minus the sum of all pending transfers (transfers triggered and processing or pending now).

Please use this Authorization token in headers to call any payout API (Refresh this page if the token is expired)

<iframe />

<Accordion title="Click to view the response codes.">
  | Sub code | Status | Message | Solution |
  | :- | :- | :- | :- |
  | 200 | SUCCESS | Ledger balance for the account | |
  | 403 | ERROR | Token is not valid | Verify the generated token. |
  | 412 | ERROR | Token missing in the request | Enter the generated token as the value for Authorization under Headers in this format: Bearer \<token>. |
</Accordion>


# Get Balance V1.2
Source: https://www.cashfree.com/docs/api-reference/payouts/v1/get-balance-v12

get /payout/v1.2/getBalance
Use this API to get the ledger balance and available balance of your account. Available balance is ledger balance minus the sum of all pending transfers (transfers triggered and processing or pending now).

Please use this Authorization token in headers to call any payout API (Refresh this page if the token is expired)

<iframe />


# Get Batch Transfer Status
Source: https://www.cashfree.com/docs/api-reference/payouts/v1/get-batch-transfer-status

get /payout/v1/getBatchTransferStatus
Use this API to get the status of the Batch Transfer.

<Warning> This API will be retired soon. Please plan to migrate to the latest version, [Transfers V2](/docs/api-reference/payouts/v2/transfers-v2/get-transfer-status-v2). </Warning>

Please use this Authorization token in headers to call any payout API (Refresh this page if the token is expired)

<iframe />

<Accordion title="Click to view the batch format.">
  | Sub code | Status | Message |
  | :- | :- | :- |
  | 200 | SUCCESS | Data retrieved successfully |
  | 201 | PENDING | Entries are not processed yet |
  | 403 | ERROR | Token is not valid |
  | 403 | ERROR | IP not whitelisted |
  | 404 | ERROR | Bulk Transfer Id does not exist |
  | 412 | ERROR | Token missing in the request |
  | 520 | ERROR | Error while fetching data |
  | 520 | ERROR | Unknown error occurred at batchTransfer |
</Accordion>


# Get Batch Transfer Status
Source: https://www.cashfree.com/docs/api-reference/payouts/v1/get-batch-transfer-status-1

get /payout/v1.3/getBatchTransferStatus
Use this API to get the status of the Batch Transfer.

<Warning> This API will be retired soon. Please plan to migrate to the latest version, [Transfers V2](/docs/api-reference/payouts/v2/transfers-v2/get-transfer-status-v2). </Warning>


# Get Batch Transfer Status V1.2
Source: https://www.cashfree.com/docs/api-reference/payouts/v1/get-batch-transfer-status-v12

get /payout/v1.2/getBatchTransferStatus
Use this API to get the status of the Batch Transfer.

<Warning> This API will be retired soon. Please plan to migrate to the latest version, [Transfers V2](/docs/api-reference/payouts/v2/transfers-v2/get-transfer-status-v2). </Warning>

Please use this Authorization token in headers to call any payout API (Refresh this page if the token is expired)

<iframe />

<Accordion title="Click to view the response codes.">
  | Sub code | Status | Message | Next action |
  | :- | :- | :- | :- |
  | 200 | SUCCESS | Data retrieved successfully | - |
  | 201 | PENDING | Entries are not processed yet | - |
  | 403 | ERROR | Token is not valid | Verify the generated token. |
  | 403 | ERROR | IP not whitelisted | Whitelist the IP address. |
  | 404 | ERROR | Bulk Transfer Id does not exist | Enter a valid batch transfer ID. |
  | 412 | ERROR | Token missing in the request | Enter a valid token in the request. |
  | 520 | ERROR | Error while fetching data | |
  | 520 | ERROR | Unknown error occurred at batchTransfer | |
</Accordion>


# Get Beneficiary Details
Source: https://www.cashfree.com/docs/api-reference/payouts/v1/get-beneficiary-details

get /payout/v1/getBeneficiary/{beneId}
Use this API to get the details of a particular beneficiary in your account.

<Warning> This API will be retired soon. Please plan to migrate to the latest version, [Beneficiary V2](/docs/api-reference/payouts/v2/beneficiary-v2/get-beneficiary-v2). </Warning>

Please use this Authorization token in headers to call any payout API (Refresh this page if the token is expired)

<iframe />

<Accordion title="Click to view the response codes.">
  | Sub code | Status | Message | Next action |
  | :- | :- | :- | :- |
  | 200 | SUCCESS | Details of beneficiary | - |
  | 403 | ERROR | Token is not valid | Verify the generated token |
  | 404 | ERROR | Beneficiary does not exist | Provide a valid beneficiary ID |
  | 412 | ERROR | Token missing in the request | Enter the generated token as the value for Authorization under Headers in this format: `Bearer <token>`. |
</Accordion>


# Get Beneficiary History
Source: https://www.cashfree.com/docs/api-reference/payouts/v1/get-beneficiary-history

get /payout/v1/beneHistory
Use this API to fetch the transaction history for a particular beneficiary and for a desired period of time.

<Warning> This API will be retired soon. Please plan to migrate to the latest version, [Beneficiary V2](/docs/api-reference/payouts/v2/beneficiary-v2/get-beneficiary-v2). </Warning>

Please use this Authorization token in headers to call any payout API (Refresh this page if the token is expired)

<iframe />

<Accordion title="Click to view the response codes.">
  | Sub code | Status | Message | Solution |
  | :- | :- | :- | :- |
  | 200 | SUCCESS | Data retrieved successfully. | - |
  | 403 | ERROR | Token is invalid. | Validate the generated token. |
  | 405 | ERROR | Invalid request URL or HTTP method. | |
  | 422 | ERROR | Requested date range is invalid. | Enter a valid date rage. |
  | 422 | ERROR | Page value should be minimum 1. | Enter the page value as 1. |
  | 422 | ERROR | Please provide a valid Beneficiary Id. | Enter a valid beneficiary ID. |
  | 422 | ERROR | startDate should be of format yyyy-mm-dd | Enter the date range in the format: yyyy-mm-dd. |
  | 422 | ERROR | endDate should be of format yyyy-mm-dd | Enter the date range in the format: yyyy-mm-dd. |
  | 422 | ERROR | startDate should be less than or equal to EndDate | Enter a startDate value lesser than or equal to endDate. |
  | 422 | ERROR | perPage should be at max 25 | Enter the perPage value lesser than or equal to 25. |
  | 429 | ERROR | Too many requests. | |
  | 520 | ERROR | Unknown error occurred. | Try again after some time. |
</Accordion>


# Get Beneficiary ID
Source: https://www.cashfree.com/docs/api-reference/payouts/v1/get-beneficiary-id

get /payout/v1/getBeneId
Use this API to get the beneficiary ID by providing the bank account number and ifsc.

<Warning> This API will be retired soon. Please plan to migrate to the latest version, [Beneficiary V2](/docs/api-reference/payouts/v2/beneficiary-v2/get-beneficiary-v2). </Warning>

Please use this Authorization token in headers to call any payout API (Refresh this page if the token is expired)

<iframe />

<Accordion title="Click to view the response codes.">
  | Sub code | Status | Message | Next action |
  | :- | :- | :- | :- |
  | 200 | SUCCESS | BeneId retrieved successfully | - |
  | 52 | ERROR | Error while fetching beneId | Retry or try again after some time. |
  | 403 | ERROR | Token is not valid | Validate the generated token. |
  | 403 | ERROR | IP not whitelisted | Whitelist the IP address. |
  | 404 | ERROR | Beneficiary not found with given bank account details | Enter a valid bank account number and IFSC. |
  | 412 | ERROR | Token missing in the request | Enter the generated token as the value for Authorization under Headers in this format: `Bearer <token>`. |
  | 422 | ERROR | Please provide a valid bank account and ifsc | Enter a valid bank account number and IFSC. |
  | 422 | ERROR | Please provide both bank account and ifsc | Enter both the bank account number and IFSC. |
  | 422 | ERROR | Please provide a valid ifsc | Enter a valid IFSC. |
</Accordion>


# Get Cashgram Status
Source: https://www.cashfree.com/docs/api-reference/payouts/v1/get-cashgram-status

get /payout/v1/getCashgramStatus
Use this API to get the status of the Cashgram created.



# Get Incidents
Source: https://www.cashfree.com/docs/api-reference/payouts/v1/get-incidents

get /payout/v1/incidents
Use this API to get the list of incidents on banks(Resolved,Unresolved,All) for a given time range.

Please use this Authorization token in headers to call any payout API (Refresh this page if the token is expired)

<iframe />

<Accordion title="Click to view the response codes.">
  | Status | Sub code | Message | |
  | - | - | - | - |
  | SUCCESS | 200 | List of incidents retrieved | |
  | ERROR | 403 | Token is not valid | |
  | ERROR | 403 | IP Not Whitelisted | |
  | ERROR | 403 | APIs not enabled. Please fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) | |
  | ERROR | 412 | Token missing in the request | |
  | ERROR | 422 | Status is invalid | |
  | ERROR | 422 | startTime should be less than or equal to EndTime. | |
  | ERROR | 422 | Maximum time difference can be up to 7 days and startTime should be within 90 days from now. | |
  | ERROR | 422 | startTime should be of the format yyyy-mm-dd | |
  | hh:mm:ss | | | |
  | ERROR | 422 | endTime should be of the format yyyy-mm-dd | |
  | hh:mm:ss | | | |
  | ERROR | 520 | Unknown error occurred! | |
</Accordion>


# Get Transfer Status
Source: https://www.cashfree.com/docs/api-reference/payouts/v1/get-transfer-status

get /payout/v1.1/getTransferStatus
Use these details to get details of a particular transfer. You can pass referenceId or transferId to fetch the details.

<Warning> This API will be retired soon. Please plan to migrate to the latest version, [Transfers V2](/docs/api-reference/payouts/v2/transfers-v2/get-transfer-status-v2). </Warning>

Please use this Authorization token in headers to call any payout API (Refresh this page if the token is expired)

<iframe />

<Accordion title="Click to view the response codes.">
  | Sub code | Status | Message | Solution |
  | :- | :- | :- | :- |
  | 200 | SUCCESS | Details of transfer with referenceId (or transferId) XXXX | - |
  | 403 | ERROR | Token is not valid | Verify the generated token. |
  | 403 | ERROR | IP not whitelisted | Whitelist the IP address. |
  | 404 | ERROR | TransferId is invalid or does not exist | Enter a valid transfer ID. |
  | 404 | ERROR | ReferenceId is invalid or does not exist | Enter a valid reference ID. |
  | 412 | ERROR | Token missing in the request | Enter a valid token in the request. |
  | 422 | ERROR | Please provide referenceId or transferId to fetch details | Enter a valid reference or transferId. |
  | /520 | ERROR | Unknown error occurred | Try again after some time. |
</Accordion>

<Accordion title="Click to view failure reasons.">
  | Reason (in API response) | Category | Description | Solution |
  | :- | :- | :- | :- |
  | BANK\_GATEWAY\_ERROR | Bank | Technical error at the bank | |
  | SOURCE\_BANK\_DECLINED | Bank | TPS exceeded at the bank/NPCI | |
  | FAILED | Bank | No explicit failure reason from the bank | |
  | INVALID\_AMOUNT\_FAIL | Merchant | Amount is invalid for the given transfer mode | Enter a valid transfer amount. |
  | INVALID\_AMOUNT\_FAIL | Customer | Bank account is invalid | Enter valid bank account details. |
  | INVALID\_REQUEST | Merchant | Request is invalid | |
  | RETURNED\_FROM\_BENEFICIARY | Bank | Immediate reversal from the beneficiary bank | |
  | INSUFFICIENT\_BALANCE | Merchant | Balance is exhausted, need to add funds | |
  | IMPS\_MODE\_FAIL | Bank | IMPS mode not supported for the beneficiary | |
  | RTGS\_MODE\_FAIL | Bank | RTGS mode not supported (only for RTGS) | |
  | REINITIALIZE\_TRANSFER\_LATER | Bank | Technical error at the bank, retry later | |
  | NRE\_ACCOUNT\_FAIL | Customer | Customer bank account is an NRE account | |
  | ACCOUNT\_BLOCKED | Customer | Customer bank account is blocked | |
  | DEST\_LIMIT\_REACHED | Bank | Transfer limit to beneficiary exceeded | |
  | INVALID\_MODE\_FAIL | Bank | Transfer mode not valid for beneficiary | Enter a different transfer mode. |
  | NPCI\_UNAVAILABLE | Bank | NPCI in unavailable | |
  | BENEFICIARY\_BANK\_OFFLINE | Bank | Beneficiary bank is offline | |
</Accordion>

<Accordion title="Click to view the reversed reasons.">
  | Reason (in API response) | Category | Description | Solution |
  | :- | :- | :- | :- |
  | ACCOUNT\_FROZEN\_OR\_CLOSED | Customer | Account is closed or frozen | |
  | CREDIT\_LIMIT\_EXCEEDED | Customer | Transfer limit to beneficiary exceeded | |
  | ACCOUNT\_CLOSED\_OR\_FROZEN | Customer | Transfer limit to beneficiary exceeded | |
  | ACCOUNT\_ON\_HOLD | Customer | Account is temporarily on hold | |
  | ACCOUNT\_FROZEN | Customer | Account is frozen | |
  | IFSC\_DOES\_NOT\_MATCH | Customer | IFSC does not match | Enter a valid IFSC. |
  | FRAUD\_REVERSED | Customer | Suspect fraudulent transfer | |
  | ANY OTHER REASON | Bank | Reason not specified by bank | |
  | INVALID\_OR\_NO\_SUCH\_ACCOUNT\_TYPE | Customer | Invalid account | |
  | ACCOUNT\_CLOSED | Customer | Account is closed | |
  | ACCOUNT\_FROZEN\_OR\_BLOCKED | Customer | Account is frozen or blocked | |
  | BENEFICIARY\_NAME\_DIFFERS | Customer | Beneficiary name does not match (only for NEFT) | |
  | BENEFICIARY\_BANK\_NODE\_OFFLINE | Bank | Beneficiary bank offline | |
  | ACCOUNT\_DOES\_NOT\_EXIST | Customer | Account does not exist | Enter valid bank account details. |
</Accordion>


# Get Transfer Status V1.2
Source: https://www.cashfree.com/docs/api-reference/payouts/v1/get-transfer-status-v12

get /payout/v1.2/getTransferStatus
Use these details to get details of a particular transfer. You can pass referenceId or transferId to fetch the details.

<Warning> This API will be retired soon. Please plan to migrate to the latest version, [Transfers V2](/docs/api-reference/payouts/v2/transfers-v2/get-transfer-status-v2). </Warning>

Please use this Authorization token in headers to call any payout API (Refresh this page if the token is expired)

<iframe />

<Accordion title="Click to view the response codes.">
  | Sub code | Status | Message | Next action |
  | :- | :- | :- | :- |
  | 200 | SUCCESS | Details of transfer with referenceId (or transferId) XXXX | - |
  | 403 | ERROR | Token is not valid | Verify the generated token. |
  | 403 | ERROR | IP not whitelisted | Whitelist the IP address. |
  | 404 | ERROR | ReferenceId is invalid or does not exist | Enter a valid reference ID. |
  | 404 | ERROR | TransferId is invalid or does not exist | Enter a valid transfer ID. |
  | 412 | ERROR | Token missing in the request | Enter a valid token in the API request. |
  | 422 | ERROR | Please provide referenceId or transferId to fetch details | Enter a valid referenceId or transferId. |
  | 520 | ERROR | Unknown error occurred | Try again after some time. |
</Accordion>

<Accordion title="Click to view the failed reasons.">
  FAILED / REJECTED / REVERSED Reasons  (**reason** field will be available only for these 3 statuses)

  | Reason (in API response) | Category | Description | Next action |
  | :- | :- | :- | :- |
  | BANK\_GATEWAY\_ERROR | Bank | Technical error at the bank | |
  | BENE\_BANK\_DECLINED | Bank | Rejected by Beneficiary bank due to business reasons | |
  | FAILED | Bank | No explicit failure reason from the bank | |
  | INVALID\_IFSC\_FAIL | Customer | Invalid ifsc code provided for bank account | Enter a valid IFSC. |
  | INVALID\_ACCOUNT\_FAIL | Customer | Bank account is invalid | Enter valid bank account information. |
  | RETURNED\_FROM\_BENEFICIARY | Bank | Immediate reversal from the beneficiary bank | |
  | INSUFFICIENT\_BALANCE | Merchant | Merchant balance is exhausted, need to add funds | |
  | IMPS\_MODE\_FAIL | Bank | IMPS mode not supported for the beneficiary | |
  | RTGS\_MODE\_FAIL | Bank | RTGS mode not supported (only for RTGS) | |
  | REINITIALIZE\_TRANSFER\_LATER | Bank | Technical error at the bank, retry later | Retry after some time. |
  | NRE\_ACCOUNT\_FAIL | Customer | Customer bank account is an NRE account | |
  | ACCOUNT\_BLOCKED | Customer | Customer bank account is blocked | |
  | DEST\_LIMIT\_REACHED | Bank | Transfer limit to beneficiary exceeded | |
  | INVALID\_MODE\_FAIL | Bank | Transfer mode not valid for beneficiary | |
  | NPCI\_UNAVAILABLE | Bank | NPCI in unavailable | |
  | BENEFICIARY\_BANK\_OFFLINE | Bank | Beneficiary bank is offline | |
  | INVALID\_AMOUNT\_FAIL | Merchant | Amount is invalid for the given transfer mode | Enter a valid amount for the provided transfer mode. |
  | SUSPECTED\_TRANSFER | Customer | Suspicious transfer identified | |
  | BENE\_NAME\_DIFFERS | Customer | Beneficiary name not matching with bank records | Enter the beneficiary name as per bank records. |
  | DISABLED\_MODE | Merchant | Transfer mode not enabled for the account | Enter a different transfer mode for the account or enable the transfer mode before initiating the transfer request. |
  | AMAZON\_AMOUNT\_EXCEED | Merchant | Amount should be less than 10000 for Amazon Pay mode | Enter a transfer amount that is lesser than Rs. 10000. |
  | BENEFICIARY\_BLACKLISTED | Merchant | Beneficiary is blacklisted | Enter a beneficiary that is not in the blacklist. |
  | PAYOUT\_INACTIVE | Merchant | Payout account is not active | |
  | INVALID\_TRANSFER\_AMOUNT | Merchant | Transfer amount is invalid | Enter a valid transfer amount. |
  | BENEFICIARY\_NOT\_EXIST | Merchant | Beneficiary does not exist | Enter valid beneficiary details. |
  | BENEFICIARY\_INVALID\_MODE | Merchant | Mode Not valid for Beneficiary | Enter a different transfer mode for the specified beneficiary. |
  | INVALID\_BENE\_ACCOUNT\_OR\_IFSC | Merchant | Invalid bank account number or ifsc provided | Enter a valid bank account number or IFSC. |
  | BENEFICIARY\_NAME\_DIFFERS | Customer | Beneficiary name not matching with bank records | Enter the beneficiary name as per bank records. |
  | ANY\_OTHER\_REASON | Bank | No reason provided for the failure/reversal | |
  | INVALID\_OR\_NO\_SUCH\_ACCOUNT\_TYPE | Customer | Invalid account | |
</Accordion>

<Accordion title="List of possible transfer statuses returned by Cashfree.">
  | Transfer status | Description |
  | :- | :- |
  | SUCCESS | Transfer completed successfully. Acknowledged flag in the response tells whether the beneficiary bank has provided acknowledgement of the transfer request. |
  | ERROR | There was an error while requesting the transfer. See sub status code received for more details on why the error occurred. Example: Wrong IFSC. |
  | FAILED | The transfer has failed. |
  | PENDING | The request is getting processed. Query transfer status (/getTransferStatus) after some time to see whether the request was successful/failed. |
  | REVERSED | Transfer rejected by the beneficiary bank. The payout balance gets credited back with the amount charged. You don't receive this when you are attempting a transfer but might see this when querying for transfer status (after a couple of hours). Configure the webhook endpoint to be notified in such cases. |
</Accordion>


# Getting Started
Source: https://www.cashfree.com/docs/api-reference/payouts/v1/getting-started-with-payouts-apis

Set up sandbox credentials, IP whitelisting, and the production environment so you can test and go live with the Cashfree Payouts v1 APIs and SDKs.

1. [Download Postman Collection](#download-postman-collection)
2. [View End Points](#view-end-points)
3. [Generate API Keys](#generate-api-keys)
4. [Whitelist IP Address](#whitelist-your-ip-address) / [Generate Signature](#generate-signature)
5. [Any Queries: Contact Us](#any-queries-contact-us)

***

## Download Postman collection

This collection can save you time because of easy access to different requests.

[Download Cashfree Payouts Postman Collection](https://gocashassets.s3.ap-south-1.amazonaws.com/repostmancollection/Cashfree_Payouts_Collection.json.zip)

***

## View end points

| Environment | Base URL |
| :- | :- |
| Production | [https://payout-api.cashfree.com](https://payout-api.cashfree.com) |
| Test | [https://payout-gamma.cashfree.com](https://payout-gamma.cashfree.com) |

Cashfree uses unique identifiers to allow access to the API. Once you have signed up at our merchant site, you can see your **AppId** and **SecretKey**. Each API request to the server requires these credentials.

Use this endpoint to verify your credentials: /api/v1/credentials/verify

***

## Generate API keys

Follow the instructions below to generate API keys:

1. From the Payouts dashboard, click **Developers** on the navigation panel.
2. Click **API Keys**.
3. Click **Generate API Keys** from the *API Keys* screen.
4. The *New API Keys* popup displays with the client ID and client secret information.
5. Click **Download API Keys** to download the information and save them in your local system folder. Do not share the keys with anyone because they are confidential. You can generate a maximum of 10 API keys.

<Note>
  API Keys - Production Environment: You need to perform an OTP authentication
  to generate API keys for production environment.
</Note>

***

## Identity verification

Whitelisting the IP address or generating a signature provides a layer of authentication. These cybersecurity techniques prevent anonymous or unknown disbursement requests and allow only verified requests.

### Whitelist your IP address

Your IP address needs to be whitelisted in the Cashfree production server or it rejects all incoming requests.

<Note>
  Only the production environment needs approval from Cashfree and not
  for the test environment.
</Note>

Follow the instructions below to whitelist your IP:

1. From the \_Payout\_s dashboard, click **Developers** > **Two-Factor Authentication**.
2. Choose **IP Whitelist** from the *Select 2FA Method* drop-down.
3. Click **Add IP Address**.
4. Enter the IP address you want to whitelist in the respective field and click **Add IP Address** to save the details. Note that the IPv4 has to be whitelisted, and not IPv6. The whitelisted IPs are displayed in the grid as shown below. You can whitelist a maximum of 25 IPs.

### Generate signature

To generate a signature, you need to generate the public key. You then use the generated public key to generate the signature.

#### Generate public key

1. From the *Payouts* dashboard, click **Developers** > **Two-Factor Authentication**.
2. Select **Public Key** from the *Select 2FA Method* drop-down.
3. Click **Generate Public Key**.
4. The public key is downloaded to your computer. Use your registered email ID to access the key.

#### Generate signature

Below are the steps to generate your signature:

1. Retrieve your clientId (one which you are passing through the header X-Client-Id )
2. Append this with CURRENT UNIX timestamp separated by a period (.)
3. Encrypt this data using RSA encrypt with Public key you received – this is the signature.
4. Pass this signature through the header X-Cf-Signature.

In the case of using our library, go through the libraries section. During the initialization process, you need to pass the key as a parameter.

<CodeGroup>
  ```php PHP theme={"dark"}
  [](?php
  public static function getSignature() {
      $clientId = "[](your clientId here>";
      $publicKey =
  openssl_pkey_get_public(file_get_contents("/path/to/certificate/public
  _key.pem"));
      $encodedData = $clientId.".".strtotime("now");
      return static::encrypt_RSA($encodedData, $publicKey);
    }
  private static function encrypt_RSA($plainData, $publicKey) { if (openssl_public_encrypt($plainData, $encrypted, $publicKey,
  OPENSSL_PKCS1_OAEP_PADDING))
        $encryptedData = base64_encode($encrypted);
      else return NULL;
      return $encryptedData;
    }
  ?>
  ```

  ```java Java theme={"dark"}
  private static String generateEncryptedSignature(String clientIdWithEpochTimestamp) {
      // String clientIdWithEpochTimeStamp = clientId+"."+Instant.now().getEpochSecond();
      String encrytedSignature = "";
      try {
          byte[] keyBytes = Files
              .readAllBytes(new File("/Users/sameera/Downloads/payout_test_public_key.pem").toPath()); // Absolute Path to be replaced
          String publicKeyContent = new String(keyBytes);
          System.out.println(publicKeyContent);
          publicKeyContent = publicKeyContent.replaceAll("[\\t\\n\\r]", "")
              .replace("-----BEGIN PUBLIC KEY-----", "").replace("-----END PUBLIC KEY-----", "");
          KeyFactory kf = KeyFactory.getInstance("RSA");
          System.out.println(publicKeyContent);
          X509EncodedKeySpec keySpecX509 = new X509EncodedKeySpec(
              Base64.getDecoder().decode(publicKeyContent));
          RSAPublicKey pubKey = (RSAPublicKey) kf.generatePublic(keySpecX509);
          final Cipher cipher = Cipher.getInstance("RSA/ECB/OAEPWithSHA-1AndMGF1Padding");
          cipher.init(Cipher.ENCRYPT_MODE, pubKey);
          encrytedSignature = Base64.getEncoder().encodeToString(cipher.doFinal(clientIdWithEpochTimestamp.getBytes()));
          System.out.println(encrytedSignature);
      } catch (Exception e) {
          e.printStackTrace();
      }
      return encrytedSignature;
  }
  ```

  ```python Python theme={"dark"}
  from cashfree_sdk.payouts import Payouts
  // Initialise the SDK, pass public key for dynamic IP
  Payouts.init("[](client_id>", "[](client_secret>", "PROD", public_key= b'public key')
  ```

  ```javascript Node theme={"dark"}
  //require CashfreeSDK
  const cfSdk = require("cashfree-sdk");

  //access the PayoutsSdk from CashfreeSDK
  const { Payouts } = cfSdk;

  // Instantiate Cashfree Payouts
  const payoutsInstance = new Payouts({
  	env: "TEST",
  	clientId: "[](CLIENT_ID>",
  	clientSecret: "[](CLIENT_SECRET>",
  	pathToPublicKey: "/path/to/your/public/key/file.pem",
  	//"publicKey": "ALTERNATIVE TO SPECIFYING PATH (DIRECTLY PASTE PublicKey)"
  });
  ```
</CodeGroup>

***

## Any queries: Contact us

For identifying, diagnosing, and resolving problems related to API requests, ensure the information below is communicated while contacting us:

* Share the API request and response details along with only **x-client-ID**.
* Mention the registered email ID and environment in the email.
* Use your registered email address (with Cashfree) to send the email or mention the registered email address.
* Include your account manager in the CC of the email request.

<Note>
  For dashboard queries, share the screenshot and .har file of the screen.
</Note>


# Internal Transfer
Source: https://www.cashfree.com/docs/api-reference/payouts/v1/internal-transfer

post /payout/v1/internalTransfer
Use this API to request an internal transfer at Cashfree. The internal transfer API is useful for multiple Payouts accounts. The API response will either result in an ERROR or SUCCESS response.

Please use this Authorization token in headers to call any payout API (Refresh this page if the token is expired)

<iframe />


# Internal Transfer V1.2
Source: https://www.cashfree.com/docs/api-reference/payouts/v1/internal-transfer-v12

post /payout/v1.2/internalTransfer
Use this API to request an internal transfer. It is useful for accounts with multiple fund sources. You need to provide either the rechargeAccount or paymentInstrumentId and toPaymentInstrumentId along with the amount.

Please use this Authorization token in headers to call any payout API (Refresh this page if the token is expired)

<iframe />


# Lend
Source: https://www.cashfree.com/docs/api-reference/payouts/v1/lend

post /payout/v1/lend
Use this API to send requests for loan disbursement to the beneficiary. The service charges are pooled for the respective party and disbursed at the end of day. Disbursement amount = (Amount - total service charges).

Please use this Authorization token in headers to call any payout API (Refresh this page if the token is expired)

<iframe />

<Accordion title="Click to view the response codes.">
  | Sub code | Status | Message | Next action |
  | :- | :- | :- | :- |
  | 200 | SUCCESS | Transfer completed successfully | None |
  | 201 | PENDING | Transfer request pending at the bank | None |
  | 400 | ERROR | beneId is missing in the request | Enter a beneId in the request |
  | 400 | ERROR | Total service charge is greater than disbursal amount | Enter valid amount which is greater than sum of service charges |
  | 400 | ERROR | Insufficient balance in LENDER fundsource | Lender needs to recharges their CF wallet |
  | 403 | ERROR | APIs not enabled. Please fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) | Please fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) |
  | 422 | ERROR | Please provide valid token details | Provide a valid token |
  | 422 | ERROR | amount should be at least 1.0 | Enter a transfer amount that is equal to or more than Rs. 1. |
  | 422 | ERROR | Invalid bank account number or ifsc provided | Provide valid bank account details |
</Accordion>


# Add Registered Recharge Account(Whitelist Bank Account)
Source: https://www.cashfree.com/docs/api-reference/payouts/v1/oneescrow/add-registered-recharge-accountwhitelist-bank-account

post /v1/whitelisted-bank-accounts



# Create Virtual Account
Source: https://www.cashfree.com/docs/api-reference/payouts/v1/oneescrow/create-virtual-account

post /fundsources/connected/virtual-account
Use this API to create a virtual account that helps streamline the management of funds, enhance tracking capabilities, and simplify the financial process.



# Debit Connected Wallet
Source: https://www.cashfree.com/docs/api-reference/payouts/v1/oneescrow/debit-connected-wallet

post /payout/v1/connected-wallet/debit



# Get Account Statement
Source: https://www.cashfree.com/docs/api-reference/payouts/v1/oneescrow/get-account-statement

get /v1/accountStatement
Use this API to fetch the account statement of the virtual account in a paginated format using cursor-based pagination.



# Get Fund Source Details
Source: https://www.cashfree.com/docs/api-reference/payouts/v1/oneescrow/get-fund-source-details

get /v1/fundsources/{paymentInstrumentId}
Use this API to get the details of the fund source.



# Allocate Funds to Virtual Account
Source: https://www.cashfree.com/docs/api-reference/payouts/v1/oneescrow/recharge-oneescrow-account

post /v1/connected-wallet/recharge
Use this API to recharge the OneEscrow account (notional credit) using a payment instrument.



# Transfer Funds Between VAs
Source: https://www.cashfree.com/docs/api-reference/payouts/v1/oneescrow/transfer-funds-between-vas

post /v1.2/internalTransfer
Use this API to transfer funds between virtual accounts (VAs).



# Overview
Source: https://www.cashfree.com/docs/api-reference/payouts/v1/payouts-api-overview

Use Cashfree Payouts v1 APIs to send funds to bank accounts, UPI IDs, cards, and wallets, with sandbox and production keys, request parameters, and error codes.

**You can perform the following tasks using the Payouts API:**

* Add and manage your beneficiaries efficiently
* Transfer money to your beneficiaries' accounts using different transfer methods
* Track the transfer status
* Check the ledger and available balance instantly

<Note>
  Use the [V2 version](/docs/api-reference/payouts/v2/payouts-api-v2-new) of the Payouts APIs if you are starting a new integration. V1 is a legacy version.
</Note>

## Beneficiary APIs

| API name | Description |
| :- | :- |
| [Add Beneficiary](/docs/api-reference/payouts/v1/add-beneficiary) | Add a beneficiary to your Payouts account. |
| [Retrieve Beneficiary Details](/docs/api-reference/payouts/v1/get-beneficiary-details) | Retrieve a beneficiary's details. |
| [Find Beneficiary ID](/docs/api-reference/payouts/v1/get-beneficiary-id) | Find the ID of a specific beneficiary. |
| [Remove Beneficiary](/docs/api-reference/payouts/v1/remove-beneficiary) | Remove a beneficiary from your Payouts account. |
| [Retrieve Beneficiary Transfers](/docs/api-reference/payouts/v1/get-beneficiary-history) | Retrieve transfer data of a specific beneficiary. |

## Account APIs

| API name | Description |
| :- | :- |
| [View Balance](/docs/api-reference/payouts/v1/get-balance) | View the ledger and available balance of your account. |
| [View Balance V1.2](/docs/api-reference/payouts/v1/get-balance-v12) | Version 1.2 allows you to specify the payment instrument Id. |
| [Self Withdrawal](/docs/api-reference/payouts/v1/self-withdrawal) | Request a self-withdrawal from your Payouts account. |
| [Internal Transfer](/docs/api-reference/payouts/v1/internal-transfer) | Request an internal transfer between your Payouts accounts. |

## Transfers APIs

| API version 1.2 | API version 1 | Description | Transactions per minute (TPM) | Response time |
| :- | :- | :- | :- | :- |
| [Standard Transfer Sync V1.2](/docs/api-reference/payouts/v1/standard-transfer-sync-v12) | [Standard Transfer Sync](/docs/api-reference/payouts/v1/standard-transfer-sync) | Initiate a sync transfer request | N/A | 9.77 s |
| [Standard Transfer Async V1.2](/docs/api-reference/payouts/v1/standard-transfer-async-v12) | [Standard Transfer Async](/docs/api-reference/payouts/v1/standard-transfer-async) | Initiate an async transfer request | 1000 | 25.0 ms |
| [Direct Transfer V1.2](/docs/api-reference/payouts/v1/direct-transfer-v12) | [Direct Transfer](/docs/api-reference/payouts/v1/direct-transfer) | Initiate an amount transfer request directly to the beneficiary not in the database. | 1000 | 9.04 s |
| [Get Transfer Status V1.2](/docs/api-reference/payouts/v1/get-transfer-status-v12) | [Get Transfer Status](/docs/api-reference/payouts/v1/get-transfer-status) | Get the status of the transfer request. | - | 244 ms |
| [Batch Transfer V1.2](/docs/api-reference/payouts/v1/batch-transfer-v12) | [Batch Transfer](/docs/api-reference/payouts/v1/batch-transfer) | Initiate a transfer request to multiple beneficiaries. | 1000 | 182 ms |
| [Get Batch Transfer Status V1.2](/docs/api-reference/payouts/v1/get-batch-transfer-status-v12) | [Get Batch Transfer Status](/docs/api-reference/payouts/v1/get-batch-transfer-status) | Get the status of the batch transfer request. | - | 6.19 ms |
| [Validate Payout V1.2](/docs/api-reference/payouts/v1/validate-payout-v1-2) | [Validate Payout V1](/docs/api-reference/payouts/v1/validate-payout-v1) | Validates a UPI VPA or phone number and returns a single-use transfer token. | - | - |
| [Process Validated Payout V1.2](/docs/api-reference/payouts/v1/verify-and-pay-direct-transfer-v1-2) | [Process Validated Payout V1](/docs/api-reference/payouts/v1/verify-and-pay-direct-transfer-v1) | Initiates a payout using the transfer token from the corresponding Validate Payout API. | - | - |

***

## Payouts - Postman Collection

This collection can save you time because of easy access to different requests.

<a href="https://gocashassets.s3.ap-south-1.amazonaws.com/repostmancollection/Cashfree_Payouts_Collection.json.zip">
  Download Cashfree Payouts Postman Collection
</a>


# Remove Beneficiary
Source: https://www.cashfree.com/docs/api-reference/payouts/v1/remove-beneficiary

post /payout/v1/removeBeneficiary
Use this API to remove an existing beneficiary from a list of added beneficiaries.

<Warning> This API will be retired soon. Please plan to migrate to the latest version, [Beneficiary V2](/docs/api-reference/payouts/v2/beneficiary-v2/get-beneficiary-v2). </Warning>

Please use this Authorization token in headers to call any payout API (Refresh this page if the token is expired)

<iframe />

<Accordion title="Click to view the response codes.">
  | Sub code | Status | Message | Next action |
  | :- | :- | :- | :- |
  | 200 | SUCCESS | Beneficiary removed | - |
  | 403 | ERROR | Token is not valid | Validate the generated token. |
  | 403 | ERROR | IP not whitelisted | Whitelist the IP address. |
  | 404 | ERROR | Beneficiary does not exist with given Id | Enter a valid beneficiary ID. |
  | 412 | ERROR | Token missing in the request | Enter the generated token as the value for Authorization under Headers in this format: `Bearer <token>` |
  | 412 | ERROR | BeneId missing in the request | Enter a valid beneficiary ID. |
  | 422 | ERROR | Please provide a valid Beneficiary Id | Enter a valid beneficiary ID. |
  | 520 | ERROR | Unknown error occurred | Try again after some time. |
</Accordion>


# Response Codes
Source: https://www.cashfree.com/docs/api-reference/payouts/v1/response-codes

Look up Cashfree Payouts v1 response codes for Cashgram, beneficiary, and transfer APIs, with HTTP status, error codes, messages, and recommended next actions.

## Cashgram V1

### Create Cashgram

<Accordion title="Click to view the response codes.">
  | HTTP status code | Error code | Message | Next action |
  | - | - | - | - |
  | 200 | - | Cashgram created successfully. | N/A |
  | 409 | cashgram\_id\_already\_exists | A Cashgram with the given ID already exists. Please provide a unique Cashgram ID. | Provide a unique Cashgram ID. |
  | 422 | notifyCustomer\_invalid | The `notifyCustomer` value can only be 0 or 1. Please try again with a valid value. | Use a valid `notifyCustomer` value (0 or 1). |
  | 422 | amount\_invalid | The amount must be at least 1. Please try again with a valid amount. | Provide an amount of 1 or more. |
  | 422 | cashgram\_id\_length\_exceeded | The Cashgram ID cannot exceed 36 characters. Please try again with a valid Cashgram ID. | Provide a Cashgram ID of 36 characters or fewer. |
  | 422 | phone\_invalid | The phone number must be numeric and valid. Please try again with the correct phone number. | Provide a valid numeric phone number. |
  | 422 | expiry\_date\_invalid | The link expiry date must be in the format `YYYY/MM/DD` and within 30 days from the creation date. | Provide a valid expiry date in the correct format. |
  | 422 | amount\_below\_minimum | The requested Cashgram amount is below the minimum allowed amount of ₹x. | Increase the amount or update the minimum amount preference. |
  | 422 | amount\_above\_maximum | The requested Cashgram amount exceeds the maximum allowed amount of ₹x. | Decrease the amount or update the maximum amount preference. |
  | 500 | internal\_error | An internal error occurred. Please try again later. | Retry after some time. If the issue persists, contact support. |
  | 500 | no\_fund\_source\_active | No active fund source is available for your account. | Activate a fund source and try again. |
  | 500 | rates\_not\_configured | Rates have not been configured. Please contact Cashfree. | Reach out to Cashfree to configure rates. |
  | 520 | unknown\_error | An unknown error occurred. Please try again later. | Retry after some time. If the issue persists, contact support. |
</Accordion>

### Get Cashgram Status

<Accordion title="Click to view the response codes.">
  | HTTP status code | Error code | Message | Next action |
  | - | - | - | - |
  | 200 | - | Cashgram details retrieved successfully. | N/A |
  | 404 | cashgram\_not\_found | A Cashgram with the given ID does not exist. | Provide a valid Cashgram ID. |
  | 422 | cashgram\_id\_invalid | Please provide a valid Cashgram ID. | Provide a valid Cashgram ID. |
  | 422 | cashgram\_id\_length\_exceeded | The Cashgram ID cannot exceed 37 characters. Please try again. | Provide a Cashgram ID of 37 characters or fewer. |
  | 500 | internal\_error | An internal error occurred. Please try again later. | Retry after some time. If the issue persists, contact support. |
</Accordion>

### Deactivate Cashgram

<Accordion title="Click to view the response codes.">
  | HTTP status code | Error code | Message | Next action |
  | - | - | - | - |
  | 200 | - | Cashgram with ID - ABC123 successfully deactivated. | N/A |
  | 404 | cashgram\_not\_found | The given Cashgram ID does not exist. Please provide a valid Cashgram ID. | Provide a valid Cashgram ID. |
  | 412 | cashgram\_already\_processed | Cashgram with ID - ABC123 has already been processed and cannot be deactivated. | No action possible. |
  | 412 | cashgram\_expired | Cashgram with ID - ABC123 has already expired and cannot be deactivated. | No action possible. |
  | 412 | status\_update\_not\_allowed | The status of the given Cashgram is not active. Only active Cashgrams can be deactivated. | Ensure the Cashgram status is active before deactivating. |
  | 412 | cashgram\_already\_redeemed | The Cashgram provided in the request has already been redeemed and cannot be deactivated. | No action possible. |
  | 500 | internal\_error | An internal error occurred. Please try again later. | Retry after some time. If the issue persists, contact support. |
</Accordion>


# Self Withdrawal
Source: https://www.cashfree.com/docs/api-reference/payouts/v1/self-withdrawal

post /payout/v1/selfWithdrawal
Use this API to request a self withdrawal at Cashfree. Self withdrawal is allowed a maximum of 3 times a day. The API response will either result in an ERROR or SUCCESS response. The status of the withdrawal request is available on the dashboard.

Please use this Authorization token in headers to call any payout API (Refresh this page if the token is expired)

<iframe />

<Accordion title="Click to view the response codes.">
  | Sub code | Status | Message | Next action |
  | :- | :- | :- | :- |
  | 200 | SUCCESS | | - |
  | 403 | ERROR | Token is not valid | Verify the generated token. |
  | 412 | ERROR | withdrawalId missing in the request | Enter a withdrawal ID. |
  | 412 | ERROR | Token missing in the request | Enter the generated token as the value for Authorization under Headers |
</Accordion>


# Standard Transfer Async
Source: https://www.cashfree.com/docs/api-reference/payouts/v1/standard-transfer-async

post /payout/v1/requestAsyncTransfer
Use this API to initiate an amount transfer request at Cashfree by providing beneficiary id, amount, and transfer id. This is an async transfer request.

<Warning> This API will be retired soon. Please plan to migrate to the latest version, [Transfers V2](/docs/api-reference/payouts/v2/transfers-v2/get-transfer-status-v2). </Warning>

Once you trigger the requestAsyncTransfer API, Cashfree verifies your request and returns the Cashfree referenceId. The transfer to beneficiary account will be attempted within the next 60 seconds and you may query the transfer status after 60 seconds.

Use this API to process very high volumes.

**Benefits**:

1. The API response is much faster for the async transfer endpoint. The async transfer response takes \<100 ms as compared to a median value of 2-5 sec for the sync payout transfer API.
2. The asynchronous API can handle a higher TPM (transactions per minute) as compared to the synchronous API. The async API allows us to handle up to 1000 transactions per minute.

Please use this Authorization token in headers to call any payout API (Refresh this page if the token is expired)

<iframe />

<Accordion title="Click to view the response codes.">
  | Sub code | Status | Message |
  | :- | :- | :- |
  | 200 | SUCCESS | Transfer completed successfully. |
  | 201 | SUCCESS | Transfer Scheduled for next working day. |
  | 201 | PENDING | Awaiting confirmation from beneficiary bank. |
  | 201 | PENDING | Transfer request pending at the bank. |
  | 202 | PENDING | Request received. Please check status after some time. |
  | 403 | ERROR | Token is not valid |
  | 403 | ERROR | IP not whitelisted |
  | 403 | ERROR | This feature is not available for your account. |
  | 403 | ERROR | Transfer mode is not available for your account. |
  | 412 | ERROR | Token missing in the request. |
  | 412 | ERROR | BeneId missing in the request. |
  | 412 | ERROR | Amount missing in the request. |
  | 412 | ERROR | TransferId missing in the request. |
  | 422 | ERROR | Invalid amount passed. |
  | 422 | ERROR | Invalid transferId passed. |
  | 422 | ERROR | No Payee Virtual Address associated with the beneficiary. |
  | 422 | ERROR | Remarks can have only numbers, alphabets and whitespaces. |
  | 409 | ERROR | Transfer Id already exists. |
  | 404 | ERROR | Beneficiary does not exist. |
  | 422 | ERROR | Beneficiary details not valid. |
  | 422 | ERROR | No Bank account or IFSC associated with the beneficiary. |
  | 412 | ERROR | Not enough available balance in the account. |
  | 412 | ERROR | Please wait 30 minutes after adding the beneficiary. |
  | 412 | ERROR | Transfer amount is less than minimum amount of Rs. 100. |
  | 412 | ERROR | Transfer amount is greater than the maximum amount of Rs.100000. |
  | 422 | ERROR | Invalid IFSC code provided for bank account. |
  | 422 | ERROR | Invalid bank account number or IFSC provided. |
  | 422 | ERROR | Transfer request to paytm wallet failed. |
  | 400/520 | ERROR | Transfer attempt failed at the bank. |
  | 520 | ERROR | Transfer request triggered. No response from bank. |
  | 403 | ERROR | Transfer to this beneficiary not allowed. |
  | 412 | ERROR | Transfer limit for beneficiary exceeded. |
  | 412 | ERROR | Transfer limit for your account exceeded. |
  | 412 | ERROR | Invalid transfer mode passed in the request. |
  | 412 | ERROR | Transfer mode not enabled for the account. |
  | 412 | ERROR | Invalid Tag passed in the request. |
</Accordion>


# Standard Transfer Async v1.2
Source: https://www.cashfree.com/docs/api-reference/payouts/v1/standard-transfer-async-v12

post /payout/v1.2/requestAsyncTransfer
Use this API to initiate an amount transfer request at Cashfree by providing beneficiary id, amount, and transfer id. This is an async transfer request.

<Warning> This API will be retired soon. Please plan to migrate to the latest version, [Transfers V2](/docs/api-reference/payouts/v2/transfers-v2/get-transfer-status-v2). </Warning>

Once you trigger the requestAsyncTransfer API, Cashfree verifies your request and returns the Cashfree referenceId. The transfer to beneficiary account will be attempted within the next 60 seconds and you may query the transfer status after 60 seconds.

Use this API to process very high volumes.

**Benefits**:

1. The API response is much faster for the async transfer endpoint. The async transfer response takes \<100 ms as compared to a median value of 2-5 sec for the sync payout transfer API.
2. The asynchronous API can handle a higher TPM (transactions per minute) as compared to the synchronous API. The async API allows us to handle up to 1000 transactions per minute.

Please use this Authorization token in headers to call any payout API (Refresh this page if the token is expired)

<iframe />

<Accordion title="Click to view the response codes.">
  | Sub code | Status | Message | Next action |
  | :- | :- | :- | :- |
  | 200 | SUCCESS | Transfer completed successfully. | - |
  | 201 | PENDING | Transfer Scheduled for next working day. | - |
  | 201 | PENDING | Awaiting confirmation from beneficiary bank. | - |
  | 201 | PENDING | Transfer request pending at the bank. | - |
  | 202 | PENDING | Request received. Please check status after some time. | - |
  | 400 | ERROR | Transfer amount is less than minimum amount of Rs.1 | Enter a transfer amount that is equal to or more than Rs. 1. |
  | 400 | ERROR | Not enough available balance in the account. | Retry with sufficient balance in the account. |
  | 400 | ERROR | Transfer Id already exists. | Enter a different transfer ID. |
  | 400 | ERROR | Please wait 30 minutes after adding the beneficiary. | - |
  | 400 | ERROR | Transfer amount is less than minimum amount of Rs. 100. | Enter a transfer amount that is equal to or more than Rs. 100. |
  | 400 | ERROR | Transfer amount is greater than the maximum amount of Rs.100000. | Enter a transfer amount that is equal to or less than Rs. 100000. |
  | 400 | ERROR | Transfer attempt failed at the bank. | |
  | 400 | ERROR | Transfer to this beneficiary not allowed. | Enter a different beneficiary ID. |
  | 400 | ERROR | Transfer limit for your account exceeded. | |
  | 400 | ERROR | Transfer limit for beneficiary exceeded. | |
  | 403 | ERROR | Token is not valid | Verify the generated token. |
  | 404 | ERROR | Beneficiary does not exist. | Enter a valid beneficiary ID. |
  | 412 | ERROR | Transfer mode not enabled for the account. | |
  | 422 | ERROR | Please provide a valid beneId | Enter a valid beneficiary ID. |
  | 422 | ERROR | Invalid Amount Passed. Only 2 decimal places are allowed. | Enter an amount with a maximum of only 2 decimal places. |
  | 422 | ERROR | Please provide a valid transferId. | Enter a valid transfer ID. |
  | 422 | ERROR | Invalid IFSC code provided for bank account. | Enter a valid IFSC. |
  | 422 | ERROR | Invalid bank account number or IFSC provided. | Enter a valid bank account number and IFSC. |
</Accordion>


# Standard Transfer Sync
Source: https://www.cashfree.com/docs/api-reference/payouts/v1/standard-transfer-sync

post /payout/v1/requestTransfer
Use this API to initiate an amount transfer request at Cashfree by providing beneficiary id, amount, and transfer id. This is a sync transfer request.

<Warning> This API will be retired soon. Please plan to migrate to the latest version, [Transfers V2](/docs/api-reference/payouts/v2/transfers-v2/get-transfer-status-v2). </Warning>

Once you trigger the requestTransfer API, the transfer to the beneficiary account will be attempted immediately and the bank's reference number will be returned in the API response. The median time for the response is 2 to 5 seconds.

Please use this Authorization token in headers to call any payout API (Refresh this page if the token is expired)

<iframe />

<Accordion title="Click to view the response codes.">
  | Sub code | Status | Message | Next action |
  | :- | :- | :- | :- |
  | 200 | SUCCESS | Transfer completed successfully. | |
  | 201 | SUCCESS | Transfer Scheduled for next working day. | |
  | 201 | PENDING | Awaiting confirmation from beneficiary bank. | |
  | 201 | PENDING | Transfer request pending at the bank. | |
  | 202 | PENDING | Request received. Please check status after some time. | |
  | 403 | ERROR | Token is not valid | Verify the generated token. |
  | 403 | ERROR | IP not whitelisted | Whitelist the IP address. |
  | 403 | ERROR | This feature is not available for your account. | |
  | 403 | ERROR | Transfer mode is not available for your account. | |
  | 412 | ERROR | Token missing in the request. | |
  | 412 | ERROR | BeneId missing in the request. | Enter a valid beneficiary ID. |
  | 412 | ERROR | Amount missing in the request. | Enter a valid transfer amount. |
  | 412 | ERROR | TransferId missing in the request. | Enter a valid transfer ID. |
  | 422 | ERROR | Invalid amount passed. | Enter a valid transfer amount. |
  | 422 | ERROR | Invalid transferId passed. | Enter a valid transfer ID. |
  | 422 | ERROR | No Payee Virtual Address associated with the beneficiary. | |
  | 422 | ERROR | Remarks can have only numbers, alphabets and whitespaces. | Enter any remarks of a maximum of 70 alphanumeric characters and white spaces. |
  | 409 | ERROR | Transfer Id already exists. | Enter a different transfer ID. |
  | 404 | ERROR | Beneficiary does not exist. | Enter valid beneficiary details. |
  | 422 | ERROR | Beneficiary details not valid. | Enter valid beneficiary details. |
  | 422 | ERROR | No Bank account or IFSC associated with the beneficiary. | Enter valid bank account details. |
  | 412 | ERROR | Not enough available balance in the account. | Retry with sufficient balance in the account. |
  | 412 | ERROR | Please wait 30 minutes after adding the beneficiary. | |
  | 412 | ERROR | Transfer amount is less than minimum amount of Rs. 100. | Enter a transfer amount that is equal to or more than Rs. 100. |
  | 412 | ERROR | Transfer amount is greater than the maximum amount of Rs.100000. | Enter a transfer amount that is equal to or less than Rs. 100000. |
  | 422 | ERROR | Invalid IFSC code provided for bank account. | Enter valid bank account details. |
  | 422 | ERROR | Invalid bank account number or IFSC provided. | Enter a valid bank account number and IFSC. |
  | 422 | ERROR | Transfer request to paytm wallet failed. | |
  | 400/520 | ERROR | Transfer attempt failed at the bank. | |
  | 520 | ERROR | Transfer request triggered. No response from bank. | |
  | 403 | ERROR | Transfer to this beneficiary not allowed. | Enter a different beneficiary ID. |
  | 400 | ERROR | Transfer limit for beneficiary exceeded. | |
  | 412 | ERROR | Transfer limit for your account exceeded. | |
  | 412 | ERROR | Invalid transfer mode passed in the request. | |
  | 412 | ERROR | Transfer mode not enabled for the account. | |
  | 412 | ERROR | Invalid Tag passed in the request. | |
</Accordion>


# Standard Transfer Sync v1.2
Source: https://www.cashfree.com/docs/api-reference/payouts/v1/standard-transfer-sync-v12

post /payout/v1.2/requestTransfer
Use this API to initiate an amount transfer request at Cashfree by providing beneficiary id, amount, and transfer id. This is a sync transfer request.

<Warning> This API will be retired soon. Please plan to migrate to the latest version, [Transfers V2](/docs/api-reference/payouts/v2/transfers-v2/get-transfer-status-v2). </Warning>

Once you trigger the requestTransfer API, the transfer to the beneficiary account will be attempted immediately and the bank's reference number will be returned in the API response. The median time for the response is 2 to 5 seconds.

Please use this Authorization token in headers to call any payout API (Refresh this page if the token is expired)

<iframe />

<Accordion title="Click to view the response codes.">
  | Sub code | Status | Message | Next action |
  | :- | :- | :- | :- |
  | 200 | SUCCESS | Transfer completed successfully. | - |
  | 201 | SUCCESS | Transfer Scheduled for next working day. | - |
  | 201 | PENDING | Awaiting confirmation from beneficiary bank. | - |
  | 201 | PENDING | Transfer request pending at the bank. | - |
  | 201 | ERROR | Transfer request triggered. No response from bank. | - |
  | 202 | PENDING | Request received. Please check status after some time. | - |
  | 400 | ERROR | Mode Not valid for Beneficiary. | Enter a different transfer mode for the beneficiary. |
  | 400 | ERROR | Transfer Id already exists. | Enter a different transfer ID. |
  | 400 | ERROR | Not enough available balance in the account. | Retry with sufficient balance in the account. |
  | 400 | ERROR | Please wait 30 minutes after adding the beneficiary. | - |
  | 400 | ERROR | Transfer amount is less than minimum amount of Rs. 100. | Enter a transfer amount that is equal to or more than Rs. 100. |
  | 400 | ERROR | Transfer amount is greater than the maximum amount of Rs.100000. | Enter a transfer amount that is equal to or less than Rs. 100000. |
  | 400 | ERROR | Transfer request to paytm wallet failed. | Retry the request with a different transfer mode. |
  | 400 | ERROR | Transfer attempt failed at the bank. | |
  | 400 | ERROR | Transfer to this beneficiary not allowed. | Enter a different beneficiary ID. |
  | 400 | ERROR | Transfer amount is less than minimum amount of Rs.1 | Enter a transfer amount that is equal to or more than Rs. 1. |
  | 400 | ERROR | Transfer limit for your account exceeded. | |
  | 400 | ERROR | Transfer mode not enabled for the account. | |
  | 400 | ERROR | Specified paymentInstrumentId not available. | Enter a valid payment instrument ID. |
  | 400 | ERROR | Specified paymentInstrumentId not valid for this payment mode. | Enter a valid payment instrument ID. |
  | 400 | ERROR | Multiple PaymentInstruments available for this payment mode. | |
  | 400 | ERROR | Transfer limit for beneficiary exceeded. | |
  | 403 | ERROR | Token is not valid | Verify the generated token. |
  | 403 | ERROR | IP not whitelisted | Whitelist the IP address. |
  | 404 | ERROR | Beneficiary does not exist. | Enter a valid beneficiary ID. |
  | 412 | ERROR | Please provide a valid transferId. | Enter a valid transfer ID. |
  | 422 | ERROR | Please provide a valid beneId. | Enter a valid beneficiary ID. |
  | 422 | ERROR | Invalid bank account number or IFSC provided. | Enter a valid bank account number and IFSC. |
  | 422 | ERROR | Invalid IFSC code provided for bank account. | Enter a valid IFSC. |
  | 422 | ERROR | Invalid Amount Passed. Only 2 decimal places are allowed. | |
  | 422 | ERROR | Please provide a valid transferId. | Enter a valid transfer ID. |
  | 422 | ERROR | Remarks is invalid. | Enter any remarks of a maximum of 70 alphanumeric characters and white spaces. |
</Accordion>


# Overview
Source: https://www.cashfree.com/docs/api-reference/payouts/v1/transfer

Transfer funds to your beneficiaries through Cashfree Payouts v1 using bank transfers, Paytm, Amazon Pay, UPI, IMPS, and NEFT, with sync and async modes.

<Warning> These APIs will be retired soon. Please plan to migrate to the latest version, Transfers V2. </Warning>

You can perform the following tasks using the transfers API:

* Transfer money to your beneficiaries accounts through Sync, Async, Direct, and Batch APIs.
* Check the status of each transfer using the referenceId or transferId.

The flow diagram will help you understand the different transfer APIs and their use cases.

<Frame>
  <img />
</Frame>

Learn how each API functions using the following table and use the best-suited API for your transactions.

| | [Transfer sync](/docs/api-reference/payouts/v1/standard-transfer-sync-v12) | [Transfer async](/docs/api-reference/payouts/v1/standard-transfer-async-v12) | [Direct transfer](/docs/api-reference/payouts/v1/direct-transfer-v12) | [Batch transfer](/docs/api-reference/payouts/v1/batch-transfer-v12) |
| - | - | - | - | - |
| **Functionality** | Initiate an amount transfer request | Initiate an amount transfer request | Initiate an amount transfer request directly to the beneficiary not added in your Payouts account (add beneficiary details in the API request) | Initiate amount transfer request to multiple beneficiaries |
| **Sync / Async** | Sync | Async | Async | Async |
| **UTR / Cashfree Reference ID** | Both UTR and Cashfree Reference ID | Cashfree Reference ID | Cashfree Reference ID | Cashfree Reference ID |
| **Required Body Params** | beneId \namount \ntransferId | beneId \namount \ntransferId | amount \ntransferId \ntransferMode \nbeneDetails | batchTransferId \nbatchFormat |
| **Default Transfer Mode** | Bank Transfer | Bank Transfer | Not Applicable | Not Applicable |
| **Available Transfer Modes** | Bank, UPI, Paytm, Amazon Pay | Bank, UPI, Paytm, Amazon Pay, Card | Bank, UPI, Paytm, Amazon Pay, Card, IMPS, NEFT | Bank, UPI, Paytm, Amazon Pay |
| **Response Time** | 9.77 s | 25.0 ms | 9.04 s | 182 ms |
| **Transactions Volume** | Low | High: up to 1000 transactions per minute | High: up to 1000 transactions per minute | High: up to 1000 transactions per minute |

**Transfers APIs**

The version 1.2 APIs include **paymentInstrumentId** as one of the body parameters. Find the list of transfer APIs below:

| API version 1.2 | API version 1 | Response time |
| :- | :- | :- |
| [Standard Transfer Sync V1.2](/docs/api-reference/payouts/v1/standard-transfer-sync-v12) | [Standard Transfer Sync](/docs/api-reference/payouts/v1/standard-transfer-sync) | 9.77 s |
| [Standard Transfer Async V1.2](/docs/api-reference/payouts/v1/standard-transfer-async-v12) | [Standard Transfer Async](/docs/api-reference/payouts/v1/standard-transfer-async) | 25.0 ms |
| [Direct Transfer V1.2](/docs/api-reference/payouts/v1/direct-transfer-v12) | [Direct Transfer](/docs/api-reference/payouts/v1/direct-transfer) | 9.04 s |
| [Get Transfer Status V1.2](/docs/api-reference/payouts/v1/get-transfer-status-v12) | [Get Transfer Status](/docs/api-reference/payouts/v1/get-transfer-status) | 244 ms |
| [Batch Transfer V1.2](/docs/api-reference/payouts/v1/batch-transfer-v12) | [Batch Transfer](/docs/api-reference/payouts/v1/batch-transfer) | 182 ms |
| [Get Batch Transfer Status V1.2](/docs/api-reference/payouts/v1/get-batch-transfer-status-v12) | [Get Batch Transfer Status](/docs/api-reference/payouts/v1/get-batch-transfer-status) | 6.19 ms |

***

## What does the response parameter 'acknowledged' mean?

The acknowledged parameter value conveys if the beneficiary received the funds by checking its value. Ack = 1 or 0. 1 denotes the beneficiary received funds, and 0 denotes the beneficiary had not received funds.

The cash flow happens as explained below:

1. `Debit`: The debit of the transfers happens on the remitter account. After a successful debit, the beneficiary bank does further processing. When only the debit is successful, Ack = 0.

2. Credit: The beneficiary bank credits the fund to the account. The transfer is sent from the remitter bank to the beneficiary bank after a successful debit. When the credit to the end beneficiary is successful, Ack = 1.

To confirm the status of a payout, you need to check the acknowledged parameter value. If the value is 1, you can mark the transfer as successful. However, if the value is 0, you must either wait for the TRANSFER\_ACKNOWLEDGED webhook event or use the [Get Transfer Status](/docs/api-reference/payouts/v1/get-transfer-status-v12) API and confirm the acknowledged value.

***


# Overview
Source: https://www.cashfree.com/docs/api-reference/payouts/v1/transfer-v12

Use the Payouts Transfers v1.2 API to disburse funds to beneficiaries through bank accounts, UPI, IMPS, NEFT, Paytm, and Amazon Pay wallets.

<Warning> These APIs will be retired soon. Please plan to migrate to the latest version, Transfers V2. </Warning>

You can perform the following tasks using the transfers API:

* Transfer money to your beneficiaries accounts through Sync, Async, Direct, and Batch APIs.
* Check the status of each transfer using the referenceId or transferId.

The flow diagram will help you understand the different transfer APIs and their use cases.

<Frame>
  <img />
</Frame>

Learn how each API functions using the following table and use the best-suited API for your transactions.

| | [Transfer sync](/docs/api-reference/payouts/v1/standard-transfer-sync-v12) | [Transfer async](/docs/api-reference/payouts/v1/standard-transfer-async-v12) | [Direct transfer](/docs/api-reference/payouts/v1/direct-transfer-v12) | [Batch transfer](/docs/api-reference/payouts/v1/batch-transfer-v12) |
| - | - | - | - | - |
| **Functionality** | Initiate an amount transfer request | Initiate an amount transfer request | Initiate an amount transfer request directly to the beneficiary not added in your Payouts account (add beneficiary details in the API request) | Initiate amount transfer request to multiple beneficiaries |
| **Sync / Async** | Sync | Async | Async | Async |
| **UTR / Cashfree Reference ID** | Both UTR and Cashfree Reference ID | Cashfree Reference ID | Cashfree Reference ID | Cashfree Reference ID |
| **Required Body Params** | beneId \namount \ntransferId | beneId \namount \ntransferId | amount \ntransferId \ntransferMode \nbeneDetails | batchTransferId \nbatchFormat |
| **Default Transfer Mode** | Bank Transfer | Bank Transfer | Not Applicable | Not Applicable |
| **Available Transfer Modes** | Bank, UPI, Paytm, Amazon Pay, | Bank, UPI, Paytm, Amazon Pay, Card | Bank, UPI, Paytm, Amazon Pay, Card, IMPS, NEFT | Bank, UPI, Paytm, Amazon Pay |
| **Response Time** | 9.77 s | 25.0 ms | 9.04 s | 182 ms |
| **Transactions Volume** | Low | High: up to 1000 transactions per minute | High: up to 1000 transactions per minute | High: up to 1000 transactions per minute |

**Transfers APIs**

The version 1.2 APIs include **paymentInstrumentId** as one of the body parameters. Find the list of transfer APIs below:

| API version 1.2 | API version 1 | Response time |
| :- | :- | :- |
| [Standard Transfer Sync V1.2](/docs/api-reference/payouts/v1/standard-transfer-sync-v12) | [Standard Transfer Sync](/docs/api-reference/payouts/v1/standard-transfer-sync) | 9.77 s |
| [Standard Transfer Async V1.2](/docs/api-reference/payouts/v1/standard-transfer-async-v12) | [Standard Transfer Async](/docs/api-reference/payouts/v1/standard-transfer-async) | 25.0 ms |
| [Direct Transfer V1.2](/docs/api-reference/payouts/v1/direct-transfer-v12) | [Direct Transfer](/docs/api-reference/payouts/v1/direct-transfer) | 9.04 s |
| [Get Transfer Status V1.2](/docs/api-reference/payouts/v1/get-transfer-status-v12) | [Get Transfer Status](/docs/api-reference/payouts/v1/get-transfer-status) | 244 ms |
| [Batch Transfer V1.2](/docs/api-reference/payouts/v1/batch-transfer-v12) | [Batch Transfer](/docs/api-reference/payouts/v1/batch-transfer) | 182 ms |
| [Get Batch Transfer Status V1.2](/docs/api-reference/payouts/v1/get-batch-transfer-status-v12) | [Get Batch Transfer Status](/docs/api-reference/payouts/v1/get-batch-transfer-status) | 6.19 ms |

***

## What does the response parameter 'acknowledged' mean?

The acknowledged parameter value conveys if the beneficiary received the funds by checking its value. Ack = 1 or 0. 1 denotes the beneficiary received funds, and 0 denotes the beneficiary had not received funds.

The cash flow happens as explained below:

1. Debit: The debit of the transfers happens on the remitter account. After a successful debit, the beneficiary bank does further processing. When only the debit is successful, Ack = 0.

2. Credit: The beneficiary bank credits the fund to the account. The transfer is sent from the remitter bank to the beneficiary bank after a successful debit. When the credit to the end beneficiary is successful, Ack = 1.

To confirm the status of a payout, you need to check the acknowledged parameter value. If the value is 1, you can mark the transfer as successful. However, if the value is 0, you must either wait for the TRANSFER\_ACKNOWLEDGED webhook event or use the [Get Transfer Status](/docs/api-reference/payouts/v1/get-transfer-status-v12) API and confirm the acknowledged value.


# Validate Payout V1
Source: https://www.cashfree.com/docs/api-reference/payouts/v1/validate-payout-v1

post /payout/v1/validatePayout
Validates a UPI VPA or phone number and returns a single-use transfer token valid for one hour. Pass this token to the [Process Validated Payout API](/api-reference/payouts/v1/verify-and-pay-direct-transfer-v1) to initiate the payout.

In the request body, pass the value for exactly one of `vpa` or `phone`, not both.

The response contains either basic or advanced VPA details. Advanced details include IFSC branch information. To enable advanced details for your account, contact your account manager or fill in the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod&raise_issue=1).




# Validate Payout V1.2
Source: https://www.cashfree.com/docs/api-reference/payouts/v1/validate-payout-v1-2

post /payout/v1.2/validatePayout
Validates either a Virtual Payment Address (VPA) on UPI or a phone number, and returns a single-use transfer token valid for one hour. Pass this token to the [Process Validated Payout API](/api-reference/payouts/v1/verify-and-pay-direct-transfer-v1-2) to initiate the payout.

In the request body, pass the value for exactly one of `vpa` or `phone`, not both.

The response contains either basic or advanced VPA details. Advanced details include Indian Financial System Code (IFSC) branch information. To enable advanced details for your account, contact your account manager or fill in the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod&raise_issue=1).




# Verify
Source: https://www.cashfree.com/docs/api-reference/payouts/v1/verify

post /payout/v1/verifyToke
Use this API to verify the bearer token generated. If the token does not exist/invalid/expired, the response "Token is not valid" is returned. Regenerate token in case of token expiry to make API calls (use /payout/v1/authorize for this).



# Verify
Source: https://www.cashfree.com/docs/api-reference/payouts/v1/verify-1

post /payout/v1/verifyToken
Verify the bearer token generated. If the token does not exist, is invalid, or has expired, the response "Token is not valid" is returned. Regenerate token in case of token expiry for making API calls ( use /payout/v1/authorize for this).

Please use this Authorization token in headers to call any payout API (Refresh this page if the token is expired)

<iframe />


# Direct Transfer
Source: https://www.cashfree.com/docs/api-reference/payouts/v1/verify-and-pay-direct-transfer-v1

post /payout/v1/directTransfer
Use this API to initiate amount transfers directly to the beneficiary account via a bank transfer or UPI. You can add the beneficiary details in the same API request.



# Direct Transfer V1.2
Source: https://www.cashfree.com/docs/api-reference/payouts/v1/verify-and-pay-direct-transfer-v1-2

post /payout/v1.2/directTransfer
Use this API to initiate amount transfers directly to the beneficiary account via a bank transfer or UPI. You can add the beneficiary details in the same API request.



# Webhooks
Source: https://www.cashfree.com/docs/api-reference/payouts/v1/webhooks

Configure Cashgram webhooks to receive real-time HTTP callbacks for redeemed, reversed, and expired events, and learn how Cashfree polls bank status updates.

Webhooks are events that notify you about the payment status. All Cashgram integrations should establish a webhook to listen for cashgram events, like status changes on payments. Webhooks are HTTP callbacks that receive notification messages for events.

Webhooks help you receive automatic updates and are significant for completing the integration with Cashfree. Webhooks are triggered with a request from your side, for example, when a transfer fails or when a daily report is available. Requests get processed both synchronously and asynchronously. In rare scenarios, for some payment methods, the outcome may take a longer duration to confirm. Cashfree notifies you once we get updates from the bank about the payment status.

Do not go live without signature verification if you are using webhooks.

## Webhook events

​Cashfree Cashgram API enables you to receive updates about all event-driven activities originating from your account. Below is the list of Cashgram webhooks:

**CASHGRAM\_REDEEMED**: Cashgram redeemed by the customer\
**CASHGRAM\_TRANSFER\_REVERSAL**: Cashgram transfer reversed by the bank\
**CASHGRAM\_EXPIRED**: Cashgram is inactive

Cashfree gets a response from the bank with the status of the transfer. At times the notifications may get delayed due to various reasons, and the transaction status will be marked as Pending, till Cashfree gets a response.

Cashfree polls the transaction status from the bank for the next 72 hours. In case we do not receive the status of a transaction after 72 hours, the transaction will be marked as Failed.

## CASHGRAM\_REDEEMED

Sent whenever a Cashgram is redeemed.

| Parameter | Description |
| :- | :- |
| event | It contains the name of the event which just occurred. Value = CASHGRAM\_REDEEMED |
| cashgramid | Id of the cashgram passed by the merchant |
| referenceId | Id of the transfer generated by Cashfree |
| eventTime | Transfer initiation time |
| utr | Unique transaction reference number provided by the bank |
| signature | A unique string which helps distinguish that the request is genuine and initiated by Cashfree. |

## CASHGRAM\_TRANSFER\_REVERSAL

Sent whenever the bank reverses a Cashgram.

| Parameter | Description |
| :- | :- |
| event | It contains the name of the event which just occurred. Value = CASHGRAM\_TRANSFER\_REVERSAL |
| cashgramid | Id of the cashgram passed by the merchant |
| referenceId | Id of the transfer generated by Cashfree |
| eventTime | Transfer initiation time |
| signature | A unique string which helps distinguish that the request is genuine and initiated by Cashfree. |

## CASHGRAM\_EXPIRED

Cashgram can become inactive for various reasons. An inactive Cashgram cannot be re-activated. You need to create a new Cashgram to send to your customer. A Cashgram gets reversed if one of the following events occurs:

1. **Redeeming post Expiry time**: If the customer does not redeem the Cashgram before the expiration time (set by the Merchant while creating the Cashgram), the Cashgram gets deactivated.

2. **Reaching the maximum number of retries**: A maximum of three attempts is allowed to redeem the Cashgram. If the customer enters incorrect details more than three times, the Cashgram gets deactivated.

3. **OTP verification attempts exceeded**: A maximum of three attempts is allowed to verify the OTP. If the customer fails to verify the OTP successfully, the Cashgram gets deactivated.

| Parameter | Description |
| :- | :- |
| event | It contains the name of the event which just occurred. Value = CASHGRAM\_EXPIRED |
| cashgramid | Id of the cashgram passed by the merchant |
| reason | Reason for reversal |
| signature | A unique string which helps distinguish that the request is genuine and initiated by Cashfree. |

## Signature verification

Cashfree sends a signature alongside every webhook, verifying this signature ( passed along with the POST parameters ) is mandatory before processing any response. It helps authenticate that the webhook is from Cashfree.

We strongly recommend whitelisting Cashfree's production IP to help make your communication with Cashfree more secure.

Following are the steps to verify Cashfree's signature:

1. Get all the POST parameters except ‘signature’ and assign it to an array as key-value pair
2. Sort the array based on keys
3. Concatenate all the values in this array and the resultant is the post data (say, postData)
4. **postData** needs to be encrypted using SHA-256, and then base64 encoded
5. Now verify if both the signature calculated and the signature received match
6. Proceed further if it matches, else discards the request

Cashfree's libraries also support signature verification. To verify the signature returned by Cashfree call the following methods from the library.

Below code snippets can help you verify Cashfree Signature:

<CodeGroup>
  ```php theme={"dark"}
  <?php
    $data = $_POST;
    $signature = $_POST["signature"];
    unset($data["signature"]); // $data now has all the POST parameters except signature
    ksort($data); // Sort the $data array based on keys
    $postData = "";
    foreach ($data as $key => $value){
      if (strlen($value) > 0) {
        $postData .= $value;
      }
    }
    $hash_hmac = hash_hmac('sha256', $postData, $clientSecret, true) ;
    
    // Use the clientSecret from the oldest active Key Pair.
    $computedSignature = base64_encode($hash_hmac);
    if ($signature == $computedSignature) {
      // Proceed based on $event
    } else {
      // Reject this call
    }
  ?>
  ```

  ```java theme={"dark"}
  import javax.crypto.spec.SecretKeySpec;
  import javax.crypto.Mac;
  import org.apache.commons.codec.binary.Base64;

  public class ComputedSignature {
    public static String generateHMAC(String clientSecret, String data) {
      String hash = null;
      try {
        String secret = clientSecret;
        String message = data;
        Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
        SecretKeySpec secret_key = new SecretKeySpec(secret.getBytes(),"HmacSHA256");
        sha256_HMAC.init(secret_key);
        hash = Base64.encodeBase64String(sha256_HMAC.doFinal(message.getBytes()));
      }
      catch (Exception e){
        //Log it
      }
      return hash;
    }
  }
  ```

  ```javascript Node theme={"dark"}
  const Cashfree = require("cashfree-sdk");
  //convert post response recived in the notification end point to json
  //and pass that to the SDK.
  Cashfree.Payouts.VerifySignature(webhookPostDataJson, signature, clientSecret);
  ```

  ```python theme={"dark"}
  from cashfree_sdk import verification

  #webhook_data = response.content
  webhook_data = '{"cashgramId": "5b8283182e0711eaa4c531df6a4f439b-28", "event": "CASHGRAM_EXPIRED", "eventTime": "2020-01-03 15:01:06", "reason": "OTP_ATTEMPTS_EXCEEDED", "signature": "TBpM+4nr1DsWsov7QiHSTfRJP4Z9BD8XrDgEhBlf9ss="}'
  verification.verify_webhook(webhook_data, 'JSON')
  ```
</CodeGroup>

## Webhook retries

Cashfree webhooks service does its best to deliver events to your webhook endpoint. It is best practice for your application to respond to the callback. Our webhook service may send many payloads to a single endpoint in quick succession. You will need to build an application and configure your server to receive the response we send when events get triggered during the process.

Your server should return a 200 HTTP status code to acknowledge that you received the webhook without any issues. Any other information you return in the request headers or request body gets ignored. Any response code outside the 200 range, including 3xx codes, indicates that you did not receive the webhook.

When Cashfree does not get the acknowledgement due to any reason, we retry to establish the communication at regular intervals. If we do not receive a response after a few attempts, we gradually decrease the rate of retries. Based on this count, the service is disabled if it fails more than five times.

If you are not receiving notifications from Cashfree as expected, please reach out to our support team by filling the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1).


# Add Beneficiary
Source: https://www.cashfree.com/docs/api-reference/payouts/v2/add-beneficiary

post /payout/v1/addBeneficiary
Use this API to add a beneficiary to your Cashfree account by providing the bank account number, IFSC, and other required details. Before you request a transfer, ensure the account has been successfully added as a beneficiary.



# Authorize
Source: https://www.cashfree.com/docs/api-reference/payouts/v2/authorize

post /payout/v1/authorize
Use this API to authenticate with the Cashfree system and obtain the authorization bearer token. All other API calls must have this token as Authorization header in the format 'Bearer <token>' (without quotes) for them to get processed.



# Batch Transfer
Source: https://www.cashfree.com/docs/api-reference/payouts/v2/batch-transfer

post /payout/v1/requestBatchTransfer
Use this API to create multiple transfers to multiple beneficiaries. This API accepts an array of transfer objects under the batch field.



# Batch Transfer V1.2
Source: https://www.cashfree.com/docs/api-reference/payouts/v2/batch-transfer-v12

post /payout/v1.2/requestBatchTransfer
Use this API to create transfers to multiple beneficiaries. This API accepts an array of transfer objects under the batch field.



# Create Beneficiary V2
Source: https://www.cashfree.com/docs/api-reference/payouts/v2/beneficiary-v2/create-beneficiary-v2

post /beneficiary
Use this API to add a beneficiary to your Cashfree account by providing the bank account number, IFSC, and other required details. Ensure the successful creation of the benficiary in your account before initiating a transfer.

<Note>
  Cashfree no longer support adding beneficiaries with Paytm UPI handles.
</Note>

<Accordion title="Click to view the response codes.">
  | HTTP status code | Error code | Message | Next action |
  | :- | :- | :- | :- |
  | 201 | - | - | - |
  | 400 | beneficiary\_id\_length\_exceeded | beneficiary\_id : should not be more than 50 characters long. value received: test\_bene\_id | Enter a valid beneficiary\_id. |
  | 400 | beneficiary\_id\_invalid | beneficiary\_id : should contain only letters, numbers, hyphen, underscore, pipe, and dot. Value received: .\qewqefwqev | Enter a valid beneficiary\_id. |
  | 400 | bank\_ifsc\_missing | bank\_ifsc : should be provided with the request if bank\_account\_number is provided | Provide a valid bank\_ifsc if bank\_account\_number is provided. |
  | 400 | bank\_account\_number\_missing | bank\_account\_number: should be provided with the request if bank\_ifsc is provided | Provide a valid bank\_account\_number is bank\_ifsc is provided. |
  | 400 | bank\_account\_number\_length\_exceeded | bank\_account\_number : should not be more than 25 characters long. value received: 235142352346523462456345263452345 | Provide a valid bank\_account\_number. |
  | 400 | bank\_account\_number\_length\_short | bank\_account\_number : should not be less than 4 characters long. value received: 12 | Provide a valid bank\_account\_number. |
  | 400 | bank\_account\_number\_invalid | bank\_account\_number : should be alphanumeric. value received: 123@ | Provide a valid bank\_account\_number. |
  | 400 | bank\_ifsc\_invalid | bank\_ifsc : please provide a valid IFSC. value received: SBIN00708410 | Provide a valid bank\_ifsc. |
  | 400 | beneficiary\_purpose\_invalid | beneficiary\_purpose : invalid value provided. Value received: paytm | Provide a valid beneficiary\_purpose. |
  | 409 | beneficiary\_id\_already\_exists | Beneficiary already exists with the given beneficiary\_id | Provide a beneficiary\_id that is not in use |
  | 409 | beneficiary\_already\_exists | Beneficiary already exists with the given bank\_account\_number and bank\_ifsc | Use the GET API to get the details of the existing beneficiary using bank\_account\_number and bank\_ifsc |
  | 422 | bank\_account\_number\_same\_as\_source | bank\_account\_number provided is the same as source bank account | Enter a bank\_account\_number that is different from the source bank account |
  | 422 | vba\_beneficiary\_not\_allowed | Virtual bank account as bank\_account\_number for the beneficiary is not allowed | Enter the actual bank\_account\_number instead of the virtual account number |
</Accordion>


# Get Beneficiary V2
Source: https://www.cashfree.com/docs/api-reference/payouts/v2/beneficiary-v2/get-beneficiary-v2

get /beneficiary
Use this API to get the details of a particular beneficiary from your account. You can pass either beneficiary_id or the combination of bank_account_number and bank_ifsc to fetch the details.

<Accordion title="Click to view the response codes.">
  | HTTP status code | Error code | Message | Next action |
  | :- | :- | :- | :- |
  | 200 | - | - | - |
  | 400 | too\_many\_parameters\_in\_request | Please provide either bank\_account\_number and bank\_ifsc together or beneficiary\_id alone. Do not include all three parameters in the request | Please provide either bank\_account\_number and bank\_ifsc together or beneficiary\_id alone. Do not include all three parameters in the request. |
  | 400 | bank\_ifsc\_missing | bank\_ifsc: should be provided with the request if bank\_account\_number is provided | Provide a valid bank\_ifsc if bank\_account\_number is provided. |
  | 400 | bank\_account\_number\_missing | bank\_account\_number: should be provided with the request if bank\_ifsc is provided | Provide a valid bank\_account\_number is bank\_ifsc is provided. |
  | 400 | beneficiary\_identifiers\_missing | beneficiary\_identifiers\_missing	beneficiary\_identifiers: Either beneficiary\_id or the combination of bank\_account\_number and bank\_ifsc has to be provided with the request | Please provide either beneficiary\_id or the combination of bank\_account\_number and bank\_ifsc. |
  | 400 | beneficiary\_id\_length\_exceeded | beneficiary\_id : should not be more than 50 characters long. value received: test\_bene\_id | Enter a valid beneficiary\_id |
  | 400 | beneficiary\_id\_invalid | beneficiary\_id : should contain only letters, numbers, hyphen, underscore, pipe, and dot. Value received: .\qewqefwqev | Enter a valid beneficiary\_id. |
  | 400 | bank\_account\_number\_length\_exceeded | bank\_account\_number : should not be more than 25 characters long. value received: 235142352346523462456345263452345 | Provide a valid bank\_account\_number. |
  | 400 | bank\_account\_number\_length\_short | bank\_account\_number : should not be less than 4 characters long. value received: 12 | Provide a valid bank\_account\_number. |
  | .400 | bank\_account\_number\_invalid | bank\_account\_number : should be alphanumeric. value received: 123@ | Provide a valid bank\_account\_number. |
  | 400 | bank\_ifsc\_invalid | bank\_ifsc : please provide a valid IFSC. value received: SBIN00708410 | Provide a valid bank\_ifsc. |
  | 404 | beneficiary\_not\_found | Beneficiary does not exist | Provide the details of an existing beneficiary. If such a beneficiary does not exist, use CREATE API to create a new beneficiary. |
  | 404 | beneficiary\_not\_found | Beneficiary with the given bank\_account\_number and bank\_ifsc does not exist | Provide the details of an existing beneficiary. If such a beneficiary does not exist, use CREATE API to create a new beneficiary |
  | 404 | beneficiary\_not\_found | Beneficiary exists with the given bank\_account\_number but a different bank\_ifsc | If the required a beneficiary does not exist, use CREATE API to create a new beneficiary |
</Accordion>


# Remove Beneficiary V2
Source: https://www.cashfree.com/docs/api-reference/payouts/v2/beneficiary-v2/remove-beneficiary-v2

delete /beneficiary
Use this API to remove an existing beneficiary from the list of added beneficiaries.

<Accordion title="Click to view the response codes.">
  | HTTP status code | Error code | Message | Next action |
  | :- | :- | :- | :- |
  | 201 | - | - | - |
  | 400 | beneficiary\_id\_invalid | beneficiary\_id : should contain only letters, numbers, hyphen, underscore, pipe, and dot. Value received: .\qewqefwqev | Enter a valid beneficiary\_id. |
  | 400 | beneficiary\_id\_length\_exceeded | beneficiary\_id : should not be more than 50 characters long. value received: test\_bene\_id | Enter a valid a beneficiary\_id |
  | 404 | beneficiary\_not\_found | Beneficiary does not exist | Provide the beneficiary\_id of an existing beneficiary |
</Accordion>


# CardPay
Source: https://www.cashfree.com/docs/api-reference/payouts/v2/cardpay

post /payout/v1/cardpay
Use this API to transfer money to beneficiary cards. Provide details such as beneficiary name, card type, network type, and transfer ID.

You need to pass the tokenised card number or card token for this transfer.



# Create Cashgram
Source: https://www.cashfree.com/docs/api-reference/payouts/v2/create-cashgram

post /payout/v1/createCashgram
Use this API to create a Cashgram.



# Deactivate Cashgram
Source: https://www.cashfree.com/docs/api-reference/payouts/v2/deactivate-cashgram

post /payout/v1/deactivateCashgram



# Direct Transfer
Source: https://www.cashfree.com/docs/api-reference/payouts/v2/direct-transfer

post /payout/v1/directTransfer
Use this API to initiate amount transfers directly to the beneficiary account via a bank transfer or UPI. You can add the beneficiary details in the same API request.



# Direct Transfer V1.2
Source: https://www.cashfree.com/docs/api-reference/payouts/v2/direct-transfer-v12

post /payout/v1.2/directTransfer
Use this API to initiate amount transfers directly to the beneficiary account via a bank transfer or UPI. You can add the beneficiary details in the same API request.



# Get Balance
Source: https://www.cashfree.com/docs/api-reference/payouts/v2/get-balance

get /payout/v1/getBalance
Use this API to get the ledger balance and available balance of your account. Available balance is ledger balance minus the sum of all pending transfers (transfers triggered and processing or pending now).



# Get Balance V1.2
Source: https://www.cashfree.com/docs/api-reference/payouts/v2/get-balance-v12

get /payout/v1.2/getBalance
Use this API to get the ledger balance and available balance of your account. Available balance is ledger balance minus the sum of all pending transfers (transfers triggered and processing or pending now).



# Get Batch Transfer Status - WIP
Source: https://www.cashfree.com/docs/api-reference/payouts/v2/get-batch-transfer-status--wip

get /payout/v1/getBatchTransferStatus-wip
Use this API to get the status of the Batch Transfer.



# Get Batch Transfer Status V1.2
Source: https://www.cashfree.com/docs/api-reference/payouts/v2/get-batch-transfer-status-v12

get /payout/v1.2/getBatchTransferStatus
Use this API to get the status of the Batch Transfer.



# Get Beneficiary Details
Source: https://www.cashfree.com/docs/api-reference/payouts/v2/get-beneficiary-details

get /payout/v1/getBeneficiary/{beneId}
Use this API to get the details of a particular beneficiary in your account.



# Get Beneficiary History
Source: https://www.cashfree.com/docs/api-reference/payouts/v2/get-beneficiary-history

get /payout/v1/beneHistory
Use this API to fetch the transaction history for a particular beneficiary and for a desired period of time.



# Get Beneficiary ID
Source: https://www.cashfree.com/docs/api-reference/payouts/v2/get-beneficiary-id

get /payout/v1/getBeneId
Use this API to get the beneficiary ID by providing the bank account number and ifsc.



# Get Cashgram Status
Source: https://www.cashfree.com/docs/api-reference/payouts/v2/get-cashgram-status

get /payout/v1/getCashgramStatus
Use this API to get the status of the Cashgram created.



# Get Incidents
Source: https://www.cashfree.com/docs/api-reference/payouts/v2/get-incidents

get /payout/v1/incidents
Use this API to get the list of incidents on banks(Resolved,Unresolved,All) for a given time range.



# Get Transfer Status
Source: https://www.cashfree.com/docs/api-reference/payouts/v2/get-transfer-status

get /payout/v1.1/getTransferStatus
Use these details to get details of a particular transfer. You can pass referenceId or transferId to fetch the details.



# Get Transfer Status V1.2
Source: https://www.cashfree.com/docs/api-reference/payouts/v2/get-transfer-status-v12

get /payout/v1.2/getTransferStatus
Use these details to get details of a particular transfer. You can pass referenceId or transferId to fetch the details.



# Internal Transfer
Source: https://www.cashfree.com/docs/api-reference/payouts/v2/internal-transfer

post /payout/v1/internalTransfer
Use this API to request an internal transfer at Cashfree. The internal transfer API is useful for multiple Payouts accounts. The API response will either result in an ERROR or SUCCESS response.



# Internal Transfer V1.2
Source: https://www.cashfree.com/docs/api-reference/payouts/v2/internal-transfer-v12

post /payout/v1.2/internalTransfer
Use this API to request an internal transfer. It is useful for accounts with multiple fund sources. You need to provide either the rechargeAccount or paymentInstrumentId and toPaymentInstrumentId along with the amount.



# Lend
Source: https://www.cashfree.com/docs/api-reference/payouts/v2/lend

post /payout/v1/lend
Use this API to send requests for loan disbursement to the beneficiary. The service charges are pooled for the respective party and disbursed at the end of day. Disbursement amount = (Amount - total service charges).



# Overview
Source: https://www.cashfree.com/docs/api-reference/payouts/v2/overview

Use Cashfree Payouts v2 APIs to disburse funds to bank accounts, UPI IDs, cards, and wallets with enhanced beneficiary management and transfer modes.

**You can perform the following tasks using the Payouts API:**

* Add and manage your beneficiaries efficiently
* Transfer money to your beneficiaries' accounts using different transfer methods
* Track the transfer status
* Check the ledger and available balance instantly

## Beneficiary APIs

| API name | Description |
| :- | :- |
| [Add Beneficiary](/docs/api-reference/payouts/v1/add-beneficiary) | Add a beneficiary to your Payouts account. |
| [Retrieve Beneficiary Details](/docs/api-reference/payouts/v1/get-beneficiary-details) | Retrieve a beneficiary's details. |
| [Find Beneficiary ID](/docs/api-reference/payouts/v1/get-beneficiary-id) | Find the ID of a specific beneficiary. |
| [Remove Beneficiary](/docs/api-reference/payouts/v1/remove-beneficiary) | Remove a beneficiary from your Payouts account. |
| [Retrieve Beneficiary Transfers](/docs/api-reference/payouts/v1/get-beneficiary-history) | Retrieve transfer data of a specific beneficiary. |

## Account APIs

| API name | Description |
| :- | :- |
| [View Balance](/docs/api-reference/payouts/v1/get-balance) | View the ledger and available balance of your account. |
| [View Balance V1.2](/docs/api-reference/payouts/v1/get-balance-v12) | Version 1.2 allows you to specify the payment instrument Id. |
| [Self Withdrawal](/docs/api-reference/payouts/v1/self-withdrawal) | Request a self-withdrawal from your Payouts account. |
| [Internal Transfer](/docs/api-reference/payouts/v1/internal-transfer) | Request an internal transfer between your Payouts accounts. |

## Transfers APIs

| API version 1.2 | API version 1 | Description | Transactions per minute (TPM) | Response time |
| :- | :- | :- | :- | :- |
| [Standard Transfer Sync V1.2](/docs/api-reference/payouts/v1/standard-transfer-sync-v12) | [Standard Transfer Sync](/docs/api-reference/payouts/v1/standard-transfer-sync) | Initiate a sync transfer request | N/A | 9.77 s |
| [Standard Transfer Async V1.2](/docs/api-reference/payouts/v1/standard-transfer-async-v12) | [Standard Transfer Async](/docs/api-reference/payouts/v1/standard-transfer-async) | Initiate an async transfer request | 1000 | 25.0 ms |
| [Direct Transfer V1.2](/docs/api-reference/payouts/v1/direct-transfer-v12) | [Direct Transfer](/docs/api-reference/payouts/v1/direct-transfer) | Initiate an amount transfer request directly to the beneficiary not in the database. | 1000 | 9.04 s |
| [Get Transfer Status V1.2](/docs/api-reference/payouts/v1/get-transfer-status-v12) | [Get Transfer Status](/docs/api-reference/payouts/v1/get-transfer-status) | Get the status of the transfer request. | - | 244 ms |
| [Batch Transfer V1.2](/docs/api-reference/payouts/v1/batch-transfer-v12) | [Batch Transfer](/docs/api-reference/payouts/v1/batch-transfer) | Initiate a transfer request to multiple beneficiaries. | 1000 | 182 ms |
| [Get Batch Transfer Status V1.2](/docs/api-reference/payouts/v1/get-transfer-status-v12) | [Get Batch Transfer Status](/docs/api-reference/payouts/v1/get-transfer-status) | Get the status of the batch transfer request. | - | 6.19 ms |
| [Validate Payout V1.2](/docs/api-reference/payouts/v1/validate-payout-v1-2) | [Validate Payout V1](/docs/api-reference/payouts/v1/validate-payout-v1) | Validates a UPI VPA or phone number and returns a single-use transfer token. | - | - |
| [Process Validated Payout V1.2](/docs/api-reference/payouts/v1/verify-and-pay-direct-transfer-v1-2) | [Process Validated Payout V1](/docs/api-reference/payouts/v1/verify-and-pay-direct-transfer-v1) | Initiates a payout using the transfer token from the corresponding Validate Payout API. | - | - |

## Version 2 APIs

### Beneficiary V2

| API | Description |
| :- | :- |
| [Create Beneficiary](/docs/api-reference/payouts/v2/beneficiary-v2/create-beneficiary-v2) | Use this API to add a beneficiary to your Cashfree account by providing the bank account number, IFSC, and other required details. |
| [Get Beneficiary](/docs/api-reference/payouts/v2/beneficiary-v2/get-beneficiary-v2) | Use this API to get the details of a particular beneficiary from your account. |
| [Remove Beneficiary](/docs/api-reference/payouts/v2/beneficiary-v2/remove-beneficiary-v2) | Use this API to remove an existing beneficiary from the list of added beneficiaries. |

### Transfers V2

| API | Description |
| :- | :- |
| [Standard Transfer V2](/docs/api-reference/payouts/v2/transfers-v2/standard-transfer-v2) | Use this API to initiate an amount transfer at Cashfree. It's an async request by default. |
| [Get Transfer Status V2](/docs/api-reference/payouts/v2/transfers-v2/get-transfer-status-v2) | Use this API to get the status of the initiated transfer. |
| [Batch Transfer V2](/docs/api-reference/payouts/v2/transfers-v2/batch-transfer-v2) | Use this API to initiate a batch transfer request at Cashfree. You can transfer money to multiple beneficiaries. |
| [Get Batch Transfer Status V2](/docs/api-reference/payouts/v2/transfers-v2/get-batch-transfer-status-v2) | Use this API to get the status of the initiated batch transfer. |

### Verify and pay

| API | Description |
| :- | :- |
| [Validate Payout V2](/docs/api-reference/payouts/v2/validate-payout-v2) | Validates a UPI VPA or phone number and returns a single-use transfer token for the Process Validated Payout call. |
| [Process Validated Payout V2](/docs/api-reference/payouts/v2/verify-and-pay-transfers-v2) | Initiates a UPI payout using the transfer token from Validate Payout V2. |

***

## Payouts - Postman Collection

This collection can save you time because of easy access to different requests.

<a href="https://gocashassets.s3.ap-south-1.amazonaws.com/repostmancollection/Cashfree_Payouts_Collection.json.zip">
  Download Cashfree Payouts Postman Collection
</a>


# Overview
Source: https://www.cashfree.com/docs/api-reference/payouts/v2/payouts-api-v2-new

Learn the benefits of upgrading to Cashfree Payouts v2 APIs, including the unified transfers endpoint, richer beneficiary management, and v1 to v2 migration.

Payouts version 2 (v2) represents the next generation of our payout integration capabilities. These APIs are designed to provide a more streamlined, standardised, and developer-friendly experience for businesses looking to automate their payout processes.

## Benefits

This update delivers several key improvements over the previous version to enhance your integration experience.

* **Enhanced versioning**:

  Experience seamless incorporation of future breaking and non-breaking changes on existing endpoints. This strategy provides a better balance between innovation and stability.

* **Standardised API request and response**:

  Parameters follow a consistent standard for clarity, simplifying the integration process and making it easier to manage your workflows.

* **Standardised error codes**:

  Uniform error codes provide quick diagnosis of issues and clear resolution steps, reducing the need for support tickets.

* **Platform-wide standardisation**:

  Consistent standards across all Cashfree services facilitate easier onboarding and familiarity with our various products.

* **Consolidated transfer APIs**:

  Streamlined operations simplify selecting the correct API for your use case, reducing integration complexity and potential issues.

## End points

Use the following base URLs to access the Payouts version 2 APIs in different environments.

| Environment | Base URL |
| :- | :- |
| Production | [https://api.cashfree.com/payout](https://api.cashfree.com/payout) |
| Test | [https://sandbox.cashfree.com/payout](https://sandbox.cashfree.com/payout) |

## Available APIs

The following tables list the available API endpoints for beneficiary management and transfers.

### Beneficiary management

Use these APIs to manage beneficiaries in your Cashfree account.

| API | Description |
| :- | :- |
| [Create Beneficiary](/docs/api-reference/payouts/v2/beneficiary-v2/create-beneficiary-v2) | Use this API to add a beneficiary to your Cashfree account by providing the bank account number, IFSC, and other required details. |
| [Get Beneficiary](/docs/api-reference/payouts/v2/beneficiary-v2/get-beneficiary-v2) | Use this API to retrieve the details of a particular beneficiary from your account. |
| [Remove Beneficiary](/docs/api-reference/payouts/v2/beneficiary-v2/remove-beneficiary-v2) | Use this API to remove an existing beneficiary from the list of added beneficiaries. |

### Transfers

Use these APIs to initiate and track money transfers to your beneficiaries.

| API | Description |
| :- | :- |
| [Standard Transfer](/docs/api-reference/payouts/v2/transfers-v2/standard-transfer-v2) | Use this API to initiate an amount transfer at Cashfree. This is an asynchronous request by default. |
| [Get Transfer Status](/docs/api-reference/payouts/v2/transfers-v2/get-transfer-status-v2) | Use this API to retrieve the status of an initiated transfer. |
| [Batch Transfer](/docs/api-reference/payouts/v2/transfers-v2/batch-transfer-v2) | Use this API to initiate a batch transfer request at Cashfree. You can transfer money to multiple beneficiaries. |
| [Get Batch Transfer Status](/docs/api-reference/payouts/v2/transfers-v2/get-batch-transfer-status-v2) | Use this API to retrieve the status of an initiated batch transfer. |

### Verify and pay

Use these APIs for the Verify and Pay UPI flow: validate the beneficiary, then initiate the payout with the returned transfer token.

| API | Description |
| :- | :- |
| [Validate Payout](/docs/api-reference/payouts/v2/validate-payout-v2) | Validates a UPI VPA or phone number and returns a single-use transfer token for the Process Validated Payout call. |
| [Process Validated Payout](/docs/api-reference/payouts/v2/verify-and-pay-transfers-v2) | Initiates a UPI payout using the transfer token from Validate Payout. |

<Warning>
  When you receive a 5XX response, do not initiate another transaction. Check the status of the standard transfer using **Get Transfer Status**, or check the status of the batch transfer using **Get Batch Transfer Status** before proceeding.
</Warning>


# API Rate Limits
Source: https://www.cashfree.com/docs/api-reference/payouts/v2/payouts-rate-limiting

Learn the per-minute and per-day rate limits Cashfree applies to each Payouts API so you can plan retries, batch requests, and avoid throttling errors.

To maintain service reliability, protect against abuse, and ensure a consistent quality of service for all users interacting with the Payouts APIs, we have devised the following rate limits.

## 9000 TPM

| API |
| :- |
| [Standard Transfer Async](/docs/api-reference/payouts/v1/standard-transfer-async) |

## 7800 TPM

| API |
| :- |
| [Get Transfer Status](/docs/api-reference/payouts/v1/get-transfer-status) |

## 3500 TPM

| API |
| :- |
| [Create Cashgram](/docs/api-reference/payouts/v1/create-cashgram) |

## 3000 TPM

| API |
| :- |
| [Get Balance](/docs/api-reference/payouts/v1/get-balance) |
| [Authorize](/docs/api-reference/payouts/v1/authorize) |
| [Verify](/docs/api-reference/payouts/v1/verify-1) |
| [Direct Transfer](/docs/api-reference/payouts/v1/direct-transfer) |

## 2000 TPM

| API |
| :- |
| [Get payout-transfers-v2](/docs/api-reference/payouts/v2/transfers-v2/get-transfer-status-v2) |
| [Standard Transfer V2](/docs/api-reference/payouts/v2/transfers-v2/standard-transfer-v2) |
| [Get Batch Transfer Status V2](/docs/api-reference/payouts/v2/transfers-v2/get-batch-transfer-status-v2) |
| [Batch Transfer V2](/docs/api-reference/payouts/v2/transfers-v2/batch-transfer-v2) |
| [Get Beneficiary V2](/docs/api-reference/payouts/v2/beneficiary-v2/get-beneficiary-v2) |
| [Create Beneficiary V2](/docs/api-reference/payouts/v2/beneficiary-v2/create-beneficiary-v2) |
| [Remove Beneficiary V2](/docs/api-reference/payouts/v2/beneficiary-v2/remove-beneficiary-v2) |
| [Get Cashgram Status](/docs/api-reference/payouts/v1/get-cashgram-status) |

## 1200 TPM

| API |
| :- |
| [Standard Transfer Sync v1.2](/docs/api-reference/payouts/v1/standard-transfer-async-v12) |
| [Direct Transfer V1.2](/docs/api-reference/payouts/v1/direct-transfer-v12) |

## 900 TPM

| API |
| :- |
| [Add Beneficiary](/docs/api-reference/payouts/v1/add-beneficiary) |
| [Get Beneficiary ID](/docs/api-reference/payouts/v1/get-beneficiary-id) |
| [Remove Beneficiary](/docs/api-reference/payouts/v1/remove-beneficiary) |
| [Get Beneficiary Details](/docs/api-reference/payouts/v1/get-beneficiary-details) |

## 500 TPM

| API |
| :- |
| [Get Batch Transfer Status](/docs/api-reference/payouts/v1/get-batch-transfer-status) |
| [Batch Transfer](/docs/api-reference/payouts/v1/batch-transfer) |

## 100 TPM

| API |
| :- |
| [Internal Transfer](/docs/api-reference/payouts/v1/internal-transfer) |
| [Self Withdrawal](/docs/api-reference/payouts/v1/self-withdrawal) |
| [Get Balance V1.2](/docs/api-reference/payouts/v1/get-balance-v12) |
| [Internal Transfer V1.2](/docs/api-reference/payouts/v1/internal-transfer-v12) |
| [Get Batch Transfer Status V1.2](/docs/api-reference/payouts/v1/get-batch-transfer-status-v12) |
| [Standard Transfer Async v1.2](/docs/api-reference/payouts/v1/standard-transfer-async-v12) |
| [Batch Transfer V1.2](/docs/api-reference/payouts/v1/batch-transfer-v12) |
| [Get Transfer Status V1.2](/docs/api-reference/payouts/v1/get-transfer-status-v12) |
| [Create Virtual Account](/docs/api-reference/payouts/v1/oneescrow/create-virtual-account) |
| [Transfer Funds Between VAs](/docs/api-reference/payouts/v1/oneescrow/transfer-funds-between-vas) |
| [Get Account Statement](/docs/api-reference/payouts/v1/oneescrow/get-account-statement) |
| [Allocate Funds to Virtual Account](/docs/api-reference/payouts/v1/oneescrow/recharge-oneescrow-account) |
| [Get Fund Source Details](/docs/api-reference/payouts/v1/oneescrow/get-fund-source-details) |
| [Add Registered Recharge Account](/docs/api-reference/payouts/v1/oneescrow/add-registered-recharge-accountwhitelist-bank-account) |
| [Debit Connected Wallet](/docs/api-reference/payouts/v1/oneescrow/debit-connected-wallet) |
| [CardPay](/docs/api-reference/payouts/v1/cardpay) |
| [Lend](/docs/api-reference/payouts/v1/lend) |
| [Get Beneficiary History](/docs/api-reference/payouts/v1/get-beneficiary-history) |
| [Get Incidents](/docs/api-reference/payouts/v1/get-incidents) |
| [Deactivate Cashgram](/docs/api-reference/payouts/v1/deactivate-cashgram) |
| [Get Batch Transfer Status V1.3](/docs/api-reference/payouts/v1/get-batch-transfer-status-1) |


# Remove Beneficiary
Source: https://www.cashfree.com/docs/api-reference/payouts/v2/remove-beneficiary

post /payout/v1/removeBeneficiary
Use this API to remove an existing beneficiary from a list of added beneficiaries.



# Response Codes
Source: https://www.cashfree.com/docs/api-reference/payouts/v2/response-codes

Look up Cashfree Payouts v2 response codes for beneficiary and transfer APIs, with HTTP status, error subcodes, sample messages, and recommended next actions.

## Beneficiary V2

### Create Beneficiary V2

<Accordion title="Click to view the response codes.">
  | HTTP status code | Error code | Message | Next action |
  | :- | :- | :- | :- |
  | 201 | - | - | - |
  | 400 | beneficiary\_id\_length\_exceeded | beneficiary\_id : should not be more than 50 characters long. value received: test\_bene\_id | Enter a valid beneficiary\_id. |
  | 400 | beneficiary\_id\_invalid | beneficiary\_id : should contain only letters, numbers, hyphen, underscore, pipe, and dot. Value received: .\qewqefwqev | Enter a valid beneficiary\_id. |
  | 400 | bank\_ifsc\_missing | bank\_ifsc : should be provided with the request if bank\_account\_number is provided | Provide a valid bank\_ifsc if bank\_account\_number is provided. |
  | 400 | bank\_account\_number\_missing | bank\_account\_number: should be provided with the request if bank\_ifsc is provided | Provide a valid bank\_account\_number is bank\_ifsc is provided. |
  | 400 | bank\_account\_number\_length\_exceeded | bank\_account\_number : should not be more than 25 characters long. value received: 235142352346523462456345263452345 | Provide a valid bank\_account\_number. |
  | 400 | bank\_account\_number\_length\_short | bank\_account\_number : should not be less than 4 characters long. value received: 12 | Provide a valid bank\_account\_number. |
  | 400 | bank\_account\_number\_invalid | bank\_account\_number : should be alphanumeric. value received: 123@ | Provide a valid bank\_account\_number. |
  | 400 | bank\_ifsc\_invalid | bank\_ifsc : please provide a valid IFSC. value received: SBIN00708410 | Provide a valid bank\_ifsc. |
  | 400 | beneficiary\_purpose\_invalid | beneficiary\_purpose : invalid value provided. Value received: paytm | Provide a valid beneficiary\_purpose. |
  | 409 | beneficiary\_id\_already\_exists | Beneficiary already exists with the given beneficiary\_id | Provide a beneficiary\_id that is not in use |
  | 409 | beneficiary\_already\_exists | Beneficiary already exists with the given bank\_account\_number and bank\_ifsc | Use the GET API to get the details of the existing beneficiary using bank\_account\_number and bank\_ifsc |
  | 422 | bank\_account\_number\_same\_as\_source | bank\_account\_number provided is the same as source bank account | Enter a bank\_account\_number that is different from the source bank account |
  | 422 | vba\_beneficiary\_not\_allowed | Virtual bank account as bank\_account\_number for the beneficiary is not allowed | Enter the actual bank\_account\_number instead of the virtual account number |
</Accordion>

### Get Beneficiary V2

<Accordion title="Click to view the response codes.">
  | HTTP status code | Error code | Message | Next action |
  | :- | :- | :- | :- |
  | 200 | - | - | - |
  | 400 | too\_many\_parameters\_in\_request | Please provide either bank\_account\_number and bank\_ifsc together or beneficiary\_id alone. Do not include all three parameters in the request | Please provide either bank\_account\_number and bank\_ifsc together or beneficiary\_id alone. Do not include all three parameters in the request. |
  | 400 | bank\_ifsc\_missing | bank\_ifsc: should be provided with the request if bank\_account\_number is provided | Provide a valid bank\_ifsc if bank\_account\_number is provided. |
  | 400 | bank\_account\_number\_missing | bank\_account\_number: should be provided with the request if bank\_ifsc is provided | Provide a valid bank\_account\_number is bank\_ifsc is provided. |
  | 400 | beneficiary\_identifiers\_missing | beneficiary\_identifiers\_missing	beneficiary\_identifiers: Either beneficiary\_id or the combination of bank\_account\_number and bank\_ifsc has to be provided with the request | Please provide either beneficiary\_id or the combination of bank\_account\_number and bank\_ifsc. |
  | 400 | beneficiary\_id\_length\_exceeded | beneficiary\_id : should not be more than 50 characters long. value received: test\_bene\_id | Enter a valid beneficiary\_id |
  | 400 | beneficiary\_id\_invalid | beneficiary\_id : should contain only letters, numbers, hyphen, underscore, pipe, and dot. Value received: .\qewqefwqev | Enter a valid beneficiary\_id. |
  | 400 | bank\_account\_number\_length\_exceeded | bank\_account\_number : should not be more than 25 characters long. value received: 235142352346523462456345263452345 | Provide a valid bank\_account\_number. |
  | 400 | bank\_account\_number\_length\_short | bank\_account\_number : should not be less than 4 characters long. value received: 12 | Provide a valid bank\_account\_number. |
  | .400 | bank\_account\_number\_invalid | bank\_account\_number : should be alphanumeric. value received: 123@ | Provide a valid bank\_account\_number. |
  | 400 | bank\_ifsc\_invalid | bank\_ifsc : please provide a valid IFSC. value received: SBIN00708410 | Provide a valid bank\_ifsc. |
  | 404 | beneficiary\_not\_found | Beneficiary does not exist | Provide the details of an existing beneficiary. If such a beneficiary does not exist, use CREATE API to create a new beneficiary. |
  | 404 | beneficiary\_not\_found | Beneficiary with the given bank\_account\_number and bank\_ifsc does not exist | Provide the details of an existing beneficiary. If such a beneficiary does not exist, use CREATE API to create a new beneficiary |
  | 404 | beneficiary\_not\_found | Beneficiary exists with the given bank\_account\_number but a different bank\_ifsc | If the required a beneficiary does not exist, use CREATE API to create a new beneficiary |
</Accordion>

### Remove Beneficiary

<Accordion title="Click to view the response codes.">
  | HTTP status code | Error code | Message | Next action |
  | :- | :- | :- | :- |
  | 201 | - | - | - |
  | 400 | beneficiary\_id\_invalid | beneficiary\_id : should contain only letters, numbers, hyphen, underscore, pipe, and dot. Value received: .\qewqefwqev | Enter a valid beneficiary\_id. |
  | 400 | beneficiary\_id\_length\_exceeded | beneficiary\_id : should not be more than 50 characters long. value received: test\_bene\_id | Enter a valid a beneficiary\_id |
  | 404 | beneficiary\_not\_found | Beneficiary does not exist | Provide the beneficiary\_id of an existing beneficiary |
</Accordion>

## Transfer V2

### Standard Transfer V2

<Accordion title="Click to view the response codes.">
  | HTTP status code | Status | Status code | Status description | Next action | Try again via Cashfree |
  | :- | :- | :- | :- | :- | :- |
  | 200 | APPROVAL\_PENDING | VELOCITY\_CHECK\_FAILED | The transfer requires an approval as the count of transfers to a particular beneficiary etc have breached the limit. You can approve or reject the transfer request from the Cashfree [Merchant Dashboard](https://merchant.cashfree.com/auth/login). | You can approve/reject the transfer on the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and go to **Transfers > Approve**. Post the transfer is approved, the request is sent to the partner bank for further processing. | - |
  | 200 | APPROVAL\_PENDING | TRANSFER\_LIMIT\_BREACH | The transfer requires an approval as the transfer amount etc have breached the limit. You can approve or reject the transfer request from the Cashfree [Merchant Dashboard](https://merchant.cashfree.com/auth/login). | You can approve/reject the transfer on the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and go to **Transfers > Approve**. Post the transfer is approved, the request is sent to the partner bank for further processing. | - |
  | 200 | APPOVAL\_PENDING | APPROVAL\_PENDING | The transfer requires approval. You can approve or reject the transfer request from the Cashfree [Merchant Dashboard](https://merchant.cashfree.com/auth/login). | You can approve/reject the transfer on the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and go to **Transfers > Approve**. Post the transfer is approved, the request is sent to the partner bank for further processing. | - |
  | 200 | FAILED | WAIT\_TIME\_EXCEEDED | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree to reattempt with the partner bank(s). | Yes |
  | 200 | FAILED | BENE\_BANK\_DECLINED | The transfer has failed because the beneficiary bank has declined the transfer. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again with the partner bank(s). | - | Yes |
  | 200 | FAILED | IMPS\_MODE\_FAIL | The transfer has failed because the beneficiary account doesnot support IMPS transfers. This rejection is done by the partner bank for the specific beneficiary account. You can try NEFT or other channels to do the disbursals. | You can try NEFT or other channels to do the disbursals. | Yes, via a different mode. |
  | 200 | FAILED | SOURCE\_BANK\_DECLINED | The transfer has failed because our partner bank has declined the transfer because of their internal checks, technical declines etc. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again with other partner bank(s). | Yes |
  | 200 | FAILED | CONNECTION\_TIMEOUT | The transfer has failed because there was a connection timeout between the bank and Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again with the partner bank(s). | Yes |
  | 200 | FAILED | PAYOUT\_INTERNAL\_ERROR | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | - | Yes |
  | 200 | FAILED | NPCI\_UNAVAILABLE | The transfer has failed because NPCI was unavailable to complete the transfer request. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree. The success of the request is contingent on NPCI services being up. | - | Yes, after some time. |
  | 200 | FAILED | DEST\_LIMIT\_REACHED | The transfer has failed because the beneficiary account has breached the limit of receiving funds. This rejection is done by the beneficiary bank for the specific beneficiary account. You can reinitiate the transfer after a while via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). The success of the request is contingent on beneficiary's limit being available to receive incoming funds. | - | Yes, after some time. |
  | 200 | FAILED | RETURNED\_FROM\_BENEFICIARY | The transfer has failed because the beneficiary bank has returned the transfer and has not need able to credit funds to the end beneficiary. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again with the partner bank(s). | - | - |
  | 200 | FAILED | PAYOUT\_INTERNAL\_ERROR | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | - | - |
  | 200 | FAILED | INVALID\_BENE\_ACCOUNT\_OR\_IFSC | The transfer has failed because the beneficiary account or IFSC is invalid. After correcting the beneficiary account or IFSC, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | - | - |
  | 200 | FAILED | PAYOUT\_INTERNAL\_ERROR | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | - | - |
  | 200 | FAILED | FAILED | The transfer has failed because there was an intermittent issue at the partner bank's end. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after some time. |
  | 200 | FAILED | PAYOUT\_INTERNAL\_ERROR | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | - | - |
  | 200 | FAILED | INSUFFICIENT\_BALANCE | The transfer has failed because of low balance in your Cashfree Wallet/ Bank Account. After recharging the account, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After recharging the account, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after recharging. |
  | 200 | FAILED | INVALID\_BENE\_VPA | The transfer has failed because the beneficiary VPA is invalid. After correcting the VPA handle, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the VPA handle, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting VPA handle. |
  | 200 | FAILED | INVALID\_IFSC\_FAIL | The transfer has failed because the IFSC is invalid. After correcting the IFSC, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the IFSC, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting IFSC. |
  | 200 | FAILED | BAD\_GATEWAY | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | FAILED | INVALID\_AMOUNT\_FAIL | The transfer has failed because the amount entered is invalid. After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting amount |
  | 200 | FAILED | INVALID\_ACCOUNT\_FAIL | The transfer has failed because the Account Number of the beneficiary is invalid, as per our partner bank. After correcting the account number, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the account number, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting account number |
  | 200 | FAILED | INVALID\_REQUEST | The transfer has failed because the transfer request is invalid, as per our partner bank, because of exceeding the character limit of certain parameter, wrong input etc. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | - | - |
  | 200 | FAILED | ACCOUNT\_BLOCKED | The transfer has failed because the account is blocked, as per our partner bank. After getting the account unblocked, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After getting the account unblocked, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after unblocking the account number |
  | 200 | FAILED | DEBIT\_FAILURE | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | FAILED | BENEFICIARY\_BANK\_OFFLINE | The transfer has failed because the respective beneficiary bank is offline. After some time, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After some time, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after some time |
  | 200 | FAILED | AUTHENTICATION\_FAILURE | The transfer has failed because there was an authentication failure at the partner bank's end. After checking with the partner bank, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | This is a scenario when the API access is not working at the partner bank's end. After checking with the partner bank, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | FAILED | NRE\_ACCOUNT\_FAIL | The transfer has failed because the beneficiary account is an NRE Account and transfers to NRE Accounts are not supported, as per our partner bank. | Get a new account(non-NRE account) from the beneficiary; you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | FAILED | SOURCE\_LIMIT\_REACHED | The transfer has been failed by the partner bank as the source bank account has reached a limit of transferring funds. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | If you are on Cashfree Wallet, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). If you are on Connected Bank, you need to recharge your bank account and then reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after some time |
  | 200 | FAILED | BANK\_GATEWAY\_ERROR | The transfer has failed because there was an intermittent issue at the partner bank's end. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | FAILED | BAD\_REQUEST | The transfer has failed because the details of the transfer request is invalid, as per our partner bank. After correcting the details in the transfer request, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the details in the transfer request, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | FAILED | REINITIALIZE\_TRANSFER\_LATER | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | MANUALLY\_REJECTED | MANUALLY\_REJECTED | The transfer has failed because it has been manually rejected by the merchant or any team member user who has the permissions to do the same on [Merchant Dashboard](https://merchant.cashfree.com/merchants). You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again with the partner bank(s). | If the merchant wants to reinitiate the transfer, they can reinitiate the transfer via Cashfree so that the transfer can be reattempted again with the partner bank(s). | Yes,  if you want to reinitiate the transfer |
  | 200 | PENDING | SENT\_TO\_BANK | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. This has been sent to the bank by our banking operations team. Please do check statuses or await webhooks to know the terminal state of the transfer request. | Rely on Check Status API or Webhooks. | - |
  | 200 | PENDING | BANK\_GATEWAY\_ERROR | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. You should rely only on Check Status API response or Webhooks to know the terminal state of the transfer request. | Rely on Check Status API or Webhooks. | - |
  | 200 | PENDING | NO\_SUCH\_REQUEST | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. The bank is not able to find the request at their end as of now, and it has been sent to the bank by our banking operations team. Please do check statuses or await webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks. | - |
  | 200 | PENDING | IN\_PROCESS | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. Please do check statuses or await webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks. | - |
  | 200 | PENDING | ERROR\_FETCHING\_STATUS | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. The response received from the partner bank has a new code. This has been raised with the bank to understand the new code. Please do check statuses or await webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks. | - |
  | 200 | PENDING | TRANSACTION\_PROCESSED | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. You should rely only on Check Status API response or Webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks. | - |
  | 200 | PENDING | REQUEST\_TIMEDOUT | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. The bank is not able to find the request at their end as of now as the request between the partner bank has probably timed out, and it has been highlighted to the bank by our banking operations team. Please do check statuses or await webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks. | - |
  | 200 | PENDING | DUPLICATE | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. The bank claims of receiving a duplicate request at their end as of now. You should rely only on Check Status API response or Webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks. | - |
  | 200 | PENDING | PENDING | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. You should rely only on Check Status API response or Webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks. | - |
  | 200 | PENDING | SCHEDULED\_FOR\_NEXT\_WORKINGDAY | The transfer is currently in a Pending state, as the bank has scheduled the transfer for the next working day. This typically happens for NEFT/RTGS transfers if they are initiated beyond the cut-off hours or during bank holidays. You should rely only on Check Status API response or Webhooks to know the terminal state of the transfer request. | - | - |
  | 200 | PENDING | SUSPECT | The transfer is currently in a Pending state, as the bank has scheduled the transfer for the next working day. This typically happens for NEFT/RTGS transfers if they are initiated beyond the cut-off hours or during bank holidays. You should rely only on Check Status API response or Webhooks to know the terminal state of the transfer request. | - | - |
  | 200 | PENDING | IMPLEMENTATION\_ERROR | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. You should rely only on Check Status API response or Webhooks to know the terminal state of the transfer request. | - | - |
  | 200 | PENDING | UNKNOWN\_ERROR\_CODE | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. The response received from the partner bank has a new code. This has been raised with the bank to understand the new code. Please do check statuses or await webhooks to know the terminal state of the transfer request. | - | - |
  | 200 | QUEUED | QUEUED | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. You should rely only on Check Status API response or Webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks. | - |
  | 200 | RECEIVED | RECEIVED | The transfer has been received by Cashfree successfully for further processing. You should use Check Status API response or Webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks. | - |
  | 200 | REJECTED | BENE\_NOT\_EXIST | The transfer has been rejected because the beneficiary, added in the transfer request, does not exist. After adding the right beneficiary, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After adding the right beneficiary, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after adding the correct beneficiary. |
  | 200 | REJECTED | INSUFFICIENT\_BALANCE | The transfer has been rejected because of low balance in your Cashfree Wallet. After recharging the account, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After recharging the account, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after recharging. |
  | 200 | REJECTED | INSIDE\_BLACKOUT\_WINDOW | The transfer has been rejected because the transfer falls under the blackout window defined by you in Payout Protect. You can reinitiate the transfer via Cashfree, after the blackout window or after modifying the blackout window from the [Merchant Dashboard](https://merchant.cashfree.com/merchants), so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree, after the blackout window or after modifying the blackout window from the [Merchant Dashboard](https://merchant.cashfree.com/merchants), so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | REJECTED | INVALID\_MODE\_FOR\_PYID | The transfer has been rejected because the payment instrument does not support this mode of transfer. You should get this mode activated on the payment instrument ID by contacting Cashfree, and then initiate a new transfer request. | You should get this mode activated on the payment instrument ID by contacting Cashfree, and then initiate a new transfer request. | Yes, after activating model |
  | 200 | REJECTED | BENE\_BLACKLISTED | The transfer has been rejected because the beneficiary's bank account and/or VPA handles have been blacklisted by Risk team. You should get a different bank account and/or VPA to send the transfer, or you can connect with Cashfree Team to understand more about this. | You should get a different bank account and/or VPA to send the transfer, or you can connect with Cashfree Team to understand more about this. | Yes, after correcting beneficiary details |
  | 200 | REJECTED | TRANSFER\_NOT\_ATTEMPTED | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | REJECTED | INVALID\_TRANSFER\_AMOUNT | The transfer has been rejected because the amount entered is invalid. After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting the amount |
  | 200 | REJECTED | TRANSFER\_LIMIT\_BREACH | The transfer has been rejected because the amount entered breaches the limits set for your payout account. After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). You can connect with Cashfree if you are not sure about the transfer limits set for your payout account. | After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). You can connect with Cashfree if you are not sure about the transfer limits set for your payout account. | Yes, after adhering to the transfer limits. |
  | 200 | REJECTED | INVALID\_PAYMENT\_INSTRUMENT | The transfer has been rejected because the payment instrument (fundsource\_id parameter in the API request) used for attempting the transfer is invalid. After correcting the payment instrument, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | After correcting the payment instrument, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting payment instrument |
  | 200 | REJECTED | PAYOUT\_INTERNAL\_ERROR | The transfer has been rejected because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | REJECTED | VELOCITY\_CHECK\_FAILED | The transfer has been rejected because the amount entered breaches the limits set for your payout account. After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). You can connect with Cashfree if you are not sure about the transfer limits set for your payout account. | After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). You can connect with Cashfree if you are not sure about the transfer limits set for your payout account. | Yes, after adhering to the transfer limits. |
  | 200 | REJECTED | PAYOUT\_INTERNAL\_ERROR | The transfer has been rejected because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | REJECTED | PAYOUT\_INTERNAL\_ERROR | The transfer has been rejected because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | REJECTED | DISABLED\_MODE | The transfer has been rejected because your payout account does not support this mode of transfer. You should get this mode activated on your payout account by contacting Cashfree, and then initiate a new transfer request. | You should get this mode activated on your payout account by contacting Cashfree, and then initiate a new transfer request. | Yes, after activating mode. |
  | 200 | REJECTED | BANK\_ACCOUNT\_INVALID | The transfer has been rejected because there is a mismatch in the Bank Account Number of the beneficiary ID and the Bank Account Number in the transfer request. After correcting the Bank Account Number, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | After correcting the Bank Account Number, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting the bank account number. |
  | 200 | REJECTED | BANK\_IFSC\_INVALID | The transfer has been rejected because there is a mismatch in the IFSC of the beneficiary ID and the IFSC in the transfer request. After correcting the IFSC, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | After correcting the IFSC, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting the IFSC |
  | 200 | REJECTED | VPA\_INVALID | The transfer has been rejected because there is a mismatch in the VPA handle of the beneficiary ID and the VPA handle in the transfer request. After correcting the VPA handle, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | After correcting the VPA handle, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting the VPA handle |
  | 200 | REJECTED | PHONE\_INVALID | The transfer has been rejected because there is a mismatch in the Phone Number of the beneficiary ID and the Phone Number in the transfer request. After correcting the Phone Number, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | After correcting the Phone Number, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting the phone number. |
  | 200 | REJECTED | BANK\_ACCOUNT\_DETAILS\_MISSING | The transfer has been rejected because the Bank Account Details are missing in the transfer request. After adding the Bank Account Details, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | After adding the Bank Account Details, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after adding the bank account details. |
  | 200 | REVERSED | ACCOUNT\_BLOCKED | The transfer has been reversed by the beneficiary bank as the end-beneficiary's account is blocked for receiving incoming funds. After correcting the account number or getting the account unblocked, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the account number or getting the account unblocked, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after adding new details or getting account unblocked. |
  | 200 | REVERSED | FAILED | The transfer has been reversed by the beneficiary bank as they were unable to credit the end beneficiary's bank account. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | - | Yes |
  | 200 | REVERSED | NRE\_ACCOUNT\_FAIL | The transfer has been reversed by the beneficiary bank as they were unable to credit the end beneficiary's bank account as it is an NRE Account and transfers to NRE Accounts are not supported. | Get a new account(non-NRE account) from the beneficiary; you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | No |
  | 200 | REVERSED | RETURNED\_FROM\_BENEFICIARY | The transfer has been reversed by the beneficiary bank as they were unable to credit the end beneficiary's bank account. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | REVERSED | BENE\_BANK\_DECLINED | The transfer has been declined by the beneficiary bank and they were unable to credit the end beneficiary's bank account. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | REVERSED | IMPS\_MODE\_FAIL | The transfer has been reversed by the beneficiary bank because the beneficiary bank account doesnot support IMPS transfers. This rejection is done by the beneficiary bank for the specific beneficiary account. You can try NEFT or other channels to do the disbursals. | You can reinitiate the transfer via Cashfree by changing the mode so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after changing mode. |
  | 200 | REVERSED | DEST\_LIMIT\_REACHED | The transfer has been reversed by the beneficiary bank as the end-beneficiary's account has reached a limit of receiving incoming funds. This rejection is done by the beneficiary bank for the specific beneficiary account. You can reinitiate the transfer after a while via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). The success of the request is contingent on beneficiary's limit being available to receive incoming funds. | The limits on the beneficiary account are typically refreshed every 24 hours. Its not clear when the 24 hour window shall elpase so you can then reinitiate the transfer via Cashfree after some time so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after some time. |
  | 200 | REVERSED | INVALID\_ACCOUNT\_FAIL | The transfer has been reversed by the beneficiary bank because the Account Number of the beneficiary is invalid. After correcting the account number, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the account number, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting the account number |
  | 200 | SUCCESS | SENT\_TO\_BENEFICIARY | The transfer has been initiated via the partner bank successfully. The request is waiting to be processed at the beneficiary bank to do the credit to the end beneficiary. | - | - |
  | 200 | SUCCESS | COMPLETED | The transfer has been initiated via the partner bank successfully, hence your account is debited and the request is successfully processed by the beneficiary bank and has been credited to the end beneficiary. | - | - |

  \| 200              | REJECTED          | TRANSFERID\_INVALID            | transferid can contain only alphabets, numbers, underscore (\_), hyphen (-). After correcting the transferid, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | After correcting the transferid, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting transfer id. |
  \| 200              | REJECTED          | AMOUNT\_INVALID                | amount can contain only numbers. After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be attempted. | After correcting the amount, you can reinitiate the transfer. | Yes, after correcting amount. |
  \| 200              | REJECTED          | REMARKS\_INVALID               | remarks can contain only alphabets, numbers and space. | After correcting the remarks, you can reinitiate the transfer. | Yes, after correcting remarks. |
  \| 200              | REJECTED          | BENEID\_INVALID                | beneId can contain only alphabets, numbers and underscore. | After correcting the beneId, you can reinitiate the transfer. | Yes, after correcting beneficiary id. |
  \| 200              | REJECTED          | NAME\_INVALID                  | name can contain only alphabets, numbers and space. | After correcting the name, you can reinitiate the transfer. | Yes, after correcting name. |
  \| 200              | REJECTED          | EMAIL\_INVALID                 | email is not a valid email format. | After correcting the email, you can reinitiate the transfer. | Yes, after correcting email. |
  \| 200              | REJECTED          | IBAN\_INVALID                  | iban can contain only alphabets and numbers. | After correcting the iban, you can reinitiate the transfer. | Yes, after correcting IBAN. |
  \| 200              | REJECTED          | TRANSFERMODE\_INVALID          | transferMode invalid (allowed: banktransfer, upi, paytm, amazonpay, imps, neft, rtgs, ppc). | After correcting the transferMode, you can reinitiate the transfer. | Yes, after correcting mode. |
  \| 200              | REJECTED          | CURRENCY\_INVALID              | currency is invalid. | After correcting the currency, you can reinitiate the transfer. | Yes, after correcting currency. |
  \| 200              | REJECTED          | ACCOUNT\_DOES\_NOT\_EXIST        | The transfer has been rejected because the beneficiary account/ VPA does not exist as per our partner bank. After correcting the account number/ VPA, you can reinitiate the transfer. | After correcting the account number / VPA, reinitiate the transfer. | Yes, after correcting details. |
  \| 200              | FAILED            | ACCOUNT\_DOES\_NOT\_EXIST        | The transfer has failed because the beneficiary account/ VPA does not exist as per our partner bank. After correcting the account number/ VPA, you can reinitiate the transfer. | After correcting the account number / VPA, reinitiate the transfer. | Yes, after correcting details. |
  \| 200              | REJECTED          | AMAZON\_AMOUNT\_EXCEED          | The amount entered breaches the limits set for the beneficiary's Amazon account. | After verifying the limits, reinitiate the transfer. | Yes, after verifying limits. |
  \| 200              | FAILED            | AMAZON\_AMOUNT\_EXCEED          | The amount entered breaches the limits set for the beneficiary's Amazon account. | After verifying the limits, reinitiate the transfer. | Yes, after verifying limits. |
  \| 200              | REJECTED          | ANOMALY\_DETECTION             | The transfer has been rejected as risk product detected an anomaly. | Reinitiate after validation at your end. | Yes, after validation. |
  \| 200              | APPROVAL\_PENDING  | ANOMALY\_DETECTION             | The transfer requires approval as risk product detected an anomaly. | Approve / reject on dashboard (Payout Protect). | - |
  \| 200              | FAILED            | BAD\_CONNECTION                | Intermittent internal error between Cashfree and partner bank. | Reinitiate the transfer. | Yes, after some time. |
  \| 200              | REJECTED          | BENE\_INVALID                  | Beneficiary in the request does not exist. | Add correct beneficiary then reinitiate. | Yes, after adding beneficiary. |
  \| 200              | FAILED            | BENE\_INVALID                  | Beneficiary in the request does not exist. | Add correct beneficiary then reinitiate. | Yes, after adding beneficiary. |
  \| 200              | FAILED            | BENE\_NOT\_REGISTERED           | Beneficiary not registered with partner bank. | Add correct beneficiary then reinitiate. | Yes, after adding beneficiary. |
  \| 200              | VALIDATION\_PENDING| BENE\_VERIFICATION\_PENDING     | Beneficiary verification pending; transfer will be attempted post validation. | Rely on Check Status API or webhooks. | - |
  \| 200              | FAILED            | BENEFICIARY\_BANK\_UNAVAILABLE  | Beneficiary bank offline. | Reinitiate after some time. | Yes, after some time. |
  \| 200              | FAILED            | BENEFICIARY\_NAME\_DIFFERS      | Beneficiary name differs per partner bank. | Add correct beneficiary then reinitiate. | Yes, after correcting name. |
  \| 200              | REJECTED          | BENEFICIARY\_NAME\_DIFFERS      | Beneficiary name differs per partner bank. | Add correct beneficiary then reinitiate. | Yes, after correcting name. |
  \| 200              | REJECTED          | BENEFICIARY\_NAME\_MISMATCH     | Beneficiary name differs per partner bank. | Add correct beneficiary then reinitiate. | Yes, after correcting name. |
  \| 200              | REJECTED          | CARD\_UNSUPPORTED              | Card not supported. | Change payment instrument then reinitiate. | Yes, after changing instrument. |
  \| 200              | FAILED            | CARD\_UNSUPPORTED              | Card not supported. | Change payment instrument then reinitiate. | Yes, after changing instrument. |
  \| 200              | FAILED            | DUPLICATE\_FAILED              | Bank claims duplicate request. | Reinitiate with different transfer id. | Yes, with new id. |
  \| 200              | FAILED            | ERROR\_RETRIEVING\_BALANCE      | Intermittent issue at partner bank retrieving balance. | Reinitiate after some time. | Yes, after some time. |
  \| 200              | REJECTED          | INVALID\_CARD                  | Card details not correct. | Enter correct card details then reinitiate. | Yes, after correcting card. |
  \| 200              | FAILED            | INVALID\_CARD                  | Card details not correct. | Enter correct card details then reinitiate. | Yes, after correcting card. |
  \| 200              | REJECTED          | INVALID\_CURRENCY\_FOR\_PYID     | Transfer currency not supported for payment instrument id. | Change currency to INR and reinitiate. | Yes, after changing currency. |
  \| 200              | FAILED            | INVALID\_CURRENCY\_FOR\_PYID     | Transfer currency not supported for payment instrument id. | Change currency to INR and reinitiate. | Yes, after changing currency. |
  \| 200              | FAILED            | INVALID\_MODE\_FAIL             | Transfer mode not supported for beneficiary account. | Change mode then reinitiate. | Yes, after changing mode. |
  \| 200              | REJECTED          | INVALID\_OR\_NO\_SUCH\_ACCOUNT\_TYPE | Beneficiary account type invalid / unsupported. | Get new account from beneficiary then reinitiate. | Yes, after new account. |
  \| 200              | FAILED            | INVALID\_OR\_NO\_SUCH\_ACCOUNT\_TYPE | Beneficiary account type invalid / unsupported. | Get new account from beneficiary then reinitiate. | Yes, after new account. |
  \| 200              | FAILED            | INVALID\_PHONE\_BENEFICIARY     | Phone number not linked to any VPA. | Add correct phone beneficiary then reinitiate. | Yes, after correcting phone. |
  \| 200              | REJECTED          | INVALID\_TRANSFER\_CURRENCY     | Transfer currency not supported. | Change currency to INR then reinitiate. | Yes, after changing currency. |
  \| 200              | FAILED            | INVALID\_TRANSFER\_CURRENCY     | Transfer currency not supported. | Change currency to INR then reinitiate. | Yes, after changing currency. |
  \| 200              | REJECTED          | KYC\_COMPLIANCE\_VERIFICATION\_FAILED | KYC verification failed. | Reinitiate after resolving KYC. | Yes, after KYC resolution. |
  \| 200              | REJECTED          | KYC\_REQUIREMENTS\_NOT\_SATISFIED | KYC requirements not satisfied. | Complete KYC then reinitiate. | Yes, after completing KYC. |
  \| 200              | FAILED            | LOAD\_LIMIT\_EXHAUSTED          | Beneficiary account reached max transaction amount limit. | Reinitiate after 24 hours. | Yes, after 24 hours. |
  \| 200              | FAILED            | LOAN\_FUND\_MOVEMENT\_FAILURE    | Intermittent issue at Cashfree. | Reinitiate transfer. | Yes, after some time. |
  \| 200              | PENDING           | LOW\_BALANCE\_QUEUED            | Balance in the fund source is exhausted; will auto process post recharge. | Recharge fund source; rely on status API/webhook. | - |
  \| 200              | REJECTED          | MANUALLY\_REJECTED             | Transfer manually rejected by you. | Reinitiate if required. | Yes, if needed. |
  \| 200              | REJECTED          | PAYOUT\_INACTIVE               | Payout account inactive. | Activate account then reinitiate. | Yes, after activation. |
  \| 200              | FAILED            | POOL\_CONNECTION\_TIMEOUT       | Connection issue with partner bank. | Reinitiate after some time. | Yes, after some time. |
  \| 200              | REJECTED          | QUICK\_TRANSFER\_DISABLED       | Quick transfer disabled for payout account. | Enable quick transfer then reinitiate. | Yes, after enabling. |
  \| 200              | REJECTED          | REJECTED                      | Transfer rejected (generic). | Review request and correct issues. | Yes, after correction. |
  \| 200              | REVERSED          | REVERSED                      | Transfer reversed by beneficiary bank; credit failed. | Reinitiate after correcting issue. | Yes, after correction. |
  \| 200              | FAILED            | RTGS\_MODE\_FAIL                | Beneficiary account does not support RTGS transfers. | Try NEFT or other channels. | Yes, via different mode. |
  \| 200              | FAILED            | SUSPECTED\_FAILED              | Partner bank suspects transfer is fraudulent. | Contact support / investigate before retry. | No (investigate). |
  \| 200              | REJECTED          | VBA\_TRANSFER\_DISABLED         | Transfers to virtual bank accounts not enabled. | Enable payouts to VBAs then reinitiate. | Yes, after enabling. |
  \| 200              | REJECTED          | ERROR\_SELECTING\_FUND\_SOURCE   | Issue with account configuration selecting fund source. | Contact care team; fix config then reinitiate. | Yes, after fixing config. |
  \| 200              | VALIDATION\_PENDING| VALIDATION\_PENDING            | Beneficiary verification pending; transfer will be attempted post validation. | Rely on Status API / webhooks. | - |
  \| 200              | REJECTED          | INVALID\_BENEFICIARY\_CODE      | Beneficiary code invalid. | Correct beneficiary code then reinitiate. | Yes, after correcting code. |
  \| 200              | REJECTED          | DUPLICATE\_TRANSFER            | Transfer already present / processed; duplicate transferId. | Change transferId and reinitiate. | Yes, with new transfer id. |

  #### 4XX errors

  | HTTP status code | Error code | Message | Next action |
  | :- | :- | :- | :- |
  | 400 | transfer\_id\_missing | transfer\_id is missing in the request | Enter a valid transfer\_id in the request. |
  | 400 | transfer\_id\_invalid | transfer\_id should be alphanumeric | Enter a valid transfer\_id in the request. |
  | 400 | transfer\_amount\_invalid | transfer\_amount should be greater then 1.00 | Enter an amount greater than 1.00. |
  | 400 | transfer\_amount\_missing | transfer\_amount is missing in the request | Provide a value for the transfer\_amount parameter in the request. |
  | 400 | transfer\_mode\_invalid | transfer\_mode is invalid allowed values are : bank, imps, neft, rtgs, upi, paytm, amazonpay, card and cardupi | Provide a valid transfer\_mode in the request. |
  | 400 | beneficiary\_details.beneficiary\_id\_invalid | beneficiary\_id should be alphanumeric | Enter a valid beneficiary\_id. |
  | 400 | beneficiary\_details.beneficiary\_name\_invalid | beneficiary\_name is invalid. only alphabets and whitespaces are allowed | Enter a valid beneficiary\_id. |
  | 400 | beneficiary\_details.beneficiary\_instrument\_details.bank\_account\_number\_invalid | bank\_account\_number should be alphanumeric | Enter a valid bank\_account\_number. |
  | 400 | beneficiary\_details.beneficiary\_instrument\_details.bank\_account\_number\_invalid | Bank account number passed in the request does not match with the beneficiary with beneficiary\_id :: test\_beneId | Enter the correct bank\_account\_number associated with the beneficiary\_id. |
  | 400 | beneficiary\_details.beneficiary\_instrument\_details.bank\_ifsc\_invalid | bank\_ifsc should be in standard ifsc format | Enter a valid bank\_ifsc. |
  | 400 | beneficiary\_details.beneficiary\_instrument\_details.bank\_ifsc\_invalid | Bank ifsc passed in the request does not match with the beneficiary with beneficiary\_id :: test\_beneId | Enter the correct bank\_ifsc associated with the beneficiary\_id. |
  | 400 | beneficiary\_details.beneficiary\_instrument\_details.vpa\_invalid | vpa is in invalid format | Enter a valid VPA. |
  | 400 | beneficiary\_details.beneficiary\_instrument\_details.vpa\_invalid | Vpa passed in the request does not match with the beneficiary with beneficiary\_id :: test\_beneId | Enter the correct vpa associated with the beneficiary\_id. |
  | 404 | beneficiary\_not\_found | Beneficiary does not exist | Enter a valid beneficiary\_id. |

  <br />
</Accordion>

### Get Transfer Status V2

<Accordion title="Click to view the response codes.">
  | HTTP status code | Status | Status code | Status description | Next action | Try again via Cashfree - Yes or no |
  | :- | :- | :- | :- | :- | :- |
  | 200 | APPROVAL\_PENDING | VELOCITY\_CHECK\_FAILED | The transfer requires an approval as the count of transfers to a particular beneficiary etc have breached the limit. You can approve or reject the transfer request from the Cashfree [Merchant Dashboard](https://merchant.cashfree.com/auth/login). | You can approve/reject the transfer on the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and go to **Transfers > Approve** tab. Post the transfer is approved, the request is sent to the partner bank for further processing. | - |
  | 200 | APPROVAL\_PENDING | TRANSFER\_LIMIT\_BREACH | The transfer requires an approval as the transfer amount etc have breached the limit. You can approve or reject the transfer request from the Cashfree [Merchant Dashboard](https://merchant.cashfree.com/auth/login). | You can approve/reject the transfer on the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and go to **Transfers > Approve** tab. Post the transfer is approved, the request is sent to the partner bank for further processing. | - |
  | 200 | APPROVAL\_PENDING | APPROVAL\_PENDING | The transfer requires approval. You can approve or reject the transfer request from the Cashfree [Merchant Dashboard](https://merchant.cashfree.com/auth/login). | You can approve/reject the transfer on the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and go to **Transfers > Approve** tab. Post the transfer is approved, the request is sent to the partner bank for further processing. | - |
  | 200 | APPROVAL\_PENDING | ANOMALY\_DETECTION | The transfer requires approval as it is a high risk transaction detected by Payout Protect model.  You can approve or reject the transfer request from the Cashfree [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and go to **Payout Protect > Risky Transfers > Flagged Transfers** | You can approve/reject the transfer on the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and go to **Payout Protect > Risky Transfers > Flagged Transfers** tab. Post the transfer is approved, the request is sent to the partner bank for further processing. | |
  | 200 | FAILED | WAIT\_TIME\_EXCEEDED | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | FAILED | BENE | The transfer has failed because the beneficiary bank has declined the transfer. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again with the partner bank(s). | - | Yes |
  | 200 | FAILED | IMPS\_MODE\_FAIL | The transfer has failed because the beneficiary account doesnot support IMPS transfers. This rejection is done by the partner bank for the specific beneficiary account. You can try NEFT or other channels to do the disbursals. | You can try NEFT or other channels to do the disbursals. | Yes, via a different mode |
  | 200 | FAILED | SOURCE\_BENE\_DECLINED | The transfer has failed because our partner bank has declined the transfer because of their internal checks, technical declines etc. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again with other partner bank(s). | Yes |
  | 200 | FAILED | CONNECTION\_TIMEOUT | The transfer has failed because there was a connection timeout between the bank and Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again with the partner bank(s). | YES |
  | 200 | FAILED | PAYOUT\_INTERNAL\_ERROR | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | - | Yes |
  | 200 | FAILED | NPCI\_UNAVAILABLE | The transfer has failed because NPCI was unavailable to complete the transfer request. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree. The success of the request is contingent on NPCI services being up. | - | Yes, after some time. |
  | 200 | FAILED | DEST\_LIMIT\_REACHED | The transfer has failed because the beneficiary account has breached the limit of receiving funds. This rejection is done by the beneficiary bank for the specific beneficiary account. You can reinitiate the transfer after a while via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). The success of the request is contingent on beneficiary's limit being available to receive incoming funds. | - | Yes, after some time. |
  | 200 | FAILED | RETURNED\_FROM\_BENEFICIARY | The transfer has failed because the beneficiary bank has returned the transfer and has not need able to credit funds to the end beneficiary. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again with the partner bank(s). | - | - |
  | 200 | FAILED | PAYOUT\_INTERNAL\_ERROR | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | - | - |
  | 200 | FAILED | INVALID\_BENE\_ACCOUNT\_OR\_IFSC | The transfer has failed because the beneficiary account or IFSC is invalid. After correcting the beneficiary account or IFSC, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | - | - |
  | 200 | FAILED | PAYOUT\_INTERNAL\_ERROR | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | - | - |
  | 200 | FAILED | FAILED | The transfer has failed because there was an intermittent issue at the partner bank's end. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after some time. |
  | 200 | FAILED | PAYOUT\_INTERNAL\_ERROR | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | - | - |
  | 200 | FAILED | INSUFFICIENT\_BALANCE | The transfer has failed because of low balance in your Cashfree Wallet/ Bank Account. After recharging the account, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After recharging the account, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after recharging. |
  | 200 | FAILED | INVALID\_BENE\_VPA | The transfer has failed because the beneficiary VPA is invalid. After correcting the VPA handle, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the VPA handle, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting VPA handle. |
  | 200 | FAILED | INVALID\_IFSC\_FAIL | The transfer has failed because the IFSC is invalid. After correcting the IFSC, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the IFSC, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting IFSC |
  | 200 | FAILED | BAD\_GATEWAY | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | FAILED | INVALID\_AMOUNT\_FAIL | The transfer has failed because the amount entered is invalid. After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting the amount |
  | 200 | FAILED | INVALID\_ACCOUNT\_FAIL | The transfer has failed because the Account Number of the beneficiary is invalid, as per our partner bank. After correcting the account number, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the account number, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting the account number |
  | 200 | FAILED | INVALID\_REQUEST | The transfer has failed because the transfer request is invalid, as per our partner bank, because of exceeding the character limit of certain parameter, wrong input etc. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | - | - |
  | 200 | FAILED | ACCOUNT\_BLOCKED | The transfer has failed because the account is blocked, as per our partner bank. After getting the account unblocked, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After getting the account unblocked, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after unblocking the account number |
  | 200 | FAILED | DEBIT\_FAILURE | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | FAILED | BENEFICIARY\_BANK\_OFFLINE | The transfer has failed because the respective beneficiary bank is offline. After some time, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After some time, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s) | Yes |
  | 200 | FAILED | AUTHENTICATION\_FAILURE | The transfer has failed because there was an authentication failure at the partner bank's end. After checking with the partner bank, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | This is a scenario when the API access is not working at the partner bank's end. After checking with the partner bank, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | FAILED | NRE\_ACCOUNT\_FAIL | The transfer has failed because the beneficiary account is an NRE Account and transfers to NRE Accounts are not supported, as per our partner bank. | Get a new account(non-NRE account) from the beneficiary; you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | No |
  | 200 | FAILED | SOURCE\_LIMIT\_REACHED | The transfer has been failed by the partner bank as the source bank account has reached a limit of transferring funds. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | If you are on Cashfree Wallet, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). If you are on Connected Bank, you need to recharge your bank account and then reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after some time. |
  | 200 | FAILED | BANK\_GATEWAY\_ERROR | The transfer has failed because there was an intermittent issue at the partner bank's end. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | FAILED | BAD\_REQUEST | The transfer has failed because the details of the transfer request is invalid, as per our partner bank. After correcting the details in the transfer request, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the details in the transfer request, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | FAILED | REINITIALIZE\_TRANSFER\_LATER | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | MANUALLY\_REJECTED | MANUALLY\_REJECTED | The transfer has failed because it has been manually rejected by the merchant or any team member user who has the permissions to do the same on [Merchant Dashboard](https://merchant.cashfree.com/merchants). You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again with the partner bank(s). | If the merchant wants to reinitiate the transfer, they can reinitiate the transfer via Cashfree so that the transfer can be reattempted again with the partner bank(s). | Yes, if you want to reinitiate the transfer |
  | 200 | PENDING | SENT\_TO\_BANK | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. This has been sent to the bank by our banking operations team. Please do check statuses or await webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks. | - |
  | 200 | PENDING | BANK\_GATEWAY\_ERROR | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. You should rely only on Check Status API response or Webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks | - |
  | 200 | PENDING | NO\_SUCH\_REQUEST | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. The bank is not able to find the request at their end as of now, and it has been sent to the bank by our banking operations team. Please do check statuses or await webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks. | - |
  | 200 | PENDING | IN\_PROCESS | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. Please do check statuses or await webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks | - |
  | 200 | PENDING | ERROR\_FETCHING\_STATUS | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. The response received from the partner bank has a new code. This has been raised with the bank to understand the new code. Please do check statuses or await webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks | - |
  | 200 | PENDING | TRANSACTION\_PROCESSED | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. You should rely only on Check Status API response or Webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks | - |
  | 200 | PENDING | REQUEST\_TIMEDOUT | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. The bank is not able to find the request at their end as of now as the request between the partner bank has probably timed out, and it has been highlighted to the bank by our banking operations team. Please do check statuses or await webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks | - |
  | 200 | PENDING | DUPLICATE | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. The bank claims of receiving a duplicate request at their end as of now. You should rely only on Check Status API response or Webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks | - |
  | 200 | PENDING | - | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. You should rely only on Check Status API response or Webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks | - |
  | 200 | PENDING | SCHEDULED\_FOR\_NEXT\_WORKINGDAY | The transfer is currently in a Pending state, as the bank has scheduled the transfer for the next working day. This typically happens for NEFT/RTGS transfers if they are initiated beyond the cut-off hours or during bank holidays. You should rely only on Check Status API response or Webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks | - |
  | 200 | PENDING | SUSPECT | The transfer is currently in a Pending state, as the bank has scheduled the transfer for the next working day. This typically happens for NEFT/RTGS transfers if they are initiated beyond the cut-off hours or during bank holidays. You should rely only on Check Status API response or Webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks | - |
  | 200 | PENDING | IMPLEMENTATION\_ERROR | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. You should rely only on Check Status API response or Webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks | - |
  | 200 | PENDING | UNKNOWN\_ERROR\_CODE | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. The response received from the partner bank has a new code. This has been raised with the bank to understand the new code. Please do check statuses or await webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks | - |
  | 200 | QUEUED | QUEUED | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. You should rely only on Check Status API response or Webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks | - |
  | 200 | RECEIVED | RECEIVED | The transfer has been received by Cashfree successfully for further processing. You should use Check Status API response or Webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks | - |
  | 200 | REJECTED | BENE\_NOT\_EXIST | The transfer has been rejected because the beneficiary, added in the transfer request, does not exist. After adding the right beneficiary, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After adding the right beneficiary, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after adding the correct beneficiary |
  | 200 | REJECTED | INSUFFICIENT\_BALANCE | The transfer has been rejected because of low balance in your Cashfree Wallet. After recharging the account, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After recharging the account, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after recharging the account |
  | 200 | REJECTED | INSIDE\_BLACKOUT\_WINDOW | The transfer has been rejected because the transfer falls under the blackout window defined by you in Payout Protect. You can reinitiate the transfer via Cashfree, after the blackout window or after modifying the blackout window from the [Merchant Dashboard](https://merchant.cashfree.com/merchants), so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree, after the blackout window or after modifying the blackout window from the merchant dashboard, so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | REJECTED | INVALID\_MODE\_FOR\_PYID | The transfer has been rejected because the payment instrument does not support this mode of transfer. You should get this mode activated on the payment instrument ID by contacting Cashfree, and then initiate a new transfer request. | You should get this mode activated on the payment instrument ID by contacting Cashfree, and then initiate a new transfer request. | Yes, after activating mode |
  | 200 | REJECTED | BENE\_BLACKLISTED | The transfer has been rejected because the beneficiary's bank account and/or VPA handles have been blacklisted by Risk team. You should get a different bank account and/or VPA to send the transfer, or you can connect with Cashfree Team to understand more about this. | You should get a different bank account and/or VPA to send the transfer, or you can connect with Cashfree Team to understand more about this. | Yes, after correcting beneficiary details |
  | 200 | REJECTED | TRANSFER\_NOT\_ATTEMPTED | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | REJECTED | INVALID\_TRANSFER\_AMOUNT | The transfer has been rejected because the amount entered is invalid. After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting the amount |
  | 200 | REJECTED | TRANSFER\_LIMIT\_BREACH | The transfer has been rejected because the amount entered breaches the limits set for your payout account. After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). You can connect with Cashfree if you are not sure about the transfer limits set for your payout account. | After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). You can connect with Cashfree if you are not sure about the transfer limits set for your payout account. | Yes, after adhering to the transfer limits |
  | 200 | REJECTED | INVALID\_PAYMENT\_INSTRUMENT | The transfer has been rejected because the payment instrument (fundsource\_id parameter in the API request) used for attempting the transfer is invalid. After correcting the payment instrument, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | After correcting the payment instrument, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting the payment instrument |
  | 200 | REJECTED | PAYOUT\_INTERNAL\_ERROR | The transfer has been rejected because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | REJECTED | VELOCITY\_CHECK\_FAILED | The transfer has been rejected because the amount entered breaches the limits set for your payout account. After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). You can connect with Cashfree if you are not sure about the transfer limits set for your payout account. | After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). You can connect with Cashfree if you are not sure about the transfer limits set for your payout account. | Yes, after adhering to the transfer limits |
  | 200 | REJECTED | PAYOUT\_INTERNAL\_ERROR | The transfer has been rejected because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | REJECTED | PAYOUT\_INTERNAL\_PEOPLE | The transfer has been rejected because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | REJECTED | DISABLED\_MODE | The transfer has been rejected because your payout account does not support this mode of transfer. You should get this mode activated on your payout account by contacting Cashfree, and then initiate a new transfer request. | You should get this mode activated on your payout account by contacting Cashfree, and then initiate a new transfer request. | Yes, after activating the mode |
  | 200 | REJECTED | BANK\_ACCOUNT\_INVALID | The transfer has been rejected because there is a mismatch in the Bank Account Number of the beneficiary ID and the Bank Account Number in the transfer request. After correcting the Bank Account Number, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | After correcting the Bank Account Number, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting the bank account number. |
  | 200 | REJECTED | BANK\_IFSC\_INVALID | The transfer has been rejected because there is a mismatch in the IFSC of the beneficiary ID and the IFSC in the transfer request. After correcting the IFSC, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | After correcting the IFSC, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting the IFSC |
  | 200 | REJECTED | VPA\_INVALID | The transfer has been rejected because there is a mismatch in the VPA handle of the beneficiary ID and the VPA handle in the transfer request. After correcting the VPA handle, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | After correcting the VPA handle, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting the VPA handle |
  | 200 | REJECTED | PHONE\_INVALID | The transfer has been rejected because there is a mismatch in the Phone Number of the beneficiary ID and the Phone Number in the transfer request. After correcting the Phone Number, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | After correcting the Phone Number, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting the phone number |
  | 200 | REJECTED | BANK\_ACCOUNT\_DETAILS\_MISSING | The transfer has been rejected because the Bank Account Details are missing in the transfer request. After adding the Bank Account Details, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | After adding the Bank Account Details, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after adding the bank account details |
  | 200 | REVERSED | ACCOUNT\_BLOCKED | The transfer has been reversed by the beneficiary bank as the end-beneficiary's account is blocked for receiving incoming funds. After correcting the account number or getting the account unblocked, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the account number or getting the account unblocked, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after adding new details or getting the account unblocked |
  | 200 | REVERSED | FAILED | The transfer has been reversed by the beneficiary bank as they were unable to credit the end beneficiary's bank account. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | - | Yes |
  | 200 | REVERSED | NRE\_ACCOUNT\_FAIL | The transfer has been reversed by the beneficiary bank as they were unable to credit the end beneficiary's bank account as it is an NRE Account and transfers to NRE Accounts are not supported. | Get a new account(non-NRE account) from the beneficiary; you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | No |
  | 200 | REVERSED | RETURNED\_FROM\_BENEFICIARY | The transfer has been reversed by the beneficiary bank as they were unable to credit the end beneficiary's bank account. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | REVERSED | BENE\_BANK\_DECLINED | The transfer has been declined by the beneficiary bank and they were unable to credit the end beneficiary's bank account. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | REVERSED | IMPS\_MODE\_FAIL | The transfer has been reversed by the beneficiary bank because the beneficiary bank account doesnot support IMPS transfers. This rejection is done by the beneficiary bank for the specific beneficiary account. You can try NEFT or other channels to do the disbursals. | You can reinitiate the transfer via Cashfree by changing the mode so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after changing the mode. |
  | 200 | REVERSED | DEST\_LIMIT\_REACHED | The transfer has been reversed by the beneficiary bank as the end-beneficiary's account has reached a limit of receiving incoming funds. This rejection is done by the beneficiary bank for the specific beneficiary account. You can reinitiate the transfer after a while via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). The success of the request is contingent on beneficiary's limit being available to receive incoming | The limits on the beneficiary account are typically refreshed every 24 hours. Its not clear when the 24 hour window shall elpase so you can then reinitiate the transfer via Cashfree after some time so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after some time. |
  | 200 | REVERSED | INVALID\_ACCOUNT\_FAIL | The transfer has been reversed by the beneficiary bank because the Account Number of the beneficiary is invalid. After correcting the account number, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the account number, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting the account number. |
  | 200 | REVERSED | BENE\_NAME\_DIFFERS | The transfer has been reversed by the beneficiary bank because the Account Name of the beneficiary is different. After correcting the beneficiary name, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the beneficiary name, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting the account name |
  | 200 | SUCCESS | SENT\_TO\_BENEFICIARY | The transfer has been initiated via the partner bank successfully. The request is waiting to be processed at the beneficiary bank to do the credit to the end beneficiary. | - | - |
  | 200 | SUCCESS | COMPLETED | The transfer has been initiated via the partner bank successfully, hence your account is debited and the request is successfully processed by the beneficiary bank and has been credited to the end beneficiary. | - | - |

  \| 200              | REJECTED          | TRANSFERID\_INVALID            | transferid can contain only alphabets, numbers, underscore (\_), hyphen (-). After correcting the transferid, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | After correcting the transferid, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting transfer id. |
  \| 200              | REJECTED          | AMOUNT\_INVALID                | amount can contain only numbers. After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be attempted. | After correcting the amount, you can reinitiate the transfer. | Yes, after correcting amount. |
  \| 200              | REJECTED          | REMARKS\_INVALID               | remarks can contain only alphabets, numbers and space. | After correcting the remarks, you can reinitiate the transfer. | Yes, after correcting remarks. |
  \| 200              | REJECTED          | BENEID\_INVALID                | beneId can contain only alphabets, numbers and underscore. | After correcting the beneId, you can reinitiate the transfer. | Yes, after correcting beneficiary id. |
  \| 200              | REJECTED          | NAME\_INVALID                  | name can contain only alphabets, numbers and space. | After correcting the name, you can reinitiate the transfer. | Yes, after correcting name. |
  \| 200              | REJECTED          | EMAIL\_INVALID                 | email is not a valid email format. | After correcting the email, you can reinitiate the transfer. | Yes, after correcting email. |
  \| 200              | REJECTED          | IBAN\_INVALID                  | iban can contain only alphabets and numbers. | After correcting the iban, you can reinitiate the transfer. | Yes, after correcting IBAN. |
  \| 200              | REJECTED          | TRANSFERMODE\_INVALID          | transferMode invalid (allowed: banktransfer, upi, paytm, amazonpay, imps, neft, rtgs, ppc). | After correcting the transferMode, you can reinitiate the transfer. | Yes, after correcting mode. |
  \| 200              | REJECTED          | CURRENCY\_INVALID              | currency is invalid. | After correcting the currency, you can reinitiate the transfer. | Yes, after correcting currency. |
  \| 200              | REJECTED          | ACCOUNT\_DOES\_NOT\_EXIST        | The transfer has been rejected because the beneficiary account/ VPA does not exist as per our partner bank. After correcting the account number/ VPA, you can reinitiate the transfer. | After correcting the account number / VPA, reinitiate the transfer. | Yes, after correcting details. |
  \| 200              | FAILED            | ACCOUNT\_DOES\_NOT\_EXIST        | The transfer has failed because the beneficiary account/ VPA does not exist as per our partner bank. After correcting the account number/ VPA, you can reinitiate the transfer. | After correcting the account number / VPA, reinitiate the transfer. | Yes, after correcting details. |
  \| 200              | REJECTED          | AMAZON\_AMOUNT\_EXCEED          | The amount entered breaches the limits set for the beneficiary's Amazon account. | After verifying the limits, reinitiate the transfer. | Yes, after verifying limits. |
  \| 200              | FAILED            | AMAZON\_AMOUNT\_EXCEED          | The amount entered breaches the limits set for the beneficiary's Amazon account. | After verifying the limits, reinitiate the transfer. | Yes, after verifying limits. |
  \| 200              | REJECTED          | ANOMALY\_DETECTION             | The transfer has been rejected as risk product detected an anomaly. | Reinitiate after validation at your end. | Yes, after validation. |
  \| 200              | APPROVAL\_PENDING  | ANOMALY\_DETECTION             | The transfer requires approval as risk product detected an anomaly. | Approve / reject on dashboard (Payout Protect). | - |
  \| 200              | FAILED            | BAD\_CONNECTION                | Intermittent internal error between Cashfree and partner bank. | Reinitiate the transfer. | Yes, after some time. |
  \| 200              | REJECTED          | BENE\_INVALID                  | Beneficiary in the request does not exist. | Add correct beneficiary then reinitiate. | Yes, after adding beneficiary. |
  \| 200              | FAILED            | BENE\_INVALID                  | Beneficiary in the request does not exist. | Add correct beneficiary then reinitiate. | Yes, after adding beneficiary. |
  \| 200              | FAILED            | BENE\_NOT\_REGISTERED           | Beneficiary not registered with partner bank. | Add correct beneficiary then reinitiate. | Yes, after adding beneficiary. |
  \| 200              | VALIDATION\_PENDING| BENE\_VERIFICATION\_PENDING     | Beneficiary verification pending; transfer will be attempted post validation. | Rely on Check Status API or webhooks. | - |
  \| 200              | FAILED            | BENEFICIARY\_BANK\_UNAVAILABLE  | Beneficiary bank offline. | Reinitiate after some time. | Yes, after some time. |
  \| 200              | FAILED            | BENEFICIARY\_NAME\_DIFFERS      | Beneficiary name differs per partner bank. | Add correct beneficiary then reinitiate. | Yes, after correcting name. |
  \| 200              | REJECTED          | BENEFICIARY\_NAME\_DIFFERS      | Beneficiary name differs per partner bank. | Add correct beneficiary then reinitiate. | Yes, after correcting name. |
  \| 200              | REJECTED          | BENEFICIARY\_NAME\_MISMATCH     | Beneficiary name differs per partner bank. | Add correct beneficiary then reinitiate. | Yes, after correcting name. |
  \| 200              | REJECTED          | CARD\_UNSUPPORTED              | Card not supported. | Change payment instrument then reinitiate. | Yes, after changing instrument. |
  \| 200              | FAILED            | CARD\_UNSUPPORTED              | Card not supported. | Change payment instrument then reinitiate. | Yes, after changing instrument. |
  \| 200              | FAILED            | DUPLICATE\_FAILED              | Bank claims duplicate request. | Reinitiate with different transfer id. | Yes, with new id. |
  \| 200              | FAILED            | ERROR\_RETRIEVING\_BALANCE      | Intermittent issue at partner bank retrieving balance. | Reinitiate after some time. | Yes, after some time. |
  \| 200              | REJECTED          | INVALID\_CARD                  | Card details not correct. | Enter correct card details then reinitiate. | Yes, after correcting card. |
  \| 200              | FAILED            | INVALID\_CARD                  | Card details not correct. | Enter correct card details then reinitiate. | Yes, after correcting card. |
  \| 200              | REJECTED          | INVALID\_CURRENCY\_FOR\_PYID     | Transfer currency not supported for payment instrument id. | Change currency to INR and reinitiate. | Yes, after changing currency. |
  \| 200              | FAILED            | INVALID\_CURRENCY\_FOR\_PYID     | Transfer currency not supported for payment instrument id. | Change currency to INR and reinitiate. | Yes, after changing currency. |
  \| 200              | FAILED            | INVALID\_MODE\_FAIL             | Transfer mode not supported for beneficiary account. | Change mode then reinitiate. | Yes, after changing mode. |
  \| 200              | REJECTED          | INVALID\_OR\_NO\_SUCH\_ACCOUNT\_TYPE | Beneficiary account type invalid / unsupported. | Get new account from beneficiary then reinitiate. | Yes, after new account. |
  \| 200              | FAILED            | INVALID\_OR\_NO\_SUCH\_ACCOUNT\_TYPE | Beneficiary account type invalid / unsupported. | Get new account from beneficiary then reinitiate. | Yes, after new account. |
  \| 200              | FAILED            | INVALID\_PHONE\_BENEFICIARY     | Phone number not linked to any VPA. | Add correct phone beneficiary then reinitiate. | Yes, after correcting phone. |
  \| 200              | REJECTED          | INVALID\_TRANSFER\_CURRENCY     | Transfer currency not supported. | Change currency to INR then reinitiate. | Yes, after changing currency. |
  \| 200              | FAILED            | INVALID\_TRANSFER\_CURRENCY     | Transfer currency not supported. | Change currency to INR then reinitiate. | Yes, after changing currency. |
  \| 200              | REJECTED          | KYC\_COMPLIANCE\_VERIFICATION\_FAILED | KYC verification failed. | Reinitiate after resolving KYC. | Yes, after KYC resolution. |
  \| 200              | REJECTED          | KYC\_REQUIREMENTS\_NOT\_SATISFIED | KYC requirements not satisfied. | Complete KYC then reinitiate. | Yes, after completing KYC. |
  \| 200              | FAILED            | LOAD\_LIMIT\_EXHAUSTED          | Beneficiary account reached max transaction amount limit. | Reinitiate after 24 hours. | Yes, after 24 hours. |
  \| 200              | FAILED            | LOAN\_FUND\_MOVEMENT\_FAILURE    | Intermittent issue at Cashfree. | Reinitiate transfer. | Yes, after some time. |
  \| 200              | PENDING           | LOW\_BALANCE\_QUEUED            | Balance in the fund source is exhausted; will auto process post recharge. | Recharge fund source; rely on status API/webhook. | - |
  \| 200              | REJECTED          | MANUALLY\_REJECTED             | Transfer manually rejected by you. | Reinitiate if required. | Yes, if needed. |
  \| 200              | REJECTED          | PAYOUT\_INACTIVE               | Payout account inactive. | Activate account then reinitiate. | Yes, after activation. |
  \| 200              | FAILED            | POOL\_CONNECTION\_TIMEOUT       | Connection issue with partner bank. | Reinitiate after some time. | Yes, after some time. |
  \| 200              | REJECTED          | QUICK\_TRANSFER\_DISABLED       | Quick transfer disabled for payout account. | Enable quick transfer then reinitiate. | Yes, after enabling. |
  \| 200              | REJECTED          | REJECTED                      | Transfer rejected (generic). | Review request and correct issues. | Yes, after correction. |
  \| 200              | REVERSED          | REVERSED                      | Transfer reversed by beneficiary bank; credit failed. | Reinitiate after correcting issue. | Yes, after correction. |
  \| 200              | FAILED            | RTGS\_MODE\_FAIL                | Beneficiary account does not support RTGS transfers. | Try NEFT or other channels. | Yes, via different mode. |
  \| 200              | FAILED            | SUSPECTED\_FAILED              | Partner bank suspects transfer is fraudulent. | Contact support / investigate before retry. | No (investigate). |
  \| 200              | REJECTED          | VBA\_TRANSFER\_DISABLED         | Transfers to virtual bank accounts not enabled. | Enable payouts to VBAs then reinitiate. | Yes, after enabling. |
  \| 200              | REJECTED          | ERROR\_SELECTING\_FUND\_SOURCE   | Issue with account configuration selecting fund source. | Contact care team; fix config then reinitiate. | Yes, after fixing config. |
  \| 200              | VALIDATION\_PENDING| VALIDATION\_PENDING            | Beneficiary verification pending; transfer will be attempted post validation. | Rely on Status API / webhooks. | - |
  \| 200              | REJECTED          | INVALID\_BENEFICIARY\_CODE      | Beneficiary code invalid. | Correct beneficiary code then reinitiate. | Yes, after correcting code. |
  \| 200              | REJECTED          | DUPLICATE\_TRANSFER            | Transfer already present / processed; duplicate transferId. | Change transferId and reinitiate. | Yes, with new transfer id. |

  #### 4XX errors

  | HTTP status code | Error code | Message | Next action |
  | :- | :- | :- | :- |
  | 400 | transfer\_id\_missing | transfer\_id is missing in the request | Enter a transfer\_id in the request. |
  | 400 | transfer\_id\_invalid | transfer\_id should be alphanumeric | Enter a valid transfer\_id. |
  | 400 | transfer\_amount\_invalid | transfer\_amount should be greater then 1.00 | Enter a transfer\_amount greater than 1.00. |
  | 400 | transfer\_amount\_missing | transfer\_amount is missing in the request | Enter a transfer\_amount in the request. |
  | 400 | transfer\_mode\_invalid | transfer\_mode is invalid allowed values are : bank, imps, neft, rtgs, upi, paytm, amazonpay, card and cardupi | Provide a valid transfer\_mode in the request. |
  | 400 | transfer\_mode\_invalid | transfer\_mode\_invalid	transfer\_mode is invalid allowed values are : bank, imps, neft, rtgs, upi, paytm, amazonpay, card and cardupi | Provide a valid transfer\_mode in the request. |
  | 400 | beneficiary\_details.beneficiary\_id\_invalid | beneficiary\_id should be alphanumeric | Provide a valid beneficiary\_id in the request. |
  | 400 | beneficiary\_details.beneficiary\_name\_invalid | beneficiary\_name is invalid. only alphabets and whitespaces are allowed | Provide a valid beneficiary\_name in the request. |
  | 400 | beneficiary\_details.beneficiary\_instrument\_details.bank\_account\_number\_invalid | bank\_account\_number should be alphanumeric | Provide a valid bank\_account\_number in the request |
  | 400 | beneficiary\_details.beneficiary\_instrument\_details.bank\_account\_number\_invalid | Bank account number passed in the request does not match with the beneficiary with beneficiary\_id :: test\_beneId | Provide the correct bank\_account\_number in the request. |
  | 400 | beneficiary\_details.beneficiary\_instrument\_details.bank\_ifsc\_invalid | bank\_ifsc should be in standard ifsc format | Provide a valid bank\_ifsc. |
  | 400 | beneficiary\_details.beneficiary\_instrument\_details.bank\_ifsc\_invalid | Bank ifsc passed in the request does not match with the beneficiary with beneficiary\_id :: test\_beneId | Provide the correct bank\_ifsc for the beneficiary. |
  | 400 | beneficiary\_details.beneficiary\_instrument\_details.vpa\_invalid | vpa is in invalid format | Provide a valid vpa. |
  | 400 | beneficiary\_details.beneficiary\_instrument\_details.vpa\_invalid | Vpa passed in the request does not match with the beneficiary with beneficiary\_id :: test\_beneId | Provide the correct vpa for the beneficiary. |
  | 404 | beneficiary\_not\_found | Beneficiary does not exist | Provide an existing beneficiary. |
</Accordion>

### Batch Transfer V2

<Accordion title="Click to view the response codes.">
  <br />

  | HTTP status code | Status | Status code | Status description | Next action | Try again via Cashfree - Yes or no |
  | :- | :- | :- | :- | :- | :- |
  | 200 | APPROVAL\_PENDING | VELOCITY\_CHECK\_FAILED | The transfer requires an approval as the count of transfers to a particular beneficiary etc have breached the limit. You can approve or reject the transfer request from the Cashfree [Merchant Dashboard](https://merchant.cashfree.com/auth/login). | You can approve/reject the transfer on the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and go to **Transfers > Approve** tab. Post the transfer is approved, the request is sent to the partner bank for further processing. | - |
  | 200 | APPROVAL\_PENDING | TRANSFER\_LIMIT\_BREACH | The transfer requires an approval as the transfer amount etc have breached the limit. You can approve or reject the transfer request from the Cashfree [Merchant Dashboard](https://merchant.cashfree.com/auth/login). | You can approve/reject the transfer on the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and go to **Transfers > Approve** tab. Post the transfer is approved, the request is sent to the partner bank for further processing. | - |
  | 200 | APPROVAL\_PENDING | APPROVAL\_PENDING | The transfer requires approval. You can approve or reject the transfer request from the Cashfree [Merchant Dashboard](https://merchant.cashfree.com/auth/login). | You can approve/reject the transfer on the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and go to **Transfers > Approve** tab. Post the transfer is approved, the request is sent to the partner bank for further processing. | - |
  | 200 | FAILED | WAIT\_TIME\_EXCEEDED | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | FAILED | BENE\_BANK\_DECLINED | The transfer has failed because the beneficiary bank has declined the transfer. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again with the partner bank(s). | - | Yes |
  | 200 | FAILED | IMPS\_MODE\_FAIL | The transfer has failed because the beneficiary account doesnot support IMPS transfers. This rejection is done by the partner bank for the specific beneficiary account. You can try NEFT or other channels to do the disbursals | You can try NEFT or other channels to do the disbursals. | Yes, via a different mode |
  | 200 | FAILED | SOURCE\_BANK\_DECLINED | The transfer has failed because our partner bank has declined the transfer because of their internal checks, technical declines etc. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again with other partner bank(s). | Yes |
  | 200 | FAILED | CONNECTION\_TIMEOUT | The transfer has failed because there was a connection timeout between the bank and Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again with the partner bank(s). | Yes |
  | 200 | FAILED | PAYOUT\_INTERNAL\_ERROR | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | - | Yes |
  | 200 | FAILED | NPCI\_UNAVAILABLE | The transfer has failed because NPCI was unavailable to complete the transfer request. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree. The success of the request is contingent on NPCI services being up. | - | Yes, after some time |
  | 200 | FAILED | DEST\_LIMIT\_REACHED | The transfer has failed because the beneficiary account has breached the limit of receiving funds. This rejection is done by the beneficiary bank for the specific beneficiary account. You can reinitiate the transfer after a while via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). The success of the request is contingent on beneficiary's limit being available to receive incoming funds. | - | Yes, after some time |
  | 200 | FAILED | RETURNED\_FROM\_BENEFICIARY | The transfer has failed because the beneficiary bank has returned the transfer and has not need able to credit funds to the end beneficiary. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again with the partner bank(s). | - | - |
  | 200 | FAILED | PAYOUT\_INTERNAL\_ERROR | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | - | - |
  | 200 | FAILED | INVALID\_BENE\_ACCOUNT\_OR\_IFSC | The transfer has failed because the beneficiary account or IFSC is invalid. After correcting the beneficiary account or IFSC, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | - | - |
  | 200 | FAILED | PAYOUT\_INTERNAL\_ERROR | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | - | - |
  | 200 | FAILED | FAILED | The transfer has failed because there was an intermittent issue at the partner bank's end. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after some time |
  | 200 | FAILED | PAYOUT\_INTERNAL\_ERROR | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | - | - |
  | 200 | FAILED | INSUFFICIENT\_BALANCE | The transfer has failed because of low balance in your Cashfree Wallet/ Bank Account. After recharging the account, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After recharging the account, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after recharging |
  | 200 | FAILED | INVALID\_BENE\_VPA | The transfer has failed because the beneficiary VPA is invalid. After correcting the VPA handle, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the VPA handle, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting the VPA handle |
  | 200 | FAILED | INVALID\_IFSC\_FAIL | The transfer has failed because the IFSC is invalid. After correcting the IFSC, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the IFSC, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting the IFSC |
  | 200 | FAILED | BAD\_GATEWAY | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | FAILED | INVALID\_AMOUNT\_FAIL | The transfer has failed because the amount entered is invalid. After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting the amount |
  | 200 | FAILED | INVALID\_ACCOUNT\_FAIL | The transfer has failed because the Account Number of the beneficiary is invalid, as per our partner bank. After correcting the account number, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the account number, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting the account number |
  | 200 | FAILED | INVALID\_REQUEST | The transfer has failed because the transfer request is invalid, as per our partner bank, because of exceeding the character limit of certain parameter, wrong input etc. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | - | - |
  | 200 | FAILED | ACCOUNT\_BLOCKED | The transfer has failed because the account is blocked, as per our partner bank. After getting the account unblocked, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After getting the account unblocked, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after unblocking the account number |
  | 200 | FAILED | DEBIT\_FAILURE | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | FAILED | BENEFICIARY\_BANK\_OFFLINE | The transfer has failed because the respective beneficiary bank is offline. After some time, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After some time, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | FAILED | AUTHENTICATION\_FAILURE | The transfer has failed because there was an authentication failure at the partner bank's end. After checking with the partner bank, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | This is a scenario when the API access is not working at the partner bank's end. After checking with the partner bank, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | FAILED | NRE\_ACCOUT\_FAIL | The transfer has failed because the beneficiary account is an NRE Account and transfers to NRE Accounts are not supported, as per our partner bank. | Get a new account(non-NRE account) from the beneficiary; you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | No |
  | 200 | FAILED | SOURCE\_LIMIT\_REACHED | The transfer has been failed by the partner bank as the source bank account has reached a limit of transferring funds. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | If you are on Cashfree Wallet, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). If you are on Connected Bank, you need to recharge your bank account and then reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after some time |
  | 200 | FAILED | BANK\_GATEWAY\_ERROR | The transfer has failed because there was an intermittent issue at the partner bank's end. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | FAILED | BAD\_REQUEST | The transfer has failed because the details of the transfer request is invalid, as per our partner bank. After correcting the details in the transfer request, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the details in the transfer request, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | FAILED | REINITIALIZE\_TRANSFER\_LATER | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | MANUALLY\_REJECTED | MANUALLY\_REJECTED | The transfer has failed because it has been manually rejected by the merchant or any team member user who has the permissions to do the same on merchant dashboard. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again with the partner bank(s). | If the merchant wants to reinitiate the transfer, they can reinitiate the transfer via Cashfree so that the transfer can be reattempted again with the partner bank(s). | Yes, if you want to reinitiate the transfer |
  | 200 | PENDING | SENT\_TO\_BANK | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. This has been sent to the bank by our banking operations team. Please do check statuses or await webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks | - |
  | 200 | PENDING | BANK\_GATEWAY\_ERROR | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. You should rely only on Check Status API response or Webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks | - |
  | 200 | PENDING | NO\_SUCH\_REQUEST | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. The bank is not able to find the request at their end as of now, and it has been sent to the bank by our banking operations team. Please do check statuses or await webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks | - |
  | 200 | PENDING | IN\_PROCESS | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. Please do check statuses or await webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks | - |
  | 200 | PENDING | ERROR\_FETCHING\_STATUS | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. The response received from the partner bank has a new code. This has been raised with the bank to understand the new code. Please do check statuses or await webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks | - |
  | 200 | PENDING | TRANSACTION\_PROCESSED | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. You should rely only on Check Status API response or Webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks | - |
  | 200 | PENDING | REQUEST\_TIMEDOUT | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. The bank is not able to find the request at their end as of now as the request between the partner bank has probably timed out, and it has been highlighted to the bank by our banking operations team. Please do check statuses or await webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks | - |
  | 200 | PENDING | DUPLICATE | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. The bank claims of receiving a duplicate request at their end as of now. You should rely only on Check Status API response or Webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks | - |
  | 200 | PENDING | PENDING | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. You should rely only on Check Status API response or Webhooks to know the terminal state of the transfer request. | | |
  | 200 | PENDING | SCHEDULED\_FOR\_NEXT\_WORKINGDAY | The transfer is currently in a Pending state, as the bank has scheduled the transfer for the next working day. This typically happens for NEFT/RTGS transfers if they are initiated beyond the cut-off hours or during bank holidays. You should rely only on Check Status API response or Webhooks to know the terminal state of the transfer request. | - | - |
  | 200 | PENDING | SUSPECT | The transfer is currently in a Pending state, as the bank has scheduled the transfer for the next working day. This typically happens for NEFT/RTGS transfers if they are initiated beyond the cut-off hours or during bank holidays. You should rely only on Check Status API response or Webhooks to know the terminal state of the transfer request. | - | - |
  | 200 | PENDING | IMPLEMENTATION\_ERROR | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. You should rely only on Check Status API response or Webhooks to know the terminal state of the transfer request. | - | - |
  | 200 | PENDING | UNKNOWN\_ERROR\_CODE | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. The response received from the partner bank has a new code. This has been raised with the bank to understand the new code. Please do check statuses or await webhooks to know the terminal state of the transfer request. | - | - |
  | 200 | QUEUED | QUEUED | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. You should rely only on Check Status API response or Webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks | - |
  | 200 | RECEIVED | RECEIVED | The transfer has been received by Cashfree successfully for further processing. You should use Check Status API response or Webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks | - |
  | 200 | REJECTED | BENE\_NOT\_EXIST | The transfer has been rejected because the beneficiary, added in the transfer request, does not exist. After adding the right beneficiary, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After adding the right beneficiary, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after adding the right beneficiary |
  | 200 | REJECTED | INSUFFICIENT\_BALANCE | The transfer has been rejected because of low balance in your Cashfree Wallet. After recharging the account, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After recharging the account, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after recharging |
  | 200 | REJECTED | INSIDE\_BLACKOUT\_WINDOW | The transfer has been rejected because the transfer falls under the blackout window defined by you in Payout Protect. You can reinitiate the transfer via Cashfree, after the blackout window or after modifying the blackout window from the [Merchant Dashboard](https://merchant.cashfree.com/merchants), so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree, after the blackout window or after modifying the blackout window from the [Merchant Dashboard](https://merchant.cashfree.com/merchants), so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | REJECTED | INVALID\_MODE\_FOR\_PYID | The transfer has been rejected because the payment instrument does not support this mode of transfer. You should get this mode activated on the payment instrument ID by contacting Cashfree, and then initiate a new transfer request. | You should get this mode activated on the payment instrument ID by contacting Cashfree, and then initiate a new transfer request. | Yes, after activating the mode. |
  | 200 | REJECTED | BENE\_BLACKLISTED | The transfer has been rejected because the beneficiary's bank account and/or VPA handles have been blacklisted by Risk team. You should get a different bank account and/or VPA to send the transfer, or you can connect with Cashfree Team to understand more about this. | You should get a different bank account and/or VPA to send the transfer, or you can connect with Cashfree Team to understand more about this. | Yes, after correcting the beneficiary details |
  | 200 | REJECTED | TRANSFER\_NOT\_ATTEMPTED | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | REJECTED | INVALID\_TRANSFER\_AMOUNT | The transfer has been rejected because the amount entered is invalid. After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s) | Yes, after correcting the amount |
  | 200 | REJECTED | TRANSFER\_LIMIT\_BREACH | The transfer has been rejected because the amount entered breaches the limits set for your payout account. After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). You can connect with Cashfree if you are not sure about the transfer limits set for your payout account. | After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). You can connect with Cashfree if you are not sure about the transfer limits set for your payout account. | Yes, after adhering to the transfer limits |
  | 200 | REJECTED | INVALID\_PAYMENT\_INSTRUMENT | The transfer has been rejected because the payment instrument (fundsource\_id parameter in the API request) used for attempting the transfer is invalid. After correcting the payment instrument, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | After correcting the payment instrument, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting the payment instrument |
  | 200 | REJECTED | PAYOUT\_INTERNAL\_ERROR | The transfer has been rejected because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | REJECTED | VELOCITY\_CHECK\_FAILED | The transfer has been rejected because the amount entered breaches the limits set for your payout account. After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). You can connect with Cashfree if you are not sure about the transfer limits set for your payout account. | After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). You can connect with Cashfree if you are not sure about the transfer limits set for your payout account. | Yes, after adhering to the transfer limit |
  | 200 | REJECTED | PAYOUT\_INTERNAL\_ERROR | The transfer has been rejected because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | REJECTED | PAYOUT\_INTERNAL\_ERROR | The transfer has been rejected because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | REJECTED | DISABLED\_MODE | The transfer has been rejected because your payout account does not support this mode of transfer. You should get this mode activated on your payout account by contacting Cashfree, and then initiate a new transfer request. | You should get this mode activated on your payout account by contacting Cashfree, and then initiate a new transfer request. | Yes, after activating the mode |
  | 200 | REJECTED | BANK\_ACCOUNT\_INVALID | The transfer has been rejected because there is a mismatch in the Bank Account Number of the beneficiary ID and the Bank Account Number in the transfer request. After correcting the Bank Account Number, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | After correcting the Bank Account Number, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting the bank account number |
  | 200 | REJECTED | BANK\_IFSC\_INVALID | The transfer has been rejected because there is a mismatch in the IFSC of the beneficiary ID and the IFSC in the transfer request. After correcting the IFSC, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | After correcting the IFSC, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting the IFSC |
  | 200 | REJECTED | VPA\_INVALID | The transfer has been rejected because there is a mismatch in the VPA handle of the beneficiary ID and the VPA handle in the transfer request. After correcting the VPA handle, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | After correcting the VPA handle, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting the VPA handle |
  | 200 | REJECTED | PHONE\_INVALID | The transfer has been rejected because there is a mismatch in the Phone Number of the beneficiary ID and the Phone Number in the transfer request. After correcting the Phone Number, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | After correcting the Phone Number, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting the phone number. |
  | 200 | REJECTED | BANK\_ACCOUNT\_DETAILS\_MISSING | The transfer has been rejected because the Bank Account Details are missing in the transfer request. After adding the Bank Account Details, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | After adding the Bank Account Details, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after adding the bank account details. |
  | 200 | REVERSED | ACCOUNT\_BLOCKED | The transfer has been reversed by the beneficiary bank as the end-beneficiary's account is blocked for receiving incoming funds. After correcting the account number or getting the account unblocked, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the account number or getting the account unblocked, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after adding the new details or getting the account unblocked |
  | 200 | REVERSED | FAILED | The transfer has been reversed by the beneficiary bank as they were unable to credit the end beneficiary's bank account. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | - | Yes |
  | 200 | REVERSED | NRE\_ACCOUNT\_FAIL | The transfer has been reversed by the beneficiary bank as they were unable to credit the end beneficiary's bank account as it is an NRE Account and transfers to NRE Accounts are not supported. | Get a new account(non-NRE account) from the beneficiary; you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | No |
  | 200 | REVERSED | RETURNED\_FROM\_BENEFICIARY | The transfer has been reversed by the beneficiary bank as they were unable to credit the end beneficiary's bank account. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | REVERSED | BENE\_BANK\_DECLINED | The transfer has been declined by the beneficiary bank and they were unable to credit the end beneficiary's bank account. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | REVERSED | IMPS\_MODE\_FAIL | The transfer has been reversed by the beneficiary bank because the beneficiary bank account doesnot support IMPS transfers. This rejection is done by the beneficiary bank for the specific beneficiary account. You can try NEFT or other channels to do the disbursals. | You can reinitiate the transfer via Cashfree by changing the mode so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after changing the mode |
  | 200 | REVERSED | DEST\_LIMIT\_REACHED | The transfer has been reversed by the beneficiary bank as the end-beneficiary's account has reached a limit of receiving incoming funds. This rejection is done by the beneficiary bank for the specific beneficiary account. You can reinitiate the transfer after a while via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). The success of the request is contingent on beneficiary's limit being available to receive incoming funds. | The limits on the beneficiary account are typically refreshed every 24 hours. Its not clear when the 24 hour window shall elpase so you can then reinitiate the transfer via Cashfree after some time so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after some time. |
  | 200 | REVERSED | INVALID\_ACCOUNT\_FAIL | The transfer has been reversed by the beneficiary bank because the Account Number of the beneficiary is invalid. After correcting the account number, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the account number, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting the account number |
  | 200 | REVERSED | BENE\_NAME\_DIFFERS | The transfer has been reversed by the beneficiary bank because the Account Name of the beneficiary is different. After correcting the beneficiary name, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the beneficiary name, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting the account name |
  | 200 | SUCCESS | SENT\_TO\_BENEFICIARY | The transfer has been initiated via the partner bank successfully. The request is waiting to be processed at the beneficiary bank to do the credit to the end beneficiary. | - | - |
  | 200 | SUCCESS | COMPLETED | The transfer has been initiated via the partner bank successfully, hence your account is debited and the request is successfully processed by the beneficiary bank and has been credited to the end beneficiary. | - | - |

  \| 200              | REJECTED          | TRANSFERID\_INVALID            | transferid can contain only alphabets, numbers, underscore (\_), hyphen (-). After correcting the transferid, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | After correcting the transferid, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting transfer id. |
  \| 200              | REJECTED          | AMOUNT\_INVALID                | amount can contain only numbers. After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be attempted. | After correcting the amount, you can reinitiate the transfer. | Yes, after correcting amount. |
  \| 200              | REJECTED          | REMARKS\_INVALID               | remarks can contain only alphabets, numbers and space. | After correcting the remarks, you can reinitiate the transfer. | Yes, after correcting remarks. |
  \| 200              | REJECTED          | BENEID\_INVALID                | beneId can contain only alphabets, numbers and underscore. | After correcting the beneId, you can reinitiate the transfer. | Yes, after correcting beneficiary id. |
  \| 200              | REJECTED          | NAME\_INVALID                  | name can contain only alphabets, numbers and space. | After correcting the name, you can reinitiate the transfer. | Yes, after correcting name. |
  \| 200              | REJECTED          | EMAIL\_INVALID                 | email is not a valid email format. | After correcting the email, you can reinitiate the transfer. | Yes, after correcting email. |
  \| 200              | REJECTED          | IBAN\_INVALID                  | iban can contain only alphabets and numbers. | After correcting the iban, you can reinitiate the transfer. | Yes, after correcting IBAN. |
  \| 200              | REJECTED          | TRANSFERMODE\_INVALID          | transferMode invalid (allowed: banktransfer, upi, paytm, amazonpay, imps, neft, rtgs, ppc). | After correcting the transferMode, you can reinitiate the transfer. | Yes, after correcting mode. |
  \| 200              | REJECTED          | CURRENCY\_INVALID              | currency is invalid. | After correcting the currency, you can reinitiate the transfer. | Yes, after correcting currency. |
  \| 200              | REJECTED          | ACCOUNT\_DOES\_NOT\_EXIST        | The transfer has been rejected because the beneficiary account/ VPA does not exist as per our partner bank. After correcting the account number/ VPA, you can reinitiate the transfer. | After correcting the account number / VPA, reinitiate the transfer. | Yes, after correcting details. |
  \| 200              | FAILED            | ACCOUNT\_DOES\_NOT\_EXIST        | The transfer has failed because the beneficiary account/ VPA does not exist as per our partner bank. After correcting the account number/ VPA, you can reinitiate the transfer. | After correcting the account number / VPA, reinitiate the transfer. | Yes, after correcting details. |
  \| 200              | REJECTED          | AMAZON\_AMOUNT\_EXCEED          | The amount entered breaches the limits set for the beneficiary's Amazon account. | After verifying the limits, reinitiate the transfer. | Yes, after verifying limits. |
  \| 200              | FAILED            | AMAZON\_AMOUNT\_EXCEED          | The amount entered breaches the limits set for the beneficiary's Amazon account. | After verifying the limits, reinitiate the transfer. | Yes, after verifying limits. |
  \| 200              | REJECTED          | ANOMALY\_DETECTION             | The transfer has been rejected as risk product detected an anomaly. | Reinitiate after validation at your end. | Yes, after validation. |
  \| 200              | APPROVAL\_PENDING  | ANOMALY\_DETECTION             | The transfer requires approval as risk product detected an anomaly. | Approve / reject on dashboard (Payout Protect). | - |
  \| 200              | FAILED            | BAD\_CONNECTION                | Intermittent internal error between Cashfree and partner bank. | Reinitiate the transfer. | Yes, after some time. |
  \| 200              | REJECTED          | BENE\_INVALID                  | Beneficiary in the request does not exist. | Add correct beneficiary then reinitiate. | Yes, after adding beneficiary. |
  \| 200              | FAILED            | BENE\_INVALID                  | Beneficiary in the request does not exist. | Add correct beneficiary then reinitiate. | Yes, after adding beneficiary. |
  \| 200              | FAILED            | BENE\_NOT\_REGISTERED           | Beneficiary not registered with partner bank. | Add correct beneficiary then reinitiate. | Yes, after adding beneficiary. |
  \| 200              | VALIDATION\_PENDING| BENE\_VERIFICATION\_PENDING     | Beneficiary verification pending; transfer will be attempted post validation. | Rely on Check Status API or webhooks. | - |
  \| 200              | FAILED            | BENEFICIARY\_BANK\_UNAVAILABLE  | Beneficiary bank offline. | Reinitiate after some time. | Yes, after some time. |
  \| 200              | FAILED            | BENEFICIARY\_NAME\_DIFFERS      | Beneficiary name differs per partner bank. | Add correct beneficiary then reinitiate. | Yes, after correcting name. |
  \| 200              | REJECTED          | BENEFICIARY\_NAME\_DIFFERS      | Beneficiary name differs per partner bank. | Add correct beneficiary then reinitiate. | Yes, after correcting name. |
  \| 200              | REJECTED          | BENEFICIARY\_NAME\_MISMATCH     | Beneficiary name differs per partner bank. | Add correct beneficiary then reinitiate. | Yes, after correcting name. |
  \| 200              | REJECTED          | CARD\_UNSUPPORTED              | Card not supported. | Change payment instrument then reinitiate. | Yes, after changing instrument. |
  \| 200              | FAILED            | CARD\_UNSUPPORTED              | Card not supported. | Change payment instrument then reinitiate. | Yes, after changing instrument. |
  \| 200              | FAILED            | DUPLICATE\_FAILED              | Bank claims duplicate request. | Reinitiate with different transfer id. | Yes, with new id. |
  \| 200              | FAILED            | ERROR\_RETRIEVING\_BALANCE      | Intermittent issue at partner bank retrieving balance. | Reinitiate after some time. | Yes, after some time. |
  \| 200              | REJECTED          | INVALID\_CARD                  | Card details not correct. | Enter correct card details then reinitiate. | Yes, after correcting card. |
  \| 200              | FAILED            | INVALID\_CARD                  | Card details not correct. | Enter correct card details then reinitiate. | Yes, after correcting card. |
  \| 200              | REJECTED          | INVALID\_CURRENCY\_FOR\_PYID     | Transfer currency not supported for payment instrument id. | Change currency to INR and reinitiate. | Yes, after changing currency. |
  \| 200              | FAILED            | INVALID\_CURRENCY\_FOR\_PYID     | Transfer currency not supported for payment instrument id. | Change currency to INR and reinitiate. | Yes, after changing currency. |
  \| 200              | FAILED            | INVALID\_MODE\_FAIL             | Transfer mode not supported for beneficiary account. | Change mode then reinitiate. | Yes, after changing mode. |
  \| 200              | REJECTED          | INVALID\_OR\_NO\_SUCH\_ACCOUNT\_TYPE | Beneficiary account type invalid / unsupported. | Get new account from beneficiary then reinitiate. | Yes, after new account. |
  \| 200              | FAILED            | INVALID\_OR\_NO\_SUCH\_ACCOUNT\_TYPE | Beneficiary account type invalid / unsupported. | Get new account from beneficiary then reinitiate. | Yes, after new account. |
  \| 200              | FAILED            | INVALID\_PHONE\_BENEFICIARY     | Phone number not linked to any VPA. | Add correct phone beneficiary then reinitiate. | Yes, after correcting phone. |
  \| 200              | REJECTED          | INVALID\_TRANSFER\_CURRENCY     | Transfer currency not supported. | Change currency to INR then reinitiate. | Yes, after changing currency. |
  \| 200              | FAILED            | INVALID\_TRANSFER\_CURRENCY     | Transfer currency not supported. | Change currency to INR then reinitiate. | Yes, after changing currency. |
  \| 200              | REJECTED          | KYC\_COMPLIANCE\_VERIFICATION\_FAILED | KYC verification failed. | Reinitiate after resolving KYC. | Yes, after KYC resolution. |
  \| 200              | REJECTED          | KYC\_REQUIREMENTS\_NOT\_SATISFIED | KYC requirements not satisfied. | Complete KYC then reinitiate. | Yes, after completing KYC. |
  \| 200              | FAILED            | LOAD\_LIMIT\_EXHAUSTED          | Beneficiary account reached max transaction amount limit. | Reinitiate after 24 hours. | Yes, after 24 hours. |
  \| 200              | FAILED            | LOAN\_FUND\_MOVEMENT\_FAILURE    | Intermittent issue at Cashfree. | Reinitiate transfer. | Yes, after some time. |
  \| 200              | PENDING           | LOW\_BALANCE\_QUEUED            | Balance in the fund source is exhausted; will auto process post recharge. | Recharge fund source; rely on status API/webhook. | - |
  \| 200              | REJECTED          | MANUALLY\_REJECTED             | Transfer manually rejected by you. | Reinitiate if required. | Yes, if needed. |
  \| 200              | REJECTED          | PAYOUT\_INACTIVE               | Payout account inactive. | Activate account then reinitiate. | Yes, after activation. |
  \| 200              | FAILED            | POOL\_CONNECTION\_TIMEOUT       | Connection issue with partner bank. | Reinitiate after some time. | Yes, after some time. |
  \| 200              | REJECTED          | QUICK\_TRANSFER\_DISABLED       | Quick transfer disabled for payout account. | Enable quick transfer then reinitiate. | Yes, after enabling. |
  \| 200              | REJECTED          | REJECTED                      | Transfer rejected (generic). | Review request and correct issues. | Yes, after correction. |
  \| 200              | REVERSED          | REVERSED                      | Transfer reversed by beneficiary bank; credit failed. | Reinitiate after correcting issue. | Yes, after correction. |
  \| 200              | FAILED            | RTGS\_MODE\_FAIL                | Beneficiary account does not support RTGS transfers. | Try NEFT or other channels. | Yes, via different mode. |
  \| 200              | FAILED            | SUSPECTED\_FAILED              | Partner bank suspects transfer is fraudulent. | Contact support / investigate before retry. | No (investigate). |
  \| 200              | REJECTED          | VBA\_TRANSFER\_DISABLED         | Transfers to virtual bank accounts not enabled. | Enable payouts to VBAs then reinitiate. | Yes, after enabling. |
  \| 200              | REJECTED          | ERROR\_SELECTING\_FUND\_SOURCE   | Issue with account configuration selecting fund source. | Contact care team; fix config then reinitiate. | Yes, after fixing config. |
  \| 200              | VALIDATION\_PENDING| VALIDATION\_PENDING            | Beneficiary verification pending; transfer will be attempted post validation. | Rely on Status API / webhooks. | - |
  \| 200              | REJECTED          | INVALID\_BENEFICIARY\_CODE      | Beneficiary code invalid. | Correct beneficiary code then reinitiate. | Yes, after correcting code. |
  \| 200              | REJECTED          | DUPLICATE\_TRANSFER            | Transfer already present / processed; duplicate transferId. | Change transferId and reinitiate. | Yes, with new transfer id. |

  #### 4XX errors

  | HTTP status code | Error code | Message | Next action |
  | :- | :- | :- | :- |
  | 400 | batch\_transfer\_id\_missing | batch\_transfer\_id\_missing is missing in the request | Enter a batch transfer ID in the request. |
  | 400 | batch\_transfer\_id\_invalid | batch\_transfer\_id\_invalid should be alphanumeric | Enter a valid batch transfer ID. |
  | 400 | transfers\[0].transfer\_id\_invalid | transfer\_id should be alphanumeric | Enter a valid transfer ID. |
  | 400 | transfers\[0].transfer\_id\_missing | transfer\_id is missing in the request | Enter a transfer ID in the request. |
  | 400 | transfers\[0].transfer\_amount\_invalid | transfer\_amount should be greater then 1.00 | Enter an amount greater than 1.00. |
  | 400 | transfers\[0].transfer\_amount\_missing | transfer\_amount is missing in the request | Enter a transfer amount in the request. |
  | 400 | transfers\[0].transfer\_mode\_invalid | transfer\_mode is invalid allowed values are : bank, imps, neft, rtgs, upi, paytm, amazonpay, card and cardupi | Enter a valid transfer mode. |
  | 400 | transfers\[0].beneficiary\_details.beneficiary\_id\_invalid | beneficiary\_id should be alphanumeric | Enter a valid beneficiary ID. |
  | 400 | transfers\[0].beneficiary\_details.beneficiary\_name\_invalid | beneficiary\_name is invalid. only alphabets and whitespaces are allowed | Enter a valid beneficiary name. |
  | 400 | transfers\[0].beneficiary\_details.beneficiary\_instrument\_details.bank\_account\_number\_invalid | bank\_account\_number should be alphanumeric | Enter a valid bank account number. |
  | 400 | transfers\[0].beneficiary\_details.beneficiary\_instrument\_details.bank\_ifsc\_invalid | bank\_ifsc should be in standard ifsc format | Enter a valid IFSC. |
  | 400 | transfers\[0].beneficiary\_details.beneficiary\_instrument\_details.vpa\_invalid | vpa is in invalid format | Enter a valid VPA. |
</Accordion>

### Get Batch Transfer Status V2

<Accordion title="Click to view the response codes.">
  | HTTP status code | Status | Status code | Status description | Next action | Try again via Cashfree - Yes or no |
  | :- | :- | :- | :- | :- | :- |
  | 200 | APPROVAL\_PENDING | VELOCITY\_CHECK\_FAILED | The transfer requires an approval as the count of transfers to a particular beneficiary etc have breached the limit. You can approve or reject the transfer request from the Cashfree [Merchant Dashboard](https://merchant.cashfree.com/auth/login). | You can approve/reject the transfer on the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and go to **Transfers > Approve** tab. Post the transfer is approved, the request is sent to the partner bank for further processing. | - |
  | 200 | APPROVAL\_PENDING | TRANSFER\_LIMIT\_BREACH | The transfer requires an approval as the transfer amount etc have breached the limit. You can approve or reject the transfer request from the Cashfree [Merchant Dashboard](https://merchant.cashfree.com/auth/login). | You can approve/reject the transfer on the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and go to **Transfers > Approve** tab. Post the transfer is approved, the request is sent to the partner bank for further processing. | - |
  | 200 | APPROVAL\_PENDING | APPROVAL\_PENDING | The transfer requires approval. You can approve or reject the transfer request from the Cashfree [Merchant Dashboard](https://merchant.cashfree.com/auth/login). | You can approve/reject the transfer on the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and go to **Transfers > Approve** tab. Post the transfer is approved, the request is sent to the partner bank for further processing. | - |
  | 200 | APPROVAL\_PENDING | ANOMALY\_DETECTION | The transfer requires approval as it is a high risk transaction detected by Payout Protect model.  You can approve or reject the transfer request from the Cashfree [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and go to **Payout Protect > Risky Transfers > Flagged Transfers** | You can approve/reject the transfer on the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and go to **Payout Protect > Risky Transfers > Flagged Transfers** tab. Post the transfer is approved, the request is sent to the partner bank for further processing. | |
  | 200 | FAILED | WAIT\_TIME\_EXCEEDED | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | FAILED | BENE\_BANK\_DECLINED | The transfer has failed because the beneficiary bank has declined the transfer. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again with the partner bank(s). | - | Yes |
  | 200 | FAILED | IMPS\_MODE\_FAIL | The transfer has failed because the beneficiary account doesnot support IMPS transfers. This rejection is done by the partner bank for the specific beneficiary account. You can try NEFT or other channels to do the disbursals. | You can try NEFT or other channels to do the disbursals. | Yes, via a different mode |
  | 200 | FAILED | SOURCE\_BANK\_DECLINED | The transfer has failed because our partner bank has declined the transfer because of their internal checks, technical declines etc. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again with other partner bank(s). | Yes |
  | 200 | FAILED | CONNECTION\_TIMEOUT | The transfer has failed because there was a connection timeout between the bank and Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again with the partner bank(s). | Yes |
  | 200 | FAILED | PAYOUT\_INTERNAL\_ERROR | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | - | Yes |
  | 200 | FAILED | NPCI\_UNAVAILABLE | The transfer has failed because NPCI was unavailable to complete the transfer request. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree. The success of the request is contingent on NPCI services being up. | - | Yes, after some time |
  | 200 | FAILED | DEST\_LIMIT\_BREACHED | The transfer has failed because the beneficiary account has breached the limit of receiving funds. This rejection is done by the beneficiary bank for the specific beneficiary account. You can reinitiate the transfer after a while via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). The success of the request is contingent on beneficiary's limit being available to receive incoming funds. | - | Yes, after some time |
  | 200 | FAILED | RETURNED\_FROM\_BENEFICIARY | The transfer has failed because the beneficiary bank has returned the transfer and has not need able to credit funds to the end beneficiary. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again with the partner bank(s). | - | - |
  | 200 | FAILED | PAYOUT\_INTERNAL\_ERROR | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | - | - |
  | 200 | FAILED | INVALID\_BENE\_ACCOUNT\_OR\_IFSC | The transfer has failed because the beneficiary account or IFSC is invalid. After correcting the beneficiary account or IFSC, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | - | - |
  | 200 | FAILED | PAYOUT\_INTERNAL\_ERROR | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | - | - |
  | 200 | FAILED | FAILED | The transfer has failed because there was an intermittent issue at the partner bank's end. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after some time |
  | 200 | FAILED | PAYOUT\_INTERNAL\_ERROR | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | - | - |
  | 200 | FAILED | INSUFFICIENT\_BALANCE | The transfer has failed because of low balance in your Cashfree Wallet/ Bank Account. After recharging the account, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After recharging the account, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after recharging |
  | 200 | FAILED | INVALID\_BENE\_VPA | The transfer has failed because the beneficiary VPA is invalid. After correcting the VPA handle, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the VPA handle, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting the VPA handle |
  | 200 | FAILED | INVALID\_IFSC\_FAIL | The transfer has failed because the IFSC is invalid. After correcting the IFSC, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the IFSC, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting the IFSC |
  | 200 | FAILED | BAD\_GATEWAY | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | FAILED | INVALID\_AMOUNT\_FAIL | The transfer has failed because the amount entered is invalid. After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting the amount. |
  | 200 | FAILED | INVALID\_ACCOUNT\_FAIL | The transfer has failed because the Account Number of the beneficiary is invalid, as per our partner bank. After correcting the account number, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the account number, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting the account number |
  | 200 | FAILED | INVALID\_REQUEST | The transfer has failed because the transfer request is invalid, as per our partner bank, because of exceeding the character limit of certain parameter, wrong input etc. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | - | - |
  | 200 | FAILED | ACCOUNT\_BLOCKED | The transfer has failed because the account is blocked, as per our partner bank. After getting the account unblocked, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After getting the account unblocked, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after unblocking the account |
  | 200 | FAILED | DEBIT\_FAILURE | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | FAILED | BENEFICIARY\_BANK\_OFFLINE | The transfer has failed because the respective beneficiary bank is offline. After some time, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After some time, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | FAILED | AUTHENTICATION\_FAILURE | The transfer has failed because there was an authentication failure at the partner bank's end. After checking with the partner bank, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | This is a scenario when the API access is not working at the partner bank's end. After checking with the partner bank, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | FAILED | NRE\_ACCOUNT\_FAIL | The transfer has failed because the beneficiary account is an NRE Account and transfers to NRE Accounts are not supported, as per our partner bank. | Get a new account(non-NRE account) from the beneficiary; you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | No |
  | 200 | FAILED | SOURCE\_LIMIT\_REACHED | The transfer has been failed by the partner bank as the source bank account has reached a limit of transferring funds. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | If you are on Cashfree Wallet, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). If you are on Connected Bank, you need to recharge your bank account and then reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after some time |
  | 200 | FAILED | BANK\_GATEWAY\_ERROR | The transfer has failed because there was an intermittent issue at the partner bank's end. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | FAILED | BAD\_REQUEST | The transfer has failed because the details of the transfer request is invalid, as per our partner bank. After correcting the details in the transfer request, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the details in the transfer request, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | FAILED | REINITIALIZE\_TRANSFER\_LATER | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | MANUALLY\_REJECTED | MANUALLY\_REJECTED | The transfer has failed because it has been manually rejected by the merchant or any team member user who has the permissions to do the same on [Merchant Dashboard](https://merchant.cashfree.com/merchants). You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again with the partner bank(s). | If the merchant wants to reinitiate the transfer, they can reinitiate the transfer via Cashfree so that the transfer can be reattempted again with the partner bank(s). | Yes, if you want to reinitiate the transfer |
  | 200 | PENDING | SENT\_TO\_BANK | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. This has been sent to the bank by our banking operations team. Please do check statuses or await webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks | - |
  | 200 | PENDING | BANK\_GATEWAY\_ERROR | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. You should rely only on Check Status API response or Webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks | - |
  | 200 | PENDING | NO\_SUCH\_REQUEST | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. The bank is not able to find the request at their end as of now, and it has been sent to the bank by our banking operations team. Please do check statuses or await webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks | - |
  | 200 | PENDING | IN\_PROCESS | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. Please do check statuses or await webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks | - |
  | 200 | PENDING | ERROR\_FETCHING\_STATUS | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. The response received from the partner bank has a new code. This has been raised with the bank to understand the new code. Please do check statuses or await webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks | - |
  | 200 | PENDING | TRANSACTION\_PROCESSED | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. You should rely only on Check Status API response or Webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks | - |
  | 200 | PENDING | REQUEST\_TIMEOUT | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. The bank is not able to find the request at their end as of now as the request between the partner bank has probably timed out, and it has been highlighted to the bank by our banking operations team. Please do check statuses or await webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks | - |
  | 200 | PENDING | DUPLICATE | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. The bank claims of receiving a duplicate request at their end as of now. You should rely only on Check Status API response or Webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks | - |
  | 200 | PENDING | PENDING | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. You should rely only on Check Status API response or Webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks | - |
  | 200 | PENDING | SCHEDULED\_FOR\_NEXT\_WORKINGDAY | The transfer is currently in a Pending state, as the bank has scheduled the transfer for the next working day. This typically happens for NEFT/RTGS transfers if they are initiated beyond the cut-off hours or during bank holidays. You should rely only on Check Status API response or Webhooks to know the terminal state of the transfer request. | - | - |
  | 200 | PENDING | SUSPECT | The transfer is currently in a Pending state, as the bank has scheduled the transfer for the next working day. This typically happens for NEFT/RTGS transfers if they are initiated beyond the cut-off hours or during bank holidays. You should rely only on Check Status API response or Webhooks to know the terminal state of the transfer request. | - | - |
  | 200 | PENDING | IMPLEMENTATION\_ERROR | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. You should rely only on Check Status API response or Webhooks to know the terminal state of the transfer request. | - | - |
  | 200 | PENDING | UNKNOWN\_ERROR\_CODE | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. The response received from the partner bank has a new code. This has been raised with the bank to understand the new code. Please do check statuses or await webhooks to know the terminal state of the transfer request. | - | - |
  | 200 | QUEUED | QUEUED | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. You should rely only on Check Status API response or Webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks | - |
  | 200 | RECEIVED | RECEIVED | The transfer has been received by Cashfree successfully for further processing. You should use Check Status API response or Webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks | - |
  | 200 | REJECTED | BENE\_NOT\_EXIST | The transfer has been rejected because the beneficiary, added in the transfer request, does not exist. After adding the right beneficiary, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After adding the right beneficiary, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after adding the correct beneficiary |
  | 200 | REJECTED | INSUFFICIENT\_BALANCE | The transfer has been rejected because of low balance in your Cashfree Wallet. After recharging the account, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After recharging the account, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after recharging |
  | 200 | REJECTED | INSIDE\_BLACKOUT\_WINDOW | The transfer has been rejected because the transfer falls under the blackout window defined by you in Payout Protect. You can reinitiate the transfer via Cashfree, after the blackout window or after modifying the blackout window from the [Merchant Dashboard](https://merchant.cashfree.com/merchants), so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree, after the blackout window or after modifying the blackout window from the [Merchant Dashboard](https://merchant.cashfree.com/merchants), so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | REJECTED | INVALID\_MODE\_FOR\_PYID | The transfer has been rejected because the payment instrument does not support this mode of transfer. You should get this mode activated on the payment instrument ID by contacting Cashfree, and then initiate a new transfer request. | You should get this mode activated on the payment instrument ID by contacting Cashfree, and then initiate a new transfer request. | Yes, after activating the mode |
  | 200 | REJECTED | BENE\_BLACKLISTED | The transfer has been rejected because the beneficiary's bank account and/or VPA handles have been blacklisted by Risk team. You should get a different bank account and/or VPA to send the transfer, or you can connect with Cashfree Team to understand more about this. | You should get a different bank account and/or VPA to send the transfer, or you can connect with Cashfree Team to understand more about this. | Yes, after correcting beneficiary details |
  | 200 | REJECTED | TRANSFER\_NOT\_ATTEMPTED | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | REJECTED | INVALID\_TRANSFER\_AMOUNT | The transfer has been rejected because the amount entered is invalid. After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting the amount |
  | 200 | REJECTED | TRANSFER\_LIMIT\_BREACH | The transfer has been rejected because the amount entered breaches the limits set for your payout account. After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). You can connect with Cashfree if you are not sure about the transfer limits set for your payout account. | After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). You can connect with Cashfree if you are not sure about the transfer limits set for your payout account. | Yes, after adhering to the transfer limits |
  | 200 | REJECTED | INVALID\_PAYMENT\_INSTRUMENT | The transfer has been rejected because the payment instrument (fundsource\_id parameter in the API request) used for attempting the transfer is invalid. After correcting the payment instrument, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | After correcting the payment instrument, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting payment instrument details |
  | 200 | REJECTED | PAYOUT\_INTERNAL\_ERROR | The transfer has been rejected because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | REJECTED | VELOCITY\_CHECK\_FAILED | The transfer has been rejected because the amount entered breaches the limits set for your payout account. After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). You can connect with Cashfree if you are not sure about the transfer limits set for your payout account. | After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). You can connect with Cashfree if you are not sure about the transfer limits set for your payout account. | Yes, after adhering to the transfer limits |
  | 200 | REJECTED | PAYOUT\_INTERNAL\_ERROR | The transfer has been rejected because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | REJECTED | PAYOUT\_INTERNAL\_ERROR | The transfer has been rejected because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | REJECTED | DISABLED\_MODE | The transfer has been rejected because your payout account does not support this mode of transfer. You should get this mode activated on your payout account by contacting Cashfree, and then initiate a new transfer request. | You should get this mode activated on your payout account by contacting Cashfree, and then initiate a new transfer request. | Yes, after activating the mode. |
  | 200 | REJECTED | BANK\_ACCOUNT\_INVALID | The transfer has been rejected because there is a mismatch in the Bank Account Number of the beneficiary ID and the Bank Account Number in the transfer request. After correcting the Bank Account Number, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | After correcting the Bank Account Number, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting the bank account number |
  | 200 | REJECTED | BANK\_IFSC\_INVALID | The transfer has been rejected because there is a mismatch in the IFSC of the beneficiary ID and the IFSC in the transfer request. After correcting the IFSC, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | After correcting the IFSC, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting the IFSC information |
  | 200 | REJECTED | VPA\_INVALID | The transfer has been rejected because there is a mismatch in the VPA handle of the beneficiary ID and the VPA handle in the transfer request. After correcting the VPA handle, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | After correcting the VPA handle, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting the VPA information. |
  | 200 | REJECTED | PHONE\_INVALID | The transfer has been rejected because there is a mismatch in the Phone Number of the beneficiary ID and the Phone Number in the transfer request. After correcting the Phone Number, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | After correcting the Phone Number, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting the phone number. |
  | 200 | REJECTED | BANK\_ACCOUNT\_DETAILS\_MISSING | The transfer has been rejected because the Bank Account Details are missing in the transfer request. After adding the Bank Account Details, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | After adding the Bank Account Details, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after adding the bank account details. |
  | 200 | REVERSED | ACCOUNT\_BLOCKED | The transfer has been reversed by the beneficiary bank as the end-beneficiary's account is blocked for receiving incoming funds. After correcting the account number or getting the account unblocked, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the account number or getting the account unblocked, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after adding new details or getting account unblocked |
  | 200 | REVERSED | FAILED | The transfer has been reversed by the beneficiary bank as they were unable to credit the end beneficiary's bank account. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | - | Yes |
  | 200 | REVERSED | NRE\_ACCOUNT\_FAIL | The transfer has been reversed by the beneficiary bank as they were unable to credit the end beneficiary's bank account as it is an NRE Account and transfers to NRE Accounts are not supported. | Get a new account(non-NRE account) from the beneficiary; you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | No |
  | 200 | REVERSED | RETURENED\_FROM\_BENEFICIARY | The transfer has been reversed by the beneficiary bank as they were unable to credit the end beneficiary's bank account. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | REVERSED | BENE\_BANK\_DECLINED | The transfer has been declined by the beneficiary bank and they were unable to credit the end beneficiary's bank account. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | REVERSED | IMPS\_MODE\_FAIL | The transfer has been reversed by the beneficiary bank because the beneficiary bank account doesnot support IMPS transfers. This rejection is done by the beneficiary bank for the specific beneficiary account. You can try NEFT or other channels to do the disbursals. | You can reinitiate the transfer via Cashfree by changing the mode so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after changing the mode. |
  | 200 | REVERSED | DEST\_LIMIT\_REACHED | The transfer has been reversed by the beneficiary bank as the end-beneficiary's account has reached a limit of receiving incoming funds. This rejection is done by the beneficiary bank for the specific beneficiary account. You can reinitiate the transfer after a while via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). The success of the request is contingent on beneficiary's limit being available to receive incoming funds. | The limits on the beneficiary account are typically refreshed every 24 hours. Its not clear when the 24 hour window shall elpase so you can then reinitiate the transfer via Cashfree after some time so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after some time. |
  | 200 | REVERSED | INVALID\_ACCOUNT\_FAIL | The transfer has been reversed by the beneficiary bank because the Account Number of the beneficiary is invalid. After correcting the account number, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the account number, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting the account number. |
  | 200 | REVERSED | BENE\_NAME\_DIFFERS | The transfer has been reversed by the beneficiary bank because the Account Name of the beneficiary is different. After correcting the beneficiary name, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the beneficiary name, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting the account name. |
  | 200 | SUCCESS | SENT\_TO\_BENEFICIARY | The transfer has been initiated via the partner bank successfully. The request is waiting to be processed at the beneficiary bank to do the credit to the end beneficiary. | - | - |
  | 200 | SUCCESS | COMPLETED | The transfer has been initiated via the partner bank successfully, hence your account is debited and the request is successfully processed by the beneficiary bank and has been credited to the end beneficiary. | - | - |

  \| 200              | REJECTED          | TRANSFERID\_INVALID            | transferid can contain only alphabets, numbers, underscore (\_), hyphen (-). After correcting the transferid, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | After correcting the transferid, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting transfer id. |
  \| 200              | REJECTED          | AMOUNT\_INVALID                | amount can contain only numbers. After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be attempted. | After correcting the amount, you can reinitiate the transfer. | Yes, after correcting amount. |
  \| 200              | REJECTED          | REMARKS\_INVALID               | remarks can contain only alphabets, numbers and space. | After correcting the remarks, you can reinitiate the transfer. | Yes, after correcting remarks. |
  \| 200              | REJECTED          | BENEID\_INVALID                | beneId can contain only alphabets, numbers and underscore. | After correcting the beneId, you can reinitiate the transfer. | Yes, after correcting beneficiary id. |
  \| 200              | REJECTED          | NAME\_INVALID                  | name can contain only alphabets, numbers and space. | After correcting the name, you can reinitiate the transfer. | Yes, after correcting name. |
  \| 200              | REJECTED          | EMAIL\_INVALID                 | email is not a valid email format. | After correcting the email, you can reinitiate the transfer. | Yes, after correcting email. |
  \| 200              | REJECTED          | IBAN\_INVALID                  | iban can contain only alphabets and numbers. | After correcting the iban, you can reinitiate the transfer. | Yes, after correcting IBAN. |
  \| 200              | REJECTED          | TRANSFERMODE\_INVALID          | transferMode invalid (allowed: banktransfer, upi, paytm, amazonpay, imps, neft, rtgs, ppc). | After correcting the transferMode, you can reinitiate the transfer. | Yes, after correcting mode. |
  \| 200              | REJECTED          | CURRENCY\_INVALID              | currency is invalid. | After correcting the currency, you can reinitiate the transfer. | Yes, after correcting currency. |
  \| 200              | REJECTED          | ACCOUNT\_DOES\_NOT\_EXIST        | The transfer has been rejected because the beneficiary account/ VPA does not exist as per our partner bank. After correcting the account number/ VPA, you can reinitiate the transfer. | After correcting the account number / VPA, reinitiate the transfer. | Yes, after correcting details. |
  \| 200              | FAILED            | ACCOUNT\_DOES\_NOT\_EXIST        | The transfer has failed because the beneficiary account/ VPA does not exist as per our partner bank. After correcting the account number/ VPA, you can reinitiate the transfer. | After correcting the account number / VPA, reinitiate the transfer. | Yes, after correcting details. |
  \| 200              | REJECTED          | AMAZON\_AMOUNT\_EXCEED          | The amount entered breaches the limits set for the beneficiary's Amazon account. | After verifying the limits, reinitiate the transfer. | Yes, after verifying limits. |
  \| 200              | FAILED            | AMAZON\_AMOUNT\_EXCEED          | The amount entered breaches the limits set for the beneficiary's Amazon account. | After verifying the limits, reinitiate the transfer. | Yes, after verifying limits. |
  \| 200              | REJECTED          | ANOMALY\_DETECTION             | The transfer has been rejected as risk product detected an anomaly. | Reinitiate after validation at your end. | Yes, after validation. |
  \| 200              | APPROVAL\_PENDING  | ANOMALY\_DETECTION             | The transfer requires approval as risk product detected an anomaly. | Approve / reject on dashboard (Payout Protect). | - |
  \| 200              | FAILED            | BAD\_CONNECTION                | Intermittent internal error between Cashfree and partner bank. | Reinitiate the transfer. | Yes, after some time. |
  \| 200              | REJECTED          | BENE\_INVALID                  | Beneficiary in the request does not exist. | Add correct beneficiary then reinitiate. | Yes, after adding beneficiary. |
  \| 200              | FAILED            | BENE\_INVALID                  | Beneficiary in the request does not exist. | Add correct beneficiary then reinitiate. | Yes, after adding beneficiary. |
  \| 200              | FAILED            | BENE\_NOT\_REGISTERED           | Beneficiary not registered with partner bank. | Add correct beneficiary then reinitiate. | Yes, after adding beneficiary. |
  \| 200              | VALIDATION\_PENDING| BENE\_VERIFICATION\_PENDING     | Beneficiary verification pending; transfer will be attempted post validation. | Rely on Check Status API or webhooks. | - |
  \| 200              | FAILED            | BENEFICIARY\_BANK\_UNAVAILABLE  | Beneficiary bank offline. | Reinitiate after some time. | Yes, after some time. |
  \| 200              | FAILED            | BENEFICIARY\_NAME\_DIFFERS      | Beneficiary name differs per partner bank. | Add correct beneficiary then reinitiate. | Yes, after correcting name. |
  \| 200              | REJECTED          | BENEFICIARY\_NAME\_DIFFERS      | Beneficiary name differs per partner bank. | Add correct beneficiary then reinitiate. | Yes, after correcting name. |
  \| 200              | REJECTED          | BENEFICIARY\_NAME\_MISMATCH     | Beneficiary name differs per partner bank. | Add correct beneficiary then reinitiate. | Yes, after correcting name. |
  \| 200              | REJECTED          | CARD\_UNSUPPORTED              | Card not supported. | Change payment instrument then reinitiate. | Yes, after changing instrument. |
  \| 200              | FAILED            | CARD\_UNSUPPORTED              | Card not supported. | Change payment instrument then reinitiate. | Yes, after changing instrument. |
  \| 200              | FAILED            | DUPLICATE\_FAILED              | Bank claims duplicate request. | Reinitiate with different transfer id. | Yes, with new id. |
  \| 200              | FAILED            | ERROR\_RETRIEVING\_BALANCE      | Intermittent issue at partner bank retrieving balance. | Reinitiate after some time. | Yes, after some time. |
  \| 200              | REJECTED          | INVALID\_CARD                  | Card details not correct. | Enter correct card details then reinitiate. | Yes, after correcting card. |
  \| 200              | FAILED            | INVALID\_CARD                  | Card details not correct. | Enter correct card details then reinitiate. | Yes, after correcting card. |
  \| 200              | REJECTED          | INVALID\_CURRENCY\_FOR\_PYID     | Transfer currency not supported for payment instrument id. | Change currency to INR and reinitiate. | Yes, after changing currency. |
  \| 200              | FAILED            | INVALID\_CURRENCY\_FOR\_PYID     | Transfer currency not supported for payment instrument id. | Change currency to INR and reinitiate. | Yes, after changing currency. |
  \| 200              | FAILED            | INVALID\_MODE\_FAIL             | Transfer mode not supported for beneficiary account. | Change mode then reinitiate. | Yes, after changing mode. |
  \| 200              | REJECTED          | INVALID\_OR\_NO\_SUCH\_ACCOUNT\_TYPE | Beneficiary account type invalid / unsupported. | Get new account from beneficiary then reinitiate. | Yes, after new account. |
  \| 200              | FAILED            | INVALID\_OR\_NO\_SUCH\_ACCOUNT\_TYPE | Beneficiary account type invalid / unsupported. | Get new account from beneficiary then reinitiate. | Yes, after new account. |
  \| 200              | FAILED            | INVALID\_PHONE\_BENEFICIARY     | Phone number not linked to any VPA. | Add correct phone beneficiary then reinitiate. | Yes, after correcting phone. |
  \| 200              | REJECTED          | INVALID\_TRANSFER\_CURRENCY     | Transfer currency not supported. | Change currency to INR then reinitiate. | Yes, after changing currency. |
  \| 200              | FAILED            | INVALID\_TRANSFER\_CURRENCY     | Transfer currency not supported. | Change currency to INR then reinitiate. | Yes, after changing currency. |
  \| 200              | REJECTED          | KYC\_COMPLIANCE\_VERIFICATION\_FAILED | KYC verification failed. | Reinitiate after resolving KYC. | Yes, after KYC resolution. |
  \| 200              | REJECTED          | KYC\_REQUIREMENTS\_NOT\_SATISFIED | KYC requirements not satisfied. | Complete KYC then reinitiate. | Yes, after completing KYC. |
  \| 200              | FAILED            | LOAD\_LIMIT\_EXHAUSTED          | Beneficiary account reached max transaction amount limit. | Reinitiate after 24 hours. | Yes, after 24 hours. |
  \| 200              | FAILED            | LOAN\_FUND\_MOVEMENT\_FAILURE    | Intermittent issue at Cashfree. | Reinitiate transfer. | Yes, after some time. |
  \| 200              | PENDING           | LOW\_BALANCE\_QUEUED            | Balance in the fund source is exhausted; will auto process post recharge. | Recharge fund source; rely on status API/webhook. | - |
  \| 200              | REJECTED          | MANUALLY\_REJECTED             | Transfer manually rejected by you. | Reinitiate if required. | Yes, if needed. |
  \| 200              | REJECTED          | PAYOUT\_INACTIVE               | Payout account inactive. | Activate account then reinitiate. | Yes, after activation. |
  \| 200              | FAILED            | POOL\_CONNECTION\_TIMEOUT       | Connection issue with partner bank. | Reinitiate after some time. | Yes, after some time. |
  \| 200              | REJECTED          | QUICK\_TRANSFER\_DISABLED       | Quick transfer disabled for payout account. | Enable quick transfer then reinitiate. | Yes, after enabling. |
  \| 200              | REJECTED          | REJECTED                      | Transfer rejected (generic). | Review request and correct issues. | Yes, after correction. |
  \| 200              | REVERSED          | REVERSED                      | Transfer reversed by beneficiary bank; credit failed. | Reinitiate after correcting issue. | Yes, after correction. |
  \| 200              | FAILED            | RTGS\_MODE\_FAIL                | Beneficiary account does not support RTGS transfers. | Try NEFT or other channels. | Yes, via different mode. |
  \| 200              | FAILED            | SUSPECTED\_FAILED              | Partner bank suspects transfer is fraudulent. | Contact support / investigate before retry. | No (investigate). |
  \| 200              | REJECTED          | VBA\_TRANSFER\_DISABLED         | Transfers to virtual bank accounts not enabled. | Enable payouts to VBAs then reinitiate. | Yes, after enabling. |
  \| 200              | REJECTED          | ERROR\_SELECTING\_FUND\_SOURCE   | Issue with account configuration selecting fund source. | Contact care team; fix config then reinitiate. | Yes, after fixing config. |
  \| 200              | VALIDATION\_PENDING| VALIDATION\_PENDING            | Beneficiary verification pending; transfer will be attempted post validation. | Rely on Status API / webhooks. | - |
  \| 200              | REJECTED          | INVALID\_BENEFICIARY\_CODE      | Beneficiary code invalid. | Correct beneficiary code then reinitiate. | Yes, after correcting code. |
  \| 200              | REJECTED          | DUPLICATE\_TRANSFER            | Transfer already present / processed; duplicate transferId. | Change transferId and reinitiate. | Yes, with new transfer id. |

  #### 4XX errors

  | HTTP status code | Error code | Message | Next action |
  | :- | :- | :- | :- |
  | 404 | batch\_transfer\_id\_not\_found | batch\_transfer\_id does not exist | Enter an existing batch transfer ID. |
  | 404 | cf\_batch\_transfer\_id\_invalid | cf\_batch\_transfer\_id does not exist | Enter an existing cf batch transfer ID. |
</Accordion>


# Self Withdrawal
Source: https://www.cashfree.com/docs/api-reference/payouts/v2/self-withdrawal

post /payout/v1/selfWithdrawal
Use this API to request a self withdrawal at Cashfree. Self withdrawal is allowed a maximum of 3 times a day. The API response will either result in an ERROR or SUCCESS response. The status of the withdrawal request is available on the dashboard.



# Standard Transfer Async
Source: https://www.cashfree.com/docs/api-reference/payouts/v2/standard-transfer-async

post /payout/v1/requestAsyncTransfer
Use this API to initiate an amount transfer request at Cashfree by providing beneficiary id, amount, and transfer id. This is an async transfer request.



# Standard Transfer Async v1.2
Source: https://www.cashfree.com/docs/api-reference/payouts/v2/standard-transfer-async-v12

post /payout/v1.2/requestAsyncTransfer
Use this API to initiate an amount transfer request at Cashfree by providing beneficiary id, amount, and transfer id. This is an async transfer request.



# Standard Transfer Sync
Source: https://www.cashfree.com/docs/api-reference/payouts/v2/standard-transfer-sync

post /payout/v1/requestTransfer
Use this API to initiate an amount transfer request at Cashfree by providing beneficiary id, amount, and transfer id. This is a sync transfer request.



# Standard Transfer Sync v1.2
Source: https://www.cashfree.com/docs/api-reference/payouts/v2/standard-transfer-sync-v12

post /payout/v1.2/requestTransfer
Use this API to initiate an amount transfer request at Cashfree by providing beneficiary id, amount, and transfer id. This is a sync transfer request.



# Batch Transfer V2
Source: https://www.cashfree.com/docs/api-reference/payouts/v2/transfers-v2/batch-transfer-v2

post /transfers/batch
Use this API to initiate a batch transfer request at Cashfree. You can transfer money to multiple beneficiaries. The batch transfer limit is 5,000 in the production environment and 1,000 by default in the test environment.

<Warning>
  **5XX error**<br />
  When you get a 5XX response, don't initiate another transaction.<br />
  Check the status of the batch transfer using Get Batch Transfer Status V2 and then proceed further.
</Warning>

<Note>
  **Get Transfer Status**<br />
  Use the [Get Batch Transfer Status V2](/docs/api-reference/payouts/v2/transfers-v2/get-batch-transfer-status-v2) API to get the status of the batch transfer request. The Get Transfer Status V2 API does not give you the status of the batch transfer requests.
</Note>

<Accordion title="Click to view the response codes.">
  <br />

  | HTTP status code | Status | Status code | Status description | Next action | Try again via Cashfree - Yes or no |
  | :- | :- | :- | :- | :- | :- |
  | 200 | APPROVAL\_PENDING | VELOCITY\_CHECK\_FAILED | The transfer requires an approval as the count of transfers to a particular beneficiary etc, have breached the limit. You can approve or reject the transfer request from the [Merchant Dashboard](https://merchant.cashfree.com/auth/login). | You can approve/reject the transfer on the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and go to **Transfers > Approve** tab. Post the transfer is approved, the request is sent to the partner bank for further processing. | - |
  | 200 | APPROVAL\_PENDING | TRANSFER\_LIMIT\_BREACH | The transfer requires approval as the transfer amount etc, has breached the limit. You can approve or reject the transfer request from the [Merchant Dashboard](https://merchant.cashfree.com/auth/login). | You can approve/reject the transfer on the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and go to **Transfers > Approve** tab. Post the transfer is approved, the request is sent to the partner bank for further processing. | - |
  | 200 | APPROVAL\_PENDING | APPROVAL\_PENDING | The transfer requires approval. You can approve or reject the transfer request from the [Merchant Dashboard](https://merchant.cashfree.com/auth/login). | You can approve/reject the transfer on the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and go to **Transfers > Approve** tab. Post the transfer is approved, the request is sent to the partner bank for further processing. | - |
  | 200 | APPROVAL\_PENDING | ANOMALY\_DETECTION | The transfer requires approval as it is a high risk transaction detected by the Payout Protect model. You can approve or reject the transfer request from the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and go to **Payout Protect > Risky Transfers > Flagged Transfers** | You can approve/reject the transfer on the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and go to **Payout Protect > Risky Transfers > Flagged Transfers** tab. Post the transfer is approved, the request is sent to the partner bank for further processing. | - |
  | 200 | APPROVAL\_PENDING | RISK\_CHECK\_MANUAL\_REVIEW\_REQ | The transfer requires approval as it has been flagged by the Payout Protect risk model for manual review. You can approve or reject the transfer request from the [Merchant Dashboard](https://merchant.cashfree.com/auth/login). | Approve/reject the transfer on the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and go to **Payout Protect > Risky Transfers > Flagged Transfers** tab. | - |
  | 200 | APPROVAL\_PENDING | RISK\_CHECK\_ANOMALY\_DETECTED | The transfer requires approval as it has been flagged by the Payout Protect risk model for manual review due to anomaly detection. You can approve or reject the transfer request from the [Merchant Dashboard](https://merchant.cashfree.com/auth/login). | Approve/reject the transfer on the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and go to **Payout Protect > Risky Transfers > Flagged Transfers** tab. | - |
  | 200 | APPROVAL\_PENDING | RISK\_CHECK\_BENEFICIARY\_HIGH\_RISK | The transfer requires approval as the beneficiary has been identified as high risk by the Payout Protect model. You can approve or reject the transfer request from the [Merchant Dashboard](https://merchant.cashfree.com/auth/login). | Approve/reject the transfer on the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and go to **Payout Protect > Risky Transfers > Flagged Transfers** tab. | - |
  | 200 | APPROVAL\_PENDING | RISK\_CHECK\_VELOCITY\_THRESHOLD | The transfer requires approval as it breaches the velocity threshold set in the Payout Protect rules. You can approve or reject the transfer request from the [Merchant Dashboard](https://merchant.cashfree.com/auth/login). | Approve/reject the transfer on the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and go to **Payout Protect > Risky Transfers > Flagged Transfers** tab. | - |
  | 200 | APPROVAL\_PENDING | RISK\_CHECK\_TIME\_WINDOW\_BREACH | The transfer requires approval as it falls outside the allowed time window defined in the Payout Protect rules. You can approve or reject the transfer request from the [Merchant Dashboard](https://merchant.cashfree.com/auth/login). | Approve/reject the transfer on the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and go to **Payout Protect > Risky Transfers > Flagged Transfers** tab. | - |
  | 200 | APPROVAL\_PENDING | RISK\_CHECK\_AMOUNT\_THRESHOLD | The transfer requires approval as it exceeds the amount threshold set in the Payout Protect rules. You can approve or reject the transfer request from the [Merchant Dashboard](https://merchant.cashfree.com/auth/login). | Approve/reject the transfer on the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and go to **Payout Protect > Risky Transfers > Flagged Transfers** tab. | - |
  | 200 | APPROVAL\_PENDING | HIGH\_RISK\_BENEFICIARY | The transfer requires approval as the beneficiary is identified as high risk. You can approve or reject the transfer request from the [Merchant Dashboard](https://merchant.cashfree.com/auth/login). | Approve/reject the transfer on the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and go to **Payout Protect > Risky Transfers > Flagged Transfers** tab. | - |
  | 200 | APPROVAL\_PENDING | UNUSUAL\_ACTIVITY\_DETECTED | The transfer requires approval as unusual activity has been detected in the transfer pattern. You can approve or reject the transfer request from the [Merchant Dashboard](https://merchant.cashfree.com/auth/login). | Approve/reject the transfer on the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and go to **Payout Protect > Risky Transfers > Flagged Transfers** tab. | - |
  | 200 | APPROVAL\_PENDING | BLACKOUT\_WINDOW\_RULE | The transfer requires approval as it falls within the blackout window defined in the Payout Protect rules. You can approve or reject the transfer request from the [Merchant Dashboard](https://merchant.cashfree.com/auth/login). | Approve/reject the transfer on the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and go to **Payout Protect > Risky Transfers > Flagged Transfers** tab. | - |
  | 200 | APPROVAL\_PENDING | CUSTOM\_RULE\_TRIGGERED | The transfer requires approval as it has triggered a custom rule defined in the Payout Protect settings. You can approve or reject the transfer request from the [Merchant Dashboard](https://merchant.cashfree.com/auth/login). | Approve/reject the transfer on the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and go to **Payout Protect > Risky Transfers > Flagged Transfers** tab. | - |
  | 200 | APPROVAL\_PENDING | MANUAL\_APPROVAL\_REQUIRED | The transfer requires manual approval as per the configured workflow. You can approve or reject the transfer request from the [Merchant Dashboard](https://merchant.cashfree.com/auth/login). | Approve/reject the transfer on the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and go to **Transfers > Approve** tab. | - |
  | 200 | APPROVAL\_PENDING | COMPLIANCE\_REVIEW\_PENDING | The transfer requires approval as it is pending compliance review. You can approve or reject the transfer request from the [Merchant Dashboard](https://merchant.cashfree.com/auth/login). | Approve/reject the transfer on the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and go to **Transfers > Approve** tab. | - |
  | 200 | FAILED | WAIT\_TIME\_EXCEEDED | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | FAILED | BENE\_BANK\_DECLINED | The transfer has failed because the beneficiary bank has declined the transfer. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again with the partner bank(s). | - | Yes |
  | 200 | FAILED | IMPS\_MODE\_FAIL | The transfer has failed because the beneficiary account does not support IMPS transfers. This rejection is done by the partner bank for the specific beneficiary account. You can try NEFT or other channels to do the disbursals | You can try NEFT or other channels to do the disbursals. | Yes, via a different mode |
  | 200 | FAILED | SOURCE\_BANK\_DECLINED | The transfer has failed because our partner bank has declined the transfer because of their internal checks, technical declines etc. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again with other partner bank(s). | Yes |
  | 200 | FAILED | CONNECTION\_TIMEOUT | The transfer has failed because there was a connection timeout between the bank and Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again with the partner bank(s). | Yes |
  | 200 | FAILED | PAYOUT\_INTERNAL\_ERROR | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | - | Yes |
  | 200 | FAILED | NPCI\_UNAVAILABLE | The transfer has failed because NPCI was unavailable to complete the transfer request. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree. The success of the request is contingent on NPCI services being up. | - | Yes, after some time |
  | 200 | FAILED | DEST\_LIMIT\_REACHED | The transfer has failed because the beneficiary account has breached the limit of receiving funds. This rejection is done by the beneficiary bank for the specific beneficiary account. You can reinitiate the transfer after a while via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). The success of the request is contingent on beneficiary's limit being available to receive incoming funds. | - | Yes, after some time |
  | 200 | FAILED | RETURNED\_FROM\_BENEFICIARY | The transfer has failed because the beneficiary bank has returned the transfer and has not need able to credit funds to the end beneficiary. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again with the partner bank(s). | - | - |
  | 200 | FAILED | PAYOUT\_INTERNAL\_ERROR | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | - | - |
  | 200 | FAILED | INVALID\_BENE\_ACCOUNT\_OR\_IFSC | The transfer has failed because the beneficiary account or IFSC is invalid. After correcting the beneficiary account or IFSC, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | - | - |
  | 200 | FAILED | PAYOUT\_INTERNAL\_ERROR | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | - | - |
  | 200 | FAILED | FAILED | The transfer has failed because there was an intermittent issue at the partner bank's end. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after some time |
  | 200 | FAILED | PAYOUT\_INTERNAL\_ERROR | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | - | - |
  | 200 | FAILED | INSUFFICIENT\_BALANCE | The transfer has failed because of low balance in your Cashfree Wallet/ Bank Account. After recharging the account, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After recharging the account, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after recharging |
  | 200 | FAILED | INVALID\_BENE\_VPA | The transfer has failed because the beneficiary VPA is invalid. After correcting the VPA handle, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the VPA handle, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting the VPA handle |
  | 200 | FAILED | INVALID\_IFSC\_FAIL | The transfer has failed because the IFSC is invalid. After correcting the IFSC, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the IFSC, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting the IFSC |
  | 200 | FAILED | BAD\_GATEWAY | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | FAILED | INVALID\_AMOUNT\_FAIL | The transfer has failed because the amount entered is invalid. After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting the amount |
  | 200 | FAILED | INVALID\_ACCOUNT\_FAIL | The transfer has failed because the Account Number of the beneficiary is invalid, as per our partner bank. After correcting the account number, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the account number, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting the account number |
  | 200 | FAILED | INVALID\_REQUEST | The transfer has failed because the transfer request is invalid, as per our partner bank, because of exceeding the character limit of certain parameter, wrong input etc. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | - | - |
  | 200 | FAILED | ACCOUNT\_BLOCKED | The transfer has failed because the account is blocked, as per our partner bank. After getting the account unblocked, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After getting the account unblocked, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after unblocking the account number |
  | 200 | FAILED | DEBIT\_FAILURE | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | FAILED | BENEFICIARY\_BANK\_OFFLINE | The transfer has failed because the respective beneficiary bank is offline. After some time, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After some time, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | FAILED | AUTHENTICATION\_FAILURE | The transfer has failed because there was an authentication failure at the partner bank's end. After checking with the partner bank, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | This is a scenario when the API access is not working at the partner bank's end. After checking with the partner bank, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | FAILED | NRE\_ACCOUNT\_FAIL | The transfer has failed because the beneficiary account is an NRE Account and transfers to NRE Accounts are not supported, as per our partner bank. | Get a new account(non-NRE account) from the beneficiary; you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | No |
  | 200 | FAILED | SOURCE\_LIMIT\_REACHED | The transfer has been failed by the partner bank as the source bank account has reached a limit of transferring funds. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | If you are on Cashfree Wallet, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). If you are on Connected Bank, you need to recharge your bank account and then reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after some time |
  | 200 | FAILED | BANK\_GATEWAY\_ERROR | The transfer has failed because there was an intermittent issue at the partner bank's end. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | FAILED | BAD\_REQUEST | The transfer has failed because the details of the transfer request is invalid, as per our partner bank. After correcting the details in the transfer request, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the details in the transfer request, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | FAILED | REINITIALIZE\_TRANSFER\_LATER | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | MANUALLY\_REJECTED | MANUALLY\_REJECTED | The transfer has failed because it has been manually rejected by the merchant or any team member user who has the permissions to do the same on [Merchant Dashboard](https://merchant.cashfree.com/auth/login). You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again with the partner bank(s). | If the merchant wants to reinitiate the transfer, they can reinitiate the transfer via Cashfree so that the transfer can be reattempted again with the partner bank(s). | Yes, if you want to reinitiate the transfer |
  | 200 | PENDING | SENT\_TO\_BANK | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. This has been sent to the bank by our banking operations team. Please do check statuses or await webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks | - |
  | 200 | PENDING | BANK\_GATEWAY\_ERROR | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. You should rely only on Check Status API response or Webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks | - |
  | 200 | PENDING | NO\_SUCH\_REQUEST | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. The bank is not able to find the request at their end as of now, and it has been sent to the bank by our banking operations team. Please do check statuses or await webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks | - |
  | 200 | PENDING | IN\_PROCESS | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. Please do check statuses or await webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks | - |
  | 200 | PENDING | ERROR\_FETCHING\_STATUS | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. The response received from the partner bank has a new code. This has been raised with the bank to understand the new code. Please do check statuses or await webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks | - |
  | 200 | PENDING | TRANSACTION\_PROCESSED | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. You should rely only on Check Status API response or Webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks | - |
  | 200 | PENDING | REQUEST\_TIMEDOUT | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. The bank is not able to find the request at their end as of now as the request between the partner bank has probably timed out, and it has been highlighted to the bank by our banking operations team. Please do check statuses or await webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks | - |
  | 200 | PENDING | DUPLICATE | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. The bank claims of receiving a duplicate request at their end as of now. You should rely only on Check Status API response or Webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks | - |
  | 200 | PENDING | PENDING | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. You should rely only on Check Status API response or Webhooks to know the terminal state of the transfer request. | | |
  | 200 | PENDING | SCHEDULED\_FOR\_NEXT\_WORKINGDAY | The transfer is currently in a Pending state, as the bank has scheduled the transfer for the next working day. This typically happens for NEFT/RTGS transfers if they are initiated beyond the cut-off hours or during bank holidays. You should rely only on Check Status API response or Webhooks to know the terminal state of the transfer request. | - | - |
  | 200 | PENDING | SUSPECT | The transfer is currently in a Pending state, as the bank has scheduled the transfer for the next working day. This typically happens for NEFT/RTGS transfers if they are initiated beyond the cut-off hours or during bank holidays. You should rely only on Check Status API response or Webhooks to know the terminal state of the transfer request. | - | - |
  | 200 | PENDING | IMPLEMENTATION\_ERROR | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. You should rely only on Check Status API response or Webhooks to know the terminal state of the transfer request. | - | - |
  | 200 | PENDING | UNKNOWN\_ERROR\_CODE | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. The response received from the partner bank has a new code. This has been raised with the bank to understand the new code. Please do check statuses or await webhooks to know the terminal state of the transfer request. | - | - |
  | 200 | QUEUED | QUEUED | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. You should rely only on Check Status API response or Webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks | - |
  | 200 | RECEIVED | RECEIVED | The transfer has been received by Cashfree successfully for further processing. You should use Check Status API response or Webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks | - |
  | 200 | REJECTED | BENE\_NOT\_EXIST | The transfer has been rejected because the beneficiary, added in the transfer request, does not exist. After adding the right beneficiary, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After adding the right beneficiary, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after adding the right beneficiary |
  | 200 | REJECTED | INSUFFICIENT\_BALANCE | The transfer has been rejected because of low balance in your Cashfree Wallet. After recharging the account, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After recharging the account, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after recharging |
  | 200 | REJECTED | INSIDE\_BLACKOUT\_WINDOW | The transfer has been rejected because the transfer falls under the blackout window defined by you in Payout Protect. You can reinitiate the transfer via Cashfree, after the blackout window or after modifying the blackout window from the [Merchant Dashboard](https://merchant.cashfree.com/auth/login), so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree, after the blackout window or after modifying the blackout window from the [Merchant Dashboard](https://merchant.cashfree.com/auth/login), so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | REJECTED | INVALID\_MODE\_FOR\_PYID | The transfer has been rejected because the payment instrument does not support this mode of transfer. You should get this mode activated on the payment instrument ID by contacting Cashfree, and then initiate a new transfer request. | You should get this mode activated on the payment instrument ID by contacting Cashfree, and then initiate a new transfer request. | Yes, after activating the mode. |
  | 200 | REJECTED | BENE\_BLACKLISTED | The transfer has been rejected because the beneficiary's bank account and/or VPA handles have been blacklisted by Risk team. You should get a different bank account and/or VPA to send the transfer, or you can connect with Cashfree Team to understand more about this. | You should get a different bank account and/or VPA to send the transfer, or you can connect with Cashfree Team to understand more about this. | Yes, after correcting the beneficiary details |
  | 200 | REJECTED | TRANSFER\_NOT\_ATTEMPTED | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | REJECTED | INVALID\_TRANSFER\_AMOUNT | The transfer has been rejected because the amount entered is invalid. After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s) | Yes, after correcting the amount |
  | 200 | REJECTED | TRANSFER\_LIMIT\_BREACH | The transfer has been rejected because the amount entered breaches the limits set for your payout account. After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). You can connect with Cashfree if you are not sure about the transfer limits set for your payout account. | After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). You can connect with Cashfree if you are not sure about the transfer limits set for your payout account. | Yes, after adhering to the transfer limits |
  | 200 | REJECTED | INVALID\_PAYMENT\_INSTRUMENT | The transfer has been rejected because the payment instrument (fundsource\_id parameter in the API request) used for attempting the transfer is invalid. After correcting the payment instrument, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | After correcting the payment instrument, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting the payment instrument |
  | 200 | REJECTED | PAYOUT\_INTERNAL\_ERROR | The transfer has been rejected because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | REJECTED | VELOCITY\_CHECK\_FAILED | The transfer has been rejected because the amount entered breaches the limits set for your payout account. After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). You can connect with Cashfree if you are not sure about the transfer limits set for your payout account. | After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). You can connect with Cashfree if you are not sure about the transfer limits set for your payout account. | Yes, after adhering to the transfer limit |
  | 200 | REJECTED | PAYOUT\_INTERNAL\_ERROR | The transfer has been rejected because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | REJECTED | PAYOUT\_INTERNAL\_ERROR | The transfer has been rejected because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | REJECTED | DISABLED\_MODE | The transfer has been rejected because your payout account does not support this mode of transfer. You should get this mode activated on your payout account by contacting Cashfree, and then initiate a new transfer request. | You should get this mode activated on your payout account by contacting Cashfree, and then initiate a new transfer request. | Yes, after activating the mode |
  | 200 | REJECTED | BANK\_ACCOUNT\_INVALID | The transfer has been rejected because there is a mismatch in the Bank Account Number of the beneficiary ID and the Bank Account Number in the transfer request. After correcting the Bank Account Number, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | After correcting the Bank Account Number, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting the bank account number |
  | 200 | REJECTED | BANK\_IFSC\_INVALID | The transfer has been rejected because there is a mismatch in the IFSC of the beneficiary ID and the IFSC in the transfer request. After correcting the IFSC, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | After correcting the IFSC, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting the IFSC |
  | 200 | REJECTED | VPA\_INVALID | The transfer has been rejected because there is a mismatch in the VPA handle of the beneficiary ID and the VPA handle in the transfer request. After correcting the VPA handle, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | After correcting the VPA handle, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting the VPA handle |
  | 200 | REJECTED | PHONE\_INVALID | The transfer has been rejected because there is a mismatch in the Phone Number of the beneficiary ID and the Phone Number in the transfer request. After correcting the Phone Number, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | After correcting the Phone Number, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting the phone number. |
  | 200 | REJECTED | BANK\_ACCOUNT\_DETAILS\_MISSING | The transfer has been rejected because the Bank Account Details are missing in the transfer request. After adding the Bank Account Details, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | After adding the Bank Account Details, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after adding the bank account details. |
  | 200 | REVERSED | ACCOUNT\_BLOCKED | The transfer has been reversed by the beneficiary bank as the end-beneficiary's account is blocked for receiving incoming funds. After correcting the account number or getting the account unblocked, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the account number or getting the account unblocked, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after adding the new details or getting the account unblocked |
  | 200 | REVERSED | FAILED | The transfer has been reversed by the beneficiary bank as they were unable to credit the end beneficiary's bank account. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | - | Yes |
  | 200 | REVERSED | NRE\_ACCOUNT\_FAIL | The transfer has been reversed by the beneficiary bank as they were unable to credit the end beneficiary's bank account as it is an NRE Account and transfers to NRE Accounts are not supported. | Get a new account(non-NRE account) from the beneficiary; you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | No |
  | 200 | REVERSED | RETURNED\_FROM\_BENEFICIARY | The transfer has been reversed by the beneficiary bank as they were unable to credit the end beneficiary's bank account. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | REVERSED | BENE\_BANK\_DECLINED | The transfer has been declined by the beneficiary bank and they were unable to credit the end beneficiary's bank account. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | REVERSED | IMPS\_MODE\_FAIL | The transfer has been reversed by the beneficiary bank because the beneficiary bank account does not support IMPS transfers. This rejection is done by the beneficiary bank for the specific beneficiary account. You can try NEFT or other channels to do the disbursals. | You can reinitiate the transfer via Cashfree by changing the mode so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after changing the mode |
  | 200 | REVERSED | DEST\_LIMIT\_REACHED | The transfer has been reversed by the beneficiary bank as the end-beneficiary's account has reached a limit of receiving incoming funds. This rejection is done by the beneficiary bank for the specific beneficiary account. You can reinitiate the transfer after a while via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). The success of the request is contingent on beneficiary's limit being available to receive incoming funds. | The limits on the beneficiary account are typically refreshed every 24 hours. Its not clear when the 24 hour window shall elpase so you can then reinitiate the transfer via Cashfree after some time so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after some time. |
  | 200 | REVERSED | INVALID\_ACCOUNT\_FAIL | The transfer has been reversed by the beneficiary bank because the Account Number of the beneficiary is invalid. After correcting the account number, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the account number, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting the account number |
  | 200 | REVERSED | BENE\_NAME\_DIFFERS | The transfer has been reversed by the beneficiary bank because the Account Name of the beneficiary is different. After correcting the beneficiary name, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the beneficiary name, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting the account name |
  | 200 | SUCCESS | SENT\_TO\_BENEFICIARY | The transfer has been initiated via the partner bank successfully. The request is waiting to be processed at the beneficiary bank to do the credit to the end beneficiary. | - | - |
  | 200 | SUCCESS | COMPLETED | The transfer has been initiated via the partner bank successfully, hence your account is debited and the request is successfully processed by the beneficiary bank and has been credited to the end beneficiary. | - | - |

  #### 4XX errors

  | HTTP status code | Error code | Message | Next action |
  | :- | :- | :- | :- |
  | 400 | batch\_transfer\_id\_missing | batch\_transfer\_id\_missing is missing in the request | Enter a batch transfer ID in the request. |
  | 400 | batch\_transfer\_id\_invalid | batch\_transfer\_id\_invalid should be alphanumeric | Enter a valid batch transfer ID. |
  | 400 | transfers\[0].transfer\_id\_invalid | transfer\_id should be alphanumeric | Enter a valid transfer ID. |
  | 400 | transfers\[0].transfer\_id\_missing | transfer\_id is missing in the request | Enter a transfer ID in the request. |
  | 400 | transfers\[0].transfer\_amount\_invalid | transfer\_amount should be greater then 1.00 | Enter an amount greater than 1.00. |
  | 400 | transfers\[0].transfer\_amount\_missing | transfer\_amount is missing in the request | Enter a transfer amount in the request. |
  | 400 | transfers\[0].transfer\_mode\_invalid | transfer\_mode is invalid allowed values are : bank, imps, neft, rtgs, upi, paytm, amazonpay, card and cardupi | Enter a valid transfer mode. |
  | 400 | transfers\[0].beneficiary\_details.beneficiary\_id\_invalid | beneficiary\_id should be alphanumeric | Enter a valid beneficiary ID. |
  | 400 | transfers\[0].beneficiary\_details.beneficiary\_name\_invalid | beneficiary\_name is invalid. only alphabets and whitespaces are allowed | Enter a valid beneficiary name. |
  | 400 | transfers\[0].beneficiary\_details.beneficiary\_instrument\_details.bank\_account\_number\_invalid | bank\_account\_number should be alphanumeric | Enter a valid bank account number. |
  | 400 | transfers\[0].beneficiary\_details.beneficiary\_instrument\_details.bank\_ifsc\_invalid | bank\_ifsc should be in standard ifsc format | Enter a valid IFSC. |
  | 400 | transfers\[0].beneficiary\_details.beneficiary\_instrument\_details.vpa\_invalid | vpa is in invalid format | Enter a valid VPA. |
</Accordion>


# Get Batch Transfer Status V2
Source: https://www.cashfree.com/docs/api-reference/payouts/v2/transfers-v2/get-batch-transfer-status-v2

get /transfers/batch
Use this API to get the status of the initiated batch transfer. You can use either the batch_transfer_id or cf_batch_transfer_id to fetch the details.

<Note>
  To check the status of batch transfers, use the [Get Batch Transfer Status API](/docs/api-reference/payouts/v2/transfers-v2/get-batch-transfer-status-v2). Do not use the Get Transfer Status API; it applies only to individual transfers and may not provide accurate results for batch transactions.
</Note>

<Accordion title="Click to view the response codes.">
  | HTTP status code | Status | Status code | Status description | Next action | Try again via Cashfree - Yes or no |
  | :- | :- | :- | :- | :- | :- |
  | 200 | APPROVAL\_PENDING | VELOCITY\_CHECK\_FAILED | The transfer requires an approval as the count of transfers to a particular beneficiary etc have breached the limit. You can approve or reject the transfer request from the Cashfree [Merchant Dashboard](https://merchant.cashfree.com/auth/login). | You can approve/reject the transfer on the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and go to **Transfers > Approve** tab. Post the transfer is approved, the request is sent to the partner bank for further processing. | - |
  | 200 | APPROVAL\_PENDING | TRANSFER\_LIMIT\_BREACH | The transfer requires an approval as the transfer amount etc have breached the limit. You can approve or reject the transfer request from the Cashfree [Merchant Dashboard](https://merchant.cashfree.com/auth/login). | You can approve/reject the transfer on the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and go to **Transfers > Approve** tab. Post the transfer is approved, the request is sent to the partner bank for further processing. | - |
  | 200 | APPROVAL\_PENDING | APPROVAL\_PENDING | The transfer requires approval. You can approve or reject the transfer request from the Cashfree [Merchant Dashboard](https://merchant.cashfree.com/auth/login). | You can approve/reject the transfer on the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and go to **Transfers > Approve** tab. Post the transfer is approved, the request is sent to the partner bank for further processing. | - |
  | 200 | APPROVAL\_PENDING | ANOMALY\_DETECTION | The transfer requires approval as it is a high risk transaction detected by Payout Protect model.  You can approve or reject the transfer request from the Cashfree [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and go to **Payout Protect > Risky Transfers > Flagged Transfers** | You can approve/reject the transfer on the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and go to **Payout Protect > Risky Transfers > Flagged Transfers** tab. Post the transfer is approved, the request is sent to the partner bank for further processing. | |
  | 200 | APPROVAL\_PENDING | RISK\_CHECK\_MANUAL\_REVIEW\_REQ | The transfer requires approval as it has been flagged by the Payout Protect risk model for manual review. You can approve or reject the transfer request from the Cashfree Merchant Dashboard. | Approve/reject the transfer on the Merchant Dashboard and go to **Payout Protect > Risky Transfers > Flagged Transfers** tab. | - |
  | 200 | APPROVAL\_PENDING | RISK\_CHECK\_ANOMALY\_DETECTED | The transfer requires approval as it has been flagged by the Payout Protect risk model for manual review due to anomaly detection. You can approve or reject the transfer request from the Cashfree Merchant Dashboard. | Approve/reject the transfer on the Merchant Dashboard and go to **Payout Protect > Risky Transfers > Flagged Transfers** tab. | - |
  | 200 | APPROVAL\_PENDING | RISK\_CHECK\_BENEFICIARY\_HIGH\_RISK | The transfer requires approval as the beneficiary has been identified as high risk by the Payout Protect model. You can approve or reject the transfer request from the Cashfree Merchant Dashboard. | Approve/reject the transfer on the Merchant Dashboard and go to **Payout Protect > Risky Transfers > Flagged Transfers** tab. | - |
  | 200 | APPROVAL\_PENDING | RISK\_CHECK\_VELOCITY\_THRESHOLD | The transfer requires approval as it breaches the velocity threshold set in the Payout Protect rules. You can approve or reject the transfer request from the Cashfree Merchant Dashboard. | Approve/reject the transfer on the Merchant Dashboard and go to **Payout Protect > Risky Transfers > Flagged Transfers** tab. | - |
  | 200 | APPROVAL\_PENDING | RISK\_CHECK\_TIME\_WINDOW\_BREACH | The transfer requires approval as it falls outside the allowed time window defined in the Payout Protect rules. You can approve or reject the transfer request from the Cashfree Merchant Dashboard. | Approve/reject the transfer on the Merchant Dashboard and go to **Payout Protect > Risky Transfers > Flagged Transfers** tab. | - |
  | 200 | APPROVAL\_PENDING | RISK\_CHECK\_AMOUNT\_THRESHOLD | The transfer requires approval as it exceeds the amount threshold set in the Payout Protect rules. You can approve or reject the transfer request from the Cashfree Merchant Dashboard. | Approve/reject the transfer on the Merchant Dashboard and go to **Payout Protect > Risky Transfers > Flagged Transfers** tab. | - |
  | 200 | APPROVAL\_PENDING | HIGH\_RISK\_BENEFICIARY | The transfer requires approval as the beneficiary is identified as high risk. You can approve or reject the transfer request from the Cashfree Merchant Dashboard. | Approve/reject the transfer on the Merchant Dashboard and go to **Payout Protect > Risky Transfers > Flagged Transfers** tab. | - |
  | 200 | APPROVAL\_PENDING | UNUSUAL\_ACTIVITY\_DETECTED | The transfer requires approval as unusual activity has been detected in the transfer pattern. You can approve or reject the transfer request from the Cashfree Merchant Dashboard. | Approve/reject the transfer on the Merchant Dashboard and go to **Payout Protect > Risky Transfers > Flagged Transfers** tab. | - |
  | 200 | APPROVAL\_PENDING | BLACKOUT\_WINDOW\_RULE | The transfer requires approval as it falls within the blackout window defined in the Payout Protect rules. You can approve or reject the transfer request from the Cashfree Merchant Dashboard. | Approve/reject the transfer on the Merchant Dashboard and go to **Payout Protect > Risky Transfers > Flagged Transfers** tab. | - |
  | 200 | APPROVAL\_PENDING | CUSTOM\_RULE\_TRIGGERED | The transfer requires approval as it has triggered a custom rule defined in the Payout Protect settings. You can approve or reject the transfer request from the Cashfree Merchant Dashboard. | Approve/reject the transfer on the Merchant Dashboard and go to **Payout Protect > Risky Transfers > Flagged Transfers** tab. | - |
  | 200 | APPROVAL\_PENDING | MANUAL\_APPROVAL\_REQUIRED | The transfer requires manual approval as per the configured workflow. You can approve or reject the transfer request from the Cashfree Merchant Dashboard. | Approve/reject the transfer on the Merchant Dashboard and go to **Transfers > Approve** tab. | - |
  | 200 | APPROVAL\_PENDING | COMPLIANCE\_REVIEW\_PENDING | The transfer requires approval as it is pending compliance review. You can approve or reject the transfer request from the Cashfree Merchant Dashboard. | Approve/reject the transfer on the Merchant Dashboard and go to **Transfers > Approve** tab. | - |
  | 200 | FAILED | WAIT\_TIME\_EXCEEDED | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | FAILED | BENE\_BANK\_DECLINED | The transfer has failed because the beneficiary bank has declined the transfer. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again with the partner bank(s). | - | Yes |
  | 200 | FAILED | IMPS\_MODE\_FAIL | The transfer has failed because the beneficiary account doesnot support IMPS transfers. This rejection is done by the partner bank for the specific beneficiary account. You can try NEFT or other channels to do the disbursals. | You can try NEFT or other channels to do the disbursals. | Yes, via a different mode |
  | 200 | FAILED | SOURCE\_BANK\_DECLINED | The transfer has failed because our partner bank has declined the transfer because of their internal checks, technical declines etc. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again with other partner bank(s). | Yes |
  | 200 | FAILED | CONNECTION\_TIMEOUT | The transfer has failed because there was a connection timeout between the bank and Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again with the partner bank(s). | Yes |
  | 200 | FAILED | PAYOUT\_INTERNAL\_ERROR | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | - | Yes |
  | 200 | FAILED | NPCI\_UNAVAILABLE | The transfer has failed because NPCI was unavailable to complete the transfer request. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree. The success of the request is contingent on NPCI services being up. | - | Yes, after some time |
  | 200 | FAILED | DEST\_LIMIT\_BREACHED | The transfer has failed because the beneficiary account has breached the limit of receiving funds. This rejection is done by the beneficiary bank for the specific beneficiary account. You can reinitiate the transfer after a while via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). The success of the request is contingent on beneficiary's limit being available to receive incoming funds. | - | Yes, after some time |
  | 200 | FAILED | RETURNED\_FROM\_BENEFICIARY | The transfer has failed because the beneficiary bank has returned the transfer and has not need able to credit funds to the end beneficiary. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again with the partner bank(s). | - | - |
  | 200 | FAILED | PAYOUT\_INTERNAL\_ERROR | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | - | - |
  | 200 | FAILED | INVALID\_BENE\_ACCOUNT\_OR\_IFSC | The transfer has failed because the beneficiary account or IFSC is invalid. After correcting the beneficiary account or IFSC, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | - | - |
  | 200 | FAILED | PAYOUT\_INTERNAL\_ERROR | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | - | - |
  | 200 | FAILED | FAILED | The transfer has failed because there was an intermittent issue at the partner bank's end. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after some time |
  | 200 | FAILED | PAYOUT\_INTERNAL\_ERROR | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | - | - |
  | 200 | FAILED | INSUFFICIENT\_BALANCE | The transfer has failed because of low balance in your Cashfree Wallet/ Bank Account. After recharging the account, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After recharging the account, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after recharging |
  | 200 | FAILED | INVALID\_BENE\_VPA | The transfer has failed because the beneficiary VPA is invalid. After correcting the VPA handle, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the VPA handle, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting the VPA handle |
  | 200 | FAILED | INVALID\_IFSC\_FAIL | The transfer has failed because the IFSC is invalid. After correcting the IFSC, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the IFSC, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting the IFSC |
  | 200 | FAILED | BAD\_GATEWAY | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | FAILED | INVALID\_AMOUNT\_FAIL | The transfer has failed because the amount entered is invalid. After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting the amount. |
  | 200 | FAILED | INVALID\_ACCOUNT\_FAIL | The transfer has failed because the Account Number of the beneficiary is invalid, as per our partner bank. After correcting the account number, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the account number, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting the account number |
  | 200 | FAILED | INVALID\_REQUEST | The transfer has failed because the transfer request is invalid, as per our partner bank, because of exceeding the character limit of certain parameter, wrong input etc. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | - | - |
  | 200 | FAILED | ACCOUNT\_BLOCKED | The transfer has failed because the account is blocked, as per our partner bank. After getting the account unblocked, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After getting the account unblocked, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after unblocking the account |
  | 200 | FAILED | DEBIT\_FAILURE | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | FAILED | BENEFICIARY\_BANK\_OFFLINE | The transfer has failed because the respective beneficiary bank is offline. After some time, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After some time, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | FAILED | AUTHENTICATION\_FAILURE | The transfer has failed because there was an authentication failure at the partner bank's end. After checking with the partner bank, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | This is a scenario when the API access is not working at the partner bank's end. After checking with the partner bank, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | FAILED | NRE\_ACCOUNT\_FAIL | The transfer has failed because the beneficiary account is an NRE Account and transfers to NRE Accounts are not supported, as per our partner bank. | Get a new account(non-NRE account) from the beneficiary; you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | No |
  | 200 | FAILED | SOURCE\_LIMIT\_REACHED | The transfer has been failed by the partner bank as the source bank account has reached a limit of transferring funds. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | If you are on Cashfree Wallet, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). If you are on Connected Bank, you need to recharge your bank account and then reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after some time |
  | 200 | FAILED | BANK\_GATEWAY\_ERROR | The transfer has failed because there was an intermittent issue at the partner bank's end. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | FAILED | BAD\_REQUEST | The transfer has failed because the details of the transfer request is invalid, as per our partner bank. After correcting the details in the transfer request, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the details in the transfer request, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | FAILED | REINITIALIZE\_TRANSFER\_LATER | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | MANUALLY\_REJECTED | MANUALLY\_REJECTED | The transfer has failed because it has been manually rejected by the merchant or any team member user who has the permissions to do the same on [Merchant Dashboard](https://merchant.cashfree.com/auth/login). You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again with the partner bank(s). | If the merchant wants to reinitiate the transfer, they can reinitiate the transfer via Cashfree so that the transfer can be reattempted again with the partner bank(s). | Yes, if you want to reinitiate the transfer |
  | 200 | PENDING | SENT\_TO\_BANK | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. This has been sent to the bank by our banking operations team. Please do check statuses or await webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks | - |
  | 200 | PENDING | BANK\_GATEWAY\_ERROR | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. You should rely only on Check Status API response or Webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks | - |
  | 200 | PENDING | NO\_SUCH\_REQUEST | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. The bank is not able to find the request at their end as of now, and it has been sent to the bank by our banking operations team. Please do check statuses or await webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks | - |
  | 200 | PENDING | IN\_PROCESS | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. Please do check statuses or await webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks | - |
  | 200 | PENDING | ERROR\_FETCHING\_STATUS | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. The response received from the partner bank has a new code. This has been raised with the bank to understand the new code. Please do check statuses or await webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks | - |
  | 200 | PENDING | TRANSACTION\_PROCESSED | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. You should rely only on Check Status API response or Webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks | - |
  | 200 | PENDING | REQUEST\_TIMEOUT | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. The bank is not able to find the request at their end as of now as the request between the partner bank has probably timed out, and it has been highlighted to the bank by our banking operations team. Please do check statuses or await webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks | - |
  | 200 | PENDING | DUPLICATE | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. The bank claims of receiving a duplicate request at their end as of now. You should rely only on Check Status API response or Webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks | - |
  | 200 | PENDING | PENDING | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. You should rely only on Check Status API response or Webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks | - |
  | 200 | PENDING | SCHEDULED\_FOR\_NEXT\_WORKINGDAY | The transfer is currently in a Pending state, as the bank has scheduled the transfer for the next working day. This typically happens for NEFT/RTGS transfers if they are initiated beyond the cut-off hours or during bank holidays. You should rely only on Check Status API response or Webhooks to know the terminal state of the transfer request. | - | - |
  | 200 | PENDING | SUSPECT | The transfer is currently in a Pending state, as the bank has scheduled the transfer for the next working day. This typically happens for NEFT/RTGS transfers if they are initiated beyond the cut-off hours or during bank holidays. You should rely only on Check Status API response or Webhooks to know the terminal state of the transfer request. | - | - |
  | 200 | PENDING | IMPLEMENTATION\_ERROR | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. You should rely only on Check Status API response or Webhooks to know the terminal state of the transfer request. | - | - |
  | 200 | PENDING | UNKNOWN\_ERROR\_CODE | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. The response received from the partner bank has a new code. This has been raised with the bank to understand the new code. Please do check statuses or await webhooks to know the terminal state of the transfer request. | - | - |
  | 200 | QUEUED | QUEUED | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. You should rely only on Check Status API response or Webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks | - |
  | 200 | RECEIVED | RECEIVED | The transfer has been received by Cashfree successfully for further processing. You should use Check Status API response or Webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks | - |
  | 200 | REJECTED | BENE\_NOT\_EXIST | The transfer has been rejected because the beneficiary, added in the transfer request, does not exist. After adding the right beneficiary, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After adding the right beneficiary, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after adding the correct beneficiary |
  | 200 | REJECTED | INSUFFICIENT\_BALANCE | The transfer has been rejected because of low balance in your Cashfree Wallet. After recharging the account, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After recharging the account, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after recharging |
  | 200 | REJECTED | INSIDE\_BLACKOUT\_WINDOW | The transfer has been rejected because the transfer falls under the blackout window defined by you in Payout Protect. You can reinitiate the transfer via Cashfree, after the blackout window or after modifying the blackout window from the [Merchant Dashboard](https://merchant.cashfree.com/auth/login), so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree, after the blackout window or after modifying the blackout window from the [Merchant Dashboard](https://merchant.cashfree.com/auth/login), so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | REJECTED | INVALID\_MODE\_FOR\_PYID | The transfer has been rejected because the payment instrument does not support this mode of transfer. You should get this mode activated on the payment instrument ID by contacting Cashfree, and then initiate a new transfer request. | You should get this mode activated on the payment instrument ID by contacting Cashfree, and then initiate a new transfer request. | Yes, after activating the mode |
  | 200 | REJECTED | BENE\_BLACKLISTED | The transfer has been rejected because the beneficiary's bank account and/or VPA handles have been blacklisted by Risk team. You should get a different bank account and/or VPA to send the transfer, or you can connect with Cashfree Team to understand more about this. | You should get a different bank account and/or VPA to send the transfer, or you can connect with Cashfree Team to understand more about this. | Yes, after correcting beneficiary details |
  | 200 | REJECTED | TRANSFER\_NOT\_ATTEMPTED | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | REJECTED | INVALID\_TRANSFER\_AMOUNT | The transfer has been rejected because the amount entered is invalid. After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting the amount |
  | 200 | REJECTED | TRANSFER\_LIMIT\_BREACH | The transfer has been rejected because the amount entered breaches the limits set for your payout account. After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). You can connect with Cashfree if you are not sure about the transfer limits set for your payout account. | After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). You can connect with Cashfree if you are not sure about the transfer limits set for your payout account. | Yes, after adhering to the transfer limits |
  | 200 | REJECTED | INVALID\_PAYMENT\_INSTRUMENT | The transfer has been rejected because the payment instrument (fundsource\_id parameter in the API request) used for attempting the transfer is invalid. After correcting the payment instrument, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | After correcting the payment instrument, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting payment instrument details |
  | 200 | REJECTED | PAYOUT\_INTERNAL\_ERROR | The transfer has been rejected because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | REJECTED | VELOCITY\_CHECK\_FAILED | The transfer has been rejected because the amount entered breaches the limits set for your payout account. After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). You can connect with Cashfree if you are not sure about the transfer limits set for your payout account. | After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). You can connect with Cashfree if you are not sure about the transfer limits set for your payout account. | Yes, after adhering to the transfer limits |
  | 200 | REJECTED | PAYOUT\_INTERNAL\_ERROR | The transfer has been rejected because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | REJECTED | PAYOUT\_INTERNAL\_ERROR | The transfer has been rejected because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | REJECTED | DISABLED\_MODE | The transfer has been rejected because your payout account does not support this mode of transfer. You should get this mode activated on your payout account by contacting Cashfree, and then initiate a new transfer request. | You should get this mode activated on your payout account by contacting Cashfree, and then initiate a new transfer request. | Yes, after activating the mode. |
  | 200 | REJECTED | BANK\_ACCOUNT\_INVALID | The transfer has been rejected because there is a mismatch in the Bank Account Number of the beneficiary ID and the Bank Account Number in the transfer request. After correcting the Bank Account Number, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | After correcting the Bank Account Number, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting the bank account number |
  | 200 | REJECTED | BANK\_IFSC\_INVALID | The transfer has been rejected because there is a mismatch in the IFSC of the beneficiary ID and the IFSC in the transfer request. After correcting the IFSC, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | After correcting the IFSC, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting the IFSC information |
  | 200 | REJECTED | VPA\_INVALID | The transfer has been rejected because there is a mismatch in the VPA handle of the beneficiary ID and the VPA handle in the transfer request. After correcting the VPA handle, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | After correcting the VPA handle, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting the VPA information. |
  | 200 | REJECTED | PHONE\_INVALID | The transfer has been rejected because there is a mismatch in the Phone Number of the beneficiary ID and the Phone Number in the transfer request. After correcting the Phone Number, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | After correcting the Phone Number, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting the phone number. |
  | 200 | REJECTED | BANK\_ACCOUNT\_DETAILS\_MISSING | The transfer has been rejected because the Bank Account Details are missing in the transfer request. After adding the Bank Account Details, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | After adding the Bank Account Details, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after adding the bank account details. |
  | 200 | REJECTED | BENE\_INVALID\_MODE | The transfer has been rejected because the mode is invalid for the given beneficiary. After correcting the mode and beneficiary, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | After correcting the mode and beneficiary, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting the details |
  | 200 | REJECTED | INVALID\_PHONE\_BENEFICIARY | The transfer has been rejected because the beneficiary is Invalid. After correcting the beneficiary, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | After correcting the beneficiary, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting beneficiary details |
  | 200 | REJECTED | INVALID\_BENE\_ACCOUNT\_OR\_IFSC | The transfer has been rejected because the beneficiary account or ifsc is Invalid. After correcting the beneficiary details, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | After correcting the beneficiary details, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting beneficiary details |
  | 200 | REJECTED | NAME\_INVALID | The transfer has been rejected because the name is Invalid. Please refer Cashfree official documentation and after correcting the name, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Please refer Cashfree official documentation and after correcting the name, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting the name |
  | 200 | REJECTED | EMAIL\_INVALID | The transfer has been rejected because the email is Invalid. Please refer Cashfree official documentation and after correcting the email, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Please refer Cashfree official documentation and after correcting the email, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting the email |
  | 200 | REJECTED | REMARKS\_INVALID | The transfer has been rejected because the remark is Invalid. Please refer Cashfree official documentation and after correcting the remarks, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Please refer Cashfree official documentation and after correcting the remarks, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting the remarks |
  | 200 | REVERSED | ACCOUNT\_BLOCKED | The transfer has been reversed by the beneficiary bank as the end-beneficiary's account is blocked for receiving incoming funds. After correcting the account number or getting the account unblocked, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the account number or getting the account unblocked, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after adding new details or getting account unblocked |
  | 200 | REVERSED | FAILED | The transfer has been reversed by the beneficiary bank as they were unable to credit the end beneficiary's bank account. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | - | Yes |
  | 200 | REVERSED | NRE\_ACCOUNT\_FAIL | The transfer has been reversed by the beneficiary bank as they were unable to credit the end beneficiary's bank account as it is an NRE Account and transfers to NRE Accounts are not supported. | Get a new account(non-NRE account) from the beneficiary; you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | No |
  | 200 | REVERSED | RETURENED\_FROM\_BENEFICIARY | The transfer has been reversed by the beneficiary bank as they were unable to credit the end beneficiary's bank account. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | REVERSED | BENE\_BANK\_DECLINED | The transfer has been declined by the beneficiary bank and they were unable to credit the end beneficiary's bank account. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | REVERSED | IMPS\_MODE\_FAIL | The transfer has been reversed by the beneficiary bank because the beneficiary bank account doesnot support IMPS transfers. This rejection is done by the beneficiary bank for the specific beneficiary account. You can try NEFT or other channels to do the disbursals. | You can reinitiate the transfer via Cashfree by changing the mode so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after changing the mode. |
  | 200 | REVERSED | DEST\_LIMIT\_REACHED | The transfer has been reversed by the beneficiary bank as the end-beneficiary's account has reached a limit of receiving incoming funds. This rejection is done by the beneficiary bank for the specific beneficiary account. You can reinitiate the transfer after a while via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). The success of the request is contingent on beneficiary's limit being available to receive incoming funds. | The limits on the beneficiary account are typically refreshed every 24 hours. Its not clear when the 24 hour window shall elpase so you can then reinitiate the transfer via Cashfree after some time so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after some time. |
  | 200 | REVERSED | INVALID\_ACCOUNT\_FAIL | The transfer has been reversed by the beneficiary bank because the Account Number of the beneficiary is invalid. After correcting the account number, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the account number, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting the account number. |
  | 200 | REVERSED | BENE\_NAME\_DIFFERS | The transfer has been reversed by the beneficiary bank because the Account Name of the beneficiary is different. After correcting the beneficiary name, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the beneficiary name, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting the account name. |
  | 200 | SUCCESS | SENT\_TO\_BENEFICIARY | The transfer has been initiated via the partner bank successfully. The request is waiting to be processed at the beneficiary bank to do the credit to the end beneficiary. | - | - |
  | 200 | SUCCESS | COMPLETED | The transfer has been initiated via the partner bank successfully, hence your account is debited and the request is successfully processed by the beneficiary bank and has been credited to the end beneficiary. | - | - |

  #### 4XX errors

  | HTTP status code | Error code | Message | Next action |
  | :- | :- | :- | :- |
  | 404 | batch\_transfer\_id\_not\_found | batch\_transfer\_id does not exist | Enter an existing batch transfer ID. |
  | 404 | cf\_batch\_transfer\_id\_invalid | cf\_batch\_transfer\_id does not exist | Enter an existing cf batch transfer ID. |
  | 404 | transfer\_id\_not\_found | transfer\_id does not exist | Enter an existing transfer ID. |
</Accordion>


# Get Transfer Status V2
Source: https://www.cashfree.com/docs/api-reference/payouts/v2/transfers-v2/get-transfer-status-v2

get /transfers
Use this API to get the status of the initiated transfer. You can use either the transfer_id or cf_transfer_id to fetch the details.

<Note>For batch transfers, check the status of individual transfers **only after** the batch status is `PROCESSED`.</Note>

<Accordion title="Click to view the response codes.">
  | HTTP status code | Status | Status code | Status description | Next action | Try again via Cashfree - Yes or no |
  | :- | :- | :- | :- | :- | :- |
  | 200 | APPROVAL\_PENDING | VELOCITY\_CHECK\_FAILED | The transfer requires an approval as the count of transfers to a particular beneficiary etc have breached the limit. You can approve or reject the transfer request from the Cashfree [Merchant Dashboard](https://merchant.cashfree.com/auth/login). | You can approve/reject the transfer on the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and go to **Transfers > Approve** tab. Post the transfer is approved, the request is sent to the partner bank for further processing. | - |
  | 200 | APPROVAL\_PENDING | TRANSFER\_LIMIT\_BREACH | The transfer requires an approval as the transfer amount etc have breached the limit. You can approve or reject the transfer request from the Cashfree [Merchant Dashboard](https://merchant.cashfree.com/auth/login). | You can approve/reject the transfer on the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and go to **Transfers > Approve** tab. Post the transfer is approved, the request is sent to the partner bank for further processing. | - |
  | 200 | APPROVAL\_PENDING | APPROVAL\_PENDING | The transfer requires approval. You can approve or reject the transfer request from the Cashfree [Merchant Dashboard](https://merchant.cashfree.com/auth/login). | You can approve/reject the transfer on the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and go to **Transfers > Approve** tab. Post the transfer is approved, the request is sent to the partner bank for further processing. | - |
  | 200 | APPROVAL\_PENDING | ANOMALY\_DETECTION | The transfer requires approval as it is a high risk transaction detected by Payout Protect model.  You can approve or reject the transfer request from the Cashfree [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and go to **Payout Protect > Risky Transfers > Flagged Transfers**. | You can approve/reject the transfer on the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and go to **Payout Protect > Risky Transfers > Flagged Transfers** tab. Post the transfer is approved, the request is sent to the partner bank for further processing. | |
  | 200 | APPROVAL\_PENDING | RISK\_CHECK\_MANUAL\_REVIEW\_REQ | The transfer requires approval as it has been flagged by the Payout Protect risk model for manual review. You can approve or reject the transfer request from the Cashfree Merchant Dashboard. | Approve/reject the transfer on the Merchant Dashboard and go to **Payout Protect > Risky Transfers > Flagged Transfers** tab. | - |
  | 200 | APPROVAL\_PENDING | RISK\_CHECK\_ANOMALY\_DETECTED | The transfer requires approval as it has been flagged by the Payout Protect risk model for manual review due to anomaly detection. You can approve or reject the transfer request from the Cashfree Merchant Dashboard. | Approve/reject the transfer on the Merchant Dashboard and go to **Payout Protect > Risky Transfers > Flagged Transfers** tab. | - |
  | 200 | APPROVAL\_PENDING | RISK\_CHECK\_BENEFICIARY\_HIGH\_RISK | The transfer requires approval as the beneficiary has been identified as high risk by the Payout Protect model. You can approve or reject the transfer request from the Cashfree Merchant Dashboard. | Approve/reject the transfer on the Merchant Dashboard and go to **Payout Protect > Risky Transfers > Flagged Transfers** tab. | - |
  | 200 | APPROVAL\_PENDING | RISK\_CHECK\_VELOCITY\_THRESHOLD | The transfer requires approval as it breaches the velocity threshold set in the Payout Protect rules. You can approve or reject the transfer request from the Cashfree Merchant Dashboard. | Approve/reject the transfer on the Merchant Dashboard and go to **Payout Protect > Risky Transfers > Flagged Transfers** tab. | - |
  | 200 | APPROVAL\_PENDING | RISK\_CHECK\_TIME\_WINDOW\_BREACH | The transfer requires approval as it falls outside the allowed time window defined in the Payout Protect rules. You can approve or reject the transfer request from the Cashfree Merchant Dashboard. | Approve/reject the transfer on the Merchant Dashboard and go to **Payout Protect > Risky Transfers > Flagged Transfers** tab. | - |
  | 200 | APPROVAL\_PENDING | RISK\_CHECK\_AMOUNT\_THRESHOLD | The transfer requires approval as it exceeds the amount threshold set in the Payout Protect rules. You can approve or reject the transfer request from the Cashfree Merchant Dashboard. | Approve/reject the transfer on the Merchant Dashboard and go to **Payout Protect > Risky Transfers > Flagged Transfers** tab. | - |
  | 200 | APPROVAL\_PENDING | HIGH\_RISK\_BENEFICIARY | The transfer requires approval as the beneficiary is identified as high risk. You can approve or reject the transfer request from the Cashfree Merchant Dashboard. | Approve/reject the transfer on the Merchant Dashboard and go to **Payout Protect > Risky Transfers > Flagged Transfers** tab. | - |
  | 200 | APPROVAL\_PENDING | UNUSUAL\_ACTIVITY\_DETECTED | The transfer requires approval as unusual activity has been detected in the transfer pattern. You can approve or reject the transfer request from the Cashfree Merchant Dashboard. | Approve/reject the transfer on the Merchant Dashboard and go to **Payout Protect > Risky Transfers > Flagged Transfers** tab. | - |
  | 200 | APPROVAL\_PENDING | BLACKOUT\_WINDOW\_RULE | The transfer requires approval as it falls within the blackout window defined in the Payout Protect rules. You can approve or reject the transfer request from the Cashfree Merchant Dashboard. | Approve/reject the transfer on the Merchant Dashboard and go to **Payout Protect > Risky Transfers > Flagged Transfers** tab. | - |
  | 200 | APPROVAL\_PENDING | CUSTOM\_RULE\_TRIGGERED | The transfer requires approval as it has triggered a custom rule defined in the Payout Protect settings. You can approve or reject the transfer request from the Cashfree Merchant Dashboard. | Approve/reject the transfer on the Merchant Dashboard and go to **Payout Protect > Risky Transfers > Flagged Transfers** tab. | - |
  | 200 | APPROVAL\_PENDING | MANUAL\_APPROVAL\_REQUIRED | The transfer requires manual approval as per the configured workflow. You can approve or reject the transfer request from the Cashfree Merchant Dashboard. | Approve/reject the transfer on the Merchant Dashboard and go to **Transfers > Approve** tab. | - |
  | 200 | APPROVAL\_PENDING | COMPLIANCE\_REVIEW\_PENDING | The transfer requires approval as it is pending compliance review. You can approve or reject the transfer request from the Cashfree Merchant Dashboard. | Approve/reject the transfer on the Merchant Dashboard and go to **Transfers > Approve** tab. | - |
  | 200 | FAILED | WAIT\_TIME\_EXCEEDED | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | FAILED | BENE | The transfer has failed because the beneficiary bank has declined the transfer. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again with the partner bank(s). | - | Yes |
  | 200 | FAILED | IMPS\_MODE\_FAIL | The transfer has failed because the beneficiary account doesnot support IMPS transfers. This rejection is done by the partner bank for the specific beneficiary account. You can try NEFT or other channels to do the disbursals. | You can try NEFT or other channels to do the disbursals. | Yes, via a different mode |
  | 200 | FAILED | SOURCE\_BENE\_DECLINED | The transfer has failed because our partner bank has declined the transfer because of their internal checks, technical declines etc. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again with other partner bank(s). | Yes |
  | 200 | FAILED | CONNECTION\_TIMEOUT | The transfer has failed because there was a connection timeout between the bank and Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again with the partner bank(s). | YES |
  | 200 | FAILED | PAYOUT\_INTERNAL\_ERROR | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | - | Yes |
  | 200 | FAILED | NPCI\_UNAVAILABLE | The transfer has failed because NPCI was unavailable to complete the transfer request. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree. The success of the request is contingent on NPCI services being up. | - | Yes, after some time. |
  | 200 | FAILED | DEST\_LIMIT\_REACHED | The transfer has failed because the beneficiary account has breached the limit of receiving funds. This rejection is done by the beneficiary bank for the specific beneficiary account. You can reinitiate the transfer after a while via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). The success of the request is contingent on beneficiary's limit being available to receive incoming funds. | - | Yes, after some time. |
  | 200 | FAILED | RETURNED\_FROM\_BENEFICIARY | The transfer has failed because the beneficiary bank has returned the transfer and has not need able to credit funds to the end beneficiary. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again with the partner bank(s). | - | - |
  | 200 | FAILED | PAYOUT\_INTERNAL\_ERROR | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | - | - |
  | 200 | FAILED | INVALID\_BENE\_ACCOUNT\_OR\_IFSC | The transfer has failed because the beneficiary account or IFSC is invalid. After correcting the beneficiary account or IFSC, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | - | - |
  | 200 | FAILED | PAYOUT\_INTERNAL\_ERROR | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | - | - |
  | 200 | FAILED | FAILED | The transfer has failed because there was an intermittent issue at the partner bank's end. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after some time. |
  | 200 | FAILED | PAYOUT\_INTERNAL\_ERROR | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | - | - |
  | 200 | FAILED | INSUFFICIENT\_BALANCE | The transfer has failed because of low balance in your Cashfree Wallet/ Bank Account. After recharging the account, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After recharging the account, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after recharging. |
  | 200 | FAILED | INVALID\_BENE\_VPA | The transfer has failed because the beneficiary VPA is invalid. After correcting the VPA handle, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the VPA handle, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting VPA handle. |
  | 200 | FAILED | INVALID\_IFSC\_FAIL | The transfer has failed because the IFSC is invalid. After correcting the IFSC, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the IFSC, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting IFSC |
  | 200 | FAILED | BAD\_GATEWAY | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | FAILED | INVALID\_AMOUNT\_FAIL | The transfer has failed because the amount entered is invalid. After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting the amount |
  | 200 | FAILED | INVALID\_ACCOUNT\_FAIL | The transfer has failed because the Account Number of the beneficiary is invalid, as per our partner bank. After correcting the account number, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the account number, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting the account number |
  | 200 | FAILED | INVALID\_REQUEST | The transfer has failed because the transfer request is invalid, as per our partner bank, because of exceeding the character limit of certain parameter, wrong input etc. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | - | - |
  | 200 | FAILED | ACCOUNT\_BLOCKED | The transfer has failed because the account is blocked, as per our partner bank. After getting the account unblocked, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After getting the account unblocked, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after unblocking the account number |
  | 200 | FAILED | DEBIT\_FAILURE | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | FAILED | BENEFICIARY\_BANK\_OFFLINE | The transfer has failed because the respective beneficiary bank is offline. After some time, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After some time, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s) | Yes |
  | 200 | FAILED | AUTHENTICATION\_FAILURE | The transfer has failed because there was an authentication failure at the partner bank's end. After checking with the partner bank, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | This is a scenario when the API access is not working at the partner bank's end. After checking with the partner bank, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | FAILED | NRE\_ACCOUNT\_FAIL | The transfer has failed because the beneficiary account is an NRE Account and transfers to NRE Accounts are not supported, as per our partner bank. | Get a new account(non-NRE account) from the beneficiary; you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | No |
  | 200 | FAILED | SOURCE\_LIMIT\_REACHED | The transfer has been failed by the partner bank as the source bank account has reached a limit of transferring funds. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | If you are on Cashfree Wallet, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). If you are on Connected Bank, you need to recharge your bank account and then reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after some time. |
  | 200 | FAILED | BANK\_GATEWAY\_ERROR | The transfer has failed because there was an intermittent issue at the partner bank's end. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | FAILED | BAD\_REQUEST | The transfer has failed because the details of the transfer request is invalid, as per our partner bank. After correcting the details in the transfer request, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the details in the transfer request, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | FAILED | REINITIALIZE\_TRANSFER\_LATER | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | MANUALLY\_REJECTED | MANUALLY\_REJECTED | The transfer has failed because it has been manually rejected by the merchant or any team member user who has the permissions to do the same on [Merchant Dashboard](https://merchant.cashfree.com/auth/login). You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again with the partner bank(s). | If the merchant wants to reinitiate the transfer, they can reinitiate the transfer via Cashfree so that the transfer can be reattempted again with the partner bank(s). | Yes, if you want to reinitiate the transfer |
  | 200 | PENDING | SENT\_TO\_BANK | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. This has been sent to the bank by our banking operations team. Please do check statuses or await webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks. | - |
  | 200 | PENDING | BANK\_GATEWAY\_ERROR | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. You should rely only on Check Status API response or Webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks | - |
  | 200 | PENDING | NO\_SUCH\_REQUEST | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. The bank is not able to find the request at their end as of now, and it has been sent to the bank by our banking operations team. Please do check statuses or await webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks. | - |
  | 200 | PENDING | IN\_PROCESS | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. Please do check statuses or await webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks | - |
  | 200 | PENDING | ERROR\_FETCHING\_STATUS | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. The response received from the partner bank has a new code. This has been raised with the bank to understand the new code. Please do check statuses or await webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks | - |
  | 200 | PENDING | TRANSACTION\_PROCESSED | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. You should rely only on Check Status API response or Webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks | - |
  | 200 | PENDING | REQUEST\_TIMEDOUT | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. The bank is not able to find the request at their end as of now as the request between the partner bank has probably timed out, and it has been highlighted to the bank by our banking operations team. Please do check statuses or await webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks | - |
  | 200 | PENDING | DUPLICATE | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. The bank claims of receiving a duplicate request at their end as of now. You should rely only on Check Status API response or Webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks | - |
  | 200 | PENDING | - | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. You should rely only on Check Status API response or Webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks | - |
  | 200 | PENDING | SCHEDULED\_FOR\_NEXT\_WORKINGDAY | The transfer is currently in a Pending state, as the bank has scheduled the transfer for the next working day. This typically happens for NEFT/RTGS transfers if they are initiated beyond the cut-off hours or during bank holidays. You should rely only on Check Status API response or Webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks | - |
  | 200 | PENDING | SUSPECT | The transfer is currently in a Pending state, as the bank has scheduled the transfer for the next working day. This typically happens for NEFT/RTGS transfers if they are initiated beyond the cut-off hours or during bank holidays. You should rely only on Check Status API response or Webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks | - |
  | 200 | PENDING | IMPLEMENTATION\_ERROR | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. You should rely only on Check Status API response or Webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks | - |
  | 200 | PENDING | UNKNOWN\_ERROR\_CODE | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. The response received from the partner bank has a new code. This has been raised with the bank to understand the new code. Please do check statuses or await webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks | - |
  | 200 | QUEUED | QUEUED | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. You should rely only on Check Status API response or Webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks | - |
  | 200 | RECEIVED | RECEIVED | The transfer has been received by Cashfree successfully for further processing. You should use Check Status API response or Webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks | - |
  | 200 | REJECTED | BENE\_NOT\_EXIST | The transfer has been rejected because the beneficiary, added in the transfer request, does not exist. After adding the right beneficiary, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After adding the right beneficiary, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after adding the correct beneficiary |
  | 200 | REJECTED | INSUFFICIENT\_BALANCE | The transfer has been rejected because of low balance in your Cashfree Wallet. After recharging the account, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After recharging the account, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after recharging the account |
  | 200 | REJECTED | INSIDE\_BLACKOUT\_WINDOW | The transfer has been rejected because the transfer falls under the blackout window defined by you in Payout Protect. You can reinitiate the transfer via Cashfree, after the blackout window or after modifying the blackout window from the [Merchant Dashboard](https://merchant.cashfree.com/auth/login), so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree, after the blackout window or after modifying the blackout window from the [Merchant Dashboard](https://merchant.cashfree.com/auth/login), so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | REJECTED | INVALID\_MODE\_FOR\_PYID | The transfer has been rejected because the payment instrument does not support this mode of transfer. You should get this mode activated on the payment instrument ID by contacting Cashfree, and then initiate a new transfer request. | You should get this mode activated on the payment instrument ID by contacting Cashfree, and then initiate a new transfer request. | Yes, after activating mode |
  | 200 | REJECTED | BENE\_BLACKLISTED | The transfer has been rejected because the beneficiary's bank account and/or VPA handles have been blacklisted by Risk team. You should get a different bank account and/or VPA to send the transfer, or you can connect with Cashfree Team to understand more about this. | You should get a different bank account and/or VPA to send the transfer, or you can connect with Cashfree Team to understand more about this. | Yes, after correcting beneficiary details |
  | 200 | REJECTED | TRANSFER\_NOT\_ATTEMPTED | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | REJECTED | INVALID\_TRANSFER\_AMOUNT | The transfer has been rejected because the amount entered is invalid. After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting the amount |
  | 200 | REJECTED | TRANSFER\_LIMIT\_BREACH | The transfer has been rejected because the amount entered breaches the limits set for your payout account. After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). You can connect with Cashfree if you are not sure about the transfer limits set for your payout account. | After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). You can connect with Cashfree if you are not sure about the transfer limits set for your payout account. | Yes, after adhering to the transfer limits |
  | 200 | REJECTED | INVALID\_PAYMENT\_INSTRUMENT | The transfer has been rejected because the payment instrument (fundsource\_id parameter in the API request) used for attempting the transfer is invalid. After correcting the payment instrument, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | After correcting the payment instrument, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting the payment instrument |
  | 200 | REJECTED | PAYOUT\_INTERNAL\_ERROR | The transfer has been rejected because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | REJECTED | VELOCITY\_CHECK\_FAILED | The transfer has been rejected because the amount entered breaches the limits set for your payout account. After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). You can connect with Cashfree if you are not sure about the transfer limits set for your payout account. | After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). You can connect with Cashfree if you are not sure about the transfer limits set for your payout account. | Yes, after adhering to the transfer limits |
  | 200 | REJECTED | PAYOUT\_INTERNAL\_ERROR | The transfer has been rejected because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | REJECTED | PAYOUT\_INTERNAL\_PEOPLE | The transfer has been rejected because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | REJECTED | DISABLED\_MODE | The transfer has been rejected because your payout account does not support this mode of transfer. You should get this mode activated on your payout account by contacting Cashfree, and then initiate a new transfer request. | You should get this mode activated on your payout account by contacting Cashfree, and then initiate a new transfer request. | Yes, after activating the mode |
  | 200 | REJECTED | BANK\_ACCOUNT\_INVALID | The transfer has been rejected because there is a mismatch in the Bank Account Number of the beneficiary ID and the Bank Account Number in the transfer request. After correcting the Bank Account Number, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | After correcting the Bank Account Number, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting the bank account number. |
  | 200 | REJECTED | BANK\_IFSC\_INVALID | The transfer has been rejected because there is a mismatch in the IFSC of the beneficiary ID and the IFSC in the transfer request. After correcting the IFSC, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | After correcting the IFSC, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting the IFSC |
  | 200 | REJECTED | VPA\_INVALID | The transfer has been rejected because there is a mismatch in the VPA handle of the beneficiary ID and the VPA handle in the transfer request. After correcting the VPA handle, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | After correcting the VPA handle, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting the VPA handle |
  | 200 | REJECTED | PHONE\_INVALID | The transfer has been rejected because there is a mismatch in the Phone Number of the beneficiary ID and the Phone Number in the transfer request. After correcting the Phone Number, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | After correcting the Phone Number, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting the phone number |
  | 200 | REJECTED | BANK\_ACCOUNT\_DETAILS\_MISSING | The transfer has been rejected because the Bank Account Details are missing in the transfer request. After adding the Bank Account Details, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | After adding the Bank Account Details, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after adding the bank account details |
  | 200 | REJECTED | BENE\_INVALID\_MODE | The transfer has been rejected because the mode is invalid for the given beneficiary. After correcting the mode and beneficiary, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | After correcting the mode and beneficiary, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting the details |
  | 200 | REJECTED | INVALID\_PHONE\_BENEFICIARY | The transfer has been rejected because the beneficiary is Invalid. After correcting the beneficiary, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | After correcting the beneficiary, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting beneficiary details |
  | 200 | REJECTED | INVALID\_BENE\_ACCOUNT\_OR\_IFSC | The transfer has been rejected because the beneficiary account or ifsc is Invalid. After correcting the beneficiary details, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | After correcting the beneficiary details, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting beneficiary details |
  | 200 | REJECTED | NAME\_INVALID | The transfer has been rejected because the name is Invalid. Please refer Cashfree official documentation and after correcting the name, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Please refer Cashfree official documentation and after correcting the name, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting the name |
  | 200 | REJECTED | EMAIL\_INVALID | The transfer has been rejected because the email is Invalid. Please refer Cashfree official documentation and after correcting the email, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Please refer Cashfree official documentation and after correcting the email, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting the email |
  | 200 | REJECTED | REMARKS\_INVALID | The transfer has been rejected because the remark is Invalid. Please refer Cashfree official documentation and after correcting the remarks, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Please refer Cashfree official documentation and after correcting the remarks, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting the remarks |
  | 200 | REVERSED | ACCOUNT\_BLOCKED | The transfer has been reversed by the beneficiary bank as the end-beneficiary's account is blocked for receiving incoming funds. After correcting the account number or getting the account unblocked, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the account number or getting the account unblocked, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after adding new details or getting the account unblocked |
  | 200 | REVERSED | FAILED | The transfer has been reversed by the beneficiary bank as they were unable to credit the end beneficiary's bank account. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | - | Yes |
  | 200 | REVERSED | NRE\_ACCOUNT\_FAIL | The transfer has been reversed by the beneficiary bank as they were unable to credit the end beneficiary's bank account as it is an NRE Account and transfers to NRE Accounts are not supported. | Get a new account(non-NRE account) from the beneficiary; you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | No |
  | 200 | REVERSED | RETURNED\_FROM\_BENEFICIARY | The transfer has been reversed by the beneficiary bank as they were unable to credit the end beneficiary's bank account. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | REVERSED | BENE\_BANK\_DECLINED | The transfer has been declined by the beneficiary bank and they were unable to credit the end beneficiary's bank account. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | REVERSED | IMPS\_MODE\_FAIL | The transfer has been reversed by the beneficiary bank because the beneficiary bank account doesnot support IMPS transfers. This rejection is done by the beneficiary bank for the specific beneficiary account. You can try NEFT or other channels to do the disbursals. | You can reinitiate the transfer via Cashfree by changing the mode so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after changing the mode. |
  | 200 | REVERSED | DEST\_LIMIT\_REACHED | The transfer has been reversed by the beneficiary bank as the end-beneficiary's account has reached a limit of receiving incoming funds. This rejection is done by the beneficiary bank for the specific beneficiary account. You can reinitiate the transfer after a while via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). The success of the request is contingent on beneficiary's limit being available to receive incoming | The limits on the beneficiary account are typically refreshed every 24 hours. Its not clear when the 24 hour window shall elpase so you can then reinitiate the transfer via Cashfree after some time so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after some time. |
  | 200 | REVERSED | INVALID\_ACCOUNT\_FAIL | The transfer has been reversed by the beneficiary bank because the Account Number of the beneficiary is invalid. After correcting the account number, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the account number, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting the account number. |
  | 200 | REVERSED | BENE\_NAME\_DIFFERS | The transfer has been reversed by the beneficiary bank because the Account Name of the beneficiary is different. After correcting the beneficiary name, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the beneficiary name, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting the account name |
  | 200 | SUCCESS | SENT\_TO\_BENEFICIARY | The transfer has been initiated via the partner bank successfully. The request is waiting to be processed at the beneficiary bank to do the credit to the end beneficiary. | - | - |
  | 200 | SUCCESS | COMPLETED | The transfer has been initiated via the partner bank successfully, hence your account is debited and the request is successfully processed by the beneficiary bank and has been credited to the end beneficiary. | - | - |

  #### 4XX errors

  | HTTP status code | Error code | Message | Next action |
  | :- | :- | :- | :- |
  | 400 | transfer\_id\_missing | transfer\_id is missing in the request | Enter a transfer\_id in the request. |
  | 400 | transfer\_id\_invalid | transfer\_id should be alphanumeric | Enter a valid transfer\_id. |
  | 400 | transfer\_amount\_invalid | transfer\_amount should be greater then 1.00 | Enter a transfer\_amount greater than 1.00. |
  | 400 | transfer\_amount\_missing | transfer\_amount is missing in the request | Enter a transfer\_amount in the request. |
  | 400 | transfer\_mode\_invalid | transfer\_mode is invalid allowed values are : bank, imps, neft, rtgs, upi, paytm, amazonpay, card and cardupi | Provide a valid transfer\_mode in the request. |
  | 400 | transfer\_mode\_invalid | transfer\_mode\_invalid	transfer\_mode is invalid allowed values are : bank, imps, neft, rtgs, upi, paytm, amazonpay, card and cardupi | Provide a valid transfer\_mode in the request. |
  | 400 | beneficiary\_details.beneficiary\_id\_invalid | beneficiary\_id should be alphanumeric | Provide a valid beneficiary\_id in the request. |
  | 400 | beneficiary\_details.beneficiary\_name\_invalid | beneficiary\_name is invalid. only alphabets and whitespaces are allowed | Provide a valid beneficiary\_name in the request. |
  | 400 | beneficiary\_details.beneficiary\_instrument\_details.bank\_account\_number\_invalid | bank\_account\_number should be alphanumeric | Provide a valid bank\_account\_number in the request |
  | 400 | beneficiary\_details.beneficiary\_instrument\_details.bank\_account\_number\_invalid | Bank account number passed in the request does not match with the beneficiary with beneficiary\_id :: test\_beneId | Provide the correct bank\_account\_number in the request. |
  | 400 | beneficiary\_details.beneficiary\_instrument\_details.bank\_ifsc\_invalid | bank\_ifsc should be in standard ifsc format | Provide a valid bank\_ifsc. |
  | 400 | beneficiary\_details.beneficiary\_instrument\_details.bank\_ifsc\_invalid | Bank ifsc passed in the request does not match with the beneficiary with beneficiary\_id :: test\_beneId | Provide the correct bank\_ifsc for the beneficiary. |
  | 400 | beneficiary\_details.beneficiary\_instrument\_details.vpa\_invalid | vpa is in invalid format | Provide a valid vpa. |
  | 400 | beneficiary\_details.beneficiary\_instrument\_details.vpa\_invalid | Vpa passed in the request does not match with the beneficiary with beneficiary\_id :: test\_beneId | Provide the correct vpa for the beneficiary. |
  | 404 | beneficiary\_not\_found | Beneficiary does not exist | Provide an existing beneficiary. |
</Accordion>


# Standard Transfer V2
Source: https://www.cashfree.com/docs/api-reference/payouts/v2/transfers-v2/standard-transfer-v2

post /transfers
Use this API to initiate an amount transfer at Cashfree. It is an async request by default.

<Warning>
  **5XX error**<br />
  When you get a 5XX response, do not initiate another transaction.<br />
  Check the status of the batch transfer using Get Batch Transfer Status V2 and then proceed further.
</Warning>

<Note>
  **Get Transfer Status**<br />
  Use the [Get Transfer Status V2](/docs/api-reference/payouts/v2/transfers-v2/standard-transfer-v2) API to get the status of the batch transfer request. The Get Transfer Status V2 API does not give you the status of the batch transfer requests.
</Note>

<Accordion title="Click to view the response codes.">
  | HTTP status code | Status | Status code | Status description | Next action | Try again via Cashfree |
  | :- | :- | :- | :- | :- | :- |
  | 200 | APPROVAL\_PENDING | VELOCITY\_CHECK\_FAILED | The transfer requires an approval as the count of transfers to a particular beneficiary etc have breached the limit. You can approve or reject the transfer request from the Cashfree [Merchant Dashboard](https://merchant.cashfree.com/auth/login). | You can approve/reject the transfer on the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and go to **Transfers > Approve**. Post the transfer is approved, the request is sent to the partner bank for further processing. | - |
  | 200 | APPROVAL\_PENDING | TRANSFER\_LIMIT\_BREACH | The transfer requires an approval as the transfer amount etc have breached the limit. You can approve or reject the transfer request from the Cashfree [Merchant Dashboard](https://merchant.cashfree.com/auth/login). | You can approve/reject the transfer on the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and go to **Transfers > Approve**. Post the transfer is approved, the request is sent to the partner bank for further processing. | - |
  | 200 | APPOVAL\_PENDING | APPROVAL\_PENDING | The transfer requires approval. You can approve or reject the transfer request from the Cashfree [Merchant Dashboard](https://merchant.cashfree.com/auth/login). | You can approve/reject the transfer on the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and go to **Transfers > Approve**. Post the transfer is approved, the request is sent to the partner bank for further processing. | - |
  | 200 | FAILED | WAIT\_TIME\_EXCEEDED | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree to reattempt with the partner bank(s). | Yes |
  | 200 | FAILED | BENE\_BANK\_DECLINED | The transfer has failed because the beneficiary bank has declined the transfer. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again with the partner bank(s). | - | Yes |
  | 200 | FAILED | IMPS\_MODE\_FAIL | The transfer has failed because the beneficiary account doesnot support IMPS transfers. This rejection is done by the partner bank for the specific beneficiary account. You can try NEFT or other channels to do the disbursals. | You can try NEFT or other channels to do the disbursals. | Yes, via a different mode. |
  | 200 | FAILED | SOURCE\_BANK\_DECLINED | The transfer has failed because our partner bank has declined the transfer because of their internal checks, technical declines etc. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again with other partner bank(s). | Yes |
  | 200 | FAILED | CONNECTION\_TIMEOUT | The transfer has failed because there was a connection timeout between the bank and Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again with the partner bank(s). | Yes |
  | 200 | FAILED | PAYOUT\_INTERNAL\_ERROR | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | - | Yes |
  | 200 | FAILED | NPCI\_UNAVAILABLE | The transfer has failed because NPCI was unavailable to complete the transfer request. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree. The success of the request is contingent on NPCI services being up. | - | Yes, after some time. |
  | 200 | FAILED | DEST\_LIMIT\_REACHED | The transfer has failed because the beneficiary account has breached the limit of receiving funds. This rejection is done by the beneficiary bank for the specific beneficiary account. You can reinitiate the transfer after a while via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). The success of the request is contingent on beneficiary's limit being available to receive incoming funds. | - | Yes, after some time. |
  | 200 | FAILED | RETURNED\_FROM\_BENEFICIARY | The transfer has failed because the beneficiary bank has returned the transfer and has not need able to credit funds to the end beneficiary. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again with the partner bank(s). | - | - |
  | 200 | FAILED | PAYOUT\_INTERNAL\_ERROR | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | - | - |
  | 200 | FAILED | INVALID\_BENE\_ACCOUNT\_OR\_IFSC | The transfer has failed because the beneficiary account or IFSC is invalid. After correcting the beneficiary account or IFSC, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | - | - |
  | 200 | FAILED | PAYOUT\_INTERNAL\_ERROR | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | - | - |
  | 200 | FAILED | FAILED | The transfer has failed because there was an intermittent issue at the partner bank's end. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after some time. |
  | 200 | FAILED | PAYOUT\_INTERNAL\_ERROR | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | - | - |
  | 200 | FAILED | INSUFFICIENT\_BALANCE | The transfer has failed because of low balance in your Cashfree Wallet/ Bank Account. After recharging the account, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After recharging the account, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after recharging. |
  | 200 | FAILED | INVALID\_BENE\_VPA | The transfer has failed because the beneficiary VPA is invalid. After correcting the VPA handle, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the VPA handle, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting VPA handle. |
  | 200 | FAILED | INVALID\_IFSC\_FAIL | The transfer has failed because the IFSC is invalid. After correcting the IFSC, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the IFSC, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting IFSC. |
  | 200 | FAILED | BAD\_GATEWAY | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | FAILED | INVALID\_AMOUNT\_FAIL | The transfer has failed because the amount entered is invalid. After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting amount |
  | 200 | FAILED | INVALID\_ACCOUNT\_FAIL | The transfer has failed because the Account Number of the beneficiary is invalid, as per our partner bank. After correcting the account number, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the account number, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting account number |
  | 200 | FAILED | INVALID\_REQUEST | The transfer has failed because the transfer request is invalid, as per our partner bank, because of exceeding the character limit of certain parameter, wrong input etc. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | - | - |
  | 200 | FAILED | ACCOUNT\_BLOCKED | The transfer has failed because the account is blocked, as per our partner bank. After getting the account unblocked, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After getting the account unblocked, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after unblocking the account number |
  | 200 | FAILED | DEBIT\_FAILURE | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | FAILED | BENEFICIARY\_BANK\_OFFLINE | The transfer has failed because the respective beneficiary bank is offline. After some time, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After some time, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after some time |
  | 200 | FAILED | AUTHENTICATION\_FAILURE | The transfer has failed because there was an authentication failure at the partner bank's end. After checking with the partner bank, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | This is a scenario when the API access is not working at the partner bank's end. After checking with the partner bank, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | FAILED | NRE\_ACCOUNT\_FAIL | The transfer has failed because the beneficiary account is an NRE Account and transfers to NRE Accounts are not supported, as per our partner bank. | Get a new account(non-NRE account) from the beneficiary; you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | FAILED | SOURCE\_LIMIT\_REACHED | The transfer has been failed by the partner bank as the source bank account has reached a limit of transferring funds. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | If you are on Cashfree Wallet, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). If you are on Connected Bank, you need to recharge your bank account and then reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after some time |
  | 200 | FAILED | BANK\_GATEWAY\_ERROR | The transfer has failed because there was an intermittent issue at the partner bank's end. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | FAILED | BAD\_REQUEST | The transfer has failed because the details of the transfer request is invalid, as per our partner bank. After correcting the details in the transfer request, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the details in the transfer request, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | FAILED | REINITIALIZE\_TRANSFER\_LATER | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | MANUALLY\_REJECTED | MANUALLY\_REJECTED | The transfer has failed because it has been manually rejected by the merchant or any team member user who has the permissions to do the same on [Merchant Dashboard](https://merchant.cashfree.com/auth/login). You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again with the partner bank(s). | If the merchant wants to reinitiate the transfer, they can reinitiate the transfer via Cashfree so that the transfer can be reattempted again with the partner bank(s). | Yes,  if you want to reinitiate the transfer |
  | 200 | PENDING | SENT\_TO\_BANK | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. This has been sent to the bank by our banking operations team. Please do check statuses or await webhooks to know the terminal state of the transfer request. | Rely on Check Status API or Webhooks. | - |
  | 200 | PENDING | BANK\_GATEWAY\_ERROR | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. You should rely only on Check Status API response or Webhooks to know the terminal state of the transfer request. | Rely on Check Status API or Webhooks. | - |
  | 200 | PENDING | NO\_SUCH\_REQUEST | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. The bank is not able to find the request at their end as of now, and it has been sent to the bank by our banking operations team. Please do check statuses or await webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks. | - |
  | 200 | PENDING | IN\_PROCESS | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. Please do check statuses or await webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks. | - |
  | 200 | PENDING | ERROR\_FETCHING\_STATUS | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. The response received from the partner bank has a new code. This has been raised with the bank to understand the new code. Please do check statuses or await webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks. | - |
  | 200 | PENDING | TRANSACTION\_PROCESSED | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. You should rely only on Check Status API response or Webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks. | - |
  | 200 | PENDING | REQUEST\_TIMEDOUT | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. The bank is not able to find the request at their end as of now as the request between the partner bank has probably timed out, and it has been highlighted to the bank by our banking operations team. Please do check statuses or await webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks. | - |
  | 200 | PENDING | DUPLICATE | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. The bank claims of receiving a duplicate request at their end as of now. You should rely only on Check Status API response or Webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks. | - |
  | 200 | PENDING | PENDING | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. You should rely only on Check Status API response or Webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks. | - |
  | 200 | PENDING | SCHEDULED\_FOR\_NEXT\_WORKINGDAY | The transfer is currently in a Pending state, as the bank has scheduled the transfer for the next working day. This typically happens for NEFT/RTGS transfers if they are initiated beyond the cut-off hours or during bank holidays. You should rely only on Check Status API response or Webhooks to know the terminal state of the transfer request. | - | - |
  | 200 | PENDING | SUSPECT | The transfer is currently in a Pending state, as the bank has scheduled the transfer for the next working day. This typically happens for NEFT/RTGS transfers if they are initiated beyond the cut-off hours or during bank holidays. You should rely only on Check Status API response or Webhooks to know the terminal state of the transfer request. | - | - |
  | 200 | PENDING | IMPLEMENTATION\_ERROR | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. You should rely only on Check Status API response or Webhooks to know the terminal state of the transfer request. | - | - |
  | 200 | PENDING | UNKNOWN\_ERROR\_CODE | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. The response received from the partner bank has a new code. This has been raised with the bank to understand the new code. Please do check statuses or await webhooks to know the terminal state of the transfer request. | - | - |
  | 200 | QUEUED | QUEUED | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. You should rely only on Check Status API response or Webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks. | - |
  | 200 | RECEIVED | RECEIVED | The transfer has been received by Cashfree successfully for further processing. You should use Check Status API response or Webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks. | - |
  | 200 | REJECTED | BENE\_NOT\_EXIST | The transfer has been rejected because the beneficiary, added in the transfer request, does not exist. After adding the right beneficiary, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After adding the right beneficiary, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after adding the correct beneficiary. |
  | 200 | REJECTED | INSUFFICIENT\_BALANCE | The transfer has been rejected because of low balance in your Cashfree Wallet. After recharging the account, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After recharging the account, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after recharging. |
  | 200 | REJECTED | INSIDE\_BLACKOUT\_WINDOW | The transfer has been rejected because the transfer falls under the blackout window defined by you in Payout Protect. You can reinitiate the transfer via Cashfree, after the blackout window or after modifying the blackout window from the [Merchant Dashboard](https://merchant.cashfree.com/auth/login), so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree, after the blackout window or after modifying the blackout window from the [Merchant Dashboard](https://merchant.cashfree.com/auth/login), so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | REJECTED | INVALID\_MODE\_FOR\_PYID | The transfer has been rejected because the payment instrument does not support this mode of transfer. You should get this mode activated on the payment instrument ID by contacting Cashfree, and then initiate a new transfer request. | You should get this mode activated on the payment instrument ID by contacting Cashfree, and then initiate a new transfer request. | Yes, after activating model |
  | 200 | REJECTED | BENE\_BLACKLISTED | The transfer has been rejected because the beneficiary's bank account and/or VPA handles have been blacklisted by Risk team. You should get a different bank account and/or VPA to send the transfer, or you can connect with Cashfree Team to understand more about this. | You should get a different bank account and/or VPA to send the transfer, or you can connect with Cashfree Team to understand more about this. | Yes, after correcting beneficiary details |
  | 200 | REJECTED | TRANSFER\_NOT\_ATTEMPTED | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | REJECTED | INVALID\_TRANSFER\_AMOUNT | The transfer has been rejected because the amount entered is invalid. After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting the amount |
  | 200 | REJECTED | TRANSFER\_LIMIT\_BREACH | The transfer has been rejected because the amount entered breaches the limits set for your payout account. After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). You can connect with Cashfree if you are not sure about the transfer limits set for your payout account. | After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). You can connect with Cashfree if you are not sure about the transfer limits set for your payout account. | Yes, after adhering to the transfer limits. |
  | 200 | REJECTED | INVALID\_PAYMENT\_INSTRUMENT | The transfer has been rejected because the payment instrument (fundsource\_id parameter in the API request) used for attempting the transfer is invalid. After correcting the payment instrument, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | After correcting the payment instrument, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting payment instrument |
  | 200 | REJECTED | PAYOUT\_INTERNAL\_ERROR | The transfer has been rejected because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | REJECTED | VELOCITY\_CHECK\_FAILED | The transfer has been rejected because the amount entered breaches the limits set for your payout account. After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). You can connect with Cashfree if you are not sure about the transfer limits set for your payout account. | After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). You can connect with Cashfree if you are not sure about the transfer limits set for your payout account. | Yes, after adhering to the transfer limits. |
  | 200 | REJECTED | PAYOUT\_INTERNAL\_ERROR | The transfer has been rejected because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | REJECTED | PAYOUT\_INTERNAL\_ERROR | The transfer has been rejected because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | REJECTED | DISABLED\_MODE | The transfer has been rejected because your payout account does not support this mode of transfer. You should get this mode activated on your payout account by contacting Cashfree, and then initiate a new transfer request. | You should get this mode activated on your payout account by contacting Cashfree, and then initiate a new transfer request. | Yes, after activating mode. |
  | 200 | REJECTED | BANK\_ACCOUNT\_INVALID | The transfer has been rejected because there is a mismatch in the Bank Account Number of the beneficiary ID and the Bank Account Number in the transfer request. After correcting the Bank Account Number, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | After correcting the Bank Account Number, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting the bank account number. |
  | 200 | REJECTED | BANK\_IFSC\_INVALID | The transfer has been rejected because there is a mismatch in the IFSC of the beneficiary ID and the IFSC in the transfer request. After correcting the IFSC, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | After correcting the IFSC, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting the IFSC |
  | 200 | REJECTED | VPA\_INVALID | The transfer has been rejected because there is a mismatch in the VPA handle of the beneficiary ID and the VPA handle in the transfer request. After correcting the VPA handle, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | After correcting the VPA handle, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting the VPA handle |
  | 200 | REJECTED | PHONE\_INVALID | The transfer has been rejected because there is a mismatch in the Phone Number of the beneficiary ID and the Phone Number in the transfer request. After correcting the Phone Number, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | After correcting the Phone Number, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting the phone number. |
  | 200 | REJECTED | BANK\_ACCOUNT\_DETAILS\_MISSING | The transfer has been rejected because the Bank Account Details are missing in the transfer request. After adding the Bank Account Details, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | After adding the Bank Account Details, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after adding the bank account details. |
  | 200 | REVERSED | ACCOUNT\_BLOCKED | The transfer has been reversed by the beneficiary bank as the end-beneficiary's account is blocked for receiving incoming funds. After correcting the account number or getting the account unblocked, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the account number or getting the account unblocked, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after adding new details or getting account unblocked. |
  | 200 | REVERSED | FAILED | The transfer has been reversed by the beneficiary bank as they were unable to credit the end beneficiary's bank account. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | - | Yes |
  | 200 | REVERSED | NRE\_ACCOUNT\_FAIL | The transfer has been reversed by the beneficiary bank as they were unable to credit the end beneficiary's bank account as it is an NRE Account and transfers to NRE Accounts are not supported. | Get a new account(non-NRE account) from the beneficiary; you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | No |
  | 200 | REVERSED | RETURNED\_FROM\_BENEFICIARY | The transfer has been reversed by the beneficiary bank as they were unable to credit the end beneficiary's bank account. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | REVERSED | BENE\_BANK\_DECLINED | The transfer has been declined by the beneficiary bank and they were unable to credit the end beneficiary's bank account. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | REVERSED | IMPS\_MODE\_FAIL | The transfer has been reversed by the beneficiary bank because the beneficiary bank account doesnot support IMPS transfers. This rejection is done by the beneficiary bank for the specific beneficiary account. You can try NEFT or other channels to do the disbursals. | You can reinitiate the transfer via Cashfree by changing the mode so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after changing mode. |
  | 200 | REVERSED | DEST\_LIMIT\_REACHED | The transfer has been reversed by the beneficiary bank as the end-beneficiary's account has reached a limit of receiving incoming funds. This rejection is done by the beneficiary bank for the specific beneficiary account. You can reinitiate the transfer after a while via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). The success of the request is contingent on beneficiary's limit being available to receive incoming funds. | The limits on the beneficiary account are typically refreshed every 24 hours. Its not clear when the 24 hour window shall elpase so you can then reinitiate the transfer via Cashfree after some time so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after some time. |
  | 200 | REVERSED | INVALID\_ACCOUNT\_FAIL | The transfer has been reversed by the beneficiary bank because the Account Number of the beneficiary is invalid. After correcting the account number, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the account number, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting the account number |
  | 200 | SUCCESS | SENT\_TO\_BENEFICIARY | The transfer has been initiated via the partner bank successfully. The request is waiting to be processed at the beneficiary bank to do the credit to the end beneficiary. | - | - |
  | 200 | SUCCESS | COMPLETED | The transfer has been initiated via the partner bank successfully, hence your account is debited and the request is successfully processed by the beneficiary bank and has been credited to the end beneficiary. | - | - |
  | 200 | REJECTED | TRANSFERID\_INVALID | transferid can contain only alphabets, numbers, underscore (\_), hyphen (-). | After correcting the transferid, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting transfer id. |
  | 200 | REJECTED | AMOUNT\_INVALID | amount can contain only numbers. | After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting amount. |
  | 200 | REJECTED | REMARKS\_INVALID | remarks can contain only alphabets, numbers and space. | After correcting the remarks, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting remarks. |
  | 200 | REJECTED | BENEID\_INVALID | beneId can contain only alphabets, numbers and underscore. | After correcting the beneid, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting beneficiary id. |
  | 200 | REJECTED | NAME\_INVALID | name can contain only alphabets, numbers and space. | After correcting the name, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting name. |
  | 200 | REJECTED | EMAIL\_INVALID | email is not a valid email format. | After correcting the email, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting email. |
  | 200 | REJECTED | IBAN\_INVALID | iban can contain only alphabet and numbers. | After correcting the iban, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting IBAN. |
  | 200 | REJECTED | TRANSFERMODE\_INVALID | transferMode can contain in one of banktransfer upi paytm amazonpay imps neft rtgs ppc. | After correcting the transfermode, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting mode. |
  | 200 | REJECTED | CURRENCY\_INVALID | currency is invalid. | After correcting the currency, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting currency. |
  | 200 | REJECTED | ACCOUNT\_DOES\_NOT\_EXIST | The transfer has been rejected because the beneficiary account/ VPA does not exist as per our partner bank. | After correcting the account number, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting details. |
  | 200 | FAILED | ACCOUNT\_DOES\_NOT\_EXIST | The transfer has failed because the beneficiary account/ VPA does not exist as per our partner bank. | After correcting the account number, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting details. |
  | 200 | REJECTED | AMAZON\_AMOUNT\_EXCEED | The transfer has been rejected because the amount entered breaches the limits set for the beneficiaries amazon account. | After verifying the limits for beneficiaries amazon account, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after verifying limits. |
  | 200 | FAILED | AMAZON\_AMOUNT\_EXCEED | The transfer has failed because the amount entered breaches the limits set for the beneficiaries amazon account. | After verifying the limits for beneficiaries amazon account, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after verifying limits. |
  | 200 | REJECTED | ANOMALY\_DETECTION | The transfer has been rejected as Cashfree risk product has detected an anamoly. | You can reinitiate the transfer request after validation at your end. | Yes, after validation. |
  | 200 | APPROVAL\_PENDING | ANOMALY\_DETECTION | The transfer requires approval as Cashfree risk product has detected an anamoly. | You can approve/reject the transfer on the merchant dashboard. Post the transfer is approved, the request is sent to the partner bank for further processing. | - |
  | 200 | FAILED | BAD\_CONNECTION | The transfer has failed because there was an intermittent internal error between Cashfree and the partner bank. | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after some time. |
  | 200 | REJECTED | BENE\_INVALID | The transfer has been rejected because the beneficiary added in the transfer request does not exist. | After adding the right beneficiary, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after adding beneficiary. |
  | 200 | FAILED | BENE\_INVALID | The transfer has failed because the beneficiary added in the transfer request does not exist. | After adding the right beneficiary, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after adding beneficiary. |
  | 200 | FAILED | BENE\_NOT\_REGISTERED | The transfer has been rejected because the beneficiary added in the transfer request is not registered with the partner bank. | After adding the right beneficiary, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after adding beneficiary. |
  | 200 | VALIDATION\_PENDING | BENE\_VERIFICATION\_PENDING | The transfer is pending because the beneficiary verification is pending. Once the beneficiary is validated we will attempt the transfers with partner bank(s). | - | - |
  | 200 | FAILED | BENEFICIARY\_BANK\_UNAVAILABLE | The transfer has failed because the respective beneficiary bank is offline. | After some time, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after some time. |
  | 200 | FAILED | BENEFICIARY\_NAME\_DIFFERS | The transfer has failed because the beneficiary name differs as per Cashfree's partner bank. | After adding the right beneficiary, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting name. |
  | 200 | REJECTED | BENEFICIARY\_NAME\_DIFFERS | The transfer has been rejected because the beneficiary name differs as per Cashfree's partner bank. | After adding the right beneficiary, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting name. |
  | 200 | REJECTED | BENEFICIARY\_NAME\_MISMATCH | The transfer has been rejected because the beneficiary name differs as per Cashfree's partner bank. | After adding the right beneficiary, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting name. |
  | 200 | REJECTED | CARD\_UNSUPPORTED | The transfer has been rejected because the card is not supported. | After changing the payment instrument details, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after changing instrument. |
  | 200 | FAILED | CARD\_UNSUPPORTED | The transfer has failed because the card is not supported. | After changing the payment instrument details, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after changing instrument. |
  | 200 | FAILED | DUPLICATE\_FAILED | The transfer has failed as the bank claims of receiving a duplicate request at their end as of now. | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, with new id. |
  | 200 | FAILED | ERROR\_RETRIEVING\_BALANCE | The transfer has failed because there was an intermittent issue at the partner bank's end. | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after some time. |
  | 200 | REJECTED | INVALID\_CARD | The transfer has been rejected because the card details are not correct. | After changing the payment instrument details, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting card. |
  | 200 | FAILED | INVALID\_CARD | The transfer has failed because the card details are not correct. | After changing the payment instrument details, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting card. |
  | 200 | REJECTED | INVALID\_CURRENCY\_FOR\_PYID | The transfer has been rejected because the transfer currency passed in the transfer request is not supported by Cashfree. | After changing the currency to INR, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after changing currency. |
  | 200 | FAILED | INVALID\_CURRENCY\_FOR\_PYID | The transfer has been rejected because the transfer currency passed in the transfer request is not supported by Cashfree. | After changing the currency to INR, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after changing currency. |
  | 200 | FAILED | INVALID\_MODE\_FAIL | The transfer has failed because the requested transfer mode is not supported for this beneficiary account as per the partner bank. | After changing the transfer mode, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after changing mode. |
  | 200 | REJECTED | INVALID\_OR\_NO\_SUCH\_ACCOUNT\_TYPE | The transfer has been rejected because the beneficiary account type is invalid or not supported as per our partner bank. | Get a new account from the beneficiary; you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after new account. |
  | 200 | FAILED | INVALID\_OR\_NO\_SUCH\_ACCOUNT\_TYPE | The transfer has failed because the beneficiary account type is invalid or not supported as per our partner bank. | Get a new account from the beneficiary; you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after new account. |
  | 200 | FAILED | INVALID\_PHONE\_BENEFICIARY | The transfer has failed because the beneficiary's phone number is not linked to any VPA. | After adding the right phone beneficiary, You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting phone. |
  | 200 | REJECTED | INVALID\_TRANSFER\_CURRENCY | The transfer has been rejected because the transfer currency passed in the transfer request is not supported by Cashfree. | After changing the currency to INR, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after changing currency. |
  | 200 | FAILED | INVALID\_TRANSFER\_CURRENCY | The transfer has failed because the transfer currency passed in the transfer request is not supported by Cashfree. | After changing the currency to INR, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after changing currency. |
  | 200 | REJECTED | KYC\_COMPLIANCE\_VERIFICATION\_FAILED | The transfer has failed because the KYC verification has failed. | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after KYC resolution. |
  | 200 | REJECTED | KYC\_REQUIREMENTS\_NOT\_SATISFIED | The transfer has failed because the KYC requirements have not been satisfied. | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after completing KYC. |
  | 200 | FAILED | LOAD\_LIMIT\_EXHAUSTED | The transfer has failed because the beneficiaries account has reached maximum transaction amount limit. | After 24 hours, You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after 24 hours. |
  | 200 | FAILED | LOAN\_FUND\_MOVEMENT\_FAILURE | The transfer has failed because of an intermittent issue at Cashfree's end. | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after some time. |
  | 200 | PENDING | LOW\_BALANCE\_QUEUED | The transfer is pending because the balance in the fund source is exhausted. This transfer will be processed after you recharge the fund source, you need not reinitiate this transfer. | This transfer will be processed after you recharge the fund source, you need not reinitiate this transfer. Please rely on check status API or webhook for checking the status of this transfer. | - |
  | 200 | REJECTED | MANUALLY\_REJECTED | The transfer has been manually rejected by you. | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree. | Yes, if needed. |
  | 200 | REJECTED | PAYOUT\_INACTIVE | The transfer has been rejected because your payout account has been inactive. | After getting the account activated, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after activation. |
  | 200 | PENDING | PENDING | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. | Rely on Check Status API or Webhooks | - |
  | 200 | FAILED | POOL\_CONNECTION\_TIMEOUT | The transfer has failed because there was a connection issue with the partner bank's end. | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after some time. |
  | 200 | REJECTED | QUICK\_TRANSFER\_DISABLED | The transfer has been rejected because quick transfer is disabled for your payout account. | After getting quick transfer enabled, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after enabling. |
  | 200 | REJECTED | REJECTED | Transfer rejected. | - | Yes, after correction. |
  | 200 | REVERSED | REVERSED | The transfer has been reversed by the beneficiary bank as the credit to end-beneficiary's account has failed. | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correction. |
  | 200 | FAILED | RTGS\_MODE\_FAIL | The transfer has failed because the beneficiary account doesnot support RTGS transfers. | You can try NEFT or other channels to do the disbursals. | Yes, via different mode. |
  | 200 | FAILED | SUSPECTED\_FAILED | The transfer has failed, as the partner bank suspects that the transfer is of fraudulent nature. | - | No (investigate). |
  | 200 | REJECTED | VBA\_TRANSFER\_DISABLED | The transfer has been rejected because transfers to virtual bank accounts are not enabled for your Cashfree Account. | After getting payouts to virtual bank accounts enabled, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). You can connect with Cashfree for enabling payouts to virtual bank accounts. | Yes, after enabling. |
  | 200 | REJECTED | ERROR\_SELECTING\_FUND\_SOURCE | The transfer has been rejected because their is some issue with your account configuration. | You can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after fixing config. |
  | 200 | VALIDATION\_PENDING | VALIDATION\_PENDING | The transfer is pending because the beneficiary verification is pending. Once the beneficiary is validated we will attempt the transfers with partner bank(s). | Rely on Check Status API or Webhooks | - |
  | 200 | REJECTED | INVALID\_BENEFICIARY\_CODE | The transfer has been rejected because the bene code is Invalid. | After correcting the beneficiary code, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting code. |
  | 200 | REJECTED | DUPLICATE\_TRANSFER | The transfer is already present in the file or has been processed previously. Please change the transferId in the api request. | After changing the Transfer Id, You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, with new transfer id. |

  #### 4XX errors

  | HTTP status code | Error code | Message | Next action |
  | :- | :- | :- | :- |
  | 400 | transfer\_id\_missing | transfer\_id is missing in the request | Enter a valid transfer\_id in the request. |
  | 400 | transfer\_id\_invalid | transfer\_id should be alphanumeric | Enter a valid transfer\_id in the request. |
  | 400 | transfer\_amount\_invalid | transfer\_amount should be greater then 1.00 | Enter an amount greater than 1.00. |
  | 400 | transfer\_amount\_missing | transfer\_amount is missing in the request | Provide a value for the transfer\_amount parameter in the request. |
  | 400 | transfer\_mode\_invalid | transfer\_mode is invalid allowed values are : bank, imps, neft, rtgs, upi, paytm, amazonpay, card and cardupi | Provide a valid transfer\_mode in the request. |
  | 400 | beneficiary\_details.beneficiary\_id\_invalid | beneficiary\_id should be alphanumeric | Enter a valid beneficiary\_id. |
  | 400 | beneficiary\_details.beneficiary\_name\_invalid | beneficiary\_name is invalid. only alphabets and whitespaces are allowed | Enter a valid beneficiary\_id. |
  | 400 | beneficiary\_details.beneficiary\_instrument\_details.bank\_account\_number\_invalid | bank\_account\_number should be alphanumeric | Enter a valid bank\_account\_number. |
  | 400 | beneficiary\_details.beneficiary\_instrument\_details.bank\_account\_number\_invalid | Bank account number passed in the request does not match with the beneficiary with beneficiary\_id :: test\_beneId | Enter the correct bank\_account\_number associated with the beneficiary\_id. |
  | 400 | beneficiary\_details.beneficiary\_instrument\_details.bank\_ifsc\_invalid | bank\_ifsc should be in standard ifsc format | Enter a valid bank\_ifsc. |
  | 400 | beneficiary\_details.beneficiary\_instrument\_details.bank\_ifsc\_invalid | Bank ifsc passed in the request does not match with the beneficiary with beneficiary\_id :: test\_beneId | Enter the correct bank\_ifsc associated with the beneficiary\_id. |
  | 400 | beneficiary\_details.beneficiary\_instrument\_details.vpa\_invalid | vpa is in invalid format | Enter a valid VPA. |
  | 400 | beneficiary\_details.beneficiary\_instrument\_details.vpa\_invalid | Vpa passed in the request does not match with the beneficiary with beneficiary\_id :: test\_beneId | Enter the correct vpa associated with the beneficiary\_id. |
  | 404 | beneficiary\_not\_found | Beneficiary does not exist | Enter a valid beneficiary\_id. |

  <br />
</Accordion>


# Validate Payout
Source: https://www.cashfree.com/docs/api-reference/payouts/v2/validate-payout-v2

post /payout/validatePayout
Validates a UPI VPA or phone number and returns a single-use transfer token valid for one hour. Pass this token to the [Process Validated Payout API](/docs/api-reference/payouts/v2/verify-and-pay-transfers-v2) (`POST /payout/transfers`) to initiate the payout.

In the request body, pass the value for exactly one of `vpa` or `phone`, not both.

The response contains either basic or advanced VPA details. Advanced details include IFSC branch information. To enable advanced details for your account, fill the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod&raise_issue=1).




# Verify
Source: https://www.cashfree.com/docs/api-reference/payouts/v2/verify

post /payout/v1/verifyToke
Use this API to verify the bearer token generated. If the token does not exist/invalid/expired, the response "Token is not valid" is returned. Regenerate token in case of token expiry to make API calls (use /payout/v1/authorize for this).



# Verify
Source: https://www.cashfree.com/docs/api-reference/payouts/v2/verify-1

post /payout/v1/verifyToken
Verify the bearer token generated. If the token does not exist, is invalid, or has expired, the response "Token is not valid" is returned. Regenerate token in case of token expiry for making API calls ( use /payout/v1/authorize for this).



# Process Validated Payout
Source: https://www.cashfree.com/docs/api-reference/payouts/v2/verify-and-pay-transfers-v2

post /payout/transfers
Initiates a UPI payout using the transfer token returned by the [Validate Payout API](/docs/api-reference/payouts/v2/validate-payout-v2). The token is single-use and expires after one hour. When you use a transfer token, only `upi` is supported as the transfer mode.

The `transfer_id` in this request must match the `transfer_id` you used in that Validate Payout call.

Optionally set `fundsource_id` to the connected bank account to use as the fund source.




# Webhook Version V1
Source: https://www.cashfree.com/docs/api-reference/payouts/v2/webhooks/webhooks-v1

Configure Cashfree Payouts v1 webhooks to receive HTTP callbacks for transfer events, set the webhook URL in the dashboard, and verify signatures.

Webhooks are events that notify you about the payment status. All Payout integrations should establish a webhook to listen to payout events, like status changes on payments. Webhooks are HTTP callbacks that receive notification messages for events.

Webhooks help you receive automatic updates and are significant for completing the integration with Cashfree. Webhooks are triggered with a request from your side, for example, when a transfer fails or when a daily report is available. Requests get processed both synchronously and asynchronously. In rare scenarios, for some payment methods, the outcome may take a longer duration to confirm. Cashfree notifies you once we get updates from the bank about the payment status.

Do not go live without signature verification if you are using webhooks.

<Note>
  The oldest API keys, that are active, for Webhook signature verification to
  avoid signature mismatch errors.
</Note>

### Add a webhook

Follow the instructions below to configure webhooks for version 2 APIs:

1. Log in to the *Payouts* dashboard using your credentials.
2. Navigate to **Developers** > **Webhooks**.
3. Click **Add Webhook URL** in the *Webhooks* page.
   <Frame>
     <img />
   </Frame>
4. In the *Add Webhook* popup, enter the following information:
   * **Webhook URL**: Enter the URL where you want to receive the transfer related notifications.
   * **Select a webhook version**: Select **V1** from the dropdown menu.
5. Click **Test & Add Webhook**.
   <Frame>
     <img />
   </Frame>

***

## Webhook events

Payouts webhooks enable you to receive updates about all event-driven activities originating from your account. Below is the list of payouts webhooks:

| Events | Notifications |
| :- | :- |
| TRANSFER\_SUCCESS | Transfer successful at the bank and account debited. |
| TRANSFER\_FAILED | Sent whenever a transfer attempt fails. |
| TRANSFER\_REVERSED | Transfer reversed by the beneficiary bank. |
| CREDIT\_CONFIRMATION | Confirmation of balance credit. |
| TRANSFER\_ACKNOWLEDGED | After the beneficiary bank has deposited the money it confirms the transfer. |
| TRANSFER\_REJECTED | Transfer rejected by Cashfree. |
| BENEFICIARY\_INCIDENT | Sent whenever a beneficiary incident is created/resolved. |
| LOW\_BALANCE\_ALERT | Payouts recharge account low balance alert. |
| [BULK\_TRANSFER\_REJECTED](/docs/api-reference/payouts/v2/webhooks/webhooks-v1#bulk_transfer_rejected) | One of the transfers in the batch transfer file has been rejected. |

## TRANSFER\_SUCCESS​

Sent when a transfer is attempted successfully.

| Parameters | Description |
| :- | :- |
| event | It contains the name of the event which just occurred. Value = TRANSFER\_SUCCESS. |
| transferId | Id of the transfer passed by the merchant. |
| referenceId | Id of the transfer generated by Cashfree. |
| acknowledged | The flag indicates if the beneficiary bank has acknowledged the transfer. |
| eventTime | Transfer initiation time. |
| utr | Unique transaction reference number provided by the bank. |
| signature | A unique string that helps distinguish that the request is genuine and initiated by Cashfree. |

### What does the response parameter 'acknowledged' mean

The acknowledged parameter value conveys if the beneficiary received the funds by checking its value. Ack = 1 or 0. 1 denotes the beneficiary received funds, and 0 denotes the beneficiary had not received funds.

The cash flow happens as explained below:

1. Debit: The debit of the transfers happens on the remitter account. After a successful debit, the beneficiary bank does further processing. When only the debit is successful, Ack = 0.

2. Credit: The beneficiary bank credits the fund to the account. The transfer is sent from the remitter bank to the beneficiary bank after a successful debit. When the credit to the end beneficiary is successful, Ack = 1.

To confirm the status of a payout, you need to check the acknowledged parameter value. If the value is 1, you can mark the transfer as successful. However, if the value is 0, you must either wait for the TRANSFER\_ACKNOWLEDGED webhook event or use the [Get Transfer Status](/docs/api-reference/payouts/v1/get-transfer-status-v12) API and confirm the acknowledged value.

***

## ​TRANSFER\_FAILED

Sent when a transfer attempt fails.

| Parameters | Description |
| :- | :- |
| event | It contains the name of the event which just occurred. Value = TRANSFER\_FAILED. |
| transferId | Id of the transfer passed by the merchant |
| referenceId | Id of the transfer generated by Cashfree. |
| reason | Reason for failure. |
| signature | A unique string that helps distinguish that the request is genuine and initiated by Cashfree. |

## TRANSFER\_REVERSED

Sent when the beneficiary bank reverses a transfer.

| Parameters | Description |
| :- | :- |
| event | It contains the name of the event which just occurred. Value = TRANSFER\_REVERSED. |
| transferId | Id of the transfer passed by the merchant. |
| referenceId | Id of the transfer generated by Cashfree. |
| eventTime | Time at which the transfer was reversed. |
| reason | Reason for failure. |
| signature | A unique string that helps distinguish that the request is genuine and initiated by Cashfree. |

## CREDIT\_CONFIRMATION

Sent when the balance credit is confirmed.

| Parameters | Description |
| :- | :- |
| event | It contains the name of the event which just occurred. Value = CREDIT\_CONFIRMATION. |
| ledgerBalance | The overall balance of the ledger. |
| amount | Amount deposited. |
| utr | Unique transaction reference number provided by the bank. |
| signature | A unique string that helps distinguish that the request is genuine and initiated by Cashfree. |

## TRANSFER\_ACKNOWLEDGED

Sent when the bank acknowledges a transfer.

| Parameters | Description |
| :- | :- |
| event | It contains the name of the event which just occurred. Value = TRANSFER\_ACKNOWLEDGED. |
| transferId | Id of the transfer passed by the merchant. |
| referenceId | Id of the transfer generated by Cashfree. |
| acknowledged | The flag illustrates if the beneficiary bank acknowledges the transfer. |
| signature | A unique string that helps distinguish that the request is genuine and initiated by Cashfree. |

## TRANSFER\_REJECTED

Sent when a transfer is rejected.

| Parameter | Description |
| :- | :- |
| event | It contains the name of the event which just occurred. Value = TRANSFER\_REJECTED. |
| transferId | Id of the transfer passed by the merchant. |
| referenceId | Id of the transfer generated by Cashfree. |
| reason | Reason for rejection. |
| signature | A unique string that helps distinguish that the request is genuine and initiated by Cashfree. |

## BENEFICIARY\_INCIDENT

Sent when a beneficiary incident is created or resolved.

| Parameter | Description |
| :- | :- |
| event | It contains the name of the event which just occurred. Value = BENEFICIARY\_INCIDENT. |
| beneEntity | The entity of the beneficiary (BANK). |
| id | Identifier of the incident. |
| mode | Mode of the incident (IMPS/NEFT) |
| startedAt | Start time of the incident. |
| status | Status of the incident (ACTIVE/RESOLVED). |
| isScheduled | Scheduled or unscheduled incident (true or false). |
| severity | The severity of the incident (LOW/HIGH). |
| entityName | Name of the entity on which the incident is created (Bank Name). |
| entityCode | Code of the entity on which the incident is created. |
| resolvedAt | Resolution time of the incident. |

## LOW\_BALANCE\_ALERT

Sent when the payout balance is low.

| Parameter | Description |
| :- | :- |
| event | It contains the name of the event which just occurred. Value = LOW\_BALANCE\_ALERT |
| currentBalance | The current balance of the beneficiary account |
| alertTime | Alert initiation time. |
| signature | A unique string that helps distinguish that the request is genuine and initiated by Cashfree. |

### BULK\_TRANSFER\_REJECTED

Sent when one of the transfers in the batch transfer file has been rejected.

| Parameter | Description |
| :- | :- |
| event | One of the transfers in the batch transfer file has been rejected |
| transferId | It is the unique ID you created to identify the transfer |
| batchTransferReferenceId | It is the ID created by Cashfree for internal reference. |
| eventTime | Event initiation time |
| reason | It describes the reason for the rejection. |
| signature | A unique string which helps distinguish that the request is genuine and initiated by Cashfree. |

**Delay in Receiving the Response**

Cashfree receives a response from the bank with the status of the transfer instantly. At times the response may get delayed due to various reasons, and the transaction status will be marked as Pending, till we get a response.

Cashfree polls the transaction status from the bank for the next 72 hours. If we do not receive the status after 72 hours, you must manually reconcile the transaction.

***

### Signature Verification

Cashfree sends a signature alongside every webhook, verifying this signature ( passed along with the POST parameters ) is mandatory before processing any response. It helps authenticate that the webhook is from Cashfree.

We strongly recommend whitelisting Cashfree production IP to help make your communication with us more secure.

Following are the steps to verify Cashfree signature:

1. Get all the POST parameters except ‘signature’ and assign it to an array as key-value pair.
2. Sort the array based on keys.
3. Concatenate all the values in this array and the resultant is the post data (say, postData).
4. Encrypt **postData** using SHA-256, then base64-encode it.
5. Now verify if both the signature calculated and the signature received a match.
6. Proceed further if it matches, else discard the request.

Our libraries also support signature verification. To verify the signature returned by Cashfree call the following methods from the library.

Below are the code snippets that can help you verify the signature:

<CodeGroup>
  ```php PHP theme={"dark"}
  <?php
    $data = $_POST;
    $signature = $_POST["signature"];
    unset($data["signature"]); // $data now has all the POST parameters except signature
    ksort($data); // Sort the $data array based on keys
    $postData = "";
    foreach ($data as $key => $value){
      if (strlen($value) > 0) {
        $postData .= $value;
      }
    }
    $hash_hmac = hash_hmac('sha256', $postData, $clientSecret, true) ;
    
    // Use the clientSecret from the oldest active Key Pair.
    $computedSignature = base64_encode($hash_hmac);
    if ($signature == $computedSignature) {
      // Proceed based on $event
    } else {
      // Reject this call
    }
  ?>
  ```

  ```java Java theme={"dark"}
  import java.util.LinkedHashMap;
  import java.util.Map;
  import java.util.stream.Collectors;

  import com.fasterxml.jackson.core.type.TypeReference;
  import com.fasterxml.jackson.databind.ObjectMapper;
  import javax.crypto.spec.SecretKeySpec;
  import javax.crypto.Mac;
  import org.apache.commons.codec.binary.Base64;

  public class ComputedSignature {

      public static boolean checkSignature(String clientSecret, String data) {

  // write your code here
  ObjectMapper objectMapper = new ObjectMapper();
  String signatureKey = "signature";
  String hash = "";
  try {
  Map<String, Object> jsonMap = objectMapper.readValue(data, new TypeReference<Map<String, Object>>(){});
  String signature = jsonMap.get(signatureKey).toString();

              // remove the signature from map
              jsonMap.remove(signatureKey);
               Map<String, Object> sortedMap =  jsonMap.entrySet().
                       stream().
                       sorted(Map.Entry.comparingByKey()).
                       collect(Collectors.toMap(
                               Map.Entry::getKey,
                               Map.Entry::getValue,
                               (oldValue, newValue) -> oldValue, LinkedHashMap::new
                       ));

               // sort the map based on keys
               String postDataString = sortedMap.keySet().stream().map(key -> sortedMap.get(key).toString()).collect(Collectors.joining());

               // encode the post data on sha256
               Mac sha256HMAC = Mac.getInstance("HmacSHA256");
               SecretKeySpec secretKey  = new SecretKeySpec(clientSecret.getBytes(), "HmacSHA256");
               sha256HMAC.init(secretKey);

               hash = Base64.encodeBase64String(sha256HMAC.doFinal(postDataString.getBytes()));

               // check the hash generated with signature passed
               return hash.equals(signature);

          } catch (Exception e) {
              e.printStackTrace();
              return false;
          }
      }

  }

  ```

  ```javascript Node theme={"dark"}
  const Cashfree = require("cashfree-sdk");
  //convert post response recived in the notification end point to json
  //and pass that to the SDK.
  Cashfree.Payouts.VerifySignature(webhookPostDataJson, signature, clientSecret);
  ```

  ```python Python theme={"dark"}
  from cashfree_sdk import verification

  #webhook_data = response.content
  webhook_data = '{"cashgramId": "5b8283182e0711eaa4c531df6a4f439b-28", "event": "CASHGRAM_EXPIRED", "eventTime": "2020-01-03 15:01:06", "reason": "OTP_ATTEMPTS_EXCEEDED", "signature": "TBpM+4nr1DsWsov7QiHSTfRJP4Z9BD8XrDgEhBlf9ss="}'
  verification.verify_webhook(webhook_data, 'JSON')
  ```
</CodeGroup>

## Webhook Retries

Cashfree webhooks service does its best to deliver events to your webhook endpoint. It's best practice for your application to respond to the callback. Our webhook service may send many payloads to a single endpoint in quick succession. You will need to build an application and configure your server to receive the response we send when events get triggered during the payout process.

Your server should return a 200 HTTP status code to acknowledge that you received the webhook without any issues. Any other information you return in the request headers or request body is ignored. Any response code outside the 200 range, including 3xx codes, indicates that you didn't receive the webhook.

When Cashfree doesn't receive the acknowledgement for any reason, we retry to establish communication at regular intervals. If we don't receive the response after several attempts, we gradually decrease the rate of retries. Based on this count, the service is disabled if it fails more than five times.

If you don't receive notifications from Cashfree as expected, please fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1).

## IPs to whitelist

When you decide to consume the webhooks, first, you need to verify whether your systems need IP whitelisting to be done at your end or not. Accordingly, you can whitelist the below IPs of Cashfree:

| UAT |
| :- |
| 52.66.25.127 |
| 15.206.45.168 |

| Prod |
| :- |
| 52.66.101.190 |
| 3.109.102.144 |
| 18.60.134.245 |
| 18.60.183.142 |

| Port |
| :- |
| 443 (secured) |


# Webhooks Version V2
Source: https://www.cashfree.com/docs/api-reference/payouts/v2/webhooks/webhooks-v2

Set up Cashfree Payouts v2 webhooks to receive HTTP callbacks for transfer events, configure retries, whitelist Cashfree IPs, and explore sample event payloads.

Webhooks are HTTP callbacks that Cashfree sends to your server when specific events occur in your payout transactions. They provide real-time notifications about transfer status changes, enabling you to automate your business processes and keep your systems synchronised with transaction updates.

Version 2 webhooks offer enhanced reliability, improved payload structure, and additional event types compared to the previous version. They're essential for maintaining accurate transaction records and providing timely updates to your end users about their transfer status.

For seamless integration and security in handling your transactions, refer to the following essential guidelines:

* [Add a webhook](#add-a-webhook)
* [Webhook retries](#webhook-retries)
* [IPs to whitelist](#ips-to-whitelist)

### Add a webhook

Follow the instructions below to configure webhooks for version 2 APIs:

1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/merchants/landing).
2. Select **Payouts**.
3. Navigate to **Developers** > **Webhooks**.
4. Click **Add Webhook URL** on the *Webhooks* page.

<Frame>
  <img />
</Frame>

5. In the *Add Webhook* popup, enter the following information:
   * **Webhook URL**: Enter the URL where you want to receive transfer-related notifications.
   * **Select a webhook version**: Select **V2** from the dropdown menu.

<Note>
  **Webhook Version: V2**: You will receive V2 webhooks only if you select the option as described and configure the respective URL.
</Note>

6. Click **Test & Add Webhook**.
   <Frame>
     <img />
   </Frame>

## Webhook signature verification code

These code snippets provide functionality to verify the authenticity of webhook requests and parse the payload data. They ensure that incoming webhook requests are from a trusted source by checking their signature and then processing the request data.

<CodeGroup>
  ```go Go theme={"dark"}
  type PayoutWebhookEvent struct {
  Type   string
  Raw    string
  Object interface{}
  }

  func PayoutVerifyWebhookSignature(signature string, rawBody string, timestamp string) (*PayoutWebhookEvent, error) {
  signatureString := timestamp + rawBody
  hmacInstance := hmac.New(sha256.New, []byte(*XClientSecret))
  hmacInstance.Write([]byte(signatureString))
  bytesData := hmacInstance.Sum(nil)
  generatedSignature := base64.StdEncoding.EncodeToString(bytesData)
  if generatedSignature == signature {
  var object interface{}
  err := json.Unmarshal([]byte(rawBody), &object)
  if err != nil {
  return nil, errors.New("something went wrong when unmarshalling raw body")
  }
  if objectAsMapInterface, ok := object.(map[string]interface{}); ok {
  if webhookType, ok := objectAsMapInterface["type"].(string); ok {
  return &PayoutWebhookEvent{Type: webhookType, Raw: rawBody, Object: object}, nil
  }
  }
  return &PayoutWebhookEvent{Type: "", Raw: rawBody, Object: object}, nil
  }
  return nil, errors.New("generated signature and received signature did not match")
  }
  ```

  ```jsx Node theme={"dark"}
  import crypto from "crypto";

  class PayoutWebhookEvent {
  	constructor(type, rawBody, object) {
  		this.type = type;
  		this.raw = rawBody;
  		this.object = object;
  	}
  }

  class Cashfree {
  	static XClientSecret;
  	static XApiVersion = "2024-01-01";

  	/**
  	 * Use this API to verify your webhook signature once you receive from Cashfree's server.
  	 * @summary Verify Webhook Signatures
  	 * @param {string} signature that is present in the header of the webhook ("x-webhook-signature")
  	 * @param {string} rawBody is the entire body sent to the server in string format
  	 * @param {string} timestamp that is present in the header of the webhook ("x-webhook-timestamp")
  	 * @throws {Error}
  	 */
  	static PayoutVerifyWebhookSignature(signature, rawBody, timestamp) {
  		const body = timestamp + rawBody;
  		const secretKey = Cashfree.XClientSecret;
  		let generatedSignature = crypto
  			.createHmac("sha256", secretKey)
  			.update(body)
  			.digest("base64");
  		if (generatedSignature === signature) {
  			let jsonObject = JSON.parse(rawBody);
  			return new PayoutWebhookEvent(jsonObject.type, rawBody, jsonObject);
  		}
  		throw new Error(
  			"Generated signature and received signature did not match."
  		);
  	}
  }
  ```
</CodeGroup>

<Note>
  **Client secret for webhooksignature**<br />
  Please ensure that the oldest active client secret is used to generate the webhook signature. Using any other client secret will lead to a signature mismatch.
</Note>

### Components

The webhook signature verification implementation uses the following key components to ensure secure processing of webhook events:

#### PayoutWebhookEvent class

This class represents the structure of a webhook event and contains the following properties:

| Property | Type | Description |
| :- | :- | :- |
| `Type` | string | The type of the event. |
| `Raw` | string | The raw JSON body of the webhook request. |
| `Object` | object | The parsed JSON object from the raw body. |

#### PayoutVerifyWebhookSignature method

This method verifies the signature of a webhook request and parses the data. Use the following parameters when calling this method:

| Parameter | Type | Description |
| :- | :- | :- |
| `signature` | string | The HMAC signature provided in the header information of the webhook. |
| `rawBody` | string | The raw JSON body of the request in string format. |
| `timestamp` | string | The timestamp provided in the header information of the webhook. |

#### Cashfree class

This class provides the method for verifying webhook signatures and includes the following properties:

| Property | Type | Description |
| :- | :- | :- |
| `XClientSecret` | string | Secret key. |
| `XAPIVersion` | string | The API version: 2024-01-01. |

## Webhook events

Payouts webhooks enable you to receive updates about all event-driven activities originating from your account. Below is the list of payout webhooks:

| Events | Notifications |
| :- | :- |
| `TRANSFER_ACKNOWLEDGED` | You receive this event when the transfer is successful, the amount is debited from the account, and the funds are credited to the end user. |
| `TRANSFER_SUCCESS` | You receive this event when the transferred amount is deposited in the beneficiary's bank account. |
| `TRANSFER_FAILED` | You receive this event when the transfer attempt fails. |
| `TRANSFER_REVERSED` | You receive this event when the beneficiary's bank reverses the transfer request. |
| `TRANSFER_REJECTED` | You receive this event when Cashfree rejects the transfer request. |
| `BULK_TRANSFER_REJECTED` | You receive this event when one or more transfers in the batch transfer request are rejected. |
| `BENEFICIARY_INCIDENT` | You receive this event when there is a service disruption or incident affecting a specific beneficiary bank or payment mode. |
| `CREDIT_CONFIRMATION` | You receive this event when funds are credited to your account balance, providing confirmation of the credit transaction. |
| `LOW_BALANCE_ALERT` | You receive this event when your account balance falls below a predefined threshold, alerting you to add funds. |

### Sample payload

The following examples show the JSON payload structure for each webhook event type listed above. Each payload contains event-specific data that helps you understand the transfer status and take appropriate action in your application.

<CodeGroup>
  ```json ACKNOWLEDGED theme={"dark"}
  {
  	"data": {
  		"transfer_id": "JUNOB2018",
  		"cf_transfer_id": "123456",
  		"status": "SUCCESS",
  		"status_code": "COMPLETED",
  		"status_description": "The transfer has been initiated via the partner bank successfully, hence your account is debited and the request is successfully processed by the beneficiary bank and has been credited to the end beneficiary.",
  		"beneficiary_details": {
  			"beneficiary_id": "JOHN18011",
  			"beneficiary_instrument_details": {
  				"bank_account_number": "7766671501729",
  				"bank_ifsc": "SBIN0000003"
  			}
  		},
  		"transfer_amount": 1,
  		"transfer_service_charge": 1,
  		"transfer_service_tax": 0.18,
  		"transfer_mode": "BANK",
  		"transfer_utr": "TESTR92023012200543116",
  		"fundsource_id": "CASHFREE_1",
  		"added_on": "2021-11-24T13:39:25Z",
  		"updated_on": "2021-11-24T13:40:27Z"
  	},
  	"event_time": "2024-07-25T17:43:37",
  	"type": "TRANSFER_ACKNOWLEDGED"
  }
  ```

  ```json SUCCESS theme={"dark"}
  {
  	"data": {
  		"transfer_id": "JUNOB2018",
  		"cf_transfer_id": "123456",
  		"status": "SUCCESS",
  		"status_code": "SENT_TO_BENEFICIARY",
  		"status_description": "The transfer has been initiated via the partner bank successfully. The request is waiting to be processed at the beneficiary bank to do the credit to the end beneficiary.",
  		"beneficiary_details": {
  			"beneficiary_id": "JOHN18011",
  			"beneficiary_instrument_details": {
  				"bank_account_number": "7766671501729",
  				"bank_ifsc": "SBIN0000003"
  			}
  		},
  		"transfer_amount": 1,
  		"transfer_service_charge": 1,
  		"transfer_service_tax": 0.18,
  		"transfer_mode": "BANK",
  		"transfer_utr": "TESTR92023012200543116",
  		"fundsource_id": "CASHFREE_1",
  		"added_on": "2021-11-24T13:39:25Z",
  		"updated_on": "2021-11-24T13:40:27Z"
  	},
  	"event_time": "2024-07-25T17:43:37",
  	"type": "TRANSFER_SUCCESS"
  }
  ```

  ```json FAILED theme={"dark"}
  {
  	"data": {
  		"transfer_id": "JUNOB2018",
  		"cf_transfer_id": "123456",
  		"status": "FAILED",
  		"status_code": "IMPS_MODE_FAIL",
  		"status_description": "The transfer has failed because the beneficiary account doesnot support IMPS transfers. This rejection is done by the partner bank for the specific beneficiary account. You can try NEFT or other channels to do the disbursals.",
  		"beneficiary_details": {
  			"beneficiary_id": "JOHN18011",
  			"beneficiary_instrument_details": {
  				"bank_account_number": "7766671501729",
  				"bank_ifsc": "SBIN0000003"
  			}
  		},
  		"transfer_amount": 1,
  		"transfer_service_charge": 1,
  		"transfer_service_tax": 0.18,
  		"transfer_mode": "BANK",
  		"transfer_utr": "TESTR92023012200543116",
  		"fundsource_id": "CASHFREE_1",
  		"added_on": "2021-11-24T13:39:25Z",
  		"updated_on": "2021-11-24T13:40:27Z"
  	},
  	"event_time": "2024-07-25T17:43:37",
  	"type": "TRANSFER_FAILED"
  }
  ```

  ```json REVERSED theme={"dark"}
  {
  	"data": {
  		"transfer_id": "JUNOB2018",
  		"cf_transfer_id": "123456",
  		"status": "REVERSED",
  		"status_code": "INVALID_ACCOUNT_FAIL",
  		"status_description": "The transfer has been reversed by the beneficiary bank because the Account Number of the beneficiary is invalid. After correcting the account number, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s).",
  		"beneficiary_details": {
  			"beneficiary_id": "JOHN18011",
  			"beneficiary_instrument_details": {
  				"bank_account_number": "7766671501729",
  				"bank_ifsc": "SBIN0000003"
  			}
  		},
  		"transfer_amount": 1,
  		"transfer_mode": "BANK",
  		"fundsource_id": "CASHFREE_1",
  		"added_on": "2021-11-24T13:39:25Z",
  		"updated_on": "2021-11-24T13:40:27Z"
  	},
  	"event_time": "2024-07-25T17:43:37",
  	"type": "TRANSFER_REVERSED"
  }
  ```

  ```json REJECTED theme={"dark"}
  {
  	"data": {
  		"transfer_id": "JUNOB2018",
  		"cf_transfer_id": "123456",
  		"status": "REJECTED",
  		"status_code": "INVALID_MODE_FOR_PYID",
  		"status_description": "The transfer has been rejected because the fundsource does not support this mode of transfer. You should get this mode activated on the fundsource by contacting Cashfree, and then initiate a new transfer request.",
  		"beneficiary_details": {
  			"beneficiary_id": "JOHN18011"
  		},
  		"transfer_amount": 1,
  		"transfer_mode": "BANK",
  		"fundsource_id": "CASHFREE_1",
  		"added_on": "2021-11-24T13:39:25Z",
  		"updated_on": "2021-11-24T13:40:27Z"
  	},
  	"event_time": "2024-07-25T17:43:37",
  	"type": "TRANSFER_REJECTED"
  }
  ```

  ```json BULK_TRANSFER_REJECTED theme={"dark"}
  {
  	"data": {
  		"batch_transfer_id": "test_batch_transfer_id",
  		"cf_batch_transfer_id": "123456",
  		"status": "REJECTED"
  	},
  	"event_time": "2024-07-25T17:43:37",
  	"type": "BULK_TRANSFER_REJECTED"
  }
  ```

  ```json LOW_BALANCE theme={"dark"}
  {
    "data" : {
      "current_balance": "8.53",
      "fundsource_id": "astring"
    },
    "type": "LOW_BALANCE_ALERT",
    "event_time": "2024-07-25T17:43:37"
  }
  ```

  ```json CREDIT_CONFIRMATION theme={"dark"}
  {
    "data" : {
      "ledger_balance": "8.53",
      "utr": "ledgerEntryUTR654321",
      "amount": "10.50",
      "fundsource_id": "astring"
    },
    "type": "CREDIT_CONFIRMATION",
    "event_time": "2024-07-25T17:43:37"
  }

  ```

  ```json BENEFICIARY_INCIDENT theme={"dark"}
  {
    "data" : {
      "bene_entity": "BANK",
      "id": 789,
      "mode": "UPI",
      "started_at": "yyyy-MM-dd HH:mm:ss",
      "status": "ACTIVE",
      "is_scheduled": true,
      "severity": "High",
      "entity_name": "name",
      "entity_code": "code",
      "resolved_at": "yyyy-MM-dd HH:mm:ss"
    },
    "event_time": "2024-07-25T17:43:37",
    "type": "BENEFICIARY_INCIDENT"
  }
  ```
</CodeGroup>

### Parameters

Find the parameters and their descriptions for the events `TRANSFER_ACKNOWLEDGED`, `TRANSFER_SUCCESS`, `TRANSFER_FAILED`, `TRANSFER_REVERSED`, and `TRANSFER_REJECTED` below:

| Parameter | Description |
| :- | :- |
| `transfer_id` | The unique ID you created to identify the transfer request. |
| `cf_transfer_id` | The unique ID created by Cashfree for reference purposes. |
| `status` | The status of the transfer. |
| `status_code` | The specific status of the transfer. |
| `status_description` | The detailed explanation of the transfer status. |
| `beneficiary_details` | Information about the beneficiary. |
| `beneficiary_id` | The unique ID to identify the beneficiary. |
| `beneficiary_instrument_details` | The account information of the beneficiary. |
| `bank_account_number` | The bank account number of the beneficiary. |
| `bank_ifsc` | The IFSC information of the bank. |
| `transfer_amount` | The transfer amount. |
| `transfer_service_charge` | The service charge applied for the transfer amount. |
| `transfer_service_tax` | The taxable amount for the service charge. |
| `transfer_mode` | The transfer mode. |
| `transfer_utr` | The unique transaction reference number. |
| `fundsource_id` | The unique ID to identify the fund source. |
| `added_on` | The date and time of the addition. |
| `updated_on` | The date and time of the update. |
| `event_time` | The date and time of the webhook event initiation. |
| `type` | The event type. |

Find the parameters and their descriptions for the event `BULK_TRANSFER_REJECTED` below:

| Parameter | Description |
| :- | :- |
| `batch_transfer_id` | The unique ID you created to identify the batch transfer request. |
| `cf_batch_transfer_id` | The unique ID created by Cashfree for reference purposes. |
| `status` | The status of the batch transfer request. |
| `event_time` | The date and time of the webhook event initiation. |
| `type` | The event type. |

<Note>
  A transfer is considered successful only when both the status is `SUCCESS` and the status code is `COMPLETED`.
</Note>

### Webhook retries

Cashfree webhooks service does its best to deliver events to your webhook endpoint. It's best practice for your application to respond to the callback. Our webhook service may send many payloads to a single endpoint in quick succession. You will need to build an application and configure your server to receive the response we send when events get triggered during the payout process.

Your server should return a 200 HTTP status code to acknowledge that you received the webhook without any issues. Any other information you return in the request headers or request body is ignored. Any response code outside the 200 range, including 3xx codes, indicates that you didn't receive the webhook.

When Cashfree doesn't receive the acknowledgement for any reason, we retry to establish communication at regular intervals. If we don't receive the response after several attempts, we gradually decrease the rate of retries. Based on this count, the service is disabled if it fails more than five times.

If you don't receive notifications from Cashfree as expected, please fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1).

### IPs to whitelist

When you decide to consume the webhooks, first, you need to verify whether your systems need IP whitelisting to be done at your end or not. Accordingly, you can whitelist the below IPs of Cashfree:

| UAT |
| :- |
| 52.66.25.127 |
| 15.206.45.168 |

| Prod |
| :- |
| 52.66.101.190 |
| 3.109.102.144 |
| 18.60.134.245 |
| 18.60.183.142 |

| Port |
| :- |
| 443 (secured) |

## FAQs

<AccordionGroup>
  <Accordion title="Can I subscribe to webhooks V2 if I use Payouts APIs as V1 and V1.2?">
    Yes, you can subscribe to **Webhooks V2** even if you're currently using **Payout APIs v1 and v1.2**.
  </Accordion>

  <Accordion title="Can I utilise webhooks V1 whilst using Payouts APIs V2?">
    Yes, you can typically subscribe to **Webhooks V1** even if you're using **Payout APIs V2**.
  </Accordion>

  <Accordion title="How do I configure the webhook URL for Payouts in the sandbox environment?">
    To configure your Payouts webhook URL in the sandbox (UAT) environment:

    1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
    2. Click the 9-dot (Apps) icon and select **Payouts**.
    3. Click **Switch to Test** to move to the sandbox environment.
    4. Go to **Developers > Webhooks**.
    5. Add your webhook URL.
    6. Click **Test & Add Webhook** to verify the configuration and save your changes.

    After you configure the URL, retry the transfer to receive webhook events. See [Payouts webhooks](/docs/payouts/payouts/make-payouts/webhooks).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Who can configure webhooks in the Merchant Dashboard?">
    You need Admin access to add or configure webhooks. If you do not see the option to configure webhooks, log in with the email address associated with the Admin account, or ask your account Admin to complete the configuration.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="I received a LOW_BALANCE_ALERT webhook right after configuring my endpoint. Is this a real alert?">
    No.

    <Note>
      This is a validation event, not a real low-balance alert.
    </Note>

    When you configure a Payouts webhook endpoint and select **Test & Add Webhook**, Cashfree sends a test `LOW_BALANCE_ALERT` payload to confirm the endpoint is reachable and returns HTTP 200. Cashfree sends real `LOW_BALANCE_ALERT` events only when your wallet balance falls below the configured threshold. Ensure your endpoint returns HTTP 200 to all incoming payloads, including test ones. See [Payouts webhooks](/docs/payouts/payouts/make-payouts/webhooks) for the full explanation.
  </Accordion>
</AccordionGroup>


# Payouts Webhooks
Source: https://www.cashfree.com/docs/api-reference/payouts/webhooks-overview

Consolidated index for Payouts webhook documentation, including V2 JSON webhooks, legacy V1 webhooks, Cashgram, dashboard setup, and signature rules.

Payouts can emit webhooks for transfer lifecycle updates, batch outcomes, beneficiary incidents, and balance signals. **Payouts Webhooks V2** uses JSON bodies and **header-based** HMAC verification. **Cashgram** and some legacy flows use different payload and verification rules. For shared webhook behaviour (retries, IP allow lists), see the [Cashfree webhooks overview](/docs/api-reference/webhooks/overview).

## API reference

Use the following pages for payload shapes, headers, and event names.

<CardGroup>
  <Card title="Webhooks V2" icon="code" href="/docs/api-reference/payouts/v2/webhooks/webhooks-v2">
    Transfer status notifications with payloads, header signatures, retries, and IP addresses.
  </Card>

  <Card title="Webhooks V1 (V2 dashboard)" icon="clock-rotate-left" href="/docs/api-reference/payouts/v2/webhooks/webhooks-v1">
    Transfer status notifications and setup notes when using the V2 webhook configuration surface.
  </Card>

  <Card title="Cashgram webhooks" icon="file-lines" href="/docs/api-reference/payouts/v1/webhooks">
    Cashgram redemption, reversal, and expiry event reference.
  </Card>
</CardGroup>

## Product guides

The same webhook events, covered from a dashboard and operational perspective.

<CardGroup>
  <Card title="Payouts product webhooks" icon="chart-line" href="/docs/payouts/payouts/make-payouts/webhooks">
    Dashboard configuration steps and operational guidance for the Webhooks V1 (V2 dashboard) events above, described in product language.
  </Card>

  <Card title="Cashgram integration webhooks" icon="link" href="/docs/payouts/cashgram/integration/webhooks">
    Cashgram redemption, reversal, expiry events, and form-parameter signature verification.
  </Card>
</CardGroup>

For payout **status codes** returned in APIs and webhooks, see the [Payouts V2 response codes API](/docs/api-reference/payouts/v2/response-codes).


# Create Embeddable Onboarding Link (does not require login)
Source: https://www.cashfree.com/docs/api-reference/platforms/latest/merchant-onboarding/create-embeddable-onboarding-link-does-not-require-login

post /merchants/{merchant_id}/onboarding_link
Use this API to create a pre-built onboarding link for the sub-merchant account. Embed this link within your platform so that merchants can complete their KYC process. The link remains active for 1 hour only.



# Create Merchant
Source: https://www.cashfree.com/docs/api-reference/platforms/latest/merchant-onboarding/create-merchant

post /merchants
Use this API to create a sub-merchant account. You can provide basic merchant details during creation. KYC documents are required to activate the account.



# Create Standard Onboarding Link (with login required by merchant)
Source: https://www.cashfree.com/docs/api-reference/platforms/latest/merchant-onboarding/create-standard-onboarding-link-with-login-required-by-merchant

post /merchants/{merchant_id}/onboarding_link/standard
Use this API to create a pre-built onboarding link for the sub-merchant account. Share this link with the sub-merchant so they can complete their KYC process. The merchant needs to log in using their Cashfree password or OTP received on their registered email.



# Get Merchant Status
Source: https://www.cashfree.com/docs/api-reference/platforms/latest/merchant-onboarding/get-merchant-status

get /merchants/{merchant_id}
Use this API to get merchant onboarding details for the sub-merchant account.



# Getting Started
Source: https://www.cashfree.com/docs/api-reference/platforms/latest/merchant-onboarding/getting-started

Set up Cashfree Merchant Onboarding APIs for your platform with API keys, sandbox access, webhooks, and KYC document flows for sub-merchant lifecycles.

Embedded Payments by Cashfree is an end-to-end payment product for your platform to facilitate direct payments between your businesses and their customers. You can use Embedded Payments to provide your businesses a seamless onboarding experience and a fully compliant payments module within your platform.

Merchant Onboarding APIs is a feature of Embedded Payments through which you can onboard your merchants to your platform. Through the merchant onboarding APIs, you can perform various actions such as adding a merchant, updating the merchant's details, fetching the merchant's status, and creating onboarding links.

## View end points

| Environment | Base URL |
| :- | :- |
| Test | [https://api-sandbox.cashfree.com/partners](https://api-sandbox.cashfree.com/partners) |
| Production | [https://api.cashfree.com/partners](https://api.cashfree.com/partners) |
| Latest version | v3, 2023-01-01 |

The table below provides the list of Merchant Onboarding APIs along with their description.

**Merchant Onboarding APIs**

| API name | Description |
| :- | :- |
| [Create Merchant](/docs/api-reference/platforms/latest/merchant-onboarding/create-merchant) | Use this API to create a sub-merchant account. You can provide additional basic details. KYC documents are then required to activate the account. |
| [Update Merchant](/docs/api-reference/platforms/latest/merchant-onboarding/update-merchant) | Use this API to update a sub-merchant account. You can provide basic details only if the account is not yet active. |
| [Get Merchant Status](/docs/api-reference/platforms/latest/merchant-onboarding/get-merchant-status) | Use this API to get Merchant onboarding details for the sub-merchant account. |
| [Create Onboarding Link](/docs/api-reference/platforms/latest/merchant-onboarding/create-embeddable-onboarding-link-does-not-require-login) | Use this API to create a pre-built onboarding link for the sub-merchant account. Embed within your platform and Merchant can fill their KYC per compliance. |

**Get started in the test environment**

To get started with Merchant Onboarding API requests, you must follow the steps below:

1. Create an account on the Test Environment using this [signup link](https://test.cashfree.com/partner-ui/authentication/signup?product=embedded)
2. Once logged in, go to the **Developers** section and click **Generate API Key**.  Copy and download the API keys for future reference. You can also add a webhook endpoint to use the merchant activation status webhook.


# Update Merchant
Source: https://www.cashfree.com/docs/api-reference/platforms/latest/merchant-onboarding/update-merchant

patch /merchants/{merchant_id}
Use this API to update a sub-merchant account. You can modify basic details only if the account is not yet active.



# Upload Documents
Source: https://www.cashfree.com/docs/api-reference/platforms/latest/merchant-onboarding/upload-documents

post /merchants/{merchant_id}/documents
Use this API to upload KYC documents for merchants.

<Accordion title="Supported document types">
  The `document_type` parameter accepts the following values organised by document category:

  ### Business proof documents

  | Document type | Description |
  | - | - |
  | `businessproof_saecertificate` | Certificate or licence issued by the appropriate authorities under Shops and Establishment Act and any other Acts as applicable to the firm |
  | `businessproof_regproof` | Other government-issued registration proof |
  | `businessproof_municipal` | Municipal certificate |
  | `businessproof_udhyog` | Udyog Aadhaar |
  | `businessproof_taxreturn` | Sales tax and income tax return |
  | `businessproof_roc` | Registration certificate from ROC (Registrar of Company for a Jurisdiction) |
  | `businessproof_taxreturnfull` | Full tax return |
  | `businessproof_customeragreement` | Customer agreement |
  | `businessproof_platformconfirm` | Platform confirmation |
  | `businessproof_invoices` | Business invoices |

  ### Entity proof documents

  | Document type | Description |
  | - | - |
  | `entityproof_partnershipdeed` | Partnership deed |
  | `entityproof_trustdeed` | Trust deed |
  | `entityproof_societycertificate` | Society certificate |
  | `entityproof_hufdeed` | HUF deed |
  | `entityproof_llp` | LLPIN document |

  ### Line of business proof documents

  | Document type | Description |
  | - | - |
  | `lobproof_nonprofit` | Domestic: 80 G, 12 A or International: FCRA |
  | `lobproof_travel` | IATA certificate or IRCTC agency certificate |
  | `lobproof_pcidss` | AOC for PCI-DSS compliance |
  | `lobproof_gaming` | RNG certificate (if applicable), legal opinion |
  | `lobproof_food` | FSSAI |
  | `lobproof_bbps` | BBPS certificate |
  | `lobproof_jewellery` | BIS certificate, 916 Hallmark, 925 Hallmark, or GII certificate |
  | `lobproof_nbfc` | NBFCs or Service Level Agreements with RBI approved NBFCs |
  | `lobproof_papg` | PA-PG licence |
  | `lobproof_pharmacy` | Pharmacy licence, retail or wholesale drug licence, undertaking of authorised signatory under Drugs and Cosmetics Act 1940, declaration (Form 20, Form 21, Form 21B, Form 20B) |
  | `lobproof_ppi` | Bank PPI licence or Non Bank PPI licence |
  | `lobproof_mutualfunds` | AMFI certificate |
  | `lobproof_fema` | FEMA registration, FFMC certificate (FFMC state wise) |
  | `lobproof_ayush` | Ayush (manufacturing licence - Form 24D) |
  | `lobproof_sebi` | SEBI certificate |
  | `lobproof_insurance` | IRDA: Life insurance, general insurance, health insurance or SLA with the insurer if this is being issued by a different party |
  | `lobproof_education` | UGC certificate, ICSE, CBSE, or AICTE |

  ### Other documents

  | Document type | Description |
  | - | - |
  | `bank_statement` | Bank statement |
  | `certificate_of_incorporation` | Certificate of incorporation |
  | `board_resolution` | Board resolution |
  | `gst_certificate` | GST certificate |
  | `localtax_identifier` | Local tax identifier |
  | `bene_owner_id_proof_1` to `bene_owner_id_proof_6` | Beneficial owner ID proofs |
</Accordion>


# Webhooks
Source: https://www.cashfree.com/docs/api-reference/platforms/latest/merchant-onboarding/webhooks

This is list of webhooks triggered from the Cashfree system. These webhooks allow partners to remain alert to state changes for their merchants.

## Configure webhook

To configure the webhook, go to [**Partner Dashboard**](https://partner.cashfree.com/auth/login) > **Developers** > **Webhooks**. Add your webhook endpoint where you want to receive alerts. Ensure you do not process duplicate events.

Webhook will be sent to your configured endpoint as a POST request with the body containing the various parameters specifying the details of each event. Each request contains an event parameter that identifies its type.

We support webhooks in both encoded and JSON formats.

The following are the webhook header parameters and their corresponding descriptions:

| Parameter | Description |
| - | - |
| x-cashfree-timestamp | Timestamp in ISO format. Time at which the webhook is triggered. |
| x-cashfree-signature | String. It is a base64 encoded entity of the hash (SHA256) of the raw payload sorted by alphabetical order of keys and the latest partner API key. This signature should be used to verify authenticity of the webhook. |

## Webhook event

The following is the webhook event type and its corresponding description:

| Event type | Description |
| :- | :- |
| `MERCHANT_ONBOARDING_STATUS` | Triggered when the merchant's onboarding status changes (e.g., email verified, KYC approved, account activated). |

### Sample webhook events

The following is an example of a webhook event that you may receive:

<CodeGroup>
  ```Text MERCHANT_ONBOARDING_STATUS theme={"dark"} theme={"dark"}
  {
     "type":"MERCHANT_ONBOARDING_STATUS",
     "event_time":"2006-01-02T15:04:05Z",
     "data":{
          "merchant_id": "CF89797",
          "merchant_name": "Business A",
          "created_at": "2021-06-23T23:15:20+05:30",
          "onboarding_status": "ACTIVE"
      }
  }
  ```
</CodeGroup>

## Webhook payload fields

The following are the webhook payload fields and their corresponding descriptions:

| Field | Type | Description |
| - | - | - |
| `type` | `string` | Indicates the type of event that triggered the webhook. |
| `event_time` | `string` | The UTC timestamp of when the event occurred, formatted in ISO 8601 (`YYYY-MM-DDTHH:MM:SSZ`). |
| `data` | `object` | Contains event-specific details related to merchant onboarding. |

The following are the webhook parameters and their corresponding descriptions:

| Parameter | Description |
| :- | :- |
| data.merchant\_id | Unique merchant ID provided by the partner at the time of merchant creation. |
| data.merchant\_name | Name of the merchant. |
| data.created\_at | Timestamp in ISO format for when the merchant was created in CF system. |
| data.onboarding\_status | Onboarding status for the merchant. |
| event\_time | Timestamp in ISO format. Time when event was created. |
| type | Type of webhook. Value is "MERCHANT\_ONBOARDING\_STATUS". |
| version | Version of webhook. Default is 1. |

## Webhook signature

The following is a sample header from a webhook request containing the signature:

<Tabs>
  <Tab title="Version (2025-01-01)">
    | Header name | Header value |
    | - | :-: |
    | content-length | 1099 |
    | x-webhook-attempt | 1 |
    | content-type | application/json |
    | x-webhook-signature | 07r5C3VMwsGYeldGOCYxe5zoHhIN1zLfa8O0U/yngHI= |
    | x-webhook-timestamp | 1746427759733 |
    | x-webhook-version | 2025-01-01 |
  </Tab>

  <Tab title="Version (Legacy)">
    | Header name | Header value |
    | - | :-: |
    | x-cashfree-timestamp | 2021-04-16T14:10:36+05:30 |
    | x-cashfree-signature | 07r5C3VMwsGYeldGOCYxe5zoHhIN1zLfa8O0U/yngHI= |
  </Tab>
</Tabs>

<Tip> Always capture the webhook payload in its raw text format before parsing into JSON. Parsing and re-serialising the payload can change the structure (for example, array ordering, spacing, or `null` handling) and cause a signature mismatch during verification. Use the exact raw body string from the request when computing the signature.</Tip>

## Verify signature

Use the signature received in webhooks to verify if the request has not been tampered. This is generally a good security practice to avoid abuse via a fraudulent party.

To verify the signature at your end, you need your Cashfree Partner API Key along with the webhook object.

* The timestamp is present in the webhook object header `x-webhook-timestamp`.
* The actual signature generated by Cashfree is present in the webhook object header `x-webhook-signature`.

The signature creation logic is as below:

```php Signature theme={"dark"}
timestamp := 1617695238078; 
signedPayload := $timestamp.$payload;
expectedSignature := Base64Encode(HMACSHA256($signedPayload, $partnerApiKey));
```

***

## Activation lifecycle

The following are the status stages included in the merchant onboarding process:

1. **Pending Email verification**: The merchant must first verify their registered Email address. An Email is sent automatically from Cashfree to the merchant Email ID you specified when you added the merchant details. If the merchant has not received the Email in their primary inbox, please ask them to check the spam folder. If the merchant still has not received the Email, you can use the resend Email option or contact the [support form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) for further assistance.
2. **Email verified**: This means that the merchant has verified their Email address and can now start their KYC verification process.

## KYC status

The following are the status stages involved in the merchant KYC process:

1. **Min KYC Pending**: Merchant must submit the required KYC details and documents.
2. **Min KYC Submitted**: Merchant has submitted their KYC details and documents and the documents are being reviewed by Cashfree.
3. **Min KYC Rejected**: Merchant KYC has discrepancies and corresponding KYC details and documents need to be provided.
4. **Min KYC Approved**: Merchant KYC has been approved and **Payment Gateway** product is activated.

<Note>
  If the merchants have verified their email you can fill out the KYC on behalf of the merchant and activate the account for your merchants.
</Note>


# Partner Platform Webhooks
Source: https://www.cashfree.com/docs/api-reference/platforms/latest/webhooks-overview

Consolidated index for partner and platform APIs, including merchant onboarding webhooks and where to configure them in the Partner or platform flow.

Platform and partner integrations use webhooks to notify your systems about merchant onboarding and related asynchronous state changes. Payload and header conventions follow the specific API group you integrate with. For generic webhook operations (HTTPS, `200` acknowledgement, idempotency), see the [Cashfree webhooks overview](/docs/api-reference/webhooks/overview).

## References

Onboarding lifecycle events, sample payloads, and configuration notes for embedded and standard onboarding links are documented on the [merchant onboarding webhooks](/docs/api-reference/platforms/latest/merchant-onboarding/webhooks) page.

For product context outside the API reference, see [Add merchants](/docs/partners/embedded/add-merchants).


# Overview
Source: https://www.cashfree.com/docs/api-reference/platforms/overview

Use Cashfree Platform APIs to onboard merchants, manage their lifecycle, and process payments inside your marketplace or SaaS application end to end.

Cashfree’s Platform APIs enable platforms to integrate payment solutions seamlessly within their applications or marketplaces. These APIs allow you to onboard merchants, manage their lifecycle, and process payments efficiently, following standard web conventions.

You can use these APIs to integrate a seamless payment experience into your platform, manage merchant details, and ensure compliance throughout the process.

<div>
  <div>
    <div>
      <h4>Merchant onboarding and management</h4>

      <div>
        <div>
          <a href="/docs/api-reference/platforms/latest/merchant-onboarding/create-merchant">Create Merchant</a>

          <p>
            Use this API to create and onboard a new sub-merchant account to your platform with their business details and configuration.
          </p>
        </div>
      </div>

      ***

      <div>
        <div>
          <a href="/docs/api-reference/platforms/latest/merchant-onboarding/get-merchant-status">Get Merchant Status</a>

          <p>
            Use this API to retrieve the current onboarding status and details of an existing sub-merchant account.
          </p>
        </div>
      </div>

      ***

      <div>
        <div>
          <a href="/docs/api-reference/platforms/latest/merchant-onboarding/update-merchant">Update Merchant</a>

          <p>
            Use this API to update sub-merchant account details and configuration after initial onboarding.
          </p>
        </div>
      </div>
    </div>
  </div>

  <div>
    <div>
      <h4> </h4>

      <div>
        <div>
          <a href="/docs/api-reference/platforms/latest/merchant-onboarding/upload-documents">Upload Documents</a>

          <p>
            Use this API to upload required KYC and business documents for merchant verification and compliance.
          </p>
        </div>
      </div>

      ***

      <div>
        <div>
          <a href="/docs/api-reference/platforms/latest/merchant-onboarding/create-embeddable-onboarding-link-does-not-require-login">Create Embeddable Onboarding Link</a>

          <p>
            Use this API to create a pre-built onboarding link for the sub-merchant account. Embed within your platform for KYC compliance.
          </p>
        </div>
      </div>

      ***

      <div>
        <div>
          <a href="/docs/api-reference/platforms/latest/merchant-onboarding/create-standard-onboarding-link-with-login-required-by-merchant">Create Standard Onboarding Link</a>

          <p>
            Use this API to create a pre-built onboarding link for the sub-merchant account. Requires merchant login via password or OTP for secure access.
          </p>
        </div>
      </div>
    </div>
  </div>
</div>

## Getting started

Use the following resources to begin implementing Platform APIs:

<CardGroup>
  <Card title="Product documentation" href="/docs/partners/introduction" icon="book-open">
    Introduction to Partners and Platforms, partnership models, and key benefits
  </Card>

  <Card title="API setup" href="/docs/api-reference/platforms/latest/merchant-onboarding/getting-started" icon="rocket">
    Base URLs, API keys, and steps to run your first Merchant Onboarding API request in test
  </Card>
</CardGroup>


# Postman Collections
Source: https://www.cashfree.com/docs/api-reference/postman-collections

Download Cashfree Postman collections for payments, payouts, and verification APIs to test endpoints with preconfigured requests and sample data.

Cashfree provides comprehensive Postman collections for all API products, making it easy to test and integrate APIs. Each collection includes pre-configured requests, sample data, and environment variables to get you started.

## Available collections

<CardGroup>
  <Card title="Payment Gateway APIs" icon="credit-card" href="https://www.postman.com/cashfreedevelopers/cashfree-apis-v2025-01-01/overview">
    Complete collection for payment processing, orders, refunds, settlement, and subscription APIs.
  </Card>

  <Card title="Payouts APIs" icon="building-columns" href="https://gocashassets.s3.ap-south-1.amazonaws.com/repostmancollection/Cashfree_Payouts_Collection.json.zip">
    Transfer funds and manage company finances through payout APIs.
  </Card>

  <Card title="Secure ID APIs" icon="shield-check" href="https://www.postman.com/cashfreedevelopers/cashfree-secure-id/collection/40140981-e0241e2f-d2f4-4800-b3ae-558275ae7254">
    Identity verification APIs for PAN, Aadhaar, and other document verification services.
  </Card>
</CardGroup>

<Frame>
  <iframe title="Testing in Postman" />
</Frame>

<p>
  Testing APIs in Postman
</p>

## Getting started

To import a Postman collection, choose your preferred method:

<Tabs>
  <Tab title="Fork Collection (Recommended)">
    1. Click on any collection link above.
    2. Click the **Fork** button in Postman.
    3. Choose your workspace.
    4. The collection will be available in your workspace with automatic updates.
  </Tab>

  <Tab title="Download and Import">
    1. Download the collection JSON file from the workspace.
    2. Open Postman.
    3. Click **Import** → **Upload Files**.
    4. Select the downloaded JSON file.
  </Tab>
</Tabs>

To configure your environment variables:

1. Create a new environment in Postman.
2. Add the following variables:
   * `base_url`: Set to `https://sandbox.cashfree.com` (sandbox) or `https://api.cashfree.com` (production)
   * `client_id`: Your Cashfree Client ID
   * `client_secret`: Your Cashfree Client Secret
   * `x-api-version`: API version (for example, `2025-01-01`)

<Warning>
  Never share your production credentials. Use sandbox credentials for testing and development.
</Warning>

The following examples show the environment variable configuration for both environments:

Sandbox:

```json theme={"dark"}
{
  "base_url": "https://sandbox.cashfree.com",
  "client_id": "your_sandbox_client_id",
  "client_secret": "your_sandbox_client_secret",
  "x-api-version": "2025-01-01"
}
```

Production:

```json theme={"dark"}
{
  "base_url": "https://api.cashfree.com",
  "client_id": "your_production_client_id",
  "client_secret": "your_production_client_secret",
  "x-api-version": "2025-01-01"
}
```

To test your first request:

1. Select your environment from the dropdown in the top-right corner.
2. Choose a simple request like "Get Order" or "Create Order."
3. Review the request parameters and body.
4. Click **Send** to execute the request.

## Features and best practices

Each Postman collection includes the following features:

* Pre-configured requests with correct HTTP methods and headers.
* Sample request bodies with placeholder data.
* Environment variables for dynamic URLs and authentication.
* Example data including test card numbers and mock account details.
* Test scripts for automatic response validation.

Collections automatically handle authentication using your credentials. Tokens are generated and refreshed as needed, so you don't need to manually manage authorisation headers.

Use environment variables for dynamic data, update placeholder values with real test data, and keep sensitive information in environment variables rather than in requests.

Review response status codes and error messages, check the **Tests** tab for automated validations, and use the **Console** view to debug request/response details.

## Troubleshooting common issues

The following are common Postman collection errors and solutions:

<Accordion title="Authentication Failed (401)">
  * Verify your `client_id` and `client_secret` are correct.
  * Ensure you're using the right environment (sandbox vs production).
  * Check that your credentials are active and not expired.
</Accordion>

<Accordion title="Invalid API Version (400)">
  * Confirm the `x-api-version` header is set correctly.
  * Use `2026-01-01` for the latest API version.
  * Check the API documentation for supported versions.
</Accordion>

<Accordion title="Environment Variables Not Working">
  * Ensure you've selected the correct environment.
  * Verify all required variables are defined.
  * Check for typos in variable names (case-sensitive).
</Accordion>

<Accordion title="Request Validation Errors">
  * Review the API documentation for required fields.
  * Check data types and formats in request body.
  * Ensure all mandatory parameters are included.
</Accordion>

## Support

If you need help with Postman collections or API integration, you can use the following resources:

* Documentation: Review the detailed [API documentation](/docs/api-reference/overview).
* Support form: Submit a ticket through the [support form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) for technical assistance.
* Support: Contact the [developer support team](mailto:developers@cashfree.com).
* Community: Join the [developer community](https://discord.gg/ed9VWDnrh7).

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/authentication">Authentication Overview</a></li>
    <li><a href="/docs/api-reference/rate-limits">Rate Limits</a></li>
    <li><a href="/docs/api-reference/integration-troubleshooting/overview-ts">Integration Troubleshooting</a></li>
  </ul>
</div>


# Getting Started
Source: https://www.cashfree.com/docs/api-reference/prepaid-payment-instruments/getting-started

Get started with the Cashfree PPI APIs by reviewing endpoints, generating API keys, configuring webhooks, and contacting Cashfree for production access.

Follow these setup steps to get started with the PPI APIs:

* [View end points](/docs/api-reference/prepaid-payment-instruments/getting-started#view-end-points)
* [Generate API keys](/docs/api-reference/prepaid-payment-instruments/getting-started#generate-api-keys)
* [Contact us](/docs/api-reference/prepaid-payment-instruments/getting-started#contact-us)

## View end points

Cashfree uses API keys to authenticate and authorise access to the API. You must include your API keys in all API requests to the server.

| Environment | URL |
| :- | :- |
| Production | [https://api.cashfree.com/ppi](https://api.cashfree.com/ppi) |
| Test | [https://sandbox.cashfree.com/ppi](https://sandbox.cashfree.com/ppi) |

## Generate API keys

During onboarding, Cashfree provides merchants with the required API keys **Client ID** and **Client Secret** directly, typically via email. These credentials can be used immediately to authenticate and access the PPI API.

<Warning>
  Do not share your API keys with anyone, as they are confidential.
</Warning>

## Contact us

Submit a request through the [raise an issue support form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1), completing the fields as specified below:

* **Subject**: Provide a clear one-line summary of the issue.
* **Product**: Select the relevant product under which the issue was raised or specify it as Other queries.
* **Description**: Provide a detailed description of the issue specifying the endpoint URL, HTTP method, and relevant request or response details.
* **Notify People**: You may add your account manager to be notified.
* **Attachment**: Upload any file for context to highlight the specific issue.

<Note>
  For dashboard issues, attach a screenshot and the HAR file.
</Note>


# Get Video KYC Details
Source: https://www.cashfree.com/docs/api-reference/prepaid-payment-instruments/kyc-verification/get-video-kyc-status

openapi/ppi/ppi.yaml post /ppi/kyc/vkyc/details
Retrieves the current status and other details of a Video KYC verification request, using the `user_id` and `verification_id` you supplied while initiating the request.


Refer to the [Status and Status Code reference](/docs/api-reference/prepaid-payment-instruments/kyc-verification/vkyc-status-descriptions#status-statuscode-mapping) page for a comprehensive list of status and status\_code combinations.


# Min KYC Verification
Source: https://www.cashfree.com/docs/api-reference/prepaid-payment-instruments/kyc-verification/min-kyc-verification

openapi/ppi/ppi.yaml post /ppi/kyc/min
Completes the minimum KYC verification process by validating user documents and OTP verification.
This endpoint processes document information (PAN card details) along with the OTP verification ID
to complete the minimum KYC requirements for the user.




# Generate OTP
Source: https://www.cashfree.com/docs/api-reference/prepaid-payment-instruments/kyc-verification/send-otp

openapi/ppi/ppi.yaml post /ppi/otp/generate
Sends an OTP (One-Time Password) to the user via the specified notification modes.
Supports multiple delivery channels including SMS and WhatsApp for secure user verification.




# Submit OTP
Source: https://www.cashfree.com/docs/api-reference/prepaid-payment-instruments/kyc-verification/verify-otp

openapi/ppi/ppi.yaml post /ppi/otp/submit
Verifies the OTP (One-Time Password) sent to the user for verification. 
This endpoint validates the OTP provided by the user against the OTP verification ID.




# Initiate Video KYC
Source: https://www.cashfree.com/docs/api-reference/prepaid-payment-instruments/kyc-verification/video-kyc-verification

openapi/ppi/ppi.yaml post /ppi/kyc/vkyc
Initiates Video KYC for a user and generates a VKYC link.
This endpoint creates a VKYC verification request and sends the notification across
the requested channels.


Refer to the [Status and Status Code reference](/docs/api-reference/prepaid-payment-instruments/kyc-verification/vkyc-status-descriptions#status-statuscode-mapping) page for a comprehensive list of status and status\_code combinations.


# VKYC Status and Status-Code Mapping
Source: https://www.cashfree.com/docs/api-reference/prepaid-payment-instruments/kyc-verification/vkyc-status-descriptions

Reference for PPI Video KYC status and status-code combinations returned by VKYC APIs and webhooks, with recommended actions for each scenario.

This reference guide explains the status and status-code values returned by PPI Video KYC APIs and webhooks. Use this information to interpret responses and configure your verification flow.

<span />

## Status and status-code reference

The following table describes all possible status and status-code combinations returned by the VKYC API, along with recommended actions for each scenario.

### Verification phase statuses

Statuses are organised by verification phase. Each phase contains specific status codes that indicate the current state and required actions.

<Accordion title="`RECEIVED` – Request accepted">
  | Status code | Description | Recommended action |
  | - | - | - |
  | `LINK_GENERATED` | Cashfree generated the Video KYC link successfully. | Share the link with the user through your preferred channel |
</Accordion>

<Accordion title="`EXPIRED` – Link expired">
  | Status code | Description | Recommended action |
  | - | - | - |
  | `VKYC_EXPIRED` | The Video KYC link has expired. | Initiate a new Video KYC request for the user |
</Accordion>

<Accordion title="`PRE_VIDEO_CALL` – Pre-verification checks">
  | Status code | Description | Recommended action |
  | - | - | - |
  | `AADHAAR_VERIFICATION_SUCCESS` | Aadhaar verification succeeded. | Proceed to the next verification step |
  | `AADHAAR_VERIFICATION_FAILED` | Aadhaar verification failed. | Ask the user to retry with correct Aadhaar information |
  | `AADHAAR_VERIFICATION_EXPIRED` | The Aadhaar verification session expired. | Restart the Aadhaar verification process |
  | `USER_IP_VERIFICATION_SUCCESSFUL` | IP address verification succeeded. | Continue with the verification flow |
  | `USER_PROXY_DETECTED` | Cashfree detected a proxy or VPN. | Ask the user to disable the proxy or VPN and retry |
  | `TECHNICAL_FAILURE` | A technical issue occurred during verification. | Retry after some time or contact Cashfree support |
  | `USER_LOCATION_VERIFICATION_SUCCESS` | Location verification succeeded. | Proceed to device checks |
  | `USER_LOCATION_OUTSIDE_INDIA` | The user is outside India. | Reject the request or ask the user to retry from India |
  | `USER_AUDIO_CHECK_FAILED` | Microphone access is not enabled. | Ask the user to enable microphone access |
  | `USER_VIDEO_CHECK_FAILED` | Camera access is not enabled. | Ask the user to enable camera access |
  | `USER_LOCATION_PERMISSION_DISABLED` | The user did not grant location access. | Ask the user to allow location permissions |
  | `USER_DEVICE_CHECK_SUCCESS` | The device passed all checks. | Proceed to agent assignment |
  | `USER_QUEUED` | The user is waiting for an available agent. | Display the queue position and estimated wait time |
  | `SCHEDULED_USER_QUEUED` | The user is queued for a scheduled appointment. | Notify the user of the scheduled time |
  | `NO_AGENT_FOUND` | No agent is available at this time. | Retry after some time or offer scheduling |
  | `AGENT_ASSIGNED_TO_USER` | Cashfree assigned an agent to the user. | Notify the user that verification will begin |
  | `USER_MEETING_SCHEDULED` | Cashfree scheduled the user meeting successfully. | Send the meeting details to the user |
  | `USER_MEETING_CANCELLED` | The user meeting was cancelled. | Offer rescheduling options |
</Accordion>

<Accordion title="`VIDEO_CALL` – During video verification">
  | Status code | Description | Recommended action |
  | - | - | - |
  | `USER_ACCEPTED_MEETING` | The user accepted the meeting invitation. | Start the VKYC verification process |
  | `USER_REJECTED_MEETING` | The user rejected the meeting invitation. | Reschedule or mark verification as failed |
  | `USER_MISSED_MEETING` | The user missed the scheduled meeting. | Offer rescheduling options |
  | `USER_DROPPED_OFF` | The user disconnected during verification. | Log the issue and offer reconnection |
  | `AGENT_DROPPED_OFF` | The agent disconnected during verification. | Retry with another agent |
  | `USER_ENDED_CALL` | The user ended the call. | Review session completeness |
  | `AGENT_ENDED_CALL` | The agent ended the call. | Review the agent remarks and next steps |
</Accordion>

<Accordion title="`FAILED` – Verification failed">
  | Status code | Description | Recommended action |
  | - | - | - |
  | `TECHNICAL_ERROR` | A technical error occurred during verification. | Retry the verification or escalate to Cashfree support |
</Accordion>

<Accordion title="`AGENT_REVIEWED` – Agent review complete">
  | Status code | Description | Recommended action |
  | - | - | - |
  | `AGENT_APPROVED` | The agent approved the KYC verification. | Proceed to the auditor review stage |
  | `AGENT_REJECTED` | The agent rejected the KYC verification. | Notify the user with the rejection reason |
  | `AGENT_UNABLE_TO_VALIDATE` | The agent could not complete validation. | Retry with another agent or initiate a new session |
</Accordion>

<Accordion title="`AUDITOR_REVIEWED` – Final review complete">
  | Status code | Description | Recommended action |
  | - | - | - |
  | `AUDITOR_APPROVED` | The auditor approved the KYC verification. | Mark verification as complete |
  | `AUDITOR_REJECTED` | The auditor rejected the KYC verification. | Mark verification as failed |
</Accordion>


# Video KYC Webhooks
Source: https://www.cashfree.com/docs/api-reference/prepaid-payment-instruments/kyc-verification/webhook-vkyc

Configure Video KYC webhooks to receive real-time notifications when VKYC verification status changes in your PPI integration.

Cashfree sends event-based notifications when specific Video KYC events occur. Use these notifications to track the status and progress of VKYC in real time.

<Warning>
  Network retries, read timeouts, processing delays, or delivery failures can cause the same webhook to be delivered more than once for the same event. To prevent unintended side effects, implement idempotency in your webhook handler to handle duplicate deliveries.
</Warning>

## Webhook signature

You receive the webhook signature in the webhook header. The following table shows a sample header from a webhook request.

| Header name | Header value |
| - | :-: |
| content-length | 1099 |
| x-webhook-attempt | 1 |
| content-type | application/json |
| x-webhook-signature | 07r5C3VMwsGYeldGOCYxe5zoHhIN1zLfa8O0U/yngHI= |
| x-webhook-timestamp | 1746427759733 |
| x-webhook-version | 2025-01-01 |

<Tip>Always capture the webhook payload in its raw text format before parsing into JSON. Parsing and reserialising the payload can change the structure — for example, array ordering, spacing, or `null` handling — and cause a signature mismatch during verification. Use the exact raw body string from the request when computing the signature.</Tip>

## VKYC webhook events

The following events are triggered at different stages of the Video KYC process.

| Event | Description |
| :- | :- |
| `VKYC_USER_LINK_GENERATED` | Cashfree generated the VKYC link for the user. |
| `VKYC_USER_LINK_EXPIRED` | The VKYC link expired. |
| `VKYC_USER_AADHAAR_VERIFIED` | Cashfree verified the Aadhaar details. |
| `VKYC_USER_CALL_SCHEDULED` | Cashfree scheduled the VKYC call for the user. |
| `VKYC_USER_PRECHECK_FAILED` | Pre-verification checks failed. |
| `VKYC_USER_CALL_QUEUED` | The user joined and is waiting in the queue for an agent. |
| `VKYC_USER_CALL_STARTED` | The VKYC call started with an agent. |
| `VKYC_USER_DROPOFF_FROM_CALL` | The user dropped off from the VKYC call. |
| `VKYC_USER_CALL_COMPLETED` | The VKYC call completed successfully. |
| `VKYC_AUDITOR_REVIEW_COMPLETED` | The auditor approved or rejected the VKYC packet. |

<AccordionGroup>
  <Accordion title="VKYC_USER_LINK_GENERATED">
    ```json theme={"dark"}
    {
      "event_type": "VKYC_USER_LINK_GENERATED",
      "event_time": "2025-05-22T03:51:14Z",
      "data": {
        "verification_id": "TestVkycVerification",
        "cf_verification_id": "8901234567890123458",
        "user_id": "USER827364",
        "status": "RECEIVED", 
        "status_code": "LINK_GENERATED",
        "link": "https://vkyc.cashfree.com/session/abc123",
        "link_expiry": "2026-06-27", 
        "meeting_schedule": null, 
        "auditor_remarks": null,
        "agent_remarks": null
      }
    }
    ```
  </Accordion>

  <Accordion title="VKYC_USER_LINK_EXPIRED">
    ```json theme={"dark"}
    {
      "event_type": "VKYC_USER_LINK_EXPIRED",
      "event_time": "2025-05-22T03:51:14Z",
      "data": {
        "verification_id": "TestVkycVerification",
        "cf_verification_id": "8901234567890123458",
        "user_id": "USER827364",
        "status": "EXPIRED",
        "status_code": "VKYC_EXPIRED",
        "link": "https://vkyc.cashfree.com/session/abc123",
        "link_expiry": "2025-05-22", 
        "meeting_schedule": null,
        "auditor_remarks": null,
        "agent_remarks": null
      }
    }
    ```
  </Accordion>

  <Accordion title="VKYC_USER_AADHAAR_VERIFIED">
    ```json theme={"dark"}
    {
      "event_type": "VKYC_USER_AADHAAR_VERIFIED",
      "event_time": "2025-05-22T03:51:14Z",
      "data": {
        "verification_id": "TestVkycVerification",
        "cf_verification_id": "8901234567890123458",
        "user_id": "USER827364",
        "status": "PRE_VIDEO_CALL",
        "status_code": "AADHAAR_VERIFICATION_SUCCESS",
        "link": "https://vkyc.cashfree.com/session/abc123",
        "link_expiry": "2026-06-27", 
        "meeting_schedule": null,
        "auditor_remarks": null,
        "agent_remarks": null
      }
    }
    ```
  </Accordion>

  <Accordion title="VKYC_USER_CALL_SCHEDULED">
    ```json theme={"dark"}
    {
      "event_type": "VKYC_USER_CALL_SCHEDULED",
      "event_time": "2025-05-22T03:51:14Z",
      "data": {
        "verification_id": "TestVkycVerification",
        "cf_verification_id": "8901234567890123458",
        "user_id": "USER827364",
        "status": "PRE_VIDEO_CALL",
        "status_code": "USER_MEETING_SCHEDULED",
        "link": "https://vkyc.cashfree.com/session/abc123",
        "link_expiry": "2026-06-27", 
        "meeting_schedule": "2025-05-23T14:30:00Z",
        "auditor_remarks": null,
        "agent_remarks": null
      }
    }
    ```
  </Accordion>

  <Accordion title="VKYC_USER_PRECHECK_FAILED">
    ```json theme={"dark"}
    {
      "event_type": "VKYC_USER_PRECHECK_FAILED",
      "event_time": "2025-05-22T03:51:14Z",
      "data": {
        "verification_id": "TestVkycVerification",
        "cf_verification_id": "8901234567890123458",
        "user_id": "USER827364",
        "status": "PRE_VIDEO_CALL",
        "status_code": "USER_VIDEO_CHECK_FAILED",
        "link": "https://vkyc.cashfree.com/session/abc123",
        "link_expiry": "2026-06-27", 
        "meeting_schedule": null,
        "auditor_remarks": null,
        "agent_remarks": null
      }
    }
    ```
  </Accordion>

  <Accordion title="VKYC_USER_CALL_QUEUED">
    ```json theme={"dark"}
    {
      "event_type": "VKYC_USER_CALL_QUEUED",
      "event_time": "2025-05-22T03:51:14Z",
      "data": {
        "verification_id": "TestVkycVerification",
        "cf_verification_id": "8901234567890123458",
        "user_id": "USER827364",
        "status": "PRE_VIDEO_CALL",
        "status_code": "USER_QUEUED",
        "link": "https://vkyc.cashfree.com/session/abc123",
        "link_expiry": "2026-06-27",
        "meeting_schedule": null,
        "auditor_remarks": null,
        "agent_remarks": null
      }
    }
    ```
  </Accordion>

  <Accordion title="VKYC_USER_CALL_STARTED">
    ```json theme={"dark"}
    {
      "event_type": "VKYC_USER_CALL_STARTED",
      "event_time": "2025-05-22T03:51:14Z",
      "data": {
        "verification_id": "TestVkycVerification",
        "cf_verification_id": "8901234567890123458",
        "user_id": "USER827364",
        "status": "VIDEO_CALL",
        "status_code": "USER_ACCEPTED_MEETING",
        "link": "https://vkyc.cashfree.com/session/abc123",
        "link_expiry": "2026-06-27",
        "meeting_schedule": null,
        "auditor_remarks": null,
        "agent_remarks": null
      }
    }
    ```
  </Accordion>

  <Accordion title="VKYC_USER_DROPOFF_FROM_CALL">
    ```json theme={"dark"}
    {
      "event_type": "VKYC_USER_DROPOFF_FROM_CALL",
      "event_time": "2025-05-22T03:51:14Z",
      "data": {
        "verification_id": "TestVkycVerification",
        "cf_verification_id": "8901234567890123458",
        "user_id": "USER827364",
        "status": "VIDEO_CALL",
        "status_code": "USER_DROPPED_OFF",
        "link": "https://vkyc.cashfree.com/session/abc123",
        "link_expiry": "2026-06-27",
        "meeting_schedule": null,
        "auditor_remarks": null,
        "agent_remarks": null
      }
    }
    ```
  </Accordion>

  <Accordion title="VKYC_USER_CALL_COMPLETED">
    ```json theme={"dark"}
    {
      "event_type": "VKYC_USER_CALL_COMPLETED",
      "event_time": "2025-05-22T03:51:14Z",
      "data": {
        "verification_id": "TestVkycVerification",
        "cf_verification_id": "8901234567890123458",
        "user_id": "USER827364",
        "status": "POST_VIDEO_CALL",
        "status_code": "AGENT_APPROVED",
        "link": "https://vkyc.cashfree.com/session/abc123",
        "link_expiry": "2026-06-27",
        "meeting_schedule": null,
        "auditor_remarks": null,
        "agent_remarks": "Good to go"
      }
    }
    ```
  </Accordion>

  <Accordion title="VKYC_AUDITOR_REVIEW_COMPLETED">
    ```json theme={"dark"}
    {
      "event_type": "VKYC_AUDITOR_REVIEW_COMPLETED",
      "event_time": "2025-05-22T03:51:14Z",
      "data": {
        "verification_id": "TestVkycVerification",
        "cf_verification_id": "8901234567890123458",
        "user_id": "USER827364",
        "status": "AUDITOR_REVIEWED",
        "status_code": "AUDITOR_APPROVED",
        "link": "https://vkyc.cashfree.com/session/abc123",
        "link_expiry": "2026-06-27",
        "meeting_schedule": null,
        "auditor_remarks": "Looks Good",
        "agent_remarks": "Good to go"
      }
    }
    ```
  </Accordion>
</AccordionGroup>

## Webhook payload fields

The webhook payload contains important metadata in its top-level fields.

| Field | Type | Description |
| - | - | - |
| `event_type` | `string` | Indicates the type of event that triggered the webhook. |
| `event_time` | `string` | The UTC timestamp of when the event occurred, formatted in ISO 8601 (`YYYY-MM-DDTHH:MM:SSZ`). |
| `data` | `object` | Contains event-specific details related to this feature. |

### Data object fields

The following table describes the fields returned inside the `data` object.

| Field | Type | Description |
| - | - | - |
| `verification_id` | `string` | The unique ID for the VKYC verification request, as provided by you during initiation. |
| `cf_verification_id` | `string` | The unique ID for the VKYC verification request, generated by Cashfree. |
| `user_id` | `string` | The user ID provided when initiating Video KYC. |
| `status` | `string` | The current status of the VKYC request. |
| `status_code` | `string` | The sub-status providing additional detail about the current state. |
| `link` | `string` | The URL shared with the user to complete the VKYC process. |
| `link_expiry` | `string` | The date on which the VKYC link expires. |
| `meeting_schedule` | `string` or `null` | The scheduled UTC timestamp for the VKYC meeting. Returns `null` if no meeting is scheduled. |
| `auditor_remarks` | `string` or `null` | Remarks provided by the auditor after reviewing the VKYC session. Returns `null` if not yet reviewed. |
| `agent_remarks` | `string` or `null` | Remarks provided by the agent at the end of the VKYC call. Returns `null` if the call is not completed. |

## Important status information

For certain webhook events, specifically `VKYC_USER_PRECHECK_FAILED` and `VKYC_USER_CALL_SCHEDULED`, you may encounter more than one `status_code` value.

See the [Status and status-code reference](/docs/api-reference/prepaid-payment-instruments/kyc-verification/vkyc-status-descriptions#status-and-status-code-reference) page for a comprehensive list of status and status\_code combinations.

<Note>
  Verifying the signature is mandatory before processing any response. For more information, see [Signature verification](/docs/api-reference/prepaid-payment-instruments/webhook-signature-verification).
</Note>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/prepaid-payment-instruments/kyc-verification/video-kyc-verification">Initiate Video KYC API</a></li>
    <li><a href="/docs/api-reference/prepaid-payment-instruments/kyc-verification/get-video-kyc-status">Get Video KYC Status API</a></li>
    <li><a href="/docs/api-reference/prepaid-payment-instruments/kyc-verification/vkyc-status-descriptions">VKYC status and sub-status mapping</a></li>
    <li><a href="/docs/api-reference/prepaid-payment-instruments/webhook-signature-verification">Webhook signature verification</a></li>
  </ul>
</div>


# Overview
Source: https://www.cashfree.com/docs/api-reference/prepaid-payment-instruments/overview

Integrate and manage PPI APIs for wallet creation, balance checks, and transaction management in digital payments.

Use the Prepaid Payment Instrument (PPI) APIs to create and manage digital wallets, sub-wallets, gift cards, and prepaid cards for your users. They enable secure fund transactions, ensure compliance with RBI guidelines, and support integration across multiple business use cases.

## Key features

The key features offered by Cashfree's PPI APIs are:

* **Create and manage users, wallets, and sub-wallets:** Onboard users and create wallets or sub-wallets with program-based configuration, and update them as needed.
* **Fund transfers:** Handle credits, debits, and refunds securely with duplicate-transaction protection.
* **RBI-compliant KYC and rules:** Enforce KYC verification, balance limits, and transaction rules in line with RBI guidelines.
* **Wallet balances:** Retrieve total and sub-wallet balances in real time.

## Program structure

A Program defines the wallet type and rules for your integration.

* **Definition:** A Program specifies the type of wallet or instrument you can offer.
* **Functions:** It lets you configure limits, validity, and usage rules.
* **Sub-programs:** A Program can include multiple categories, such as meal, reward, or gift wallets, to support different use cases.

For example, the main program may have an overall load limit of ₹50,000 per month. Within it, the Meal sub-wallet could allow only ₹2,000 per month and be restricted to food merchants.

<Tabs>
  <Tab title="User Management and KYC">
    <div>
      <div>
        <div>
          <h4>User lifecycle</h4>

          <div>
            <div>
              <a href="/docs/api-reference/prepaid-payment-instruments/user-management/create-ppi-user">Create PPI User</a>

              <p>
                Create a new user in the PPI system with personal information required for wallet operations.
              </p>
            </div>
          </div>

          <hr />

          <div>
            <div>
              <a href="/docs/api-reference/prepaid-payment-instruments/user-management/get-ppi-user-details">Get PPI User Details</a>

              <p>
                Retrieve details of an existing user based on the user ID.
              </p>
            </div>
          </div>

          <hr />

          <div>
            <div>
              <a href="/docs/api-reference/prepaid-payment-instruments/user-management/update-ppi-user">Update PPI User</a>

              <p>
                Update an existing PPI user's information.
              </p>
            </div>
          </div>
        </div>
      </div>

      <div>
        <div>
          <h4>Verification flows</h4>

          <div>
            <div>
              <a href="/docs/api-reference/prepaid-payment-instruments/kyc-verification/min-kyc-verification">Min KYC Verification</a>

              <p>
                Perform minimum KYC verification for wallet users as per RBI guidelines.
              </p>
            </div>
          </div>

          <hr />

          <div>
            <div>
              <a href="/docs/api-reference/prepaid-payment-instruments/kyc-verification/send-otp">Send OTP</a>

              <p>
                Send an OTP to the user's registered mobile number for verification.
              </p>
            </div>
          </div>

          <hr />

          <div>
            <div>
              <a href="/docs/api-reference/prepaid-payment-instruments/kyc-verification/verify-otp">Verify OTP</a>

              <p>
                Verify the OTP submitted by the user to complete the verification flow.
              </p>
            </div>
          </div>
        </div>
      </div>
    </div>
  </Tab>

  <Tab title="Wallet Management">
    <div>
      <div>
        <div>
          <h4>Wallet lifecycle</h4>

          <div>
            <div>
              <a href="/docs/api-reference/prepaid-payment-instruments/wallet-management/create-wallet">Create Wallet</a>

              <p>
                Create a wallet and associated sub-wallets based on a program configuration.
              </p>
            </div>
          </div>

          <hr />

          <div>
            <div>
              <a href="/docs/api-reference/prepaid-payment-instruments/wallet-management/get-wallet-details">Get Wallet Details</a>

              <p>
                Fetch total wallet and sub-wallet balances with optional filtering by specific sub-wallet.
              </p>
            </div>
          </div>

          <hr />

          <div>
            <div>
              <a href="/docs/api-reference/prepaid-payment-instruments/wallet-management/check-wallet-eligibility">Check Wallet Eligibility</a>

              <p>
                Check if a user is eligible for wallet creation under a program.
              </p>
            </div>
          </div>

          <hr />

          <div>
            <div>
              <a href="/docs/api-reference/prepaid-payment-instruments/wallet-management/close-wallet">Close Wallet</a>

              <p>
                Close a specific sub-wallet.
              </p>
            </div>
          </div>
        </div>
      </div>

      <div>
        <div>
          <h4>Fund operations</h4>

          <div>
            <div>
              <a href="/docs/api-reference/prepaid-payment-instruments/wallet-management/credit-wallet">Credit Wallet</a>

              <p>
                Credit funds to a user's sub-wallet and issue gift codes for gift wallets.
              </p>
            </div>
          </div>

          <hr />

          <div>
            <div>
              <a href="/docs/api-reference/prepaid-payment-instruments/wallet-management/debit-wallet">Debit Wallet</a>

              <p>
                Debit an amount from a user's sub-wallet. Behaviour varies depending on the sub-wallet type.
              </p>
            </div>
          </div>

          <hr />

          <div>
            <div>
              <a href="/docs/api-reference/prepaid-payment-instruments/wallet-management/refund-wallet">Refund Wallet</a>

              <p>
                Process refunds for previously debited transactions, crediting the amount back to the user's sub-wallet.
              </p>
            </div>
          </div>

          <hr />

          <div>
            <div>
              <a href="/docs/api-reference/prepaid-payment-instruments/wallet-management/get-wallet-statement">Get Wallet Statement</a>

              <p>
                Fetch statement details for a specific sub-wallet.
              </p>
            </div>
          </div>
        </div>
      </div>
    </div>
  </Tab>
</Tabs>

## Getting started

Use the following resources to begin implementing PPI APIs:

<CardGroup>
  <Card title="API setup" href="/docs/api-reference/prepaid-payment-instruments/getting-started" icon="rocket">
    Base URLs, API keys, and steps to run your first PPI API request
  </Card>

  <Card title="Secure your integration" href="/docs/api-reference/authentication" icon="key">
    Authenticate requests and keep credentials safe with Client ID and Client Secret
  </Card>
</CardGroup>


# Get Transfer Details
Source: https://www.cashfree.com/docs/api-reference/prepaid-payment-instruments/transfers/get-transfer-details

openapi/ppi/ppi.yaml post /ppi/wallet/transfer/details
Retrieves detailed information about a specific transfer transaction, including current status, beneficiary details.

This endpoint provides comprehensive transfer information including:
- Current transfer status and bank status
- Beneficiary and instrument details
- Transaction timestamps and reference numbers if transaction successfully completed
- Sub-wallet balance after the transfer


<Accordion title="Click to view the response codes.">
  | HTTP status code | Status | Status code | Status description | Next action | Try again via Cashfree |
  | :- | :- | :- | :- | :- | :- |
  | 200 | APPROVAL\_PENDING | VELOCITY\_CHECK\_FAILED | The transfer requires an approval as the count of transfers to a particular beneficiary etc have breached the limit. You can approve or reject the transfer request from the Cashfree [Merchant Dashboard](https://merchant.cashfree.com/auth/login). | You can approve/reject the transfer on the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and go to **Transfers > Approve**. Post the transfer is approved, the request is sent to the partner bank for further processing. | - |
  | 200 | APPROVAL\_PENDING | TRANSFER\_LIMIT\_BREACH | The transfer requires an approval as the transfer amount etc have breached the limit. You can approve or reject the transfer request from the Cashfree [Merchant Dashboard](https://merchant.cashfree.com/auth/login). | You can approve/reject the transfer on the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and go to **Transfers > Approve**. Post the transfer is approved, the request is sent to the partner bank for further processing. | - |
  | 200 | APPOVAL\_PENDING | APPROVAL\_PENDING | The transfer requires approval. You can approve or reject the transfer request from the Cashfree [Merchant Dashboard](https://merchant.cashfree.com/auth/login). | You can approve/reject the transfer on the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and go to **Transfers > Approve**. Post the transfer is approved, the request is sent to the partner bank for further processing. | - |
  | 200 | FAILED | WAIT\_TIME\_EXCEEDED | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree to reattempt with the partner bank(s). | Yes |
  | 200 | FAILED | BENE\_BANK\_DECLINED | The transfer has failed because the beneficiary bank has declined the transfer. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again with the partner bank(s). | - | Yes |
  | 200 | FAILED | IMPS\_MODE\_FAIL | The transfer has failed because the beneficiary account doesnot support IMPS transfers. This rejection is done by the partner bank for the specific beneficiary account. You can try NEFT or other channels to do the disbursals. | You can try NEFT or other channels to do the disbursals. | Yes, via a different mode. |
  | 200 | FAILED | SOURCE\_BANK\_DECLINED | The transfer has failed because our partner bank has declined the transfer because of their internal checks, technical declines etc. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again with other partner bank(s). | Yes |
  | 200 | FAILED | CONNECTION\_TIMEOUT | The transfer has failed because there was a connection timeout between the bank and Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again with the partner bank(s). | Yes |
  | 200 | FAILED | PPI\_INTERNAL\_ERROR | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | - | Yes |
  | 200 | FAILED | NPCI\_UNAVAILABLE | The transfer has failed because NPCI was unavailable to complete the transfer request. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree. The success of the request is contingent on NPCI services being up. | - | Yes, after some time. |
  | 200 | FAILED | DEST\_LIMIT\_REACHED | The transfer has failed because the beneficiary account has breached the limit of receiving funds. This rejection is done by the beneficiary bank for the specific beneficiary account. You can reinitiate the transfer after a while via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). The success of the request is contingent on beneficiary's limit being available to receive incoming funds. | - | Yes, after some time. |
  | 200 | FAILED | RETURNED\_FROM\_BENEFICIARY | The transfer has failed because the beneficiary bank has returned the transfer and has not need able to credit funds to the end beneficiary. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again with the partner bank(s). | - | - |
  | 200 | FAILED | PPI\_INTERNAL\_ERROR | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | - | - |
  | 200 | FAILED | INVALID\_BENE\_ACCOUNT\_OR\_IFSC | The transfer has failed because the beneficiary account or IFSC is invalid. After correcting the beneficiary account or IFSC, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | - | - |
  | 200 | FAILED | PPI\_INTERNAL\_ERROR | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | - | - |
  | 200 | FAILED | FAILED | The transfer has failed because there was an intermittent issue at the partner bank's end. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after some time. |
  | 200 | FAILED | PPI\_INTERNAL\_ERROR | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | - | - |
  | 200 | FAILED | INSUFFICIENT\_BALANCE | The transfer has failed because of low balance in your Cashfree Wallet/ Bank Account. After recharging the account, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After recharging the account, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after recharging. |
  | 200 | FAILED | INVALID\_BENE\_VPA | The transfer has failed because the beneficiary VPA is invalid. After correcting the VPA handle, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the VPA handle, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting VPA handle. |
  | 200 | FAILED | INVALID\_IFSC\_FAIL | The transfer has failed because the IFSC is invalid. After correcting the IFSC, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the IFSC, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting IFSC. |
  | 200 | FAILED | BAD\_GATEWAY | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | FAILED | INVALID\_AMOUNT\_FAIL | The transfer has failed because the amount entered is invalid. After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting amount |
  | 200 | FAILED | INVALID\_ACCOUNT\_FAIL | The transfer has failed because the Account Number of the beneficiary is invalid, as per our partner bank. After correcting the account number, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the account number, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting account number |
  | 200 | FAILED | INVALID\_REQUEST | The transfer has failed because the transfer request is invalid, as per our partner bank, because of exceeding the character limit of certain parameter, wrong input etc. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | - | - |
  | 200 | FAILED | ACCOUNT\_BLOCKED | The transfer has failed because the account is blocked, as per our partner bank. After getting the account unblocked, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After getting the account unblocked, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after unblocking the account number |
  | 200 | FAILED | DEBIT\_FAILURE | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | FAILED | BENEFICIARY\_BANK\_OFFLINE | The transfer has failed because the respective beneficiary bank is offline. After some time, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After some time, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after some time |
  | 200 | FAILED | AUTHENTICATION\_FAILURE | The transfer has failed because there was an authentication failure at the partner bank's end. After checking with the partner bank, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | This is a scenario when the API access is not working at the partner bank's end. After checking with the partner bank, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | FAILED | NRE\_ACCOUNT\_FAIL | The transfer has failed because the beneficiary account is an NRE Account and transfers to NRE Accounts are not supported, as per our partner bank. | Get a new account(non-NRE account) from the beneficiary; you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | FAILED | SOURCE\_LIMIT\_REACHED | The transfer has been failed by the partner bank as the source bank account has reached a limit of transferring funds. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | If you are on Cashfree Wallet, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). If you are on Connected Bank, you need to recharge your bank account and then reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after some time |
  | 200 | FAILED | BANK\_GATEWAY\_ERROR | The transfer has failed because there was an intermittent issue at the partner bank's end. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | FAILED | BAD\_REQUEST | The transfer has failed because the details of the transfer request is invalid, as per our partner bank. After correcting the details in the transfer request, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the details in the transfer request, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | FAILED | REINITIALIZE\_TRANSFER\_LATER | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | MANUALLY\_REJECTED | MANUALLY\_REJECTED | The transfer has failed because it has been manually rejected by the merchant or any team member user who has the permissions to do the same on [Merchant Dashboard](https://merchant.cashfree.com/auth/login). You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again with the partner bank(s). | If the merchant wants to reinitiate the transfer, they can reinitiate the transfer via Cashfree so that the transfer can be reattempted again with the partner bank(s). | Yes,  if you want to reinitiate the transfer |
  | 200 | PENDING | SENT\_TO\_BANK | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. This has been sent to the bank by our banking operations team. Please do check statuses or await webhooks to know the terminal state of the transfer request. | Rely on Check Status API or Webhooks. | - |
  | 200 | PENDING | BANK\_GATEWAY\_ERROR | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. You should rely only on Check Status API response or Webhooks to know the terminal state of the transfer request. | Rely on Check Status API or Webhooks. | - |
  | 200 | PENDING | NO\_SUCH\_REQUEST | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. The bank is not able to find the request at their end as of now, and it has been sent to the bank by our banking operations team. Please do check statuses or await webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks. | - |
  | 200 | PENDING | IN\_PROCESS | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. Please do check statuses or await webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks. | - |
  | 200 | PENDING | ERROR\_FETCHING\_STATUS | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. The response received from the partner bank has a new code. This has been raised with the bank to understand the new code. Please do check statuses or await webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks. | - |
  | 200 | PENDING | TRANSACTION\_PROCESSED | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. You should rely only on Check Status API response or Webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks. | - |
  | 200 | PENDING | REQUEST\_TIMEDOUT | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. The bank is not able to find the request at their end as of now as the request between the partner bank has probably timed out, and it has been highlighted to the bank by our banking operations team. Please do check statuses or await webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks. | - |
  | 200 | PENDING | DUPLICATE | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. The bank claims of receiving a duplicate request at their end as of now. You should rely only on Check Status API response or Webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks. | - |
  | 200 | PENDING | PENDING | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. You should rely only on Check Status API response or Webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks. | - |
  | 200 | PENDING | SCHEDULED\_FOR\_NEXT\_WORKINGDAY | The transfer is currently in a Pending state, as the bank has scheduled the transfer for the next working day. This typically happens for NEFT/RTGS transfers if they are initiated beyond the cut-off hours or during bank holidays. You should rely only on Check Status API response or Webhooks to know the terminal state of the transfer request. | - | - |
  | 200 | PENDING | SUSPECT | The transfer is currently in a Pending state, as the bank has scheduled the transfer for the next working day. This typically happens for NEFT/RTGS transfers if they are initiated beyond the cut-off hours or during bank holidays. You should rely only on Check Status API response or Webhooks to know the terminal state of the transfer request. | - | - |
  | 200 | PENDING | IMPLEMENTATION\_ERROR | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. You should rely only on Check Status API response or Webhooks to know the terminal state of the transfer request. | - | - |
  | 200 | PENDING | UNKNOWN\_ERROR\_CODE | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. The response received from the partner bank has a new code. This has been raised with the bank to understand the new code. Please do check statuses or await webhooks to know the terminal state of the transfer request. | - | - |
  | 200 | QUEUED | QUEUED | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. You should rely only on Check Status API response or Webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks. | - |
  | 200 | RECEIVED | RECEIVED | The transfer has been received by Cashfree successfully for further processing. You should use Check Status API response or Webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks. | - |
  | 200 | REJECTED | BENE\_NOT\_EXIST | The transfer has been rejected because the beneficiary, added in the transfer request, does not exist. After adding the right beneficiary, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After adding the right beneficiary, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after adding the correct beneficiary. |
  | 200 | REJECTED | INSUFFICIENT\_BALANCE | The transfer has been rejected because of low balance in your Cashfree Wallet. After recharging the account, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After recharging the account, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after recharging. |
  | 200 | REJECTED | INSIDE\_BLACKOUT\_WINDOW | The transfer has been rejected because the transfer falls under the blackout window defined by you in PPI Protect. You can reinitiate the transfer via Cashfree, after the blackout window or after modifying the blackout window from the [Merchant Dashboard](https://merchant.cashfree.com/auth/login), so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree, after the blackout window or after modifying the blackout window from the [Merchant Dashboard](https://merchant.cashfree.com/auth/login), so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | REJECTED | INVALID\_MODE\_FOR\_PYID | The transfer has been rejected because the payment instrument does not support this mode of transfer. You should get this mode activated on the payment instrument ID by contacting Cashfree, and then initiate a new transfer request. | You should get this mode activated on the payment instrument ID by contacting Cashfree, and then initiate a new transfer request. | Yes, after activating model |
  | 200 | REJECTED | BENE\_BLACKLISTED | The transfer has been rejected because the beneficiary's bank account and/or VPA handles have been blacklisted by Risk team. You should get a different bank account and/or VPA to send the transfer, or you can connect with Cashfree Team to understand more about this. | You should get a different bank account and/or VPA to send the transfer, or you can connect with Cashfree Team to understand more about this. | Yes, after correcting beneficiary details |
  | 200 | REJECTED | TRANSFER\_NOT\_ATTEMPTED | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | REJECTED | INVALID\_TRANSFER\_AMOUNT | The transfer has been rejected because the amount entered is invalid. After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting the amount |
  | 200 | REJECTED | TRANSFER\_LIMIT\_BREACH | The transfer has been rejected because the amount entered breaches the limits set for your ppi account. After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). You can connect with Cashfree if you are not sure about the transfer limits set for your ppi account. | After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). You can connect with Cashfree if you are not sure about the transfer limits set for your ppi account. | Yes, after adhering to the transfer limits. |
  | 200 | REJECTED | INVALID\_PAYMENT\_INSTRUMENT | The transfer has been rejected because the payment instrument (fundsource\_id parameter in the API request) used for attempting the transfer is invalid. After correcting the payment instrument, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | After correcting the payment instrument, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting payment instrument |
  | 200 | REJECTED | PPI\_INTERNAL\_ERROR | The transfer has been rejected because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | REJECTED | VELOCITY\_CHECK\_FAILED | The transfer has been rejected because the amount entered breaches the limits set for your ppi account. After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). You can connect with Cashfree if you are not sure about the transfer limits set for your ppi account. | After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). You can connect with Cashfree if you are not sure about the transfer limits set for your ppi account. | Yes, after adhering to the transfer limits. |
  | 200 | REJECTED | PPI\_INTERNAL\_ERROR | The transfer has been rejected because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | REJECTED | PPI\_INTERNAL\_ERROR | The transfer has been rejected because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | REJECTED | DISABLED\_MODE | The transfer has been rejected because your ppi account does not support this mode of transfer. You should get this mode activated on your payout account by contacting Cashfree, and then initiate a new transfer request. | You should get this mode activated on your ppi account by contacting Cashfree, and then initiate a new transfer request. | Yes, after activating mode. |
  | 200 | REJECTED | BANK\_ACCOUNT\_INVALID | The transfer has been rejected because there is a mismatch in the Bank Account Number of the beneficiary ID and the Bank Account Number in the transfer request. After correcting the Bank Account Number, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | After correcting the Bank Account Number, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting the bank account number. |
  | 200 | REJECTED | BANK\_IFSC\_INVALID | The transfer has been rejected because there is a mismatch in the IFSC of the beneficiary ID and the IFSC in the transfer request. After correcting the IFSC, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | After correcting the IFSC, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting the IFSC |
  | 200 | REJECTED | VPA\_INVALID | The transfer has been rejected because there is a mismatch in the VPA handle of the beneficiary ID and the VPA handle in the transfer request. After correcting the VPA handle, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | After correcting the VPA handle, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting the VPA handle |
  | 200 | REJECTED | PHONE\_INVALID | The transfer has been rejected because there is a mismatch in the Phone Number of the beneficiary ID and the Phone Number in the transfer request. After correcting the Phone Number, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | After correcting the Phone Number, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting the phone number. |
  | 200 | REJECTED | BANK\_ACCOUNT\_DETAILS\_MISSING | The transfer has been rejected because the Bank Account Details are missing in the transfer request. After adding the Bank Account Details, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | After adding the Bank Account Details, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after adding the bank account details. |
  | 200 | REVERSED | ACCOUNT\_BLOCKED | The transfer has been reversed by the beneficiary bank as the end-beneficiary's account is blocked for receiving incoming funds. After correcting the account number or getting the account unblocked, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the account number or getting the account unblocked, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after adding new details or getting account unblocked. |
  | 200 | REVERSED | FAILED | The transfer has been reversed by the beneficiary bank as they were unable to credit the end beneficiary's bank account. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | - | Yes |
  | 200 | REVERSED | NRE\_ACCOUNT\_FAIL | The transfer has been reversed by the beneficiary bank as they were unable to credit the end beneficiary's bank account as it is an NRE Account and transfers to NRE Accounts are not supported. | Get a new account(non-NRE account) from the beneficiary; you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | No |
  | 200 | REVERSED | RETURNED\_FROM\_BENEFICIARY | The transfer has been reversed by the beneficiary bank as they were unable to credit the end beneficiary's bank account. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | REVERSED | BENE\_BANK\_DECLINED | The transfer has been declined by the beneficiary bank and they were unable to credit the end beneficiary's bank account. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | REVERSED | IMPS\_MODE\_FAIL | The transfer has been reversed by the beneficiary bank because the beneficiary bank account doesnot support IMPS transfers. This rejection is done by the beneficiary bank for the specific beneficiary account. You can try NEFT or other channels to do the disbursals. | You can reinitiate the transfer via Cashfree by changing the mode so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after changing mode. |
  | 200 | REVERSED | DEST\_LIMIT\_REACHED | The transfer has been reversed by the beneficiary bank as the end-beneficiary's account has reached a limit of receiving incoming funds. This rejection is done by the beneficiary bank for the specific beneficiary account. You can reinitiate the transfer after a while via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). The success of the request is contingent on beneficiary's limit being available to receive incoming funds. | The limits on the beneficiary account are typically refreshed every 24 hours. Its not clear when the 24 hour window shall elpase so you can then reinitiate the transfer via Cashfree after some time so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after some time. |
  | 200 | REVERSED | INVALID\_ACCOUNT\_FAIL | The transfer has been reversed by the beneficiary bank because the Account Number of the beneficiary is invalid. After correcting the account number, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the account number, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting the account number |
  | 200 | SUCCESS | SENT\_TO\_BENEFICIARY | The transfer has been initiated via the partner bank successfully. The request is waiting to be processed at the beneficiary bank to do the credit to the end beneficiary. | - | - |
  | 200 | SUCCESS | COMPLETED | The transfer has been initiated via the partner bank successfully, hence your account is debited and the request is successfully processed by the beneficiary bank and has been credited to the end beneficiary. | - | - |
  | 200 | REJECTED | TRANSFERID\_INVALID | transferid can contain only alphabets, numbers, underscore (\_), hyphen (-). | After correcting the transferid, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting transfer id. |
  | 200 | REJECTED | AMOUNT\_INVALID | amount can contain only numbers. | After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting amount. |
  | 200 | REJECTED | REMARKS\_INVALID | remarks can contain only alphabets, numbers and space. | After correcting the remarks, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting remarks. |
  | 200 | REJECTED | BENEID\_INVALID | beneId can contain only alphabets, numbers and underscore. | After correcting the beneid, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting beneficiary id. |
  | 200 | REJECTED | NAME\_INVALID | name can contain only alphabets, numbers and space. | After correcting the name, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting name. |
  | 200 | REJECTED | EMAIL\_INVALID | email is not a valid email format. | After correcting the email, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting email. |
  | 200 | REJECTED | IBAN\_INVALID | iban can contain only alphabet and numbers. | After correcting the iban, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting IBAN. |
  | 200 | REJECTED | TRANSFERMODE\_INVALID | transferMode can contain in one of banktransfer upi paytm amazonpay imps neft rtgs ppc. | After correcting the transfermode, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting mode. |
  | 200 | REJECTED | CURRENCY\_INVALID | currency is invalid. | After correcting the currency, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting currency. |
  | 200 | REJECTED | ACCOUNT\_DOES\_NOT\_EXIST | The transfer has been rejected because the beneficiary account/ VPA does not exist as per our partner bank. | After correcting the account number, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting details. |
  | 200 | FAILED | ACCOUNT\_DOES\_NOT\_EXIST | The transfer has failed because the beneficiary account/ VPA does not exist as per our partner bank. | After correcting the account number, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting details. |
  | 200 | REJECTED | AMAZON\_AMOUNT\_EXCEED | The transfer has been rejected because the amount entered breaches the limits set for the beneficiaries amazon account. | After verifying the limits for beneficiaries amazon account, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after verifying limits. |
  | 200 | FAILED | AMAZON\_AMOUNT\_EXCEED | The transfer has failed because the amount entered breaches the limits set for the beneficiaries amazon account. | After verifying the limits for beneficiaries amazon account, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after verifying limits. |
  | 200 | REJECTED | ANOMALY\_DETECTION | The transfer has been rejected as Cashfree risk product has detected an anamoly. | You can reinitiate the transfer request after validation at your end. | Yes, after validation. |
  | 200 | APPROVAL\_PENDING | ANOMALY\_DETECTION | The transfer requires approval as Cashfree risk product has detected an anamoly. | You can approve/reject the transfer on the merchant dashboard. Post the transfer is approved, the request is sent to the partner bank for further processing. | - |
  | 200 | FAILED | BAD\_CONNECTION | The transfer has failed because there was an intermittent internal error between Cashfree and the partner bank. | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after some time. |
  | 200 | REJECTED | BENE\_INVALID | The transfer has been rejected because the beneficiary added in the transfer request does not exist. | After adding the right beneficiary, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after adding beneficiary. |
  | 200 | FAILED | BENE\_INVALID | The transfer has failed because the beneficiary added in the transfer request does not exist. | After adding the right beneficiary, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after adding beneficiary. |
  | 200 | FAILED | BENE\_NOT\_REGISTERED | The transfer has been rejected because the beneficiary added in the transfer request is not registered with the partner bank. | After adding the right beneficiary, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after adding beneficiary. |
  | 200 | VALIDATION\_PENDING | BENE\_VERIFICATION\_PENDING | The transfer is pending because the beneficiary verification is pending. Once the beneficiary is validated we will attempt the transfers with partner bank(s). | - | - |
  | 200 | FAILED | BENEFICIARY\_BANK\_UNAVAILABLE | The transfer has failed because the respective beneficiary bank is offline. | After some time, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after some time. |
  | 200 | FAILED | BENEFICIARY\_NAME\_DIFFERS | The transfer has failed because the beneficiary name differs as per Cashfree's partner bank. | After adding the right beneficiary, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting name. |
  | 200 | REJECTED | BENEFICIARY\_NAME\_DIFFERS | The transfer has been rejected because the beneficiary name differs as per Cashfree's partner bank. | After adding the right beneficiary, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting name. |
  | 200 | REJECTED | BENEFICIARY\_NAME\_MISMATCH | The transfer has been rejected because the beneficiary name differs as per Cashfree's partner bank. | After adding the right beneficiary, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting name. |
  | 200 | REJECTED | CARD\_UNSUPPORTED | The transfer has been rejected because the card is not supported. | After changing the payment instrument details, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after changing instrument. |
  | 200 | FAILED | CARD\_UNSUPPORTED | The transfer has failed because the card is not supported. | After changing the payment instrument details, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after changing instrument. |
  | 200 | FAILED | DUPLICATE\_FAILED | The transfer has failed as the bank claims of receiving a duplicate request at their end as of now. | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, with new id. |
  | 200 | FAILED | ERROR\_RETRIEVING\_BALANCE | The transfer has failed because there was an intermittent issue at the partner bank's end. | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after some time. |
  | 200 | REJECTED | INVALID\_CARD | The transfer has been rejected because the card details are not correct. | After changing the payment instrument details, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting card. |
  | 200 | FAILED | INVALID\_CARD | The transfer has failed because the card details are not correct. | After changing the payment instrument details, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting card. |
  | 200 | REJECTED | INVALID\_CURRENCY\_FOR\_PYID | The transfer has been rejected because the transfer currency passed in the transfer request is not supported by Cashfree. | After changing the currency to INR, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after changing currency. |
  | 200 | FAILED | INVALID\_CURRENCY\_FOR\_PYID | The transfer has been rejected because the transfer currency passed in the transfer request is not supported by Cashfree. | After changing the currency to INR, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after changing currency. |
  | 200 | FAILED | INVALID\_MODE\_FAIL | The transfer has failed because the requested transfer mode is not supported for this beneficiary account as per the partner bank. | After changing the transfer mode, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after changing mode. |
  | 200 | REJECTED | INVALID\_OR\_NO\_SUCH\_ACCOUNT\_TYPE | The transfer has been rejected because the beneficiary account type is invalid or not supported as per our partner bank. | Get a new account from the beneficiary; you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after new account. |
  | 200 | FAILED | INVALID\_OR\_NO\_SUCH\_ACCOUNT\_TYPE | The transfer has failed because the beneficiary account type is invalid or not supported as per our partner bank. | Get a new account from the beneficiary; you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after new account. |
  | 200 | FAILED | INVALID\_PHONE\_BENEFICIARY | The transfer has failed because the beneficiary's phone number is not linked to any VPA. | After adding the right phone beneficiary, You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting phone. |
  | 200 | REJECTED | INVALID\_TRANSFER\_CURRENCY | The transfer has been rejected because the transfer currency passed in the transfer request is not supported by Cashfree. | After changing the currency to INR, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after changing currency. |
  | 200 | FAILED | INVALID\_TRANSFER\_CURRENCY | The transfer has failed because the transfer currency passed in the transfer request is not supported by Cashfree. | After changing the currency to INR, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after changing currency. |
  | 200 | REJECTED | KYC\_COMPLIANCE\_VERIFICATION\_FAILED | The transfer has failed because the KYC verification has failed. | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after KYC resolution. |
  | 200 | REJECTED | KYC\_REQUIREMENTS\_NOT\_SATISFIED | The transfer has failed because the KYC requirements have not been satisfied. | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after completing KYC. |
  | 200 | FAILED | LOAD\_LIMIT\_EXHAUSTED | The transfer has failed because the beneficiaries account has reached maximum transaction amount limit. | After 24 hours, You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after 24 hours. |
  | 200 | FAILED | LOAN\_FUND\_MOVEMENT\_FAILURE | The transfer has failed because of an intermittent issue at Cashfree's end. | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after some time. |
  | 200 | PENDING | LOW\_BALANCE\_QUEUED | The transfer is pending because the balance in the fund source is exhausted. This transfer will be processed after you recharge the fund source, you need not reinitiate this transfer. | This transfer will be processed after you recharge the fund source, you need not reinitiate this transfer. Please rely on check status API or webhook for checking the status of this transfer. | - |
  | 200 | REJECTED | MANUALLY\_REJECTED | The transfer has been manually rejected by you. | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree. | Yes, if needed. |
  | 200 | REJECTED | PPI\_INACTIVE | The transfer has been rejected because your ppi account has been inactive. | After getting the account activated, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after activation. |
  | 200 | PENDING | PENDING | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. | Rely on Check Status API or Webhooks | - |
  | 200 | FAILED | POOL\_CONNECTION\_TIMEOUT | The transfer has failed because there was a connection issue with the partner bank's end. | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after some time. |
  | 200 | REJECTED | QUICK\_TRANSFER\_DISABLED | The transfer has been rejected because quick transfer is disabled for your ppi account. | After getting quick transfer enabled, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after enabling. |
  | 200 | REJECTED | REJECTED | Transfer rejected. | - | Yes, after correction. |
  | 200 | REVERSED | REVERSED | The transfer has been reversed by the beneficiary bank as the credit to end-beneficiary's account has failed. | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correction. |
  | 200 | FAILED | RTGS\_MODE\_FAIL | The transfer has failed because the beneficiary account doesnot support RTGS transfers. | You can try NEFT or other channels to do the disbursals. | Yes, via different mode. |
  | 200 | FAILED | SUSPECTED\_FAILED | The transfer has failed, as the partner bank suspects that the transfer is of fraudulent nature. | - | No (investigate). |
  | 200 | REJECTED | VBA\_TRANSFER\_DISABLED | The transfer has been rejected because transfers to virtual bank accounts are not enabled for your Cashfree Account. | After getting payouts to virtual bank accounts enabled, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). You can connect with Cashfree for enabling payouts to virtual bank accounts. | Yes, after enabling. |
  | 200 | REJECTED | ERROR\_SELECTING\_FUND\_SOURCE | The transfer has been rejected because their is some issue with your account configuration. | You can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after fixing config. |
  | 200 | VALIDATION\_PENDING | VALIDATION\_PENDING | The transfer is pending because the beneficiary verification is pending. Once the beneficiary is validated we will attempt the transfers with partner bank(s). | Rely on Check Status API or Webhooks | - |
  | 200 | REJECTED | INVALID\_BENEFICIARY\_CODE | The transfer has been rejected because the bene code is Invalid. | After correcting the beneficiary code, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting code. |
  | 200 | REJECTED | DUPLICATE\_TRANSFER | The transfer is already present in the file or has been processed previously. Please change the transferId in the api request. | After changing the Transfer Id, You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, with new transfer id. |
</Accordion>


# Initiate Transfer
Source: https://www.cashfree.com/docs/api-reference/prepaid-payment-instruments/transfers/initiate-transfer

openapi/ppi/ppi.yaml post /ppi/wallet/transfer
Initiates a fund transfer from a user's FULL_KYC_PPI sub-wallet to a beneficiary account. Supports multiple transfer modes including RTGS, NEFT, IMPS, and UPI. It is an async request by default.

The beneficiary can be specified using either:
- Existing beneficiary ID and instrument ID
- New instrument details (bank account or UPI)


<Note>
  **Get Transfer Detail/Status**<br />
  Use the [Get Transfer Details](/docs/api-reference/prepaid-payment-instruments/transfers/get-transfer-details) API to get the details of the transfer request.

  **OTP verification**<br />
  Call [Verify Transfer OTP](/docs/api-reference/prepaid-payment-instruments/transfers/verify-transfer) with the OTP before the transfer is sent for bank processing.
</Note>

<Accordion title="Click to view the response codes.">
  | HTTP status code | Status | Status code | Status description | Next action | Try again via Cashfree |
  | :- | :- | :- | :- | :- | :- |
  | 200 | APPROVAL\_PENDING | VELOCITY\_CHECK\_FAILED | The transfer requires an approval as the count of transfers to a particular beneficiary etc have breached the limit. You can approve or reject the transfer request from the Cashfree [Merchant Dashboard](https://merchant.cashfree.com/auth/login). | You can approve/reject the transfer on the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and go to **Transfers > Approve**. Post the transfer is approved, the request is sent to the partner bank for further processing. | - |
  | 200 | APPROVAL\_PENDING | TRANSFER\_LIMIT\_BREACH | The transfer requires an approval as the transfer amount etc have breached the limit. You can approve or reject the transfer request from the Cashfree [Merchant Dashboard](https://merchant.cashfree.com/auth/login). | You can approve/reject the transfer on the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and go to **Transfers > Approve**. Post the transfer is approved, the request is sent to the partner bank for further processing. | - |
  | 200 | APPOVAL\_PENDING | APPROVAL\_PENDING | The transfer requires approval. You can approve or reject the transfer request from the Cashfree [Merchant Dashboard](https://merchant.cashfree.com/auth/login). | You can approve/reject the transfer on the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and go to **Transfers > Approve**. Post the transfer is approved, the request is sent to the partner bank for further processing. | - |
  | 200 | FAILED | WAIT\_TIME\_EXCEEDED | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree to reattempt with the partner bank(s). | Yes |
  | 200 | FAILED | BENE\_BANK\_DECLINED | The transfer has failed because the beneficiary bank has declined the transfer. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again with the partner bank(s). | - | Yes |
  | 200 | FAILED | IMPS\_MODE\_FAIL | The transfer has failed because the beneficiary account does not support IMPS transfers. This rejection is done by the partner bank for the specific beneficiary account. You can try NEFT or other channels to do the disbursals. | You can try NEFT or other channels to do the disbursals. | Yes, via a different mode. |
  | 200 | FAILED | SOURCE\_BANK\_DECLINED | The transfer has failed because our partner bank has declined the transfer because of their internal checks, technical declines etc. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again with other partner bank(s). | Yes |
  | 200 | FAILED | CONNECTION\_TIMEOUT | The transfer has failed because there was a connection timeout between the bank and Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again with the partner bank(s). | Yes |
  | 200 | FAILED | PPI\_INTERNAL\_ERROR | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | - | Yes |
  | 200 | FAILED | NPCI\_UNAVAILABLE | The transfer has failed because NPCI was unavailable to complete the transfer request. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree. The success of the request is contingent on NPCI services being up. | - | Yes, after some time. |
  | 200 | FAILED | DEST\_LIMIT\_REACHED | The transfer has failed because the beneficiary account has breached the limit of receiving funds. This rejection is done by the beneficiary bank for the specific beneficiary account. You can reinitiate the transfer after a while via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). The success of the request is contingent on beneficiary's limit being available to receive incoming funds. | - | Yes, after some time. |
  | 200 | FAILED | RETURNED\_FROM\_BENEFICIARY | The transfer has failed because the beneficiary bank has returned the transfer and has not need able to credit funds to the end beneficiary. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again with the partner bank(s). | - | - |
  | 200 | FAILED | PPI\_INTERNAL\_ERROR | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | - | - |
  | 200 | FAILED | INVALID\_BENE\_ACCOUNT\_OR\_IFSC | The transfer has failed because the beneficiary account or IFSC is invalid. After correcting the beneficiary account or IFSC, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | - | - |
  | 200 | FAILED | PPI\_INTERNAL\_ERROR | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | - | - |
  | 200 | FAILED | FAILED | The transfer has failed because there was an intermittent issue at the partner bank's end. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after some time. |
  | 200 | FAILED | PPI\_INTERNAL\_ERROR | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | - | - |
  | 200 | FAILED | INSUFFICIENT\_BALANCE | The transfer has failed because of low balance in your Cashfree Wallet/ Bank Account. After recharging the account, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After recharging the account, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after recharging. |
  | 200 | FAILED | INVALID\_BENE\_VPA | The transfer has failed because the beneficiary VPA is invalid. After correcting the VPA handle, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the VPA handle, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting VPA handle. |
  | 200 | FAILED | INVALID\_IFSC\_FAIL | The transfer has failed because the IFSC is invalid. After correcting the IFSC, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the IFSC, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting IFSC. |
  | 200 | FAILED | BAD\_GATEWAY | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | FAILED | INVALID\_AMOUNT\_FAIL | The transfer has failed because the amount entered is invalid. After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting amount |
  | 200 | FAILED | INVALID\_ACCOUNT\_FAIL | The transfer has failed because the Account Number of the beneficiary is invalid, as per our partner bank. After correcting the account number, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the account number, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting account number |
  | 200 | FAILED | INVALID\_REQUEST | The transfer has failed because the transfer request is invalid, as per our partner bank, because of exceeding the character limit of certain parameter, wrong input etc. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | - | - |
  | 200 | FAILED | ACCOUNT\_BLOCKED | The transfer has failed because the account is blocked, as per our partner bank. After getting the account unblocked, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After getting the account unblocked, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after unblocking the account number |
  | 200 | FAILED | DEBIT\_FAILURE | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | FAILED | BENEFICIARY\_BANK\_OFFLINE | The transfer has failed because the respective beneficiary bank is offline. After some time, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After some time, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after some time |
  | 200 | FAILED | AUTHENTICATION\_FAILURE | The transfer has failed because there was an authentication failure at the partner bank's end. After checking with the partner bank, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | This is a scenario when the API access is not working at the partner bank's end. After checking with the partner bank, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | FAILED | NRE\_ACCOUNT\_FAIL | The transfer has failed because the beneficiary account is an NRE Account and transfers to NRE Accounts are not supported, as per our partner bank. | Get a new account(non-NRE account) from the beneficiary; you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | FAILED | SOURCE\_LIMIT\_REACHED | The transfer has been failed by the partner bank as the source bank account has reached a limit of transferring funds. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | If you are on Cashfree Wallet, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). If you are on Connected Bank, you need to recharge your bank account and then reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after some time |
  | 200 | FAILED | BANK\_GATEWAY\_ERROR | The transfer has failed because there was an intermittent issue at the partner bank's end. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | FAILED | BAD\_REQUEST | The transfer has failed because the details of the transfer request is invalid, as per our partner bank. After correcting the details in the transfer request, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the details in the transfer request, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | FAILED | REINITIALIZE\_TRANSFER\_LATER | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | MANUALLY\_REJECTED | MANUALLY\_REJECTED | The transfer has failed because it has been manually rejected by the merchant or any team member user who has the permissions to do the same on [Merchant Dashboard](https://merchant.cashfree.com/auth/login). You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again with the partner bank(s). | If the merchant wants to reinitiate the transfer, they can reinitiate the transfer via Cashfree so that the transfer can be reattempted again with the partner bank(s). | Yes,  if you want to reinitiate the transfer |
  | 200 | PENDING | SENT\_TO\_BANK | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. This has been sent to the bank by our banking operations team. Please do check statuses or await webhooks to know the terminal state of the transfer request. | Rely on Check Status API or Webhooks. | - |
  | 200 | PENDING | BANK\_GATEWAY\_ERROR | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. You should rely only on Check Status API response or Webhooks to know the terminal state of the transfer request. | Rely on Check Status API or Webhooks. | - |
  | 200 | PENDING | NO\_SUCH\_REQUEST | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. The bank is not able to find the request at their end as of now, and it has been sent to the bank by our banking operations team. Please do check statuses or await webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks. | - |
  | 200 | PENDING | IN\_PROCESS | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. Please do check statuses or await webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks. | - |
  | 200 | PENDING | ERROR\_FETCHING\_STATUS | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. The response received from the partner bank has a new code. This has been raised with the bank to understand the new code. Please do check statuses or await webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks. | - |
  | 200 | PENDING | TRANSACTION\_PROCESSED | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. You should rely only on Check Status API response or Webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks. | - |
  | 200 | PENDING | REQUEST\_TIMEDOUT | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. The bank is not able to find the request at their end as of now as the request between the partner bank has probably timed out, and it has been highlighted to the bank by our banking operations team. Please do check statuses or await webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks. | - |
  | 200 | PENDING | DUPLICATE | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. The bank claims of receiving a duplicate request at their end as of now. You should rely only on Check Status API response or Webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks. | - |
  | 200 | PENDING | PENDING | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. You should rely only on Check Status API response or Webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks. | - |
  | 200 | PENDING | SCHEDULED\_FOR\_NEXT\_WORKINGDAY | The transfer is currently in a Pending state, as the bank has scheduled the transfer for the next working day. This typically happens for NEFT/RTGS transfers if they are initiated beyond the cut-off hours or during bank holidays. You should rely only on Check Status API response or Webhooks to know the terminal state of the transfer request. | - | - |
  | 200 | PENDING | SUSPECT | The transfer is currently in a Pending state, as the bank has scheduled the transfer for the next working day. This typically happens for NEFT/RTGS transfers if they are initiated beyond the cut-off hours or during bank holidays. You should rely only on Check Status API response or Webhooks to know the terminal state of the transfer request. | - | - |
  | 200 | PENDING | IMPLEMENTATION\_ERROR | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. You should rely only on Check Status API response or Webhooks to know the terminal state of the transfer request. | - | - |
  | 200 | PENDING | UNKNOWN\_ERROR\_CODE | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. The response received from the partner bank has a new code. This has been raised with the bank to understand the new code. Please do check statuses or await webhooks to know the terminal state of the transfer request. | - | - |
  | 200 | QUEUED | QUEUED | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. You should rely only on Check Status API response or Webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks. | - |
  | 200 | RECEIVED | RECEIVED | The transfer has been received by Cashfree successfully for further processing. You should use Check Status API response or Webhooks to know the terminal state of the transfer request. | Rely on Check Status API or webhooks. | - |
  | 200 | REJECTED | BENE\_NOT\_EXIST | The transfer has been rejected because the beneficiary, added in the transfer request, does not exist. After adding the right beneficiary, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After adding the right beneficiary, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after adding the correct beneficiary. |
  | 200 | REJECTED | INSUFFICIENT\_BALANCE | The transfer has been rejected because of low balance in your Cashfree Wallet. After recharging the account, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After recharging the account, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after recharging. |
  | 200 | REJECTED | INSIDE\_BLACKOUT\_WINDOW | The transfer has been rejected because the transfer falls under the blackout window defined by you in PPI Protect. You can reinitiate the transfer via Cashfree, after the blackout window or after modifying the blackout window from the [Merchant Dashboard](https://merchant.cashfree.com/auth/login), so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree, after the blackout window or after modifying the blackout window from the [Merchant Dashboard](https://merchant.cashfree.com/auth/login), so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | REJECTED | INVALID\_MODE\_FOR\_PYID | The transfer has been rejected because the payment instrument does not support this mode of transfer. You should get this mode activated on the payment instrument ID by contacting Cashfree, and then initiate a new transfer request. | You should get this mode activated on the payment instrument ID by contacting Cashfree, and then initiate a new transfer request. | Yes, after activating model |
  | 200 | REJECTED | BENE\_BLACKLISTED | The transfer has been rejected because the beneficiary's bank account and/or VPA handles have been blacklisted by Risk team. You should get a different bank account and/or VPA to send the transfer, or you can connect with Cashfree Team to understand more about this. | You should get a different bank account and/or VPA to send the transfer, or you can connect with Cashfree Team to understand more about this. | Yes, after correcting beneficiary details |
  | 200 | REJECTED | TRANSFER\_NOT\_ATTEMPTED | The transfer has failed because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | REJECTED | INVALID\_TRANSFER\_AMOUNT | The transfer has been rejected because the amount entered is invalid. After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting the amount |
  | 200 | REJECTED | TRANSFER\_LIMIT\_BREACH | The transfer has been rejected because the amount entered breaches the limits set for your ppi account. After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). You can connect with Cashfree if you are not sure about the transfer limits set for your ppi account. | After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). You can connect with Cashfree if you are not sure about the transfer limits set for your ppi account. | Yes, after adhering to the transfer limits. |
  | 200 | REJECTED | INVALID\_PAYMENT\_INSTRUMENT | The transfer has been rejected because the payment instrument (fundsource\_id parameter in the API request) used for attempting the transfer is invalid. After correcting the payment instrument, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | After correcting the payment instrument, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting payment instrument |
  | 200 | REJECTED | PPI\_INTERNAL\_ERROR | The transfer has been rejected because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | REJECTED | VELOCITY\_CHECK\_FAILED | The transfer has been rejected because the amount entered breaches the limits set for your ppi account. After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). You can connect with Cashfree if you are not sure about the transfer limits set for your ppi account. | After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). You can connect with Cashfree if you are not sure about the transfer limits set for your ppi account. | Yes, after adhering to the transfer limits. |
  | 200 | REJECTED | PPI\_INTERNAL\_ERROR | The transfer has been rejected because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | REJECTED | PPI\_INTERNAL\_ERROR | The transfer has been rejected because there was an intermittent internal error at Cashfree. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | REJECTED | DISABLED\_MODE | The transfer has been rejected because your ppi account does not support this mode of transfer. You should get this mode activated on your payout account by contacting Cashfree, and then initiate a new transfer request. | You should get this mode activated on your ppi account by contacting Cashfree, and then initiate a new transfer request. | Yes, after activating mode. |
  | 200 | REJECTED | BANK\_ACCOUNT\_INVALID | The transfer has been rejected because there is a mismatch in the Bank Account Number of the beneficiary ID and the Bank Account Number in the transfer request. After correcting the Bank Account Number, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | After correcting the Bank Account Number, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting the bank account number. |
  | 200 | REJECTED | BANK\_IFSC\_INVALID | The transfer has been rejected because there is a mismatch in the IFSC of the beneficiary ID and the IFSC in the transfer request. After correcting the IFSC, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | After correcting the IFSC, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting the IFSC |
  | 200 | REJECTED | VPA\_INVALID | The transfer has been rejected because there is a mismatch in the VPA handle of the beneficiary ID and the VPA handle in the transfer request. After correcting the VPA handle, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | After correcting the VPA handle, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting the VPA handle |
  | 200 | REJECTED | PHONE\_INVALID | The transfer has been rejected because there is a mismatch in the Phone Number of the beneficiary ID and the Phone Number in the transfer request. After correcting the Phone Number, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | After correcting the Phone Number, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting the phone number. |
  | 200 | REJECTED | BANK\_ACCOUNT\_DETAILS\_MISSING | The transfer has been rejected because the Bank Account Details are missing in the transfer request. After adding the Bank Account Details, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | After adding the Bank Account Details, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after adding the bank account details. |
  | 200 | REVERSED | ACCOUNT\_BLOCKED | The transfer has been reversed by the beneficiary bank as the end-beneficiary's account is blocked for receiving incoming funds. After correcting the account number or getting the account unblocked, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the account number or getting the account unblocked, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after adding new details or getting account unblocked. |
  | 200 | REVERSED | FAILED | The transfer has been reversed by the beneficiary bank as they were unable to credit the end beneficiary's bank account. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | - | Yes |
  | 200 | REVERSED | NRE\_ACCOUNT\_FAIL | The transfer has been reversed by the beneficiary bank as they were unable to credit the end beneficiary's bank account as it is an NRE Account and transfers to NRE Accounts are not supported. | Get a new account(non-NRE account) from the beneficiary; you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | No |
  | 200 | REVERSED | RETURNED\_FROM\_BENEFICIARY | The transfer has been reversed by the beneficiary bank as they were unable to credit the end beneficiary's bank account. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | REVERSED | BENE\_BANK\_DECLINED | The transfer has been declined by the beneficiary bank and they were unable to credit the end beneficiary's bank account. You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes |
  | 200 | REVERSED | IMPS\_MODE\_FAIL | The transfer has been reversed by the beneficiary bank because the beneficiary bank account does not support IMPS transfers. This rejection is done by the beneficiary bank for the specific beneficiary account. You can try NEFT or other channels to do the disbursals. | You can reinitiate the transfer via Cashfree by changing the mode so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after changing mode. |
  | 200 | REVERSED | DEST\_LIMIT\_REACHED | The transfer has been reversed by the beneficiary bank as the end-beneficiary's account has reached a limit of receiving incoming funds. This rejection is done by the beneficiary bank for the specific beneficiary account. You can reinitiate the transfer after a while via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). The success of the request is contingent on beneficiary's limit being available to receive incoming funds. | The limits on the beneficiary account are typically refreshed every 24 hours. Its not clear when the 24 hour window shall elapse so you can then reinitiate the transfer via Cashfree after some time so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after some time. |
  | 200 | REVERSED | INVALID\_ACCOUNT\_FAIL | The transfer has been reversed by the beneficiary bank because the Account Number of the beneficiary is invalid. After correcting the account number, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | After correcting the account number, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting the account number |
  | 200 | SUCCESS | SENT\_TO\_BENEFICIARY | The transfer has been initiated via the partner bank successfully. The request is waiting to be processed at the beneficiary bank to do the credit to the end beneficiary. | - | - |
  | 200 | SUCCESS | COMPLETED | The transfer has been initiated via the partner bank successfully, hence your account is debited and the request is successfully processed by the beneficiary bank and has been credited to the end beneficiary. | - | - |
  | 200 | REJECTED | TRANSFERID\_INVALID | transferid can contain only alphabets, numbers, underscore (\_), hyphen (-). | After correcting the transferid, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting transfer id. |
  | 200 | REJECTED | AMOUNT\_INVALID | amount can contain only numbers. | After correcting the amount, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting amount. |
  | 200 | REJECTED | REMARKS\_INVALID | remarks can contain only alphabets, numbers and space. | After correcting the remarks, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting remarks. |
  | 200 | REJECTED | BENEID\_INVALID | beneId can contain only alphabets, numbers and underscore. | After correcting the beneid, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting beneficiary id. |
  | 200 | REJECTED | NAME\_INVALID | name can contain only alphabets, numbers and space. | After correcting the name, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting name. |
  | 200 | REJECTED | EMAIL\_INVALID | email is not a valid email format. | After correcting the email, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting email. |
  | 200 | REJECTED | IBAN\_INVALID | iban can contain only alphabet and numbers. | After correcting the iban, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting IBAN. |
  | 200 | REJECTED | TRANSFERMODE\_INVALID | transferMode can contain in one of banktransfer upi paytm amazonpay imps neft rtgs ppc. | After correcting the transfermode, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting mode. |
  | 200 | REJECTED | CURRENCY\_INVALID | currency is invalid. | After correcting the currency, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting currency. |
  | 200 | REJECTED | ACCOUNT\_DOES\_NOT\_EXIST | The transfer has been rejected because the beneficiary account/ VPA does not exist as per our partner bank. | After correcting the account number, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting details. |
  | 200 | FAILED | ACCOUNT\_DOES\_NOT\_EXIST | The transfer has failed because the beneficiary account/ VPA does not exist as per our partner bank. | After correcting the account number, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting details. |
  | 200 | REJECTED | AMAZON\_AMOUNT\_EXCEED | The transfer has been rejected because the amount entered breaches the limits set for the beneficiaries amazon account. | After verifying the limits for beneficiaries amazon account, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after verifying limits. |
  | 200 | FAILED | AMAZON\_AMOUNT\_EXCEED | The transfer has failed because the amount entered breaches the limits set for the beneficiaries amazon account. | After verifying the limits for beneficiaries amazon account, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after verifying limits. |
  | 200 | REJECTED | ANOMALY\_DETECTION | The transfer has been rejected as Cashfree risk product has detected an anomaly. | You can reinitiate the transfer request after validation at your end. | Yes, after validation. |
  | 200 | APPROVAL\_PENDING | ANOMALY\_DETECTION | The transfer requires approval as Cashfree risk product has detected an anomaly. | You can approve/reject the transfer on the merchant dashboard. Post the transfer is approved, the request is sent to the partner bank for further processing. | - |
  | 200 | FAILED | BAD\_CONNECTION | The transfer has failed because there was an intermittent internal error between Cashfree and the partner bank. | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after some time. |
  | 200 | REJECTED | BENE\_INVALID | The transfer has been rejected because the beneficiary added in the transfer request does not exist. | After adding the right beneficiary, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after adding beneficiary. |
  | 200 | FAILED | BENE\_INVALID | The transfer has failed because the beneficiary added in the transfer request does not exist. | After adding the right beneficiary, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after adding beneficiary. |
  | 200 | FAILED | BENE\_NOT\_REGISTERED | The transfer has been rejected because the beneficiary added in the transfer request is not registered with the partner bank. | After adding the right beneficiary, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after adding beneficiary. |
  | 200 | VALIDATION\_PENDING | BENE\_VERIFICATION\_PENDING | The transfer is pending because the beneficiary verification is pending. Once the beneficiary is validated we will attempt the transfers with partner bank(s). | - | - |
  | 200 | FAILED | BENEFICIARY\_BANK\_UNAVAILABLE | The transfer has failed because the respective beneficiary bank is offline. | After some time, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after some time. |
  | 200 | FAILED | BENEFICIARY\_NAME\_DIFFERS | The transfer has failed because the beneficiary name differs as per Cashfree's partner bank. | After adding the right beneficiary, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting name. |
  | 200 | REJECTED | BENEFICIARY\_NAME\_DIFFERS | The transfer has been rejected because the beneficiary name differs as per Cashfree's partner bank. | After adding the right beneficiary, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting name. |
  | 200 | REJECTED | BENEFICIARY\_NAME\_MISMATCH | The transfer has been rejected because the beneficiary name differs as per Cashfree's partner bank. | After adding the right beneficiary, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting name. |
  | 200 | REJECTED | CARD\_UNSUPPORTED | The transfer has been rejected because the card is not supported. | After changing the payment instrument details, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after changing instrument. |
  | 200 | FAILED | CARD\_UNSUPPORTED | The transfer has failed because the card is not supported. | After changing the payment instrument details, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after changing instrument. |
  | 200 | FAILED | DUPLICATE\_FAILED | The transfer has failed as the bank claims of receiving a duplicate request at their end as of now. | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, with new id. |
  | 200 | FAILED | ERROR\_RETRIEVING\_BALANCE | The transfer has failed because there was an intermittent issue at the partner bank's end. | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after some time. |
  | 200 | REJECTED | INVALID\_CARD | The transfer has been rejected because the card details are not correct. | After changing the payment instrument details, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting card. |
  | 200 | FAILED | INVALID\_CARD | The transfer has failed because the card details are not correct. | After changing the payment instrument details, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting card. |
  | 200 | REJECTED | INVALID\_CURRENCY\_FOR\_PYID | The transfer has been rejected because the transfer currency passed in the transfer request is not supported by Cashfree. | After changing the currency to INR, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after changing currency. |
  | 200 | FAILED | INVALID\_CURRENCY\_FOR\_PYID | The transfer has been rejected because the transfer currency passed in the transfer request is not supported by Cashfree. | After changing the currency to INR, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after changing currency. |
  | 200 | FAILED | INVALID\_MODE\_FAIL | The transfer has failed because the requested transfer mode is not supported for this beneficiary account as per the partner bank. | After changing the transfer mode, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after changing mode. |
  | 200 | REJECTED | INVALID\_OR\_NO\_SUCH\_ACCOUNT\_TYPE | The transfer has been rejected because the beneficiary account type is invalid or not supported as per our partner bank. | Get a new account from the beneficiary; you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after new account. |
  | 200 | FAILED | INVALID\_OR\_NO\_SUCH\_ACCOUNT\_TYPE | The transfer has failed because the beneficiary account type is invalid or not supported as per our partner bank. | Get a new account from the beneficiary; you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after new account. |
  | 200 | FAILED | INVALID\_PHONE\_BENEFICIARY | The transfer has failed because the beneficiary's phone number is not linked to any VPA. | After adding the right phone beneficiary, You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correcting phone. |
  | 200 | REJECTED | INVALID\_TRANSFER\_CURRENCY | The transfer has been rejected because the transfer currency passed in the transfer request is not supported by Cashfree. | After changing the currency to INR, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after changing currency. |
  | 200 | FAILED | INVALID\_TRANSFER\_CURRENCY | The transfer has failed because the transfer currency passed in the transfer request is not supported by Cashfree. | After changing the currency to INR, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after changing currency. |
  | 200 | REJECTED | KYC\_COMPLIANCE\_VERIFICATION\_FAILED | The transfer has failed because the KYC verification has failed. | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after KYC resolution. |
  | 200 | REJECTED | KYC\_REQUIREMENTS\_NOT\_SATISFIED | The transfer has failed because the KYC requirements have not been satisfied. | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after completing KYC. |
  | 200 | FAILED | LOAD\_LIMIT\_EXHAUSTED | The transfer has failed because the beneficiaries account has reached maximum transaction amount limit. | After 24 hours, You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after 24 hours. |
  | 200 | FAILED | LOAN\_FUND\_MOVEMENT\_FAILURE | The transfer has failed because of an intermittent issue at Cashfree's end. | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after some time. |
  | 200 | PENDING | LOW\_BALANCE\_QUEUED | The transfer is pending because the balance in the fund source is exhausted. This transfer will be processed after you recharge the fund source, you need not reinitiate this transfer. | This transfer will be processed after you recharge the fund source, you need not reinitiate this transfer. Please rely on check status API or webhook for checking the status of this transfer. | - |
  | 200 | REJECTED | MANUALLY\_REJECTED | The transfer has been manually rejected by you. | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree. | Yes, if needed. |
  | 200 | REJECTED | PPI\_INACTIVE | The transfer has been rejected because your ppi account has been inactive. | After getting the account activated, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after activation. |
  | 200 | PENDING | PENDING | The transfer is currently in a Pending state, as Cashfree is awaiting a final confirmation from the partner bank for a terminal status. | Rely on Check Status API or Webhooks | - |
  | 200 | FAILED | POOL\_CONNECTION\_TIMEOUT | The transfer has failed because there was a connection issue with the partner bank's end. | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after some time. |
  | 200 | REJECTED | QUICK\_TRANSFER\_DISABLED | The transfer has been rejected because quick transfer is disabled for your ppi account. | After getting quick transfer enabled, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after enabling. |
  | 200 | REJECTED | REJECTED | Transfer rejected. | - | Yes, after correction. |
  | 200 | REVERSED | REVERSED | The transfer has been reversed by the beneficiary bank as the credit to end-beneficiary's account has failed. | You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, after correction. |
  | 200 | FAILED | RTGS\_MODE\_FAIL | The transfer has failed because the beneficiary account does not support RTGS transfers. | You can try NEFT or other channels to do the disbursals. | Yes, via different mode. |
  | 200 | FAILED | SUSPECTED\_FAILED | The transfer has failed, as the partner bank suspects that the transfer is of fraudulent nature. | - | No (investigate). |
  | 200 | REJECTED | VBA\_TRANSFER\_DISABLED | The transfer has been rejected because transfers to virtual bank accounts are not enabled for your Cashfree Account. | After getting payouts to virtual bank accounts enabled, you can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). You can connect with Cashfree for enabling payouts to virtual bank accounts. | Yes, after enabling. |
  | 200 | REJECTED | ERROR\_SELECTING\_FUND\_SOURCE | The transfer has been rejected because their is some issue with your account configuration. | You can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after fixing config. |
  | 200 | VALIDATION\_PENDING | VALIDATION\_PENDING | The transfer is pending because the beneficiary verification is pending. Once the beneficiary is validated we will attempt the transfers with partner bank(s). | Rely on Check Status API or Webhooks | - |
  | 200 | REJECTED | INVALID\_BENEFICIARY\_CODE | The transfer has been rejected because the bene code is Invalid. | After correcting the beneficiary code, you can reinitiate the transfer via Cashfree so that the transfer can be attempted by Cashfree with the partner bank(s). | Yes, after correcting code. |
  | 200 | REJECTED | DUPLICATE\_TRANSFER | The transfer is already present in the file or has been processed previously. Please change the transferId in the api request. | After changing the Transfer Id, You can reinitiate the transfer via Cashfree so that the transfer can be reattempted again by Cashfree with the partner bank(s). | Yes, with new transfer id. |

  #### 4XX errors

  | HTTP status code | Error code | Message | Next action |
  | :- | :- | :- | :- |
  | 400 | transfer\_id\_missing | transfer\_id parameter missing in the request | Enter a valid transfer\_id in the request. |
  | 400 | transfer\_id\_invalid | transfer\_id value invalid | Enter a valid transfer\_id in the request. |
  | 400 | user\_id\_missing | user\_id parameter is missing | Provide a valid user\_id in the request. |
  | 400 | user\_id\_value\_invalid | user\_id invalid value | Enter a valid user\_id in the request. |
  | 400 | wallet\_id\_missing | wallet\_id parameter is missing | Provide a valid wallet\_id in the request. |
  | 400 | wallet\_id\_value\_invalid | wallet\_id invalid value | Enter a valid wallet\_id in the request. |
  | 400 | cf\_sub\_wallet\_id\_missing | cf\_sub\_wallet\_id parameter is missing | Provide a valid cf\_sub\_wallet\_id in the request. |
  | 400 | cf\_sub\_wallet\_id\_value\_invalid | cf\_sub\_wallet\_id invalid value | Enter a valid cf\_sub\_wallet\_id in the request. |
  | 400 | amount\_missing | amount parameter is missing | Provide a value for the amount parameter in the request. |
  | 400 | amount\_value\_invalid | amount invalid value | Enter an amount up to 2 decimal place and greater than 1.00. |
  | 400 | transfer\_mode\_missing | transfer\_mode parameter is missing | Provide a valid transfer\_mode in the request. |
  | 400 | transfer\_mode\_invalid | transfer\_mode is invalid allowed values are : bank, imps, neft, rtgs, upi | Provide a valid transfer\_mode in the request. |
  | 400 | bene\_details\_missing | bene\_details parameter is missing | Provide beneficiary details in the request. |
  | 400 | bene\_details.bene\_id\_invalid | beneficiary\_id should be alphanumeric | Enter a valid beneficiary\_id. |
  | 400 | bene\_details.instrument\_details.bank\_account\_number\_invalid | bank\_account\_number should be alphanumeric | Enter a valid bank\_account\_number. |
  | 400 | bene\_details.instrument\_details.bank\_account\_number\_invalid | Bank account number passed in the request does not match with the beneficiary with beneficiary\_id :: test\_beneId | Enter the correct bank\_account\_number associated with the beneficiary\_id. |
  | 400 | bene\_details.instrument\_details.bank\_ifsc\_invalid | bank\_ifsc should be in standard ifsc format | Enter a valid bank\_ifsc. |
  | 400 | bene\_details.instrument\_details.bank\_ifsc\_invalid | Bank ifsc passed in the request does not match with the beneficiary with beneficiary\_id :: test\_beneId | Enter the correct bank\_ifsc associated with the beneficiary\_id. |
  | 400 | bene\_details.instrument\_details.full\_name\_invalid | full name value invalid | Enter a valid full name for the beneficiary. |
  | 400 | bene\_details.instrument\_details.vpa\_invalid | vpa is in invalid format | Enter a valid VPA. |
  | 400 | bene\_details.instrument\_details.vpa\_invalid | Vpa passed in the request does not match with the beneficiary with beneficiary\_id :: test\_beneId | Enter the correct vpa associated with the beneficiary\_id. |
  | 404 | user\_id\_not\_found | The specified user\_id does not exist | Enter a valid user\_id. |
  | 404 | wallet\_not\_found | No ACTIVE wallet found with the provided wallet\_id | Enter a valid wallet\_id. |
  | 404 | sub\_wallet\_not\_found | No ACTIVE sub-wallet found with the provided cf\_sub\_wallet\_id | Enter a valid cf\_sub\_wallet\_id. |
  | 409 | duplicate\_transfer\_id | A transfer with the provided transfer\_id already exists | Use a unique transfer\_id for the request. |
  | 422 | transfer\_limit\_exceeded | Transfer amount exceeds the daily/monthly limit | Reduce the transfer amount or wait for limit reset. |
  | 422 | full\_kyc\_required | FULL KYC verification is required for fund transfer | Complete FULL KYC verification before attempting the transfer. |

  <br />
</Accordion>


# Verify Transfer
Source: https://www.cashfree.com/docs/api-reference/prepaid-payment-instruments/transfers/verify-transfer

openapi/ppi/ppi.yaml post /ppi/wallet/transfer/verify
Submits the OTP for a wallet transfer that was initiated with mode `OTP_VERIFICATION`. 
Use **Get Transfer Details** or webhooks for terminal status.


<Note>
  Call this API after [Initiate Transfer](/docs/api-reference/prepaid-payment-instruments/transfers/initiate-transfer). Use [Get Transfer Details](/docs/api-reference/prepaid-payment-instruments/transfers/get-transfer-details) to proceed with bank processing after OTP succeeds.
</Note>

You can submit an OTP for verification **at most three times** per transfer.


# Transfer Webhook Events
Source: https://www.cashfree.com/docs/api-reference/prepaid-payment-instruments/transfers/webhook-transfer

Configure Transfer webhooks to receive event-based notifications whenever a wallet transfer changes status in your PPI integration.

Webhooks are event-based notifications that you receive when a specific event related to a wallet transfer occurs.

<Warning>
  In rare cases, such as network retries, read timeouts, processing delays, or delivery failures, Cashfree may send the same webhook more than once for the same event. To prevent unintended side effects, implement idempotency (ensuring a duplicate webhook produces the same result as processing it once) in your webhook handler to handle duplicate deliveries.
</Warning>

## Webhook signature

Cashfree includes the webhook signature in the request header. The following is a sample header from a webhook request.

| Header name | Header value |
| - | :-: |
| content-length | 1099 |
| x-webhook-attempt | 1 |
| content-type | application/json |
| x-webhook-signature | 07r5C3VMwsGYeldGOCYxe5zoHhIN1zLfa8O0U/yngHI= |
| x-webhook-timestamp | 1746427759733 |
| x-webhook-version | 2025-01-01 |

<Tip>
  Always capture the webhook payload in its raw text format before parsing into JSON. Parsing and re-serialising the payload can change the structure (for example, array ordering, spacing, or `null` handling) and cause a signature mismatch during verification. Use the exact raw body string from the request when computing the signature.
</Tip>

<Note>
  Verifying the signature is mandatory before processing any webhook. Refer to [Signature Verification](/docs/api-reference/prepaid-payment-instruments/webhook-signature-verification) for more details.
</Note>

## Transfer webhook events

Cashfree triggers the following events at different stages of a wallet transfer:

| Event | Description |
| :- | :- |
| PPI\_TRANSFER\_SUCCESS | The transfer is successfully credited to the beneficiary's account. |
| PPI\_TRANSFER\_FAILED | The transfer cannot be processed due to an error or rejection by the bank. |
| PPI\_TRANSFER\_REVERSED | The beneficiary bank returns the transfer after initial processing. |
| PPI\_TRANSFER\_REJECTED | Cashfree rejects the transfer before it reaches the bank due to a validation failure. |

The following examples show the webhook payload for each event type.

<AccordionGroup>
  <Accordion title="PPI_TRANSFER_SUCCESS">
    ```json theme={"dark"}
    {
      "event_type": "PPI_TRANSFER_SUCCESS",
      "event_time": "2026-05-18T10:00:45Z",
      "data": {
        "user_id": "usr_001",
        "wallet_id": "wlt_001",
        "cf_transfer_id": "1003",
        "transfer_id": "txn_ext_003",
        "amount": 500.00,
        "transfer_mode": "IMPS",
        "actual_mode": "IMPS",
        "sub_wallet": {
          "cf_sub_wallet_id": "swlt_001",
          "name": "Primary Wallet",
          "type": "PRIMARY",
          "status": "ACTIVE",
          "balance": 4500.00,
          "available_balance": 4500.00,
          "funds_on_hold": 0.00
        },
        "status": "SUCCESS",
        "status_code": "ACKNOWLEDGED_VIA_BENE_BANK",
        "bank_reference_number": "BNKREF789012",
        "bene_details": {
          "bene_id": "bene_001",
          "bene_instrument_id": "instr_001"
        },
        "purpose": "salary",
        "remarks": "Monthly salary",
        "initiated_at": "2026-05-18T10:00:00Z",
        "processed_at": "2026-05-18T10:00:45Z",
        "notes": null
      }
    }
    ```
  </Accordion>

  <Accordion title="PPI_TRANSFER_FAILED">
    ```json theme={"dark"}
    {
      "event_type": "PPI_TRANSFER_FAILED",
      "event_time": "2026-05-18T10:00:01Z",
      "data": {
        "user_id": "usr_001",
        "wallet_id": "wlt_001",
        "cf_transfer_id": "1004",
        "transfer_id": "txn_ext_004",
        "amount": 500.00,
        "transfer_mode": "IMPS",
        "actual_mode": null,
        "sub_wallet": {
          "cf_sub_wallet_id": "swlt_001",
          "name": "Primary Wallet",
          "type": "PRIMARY",
          "status": "ACTIVE",
          "balance": 5000.00,
          "available_balance": 5000.00,
          "funds_on_hold": 0.00
        },
        "status": "FAILED",
        "status_code": "INSUFFICIENT_BALANCE",
        "bank_reference_number": null,
        "bene_details": {
          "bene_id": "bene_001",
          "bene_instrument_id": "instr_001"
        },
        "purpose": "salary",
        "remarks": "Monthly salary",
        "initiated_at": "2026-05-18T10:00:00Z",
        "processed_at": "2026-05-18T10:00:01Z",
        "notes": null
      }
    }
    ```
  </Accordion>

  <Accordion title="PPI_TRANSFER_REVERSED">
    ```json theme={"dark"}
    {
      "event_type": "PPI_TRANSFER_REVERSED",
      "event_time": "2026-05-18T10:05:00Z",
      "data": {
        "user_id": "usr_001",
        "wallet_id": "wlt_001",
        "cf_transfer_id": "1005",
        "transfer_id": "txn_ext_005",
        "amount": 500.00,
        "transfer_mode": "IMPS",
        "actual_mode": "IMPS",
        "sub_wallet": {
          "cf_sub_wallet_id": "swlt_001",
          "name": "Primary Wallet",
          "type": "PRIMARY",
          "status": "ACTIVE",
          "balance": 5000.00,
          "available_balance": 5000.00,
          "funds_on_hold": 0.00
        },
        "status": "REVERSED",
        "status_code": "RETURNED_FROM_BENE",
        "bank_reference_number": "BNKREF_REV001",
        "bene_details": {
          "bene_id": "bene_001",
          "bene_instrument_id": "instr_001"
        },
        "purpose": "salary",
        "remarks": "Monthly salary",
        "initiated_at": "2026-05-18T10:00:00Z",
        "processed_at": "2026-05-18T10:05:00Z",
        "notes": null
      }
    }
    ```
  </Accordion>

  <Accordion title="PPI_TRANSFER_REJECTED">
    ```json theme={"dark"}
    {
      "event_type": "PPI_TRANSFER_REJECTED",
      "event_time": "2026-05-18T10:00:01Z",
      "data": {
        "user_id": "usr_001",
        "wallet_id": "wlt_001",
        "cf_transfer_id": "1006",
        "transfer_id": "txn_ext_006",
        "amount": 500.00,
        "transfer_mode": "IMPS",
        "actual_mode": null,
        "sub_wallet": {
          "cf_sub_wallet_id": "swlt_001",
          "name": "Primary Wallet",
          "type": "PRIMARY",
          "status": "ACTIVE",
          "balance": 5000.00,
          "available_balance": 5000.00,
          "funds_on_hold": 0.00
        },
        "status": "REJECTED",
        "status_code": "BENE_BLACKLISTED",
        "bank_reference_number": null,
        "bene_details": {
          "bene_id": "bene_001",
          "bene_instrument_id": "instr_001"
        },
        "purpose": "salary",
        "remarks": "Monthly salary",
        "initiated_at": "2026-05-18T10:00:00Z",
        "processed_at": "2026-05-18T10:00:01Z",
        "notes": null
      }
    }
    ```
  </Accordion>
</AccordionGroup>

## Transfer webhook payload fields

The webhook payload contains important metadata in its top-level fields.

| Field | Type | Description |
| - | - | - |
| `event_type` | `string` | Type of transfer event: `PPI_TRANSFER_SUCCESS`, `PPI_TRANSFER_FAILED`, `PPI_TRANSFER_REVERSED`, or `PPI_TRANSFER_REJECTED` |
| `event_time` | `string` | The UTC timestamp when the event occurred, in ISO 8601 format |
| `data` | `object` | Transfer-specific event details |

## Transfer data fields

Transfer webhook events contain the following fields inside `data`:

| Field | Type | Description |
| - | - | - |
| `user_id` | `string` | Identifier of the user who initiated the transfer |
| `wallet_id` | `string` | Identifier of the wallet from which the transfer was made |
| `transfer_id` | `string` | Your unique identifier for the transfer transaction |
| `cf_transfer_id` | `string` | Cashfree's unique identifier for the transfer transaction |
| `amount` | `number` | Transfer amount in INR |
| `transfer_mode` | `string` | Transfer mode requested: `RTGS`, `NEFT`, `IMPS`, or `UPI` |
| `actual_mode` | `string` | Transfer mode actually used to process the transaction. Set only when the transfer reaches the bank (`SUCCESS` or `REVERSED`); `null` otherwise |
| `sub_wallet` | `object` | Details of the sub-wallet from which funds were transferred |
| `sub_wallet.cf_sub_wallet_id` | `string` | Cashfree's unique identifier for the sub-wallet |
| `sub_wallet.name` | `string` | Name of the sub-wallet |
| `sub_wallet.type` | `string` | Type of the sub-wallet (for example, `PRIMARY`, `FULL_KYC_PPI`, `GIFT_PPI`) |
| `sub_wallet.status` | `string` | Current status of the sub-wallet (for example, `ACTIVE`, `SUSPENDED`) |
| `sub_wallet.balance` | `number` | Total balance in the sub-wallet in INR |
| `sub_wallet.available_balance` | `number` | Balance available for new transfers after accounting for funds on hold, in INR |
| `sub_wallet.funds_on_hold` | `number` | Amount reserved for in-flight transfers not yet settled, in INR |
| `status` | `string` | Current status of the transfer: `SUCCESS`, `FAILED`, `REVERSED`, or `REJECTED` |
| `status_code` | `string` | Granular status code for the transfer (for example, `ACKNOWLEDGED_VIA_BENE_BANK`, `INSUFFICIENT_BALANCE`, `RETURNED_FROM_BENE`, `BENE_BLACKLISTED`) |
| `bank_reference_number` | `string` | Bank reference number for the transaction. Set only when the transfer reaches the bank (`SUCCESS` or `REVERSED`); `null` otherwise |
| `bene_details` | `object` | Beneficiary details for the transfer |
| `bene_details.bene_id` | `string` | Your unique identifier for the beneficiary |
| `bene_details.bene_instrument_id` | `string` | Your unique identifier for the beneficiary instrument |
| `purpose` | `string` | Purpose of the transfer |
| `remarks` | `string` | Additional remarks for the transfer |
| `notes` | `object \| null` | Custom key-value pairs provided during transfer creation. Returns `null` if no notes were set. |
| `initiated_at` | `string` | Timestamp when the transfer was initiated |
| `processed_at` | `string` | Timestamp when the transfer reached a terminal state |


# Create Beneficiary
Source: https://www.cashfree.com/docs/api-reference/prepaid-payment-instruments/user-beneficiary/create-user-bene

openapi/ppi/ppi.yaml post /ppi/user/bene
Creates a new beneficiary to user's Full KYC wallet by providing bank account number or VPA and other required details. Ensure the successful creation of the beneficiary before initiating a fund transfer.




# Get Beneficiary Details
Source: https://www.cashfree.com/docs/api-reference/prepaid-payment-instruments/user-beneficiary/get-user-bene

openapi/ppi/ppi.yaml post /ppi/user/bene/details
Retrieves details of an existing beneficiary of user in the PPI system.
- If `bene_instrument_id` is provided, the response includes details for the specified instrument only.
- If `bene_instrument_id` is not provided, the response includes details for all `bene_instruments` linked to the given `bene_id`.




# Remove Beneficiary
Source: https://www.cashfree.com/docs/api-reference/prepaid-payment-instruments/user-beneficiary/remove-user-bene

openapi/ppi/ppi.yaml delete /ppi/user/bene/remove
Removes an existing beneficiary of the user in the PPI system.
- If `bene_instrument_id` is provided, only the specified instrument is removed from the beneficiary.
- If `bene_instrument_id` is not provided, the entire beneficiary along with all its `bene_instruments` is removed.




# Create User
Source: https://www.cashfree.com/docs/api-reference/prepaid-payment-instruments/user-management/create-ppi-user

openapi/ppi/ppi.yaml post /ppi/user
Creates a new user in the PPI system with the provided personal information. This endpoint enables merchants 
to onboard new users who can then be associated with wallets or cards.




# Get User Details
Source: https://www.cashfree.com/docs/api-reference/prepaid-payment-instruments/user-management/get-ppi-user-details

openapi/ppi/ppi.yaml post /ppi/user/details
Retrieves details of an existing user in the PPI system based on the provided user ID.
Returns the user's personal information and account status.




# Update User
Source: https://www.cashfree.com/docs/api-reference/prepaid-payment-instruments/user-management/update-ppi-user

openapi/ppi/ppi.yaml post /ppi/user/update
Updates user details in the PPI system. Only the fields provided in the request body will be updated; 
all other user fields remain unchanged.




# Check Transaction Eligibility
Source: https://www.cashfree.com/docs/api-reference/prepaid-payment-instruments/wallet-management/check-wallet-eligibility

openapi/ppi/ppi.yaml post /ppi/wallet/eligibility
Validates a user’s eligibility to perform credit or debit transactions on a sub-wallet based on compliance rules.




# Close Wallet
Source: https://www.cashfree.com/docs/api-reference/prepaid-payment-instruments/wallet-management/close-wallet

openapi/ppi/ppi.yaml post /ppi/wallet/closure
Closes a user's sub-wallet, making it inactive for future transactions. The closure process may require approval 
depending on the sub-wallet type and business rules:
- Any remaining balance is handled according to the configured closure policy.


<AccordionGroup>
  <Accordion title="Closure Status Descriptions">
    The following table outlines the possible status values returned in the closure response:

    | **Status** | **Description** |
    | - | - |
    | `SUCCESS` | The wallet closure has been processed successfully and the sub-wallet is now inactive. All remaining balance has been handled according to the closure policy. |
    | `PENDING` | The closure request has been accepted and is currently being processed. |
    | `APPROVAL_PENDING` | The closure request requires manual approval. |
  </Accordion>
</AccordionGroup>


# Create Wallet
Source: https://www.cashfree.com/docs/api-reference/prepaid-payment-instruments/wallet-management/create-wallet

openapi/ppi/ppi.yaml post /ppi/wallet
Creates a primary wallet and the associated sub-wallets for a user based on the specified program ID. The sub-wallet types, such as meal, fuel, and gift wallets, are determined by the program configuration. If the program is linked to a card program, a card is automatically created and associated with the wallet.


<Accordion title="Request parameters">
  The following parameters are required to create a wallet.

  | Parameter | Required | Description |
  | - | - | - |
  | `user_id` | Always | The unique identifier of the user. |
  | `wallet_id` | Always | The unique identifier of the wallet. |
  | `cf_program_id` | Always | The unique identifier of the program. |
  | `card_id` | Conditionally | Required if `cf_program_id` is associated with a card program. |

  <Note>
    If `cf_program_id` is linked to a card program, you must provide `card_id` in the request. The card is associated with the wallet at the time of wallet creation.
  </Note>
</Accordion>


# Credit Wallet
Source: https://www.cashfree.com/docs/api-reference/prepaid-payment-instruments/wallet-management/credit-wallet

openapi/ppi/ppi.yaml post /ppi/wallet/credit
Credits funds to a specified user sub-wallet, adding money to their available balance. Supports various sub-wallet types with behaviour determined by wallet configuration.




# Debit Status and Status-Code Mapping
Source: https://www.cashfree.com/docs/api-reference/prepaid-payment-instruments/wallet-management/debit-status-descriptions

Understand debit status and status_code combinations returned by PPI Debit Wallet and Verify Debit Wallet APIs, with recommended actions for each scenario.

Use this reference to understand the `status` and `status_code` values returned by the [Debit Wallet API](/docs/api-reference/prepaid-payment-instruments/wallet-management/debit-wallet) and [Verify Debit Wallet API](/docs/api-reference/prepaid-payment-instruments/wallet-management/verify-debit-wallet), and configure your debit flow accordingly.

<span />

## Status and status-code reference

The following table describes all possible `status` and `status_code` combinations returned by debit APIs, along with recommended actions for each scenario.

### Debit transaction statuses

Statuses are organised by transaction state. Each state contains specific status codes that indicate the current progress and required actions.

<Accordion title="PENDING - Debit in progress">
  | Status code | Description | Recommended action |
  | - | - | - |
  | `PENDING` | Cashfree received the debit request and is processing it. | Wait for a terminal status or poll using the debit response |
  | `OTP_GENERATED` | Cashfree sent an OTP to the user for debit authorisation. | Call the [Verify Debit Wallet API](/docs/api-reference/prepaid-payment-instruments/wallet-management/verify-debit-wallet) with the `debit_id` and OTP |
  | `LAST_OTP_ATTEMPT_FAILED` | The OTP verification attempt failed, but retries remain. | Prompt the user to re-enter the OTP and call the [Verify Debit Wallet API](/docs/api-reference/prepaid-payment-instruments/wallet-management/verify-debit-wallet) again |
</Accordion>

<Accordion title="SUCCESS - Debit completed">
  | Status code | Description | Recommended action |
  | - | - | - |
  | `SUCCESS` | The debit completed successfully. | Proceed with order fulfilment or downstream processing |
</Accordion>

<Accordion title="FAILED - Debit failed">
  | Status code | Description | Recommended action |
  | - | - | - |
  | `OTP_GENERATION_FAILED` | Cashfree could not generate the OTP for the debit. | Retry the debit or verify notification channel configuration |
  | `OTP_VERIFICATION_FAILED` | The OTP verification failed. | Initiate a new debit if required |
  | `OTP_EXPIRED` | The OTP has expired. | Initiate a new debit |
  | `OTP_VERIFICATION_ATTEMPT_EXHAUSTED` | The maximum OTP verification attempts were exceeded. | Initiate a new debit |
  | `FAILED` | The debit failed. | Review the failure reason and retry if applicable |
</Accordion>

<Accordion title="REJECTED - Debit rejected">
  | Status code | Description | Recommended action |
  | - | - | - |
  | `REJECTED` | Cashfree rejected the debit. | Review the rejection reason before retrying |
  | `INSUFFICIENT_BALANCE` | The sub-wallet does not have sufficient balance for the debit. | Ask the user to top up the wallet or reduce the debit amount |
</Accordion>

<Accordion title="REVERSED - Debit reversed">
  | Status code | Description | Recommended action |
  | - | - | - |
  | `REVERSED` | Cashfree reversed the debit. | Update order or balance records accordingly |
</Accordion>


# Debit Wallet
Source: https://www.cashfree.com/docs/api-reference/prepaid-payment-instruments/wallet-management/debit-wallet

openapi/ppi/ppi.yaml post /ppi/wallet/debit
Debits funds from a user's sub-wallet for purchases. The behaviour varies based on the sub-wallet type:

- `GIFT_PPI`: Identifies the applicable gift card and debits the amount transactionally from both the gift card and the gift wallet. This debit completes in a single step and does not require OTP verification.

- `CLOSED_LOOP_PPI`: Performs ledger maintenance only. No actual money movement occurs.

- `SMALL_PPI` and `FULL_KYC_PPI`: The debit uses a two-step flow that requires OTP verification.
  1. In your request, include the `auth` object with `mode` set to `OTP_VERIFICATION` and specify at least one channel in `auth.data.notification_modes`.
  2. Cashfree records the request, generates an OTP, and returns a response with `status: PENDING` and `status_code: OTP_GENERATED`.
  3. Call the [Verify Debit Wallet](/api-reference/prepaid-payment-instruments/wallet-management/verify-debit-wallet) API with the `debit_id` and OTP to complete the debit. On successful verification, the status moves to `SUCCESS`.


<Note>
  For `SMALL_PPI` and `FULL_KYC_PPI` sub-wallets, the `auth` object with `mode: OTP_VERIFICATION` is required to initiate a debit. To complete the transaction, call the [Verify Wallet Debit API](/docs/api-reference/prepaid-payment-instruments/wallet-management/verify-debit-wallet) when the response returns `status_code: OTP_GENERATED`. This two-step flow does not apply to `GIFT_PPI` or `CLOSED_LOOP_PPI` sub-wallets.
</Note>

Refer to [Status and status-code reference](/docs/api-reference/prepaid-payment-instruments/wallet-management/debit-status-descriptions#status-statuscode-mapping) for a comprehensive list of `status` and `status_code` combinations.


# Get Wallet Details
Source: https://www.cashfree.com/docs/api-reference/prepaid-payment-instruments/wallet-management/get-wallet-details

openapi/ppi/ppi.yaml post /ppi/wallet/details
Use this API to fetch wallet details and associated sub-wallet balances for a specified user. You can query by wallet ID, card ID, or a combination of either with a sub-wallet ID.


<AccordionGroup>
  <Accordion title="Request parameters">
    `user_id` is always required. You must also provide one of the following identifier combinations.

    | Combination | Required parameters |
    | - | - |
    | By wallet | `user_id`, `wallet_id` |
    | By card | `user_id`, `card_id` |
    | By wallet and sub-wallet | `user_id`, `wallet_id`, `cf_sub_wallet_id` |
    | By card and sub-wallet | `user_id`, `card_id`, `cf_sub_wallet_id` |
  </Accordion>

  <Accordion title="Response behaviour">
    The response always includes wallet details and sub-wallet details. The following rules determine what additional data is returned based on the identifiers you provide.

    * If you provide `wallet_id` and the wallet has no associated card, the response returns wallet and sub-wallet details only.
    * If you provide `wallet_id` and the wallet has an associated card, the response also includes card details.
    * If you provide `card_id`, the response includes card details alongside wallet and sub-wallet details.
    * If you provide both `wallet_id` and `cf_sub_wallet_id`, the response returns details for the specified sub-wallet only.
    * If you provide both `card_id` and `cf_sub_wallet_id`, the response returns details for the specified sub-wallet along with wallet and card details.
  </Accordion>
</AccordionGroup>


# Get Wallet Statement
Source: https://www.cashfree.com/docs/api-reference/prepaid-payment-instruments/wallet-management/get-wallet-statement

openapi/ppi/ppi.yaml post /ppi/wallet/statement
Retrieves a paginated wallet statement for a user, including both credit and debit transactions for a specific sub-wallet.
- The statement can be fetched for a specified date range. If no range is provided, the API returns transactions from the last 6 months.
- The `from` date **cannot** be earlier than 1 year from the current date.
- Pagination is handled using the `after` and `before` parameters, which define the `cf_statement_id` boundary for retrieving the next or previous set of records.
- Only **one** of `after` or `before` can be passed at a time.




# Refund Debit Wallet
Source: https://www.cashfree.com/docs/api-reference/prepaid-payment-instruments/wallet-management/refund-wallet

openapi/ppi/ppi.yaml post /ppi/wallet/refund
Processes a refund for a previously debited transaction from a user's sub-wallet. The refund operation 
credits the amount back to the user's sub-wallet, effectively reversing a debit transaction:
- `GIFT_PPI`: Credits amount back to gift wallet.
- `CLOSED_LOOP_PPI` and `SMALL_PPI`: Credits amount back to the respective sub-wallet.
- Refund amount cannot exceed the original debit amount.


<AccordionGroup>
  <Accordion title="Refund Status Descriptions">
    The following table outlines the possible status values returned in the refund response:

    | **Status** | **Description** |
    | - | - |
    | `SUCCESS` | The refund has been processed successfully and the amount has been credited back to the user's sub-wallet. The transaction is complete. |
    | `PENDING` | The refund request has been accepted and is currently being processed. The amount will be credited to the wallet shortly. Check the status later or wait for webhook notification. |
  </Accordion>
</AccordionGroup>


# Verify Debit Wallet
Source: https://www.cashfree.com/docs/api-reference/prepaid-payment-instruments/wallet-management/verify-debit-wallet

openapi/ppi/ppi.yaml post /ppi/wallet/debit/verify
Completes a debit transaction that requires OTP verification for SMALL_PPI or FULL_KYC_PPI sub-wallets. Use this endpoint after the [Debit Wallet API](/api-reference/prepaid-payment-instruments/wallet-management/debit-wallet) returns status_code: OTP_GENERATED. Pass the debit_id from that response along with the OTP received by the customer through the channels configured in auth.data.notification_modes. On successful verification, the API returns status: SUCCESS and status_code: SUCCESS, and the debit transaction is completed. Each debit_id supports a maximum of three OTP verification attempts.


<Note>
  Use this API to complete a debit transaction that requires OTP verification. Call this API after the [Debit Wallet API](/docs/api-reference/prepaid-payment-instruments/wallet-management/debit-wallet) returns `status_code: OTP_GENERATED` for `SMALL_PPI` or `FULL_KYC_PPI` sub-wallets. The request accepts two fields: `debit_id` and `otp`.
</Note>

Refer to [Status and status-code reference](/docs/api-reference/prepaid-payment-instruments/wallet-management/debit-status-descriptions#status-statuscode-mapping) for a comprehensive list of `status` and `status_code` combinations.

<Warning>
  A maximum of three verification attempts is allowed per `debit_id`. Further attempts return an error.
</Warning>


# Card Webhooks
Source: https://www.cashfree.com/docs/api-reference/prepaid-payment-instruments/wallet-management/webhook-card

Configure Cashfree Card webhooks to receive event-based notifications whenever card transactions, refunds or card status updates occur in your PPI integration.

Webhooks are event-based notifications that are received when a specific event related to the Card occurs.

<Warning>
  In rare cases, such as network retries, read timeouts, processing delays, or delivery failures, the same webhook might be sent more than once for the same event. To prevent unintended side effects, implement idempotency in your webhook handler to handle duplicate deliveries.
</Warning>

## Webhook signature

You will receive the webhook signature in the webhook header. Here is a sample header from a webhook request.

| Header name | Header value |
| - | :-: |
| content-length | 1099 |
| x-webhook-attempt | 1 |
| content-type | application/json |
| x-webhook-signature | 07r5C3VMwsGYeldGOCYxe5zoHhIN1zLfa8O0U/yngHI= |
| x-webhook-timestamp | 1746427759733 |
| x-webhook-version | 2025-01-01 |

<Tip>
  Always capture the webhook payload in its raw text format before parsing into JSON. Parsing and reserialising the payload can change the structure (for example, array ordering, spacing, or `null` handling) and cause a signature mismatch during verification. Use the exact raw body string from the request when computing the signature.
</Tip>

## Card transaction webhooks

### Webhook payload fields

The webhook payload contains important metadata in its top-level fields.

| Field | Type | Description |
| - | - | - |
| `event_type` | `string` | Indicates the type of event that triggered the webhook. Possible values: `CARD_TRANSACTION_SUCCESS`, `CARD_TRANSACTION_FAILED`, `CARD_TRANSACTION_REVERSED`, `CARD_TRANSACTION_REJECTED`. |
| `event_time` | `string` | The UTC timestamp of when the event occurred, formatted in ISO 8601 (`YYYY-MM-DDTHH:MM:SSZ`). |
| `version` | `string` | The version of the webhook payload. |
| `data` | `object` | Contains event-specific details related to this feature. |

The following events are triggered at different stages of a card transaction:

| Event | Description |
| :- | :- |
| CARD\_TRANSACTION\_SUCCESS | The card transaction was successfully processed. |
| CARD\_TRANSACTION\_FAILED | The card transaction failed due to an error (for example, insufficient funds). |
| CARD\_TRANSACTION\_REVERSED | The card transaction was reversed (for example, a refund or void). |
| CARD\_TRANSACTION\_REJECTED | The card transaction was rejected by the system or issuer. |

<AccordionGroup>
  <Accordion title="CARD_TRANSACTION_SUCCESS">
    ```json theme={"dark"}
    {
      "event_type": "CARD_TRANSACTION_SUCCESS",
      "event_time": "2025-01-02T15:04:05Z",
      "version": "2025-01-01",
      "data": {
        "user_id": "USER827364",
        "wallet_id": "WALLET936721",
        "cf_wallet_id": "901234567890123456",
        "card_id": "CARD5678",
        "cf_card_id": "78901234567890123",
        "cf_card_transaction_id": "47821234567890123",
        "amount": 500.0,
        "channel": "ECOM",
        "status": "SUCCESS",
        "statusCode": "SUCCESS",
        "bank_reference_number": "123456789012",
        "usedAt": "AMAZON INDIA",
        "initiated_at": "2025-01-02T15:00:00Z",
        "processed_at": "2025-01-02T15:04:05Z",
        "sub_wallet": {
          "cf_sub_wallet_id": "35246543210987654321",
          "name": "General Wallet",
          "type": "GENERAL_PPI",
          "status": "ACTIVE",
          "balance": 1000.0,
          "available_balance": 1000.0,
          "funds_on_hold": 0.00
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="CARD_TRANSACTION_FAILED">
    ```json theme={"dark"}
    {
      "event_type": "CARD_TRANSACTION_FAILED",
      "event_time": "2025-01-02T15:01:30Z",
      "version": "2025-01-01",
      "data": {
        "user_id": "USER827364",
        "wallet_id": "WALLET936721",
        "cf_wallet_id": "901234567890123456",
        "card_id": "CARD5678",
        "cf_card_id": "78901234567890123",
        "cf_card_transaction_id": "47821234567890123",
        "amount": 100000.0,
        "channel": "ECOM",
        "status": "FAILED",
        "statusCode": "UNKNOWN_REASON",
        "bank_reference_number": null,
        "usedAt": "LUXURY STORE",
        "initiated_at": "2025-01-02T15:01:00Z",
        "processed_at": "2025-01-02T15:01:30Z",
        "sub_wallet": {
          "cf_sub_wallet_id": "35246543210987654321",
          "name": "General Wallet",
          "type": "GENERAL_PPI",
          "status": "ACTIVE",
          "balance": 1000.0,
          "available_balance": 1000.0,
          "funds_on_hold": 0.00
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="CARD_TRANSACTION_REVERSED">
    ```json theme={"dark"}
    {
      "event_type": "CARD_TRANSACTION_REVERSED",
      "event_time": "2025-01-02T16:00:00Z",
      "version": "2025-01-01",
      "data": {
        "user_id": "USER827364",
        "wallet_id": "WALLET936721",
        "cf_wallet_id": "901234567890123456",
        "card_id": "CARD5678",
        "cf_card_id": "78901234567890123",
        "cf_card_transaction_id": "47821234567890123",
        "amount": 500.0,
        "channel": "ECOM",
        "status": "REVERSED",
        "statusCode": "REVERSED",
        "bank_reference_number": "123456789012",
        "usedAt": "AMAZON INDIA",
        "initiated_at": "2025-01-02T15:00:00Z",
        "processed_at": "2025-01-02T16:00:00Z",
        "sub_wallet": {
          "cf_sub_wallet_id": "35246543210987654321",
          "name": "General Wallet",
          "type": "GENERAL_PPI",
          "status": "ACTIVE",
          "balance": 1500.0,
          "available_balance": 1500.0,
          "funds_on_hold": 0.00
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="CARD_TRANSACTION_REJECTED">
    ```json theme={"dark"}
    {
      "event_type": "CARD_TRANSACTION_REJECTED",
      "event_time": "2025-01-02T15:00:01Z",
      "version": "2025-01-01",
      "data": {
        "user_id": "USER827364",
        "wallet_id": "WALLET936721",
        "cf_wallet_id": "901234567890123456",
        "card_id": "CARD5678",
        "cf_card_id": "78901234567890123",
        "cf_card_transaction_id": "47821234567890123",
        "amount": 500.0,
        "channel": "POS",
        "status": "REJECTED",
        "statusCode": "INSUFFICIENT_BALANCE",
        "bank_reference_number": null,
        "usedAt": "SUSPICIOUS MERCHANT",
        "initiated_at": "2025-01-02T15:00:00Z",
        "processed_at": "2025-01-02T15:00:01Z",
        "sub_wallet": {
          "cf_sub_wallet_id": "35246543210987654321",
          "name": "General Wallet",
          "type": "GENERAL_PPI",
          "status": "ACTIVE",
          "balance": 1000.0,
          "available_balance": 1000.0,
          "funds_on_hold": 0.00
        }
      }
    }
    ```
  </Accordion>
</AccordionGroup>

### Card transaction data fields

| Field | Type | Description |
| - | - | - |
| `user_id` | `string` | Merchant's unique ID for the user. |
| `wallet_id` | `string` | Merchant's unique ID for the wallet. |
| `cf_wallet_id` | `string` | Cashfree's unique ID for the wallet. |
| `card_id` | `string` | Merchant's unique ID for the card. |
| `cf_card_id` | `string` | Cashfree's unique ID for the card. |
| `cf_card_transaction_id` | `string` | Cashfree's unique ID for the transaction. |
| `amount` | `number` | Transaction amount. |
| `channel` | `string` | Channel used for transaction (for example, ECOM, POS, ATM). |
| `status` | `string` | Status of the transaction. |
| `statusCode` | `string` | Granular Status code of the transaction. |
| `bank_reference_number` | `string` | Bank reference number (RRN) for the transaction. |
| `usedAt` | `string` | Location or merchant information where the card was used. |
| `initiated_at` | `string` | Timestamp when the transaction was initiated (ISO 8601). |
| `processed_at` | `string` | Timestamp when the transaction was processed (ISO 8601). |
| `sub_wallet` | `object` | Details of the sub-wallet used for the transaction. |

### Status and statusCode mapping

The following table shows the possible `statusCode` values for each transaction `status`:

| Status | StatusCode |
| - | - |
| RECEIVED | RECEIVED |
| SUCCESS | SUCCESS |
| REVERSED | REVERSED |
| FAILED | UNKNOWN\_REASON |
| REJECTED | CARD\_VELOCITY\_LIMIT\_EXCEEDED, INVALID\_CARD, INVALID\_CVV, FRM\_DECLINE, INVALID\_OTP, INSUFFICIENT\_BALANCE, WALLET\_VELOCITY\_LIMIT\_EXCEEDED, USER\_NOT\_ACTIVE, CARD\_NOT\_ACTIVE, CARD\_EXPIRED, MCC\_NOT\_ALLOWED, CHANNEL\_NOT\_ALLOWED |

## Card refund webhooks

### Webhook payload fields

The webhook payload contains important metadata in its top-level fields.

| Field | Type | Description |
| - | - | - |
| `event_type` | `string` | Indicates the type of event that triggered the webhook. Possible values: `CARD_REFUND_SUCCESS`, `CARD_REFUND_FAILED`, `CARD_REFUND_REJECTED`. |
| `event_time` | `string` | The UTC timestamp of when the event occurred, formatted in ISO 8601 (`YYYY-MM-DDTHH:MM:SSZ`). |
| `version` | `string` | The version of the webhook payload. |
| `data` | `object` | Contains event-specific details related to this feature. |

The following events are triggered at different stages of a card refund:

| Event | Description |
| :- | :- |
| CARD\_REFUND\_SUCCESS | The card refund was successfully processed and credited. |
| CARD\_REFUND\_FAILED | The card refund failed due to an error during processing. |
| CARD\_REFUND\_REJECTED | The card refund was rejected by the system or bank. |

<AccordionGroup>
  <Accordion title="CARD_REFUND_SUCCESS">
    ```json theme={"dark"}
    {
      "event_type": "CARD_REFUND_SUCCESS",
      "event_time": "2025-01-02T15:04:05Z",
      "version": "2025-01-01",
      "data": {
        "user_id": "USER827364",
        "wallet_id": "WALLET936721",
        "cf_wallet_id": "901234567890123456",
        "card_id": "CARD5678",
        "cf_card_id": "78901234567890123",
        "cf_card_transaction_id": "47821234567890123",
        "cf_card_refund_id": "REF987654321",
        "amount": 500.0,
        "status": "SUCCESS",
        "bank_reference_number": "123456789012",
        "used_at": "AMAZON INDIA",
        "initiated_at": "2025-01-02T15:00:00Z",
        "processed_at": "2025-01-02T15:04:05Z",
        "sub_wallet": {
          "cf_sub_wallet_id": "35246543210987654321",
          "name": "General Wallet",
          "type": "GENERAL_PPI",
          "status": "ACTIVE",
          "balance": 1500.0,
          "available_balance": 1500.0,
          "funds_on_hold": 0.00
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="CARD_REFUND_FAILED">
    ```json theme={"dark"}
    {
      "event_type": "CARD_REFUND_FAILED",
      "event_time": "2025-01-02T15:01:30Z",
      "version": "2025-01-01",
      "data": {
        "user_id": "USER827364",
        "wallet_id": "WALLET936721",
        "cf_wallet_id": "901234567890123456",
        "card_id": "CARD5678",
        "cf_card_id": "78901234567890123",
        "cf_card_transaction_id": "47821234567890123",
        "cf_card_refund_id": "REF987654322",
        "amount": 100.0,
        "status": "FAILED",
        "bank_reference_number": null,
        "used_at": "LUXURY STORE",
        "initiated_at": "2025-01-02T15:01:00Z",
        "processed_at": "2025-01-02T15:01:30Z",
        "sub_wallet": {
          "cf_sub_wallet_id": "35246543210987654321",
          "name": "General Wallet",
          "type": "GENERAL_PPI",
          "status": "ACTIVE",
          "balance": 1000.0,
          "available_balance": 1000.0,
          "funds_on_hold": 0.00
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="CARD_REFUND_REJECTED">
    ```json theme={"dark"}
    {
      "event_type": "CARD_REFUND_REJECTED",
      "event_time": "2025-01-02T15:00:01Z",
      "version": "2025-01-01",
      "data": {
        "user_id": "USER827364",
        "wallet_id": "WALLET936721",
        "cf_wallet_id": "901234567890123456",
        "card_id": "CARD5678",
        "cf_card_id": "78901234567890123",
        "cf_card_transaction_id": "47821234567890123",
        "cf_card_refund_id": "REF987654323",
        "amount": 500.0,
        "status": "REJECTED",
        "bank_reference_number": null,
        "used_at": "SUSPICIOUS MERCHANT",
        "initiated_at": "2025-01-02T15:00:00Z",
        "processed_at": "2025-01-02T15:00:01Z",
        "sub_wallet": {
          "cf_sub_wallet_id": "35246543210987654321",
          "name": "General Wallet",
          "type": "GENERAL_PPI",
          "status": "ACTIVE",
          "balance": 1000.0,
          "available_balance": 1000.0,
          "funds_on_hold": 0.00
        }
      }
    }
    ```
  </Accordion>
</AccordionGroup>

### Card refund data fields

| Field | Type | Description |
| - | - | - |
| `user_id` | `string` | Merchant's unique ID for the user. |
| `wallet_id` | `string` | Merchant's unique ID for the wallet. |
| `cf_wallet_id` | `string` | Cashfree's unique ID for the wallet. |
| `card_id` | `string` | Merchant's unique ID for the card. |
| `cf_card_id` | `string` | Cashfree's unique ID for the card. |
| `cf_card_transaction_id` | `string` | Cashfree's unique ID for the original card transaction. |
| `cf_card_refund_id` | `string` | Cashfree's unique ID for the refund. |
| `amount` | `number` | Refund amount. |
| `status` | `string` | Status of the refund. |
| `bank_reference_number` | `string` | Bank reference number (RRN) for the refund transaction. |
| `used_at` | `string` | Location or merchant information where the card was used. |
| `initiated_at` | `string` | Timestamp when the refund was initiated (ISO 8601). |
| `processed_at` | `string` | Timestamp when the refund was processed (ISO 8601). |
| `sub_wallet` | `object` | Details of the sub-wallet where the refund was credited. |

## Card status update webhooks

### Webhook payload fields

The webhook payload contains important metadata in its top-level fields.

| Field | Type | Description |
| - | - | - |
| `event_type` | `string` | Indicates the type of event that triggered the webhook. Possible values: `PPI_CARD_INACTIVE`, `PPI_CARD_EXPIRED`. |
| `event_time` | `string` | The UTC timestamp of when the event occurred, formatted in ISO 8601 (`YYYY-MM-DDTHH:MM:SSZ`). |
| `version` | `string` | The version of the webhook payload. |
| `data` | `object` | Contains event-specific details related to this feature. |

The following events are triggered when a card's status changes:

| Event | Description |
| :- | :- |
| PPI\_CARD\_INACTIVE | The card status has been updated to INACTIVE. |
| PPI\_CARD\_EXPIRED | The card has reached its expiry date and is now EXPIRED. |

<AccordionGroup>
  <Accordion title="PPI_CARD_INACTIVE">
    ```json theme={"dark"}
    {
      "event_type": "PPI_CARD_INACTIVE",
      "event_time": "2025-01-02T15:00:01Z",
      "version": "2025-01-01",
      "data": {
        "user_id": "USER827364",
        "cf_program_id": "10021",
        "wallet_id": "WALLET936721",
        "cf_wallet_id": "901234567890123456",
        "wallet_name": "PayNext Vendor Program",
        "sub_wallets": [
          {
            "cf_sub_wallet_id": "35246543210987654321",
            "name": "Holiday Gift Card 2026",
            "type": "STANDARD_PPI",
            "status": "ACTIVE",
            "balance": 0.00,
            "available_balance": 0.00,
            "funds_on_hold": 0.00
          }
        ],
        "card": {
          "card_name": "PayNext Vendor Program",
          "card_id": "CARD5678",
          "cf_card_id": "78901234567890123",
          "masked_card_number": "XXXXXXXXXXXX7092",
          "name_on_card": "John Doe",
          "card_holder_name": "John Doe",
          "network": "RUPAY",
          "status": "INACTIVE"
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="PPI_CARD_EXPIRED">
    ```json theme={"dark"}
    {
      "event_type": "PPI_CARD_EXPIRED",
      "event_time": "2025-01-02T00:00:01Z",
      "version": "2025-01-01",
      "data": {
        "user_id": "USER827364",
        "cf_program_id": "10021",
        "wallet_id": "WALLET936721",
        "cf_wallet_id": "901234567890123456",
        "wallet_name": "PayNext Vendor Program",
        "sub_wallets": [
          {
            "cf_sub_wallet_id": "35246543210987654321",
            "name": "Holiday Gift Card 2026",
            "type": "STANDARD_PPI",
            "status": "ACTIVE",
            "balance": 0.00,
            "available_balance": 0.00,
            "funds_on_hold": 0.00
          }
        ],
        "card": {
          "card_name": "PayNext Vendor Program",
          "card_id": "CARD5678",
          "cf_card_id": "78901234567890123",
          "masked_card_number": "XXXXXXXXXXXX7092",
          "name_on_card": "John Doe",
          "card_holder_name": "John Doe",
          "network": "RUPAY",
          "status": "EXPIRED"
        }
      }
    }
    ```
  </Accordion>
</AccordionGroup>

### Card status update data fields

| Field | Type | Description |
| - | - | - |
| `user_id` | `string` | Merchant's unique ID for the user. |
| `cf_program_id` | `string` | Cashfree's unique ID for the card wallet program. |
| `wallet_id` | `string` | Merchant's unique ID for the wallet. |
| `cf_wallet_id` | `string` | Cashfree's unique ID for the wallet. |
| `wallet_name` | `string` | Name of the wallet. |
| `sub_wallets` | `array` | List of sub-wallets associated with the wallet. |
| `sub_wallets[].cf_sub_wallet_id` | `string` | Cashfree's unique ID for the sub-wallet. |
| `sub_wallets[].name` | `string` | Name of the sub-wallet. |
| `sub_wallets[].type` | `string` | Type of the sub-wallet. |
| `sub_wallets[].status` | `string` | Current status of the sub-wallet. |
| `sub_wallets[].balance` | `number` | Total balance in the sub-wallet. |
| `sub_wallets[].available_balance` | `number` | Balance available for transactions in the sub-wallet. |
| `sub_wallets[].funds_on_hold` | `number` | Funds that are reserved and not yet available for use. |
| `card` | `object` | Details of the card whose status was updated. |
| `card.card_name` | `string` | Name of the card program. |
| `card.card_id` | `string` | Merchant's unique ID for the card. |
| `card.cf_card_id` | `string` | Cashfree's unique ID for the card. |
| `card.masked_card_number` | `string` | Masked card number. |
| `card.name_on_card` | `string` | Name as printed on the card. |
| `card.card_holder_name` | `string` | Name of the person holding the card. |
| `card.network` | `string` | Card network (for example, RUPAY). |
| `card.status` | `string` | New status of the card (for example, INACTIVE, EXPIRED). |

<Note>
  Verifying the signature is mandatory before processing any response. Refer to [Signature Verification](/docs/api-reference/prepaid-payment-instruments/webhook-signature-verification) for more details.
</Note>


# Wallet Webhooks
Source: https://www.cashfree.com/docs/api-reference/prepaid-payment-instruments/wallet-management/webhook-wallet

Configure Cashfree wallet webhooks to receive credit and debit event notifications in your prepaid instrument integration.

Cashfree sends event-based notifications when a wallet event occurs.

<Warning>
  In rare cases, such as network retries, read timeouts, processing delays, or delivery failures, the same webhook might be sent more than once for the same event. To prevent unintended side effects, implement idempotency in your webhook handler to handle duplicate deliveries.
</Warning>

## Webhook signature

You receive the webhook signature in the webhook header. The following table shows a sample header from a webhook request.

| Header name | Header value |
| - | :-: |
| `content-length` | 1099 |
| `x-webhook-attempt` | 1 |
| `content-type` | application/json |
| `x-webhook-signature` | 07r5C3VMwsGYeldGOCYxe5zoHhIN1zLfa8O0U/yngHI= |
| `x-webhook-timestamp` | 1746427759733 |
| `x-webhook-version` | 2025-01-01 |

<Tip> Always capture the webhook payload in its raw text format before parsing into JSON. Parsing and reserialising the payload can change the structure (for example, array ordering, spacing, or `null` handling) and cause a signature mismatch during verification. Use the exact raw body string from the request when computing the signature.</Tip>

## Wallet credit events

Cashfree sends the following event when a wallet credit succeeds:

| Event | Description |
| :- | :- |
| `PPI_CREDIT_SUCCESS` | The credit completes successfully and Cashfree adds funds to the sub-wallet. |

The following example shows a `PPI_CREDIT_SUCCESS` webhook for a `GIFT_PPI` sub-wallet. The `issued_gift_codes` array appears only for gift wallets.

<CodeGroup>
  ```json PPI_CREDIT_SUCCESS theme={"dark"}
  {
    "event_type": "PPI_CREDIT_SUCCESS",
    "event_time": "2006-01-02T15:04:05Z",
    "data": {
      "credit_id": "CREDIT126345",
      "cf_credit_id": "8901234567890123456",
      "wallet_id": "WALLET936721",
      "user_id": "USER827364",
      "amount": 100.5,
      "sub_wallet": {
        "cf_sub_wallet_id": "35246543210987654321",
        "name": "Gift Wallet",
        "type": "GIFT_PPI",
        "status": "ACTIVE",
        "balance": 1500.75
      },
      "issued_gift_codes": [
        {
          "code": "GIFT-2025-XYZ123",
          "value": 100.5,
          "expiry": "2025-12-31T23:59:59Z"
        }
      ],
      "status": "SUCCESS",
      "remarks": "Refund for order 123",
      "initiated_at": "2025-09-02T10:15:30Z",
      "processed_at": "2025-09-02T10:20:45Z"
    }
  }
  ```
</CodeGroup>

## Wallet credit webhook payload fields

The webhook payload contains important metadata in its top-level fields.

| Field | Type | Description |
| - | - | - |
| `event_type` | `string` | Indicates the type of event that triggered the webhook. Possible value: `PPI_CREDIT_SUCCESS`. |
| `event_time` | `string` | The UTC timestamp of when the event occurred, formatted in ISO 8601 (`YYYY-MM-DDTHH:MM:SSZ`). |
| `data` | `object` | Contains credit-specific details. The object matches the successful [Credit Wallet API](/docs/api-reference/prepaid-payment-instruments/wallet-management/credit-wallet) response. |

## Wallet debit events

Cashfree sends a debit webhook when a wallet debit completes with `SUCCESS`. Webhooks are not sent while the debit is `PENDING` (for example, while OTP verification is in progress). For `SMALL_PPI` and `FULL_KYC_PPI` sub-wallets, the webhook is sent after you complete verification with the [Verify Debit Wallet API](/docs/api-reference/prepaid-payment-instruments/wallet-management/verify-debit-wallet).

Cashfree sends the following event when a wallet debit succeeds:

| Event | Description |
| :- | :- |
| `PPI_DEBIT_SUCCESS` | The debit completes successfully and Cashfree deducts funds from the sub-wallet. |

The webhook `data` object uses `status` and `status_code` of `SUCCESS`. For other combinations returned by the Debit Wallet and Verify Debit Wallet APIs, see [Status and status-code reference](/docs/api-reference/prepaid-payment-instruments/wallet-management/debit-status-descriptions#status-and-status-code-reference).

The following example shows a `PPI_DEBIT_SUCCESS` webhook for a `GIFT_PPI` sub-wallet. The `applied_gift_codes` array appears only for gift wallets.

<CodeGroup>
  ```json PPI_DEBIT_SUCCESS theme={"dark"}
  {
    "event_type": "PPI_DEBIT_SUCCESS",
    "event_time": "2025-07-28T10:30:00Z",
    "data": {
      "debit_id": "DEBIT420984",
      "user_id": "USER827364",
      "cf_debit_id": "8901234567890123456",
      "wallet_id": "WALLET936721",
      "sub_wallet": {
        "cf_sub_wallet_id": "35246543210987654321",
        "name": "Gift Wallet",
        "type": "GIFT_PPI",
        "status": "ACTIVE",
        "balance": 1500.75,
        "available_balance": 1500.75,
        "funds_on_hold": 0.0
      },
      "applied_gift_codes": [
        {
          "code": "GHO-8900-HKDH-8899",
          "amount_debited": 100.00,
          "value": 100.00,
          "expiry": "2026-07-28T10:30:00Z"
        },
        {
          "code": "NMK-8454-JKJD-4224",
          "amount_debited": 500.00,
          "value": 600.00,
          "expiry": "2026-07-28T10:30:00Z"
        }
      ],
      "status": "SUCCESS",
      "status_code": "SUCCESS",
      "amount": 600.00,
      "remarks": "Purchase of electronics item",
      "initiated_at": "2025-07-28T10:30:00Z",
      "processed_at": "2025-07-28T10:30:00Z",
      "notes": {
        "example_key1": "example_value1",
        "example_key2": "example_value2"
      }
    }
  }
  ```
</CodeGroup>

## Wallet debit webhook payload fields

The webhook payload contains important metadata in its top-level fields.

| Field | Type | Description |
| - | - | - |
| `event_type` | `string` | Indicates the type of event that triggered the webhook. Possible value: `PPI_DEBIT_SUCCESS`. |
| `event_time` | `string` | The UTC timestamp of when the event occurred, formatted in ISO 8601 (`YYYY-MM-DDTHH:MM:SSZ`). |
| `data` | `object` | Contains debit-specific details. The object matches the successful [Debit Wallet API](/docs/api-reference/prepaid-payment-instruments/wallet-management/debit-wallet) or [Verify Debit Wallet API](/docs/api-reference/prepaid-payment-instruments/wallet-management/verify-debit-wallet) response. |

<Note>
  Verify the signature before you process any webhook payload. For more information, see [Webhook signature verification](/docs/api-reference/prepaid-payment-instruments/webhook-signature-verification#webhook-signature-verification).
</Note>


# Webhook Signature Verification
Source: https://www.cashfree.com/docs/api-reference/prepaid-payment-instruments/webhook-signature-verification

Verify Cashfree PPI webhook signatures using your client secret and the supplied timestamp header to confirm authenticity before processing wallet events.

Verifying the signature is mandatory before processing any response. It helps authenticate that the webhook is from Cashfree.

Every webhook contains a signature (`x-webhook-signature`) in the header.

The verification process is as follows:

1. Extract the **`x-webhook-timestamp`** from the headers.
2. Concatenate the timestamp and the **raw request body** (exact payload, unmodified).
3. Generate an **HMAC-SHA256 hash** of this string using your **client secret**.
4. Base64-encode the hash.
5. Compare it with the `x-webhook-signature` header value. If they match, the webhook is valid.

<Warning>
  * Always use the **raw request body** and not a parsed JSON object. This prevents signature mismatch.
  * Reject the webhook if the signature does not match.
</Warning>

### Sample code

<CodeGroup>
  ```javascript Node (Express) theme={"dark"}
  const crypto = require("crypto");

  function verify(req) {
    const ts = req.headers["x-webhook-timestamp"];
    const rawBody = req.rawBody; // middleware must store raw body
    const secretKey = "<client-secret>";
    const signStr = ts + rawBody;
    return crypto.createHmac("sha256", secretKey).update(signStr).digest("base64");
  }
  ```

  ```go Go (Echo) theme={"dark"}
  import (
      "crypto/hmac"
      "crypto/sha256"
      "encoding/base64"
      "io/ioutil"
  )

  func VerifySignature(expectedSig, ts, body string) (string, error) {
      signStr := ts + body
      key := "<client-secret>"
      h := hmac.New(sha256.New, []byte(key))
      h.Write([]byte(signStr))
      b := h.Sum(nil)
      return base64.StdEncoding.EncodeToString(b), nil
  }

  // usage
  timestamp := c.Request().Header.Get("x-webhook-timestamp")
  body, _ := ioutil.ReadAll(c.Request().Body)
  rawBody := string(body)
  signature := c.Request().Header.Get("x-webhook-signature")

  VerifySignature(signature, timestamp, rawBody)
  ```

  ```php PHP theme={"dark"}
  function computeSignature() {
      $rawBody = file_get_contents('php://input');
      $ts = getallheaders()['x-webhook-timestamp'];

      $signStr = $ts . $rawBody;
      $key = "<client-secret>";
      $computeSig = base64_encode(hash_hmac('sha256', $signStr, $key, true));
      return $computeSig; // compare with x-webhook-signature
  }
  ```

  ```java Java (Servlet) theme={"dark"}
  import javax.crypto.Mac;
  import javax.crypto.spec.SecretKeySpec;
  import java.util.Base64;

  public String generateSignature(HttpServletRequest request) throws Exception {
      BufferedReader bufferedReader = request.getReader();
      StringBuilder stringBuilder = new StringBuilder();
      String line;
      while ((line = bufferedReader.readLine()) != null) {
          stringBuilder.append(line);
      }
      String payload = stringBuilder.toString();
      String timestamp = request.getHeader("x-webhook-timestamp");

      String data = timestamp + payload;
      String secretKey = "<client-secret>";

      Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
      SecretKeySpec secret_key_spec = new SecretKeySpec(secretKey.getBytes(), "HmacSHA256");
      sha256_HMAC.init(secret_key_spec);

      return Base64.getEncoder().encodeToString(sha256_HMAC.doFinal(data.getBytes()));
  }
  ```

  ```python Python (Flask/Django) theme={"dark"}
  import base64
  import hashlib
  import hmac

  def generateSignature(request):
      raw_body = request.data
      payload = raw_body.decode('utf-8')
      timestamp = request.headers['x-webhook-timestamp']

      signatureData = timestamp + payload
      message = bytes(signatureData, 'utf-8')
      secretkey = bytes("<client-secret>", 'utf-8')
      signature = base64.b64encode(hmac.new(secretkey, message, digestmod=hashlib.sha256).digest())
      return signature.decode("utf-8")  # compare with x-webhook-signature
  ```
</CodeGroup>

## IPs to whitelist

When you decide to consume the webhooks, first, you need to verify if your systems need an IP whitelisting to be done at your end or not. Accordingly you can whitelist the below IPs of Cashfree:

| Sandbox |
| :- |
| 52.66.25.127 |
| 15.206.45.168 |

| Prod |
| :- |
| 52.66.101.190 |
| 3.109.102.144 |
| 18.60.134.245 |
| 18.60.183.142 |

| Port |
| :- |
| 443 (secured) |


# PPI Webhooks
Source: https://www.cashfree.com/docs/api-reference/prepaid-payment-instruments/webhooks-overview

Index of prepaid instrument (PPI) wallet webhooks, including credit events, wallet notifications, and HMAC verification for JSON payloads.

PPI (wallet) integrations use webhooks for asynchronous outcomes such as wallet credits. Payloads include **`event_type`** and a **`signature`** field; follow the dedicated verification guide before processing money movement. For general webhook reliability guidance, see the [Cashfree webhooks overview](/docs/api-reference/webhooks/overview).

## References

<CardGroup>
  <Card title="Webhook signature verification" icon="key" href="/docs/api-reference/prepaid-payment-instruments/webhook-signature-verification">
    How to compute and validate the HMAC for PPI webhook JSON, including `data` field ordering rules.
  </Card>

  <Card title="Wallet management webhook" icon="wallet" href="/docs/api-reference/prepaid-payment-instruments/wallet-management/webhook-wallet">
    Wallet-related webhook events and payload references tied to wallet management APIs.
  </Card>
</CardGroup>

If a dashboard option for PPI webhooks isn't visible, review the signature verification page above, then raise a request using the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1).


# Rate Limits
Source: https://www.cashfree.com/docs/api-reference/rate-limits

Understand how Cashfree API rate limits work, including per-minute thresholds, response headers, and best practices for handling 429 throttling errors.

We implement rate limiting in Cashfree APIs to control the number of requests a client can make within a specified timeframe. This ensures fair usage among all users, protects the API infrastructure from abuse or spikes in traffic, and maintains consistent performance.

Each API endpoint may have its own rate limit, defined by the maximum number of requests allowed per minute or hour.

You can view the specific rate limits for each API through these links:

<Card href="/docs/api-reference/payments/rate-limits">
  Payment API Rate limits
</Card>

<Card href="/docs/api-reference/vrs/v2/verification-rate-limits">
  SecureID API Rate limits
</Card>

## Response Headers

Cashfree APIs include rate-limiting information in the response headers, such as:

* `X-RateLimit-Limit`: The maximum number of requests allowed in the current window.
* `X-RateLimit-Remaining`: The number of requests remaining in the current window.
* `X-RateLimit-Reset`: The time (in seconds) until the rate limit resets.

## Throttling

If the limit is exceeded, the API returns a `429` Too Many Requests status code. Clients are advised to respect the retry-after time mentioned in the response headers before sending further requests.

## Requesting rate limit increases

If your application requires higher rate limits, you can submit a request through the [support form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) or contact your account manager directly. When you submit your request, include the following information:

* Your merchant ID.
* Current usage patterns and volumes.
* Expected future usage requirements.
* Business justification for the increase.

Your account manager can provide faster processing and personalised assistance for rate limit increase requests.

## Best Practices

1. Implement exponential backoff strategies to handle retries gracefully.
2. Monitor API usage and avoid excessive calls by caching responses where applicable.
3. Use API keys responsibly and ensure the application logic adheres to the documented rate limits.


# 2FA API Signature Generation
Source: https://www.cashfree.com/docs/api-reference/vrs/2fa-api-signature-generation

Generate the 2FA signature for Cashfree Secure ID APIs by combining your clientId with a UNIX timestamp and encrypting it with the provided public key.

Follow the steps below to generate your signature:

1. Retrieve your clientId (one which you are passing through the header X-Client-Id)
2. Append this with CURRENT UNIX timestamp separated by a period (.)
3. Encrypt this data using RSA-OAEP with SHA1 and your Public key (.pem file) – this is the signature.
4. Pass this signature through the header X-Cf-Signature.
5. Also include the `x-api-version` header in your request (for example, `2022-09-13`).

The signature is generally valid for 5–10 minutes. Generate a fresh signature for each session.

In the case of using our library, go through the libraries section. During the initialization process, you need to pass the key as a parameter.

<CodeGroup>
  ```php PHP theme={"dark"}
  <?php
  public static function getSignature() {
      $clientId = "<your clientId here>";
      $publicKey =
  openssl_pkey_get_public(file_get_contents("/path/to/certificate/public
  _key.pem"));
      $encodedData = $clientId.".".strtotime("now");
      return static::encrypt_RSA($encodedData, $publicKey);
    }
  private static function encrypt_RSA($plainData, $publicKey) { if (openssl_public_encrypt($plainData, $encrypted, $publicKey,
  OPENSSL_PKCS1_OAEP_PADDING))
        $encryptedData = base64_encode($encrypted);
      else return NULL;
      return $encryptedData;
    }
  ?>
  ```

  ```java Java theme={"dark"}
  private static String generateEncryptedSignature(String clientIdWithEpochTimestamp) {
      // String clientIdWithEpochTimeStamp = clientId+"."+Instant.now().getEpochSecond();
      String encrytedSignature = "";
      try {
          byte[] keyBytes = Files
              .readAllBytes(new File("/Users/sameera/Downloads/payout_test_public_key.pem").toPath()); // Absolute Path to be replaced
          String publicKeyContent = new String(keyBytes);
          System.out.println(publicKeyContent);
          publicKeyContent = publicKeyContent.replaceAll("[\\t\\n\\r]", "")
              .replace("-----BEGIN PUBLIC KEY-----", "").replace("-----END PUBLIC KEY-----", "");
          KeyFactory kf = KeyFactory.getInstance("RSA");
          System.out.println(publicKeyContent);
          X509EncodedKeySpec keySpecX509 = new X509EncodedKeySpec(
              Base64.getDecoder().decode(publicKeyContent));
          RSAPublicKey pubKey = (RSAPublicKey) kf.generatePublic(keySpecX509);
          final Cipher cipher = Cipher.getInstance("RSA/ECB/OAEPWithSHA-1AndMGF1Padding");
          cipher.init(Cipher.ENCRYPT_MODE, pubKey);
          encrytedSignature = Base64.getEncoder().encodeToString(cipher.doFinal(clientIdWithEpochTimestamp.getBytes()));
          System.out.println(encrytedSignature);
      } catch (Exception e) {
          e.printStackTrace();
      }
      return encrytedSignature;
  }
  ```
</CodeGroup>

## FAQs

<AccordionGroup>
  <Accordion title="Can I disable 2FA in the sandbox environment for testing?">
    No. Due to product architecture limitations, 2FA cannot be disabled in any environment, including sandbox. Depending on your integration, you can use either IP Whitelisting or Public Key authentication as your 2FA method.
  </Accordion>

  <Accordion title="What does a signature mismatch error mean?">
    A signature mismatch error typically indicates that 2FA via Public Key is enabled for your account. You must include a dynamic signature in the `x-cf-signature` header of each API request. Make sure you are also providing the `x-api-version` header (for example, `2022-09-13`). The signature is valid for 5–10 minutes, so generate a fresh one for each session.
  </Accordion>
</AccordionGroup>


# Data to Test Integration
Source: https://www.cashfree.com/docs/api-reference/vrs/data-to-test-integration

Use these sample documents, bank accounts, and parameters to validate every Cashfree Secure ID API across both success and failure verification scenarios.

This topic provides a comprehensive set of test data to help you validate and integrate Secure ID APIs effectively. It includes sample account details, document numbers, and API-specific parameters required for simulating various test scenarios.
Use this data to ensure that your integration behaves correctly for both successful and failure cases across multiple Secure ID services such as Aadhaar verification, PAN validation, passport verification, liveness checks, name matching, and more.

<Note>
  **Note**:

  * Validations using any data other than what’s listed in this topic will fail. Test mode validations simulate live transactions but aren't processed through actual verification systems.

  * All different modes and validation for the TEST and PROD environment have to be enabled by Cashfree before you attempt. You can contact your account manager or fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) to enable it for your account.
</Note>

## Test account details

The SMS notification service is unavailable on the TEST environment, and the OTP is standard across all OTP requests. It is 111000.

### Account holder names

Use the below details to test account holder name validation.

| Given name | Name specified | Match score | Match result | Account number |
| :- | :- | :- | :- | :- |
| JOHN DOE | john doe | 100.00 | DIRECT\_MATCH | 026291800001191 |
| JOHN DOE | john d | 85.00 | GOOD\_PARTIAL\_MATCH | 026291800001191 |
| JOHN DOE | j doe | 70.00 | MODERATE\_PARTIAL\_MATCH | 026291800001191 |
| JOHN DOE | jane d | 38.00 | POOR\_PARTIAL\_MATCH | 026291800001191 |
| TOM WELLS | tom wells | 100.00 | DIRECT\_MATCH | 1233943142 |
| TOM WELLS | tom w | 85.00 | GOOD\_PARTIAL\_MATCH | 1233943142 |
| TOM WELLS | t wells | 70.00 | MODERATE\_PARTIAL\_MATCH | 1233943142 |
| TOM WELLS | tim lee | 38.00 | POOR\_PARTIAL\_MATCH | 1233943142 |
| BOB HOPE | bob hope | 100.00 | DIRECT\_MATCH | 388108022658 |
| BOB HOPE | bob h | 85.00 | GOOD\_PARTIAL\_MATCH | 388108022658 |
| BOB HOPE | b hope | 70.00 | MODERATE\_PARTIAL\_MATCH | 388108022658 |
| BOB HOPE | bane hue | 38.00 | POOR\_PARTIAL\_MATCH | 388108022658 |

### Aadhaar masking

You will get a success response for the API request when you upload a valid image format.

### Passport

The file\_number parameter requires a 15-character string value. Use the following prefixes:

| Prefix for file\_number | Remarks |
| :- | :- |
| PA1 | SUCCESS |
| PA0 | INVALID |
| Any other value | GATEWAY\_ERROR |

### Face liveness

Upload a valid image format and use the following prefix for the verification\_id parameter:

| Verification ID | Remarks |
| :- | :- |
| 2222XXXXX | MULTIPLE\_FACES\_DETECTED |
| 3333XXXXX | FACE\_NOT\_DETECTED |
| 4444XXXXX | REAL\_FACE\_NOT\_DETECTED |
| XXXXXXXXX | Success |

### Face match

You will get a success response for the API request when you upload a valid image format.

### CIN

| CIN | Remarks |
| :- | :- |
| U72900KA2015PTC082989 | VALID |
| U72900KA2015PTC082988 | VALID |
| U72900KA2015PTC082987 | VALID |
| U72900KA2015PTC082981 | INVALID |
| U72900KA2015PTC082982 | INVALID |

### Registration certificate (vehicle)

| Registration number | Remarks |
| :- | :- |
| HJ01ME5279 | INVALID |
| HJ01ME5679 | INVALID |
| HJ01ME5678 | VALID |

### Driving licence

| Driving licence | DOB | Remarks |
| :- | :- | :- |
| KA0120198900984 | 1994-08-05 | VALID |
| KA2320238908787 | 1987-09-04 | INVALID |

### Reverse geocoding coordinates

| Latitude | Longitude | Remarks |
| :- | :- | :- |
| 1 | 2 | Internal server error |
| 12.9274915 | 77.6326806 | Success |

### Geocoding

| Address | Remarks |
| :- | :- |
| Bangalore Karnataka | VALID |
| AAA BBB CCC | INVALID |

### Voter ID

| EPIC number | Remarks |
| :- | :- |
| UAI4574761 | Valid |
| UAI4574762 | Invalid |

### IP address

| IP address | Remarks |
| :- | :- |
| 1.0.171.255 | VALID |
| 219.12.67.255 | INVALID |

### Fetch GSTIN with PAN

| PAN | Remarks |
| :- | :- |
| DUMPY1001A | Success |
| DUMPY1030A | Unavailable |

### Employment information

| Parameter | Value |
| :- | :- |
| phone | 9988775566 |
| pan | ABCDE5930G |
| uan | 101340612345 |
| dob | 1999-01-27 |
| employee\_name | John Doe |
| employer\_name | Cashfree India Private Ltd |

### Name match

| name\_1 | name\_2 | score | reason |
| :- | :- | :- | :- |
| JOHN DOE | JOHN DOE | 1 | DIRECT\_MATCH |
| JOHN DOE | JOHN DE | 0.93 | GOOD\_PARTIAL\_MATCH |
| JOHN DOE | JOHN | 0.77 | MODERATE\_PARTIAL\_MATCH |
| JOHN DOE | J DO | 0.53 | POOR\_PARTIAL\_MATCH |
| JOHN DOE | DO | 0 | NO\_MATCH |

### Bank numbers

For banks, the primary parameters for transfer would be the bank account and IFSC number included while adding the beneficiary. Use these test bank numbers to test payouts to a card. Utilised only with test API keys.

| Account number | IFSC | Remarks |
| :- | :- | :- |
| 026291800001191 | YESB0000262 | Success |
| 00011020001772 | HDFC0000001 | Success |
| 000890289871772 | SCBL0036078 | Success |
| 000100289877623 | SBIN0008752 | Failed at bank |
| 2640101002729 | CNRR0002640 | Failure–Invalid IFSC code |
| 026291800001190 | YESB0000262 | Failure–Invalid Account number |
| 02014457596969 | CITI0000001 | Success (later to Reversed) |

### Aadhaar

| Aadhaar number | Remarks |
| :- | :- |
| 655675523712 | Valid |
| 655675523711 | Valid |
| 655675523710 | Invalid |
| 655675523709 | Invalid |

### GSTIN

| GSTIN | Remarks |
| :- | :- |
| 29AAICP2912R1ZR | Valid |
| 27ABCFGH5678D1Z | Valid |
| 36JKLPQR9012E2Y | Valid |
| 45XYZLMN2345G3W | Valid |
| 12PQRST6789A4BC | Valid |
| 39ABCDE0987F6GH | Valid |
| 23UVWXYZ5678H5D | Valid |
| 05BBICP2912R1ZR | Valid |
| 29AAIZP2912R1ZR | Invalid |
| 05BBICA2912R1ZR | Invalid |

### PAN

| PAN | Remarks |
| :- | :- |
| Individual PAN - ABCPV1234D | Valid |
| Individual PAN - XYZPP4321W | Valid |
| Individual PAN - AZJPG7110R | Valid |
| Business PAN - ABCCD8000T | Valid |
| Business PAN - XYZHP2000L | Valid |
| Business PAN - AAAHU4383C | Valid |
| Business PAN - AMJCL2021N | Valid |
| Individual PAN - DEFPV0126D | Invalid |
| Individual PAN - TUVPP5678W | Invalid |
| Business PAN - LMNCD8010T | Invalid |
| Business PAN - EFGHH2020L | Invalid |

### Mobile 360

Use the following prefix as the data to test the API:

| Mobile number | Remarks |
| :- | :- |
| 9999999999 | SUCCESS |
| 8888888888 | DETAILS\_NOT\_FOUND |

### UPI Penny Drop

Use the following VPAs to test UPI Penny Drop scenarios.

| VPA | Remarks |
| :- | :- |
| success\@upi | VALID |
| valid\@upi | VALID |
| valid\@ybl | VALID |
| invalid\@upi | INVALID |
| incorrect\@upi | INVALID |
| invalid\@ybl | INVALID |
| expired\@upi | EXPIRED |
| expired1\@upi | EXPIRED |
| expired\@ybl | EXPIRED |

### DigiLocker verify account

Use the following prefix as the data to test the API:

| Mobile number | Remarks |
| :- | :- |
| 9988xxxxxx | VALID |
| 919988xxxxxxx | VALID |
| +919988xxxxxx | VALID |

### Geocoding

| Address | Remarks |
| :- | :- |
| Bangalore Karnataka | VALID |
| AAA BBB CCC | VALID |

### One click onboarding

Use the following phone number and OTP to test the APIs:

| Phone number | OTP |
| :- | :- |
| 9999991234 | 1234 |

### Video KYC

Use the following OTP as the test otp to test the VKYC flow during mobile verification in the initial step:

| OTP |
| :- |
| 123456 |

### PAN to UDYAM verification

Use the following PAN numbers to test PAN-Udyam verification scenarios:

| PAN number | Remarks |
| :- | :- |
| AMJCL2021N | SUCCESS |
| LMNCD8010T | UDYAM\_NOT\_FOUND |
| ABCCD8000T | UDYAM\_CANCELLED |

### UDYAM verification

Use the following Udyam reference numbers to test Udyam verification scenarios:

| Udyam reference number | Remarks |
| :- | :- |
| UDYAM-UP-43-1234567 | SUCCESS |
| UDYAM-MH-43-1234567 | UDYAM\_NOT\_FOUND |
| UDYAM-KA-43-1234567 | UDYAM\_IS\_CANCELLED |


# Getting Started
Source: https://www.cashfree.com/docs/api-reference/vrs/getting-started

Set up your Cashfree Secure ID integration by generating API keys, whitelisting IPs, configuring 2FA signatures, and reviewing test endpoints before going live.

* [View end points](/docs/api-reference/vrs/getting-started#view-end-points)
* [Generate API keys](/docs/api-reference/vrs/getting-started#generate-api-keys)
* [Whitelist IP address](/docs/api-reference/vrs/getting-started#whitelist-your-ip-address)
* [2FA API signature generation](/docs/api-reference/vrs/getting-started#2fa-api-signature-generation)
* [Configure success rate alerts](/docs/api-reference/vrs/getting-started#configure-success-rate-alerts)
* [Any queries: contact us](/docs/api-reference/vrs/getting-started#contact-us-for-any-queries)

<Tip>Install [Cashfree Agent Skills](/docs/tools-ai/cashfree-agent-skills) to bring Cashfree product knowledge into your AI coding assistant (Claude Code, Cursor, VS Code Copilot, Gemini CLI, and more) to answer integration questions and generate accurate code without leaving your editor.</Tip>

## View end points

Cashfree uses API keys to allow access to the API. Once you have signed up at our merchant site, you will be able to see your AppId and SecretKey.

Cashfree expects API key to be included in all API requests to the server. Use the endpoint **/api/v1/credentials/verify** to verify your credentials.

| Environment | URL |
| :- | :- |
| Production | [https://api.cashfree.com/verification](https://api.cashfree.com/verification) |
| Test | [https://sandbox.cashfree.com/verification](https://sandbox.cashfree.com/verification) |

## Generate API keys

Follow the instructions below to generate API keys:

1. Log in to your [Secure ID dashboard](https://merchant.cashfree.com/verificationsuite/home) and click **Developers** on the navigation panel.
2. Click **API Keys**.
3. Click **Generate API Keys** from the *API Keys* screen.
   <Frame>
     <img />
   </Frame>
4. The *New API Keys* popup displays with the client ID and client secret information.
5. Click **Download API Keys** to download the information and save them in your local system folder. Do not share the keys with anyone because they are confidential. You can generate a maximum of 10 API keys.

<Note>
  API Keys - Production Environment: You need to perform an OTP authentication
  to generate API keys for production environment.
</Note>

## Whitelist your IP address

Whitelisting the IP address or generating a public key provides a layer of authentication. These cybersecurity techniques prevent anonymous or unknown disbursement requests and allow only verified requests. Your IP address needs to be whitelisted in the Cashfree production server or it rejects all incoming requests.

Follow the instructions below to whitelist your IP:

1. Log in to your [Secure ID dashboard](https://merchant.cashfree.com/verificationsuite/home) and click **Developers** from the navigation pane > **Two-Factor Authentication** from the **Secure ID** card.
2. Choose **IP Whitelist** from the **Select 2FA Method** drop-down.
3. Click **Add IP Address**.
4. Enter the IP address you want to whitelist in the respective field and click **Add IP Address** to save the details. Note that only IPv4 must be whitelisted, not IPv6. The whitelisted IPs appear in the dashboard.

<Note>
  You can whitelist up to 25 IP addresses. If you need to whitelist more than 25 IP addresses or if your IP addresses are dynamic (not static), use the [Signature Generation](/docs/api-reference/vrs/getting-started#2fa-api-signature-generation) method.
</Note>

<img alt="" />

<Note>
  **How to find my IP address?**

  Depending on your operating system, you can retrieve the IP of the system via
  multiple methods. You can also find your IP using helper sites such as
  [https://whatismyipaddress.com/](https://whatismyipaddress.com/).
</Note>

## 2FA API signature generation

To generate a signature, you need to generate the public key. You then use the generated public key to generate the signature.

### Generate public key

1. Log in to your [Secure ID dashboard](https://merchant.cashfree.com/verificationsuite/home) and click **Developers** from the navigation pane > **Two-Factor Authentication** from the **Secure ID** card.
2. Select **Public Key** from the *Select 2FA Method* drop-down.
3. Click **Generate Public Key**.  You can have only one active public key at a time, and you can download it only once.
4. The public key is downloaded to your computer. The public key file is password protected you need to use the unique password sent to your registered email address (linked to your Cashfree account) to open it.

### Generate signature

Follow the steps below to generate your signature:

1. Retrieve your clientId (one which you are passing through the header X-Client-Id)
2. Append this with CURRENT UNIX timestamp separated by a period (.)
3. Encrypt this data using RSA encrypt with Public key you received – this is the signature.
4. Pass this signature through the header X-Cf-Signature.

<Note>
  This method generates a signature that is valid for 5 minutes. Generate a new signature every 5 minutes.
</Note>

In the case of using our library, go through the libraries section. During the initialization process, you need to pass the key as a parameter.

<CodeGroup>
  ```php PHP theme={"dark"}
  <?php
  public static function getSignature() {
      $clientId = "<your clientId here>";
      $publicKey =
  openssl_pkey_get_public(file_get_contents("/path/to/certificate/public
  _key.pem"));
      $encodedData = $clientId.".".strtotime("now");
      return static::encrypt_RSA($encodedData, $publicKey);
    }
  private static function encrypt_RSA($plainData, $publicKey) { if (openssl_public_encrypt($plainData, $encrypted, $publicKey,
  OPENSSL_PKCS1_OAEP_PADDING))
        $encryptedData = base64_encode($encrypted);
      else return NULL;
      return $encryptedData;
    }
  ?>
  ```

  ```java Java theme={"dark"}
  private static String generateEncryptedSignature(String clientIdWithEpochTimestamp) {
      // String clientIdWithEpochTimeStamp = clientId+"."+Instant.now().getEpochSecond();
      String encrytedSignature = "";
      try {
          byte[] keyBytes = Files
              .readAllBytes(new File("/Users/sameera/Downloads/payout_test_public_key.pem").toPath()); // Absolute Path to be replaced
          String publicKeyContent = new String(keyBytes);
          System.out.println(publicKeyContent);
          publicKeyContent = publicKeyContent.replaceAll("[\\t\\n\\r]", "")
              .replace("-----BEGIN PUBLIC KEY-----", "").replace("-----END PUBLIC KEY-----", "");
          KeyFactory kf = KeyFactory.getInstance("RSA");
          System.out.println(publicKeyContent);
          X509EncodedKeySpec keySpecX509 = new X509EncodedKeySpec(
              Base64.getDecoder().decode(publicKeyContent));
          RSAPublicKey pubKey = (RSAPublicKey) kf.generatePublic(keySpecX509);
          final Cipher cipher = Cipher.getInstance("RSA/ECB/OAEPWithSHA-1AndMGF1Padding");
          cipher.init(Cipher.ENCRYPT_MODE, pubKey);
          encrytedSignature = Base64.getEncoder().encodeToString(cipher.doFinal(clientIdWithEpochTimestamp.getBytes()));
          System.out.println(encrytedSignature);
      } catch (Exception e) {
          e.printStackTrace();
      }
      return encrytedSignature;
  }
  ```
</CodeGroup>

## Configure success rate alerts

Configure email alerts for each KYC API to be notified when the success rate (SR) falls below a specified threshold for any endpoint. These alerts help you proactively monitor API performance and take timely action to maintain smooth verification workflows.

To configure alerts for your Secure ID account:

1. Log in to your [Secure ID dashboard](https://merchant.cashfree.com/verificationsuite/home) using your credentials.
2. Select **Settings** from the top navigation menu.
3. Select **Email Notifications** under the **Secure ID** section.
4. Select the **SR Alerts** tab and enable the specific API endpoints you want to monitor.
5. Select **Email Notification** from the **Manage Notifications** drop-down, and enter the email addresses to receive alerts.
6. Select **Next**, review your configuration, and select **Submit**.

<img alt="" />

## Contact us for any queries

For identifying, diagnosing, and resolving problems related to API requests, ensure the information below is communicated while contacting us:

* Share the API request and response details along with `referenceId` or `verificationId`.
* Mention the registered email ID and environment in the email.
* Use your registered email address (with Cashfree) to send the email or mention the registered email address.
* Include your account manager in the CC of the email request.

<Note>
  For dashboard queries, share the screenshot and .har file of the screen.
</Note>


# Overview
Source: https://www.cashfree.com/docs/api-reference/vrs/overview

Use Cashfree Secure ID REST APIs to verify identities, documents, and bank accounts in real time with webhooks, SDKs, and bulk processing support.

The Secure ID APIs provide RESTful endpoints for identity verification and document authentication with industry-leading success rates and highly optimised latency. These APIs support both sandbox testing and production environments, determined by your credentials, with consistent authentication and error handling across all endpoints. Real-time webhooks and SDKs ensure seamless integration with sub-second response times for critical verification workflows, including bulk processing capabilities for high-volume verification requirements.

## Key features

The key features offered by Cashfree's Secure ID APIs are:

* **Identity verification**: Verify PAN, GSTIN, DigiLocker, and other government documents in real-time.
* **Document OCR**: Extract and verify information from 8+ official documents including PAN, Aadhaar, Driving License, Passport, Voter ID, Vehicle RC, and more using Smart OCR technology with E-sign integration for document authentication.
* **Biometric verification**: Perform face liveness checks, face matching, and name matching for enhanced security.
* **Bulk processing**: Handle large-volume verification requests efficiently with batch processing capabilities for enterprise-scale operations.
* **Seamless onboarding**: 1-click onboarding solutions with mobile-based data retrieval and automated form pre-filling from verified sources through APIs and SDKs.
* **Location verification**: IP verification, reverse geocoding, and address validation tools for accurate location-based authentication.

<Tabs>
  <Tab title="Bank and financial">
    <div>
      <div>
        <div>
          <h4>OCR and biometric verification</h4>

          <div>
            <div>
              <a href="/docs/api-reference/vrs/v2/face-liveness/face-liveness">Face Liveness</a>

              <p>
                Verify if the customer is real and detect spoofing attempts through facial analysis.
              </p>
            </div>
          </div>

          ***

          <div>
            <div>
              <a href="/docs/api-reference/vrs/v2/face-match/face-match">Face Match</a>

              <p>
                Compare facial features between two images or validate against ID documents.
              </p>
            </div>
          </div>

          ***

          <div>
            <div>
              <a href="/docs/api-reference/vrs/v2/name-match/name-match">Name Match</a>

              <p>
                Verify names with variations and fuzzy matching to handle different name formats and spellings.
              </p>
            </div>
          </div>

          ***

          <div>
            <div>
              <a href="/docs/api-reference/vrs/v2/smart-ocr/smart-ocr">Smart OCR</a>

              <p>
                Extract and validate information from documents using advanced OCR technology.
              </p>
            </div>
          </div>

          ***

          <div>
            <div>
              <a href="/docs/api-reference/vrs/v2/e-sign/create-e-sign-request">E-sign</a>

              <p>
                Create electronic signature requests for document signing and verification.
              </p>
            </div>
          </div>

          ***

          <div>
            <div>
              <a href="/docs/api-reference/vrs/v2/gstin/verify-gstin">KYB (GSTIN Verification)</a>

              <p>
                Know Your Business verification through GSTIN validation for comprehensive business identity verification.
              </p>
            </div>
          </div>
        </div>
      </div>

      <div>
        <div>
          <h4>Core banking services</h4>

          <div>
            <div>
              <a href="/docs/api-reference/vrs/v2/bav-v2/bank-account-verification-sync-v2">Bank Account Verification</a>

              <p>
                Verify bank account details to ensure account validity and customer name matching.
              </p>
            </div>
          </div>

          ***

          <div>
            <div>
              <a href="/docs/api-reference/vrs/v2/ifsc/ifsc-verification-v2">IFSC Verification</a>

              <p>
                Verify IFSC codes and retrieve bank branch details for accurate banking operations.
              </p>
            </div>
          </div>

          ***

          <div>
            <div>
              <a href="/docs/api-reference/vrs/v2/reverse-penny-drop/create-reverse-penny-drop-request">Reverse Penny Drop</a>

              <p>
                Validate bank account information through UPI-based ₹1 deposit verification method.
              </p>
            </div>
          </div>

          ***

          <div>
            <div>
              <a href="/docs/api-reference/vrs/v2/upi-penny-drop/create-upi-penny-drop-request">UPI Penny Drop</a>

              <p>
                Verify bank account details by depositing ₹1 through UPI to retrieve account holder information.
              </p>
            </div>
          </div>

          ***

          <div>
            <div>
              <a href="/docs/api-reference/vrs/v2/video-kyc/initiate-vkyc">Video KYC</a>

              <p>
                Initiate video-based KYC verification with live agent interaction for comprehensive identity validation.
              </p>
            </div>
          </div>
        </div>
      </div>
    </div>
  </Tab>

  <Tab title="Identity verification">
    <div>
      <div>
        <div>
          <h4>Government documents</h4>

          <div>
            <div>
              <a href="/docs/api-reference/vrs/v2/pan/pan-lite">PAN Verification</a>

              <p>
                Comprehensive PAN verification with PAN Lite and PAN 360 options for detailed customer information.
              </p>
            </div>
          </div>

          ***

          <div>
            <div>
              <a href="/docs/api-reference/vrs/v2/driving-license/verify-driving-licence-details">Driving License</a>

              <p>
                Verify driving licence details including type, issue date, and expiry date.
              </p>
            </div>
          </div>

          ***

          <div>
            <div>
              <a href="/docs/api-reference/vrs/v2/voter-id/verify-voter-id">Voter ID</a>

              <p>
                Verify voter ID authenticity and retrieve constituency details using EPIC number.
              </p>
            </div>
          </div>

          ***

          <div>
            <div>
              <a href="/docs/api-reference/vrs/v2/passport/verify-passport">Passport</a>

              <p>
                Verify passport information using file number to ensure identity authenticity.
              </p>
            </div>
          </div>

          ***

          <div>
            <div>
              <a href="/docs/api-reference/vrs/v2/udyam/verify-udyam">Udyam</a>

              <p>
                Verify Udyam information using Udyam reference number to ensure identity authenticity.
              </p>
            </div>
          </div>

          ***

          <div>
            <div>
              <a href="/docs/api-reference/vrs/v2/pan-to-udyam/fetch-udyam-with-pan">Pan to Udyam</a>

              <p>
                Verify Pan to Udyam information using Pan number to ensure identity authenticity.
              </p>
            </div>
          </div>
        </div>
      </div>

      <div>
        <div>
          <h4>Business and biometric verification</h4>

          <div>
            <div>
              <a href="/docs/api-reference/vrs/v2/gstin/verify-gstin">GSTIN</a>

              <p>
                Verify GSTIN information to validate business registration details.
              </p>
            </div>
          </div>

          ***

          <div>
            <div>
              <a href="/docs/api-reference/vrs/v2/smart-ocr/smart-ocr">Smart OCR</a>

              <p>
                Extract and validate information from documents using advanced OCR technology.
              </p>
            </div>
          </div>

          ***

          <div>
            <div>
              <a href="/docs/api-reference/vrs/v2/face-liveness/face-liveness">Face Liveness</a>

              <p>
                Verify if the customer is real and detect spoofing attempts through facial analysis.
              </p>
            </div>
          </div>

          ***

          <div>
            <div>
              <a href="/docs/api-reference/vrs/v2/face-match/face-match">Face Match</a>

              <p>
                Compare facial features between two images or validate against ID documents.
              </p>
            </div>
          </div>
        </div>
      </div>
    </div>
  </Tab>

  <Tab title="Advanced services">
    <div>
      <div>
        <div>
          <h4>Digital onboarding and mobile services</h4>

          <div>
            <div>
              <a href="/docs/api-reference/vrs/v2/1-click-onboarding/initiate-oauth">1-Click Onboarding SDK</a>

              <p>
                Streamline customer onboarding with mobile-based data retrieval and automated form pre-filling SDK from 15+ verified sources.
              </p>
            </div>
          </div>

          ***

          <div>
            <div>
              <a href="/docs/api-reference/vrs/v2/mobile-360-otp-flow/mobile-360-send-otp-request">Mobile 360 Get OTP</a>

              <p>
                Generate OTP for mobile-based identity verification and data retrieval for form pre-filling.
              </p>
            </div>
          </div>

          ***

          <div>
            <div>
              <a href="/docs/api-reference/vrs/v2/mobile-360-otp-flow/mobile-360-verify-otp">Mobile 360 Verify OTP</a>

              <p>
                Verify OTP and retrieve comprehensive personal and financial data for automated form pre-filling.
              </p>
            </div>
          </div>

          ***

          <div>
            <div>
              <a href="/docs/api-reference/vrs/v2/advanced-employment/get-employment-details">Advanced Employment</a>

              <p>
                Retrieve individual's employment details including member ID, joining date, and exit date.
              </p>
            </div>
          </div>
        </div>
      </div>

      <div>
        <div>
          <h4>Location and form services</h4>

          <div>
            <div>
              <a href="/docs/api-reference/vrs/v2/geocoding/geocoding">Geocoding</a>

              <p>
                Convert addresses into geographic coordinates for location-based verification.
              </p>
            </div>
          </div>

          ***

          <div>
            <div>
              <a href="/docs/api-reference/vrs/v2/reverse-geocoding/reverse-geocoding">Reverse Geocoding</a>

              <p>
                Convert geographic coordinates into readable location information for verification purposes.
              </p>
            </div>
          </div>

          ***

          <div>
            <div>
              <a href="/docs/api-reference/vrs/v2/kyc-links/generate-form-link">KYC Links</a>

              <p>
                Generate verification forms and manage KYC link status for digital customer onboarding.
              </p>
            </div>
          </div>
        </div>
      </div>
    </div>
  </Tab>

  <Tab title="Official documents">
    <div>
      <div>
        <div>
          <h4>Government documents</h4>

          <div>
            <div>
              <a href="/docs/api-reference/vrs/v2/driving-license/verify-driving-licence-details">Driving Licence</a>

              <p>
                Verify driving licence details including type, issue date, and expiry date.
              </p>
            </div>
          </div>

          ***

          <div>
            <div>
              <a href="/docs/api-reference/vrs/v2/passport/verify-passport">Passport Verification</a>

              <p>
                Verify passport information using file number to ensure identity authenticity.
              </p>
            </div>
          </div>

          ***

          <div>
            <div>
              <a href="/docs/api-reference/vrs/v2/voter-id/verify-voter-id">Voter ID</a>

              <p>
                Verify voter ID authenticity and retrieve constituency details using EPIC number.
              </p>
            </div>
          </div>

          ***

          <div>
            <div>
              <a href="/docs/api-reference/vrs/v2/vehicle-rc/get-vehicle-rc-details">Vehicle RC</a>

              <p>
                Retrieve vehicle registration certificate details for vehicle ownership verification.
              </p>
            </div>
          </div>

          ***

          <div>
            <div>
              <a href="/docs/api-reference/vrs/v2/udyam/verify-udyam">Udyam</a>

              <p>
                Verify Udyam information using Udyam reference number to ensure identity authenticity.
              </p>
            </div>
          </div>

          ***

          <div>
            <div>
              <a href="/docs/api-reference/vrs/v2/pan-to-udyam/fetch-udyam-with-pan">Udyam with PAN</a>

              <p>
                Fetch list of Udyam numbers associated with a PAN for business verification.
              </p>
            </div>
          </div>
        </div>
      </div>

      <div>
        <div>
          <h4>Business and employment</h4>

          <div>
            <div>
              <a href="/docs/api-reference/vrs/v2/cin/verify-cin">CIN Verification</a>

              <p>
                Retrieve company information including incorporation date, director details, and CIN status.
              </p>
            </div>
          </div>

          ***

          <div>
            <div>
              <a href="/docs/api-reference/vrs/v2/advanced-employment/get-employment-details">Employment Details</a>

              <p>
                Retrieve individual's employment details including member ID, joining date, and exit date.
              </p>
            </div>
          </div>

          ***

          <div>
            <div>
              <a href="/docs/api-reference/vrs/v2/pan-to-gstin/fetch-gstin-with-pan">GSTIN with PAN</a>

              <p>
                Fetch list of GSTIN numbers associated with a PAN for business verification.
              </p>
            </div>
          </div>
        </div>
      </div>
    </div>
  </Tab>
</Tabs>

## Getting started

Use the following resources to begin implementing Secure ID verification:

<CardGroup>
  <Card title="Product Documentation" href="/docs/secure-id/introduction" icon="book-open">
    Learn about Secure ID features, use cases, and implementation guides
  </Card>

  <Card title="SDKs and integration" href="/docs/api-reference/vrs/v2/sdk/verification-suite-server-sdks" icon="puzzle-piece">
    Download SDKs and follow step-by-step integration tutorials
  </Card>
</CardGroup>


# Bank Verification Async
Source: https://www.cashfree.com/docs/api-reference/vrs/v1/bank-account-verification/bank-verification-async

get /payout/v1/asyncValidation/bankDetails
Use this API to validate the given bank account number and IFSC. This is an async verification request.

<Warning> This API will be retired soon. Please plan to migrate to the latest version, [Bank Account Verification Async V2](/docs/api-reference/vrs/v2/bav-v2/bank-account-verification-async-v2). </Warning>


# Bank Verification Sync V1.2
Source: https://www.cashfree.com/docs/api-reference/vrs/v1/bank-account-verification/bank-verification-sync-v12

get /payout/v1.2/validation/bankDetails
Use this API to validate the given bank account number and IFSC. This is a sync verification request.

<Warning> This API will be retired soon. Please plan to migrate to the latest version, [Bank Account Verification Sync V2](/docs/api-reference/vrs/v2/bav-v2/bank-account-verification-sync-v2). </Warning>


# Bulk Bank Verification
Source: https://www.cashfree.com/docs/api-reference/vrs/v1/bank-account-verification/bulk-bank-verification

post /payout/v1/bulkValidation/bankDetails
Use this API to request bank validations in bulk. It is an asynchronous process.

<Warning> This API will be retired soon. Please plan to migrate to the latest version, [Bulk Bank Account Verification V2](/docs/api-reference/vrs/v2/bav-v2/bulk-bank-account-verification-v2). </Warning>


# Get Bulk Verification Status
Source: https://www.cashfree.com/docs/api-reference/vrs/v1/bank-account-verification/get-bulk-verification-status

get /payout/v1/getBulkValidationStatus
Use this API to get the status of bulk bank validation request by providing the bulkValidationId.

<Warning> This API will be retired soon. Please plan to migrate to the latest version, [Get Bulk BAV Status V2](/docs/api-reference/vrs/v2/bav-v2/get-bulk-bav-status-v2). </Warning>


# Get Verification Status
Source: https://www.cashfree.com/docs/api-reference/vrs/v1/bank-account-verification/get-verification-status

get /payout/v1/getValidationStatus/bank
Use this API to get the statuses of the bank validation request by providing the bvRefId or userId.

<Warning> This API will be retired soon. Please plan to migrate to the latest version, [Get BAV Status V2](/docs/api-reference/vrs/v2/bav-v2/get-bav-status-v2). </Warning>


# IFSC Verification
Source: https://www.cashfree.com/docs/api-reference/vrs/v1/bank-account-verification/ifsc-verification

get /payout/v1/ifsc/{ifsc}
Use this API to verify if a given IFSC exists. The bank name, the branch that it belongs to, the transfer modes supported, and the respective MICR code will be shown in the response.

<Warning> This API will be retired soon. Please plan to migrate to the latest version, [IFSC Verification V2](/docs/api-reference/vrs/v2/ifsc/ifsc-verification-v2). </Warning>


# Integration Overview
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/1-click-onboarding/1-click-onboarding-sdk

Integrate the Cashfree 1-Click Onboarding SDK in Android, iOS, or web apps to launch verification flows, manage sessions, and handle success or error callbacks.

The 1-Click Onboarding SDK simplifies user verification workflows for Android, iOS, and web applications. You can include a script tag, initialise the SDK with a session ID, and manage verification processes easily. Success and error callbacks handle responses, and you can close the SDK programmatically if needed.
This topic includes the following sections:

* [Integration](#integration)
* [Initializing SDK](#initializing-sdks)
* [Callback structure](#callback-structure)

## Integration

To integrate 1-Click Onboarding:

1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/verificationsuite/1-click-onboarding) and create a 1-Click Onboarding template.

2. Follow the workflow below:

   1. Verify user data using the [Data Availability API](/docs/api-reference/vrs/v2/1-click-onboarding/data-availability) to check user data availability using a mobile number. This step is mandatory.

   2. Initiate OAuth by calling the [Initiate OAuth API](/docs/api-reference/vrs/v2/1-click-onboarding/initiate-oauth) with the mobile number to obtain a `session_id` for opening the SDK.

   3. Collect user consent by opening the SDK using the `session_id`. Once the user provides consent, a callback returns an `auth_code`.

   4. Generate an access token using the auth\_code with the [OAuth Access Token Generation API](/docs/api-reference/vrs/v2/1-click-onboarding/oauth-access-token-generation) to get a token valid for one hour.

   5. Retrieve user details using the access token with the [Fetch User Details API](/docs/api-reference/vrs/v2/1-click-onboarding/fetch-user-details-from-access-token) to access user details.

Refer to the image below for a sample workflow:

<img />

## Initializing SDKs

The SDK communicates with Cashfree and provides updates via the callbacks. Initialize the applicable SDK from the options below:

* [Web](#web)
* [Android native](#android-native)
* [iOS native](#ios-native)

### Web

To initiate the web SDK, pass the `sessionId` and callback functions. Refer to the JavaScript example below:

```javascript theme={"dark"}
const cf = CF1ClickOnboarding({
  sessionId: newId,
  successCb: successCallback,
  errorCb: errorCallback,
  mode: "production" // default: "sandbox"
});

const successCallback = (data) => {
  console.log("Success: ", data);
};

const errorCallback = (error) => {
  console.error("Error: ", error);
};

// Close the SDK programmatically
cf.closeSDK();
```

#### Importing hosted JS SDK

Include the following SDK in your HTML document for the production environment:

```html theme={"dark"}
<script src="https://vssdk-prod.cashfree.com/vsvault/prod/1.0.0/index.js"></script>
```

<Note>
  To use the test environment, set `mode="sandbox"` in the `CF1ClickOnboarding` SDK. This is the default mode. To use the production environment, set `mode="production"`.
</Note>

Refer to the code snippet below for the HTML structure:

```html theme={"dark"}
<html>
  <head>
    <title>1-Click Onboarding</title>
    <script src="https://vssdk-prod.cashfree.com/vsvault/prod/1.0.0/index.js"></script>
  </head>
  <body>
    <div id="cf-sdk"></div>
  </body>
</html>
```

### Android native

To set up the Android native SDK:

1. Add the Maven repository to `settings.gradle.kts`:
   ```kotlin theme={"dark"}
   repositories {
       google()
       mavenCentral()
       maven { url = URI("https://maven.cashfree.com/release") }
   }
   ```
2. Add SDK dependency in `build.gradle.kts`:
   ```kotlin theme={"dark"}
   dependencies {
       implementation("com.cashfree.vrs:kyc-verification:1.0.1")
   }
   ```
3. Click **Sync Now** in Android Studio to sync the project.

To initialise and use the Android native SDK:

1. Create an instance of the verification service:
   ```kotlin theme={"dark"}
   val verificationService = CFVerificationService.Builder()
       .setContext(this) // Pass the context
       .build()
   ```
2. Configure the callback to handle verification responses, errors, and user drop scenarios:
   ```kotlin theme={"dark"}
   verificationService.set1ClickOnboardingCallback(object : CF1ClickOnboardingCallback {
       override fun onVerification(response: CF1ClickOnboardingResponse) {
           // Handle response
       }

       override fun onVerificationError(error: CF1ClickOnboardingErrorResponse) {
           // Handle error
       }

       override fun onUserDrop(error: CFUserDropResponse) {
           // Handle user drop
       }
   })
   ```
3. Initiate the 1-Click Onboarding SDK:
   ```kotlin theme={"dark"}
   verificationService.open1ClickOnboarding(sessionId, Environment.TEST)
   ```

It consists of the following parameters:

* **sessionId**: Unique session identifier.
* **Environment**: SDK environment. Possible values are:
  * `Environment.TEST`
  * `Environment.PROD`

### iOS native

To set up the iOS native SDK:

1. Add the SDK to your project by updating your `Podfile`:
   ```ruby theme={"dark"}
   pod 'KycVerificationSdk', '~> 1.0.2'
   ```
2. Run `pod install` to install the SDK.

To initialise and use the iOS native SDK:

1. Create an instance of the `CFVerificationService` class:
   ```swift theme={"dark"}
   let kycService = CFVerificationService.getInstance()
   ```
2. Set up callback handlers to manage events after verification processing. Implement the `CF1ClickOnboardingResponseDelegate` protocol to handle responses and errors:
   ```swift theme={"dark"}
   extension ViewController: CFResponseDelegate {
       func onVerification(_ verificationResponse: KycVerificationSdk.CF1ClickOnboardingResponse) {
           showErrorAlert(title: "Verification Success", message: verificationResponse.verificationId ?? "N/A")
       }

       func onVerificationError(_ errorResponse: KycVerificationSdk.CF1ClickOnboardingErrorResponse) {
           showErrorAlert(title: "Verification Error", message: errorResponse.status ?? "N/A")
       }

       func onUserDrop(_ userDropResponse: KycVerificationSdk.CFUserDropResponse) {
           showErrorAlert(title: "User Dropped", message: userDropResponse.verificationId ?? "N/A")
       }
   }
   ```
3. Initiate the 1-Click Onboarding SDK using the following code:
   ```swift theme={"dark"}
   do {
       let environment = Environment.PROD
       try kycService.open1ClickOnboarding(sessionId, environment, self, self)
   } catch let e {
       let error = e as! VerificationError
       print(error)
   }
   ```

It consists of the following parameters:

* **sessionId**: A unique identifier for the session.
* **environment**: Specifies the environment in which the SDK operates. Possible values are:
  * `Environment.TEST`
  * `Environment.PROD`

## Callback structure

Refer to the sample response below:

```json theme={"dark"}
{
  "verification_id": "verification_id_value",
  "auth_code": "auth_code_value",
  "status": "SUCCESS"
}
```

Refer to the table below for the possible statuses:

| Status | Description |
| - | - |
| SESSION\_EXPIRED | The session ID is invalid. |
| SESSION\_ID\_MISSING | No session ID is provided during initialization. |
| DIV\_MISSING | The `<div>` with ID `cf-sdk` is missing. |
| SUCCESS | The operation is completed successfully. |
| CLOSED | The SDK closes. |

<Note>
  **Notes**:

  * Ensure the `<div>` with ID `cf-sdk` exists in your HTML.

  * The SDK applies default styling for consistent behaviour; custom styling is not supported.

  * The iframe uses sandboxing for secure interactions.

  For detailed API documentation, refer to [1-Click Onboarding API](/docs/api-reference/vrs/v2/1-click-onboarding/data-availability) Integration.
</Note>


# Data Availability
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/1-click-onboarding/data-availability

post /user/data-availability
Use this API to check the availability of user data by passing the required details and retrieve data availability status. 

<Warning>
  The `available_scopes` values returned in the response have a validity period of 1 hour. Ensure that user consent is obtained and submitted within this timeframe. After expiration, you must make a new API call to retrieve updated scopes.
</Warning>


# Fetch User Details From Access Token
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/1-click-onboarding/fetch-user-details-from-access-token

get /oauth2/user-details
Use this API to retrieve user details by passing a valid access token fetched from the [OAuth Access Token Generation API](https://www.cashfree.com/docs/api-reference/vrs/v2/1-click-onboarding/oauth-access-token-generation#oauth-access-token-generation). 

This endpoint fetches the information associated with the authenticated user.



# Initiate OAuth
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/1-click-onboarding/initiate-oauth

post /oauth2/session
Use this API to initiate the OAuth process by passing the necessary credentials to obtain the session details, which will be used to initiate the SDK. 

<Note>
  **Notes**:

  * The session ID generated by this API is valid for 1 hour.
  * Get the X Client ID and X Client Secret from the [Merchant Dashboard](https://merchant.cashfree.com/verificationsuite/1-click-onboarding) when you create the app under the 1-Click section.
</Note>


# OAuth Access Token Generation
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/1-click-onboarding/oauth-access-token-generation

post /oauth2/generate-token
Use this API to generate an access token after the user completes the OAuth authentication process. This token is required to access user details once the user provides consent.
<Note> The X Client ID and X Client Secret mentioned in this API are obtained from the [Merchant Dashboard](https://merchant.cashfree.com/verificationsuite/1-click-onboarding) when creating the app under 1-Click section.</Note>



# Aadhaar Masking
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/aadhaar/aadhaar-masking

post /aadhaar-masking
Use this API to protect customer privacy by masking sensitive Aadhaar information. It masks the first 8 digits and disables QR codes, making Aadhaar cards safe to store in your database while maintaining compliance with data protection regulations. 

View the [test data](https://www.cashfree.com/docs/api-reference/vrs/data-to-test-integration#aadhaar-masking) and use the information to trigger the validations. The test data can be used only in the sandbox environment.

<Accordion title="Response codes">
  | Sub code | Status | Message | Next action |
  | - | - | - | - |
  | 200 | SUCCESS | VALID | - |
  | 200 | SUCCESS | INVALID\_DOCUMENT | Upload a valid copy of the aadhaar. |
  | 400 | ERROR | x-client-id is missing in the request | Enter all the header information in the API request. |
  | 400 | ERROR | image is missing in the request | Upload the image file of the aadhaar card that needs masking. |
  | 400 | ERROR | verification\_id can include only alphanum, dot, hyphen and underscores | Only alphanumeric, period (.), hyphen (-), and underscore ( \_ ) are allowed. |
  | 400 | ERROR | Client secret belongs to test environment | Enter the correct environment credentials in the request. |
  | 401 | ERROR | Invalid clientId and clientSecret combination | Enter valid client ID and secret key in the request. |
  | 403 | ERROR | IP not whitelisted your current IP is 106.51.91.104. For IP whitelisting assistance, visit our [IP Whitelisting guide](/docs/secure-id/get-started/integration/ip-whitelisting-verification) | Whitelist the IP address. |
  | 409 | ERROR | verification ID already exists | Enter a unique verification ID. |
  | 400 | ERROR | Provide a valid file or `file_url` | Upload a valid file type. |
  | 413 | ERROR | file size exceeded | The maximum file size should be 10 MB. |
  | 422 | ERROR | Insufficient balance to process this request. | Ensure you have sufficient balance and then process the request. |
  | 500 | ERROR | something went wrong | Try after some time. |
</Accordion>


# Get Employment Details
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/advanced-employment/get-employment-details

post /advance-employment
Use this API to to retrieve an individual's recent employment details. 

View the [test data](https://www.cashfree.com/docs/api-reference/vrs/data-to-test-integration#employment-information) and use the information to trigger the validations. The test data can be used only in the sandbox environment.



# Bank Account Verification Async V2
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/bav-v2/bank-account-verification-async-v2

post /bank-account/async
Use this API to verify bank account information. This asynchronous verification returns results via webhook or status polling. 


View the [test data](https://www.cashfree.com/docs/api-reference/vrs/data-to-test-integration#bank-numbers) and use the information to trigger the validations. The test data can be used only in the sandbox environment.

<Note>
  * Cashfree does not support the verification of Deutsche Bank and Paytm Payments Bank accounts.
  * For further queries, please refer to the [Bank Account Verification FAQs](/docs/secure-id/kyc-stack/verify-bank-account#faqs).
</Note>


# Bank Account Verification Sync V2
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/bav-v2/bank-account-verification-sync-v2

post /bank-account/sync
Use this API to perform real-time validation of bank account numbers and IFSC codes. This synchronous verification provides instant results for immediate account verification needs.

View the [test data](https://www.cashfree.com/docs/api-reference/vrs/data-to-test-integration#bank-numbers) and use the information to trigger the validations. The test data can be used only in the sandbox environment.

<Note>
  * Cashfree does not support the verification of Deutsche Bank and Paytm Payments Bank accounts.
  * For further queries, please refer to the [Bank Account Verification FAQs](/docs/secure-id/kyc-stack/verify-bank-account#faqs).
  * IMPS verifies only the first five characters of the IFSC code, which represent the bank. It does not verify the remaining six characters that identify the branch.
</Note>


# BAV Response Description
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/bav-v2/bav-response-description

Decode every Cashfree Bank Account Verification API response field, including account_status codes, name match scores, and bank identifier metadata.

## account\_status

It displays the status of the bank account.

| STATUS | DESCRIPTION |
| :- | :- |
| `VALID` | The account is successfully verified. |
| `INVALID` | The account is invalid. |
| `RECEIVED` | The transaction request has been successfully received and awaits processing or verification. |
| `FAILED` | The transaction failed due to an error or issue on the bank's side. |
| `REJECTED` | The transaction was rejected, typically due to issues such as insufficient funds. |
| `APPROVAL_PENDING` | This status indicates that the verification process is awaiting merchant approval of the submitted files to proceed further. |
| `PARTIALLY_APPROVED` | This status indicates that some of the submitted data or files have been approved for verification. |
| `IN_PROCESS` | This status indicates that the request is currently under validation, and the verification process is actively ongoing. |
| `CANCELLED` | This status indicates that the request was terminated by the user and will not proceed further. |
| `PROCESSING` | This status indicates that the request is being actively handled, and the system is working on completing the verification or transaction. |
| `MANUALLY_REJECTED` | This status indicates that the request was explicitly reviewed and rejected by a user. |

## account\_status\_code

| STATUS | DESCRIPTION |
| :- | :- |
| `ACCOUNT_IS_VALID` | Bank account has been successfully verified. |
| `FRAUD_ACCOUNT` | Fraudulent activity has been detected involving the bank account and IFSC. As a precautionary measure, both the account and IFSC have been blocked to prevent future transactions. To request unblocking, please contact your account manager or fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1). |
| `FAILED_AT_BANK` | The transaction failed due to an error or issue at the bank's end. |
| `NPCI_UNAVAILABLE` | The transaction could not be processed because the NPCI (National Payments Corporation of India) service is currently unavailable. |
| `CONNECTION_TIMEOUT` | The transaction failed due to a timeout while trying to establish a connection with the bank. |
| `SOURCE_BANK_DECLINED` | The transaction was declined by the source bank due to issues at their end. |
| `BENE_BANK_DECLINED` | The transaction was declined by the bene bank due to issues at their end. |
| `IMPS_MODE_FAIL` | The transaction failed because it could not be processed through the IMPS mode. |
| `BENEFICIARY_BANK_OFFLINE` | The transaction could not be processed because the beneficiary's bank is currently offline or unreachable. |
| `VALIDATION_IN_PROGRESS` | The transaction is currently being validated and is awaiting confirmation. |
| `INVALID_ACCOUNT_FAIL` | The transaction failed because the provided account details are invalid. |
| `INVALID_IFSC_FAIL` | The transaction failed because the provided IFSC code is invalid or incorrect. |
| `VERIFICATION_ALREADY_UNDER_PROCESS` | The verification is already in progress, and another verification request cannot be processed at this time. |
| `NRE_ACCOUNT_FAIL` | The transaction failed because the account is a Non-Resident External (NRE) account, which is not supported for this transaction type. |
| `ACCOUNT_BLOCKED` | The transaction failed because the account is blocked and cannot process transactions. |
| `INSUFFICIENT_BALANCE` | The transaction failed due to insufficient funds in the merchant account for processing the transaction. |

## name\_match\_result

It displays the result of the name match verification. Name match verification is done against the name provided in the request and the name associated with the bank account.

| STATUS | DESCRIPTION |
| :- | :- |
| `DIRECT_MATCH` | Indicates that the name provided in the request matches exactly with the name associated with the bank account. |
| `GOOD_PARTIAL_MATCH` | Indicates a strong similarity between the provided name and the name associated with the bank account, with minor differences. |
| `MODERATE_PARTIAL_MATCH` | Indicates a noticeable similarity between the provided name and the name associated with the bank account, but with more significant variations or missing details. |
| `POOR_PARTIAL_MATCH` | Indicates a weak similarity between the provided name and the name associated with the bank account, suggesting a potential mismatch but with some common elements. |
| `NO_MATCH` | Indicates that there is no recognisable similarity between the provided name and the name associated with the bank account, or the names are entirely different. |

Example of name\_match\_result.

| Given name | Name at bank | Match score | Match result | Account number |
| :- | :- | :- | :- | :- |
| JOHN DOE | john doe | 100.00 | DIRECT\_MATCH | 026291800001191 |
| JOHN DOE | john d | 85.00 | GOOD\_PARTIAL\_MATCH | 026291800001191 |
| JOHN DOE | j doe | 70.00 | MODERATE\_PARTIAL\_MATCH | 026291800001191 |
| JOHN DOE | jane d | 38.00 | POOR\_PARTIAL\_MATCH | 026291800001191 |
| TOM WELLS | tom wells | 100.00 | DIRECT\_MATCH | 1233943142 |
| TOM WELLS | tom w | 85.00 | GOOD\_PARTIAL\_MATCH | 1233943142 |
| TOM WELLS | t wells | 70.00 | MODERATE\_PARTIAL\_MATCH | 1233943142 |
| TOM WELLS | tim lee | 38.00 | POOR\_PARTIAL\_MATCH | 1233943142 |
| BOB HOPE | bob hope | 100.00 | DIRECT\_MATCH | 388108022658 |
| BOB HOPE | bob h | 85.00 | GOOD\_PARTIAL\_MATCH | 388108022658 |
| BOB HOPE | b hope | 70.00 | MODERATE\_PARTIAL\_MATCH | 388108022658 |
| BOB HOPE | bane hue | 38.00 | POOR\_PARTIAL\_MATCH | 388108022658 |


# Bulk Bank Account Verification V2
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/bav-v2/bulk-bank-account-verification-v2

post /bank-account/bulk
Use this API to verify bank account information in bulk.


View the [test data](https://www.cashfree.com/docs/api-reference/vrs/data-to-test-integration#bank-numbers) and use the information to trigger the validations. The test data can be used only in the sandbox environment.

<Note>
  * Cashfree does not support the verification of Deutsche Bank and Paytm Payments Bank accounts.
  * For further queries, please refer to the [Bank Account Verification FAQs](/docs/secure-id/kyc-stack/verify-bank-account#faqs).
</Note>


# Get BAV Status V2
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/bav-v2/get-bav-status-v2

get /bank-account
Use this API to check the status of your bank verification requests by passing reference ID or user ID to see if the validation is complete and get the results.

<Note>
  * Cashfree does not support the verification of Deutsche Bank and Paytm Payments Bank accounts.
  * For further queries, please refer to the [Bank Account Verification FAQs](/docs/secure-id/kyc-stack/verify-bank-account#faqs).
</Note>


# Get Bulk BAV Status V2
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/bav-v2/get-bulk-bav-status-v2

get /bank-account/bulk
Use this API to get the details of the bulk bank account verification request by passing either the bulk reference ID or bulk validation ID. If you want to get the status of a single entry, pass the particular reference ID in the request. 

<Note>
  * Cashfree does not support the verification of Deutsche Bank and Paytm Payments Bank accounts.
  * For further queries, please refer to the [Bank Account Verification FAQs](/docs/secure-id/kyc-stack/verify-bank-account#faqs).
</Note>


# Webhooks
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/bav-v2/webhooks-bank-account-verification

Subscribe to Cashfree async Bank Account Verification webhooks to receive penny drop and BAV result events when verification completes for users.

Webhooks are event-based notifications that are received when a specific event related to async bank account verification occurs.

<Warning>
  In rare cases, such as network retries, read timeouts, processing delays, or delivery failures, the same webhook might be sent more than once for the same event. To prevent unintended side effects, implement idempotency in your webhook handler to handle duplicate deliveries.
</Warning>

## Add webhooks

Add your webhook URL in our system for us to deliver webhook events.

Follow the instructions below to configure the webhook URL. Ensure to provide the publicly accessible HTTPS URL to your webhook endpoint.

1. Log in to the **[Merchant Dashboard](https://merchant.cashfree.com/merchants/)** and click **Developers**.
2. Click **Webhooks** listed under the **Secure ID** card.
3. Click **Add Webhook URL** in the **Webhook** screen.
4. In the **Add Webhook** popup, fill in the following information:
   * **Webhook URL**: Enter the URL in this field.
5. Click **Test & Add Webhook**.

<Frame>
  <img />
</Frame>

## Webhook event

The following events are triggered at different stages of the bank account verification process:

| Event | Description |
| :- | :- |
| BANK\_ACCOUNT\_VERIFICATION\_SUCCESS | Bank account verification is a success. |
| BANK\_ACCOUNT\_VERIFICATION\_REJECTED | Bank account verification is rejected. |
| BANK\_ACCOUNT\_VERIFICATION\_FAILED | Bank account verification is a failure. |

<AccordionGroup>
  <Accordion title="BANK_ACCOUNT_VERIFICATION_SUCCESS">
    ```json theme={"dark"}
    {
       "signature":"signature",    
       "event_type":"BANK_ACCOUNT_VERIFICATION_SUCCESS",    
       "event_time":"2023-07-19 10:46:16",
       "version":"v2",
       "data":{
            "reference_id": 1294785793,
            "user_id" : "123123",
            "name_at_bank": "John Doe",
            "amount_deposited": "1.04",
            "bank_name": "YES BANK",
            "utr": "404223241811",
            "city": "MUMBAI",
            "branch": "SANTACRUZ, MUMBAI",
            "micr": 400532038,
            "name_match_score": "90.00",
            "name_match_result": "GOOD_PARTIAL_MATCH",
            "account_status": "VALID",
            "account_status_code": "ACCOUNT_IS_VALID"
        }
    }
    ```
  </Accordion>

  <Accordion title="BANK_ACCOUNT_VERIFICATION_REJECTED">
    ```json theme={"dark"}
    {
       "signature":"signature",    
       "event_type":"BANK_ACCOUNT_VERIFICATION_REJECTED",    
       "event_time":"2023-07-19 10:46:16",
       "version":"v2",
       "data":{
            "reference_id": 1294785793,
            "user_id" : "123123",
            "account_status": "REJECTED",
            "account_status_code": "INSUFFICIENT_BALANCE"
        }
    }
    ```
  </Accordion>

  <Accordion title="BANK_ACCOUNT_VERIFICATION_FAILED">
    ```json theme={"dark"}
    {
       "signature":"signature",    
       "event_type":"BANK_ACCOUNT_VERIFICATION_FAILED",    
       "event_time":"2023-07-19 10:46:16",
       "version":"v2",
       "data":{
            "reference_id": 1294785793,
            "user_id" : "123123",
            "account_status": "FAILED",
            "account_status_code": "SOURCE_BANK_DECLINED"
        }
    }
    ```
  </Accordion>
</AccordionGroup>

## Webhook payload fields

The webhook payload contains important metadata in its top-level fields.

| Field | Type | Description |
| - | - | - |
| `signature` | `string` | A Base64-encoded HMAC-SHA256 signature of the payload, generated using a shared client secret. |
| `event_type` | `string` | Indicates the type of event that triggered the webhook. |
| `event_time` | `string` | The UTC timestamp of when the event occurred, formatted in ISO 8601 (`YYYY-MM-DDTHH:MM:SSZ`). |
| `version` | `string` | Indicates the webhook format being used. Default version is "v1". |
| `data` | `object` | Contains event-specific details related to this feature. |

## Signature Verification

Verifying the signature is mandatory before processing any response. It helps authenticate that the webhook is from Cashfree.

Follow the steps to verify the signature:

1. Sort the array based on keys.
2. Concatenate all the values in this array and the resultant is the post data (**postData**).
3. **postData** needs to be encrypted using SHA-256 and then base64 encoded.
4. Verify if both the signature calculated and the signature received match.
5. Proceed further only if the signatures match. If not, discard the request.
6. Ensure **clientSecret** you use is from the oldest active key pair.

For example, from the webhook received, extract the data and pass it to generate HMAC function:

```
{bank_account=026291800001191, ifsc=YESB0000262, upi=, name_at_bank=John Doe,
verification_id=fadsfdsf, ref_id=332, utr=332, status=SUCCESS,
added_on=2023-09-06T07:48:53+05:30, processed_on=2023-09-06 07:49:03,
penny_collected_on=2023-09-06 07:48:53}
```

```Text Java code - for reference theme={"dark"}
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.util.Map;
import java.util.TreeMap;

import com.fasterxml.jackson.core.type.TypeReference;
import com.fasterxml.jackson.databind.ObjectMapper;
import org.apache.commons.codec.binary.Base64;

public class ComputedSignature {
public static String generateHMAC(String clientSecret, String data) {
        String hash = null;
        ObjectMapper objectMapper = new ObjectMapper();
        try {
            Map<String, Object> jsonMap = objectMapper.readValue(data, new TypeReference<Map<String, Object>>() {
            });
            Map<String, Object> sortedMap = new TreeMap<>(jsonMap);

            // sort the map based on keys
            String postDataString = "";

            for (Map.Entry<String, Object> entry : sortedMap.entrySet()) {
                postDataString = postDataString + entry.getValue();
            }

            // encode the post data on sha256
            Mac sha256HMAC = Mac.getInstance("HmacSHA256");
            SecretKeySpec secretKey = new SecretKeySpec(clientSecret.getBytes(), "HmacSHA256");
            sha256HMAC.init(secretKey);

            hash = Base64.encodeBase64String(sha256HMAC.doFinal(postDataString.getBytes()));
        } catch (Exception e) {
            e.printStackTrace();

        }
        return hash;
    }
}

```

## IPs to whitelist

When you decide to consume the webhooks, first, you need to verify if your systems need an IP whitelisting to be done at your end or not. Accordingly you can whitelist the below IPs of Cashfree:

| Sandbox |
| :- |
| 52.66.25.127 |
| 15.206.45.168 |

| Prod |
| :- |
| 52.66.101.190 |
| 3.109.102.144 |
| 18.60.134.245 |
| 18.60.183.142 |

| Port |
| :- |
| 443 (secured) |


# Verify CIN
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/cin/verify-cin

post /cin
Use this API to retrieve information from Corporate Identification Number (CIN). 

View the [test data](https://www.cashfree.com/docs/api-reference/vrs/data-to-test-integration#cin) and use the information to trigger the validations. The test data can be used only in the sandbox environment.



# Create URL
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/digilocker/create-digilocker-url

post /digilocker
Use this API to create a DigiLocker URL to retrieve and verify Aadhaar, PAN, and driving-license information of your customer.



# DigiLocker Integration
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/digilocker/digilocker-integration

Integrate Cashfree DigiLocker APIs to fetch consent-based government documents such as Aadhaar, PAN, and driving licence for compliant customer onboarding.

Cashfree’s DigiLocker integration enables businesses to seamlessly retrieve and verify government-issued documents through DigiLocker.

This guide walks you through the steps to integrate Cashfree’s DigiLocker APIs into your application. With this integration, you can securely access user-consented documents such as Aadhaar, PAN, driving licence, and other records, improving onboarding speed and ensuring regulatory compliance.

<Note>DigiLocker access is strictly based on user consent and is compliant with the Digital Personal Data Protection Act (DPDPA), 2023.</Note>

## DigiLocker verification flow

Follow the steps below to verify your customers using DigiLocker:

<Note>
  The DigiLocker flow in the Sandbox environment requires real Aadhaar numbers and real-time DigiLocker data. Mock or test Aadhaar details aren't supported.
</Note>

### 1. Verify DigiLocker account

Use the [Verify Account API](/docs/api-reference/vrs/v2/digilocker/verify-digilocker-account) to check whether the user’s Aadhaar number or mobile number is linked with a DigiLocker account.

* If an account exists, continue with the sign-in flow.
* If not, continue with the sign-up flow.

### 2. Generate DigiLocker link

Use the [Create URL API](/docs/api-reference/vrs/v2/digilocker/create-digilocker-url) to generate a DigiLocker consent URL.

* Cashfree returns a unique, time-sensitive URL for DigiLocker login and document-consent sharing.
* The URL is valid for 10 minutes from the time of generation.

### 3. Redirect to consent URL

* Redirect the customer to the DigiLocker URL (in browser or WebView).
* The customer logs in using their Aadhaar number or Aadhaar-linked mobile number and enters the OTP.
* On successful login, DigiLocker shows a consent screen.
* The user reviews and approves the document-sharing request.

### 4. Check verification status

Use the [Get Verification Status API](/docs/api-reference/vrs/v2/digilocker/get-digilocker-verification-status) with the `verification_id` or `reference_id` to retrieve the current status.

Possible status values:

* `PENDING`: User hasn't completed the verification process.
* `AUTHENTICATED`: User has logged in and given consent.
* `EXPIRED`: Link expired before the process was completed.
* `CONSENT_DENIED`: When user rejects or denies consent.

### 5. Retrieve document

Once the user has successfully logged in and provided consent, call the [Get Document API](/docs/api-reference/vrs/v2/digilocker/get-document-from-digilocker) to fetch verified documents like Aadhaar, PAN, or driving license.

## Aadhaar via DigiLocker flow

The Aadhaar via DigiLocker flow allows businesses to securely retrieve Aadhaar documents by verifying users through their DigiLocker accounts. Follow the below steps to fetch the required details:

1. The user selects Aadhaar via DigiLocker on the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
2. The user enters their Aadhaar number.
3. The system checks if a DigiLocker account exists using the [Verify Account API](/docs/api-reference/vrs/v2/digilocker/verify-digilocker-account).
   * If account exists → Sign-in flow.
   * If not → Sign-up flow.

<Tip>
  * **Sign-up flow**: This is a PIN-based flow where the user must set a DigiLocker PIN. If the DigiLocker account already exists, the user is required to enter their existing PIN.
  * **Sign-in flow**: Also referred to as the PIN-less flow, where the user can complete the login using only an OTP.
</Tip>

### Sign-in flow

The sign-in flow enables users with an existing DigiLocker account to log in using their Aadhaar-linked credentials and provide consent to share documents. Steps are as follows:

1. Call the `Create URL API` to generate the login consent link.
2. User logs in using Aadhaar and OTP.
3. User provides consent on DigiLocker.
4. Use `Get Verification Status API` to confirm.
5. Retrieve Aadhaar data using the `Get Document API`.

<CardGroup>
  <Card />

  <Card />

  <Card />
</CardGroup>

### Sign-up flow

The sign-up flow guides users without an existing DigiLocker account to create one, set a PIN, and provide consent to share their Aadhaar documents. Steps are as follows:

1. Call the `Create URL API` to generate sign-up consent link.
2. User lands on the Digilocker page and enters the OTP.
3. User sets DigiLocker PIN in case of new account is being created and if account exists, user resets PIN via OTP.
4. User provides document-sharing consent.
5. Use `Get Verification Status API` to confirm.
6. Retrieve Aadhaar document using the `Get Document API`.

<CardGroup>
  <Card />

  <Card />

  <Card />

  <Card />
</CardGroup>

## Webhook support

You will receive [webhooks](/docs/api-reference/vrs/v2/digilocker/webhooks-digilocker) for every stage of the DigiLocker verification lifecycle, including status updates and completion callbacks.

## Summary

Provides a summary of all APIs involved in the flow:

| Step | API used | Description |
| - | - | - |
| 1 | Verify Account API | Checks if Aadhaar is linked with DigiLocker |
| 2 | Create URL API | Generates DigiLocker consent URL |
| 3 | Get Verification Status API | Checks status: PENDING, AUTHENTICATED, EXPIRED, CONSENT\_DENIED |
| 4 | Get Document API | Fetches verified user documents |

## Edge cases

Provides a summary of edge cases involved in the flow:

| **Step** | **Edge case** | **Scenario** | **Root cause** | **Resolution** |
| - | - | - | - | - |
| 1 | **`eaadhaar` not available in DigiLocker** | The `eaadhaar` field in the API response returns 'N'. | Indicates that the user’s Aadhaar document isn't currently available in their DigiLocker account. | Instruct the user to log in to DigiLocker and complete their profile by linking their Aadhaar. Once linked, fetch the document using the [Get Document API](/docs/api-reference/vrs/v2/digilocker/get-document-from-digilocker). |
| 2 | **`Can be accessed` label appears on consent screen** | The DigiLocker consent screen displays the label `Can be accessed` next to a document. | Indicates that the document isn't currently present in the user’s DigiLocker. This status implies that while the document is eligible to be linked, it hasn't yet been fetched or issued to the account. | Instruct the user to log in to DigiLocker and link the issued document manually from the issuing authority. Once linked, retrieve the document using the [Get Document API](/docs/api-reference/vrs/v2/digilocker/get-document-from-digilocker). |

<Frame>
  <img />
</Frame>


# React Native Integration
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/digilocker/digilocker-sdk

Integrate the Cashfree DigiLocker React Native SDK to fetch government-issued Aadhaar, PAN, and Driving Licence documents with consent flows.

Cashfree’s react native DigiLocker SDK allows you to seamlessly integrate DigiLocker-based identity verification into your mobile application. With this SDK, you can securely initiate DigiLocker flows, collect user consent, and retrieve verified government-issued documents.

This guide provides step-by-step instructions to help you:

* Install and configure the React Native SDK.
* Generate DigiLocker consent URLs from your backend.
* Launch DigiLocker in your React Native app.
* Handle consent flows and user responses.
* Fetch and verify user documents via secure APIs.

<Note>
  All sensitive operations such as generating DigiLocker URLs and retrieving documents, must be performed on your backend server. Don't call these APIs directly from your frontend or mobile application.
</Note>

## Setting up SDK

The React Native SDK is hosted on [npm](https://www.npmjs.com/). You can get the latest SDK [here](https://www.npmjs.com/package/@cashfreepayments/react-native-digilocker).

Our React Native SDK supports Android SDK version 19 and above and iOS minimum deployment target of 10.3 and above.

Navigate to your project and run the following command:

<CodeGroup>
  ```npm npm theme={"dark"}
  npm install @cashfreepayments/react-native-digilocker
  ```

  ```yarn yarn theme={"dark"}
  yarn add @cashfreepayments/react-native-digilocker 
  ```
</CodeGroup>

For iOS, you need to install pods:

```
cd ios && pod install
```

### Step 1: Create DigiLocker URL

To initiate the DigiLocker integration flow, your application must generate a DigiLocker consent URL.

This action must be performed from your backend server, as it requires authentication using your Client Secret. Don't call this API directly from your frontend or mobile application.

Once the DigiLocker URL is successfully generated, the API returns a unique reference\_id. Either this reference\_id or the verification\_id passed by you can be used in all the subsequent API calls.

You can view the complete request and response examples in the [Create DigiLocker URL](/docs/api-reference/vrs/v2/digilocker/create-digilocker-url) API reference.

### Step 2: Opening the DigiLocker SDK

Once the DigiLocker URL is created, the next step is to open the DigiLocker URL so the user can give the consent. The React Native SDK offer below digilocker redirection flow:

#### Initialise app

```jsx theme={"dark"}
import { DigiLockerProvider } from '@cashfreepayments/react-native-digilocker';

function App() {
  return (
    <DigiLockerProvider >
      {/* Your app content */}
    </DigiLockerProvider>
  );
}
```

### Step 3: Call verify function to initiate DigiLocker flow

```ts theme={"dark"}
const { verify } = useDigiLocker(); 

verify(
  url: string,                    // DigiLocker URL to load
  redirectUrl?: string,           // Optional redirect URL (default: 'https://verification.cashfree.com/dgl/status')
  options?: {
    userFlow?: 'signin' | 'signup';      // Optional user flow type (restricted to 'signin' or 'signup')
    onSuccess?: (data: any) => void;     // Success callback
    onError?: (error: string) => void;   // Error callback
    onCancel?: () => void;               // Cancel callback
  }
);
```

**Success callback**

```javascript theme={"dark"}
{
  success: true,
  redirect_url: 'https://example.com/thank-you?verification_id=123'
}
```

You can view the example implementation in the [DigiLocker React Native SDK](https://github.com/cashfree/react-native-digilocker/blob/master/example/src/App.tsx) GitHub repository.

### Step 4: Check verification status

Use the [Get Verification Status API](/docs/api-reference/vrs/v2/digilocker/get-digilocker-verification-status) with the `verification_id` received in the success callback to retrieve the current verification status.

### Step 5: Retrieve document

Once the user has successfully logged in and provided consent, call the [Get Document API](/docs/api-reference/vrs/v2/digilocker/get-document-from-digilocker) to fetch verified documents like Aadhaar, PAN, or driving license.

<Warning>Steps 4 and 5 must be performed from your backend server. Don't call this APIs directly from your frontend or mobile application.</Warning>


# Get Verification Status
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/digilocker/get-digilocker-verification-status

get /digilocker
Use this API to fetch the current status of a DigiLocker verification request by passing either the `verification_id` used during DigiLocker URL creation or the `reference_id` returned in the Cashfree response.



# Get Document
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/digilocker/get-document-from-digilocker

get /digilocker/document/{document_type}
Use this API to get your customer's document details from from DigiLocker after successful grant of consent.

<Note>Currently we do not support downloading of full documents through Digilocker API. This feature will be added in the future enhancements.</Note>


# Verify Account
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/digilocker/verify-digilocker-account

post /digilocker/verify-account
Use this API to verify whether a mobile number or Aadhaar number is already registered with DigiLocker. 


View the [test data](https://www.cashfree.com/docs/api-reference/vrs/data-to-test-integration#digilocker-verify-account) and use the information to trigger the validations. The test data can be used only in the sandbox environment.



# DigiLocker Webhooks
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/digilocker/webhooks-digilocker

Receive Cashfree DigiLocker webhooks for consent grants, document fetches, and verification completion so your backend can update KYC records automatically.

Webhooks are event-based notifications that are received when a specific event related to the DigiLocker verification occurs.

<Warning>
  In rare cases, such as network retries, read timeouts, processing delays, or delivery failures, the same webhook might be sent more than once for the same event. To prevent unintended side effects, implement idempotency in your webhook handler to handle duplicate deliveries.
</Warning>

## Add webhooks

Add your webhook URL in our system for us to deliver webhook events.

Follow the instructions below to configure the webhook URL. Ensure to provide the publicly accessible HTTPS URL to your webhook endpoint.

1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/merchants/) and click **Developers**.
2. Click **Webhooks** listed under the **Secure ID** card.
3. Click **Add Webhook URL** in the **Webhook** screen.
4. In the **Add Webhook** popup, enter the webhook URL.
5. Click **Test & Add Webhook**.

<Frame>
  <img />
</Frame>

## Webhook event

| Event type | Description |
| :- | :- |
| `DIGILOCKER_VERIFICATION_SUCCESS` | Triggered when the user's DigiLocker verification is successfully completed. |
| `DIGILOCKER_VERIFICATION_LINK_EXPIRED` | Triggered when the DigiLocker URL expires due to user inaction. |
| `DIGILOCKER_VERIFICATION_CONSENT_DENIED` | Triggered when the user denies consent for DigiLocker verification. |
| `DIGILOCKER_VERIFICATION_CONSENT_EXPIRED` | Triggered when the user's document consent for DigiLocker verification expires, which occurs 1 hour after the user grants consent. |
| `DIGILOCKER_VERIFICATION_FAILURE` | Triggered when the DigiLocker verification fails due to a system error. |

### Sample webhook events

The following events are triggered at different stages of the DigiLocker verification process:

<AccordionGroup>
  <Accordion title="DIGILOCKER_VERIFICATION_SUCCESS">
    ```json theme={"dark"}
    {
       "event_type":"DIGILOCKER_VERIFICATION_SUCCESS",
       "event_time":"2006-01-02T15:04:05Z",
       "version":"v1",
       "data":{
            "user_details": {
                "name": "John Doe",
                "dob": "02-02-1995",
                "gender": "M",
                "eaadhaar": "Y",
                "mobile": "9999999999"
            },
            "status": "AUTHENTICATED",
            "document_requested": [
                "AADHAAR",
                "PAN",
                "DRIVING_LICENSE"
            ],
            "document_consent": [
                "AADHAAR",
                "PAN",
                "DRIVING_LICENSE"
            ],
            "document_consent_validity": "2025-09-30T07:10:00Z",
            "verification_id": "ABC00123",
            "reference_id": 12345
        }
    }
    ```
  </Accordion>

  <Accordion title="DIGILOCKER_VERIFICATION_LINK_EXPIRED">
    ```json theme={"dark"}
    {
       "event_type":"DIGILOCKER_VERIFICATION_LINK_EXPIRED",
       "event_time":"2006-01-02T15:04:05Z",
       "version":"v1",
       "data":{
            "user_details": {},
            "status": "EXPIRED",
            "document_requested": [
                "AADHAAR"
            ],
            "document_consent": null,
            "document_consent_validity": null,
            "verification_id": "ABC00123",
            "reference_id": 12345
        }
    }
    ```
  </Accordion>

  <Accordion title="DIGILOCKER_VERIFICATION_CONSENT_DENIED">
    ```json theme={"dark"}
    {
       "event_type":"DIGILOCKER_VERIFICATION_CONSENT_DENIED",
       "event_time":"2006-01-02T15:04:05Z",
       "version":"v1",
       "data":{
            "user_details": {},
            "status": "CONSENT_DENIED",
            "document_requested": [
                "AADHAAR"
            ],
            "document_consent": null,
            "document_consent_validity": null,
            "verification_id": "ABC00123",
            "reference_id": 12345
        }
    }
    ```
  </Accordion>

  <Accordion title="DIGILOCKER_VERIFICATION_CONSENT_EXPIRED">
    ```json theme={"dark"}
    {
       "event_type":"DIGILOCKER_VERIFICATION_CONSENT_EXPIRED",
       "event_time":"2006-01-02T15:04:05Z",
       "version":"v1",
       "data":{
            "user_details": {
                "name": "John Doe",
                "dob": "02-02-1995",
                "gender": "M",
                "eaadhaar": "Y",
                "mobile": "9999999999"
            },
            "status": "AUTHENTICATED",
            "document_requested": [
                "AADHAAR",
                "PAN",
                "DRIVING_LICENSE"
            ],
            "document_consent": [
                "AADHAAR",
                "PAN",
                "DRIVING_LICENSE"
            ],
            "document_consent_validity": "2025-09-30T07:10:00Z",
            "verification_id": "ABC00123",
            "reference_id": 12345
        }
    }
    ```
  </Accordion>

  <Accordion title="DIGILOCKER_VERIFICATION_FAILURE">
    ```json theme={"dark"}
    {
       "event_type":"DIGILOCKER_VERIFICATION_FAILURE",
       "event_time":"2006-01-02T15:04:05Z",
       "version":"v1",
       "data":{
            "user_details": {},
            "status": "FAILURE",
            "document_requested": [
                "AADHAAR"
            ],
            "document_consent": null,
            "document_consent_validity": null,
            "verification_id": "ABC00123",
            "reference_id": 12345
        }
    }
    ```
  </Accordion>
</AccordionGroup>

## Webhook signature

You will receive the webhook signature in the webhook header. Here is a sample header from a webhook request.

| Header name | Header value |
| - | :-: |
| content-length | 1099 |
| x-webhook-attempt | 1 |
| content-type | application/json |
| x-webhook-signature | 07r5C3VMwsGYeldGOCYxe5zoHhIN1zLfa8O0U/yngHI= |
| x-webhook-timestamp | 1746427759733 |

<Tip> Always capture the webhook payload in its raw text format before parsing into JSON. Parsing and re-serialising the payload can change the structure (for example, array ordering, spacing, or `null` handling) and cause a signature mismatch during verification. Use the exact raw body string from the request when computing the signature.</Tip>

## Webhook payload fields

The webhook payload contains important metadata in its top-level fields.

| Field | Type | Description |
| - | - | - |
| `event_type` | `string` | Indicates the type of event that triggered the webhook. |
| `event_time` | `string` | The UTC timestamp of when the event occurred, formatted in ISO 8601 (`YYYY-MM-DDTHH:MM:SSZ`). |
| `version` | `string` | Indicates the webhook format being used. Default version is "v1". |
| `data` | `object` | Contains event-specific details related to this feature. |

<Note>
  Verifying the signature is mandatory before processing any response. Refer to [Signature Verification](/docs/api-reference/vrs/webhook-signature-verification) for more details.
</Note>


# Authentication
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/docs/authentication

Authenticate Cashfree Secure ID API calls by fetching bearer tokens, attaching them to every request, and following the general header instructions.

Calling the Authentication APIs allows you to get and verify bearer tokens returned by Cashfree. We require this token for all further communication.

<Note>
  We do not support connected fund source accounts with respect to the Secure ID products.
</Note>

## General instructions

* Cashfree's libraries automatically call the Authorize API and internally store the token.
* Do not store the token in an insecure manner.
* Regenerating a new token does not invalidate the already generated token.
* Token generated from one IP address cannot be used from a different IP.
* Token generated is valid for 600 seconds. Please ensure that you recall the authorize API once the token has expired.

## IP Whitelisting and Public Key

Whitelist your IP address. Follow the instructions listed here to whitelist your IP address.

To add the public key in the code snippet, ensure you read the file directly and not copy paste it. Copy pasting the public key turns out to be erroneous.


# Verify Driving Licence Details
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/driving-license/verify-driving-licence-details

post /driving-license
Use this API to verify whether a driving licence is valid. If the licence is valid, the associated details are sent in the response.

View the [test data](https://www.cashfree.com/docs/api-reference/vrs/data-to-test-integration#driving-licence) and use the information to trigger the validations. The test data can be used only in the sandbox environment.



# Create E-Sign Request
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/e-sign/create-e-sign-request

post /esignature
Use this API to create signature request by passing the signer(s) details and document ID that is received as a response in [Upload Document API](https://www.cashfree.com/docs/api-reference/vrs/v2/e-sign/upload-document-for-e-sign#upload-document-for-e-sign).



# Get E-Sign Status
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/e-sign/get-e-sign-status

get /esignature
Use this API to get the status of the initiated e-sign verification by passing the verification ID or reference ID that is received as a response in [Create E-Sign request API](https://www.cashfree.com/docs/api-reference/vrs/v2/e-sign/create-e-sign-request).



# Upload Document For E-Sign
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/e-sign/upload-document-for-e-sign

post /esignature/document
Use this API to upload the document before creating the request for E-Sign. The document ID received in the response of this API is required to create the request for E-Sign.



# Webhooks
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/e-sign/webhooks-esign

Configure Cashfree e-Sign webhooks to receive notifications when documents are signed, declined, expired, or completed during Aadhaar-based electronic signing.

Webhooks are event-based notifications that are received when a specific event related to the e-sign verification occurs.

<Warning>
  In rare cases, such as network retries, read timeouts, processing delays, or delivery failures, the same webhook might be sent more than once for the same event. To prevent unintended side effects, implement idempotency in your webhook handler to handle duplicate deliveries.
</Warning>

## Add webhooks

Add your webhook URL in our system for us to deliver webhook events.

Follow the instructions below to configure the webhook URL. Ensure to provide the publicly accessible HTTPS URL to your webhook endpoint.

1. Log in to the **[Merchant Dashboard](https://merchant.cashfree.com/merchants/)** and click **Developers**.
2. Click **Webhooks** listed under the **Secure ID** card.
3. Click **Add Webhook URL** in the **Webhook** screen.
4. In the **Add Webhook** popup, fill in the following information:
   * **Webhook URL**: Enter the URL in this field.
5. Click **Test & Add Webhook**.

<Frame>
  <img />
</Frame>

***

## Webhook events

| Event | Description |
| :- | :- |
| E\_SIGN\_VERIFICATION\_SUCCESS | You will receive this event when the e-sign verification is a success. |
| E\_SIGN\_VERIFICATION\_FAILURE | You will receive this event when the e-sign verification is a failure. |
| E\_SIGN\_VERIFICATION\_EXPIRED | You will receive this event when the e-sign verification is expired. |

The following events are triggered at different stages of the e-sign verification process:

<AccordionGroup>
  <Accordion title="E_SIGN_VERIFICATION_SUCCESS">
    ```json theme={"dark"}
    {
       "event_type":"ESIGN_VERIFICATION_SUCCESS", 
       "event_time":"2023-07-19 10:46:16",
       "version":"v1",
       "data": {
            "status": "SUCCESS",
            "reference_id": 32,
            "verification_id": "ABC00123",
            "document_id": 36,
            "signers": [
              {
                "name": "John Doe",
                "status": "SUCCESS",
                "is_notified": true
              },
              {
                "name": "Frank Kelvin",
                "status": "SUCCESS",
                "is_notified": true
              }
            ],
            "signed_doc_url": "SIGNED_DOC_URL"
        }
    }
    ```
  </Accordion>

  <Accordion title="E_SIGN_VERIFICATION_FAILURE">
    ```json theme={"dark"}
    {
       "event_type":"ESIGN_VERIFICATION_FAILURE", 
       "event_time":"2023-07-19 10:46:16",
       "version":"v1",
       "data": {
            "status": "FAILURE",
            "reference_id": 32,
            "verification_id": "ABC00123",
            "document_id": 36,
            "signers": [
              {
                "name": "John Doe",
                "status": "SUCCESS",
                "is_notified": true
              },
              {
                "name": "Frank Kelvin",
                "status": "FAILURE",
                "is_notified": false
              }
            ],
            "signed_doc_url": "SIGNED_DOC_URL"
        }
    }
    ```
  </Accordion>

  <Accordion title="E_SIGN_VERIFICATION_EXPIRED">
    ```json theme={"dark"}
    {
       "event_type":"ESIGN_VERIFICATION_EXPIRED", 
       "event_time":"2023-07-19 10:46:16",
       "version":"v1",
       "data": {
            "status": "EXPIRED",
            "reference_id": 32,
            "verification_id": "ABC00123",
            "document_id": 36,
            "signers": [
              {
                "name": "John Doe",
                "status": "EXPIRED",
                "is_notified": true
              },
              {
                "name": "Frank Kelvin",
                "status": "RECEVIED",
                "is_notified": false
              }
            ],
            "signed_doc_url": ""
        }
    }
    ```
  </Accordion>
</AccordionGroup>

## Webhook signature

You will receive the webhook signature in the webhook header. Here is a sample header from a webhook request.

| Header name | Header value |
| - | :-: |
| content-length | 1099 |
| x-webhook-attempt | 1 |
| content-type | application/json |
| x-webhook-signature | 07r5C3VMwsGYeldGOCYxe5zoHhIN1zLfa8O0U/yngHI= |
| x-webhook-timestamp | 1746427759733 |

<Tip> Always capture the webhook payload in its raw text format before parsing into JSON. Parsing and re-serialising the payload can change the structure (for example, array ordering, spacing, or `null` handling) and cause a signature mismatch during verification. Use the exact raw body string from the request when computing the signature.</Tip>

## Webhook payload fields

The webhook payload contains important metadata in its top-level fields.

| Field | Type | Description |
| - | - | - |
| `event_type` | `string` | Indicates the type of event that triggered the webhook. |
| `event_time` | `string` | The UTC timestamp of when the event occurred, formatted in ISO 8601 (`YYYY-MM-DDTHH:MM:SSZ`). |
| `version` | `string` | Indicates the webhook format being used. Default version is "v1". |
| `data` | `object` | Contains event-specific details related to this feature. |

<Note>
  Verifying the signature is mandatory before processing any response. Refer to [Signature Verification](/docs/api-reference/vrs/webhook-signature-verification) for more details.
</Note>


# End Points
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/end-point

Verify customer bank accounts, PAN, GSTIN, and other KYC identifiers using the Cashfree Verification Suite APIs, covering required parameters, and success and error responses.

Cashfree uses API keys to allow access to the API. Once you have signed up at our merchant site, you will be able to see your AppId and SecretKey.

Cashfree expects API key to be included in all API requests to the server. Use the endpoint /api/v1/credentials/verify to verify your credentials.

## End Points

| Environment | URL |
| :- | :- |
| Production | [https://api.cashfree.com/verification](https://api.cashfree.com/verification) |
| Test | [https://sandbox.cashfree.com/verification](https://sandbox.cashfree.com/verification) |

***

## Test data

View the [test data](/docs/api-reference/vrs/data-to-test-integration) and use this information to trigger the validations. The test data are usable only in the test environments such as gamma and sandbox, which are mentioned above.

***

## Signature Verification

Cashfree sends a signature alongside every webhook, verifying this signature ( passed along with the POST parameters ) is mandatory before processing any response. It helps authenticate that the webhook is from Cashfree.

We strongly recommend whitelisting Cashfree production IP to help make your communication with us more secure.

Following are the steps to verify Cashfree signature:

1. Get all the POST parameters except ‘signature’ and assign it to an array as key-value pair.
2. Sort the array based on keys.
3. Concatenate all the values in this array and resultant is the post data (**postData**).
4. **postData** needs to be encrypted using SHA-256 and then base64 encoded.
5. Proceed further only if the signatures match. If not, discard the request.


# Face Liveness Check
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/face-liveness/face-liveness

post /face-liveness
Use this API to check whether a submitted image contains a real human face. The API analyses facial characteristics and liveness signals to prevent spoofing attempts and validate genuine user presence and returns comprehensive facial analysis.

View the [test data](https://www.cashfree.com/docs/api-reference/vrs/data-to-test-integration#face-liveness) and use the information to trigger the validations.



# Face Match
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/face-match/face-match

post /face-match
Use this API to match the facial features of your customer in one image with another. You can compare an image with another image or with an image in an ID.

View the [test data](https://www.cashfree.com/docs/api-reference/vrs/data-to-test-integration#face-match) and use the information to trigger the validations. The test data can be used only in the sandbox environment.



# Generate KYC Link
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/generate-form-link

post /form
Use this API to generate a verification form to verify the KYC information of your users digitally.



# Geocoding
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/geocoding/geocoding

post /geocoding
Use this API to convert a physical address into geographic coordinates (latitude and longitude). This helps verify location accuracy, enable map integrations, calculate distances, and support location-based services.

View the [test data](https://www.cashfree.com/docs/api-reference/vrs/data-to-test-integration#geocoding) and use the information to trigger the validations. The test data can be used only in the sandbox environment.



# Get KYC Link Status
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/get-form-status

get /form
Use this API to get the status of the KYC link by passing `verification_id` or `reference_id` to get the KYC Link status.



# Verify GSTIN
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/gstin/verify-gstin

post /gstin
Use this API to verify whether the GSTIN information is valid. If the GSTIN is valid, the associated details are sent in the response.

View the [test data](https://www.cashfree.com/docs/api-reference/vrs/data-to-test-integration#gstin) and use the information to trigger the validations. The test data can be used only in the sandbox environment.



# IFSC Verification V2
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/ifsc/ifsc-verification-v2

post /ifsc
Use this API to verify whether the IFSC information passed in the request is valid.

View the [test data](/docs/api-reference/vrs/data-to-test-integration#bank-numbers) and use the information to trigger the validations. The test data can be used only in the sandbox environment.



# Verify IP
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/ip/verify-ip

post /ip
Use this API to fetch the details of the IP passed in the request.

View the [test data](https://www.cashfree.com/docs/api-reference/vrs/data-to-test-integration#ip-address) and use the information to trigger the validations. The test data can be used only in the sandbox environment.

<Accordion title="Response codes">
  | Sub code | Status | Message | Next action |
  | - | - | - | - |
  | 200 | SUCCESS | VALID | - |
  | 400 | ERROR | x-client-id is missing in the request. | Enter all the header information in the request. |
  | 400 | ERROR | verification\_id already exists. | Enter a unique verification ID to identify the request. |
  | 400 | ERROR | Client secret belongs to test environment | Enter the correct environment credentials in the request. |
  | 400 | ERROR | please enter a valid IP address | Enter a valid IP address in the request. |
  | 401 | ERROR | Invalid clientId and clientSecret combination | Ensure you enter valid x-client-id and x-client-secret information in the API request. |
  | 403 | ERROR | IP not whitelisted your current IP is 106.51.91.104. For IP whitelisting assistance, visit our [IP Whitelisting guide](/docs/secure-id/get-started/integration/ip-whitelisting-verification) | Whitelist the IP address. |
  | 404 | ERROR | unable to find IP details | Enter a valid IP address in the request. |
  | 422 | ERROR | Insufficient balance to process this request | Try again with sufficient balance. |
  | 500 | ERROR | something went wrong, please try after some time | Try again after some time. |
</Accordion>


# Deactivate Static KYC Link
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/kyc-links/deactivate-static-link

delete /form/static-link
Use this API to deactivate a static KYC Link.



# Generate KYC Link
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/kyc-links/generate-form-link

post /form
Use this API to generate a verification form to verify the KYC information of your users digitally.



# Generate Static KYC Link
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/kyc-links/generate-static-link

post /form/static-link
Use this API to generate a static KYC link to verify the KYC information of the users digitally. Using the generated single static link, multiple users can be verified which share same verification journey.



# Get KYC Link Status
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/kyc-links/get-form-status

get /form
Use this API to get the status of the KYC link by passing `verification_id` or `reference_id` to get the KYC Link status.



# Get Status
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/kyc-links/get-status

Look up status endpoints for every Cashfree Secure ID verification, from bank account checks to Aadhaar, PAN, e-Sign, and DigiLocker workflows.

## Bank account verification V2

Find the APIs to check the status of bank account verification V2 requests:

| API | Description |
| :- | :- |
| [Get BAV Status V2](/docs/api-reference/vrs/v2/bav-v2/get-bav-status-v2) | Use this API to get the details of the bank account verification request. You need to enter either the reference ID or user ID. |
| [Get Bulk BAV Status V2](/docs/api-reference/vrs/v2/bav-v2/get-bulk-bav-status-v2) | Use this API to get the details of the bulk bank account verification request. You need to enter either the bulk reference ID or bulk validation ID. If you want to get the status of a single entry, enter the particular reference ID in the request. |

## PAN

Find the APIs to check the status of the PAN verification requests:

| API | Description |
| :- | :- |
| [Get Status of Verify PAN Sync](/docs/api-reference/vrs/v2/pan/get-status-of-verify-pan-sync) | Use this API to get the verification status of the Verify PAN Sync API. You need to enter the reference ID to get the verification status. |
| [Get Status for Verify PAN in Bulk](/docs/api-reference/vrs/v2/pan/get-status-for-verify-pan-in-bulk) | Use this API to get the status of the Verify PAN in Bulk API request. You need to enter either the reference ID or bulk verification ID. |
| [Get Status of PAN Verification via OCR](/docs/api-reference/vrs/v2/smart-ocr/smart-ocr) | Use this API to get the status of the created PAN Verification via OCR request. You need to enter either the reference ID or verification ID to get the status. |

## Aadhaar

Finds the APIs to check the status of the aadhaar verification requests:

| API | Description |
| :- | :- |
| [Get Status of Aadhaar Verification via OCR](/docs/api-reference/vrs/v2/smart-ocr/smart-ocr) | Use this API to get the status of the created Aadhaar Verification via OCR request. You need to enter either the reference ID or verification ID to get the status. |


# Webhooks
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/kyc-links/webhooks

Subscribe to Cashfree KYC Link webhooks to track when customers open, complete, or fail verification journeys initiated through shareable KYC links.

Webhooks are event-based notifications that are received when a specific event related to the KYC verification occurs.

<Warning>
  In rare cases, such as network retries, read timeouts, processing delays, or delivery failures, the same webhook might be sent more than once for the same event. To prevent unintended side effects, implement idempotency in your webhook handler to handle duplicate deliveries.
</Warning>

## Add webhooks

Add your webhook URL in our system for us to deliver webhook events.

Follow the instructions below to configure the webhook URL. Ensure to provide the publicly accessible HTTPS URL to your webhook endpoint.

1. Log in to the **[Merchant Dashboard](https://merchant.cashfree.com/merchants/)** and click **Developers**.
2. Click **Webhooks** listed under the **Secure ID** card.
3. Click **Add Webhook URL** in the **Webhook** screen.
4. In the **Add Webhook** popup, fill in the following information:
   * **Webhook URL**: Enter the URL in this field.
5. Click **Test & Add Webhook**.

<Frame>
  <img />
</Frame>

***

## Webhook events

The following events are triggered at different stages of the KYC link process:

| Event | Description |
| :- | :- |
| KYC\_LINK\_ACTION\_PERFORMED | You will receive this event when one of the verifications is performed using the link. |
| KYC\_LINK\_SUCCESS | You will receive this event when all the verifications are performed successfully. |
| KYC\_LINK\_EXPIRED | You will receive this event when the link expires. |

<AccordionGroup>
  <Accordion title="KYC_LINK_ACTION_PERFORMED">
    ```json theme={"dark"}
    {
      "signature": "3YdAGMqBPDgWqy4zteRad/MoCmH59cm+93sogQWhOa8=",
      "event_type": "KYC_LINK_ACTION_PERFORMED",
      "event_time": "2024-02-15 16:53:15",
      "version": "v1",
      "data": {
        "name": "Test",
        "phone": "9999999999",
        "email": "test@cashfree.com",
        "verification_id": "testverificationid",
        "reference_id": 235461,
        "link_expiry": "2025-12-02",
        "form_link": "https://forms.cashfree.com/",
        "form_status": "RECEIVED",
        "verification_details": [
            {
                      "reference_id": 234,
              "type": "OFFLINE_AADHAAR_VERIFICATION",
              "status": "SUCCESS"
            },
            {
                      "reference_id": 0,
              "type": "PANDETAILS_VERIFICATION",
              "status": "RECEIVED"
        },
            {
              "reference_id": 0,
              "type": "BANKDETAILS_VALIDATION",
              "status": "RECEIVED"
            },
            {
              "reference_id": 0,
              "type": "UPIDETAILS_VALIDATION",
              "status": "RECEIVED"
            }
          ]
         }
    }
    ```
  </Accordion>

  <Accordion title="KYC_LINK_SUCCESS">
    ```json theme={"dark"}
    {
      "event_type": "KYC_LINK_SUCCESS",
      "event_time": "2024-02-15 16:53:15",
      "version": "v1",
      "data": {
        "name": "Test",
        "phone": "9999999999",
        "email": "test@cashfree.com",
        "verification_id": "testverificationid",
        "reference_id": 235461,
        "link_expiry": "2025-12-02",
        "form_link": "https://forms.cashfree.com/",
        "form_status": "SUCCESS",
        "verification_details": [
            {
                      "reference_id": 234,
              "type": "OFFLINE_AADHAAR_VERIFICATION",
              "status": "SUCCESS"
            },
            {
                      "reference_id": 235,
              "type": "PANDETAILS_VERIFICATION",
              "status": "SUCCESS"
        },
            {
              "reference_id": 236,
              "type": "BANKDETAILS_VALIDATION",
              "status": "SUCCESS"
            },
            {
              "reference_id": 237,
              "type": "UPIDETAILS_VALIDATION",
              "status": "SUCCESS"
            }
          ]
         }
    }
    ```
  </Accordion>

  <Accordion title="KYC_LINK_EXPIRED">
    ```json theme={"dark"}
    {
      "event_type": "KYC_LINK_EXPIRED",
      "event_time": "2024-02-15 16:53:15",
      "version": "v1",
      "data": {
        "name": "Test",
        "phone": "9999999999",
        "email": "test@cashfree.com",
        "verification_id": "testverificationid",
        "reference_id": 235461,
        "link_expiry": "2025-12-02",
        "form_link": "https://forms.cashfree.com/",
        "form_status": "EXPIRED",
        "verification_details": [
            {
                      "reference_id": 234,
              "type": "OFFLINE_AADHAAR_VERIFICATION",
              "status": "SUCCESS"
            },
            {
                      "reference_id": 0,
              "type": "PANDETAILS_VERIFICATION",
              "status": "EXPIRED"
        },
            {
              "reference_id": 236,
              "type": "BANKDETAILS_VALIDATION",
              "status": "SUCCESS"
            },
            {
              "reference_id": 0,
              "type": "UPIDETAILS_VALIDATION",
              "status": "EXPIRED"
            }
          ]
         }
    }
    ```
  </Accordion>
</AccordionGroup>

## Webhook signature

You will receive the webhook signature in the webhook header. Here is a sample header from a webhook request.

| Header name | Header value |
| - | :-: |
| content-length | 1099 |
| x-webhook-attempt | 1 |
| content-type | application/json |
| x-webhook-signature | 07r5C3VMwsGYeldGOCYxe5zoHhIN1zLfa8O0U/yngHI= |
| x-webhook-timestamp | 1746427759733 |

<Tip> Always capture the webhook payload in its raw text format before parsing into JSON. Parsing and re-serialising the payload can change the structure (for example, array ordering, spacing, or `null` handling) and cause a signature mismatch during verification. Use the exact raw body string from the request when computing the signature.</Tip>

## Webhook payload fields

The webhook payload contains important metadata in its top-level fields.

| Field | Type | Description |
| - | - | - |
| `event_type` | `string` | Indicates the type of event that triggered the webhook. |
| `event_time` | `string` | The UTC timestamp of when the event occurred, formatted in ISO 8601 (`YYYY-MM-DDTHH:MM:SSZ`). |
| `version` | `string` | Indicates the webhook format being used. Default version is "v1". |
| `data` | `object` | Contains event-specific details related to this feature. |

<Note>
  Verifying the signature is mandatory before processing any response. Refer to [Signature Verification](/docs/api-reference/vrs/webhook-signature-verification) for more details.
</Note>


# Mobile 360 OTP Less
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/mobile-360-otp-flow/mobile-360-otpless

post /mobile360/otpless
Use this API to extract multiple identity types from mobile number.



# Mobile 360 Send OTP Request
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/mobile-360-otp-flow/mobile-360-send-otp-request

post /mobile360/otp/send
The Mobile Send OTP API generates and sends a One-Time Password (OTP) to a user's mobile number via specified notification modes like SMS or WhatsApp.It captures consent details, ensuring secure and compliant user verification. View the [test data](https://www.cashfree.com/docs/api-reference/vrs/data-to-test-integration#mobile-360) and use the information to trigger the validations. You can use the test data only in test environments such as sandbox.



# Mobile 360 Verify OTP
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/mobile-360-otp-flow/mobile-360-verify-otp

post /mobile360/otp/verify
Use this API to extract multiple identity types from mobile number.

<AccordionGroup>
  <Accordion title="Key data fields of Mobile360 OTP Response">
    The following table outlines the key data fields returned in the OTP verification response:

    | **Field** | **Description** |
    | - | - |
    | PERSONAL\_DETAILS | Provides personal information such as full name, gender, date of birth, age, income, and occupation. |
    | RELATIVE\_DETAILS | Provides information about family members, including their names and relationships. |
    | BANK\_ACCOUNT\_DETAILS | Contains banking information such as the masked account number, IFSC code, bank address, and associated account linkage. The unmasked account number can be made available to regulated entities after a successful penny drop verification. |
    | UAN\_EMPLOYMENT\_DETAILS | Contains employment records linked to a UAN, including member ID, establishment ID, joining and exit dates, and Aadhaar linkage status. |
    | RECENT\_EMPLOYMENT\_DETAILS | Provides recent employment history, including employee and employer details, EPFO verification, and PF filing data. |
    | PAN | Contains the PAN number associated with the individual. |
    | PAN\_METADATA | Provides metadata related to the PAN, such as the registered name, name on the card, type, and Aadhaar linkage status. |
    | PHONE\_LIST | Lists phone numbers associated with the individual, including the number type and linkage source. |
    | EMAIL\_LIST | Lists email addresses associated with the individual and their linkage sources. |
    | PASSPORT\_NUMBER | Contains the passport number and associated linkage information. |
    | AADHAAR\_NUMBER | Provides a masked Aadhaar number and its source of linkage. |
    | RATION\_CARD | Contains the ration card number and linkage information. |
    | DRIVING\_LICENSE | Contains the driving license number and associated linkage. |
    | VOTER\_ID | Contains the voter ID and its linkage information. |
    | ADDRESS\_LIST | Lists known addresses, including full address, city, state, pincode, and linkage source. |
    | MOBILE\_NUMBER\_INTELLIGENCE | Provides key insights about the mobile number, including its validity, connection status, and service provider details. |
    | CREDIT\_SCORE | Provides the individual's credit score as a numeric value. |
    | RISK\_INTELLIGENCE | Provides risk insights about the mobile number, including is safe, risk level, reason, description, and relevant timestamps. |
  </Accordion>
</AccordionGroup>


# Verify Name Match
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/name-match/name-match

post /name-match
Use this API to compare two names and evaluate how closely they match. This API is helpful  in KYC, onboarding, fraud prevention, and reconciliation workflows. It supports variations such as initials, phonetic similarities, and minor spelling differences.

View the [test data](https://www.cashfree.com/docs/api-reference/vrs/data-to-test-integration#name-match) and use the information to trigger the validations. The test data can be used only in the sandbox environment.



# Fetch GSTIN with PAN
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/pan-to-gstin/fetch-gstin-with-pan

post /pan-gstin
Use this API to fetch the list of GSTIN associated with the PAN information.

View the [test data](https://www.cashfree.com/docs/api-reference/vrs/data-to-test-integration#fetch-gstin-with-pan) and use the information to trigger the validations. The test data can be used only in the sandbox environment.



# Fetch Udyam with PAN
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/pan-to-udyam/fetch-udyam-with-pan

post /pan-udyam
Use this API to fetch the Udyam registration number linked to a PAN. For a valid PAN with an associated Udyam registration, the response returns the registration number.

View the [test data](https://www.cashfree.com/docs/api-reference/vrs/data-to-test-integration#pan-to-udyam) and use the information to trigger the validations. The test data can be used only in the sandbox environment.



# Get Status
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/pan/get-status-for-verify-pan-in-bulk

get /pan/bulk
Use this API to get the status of the Verify PAN in Bulk API request. You need to enter either the reference ID or bulk verification ID.

Refer to [PAN Status description and Status Code](/docs/api-reference/vrs/v2/pan/pan-status-descriptions#pan-status-code-reference) for every pan status code value and its matching pan status description.


# Get Status
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/pan/get-status-of-verify-pan-sync

get /pan/{reference_id}
Use this API to get the verification status of the Verify PAN Sync API by passing the reference ID.

Refer to [PAN Status description and Status Code](/docs/api-reference/vrs/v2/pan/pan-status-descriptions#pan-status-code-reference) for every pan status code value and its matching pan status description.


# PAN 360
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/pan/pan-360

post /pan/advance
Use this API to verify the PAN information of a customer. You can retrieve more information such as first name, last name, masked aadhaar number,masked email, masked mobile number and other contact information and more. Please note that, mobile number, email, and address fields have an approximate fill rate of 45%, based on recent changes in the underlying data sources.

View the [test data](https://www.cashfree.com/docs/api-reference/vrs/data-to-test-integration#pan) and use the information to trigger the validations. The test data can be used only in the sandbox environment.

<Note>
  The name returned by the API may differ from the name printed on the physical PAN card. The API returns the registered name from the Income Tax Department's records, which is the authoritative source and may not match the name displayed on the card.
</Note>


# PAN Lite
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/pan/pan-lite

post /pan-lite
Use this API to validate PAN information of individuals. The API helps verify the unique identifier, name of the individual, date of birth, and other information that helps you in customer onboarding, KYC verification, and other fraud prevention security measures.

View the [test data](https://www.cashfree.com/docs/api-reference/vrs/data-to-test-integration#pan) and use the information to trigger the validations.The test data can be used only in the sandbox environment.

<Note>
  The name returned by the API may differ from the name printed on the physical PAN card. The API returns the registered name from the Income Tax Department's records, which is the authoritative source and may not match the name displayed on the card.
</Note>


# PAN Status Codes
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/pan/pan-status-descriptions

Use this reference to interpret pan status code and pan status description values returned by Cashfree PAN verification APIs.

The following table lists the pan status code values and the matching pan status description that Permanent Account Number (PAN) verification APIs return from the Income Tax Department (ITD):

* [Verify PAN Sync API](/docs/api-reference/vrs/v2/pan/verify-pan-sync)
* [Get Status of Verify PAN Sync API](/docs/api-reference/vrs/v2/pan/get-status-of-verify-pan-sync)
* [Get Status for Verify PAN in Bulk API](/docs/api-reference/vrs/v2/pan/get-status-for-verify-pan-in-bulk)

<span />

| Status code | Status description |
| :- | :- |
| `E` | Existing and valid |
| `EA` | Existing and valid but event marked as amalgamation in ITD database |
| `EC` | Existing and valid but event marked as acquisition in ITD database |
| `ED` | Existing and valid but event marked as death in ITD database |
| `EI` | Existing and valid but event marked as dissolution in ITD database |
| `EL` | Existing and valid but event marked as liquidated in ITD database |
| `EM` | Existing and valid but event marked as merger in ITD database |
| `EP` | Existing and valid but event marked as partition in ITD database |
| `ES` | Existing and valid but event marked as split in ITD database |
| `EU` | Existing and valid but event marked as under liquidation in ITD database |
| `F` | Marked as fake |
| `X` | Marked as deactivated |
| `D` | Deleted |
| `N` | Not found in ITD database or invalid PAN |
| `I` | Inoperative |

<Note>
  Codes that begin with `E` indicate an existing and valid PAN. The trailing letter identifies an event recorded against the PAN in the ITD database. Use that event to decide whether the status affects your onboarding decision.
</Note>


# Verify
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/pan/verify-pan-in-bulk

post /pan/bulk
Use this API to verify the customer PAN information individually or in bulk by passing either the reference ID or bulk verification ID.

View the [test data](https://www.cashfree.com/docs/api-reference/vrs/data-to-test-integration#pan) and use the information to trigger the validations. The test data are usable only in the test environment sandbox. 

<Note>
  The name returned by the API may differ from the name printed on the physical PAN card. The API returns the registered name from the Income Tax Department's records, which is the authoritative source and may not match the name displayed on the card.
</Note>


# Verify
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/pan/verify-pan-sync

post /pan
Use this API to check the existence of a PAN. If the PAN is valid, the response returns the registered name and the PAN type (Individual or Business).

View the [test data](https://www.cashfree.com/docs/api-reference/vrs/data-to-test-integration#pan) and use the information to trigger the validations. The test data can be used only in the sandbox environment.

<Note>
  The name returned by the API may differ from the name printed on the physical PAN card. The API returns the registered name from the Income Tax Department's records, which is the authoritative source and may not match the name displayed on the card.
</Note>

Refer to [PAN Status description and Status Code](/docs/api-reference/vrs/v2/pan/pan-status-descriptions#pan-status-code-reference) for every pan status code value and its matching pan status description.


# Verify Passport
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/passport/verify-passport

post /passport
This API verifies passport information to confirm customer identity. Provide the passport file number in the request to fetch relevant details.

View the [test data](https://www.cashfree.com/docs/api-reference/vrs/data-to-test-integration#passport)  and use the information to trigger the validations. The test data are usable only in the test environment sandbox.

<Note> Passport verification is supported only for Indian passports.</Note>

<Accordion title="Response codes">
  | Sub code | Status | Message | Next action |
  | - | - | - | - |
  | 200 | SUCCESS | VALID | - |
  | 200 | SUCCESS | INVALID | Enter the correct information in the request. |
  | 400 | ERROR | verification\_id is missing in the request. | Enter a valid verification\_id in the request. |
  | 400 | ERROR | verification\_id can include only alphanum, dot, hyphen, and underscores. | Only alphanumeric, period (.), hyphen (-), and underscore ( \_ ) are allowed. |
  | 400 | ERROR | file\_number is missing in the request. | Enter the file number in the request. |
  | 400 | ERROR | dob is missing in the request. | Enter the date of birth of the passport holder in the request. |
  | 400 | ERROR | dob should be of type YYYY-MM-DD. | Enter the DOB in the YYYY-MM-DD format. |
  | 400 | ERROR | Client secret belongs to test environment. | Enter the correct environment credentials in the request. |
  | 400 | ERROR | x-client-id is missing in the request. | Enter all the header information in the API request. |
  | 401 | ERROR | Invalid clientId and clientSecret combination. | Ensure you enter valid x-client-id and x-client-secret information in the API request. |
  | 403 | ERROR | IP not whitelisted your current IP is 106.51.91.104. For IP whitelisting assistance, visit our [IP Whitelisting guide](/docs/secure-id/get-started/integration/ip-whitelisting-verification) | Whitelist the IP address. |
  | 409 | ERROR | verification ID already exists. | Enter a unique verification ID to identify the request. |
  | 422 | ERROR | Insufficient balance to process this request. | Try again with sufficient balance. |
  | 500 | ERROR | something went wrong. | Try again after some time. |
  | 502 | ERROR | verification attempt failed. | Try again after some time. |
</Accordion>


# Reverse Geocoding
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/reverse-geocoding/reverse-geocoding

post /reverse-geocoding
Use this API to convert geographic coordinates (latitude and longitude) into readable location information for verification purposes.

View the [test data](https://www.cashfree.com/docs/api-reference/vrs/data-to-test-integration#reverse-geocoding-coordinates) and use the information to trigger the validations.The test data can be used only in the sandbox environment.



# Create Reverse Penny Drop Request
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/reverse-penny-drop/create-reverse-penny-drop-request

post /reverse-penny-drop
Use this API to create a reverse penny drop request. Reverse penny drop is a verification method for validating bank account information. 

Your customers or users makes a payment of one rupee through a UPI based transaction and get the one rupee back within 48 hours once the verification is complete.

<Note>The generated RPD link is valid for 10 minutes. You must complete the reverse penny drop process within this time.</Note>



# Get Reverse Penny Drop Request Details
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/reverse-penny-drop/get-reverse-penny-drop-request-details

get /remitter/status
Use this API to get the details of the created reverse penny drop request by passing reference ID or user ID to check if the validation is complete and get the results.



# Webhooks
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/reverse-penny-drop/webhooks-reverse-penny

Set up Cashfree Reverse Penny Drop webhooks to receive notifications when customer-initiated UPI or netbanking bank verifications complete.

Webhooks are event-based notifications that are received when a specific event related to the reverse penny drop verification occurs.

<Warning>
  In rare cases, such as network retries, read timeouts, processing delays, or delivery failures, the same webhook might be sent more than once for the same event. To prevent unintended side effects, implement idempotency in your webhook handler to handle duplicate deliveries.
</Warning>

## Add webhooks

Add your webhook URL in our system for us to deliver webhook events.

Follow the instructions below to configure the webhook URL. Ensure to provide the publicly accessible HTTPS URL to your webhook endpoint.

1. Log in to the **[Merchant Dashboard](https://merchant.cashfree.com/merchants/)** and click **Developers**.
2. Click **Webhooks** listed under the **Secure ID** card.
3. Click **Add Webhook URL** in the **Webhook** screen.
4. In the **Add Webhook** popup, fill in the following information:
   * **Webhook URL**: Enter the URL in this field.
5. Click **Test & Add Webhook**.

<Frame>
  <img />
</Frame>

## Webhook event

| Event | Description |
| :- | :- |
| RPD\_BANK\_ACCOUNT\_VERIFICATION\_SUCCESS | The reverse penny drop verification is a success. |
| RPD\_BANK\_ACCOUNT\_VERIFICATION\_EXPIRED | The reverse penny drop verification expired. |
| RPD\_BANK\_ACCOUNT\_VERIFICATION\_FAILURE | The reverse penny drop verification is a failure. |

The following events are triggered at different stages of the reverse penny drop verification process:

<AccordionGroup>
  <Accordion title="RPD_BANK_ACCOUNT_VERIFICATION_SUCCESS">
    ```json theme={"dark"}
    {
       "signature":"signature",    
       "event_type":"RPD_BANK_ACCOUNT_VERIFICATION_SUCCESS",    
       "event_time":"2023-07-19 10:46:16",
       "version":"v1",
       "data":{
            "bank_account":"026291800001191", 
            "ifsc":"YESB0000262", 
            "upi": "success@upi",
            "name_at_bank":"BHARATHTEST GKUMARUT", 
            "verification_id":"91", 
            "ref_id":"49", 
            "utr":"49" ,
            "status":"SUCCESS", 
            "name_match_score":"", 
            "name_match_result":"", 
            "added_on":"2023-07-14 17:29:50", 
            "processed_on":"2023-07-14 17:30:50",              
            "penny_collected_on":"2023-07-14 17:30:50",
            "reversal_status": "PENDING",
            "account_type": "SAVINGS"
        }
    }
    ```
  </Accordion>

  <Accordion title="RPD_BANK_ACCOUNT_VERIFICATION_EXPIRED">
    ```json theme={"dark"}
    {
       "signature":"signature",    
       "event_type":"RPD_BANK_ACCOUNT_VERIFICATION_EXPIRED",    
       "event_time":"2023-07-19 10:46:16",
       "version":"v1",
       "data":{
            "bank_account":"", 
            "ifsc":"", 
            "upi": "",
            "name_at_bank":"", 
            "verification_id":"91", 
            "ref_id":"49", 
            "utr":"" ,
            "status":"EXPIRED", 
            "name_match_score":"", 
            "name_match_result":"", 
            "added_on":"2023-07-14 17:29:50", 
            "processed_on":"2023-07-14 17:30:50",           
            "penny_collected_on":""
        }
    }
    ```
  </Accordion>

  <Accordion title="RPD_BANK_ACCOUNT_VERIFICATION_FAILURE">
    ```json theme={"dark"}
    {
       "signature":"signature",    
       "event_type":"RPD_BANK_ACCOUNT_VERIFICATION_FAILURE",    
       "event_time":"2023-07-19 10:46:16",
       "version":"v1",
       "data":{
            "bank_account":"", 
            "ifsc":"", 
            "upi": "",
            "name_at_bank":"", 
            "verification_id":"91", 
            "ref_id":"49", 
            "utr":"" ,
            "status":"FAILURE", 
            "name_match_score":"", 
            "name_match_result":"", 
            "added_on":"2023-07-14 17:29:50", 
            "processed_on":"2023-07-14 17:30:50",          
            "penny_collected_on":""
        }
    }
    ```
  </Accordion>
</AccordionGroup>

## Webhook payload fields

The webhook payload contains important metadata in its top-level fields.

| Field | Type | Description |
| - | - | - |
| `signature` | `string` | A Base64-encoded HMAC-SHA256 signature of the payload, generated using a shared client secret. |
| `event_type` | `string` | Indicates the type of event that triggered the webhook. |
| `event_time` | `string` | The UTC timestamp of when the event occurred, formatted in ISO 8601 (`YYYY-MM-DDTHH:MM:SSZ`). |
| `version` | `string` | Indicates the webhook format being used. Default version is "v1". |
| `data` | `object` | Contains event-specific details related to this feature. |

## Signature Verification

Verifying the signature is mandatory before processing any response. It helps authenticate that the webhook is from Cashfree.

Follow the steps to verify the signature:

1. Sort the array based on keys.
2. Concatenate all the values in this array and the resultant is the post data (**postData**).
3. Encrypt the `postData` with SHA-256 and Base64-encode it.
4. Verify that the calculated signature matches the signature received.
5. Continue processing only if the signatures match. Otherwise, discard the request.
6. Ensure that the `clientSecret` you use belongs to the oldest active key pair.

For example, from the webhook received, extract the data and pass it to generate HMAC function:

```
{bank_account=026291800001191, ifsc=YESB0000262, upi=, name_at_bank=John Doe,
verification_id=fadsfdsf, ref_id=332, utr=332, status=SUCCESS,
added_on=2023-09-06T07:48:53+05:30, processed_on=2023-09-06 07:49:03,
penny_collected_on=2023-09-06 07:48:53}
```

```Text Java code - for reference theme={"dark"}
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.util.Map;
import java.util.TreeMap;

import com.fasterxml.jackson.core.type.TypeReference;
import com.fasterxml.jackson.databind.ObjectMapper;
import org.apache.commons.codec.binary.Base64;

public class ComputedSignature {
public static String generateHMAC(String clientSecret, String data) {
        String hash = null;
        ObjectMapper objectMapper = new ObjectMapper();
        try {
            Map<String, Object> jsonMap = objectMapper.readValue(data, new TypeReference<Map<String, Object>>() {
            });
            Map<String, Object> sortedMap = new TreeMap<>(jsonMap);

            // sort the map based on keys
            String postDataString = "";

            for (Map.Entry<String, Object> entry : sortedMap.entrySet()) {
                postDataString = postDataString + entry.getValue();
            }

            // encode the post data on sha256
            Mac sha256HMAC = Mac.getInstance("HmacSHA256");
            SecretKeySpec secretKey = new SecretKeySpec(clientSecret.getBytes(), "HmacSHA256");
            sha256HMAC.init(secretKey);

            hash = Base64.encodeBase64String(sha256HMAC.doFinal(postDataString.getBytes()));
        } catch (Exception e) {
            e.printStackTrace();

        }
        return hash;
    }
}

```

## IPs to whitelist

When you decide to consume the webhooks, first, you need to verify if your systems need an IP whitelisting to be done at your end or not. Accordingly you can whitelist the below IPs of Cashfree:

| Sandbox |
| :- |
| 52.66.25.127 |
| 15.206.45.168 |

| Prod |
| :- |
| 52.66.101.190 |
| 3.109.102.144 |
| 18.60.134.245 |
| 18.60.183.142 |

| Port |
| :- |
| 443 (secured) |


# Server Side SDKs
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/sdk/verification-suite-server-sdks

Install and configure Cashfree Secure ID server SDKs for Node.js, Java, Python, and PHP to call KYC and verification APIs without writing low-level REST code.

Cashfree Secure ID server-side SDKs reduce the amount of work required to call Secure ID REST APIs from your backend. Each SDK wraps authentication, request formatting, and response parsing in language-specific libraries for Node.js, Java, Python, and PHP.

## Prerequisites

Complete the following before you install an SDK:

* Generate API keys and confirm your sandbox credentials. See [Getting started](/docs/api-reference/vrs/getting-started).
* Whitelist your server IP address, or configure 2FA signature generation for API requests.

## API vs SDK

Use the REST API when you need full control over HTTP requests, work in a language without an official SDK, or call only a small set of endpoints. Use an SDK when you want language-native methods, built-in authentication headers, and less boilerplate for request and response handling.

An API defines how applications send requests and receive responses, typically over a network. An SDK packages APIs with libraries, documentation, and language-specific helpers so you can call those APIs with less manual setup.

The following table compares the two approaches:

| Aspect | API | SDK |
| - | - | - |
| Purpose | Enables interaction between systems | Facilitates application development |
| Scope | Focused on specific functionality | Toolkit that often includes APIs |
| Ease of use | Requires manual setup | Provides abstractions and ready-to-use code |
| Language support | Typically language-agnostic | Usually language-specific |
| Included tools | None | Often includes helpers, samples, and related utilities |

## Why use server SDKs

Server SDKs help you integrate Secure ID verification APIs faster and with fewer errors than calling REST endpoints directly. They offer the following benefits:

* **Faster integration**: Pre-built methods map to Secure ID API operations, so you spend less time writing HTTP clients and parsing JSON.
* **Built-in authentication**: SDKs attach required headers such as `x-client-id`, `x-client-secret`, and `x-api-version` on every request.
* **Consistent error handling**: API error responses are surfaced as language-native exceptions or error objects, so you do not parse HTTP status codes manually.
* **Type safety**: Request and response models in Java and PHP help catch parameter mistakes at compile time.
* **Ongoing maintenance**: SDK releases track API changes, reducing the effort required to adopt new endpoints or fields.

## Supported SDKs

Cashfree maintains official server-side SDKs for the following languages. Each card links to the SDK GitHub repository for source code, changelogs, and issue tracking.

<CardGroup>
  <Card title="Node.js SDK" icon="node-js" href="https://github.com/cashfree/cashfree-verification-sdk-nodejs">
    Version **4.0.1**. JavaScript and TypeScript SDK for Node.js applications and serverless functions.
  </Card>

  <Card title="Java SDK" icon="java" href="https://github.com/cashfree/cashfree-verification-sdk-java">
    Version **2.0.10**. SDK for Java applications and Spring Boot services.
  </Card>

  <Card title="Python SDK" icon="python" href="https://github.com/cashfree/cashfree-verification-sdk-python">
    Version **2.0.0**. SDK for Python applications and data pipelines.
  </Card>

  <Card title="PHP SDK" icon="php" href="https://github.com/cashfree/cashfree-verification-sdk-php">
    Version **3.0.1**. SDK for PHP applications and Laravel projects.
  </Card>
</CardGroup>

## Install and configure the SDK

Select your language below, install the package, and initialise the SDK with your credentials and target environment.

<Tabs>
  <Tab title="Node.js">
    Install the package using npm:

    ```bash theme={"dark"}
    npm install cashfree-verification
    ```

    Initialise the SDK with your client ID, client secret, API version, and environment:

    ```javascript theme={"dark"}
    import { Cashfree } from "cashfree-verification";

    Cashfree.XClientId = "<CLIENT_ID>";
    Cashfree.XClientSecret = "<CLIENT_SECRET>";
    Cashfree.XEnvironment = Cashfree.Environment.SANDBOX;
    Cashfree.XApiVersion = "2024-12-01";
    ```
  </Tab>

  <Tab title="Java">
    Add the dependency to your build file.

    Gradle dependency:

    ```gradle theme={"dark"}
    implementation "com.cashfree.verification.java:cashfree_verification:2.0.10"
    ```

    Maven dependency:

    ```xml theme={"dark"}
    <dependency>
      <groupId>com.cashfree.verification.java</groupId>
      <artifactId>cashfree_verification</artifactId>
      <version>2.0.10</version>
    </dependency>
    ```

    Initialise the SDK:

    ```java theme={"dark"}
    import com.cashfree.CashfreeVrs;

    CashfreeVrs.XClientId = "<CLIENT_ID>";
    CashfreeVrs.XClientSecret = "<CLIENT_SECRET>";
    CashfreeVrs.XEnvironment = CashfreeVrs.SANDBOX;

    CashfreeVrs cashfree = new CashfreeVrs();
    String xApiVersion = "2024-12-01";
    ```
  </Tab>

  <Tab title="Python">
    Install the package using pip:

    ```bash theme={"dark"}
    pip install cashfree_verification
    ```

    Initialise the SDK:

    ```python theme={"dark"}
    from cashfree_verification import Cashfree

    Cashfree.XClientId = "<CLIENT_ID>"
    Cashfree.XClientSecret = "<CLIENT_SECRET>"
    Cashfree.XEnvironment = Cashfree.SANDBOX
    x_api_version = "2024-12-01"
    ```
  </Tab>

  <Tab title="PHP">
    Install the package using Composer:

    ```bash theme={"dark"}
    composer require cashfree/cashfree-verification
    ```

    Initialise the SDK:

    ```php theme={"dark"}
    \Cashfree\CashfreeVrs::$XClientId = "<CLIENT_ID>";
    \Cashfree\CashfreeVrs::$XClientSecret = "<CLIENT_SECRET>";
    \Cashfree\CashfreeVrs::$XEnvironment = \Cashfree\CashfreeVrs::$SANDBOX;

    $cashfree = new \Cashfree\CashfreeVrs();
    ```
  </Tab>
</Tabs>

<Warning>
  Do not embed your client secret in client-side code, mobile applications, or public repositories. Initialise SDKs only on trusted backend servers.
</Warning>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/vrs/v2/bav-v2/bank-account-verification-sync-v2">Bank Account Verification Sync V2 API</a></li>
    <li><a href="/docs/api-reference/vrs/v2/pan/pan-lite">PAN Lite API</a></li>
    <li><a href="/docs/api-reference/vrs/v2/ifsc/ifsc-verification-v2">IFSC Verification V2 API</a></li>
    <li><a href="/docs/api-reference/vrs/v2/digilocker/digilocker-sdk">DigiLocker React Native SDK</a></li>
  </ul>
</div>


# Smart OCR
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/smart-ocr/smart-ocr

post /bharat-ocr
Use this API to upload images or PDFs of documents and extract structured fields. It also includes image quality checks, fraud detection and optional verification against government databases.

<Note> **Sandbox environment** is a testing environment and responses are mocked. For real time verifications, please use the **production environment**.</Note>


# Driving Licence
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/smart-ocr/success-responses/DL

Review the sample success response returned by the Cashfree Smart OCR API for an Indian Driving Licence so you can map every field in your application.

This page provides the success response of the Smart OCR API for the Driving Licence document.

<CodeGroup>
  ```Text DRIVING_LICENCE_OCR theme={"dark"}
  {
      "verification_id": "test_verification_id",
      "reference_id": 1358,
      "status": "VALID",
      "document_type": "DRIVING_LICENCE",
      "document_fields": {
          "address": "123 Main Street, Sector 15, Noida, Uttar Pradesh",
          "blood_group": "B+",
          "date_of_birth": "2004-10-02",
          "full_name": "John Doe",
          "guardian_name": "Josh Doe",
          "issuing_authority": "Assam",
          "license_issue_date": "2019-08-16",
          "license_expiry_date": "2024-05-13",
          "license_number": "AB1120040002378",
          "pin": "247001",
          "vehicle_class": [
              {
                  "issue_date": "2004-05-14",
                  "vehicle_type": "MCWG"
              },
              {
                  "issue_date": "2004-05-14",
                  "vehicle_type": "LMV"
              }
          ]
      },
      "quality_checks": {
          "blur": true,
          "glare": false,
          "partially_present": false,
          "black_and_white": false,
          "face_present": true,
          "face_clear": false,
          "qr_present": false,
          "obscured": false
      },
      "fraud_checks": {
          "is_screenshot": true,
          "is_photo_of_screen": false,
          "is_photo_imposed": false,
          "is_overwritten": false
      },
      "verification_details": {
          "verification_id": "verification-uuid-sample-456",
          "reference_id": 9876544,
          "dl_number": "AB1120040002378",
          "dob": "2004-10-02",
          "status": "VALID",
          "badge_details": [
              {
                  "badge_issue_date": "2019-08-16",
                  "badge_no": "DL002378",
                  "class_of_vehicle": [
                      "MCWG",
                      "LMV"
                  ]
              }
          ],
          "dl_validity": {
              "non_transport": {
                  "to": "2024-05-13",
                  "from": "2019-08-16"
              },
              "hazardous_valid_till": null,
              "transport": {
                  "to": null,
                  "from": null
              },
              "hill_valid_till": null
          },
          "details_of_driving_licence": {
              "date_of_issue": "2019-08-16",
              "date_of_last_transaction": "2022-08-15",
              "status": "ACTIVE",
              "last_transacted_at": "2022-08-15T14:30:00Z",
              "name": "John Doe",
              "father_or_husband_name": "Josh Doe",
              "address_list": [
                  {
                      "complete_address": "123, Main Street, Sector 15, Noida, Uttar Pradesh, 247001",
                      "type": "permanent",
                      "split_address": {
                          "district": [
                              "GAUTAM BUDDHA NAGAR"
                          ],
                          "state": [
                              [
                                  "UTTAR PRADESH",
                                  "UP"
                              ]
                          ],
                          "city": [
                              "NOIDA"
                          ],
                          "pincode": "247001",
                          "country": [
                              "IN",
                              "IND",
                              "INDIA"
                          ],
                          "address_line": "123, Main Street, Sector 15"
                      }
                  },
                  {
                      "complete_address": "123, Main Street, Sector 15, Noida, Uttar Pradesh, 247001",
                      "type": "temporary",
                      "split_address": {
                          "district": [
                              "GAUTAM BUDDHA NAGAR"
                          ],
                          "state": [
                              [
                                  "UTTAR PRADESH",
                                  "UP"
                              ]
                          ],
                          "city": [
                              "NOIDA"
                          ],
                          "pincode": "247001",
                          "country": [
                              "IN",
                              "IND",
                              "INDIA"
                          ],
                          "address_line": "123, Main Street, Sector 15"
                      }
                  }
              ],
              "address": "123, Main Street, Sector 15, Noida, Uttar Pradesh, 247001",
              "photo": "https://example-bucket.s3.amazonaws.com/sample-dl-photo-456.jpg",
              "split_address": {
                  "district": [
                      "GAUTAM BUDDHA NAGAR"
                  ],
                  "state": [
                      [
                          "UTTAR PRADESH",
                          "UP"
                      ]
                  ],
                  "city": [
                      "NOIDA"
                  ],
                  "pincode": "247001",
                  "country": [
                      "IN",
                      "IND",
                      "INDIA"
                  ],
                  "address_line": "123, Main Street, Sector 15"
              },
              "cov_details": []
          }
      }
  }
  ```
</CodeGroup>


# Aadhaar
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/smart-ocr/success-responses/aadhaar

Inspect the Cashfree Smart OCR success response for the Aadhaar document so you can map extracted fields like name, DOB, address, and Aadhaar number.

This page provides the success response of Smart OCR API for Aadhaar document.

<CodeGroup>
  ```Text AADHAAR_FRONT theme={"dark"}
  {
      "verification_id": "test_verification_id",
      "reference_id": 1358,
      "status": "VALID",
      "document_type": "AADHAAR_FRONT",
      "document_fields": {
          "address": "S / O Josh Doe, 202-parivar daser complex , dal  bazar , Gird , Gwalior , Lashkar City , Madhya Pradesh , 474019",
          "dob": "2004-10-02",
          "father": "Josh Doe",
          "gender": "Male",
          "name": "John Doe",
          "uid": "123456789012",
      },
      "quality_checks": {
          "blur": true,
          "glare": false,
          "partially_present": false,
          "black_and_white": false,
          "face_present": true,
          "face_clear": false,
          "qr_present": false,
          "obscured": false
      },
      "fraud_checks": {
          "is_screenshot": true,
          "is_photo_of_screen": false,
          "is_photo_imposed": false,
          "is_overwritten": false
      },
      "qr_details": {
          "status": "SECURE",
          "name": "John Doe",
          "dob": "2004-10-02",
          "gender": "Male",
          "care_of": "S / O : Josh Doe",
          "address": "S / O : Josh Doe, 202-parivar daser complex, parivar daser complex, dal bazar, dal bazar, Lashkar City, Gird, Gwalior, Gwalior, Madhya Pradesh - 474019",
          "split_address": {
              "country": "India",
              "dist": "Gwalior",
              "house": "202-parivar daser complex",
              "landmark": "dal bazar",
              "pincode": 474019,
              "po": "Lashkar City",
              "state": "Madhya Pradesh",
              "street": "parivar daser complex",
              "subdist": "Gird",
              "vtc": "Gwalior",
              "locality": "dal bazar"
          },
          "year_of_birth": 2004,
          "aadhaar_last_four_digit": "9012",
          "email_linked": true,
          "mobile_linked": true,
          "mobile_hash": "hashed_mobile_value",
          "email_hash": "hashed_email_value",
          "photo_link": "<base64 encoded image>"
      }
  }
  ```

  ```Text AADHAAR_BACK theme={"dark"}
  {
      "verification_id": "test_verification_id",
      "reference_id": 1358,
      "status": "VALID",
      "document_type": "AADHAAR_BACK",
      "document_fields": {
          "address": "S / O Josh Doe, 202-parivar daser complex , dal  bazar , Gird , Gwalior , Lashkar City , Madhya Pradesh , 474019",
          "pincode": "474019",
          "uid": "123456789012"
      },
      "quality_checks": {
          "blur": true,
          "glare": false,
          "partially_present": false,
          "black_and_white": false,
          "face_present": false,
          "face_clear": false,
          "qr_present": false,
          "obscured": false
      },
      "fraud_checks": {
          "is_screenshot": true,
          "is_photo_of_screen": false,
          "is_photo_imposed": false,
          "is_overwritten": false
      },
      "qr_details": {
          "status": "SECURE",
          "name": "John Doe",
          "dob": "2004-10-02",
          "gender": "Male",
          "care_of": "S / O : Josh Doe",
          "address": "S / O : Josh Doe, 202-parivar daser complex, parivar daser complex, dal bazar, dal bazar, Lashkar City, Gird, Gwalior, Gwalior, Madhya Pradesh - 474019",
          "split_address": {
              "country": "India",
              "dist": "Gwalior",
              "house": "202-parivar daser complex",
              "landmark": "dal bazar",
              "pincode": 474019,
              "po": "Lashkar City",
              "state": "Madhya Pradesh",
              "street": "parivar daser complex",
              "subdist": "Gird",
              "vtc": "Gwalior",
              "locality": "dal bazar"
          },
          "year_of_birth": 2004,
          "aadhaar_last_four_digit": "9012",
          "email_linked": true,
          "mobile_linked": true,
          "mobile_hash": "hashed_mobile_value",
          "email_hash": "hashed_email_value",
          "photo_link": "<base64 encoded image>"
      }
  }
  ```
</CodeGroup>


# Cancelled Cheque
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/smart-ocr/success-responses/cancelled-cheque

Examine the Cashfree Smart OCR success response for a cancelled cheque image to map extracted account number, IFSC, bank name, and account holder fields.

This page provides the success response of the Smart OCR API for the cancelled cheque document.

<CodeGroup>
  ```Text CANCELLED_CHEQUE theme={"dark"}
  {
      "verification_id": "test_verification_id1",
      "reference_id": 1358,
      "status": "VALID",
      "document_type": "CANCELLED_CHEQUE",
      "document_fields": {
          "ifsc": "ABCD1234567",
          "pincode": "522201",
          "account_number": "123456789012",
          "bank_name": "State Bank Of India",
          "cheque_number": "123456",
          "account_type": "Current",
          "micr_code": "123456789",
          "contact": "8644225960",
          "branch": "TENALI BAZAR",
          "name": "JohnDoe",
          "split_address": {
              "district": "UNTUR DISTRICT",
              "state": "ANDHRA PRADESH",
              "city": "TENALI",
              "pincode": "522201",
              "country": "INDIA"
          },
          "address_line": "RMZ Eco world, Building 7 10th Floor, Devarabeesanahalli, Marathalli Outer Ring road, Bangalore - 560103",
          "issue_date": "2024-10-02",
          "expiry_date": "2024-10-30"
      }
  }
  ```
</CodeGroup>


# INVOICE
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/smart-ocr/success-responses/invoice

Read the Cashfree Smart OCR success response for an invoice document and learn how to extract vendor, buyer, GSTIN, line item, and amount details.

This page provides the success response of the Smart OCR API for the Invoice document.

<CodeGroup>
  ```Text INVOICE theme={"dark"}
  {
      "verification_id": "test_verification_id1",
      "reference_id": 1358,
      "status": "VALID",
      "document_type": "INVOICE",
      "document_fields": {
          "vendor": {
              "name": "Tech Solutions Pvt Ltd",
              "address": "1234, Business Park, MG Road, Bangalore, Karnataka, 560001, IN",
              "contact": "9876543210",
              "email": "contact@techsolutions.com",
              "gstin": "29AALCT1234E1Z9",
              "state": "Karnataka",
              "state_code": "29",
              "pan": "AALCT1234E"
          },
          "buyer": {
              "name": "Global Enterprises",
              "address": "5678, Industrial Complex, Sector 15, Noida, Uttar Pradesh, 201301, IN",
              "contact_person": "Ravi Kumar",
              "contact": "9123456789",
              "gstin": "09AABCG1234C1Z5",
              "state": "Uttar Pradesh",
              "state_code": "09",
              "place_of_supply": "Uttar Pradesh"
          },
          "invoice_details": {
              "invoice_number": "INV-20250319-001",
              "invoice_date": "2025-03-19",
              "order_reference": {
                  "order_ref_no": "ORD-20250318-1234",
                  "order_ref_date": "2025-03-18"
              },
              "indent": {
                  "indent_no": "IND-20250317-5678",
                  "indent_date": "2025-03-17"
              },
              "dispatched_through": "XYZ Logistics",
              "payment_terms": "Net 30 Days",
              "sales_person": "John Doe",
              "destination": "Noida, Uttar Pradesh"
          },
          "line_items": [
              {
                  "item_no": 1,
                  "model_no": "PROD-001",
                  "description": "Wireless Mouse Model X, 2.4 GHz, Black, Ergonomic Design",
                  "total_amount": 1200.00,
                  "unit_rate": 200.00,
                  "quantity": 6,
                  "alternate_quantity": 6,
                  "hsn_sac": "84716040"
              },
              {
                  "item_no": 2,
                  "model_no": "PROD-002",
                  "description": "Mechanical Keyboard, RGB Backlit, USB-C, 104 Keys",
                  "total_amount": 3000.00,
                  "unit_rate": 750.00,
                  "quantity": 4,
                  "alternate_quantity": 4,
                  "hsn_sac": "84716090"
              }
          ],
          "totals": {
              "sub_total": 4200.00,
              "igst": 0.00,
              "cgst": 378.00,
              "sgst": 378.00,
              "round_off": 0.00,
              "grand_total": 4956.00,
              "amount_in_words": "Four Thousand Nine Hundred Fifty-Six Only"
          },
          "bank_details": {
              "bank_name": "HDFC Bank",
              "account_number": "123456789012",
              "branch_ifs": "HDFC0000123",
              "swift_code": "HDFCINBBXXX"
          },
          "declaration": "This is a computer-generated invoice and does not require a signature.",
          "additional_info": {
              "delivery_note": "DN-20250319-001",
              "po_no": "PO-20250318-1234",
              "po_date": "2025-03-18",
              "order_form_no": "OF-20250318-5678",
              "proforma_invoice_no": "PI-20250318-001",
              "proforma_invoice_date": "2025-03-18"
          }
      }
  }
  ```
</CodeGroup>


# PAN
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/smart-ocr/success-responses/pan

Review the Cashfree Smart OCR success response for a PAN card to understand parsed values for PAN number, name, father's name, and date of birth.

This page provides the success response of Smart OCR API for PAN document.

```
{
    "verification_id": "test_verification_id",
    "reference_id": 1358,
    "status": "VALID",
    "document_type": "PAN_OCR",
    "document_fields": {
        "pan": "DUXPR7763F",
        "dob": "2004-10-02",
        "name": "John Doe",
        "father": "Josh Doe"
    },
    "quality_checks": {
        "blur": true,
        "glare": false,
        "partially_present": false,
        "black_and_white": false,
        "face_present": true,
        "face_clear": true,
        "qr_present": false,
        "obscured": false
    },
    "fraud_checks": {
        "is_screenshot": true,
        "is_photo_of_screen": false,
        "is_photo_imposed": false,
        "is_overwritten": false
    },
    "verification_details": {
        "reference_id": 98237899,
        "status": "VALID",
        "pan": "DUXPR7763F",
        "name": "John Doe",
        "dob": "2004-10-02",
        "name_match": "Y",
        "dob_match": "Y",
        "pan_status": "E",
        "aadhaar_seeding_status": "Y",
        "aadhaar_seeding_status_desc": "Aadhaar is linked to PAN"
    }
}
```


# Passport
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/smart-ocr/success-responses/passport

Examine the Cashfree Smart OCR success response for a passport document to map fields such as passport number, holder details, dates, and place of issue.

This page provides the success response of the Smart OCR API for the Passport document.

<CodeGroup>
  ```Text PASSPORT_FRONT theme={"dark"}
  {
      "verification_id": "test_verification_id",
      "reference_id": 1358,
      "status": "VALID",
      "document_type": "PASSPORT_FRONT",
      "document_fields": {
          "birth_city": "Gwalior",
          "country_code": "IND",
          "dob": "1964-02-15",
          "expiry_date": "2023-06-05",
          "gender": "M",
          "given_name": "John Doe",
          "issue_city": "Gwalior",
          "issue_date": "2013-06-06",
          "mrz": {
              "line1": "P<INDDOE<<JOHN<DOE<<<<<<<<<<<<<<<<<<<<",
              "line2": "L1234567<0IND6402156M2306123<<<<<<<<<<<<<<<6"
          },
          "nationality": "INDIAN",
          "passport_number": "L1234567",
          "surname": "Doe"
      }
  }
  ```

  ```Text PASSPORT_BACK theme={"dark"}
  {
      "verification_id": "test_verification_id1",
      "reference_id": 1358,
      "status": "VALID",
      "document_type": "PASSPORT_BACK",
      "document_fields": {
          "address": "S / O Josh Doe, 202-parivar daser complex , dal  bazar , Gird , Gwalior , Lashkar City , Madhya Pradesh , 474019",
          "father_name": "John Doe",
          "file_number": "AB1077777915514",
          "mother_name": "Josh Doe",
          "old_issue_city": "Gwalior",
          "old_issue_date": "2007-02-14",
          "old_passport_number": "M1234567",
          "passport_num": "L1234567",
          "pin": "474019",
          "spouse_name": "Doe"
      }
  }
  ```
</CodeGroup>


# Vehicle RC
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/smart-ocr/success-responses/vehicle-rc

Review the Cashfree Smart OCR success response for a Vehicle Registration Certificate to extract vehicle owner, chassis, engine, and registration details.

This page provides the success response of the Smart OCR API for the Vehicle Registration Certificate (RC) document.

<CodeGroup>
  ```Text VEHICLE_RC theme={"dark"}
  {
      "verification_id": "test_verification_id1",
      "reference_id": 1358,
      "status": "VALID",
      "document_type": "VEHICLE_RC",
      "document_fields": {
          "address": "S / O Josh Doe, 202-parivar daser complex , dal  bazar , Gird , Gwalior , Lashkar City , Madhya Pradesh , 474019",
          "chassis_number": "AB2A36FX5RCA68564",
          "engine_number": "ABCDEA82167",
          "manufacturer_name": "BAJAJ AUTO LTD",
          "manufacturing_date": "2024-04",
          "owner_name": "John Doe",
          "registration_date": "2024-05-22",
          "registration_number": "UP12KD1234",
          "registration_validity": "2039-05-21",
          "relation_name": "Josh Doe",
          "type": "ind_rc",
          "vehicle_model": "PULSAR NS 200",
          "vehicle_type": "M-Cycle/Scooter"
      }
  }
  ```
</CodeGroup>


# Voter ID
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/smart-ocr/success-responses/voterId

Inspect the Cashfree Smart OCR success response for a Voter ID card to map extracted fields such as EPIC number, voter name, parent name, and address.

This page provides the success response of the Smart OCR API for the Voter ID document.

<CodeGroup>
  ```Text VOTER_ID_FRONT theme={"dark"}
  {
      "verification_id": "test_verification_id",
      "reference_id": 1358,
      "status": "VALID",
      "document_type": "VOTER_ID_FRONT",
      "document_fields": {
          "age_on_issue_date": "20",
          "dob": "2004-06-10",
          "epic_number": "ABC1234567",
          "gender": "Male",
          "issue_date": "2024-09-07",
          "name": "John Doe",
          "relative_name": "Josh Doe",
          "type_voter_id": "New"
      }
  }
  ```

  ```Text VOTER_ID_BACK theme={"dark"}
  {
      "verification_id": "test_verification_id",
      "reference_id": 1358,
      "status": "VALID",
      "document_type": "VOTER_ID_BACK",
      "document_fields": {
          "address": "S / O Josh Doe, 202-parivar daser complex , dal  bazar , Gird , Gwalior , Lashkar City , Madhya Pradesh , 474019",
          "age_on_issue_date": "20",
          "dob": "2004-06-10",
          "epic_number": "ABC1234567",
          "gender": "Male",
          "issue_date": "2024-09-07",
          "state": "Gwalior",
          "type_voter_id": "New"
      }
  }
  ```
</CodeGroup>


# Verify Udyam
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/udyam/verify-udyam

post /udyam
Use this API to verify an Udyam registration using the Udyam reference number. For a valid registration, the response returns enterprise details such as NIC classification and enterprise unit information. 

View the [test data](https://www.cashfree.com/docs/api-reference/vrs/data-to-test-integration#udyam) and use the information to trigger the validations. The test data can be used only in the sandbox environment.



# UPI Penny Drop Request
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/upi-penny-drop/create-upi-penny-drop-request

post /upi/penny-drop
Use this API to to validate bank account details by sending a one rupee UPI transaction to the provided VPA and retrieving the associated bank account information.

View the [test data](https://www.cashfree.com/docs/api-reference/vrs/data-to-test-integration#upi-penny-drop) and use the information to trigger the validations. The test data can be used only in the sandbox environment.



# Get Vehicle RC Status
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/vehicle-rc/get-vehicle-rc-details

get /vehicle-rc
Use this API to get the details and status of the vehicle [Verify Vehicle RC API](https://www.cashfree.com/docs/api-reference/vrs/v2/vehicle-rc/get-vehicle-rc-details-1) request by passing the reference ID or verification ID.



# Verify Vehicle RC Details
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/vehicle-rc/get-vehicle-rc-details-1

post /vehicle-rc
Use this API to verify whether the vehicle information passed in the request is valid.

View the [test data](https://www.cashfree.com/docs/api-reference/vrs/data-to-test-integration#registration-certificate-vehicle) and use the information to trigger the validations. The test data can be used only in the sandbox environment.



# API Rate Limits
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/verification-rate-limits

Review transactions-per-minute rate limits for Cashfree Secure ID verification APIs and follow best practices to keep production traffic within quotas.

To maintain service reliability, protect against abuse, and ensure consistent quality of service for all users, the following rate limits apply to the APIs. All Secure ID verification APIs are subject to rate limits measured in **transactions per minute (TPM)**. These limits apply per merchant account and are categorised based on resource requirements and typical usage patterns of each API.

<CardGroup>
  <Card title="Standard" icon="server">
    **100 TPM**: Verification APIs that require real-time processing and external data validation
  </Card>

  <Card title="Medium" icon="bolt">
    **200 TPM**: Lightweight verification services with faster processing capabilities
  </Card>

  <Card title="Restricted" icon="clock">
    **5 TPM**: Resource-intensive bulk operations that require significant processing time
  </Card>
</CardGroup>

## Rate limits

<Tabs>
  <Tab title="Standard (100 TPM)">
    **Standard rate limit: 100 transactions per minute**

    Secure ID APIs that require real-time processing and external data validation.

    | API | Description |
    | :- | :- |
    | [Aadhaar Masking](/docs/api-reference/vrs/v2/aadhaar/aadhaar-masking) | Masks sensitive Aadhaar information |
    | [Bank Account Verification Async V2](/docs/api-reference/vrs/v2/bav-v2/bank-account-verification-async-v2) | Asynchronous bank account validation |
    | [Bank Account Verification Sync V2](/docs/api-reference/vrs/v2/bav-v2/bank-account-verification-sync-v2) | Synchronous bank account validation |
    | [Create Auth Token](/docs/api-reference/vrs/v2/video-kyc/oauth-token) | Creates authentication token for Video KYC |
    | [Create E-Sign Request](/docs/api-reference/vrs/v2/e-sign/create-e-sign-request) | Initiates electronic signature process |
    | [Create User for Secure ID Suite](/docs/api-reference/vrs/v2/video-kyc/add-user) | Creates user profile for Video KYC |
    | [Data Availability](/docs/api-reference/vrs/v2/1-click-onboarding/data-availability) | Checks data availability for verification |
    | [Deactivate Static KYC Link](/docs/api-reference/vrs/v2/kyc-links/deactivate-static-link) | Deactivates static KYC verification link |
    | [Driving Licence](/docs/api-reference/vrs/v2/driving-license/verify-driving-licence-details) | Validates driving licence information |
    | [Employee Details](/docs/api-reference/vrs/v2/advanced-employment/get-employment-details) | Retrieves employment verification data |
    | [Face Match](/docs/api-reference/vrs/v2/face-match/face-match) | Compares facial biometric data |
    | [Fetch Financial Information](/docs/api-reference/vrs/v2/account-aggregator/account-aggregator-fetch-fi-data) | Retrieves financial account information |
    | [Fetch GSTIN with PAN](/docs/api-reference/vrs/v2/pan-to-gstin/fetch-gstin-with-pan) | Retrieves GST numbers linked to PAN |
    | [Fetch User Details From Access Token](/docs/api-reference/vrs/v2/1-click-onboarding/fetch-user-details-from-access-token) | Retrieves user details using access token |
    | [Generate Static KYC Link](/docs/api-reference/vrs/v2/kyc-links/generate-static-link) | Generates static KYC verification link |
    | [Geocoding](/docs/api-reference/vrs/v2/geocoding/geocoding) | Converts address to geographical coordinates |
    | [Get BAV Status V2](/docs/api-reference/vrs/v2/bav-v2/get-bav-status-v2) | Retrieves bank account verification status |
    | [Get Consent Status](/docs/api-reference/vrs/v2/account-aggregator/account-aggregator-get-consent-status) | Checks consent status for data access |
    | [Get E-Sign Status](/docs/api-reference/vrs/v2/e-sign/get-e-sign-status) | Checks electronic signature status |
    | [Get Status for Verify PAN in Bulk](/docs/api-reference/vrs/v2/pan/get-status-for-verify-pan-in-bulk) | Retrieves bulk PAN verification status |
    | [Get Status of Aadhaar Verification via OCR](/docs/api-reference/vrs/v2/smart-ocr/smart-ocr) | Checks OCR-based Aadhaar verification |
    | [Get Status of PAN Verification via Smart OCR](/docs/api-reference/vrs/v2/smart-ocr/smart-ocr) | Checks OCR-based PAN verification |
    | [Get Status of Verify PAN Sync](/docs/api-reference/vrs/v2/pan/get-status-of-verify-pan-sync) | Checks synchronous PAN verification status |
    | [Get Video KYC Status](/docs/api-reference/vrs/v2/video-kyc/get-vkyc-status) | Gets Video KYC session status |
    | [IFSC Verification V2](/docs/api-reference/vrs/v2/ifsc/ifsc-verification-v2) | Validates IFSC codes and retrieves bank branch details |
    | [Initiate Video KYC Request](/docs/api-reference/vrs/v2/video-kyc/initiate-vkyc) | Starts Video KYC verification process |
    | [Mobile 360 Send OTP Request](/docs/api-reference/vrs/v2/mobile-360-otp-flow/mobile-360-send-otp-request) | Sends OTP for mobile verification |
    | [Mobile 360 Verify OTP](/docs/api-reference/vrs/v2/mobile-360-otp-flow/mobile-360-verify-otp) | Verifies OTP for mobile authentication |
    | [Name Match](/docs/api-reference/vrs/v2/name-match/name-match) | Compares name variations and matches |
    | [PAN 360](/docs/api-reference/vrs/v2/pan/pan-360) | Comprehensive PAN details and validation |
    | [Initiate OAuth](/docs/api-reference/vrs/v2/1-click-onboarding/initiate-oauth) | Initiates OAuth authentication process |
    | [OAuth Access Token Generation](/docs/api-reference/vrs/v2/1-click-onboarding/oauth-access-token-generation) | Generates OAuth access token |
    | [Passport](/docs/api-reference/vrs/v2/passport/verify-passport) | Validates passport information |
    | [Request Consent](/docs/api-reference/vrs/v2/account-aggregator/account-aggregator-consent-request) | Requests user consent for data access |
    | [Request Financial Information](/docs/api-reference/vrs/v2/account-aggregator/account-aggregator-request-fi) | Requests access to financial data |
    | [Reverse Geocoding](/docs/api-reference/vrs/v2/reverse-geocoding/reverse-geocoding) | Converts coordinates to address information |
    | [Smart OCR](/docs/api-reference/vrs/v2/smart-ocr/smart-ocr) | Optical character recognition for documents |
    | [Upload Document For E-Sign](/docs/api-reference/vrs/v2/e-sign/upload-document-for-e-sign) | Uploads documents for electronic signing |
    | [Vehicle RC](/docs/api-reference/vrs/v2/vehicle-rc/get-vehicle-rc-details) | Retrieves vehicle registration details |
    | [Verify CIN](/docs/api-reference/vrs/v2/cin/verify-cin) | Validates Corporate Identity Numbers |
    | [Verify GSTIN](/docs/api-reference/vrs/v2/gstin/verify-gstin) | Validates GST identification numbers |
    | [Voter ID](/docs/api-reference/vrs/v2/voter-id/verify-voter-id) | Validates voter identification cards |
    | [UPI Penny Drop](/docs/api-reference/vrs/v2/upi-penny-drop/create-upi-penny-drop-request) | Validates bank account via one rupee UPI transaction to VPA |
  </Tab>

  <Tab title="Medium (200 TPM)">
    **Medium rate limit: 200 transactions per minute**

    Lightweight verification services with faster processing capabilities.

    | API | Description |
    | :- | :- |
    | [Create DigiLocker URL](/docs/api-reference/vrs/v2/digilocker/create-digilocker-url) | Creates DigiLocker integration link |
    | [Create Reverse Penny Drop Request](/docs/api-reference/vrs/v2/reverse-penny-drop/create-reverse-penny-drop-request) | Initiates reverse penny drop verification |
    | [Generate KYC Link](/docs/api-reference/vrs/v2/kyc-links/generate-form-link) | Generates KYC verification link |
    | [Get DigiLocker Verification Status](/docs/api-reference/vrs/v2/digilocker/get-digilocker-verification-status) | Checks DigiLocker document verification |
    | [Get Document from DigiLocker](/docs/api-reference/vrs/v2/digilocker/get-document-from-digilocker) | Retrieves documents from DigiLocker |
    | [Get KYC Link Status](/docs/api-reference/vrs/v2/kyc-links/get-form-status) | Gets KYC link verification status |
    | [Get Reverse Penny Drop Request Details](/docs/api-reference/vrs/v2/reverse-penny-drop/get-reverse-penny-drop-request-details) | Retrieves reverse penny drop status |
    | [IP](/docs/api-reference/vrs/v2/ip/verify-ip) | Validates IP address information |
    | [Verify PAN Sync](/docs/api-reference/vrs/v2/pan/verify-pan-sync) | Synchronous PAN verification |
  </Tab>

  <Tab title="Restricted (5 TPM)">
    **Restricted rate limit: 5 transactions per minute**

    Resource-intensive bulk operations that require significant processing time.

    | API | Description |
    | :- | :- |
    | [Verify PAN in Bulk](/docs/api-reference/vrs/v2/pan/verify-pan-in-bulk) | Processes multiple PAN verifications simultaneously |
  </Tab>
</Tabs>

## Rate limit error handling

When you exceed the rate limit for any API, the system returns an HTTP 429 status code.

<Accordion title="Error Response Structure">
  The following response structure is returned when rate limits are exceeded:

  ```json theme={"dark"}
  {
    "type": "invalid_request_error",
    "code": "rate_limit_exceeded",
    "message": "Too many requests",
    "details": [
      {
        "field": "rate_limit",
        "issue": "Rate limit exceeded for this endpoint"
      }
    ]
  }
  ```
</Accordion>

## Best practices for rate limit management

Use these guidelines to optimise your API usage and avoid rate limit errors.

<Accordion title="Implement exponential backoff">
  When you receive a 429 response, implement retry logic with exponential backoff:

  ```javascript theme={"dark"}
  async function makeAPIRequest(url, options, maxRetries = 3) {
    for (let attempt = 1; attempt <= maxRetries; attempt++) {
      try {
        const response = await fetch(url, options);
        
        if (response.status === 429) {
          const retryAfter = response.headers.get('retry-after');
          const delay = retryAfter ? parseInt(retryAfter) * 1000 : Math.pow(2, attempt) * 1000;
          
          console.log(`Rate limit exceeded. Retrying after ${delay}ms`);
          await new Promise(resolve => setTimeout(resolve, delay));
          continue;
        }
        
        return response;
      } catch (error) {
        if (attempt === maxRetries) throw error;
      }
    }
  }
  ```
</Accordion>

<Accordion title="Monitor rate limit headers">
  Check the rate limit headers in successful responses to proactively manage your request timing:

  ```javascript theme={"dark"}
  const response = await fetch('/api/verify-gstin', options);

  const remaining = response.headers.get('X-RateLimit-Remaining');
  const resetTime = response.headers.get('X-RateLimit-Reset');

  if (parseInt(remaining) < 10) {
    console.log('Approaching rate limit. Consider slowing down requests.');
  }
  ```
</Accordion>

<Accordion title="Distribute requests evenly">
  Avoid sending bursts of requests at the beginning of each minute. Instead, distribute your requests evenly throughout the time window.

  **Example strategy:**

  * For 100 TPM limit: Send 1 request every \~600ms
  * For 200 TPM limit: Send 1 request every \~300ms
  * For 5 TPM limit: Send 1 request every \~12 seconds
</Accordion>

## Requesting rate limit increases

If your application requires higher rate limits, you can submit a request through the [support form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) or contact your account manager directly. When you submit your request, include the following information:

* Your merchant ID
* Current usage patterns and volumes
* Expected future usage requirements
* Business justification for the increase

Your account manager can provide faster processing and personalised assistance for rate limit increase requests.


# Create User for Secure ID
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/video-kyc/add-user

post /user
Use this API to create a Secure ID user profile, which is required to initiate Video KYC verification.



# Get User Detail
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/video-kyc/get-user

get /user
Use this API to retrieve the details of a user registered for Video KYC. You can fetch user information using either the **user_id** (provided by you) or the **user_reference_id** (generated by Cashfree).



# Get status of Video KYC
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/video-kyc/get-vkyc-status

get /vkyc
Use this API to check the status of a Video KYC request by passing `reference_id` or the `verification_id`. The API returns the current status of the Video KYC request along with user details.



# Initiate Video KYC Request
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/video-kyc/initiate-vkyc

post /vkyc
Use this API to generate a Video KYC verification link for a user and send it through the configured notification channels (SMS, email, or WhatsApp). The message content can be configured using user and agent templates.

<Note>
  **Template Behaviour**: Including Aadhaar details in this request skips the DigiLocker verification step, reducing the user journey from 3 steps to 2. See [User Templates](/docs/api-reference/vrs/v2/video-kyc/vkyc-descriptions#user-templates) for details.
</Note>


# Create Auth Token to Initialise the SDK
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/video-kyc/oauth-token

post /oauth/token
Use this API to generate an authentication token required to initialise the Cashfree SDK by passing your `app_id`, and product name (such as Video KYC) in the request body. 



# Update User Detail
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/video-kyc/update-user

patch /user
Update User Detail.



# Status Codes and Templates
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/video-kyc/vkyc-descriptions

Reference every Cashfree VKYC status, sub-status combination, user template, and agent template you need to interpret responses and configure your flow.

This reference guide explains the status codes, user templates, and agent templates available for Video KYC (VKYC) implementation. Use this information to understand response parameters and configure your VKYC flow.

## Status and sub-status reference

The following table describes all possible status and sub-status combinations returned by the VKYC API, along with recommended actions for each scenario.

### Request status types

The status codes are organised by verification phase. Each phase contains specific sub-status codes that indicate the current state and required actions.

<Accordion title="REJECTED - Request rejected">
  | Sub-status | Description | Recommended action |
  | - | - | - |
  | `INSUFFICIENT_BALANCE` | The request is rejected due to insufficient balance | Add funds to your account and retry the request |
</Accordion>

<Accordion title="RECEIVED - Request accepted">
  | Sub-status | Description | Recommended action |
  | - | - | - |
  | `LINK_GENERATED` | The link for Video KYC was generated successfully | Share the link with the user through your preferred channel |
</Accordion>

<Accordion title="PRE_VIDEO_CALL - Pre-verification checks">
  | Sub-status | Description | Recommended action |
  | - | - | - |
  | `AADHAAR_VERIFICATION_SUCCESS` | The user's Aadhaar details were verified successfully | Proceed to the next verification step |
  | `AADHAAR_VERIFICATION_FAILED` | The user's Aadhaar details could not be verified | Ask the user to retry with correct Aadhaar information |
  | `AADHAAR_VERIFICATION_EXPIRED` | The Aadhaar verification session expired | Restart the Aadhaar verification process |
  | `USER_IP_VERIFICATION_SUCCESSFUL` | The user's IP address was verified successfully | Continue with the verification flow |
  | `USER_PROXY_DETECTED` | A proxy or VPN was detected | Ask the user to disable proxy/VPN and retry |
  | `TECHNICAL_FAILURE` | A technical issue occurred during verification | Retry after some time or contact support |
  | `USER_LOCATION_VERIFICATION_SUCCESS` | The user's location was verified successfully | Proceed to device checks |
  | `USER_LOCATION_OUTSIDE_INDIA` | The user is outside India | Reject the request or ask user to retry from India |
  | `USER_AUDIO_CHECK_FAILED` | The user's microphone is not enabled | Ask the user to enable microphone access |
  | `USER_VIDEO_CHECK_FAILED` | The user's camera is not enabled | Ask the user to enable camera access |
  | `USER_LOCATION_PERMISSION_DISABLED` | The user did not grant location access | Ask the user to allow location permissions |
  | `USER_DEVICE_CHECK_SUCCESS` | The user's device passed all checks | Proceed to agent assignment |
  | `USER_QUEUED` | The user is waiting for an available agent | Display queue position and estimated wait time |
  | `SCHEDULED_USER_QUEUED` | The user is queued for a scheduled appointment | Notify user of scheduled time |
  | `NO_AGENT_FOUND` | No agent is available at this time | Retry after some time or offer scheduling |
  | `AGENT_ASSIGNED_TO_USER` | An agent has been assigned to the user | Notify user that verification will begin |
  | `USER_MEETING_SCHEDULED` | The user's meeting is scheduled successfully | Send meeting details to the user |
  | `USER_MEETING_CANCELLED` | The user's meeting was cancelled | Offer rescheduling options |
  | `VKYC_EXPIRED` | The user's VKYC link has expired | Resend the VKYC link to the user |
</Accordion>

<Accordion title="VIDEO_CALL - During video verification">
  | Sub-status | Description | Recommended action |
  | - | - | - |
  | `USER_ACCEPTED_MEETING` | The user accepted the meeting invitation | Start the VKYC verification process |
  | `USER_REJECTED_MEETING` | The user rejected the meeting invitation | Reschedule or mark verification as failed |
  | `USER_MISSED_MEETING` | The user missed the scheduled meeting | Offer rescheduling options |
  | `USER_DROPPED_OFF` | The user disconnected during verification | Log the issue and offer reconnection |
  | `AGENT_DROPPED_OFF` | The agent disconnected during verification | Retry with another agent |
  | `USER_ENDED_CALL` | The user ended the call | Review session completeness |
  | `AGENT_ENDED_CALL` | The agent ended the call | Review agent's remarks and next steps |
</Accordion>

<Accordion title="FAILED - Verification failed">
  | Sub-status | Description | Recommended action |
  | - | - | - |
  | `TECHNICAL_ERROR` | A technical error occurred during verification | Retry the verification or escalate to support |
</Accordion>

<Accordion title="AGENT_REVIEWED - Agent review complete">
  | Sub-status | Description | Recommended action |
  | - | - | - |
  | `AGENT_APPROVED` | The agent approved the user's KYC verification | Proceed to auditor review stage |
  | `AGENT_REJECTED` | The agent rejected the user's KYC verification | Notify user with rejection reason |
  | `AGENT_UNABLE_TO_VALIDATE` | The agent could not complete validation | Retry with another agent or new session |
</Accordion>

<Accordion title="AUDITOR_REVIEWED - Final review complete">
  | Sub-status | Description | Recommended action |
  | - | - | - |
  | `AUDITOR_APPROVED` | The auditor approved the user's KYC verification | Mark verification as complete |
  | `AUDITOR_REJECTED` | The auditor rejected the user's KYC verification | Mark verification as failed |
</Accordion>

## User templates

User templates define the customer journey and determine which verification steps are included in the VKYC process. The template you choose affects the user experience and verification flow.

### vkyc\_user\_template\_v1

This is the standard template that includes mobile OTP authentication, conditional DigiLocker Aadhaar verification, and agent-assisted video verification.

The template behaviour depends on whether Aadhaar details are provided in the [Initiate Video KYC Request](/docs/api-reference/vrs/v2/video-kyc/initiate-vkyc):

<Tabs>
  <Tab title="With Aadhaar details">
    **When Aadhaar details are provided:** The DigiLocker verification step is skipped, creating a streamlined 2-step process.

    <CardGroup>
      <Card title="Step 1: Mobile authentication" icon="mobile">
        <img alt="Mobile OTP authentication screen" />

        <p>User authenticates using mobile OTP sent to their registered number</p>
      </Card>

      <Card title="Step 2: Video verification" icon="video">
        <img alt="Video verification start screen" />

        <p>Direct connection with verification agent for identity confirmation</p>
      </Card>
    </CardGroup>
  </Tab>

  <Tab title="Without Aadhaar details">
    **When Aadhaar details are not provided:** The complete 3-step verification process including DigiLocker authentication.

    <CardGroup>
      <Card title="Step 1: Mobile authentication" icon="mobile">
        <img alt="Mobile OTP authentication screen" />

        <p>User authenticates using mobile OTP</p>
      </Card>

      <Card title="Step 2: DigiLocker verification" icon="id-card">
        <img alt="DigiLocker Aadhaar verification screen" />

        <p>Aadhaar verification through DigiLocker</p>
      </Card>

      <Card title="Step 3: Video verification" icon="video">
        <img alt="Video verification start screen" />

        <p>Agent-assisted video verification call</p>
      </Card>
    </CardGroup>
  </Tab>
</Tabs>

<Note>
  **Custom templates:** To create a custom `user_template` tailored to your specific requirements, contact your account manager.
</Note>

## Agent templates

Agent templates define the verification steps that agents must complete during the VKYC process. These templates ensure consistent verification procedures across all sessions.

### vkyc\_agent\_template\_v2

This is the default template used by verification agents during the VKYC process. It includes standardised verification steps and documentation requirements.

<Card title="Default agent verification template" icon="user-check">
  <div>
    <img alt="Default agent template interface showing verification steps" />
  </div>

  <p>
    Standard agent interface with verification checklist and documentation requirements
  </p>
</Card>

<Note>
  **Custom agent templates:** To create a custom `agent_template` with specific verification steps or compliance requirements, contact your account manager.
</Note>


# Video KYC Integration
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/video-kyc/vkyc-integration

Choose between SDK and API integrations for Cashfree Video KYC to meet RBI-compliant remote onboarding requirements with live agent-assisted verification.

Cashfree Video KYC (VKYC) is a secure, RBI-compliant digital customer verification solution that enables businesses to complete customer onboarding remotely through a live video interaction. Merchants can choose to integrate VKYC in two ways, depending on their user experience requirements and technical capabilities.

Cashfree offers the following ways to integrate VKYC:

**Integrating using the SDK**

* Integrate the VKYC process directly into your web or mobile application.
* Provide a seamless in-app experience for customers without redirecting them.
* Support an OTP-less flow if the customer is already authenticated in your application.
* Use SDK callbacks to handle events such as success, failure, or closure, and to track activity and customise your user interface.

**Integrating using the APIs**

* Generate a unique VKYC link for each customer.
* Share the link via SMS, email, or any external channel.
* Allow customers to complete the VKYC process outside your application.

<Tabs>
  <Tab title="Integrating using the SDK">
    The VKYC SDK supports **Web**, **Android**, and **iOS** platforms and communicates securely with Cashfree servers through callbacks.

    This topic includes the following sections:

    1. [SDK VKYC flow](/docs/api-reference/vrs/v2/video-kyc/vkyc-integration#sdk-vkyc-flow)
    2. [Initialising SDK](#initialising-sdk)
    3. [Callback structure](#callback-structure)

    ### SDK VKYC flow

    Refer to the steps below for the VKYC flow for SDK:

    1. Create the user using the [Create User for Secure ID Suite API](/docs/api-reference/vrs/v2/video-kyc/add-user). You must complete this step before initiating the VKYC session.
    2. Start the VKYC session using the [Initiate Video KYC Request API](/docs/api-reference/vrs/v2/video-kyc/initiate-vkyc). Pass the user ID and authentication token to the SDK.
    3. Generate an authentication token using the [Create Auth Token API](/docs/api-reference/vrs/v2/video-kyc/oauth-token). This token is required to initialise the SDK. Use it to bypass OTP verification if the user is already authenticated in your application.
    4. Retrieve the current session status using the [Get Video KYC Status API](/docs/api-reference/vrs/v2/video-kyc/get-vkyc-status).
    5. Configure webhooks to receive real-time updates on VKYC events. For more information, refer to [Webhook](/docs/api-reference/vrs/v2/video-kyc/webhook).

    Refer to the image below for a sample workflow:

    <img />

    ### Initialising SDK

    Refer to the instructions below to initialise the SDK for your target platform. The SDK communicates with Cashfree and provides real-time updates through callbacks.

    You can initialise the SDK for:

    * [Web](/docs/api-reference/vrs/v2/video-kyc/vkyc-integration#web-integration)
    * [Android native](/docs/api-reference/vrs/v2/video-kyc/vkyc-integration#android-native-integration)
    * [iOS native](/docs/api-reference/vrs/v2/video-kyc/vkyc-integration#ios-native-integration)

    #### Web integration

    **Initialise the Web SDK**

    Refer to the example code snippet below to initialise the Web SDK:

    ```javascript theme={"dark"}
    const vkyc = CFVKYC({
      srcUrl: "https://forms.cashfree.com/verification/<shortCode>",
      oAuthToken: "<OAuth Token>", // Optional: enables OTP-less flow
      callback: (response) => {
        console.log("VKYC Response:", response);
      },
    });
    ```

    | Parameter | Type | Required | Description |
    | - | - | - | - |
    | `srcUrl` | string | Yes | Base or full VKYC verification URL. |
    | `oAuthToken` | string | No | Pass this token for OTP-less flow. |
    | `callback` | function | Yes | Handles all SDK messages and responses. |

    <Note> Do not pass the OAuth token if you want Cashfree to perform the OTP check. </Note>

    **Close the SDK programmatically**

    Refer to the code snippet below to close the SDK instance in your application:

    ```javascript theme={"dark"}
    vkyc.closeSDK();
    ```

    **Import the hosted JavaScript SDK**

    Refer to the instructions below to import the SDK script into your HTML page.

    1. Add the SDK script for your environment.

       **Production environment:**

       ```html theme={"dark"}
       <script src="https://vssdk-prod.cashfree.com/vkyc-sdk/prod/1.0.0/index.js"></script>
       ```

       **Sandbox environment:**

       ```html theme={"dark"}
       <script src="https://vssdk-prod.cashfree.com/vkyc-sdk/gamma/1.0.0/index.js"></script>
       ```

    2. Include a `<div>` for the SDK container.

       ```html theme={"dark"}
       <html>
         <head>
           <title>Video KYC</title>
           <script src="https://vssdk-prod.cashfree.com/vkyc-sdk/prod/1.0.0/index.js"></script>
         </head>
         <body>
           <div id="cf-vkyc-sdk"></div>
         </body>
       </html>
       ```

    ### Android native integration

    **Add the SDK dependency**

    Refer to the steps below to add the SDK to your Android project.

    1. Add the Maven repository in `settings.gradle.kts`.

       ```kotlin theme={"dark"}
       repositories {
           google()
           mavenCentral()
           maven { url = URI("https://maven.cashfree.com/release") }
       }
       ```

    2. Add the SDK dependency in `build.gradle.kts`.

       ```kotlin theme={"dark"}
       dependencies {
           implementation("com.cashfree.vrs:kyc-verification:1.0.4")
       }
       ```

    3. Click **Sync Now** in Android Studio to sync your project.

    **Initialise and use the SDK**

    1. Create an instance of the verification service.

       ```kotlin theme={"dark"}
       val verificationService = CFVerificationService.Builder()
           .setContext(this)
           .build()
       ```

    2. Configure the callback to handle verification responses.

       ```kotlin theme={"dark"}
       verificationService.setKycVerificationCallback(object : CFVerificationCallback {
           override fun onVerificationResponse(response: CFVerificationResponse) {
               showAlert(response)
           }

           override fun onErrorResponse(error: CFErrorResponse) {
               showAlert("Verification Error", error.message)
           }

           override fun onVKycCloseResponse(response: CFVKycCloseResponse) {
               showAlert("VKYC Closed", response.verificationId)
           }
       })
       ```

    3. Initiate the verification process.

       ```kotlin theme={"dark"}
       verificationService.doVerification(kycUrl, token)
       ```

    | Parameter | Description |
    | - | - |
    | `kycUrl` | VKYC video call URL |
    | `token` | Authentication token for VKYC |

    ### iOS native integration

    The following are the requirements before integrating the iOS SDK:

    * iOS version: 13.0 or later
    * Swift version: 5.0 or later
    * Xcode version: 14.0 or later

    **Install the SDK**

    To install the SDK:

    1. Open your Xcode project.
    2. Go to **File > Add Packages**.
    3. Enter the repository URL:

       ```
       https://github.com/cashfree/KycVerificationSdk.git
       ```
    4. Select the version and add the package to your project.

    **Initialise and use the SDK**

    1. Create an instance.

       ```swift theme={"dark"}
       let kycService = CFVerificationService.getInstance()
       ```

    2. Set up callback handlers.

       ```swift theme={"dark"}
       func onVerificationCompletion(verificationResponse: KycVerificationSdk.CFVerificationResponse) {
           if verificationResponse.status == "SUCCESS" {
               print("Success: Verification successful")
           } else {
               print("Error: Verification failed, please try again")
           }
       }

       func onErrorResponse(errorReponse: KycVerificationSdk.CFErrorResponse) {
           print("Error: \(errorReponse.message ?? "")")
       }

       func onVerification(_ verificationResponse: KycVerificationSdk.CFSecureShareResponse) {
           print("Verification ID: \(verificationResponse.verificationId ?? "N/A")")
       }

       func onVerificationError(_ errorResponse: KycVerificationSdk.CFSecureShareErrorResponse) {
           print("Error Status: \(errorResponse.status ?? "N/A")")
       }

       func onUserDrop(_ userDropResponse: KycVerificationSdk.CFUserDropResponse) {
           print("User Dropped: \(userDropResponse.verificationId ?? "N/A")")
       }

       func onVkycCloseResponse(verificationResponse: KycVerificationSdk.CFVKycCloseResponse) {
           print("VKYC Closed")
       }
       ```

    3. Start the VKYC session.

       ```swift theme={"dark"}
       do {
           let kycService = CFVerificationService.getInstance()
           try kycService.doVerification(kycUrl, self, self, accessToken)
       } catch let error {
           print("Error: \(error)")
       }
       ```

    ### Callback structure

    Refer to the sample response below for the VKYC callback structure:

    ```json theme={"dark"}
    {
      "verificationId": "verificationId_value",
      "status": "<STATUS>"
    }
    ```

    | Status | Description |
    | - | - |
    | `TOKEN_EXPIRED` | The OAuth token has expired. |
    | `SRC_URL_MISSING` | The `srcUrl` parameter isn't provided. |
    | `DIV_MISSING` | The `<div>` with ID `cf-vkyc-sdk` is missing. |
    | `CLOSE` | The SDK session was closed by Cashfree. |

    <Note>
      **Additional Notes:**

      * Ensure the `<div>` with ID `cf-vkyc-sdk` exists in your HTML.
      * The SDK applies default styling for consistent behaviour. Custom styling is not supported.
      * The embedded iframe uses sandboxing for secure interactions.
    </Note>
  </Tab>

  <Tab title="Integrating using the APIs">
    Use a standalone link if you prefer to reach customers through external channels instead of integrating the flow in your app.

    To share a standalone VKYC link integrate the following APIs:

    1. Create the user using the [Create User for Secure ID Suite API](/docs/api-reference/vrs/v2/video-kyc/add-user). You must complete this step before initiating the VKYC session.
    2. Get the VKYC link using the [Initiate Video KYC Request API](/docs/api-reference/vrs/v2/video-kyc/initiate-vkyc). Pass the user ID.
    3. Retrieve the current session status using the [Get Video KYC Status API](/docs/api-reference/vrs/v2/video-kyc/get-vkyc-status).
    4. Configure webhooks to receive real-time updates on VKYC events. For more information, refer to [Webhook](/docs/api-reference/vrs/v2/video-kyc/webhook).
  </Tab>
</Tabs>


# Integration Overview
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/video-kyc/vkyc-overview

Discover how Cashfree Video KYC streamlines remote customer verification with secure, RBI-compliant agent-led video sessions and easy integration options.

Cashfree's Video KYC (VKYC) is a digital solution that enables businesses to verify customer identities remotely through a secure, agent-assisted video call. It helps businesses meet RBI-mandated Know Your Customer (KYC) requirements with a seamless, scalable, and easy-to-integrate process.

## Key features

Cashfree Video KYC (VKYC) offers the following features to help you verify your customers quickly and securely:

* **Capture a customer photograph**: Take a live photo of your customer and match it with the photo on an official KYC document, such as an Aadhaar card. This feature supports high-quality image capture, even in low-bandwidth conditions.

* **Verify customer identity**: Verify your customer's identity using OTP-based verification or through DigiLocker authentication. The details are verified against official sources.

* **Capture a PAN card image**: Capture a photo of your customer's PAN card to extract key details. These details are validated against trusted databases.

* **Use geo-tagging for compliance**: Confirm that your customer is located in India, as required by RBI regulations.

* **Perform a liveness check**: Ask a registered entity (RE) agent to confirm your customer's physical presence. During the check, the agent asks the customer to read a randomly generated 4-digit number.

* **Assign agents for VKYC**: Meet RBI requirements by completing VKYC through a live agent. Use the agent assignment module to manage and track this process.

* **Access session logs for auditing**: View logs for every VKYC session. Both you and Cashfree can use these logs for compliance audits.

## Integration options

Cashfree provides two options for integrating Video KYC based on your application flow:

* API-based integration for full control of the user experience

* SDK-based integration for an embedded, in-app experience

### Video KYC using APIs

Use this option if you want to manage the entire VKYC workflow through your backend and present a custom user interface.

1. **Create a user**: Register the user using the [Create User for Secure ID Suite API](/docs/api-reference/vrs/v2/video-kyc/add-user). This step is required before you initiate the VKYC session. The user profile includes basic details such as phone number, name, and address, and is required to initiate the KYC process.

2. **Initiate the Video KYC session**: Start the VKYC session using the [Initiate Video KYC Request API](/docs/api-reference/vrs/v2/video-kyc/initiate-vkyc) by generating a secure verification link. The link is sent through selected notification channels (SMS, email, or WhatsApp) and can be customised using user and agent templates.

3. **Get the VKYC status**: Retrieve the current VKYC session status using the [Get Video KYC Status API](/docs/api-reference/vrs/v2/video-kyc/get-vkyc-status). Use this to check if the session is pending, in progress, completed, or failed.

### Video KYC using the SDK

Use this option if you want to embed the VKYC flow directly into your mobile or web application using the Cashfree SDK.

1. **Create an authentication token**: Generate an auth token using the [Create Auth Token API](/docs/api-reference/vrs/v2/video-kyc/oauth-token). This token is required to initialise the SDK and allows you to bypass OTP verification if the user is already authenticated in your app.

2. **Create a user**: Register the user using the [Create User for Secure ID Suite API](/docs/api-reference/vrs/v2/video-kyc/add-user). This step must be completed before you initiate the VKYC session.

3. **Initiate the Video KYC session**: Start the VKYC session using the [Initiate Video KYC Request API](/docs/api-reference/vrs/v2/video-kyc/initiate-vkyc) and pass the user ID and authentication token to the SDK.

4. **Get the VKYC status**: Retrieve the current VKYC session status using the [Get Video KYC Status API](/docs/api-reference/vrs/v2/video-kyc/get-vkyc-status).

<Note>
  **Notes**:
  For detailed API documentation, refer to [Video KYC API](/docs/api-reference/vrs/v2/video-kyc/add-user) Integration.
</Note>


# Webhooks
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/video-kyc/webhook

Configure Cashfree Video KYC webhooks to receive real-time event updates so you can track session progress, completion, and outcomes without polling APIs.

Webhooks are event-based notifications that are received when specific events related to Video KYC occur. These notifications help you track the status and progress of VKYC in real-time.

## Add webhooks

Add your webhook URL in our system for us to deliver webhook events.

Follow the instructions below to configure the webhook URL. Ensure to provide the publicly accessible HTTPS URL to your webhook endpoint.

1. Log in to the **[Merchant Dashboard](https://merchant.cashfree.com/merchants/)** and click **Developers**.
2. Click **Webhooks** listed under the **Secure ID** card.
3. Click **Add Webhook URL** in the **Webhook** screen.
4. In the **Add Webhook** popup, fill in the following information:
   * **Webhook URL**: Enter the URL in this field.
5. Click **Test & Add Webhook**.

<Frame>
  <img />
</Frame>

## VKYC webhook events

The following events are triggered at different stages of the Video KYC process:

| Event | Description |
| :- | :- |
| VKYC\_USER\_LINK\_GENERATED | User VKYC link has been generated for the user. |
| VKYC\_USER\_LINK\_EXPIRED | User VKYC link has expired. |
| VKYC\_USER\_AADHAAR\_VERIFIED | User's Aadhaar has been successfully verified. |
| VKYC\_USER\_CALL\_SCHEDULED | User VKYC call has been scheduled. |
| VKYC\_USER\_PRECHECK\_FAILED | User Pre-verification checks have failed. |
| VKYC\_USER\_CALL\_QUEUED | User has joined and is waiting in the queue for an agent. |
| VKYC\_USER\_CALL\_STARTED | User VKYC call has started with an agent. |
| VKYC\_USER\_DROPOFF\_FROM\_CALL | User has dropped off from the VKYC call. |
| VKYC\_USER\_CALL\_COMPLETED | User VKYC call has been completed successfully. |
| VKYC\_AUDITOR\_REVIEW\_COMPLETED | Triggered when an auditor approves or rejects a VKYC packet. |

<AccordionGroup>
  <Accordion title="VKYC_USER_LINK_GENERATED">
    ```json theme={"dark"}
    {
      "signature": "wBBgeTOZUyXgj6vySAm9fJYCtdXvlVHQCA6dV5uVssw=",
      "event_type": "VKYC_USER_LINK_GENERATED",
      "event_time": "2025-05-22T03:51:14Z",
      "version": "v1",
      "data": {
        "verification_id": "test333",
        "reference_id": 10449,
        "user_reference_id": 10259,
        "user_id": "test11",
        "status": "RECEIVED",
        "sub_status": "LINK_GENERATED",
        "vkyc_link": "https://forms.qa.cashfree.net/verification/c8k926bpt84g",
        "link_expiry": "2025-06-21",
        "recording_link": null,
        "meeting_schedule": null,
        "auditor_remarks": null,
        "agent_remarks": null,
        "user_qna": null,
        "aadhaar_verification_type": null,
        "aadhaar_details": null
      }
    }
    ```
  </Accordion>

  <Accordion title="VKYC_USER_LINK_EXPIRED">
    ```json theme={"dark"}
    {
      "signature": "wBBgeTOZUyXgj6vySAm9fJYCtdXvlVHQCA6dV5uVssw=",
      "event_type": "VKYC_USER_LINK_EXPIRED",
      "event_time": "2025-05-22T03:51:14Z",
      "version": "v1",
      "data": {
        "verification_id": "test333",
        "reference_id": 10449,
        "user_reference_id": 10259,
        "user_id": "test11",
        "status": "EXPIRED",
        "sub_status": "VKYC_EXPIRED",
        "vkyc_link": "https://forms.qa.cashfree.net/verification/c8k926bpt84g",
        "link_expiry": "2025-05-22",
        "recording_link": null,
        "meeting_schedule": null,
        "auditor_remarks": null,
        "agent_remarks": null,
        "user_qna": null,
        "aadhaar_verification_type": null,
        "aadhaar_details": null
      }
    }
    ```
  </Accordion>

  <Accordion title="VKYC_USER_AADHAAR_VERIFIED">
    ```json theme={"dark"}
    {
      "signature": "wBBgeTOZUyXgj6vySAm9fJYCtdXvlVHQCA6dV5uVssw=",
      "event_type": "VKYC_USER_AADHAAR_VERIFIED",
      "event_time": "2025-05-22T03:51:14Z",
      "version": "v1",
      "data": {
        "verification_id": "test333",
        "reference_id": 10449,
        "user_reference_id": 10259,
        "user_id": "test11",
        "status": "PRE_VIDEO_CALL",
        "sub_status": "AADHAAR_VERIFICATION_SUCCESS",
        "vkyc_link": "https://forms.qa.cashfree.net/verification/c8k926bpt84g",
        "link_expiry": "2025-06-21",
        "recording_link": null,
        "meeting_schedule": null,
        "auditor_remarks": null,
        "agent_remarks": null,
        "user_qna": null,
        "aadhaar_verification_type": "DIGILOCKER",
        "aadhaar_details": {
          "last_verified_at": "2026-06-05 11:29:44",
          "care_of": "S/O: Fakkirappa Dollin",
          "dob": "02-02-1995",
          "gender": "M",
          "name": "Mallesh Fakkirappa Dollin",
          "split_address": {
            "country": "India",
            "dist": "Haveri",
            "house": "Shri Kanaka Nilaya",
            "pincode": 581115,
            "po": "Ranebennur",
            "state": "Karnataka",
            "street": "Umashankar Nagar 1st Main 5th Cross",
            "subdist": "Ranibennur",
            "vtc": "Ranibennur"
          },
          "photo_link": "https://cf-qa-cfvkyc-user-identity-docs.s3.ap-south-1.amazonaws.com/vkyc/627907/14640/photo-link/photo.jpg"
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="VKYC_USER_CALL_SCHEDULED">
    ```json theme={"dark"}
    {
      "signature": "wBBgeTOZUyXgj6vySAm9fJYCtdXvlVHQCA6dV5uVssw=",
      "event_type": "VKYC_USER_CALL_SCHEDULED",
      "event_time": "2025-05-22T03:51:14Z",
      "version": "v1",
      "data": {
        "verification_id": "test333",
        "reference_id": 10449,
        "user_reference_id": 10259,
        "user_id": "test11",
        "status": "PRE_VIDEO_CALL",
        "sub_status": "USER_MEETING_SCHEDULED",
        "vkyc_link": "https://forms.qa.cashfree.net/verification/c8k926bpt84g",
        "link_expiry": "2025-06-21",
        "recording_link": null,
        "meeting_schedule": "2025-05-23T14:30:00Z",
        "auditor_remarks": null,
        "agent_remarks": null,
        "user_qna": null,
        "aadhaar_verification_type": "DIGILOCKER",
        "aadhaar_details": {
          "last_verified_at": "2026-06-05 11:29:44",
          "care_of": "S/O: Fakkirappa Dollin",
          "dob": "02-02-1995",
          "gender": "M",
          "name": "Mallesh Fakkirappa Dollin",
          "split_address": {
            "country": "India",
            "dist": "Haveri",
            "house": "Shri Kanaka Nilaya",
            "pincode": 581115,
            "po": "Ranebennur",
            "state": "Karnataka",
            "street": "Umashankar Nagar 1st Main 5th Cross",
            "subdist": "Ranibennur",
            "vtc": "Ranibennur"
          },
          "photo_link": "https://cf-qa-cfvkyc-user-identity-docs.s3.ap-south-1.amazonaws.com/vkyc/627907/14640/photo-link/photo.jpg"
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="VKYC_USER_PRECHECK_FAILED">
    ```json theme={"dark"}
    {
      "signature": "wBBgeTOZUyXgj6vySAm9fJYCtdXvlVHQCA6dV5uVssw=",
      "event_type": "VKYC_USER_PRECHECK_FAILED",
      "event_time": "2025-05-22T03:51:14Z",
      "version": "v1",
      "data": {
        "verification_id": "test333",
        "reference_id": 10449,
        "user_reference_id": 10259,
        "user_id": "test11",
        "status": "PRE_VIDEO_CALL",
        "sub_status": "USER_VIDEO_CHECK_FAILED",
        "vkyc_link": "https://forms.qa.cashfree.net/verification/c8k926bpt84g",
        "link_expiry": "2025-06-21",
        "recording_link": null,
        "meeting_schedule": null,
        "auditor_remarks": null,
        "agent_remarks": null,
        "user_qna": null,
        "aadhaar_verification_type": "DIGILOCKER",
        "aadhaar_details": {
          "last_verified_at": "2026-06-05 11:29:44",
          "care_of": "S/O: Fakkirappa Dollin",
          "dob": "02-02-1995",
          "gender": "M",
          "name": "Mallesh Fakkirappa Dollin",
          "split_address": {
            "country": "India",
            "dist": "Haveri",
            "house": "Shri Kanaka Nilaya",
            "pincode": 581115,
            "po": "Ranebennur",
            "state": "Karnataka",
            "street": "Umashankar Nagar 1st Main 5th Cross",
            "subdist": "Ranibennur",
            "vtc": "Ranibennur"
          },
          "photo_link": "https://cf-qa-cfvkyc-user-identity-docs.s3.ap-south-1.amazonaws.com/vkyc/627907/14640/photo-link/photo.jpg"
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="VKYC_USER_CALL_QUEUED">
    ```json theme={"dark"}
    {
      "signature": "wBBgeTOZUyXgj6vySAm9fJYCtdXvlVHQCA6dV5uVssw=",
      "event_type": "VKYC_USER_CALL_QUEUED",
      "event_time": "2025-05-22T03:51:14Z",
      "version": "v1",
      "data": {
        "verification_id": "test333",
        "reference_id": 10449,
        "user_reference_id": 10259,
        "user_id": "test11",
        "status": "PRE_VIDEO_CALL",
        "sub_status": "USER_QUEUED",
        "vkyc_link": "https://forms.qa.cashfree.net/verification/c8k926bpt84g",
        "link_expiry": "2025-06-21",
        "recording_link": null,
        "meeting_schedule": null,
        "auditor_remarks": null,
        "agent_remarks": null,
        "user_qna": null,
        "aadhaar_verification_type": "DIGILOCKER",
        "aadhaar_details": {
          "last_verified_at": "2026-06-05 11:29:44",
          "care_of": "S/O: Fakkirappa Dollin",
          "dob": "02-02-1995",
          "gender": "M",
          "name": "Mallesh Fakkirappa Dollin",
          "split_address": {
            "country": "India",
            "dist": "Haveri",
            "house": "Shri Kanaka Nilaya",
            "pincode": 581115,
            "po": "Ranebennur",
            "state": "Karnataka",
            "street": "Umashankar Nagar 1st Main 5th Cross",
            "subdist": "Ranibennur",
            "vtc": "Ranibennur"
          },
          "photo_link": "https://cf-qa-cfvkyc-user-identity-docs.s3.ap-south-1.amazonaws.com/vkyc/627907/14640/photo-link/photo.jpg"
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="VKYC_USER_CALL_STARTED">
    ```json theme={"dark"}
    {
      "signature": "wBBgeTOZUyXgj6vySAm9fJYCtdXvlVHQCA6dV5uVssw=",
      "event_type": "VKYC_USER_CALL_STARTED",
      "event_time": "2025-05-22T03:51:14Z",
      "version": "v1",
      "data": {
        "verification_id": "test333",
        "reference_id": 10449,
        "user_reference_id": 10259,
        "user_id": "test11",
        "status": "VIDEO_CALL",
        "sub_status": "USER_ACCEPTED_MEETING",
        "vkyc_link": "https://forms.qa.cashfree.net/verification/c8k926bpt84g",
        "link_expiry": "2025-06-21",
        "recording_link": null,
        "meeting_schedule": null,
        "auditor_remarks": null,
        "agent_remarks": null,
        "user_qna": null,
        "aadhaar_verification_type": "DIGILOCKER",
        "aadhaar_details": {
          "last_verified_at": "2026-06-05 11:29:44",
          "care_of": "S/O: Fakkirappa Dollin",
          "dob": "02-02-1995",
          "gender": "M",
          "name": "Mallesh Fakkirappa Dollin",
          "split_address": {
            "country": "India",
            "dist": "Haveri",
            "house": "Shri Kanaka Nilaya",
            "pincode": 581115,
            "po": "Ranebennur",
            "state": "Karnataka",
            "street": "Umashankar Nagar 1st Main 5th Cross",
            "subdist": "Ranibennur",
            "vtc": "Ranibennur"
          },
          "photo_link": "https://cf-qa-cfvkyc-user-identity-docs.s3.ap-south-1.amazonaws.com/vkyc/627907/14640/photo-link/photo.jpg"
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="VKYC_USER_DROPOFF_FROM_CALL">
    ```json theme={"dark"}
    {
      "signature": "wBBgeTOZUyXgj6vySAm9fJYCtdXvlVHQCA6dV5uVssw=",
      "event_type": "VKYC_USER_DROPOFF_FROM_CALL",
      "event_time": "2025-05-22T03:51:14Z",
      "version": "v1",
      "data": {
        "verification_id": "test333",
        "reference_id": 10449,
        "user_reference_id": 10259,
        "user_id": "test11",
        "status": "VIDEO_CALL",
        "sub_status": "USER_DROPPED_OFF",
        "vkyc_link": "https://forms.qa.cashfree.net/verification/c8k926bpt84g",
        "link_expiry": "2025-06-21",
        "recording_link": null,
        "meeting_schedule": null,
        "auditor_remarks": null,
        "agent_remarks": null,
        "user_qna": null,
        "aadhaar_verification_type": "DIGILOCKER",
        "aadhaar_details": {
          "last_verified_at": "2026-06-05 11:29:44",
          "care_of": "S/O: Fakkirappa Dollin",
          "dob": "02-02-1995",
          "gender": "M",
          "name": "Mallesh Fakkirappa Dollin",
          "split_address": {
            "country": "India",
            "dist": "Haveri",
            "house": "Shri Kanaka Nilaya",
            "pincode": 581115,
            "po": "Ranebennur",
            "state": "Karnataka",
            "street": "Umashankar Nagar 1st Main 5th Cross",
            "subdist": "Ranibennur",
            "vtc": "Ranibennur"
          },
          "photo_link": "https://cf-qa-cfvkyc-user-identity-docs.s3.ap-south-1.amazonaws.com/vkyc/627907/14640/photo-link/photo.jpg"
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="VKYC_USER_CALL_COMPLETED">
    ```json theme={"dark"}
    {
      "signature": "wBBgeTOZUyXgj6vySAm9fJYCtdXvlVHQCA6dV5uVssw=",
      "event_type": "VKYC_USER_CALL_COMPLETED",
      "event_time": "2025-05-22T03:51:14Z",
      "version": "v1",
      "data": {
        "verification_id": "test333",
        "reference_id": 10449,
        "user_reference_id": 10259,
        "user_id": "test11",
        "status": "POST_VIDEO_CALL",
        "sub_status": "AGENT_APPROVED",
        "vkyc_link": "https://forms.qa.cashfree.net/verification/ashortCode",
        "link_expiry": "2025-06-21",
        "recording_link": "https://storage.cashfree.com/vkyc/recordings/test333.mp4",
        "meeting_schedule": null,
        "auditor_remarks": null,
        "agent_remarks": "Good to go",
        "user_qna": null,
        "aadhaar_verification_type": "DIGILOCKER",
        "aadhaar_details": {
          "last_verified_at": "2026-06-05 11:29:44",
          "care_of": "S/O: Fakkirappa Dollin",
          "dob": "02-02-1995",
          "gender": "M",
          "name": "Mallesh Fakkirappa Dollin",
          "split_address": {
            "country": "India",
            "dist": "Haveri",
            "house": "Shri Kanaka Nilaya",
            "pincode": 581115,
            "po": "Ranebennur",
            "state": "Karnataka",
            "street": "Umashankar Nagar 1st Main 5th Cross",
            "subdist": "Ranibennur",
            "vtc": "Ranibennur"
          },
          "photo_link": "https://cf-qa-cfvkyc-user-identity-docs.s3.ap-south-1.amazonaws.com/vkyc/627907/14640/photo-link/photo.jpg"
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="VKYC_AUDITOR_REVIEW_COMPLETED">
    ```json theme={"dark"}
    {
      "signature": "wBBgeTOZUyXgj6vySAm9fJYCtdXvlVHQCA6dV5uVssw=",
      "event_type": "VKYC_AUDITOR_REVIEW_COMPLETED",
      "event_time": "2025-05-22T03:51:14Z",
      "version": "v1",
      "data": {
        "verification_id": "test333",
        "reference_id": 10449,
        "user_reference_id": 10259,
        "user_id": "test11",
        "status": "AUDITOR_REVIEWED",
        "sub_status": "AUDITOR_APPROVED",
        "vkyc_link": "https://forms.qa.cashfree.net/verification/ashortCode",
        "link_expiry": "2025-06-21",
        "recording_link": "https://storage.cashfree.com/vkyc/recordings/test333.mp4",
        "meeting_schedule": null,
        "auditor_remarks": "Looks Good",
        "agent_remarks": "Good to go",
        "user_qna": null,
        "aadhaar_verification_type": "DIGILOCKER",
        "aadhaar_details": {
          "last_verified_at": "2026-06-05 11:29:44",
          "care_of": "S/O: Fakkirappa Dollin",
          "dob": "02-02-1995",
          "gender": "M",
          "name": "Mallesh Fakkirappa Dollin",
          "split_address": {
            "country": "India",
            "dist": "Haveri",
            "house": "Shri Kanaka Nilaya",
            "pincode": 581115,
            "po": "Ranebennur",
            "state": "Karnataka",
            "street": "Umashankar Nagar 1st Main 5th Cross",
            "subdist": "Ranibennur",
            "vtc": "Ranibennur"
          },
          "photo_link": "https://cf-qa-cfvkyc-user-identity-docs.s3.ap-south-1.amazonaws.com/vkyc/627907/14640/photo-link/photo.jpg"
        }
      }
    }
    ```
  </Accordion>
</AccordionGroup>

## Webhook payload fields

The webhook payload contains important metadata in its top-level fields.

| Field | Type | Description |
| - | - | - |
| `signature` | `string` | A Base64-encoded HMAC-SHA256 signature of the payload, generated using a shared client secret. |
| `event_type` | `string` | Indicates the type of event that triggered the webhook. |
| `event_time` | `string` | The UTC timestamp of when the event occurred, formatted in ISO 8601 (`YYYY-MM-DDTHH:MM:SSZ`). |
| `version` | `string` | Indicates the webhook format being used. Default version is "v1". |
| `data` | `object` | Contains event-specific details related to this feature. |

### data object fields

| Field | Type | Description |
| - | - | - |
| `verification_id` | `string` | The unique ID for the VKYC verification request. |
| `reference_id` | `number` | The internal reference ID for the request. |
| `user_reference_id` | `number` | The internal reference ID for the user. |
| `user_id` | `string` | The user ID provided when creating the VKYC request. |
| `status` | `string` | The current status of the VKYC request. |
| `sub_status` | `string` | The sub-status providing additional detail about the current state. |
| `vkyc_link` | `string` | The URL shared with the user to complete the VKYC process. |
| `link_expiry` | `string` | The date on which the VKYC link expires. |
| `recording_link` | `string` or `null` | A link to the VKYC session recording. Returns `null` until the video call is completed. |
| `meeting_schedule` | `string` or `null` | The scheduled UTC timestamp for the VKYC meeting. Returns `null` if no meeting is scheduled. |
| `auditor_remarks` | `string` or `null` | Remarks provided by the auditor after reviewing the VKYC session. Returns `null` if not yet reviewed. |
| `agent_remarks` | `string` or `null` | Remarks provided by the agent at the end of the VKYC call. Returns `null` if the call is not completed. |
| `user_qna` | `object` or `null` | Security questions and answers provided by the user. |
| `aadhaar_verification_type` | `string` or `null` | Type of Aadhaar verification performed. |
| `aadhaar_details` | `object` or `null` | Detailed Aadhaar information of the user. |

## Important status information

For certain webhook Events, specifically **`VKYC_USER_PRECHECK_FAILED`** and **`VKYC_USER_CALL_SCHEDULED`**, you may encounter more than one `subStatus` value.

**Action:** Consult the [Status-SubStatus Mapping](/docs/api-reference/vrs/v2/video-kyc/vkyc-descriptions#status-and-sub-status-reference) for a comprehensive list.

<Note>
  Verifying the signature is mandatory before processing any response. Refer to [Signature Verification](/docs/api-reference/vrs/webhook-signature-verification) for more details.
</Note>


# Verify Voter ID
Source: https://www.cashfree.com/docs/api-reference/vrs/v2/voter-id/verify-voter-id

post /voter-id
Use this API to verify whether the voter ID is valid by passing the EPIC number.

View the [test data](https://www.cashfree.com/docs/api-reference/vrs/data-to-test-integration#voter-id) and use the information to trigger the validations. The test data can be used only in the sandbox environment.



# Webhook Signature Verification
Source: https://www.cashfree.com/docs/api-reference/vrs/webhook-signature-verification

Validate the x-webhook-signature header on Cashfree Secure ID webhooks to confirm payload authenticity and protect your backend from spoofed events.

Verifying the signature is mandatory before processing any response. It helps authenticate that the webhook is from Cashfree.
Every webhook contains a signature (`x-webhook-signature`) in the header.

The verification process is as follows:

1. Extract the **`x-webhook-timestamp`** from the headers.
2. Concatenate the timestamp and the **raw request body** (exact payload, unmodified).
3. Generate an **HMAC-SHA256 hash** of this string using your **client secret**.
4. Base64-encode the hash.
5. Compare it with the `x-webhook-signature` header value. If they match, the webhook is valid.

<Warning>
  * Always use the **raw request body** and not a parsed JSON object. This prevents signature mismatch.
  * Reject the webhook if the signature does not match.
</Warning>

### Sample Code

<CodeGroup>
  ```javascript Node (Express) theme={"dark"}
  const crypto = require("crypto");

  function verify(req) {
    const ts = req.headers["x-webhook-timestamp"];
    const rawBody = req.rawBody; // middleware must store raw body
    const secretKey = "<client-secret>";
    const signStr = ts + rawBody;
    return crypto.createHmac("sha256", secretKey).update(signStr).digest("base64");
  }
  ```

  ```go Go (Echo) theme={"dark"}
  import (
      "crypto/hmac"
      "crypto/sha256"
      "encoding/base64"
      "io/ioutil"
  )

  func VerifySignature(expectedSig, ts, body string) (string, error) {
      signStr := ts + body
      key := "<client-secret>"
      h := hmac.New(sha256.New, []byte(key))
      h.Write([]byte(signStr))
      b := h.Sum(nil)
      return base64.StdEncoding.EncodeToString(b), nil
  }

  // usage
  timestamp := c.Request().Header.Get("x-webhook-timestamp")
  body, _ := ioutil.ReadAll(c.Request().Body)
  rawBody := string(body)
  signature := c.Request().Header.Get("x-webhook-signature")

  VerifySignature(signature, timestamp, rawBody)
  ```

  ```php PHP theme={"dark"}
  function computeSignature() {
      $rawBody = file_get_contents('php://input');
      $ts = getallheaders()['x-webhook-timestamp'];

      $signStr = $ts . $rawBody;
      $key = "<client-secret>";
      $computeSig = base64_encode(hash_hmac('sha256', $signStr, $key, true));
      return $computeSig; // compare with x-webhook-signature
  }
  ```

  ```java Java (Servlet) theme={"dark"}
  import javax.crypto.Mac;
  import javax.crypto.spec.SecretKeySpec;
  import java.util.Base64;

  public String generateSignature(HttpServletRequest request) throws Exception {
      BufferedReader bufferedReader = request.getReader();
      StringBuilder stringBuilder = new StringBuilder();
      String line;
      while ((line = bufferedReader.readLine()) != null) {
          stringBuilder.append(line);
      }
      String payload = stringBuilder.toString();
      String timestamp = request.getHeader("x-webhook-timestamp");

      String data = timestamp + payload;
      String secretKey = "<client-secret>";

      Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
      SecretKeySpec secret_key_spec = new SecretKeySpec(secretKey.getBytes(), "HmacSHA256");
      sha256_HMAC.init(secret_key_spec);

      return Base64.getEncoder().encodeToString(sha256_HMAC.doFinal(data.getBytes()));
  }
  ```

  ```python Python (Flask/Django) theme={"dark"}
  import base64
  import hashlib
  import hmac

  def generateSignature(request):
      raw_body = request.data
      payload = raw_body.decode('utf-8')
      timestamp = request.headers['x-webhook-timestamp']

      signatureData = timestamp + payload
      message = bytes(signatureData, 'utf-8')
      secretkey = bytes("<client-secret>", 'utf-8')
      signature = base64.b64encode(hmac.new(secretkey, message, digestmod=hashlib.sha256).digest())
      return signature.decode("utf-8")  # compare with x-webhook-signature
  ```
</CodeGroup>

## IPs to whitelist

When you decide to consume the webhooks, first, you need to verify if your systems need an IP whitelisting to be done at your end or not. Accordingly you can whitelist the below IPs of Cashfree:

| Sandbox |
| :- |
| 52.66.25.127 |
| 15.206.45.168 |

| Prod |
| :- |
| 52.66.101.190 |
| 3.109.102.144 |
| 18.60.134.245 |
| 18.60.183.142 |

| Port |
| :- |
| 443 (secured) |


# Secure ID Webhooks
Source: https://www.cashfree.com/docs/api-reference/vrs/webhooks-overview

Index of Secure ID webhooks (Video KYC, BAV, reverse penny drop, DigiLocker, KYC links, e-sign) and a link to signature verification.

Secure ID webhooks typically include **`event_type`**, **`event_time`**, a **`data`** object, and a Base64 **`signature`** field in the JSON body. Verification rules differ from Payment Gateway header signing. Read [Secure ID webhook signature verification](/docs/api-reference/vrs/webhook-signature-verification) before you go live. For cross-product retries and operations patterns, see the [Cashfree webhooks overview](/docs/api-reference/webhooks/overview).

## Webhook references by product

<CardGroup>
  <Card title="Video KYC" icon="video" href="/docs/api-reference/vrs/v2/video-kyc/webhook">
    `VKYC_*` session events, sample payloads, and status or sub-status notes.
  </Card>

  <Card title="Bank account verification (BAV V2)" icon="shield" href="/docs/api-reference/vrs/v2/bav-v2/webhooks-bank-account-verification">
    `BANK_ACCOUNT_VERIFICATION_*` asynchronous verification events.
  </Card>

  <Card title="Reverse penny drop" icon="money-bill" href="/docs/api-reference/vrs/v2/reverse-penny-drop/webhooks-reverse-penny">
    `RPD_BANK_ACCOUNT_VERIFICATION_*` events for reverse penny drop flows.
  </Card>

  <Card title="DigiLocker" icon="id-card" href="/docs/api-reference/vrs/v2/digilocker/webhooks-digilocker">
    DigiLocker verification webhook events and payloads.
  </Card>

  <Card title="KYC links" icon="link" href="/docs/api-reference/vrs/v2/kyc-links/webhooks">
    KYC link webhook events.
  </Card>

  <Card title="E-sign" icon="file-signature" href="/docs/api-reference/vrs/v2/e-sign/webhooks-esign">
    E-sign webhook events.
  </Card>
</CardGroup>

## Configure webhooks

Add your webhook URL in our system for us to deliver webhook events. Ensure the URL is a publicly accessible HTTPS endpoint.

1. Log in to the **[Merchant Dashboard](https://merchant.cashfree.com/merchants/)** and click **Developers**.
2. Click **Webhooks** listed under the **Secure ID** card.
3. Click **Add Webhook URL** in the **Webhook** screen.
4. In the **Add Webhook** popup, fill in the following information:
   * **Webhook URL**: Enter the URL in this field.
5. Click **Test & Add Webhook**.

This entry point applies to other Secure ID webhook-enabled products unless documented otherwise.

## Signature verification

Follow [Secure ID webhook signature verification](/docs/api-reference/vrs/webhook-signature-verification) for the canonical algorithm (including sorted `data` field handling where required).


# Configure Endpoints
Source: https://www.cashfree.com/docs/api-reference/webhooks/configure-endpoints

Register and test webhook URLs in the Merchant Dashboard for Payment Gateway, Payouts, Secure ID, and PPI. Paths vary by product.

<Note>
  Before you begin, confirm that your Cashfree account has the relevant product enabled and that you have a publicly accessible HTTPS URL ready to receive webhook requests.
</Note>

<Steps>
  <Step title="Open the Merchant Dashboard">
    Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
  </Step>

  <Step title="Navigate to webhooks for your product">
    Find your product in the [Merchant Dashboard paths by product](#merchant-dashboard-paths-by-product) section below and follow the menu path shown, then open **Webhooks** (or **Webhook**, where labelled).
  </Step>

  <Step title="Add a webhook URL">
    Select **Add Webhook URL** (or equivalent) and enter the following details:

    * **Webhook URL**: A publicly accessible HTTPS endpoint you control.
    * **Webhook version** (Payouts only): Choose **V2** for V2 JSON payloads and header signatures.

    Select **Test & Add Webhook** to validate the endpoint and save it.
  </Step>
</Steps>

<Warning>
  Production webhook endpoints must use HTTPS. HTTP isn't supported for production. For local development, use a tunnelling tool such as [ngrok](https://ngrok.com) or a request inspector such as [webhook.site](https://webhook.site).
</Warning>

## Merchant Dashboard paths by product

Expand the section for your product to find the exact dashboard navigation path.

<AccordionGroup>
  <Accordion title="Payment Gateway">
    Go to **Payment Gateway > Developers > Webhooks**. For retry policies, resend, and webhook logs, see the [Payment Gateway webhooks hub](/docs/payments/webhooks) and [Payment Gateway webhook configuration](/docs/payments/online/webhooks/configure).
  </Accordion>

  <Accordion title="Payouts">
    Go to **Payouts > Developers > Webhooks**, add a URL, and select webhook version **V2** to receive Payouts V2 payloads. Full product steps are also in [Payouts webhooks](/docs/payouts/payouts/make-payouts/webhooks).
  </Accordion>

  <Accordion title="Secure ID (Video KYC and related)">
    In the **Secure ID** card, go to **Developers > Webhooks**, as shown in [Video KYC webhooks](/docs/api-reference/vrs/v2/video-kyc/webhook). Other Secure ID flows (BAV V2 and reverse penny drop) use the same Secure ID webhook configuration unless the product page states otherwise.
  </Accordion>

  <Accordion title="PPI (Wallet)">
    Follow [PPI webhook signature verification](/docs/api-reference/prepaid-payment-instruments/webhook-signature-verification) for wallet webhook setup. If the option isn't visible in the Merchant Dashboard, raise a request using the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1).
  </Accordion>

  <Accordion title="Partner onboarding">
    Configure partner onboarding webhooks as described in [Partner onboarding webhooks](/docs/api-reference/platforms/latest/merchant-onboarding/webhooks).
  </Accordion>
</AccordionGroup>


# Events by Product
Source: https://www.cashfree.com/docs/api-reference/webhooks/events-by-product

Summary of Cashfree webhook events by product area. Open each accordion for quick reference, then use the linked product docs for versioned payloads.

This page is a consolidated index of webhook events across all Cashfree products. Expand a product section to see available events and their descriptions. Event names and JSON field shapes depend on the API version and webhook version. Always confirm field names and enum values on the linked product page before you build parsers.

<Note>
  Payment Gateway events span multiple categories: payments, refunds, subscriptions, settlements, disputes, and more. The table below shows a summary; for the complete catalogue of event names, versioned payloads, and category-level guides, see the [Payment Gateway webhooks hub](/docs/payments/webhooks).
</Note>

<AccordionGroup>
  <Accordion title="Payment Gateway">
    Cashfree sends Payment Gateway webhooks across the full payment lifecycle, including individual payments, refunds, subscriptions, payment links, tokenised instruments, settlements, and disputes. The event catalogue is extensive and versioned.

    The following table shows the primary event categories. For the complete list of event names, versioned payloads, and category-level guides, use the [Payment Gateway webhooks hub](/docs/payments/webhooks).

    | Category | Example events |
    | - | - |
    | Payment | `PAYMENT_SUCCESS`, `PAYMENT_FAILED`, `PAYMENT_USER_DROPPED` |
    | Refund | `REFUND_STATUS_WEBHOOK` |
    | Settlement | `SETTLEMENT_STATUS_WEBHOOK` |
    | Subscription | `SUBSCRIPTION_CREATED`, `SUBSCRIPTION_CHARGED`, `SUBSCRIPTION_CANCELLED` |
    | Payment Link | `PAYMENT_LINK_EVENT` |
    | Token Vault | `TOKEN_STATUS_WEBHOOK` |
  </Accordion>

  <Accordion title="Payouts V2 (recommended)">
    Payouts V2 webhooks use JSON bodies and header-based signatures. They cover the transfer lifecycle, beneficiary incidents, and account balance signals. For full payload schemas and configuration steps, see [Payouts Webhooks V2](/docs/api-reference/payouts/v2/webhooks/webhooks-v2).

    | Event | Description |
    | - | - |
    | `TRANSFER_ACKNOWLEDGED` | The transfer completes end-to-end. Your account is debited and the beneficiary bank credits the end user. |
    | `TRANSFER_SUCCESS` | The transfer is debited from your account and sent to the beneficiary bank. Confirmation at the beneficiary end may still be pending. |
    | `TRANSFER_FAILED` | The transfer attempt fails. |
    | `TRANSFER_REVERSED` | The beneficiary bank reverses the transfer. |
    | `TRANSFER_REJECTED` | Cashfree rejects the transfer request. |
    | `BULK_TRANSFER_REJECTED` | One or more transfers in a batch request are rejected. |
    | `BENEFICIARY_INCIDENT` | A service disruption or incident affects a beneficiary bank or payment mode. |
    | `CREDIT_CONFIRMATION` | Funds are credited to your account balance. |
    | `LOW_BALANCE_ALERT` | Your account balance falls below a configured threshold. |

    <Warning>
      Treat a payout as fully successful for reconciliation only when both `status` is `SUCCESS` and `status_code` is `COMPLETED`. Do not rely on `status` alone.
    </Warning>
  </Accordion>

  <Accordion title="Payouts V1 (Cashgram)">
    Cashgram webhooks cover link redemption, transfer reversals, and link expiry. For delivery format and verification steps, see [Cashgram webhooks](/docs/payouts/cashgram/integration/webhooks).

    | Event | Description |
    | - | - |
    | `CASHGRAM_REDEEMED` | The customer redeems the Cashgram link. |
    | `CASHGRAM_TRANSFER_REVERSAL` | The bank reverses a Cashgram transfer. |
    | `CASHGRAM_EXPIRED` | The link expires, reaches the maximum retry limit, or OTP verification fails. |

    <Note>
      You can subscribe to Payouts V2 webhooks even if some transfers still use the V1 or V1.2 APIs. Webhook version and REST API version are configured independently in the Merchant Dashboard.
    </Note>
  </Accordion>

  <Accordion title="Secure ID (Video KYC)">
    Video KYC webhooks track each stage of the KYC session, from link generation through auditor review. For full payload schemas, see [Video KYC webhooks](/docs/api-reference/vrs/v2/video-kyc/webhook).

    | Event | Description |
    | - | - |
    | `VKYC_USER_LINK_GENERATED` | A Video KYC link is generated for the user. |
    | `VKYC_USER_LINK_EXPIRED` | The Video KYC link expires. |
    | `VKYC_USER_AADHAAR_VERIFIED` | Aadhaar verification succeeds. |
    | `VKYC_USER_CALL_SCHEDULED` | The Video KYC call is scheduled. |
    | `VKYC_USER_PRECHECK_FAILED` | Pre-verification checks fail. |
    | `VKYC_USER_CALL_QUEUED` | The user is waiting in the agent queue. |
    | `VKYC_USER_CALL_STARTED` | The Video KYC call starts with an agent. |
    | `VKYC_USER_DROPOFF_FROM_CALL` | The user leaves the call before completion. |
    | `VKYC_USER_CALL_COMPLETED` | The Video KYC call completes successfully. |
    | `VKYC_AUDITOR_REVIEW_COMPLETED` | An auditor approves or rejects the session. |

    <Note>
      For `VKYC_USER_PRECHECK_FAILED` and `VKYC_USER_CALL_SCHEDULED`, multiple `sub_status` values are possible. See the [Video KYC status and sub-status mapping](/docs/api-reference/vrs/v2/video-kyc/vkyc-descriptions#status-and-sub-status-reference).
    </Note>
  </Accordion>

  <Accordion title="Secure ID: Bank account verification (BAV V2)">
    BAV V2 webhooks notify you of the outcome of an asynchronous bank account verification request. For full payload schemas, see [Bank account verification webhooks](/docs/api-reference/vrs/v2/bav-v2/webhooks-bank-account-verification).

    | Event | Description |
    | - | - |
    | `BANK_ACCOUNT_VERIFICATION_SUCCESS` | Bank account verification succeeds. |
    | `BANK_ACCOUNT_VERIFICATION_REJECTED` | Bank account verification is rejected. |
    | `BANK_ACCOUNT_VERIFICATION_FAILED` | Bank account verification fails. |
  </Accordion>

  <Accordion title="Secure ID (Reverse penny drop)">
    Reverse penny drop webhooks notify you when a bank account verification via reverse penny drop reaches a terminal state. For full payload schemas, see [Reverse penny drop webhooks](/docs/api-reference/vrs/v2/reverse-penny-drop/webhooks-reverse-penny).

    | Event | Description |
    | - | - |
    | `RPD_BANK_ACCOUNT_VERIFICATION_SUCCESS` | Reverse penny drop verification succeeds. |
    | `RPD_BANK_ACCOUNT_VERIFICATION_EXPIRED` | The reverse penny drop request expires. |
    | `RPD_BANK_ACCOUNT_VERIFICATION_FAILURE` | Reverse penny drop verification fails. |
  </Accordion>

  <Accordion title="PPI (Wallet)">
    PPI wallet webhooks notify you of credit events on a user's wallet. For full payload schema and signature verification, see [PPI wallet webhooks](/docs/api-reference/prepaid-payment-instruments/webhook-signature-verification).

    | Event | Description |
    | - | - |
    | `PPI_CREDIT_SUCCESS` | A wallet credit completes successfully. |
  </Accordion>
</AccordionGroup>


# Cashfree Webhooks
Source: https://www.cashfree.com/docs/api-reference/webhooks/overview

Learn what Cashfree webhooks are, when to use them, and where to find product-specific event and payload documentation across all products.

A webhook is an HTTP `POST` callback that Cashfree sends to a URL you register when a specific event occurs in your account, such as a payment confirmation, a payout reversal, or a KYC session outcome. Every webhook is signed with HMAC-SHA256 using your client secret. Signature verification is required before you process any payload.

## When to use webhooks

Use webhooks for any outcome that is asynchronous (not known immediately when the API returns):

* A bank confirmation arrives after a payment is initiated.
* A beneficiary bank reverses a payout.
* A Video KYC session is reviewed by an auditor.
* A wallet credit completes after a fund transfer.

<Note>
  For business-critical flows, combine webhooks with an API poll as a fallback. Webhooks are near real time but are not guaranteed to arrive within your application timeout.
</Note>

## Webhooks by product

Each product area has its own webhook entry point, linked below.

<CardGroup>
  <Card title="Payment Gateway webhooks" icon="credit-card" href="/docs/api-reference/payments/latest/webhooks/overview">
    Setup, event references, signature verification, and troubleshooting for Payment Gateway webhooks.
  </Card>

  <Card title="Payouts webhooks" icon="chart-line" href="/docs/api-reference/payouts/webhooks-overview">
    Payouts V2 and V1 webhook references, Cashgram, and product documentation in one place.
  </Card>

  <Card title="Secure ID webhooks" icon="shield" href="/docs/api-reference/vrs/webhooks-overview">
    Video KYC, BAV V2, reverse penny drop, DigiLocker, KYC links, e-sign, and signature verification.
  </Card>

  <Card title="PPI webhooks" icon="wallet" href="/docs/api-reference/prepaid-payment-instruments/webhooks-overview">
    Wallet credit and PPI webhook verification and wallet management webhook references.
  </Card>

  <Card title="Partner platform webhooks" icon="handshake" href="/docs/api-reference/platforms/latest/webhooks-overview">
    Merchant onboarding and other platform webhook entry points in the Partners APIs.
  </Card>
</CardGroup>

The following table lists example webhook use cases across Cashfree's product areas.

| Product area | Example use cases |
| - | - |
| **Payment Gateway** | Confirm order payment status, trigger order fulfilment, handle refund updates, process chargeback alerts, sync settlement notifications |
| **Payouts** | Detect failed or reversed transfers, trigger low-balance alerts, confirm bulk transfer outcomes, track credit confirmations |
| **Secure ID (Video KYC)** | Track KYC session progress, trigger post-approval onboarding, flag failed pre-checks |
| **Secure ID (Bank account verification)** | Confirm asynchronous verification outcomes, handle rejected or failed checks |
| **Secure ID (Reverse penny drop)** | Notify when verification succeeds, expires, or fails |
| **Prepaid Payment Instruments (PPI)** | Confirm wallet credit events and drive balance updates |

## What you need to do

Complete these steps to receive and process Cashfree webhooks reliably.

<Steps>
  <Step title="Choose products and events">
    Identify which products you integrate with and which events to handle. Use [Events by product](/docs/api-reference/webhooks/events-by-product) as a starting point.
  </Step>

  <Step title="Implement an HTTPS endpoint">
    Build a publicly reachable HTTPS URL that accepts `POST` requests, reads the raw body for signature verification, and returns `200` quickly.
  </Step>

  <Step title="Register the URL in the Merchant Dashboard">
    Open **Add Webhook Endpoint** under the product's developer settings, enter your URL, and click **Test** to verify it. Then select a retry policy and the events to subscribe to, and save. See [Configure webhook endpoints](/docs/api-reference/webhooks/configure-endpoints) for dashboard paths.
  </Step>

  <Step title="Verify signatures on every request">
    Reject any payload that fails cryptographic verification. See [Payloads and signature verification](/docs/api-reference/webhooks/payloads-and-signatures) for the algorithm per product family.
  </Step>

  <Step title="Acknowledge immediately and process asynchronously">
    Return `200` after signature verification, then process the event in a background worker. Non-`200` responses trigger retries.
  </Step>

  <Step title="Handle retries and idempotency">
    Webhooks follow at-least-once delivery. Store processed event IDs to prevent duplicate side effects. See [Reliability and operations](/docs/api-reference/webhooks/reliability-and-operations).
  </Step>

  <Step title="Test, then go live">
    Exercise flows in sandbox and confirm payloads against the product reference before enabling in production.
  </Step>
</Steps>

## In this section

This section contains the following guides for implementing and operating Cashfree webhooks.

| Guide | Purpose |
| - | - |
| [Configure webhook endpoints](/docs/api-reference/webhooks/configure-endpoints) | Merchant Dashboard paths and how to add and test a URL per product |
| [Events by product](/docs/api-reference/webhooks/events-by-product) | Summary event lists per product area |
| [Payloads and signature verification](/docs/api-reference/webhooks/payloads-and-signatures) | Body shape, sample payloads, and verification algorithms |
| [Reliability and operations](/docs/api-reference/webhooks/reliability-and-operations) | Retries, idempotency, best practices, IP allow lists, migration, and FAQs |


# Payloads and Signatures
Source: https://www.cashfree.com/docs/api-reference/webhooks/payloads-and-signatures

Understand Cashfree webhook JSON structure, sample payloads, and how to verify HMAC signatures for Payment Gateway, Payouts, Secure ID, and PPI.

This page covers the signature verification algorithm you must implement before processing any webhook, and sample payloads for common event types. If you haven't registered a webhook URL yet, start with [Configure webhook endpoints](/docs/api-reference/webhooks/configure-endpoints).

## Signature verification

<Warning>
  Verify the signature on every incoming webhook request before you trust or act on its payload. Skipping verification allows forged requests to trigger business logic and fraudulent event injection.
</Warning>

Payment Gateway, Payouts V2, Secure ID, and PPI all use the same HMAC-SHA256 header-based algorithm. Payouts V1 (Cashgram) uses form-encoded POST parameters.

### Header-based verification

Applies to Payment Gateway, Payouts V2, Secure ID, and PPI.

The signature is in the `x-webhook-signature` header. The timestamp used in the signature is in `x-webhook-timestamp`.

**Algorithm:**

```text theme={"dark"}
signedPayload     = x-webhook-timestamp + rawBody
expectedSignature = Base64Encode(HMAC-SHA256(signedPayload, clientSecret))
```

<Warning>
  Always compute the signature from the raw request body string. Parsing and re-serialising JSON can change whitespace, field order, or number formatting and will cause verification to fail.
</Warning>

<Tip>
  Use the official Cashfree SDK where available. It captures the raw body and performs signature verification in a single method call, reducing the risk of implementation errors.
</Tip>

<CodeGroup>
  ```javascript Node.js (SDK) theme={"dark"}
  const { Cashfree, CFEnvironment } = require("cashfree-pg");

  const cashfree = new Cashfree(
    CFEnvironment.PRODUCTION,
    "<CLIENT_ID>",
    "<CLIENT_SECRET_KEY>"
  );

  app.post("/webhook", function (req, res) {
    try {
      cashfree.PGVerifyWebhookSignature(
        req.headers["x-webhook-signature"],
        req.rawBody,
        req.headers["x-webhook-timestamp"]
      );
      res.sendStatus(200);
    } catch (err) {
      console.error("Signature verification failed:", err.message);
      res.sendStatus(400);
    }
  });
  ```

  ```javascript Node.js (manual) theme={"dark"}
  const crypto = require("crypto");

  function verifySignature(req) {
    const body = req.headers["x-webhook-timestamp"] + req.rawBody;
    const secret = process.env.CASHFREE_CLIENT_SECRET;

    const generatedSignature = crypto
      .createHmac("sha256", secret)
      .update(body)
      .digest("base64");

    const receivedSignature = req.headers["x-webhook-signature"];

    if (generatedSignature !== receivedSignature) {
      throw new Error("Signature mismatch. Request rejected.");
    }

    return JSON.parse(req.rawBody);
  }
  ```

  ```go Go theme={"dark"}
  func VerifyWebhookSignature(
    signature string,
    rawBody   string,
    timestamp string,
  ) error {
    signatureString := timestamp + rawBody
    h := hmac.New(sha256.New, []byte(*XClientSecret))
    h.Write([]byte(signatureString))
    generatedSignature := base64.StdEncoding.EncodeToString(h.Sum(nil))

    if generatedSignature != signature {
      return errors.New("generated signature and received signature did not match")
    }
    return nil
  }
  ```

  ```java Java theme={"dark"}
  import javax.crypto.Mac;
  import javax.crypto.spec.SecretKeySpec;
  import java.util.Base64;

  public String generateSignature(HttpServletRequest request) throws Exception {
      BufferedReader bufferedReader = request.getReader();
      StringBuilder stringBuilder = new StringBuilder();
      String line;
      while ((line = bufferedReader.readLine()) != null) {
          stringBuilder.append(line);
      }
      String payload = stringBuilder.toString();
      String timestamp = request.getHeader("x-webhook-timestamp");

      String data = timestamp + payload;
      String secretKey = "<client-secret>";

      Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
      SecretKeySpec secret_key_spec = new SecretKeySpec(secretKey.getBytes(), "HmacSHA256");
      sha256_HMAC.init(secret_key_spec);

      return Base64.getEncoder().encodeToString(sha256_HMAC.doFinal(data.getBytes()));
  }
  ```

  ```php PHP theme={"dark"}
  function verifySignature() {
      $rawBody = file_get_contents('php://input');
      $ts = getallheaders()['x-webhook-timestamp'];

      $signStr = $ts . $rawBody;
      $key = "<client-secret>";
      $computedSig = base64_encode(hash_hmac('sha256', $signStr, $key, true));

      return $computedSig; // compare with x-webhook-signature header value
  }
  ```

  ```python Python theme={"dark"}
  import base64
  import hashlib
  import hmac

  def generate_signature(request):
      raw_body = request.data.decode('utf-8')
      timestamp = request.headers['x-webhook-timestamp']

      sign_str = timestamp + raw_body
      message = bytes(sign_str, 'utf-8')
      secret_key = bytes("<client-secret>", 'utf-8')
      signature = base64.b64encode(
          hmac.new(secret_key, message, digestmod=hashlib.sha256).digest()
      )
      return signature.decode("utf-8")  # compare with x-webhook-signature header value
  ```
</CodeGroup>

<Note>
  Cashfree signs webhooks using the client secret that was active at the time the event was sent. If you have rotated your client secret, keep the previous secret active until all in-flight webhooks from that period have been processed.
</Note>

For additional language samples, see [Secure ID webhook signature verification](/docs/api-reference/vrs/webhook-signature-verification) and [PPI webhook signature verification](/docs/api-reference/prepaid-payment-instruments/webhook-signature-verification).

### Payouts V1: Cashgram

Cashgram webhooks use form-encoded POST parameters rather than a JSON body. The signature is computed as follows:

1. Collect all POST parameters except `signature` into an array.
2. Sort the array by key in ascending alphabetical order.
3. Concatenate all non-empty values in the sorted order to form `postData`.
4. Compute `HMAC-SHA256(postData, clientSecret)` and Base64-encode the result.
5. Compare the result to the received `signature` parameter. Reject the request if the values don't match.

```php PHP theme={"dark"}
$data      = $_POST;
$signature = $_POST["signature"];
unset($data["signature"]);

ksort($data);

$postData = "";
foreach ($data as $key => $value) {
  if (strlen($value) > 0) {
    $postData .= $value;
  }
}

$computedSignature = base64_encode(
  hash_hmac("sha256", $postData, $clientSecret, true)
);

if ($signature === $computedSignature) {
  // Signature is valid. Process the event.
} else {
  // Signature mismatch. Reject the request.
}
```

For the full parameter list and ordering rules, see [Cashgram webhooks](/docs/payouts/cashgram/integration/webhooks).

***

## Sample payloads

The event discriminator field is `type` for Payment Gateway and Payouts V2, and `event_type` for Secure ID and PPI. Cashgram payloads are form-encoded, not JSON. Always validate field names and enum values against the product page for your API version.

<CodeGroup>
  ```json Payments: PAYMENT_SUCCESS theme={"dark"}
  {
    "data": {
      "order": {
        "order_id": "order_1234",
        "order_amount": 500.00,
        "order_currency": "INR",
        "order_tags": null
      },
      "payment": {
        "cf_payment_id": 9876543210,
        "payment_status": "SUCCESS",
        "payment_amount": 500.00,
        "payment_currency": "INR",
        "payment_message": "Transaction successful",
        "payment_time": "2024-01-15T10:30:00+05:30",
        "bank_reference": "TXN123456789",
        "auth_id": null,
        "payment_method": {
          "upi": {
            "channel": "collect",
            "upi_id": "user@upi"
          }
        }
      },
      "customer_details": {
        "customer_name": "John Doe",
        "customer_id": "CUST001",
        "customer_email": "john@example.com",
        "customer_phone": "9999999999"
      }
    },
    "event_time": "2024-01-15T10:30:05+05:30",
    "type": "PAYMENT_SUCCESS"
  }
  ```

  ```json Payouts V2: TRANSFER_SUCCESS theme={"dark"}
  {
    "data": {
      "transfer_id": "JUNOB2018",
      "cf_transfer_id": "123456",
      "status": "SUCCESS",
      "status_code": "SENT_TO_BENEFICIARY",
      "status_description": "The transfer has been initiated via the partner bank successfully. The request is waiting to be processed at the beneficiary bank to do the credit to the end beneficiary.",
      "beneficiary_details": {
        "beneficiary_id": "JOHN18011",
        "beneficiary_instrument_details": {
          "bank_account_number": "7766671501729",
          "bank_ifsc": "SBIN0000003"
        }
      },
      "transfer_amount": 1,
      "transfer_service_charge": 1,
      "transfer_service_tax": 0.18,
      "transfer_mode": "BANK",
      "transfer_utr": "TESTR92023012200543116",
      "fundsource_id": "CASHFREE_1",
      "added_on": "2021-11-24T13:39:25Z",
      "updated_on": "2021-11-24T13:40:27Z"
    },
    "event_time": "2024-07-25T17:43:37",
    "type": "TRANSFER_SUCCESS"
  }
  ```

  ```json Secure ID: VKYC_AUDITOR_REVIEW_COMPLETED theme={"dark"}
  {
    "event_type": "VKYC_AUDITOR_REVIEW_COMPLETED",
    "event_time": "2025-05-22T03:51:14Z",
    "version": "v1",
    "data": {
      "verification_id": "test333",
      "reference_id": 10449,
      "user_reference_id": 10259,
      "user_id": "test11",
      "status": "AUDITOR_REVIEWED",
      "sub_status": "AUDITOR_APPROVED",
      "vkyc_link": "https://forms.cashfree.net/verification/ashortCode",
      "link_expiry": "2025-06-21",
      "recording_link": "https://storage.cashfree.com/vkyc/recordings/test333.mp4",
      "meeting_schedule": null,
      "auditor_remarks": "Looks Good",
      "agent_remarks": "Good to go"
    }
  }
  ```

  ```json Secure ID: BANK_ACCOUNT_VERIFICATION_SUCCESS theme={"dark"}
  {
    "event_type": "BANK_ACCOUNT_VERIFICATION_SUCCESS",
    "event_time": "2023-07-19 10:46:16",
    "version": "v2",
    "data": {
      "reference_id": 1294785793,
      "user_id": "123123",
      "name_at_bank": "John Doe",
      "amount_deposited": "1.04",
      "bank_name": "YES BANK",
      "utr": "404223241811",
      "city": "MUMBAI",
      "branch": "SANTACRUZ, MUMBAI",
      "micr": 400532038,
      "name_match_score": "90.00",
      "name_match_result": "GOOD_PARTIAL_MATCH",
      "account_status": "VALID",
      "account_status_code": "ACCOUNT_IS_VALID"
    }
  }
  ```

  ```json PPI: PPI_CREDIT_SUCCESS theme={"dark"}
  {
    "event_type": "PPI_CREDIT_SUCCESS",
    "event_time": "2006-01-02T15:04:05Z",
    "data": {
      "credit_id": "CREDIT126345",
      "cf_credit_id": "8901234567890123456",
      "wallet_id": "WALLET936721",
      "user_id": "USER827364",
      "amount": 100.5,
      "sub_wallet": {
        "cf_sub_wallet_id": "35246543210987654321",
        "name": "Gift Wallet",
        "type": "GIFT_PPI",
        "status": "ACTIVE",
        "balance": 1500.75
      },
      "status": "SUCCESS",
      "remarks": "Refund for order 123",
      "initiated_at": "2025-09-02T10:15:30Z",
      "processed_at": "2025-09-02T10:20:45Z"
    }
  }
  ```

  ```json Cashgram: CASHGRAM_REDEEMED (form parameters) theme={"dark"}
  {
    "referenceId": "JUNOB2018",
    "cashgramCode": "CASHGRAM123",
    "transferId": "TRF12345",
    "amount": "500.00",
    "beneficiaryName": "John Doe",
    "beneficiaryPhone": "9999999999",
    "status": "REDEEMED",
    "statusMessage": "Transfer Successful",
    "utr": "TESTR12345",
    "addedOn": "2024-01-15 10:30:00",
    "signature": "<base64-encoded-hmac>"
  }
  ```
</CodeGroup>

<Note>
  The Cashgram payload shows the POST parameter names formatted as JSON for readability. In practice, Cashgram webhooks arrive as `application/x-www-form-urlencoded` POST parameters, not as a JSON body. See [Cashgram webhooks](/docs/payouts/cashgram/integration/webhooks) for the authoritative parameter list.
</Note>


# Reliability and Operations
Source: https://www.cashfree.com/docs/api-reference/webhooks/reliability-and-operations

Retries, idempotency, Cashfree IP addresses, Payment Gateway webhook migration, and FAQs. Pairs with the payloads and signatures guide.

This page covers what happens after Cashfree delivers a webhook: retry behaviour by product, how to prevent duplicate processing, Cashfree IP addresses for network filtering, and how to migrate Payment Gateway webhook versions without losing events.

## Retry policy

Cashfree retries delivery when your endpoint doesn't return HTTP `200`. Responses outside the `2xx` range, including `3xx` redirects, count as delivery failures.

### Payment Gateway

You can configure a per-endpoint retry policy in the Merchant Dashboard under **Payment Gateway > Developers > Webhooks**. The following policy types are available.

| Policy | Behaviour |
| - | - |
| **Default** | Retries up to three times at 2, 10, and 30-minute intervals |
| **Fixed** | You choose the retry count (up to 10) and a fixed interval |
| **Exponential** | You choose the retry count (up to 10), a base interval, and a multiplier |
| **Custom** | You choose the retry count (up to 10) and define each interval individually |

### Payouts V2 and Cashgram

Cashfree retries failed deliveries at scheduled intervals. If your endpoint fails more than five consecutive times, the webhook endpoint is disabled automatically. Fix your handler, then re-enable the URL in the Merchant Dashboard.

<Note>
  The exact retry interval schedule for Payouts V2 and Cashgram isn't configurable. Review the Payouts dashboard for current retry timing details, or raise a request using the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1).
</Note>

### Secure ID and PPI

Failed Secure ID and PPI webhook deliveries are retried automatically. Implement idempotent handlers so that duplicate deliveries don't produce duplicate side effects.

***

## Handle duplicate events

Cashfree webhooks follow at-least-once delivery semantics. Network issues, timeouts, or slow handlers can cause the same logical event to arrive more than once. This is expected behaviour.

To avoid duplicate processing:

* Use a stable business identifier (such as `cf_payment_id`, `transfer_id`, or a verification ID) as an idempotency key.
* Before performing any irreversible action, check whether that identifier was already recorded as processed.
* For Payment Gateway webhooks on version `2025-01-01`, also use the `x-idempotency-key` header value as a de-duplication key where applicable.

<Tip>
  Design handlers to be idempotent: processing the same event twice must be safe and must produce the same outcome as processing it once.
</Tip>

***

## Best practices

**Security**

* Verify the signature before acting on any payload data. See [Payloads and signature verification](/docs/api-reference/webhooks/payloads-and-signatures).
* Use HTTPS only in production. Don't expose plain HTTP webhook URLs.
* If your network policy requires inbound IP filtering, add the Cashfree IP ranges listed in [Cashfree IP addresses](#cashfree-ip-addresses) to your allowlist.
* Where a timestamp header exists (for example, `x-webhook-timestamp` on Payment Gateway webhooks), reject requests where the timestamp is older than five minutes to limit replay attack risk.

**Reliability and testing**

* Return `200` immediately after signature verification, then queue work to a background worker. Non-`200` responses trigger retries.
* Build for idempotency using unique event or entity IDs and database-level uniqueness constraints.
* Don't assume delivery order. If ordering matters, reconcile state using the relevant resource API (for example, the [Get Order API](/docs/api-reference/payments/latest/orders/get-order)) after the webhook arrives.
* Log the event type, delivery attempt, and processing outcome for every webhook. Set up alerts for sustained delivery failures.
* Use the sandbox environment and test transactions to exercise real payloads before going live.
* Use a tunnelling tool such as [ngrok](https://ngrok.com) to receive webhook events on a local development machine.
* For Payment Gateway, use the **Batch Resend** feature in the Merchant Dashboard to replay events when your endpoint was temporarily unavailable.

***

## Cashfree IP addresses

If your infrastructure restricts inbound traffic by source IP, add HTTPS connections on port `443` from the following Cashfree addresses to your allowlist. This is optional and only required if your network policy enforces it.

<Tabs>
  <Tab title="Sandbox / UAT">
    | IP address |
    | - |
    | `52.66.25.127` |
    | `15.206.45.168` |
  </Tab>

  <Tab title="Production">
    | IP address |
    | - |
    | `52.66.101.190` |
    | `3.109.102.144` |
    | `18.60.134.245` |
    | `18.60.183.142` |
  </Tab>
</Tabs>

***

## Payment Gateway webhook migration

When you move from an older Payment Gateway webhook version to a newer one (for example, from `2023-08-01` to `2025-01-01`), use the overlap pattern below to migrate without losing events.

<Steps>
  <Step title="Create the new webhook endpoint">
    In the Merchant Dashboard, add a new webhook URL and select the target version. Subscribe to the events you need.
  </Step>

  <Step title="Deploy and activate the new endpoint">
    Deploy handler logic that returns `200` for the new endpoint URL, then activate the new webhook configuration in the Merchant Dashboard. During this overlap period, Cashfree sends each event to both the old and the new endpoint simultaneously.
  </Step>

  <Step title="Update processing logic">
    Update your handler to parse the new payload format and headers, including `x-idempotency-key` on version `2025-01-01`. Review the product changelog for any breaking field or enum changes before you go live.
  </Step>

  <Step title="Disable the old endpoint">
    After confirming the new endpoint processes events correctly, disable the old webhook configuration in the Merchant Dashboard. Monitor delivery for a period before permanently deleting the old configuration.
  </Step>
</Steps>

***

## Frequently asked questions

The following questions address the most common issues encountered when configuring or maintaining Cashfree webhook integrations.

<AccordionGroup>
  <Accordion title="Can I use Payouts V2 webhooks if I call the Payouts V1 or V1.2 APIs?">
    Yes. Webhook version and REST API version are independent settings. You can enable Payouts V2 webhooks while still using the V1 or V1.2 transfer APIs.
  </Accordion>

  <Accordion title="What should I do if my endpoint misses a webhook?">
    For Payment Gateway, use **Batch Resend** under **Developers > Webhooks > Logs** in the Merchant Dashboard. See [Payment Gateway webhooks](/docs/payments/webhooks) for steps. For other products, poll the relevant resource using the documented API, or raise a request using the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1).
  </Accordion>

  <Accordion title="Why is signature verification failing?">
    The most common causes are:

    * Computing the HMAC from a parsed or re-serialised JSON body instead of the raw request body string.
    * Using the wrong client secret. For Payouts V2, always use the oldest active secret.
    * For Cashgram and Secure ID, incorrect field sorting or concatenation order before hashing.
  </Accordion>

  <Accordion title="My endpoint is not receiving webhooks. What should I check?">
    Confirm that the endpoint URL is publicly accessible over HTTPS, returns `200` for valid signed requests, and isn't blocked by firewall or IP rules. Review webhook delivery logs in the Merchant Dashboard for error details. If the issue continues, raise a request using the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1).
  </Accordion>

  <Accordion title="Do I need to whitelist IP addresses?">
    IP whitelisting is optional. If your infrastructure requires it, add the sandbox and production IP addresses listed in [Cashfree IP addresses](#cashfree-ip-addresses) to your allowlist.
  </Accordion>
</AccordionGroup>


# Access Management
Source: https://www.cashfree.com/docs/help/account/access-management

Manage user access for your Cashfree account: invite team members, assign roles, create custom permissions, and audit role-based access controls.

Access management allows you to control who can access your Cashfree account and what actions they can perform. Use role-based access control to minimise security risks, maintain accountability, and ensure team members have appropriate permissions.

To access these features:

1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
2. Navigate to **Settings > Access Management**.

You can assign predefined or custom roles, enable specific permissions without roles, combine multiple roles for a user, or create custom roles for your organisation's needs.

The system is built on three core components that work together to provide flexible and secure access control:

<CardGroup>
  <Card title="User Management" icon="users" href="#user-management">
    Invite team members, assign roles and permissions, and manage user access to your account.
  </Card>

  <Card title="Role Management" icon="user-shield" href="#role-management">
    Create custom roles with specific permission sets tailored to your organisation's needs.
  </Card>

  <Card title="Permissions Framework" icon="sliders" href="#permissions-framework">
    Control what users can view and manage across all products and features.
  </Card>
</CardGroup>

## User management

User management allows you to invite team members to your Cashfree account and control their access through role assignments or direct permission grants. You can invite unlimited users and assign them different access levels based on their responsibilities.

### Default roles

Cashfree provides five default roles that cover common use cases. Each role includes a predefined set of permissions designed for specific responsibilities:

| Role | Description | Typical use cases |
| :- | :- | :- |
| Developer | Develops and maintains integrations with access to API secrets, webhooks, and all API resources. | API integration, webhook configuration, SDK implementation. |
| Operations | Manages daily payment processing, ensures payouts, refunds payments, handles disputes, and exports data. | Transaction processing, refund management, dispute handling. |
| Manager | Manages overall business cash flow including settlements, payment methods, and reports. | Financial oversight, settlement monitoring, business analytics. |
| Admin | Oversees account settings, transactions, payouts, and settlements. Cannot manage users or roles. | System administration, merchant configuration, reporting. |
| Support | Provides technical assistance to customers and has view-only access to transactions, refunds, and transfers. | Customer support, transaction queries, read-only access. |

### Account owner

The account owner is the user who created the Cashfree account. Unlike the five default roles, this is a system-level designation assigned automatically at account creation and can't be assigned through **User Management** on the Merchant Dashboard. Only one account owner can exist per account at any time.

<Note>
  Account deletion cannot be initiated from the [Merchant Dashboard](https://merchant.cashfree.com/auth/login). To request account deletion,
  contact your account manager by email. Your account manager coordinates with
  the Cashfree care team to process the deletion request.
</Note>

#### Transferring account ownership

Account ownership can be transferred to another user on the account. Once transferred, the new user assumes all account owner permissions and the previous owner loses them.

To transfer account ownership, contact [Cashfree support](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) or reach out to your Cashfree account manager with the request to transfer account ownership to the registered email address of the user you want.

<AccordionGroup>
  <Accordion title="View detailed permissions by role">
    The following table shows what the account owner and each default role can access. Use this to understand which role best fits your team member's responsibilities:

    | Feature | Account owner | Admin | Manager | Developer | Operations | Support |
    | :- | :- | :- | :- | :- | :- | :- |
    | **API Keys & Secrets** | Full access | Full access | No access | Full access | No access | No access |
    | **Webhooks** | Full access | Full access | No access | Full access | No access | No access |
    | **Orders & Payments** | Full access | Full access | View only | View only | Full access | View only |
    | **Refunds** | Full access | Full access | View only | No access | Full access | View only |
    | **Settlements** | Full access | Full access | Full access | No access | View only | No access |
    | **Disputes** | Full access | Full access | View only | No access | Full access | View only |
    | **Payouts** | Full access | Full access | Full access | No access | Full access | View only |
    | **Payment Methods** | Full access | Full access | Full access | No access | No access | No access |
    | **Reports** | Full access | Full access | Full access | View only | Full access | View only |
    | **User Management** | Full access | No access | No access | No access | No access | No access |
    | **Role Management** | Full access | No access | No access | No access | No access | No access |
    | **Account Settings** | Full access | Full access | View only | No access | No access | No access |

    <Tip>
      * **Full access**: Can view and modify (create, edit, delete, configure)
      * **View only**: Can see information but can't make changes
      * **No access**: Can't view or access this feature
    </Tip>
  </Accordion>
</AccordionGroup>

### Invite a user and assign a role

Follow these steps to invite a user and assign one or more roles:

1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
2. Navigate to **Settings > Access Management > User Management**.
3. Select **Invite New User**.
4. Enter the email address of the user in the **Registered email address** field under **User details**.
5. In the **Assign roles** section, select the roles you want to assign:
   * **Default roles**: Select any of the five default roles (Developer, Operations, Manager, Admin, Support)
   * **Custom roles**: Select any custom roles you have created in the Role Management section
6. Review the permissions displayed in the **Permissions** section. When multiple roles are assigned, the permissions are combined.
7. Select **Invite New User**.

The user receives an invitation email and appears in the **Invited Users** list until they accept the invitation.

<img alt="Invite user and assign role" />

<Tip>
  Assigning multiple roles

  You can assign multiple roles to a user by selecting multiple role checkboxes. The **Permissions** section displays the combined permissions of all selected roles, making it easy to review the total access granted.
</Tip>

### Invite a user with direct permissions

You can invite users and enable specific permissions without assigning a formal role. This approach is useful for providing temporary access to specific features or when a user's responsibilities don't align with existing roles.

Follow these steps to invite a user and assign direct permissions:

1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
2. Navigate to **Settings > Access Management > User Management**.
3. Select **Invite New User**.
4. Enter the email address of the user in the **Registered email address** field under **User details**.
5. Scroll down to the **Direct Permission Assignment** section and select **Enable permissions without a specific role**.
6. Use the **Select Account for Payouts or VRS** dropdown to select the accounts the user can access (if applicable).
7. Configure permissions in the **Permissions** section:
   * **Search for a permission**: Use the search bar to find specific permissions
   * **Product dropdown**: Navigate through different products and features
   * **View toggle**: Enable or disable view-only access to modules or features
   * **Manage toggle**: Enable or disable full access (add, edit, download, delete)
8. Select **Invite New User**.

The user receives an invitation email and appears in the **Invited Users** list.

<img alt="Invite user with direct permissions" />

### Manage existing users

The **User Management** screen displays all active and invited users in your account. You can enable or disable users, edit their permissions, and remove users when necessary.

<Tabs>
  <Tab title="View and filter users">
    The user management table displays the following information:

    * **User email**: The email address of the user
    * **Roles**: The roles assigned to the user
    * **Status**: Active or Invited status
    * **Enable or disable toggle**: Enable or disable user access

      <img alt="Manage users table" />
  </Tab>

  <Tab title="Edit user details">
    To modify a user's roles or permissions:

    1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
    2. Navigate to **Settings > Access Management > User Management**.
    3. Locate the user in the table and select the ellipsis (⋮) icon.
    4. Select **Edit details**.
    5. In the **Update Details** popup, modify the roles or permissions as needed.
    6. Select **Update User**.
  </Tab>

  <Tab title="Disable or delete a user">
    To temporarily disable a user:

    1. Locate the user in the **User Management** table.
    2. Use the **Enable or disable** toggle to disable the user.

    The user retains their configuration but can't access the dashboard until re-enabled.

    To permanently delete a user:

    1. Locate the user in the **User Management** table and select the ellipsis (⋮) icon.
    2. Select **Delete**.
    3. Confirm the deletion.

       <img alt="Manage user options" />

    <Warning>
      Deleting users

      Deleting a user is permanent and can't be undone. The user must be re-invited if access is needed in the future.
    </Warning>
  </Tab>
</Tabs>

### View user details

To view comprehensive details about a user's roles and permissions:

1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
2. Navigate to **Settings > Access Management > User Management**.
3. Locate the user in the table and select the ellipsis (⋮) icon.
4. Select **View details**.

The details popup displays the user's email, assigned roles, and all enabled permissions.

## Role management

Beyond the five default roles, you can create custom roles with specific permission sets tailored to your organisation's needs. Custom roles enable you to define precise access levels for specialised team functions that don't align with the default roles.

### Create a custom role

You can create roles that grant access to specific features or products. For example, you can create a role that allows users to view Payment Gateway orders but nothing beyond that, or a role that provides full access to payouts but read-only access to payments.

Follow these steps to create a custom role:

1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
2. Navigate to **Settings > Access Management > Role Management**.
3. Select **New Role**.
4. Enter the following information in the **Create New Role** popup:
   * **Role**: Enter a descriptive name for the role (for example, "Payment Gateway Viewer" or "Payout Manager")
   * **Description**: Provide a clear description of the role's purpose and intended use
5. Configure permissions using the permissions table:
   * **Search for a permission**: Use the search bar to find specific permissions
   * **Product dropdown**: Navigate through different products and features
   * **View toggle**: Enable permissions that allow users to view modules or features
   * **Manage toggle**: Enable permissions that allow users to add, edit, download, or delete
6. Select **Create New Role**.

The role is created and appears in the **Role Management** screen. You can now assign this role to users in the User Management section.

<iframe title="YouTube video player" />

### Manage custom roles

Once you have created custom roles, you can edit or delete them as your organisation's needs change.

<Tabs>
  <Tab title="Edit a role">
    To modify an existing custom role:

    1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
    2. Navigate to **Settings > Access Management > Role Management**.
    3. Locate the role in the table and select the ellipsis (⋮) icon.
    4. Select **Edit role**.
    5. Update the role name, description, or permissions as needed.
    6. Select **Update Role**.

    Changes to a role apply immediately to all users assigned that role.
  </Tab>

  <Tab title="Delete a role">
    To delete a custom role:

    1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
    2. Navigate to **Settings > Access Management > Role Management**.
    3. Locate the role in the table and select the ellipsis (⋮) icon.
    4. Select **Delete**.
    5. Confirm the deletion.

    <Warning>
      Deleting roles

      Before deleting a role, ensure that no active users are assigned to it. If users are currently assigned to the role, you must reassign them to a different role or remove the role assignment before deletion.
    </Warning>
  </Tab>
</Tabs>

## Permissions framework

The permissions framework provides granular control over what users can view and manage across all Cashfree products and features. Understanding how permissions work helps you create effective roles and grant appropriate access to your team members.

### How to access permissions

Permissions appear in the Merchant Dashboard when you work with users and roles:

* **When inviting or editing users**:
  1. Navigate to **Settings > Access Management > User Management**
  2. Select **Invite New User** or edit an existing user
  3. The **Permissions** section displays all enabled permissions based on assigned roles or direct permission grants

* **When creating or editing roles**:
  1. Navigate to **Settings > Access Management > Role Management**.
  2. Select **New Role** or edit an existing role.
  3. Use the permissions table to configure View and Manage permissions for each product and feature.

* **When viewing user details**:
  1. Navigate to **Settings > Access Management > User Management**.
  2. Select the ellipsis (⋮) icon next to a user and choose **View details**.
  3. The popup displays all permissions currently enabled for that user.

<img alt="Configuring permissions" />

### Permission levels

Each feature in the dashboard supports two permission levels:

* **View**: Allows users to view information but not make changes. Users can access dashboards, view transactions, download reports, and see configuration settings.

* **Manage**: Provides full access to add, edit, download, delete, and configure features. This level includes all View permissions plus the ability to make changes.

<Tip>
  **Multiple roles and permissions**

  When a user has multiple roles or direct permissions, all permissions are combined (additive). The highest permission level applies (Manage overrides View). Learn more about [permission conflicts](/docs/help/account/access-management-faqs).

  **Permission scope**

  Permissions are organised by product category (Payment Gateway, Payouts, Secure ID, Subscriptions, Settings, Reports). The specific features available within each product can be viewed in the permissions interface when inviting users or creating roles.
</Tip>

### Account-specific permissions

For products like Payouts and Virtual Account Services, you can grant permissions for specific accounts rather than all accounts. This allows you to:

* Limit users to specific business units or brands
* Provide segregated access in multi-account setups
* Control access to specific fund sources or settlement accounts

## Best practices

Follow these recommendations to implement secure and effective access management:

<AccordionGroup>
  <Accordion title="Security practices">
    * **Principle of least privilege**: Grant users only the permissions they need to perform their job functions
    * **Regular access reviews**: Periodically review user access and remove permissions that are no longer required
    * **Disable inactive users**: Disable or delete user accounts for team members who no longer require access
    * **Use role-based access**: Prefer role-based assignments over direct permissions for easier management and consistency
  </Accordion>

  <Accordion title="Role design practices">
    * **Create focused roles**: Design roles for specific job functions rather than broad access levels
    * **Use descriptive names**: Name roles clearly to indicate their purpose (for example, "Finance Viewer" instead of "Role 1")
    * **Document role purposes**: Use the description field to explain when and why to use each role
    * **Review before assigning**: Always review the combined permissions before assigning multiple roles
  </Accordion>

  <Accordion title="User management practices">
    * **Verify email addresses**: Ensure user email addresses are correct before sending invitations
    * **Communicate with users**: Inform users when you grant or change their access
    * **Monitor login activity**: Use the login history feature to track user access patterns
    * **Require 2FA**: Enable two-factor authentication for all users accessing the dashboard
  </Accordion>

  <Accordion title="Operational practices">
    * **Separate duties**: Assign different responsibilities to different users to maintain checks and balances
    * **Use approval workflows**: For payouts, assign Initiator and Approver roles to different users
    * **Maintain audit trails**: Keep records of who has access to what and when changes are made
    * **Test before production**: Test new roles or permission changes with a single user before broad deployment
  </Accordion>
</AccordionGroup>

## FAQs

For more information and answers to common questions about access management, refer to the [Access Management FAQs](/docs/help/account/access-management-faqs).

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/help/account/manage-account#configure-2fa-authentication">Configure 2FA authentication</a></li>
    <li><a href="/docs/help/account/account-management#view-login-history">View login history</a></li>
    <li><a href="/docs/payouts/payouts/make-payouts/initiator-approver">Assign roles to request and approve transfers</a></li>
    <li><a href="/docs/secure-id/video-kyc/add-agent-auditor">Add an agent or auditor</a></li>
  </ul>
</div>


# Access Management
Source: https://www.cashfree.com/docs/help/account/access-management-faqs

Find answers to common Cashfree access management questions about user invitations, roles, custom permissions, multi-role assignments, and audit trails.

<AccordionGroup>
  <Accordion title="Can I assign multiple roles to a single user?">
    Yes. You can assign multiple roles to a single user by selecting multiple role checkboxes when inviting or editing the user. The permissions from all assigned roles are combined, giving the user access to all features permitted by any of the roles.

    When multiple roles are assigned, the **Permissions** section displays the combined permissions, making it easy to review the total access granted to the user.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What happens when I disable a user?">
    When you disable a user, they immediately lose access to the Merchant Dashboard and can't log in. However, their user account, role assignments, and permission configuration are retained in the system.

    To restore access, use the **Enable or disable** toggle to re-enable the user. They regain access with their previous roles and permissions intact.

    Disabling is useful for temporary access suspension (for example, during employee leave) without the need to reconfigure permissions later.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I edit default roles?">
    No. The five default roles (Developer, Operations, Manager, Admin, Support) are predefined by Cashfree and can't be edited or deleted. These roles are designed to cover common use cases and maintain consistency across merchant accounts.

    If the default roles don't meet your requirements, you can create custom roles with the exact permissions you need. Custom roles can be assigned alongside default roles, and you can create as many custom roles as needed for your organisation.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What is the difference between View and Manage permissions?">
    **View** permissions allow users to see information and access dashboards without making changes. Users with View permissions can:

    * View transaction lists and details
    * Access reports and analytics
    * See configuration settings
    * Download reports (read-only access)

    **Manage** permissions provide full access to modify and configure features. Users with Manage permissions can:

    * Perform all View actions
    * Create, edit, and delete items
    * Configure settings and parameters
    * Process transactions and approvals
    * Upload files and documents

    When designing roles or assigning permissions, grant Manage permissions only to users who need to make changes, and use View permissions for monitoring and reporting purposes.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How do I request access to features I cannot see?">
    If you are unable to access certain features in the Merchant Dashboard, your current role or permissions may not include access to those features. To request access:

    1. Identify the specific feature or page you need to access.
    2. Contact your account administrator or the person who invited you to the Cashfree account.
    3. Request that they update your role or add the necessary permissions through the User Management section.

    If you are unsure who manages your account, check the **Login History** page in the dashboard to identify users with Admin roles, or contact Cashfree support for assistance.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Is there a limit to the number of users I can add?">
    No. You can invite unlimited users to your Cashfree account at no additional cost.

    Follow the principle of least privilege and only grant access to users who require it for their job functions.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I create role hierarchies or nested roles?">
    No. The access management system doesn't support role hierarchies or nested roles. Each role is independent and contains its own set of permissions.

    However, you can achieve similar functionality by:

    * Assigning multiple roles to a user, which combines the permissions from all assigned roles
    * Creating custom roles that include specific permission sets
    * Using role naming conventions to indicate the scope or level of access (for example, "Payment Gateway Viewer" and "Payment Gateway Manager")

    This approach provides flexibility while maintaining simplicity in role management.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What happens to users when I delete a custom role?">
    You can't delete a custom role if it's currently assigned to any users. Before deleting a role, you must:

    1. Identify all users assigned to the role (visible in the Role Management section).
    2. Edit each user and either assign them a different role or remove the role assignment.
    3. After all users are reassigned, you can delete the custom role.

    This safeguard prevents accidental removal of user access and ensures that you consciously reassign permissions before deleting roles.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What should I do if a user didn't receive the invitation email?">
    If a user hasn't received the invitation email, try these solutions:

    1. **Check spam or junk folder**: Invitation emails sometimes get filtered. Ask the user to check their spam or junk mail folder.

    2. **Verify email address**: Ensure you entered the correct email address when inviting the user. Check for typos in the **User Management > Invited Users** section.

    3. **Resend invitation**:
       * Navigate to **Settings > Access Management > User Management**
       * Find the user in the **Invited Users** list
       * Select the ellipsis (⋮) icon and choose **Resend Invitation**

    4. **Email provider restrictions**: Some corporate email systems block automated emails. Contact your IT team to allowlist emails from `@cashfree.com` domains.

    5. **Wait and retry**: Email delivery can sometimes be delayed. Wait 10-15 minutes before resending.

    If the issue persists, contact Cashfree support with the user's email address.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Why can't a user see features after I assigned them a role?">
    If a user can't access expected features after role assignment, try these solutions:

    1. **Verify role permissions**:
       * Navigate to **Settings > Access Management > User Management**
       * Find the user and select **View details**
       * Review the enabled permissions to ensure they include the needed features

    2. **Check for account-specific restrictions**:
       * If using multiple accounts, verify the user has access to the correct account
       * Review the **Select Account for Payouts or VRS** settings for the user

    3. **Ask user to log out and log back in**:
       * Permission changes may require a fresh login session
       * User should log out completely and log back in

    4. **Clear browser cache**:
       * Ask the user to clear their browser cache and cookies
       * Try accessing the dashboard in an incognito/private browser window

    5. **Verify role assignment was saved**:
       * Check that you selected **Update User** or **Invite New User** after making changes
       * Confirm the role appears in the user's details

    6. **Review combined permissions**:
       * If the user has multiple roles, ensure none of them conflict
       * Check that the required permission isn't restricted by product activation status

    If features remain inaccessible, verify that the specific product (Payment Gateway, Payouts, etc.) is activated for your account.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Why does a user have more or less access than expected?">
    If a user has unexpected access levels or permission conflicts, try these solutions:

    1. **Understand permission combining**:
       * When a user has multiple roles, all permissions are combined (additive)
       * If any role grants a permission, the user has that permission
       * Manage permissions override View permissions

    2. **Review all assigned roles**:
       * Navigate to **Settings > Access Management > User Management**
       * Select the user and click **View details** or **Edit details**
       * Check all assigned roles and direct permissions

    3. **Check for direct permission assignments**:
       * Users may have both role-based and direct permissions
       * Review the **Direct Permission Assignment** section in the user's details

    4. **Remove conflicting roles**:
       * If a user has too many permissions, remove unnecessary roles
       * Edit the user and uncheck roles that provide broader access than needed

    5. **Use custom roles for precise control**:
       * Instead of combining multiple default roles, create a custom role with exactly the needed permissions
       * This provides clearer access control and easier management

    6. **Audit recent changes**:
       * Check the **Login History** page to see recent permission changes
       * Review who made changes and when

    For complex permission scenarios, document your intended access structure before making changes, and test with a single user before broad deployment.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Why can't I delete or edit a role?">
    If you're unable to delete or modify a custom role, try these solutions:

    1. **Check for assigned users**: You can't delete a role that's currently assigned to users. See [What happens to users when I delete a custom role?](#what-happens-to-users-when-i-delete-a-custom-role) for the complete process.

    2. **Default roles can't be edited**: See [Can I edit default roles?](#can-i-edit-default-roles) for information about editing system-defined roles.

    3. **Verify admin permissions**: Ensure your account has the Admin role or equivalent permissions. Only users with role management permissions can edit or delete roles.

    4. **Check active sessions**: If a user with the role is currently logged in, wait for their session to end or ask active users to log out, then try again.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What should I do if the user invitation link is expired or not working?">
    If the invitation link is expired or not working when the user tries to accept it, try these solutions:

    1. **Resend the invitation**:
       * Navigate to **Settings > Access Management > User Management**
       * Find the user in **Invited Users**
       * Select the ellipsis (⋮) icon and choose **Resend Invitation**

    2. **Check invitation status**:
       * Invitations may have expiration periods
       * Verify the user appears in the **Invited Users** section (not already accepted or expired)

    3. **Create new invitation**:
       * If resending doesn't work, delete the old invitation
       * Send a new invitation to the same user

    4. **Verify email link integrity**:
       * Ensure the user clicked the full link from the email
       * Some email clients break long addresses across lines—ask user to copy/paste the entire address

    5. **Try different browser or device**:
       * The link may have browser compatibility issues
       * Ask the user to try a different browser or device

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What is an account owner?">
    The account owner is the user who created the Cashfree account. This is a system-level designation assigned automatically at account creation and cannot be assigned through the Merchant Dashboard. Only one account owner can exist per account at any time.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How do I transfer account ownership?">
    Account ownership can be transferred to another user on the account. Once transferred, the new user assumes all account owner permissions and the previous owner loses them.

    To transfer ownership, contact [Cashfree support](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) or reach out to your Cashfree account manager with the registered email address of the user you want to transfer ownership to.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How do I delete my Cashfree account?">
    Account deletion cannot be initiated from the [Merchant Dashboard](https://merchant.cashfree.com/auth/login). To request deletion, contact your account manager by email. Your account manager coordinates with the Cashfree care team to process the request.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Who can invite new users (alias accounts) to the Merchant Dashboard?">
    Only the Primary Admin of the account can invite new users. For the full procedure, see [Invite a user and assign a role](/docs/help/account/access-management#invite-a-user-and-assign-a-role).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How do I collect browser network logs (HAR file) for troubleshooting Merchant Dashboard issues?">
    A HAR (HTTP Archive) file records the network requests your browser makes, which helps Cashfree diagnose Merchant Dashboard issues. To collect a HAR file in Google Chrome:

    1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
    2. Right-click anywhere on the page and select **Inspect**.
    3. Go to the **Network** tab and select the **Preserve log** checkbox.
    4. Select the **Clear** icon to remove existing logs.
    5. Reproduce the issue by refreshing the page.
    6. Right-click inside the Network request list and select **Save all as HAR with content**.

    Chrome saves the `.har` file to your computer. Attach it when you raise a request through the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1).

    <iframe title="FAQs feedback component" />
  </Accordion>
</AccordionGroup>


# Account Activation
Source: https://www.cashfree.com/docs/help/account/account-activation

Follow Cashfree account activation steps for your business entity: KYC documents, bank verification, and entity-specific onboarding lists.

To activate a Cashfree account, you must complete the onboarding process, submit entity-specific documents, and verify business details. For exploration, the sandbox environment allows you to test Cashfree products and simulate payment scenarios before going live.

This page covers the following topics:

* [Create an account](#create-an-account)
* [Explore test environment](#explore-test-environment)
* [Required documents](#required-documents)
* [Documents by entity type](#documents-by-entity-type)

<div>
  <iframe title="Account creation process" />
</div>

## Create an account

To create a Cashfree account, complete the following steps:

1. Go to the [Cashfree sign up page](https://merchant.cashfree.com/merchants/signup?source-action=Home%20page\&action=Sign%20Up\&button-id=StartNow_Navbar).
2. Provide the business email address and set a password, then select **Continue**. Alternatively, select **Sign up with Google** to create the account directly.
3. Enter the mobile number, select **Create account**, and verify it using the OTP sent to the registered phone.

<Note>
  Select the checkbox to receive account updates via WhatsApp. Cashfree may contact you for clarifications during the onboarding process.
</Note>

After signing up, follow the instructions to complete account activation:

<Steps>
  <Step title="Business details">
    On the **Business details** page, enter the **brand name**, select the **product or service category**, and choose the **annual turnover** range from the dropdown menu. Select **Continue** to proceed.

    <img alt="Business details page" />
  </Step>

  <Step title="Choose your solution">
    On the **Choose your solution** page, select the product that best fits the business needs. Provide the following details based on the selection:

    <Tabs>
      <Tab title="Collect Payments">
        Accept and automate online payments from customers across web and mobile apps while ensuring high conversion rates.

        * **Requirements**: Provide the **website URL** or the **Play Store or App Store URL** for the app.
          <img alt="payments" />
      </Tab>

      <Tab title="Verify My Customers">
        Onboard users faster and prevent fraud using automated Aadhaar, PAN, bank account, and KYC verification.

        * **Requirements**: Provide the **website URL**.
          <img alt="secure-id" />
          <Note>Business PAN is mandatory for this selection in the next step.</Note>
      </Tab>

      <Tab title="Make Payouts">
        Send instant money transfers to bank accounts, UPI IDs, cards, or wallets for vendor payments, refunds, and salaries.

        * **Requirements**: Provide the **website URL**.
          <img alt="Payouts" />

        <Note>Business PAN is mandatory for this selection in the next step.</Note>
      </Tab>
    </Tabs>

    Select **Continue** after choosing the preferred solution.
  </Step>

  <Step title="KYC information">
    On the **KYC information** page, provide the following details:

    * **Business registration details**: Enter a valid business PAN number. The system uses the PAN to fetch the legal name and GST, CIN, LLPIN data.

      <img alt="" />

    The remaining steps on the **KYC information** page vary based on the business structure:

    <Tabs>
      <Tab title="Individual">
        * **Archetype identification**: The system automatically identifies individuals using the fourth digit "P" of the provided PAN.

        * **Business owner verification**:
          * **OTP verification**: Complete identity verification instantly using the Aadhaar number and the OTP sent to the registered mobile number.
          * **DigiLocker verification**: Securely authenticate and share Aadhaar information via the DigiLocker account.
          * **CKYC verification**: Use the Central KYC (CKYC) record to prefill details automatically. This method is optional.
          <img alt="New KYC flow" />

        * **CKYC verification flow**: If CKYC verification is chosen, follow the steps below to complete it:

          <Steps>
            <Step title="Authenticate via CKYC">
              If CKYC verification is chosen, enter the mobile number and OTP linked to the PAN's CKYC record. The system will then securely retrieve their identifying documents.

              <div>
                <img alt="CKYC Mobile" />

                <img alt="CKYC OTP" />

                <img alt="CKYC Loading" />
              </div>
            </Step>

            <Step title="Verify and confirm documents">
              Once the records are fetched, review the retrieved document (such as a driving licence or PAN). If the details are correct, click **Confirm**. You can also remove and upload a new document if needed.

              <img alt="Confirm Fetched Documents" />
            </Step>
          </Steps>

        * **Principal place of business**: Enter the complete and accurate business address. The business location is subject to physical verification.

        <div>
          <img alt="KYC step" />
        </div>

        * **Upload business documents**: For proprietorship businesses, upload at least **two** proofs of business (such as Udyam, Shop & Establishment, or MSME certificate).
          <img alt="" />
          * Municipal certificate
          * Udyog Aadhaar
          * Shop & Establishment certificate
          * Other government-issued registration proofs
          <Note>
            If you do not have these documents, Cashfree changes the business type to **Unregistered**.
          </Note>
      </Tab>

      <Tab title="Registered entity">
        * **Archetype identification**: The system automatically identifies registered entities if the fourth digit of the provided PAN is not "P". For example, the fourth letter of a business PAN is "C".

        * **Authorised signatory verification**: An authorised signatory must be verified to access the CKYC information and complete the KYC.
          <img alt="" />

        <Note>
          After getting consent of the merchant, the CKYC record is automatically retrieved using the business **PAN** and **Date of Incorporation (DOI)**.
        </Note>

        * **Beneficial owner (BO) details**:
          Identify all individuals who hold a significant beneficial interest in the business, as required under the RBI KYC Master Direction.

          <Steps>
            <Step title="Review the prefilled BO list">
              The system identifies potential beneficial owners and executives based on the merchant's records.

              * **Verified BOs**: If a BO has a green **Verified** status, no further action is required for them.

              Once the list is accurate, select **Confirm Beneficial Owners** to proceed.

              <div>
                <img alt="Prefilled BO list" />

                <img alt="Final BO confirmation" />
              </div>

              <Note>
                Once the verification is complete and the final list is confirmed, it becomes a **frozen list**. Beneficial Owner details cannot be changed or edited from the dashboard after that.
              </Note>
            </Step>

            <Step title="Select and verify unverified BOs">
              In case you are required to verify an unverified BO, you will see three verification options:

              * **CKYC verification**: Verify using the mobile number and OTP linked to their CKYC record.
              * **DigiLocker verification**: Authenticate via Aadhaar on their DigiLocker account.
              * **OTP verification**: Verify instantly using Aadhaar number and an OTP.

              <img alt="Verification Options" />
            </Step>

            <Step title="Authenticate via CKYC">
              If CKYC verification is chosen, enter the mobile number and OTP linked to the PAN's CKYC record. The system will then securely retrieve their identifying documents.

              <div>
                <img alt="CKYC Mobile" />

                <img alt="CKYC OTP" />

                <img alt="CKYC Loading" />
              </div>
            </Step>

            <Step title="Verify and confirm documents">
              Once the records are fetched, review the retrieved document (such as a driving licence or PAN). If the details are correct, click **Confirm**. You can also remove and upload a new document if needed.

              <img alt="Confirm Fetched Documents" />
            </Step>
          </Steps>

        <Note>
          A beneficial owner is any individual who:

          * Holds more than **10%** of the ownership or share capital in a **company**, **partnership**, or **Limited Liability Partnership (LLP)**.
          * Holds more than **15%** of the interest in an **association**, **body of individuals (BOI)**, or **society**.
          * Is entitled to **10% or more** of the interest in a **trust**.

          Beneficial owners do not need to be identified for publicly listed companies or their majority-owned subsidiaries.
        </Note>

        * **Principal place of business**: Enter the complete and accurate business address. The business location is subject to physical verification.

        <div>
          <img alt="KYC step" />
        </div>

        * **Upload business documents**: Provide the required business documents for final verification.
          <img alt="" />

        <Note>
          The exact documents required for upload vary depending on entity type. See [documents by entity type](#documents-by-entity-type) for the list that applies to your business.
        </Note>
      </Tab>
    </Tabs>
  </Step>

  <Step title="Bank account setup">
    On the **Bank account setup** page, enter the company's **bank account number** and **IFSC code** to ensure settlements reach the correct account. Click **Verify** to validate the details.

    <Note>
      The first transaction in newly opened accounts must be a credit from an existing KYC-complied bank account of the customer.
    </Note>

    <img alt="Bank account setup page" />
  </Step>

  <Step title="Video KYC and submit">
    **Video KYC (V-CIP)** is a remote video call used to complete KYC for **individuals** or the **authorised signatory** when required.

    * **When V-CIP is required**
      * V-CIP is triggered if **Enhanced Due Diligence (EDD) fails**, or if additional supporting documents are still needed after EDD.

    * **When V-CIP can be deferred**
      * If **EDD is successful** and any requested documents are uploaded and verified, V-CIP is **not required** and can be deferred.

    <Note>
      **Enhanced Due Diligence (EDD)** is an additional risk check performed before moving to V-CIP. EDD typically includes address verification, automated website and PAN checks, validation that the first transaction comes from an existing KYC-complied bank account, and review of email and phone communication trails. If these checks pass, the system relies on EDD and V-CIP is usually not required.
    </Note>

    Select **Submit to verify** to finalise the application. After a brief verification process, you receive a confirmation, allowing you to start [integrating Cashfree](/docs/payments/overview) into your platform.

    <img />
  </Step>
</Steps>

<Note>
  Account activation typically takes **24 working hours** after you submit all required documents, subject to compliance verification.
</Note>

The video below highlights the detailed process of account creation.

<Card>
  <iframe title="YouTube video player" />
</Card>

### Explore test environment

The test environment serves as a sandbox to explore and experiment with Cashfree features without any financial impact. You can:

* Familiarise yourself with the dashboard interface.
* Explore integrations and read product documents.
* Test product features and simulate various payment scenarios.
* Verify workflows before going live.

Once you are confident with the setup in the test environment, you can activate your account to start processing real payments.

<img alt="test environment" />

## Required documents

Account activation requires verification of the business and the identity of the person(s) who will operate it. Requirements vary by entity and line of business; see [Documents by entity type](#documents-by-entity-type) for the list that applies to your business.

### Business owner identification

Cashfree verifies the identity of the business owner or the person authorised to act for the business (authorised signatory) in one of these ways:

| Method | Description |
| :- | :- |
| **Aadhaar OTP** | Cashfree sends a one-time password (OTP) to the mobile number linked to the Aadhaar. The merchant enters it to confirm identity. This is the most common method. |
| **Central KYC (CKYC)** | If KYC has already been completed with a bank or another regulated entity, details may be in the Central KYC registry. With consent, Cashfree fetches them so the merchant does not have to re-enter everything. Cashfree must attempt this for individuals as per guidelines. |
| **DigiLocker** | The merchant can sign in to their DigiLocker account and share Aadhaar or another government ID from there. Cashfree uses it to verify identity without a physical document upload. |
| **Manual (original valid document)** | If Aadhaar OTP, CKYC, or DigiLocker doesn’t work (e.g. mobile not linked, or technical issue), Cashfree accepts a certified copy of an original valid document such as a passport, voter ID, or driving licence. |

### Documents by line of business (LOB)

Additional documents are required based on the business category to determine the Merchant Category Code (MCC) and ownership.

| Category | Sub-category | Documents |
| :- | :- | :- |
| SaaS | Software as a service (SaaS) | AOC for PCI-DSS compliance |
| SaaS | Food, health and beauty supplements | FSSAI |
| Education | Schools, colleges, vocational schools | UGC certificate/ICSE/CBSE/AICTE |
| Finance | Forex | FEMA registration, FFMC certificate |
| Finance | Payment service provider | PA PG licence, nodal account |
| Finance | Stock brokerage and trading | SEBI certificate |
| Finance | Lending | NBFCs or SLAs with RBI approved NBFCs |
| Utilities | Electric, gas, water | BBPS certificate |
| Travel | Tours and travel agencies | IATA certificate or IRCTC agency certificate |

### Website compliance

Cashfree automatically checks the merchant's website or app for:

| What is checked | Description |
| :- | :- |
| Legal name match | Cashfree confirms that the business name on the site matches the one on the registration documents so the merchant's ownership or representation can be verified. |
| Business category (MCC) | Cashfree verifies that the stated business category is correct using automated checks. This helps apply the right rules for the industry. |

### Documents by entity type

Based on the business entity type, different documents are required. The sections below list what is needed for each entity; merchants may also need [extra documents by line of business](#documents-by-line-of-business-lob).

<AccordionGroup>
  <Accordion title="Individuals (unregistered) or Proprietorship">
    For a sole proprietor, the PAN’s fourth character is **P**. The items below are what is needed to verify the merchant and the business.

    | Documents needed | Description |
    | :- | :- |
    | **PAN or Form 60** | The personal Permanent Account Number (PAN) used for the business. If the merchant does not have a PAN, Form 60 (a declaration) is used instead as per tax rules. |
    | **Bank details** | The bank account where settlements are to be received. The account must be in the name of the business owner. Cashfree needs the account number and IFSC to verify it. |
    | **Aadhaar or Central KYC (CKYC)** | Identity is verified using Aadhaar (OTP sent to the linked mobile) or by pulling details from the Central KYC registry if KYC has already been completed with a bank or other regulated entity. Cashfree must attempt CKYC for individuals as per guidelines. |
    | **Business proof** | If Cashfree's automated checks or address verification cannot confirm the business, at least **two** documents that show the business exists are required. Examples: GST registration, Udyam (MSME) certificate, Shop & Establishment licence, municipal or other local registration, tax returns, professional licence, IEC (import-export code), or any other government-issued business registration. |

    <Note>
      If the merchant's details are in the Central KYC registry, Cashfree fetches them (including Aadhaar ID and permanent and current address where available) and fewer fields need to be filled. If not, Cashfree may ask for a short video call (Video KYC) to verify identity and address via DigiLocker or document upload.
    </Note>
  </Accordion>

  <Accordion title="Public or private limited company">
    For companies registered with the Ministry of Corporate Affairs, Cashfree verifies the company, the person who will operate the account (authorised signatory), and anyone with significant ownership (beneficial owners).

    | Documents needed | Description |
    | :- | :- |
    | **Business PAN** | The company’s Permanent Account Number (PAN). Cashfree uses it to fetch basic company details from government records. |
    | **Certificate of Incorporation (CIN)** | The official document that shows the company was registered. Cashfree tries to fetch it automatically using the company PAN; if not available, the merchant may need to upload it. |
    | **Memorandum of Association (MOA) and Articles of Association (AOA)** | The legal documents that define the company’s purpose, rules, and structure. Cashfree requires certified copies. They help confirm the company name, registered address, and who the directors and significant shareholders are. |
    | **Board resolution or power of attorney** | A document from the company (on letterhead, signed by a director or company secretary) that authorises specific managers or officers to operate the Cashfree account on behalf of the company. A power of attorney can serve the same purpose if it clearly grants this authority. |
    | **Authorised signatory identity** | The person who will operate the account must prove their identity. Cashfree accepts Aadhaar or PAN, and verifies them via Central KYC (CKYC), DigiLocker, or an uploaded copy of a valid ID (e.g. passport, voter ID, driving licence). |
    | **Beneficial owners** | Anyone who holds a significant share or control in the company (as per RBI guidelines) must complete KYC. At least one beneficial owner must be verified for initial activation. Cashfree often prefills names from CKYC or from directors linked to the company PAN; the merchant confirms or adds anyone else. |
    | **Address** | The company’s registered office address and, if different, the principal place of business. Cashfree uses this for verification and correspondence. |

    <Note>
      Cashfree prefills directors and the person operating the account from company records and Central KYC when possible; then the merchant confirms or adds details. If not, the merchant will need to upload board resolution, power of attorney, and identity documents, and Cashfree may ask for a video call.
    </Note>
  </Accordion>

  <Accordion title="Limited Liability Partnership (LLP) or Partnership">
    For LLPs and partnerships, Cashfree verifies the firm, the person who will operate the account, and the partners.

    | Documents needed | Description |
    | :- | :- |
    | **Business PAN** | The firm’s or LLP’s Permanent Account Number (PAN). |
    | **LLPIN (for LLPs)** | The Limited Liability Partnership Identification Number. Cashfree fetches it automatically for LLPs where possible. |
    | **Registration certificate** | Official proof that the LLP or partnership is registered with the relevant authority (e.g. Registrar of Firms), where applicable. |
    | **Partnership deed** | The legal agreement between partners that sets out profit-sharing, roles, and other terms. It is mandatory for partnerships and helps Cashfree identify partners and the person authorised to act for the firm. |
    | **Partner or signatory identity** | The designated partner or person who will operate the Cashfree account must prove their identity using Aadhaar or PAN, verified via Central KYC (CKYC), DigiLocker, or an uploaded ID. |
    | **Partner KYC summary** | A list of all partners (or designated partners for LLPs) and any authorised signatories, with their KYC details completed as per standard individual verification requirements. |

    <Note>
      Cashfree gets partner names from the deed and the person operating the account from Central KYC when available. If not, Cashfree may ask for the registration certificate and a video call to verify identity.
    </Note>
  </Accordion>

  <Accordion title="Society, trust, or NGO">
    For trusts, societies, and NGOs Cashfree verifies the entity, the person authorised to operate the account, and key functionaries (e.g. trustees).

    | Documents needed | Description |
    | :- | :- |
    | **Entity PAN or Form 60** | The trust’s, society’s, or NGO’s Permanent Account Number (PAN). If the entity doesn’t have a PAN, Form 60 is used as per tax rules. |
    | **Authorised signatory identity** | The trustee, secretary, or other person who will operate the Cashfree account must prove their identity (Aadhaar or PAN) via Central KYC (CKYC), DigiLocker, or an uploaded ID. |
    | **Entity documents** | **Trust:** Trust deed and, if the trust is registered, its registration certificate. **NGO or Society:** Registration certificate and, where applicable, 80G or 12A certificates (tax exemption documents). These help Cashfree confirm the entity’s name, purpose, and who runs it. |
    | **Key persons and beneficiaries** | A list of trustees, key functionaries, and anyone else authorised to operate the account, with their KYC completed. For trusts, Cashfree may also need details of beneficiaries, settlor, or protector as per RBI KYC guidelines. |

    <Note>
      When the person operating the account is in Central KYC, Cashfree fetches their details and usually no video call is needed. Otherwise Cashfree may ask for a video call and the registration certificate (if the trust or society is registered).
    </Note>
  </Accordion>

  <Accordion title="Unincorporated association or body of individuals">
    For associations or bodies of individuals that are not registered as a company, LLP, or society, Cashfree needs proof of the group’s existence and who can act for it.

    | Documents needed | Description |
    | :- | :- |
    | **Governing resolution** | A resolution or decision from the managing body (e.g. committee) that authorises the relationship with Cashfree and names the person(s) who can operate the account. |
    | **PAN or Form 60** | The PAN (or Form 60 if no PAN) in the name of the association or body of individuals. |
    | **Power of attorney** | A document that authorises specific persons to carry out transactions and represent the association or body with Cashfree. |
    | **Authorised persons’ KYC** | Identity and address verification for the beneficial owners, managers, officers, or employees who are authorised to operate the account, as per standard individual KYC requirements. |
    | **Existence documents** | Any documents that together establish that the association or body exists and how it is structured (e.g. constitution, rules, or registration with a government or regulatory body). |

    <Note>
      Cashfree verifies the person authorised to act for the body; if their details are in Central KYC the process is simpler. Otherwise Cashfree may ask for a video call and documents such as the governing resolution, power of attorney, identity proof of the person authorised to act, or documents that establish the body’s existence.
    </Note>
  </Accordion>

  <Accordion title="Other juridical persons (e.g. local bodies, universities)">
    Entities such as local authorities, universities, or other legal persons created by law need to show who can act for them and that the entity exists.

    | Documents needed | Description |
    | :- | :- |
    | **Authorisation documents** | Documents that state the name of the person authorised to act on behalf of the entity and the scope of their authority (e.g. what they can sign or approve). |
    | **Authorised person’s KYC** | Identity and address verification for that person, in line with standard individual KYC requirements. |
    | **Existence documents** | Official documents that prove the entity exists—for example, registration or establishment acts, government notifications, or equivalent documents. |

    <Note>
      Identity of the person authorised to act is verified via Central KYC, DigiLocker, or document upload. If Cashfree cannot verify them automatically, a video call and documents such as authorisation proof and identity or existence documents may be requested.
    </Note>
  </Accordion>

  <Accordion title="Hindu undivided family (HUF)">
    A Hindu Undivided Family is a legal entity under Hindu law, comprising the family and its property. The **Karta** is the head of the HUF and typically manages its affairs.

    | Documents needed | Description |
    | :- | :- |
    | **HUF PAN** | The Permanent Account Number (PAN) of the HUF as an entity. It is mandatory for the HUF to have its own PAN. |
    | **Karta PAN** | The PAN of the person who is the Karta (head) of the HUF. Cashfree uses this to verify the person managing the HUF. |
    | **Bank details** | The HUF’s bank account number and IFSC code. Settlements will be credited to this account. |
    | **Aadhaar of Karta** | The Karta’s Aadhaar number. Cashfree verifies it by sending an OTP to the mobile number linked to that Aadhaar. |
    | **HUF registration proof** | A document that proves the HUF exists—typically the HUF deed, or a letter from the tax authority recognising the HUF. |
    | **Identity proof of Karta** | A copy of a valid ID for the Karta: Aadhaar, driving licence, voter ID, or passport. This supports the KYC Cashfree performs for the person acting for the HUF. |

    <Note>
      When the Karta’s details are in Central KYC Cashfree fetches them and fewer steps are required. If not, Cashfree may ask for a video call and the HUF deed.
    </Note>
  </Accordion>
</AccordionGroup>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/help/account/overview">Account Overview</a></li>
    <li><a href="/docs/help/onboarding-related/onboarding-faqs">Onboarding FAQs</a></li>
    <li><a href="/docs/help/account/faq">Account FAQs</a></li>
    <li><a href="/docs/payments/online/resources/sandbox-environment">Sandbox environment</a></li>
    <li><a href="/docs/payments/online/go-live/checklist">Go live checklist</a></li>
  </ul>
</div>


# Account Management
Source: https://www.cashfree.com/docs/help/account/account-management

Update Cashfree profile details, configure two-factor authentication, manage notification preferences, view login history, and download tax invoices.

The **Profile** page in the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) allows you to manage your account information and control overall account activities. Use this page to update your contact details, enable two-factor authentication, set notification preferences, monitor login activity, and download invoices.

This page covers the following topics:

* [Manage profile information](#manage-profile-information)
* [Configure 2FA authentication](#configure-2fa-authentication)
* [Manage communications](#manage-communications)
* [View login history](#view-login-history)
* [View invoices](#view-invoices)
* [FAQs](#faqs)

## Manage profile information

The **My Information** section displays the following details under **Personal Profile**:

* **Name**: The registered name of your Cashfree account.
* **Email ID**: The registered email address of your Cashfree account.
* **Phone Number**: The registered phone number of your Cashfree account.
* **Customer Support Email**: Your customer support email address.
* **Account Password**: Select **Update Password** to change your account password.

<img alt="My Information section in the Merchant Dashboard" />

### Update profile information

You can edit your details such as email ID, phone number, and customer support email ID using the features available on the dashboard. The **Edit** icon next to each field allows you to update the information after successful OTP authentication.

To update your profile information:

1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
2. Navigate to **Profile > My Information**.

<AccordionGroup>
  <Accordion title="Update email ID">
    1) Select the **Edit** icon next to the email ID field.
    2) In the **Edit Email** popup, enter your Aadhaar number and select **Verify**.

    <Warning>
      Correct Aadhaar number

      Ensure you use the Aadhaar number that was used during the KYC process of your Cashfree account.
    </Warning>

    3. In the **Enter OTP** popup, enter the OTP received on your Aadhaar-registered mobile number and select **Confirm**.
    4. Enter the new email address in the **Email ID** field and select **Verify Changes**.
    5. Enter the OTP sent to your new email address in the **Verify Email** popup and select **Confirm**.

    Cashfree reviews the request and updates the email ID for your account within 24-48 hours. The system logs you out after email verification. Use your updated email address and the existing password to log in.
  </Accordion>

  <Accordion title="Update phone number">
    1. Select the **Edit** icon next to the phone number field.
    2. In the **Edit Phone Number** popup, enter your Aadhaar number and select **Verify**.
    3. In the **Enter OTP** popup, enter the OTP received on your Aadhaar-registered mobile number and select **Confirm**.
    4. Enter the new phone number in the **Enter New Phone Number** field and select **Verify Phone**.
    5. Enter the OTP sent to your new phone number in the **Verify Phone Number** popup and select **Confirm**.

    Cashfree reviews the request and updates the phone number for your account within 24-48 hours.

    <Note>
      Validation process

      You only need to complete the Aadhaar validation process once when updating both email and phone number information.
    </Note>
  </Accordion>

  <Accordion title="Update customer support email ID">
    1. Select the **Edit** icon next to the customer support email ID field.
    2. Enter the OTP sent to your registered phone number or email address in the **Authenticate** popup and select **Confirm**.
    3. Enter the new customer support email ID in the **Customer Support Email ID** field and select **Verify Changes**.

    The customer support email ID is updated for your account.
  </Accordion>
</AccordionGroup>

<Note>
  To confirm your identity and prevent fraudulent activities, you must complete Aadhaar validation to update your contact information.
</Note>

## Configure 2FA authentication

Two-factor authentication (2FA) is a method to confirm secure login to your Cashfree account and authenticate specific operations. It combines two different factors: sign-in password and OTP to confirm user identity.

By default, you receive an OTP to your registered phone number via SMS. You can configure it to receive the OTP on your email as well. Once the OTP is validated, the session is valid for 15 minutes.

To add another layer of security to the login sequence for your Cashfree account:

1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
2. Navigate to **Profile > 2FA Authentication**.
3. Switch the toggle **Enable 2FA for Login** to enable two-factor authentication for every login attempt for you and your team members.

This added layer of security reduces fraud and keeps your account secure.

<img alt="2FA Authentication settings" />

<Note>
  **Use Google Authenticator**

  If you don't want to use OTP-based authentication, select **Use this Method Instead** to configure your account authentication via the Google Authenticator app.
</Note>

## Manage communications

The **Communications** section allows you to manage the notification preferences for various events.

To create or edit notification preferences:

1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
2. Navigate to **Profile > Communications**.
3. Select **Manage Notifications** and then select **Email Notifications**.
4. Enter the email address to set notification preferences and select **Next**.
5. Select which notifications to deliver to the entered email.
6. Select **Submit** to save the preference.

<img alt="Create notification preferences" />

When an email is configured to receive notifications for a particular event (for example, API Updates), a confirmation email is sent to the recipient's email address. The recipient can select the **Confirm** button to provide their consent. Once consent is provided, the recipient will start receiving notifications about those particular events.

### Check recipient's consent status

To check whether a recipient has provided their consent to receive notifications:

1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
2. Navigate to **Profile > Communications**.
3. Select any category card.
4. Hover over any email to see the consent status.

## View login history

The **Login History** section displays information about successful logins by users added to your Cashfree account.

To search and filter login history:

1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
2. Navigate to **Profile > Login History**.
3. Use the following filters to search for specific login history:
   * **All Time**: Use this dropdown menu to set the date range.
   * **Search and Filter**: Use this dropdown menu to set the search filter.
     * **Search**: Use this dropdown menu to determine the search value and enter the value in the field. For example, if you choose **Email ID**, enter the specific email ID in the field.
4. Select **Apply**.

The results display in a grid format.

<img alt="Login History section" />

## View invoices

The monthly invoices generated for your Cashfree account are available in the **Invoice** section. You can download the invoices for your records.

To view and download invoices:

1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
2. Navigate to **Profile > [Invoice](https://merchant.cashfree.com/common/profile/invoice)**.
3. Select the download icon next to the invoice you want to download.

<img alt="Invoice section" />

## FAQs

For more information and answers to common questions about account management, refer to the [Account Management FAQs](/docs/help/account/account-management-faqs).

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/help/account/overview">Account Overview</a></li>
  </ul>
</div>


# Account Management
Source: https://www.cashfree.com/docs/help/account/account-management-faqs

Browse common Cashfree account management questions about updating phone numbers, enabling two-factor authentication, login alerts, and invoice downloads.

<AccordionGroup>
  <Accordion title="I don't have access to the phone number saved for my account, how can I log in?">
    We recommend that you update your account records from the Profile section after successful login.

    Follow the [instructions to update your phone number](/docs/help/account/account-management#update-phone-number).
    If the problem still persists, fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="I am not able to get the OTP, what can I do?">
    Check the last four digits of the phone number where the OTP is being sent. If you don't recognise or have access to this phone number reach out to [care@cashfree.com](mailto:care@cashfree.com) to get it updated. If you are not able to receive OTP on the correct phone number or if you are facing other OTP verification issues, wait and try again after some time. If the problem persists, reach out to [care@cashfree.com](mailto:care@cashfree.com).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Why am I being asked for OTP on login?">
    We have rolled out a new feature that mandates two-factor authentication on login from a new device and again after every 30 days.

    We do this to ensure the safety and security of your Cashfree account, and we strongly recommend that you keep your account details updated to avoid any login difficulties.

    For more information, refer to the product update communication we sent with the subject line: \[Product Updates] Two-Factor Authentication on New Device Login

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="I don’t want to get OTP on sms, how can I change the OTP preference?">
    We strongly recommend that you use your phone number as the second factor of authentication to secure your Cashfree account.
    You can also opt for Google Authenticator to receive 2FA OTPs and you can configure this from your profile section.
    Follow the [instructions to configure 2FA authentication](/docs/help/account/account-management#configure-2fa-authentication).

    If you are facing issues with mobile OTPs and wish to use email as an OTP channel, fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) and we will be happy to assist you.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How do I enable Google Authenticator for two-factor authentication?">
    To enable Google Authenticator for 2FA on your Cashfree account:

    1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
    2. Navigate to **Profile>Manage your profile>2FA Authentication**.
    3. Authenticate using your current OTP method (SMS) to access the 2FA settings.
    4. In the 2FA section, select **Google Authenticator** as your authentication method.
    5. Download the Google Authenticator app on your mobile device from [App Store](https://apps.apple.com/app/google-authenticator/id388497605) or [Play Store](https://play.google.com/store/apps/details?id=com.google.android.apps.authenticator2) if you haven't already.
    6. Open the app and scan the QR code displayed on your dashboard, or manually enter the setup key.
    7. Enter the 6-digit code generated by the authenticator app to verify and complete the setup.

    Once enabled, you'll receive authentication codes from Google Authenticator instead of SMS OTPs. Make sure to save your recovery codes in a secure location in case you lose access to the app.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="I want to change the phone number being used to send OTPs what can I do?">
    You can change your phone number from your profile section.

    Follow the [instructions to update your phone number](/docs/help/account/account-management#update-phone-number).

    Note that you will be asked to verify your identity through Aadhaar OTP validation, so make sure that you can access the Aadhaar and Phone number that was used during the activation process. Fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) if you require further assistance.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="I want to change the registered email address from my Cashfree Account, what can I do?">
    You can change your registered email address from your profile section.

    Follow the [instructions to update your customer support email ID](/docs/help/account/account-management#update-email-id).

    Note that you will be asked to verify your identity through Aadhaar OTP validation, so make sure that you can access the Aadhaar and phone number that was used during the activation process. Fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) if you require further assistance.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="I can't log in to the Merchant Dashboard after an email change, a captcha block, or a password reset. What should I do?">
    The fix depends on the scenario:

    * **Email address changed**: log in with your new email address. Your old email address no longer works as a login once you change it.
    * **Captcha blocking login**: try an incognito or private browser window, or a different browser. Clear your cache and cookies if the issue continues.
    * **Team member sees "0 accounts connected" after a password reset**: this means the account association was lost during the reset. Fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) to have your account re-linked to the parent account.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="As an team member user, how can I change my phone number?">
    Team member user details can be updated only by the account owner from the Settings section of the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).

    As a team member, you can ask your account owner to update your profile details by logging in to [https://merchant.cashfree.com/auth/login](https://merchant.cashfree.com/auth/login) and following the [instructions to update your phone number](/docs/help/account/account-management#update-phone-number).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="I can't find the “Login by Alias” tab on the login page. Where did it go?">
    As of March 2025, the "Alias" login method has been deprecated. This functionality has been fully transitioned to the Team Members feature. Team members can now log in using their email addresses, and new team members can be invited via email.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Lost access to the authenticator app used for multi-factor authentication (MFA): How can you recover access to your Cashfree account?">
    If you've lost access to the authenticator app used for multi-factor authentication (MFA), reach out to [care@cashfree.com](mailto:care@cashfree.com) for support.

    In your support request email:

    * Clearly describe the issue.
    * Use your registered email ID.
    * Include a phone number to receive OTPs.

    The Cashfree team will verify your details and switch your MFA method to OTP.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How can I stop the setup pop-up from appearing every time I log in to the Merchant Dashboard?">
    To skip the setup pop-up during a login session, click **I will do this later**. To stop the pop-up from appearing permanently, click **Finish setting up now** and complete any pending KYC details.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Lost access to the phone number used for OTP multi-factor authentication (MFA): How can you recover access to your Cashfree account?">
    If you no longer have access to the phone number used for OTP-based MFA,reach out to [care@cashfree.com](mailto:care@cashfree.com) for support.

    In your support request email:

    * Clearly describe the issue.
    * Use your registered email ID.
    * Provide your new phone number to receive OTPs.

    The Cashfree team will verify your details and update your OTP MFA phone number.

    <iframe title="FAQs feedback component" />
  </Accordion>
</AccordionGroup>


# Account
Source: https://www.cashfree.com/docs/help/account/faq

Find answers to frequently asked questions about Cashfree account activation, KYC documents, onboarding flows, and post-go-live account management.

<AccordionGroup>
  <Accordion title="Which merchants will see the new onboarding flow?">
    This flow applies to new merchants who sign up after the go-live date (January 1, 2026):

    * **New Signups**: Will go through the new flow (Video KYC, BO identification, etc.)
    * **Existing/Pending Merchants**: Merchants who started onboarding before the new flow went live will remain on the old flow. They do not need to restart.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Why does a merchant's form look different from our help articles?">
    Check their signup date. If they signed up after January 1, 2026, they are on the "New Onboarding Journey". The UI for address verification and BO identification has changed. Refer to the New Onboarding Flow walkthrough deck for the latest screens.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Will my PG be activated if I have signed up earlier on a different product and initiated PG onboarding now?">
    If you signed up before January 1, 2026, on a different product but are now initiating Payment Gateway (PG) onboarding, you will follow the onboarding rules applicable at the time you initiate PG setup. Check your signup date to confirm which flow applies to you.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How long would it take to activate my account?">
    After submitting your documents for review, your account is **typically activated within 24 working hours, subject to compliance verification.** Cashfree's fast onboarding process allows businesses to quickly start using its **Payment Gateway** and online payment solutions.

    For more details, refer to the [account activation guide](/docs/help/account/account-activation).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Why am I being asked to do Video KYC? I didn't have to do this before.">
    Video KYC is triggered by Enhanced Due Diligence (EDD):

    * **The Reason**: We run backend address verification checks on the address fetched from your documents (Aadhaar, PAN, GST).
    * **The Trigger**: If the backend address verification fails, the system mandates Video KYC to be compliant.
    * **Response**: To ensure the security of your account and comply with new RBI guidelines, we require additional verification. Since we couldn't automatically verify your address, Video KYC is now a mandatory step to proceed.

    **Note**: Video KYC is not required if Enhanced Due Diligence (EDD) is successful.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I skip Video KYC if it appears?">
    No. If the system flags you for mandatory Video KYC (due to failed backend checks), you cannot submit the KYC form until it is completed. The "Submit" button will remain disabled or hidden until VKYC is successful.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="I don't see any Address Verification step. Is something broken?">
    No, this is intentional. The address verification happens silently in the backend:

    * **If successful**: You will see nothing and proceed smoothly.
    * **If failed**: You will be presented with the Video KYC step. You are not explicitly told "Address Verification Failed", just that Video KYC is required.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What happens if my Video KYC is rejected?">
    If your Video KYC is rejected:

    1. Your Min-KYC status will move to Rejected.
    2. You will receive a rejection email (similar to document rejection emails).
    3. You can log in to your dashboard and generate a new link to retry Video KYC.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I schedule Video KYC for later?">
    Yes. If the wait time is long, you can choose the "Schedule for Later" option and pick a time slot that works for you.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What is the Beneficial Owner step, and who needs to do it?">
    This is a new mandatory step for Non-Individual and Proprietorship merchants (Pvt Ltd, Public Ltd, LLP, Partnership, Trust):

    * **Requirement**: You must identify all individuals who own more than 10% share in the business.
    * **Process**:
      * **Pvt/Public Ltd**: We pre-fill a list of Directors fetched from the Company PAN. You must confirm if these are the Beneficial Owners or add new ones.
      * **Partnerships/Trusts**: You must manually enter the list of partners or trustees.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="I selected the wrong Beneficial Owners and confirmed. Can I edit the list?">
    No. Once you confirm the list of Beneficial Owners on the screen, it is locked.

    If you made a mistake, contact your Account Manager to raise a request to the Operations Team to reset or reject the step so you can fill it again.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Who needs to verify their KYC in the Beneficial Owner step?">
    * At least one Beneficial Owner (BO) must complete Aadhaar OTP and PAN verification.
    * If the "Authorised Signatory" (who did KYC earlier in the flow) is also a BO, that counts.
    * If the Authorised Signatory is not a BO (e.g., an employee), you must add a BO and complete verification for that BO.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Why is the approval taking so long for Private/Public Limited companies?">
    In the new flow, we are fetching MCA Documents (MOA, AOA, COI) automatically in the backend:

    * **Delay**: This fetch can take up to 24 hours.
    * **Impact**: Your account cannot be approved until these documents are successfully fetched.

    Please wait for 1 business day for the process to complete.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Why are we asking for two registration documents for Proprietorships?">
    Yes, this is correct. Under the new policy (Paragraph 28 of RBI KYC Master Direction), Proprietorships require two documents to prove their legal existence:

    * **Scenario A**: If we successfully auto-fetch both GST and Udyam, you do not need to upload anything.
    * **Scenario B**: If we only fetch one (e.g., only Udyam), you must upload a second document (e.g., GST certificate, Shop and Establishment Act, etc.).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What Website Policy checks are we doing now?">
    We have simplified the checks from 6 down to 2 mandatory checks:

    1. **Legal Name**: The registered legal name must be visible on your website (usually in the footer or Contact Us page).
    2. **Products/Services and MCC**: The products listed must match the business category selected and must not be high-risk or banned items (negative keywords).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Do I need a Refund Policy page to be approved?">
    While it is good practice, a Refund Policy page is no longer a hard blocker for the initial KYC approval in the new simplified flow (only Legal Name and Product checks are mandatory for the automated crawl).

    **Note**: Your banking partners may still require it for specific terminal procurement later.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="My account is active, but settlements are on hold. What should I do?">
    Once your account is activated, settlements are processed according to your agreed cycle. However, settlements may be put on hold due to a few common reasons:

    * **Penny Test not confirmed**: A small amount (₹1) is sent to your bank account to verify it is correct. You will receive an email titled "Bank account confirmation" or "Penny test confirmation". Please reply to that email once you receive the amount.
    * **Missing Website/App Policy Pages**: Ensure that your website or app includes all the required policy pages, such as Privacy Policy, Refund Policy, Terms and Conditions, etc.
    * **Pending Documents**: Double-check that you have submitted all the necessary documents. In some cases, additional documents may be requested. Your Account Manager will reach out if anything is missing.

    If you have already taken care of all the above and your settlements are still on hold, please contact your Account Manager directly for the quickest resolution.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I add my team members to my Cashfree account?">
    Yes, absolutely! When you create a Cashfree account, you become the account owner by default.

    You can then:

    * Add multiple team members to the same account
    * Assign roles to each user (like Finance, Tech, Support, etc.)
    * Control what each user can access or do based on their role
    * Customise permissions further if needed

    There is no limit to how many users you can add.

    Want the full details? Check out our guide on [multi-user management](https://www.cashfree.com/blog/cashfree-user-management-manual/) to know more.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How long can I access features in test mode? Is there a trial period?">
    There is no time limit on test mode—you can use it for as long as you want to try out the features.

    However, to start accepting real payments or sending money, you will need to activate your account by submitting the required [documents](/docs/help/account/account-activation#required-documents).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How do I update my registered email ID or phone number?">
    You can update your email ID and phone number from the **Profile** section in the dashboard:

    1. Go to **Profile** > **My Information**.
    2. Select the **Edit** icon next to the email or phone number.
    3. You will need to validate your identity using your **Aadhaar number** and the OTP sent to your Aadhaar-linked mobile number.
    4. Once verified, enter your new details and verify them with the OTP sent to the new email or phone.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How do I enable Two-Factor Authentication (2FA)?">
    Two-Factor Authentication (2FA) adds an extra layer of security to your account:

    1. Go to **Profile** > **2FA Authentication**.
    2. Toggle **Enable 2FA for Login**.
    3. You can choose to receive OTPs via SMS or email, or use an authenticator app like Google Authenticator.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Where can I download my monthly invoices?">
    You can view and download your monthly invoices from the **Profile** section:

    1. Go to **Profile**.
    2. Navigate to the **Invoice** section.
    3. You will see a list of generated invoices which you can download for your records.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How can I check the login history of my account?">
    To monitor access to your account:

    1. Go to **Profile** > **Login History**.
    2. You can view successful logins, filter by date range, or search by specific email IDs to track user activity.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Are there any specific businesses that are not supported by Cashfree?">
    As a business policy, Cashfree does not support businesses that deal in certain prohibited items. If your business deals in any such items, your Cashfree Payment Gateway account will not be activated.

    ### Prohibited items and services

    1. Adult goods and services, which include pornography and other sexually suggestive materials (including literature, imagery and other media), escort or prostitution services.
    2. Alcohol, which includes alcoholic beverages such as beer, liquor, wine, or champagne.
    3. Body parts, which include organs or other body parts.
    4. Bulk marketing tools, which include email lists, software, or other products enabling unsolicited email messages (spam).
    5. Cable descramblers and black boxes, which include devices intended to obtain cable and satellite signals for free.
    6. Child pornography, which includes pornographic materials involving minors.
    7. Copyright-unlocking devices, which include Mod chips or other devices designed to circumvent copyright protection.
    8. Copyrighted media, which includes unauthorised copies of books, music, movies, and other licensed or protected materials.
    9. Copyrighted software, which includes unauthorised copies of software, video games and other licensed or protected materials, including OEM or bundled software.
    10. Counterfeit and unauthorised goods, which include replicas or imitations of designer goods, items without a celebrity endorsement that would normally require such an association, fake autographs, counterfeit stamps, and other potentially unauthorised goods.
    11. Cryptocurrency exchanges, platforms dealing in cryptocurrency trading.
    12. Drugs and drug paraphernalia, which include illegal drugs and drug accessories, including herbal drugs like salvia and magic mushrooms.
    13. Drug test circumvention aids, which include drug cleansing shakes, urine test additives, and related items.
    14. Endangered species, which include plants, animals or other organisms (including product derivatives) in danger of extinction.
    15. Gaming or gambling, which includes lottery tickets, sports bets, memberships or enrolment in online gambling sites, and related content.
    16. Government IDs or documents, which include fake IDs, passports, diplomas, and noble titles.
    17. Hacking and cracking materials, which include manuals, how-to guides, information, or equipment enabling illegal access to software, servers, or other protected property.
    18. Illegal goods, which include materials, products, or information promoting illegal goods or enabling illegal acts.
    19. Miracle cures, which include unsubstantiated cures, remedies or other items marketed as quick health fixes.
    20. Offensive goods, which include literature, products or other materials that: (a) defame or slander any person or groups of people based on race, ethnicity, national origin, religion, sex, or other factors, (b) encourage or incite violent acts, (c) promote intolerance or hatred.
    21. Offensive goods and crime, which include crime scene photos or items, such as personal belongings, associated with criminals.
    22. Prescription drugs or herbal drugs, which include drugs or other products requiring a prescription by a licensed medical practitioner.
    23. Pyrotechnic devices and hazardous materials, which include fireworks and related goods, toxic, flammable, and radioactive materials and substances.
    24. Regulated goods, which include air bags, batteries containing mercury, Freon or similar substances or refrigerants, chemical or industrial solvents, government uniforms, car titles or logos, licence plates, police badges and law enforcement equipment, lock-picking devices, pesticides, postage meters, recalled items, slot machines, surveillance equipment, and goods regulated by government or other agency specifications.
    25. Securities, which include stocks, bonds, or related financial products.
    26. Tobacco and cigarettes, which include cigarettes, cigars, chewing tobacco, and related products.
    27. Traffic devices, which include radar detectors or jammers, licence plate covers, traffic signal changers, and related products.
    28. Weapons, which include firearms, ammunition, knives, brass knuckles, gun parts, and other armaments.
    29. Wholesale currency, which includes discounted currencies or currency exchanges.
    30. Live animals or hides, skins, teeth, nails and other parts, etc. of animals.
    31. Multi-level marketing collection fees.
    32. Ponzi schemes, pyramid and chain marketing.
    33. Matrix sites or sites using a matrix scheme approach.
    34. Drop-shipped merchandise.
    35. Any product or service which is not in compliance with all applicable laws and regulations, whether federal, state, local or international, including the laws of India.
    36. The merchant shall not sell, purchase, provide or exchange a cardholder's name or MasterCard/Visa account number information in any form obtained because of a MasterCard/Visa Card transaction to any third party other than its MasterCard/Visa acquiring Member-Citrus Pay, or according to a government or statutory or competent body's request.
    37. Pyrotechnic devices, combustibles, corrosives and hazardous materials, which include explosives, fireworks and related goods, toxic, flammable, and radioactive materials and substances.

    <Warning>
      If Cashfree activates your Payment Gateway and later finds that your business does not comply with these terms and conditions, Cashfree may deactivate your account at its discretion.
    </Warning>

    <iframe title="FAQs feedback component" />
  </Accordion>
</AccordionGroup>


# Manage Account
Source: https://www.cashfree.com/docs/help/account/manage-account

Manage Cashfree account settings from the Profile page: update business info, enable 2FA, set notification preferences, and review logins.

You can manage your account information and control overall activities in the **Profile** page. This includes basic account settings, two-factor authentication configuration, login history monitoring, and tax invoice viewing.

This page covers the following topics:

* [Manage profile information](#manage-profile-information)
* [Configure 2FA authentication](#configure-2fa-authentication)
* [Manage communications](#manage-communications)
* [View login history](#view-login-history)
* [View invoices](#view-invoices)

## Manage profile information

The **My Information** section displays the following details under **Personal Profile**:

* **Name**: The registered name of your Cashfree account.
* **Email ID**: The registered email address of your Cashfree account.
* **Phone Number**: The registered phone number of your Cashfree account.
* **Customer Support Email**: Your customer support email address.
* **Account Password**: Select **Update Password** to change your account password.

<img alt="My Information section in the Merchant Dashboard" />

### Update profile information

You can edit your details such as email ID, phone number, and customer support email ID using the features available on the dashboard. The **Edit** icon next to each field allows you to update the information after successful OTP authentication.

To update your profile information:

1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
2. Navigate to **Profile > My Information**.

<Note>
  Why Aadhaar validation?

  To confirm your identity and prevent fraudulent activities, you must complete Aadhaar validation to update your contact information.
</Note>

<AccordionGroup>
  <Accordion title="Update email ID">
    1. Select the **Edit** icon next to the email ID field.
    2. In the **Edit Email** popup, enter your Aadhaar number and select **Verify**.

    <Warning>
      Correct Aadhaar number

      Ensure you use the Aadhaar number that was used during the KYC process of your Cashfree account.
    </Warning>

    3. In the **Enter OTP** popup, enter the OTP received on your Aadhaar-registered mobile number and select **Confirm**.
    4. Enter the new email address in the **Email ID** field and select **Verify Changes**.
    5. Enter the OTP sent to your new email address in the **Verify Email** popup and select **Confirm**.

    Cashfree reviews the request and updates the email ID for your account within 24-48 hours. The system logs you out after email verification. Use your updated email address and the existing password to log in.
  </Accordion>

  <Accordion title="Update phone number">
    1. Select the **Edit** icon next to the phone number field.
    2. In the **Edit Phone Number** popup, enter your Aadhaar number and select **Verify**.
    3. In the **Enter OTP** popup, enter the OTP received on your Aadhaar-registered mobile number and select **Confirm**.
    4. Enter the new phone number in the **Enter New Phone Number** field and select **Verify Phone**.
    5. Enter the OTP sent to your new phone number in the **Verify Phone Number** popup and select **Confirm**.

    Cashfree reviews the request and updates the phone number for your account within 24-48 hours.

    <Note>
      Validation process

      You only need to complete the Aadhaar validation process once when updating both email and phone number information.
    </Note>
  </Accordion>

  <Accordion title="Update customer support email ID">
    1. Select the **Edit** icon next to the customer support email ID field.
    2. Enter the OTP sent to your registered phone number or email address in the **Authenticate** popup and select **Confirm**.
    3. Enter the new customer support email ID in the **Customer Support Email ID** field and select **Verify Changes**.

    The customer support email ID is updated for your account.
  </Accordion>
</AccordionGroup>

## Configure 2FA authentication

Two-factor authentication (2FA) is a method to confirm secure login to your Cashfree account and authenticate specific operations. It combines two different factors: sign-in password and OTP to confirm user identity.

By default, you receive an OTP to your registered phone number via SMS. You can configure it to receive the OTP on your email as well. Once the OTP is validated, the session is valid for 15 minutes.

To add another layer of security to the login sequence for your Cashfree account:

1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
2. Navigate to **Profile > 2FA Authentication**.
3. Switch the toggle **Enable 2FA for Login** to enable two-factor authentication for every login attempt for you and your team members.

This added layer of security reduces fraud and keeps your account secure.

<img alt="2FA Authentication settings" />

<Note>
  **Use Google Authenticator**

  If you don't want to use OTP-based authentication, select **Use this Method Instead** to configure your account authentication via the Google Authenticator app.
</Note>

## Manage communications

The **Communications** section allows you to manage the notification preferences for various events.

To create or edit notification preferences:

1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
2. Navigate to **Profile > Communications**.
3. Select **Manage Notifications** and then select **Email Notifications**.
4. Enter the email address to set notification preferences and select **Next**.
5. Select which notifications to deliver to the entered email.
6. Select **Submit** to save the preference.

<img alt="Create notification preferences" />

When an email is configured to receive notifications for a particular event (for example, API Updates), a confirmation email is sent to the recipient's email address. The recipient can select the **Confirm** button to provide their consent. Once consent is provided, the recipient will start receiving notifications about those particular events.

### Check recipient's consent status

To check whether a recipient has provided their consent to receive notifications:

1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
2. Navigate to **Profile > Communications**.
3. Select any category card.
4. Hover over any email to see the consent status.

## View login history

The **Login History** section displays information about successful logins by users added to your Cashfree account.

To search and filter login history:

1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
2. Navigate to **Profile > Login History**.
3. Use the following filters to search for specific login history:
   * **All Time**: Use this dropdown menu to set the date range.
   * **Search and Filter**: Use this dropdown menu to set the search filter.
     * **Search**: Use this dropdown menu to determine the search value and enter the value in the field. For example, if you choose **Email ID**, enter the specific email ID in the field.
4. Select **Apply**.

The results display in a grid format.

<img alt="Login History section" />

## View invoices

The monthly invoices generated for your Cashfree account are available in the **Invoice** section. You can download the invoices for your records.

To view and download invoices:

1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
2. Navigate to **Profile > [Invoice](https://merchant.cashfree.com/common/profile/invoice)**.
3. Select the download icon next to the invoice you want to download.

<img alt="Invoice section" />

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/help/account/overview">Account Overview</a></li>
    <li><a href="/docs/help/account/account-management">Account Management FAQs</a></li>
  </ul>
</div>


# Account Overview
Source: https://www.cashfree.com/docs/help/account/overview

Set up, activate, and manage your Cashfree account, covering onboarding, KYC verification, team access, and account operations.

Merchants can create a Cashfree account to process payments, send payouts, and verify customers or bank accounts. This page covers sign-up and activation, managing account details, managing team members and role-based permissions, and related operations.

When setup is complete, the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) can be used to perform a wide range of functions according to business needs.

<div>
  <iframe title="Account creation process" />
</div>

## Set up and manage your account

The account setup process is streamlined into clear actions. Follow these guides to activate your account and configure your business profile.

<CardGroup>
  <Card title="Create an account" href="/docs/help/account/account-activation" icon="clipboard-check">
    Step-by-step guidance on sign-up, KYC verification, entity-wise checklists, and tracking your activation status.
  </Card>

  <Card title="View required documents" href="/docs/help/account/account-activation#required-documents" icon="file-lines">
    See which documents you need for activation by entity type and line of business.
  </Card>

  <Card title="Manage your account" href="/docs/help/account/account-management" icon="user-gear">
    Update business profile, banking details, and settlement preferences.
  </Card>

  <Card title="Manage team access" href="/docs/help/account/access-management" icon="users">
    Invite team members and assign role-based permissions to secure your account.
  </Card>
</CardGroup>

## Support and resources

Use these resources to understand pricing, account onboarding, and answers to common questions, or review legal agreements.

* [Account help](/docs/help/account/faq): Find answers to frequently asked questions about your profile, two-factor authentication, notifications, and day-to-day account operations.
* [Onboarding and activation](/docs/help/onboarding-related/onboarding-faqs): Common questions about sign-up, account activation, and which documents you need by entity type and business category.
* [Pricing and fees](/docs/help/account/pricing): Clear information on transaction fees, settlement rates, and pricing for different payment methods.
* [Terms and policies](/docs/help/account/termsandcondition): Review the terms of service, legal requirements, and privacy policies for using Cashfree.

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/help/account/account-activation">Account Activation</a></li>
    <li><a href="/docs/help/onboarding-related/onboarding-faqs">Onboarding FAQs</a></li>
    <li><a href="/docs/help/account/faq">Account FAQs</a></li>
    <li><a href="/docs/payments/online/resources/sandbox-environment">Sandbox environment</a></li>
    <li><a href="https://merchant.cashfree.com/merchants/signup">Cashfree sign up</a></li>
  </ul>
</div>


# Pricing
Source: https://www.cashfree.com/docs/help/account/pricing

Find answers to Cashfree pricing questions covering TDR, TDS, Form 16A, billing, invoices, gateway charges, UPI fees, and integration costs.

Answers to common questions on Cashfree pricing, including transaction and tax charges (TDR, TDS, Form 16A), billing and invoices, gateway and UPI charges, and setup or integration costs.

<Note>
  The transaction charges in this topic are accurate as of 10 August 2026. Cashfree's festive offer gives new merchants who sign up on or after 21 July 2026 a 0% platform fee on domestic payment gateway transactions, up to a cumulative Gross Merchandise Value (GMV) of ₹20,00,000. The offer runs through 31 March 2027, or ends earlier once you reach the GMV cap. Charges can change without prior notice, so check the [Cashfree payment gateway charges](https://www.cashfree.com/payment-gateway-charges/) page for the most current rates.
</Note>

<AccordionGroup>
  <Accordion title="What is TDR?">
    Transaction Discount Rate (TDR) is the fee that you pay for every transaction processed using a payment gateway. The rates may differ based on the payment mode used by the customer.

    For example, when a customer pays via net banking, the TDR will be low, while for international credit card payments the TDR will be higher. We discussed in details, what is TDR and how it is split.
    [Read here](https://www.cashfree.com/payment-gateway-charges/).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What is TDS?">
    TDS (Tax Deducted at Source) is a tax collected by the Government of India at the time income is generated, rather than at a later date. It applies to payments such as commissions, professional fees, interest, and rent.

    In the context of Cashfree, TDS may be applicable on the payouts or commissions paid to merchants. The deducted amount is deposited with the government, and a TDS certificate (Form 16A) is issued to the merchant as proof of the deduction.

    You can use this certificate to claim credit while filing your income tax returns.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How do I submit a TDS claim?">
    To submit a TDS claim, follow these steps:

    1. Submit this [support form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) using your Cashfree registered email address.
    2. Attach the following documents:
       <ul>
         <li>A digitally signed Form 16A</li>
         <li>A cancelled cheque for the bank account where the refund should be credited</li>
       </ul>
    3. Cashfree Care will create a support ticket and share the estimated turnaround time (TAT).
    4. After processing, Cashfree Care will update the ticket with the UTR (Unique Transaction Reference) and the credited amount.
    5. If the details are correct, no further action is required.
    6. If you notice a discrepancy, reply to the same ticket. Cashfree Care will coordinate with the Finance team to resolve the issue.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What is Form 16A?">
    Form 16A is a TDS certificate issued for tax deducted on non-salary payments such as commissions, interest, rent, and professional fees. It contains details of the amount paid, the tax deducted at source (TDS), and the TDS payment deposited with the government.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Do you provide billing Invoices for transactions and services used?">
    Cashfree raises an invoice for all processed transactions. The invoice appears on your Cashfree [Merchant Dashboard](https://merchant.cashfree.com/auth/login) on or after the 5th of the following month. You receive a notification of the invoice generation on your registered email address.

    <Note>
      If your account has availed Free Trial credits for the billing period and you don't have any charges or deductions, or if your account is on the surcharge model, an invoice will not be raised for you, since you have not been directly charged for the transactions.
    </Note>

    Please follow the below steps to download the invoice:

    1. `Login` to your [Cashfree account](https://merchant.cashfree.com/common/profile/invoice).

    2. On the Home page, select the Profile icon in the top-right corner, then select **Profile** from the menu.

    3. On the Profile page, select **Invoices**, select the month-year combination from the dropdown, and select **Download**.

    4. A new tab will open where your generated invoice(s) will be shown and you can download them
       Cashfree India Private Limited comes under the purview of e-Invoicing under GST, and it is mandatory for us to capture all required details of the merchants correctly to generate e-Invoices. Please check the invoice to ensure that your tax details are correct.

    If you want to claim Input Tax Credits, we request you to send your latest GST registration details and the GST certificate at the earliest. Please ignore this if you have already registered your information with Cashfree and details are present on the generated invoice.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What charges do I need to pay for using Cashfree products?">
    You can check out all Cashfree products and their pricing
    [Cashfree's payment gateway charges](https://www.cashfree.com/payment-gateway-charges/). You can also talk
    to our payments expert directly and know more about the product and pricing by
    submitting this [form](https://www.cashfree.com/contact-sales).

    Cashfree doesn't charge a setup fee or an Annual Maintenance Charge (AMC). Payment Links, Payment Forms, and softPOS are included at no additional cost beyond the standard transaction charges for the payment mode used.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are the transaction charges for each payment mode?">
    Cashfree charges a Transaction Discount Rate (TDR) that varies by payment mode. The following table shows the standard rate and the current festive offer rate.

    | Payment mode | Standard rate | Festive offer rate\* |
    | :- | :- | :- |
    | UPI (Intent, Collect, Credit Line, PPI) | 1.95% | 0% |
    | UPI (RuPay Credit Card) | 2.15% | 0% |
    | Domestic credit and debit cards (Visa, Mastercard, RuPay, Maestro) | 1.95% | 0% |
    | Net banking | 1.95% | 0% |
    | Digital wallets | 1.95% | 0% |
    | Prepaid cards | 1.95% | Not applicable |

    \*The festive offer rate applies only to new merchants who sign up on or after 21 July 2026, up to a cumulative domestic transaction volume of ₹20,00,000. Prepaid cards and other excluded payment methods are always charged the standard rate. See "What are the eligibility conditions for the festive 0% offer?" in this topic for the full conditions.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are the charges for EMI and Pay Later payments?">
    Cashfree supports Credit Card EMI, Debit Card EMI, Cardless EMI, and Pay Later at checkout, each with its own charge structure.

    | Payment option | Charge |
    | :- | :- |
    | Credit Card EMI | Starting at 1.90% platform fee, plus 0.25% |
    | Debit Card EMI (HDFC Bank) | 1.50% platform fee |
    | Cardless EMI | 1.90% platform fee |
    | Pay Later | 2.20% |

    Credit Card EMI and Debit Card EMI are supported with ICICI Bank, AU Small Finance Bank, Axis Bank, Bank of Baroda, RBL Bank, Standard Chartered Bank, YES Bank, HSBC, American Express, and HDFC Bank. Cardless EMI is supported through CASHe, HDFC Bank, ICICI Bank, IDFC FIRST Bank, TVS Credit, LazyPay, HDB Financial Services, Snapmint, and Simpl Pay. Pay Later is supported through LazyPay and Simpl.

    These charges apply regardless of the festive 0% offer. EMI and Pay Later payments are excluded from that offer and are always charged at the standard rate.

    For integration details, see [Paylater and Cardless EMIs](/docs/payments/manage/payment-methods/paylaters-and-cardless-emis) and [No Cost EMIs](/docs/payments/checkout/offers/no-cost-emi).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are the charges for international card payments?">
    Cashfree charges the following rates for international card payments, in addition to any applicable Goods and Services Tax (GST).

    | Card network | Standard rate |
    | :- | :- |
    | Visa and Mastercard | 2.99% |
    | American Express | 2.95% |

    The festive 0% offer doesn't apply to international card payments processed through the International Payment Gateway (IPG). These transactions are always charged at the standard rate.

    PayPal transactions are charged at standard payment gateway rates. Cashfree also applies a foreign exchange conversion charge on transactions settled in a currency other than Indian Rupees (INR).

    For more information on accepting international payments, see the [International Payment Gateway overview](/docs/payments/international-payments/ipg/overview).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Are there charges for Virtual Bank Accounts?">
    Yes. Virtual Bank Accounts used to collect payments through IMPS, NEFT, or RTGS are charged a flat fee starting at ₹20 per transaction.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are the eligibility conditions for the festive 0% offer?">
    Cashfree's festive offer gives eligible new merchants a 0% platform fee on domestic payment gateway transactions, up to a cumulative Gross Merchandise Value (GMV) of ₹20,00,000. The offer is subject to the following conditions.

    * Applies only to new merchants who sign up for a Cashfree account on or after 21 July 2026, 12:00 PM IST. Merchants who processed any transaction with Cashfree before that date aren't eligible.
    * Is applied automatically once your Know Your Customer (KYC) verification is approved and your account is activated. You don't need a promo code or a first transaction to trigger it.
    * Covers domestic payment gateway transactions up to a cumulative GMV of ₹20,00,000. This is a one-time cap, not a recurring monthly allowance.
    * Ends when any of the following happens first: you use the full ₹20,00,000 GMV, the festive campaign ends on 31 March 2027, or you're disqualified under the fair usage conditions below. After the offer ends, the standard rate of 1.95% plus applicable taxes applies automatically.
    * Doesn't apply to the following payment methods, which are always charged the standard rate: American Express cards, Diners Club cards, corporate credit cards, EMI (credit card, debit card, and cardless), prepaid cards, Pay Later, subscriptions (e-mandate), international card payments through the International Payment Gateway (IPG), and any payment method with a standard Merchant Discount Rate (MDR) of 3% or higher.
    * Doesn't waive Goods and Services Tax (GST). GST is charged at 18% (or the prevailing rate) and calculated on the standard 1.95% rate, even on transactions where the platform fee itself is waived.
    * Is subject to fair usage: after you complete 5 or more transactions and cross a cumulative GMV of ₹5,00,000, Cashfree reviews the share of your GMV from credit card transactions. If credit card transactions account for 60% or more of your total GMV, Cashfree may withdraw the offer with immediate effect.
    * Is limited to one offer per Permanent Account Number (PAN) or bank account. If you register multiple Merchant IDs (MIDs) under the same PAN or bank account, only the first activated MID is eligible.
    * Isn't available to merchants referred through partners or resellers.
    * Isn't available to merchants in the following Merchant Category Code (MCC) categories: local and suburban passenger transportation, elementary and secondary schools, correspondence schools, and business and secretarial schools.
    * Includes a dedicated account manager and T+1 settlement by 8:00 PM IST as the default settlement cycle during the campaign, for GST-registered businesses.
    * Can be modified, suspended, withdrawn, or discontinued by Cashfree at any time, with prior notice to your registered email address.

    For the complete offer terms, see the [Cashfree payment gateway charges](https://www.cashfree.com/payment-gateway-charges/) page and the [Cashfree Terms of Use](https://www.cashfree.com/tnc/).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Does Cashfree offer enterprise or custom pricing?">
    Yes. Cashfree offers custom pricing for enterprise merchants based on transaction volume, industry, and the products you use. Enterprise pricing can include early access to new features, a dedicated account manager, discounted rates, and support over WhatsApp.

    Merchants with a dedicated account manager also get fortnightly account check-ins, priority support with a 30-minute response guarantee, and faster dispute resolution.

    To discuss custom pricing for your business, submit this [Contact Sales form](https://www.cashfree.com/contact-sales).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are the charges for Payouts, Cashgram, and Secure ID?">
    Cashfree doesn't publish a standard rate card for Payouts, Cashgram, or Secure ID. Pricing for these products is customised based on your transaction volume, use case, and business category.

    To get pricing for your business, submit this [Contact Sales form](https://www.cashfree.com/contact-sales/).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Do I need to pay any setup or integration cost?">
    Cashfree merchants need not pay any setup fee or integration charges. We offer
    a wide range of powerful REST APIs built to help you automate payments and
    achieve efficiency. We have also developed ready - to use integrations that
    work seamlessly with a range of e-commerce platforms such as Shopify,
    Woocommerce etc. You can check out our developers documents and available
    [payments integration documentation](/docs/payments/overview).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How is the billing done?">
    For all the transactions processed, an invoice is raised and shows up on your [Cashfree Merchant Dashboard](https://merchant.cashfree.com/common/profile/invoice) on the 5th of the next month, i.e for the services rendered for the period 1st Jan to 31st Jan, Cashfree raises the invoice by 5th of Feb. The invoice will have the total value of the transactions processed and respective [Transaction Discount Rate(TDR)](/docs/help/account/pricing#what-is-tdr) + GST as applicable.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Where can I find the pricing details for gateway charges?">
    You can find comprehensive pricing information for all Cashfree payment gateway charges on our dedicated [pricing page](https://www.cashfree.com/payment-gateway-charges/). This page details the transaction discount rates (TDR) for different payment modes and helps you understand the cost structure for processing payments through our gateway.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Is the MDR or TDR displayed at checkout?">
    No, the Merchant Discount Rate (MDR) or Transaction Discount Rate (TDR) is not displayed to the merchant on the checkout page. However, you can view the charges applied to your transactions on your monthly invoice. The invoice will show the processing fees or charges deducted for each transaction, allowing you to calculate and verify the TDR applied to your payments.

    <iframe title="FAQs feedback component" />
  </Accordion>
</AccordionGroup>


# Terms and Conditions
Source: https://www.cashfree.com/docs/help/account/termsandcondition

Review the terms and conditions for Cashfree offers and promotions, plus links to the official terms of service, privacy policy, and grievance policy.

Terms and conditions for Cashfree offers and promotions, and how to access Cashfree’s terms of service, privacy policy, and grievance redressal policy.

<AccordionGroup>
  <Accordion title="Terms and Conditions for MobiKwik | Cashfree Offer">
    MobiKwik Offer Details:

    * Your customer can get up to Rs.100 cashback on payment via MobiKwik Wallet
    * Minimum transaction value is Rs.100 to avail the offer
    * User will get cashback from anywhere between Rs.5-100
    * Minimum assured cashback of Rs.5
    * Offer is valid for 1 month
    * User must select MobiKwik Wallet option to complete the transaction
    * Offer valid once per user per month during the campaign
    * No cost is attached to this offer

    General T\&Cs:

    Cashback will be directly credited to your customer's MobiKwik Wallet within 24 hours. If the order is cancelled or undelivered at your end, you, i.e the merchant (not MobiKwik), will initiate a refund.

    In case of partial refunds/cancellations, the refund amount will be adjusted with the cashback received on the initial payment, and full cashback will be rolled back in case of a full refund. After the refund is initiated, the amount will be credited back to the wallet within 7-10 working days.

    <Note>
      All the merchants who have MobiKwik wallet enabled on their checkout page are eligible to be part of this offer. MobiKwik wallet is enabled for all. The offer is already integrated into the checkout page. Merchants/Businesses just need to promote it to the customers on the product catalogue page or on their website.
    </Note>

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How do I get more information on Cashfree or its policies?">
    For further information on Cashfree and its policies, or if you wish to reach out to us, please read our policies here:

    Grievance Policy: [https://www.cashfree.com/grievance-redressal-policy/](https://www.cashfree.com/grievance-redressal-policy/)

    Terms: [https://www.cashfree.com/tnc/](https://www.cashfree.com/tnc/)

    Privacy Policy: [https://www.cashfree.com/privacypolicy/](https://www.cashfree.com/privacypolicy/)

    Grievance Officer: Vaibhav Kaushal

    Address: Cashfree India Pvt Ltd
    RMZ Eco world, Building 7
    10th Floor, Devarabeesanahalli, Marathalli Outer Ring road,
    Bangalore - 560103

    E-Mail: [grievances@cashfree.com](mailto:grievances@cashfree.com)

    NODAL OFFICER: Shaik Mohammed Aftab Alam

    ADDRESS: Cashfree India Pvt Ltd
    RMZ Eco world, Building 7
    10th Floor, Devarabeesanahalli, Marathalli Outer Ring road,
    Bangalore - 560103

    E-MAIL: [dispute@cashfree.com](mailto:dispute@cashfree.com)

    <iframe title="FAQs feedback component" />
  </Accordion>
</AccordionGroup>


# Easy Split
Source: https://www.cashfree.com/docs/help/easy-split/faqs/faqs

Find answers to Easy Split FAQs covering vendor onboarding, split rules, settlement cycles, vendor payout reconciliation, and supported business use cases.

<AccordionGroup>
  <Accordion title="What features does Easy Split provide?">
    Some features our Easy Split provides:

    * Faster settlement to your vendors (T + 2 settlement cycle).
    * Unburden yourself from opening and managing a Nodal account.
    * Route payment from each order to vendors easily.
    * Individual commissions, simplify taxes and much more.
    * Make on-demand adjustments (refunds/bonus) to vendor payouts.
    * Works for non-PG or Cash on delivery orders as well.
    * Access vendor ledger wherever you need using our APIs or our dashboard.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Why should I consider Easy Split?">
    Easy Split automates payment splitting, helping you manage vendors and transactions effortlessly. With Easy Split, you can:

    * Onboard, manage, and pay vendors with ease.
    * Split payments and handle refunds at the order level.
    * Track settlements, refunds, and earnings through detailed reports.

    **Key Benefits:**

    * **Simplify Settlements:** Save your Finance team time with fewer banking tasks.
    * **Streamline Accounting:** Accept only your earnings, making tax computation easier.
    * **Clear Ledger Insights:** Access historical credits, debits, and earnings per order, vendor, or month.

    **Go Global:**

    * Onboard and support international merchants seamlessly.
    * Automate payouts to their home bank accounts with a standard T+2 payment cycle.

    Contact sales to learn [more](https://www.cashfree.com/contact-sales/)

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Handling PG Refunds in Easy Split">
    Refunds are a feature on PG that allows you to return funds back to the payment source. If the PG on your account is linked to Easy Split, then you also need to factor out how vendors will bear the liability for a refund. By default, the balance of respective vendors is debited in the proportion of their commission for the order. For example, let's say there is an order of Rs.100 where Vendor 1 gets Rs. 60 and Vendor 2 gets Rs. 40. This order has a refund of Rs. 50 against it. In such a case, Vendor 1 will receive a debit of Rs. 30 on their balance, and Vendor 2 will have a debit of Rs. 20 against it. This will be adjusted in the next payout to the respective vendors. However, this feature can be turned off in your account if you want to handle the debits against the vendors yourself.

    [Interested in Easy Split? Contact Sales for more information.](https://www.cashfree.com/contact-sales/)

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How many hours do I have to spend every day to manage settlements?">
    Zero! Everything is automated—from receiving payments through Payment Gateway to settling funds in Vendor's bank account. Focus on growing your business while we handle the rest!

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How can we add vendors at the platform for Settlement?">
    Vendors can be added manually from the dashboard. To add a new vendor,

    Go to Payment Gateway Dashboard > Easy Split - Vendor > [Add Vendor](/docs/payments/split/vendor/add).

    Enter the following details:

    Vendor ID - ID of the vendor.
    Phone Number - phone number of your vendor.
    Email ID - Email address of your vendor.
    Vendor Line of Business - Select your vendor’s line of business. Click here to know more.
    Vendor Business Type - Select the business type of your vendor. Click here to know more.
    Settlement Cycle - Select the schedule option through which you want to settle your vendors. Click here to know the available settlement cycles.
    Once done, click Next.
    Mention the Vendor Bank Account Details such as Account Holder Name, Account Number, and IFSC Code or UPI VPA to process payments to the vendor account.

    We also support automated addition through the APIs.

    The documentation for the APIs is available here. [Read more](https://www.cashfree.com/docs/api-reference/payments/latest/easy-split/create-vendor#create-vendor).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are the charges involved for Vendor payouts? Are these debited from the merchant's nodal account?">
    Charges will be communicated by your account manager. It is debited from the merchant's balance in the nodal account.

    **Example:**
    If a settlement of Rs 100 is done, Rs 100 + charges will be debited. Invoice for payout is available on the dashboard separate from payment gateway charges.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are the different possible states a transaction goes through once it’s been added against a Vendor?">
    Only successful transactions get added to a Vendor's balance. The accrued balance gets settled.
    The status can be:

    * **SUCCESS**
    * **FAILURE**
    * **IN PROGRESS**
      Read [more](/docs/payments/split/settlements/failure-reasons)

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How is the invoice presented to the merchant for the charges incurred for the payout?">
    Charges will be communicated by your account manager. It is debited from the merchant's balance in the nodal account.

    **Example:**
    If a settlement of Rs 100 is done, Rs 100 + charges will be debited.

    The invoice for the payout is available on the dashboard, separate from the payment gateway charges.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How many settlements do vendors receive per day?">
    One. Settlement of all the unsettled transactions are grouped together and sent as a single payout. We share the bank reference number for the transfers, that can be shared with the vendors for tracking purposes.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What is the Transfers option under the Vendor menu?">
    A transfer is a settlement to the vendor. The transaction is the payment that
    a customer may have made, which was added to the Settlement account manually
    or via API.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What exactly is Easy Split?">
    Easy Split automates payment splitting between you and your vendors. With Easy Split, you can:

    * Onboard, manage and disburse payments to vendors.
    * Perform splits at order level and manage refunds from vendors smoothly.
    * Track all transactions through detailed reports covering:
      * Settlements
      * Refunds
        See the [Easy Split overview](/docs/payments/split/overview) to know more.

        <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How is vendor settlement managed when there are multiple vendors linked to one transaction?">
    At the time of adding a transaction, you can assign the appropriate numeric
    commission amount against each vendor that you add with Cashfree.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How to add vendors in Easy Split?">
    Go to Payment Gateway Dashboard > Easy Split - Vendor > Add Vendor.

    Enter the following details:

    Vendor ID - ID of the vendor.
    Phone Number - phone number of your vendor.
    Email ID - Email address of your vendor.
    Vendor Line of Business - Select your vendor’s line of business. Click here to know more.
    Vendor Business Type - Select the business type of your vendor. Click here to know more.
    Settlement Cycle - Select the schedule option through which you want to settle your vendors.
    See [available schedule options](/docs/payments/split/vendor/add#available-schedule-options) to know the available settlement cycles.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are the different use cases of Easy Split?">
    Marketplace Aggregators – Split customer payments among vendors, manage commissions, and track transactions in real-time.

    * **EdTech Platforms** – Collect student payments and distribute funds to instructors after deducting charges.
    * **Franchise & Multi-Branch Outlets – Centrally manage payments and route funds to individual branches or stores.**
    * **Investment & Insurance Marketplaces – Settle 100% of the order amount to AMCs or insurers with same-day reconciliation.**
    * **Educational Institutes** – Automate payment splits for tuition, hostel, stationery, and other fees.
    * **On-Demand Services** – Seamlessly split payments for cabs, flights, food delivery, and more.

    See [Easy Split use cases](/docs/payments/split/use-cases) to know more

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are the top features of Easy Split?">
    * Add/Update Vendor: You can add or update your vendor details by providing basic information about the vendor and their account details.
    * Split after payment success: This feature allows to initiation of split after successful confirmation of payment by the customer.
    * Transfer Vendor Balance: You can initiate manual Credit/Debit of a configured vendor-configured settlement account.
    * Refund before split: If the refund is initiated before the vendor split is shared, Cashfree directly refunds the money to the customer payment instrument in the next settlement.
    * Refund after split: If the refund is initiated after the vendor split is shared - The refund will be done from your and vendor’s settlement account according to the respective transaction split created.
    * Deferred Settlement: This API allows you to assign a settlement eligibility date for an order and vendor combination.
      For more information, see [Easy Split features](/docs/payments/split/features).

      <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I edit vendor details once added in Easy Split?">
    While adding vendors, if you have specified incorrect vendor details or missed adding some information, you can modify it using the **Edit Vendor** feature on the product dashboard or use the [Update Merchant Details API](https://www.cashfree.com/docs/api-reference/payments/latest/easy-split/update-vendor-details).

    To edit the details of the vendor you have already added:

    1. Go to **Payment Gateway Dashboard > Easy Split - Vendor**.
    2. Click the ellipsis icon on the vendor you want to make changes to and select **Edit Vendor**.

    **You can update the following details:**
    **Vendor details:**

    * Vendor phone number
    * Vendor email ID
    * Settlement cycle
    * Dashboard access

    **Vendor bank account details:**

    * Account holder name
    * Account number
    * IFSC code
    * UPI VPA
    * Verify account details option

    **KYC details:**

    * Vendor type
    * Business type
    * Documents (Based on the vendor type and business type of your vendors)

    Once done updating the changes, click on the **Update Vendor Details** option to save your changes.

    **Delete Vendor**
    You can delete the added vendors from the dashboard:

    1. Click the ellipsis icon on the vendor you want to delete.
    2. Select **Delete Vendor**.
    3. Click **Delete** in the pop-up window.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I upload multiple vendors at once in Easy Split?">
    **Batch Upload**
    Use the **Batch Upload** feature to add a large number of vendors at a time. Add all the required details in a single file as per the required format and upload the file. Download the sample file to know what details are required to be filled in the batch file.

    **To upload a batch file:**

    1. Go to **Payment Gateway Dashboard > EasySplit - Vendor** and click **Upload File**.
    2. Click **Choose a file** to select the file you want to upload, and then click **Upload**.

    **Key Points:**

    * The maximum file size allowed is **8 MB**, and a maximum of **50 records** can be included in the file.
    * The file must be in the suggested format. If there are errors in the uploaded file, resolve all errors and upload the file again.

    After successful processing, all vendor details will be added, and you can start processing payments to these vendors.

    You can view the vendors that are added successfully from the uploaded files in the **Easy Split - Vendor** screen. An error log (if any) will also get downloaded to view more details.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How does split payments work?">
    To split payments to your vendors using Easy Split, you must first ensure the feature is activated for your Payment Gateway account. Fill out the Support Form or contact your Account manager to enable it for you. The feature should be activated for your Test and Production environment.

    To split payments to vendors;

    Add Vendor
    Create Order
    Accept Payment
    Split Payment
    View Split Settlement Details
    Manage Refunds using Refund Splits
    Manage Adjustments
    See the [Easy Split overview](/docs/api-reference/payments/latest/split/easy-split-overview) to view it graphically

    For more information, see the [Create Order API](/docs/api-reference/payments/latest/orders/create-order) and the [Refund API](/docs/api-reference/payments/latest/refunds/create-refund).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Why do I get 'Transaction already processed, not eligible for split' when splitting after payment?">
    The [Split After Payment](/docs/payments/split/features) feature is not enabled by default. To split a transaction after payment, fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) to enable it and configure the maximum allowable split delay, up to 48 hours after payment. You cannot retroactively split transactions created before you enable the feature.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are the different types of vendor settlements I can choose from?">
    You can define the settlement cycles right when you add the vendor. You can settle your vendors through the following settlement modes:

    * [Vendor Instant Settlement](/docs/payments/split/settlements/instant)
    * [Vendor Standard Settlement](/docs/payments/split/settlements/standard)
    * [Vendor On-Demand Settlement](/docs/payments/split/settlements/on-demand)

    To view the settlements, go to [Payment Gateway Dashboard](https://www.cashfree.com) > Settlements > Vendor. Vendor settlement details such as date and time, settlement type, vendor ID, settlement ID, and settlement status are displayed.

    Generate the settlement recon report for each vendor settlement to view all the transaction details associated with the settlement, including any adjustments/refunds. Provide the file name, choose the file format, and click Generate Report.

    Once you generate the report, you will be automatically redirected to the Reports section.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I delay my settlements to vendors?">
    You can delay vendor settlements by enabling deferred settlements in your account. To do this, ensure the Split API is called within the scheduled interval; otherwise, the full transaction amount will be credited to you.

    Delays can be added at two levels:

    Order Split Delay Post Successful Payment – Delay settlements after a payment is completed.
    Defer Settlement – Hold settlements for a specified period before processing.
    See [delayed settlements overview](/docs/payments/split/settlements/delay/overview) to know more

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are the different reports I have to track vendor payments?">
    The vendor reconciliation report lists all the transactions, adjustments, settlements and refunds that are associated with vendors. This will help you reconcile all transactions from your vendors with their respective settlement ID, time, and UTR.
    Cashfree offers a wide range of reports such as:
    Vendor Recon Report
    Transaction Summary Report
    Refunds Report
    Vendor Split Settlement Report

    To know how to view these reports, see [reconciliation reports](/docs/payments/split/reports/recon)

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How do refunds get handled?">
    Refunded amount gets adjusted during the next settlement cycle. It will be deducted from commission amount of vendors who received settlement on that transaction.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What reports are available to track vendor payments?">
    | Report type | Description |
    | - | - |
    | Vendor Recon Report | Reconcile vendor transactions and payments |
    | Transaction Summary Report | View an overview of all transactions |
    | Refunds Report | Track refund statuses and adjustments |
    | Vendor Split Settlement Report | Monitor vendor settlement details |

    View reports by day, week, or custom date range. Filter, search, and download options are available.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How can I delay settlements to vendors?">
    | Delay type | Description |
    | - | - |
    | Order-Level Delay | Set delay for individual transactions |
    | Vendor-Level Delay | Set delay for specific vendors |

    <Note>
      Enable deferred settlements in your account settings. Ensure the Split API is called within the configured settlement interval.
    </Note>

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What is the maximum period Easy Split can hold funds in deferred settlement?">
    Easy Split supports a deferred settlement period of up to 45 days. You can hold a vendor's settlement amount for up to 45 days from the transaction date. If you take no action within that window, the held amount settles to the merchant. This limit cannot currently be extended. See [Delay vendor settlements](/docs/payments/split/settlements/delay/order-level) to configure a delay within this limit.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are the different types of vendor settlements?">
    | Settlement type | Description |
    | - | - |
    | Instant Settlement | Funds transferred immediately |
    | Standard Settlement | Funds transferred on a scheduled cycle |
    | On-Demand Settlement | Funds transferred manually |

    View settlements at: Payment Gateway Dashboard > Settlements > Vendor.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How can I add multiple vendors at once?">
    Use the **Batch Upload** feature:

    1. Download the sample file
    2. Enter vendor details in the specified format
    3. Upload the completed file

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I edit vendor details after adding them?">
    | Edit method | Access path |
    | - | - |
    | Dashboard | Payment Gateway Dashboard > Easy Split - Vendor > Edit Vendor |
    | API | Use the Update Merchant Details API |

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What is the correct request body field name for updating the vendor settlement eligibility date?">
    When you update a vendor's settlement eligibility date, use `settlementEligibilityDateUpdate` in the JSON request body. Provide the date in the format `YYYY-MM-DD HH:mm:ss`. See the sample request in [Defer Settlement](/docs/payments/split/settlements/delay/vendor-level).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are the key use cases for Easy Split?">
    | Use case | Description |
    | - | - |
    | Marketplace Aggregators | Split payments with multiple product vendors |
    | EdTech Platforms | Share fees with instructors or educators |
    | Franchise & Multi-Branch | Route payments to individual stores or locations |
    | Investment/Insurance Marketplace | Same-day settlement to AMC/insurer accounts |
    | Educational Institutes | Allocate student payments across departments |
    | E-Commerce | Manage sellers within a single order |
    | Online Appointments | Share earnings with service providers |

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are the vendor limits per transaction?">
    You can split a single transaction among a maximum of **5 vendors**.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How are refunds handled?">
    Refund amounts are:

    * Deducted from the merchant’s next settlement
    * Adjusted from vendor commissions if configured
    * Applied only to vendors who received the original settlement

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How can vendors be added to Easy Split?">
    | Method | Description |
    | - | - |
    | Manual | Add vendors from the dashboard |
    | API | Use the Create Vendor API for automation |

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Why is an Easy Split vendor stuck in IN_BENE_CREATION and not becoming ACTIVE?">
    Activation runs asynchronously. When you create a vendor with a valid bank account and PAN, the expected timelines are:

    * **Sandbox**: typically within 10 minutes.
    * **Production**: may take longer depending on the processing queue.

    If the vendor remains in `IN_BENE_CREATION` after 24 hours, follow these steps:

    1. Poll the [Get Vendor API](/docs/api-reference/payments/latest/easy-split/get-vendor-all-details) to check the current status.
    2. Fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) with the vendor IDs so Cashfree can investigate.

    See [Add a vendor](/docs/payments/split/vendor/add) for the full vendor status workflow.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How many settlements do vendors receive daily?">
    Vendors receive **one settlement per day**:

    * Includes all unsettled transactions.
    * Bank reference number provided for each payout.
    * Share the reference number with vendors for tracking.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How are refunds handled when the vendor's share is still held as deferred?">
    If you initiate a refund after you create a split but before vendor settlement, use the [Create Refund API](/docs/api-reference/payments/latest/refunds/create-refund) with split details. Easy Split deducts the refund amounts from both the merchant and vendor balances, including the deferred or held share, before it refunds the customer. If the vendor has insufficient balance, adjust the balance first. See [Initiate Refunds](/docs/payments/split/refund/initiate) and [Adjust Vendor Balance](/docs/payments/split/vendor/balance/adjust).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How can I identify which vendor is linked to a specific adjustment if I don't have the vendor ID?">
    Use the Vendor Reconciliation API in time-period mode. Make a `POST` request to `/pg/recon/vendor` with a `start_date` and `end_date` in the filters, without specifying a `merchant_vendor_id`. The API returns a paginated list of reconciliation data for all vendors within that date range. Each record includes a `merchant_vendor_id` field, which you can use to identify the vendor associated with the adjustment by matching the amount, timestamp, or other known details.

    **Endpoint:** `POST https://api.cashfree.com/pg/recon/vendor`

    **Sample request body:**

    ```json theme={"dark"}
    {
      "pagination": {
        "limit": 100,
        "cursor": null
      },
      "filters": {
        "start_date": "2026-08-01T00:00:00Z",
        "end_date": "2026-08-31T23:59:59Z"
      }
    }
    ```

    <Note>
      Records older than 6 months require a date range in the request. The pagination limit must be between 10 and 100 per call.
    </Note>

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What happens to a held vendor share after the 45-day limit?">
    The 45-day period does not reverse the held vendor share to the vendor. You must initiate the split within the applicable window for that amount to settle to the vendor. If you take no action, or if you do not provide split details in the [Create Order API](/docs/api-reference/payments/latest/orders/create-order), the entire order amount settles to the merchant after the applicable period. See [Order Split Delay](/docs/payments/split/settlements/delay/order-level).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How are disputes handled for orders using Easy Split?">
    For disputed transactions, Cashfree withholds the disputed amount from the merchant balance rather than the vendor balance. Vendor settlements continue according to the configured cycle. Cashfree either reverses the withheld amount or processes it to the customer based on the final dispute status. Cashfree does not extend the 45-day window for disputes because it handles them at the merchant balance level. See [Disputes overview](/docs/payments/manage/disputes/overview).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Are there rate limits or volume caps for the Create Vendor API?">
    There is currently no specific limit on the number of vendors you can create with the [Create Vendor API](/docs/api-reference/payments/latest/easy-split/create-vendor).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are the standard PG charges for cards, UPI, and net banking?">
    For current Payment Gateway charges across cards, UPI, and net banking, see [Pricing](/docs/help/account/pricing). Standard rates apply after any promotional campaign limits are reached.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are the additional charges for using Easy Split?">
    Easy Split is an additional feature on top of the Payment Gateway. It carries a charge of 0.2% per split in addition to the standard PG charges.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Where can I find the Easy Split API documentation?">
    The following pages cover the Easy Split integration APIs:

    * [Easy Split overview](/docs/api-reference/payments/latest/split/easy-split-overview)
    * [Create vendor](/docs/api-reference/payments/latest/easy-split/create-vendor)
    * [Upload vendor documents](/docs/api-reference/payments/latest/easy-split/upload-vendor-docs)
    * [Create static split](/docs/api-reference/payments/latest/easy-split/create-static-split-configuration)
    * [Split after payment](/docs/api-reference/payments/latest/easy-split/split-after-payment)
    * [Vendor settlement webhooks](/docs/api-reference/payments/latest/split/webhooks/vendor-settlement-webhooks)
    * [Vendor status change webhooks](/docs/api-reference/payments/latest/split/webhooks/vendor-status-change-webhooks)

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Which APIs should I use to split payments between multiple vendors and process refunds?">
    You can use Easy Split to manage vendor splits. Create vendor splits while creating an order using the [Create Order API](/docs/api-reference/payments/latest/orders/create-order), and the split amount will be settled to the respective vendor based on their configured settlement cycle. Refunds can be processed using the [Refund API](/docs/api-reference/payments/latest/refunds/create-refund).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Does Easy Split support automated payouts to vendors after a successful payment?">
    Yes. Easy Split can split the payment amount among the configured vendors automatically. Pass the split details through the API, and Cashfree splits the amount according to those instructions. See [Easy Split overview](/docs/payments/split/overview).

    <iframe title="FAQs feedback component" />
  </Accordion>
</AccordionGroup>


# Disputes and Chargebacks
Source: https://www.cashfree.com/docs/help/end-customer/disputes-and-chargeback

Find answers to common customer questions about raising disputes and chargebacks for card or UPI payments processed through Cashfree on merchant websites.

<AccordionGroup>
  <Accordion title="How can I report a dispute with a bank?">
    If you want to raise a dispute on a card payment, contact your issuing bank with details of the transaction, including the order ID, UTR number, and payment details. You can get these details from the payment confirmation email that Cashfree sends at the time of a successful payment. You can contact your home branch or any other branch to report the dispute.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How can I open a dispute or chargeback with a seller?">
    You can open a dispute by [reporting it on the Cashfree report issue form](https://www.cashfree.com/en/report-issue/) within 30 days of making the payment.

    A dispute request may be raised where

    * Payment is made but the order is not delivered (we recommend that buyer waits for at least 7 days from the date of payment before raising the dispute request in this case)

    * Order received but varies significantly as compared to what was shown on the seller's website.

    Once Cashfree receives the dispute request, we work with both you and the seller to collect the necessary documents. If you win the dispute, the seller reverses the transaction and you receive your money back.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="I made a purchase but there is an issue. I want to open a dispute with a seller. How can I do it?">
    To open a dispute, you can report the issue within 30 days of payment by filling the form(link). Our team will look into the transaction and work with you and the merchant to mitigate and resolve the issue.

    <Note>
      * In general, in case of a dispute where item is not received, a buyer must wait at least 7 days from the date of payment to escalate a dispute.

      * Where an item has not been received, please do ensure you have given the seller enough time before opening a dispute
    </Note>

    * We recommend that you share all details related to the transaction when you are filling the form. This will help us resolve the issue at the earliest.

      <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What is a chargeback and dispute and difference between them?">
    A dispute is a claim filed by either a cardholder or the issuing bank. There may be multiple stages involved in a dispute until a resolution is received. A chargeback is one stage in the dispute life cycle. If the dispute resolution is not reached during the inquiry stage, a chargeback is initiated by the seller where the seller reverses the transaction and the customer receives her money back.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How do I change my email address?">
    1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).

    <img alt="" />

    2\. Go to the **Profile** section.\
    3\. Select **Edit** next to the email address field.
    <img alt="" />\
    4\. Enter the updated email address and submit the request.\
    5\. Verify the change using the **OTP sent to your Aadhaar-linked mobile number**.

    <img alt="" />

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How do I change my phone number?">
    1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
       <img alt="" />
    2. Go to the **Profile** section.
    3. Select **Edit** next to the phone number field.
       <img alt="" />
    4. Enter the new phone number and submit the request.
    5. Verify the change using the **OTP sent to your Aadhaar-linked mobile number**.
       <img alt="" />

    <iframe title="FAQs feedback component" />
  </Accordion>
</AccordionGroup>


# Fraud Prevention
Source: https://www.cashfree.com/docs/help/end-customer/fraud-prevention

Read fraud prevention FAQs to learn how customers can spot suspicious transactions, protect payment credentials, and stay safe while paying through Cashfree.

<AccordionGroup>
  <Accordion title="How can I identify a fraudulent transaction before making a payment?">
    Before you make a payment:

    * Make sure the website or app uses `https://`.
    * Verify the business provides contact information and refund policies.
    * Review customer feedback on trusted platforms.
    * Don’t proceed if something feels rushed or suspicious.

    <iframe title="FAQ feedback component" />
  </Accordion>

  <Accordion title="How do I check if a merchant is trustworthy?">
    To verify a merchant before making a payment:

    * Look for complete business details on their website.
    * Check reviews on platforms like Google or Trustpilot.
    * Be cautious of high discounts or full advance payment requests.
    * Avoid unsolicited links from social media or messaging apps.

    <iframe title="FAQ feedback component" />
  </Accordion>

  <Accordion title="What are the red flags to watch for before paying?">
    Watch for signs of fraud:

    * Poorly designed websites with broken links or missing contact details.
    * Requests for full payment without an invoice or confirmation.
    * Urgent requests to pay via unknown QR codes or links.

    <iframe title="FAQ feedback component" />
  </Accordion>

  <Accordion title="How do I protect my card and bank information from fraud?">
    To secure your financial information:

    * Don’t share your card number, CVV, OTP, or passwords.
    * Avoid saving card details on untrusted websites or apps.
    * Enable SMS or email alerts for all transactions.
    * Use trusted payment gateways like Cashfree.

    <iframe title="FAQ feedback component" />
  </Accordion>

  <Accordion title="Does Cashfree verify merchants to prevent fraud?">
    Yes. Cashfree verifies merchants through a strict onboarding and compliance process before enabling payment acceptance. However, Cashfree doesn’t manage order fulfilment. Confirm a merchant’s legitimacy before you pay. If you suspect fraud, [report it on the Cashfree report issue form](https://www.cashfree.com/en/report-issue/).

    <iframe title="FAQ feedback component" />
  </Accordion>
</AccordionGroup>


# Order and Delivery
Source: https://www.cashfree.com/docs/help/end-customer/order-and-delivery

Get answers to order and delivery questions, including how to check order status, track shipments, and contact merchants for payments processed via Cashfree.

<AccordionGroup>
  <Accordion title="How do I check the status of my order?">
    When an order is placed and the transaction is successful, Cashfree sends you a payment confirmation email. Cashfree is a payment gateway that helps merchants accept online payments.

    The orders are processed at the merchant's end. To check the status of your order, we suggest that you contact the merchant. If the merchant is not responsive, you can [report it on the Cashfree report issue form](https://www.cashfree.com/en/report-issue/).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="I have cancelled/returned my order and have not received the refund yet. Can you help me?">
    Refunds typically take 5 to 10 working days to be credited, depending on the merchant’s refund policy and payment modes:

    UPI: Up to 5 working days

    Cards: Up to 7 working days

    Net Banking and others: 7 to 10 working days

    Once a refund is initiated, you will receive an email from Cashfree with details such as refund status (‘Refund Initiated’ or ‘Refund Processed’), Order ID, Refund ID, Payment Method, Date of Initiation, Date of Processing, and ARN(Acquirer Reference Number). The ARN, a unique ID from Cashfree’s partner bank, helps track the transaction in the bank statement. If the refund is processed but not credited, contact your bank with the ARN. If you haven’t received a ‘Refund Initiated’ email, contact the merchant. If they are unresponsive, feel free to [report the issue on the Cashfree report issue form](https://www.cashfree.com/en/report-issue/).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="I made payment using Cashfree, but the order is not showing on the seller website/app. How do I view my order?">
    When an order is placed and the transaction is successful, Cashfree sends you a payment confirmation email. Cashfree is a payment gateway that helps merchants accept online payments.

    The orders are processed at the merchant's end. To check the status of your order, we suggest that you contact the merchant.

    If you have not received the payment confirmation, you can [raise a request with us on the Cashfree report issue form](https://www.cashfree.com/en/report-issue/)

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="I did not receive the order confirmation email from the seller. What should I do?">
    The orders are processed at the merchant's end, when an order is placed successfully, the merchant sends order confirmation email.

    If you haven't received the order confirmation email from the merchant, do double-check your promotions, updates folder, or SPAM inbox. If the order confirmation email is not found, we suggest that you contact the merchant. If the merchant is not able to resolve your issue, you can [raise a request with us on the Cashfree report issue form](https://www.cashfree.com/en/report-issue/)

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="I want to track my order, or I am unable to view my order on the seller's website/application. Can you help me?">
    The orders are processed at the merchant's end. Cashfree is a payment gateway that helps merchants accept online payments.

    To know the status of your order, we suggest that you contact the merchant. If the merchant is not responsive, you can [report the issue on the Cashfree report issue form](https://www.cashfree.com/en/report-issue/).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="I want to modify/exchange my order. Can you help me?">
    The orders are processed at the merchant's end. Cashfree is a payment gateway that helps merchants with accepting online payments only.

    To modify or exchange your order, we suggest that you contact the merchant. If the merchant is not responsive, you can [report the issue on the Cashfree report issue form](https://www.cashfree.com/en/report-issue/).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="My order has not been delivered yet. Can you help me?">
    The orders are processed at the merchant's end.

    Cashfree is a payment gateway that helps merchants accept online payments.

    To know the status of your order delivery, we suggest that you contact the merchant.

    If the merchant is not responsive, you can [report the issue on the Cashfree report issue form](https://www.cashfree.com/en/report-issue/).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title=" I paid for a service, but it hasn't been delivered. What should I do?">
    Cashfree is a payment gateway that helps merchants with accepting online payments only.

    To get an update on the service fulfilment, we suggest that you contact the merchant.

    If the merchant is not responsive, you can [report the issue on the Cashfree report issue form](https://www.cashfree.com/en/report-issue/).

    <iframe title="FAQs feedback component" />
  </Accordion>
</AccordionGroup>


# Payment
Source: https://www.cashfree.com/docs/help/end-customer/payment-related

Read payment FAQs to understand failed transactions, debited but failed payments, refund timelines, and what to do when issues arise on Cashfree checkouts.

<AccordionGroup>
  <Accordion title="I made a payment. My account has been debited but the transaction failed. What should I do?">
    If the payment has been deducted from your account but the transaction failed, your account will be auto-credited within 3-5 working days as per bank's timeline.
    We suggest that you wait for at least 5 working days from the payment date and check your bank statement at the end of the 5 days. If you face an issue after 5 working days, you can [report the issue on the Cashfree report issue form](https://www.cashfree.com/en/report-issue/). For fastest resolution, please mention the UTR and the payment date.

    [What is UTR and where will I find it?](/docs/help/end-customer/payment-related#what-is-utr-and-where-can-i-find-it)

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="I made a payment. My account has been debited but the transaction is showing pending. What should I do?">
    In certain cases, when a payment is initiated, the payment transaction may show as pending on the payment platform. Until the payment transaction shows successful, the order will not be placed.

    Bank may take up to 2-3 working days to share the final status update for pending transactions.

    During this time, Cashfree will wait for the update from the bank, if the bank confirms the transaction as successful, the transaction status will change to successful and your amount will be auto-credited to your account within 5-7 working days from the date the bank confirms the status.

    However, if the bank marks the transaction as failed, your amount will be auto-credited to your account within 5-7 working days. We suggest that you check you bank statement after 7 days of date of payment in case of such transactions.

    If you face an issue after 7 working days, you can [report the issue on the Cashfree report issue form](https://www.cashfree.com/en/report-issue/). For fastest resolution, please mention the UTR and the payment date.

    [What is UTR and where will I find it?](/docs/help/end-customer/payment-related#what-is-utr-and-where-can-i-find-it)

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How can I check my order payment status?">
    When an order is placed and the transaction is successful, you will receive a payment confirmation email from Cashfree. Cashfree is a payment gateway that helps merchants with accepting online payments.

    If there is no payment confirmation, this may mean that the transaction failed. If the amount is debited from your account, it should get auto-credited within 3-5 working days.

    If you still have an issue, you can [report the issue on the Cashfree report issue form](https://www.cashfree.com/en/report-issue/). For fastest resolution, please mention the payment date and provide your order ID.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="I have made the payment but did not get any payment confirmation. What should I do?">
    If the payment has been successful you would receive a payment confirmation email from Cashfree. If you do not see the email, do double check your promotions, updates folder, or SPAM inbox.

    If there is no payment confirmation email, this may mean that the transaction failed. If the amount is debited from your account, it should get auto-credited within 3-5 working days.

    If you still have an issue, you can [report the issue on the Cashfree report issue form](https://www.cashfree.com/en/report-issue/). For fastest resolution, please mention the payment date and provide your order ID.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What is UTR and where can I find it?">
    UTR number stands for Unique Transaction Reference number. It is used for
    identifying a particular transaction. You will find UTR number in your bank
    statement. Some payment platforms may show it as Transaction ID or ARN.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="I made a payment but the amount has been deducted twice. What should I do now?">
    If the amount has been debited twice, you can [report your issue on the Cashfree report issue form](https://www.cashfree.com/en/report-issue/). For the fastest resolution please do mention the payment date and Order ID. In the message section on the form, you can add transaction UTRs.

    [What is UTR and where will I find it?](/docs/help/end-customer/payment-related#what-is-utr-and-where-can-i-find-it)

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="I haven't received the OTP to make the payment. What should I do?">
    Cashfree is a payment gateway that helps merchants accept payments using multiple payment mode such as net banking, UPI, wallets etc. If you have initiated a payment using any payment platform (For example Paytm, PhonePe, Net banking etc) and the OTP is not received, we suggest that you reach out to the payment platform or the merchant.

    If the merchant is not responsive, you can [report the issue on the Cashfree report issue form](https://www.cashfree.com/en/report-issue/).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="I made a payment to a Cashfree UPI ID. I can't see it on seller website/app. What should I do?">
    You can [report your issue on the Cashfree report issue form](https://www.cashfree.com/en/report-issue/). For the fastest resolution please do mention the payment date and Order ID. In the message section on the form, you can add transaction UTR.

    [What is UTR and where will I find it?](/docs/help/end-customer/payment-related#what-is-utr-and-where-can-i-find-it)

    <iframe title="FAQs feedback component" />
  </Accordion>
</AccordionGroup>


# Refunds
Source: https://www.cashfree.com/docs/help/end-customer/refunds

Get answers to refund FAQs covering how to check refund status from the Merchant Dashboard, expected processing timelines, and steps for troubleshooting delays.

<AccordionGroup>
  <Accordion title="What is the status of my refund or reversal?">
    Check the status of an initiated refund from the [Merchant Dashboard](https://merchant.cashfree.com/auth/login). Go to **Payment Gateway Dashboard** > **Transactions** > **Refunds** > **Initiated Refunds** and enter the **Order ID**.

    A refund goes through the following states:

    * **PENDING**: The refund is currently being processed. View detailed remarks by navigating to **Payment Gateway Dashboard** > **Transactions** > **Refunds** > **Initiated Refunds** > **Pending**.
    * **SUCCESS**: The refund is successfully processed and approved. The amount may take additional time to reflect in the customer's bank or payment account.
    * **CANCELLED**: The refund is cancelled. A notification is sent to the registered email ID on the [Merchant Dashboard](https://merchant.cashfree.com/merchants).
    * **ON HOLD**: The refund is temporarily on hold due to insufficient funds.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How long does it take to receive a refund?">
    Refunds typically take 5 to 10 working days to be credited, depending on the merchant’s refund policy and payment modes:

    * **UPI**: Up to 5 working days.
    * **Cards**: Up to 7 working days.
    * **Net Banking and others**: 7 to 10 working days.
    * **Reversals**: Typically processed within 5 working days for all payment modes.

    Once a refund is initiated, you will receive an email from Cashfree with the following details:

    * **Refund status**: Refund Initiated or Refund Processed.
    * **Order ID and Refund ID**: Unique identifiers for your transaction.
    * **Payment Method**: Original mode of payment.
    * **Date of initiation and processing**: Timelines for when the request was made and completed.
    * **ARN (Acquirer Reference Number)**: A unique ID from the partner bank to track the refund in your bank statement.

    If the refund is processed but not credited, contact your bank with the **ARN**. If you have not received a **Refund Initiated** email, contact the merchant. If they are unresponsive, [report the issue on the Cashfree report issue form](https://www.cashfree.com/en/report-issue/).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What is an ARN number in refunds?">
    The ARN (Acquirer Reference Number) is a unique ID provided by Cashfree's partner bank. It helps track the refund transaction in your bank statement.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Why is my refund delayed?">
    Refund processing time depends on the payment mode. Common reasons for delays include:

    1. **Clearing and settlement**: Refunds pass through payment networks and banks, where data matching and settlement depends on network efficiency.
    2. **Fraud checks**: Identity verification and risk reviews for flagged transactions can extend timelines.
    3. **Non-business days**: Processing is paused on weekends and public holidays, and resumes during business hours.

    If your refund is not received within 10 working days, [report it on the Cashfree report issue form](https://www.cashfree.com/en/report-issue/) with the payment date and **Order ID**.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="If the status of the refund is on hold due to insufficient balance, then how do I recharge my wallet?">
    To add money to your Refund Wallet:

    1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
    2. Click the **Settings** icon in the upper-right corner.
    3. Under **Payment Gateway**, select **Wallets**.
    4. In the **Refund Wallet** section, select **Add money**. The virtual bank account details linked to your Cashfree Refund Wallet will appear.
    5. Transfer funds to the displayed bank account using NEFT, RTGS, or IMPS.

    Once you recharge, the credits should appear in your Cashfree wallet within 30 minutes. Your refund will then be auto-processed following the usual timeline.

    <img alt="Refund" />

    <iframe title="FAQs feedback component" />
  </Accordion>
</AccordionGroup>


# Report a Fraud
Source: https://www.cashfree.com/docs/help/end-customer/report-fraud

Learn how to identify and report suspicious Cashfree-related charges on your statement, raise complaints with the merchant, and protect yourself from fraud.

<AccordionGroup>
  <Accordion title="I see Cashfree on my statement, I do not remember making any payment to Cashfree directly. I want to know what is this debit for?">
    Cashfree is a payment gateway that helps merchants accept online payments. If you are seeing Cashfree name mentioned on a statement, it would be related to a payment made to a merchant using Cashfree.

    In case of a successful payment you would have got a payment confirmation email that would show the transaction details as well as merchant details. You can use the merchant details and contact the merchant for any transaction related clarification.

    If the merchant is unable to resolve your issue you can [report it on the Cashfree report issue form](https://www.cashfree.com/en/report-issue/). For fastest resolution we recommend that you provide the payment date, Order ID and UTR

    [What is UTR and where to find it?](/docs/help/end-customer/payment-related#what-is-utr-and-where-can-i-find-it)

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="I am trying to reach the merchant but the merchant is not responding. Can you help?">
    Orders are processed at the merchants end, if the merchant is unresponsive you can [report it on the Cashfree report issue form](https://www.cashfree.com/en/report-issue/). For fastest resolution, please do mention the payment date and order ID along with your concern on the message box.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="I did not receive my order even after 10 days. I want to report a fraud case.">
    The orders are processed at the merchant's end. Cashfree is a payment gateway that helps merchants with accepting online payments. To get a status of your order delivery, we suggest that you contact the merchant.

    In case the issue still remains unresolved, you can [report it on the Cashfree report issue form](https://www.cashfree.com/en/report-issue/).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How do I report a suspicious transaction?">
    If you see any suspicious or unauthorised transaction, you can [report your issue on the Cashfree report issue form](https://www.cashfree.com/en/report-issue/). Do mention your UTR and payment date on the form for fastest resolution. We would also suggest that you make sure that the suspicious activity or unauthorised transaction has not been made by a family member using your card without your knowledge, or is related to a prior authorised auto-debit as in case of periodic subscription plans.

    <iframe title="FAQs feedback component" />
  </Accordion>
</AccordionGroup>


# Subscriptions
Source: https://www.cashfree.com/docs/help/end-customer/subscriptions

Find answers about cancelling or modifying NACH mandates, managing recurring payments, and resolving subscription issues for merchants using Cashfree.

<AccordionGroup>
  <Accordion title="How can I cancel or make changes to my NACH mandate?">
    You can cancel, amend, or temporarily suspend your NACH mandate at any time. To make changes, [submit a request on the Cashfree report issue form](https://www.cashfree.com/en/report-issue/). We’ll guide you through the process and ensure your request is handled smoothly.

    <iframe title="FAQs feedback component" />
  </Accordion>
</AccordionGroup>


# FlowWise
Source: https://www.cashfree.com/docs/help/flowwise/general-faqs

Get answers to common questions about Cashfree FlowWise, including supported payment partners, routing rules, settlements, refunds, and onboarding requirements.

<AccordionGroup>
  <Accordion title="What is FlowWise?">
    FlowWise is a Payments Management System built for growing or large businesses to enable smarter, easier, and more efficient use of multiple payment gateways.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What payment gateways does FlowWise support?">
    FlowWise currently supports the following payment gateways:

    * Cashfree
    * Razorpay
    * Paytm
    * PayU
    * Techprocess / Ingenico / Worldline
    * PhonePe
    * Plural (PineLabs)
    * Easebuzz
    * PineLabs
    * Stripe
    * Atom (WIP)
    * PayG
    * Billdesk (WIP)
    * CCAvenue

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are the different payment modes does FlowWise support?">
    * Cards
    * Netbanking
    * UPI
    * Wallets
    * EMI or BNPL providers

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How does FlowWise increase the success rate?">
    FlowWise monitors success rates across payment gateways for all payment modes. Whenever a dip in success rate is seen on one payment gateway, FlowWise automatically routes the transaction through the next preferred payment gateway.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How to process refunds in FlowWise?">
    FlowWise manages back end orchestration effortlessly. You can initiate refunds from Cashfree dashboard without having to integrate with other aggregators.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What is payment gateway distribution?">
    When setting up a payment configuration, you can define the gateway distribution percentage to allocate transaction volume across multiple payment gateways or aggregators, such as PayU, Paytm, and Razorpay.

    For example, you can distribute transactions based on percentage, volume, or specific networks like Visa or Mastercard to a designated payment gateway. You can also set a priority gateway, ensuring that most transactions are routed through it.

    If there is any success rate (SR) fluctuation or downtime in the primary gateway, transactions are automatically redirected to the next preferred gateway based on the assigned priority.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I delete a rule in FlowWise?">
    No, you cannot delete a rule. You can only enable/disable a rule.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are the options based on which we can create rules in FlowWise?">
    You can create rules based on:

    * Order currency
    * Amount
    * Payment mode
    * Card scheme
    * Card country
    * Card bin
    * Issuing bank

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How many rules can I create in FlowWise?">
    There is no limit on the number of rules you can create in FlowWise.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How to enable seamless option on FlowWise?">
    To use FlowWise, the Payment Gateway account you are choosing should have seamless option enabled. To activate seamless option write to your corresponding payment gateway relationship manager asking to enable seamless mode for your account. Mention that you are using Cashfree as the technology company to handle sensitive card data.

    <iframe title="FAQs feedback component" />
  </Accordion>
</AccordionGroup>


# Account Onboarding
Source: https://www.cashfree.com/docs/help/onboarding-related/onboarding-faqs

Find answers on Cashfree onboarding covering business eligibility, prohibited categories, website compliance, KYC documents, and activation timelines.

Find answers to common questions about creating, verifying, and activating your Cashfree account, including eligibility, required documents, and supported products.

<AccordionGroup>
  <Accordion title="Do I need separate accounts for Payment Gateway and Payouts?">
    No, you can use all Cashfree products under a single account. Share your requirements with the payment expert during onboarding, or contact your account manager later to activate additional desired products on your account.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I use Cashfree for a dropshipping business?">
    No, Cashfree does not support dropshipping businesses.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="I have just signed up. What should I do next?">
    After signing up:

    1. Verify your email address.
    2. Update your business details.
    3. Upload the [required documents](/docs/help/account/account-activation#required-documents).

    A payment expert will contact you within 24 working hours of account creation to understand your requirements. Your account is activated within 24–48 working hours after document verification.

    You can use the test environment to familiarise yourself with the dashboard and try out products and features even before going live. If you would like to try out the available integrations, you can use our test API keys.

    <Tip>
      **To get test API credentials:**

      1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
      2. Navigate to **Developers > API Keys**.
      3. Copy the test mode keys (`client_id` and `client_secret`).

      Use these with the sandbox base URL: `https://sandbox.cashfree.com`.
    </Tip>

    <Warning>
      You must activate your account before transacting in production. See [account activation](/docs/help/account/account-activation#create-an-account).
    </Warning>

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Who is a payment expert?">
    A payment expert is a Cashfree representative who calls you within 24 working hours of account creation to understand your initial requirements and assist with the onboarding process. Ensure your contact details are updated so they can reach you.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Which businesses are not supported by Cashfree?">
    Cashfree does not support businesses dealing in prohibited goods or services, including:

    * Adult goods and services, escort or prostitution services.
    * Alcohol, tobacco, and cigarettes.
    * Body parts, organs, or human remains.
    * Bulk marketing tools, such as spam software or email lists.
    * Cable descramblers, black boxes, and copyright unlocking devices.
    * Child pornography and other pornographic materials involving minors.
    * Offensive content, including material that defames or incites violence, hatred, or intolerance against any person or group based on race, ethnicity, religion, or similar factors.
    * Crime-related items, such as crime scene photos or personal belongings associated with criminals.
    * Counterfeit, unauthorised, or copyrighted goods, including media and software.
    * Cryptocurrency exchanges and trading platforms.
    * Drugs, drug paraphernalia, and prescription medication without authorisation.
    * Drug test circumvention aids.
    * Endangered species and live animals or animal parts.
    * Gambling, lottery tickets, and online betting.
    * Government IDs, fake documents, or law enforcement equipment.
    * Hacking and cracking materials, and other illegal goods.
    * Miracle cures and unsubstantiated remedies.
    * Multi-level marketing collection fees, Ponzi schemes, or matrix schemes.
    * Pyrotechnic, hazardous, or radioactive materials.
    * Regulated goods, such as airbags, mercury batteries, refrigerants, industrial solvents, lock-picking devices, postage meters, slot machines, surveillance equipment, recalled items, or government and law enforcement uniforms and badges.
    * Securities, stocks, bonds, and wholesale currency.
    * Traffic devices, such as radar jammers or fake licence plates.
    * Weapons, ammunition, and armaments.
    * Dropshipped merchandise.
    * Any product or service that violates applicable Indian or international laws.

    <Note>
      Merchants must not share cardholder data with any third party other than the acquiring member or government bodies as required.
    </Note>

    <Warning>
      If a Cashfree account is later found non-compliant, it may be deactivated at Cashfree's discretion.
    </Warning>

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Is GSTIN mandatory for account activation?">
    No, GSTIN is not mandatory. However, adding GST details lets you avail of GST benefits.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What changes do I need to make to my website for account activation?">
    Your website must be live and include the following sections.

    **Mandatory:**

    * Terms and conditions
    * About us
    * Contact us (one email ID and a valid phone number)
    * Privacy policy
    * Registered business name

    **Conditional (based on business model):**

    * Refund or return policy
    * Shipping and delivery policy
    * Product or services
    * Pricing

    <Warning>
      If your website is later found to be non-compliant, your account may be deactivated at Cashfree's discretion.
    </Warning>

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are the mandatory documents required for onboarding?">
    Required documents vary by business type, but generally include:

    * Contact information
    * Business PAN
    * Business owner PAN
    * Business details and registration documents
    * Website or app details
    * Bank account details
    * Business owner KYC
    * Declaration of beneficial ownership
    * Signed service agreement

    See [create account](/docs/help/account/account-activation#create-an-account) for details.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What documents need to be uploaded based on business type?">
    Required documents vary by business type:

    | Business type | Required documents |
    | - | - |
    | Individual | PAN, Aadhaar, bank account details (all required) |
    | Proprietorship | Any one: Registrar of Companies certificate, Shops and Establishment licence, or Sales/Income Tax return |
    | Partnership | Any one: Partnership deed or Registrar of Firms certificate |
    | Society / Trust / NGO | Any one: Trust deed or Society/NGO registration certificate |
    | Private Limited / LLP | LLP corporation document and certificate of incorporation |

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What additional documents are required based on line of business (LOB)?">
    Additional documents depend on your business category:

    | Line of business | Required document |
    | - | - |
    | SaaS | AOC for PCI-DSS compliance |
    | Food, health, and beauty supplements | FSSAI licence |
    | Education | UGC, ICSE, CBSE, or AICTE certificate |
    | Finance (forex, stock brokerage, payments) | FEMA registration, SEBI certificate, or PA/PG licence |
    | Jewellery | BIS certificate, or 916/925 hallmark |
    | Online gaming | RNG certificate (if applicable) and legal opinion |
    | Pharmacy and drug stores | Pharmacy licence, drug licence, and compliance declarations |
    | Government and utilities | BBPS certificate and sub-category registration |
    | Travel and hospitality | IATA certificate or IRCTC agency certificate |

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Do I need a website or an app for account activation?">
    Yes, you must have either a live website or an app published on the App Store or Play Store.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Does my business need to be registered in India?">
    Yes, your business must be registered in India to use Cashfree's services.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What if my business is not registered?">
    Sign up as an Individual. Once your business is registered, create a new account under Proprietorship or another applicable business type.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Is Aadhaar–phone number linkage mandatory for account activation?">
    Yes, youour Aadhaar must be linked to your phone number. Update your linked number on the [UIDAI portal](https://uidai.gov.in).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I activate my account without a PAN?">
    No, PAN is mandatory. If you do not have a business PAN, register as an Individual using your personal PAN.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I use the same email for multiple businesses?">
    No, each business must have a unique email ID for registration and activation.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How long does the onboarding form take to complete?">
    Less than 5 minutes if you have all required documents ready.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What products does Cashfree offer?">
    Cashfree offers a complete suite of payment and banking solutions:

    | Product | What it does |
    | - | - |
    | Payment Gateway | Accept payments via 180+ modes including UPI, cards, wallets, and EMI. |
    | Payouts | Send instant bulk payments via bank transfer, UPI, wallets, and cards. |
    | Buy Now Pay Later (BNPL) | Cardless EMI, debit/credit card EMI, and Pay Later options. |
    | Subscription Payments | Automate recurring collections via UPI AutoPay and eNACH. |
    | Marketplace Settlement | Auto-split payments and settle vendor commissions. |
    | Secure ID | Verify bank, UPI, PAN, Aadhaar, IFSC, and GSTIN from one dashboard. |
    | Cross Border | Help international merchants and aggregators collect payments from Indian customers. |
    | One Click Checkout | Faster checkouts with OTP auto-fill and address pre-fill. |
    | Cashgram | Accept payments without a website using shareable links or forms. |
    | softPOS | Turn smartphones into POS terminals to accept card payments. |
    | RiskShield | ML-based fraud prevention and anomaly detection. |

    <Tip>
      You get a dedicated account manager and can add unlimited users with role-based access controls.
    </Tip>

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What document types are supported for KYC verification?">
    Documents are grouped into the following categories:

    **Business proof:**

    * Shop and Establishment certificate or licence
    * Government-issued registration proof
    * Municipal certificate
    * Udyog Aadhaar
    * Sales tax or income tax return
    * ROC registration certificate
    * Customer agreement and platform confirmation

    **Entity proof:**

    * Partnership deed
    * Trust deed
    * Society certificate
    * HUF deed
    * LLP documents

    **Line of business proof:**

    * Non-profit: 80G/12A or FCRA certificate
    * Travel: IATA or IRCTC certificate
    * Food: FSSAI licence
    * Gaming: RNG certificate and legal opinion
    * Pharmacy: drug licence and compliance declarations
    * Financial services: SEBI, FEMA, or NBFC licence
    * Education: UGC, CBSE, ICSE, or AICTE certificate

    **Other documents:**

    * Bank statement
    * Certificate of incorporation
    * Board resolution
    * GST certificate
    * Beneficial owner ID proofs

    For the complete list and technical parameters, see [supported document types](/docs/api-reference/platforms/latest/merchant-onboarding/upload-documents#supported-document-types).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What documents are required for Society, Trust, or NGO businesses?">
    Submit the following:

    * **Trust deed / Society / NGO registration certificate**: primary registration document.
    * **Form 80G / 12A**: tax exemption certificates for charitable organisations.
    * **Trust PAN and bank details**: PAN and bank account specific to the trust.

    <Note>
      Exact requirements may vary based on your organisation type and activities. Contact your account manager during onboarding for specifics.
    </Note>

    See the [account activation guide](/docs/help/account/account-activation#required-documents) for more details.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How do I become a Cashfree Partner?">
    Sign up via the [Cashfree Partner page](https://partner.cashfree.com/partner-ui/authentication/signup), then complete partner KYC by replying to the welcome email with your business details and documents. KYC and settlement enablement take up to 48 hours after submission.

    See [commissions and invoices](/docs/partners/affiliates/partner-commissions-and-invoices) for commission calculation examples and settlement timelines, and [affiliate partner dashboard](/docs/partners/affiliates/dashboard) for tracking earnings.

    <Note>
      Commission settlement is available only after partner KYC is complete and the commission structure is configured.
    </Note>

    <iframe title="FAQs feedback component" />
  </Accordion>
</AccordionGroup>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/help/account/account-activation">Account activation</a></li>
    <li><a href="/docs/help/account/overview">Account overview</a></li>
    <li><a href="/docs/help/account/faq">Account FAQs</a></li>
    <li><a href="/docs/help/account/access-management">Access management</a></li>
    <li><a href="/docs/help/account/pricing">Pricing</a></li>
    <li><a href="/docs/partners/affiliates/faqs">Affiliate program FAQs</a></li>
  </ul>
</div>


# One Click Checkout
Source: https://www.cashfree.com/docs/help/one-click-checkout

Find answers to One Click Checkout FAQs covering COD and shipping profile setup, Shopify conversion-data syncing, and native checkout fallback scenarios.

<AccordionGroup>
  <Accordion title="How can I set up COD and shipping profiles for One Click Checkout?">
    To configure these settings:

    1. Log in to the **[Merchant Dashboard](https://merchant.cashfree.com/auth/login)**.
    2. Go to **PG Products > One Click Checkout**.
    3. Select **[COD](https://merchant.cashfree.com/merchants/pg/one-click-checkout-activated/cod)** to configure your Cash on Delivery settings, select **COD & RTO** to configure RTO settings, or select **[Shipping & Delivery](https://merchant.cashfree.com/merchants/pg/one-click-checkout-activated/shipping-delivery)** to configure your shipping and delivery profiles.

    To view checkout event tracking and analytics, go to **[Checkout Analytics](https://merchant.cashfree.com/merchants/pg/developers/checkout-analytics)**.

    For a full configuration checklist, see the [Go Live Checklist](/docs/payments/checkout/checklist).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Does Shopify sync conversion data back to the Shopify dashboard when using One Click Checkout?">
    Shopify does not allow Cashfree to push conversion data back to the Shopify dashboard when One Click Checkout is active. Use the Merchant Dashboard for analytics insights, or use external tools such as Google Analytics to view your data.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Does One Click Checkout for Shopify forward custom cart attributes to the Abandoned Checkout webhook?">
    Cashfree One Click Checkout for Shopify forwards a fixed set of fields to the Abandoned Checkout webhook payload (such as `cart_token`, `abandoned_checkout_url`, and UTM parameters). It does not support forwarding arbitrary custom Shopify cart attributes into the webhook payload.

    To track custom data such as marketing consent, use `cart_token` or `cart_id` as a join key. Store the mapping of `cart_token` to your custom attribute on your server, and look up that mapping when the `ABANDONED_CHECKOUT` webhook is received.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Why are some of my Shopify orders being redirected to the native Shopify Checkout instead of Cashfree Checkout?">
    Orders may fall back to the native Shopify Checkout in the following scenarios:

    * **Inventory issues**: Unavailable inventory or items with zero quantity.
    * **Network interruptions**: Technical connectivity issues can cause the system to default to the native checkout flow.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Do I need to publish products to the Cashfree-OCC sales channel in Shopify?">
    No. The Cashfree-OCC sales channel does not need to be separately configured or published for individual products. Once One Click Checkout is activated and the required integration is configured, it applies to all eligible products by default.
  </Accordion>

  <Accordion title="I don't see OCC listed under Sales Channels in Shopify while updating products. Will it still work?">
    Yes. The One Click Checkout (OCC) integration works even if OCC is not visible as an option under Sales Channels while updating your products. When you activate OCC, it's added automatically, and you don't need to take any further action.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I make the email field non-mandatory in the One Click Checkout (OCC) flow?">
    No. Making the email field non-mandatory in the OCC flow is not currently supported.

    <iframe title="FAQs feedback component" />
  </Accordion>
</AccordionGroup>


# One Click Checkout
Source: https://www.cashfree.com/docs/help/one-click-checkout/faqs/faqs

Find answers to One Click Checkout FAQs covering COD and shipping profile setup, Shopify conversion-data syncing, and native checkout fallback scenarios.

<AccordionGroup>
  <Accordion title="How can I set up COD and shipping profiles for One Click Checkout?">
    To configure these settings:

    1. Log in to the **[Merchant Dashboard](https://merchant.cashfree.com/auth/login)**.
    2. Go to **PG Products > One Click Checkout**.
    3. Select **[COD](https://merchant.cashfree.com/merchants/pg/one-click-checkout-activated/cod)** to configure your Cash on Delivery settings, select **COD & RTO** to configure RTO settings, or select **[Shipping & Delivery](https://merchant.cashfree.com/merchants/pg/one-click-checkout-activated/shipping-delivery)** to configure your shipping and delivery profiles.

    To view checkout event tracking and analytics, go to **[Checkout Analytics](https://merchant.cashfree.com/merchants/pg/developers/checkout-analytics)**.

    For a full configuration checklist, see the [Go Live Checklist](/docs/payments/checkout/checklist).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Does Shopify sync conversion data back to the Shopify dashboard when using One Click Checkout?">
    Shopify does not allow Cashfree to push conversion data back to the Shopify dashboard when One Click Checkout is active. Use the Merchant Dashboard for analytics insights, or use external tools such as Google Analytics to view your data.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Does One Click Checkout for Shopify forward custom cart attributes to the Abandoned Checkout webhook?">
    Cashfree One Click Checkout for Shopify forwards a fixed set of fields to the Abandoned Checkout webhook payload (such as `cart_token`, `abandoned_checkout_url`, and UTM parameters). It does not support forwarding arbitrary custom Shopify cart attributes into the webhook payload.

    To track custom data such as marketing consent, use `cart_token` or `cart_id` as a join key. Store the mapping of `cart_token` to your custom attribute on your server, and look up that mapping when the `ABANDONED_CHECKOUT` webhook is received.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Why are some of my Shopify orders being redirected to the native Shopify Checkout instead of Cashfree Checkout?">
    Orders may fall back to the native Shopify Checkout in the following scenarios:

    * **Inventory issues**: Unavailable inventory or items with zero quantity.
    * **Network interruptions**: Technical connectivity issues can cause the system to default to the native checkout flow.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Do I need to publish products to the Cashfree-OCC sales channel in Shopify?">
    No. The Cashfree-OCC sales channel does not need to be separately configured or published for individual products. Once One Click Checkout is activated and the required integration is configured, it applies to all eligible products by default.
  </Accordion>

  <Accordion title="I don't see OCC listed under Sales Channels in Shopify while updating products. Will it still work?">
    Yes. The One Click Checkout (OCC) integration works even if OCC is not visible as an option under Sales Channels while updating your products. When you activate OCC, it's added automatically, and you don't need to take any further action.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I make the email field non-mandatory in the One Click Checkout (OCC) flow?">
    No. Making the email field non-mandatory in the OCC flow is not currently supported.

    <iframe title="FAQs feedback component" />
  </Accordion>
</AccordionGroup>


# Cashfree FAQs
Source: https://www.cashfree.com/docs/help/overview

Find answers and support resources for Cashfree, with FAQs grouped by product and direct contact options for the merchant support team.

## Browse FAQs by category

Browse frequently asked questions organised by product category to find quick answers to common questions.
<Tip>First-time setup: Create your account in the [Account setup](/docs/help/account/account-activation) section, then browse FAQs for feature-specific guidance.</Tip>

<CardGroup>
  <Card href="/docs/help/account/faq">Account</Card>

  <Card href="/docs/help/onboarding-related/onboarding-faqs">Onboarding</Card>

  <Card href="/docs/help/payments/transactions/transactions">Payment Gateway</Card>

  <Card href="/docs/help/payment-links/faqs/faqs">Payment Links</Card>

  <Card href="/docs/help/payment-forms/faqs/faqs">Payment Forms</Card>

  <Card href="/docs/help/easy-split/faqs/faqs">Easy Split</Card>

  <Card href="/docs/help/subscriptions/faqs/faqs">Subscriptions</Card>

  <Card href="/docs/help/flowwise/general-faqs">FlowWise</Card>

  <Card href="/docs/help/softpos/softpos">softPOS</Card>

  <Card href="/docs/help/payouts/general-faqs">Payouts</Card>

  <Card href="/docs/help/secure-id/aadhaar-verification">Secure ID</Card>

  <Card href="/docs/help/end-customer/disputes-and-chargeback">End Customer</Card>
</CardGroup>

## Contact support

Use these channels to raise queries directly with Cashfree support teams:

<CardGroup>
  <Card title="Merchant Support" icon="store" href="https://www.cashfree.com/contact-us/">
    Get help with account activation, product configuration, pricing, settlements, and business queries.
  </Card>

  <Card title="Customer Support" icon="users" href="https://www.cashfree.com/en/report-issue/">
    Having issues with a payment made via Cashfree? Report an issue here.
  </Card>
</CardGroup>

## Additional support

If you didn't find what you're looking for, you can:

* Contact the [support team](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) for personalised assistance.
* Join the Cashfree [Discord Server](https://discord.gg/ed9VWDnrh7) for developer support.
* Watch the [Testing APIs in Postman](https://www.youtube.com/watch?v=OkzoR7K3yxw) video tutorial to learn API testing.
* View the [Documentation Walkthrough](https://youtu.be/tqcOHCUZgOM) for a comprehensive guide to navigating these docs.


# Payment Forms
Source: https://www.cashfree.com/docs/help/payment-forms/faqs/faqs

Find answers to payment forms FAQs covering form creation, custom fields, branding, sharing options, supported payment modes, and submission tracking workflows.

<AccordionGroup>
  <Accordion title="What is a Payment Form and how does it work?">
    Payment Forms let you collect online payments via 120+ methods like UPI and net banking—no payment gateway needed! Customise the form, accept domestic and international payments, and collect customer details. Set a fixed or flexible amount and share the form via SMS, email, WhatsApp, or your website to start receiving payments instantly.
    See [Creating a payment form](/docs/payments/no-code/payment-forms/overview#creating-a-payment-form) to see how

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How do I create a Payment Form?">
    To create a payment form:

    1. Go to **Payment Gateway Dashboard** > **Payment Forms** > click **Create Payment Form**.
    2. In the **Payment For** field, explain the purpose of payment to the customer. Keep this text short and precise. This information is necessary for customers to understand the purpose of payment.
    3. Configure amount fields. You can specify a single or multiple amounts.
    4. Personalise the URL to include your brand name for easy identification.
    5. Specify the payment form validity time. (Validity time supported: 1, 2, 7, 14, 30 days, or set as No Expiry to keep it active always).

    **Add Payment Details**
    **Add Customer Details**
    **Add Business Details**

    Save and create the payment form. The payment form created will be active to collect payments. Share the payment form URL with your customers and start collecting payments instantly.

    All the payment forms created will be visible in the **Payment Forms** screen. You can edit, cancel, activate a cancelled payment form, and also share the payment form details with your customers after you create it. You can see and track the payment statuses in the **Orders** section.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I generate a report for all payment form transactions?">
    Yes, you can generate a report for all Payment Form transactions.

    The payment form report has the list and details of orders and payments made against the payment forms in the period selected. Order details, customer details, transaction amount, payment method, card details, and more are available in this report.

    To generate the payment form report,‌

    1. Go to Payment Gateway Dashboard > Reports.
    2. In the Search & Filter field, select Payment Form, and click Generate.
    3. Select the date range for which you want to view the report, and click Generate.
    4. The report will be generated based on the criteria you have filtered. You can download the report after it has been generated.

       <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How do I know when a payment is made via a Payment Form?">
    You will be notified about the payments made using the payment form via webhooks.

    The Payment Form webhook will be triggered when your customers make a complete payment using the payment form you shared.

    To start receiving webhook event notifications:

    1. Go to **Payment Gateway Dashboard** > click **Developers** in the left navigation.
    2. Select **Webhooks** in the **Payment Gateway** section.
    3. Click **Add Webhook URL** and select the event you want to be notified about.
    4. Enter the URL where you want to receive the webhook notifications, and click **Add**.

    You will start to receive webhook event notifications on the URLs you have specified. You can use one URL to handle several different event types at once or specify individual URLs for specific events.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I use the same Payment Form for multiple products or services?">
    Yes, the same form can be set up to take in different product information and pricing. The customer can select and pay for the product/service he/she is interested in.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What is a Subscription Payment Form?">
    A Subscription Payment Form collects recurring payments through a hosted checkout. You can publish the form with a single plan, or add multiple plans to the same form. On a single-plan form, customers complete mandate registration for that plan. On a multi-plan form, they choose one plan at checkout. Cashfree creates a mandate and a subscription only for the plan used at checkout. See [Subscription Payment Form](/docs/payments/no-code/payment-forms/subscription-payment-form).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I add more than one subscription plan to a Payment Form?">
    Yes. A Subscription Payment Form needs at least one plan. Click **Add Plan** to include more plans on the same form. Customers then see every available plan and select one at checkout. Cashfree creates a mandate and a subscription only for the selected plan. For setup steps, see [Subscription Payment Form](/docs/payments/no-code/payment-forms/subscription-payment-form).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can a customer subscribe to more than one plan from the same Payment Form?">
    No. The customer selects one plan and completes mandate registration for that plan only. Customers cannot switch plans after the subscription is created. Create a new subscription if the customer needs a different plan.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Do all subscription plans on a Payment Form need the same currency?">
    Yes. Every plan on a Payment Form must use the same currency. Use a separate Payment Form if you need to collect in another currency.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="I am using a hosted payment form and cannot call the Create Order API directly. How do I pass custom fields for reconciliation?">
    Collect the custom fields your reconciliation needs on your own page before the customer reaches the hosted payment form, for example institute code, roll number, or division for education and multi-institute fees, or other identifiers such as branch, campaign, or invoice reference. Submit those values to your backend, create the order server-side using the [Create Order API](/docs/api-reference/payments/latest/orders/create) with the fields mapped into `order_tags`, and then redirect the customer to the Cashfree payment session using the returned `payment_session_id`. This ensures the tags are always set correctly and appear in the Settlement Recon Report.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Why is my Payment Form not automatically redirecting after payment even though I set a redirect URL?">
    To ensure automatic redirection after a payment on a Payment Form, pass the `return_url` in the `order_meta` object during order creation.

    If your Payment Form is not redirecting and instead shows a success page with a **Download Invoice** button, disable the **Download Invoice** option in your Invoice Settings in the Merchant Dashboard. When this option is active, customers stay on the Cashfree success page to view the invoice instead of being redirected to the configured return URL.
  </Accordion>
</AccordionGroup>


# Payment Links
Source: https://www.cashfree.com/docs/help/payment-links/faqs/faqs

Find answers to payment links FAQs covering link creation, bulk uploads, sharing options, expiry rules, partial payments, and tracking customer collections.

<AccordionGroup>
  <Accordion title="How do I start using Payment Links with Cashfree?">
    Simply sign up for a Payment Links account, and Cashfree Payment Gateway will be automatically activated for your account. The Payment Links feature will be available inside the **Payment Gateway** product.\
    All payments collected via the payment links are automatically updated in the **Reports** and **Transactions** module in Cashfree Payment Gateway.

    Know more in the [Payment Links documentation](/docs/payments/no-code/payment-link).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title=" Can I create a payment link for a restricted time period?">
    Yes, you can create a payment link in the Cashfree Payment Gateway Dashboard with an expiry limit to ensure you get paid within a specific timeframe.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What information do I need to provide to create Payment Links?">
    Enter the customer’s phone or email, amount, and purpose, then share the link. You can also enable SMS & Email notifications, set an expiry date, and allow partial payments for added flexibility.

    See [Payment Links](/docs/payments/no-code/payment-link) to know more

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How do I increase my payment link amount?">
    To update the amount on an existing payment link, follow these steps.

    1. Sign in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
    2. Go to **Payment Gateway** > **Payment Links** > **All**.
    3. Find the payment link in the table and click the **more options** icon (⋮) on that row.
    4. Click **Edit**.
    5. In the **Edit Payment Link** dialog, enter the new value in the **Amount** field.
    6. Click **Update**.

    **Result:** A confirmation message appears and the Amount column updates to reflect the new value.

    For a complete list of fields you can edit, including payment reason and customer details, see [Edit Payment Link](/docs/payments/no-code/customize/edit-payment-link).

    <Note>
      Each Unified Payments Interface (UPI) payment link supports a maximum collection of ₹1 lakh. To collect a higher amount, select **All payment methods** instead of **Only UPI**, or distribute the total across multiple links or payments.
    </Note>

    If an account or transaction limit prevents the update, raise a request using the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I create Payment Links in bulk?">
    Yes, you can create Payment Links in bulk using the Batch feature. Simply fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) with your business requirements, and we’ll verify and activate it for your account. Meanwhile, you can test the flow in the sandbox.

    Once activated, upload a file with the required details in the Batch section. Download the sample file to check the format.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can my customers make multiple partial payments on Payment Links?">
    Yes, you can enable **Partial Payments** and provide the minimum amount you
    wish to collect for a Payment Link. The customer can choose to make multiple
    payments, between the minimum amount and the link amount. Cashfree will notify
    you of all partial payments done.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Are international payments supported on Payment Link?">
    Yes, it is possible to enable international payments on Cashfree Payment
    Links. Talk to us and help us understand your business for quick activation.
    If you have a **Paypal** account, connect **Paypal** to Cashfree and start
    offering Paypal as a checkout option on the payment page instantly.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are Orders?">
    Each time your customer opens a payment Link and attempts payment, a new
    Order is created against that link. This gives you the information on how
    many times the customer has visited the link before completely paying the full
    amount. You can follow up with such customers and try to improve your
    conversion rate.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are Cashfree Payment Links and why should I use them?">
    Payment Links by Cashfree is the easiest way to receive payments from your customers for any goods or services, without taking them to any app or website.

    Payment Link can be shared with the customer via different channels like WhatsApp, SMS, email, etc., and upon clicking the link, your customers can pay using all available payment methods. Cashfree will notify you when payment(s) are made using the link.

    Payment Links are a **no-code solution** that are used to accept online payments without any payment gateway integration required. Any business can create a payment link and collect online payments. No website required.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How can I create payment links for my business?">
    1. Go to **Payment Gateway Dashboard** > **Payment links** > **Create Payment Link**
    2. List the reason, the amount and the customer details.
    3. You can also select an expiry time for the link, a custom thank you message, add a note in the more section.
    4. Click create and all set!

       <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How can I create UPI payment links for my business?">
    Create and share UPI payment links with your customers to accept payments via UPI applications. To create a UPI payment link, you first need to add your product and customer details. You can share the payment link via SMS, email, WhatsApp, or any other platform. To make payments, customers must click the URL that you have sent, and a list of UPI apps installed on their mobile will be displayed. Customers can select any UPI app and complete the payment. A maximum amount of rupees 1 Lakh can be collected using the UPI payment link.

    To create a UPI payment link:

    1. Go to **Payment Gateway Dashboard** > **Payment Links** > click **Create Payment Link**.
    2. Select the option **Create UPI Link**.
    3. In the **Payment For** field, explain what the customer is making the payment for. Keep this text short and clear. This information is important for customers to understand the purpose of payment. Partial payments are not allowed for the UPI payment method.
    4. Set the **Link Expiry** limit.
    5. Enter the customer details (phone number and email ID) to send the payment link.
    6. Select the option **Send Auto Reminders** to send payment reminders automatically to your customers.
    7. Enable **Send Auto Reminders** option to notify your customers about the payment. See [Payment Links](/docs/payments/no-code/payment-link) to know more.
    8. You can add the **Link ID** and additional description for your reference. This will not be visible to your customers.

       <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What information is required to create a Payment Link?">
    To quickly request payment from your customer via Payment Link, you simply need to provide the customer’s phone or email information, and the amount and purpose for the link. Once the details are entered, the link can be shared with the customer.

    While creating a Payment Link, you can:

    * Enable the **Send SMS** and **Email** checkboxes, and Cashfree will send the link to the customer on the provided contact information.
    * Set the **expiry** for the link.
    * Enable **partial payments** if you want the customer to make payments in parts.

      <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I generate a report of all payment link transactions?">
    Yes, you can generate a report of all payment link transactions.\
    The payment link orders report provides the list and details of orders and payments made against all payment links within the selected period. This includes order details, customer details, transaction amount, payment method, transaction status, settlement UTR (if the settlement is complete), and more.

    To generate the payment link orders report:

    1. Go to **Payment Gateway Dashboard** > **Reports**.
    2. In the **Report Type** field, select **Payment Link Transactions**, and click **Generate**.
    3. Select the date range for which you want to view the report, and click **Generate**.

    The report will be generated based on your selected criteria. You can download the report after it has been generated.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Do I get notified when a payment is made on a payment link?">
    Yes, you can use webhooks to get notified about different events such as orders, payments, and settlements.

    The **Payment Link webhook** will be triggered when your customer makes a complete or partial payment using the payment link you shared. You will also be notified via the same webhook when the payment link gets cancelled or expired.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How to cancel or delete a payment link?">
    You can’t permanently delete a payment link, but you can cancel it to stop receiving payments.

    From the [Merchant Dashboard](https://merchant.cashfree.com/auth/login), click the **ellipsis (⋮)** icon next to the link and select **Cancel**.
    From API: Use POST /links//cancel (works only for ACTIVE links).
    Once cancelled, no further payments can be made.

    See [Cancel a payment link](/docs/payments/no-code/customize/cancel-payment-link) to know more.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I create a payment link for a restricted time period?">
    Yes, you can create a payment link in the Cashfree payment gateway dashboard, with an expiry limit to make sure you get paid within a specific timeframe.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How to share a Payment Link?">
    The payment link can be shared via SMS, email, Whatsapp or any other platform.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How do I create a TPV payment link from the dashboard?">
    To create a TPV (Third-Party Validation) payment link from the Merchant Dashboard,
    the TPV feature must be enabled on your MID (Merchant ID). If it isn't enabled yet,
    see the Note below before proceeding.

    1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
    2. Navigate to **Payment Gateway** > **Payment Links** > **Create Payment Link**.
    3. Fill in the payment link details, such as amount, purpose, and customer details.
    4. In the **Add Notes** section, enter the following TPV parameters:
       * `customer_bank_account_number`: The customer's bank account number.
       * `customer_bank_ifsc`: The customer's bank IFSC code.
       * `customer_bank_code` (optional): The customer's bank code.
    5. Click **Create & Send** to generate and share the payment link.

    When the customer pays using this link, the payment is validated against
    the bank account details you provided.

    <Note>
      The TPV feature must be activated on your MID before you can use this flow.
      Contact your Account Manager or submit a request through the
      [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1)
      to enable it.
    </Note>
  </Accordion>

  <Accordion title="Is there a character limit on the Payment Link link_id?">
    Yes. The `link_id` field has a maximum length of 50 characters. If your generated `link_id` exceeds this limit, the Payment Link creation API returns a `link_id_invalid` validation error.

    Shorten the `link_id` to 50 characters or fewer; this limit cannot currently be increased.
  </Accordion>

  <Accordion title="Can I customise the Order Note for orders generated through the Payment Link API?">
    When you create payment links through the API, Cashfree generates the Order Note as part of the payment link creation flow. You cannot customise or modify it.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How can I add custom information like a purpose or notes when creating a Payment Link through the API?">
    When you create payment links through the [Create Payment Link API](/docs/api-reference/payments/latest/payment-links/create-payment-link), pass additional information in `link_purpose` and `link_notes`. These details appear in the Payment Links section of the Merchant Dashboard.

    <iframe title="FAQs feedback component" />
  </Accordion>
</AccordionGroup>


# External Analytics
Source: https://www.cashfree.com/docs/help/payments/external-analytics/external-analytics

Find answers to external analytics FAQs about Meta Pixel and Google Analytics integrations on Cashfree checkouts, event tracking, and configuration steps.

<AccordionGroup>
  <Accordion title="I am not able to see events in the Meta Pixel Helper (Meta Pixel Ad Helper). Why?">
    Cashfree External Analytics integration supports server-side events only, which are pushed directly to the Meta Events Manager dashboard instead of the browser. As a result, events do not appear in the Meta Pixel Helper, but they are visible in the Meta Events Manager dashboard.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How long does it take for events to appear in Meta Pixel?">
    * After configuration in the Merchant Dashboard, events may take approximately **30 minutes to 1 hour** to appear in the Meta Events Manager.
    * It may take **24–48 hours** for the same events to become visible in Meta Ads reporting.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How long does it take for GA4 data to appear after configuring it in Cashfree OCC?">
    After configuring GA4 in Cashfree OCC, monitor the data for approximately **24–48 hours** to allow a sufficient sample size to accumulate. Note that only events generated after the configuration is enabled will be sent. Orders or events created prior to the configuration will not be available.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What should I do if I am receiving duplicate events in Meta Pixel?">
    If you are receiving duplicate purchase events in the Meta Events Manager, events may be getting triggered from multiple sources.

    To avoid duplication, disable the `purchase` event from the Merchant Dashboard. This prevents Cashfree from sending the purchase event and resolves the duplication issue.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Where can I find documentation to set up Meta Pixel and GA4 tracking for Cashfree checkout?">
    You can configure external analytics from the [Merchant Dashboard](https://merchant.cashfree.com/auth/login). For setup instructions, see:

    * [Google Analytics 4 (GA4)](/docs/payments/checkout/after/external-analytics#google-analytics-4-ga4)
    * [Meta Pixel](/docs/payments/checkout/after/external-analytics#meta-pixel)

    After setup, monitor the event flow for 24–48 hours to ensure events are being tracked correctly.

    <iframe title="FAQs feedback component" />
  </Accordion>
</AccordionGroup>


# Integrations
Source: https://www.cashfree.com/docs/help/payments/integrations/integrations

Find answers to Cashfree payment integration FAQs covering ecommerce plugins, hosted checkout, custom server flows, supported platforms, and webhook setup.

<AccordionGroup>
  <Accordion title="How do I integrate Cashfree with my website or mobile app?">
    **Cashfree offers multiple integration APIs for:**

    * Website integration
    * Mobile SDK integration
    * Predefined plugins for major e-commerce platforms like:
      * [Shopify](https://www.shopify.com)
      * [Magento](https://magento.com)
      * [Woo-Commerce](https://woocommerce.com)
      * [OpenCart](https://www.opencart.com)
      * [WHMCS](https://www.whmcs.com)
      * [PrestaShop](https://www.prestashop.com)

    You can make use of these APIs to set up Cashfree payment gateway with your website or mobile app and start accepting payments.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are the different ways I can set up the payment gateway for my business?">
    Cashfree lets you integrate your [website](https://www.cashfree.com/payment-gateway-india/) or [mobile app](https://www.cashfree.com/payment-gateway-india/) with our payment gateway to accept payments. Over and above this, we also offer [plugins](https://www.cashfree.com/payment-gateway-india/) to major ecommerce sites like [Shopify](https://www.shopify.com), [Magento](https://magento.com), [Woo-commerce](https://woocommerce.com), [OpenCart](https://www.opencart.com), [PrestaShop](https://www.prestashop.com), [WHMCS](https://www.whmcs.com).
    [Click here to know more](/docs/payments/plugins/others#whmcs).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are the different web integrations possible with Cashfree?">
    There are three types of web integrations possible with Cashfree:

    1. [**Popup**](/docs/payments/online/web/redirect#3-open-cashfree-checkout)
    2. [**Cashfree Hosted**](/docs/payments/online/web/redirect)
    3. [**Element**](/docs/payments/online/element/overview)

    You can instantly set up any of these based on your requirements.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are the different mobile SDK integrations possible with Cashfree?">
    Cashfree offers a wide range of mobile SDK integrations such as:

    * [Android SDK](/docs/payments/online/mobile/android)
    * [iOS SDK](/docs/payments/online/mobile/ios)
    * [React Native SDK](/docs/payments/online/mobile/react-native)
    * [Flutter SDK](/docs/payments/online/mobile/flutter)
    * [Cordova SDK](/docs/payments/online/mobile/cordova)

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I test my app if it is not yet published on the Play Store or App Store?">
    Yes. In the sandbox environment, Cashfree Integrity does not enforce store verification, so you can test without a Play Store or App Store listing. For production testing, distribute your app through the Play Store's internal testing track instead of sideloading the APK directly. This satisfies Cashfree Integrity's store verification requirement without requiring a public release. For setup instructions, see [Integrity prod setup](/docs/payments/online/mobile/misc/cashfree_integrity_prod_testing).
  </Accordion>

  <Accordion title="What are the stores supported by Cashfree Integrity?">
    Google Play Store and Apple App Store are the stores currently supported by Cashfree Integrity.
  </Accordion>

  <Accordion title="When will the payment fail in Cashfree Integrity?">
    If an APK file is distributed through an unauthorised channel, Cashfree Integrity will block any payment happening through that application. If you are testing in production mode, payments will fail if the application is not installed from an authorised source. You can simulate production payments by doing a beta release of your application.
    [Setup for PROD test](/docs/payments/online/mobile/misc/cashfree_integrity_prod_testing)
  </Accordion>

  <Accordion title="What are the security mechanisms available in Cashfree Integrity?">
    Cashfree Integrity provides the following security mechanisms:

    * **Verified Package Names:** Transactions occur only through verified package names.
    * **Whitelisted Sources:** Package names are whitelisted to ensure applications are installed from verified stores.
  </Accordion>

  <Accordion title="Can I integrate Cashfree payment gateway to my Shopify website?">
    Yes, we do provide a predefined [plugin for WHMCS](/docs/payments/plugins/others#whmcs) that helps you set up Cashfree payment gateway with your [Shopify](https://www.shopify.com) account in no time, and with absolutely no code.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I integrate Cashfree payment gateway to my Magento website?">
    Yes, we provide a predefined [plugin for Magento](/docs/payments/plugins/magento) that helps you set up Cashfree payment gateway with your [Shopify](https://www.shopify.com) account in no time, and with absolutely no code.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I integrate Cashfree payment gateway to my Woo-Commerce website?">
    Yes, we provide a predefined plugin for [**Woo-Commerce**](/docs/payments/checkout/woocommerce) that
    helps you set up Cashfree payment gateway with your Woo-Commerce account in no
    time, and with absolutely no code.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I integrate Cashfree payment gateway to my OpenCart website?">
    Yes, we provide a predefined plugin for [**OpenCart**](/docs/payments/plugins/others#opencart) that helps
    you set up Cashfree payment gateway with your OpenCart account in no time, and
    with absolutely no code.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I integrate Cashfree payment gateway to my PrestaShop website?">
    Yes, we do provide a predefined plugin for [**PrestaShop**](/docs/payments/plugins/others#prestashop) that
    helps you set up Cashfree payment gateway with your PrestaShop account in no
    time, and with absolutely no code.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I integrate Cashfree payment gateway to my WHMCS website?">
    Yes, we do provide a predefined plugin for [WHMCS](/docs/payments/plugins/others#whmcs) that helps you set up Cashfree payment gateway with your Shopify account in no time, and with absolutely no code.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I integrate Cashfree with Shiprocket?">
    No. Cashfree does not currently support integration with Shiprocket. Integrations with other major e-commerce and platform partners are supported.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I integrate Cashfree payment gateway to Paytm?">
    Follow these steps to show Paytm as a payment option on your checkout page. You need to create a Paytm business account and connect Paytm with Cashfree. The process takes **24–48 hours**, after which Paytm will be available as a payment option for your customers.

    1. **Create a Paytm Business Account:**
       * Go to [Paytm Business](https://business.paytm.com/) and create a test account.

    2. **Receive Test Credentials:**
       1. After creating the test account, Paytm will send you an email with your *Merchant Staging Credentials*.
       2. Forward this email to the Cashfree team.
       3. Alternatively, you can find these details in your Paytm dashboard under the **Test API Details** tab.

    3. **Share Test Credentials:**
       1. Share your test credentials with your Cashfree Account Manager.
       2. To activate your production account, Cashfree will place **three test orders** on Paytm.
       3. Your account manager will share the status of these orders, which you need to forward to Paytm.

    4. **Receive Production Credentials:**
       * After verifying the test orders, Paytm will generate the following production credentials for your merchant account:
         * Website (for web)
         * Merchant ID
         * Merchant Key
         * Industry Type ID
         * Channel ID (for web)
         * Production Server URL

    5. **Activate Paytm on Cashfree:**
       * Share your production credentials with your Cashfree Account Manager.
       * Once this is done, the Paytm payment option will be activated on your account.

    For any queries, contact your Account Manager or submit a [Support Form](https://merchant.cashfree.com/auth/login).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Is the Drop-in Checkout flow still supported for mobile SDK integrations?">
    The Drop-in Checkout flow has been deprecated and is no longer under active development. Use the Web Checkout flow for mobile SDK integrations instead. See the [Android integration guide](/docs/payments/online/mobile/android) for setup instructions.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can we fetch the list of installed apps for mobile web integration?">
    No, it's not possible to fetch the list of installed apps from a mobile web environment. However, you can display the default UPI apps such as Google Pay, PhonePe, and Paytm on both Android and iOS devices.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Is Kotak-811 supported as a PSP app for UPI Intent flow?">
    Kotak-811 is currently not supported as a PSP app for the UPI Intent flow. For the currently supported UPI Intent applications and integration steps, see [UPI Intent in JS SDK](/docs/payments/online/mobile/misc/upi_intent_support_js_sdk).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Why is the UPI Intent option not appearing in my Android WebView checkout?">
    UPI Intent relies on redirection to a UPI application and is generally supported through mobile app flows. If you use a WebView checkout through the JS SDK, you must implement the intent redirection changes. Cashfree must also enable a feature flag on your account to display the supported UPI Intent apps in checkout. Submit a request through the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1). See [UPI Intent in JS SDK](/docs/payments/online/mobile/misc/upi_intent_support_js_sdk) for implementation details.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What should I do if my account is not eligible for S2S (Order Pay API) enablement?">
    If your account is not eligible for S2S (Server-to-Server) enablement or the [Order Pay API](/docs/api-reference/payments/latest/payments/order-pay), you can use the [Elements SDK](/docs/payments/online/element/introduction) as an alternative integration method.

    <iframe title="FAQs feedback component" />
  </Accordion>
</AccordionGroup>


# Offers
Source: https://www.cashfree.com/docs/help/payments/offers/offers

Find answers to Cashfree offers FAQs covering bank discounts, EMI promotions, cashback rules, offer configuration on checkout, and customer eligibility checks.

<AccordionGroup>
  <Accordion title="What is the Offers Section in Merchant Dashboard?">
    Boost Sales with Discounts & Cashback! Attract customers, increase AOV, and drive conversions with easy-to-set-up offers.
    Cashfree lets you create discounts and cashback deals across multiple payment methods for a seamless shopping experience.
    See [overview of offers](/docs/payments/checkout/offers) to know more

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How can I create and show offers to my customers on checkout?">
    Offer discounts and cashback to attract customers and improve sales when they make payments on your website or apps. You can specify different offers on various payment methods and give your customers the flexibility to pay from the payment method they choose.

    When you create the offers, you can:

    * Specify the offer code and offer type (Discount or Cashback).

    * Select the payment methods on which the offers should be applicable.

    * Reduce the total amount a customer pays by a percentage or a flat amount.

    * Specify the maximum number of transactions allowed per payment method.

    * Define the offer validity period.

    * View a consolidated report for each offer you created.

    Offers will automatically be applicable for businesses using Cashfree hosted checkout pages and plugins, and no additional integration effort is required. You can create Offers using our Payment Gateway Dashboard.
    **Create Offers**

    **To create an offer:**

    1. Go to **Payment Gateway Dashboard > Offers > Create New Offer**.

    2. Specify the offer details:

    * Enter a title for the offer that the customers can relate to.

    * Add an offer code and an offer description. These details will be visible to customers on your checkout page or plugin during payment.

    3. Specify the offer's start and end dates and its terms and conditions:

    * You can link your business's terms and conditions or add a short description.

    4. Select the offer category that applies to your business:

    * Provide discounts, cashback, or both to your customers.

    5. Select the discount type:

    * Provide discounts at a flat rate or as a percentage.

    * Specify the maximum discount amount or discount percentage for the selected type.

    6. Select the payment modes for which the offers apply:

    * Choose all or specific payment modes.

    * Optionally, specify the banks and card types relevant to the offer.

    * Click **Create**.

    The offer is now active and available in the **Offers** section. You can activate or deactivate the offer at any time.

    **Offers Shown to Customers**

    When customers initiate a payment, all available offers are listed on your checkout page. Offer details like the description and code will be visible to customers, so ensure you clearly explain your offer's context using these fields.

    Customers can select an offer and proceed with the payment. The reduced amount is displayed on the checkout page, and the customer completes the payment with the final amount.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How to create No Cost EMI offer on Cashfree?">
    Log in to **Cashfree** > **Offers** > **Create No-Cost EMI**
    Enter Details – Add a title, offer code, and description.
    Set Timeline – Define start and end dates.
    Choose EMI Options – Select credit/debit card EMI, banks, and duration (3, 6, 9 months).
    Set Limits – Control how many times the offer can be used.
    Activate – Ensure the offer is live for customers.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I deactivate a running offer anytime?">
    Yes, you can deactivate an offer at any point in time. To change the status of
    an offer, select the toggle button in the **Status** (Active/Inactive). Click
    on a particular offer to view the offer details. You can **Deactivate** the
    ongoing offer, and if you want to create a similar offer, select the
    **Duplicate** option.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Do I need any additional integration to use offers?">
    Offers will automatically be applicable for businesses using Cashfree hosted checkout pages and plugins, and no additional integration effort is required. You can create Offers using our Payment Gateway Dashboard. Merchants who are using the upfront TDR model will not be allowed to create offers.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How can I highlight a prepaid discount offer during checkout?">
    To highlight an offer on the checkout page, create an automatic or manual offer in the Merchant Dashboard without restricting payment methods. Restricting payment methods prevents the offer from being highlighted at checkout. Also confirm that the offer banner is turned on in the Merchant Dashboard. A disabled offer banner can hide automatic and manual offers from customers. See [Checkout experience](/docs/payments/checkout/offers#checkout-experience).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How can I prevent multiple discount codes from being stacked with a Cashfree prepaid offer?">
    To prevent stacking, create non-combinable offers on Shopify. Cashfree-created offers (such as PREPAID10) cannot be combined with other discounts created within the Cashfree system. Setting the Shopify offer to be non-combinable ensures it will not stack with other Shopify-based discounts, while the Cashfree offer remains applicable.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What is the prerequisite for enabling Snapmint on my Cashfree account?">
    One Click Checkout (OCC) is a prerequisite for enabling Snapmint. You must have OCC enabled on your account before Snapmint activation can proceed.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How do I stop an old discount code from being applied by customers?">
    If you have discontinued a marketing campaign or an offer, you must disable or inactivate the offer on both the Shopify dashboard and the Merchant Dashboard to prevent customers from using the discount code.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How do I complete the Snapmint setup on Cashfree?">
    To complete Snapmint setup, submit a request through the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Why am I unable to find a One Click Checkout (OCC) order when searching by customer email or phone number?">
    For One Click Checkout (OCC) transactions, searching by customer email or phone number may not always yield results because a dummy email might be passed during the transaction flow. Search using the Cashfree Order ID or Transaction ID instead.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I delete a paused offer on the Merchant Dashboard?">
    Offers can be inactivated on the Merchant Dashboard. If the offer was created via Shopify, it should be deleted on the Shopify dashboard.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Why are offers appearing on my checkout page even though I have not created any discount coupons?">
    The offers displayed on the checkout page may be offers that Cashfree funds directly. These offers are enabled by default and are displayed to all eligible merchant accounts, so the offers section can appear even if you have not created any coupons or offers yourself.
  </Accordion>
</AccordionGroup>


# Orders and Payments
Source: https://www.cashfree.com/docs/help/payments/orders-and-payments/orders-and-payments

Find answers to orders and payments FAQs covering accepting payments without an integration, order creation, payment statuses, and customer payment options.

<AccordionGroup>
  <Accordion title=" Can I receive payments from my customers without integrating Cashfree to my website?">
    You can use the Cashfree Payment Gateway Dashboard to create orders and accept payments using
    [payment link](/docs/payments/no-code/payment-link). These links can be sent to your customers via email or SMS, without the need to integrate Cashfree to your website.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title=" Can I create a payment link for a restricted time period?">
    Yes, you can create a payment link in the Cashfree payment gateway dashboard.
    With an expiry limit to make sure you get paid within a specific timeframe.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="I run an NGO. How can I use Cashfree to accept donations?">
    Cashfree provides you with the flexibility to create [**Payment Forms**](/docs/payments/no-code/payment-forms/overview), a no-code solution that your customers can use to pay any amount of their choice to your account.

    Here's how you can set up a Payment Form to help receive donations for a cause:

    1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and go to **Payment Gateway > Payment Forms > All**.

    2. Select **Create a Payment Form** and complete the following details:

       * **Payment For**: Enter the campaign title. (Example: India Needs Oxygen and Vaccines!).

       * **Personalised URL**: Enter the URL identifier that will be shared with customers. (Example: covid-relief-fund).

       * **Description**: Add details about the donation cause — mention how the donated funds will be used and whether you have partnered with any other agency. (Example: Our hospitals are going through dire situations; we urgently need more oxygen concentrators and vaccine doses to save as many lives as possible.)

       * **Amount configuration**: Select **Multiple amounts** to let donors choose their contribution.

    3. Set up customer data collection:

       * Enable **Name**, **Phone number**, and **Email address**.

       * Enable **Address field** to collect the donor's residential address.

    4. Under **Terms and conditions**, add your donation terms:

       * If your organisation is eligible to give 80G certificates, clearly mention your registration number and PAN details. (Example: Your contribution has an exemption of 50% under Section 80G of the IT Act. An 80G certificate will be provided within a few days if a valid PAN and residential address are provided by the payer. Compulsory for donations above Rs. 50,000. \<br>Registration No: XX \<br>PAN: XX.)

       * Add any applicable terms for donors. (Example: Donations using this link can be made by Indian citizens only (residents and non-residents). We accept cards issued outside India.)

    5. Under **Business contact information**, add your contact details so donors can reach you. (Example: [youremailid@yourdomain.com](mailto:youremailid@yourdomain.com)\<br>+9199999xxxxx\<br>Your Registered Address.)

    6. Select **Create** to publish the payment form and share the URL with your donors.

    You can view a [sample donation form](https://payments-test.cashfree.com/forms/donation-demo) to see what the final result looks like.

    If you follow all the above-mentioned steps correctly, the final output would be similar to the image below:

    <img />

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="I want to accept international payments. Can I use Cashfree to accept payments in other currencies?">
    Yes, you can use Cashfree to accept international payments in other currencies. Here are the key points:

    Cashfree offers a Global Collections feature that allows you to accept international payments from customers.
    You can accept payments in more than 17 currencies from over 180 countries. See the list of [supported currencies](/docs/payments/international-payments/global-collections/collection-accounts#supported-currencies).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title=" Can I receive international payments via PayPal using Cashfree?">
    If your business deals with customers who want to pay using PayPal, you can link your existing PayPal account to your Payment Gateway and accept payments from those customers. You can accept payments from international customers using this account.

    <Note>
      USD will be the default currency. You must complete your KYC to receive payments in INR.
    </Note>

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="I am an existing PayPal user. How do I connect my PayPal account with Cashfree?">
    Yes, if you already have an account with PayPal, you need to authorise
    Cashfree to collect payments.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="When will the payment gateway charges be deducted for my transactions?">
    For every transaction that your customers make through Cashfree, TDR will be deducted from the total amount and the remaining amount will be settled to your bank account. However, we have a postpaid model as well. See [billing configuration](/docs/payments/split/billing/configuration) to know more.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Why do I get a duplicate order ID error when a customer retries a failed payment?">
    An order ID must be unique per merchant account and can only be used once. If a [Create Order API](/docs/api-reference/payments/latest/orders/create-order) request uses an `order_id` that already exists, the API returns a `409` error (`order_already_exists`), regardless of whether the prior order is `ACTIVE`, `PAID`, or `EXPIRED`.

    Generate a new, unique order ID for each payment attempt. Multiple payment attempts (transaction IDs) can exist against the same order, but you cannot recreate the order itself with the same ID.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How do I initiate refunds in Cashfree?">
    You can initiate refunds either using our APIs or from within the **[Merchant Dashboard](https://merchant.cashfree.com/auth/login)**.
    Steps: Navigate to **Payment Gateway Dashboard → Transactions → Payments**.
    Search for the transaction you want to initiate a refund for, and select **Initiate Refund**.

    By default, the entire amount is refunded. If you issue a partial refund, ensure the partial refund option is selected and enter the desired value in INR.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title=" Can I initiate bulk refunds in Cashfree?">
    Yes, use the Batch Refunds feature to initiate refunds for a large number of payments at a time.
    Log in to the **[Merchant Dashboard](https://merchant.cashfree.com/auth/login)** and go to **Payment Gateway > Transactions > Refunds > Batch Refunds > Upload File**. Add all the required refund details in a single file as per the required format and upload the file.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How long does it take to process refunds?">
    You can check the status of an initiated refund for a transaction from the **[Merchant Dashboard](https://merchant.cashfree.com/auth/login)** and go to **Payment Gateway > Transactions > Refunds > Initiated Refunds**, and enter the corresponding Order ID.
    The refund processing time depends on the payment mode:

    * UPI: Up to 5 working days.

    * Cards: Up to 7 working days.

    * Net Banking and others: 7 to 10 working days.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What should I do before updating or displaying the status of a transaction or order to the customer?">
    Before you update or display the status of a transaction or order to the customer, complete the following steps to ensure that the status is accurate:

    1. Check the status manually in the **[Merchant Dashboard](https://merchant.cashfree.com/auth/login)**.

    Sign in to the [Cashfree Merchant Dashboard](https://merchant.cashfree.com/auth/login) to view the current status of the transaction or order. Use this method for one-time checks or if API or webhook integration isn't set up.

    2. Use the return URL flow to confirm the final status.

    After the payment reaches a final state (such as SUCCESS or FAILED), Cashfree redirects the customer to the return URL you provided. At this point, call the Get Order/Transaction Status API to confirm and display the transaction status to the customer.

    3. Handle redirection failures and delayed status changes with webhooks.

    If the return URL redirection fails or if the transaction moves from an intermediate state (such as PENDING) to a final state later, use webhook notifications to receive real-time updates. This helps ensure your system remains accurate even without redirection.

    4. Use the API to retrieve the latest status.

    To programmatically check the current status of an order, call the Get Payment Status for an Order API. Use this method to confirm the status before updating it on your system or displaying it to the customer.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Why are duplicate payments being automatically refunded by Cashfree?">
    Cashfree's system identifies duplicate successful payments received against the same order ID and triggers an automatic refund for the duplicate transaction. These automatic refunds are system-level safeguards intended to protect against duplicate or invalid captures. They differ from refunds that you initiate manually.

    There is no merchant-side configuration to disable automatic refunds globally. To prevent these scenarios, ensure each payment attempt uses a unique `order_id`, handle retry flows idempotently, and confirm the final payment status using the [Get Payments for an Order API](/docs/api-reference/payments/latest/payments/get-payments-for-an-order) or webhooks before marking an order as paid.

    <iframe title="FAQs feedback component" />
  </Accordion>
</AccordionGroup>


# Product Walkthrough
Source: https://www.cashfree.com/docs/help/payments/product-walkthrough/product-walkthrough

Get a guided product walkthrough of Cashfree Payment Gateway features, including the new dashboard, hosted checkout, payment links, refunds, and reporting.

<AccordionGroup>
  <Accordion title="Cashfree Payment Gateway - New Dashboard">
    Cashfree Payment Gateway helps businesses accept domestic and international payments, with a wide range of payment options. You can easily collect payments from your customers using our pre-built checkout integrations or customise the payment flow (Seamless Basic and Seamless Pro) for your customers in line with your business needs.

    **Accessing Your Cashfree Payment Gateway Dashboard**

    * **Log in** to your Cashfree account.
    * Navigate to **Payment Gateway** → Select **Access** to proceed.

    **Dashboard Overview**
    The **All-New Cashfree Payment Gateway Dashboard** is divided into the following parts:

    **Summary**
    The Summary section gives an overview of key metrics in the payment gateway dashboard, including daily and weekly transaction insights.
    Here, you can check the summary of:

    * **Recent Settlements**
    * **Disputed Transactions**
    * **Suspicious Transactions**
    * Total number of **Transactions & Refunds**

    Use the **Date Filter** to view details for a specific period. The **Business Metrics** provided help with informed decision-making.

    **Transactions**
    Under **Transactions**, you can see details of all payments at different stages: refunds, disputes, and suspicious transactions.

    **Payments**

    * View all received payments and their status against created orders.
    * Select a transaction to view **Customer Details** such as Name, Email, and Contact Number.
    * Use filters like **Status**, **Payment Methods**, and **Order Amount** to search for transactions.
    * To initiate a refund:
      * Select **Initiate Refund** for successful transactions.
      * For partial refunds, specify the amount and confirm.
      * Refunds are processed within 5 working days.

    **Refunds (New!)**

    * Use the Refunds tab to view all initiated refunds.
    * To check refund status, click the transaction and view its details.

    **Disputes**
    The Disputes tab lists transactions marked as disputed.

    * Disputed transactions arise when a customer questions the validity of a transaction.
    * Merchants can upload documents to validate transactions by selecting **Respond**.
    * The transaction status will be marked as **Dispute Opened** until resolved, after which it is either **Dispute Closed** or refunded to the customer.
    * Common dispute reasons include unauthorised transactions, billing errors, or dissatisfaction with goods/services.

    **Suspicious Transactions**

    * High-risk transactions are marked as **Suspicious**.
    * Details of suspicious transactions are available by selecting the transaction.

    **Settlements**
    The Settlements tab allows you to view all settlements for customer payments.

    * Use filters to find specific transactions.
    * Download settlement reports using the **Download** button.

    **Instant Settlements (New!)**

    * Gain immediate access to funds for better cash flow management.
    * To enable instant settlements, fill out the provided form.

    **Payment Links**
    Under **Payment Links**, view payments as **Received**, **Awaited**, or **Expired**.

    **Creation**

    * Create a payment link by selecting **Create Payments Link** → Enter details → Set order expiry time → Select **Create & Send**.

    **Details**

    * View transaction details, including Name, Email, and Number of the customer.
    * Track the status of the payment link on this page.
    * Reshare or edit payment links if the payment is awaiting.

    **Batch Payment Links**

    * Generate payment links for multiple transactions under the **Batch** tab.
    * Download the sample file, upload transactions, and select **Upload File**.

    **Reports**
    Cashfree offers a variety of reports for better understanding and reconciliation, such as:

    * **Transactions**, **Settlements**, **Refunds**, and **Ledger Reports**.

    **Downloading Reports**

    * Select **Report Type**, specify the period and filters, then select **Generate Report**.
    * Reports can be downloaded in CSV format.

    **API Keys**

    * Generate API keys by selecting **Generate Key** and authenticate via OTP.
    * View or reset keys through the dashboard.

    **Settings**

    * **Branding**: Customise your logo and brand colours.
    * **Payment Methods**: View and manage activated payment methods.
    * **Merchant Notifications**: Configure notifications for payments, refunds, and risk alerts.
    * **Bank Accounts**: View active and inactive settlement bank accounts.

    For testing, switch to the **Test Environment**. For queries, fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1).

    <iframe title="FAQs feedback component" />
  </Accordion>
</AccordionGroup>


# Instant Settlement
Source: https://www.cashfree.com/docs/help/payments/settlements/instant-settlements

Get answers to Cashfree instant settlement FAQs covering 15-minute payout cycles, eligibility criteria, fees, supported banks, and how to enable the feature.

<AccordionGroup>
  <Accordion title="What is an instant settlement?">
    Cashfree’s instant settlements enable you to receive funds almost instantly, with cycles starting from 15 minutes, reducing the standard T+1 or T+2 settlement periods. You must meet specific eligibility criteria. For more information, fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1).

    Instant Settlement is an advanced payment gateway feature offered by Cashfree that lets you access your funds within 15 minutes of payment capture from the customer. This will help you to respond faster to new business opportunities, and get complete control over your working capital.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How Instant Settlements will help you grow your businesses?">
    * Manage your working capital better: With instant access to your funds, you can plan your business expenditure better and drive your business towards growth. This can also help avoid the dependency on costly short-term loans to meet business needs.

    * Make fool-proof projections: You can now plan your short-term business goals better without the need to assume the revenue you are yet to receive. You can take calculated risks based on your liquidity and not shoot in the dark.

    * Handle refunds and chargebacks better: The uncertainty around the usual settlement cycles often affect transactions where the customer has requested for a refund or a chargeback immediately. With instant settlements, you get instant access to those funds and in case of refunds or chargebacks, you can happily reverse the payments instantly, without the need to incur any loss for those transactions.

      <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Are there any processing fees for Instant Settlements?">
    Yes, a nominal fee is applied for processing instant settlements.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Is there any limit on Instant Settlements?">
    Yes, We have introduced limits on Instant Settlements to streamline the settlement process and meet your daily needs. With limits, you can:

    * Settle a specified amount up to the assigned limit until the next working day.

    * Benefit from faster and higher success rates throughout the working day.

    For any queries, fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1)

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title=" How do I enable instant settlements?">
    To activate instant settlements (IS) for your account, please follow the steps below:

    * Your account already comes with a ₹50,000/- settlement limit auto-activated for instant settlements.
    * If you want to increase this limit, you can request it by [clicking here](https://merchant.cashfree.com/merchants/pg/settlements/standard). This will take you to the Merchant Dashboard, where you can request activation of instant settlements for your account.
    * Once the request is submitted, your account will be reviewed and, if eligible, instant settlements will be enabled for you.

    If you have any further queries, please reach out to us through the 24/7 [Chatbot](https://merchant.cashfree.com/common/settings?open=chat) on the Merchant Dashboard.

    <iframe title="FAQs feedback component" />
  </Accordion>
</AccordionGroup>


# Settlements
Source: https://www.cashfree.com/docs/help/payments/settlements/settlements

Understand how Cashfree settles funds to your bank account, including cycles, on-demand settlements, holds, and reconciling credits in the dashboard.

<AccordionGroup>
  <Accordion title="What are settlements?">
    Settlements refer to the process of transferring funds to your (merchant) bank account after aggregating the transaction amount and deducting our applicable charges and adjustments (Refunds, Chargebacks, etc). [Learn more about settlements](/docs/payments/manage/settlements).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are the different types of settlements?">
    The different types of settlements are as follows:

    1. **Standard settlements (Default)**: Standard settlements are processed on a T+1 or T+2 basis, depending on your configured settlement cycle:
       * T+1: The amount is settled on the next business day after the transaction.
       * T+2: The amount is settled two business days after the transaction.
         <Note>Business days exclude weekends and bank holidays. If the scheduled settlement day falls on a non-working day, the settlement will occur on the next working day.</Note>

    For example:

    * If a transaction occurs on Friday, June 3:
      * For T+1 settlement, funds will be settled on Monday, June 6, as Saturday and Sunday are non-working days.
      * For T+2 settlement, funds will be settled on Tuesday, June 7.

    2. **Instant settlements**: Instant Settlements enable you to access your funds within 15 minutes, significantly faster than the standard T+2 settlement cycle.

    3. **On-demand settlements**: On-demand settlements allow instant fund transfers to your bank 24x7, including holidays, for a small fee. Activation is required, as the default cycle is T+2 days.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How do I check settlements in my bank account?">
    Each settlement includes a Unique Transaction Reference (UTR) provided by our banking partners. You can view this number in the settlement section by clicking on a specific settlement ID. Additionally, Settlement Reports can be downloaded from the Reports section to access the UTR, which serves as a unique reference across banks for tracking specific settlements in your bank account.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Which account receives the settlement amount, and how can I view it?">
    Settlements are credited to the bank account you add when you set up your merchant account. Settlements include the total transaction value minus any applicable charges and adjustments.

    To view or manage your settlement bank account, go to **[Payment Gateway Dashboard](https://merchant.cashfree.com/merchants/pg/settings/bank-accounts?env=prod) > Settings > Bank Accounts** in your .

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="My Settlement isn't credited yet, what do I do?">
    If your settlement is scheduled for today, please wait until the end of the day (EOD).
    In the rare case of a delay from the bank’s side (such as due to network issues or public holidays), we’ll keep you informed and share updates as soon as possible.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="If my settlement failed previously, can it be attempted again?">
    If your settlement fails, it will automatically be reattempted during your next settlement cycle.
    The settlement will reinitiate only if you are an active transacting merchant, which means you must have at least one successful transaction during that cycle.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="The status of my settlement shows as failed on the Dashboard. What do I do?">
    Based on the settlement’s failure reason, take the corrective actions and this will get settled in the next settlement cycle.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How does on-demand settlement work, and what are the steps to activate it?">
    With on-demand settlements, you can request settlements to your bank account on any day and at any time 24x7, including holidays.

    You can specify the amount you want to withdraw as per your requirement. A small fee is applicable to process these settlements. On-demand settlements enable you to receive the unsettled amount to your bank account instantly 24x7 including holidays.

    By default, the settlement cycle is t+2\* days, where 't' is the day of the transaction. To use on-demand settlements, the feature must be enabled.

    <img alt="1200" />

    On-Demand Settlement Flow

    ### Activate on-demand settlements

    To enable instant settlement from the Cashfree dashboard:

    1. Go to the Payment Gateway Dashboard.
    2. Navigate to the Settlements section.
    3. Look for the On-Demand Settlements option.
       If you're eligible, you'll see options to configure On-Demand settlements.

    After activation, you can request settlements instantly 24x7 including holidays.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How to initiate On-Demand Settlements?">
    1. Go to Payment Gateway Dashboard > Settlements > On-Demand.

    2. In the On-Demand settlement screen, click Request Activation. The feature activation request will be sent to your Cashfree account manager, and they will enable it for you. You will receive an email after the feature has been activated.

    After activation, you can request settlements instantly 24x7 including holidays.

    ### Initiate on-demand settlement

    To initiate an on-demand settlement, you must first get the feature activated. After activation, you can request settlements instantly 24x7 including holidays.

    To initiate on-demand settlement,

    1. Go to Payment Gateway Dashboard > Settlements > On-Demand > click Settle Now.

    2. In the On-Demand Settlement screen, specify the amount you want to withdraw and click Confirm. You will see the amount you are allowed to withdraw and the additional charges applicable is also shown.

       <img alt="3584" />

    Settlement Amount
    You will see a success screen as shown below:

    <img alt="3584" />

    Settlement Success

    You will see all the settlements received in the Settlements > On-Demand screen. You can click the individual settlements to know more details.

    <Note>
      Settlement cycle is subject to bank approval and can vary based on transaction type, business category/model, risk parameters and other factors.
    </Note>

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Is there a bank holidays list I can refer to for settlement purpose?">
    At Cashfree, we follow the RBI's bank holiday list for Mumbai. You can refer to the [RBI bank holiday list](https://www.rbi.org.in/Scripts/HolidayMatrixDisplay.aspx). There can be other holidays that banks may observe which may vary bank to bank and state to state. We send regular updates related to settlements, to receive the emails, you can get your email ID for settlement notifications using your Cashfree Dashboard.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title=" How are settlements processed?">
    Cashfree offers you the fastest settlement cycle. By default the settlement cycle will be T+2\* days, which means a payment captured on Monday, will be credited to your account on Wednesday i.e three working days.

    <Note>
      The settlements aren't processed on banking holidays. You can refer to the [RBI's bank holiday list](https://www.rbi.org.in/Scripts/HolidayMatrixDisplay.aspx).
    </Note>

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What is an instant settlement?">
    Cashfree’s instant settlements enable businesses to receive funds almost instantly, with cycles starting from 15 minutes, reducing the standard T+1 or T+2 settlement periods. Eligibility requires meeting specific criteria. For more information, fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1).

    Instant settlement is an advanced payment gateway feature offered by Cashfree that lets you access your funds within 15 minutes of payment capture from the customer. This will help you to respond faster to new business opportunities, and get complete control over your working capital.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How instant settlements will help you grow your businesses?">
    * Manage your working capital better: With instant access to your funds, you can plan your business expenditure better and drive your business towards growth. This can also help avoid the dependency on costly short-term loans to meet business needs.

    - Make fool-proof projections: You can now plan your short-term business goals better without the need to assume the revenue you are yet to receive. You can take calculated risks based on your liquidity and not shoot in the dark.

    - Handle refunds and chargebacks better: The uncertainty around the usual settlement cycles often affect transactions where the customer has requested for a refund or a chargeback immediately. With instant settlements, you get instant access to those funds and in case of refunds or chargebacks, you can happily reverse the payments instantly, without the need to incur any loss for those transactions.

      <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Are there any processing fees for instant settlements?">
    Yes, a nominal fee is applied for processing instant settlements.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Is there any limit on instant settlements?">
    Yes, we've introduced limits on instant settlements to streamline the settlement process and meet your daily needs. With limits, you can:

    * Settle a specified amount up to the assigned limit until the next working day.

    * Benefit from faster and higher success rates throughout the working day.

    For any queries, fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1)

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title=" How do I enable instant settlements?">
    To activate instant settlements (IS) for your account, please follow the steps below:

    * Your account already comes with a ₹50,000/- settlement limit auto-activated for instant settlements.
    * If you want to increase this limit, you can [request activation on the Merchant Dashboard](https://merchant.cashfree.com/merchants/pg/settlements/standard) for your account.
    * Once the request is submitted, your account will be reviewed and, if eligible, instant settlements will be enabled for you.

    If you have any further queries, please reach out to us through the 24/7 [Chatbot](https://merchant.cashfree.com/common/settings?open=chat) on the Merchant Dashboard.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are the eligibility criteria and activation requirements for instant settlements?">
    To be eligible for instant settlements, the following conditions must be met:

    * Your merchant account must be fully onboarded and KYC-verified (business details, bank account, etc).

    * Your transaction history, business category, risk profile and bank approval must satisfy the criteria for instant settlements.

    * The feature is subject to the account being configured and the merchant being deemed eligible; once your request is submitted, it will be reviewed and enabled where applicable.

    Once enabled, you'll see the instant settlement limits and usage in **Merchant Dashboard → Payment Gateway → Settlements → Online**.

    After activation or limit-increase, you will be able to use instant settlements (funds credited within \~15 minutes) instead of the standard T+1/T+2 settlement cycle.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How do I check unsettled amount?">
    You can check the unsettled amount from the **Summary and Settlement** sections of the Merchant Dashboard.

    1. Log in to your account on the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
    2. Navigate to the **Summary** section on the Payment Gateway module. This section displays:
       * The total transaction amount for the day.
       * The amount to be settled (unsettled amount).
    3. For a detailed view:

       1. Navigate to the **Settlement** section.
       2. Select the Standard option.

       The unsettled amount will be displayed on the screen.

       <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What fields are included in Cashfree settlement reconciliation reports?">
    Cashfree settlement reconciliation reports and APIs include transaction and settlement-related details. The data contains fields such as Settlement ID, UTR, Order ID, Cashfree Payment ID, Transaction Amount, Settlement Amount, Service Charges, GST, Payment Mode, Settlement Status, and Customer Details. This allows for reconciliation at an individual order level.

    You can access settlement reconciliation data from:

    * The [Settlement Reconciliation API](/docs/api-reference/payments/latest/settlement-reconciliation/settlement-reconciliation)
    * Downloadable reports from your Merchant Dashboard under **Payment Gateway > Reports**
  </Accordion>

  <Accordion title="What do the SETTLEMENT_INITIATED and SETTLEMENT_SUCCESS statuses mean?">
    * **SETTLEMENT\_INITIATED**: This is an internal Cashfree status indicating that the settlement cycle has been triggered and the batch is being prepared. The transfer instruction has not yet been sent to the bank. Do not trigger downstream payouts based on this status.

    * **SETTLEMENT\_SUCCESS**: This means Cashfree has sent the settlement instruction to the bank and the bank has acknowledged it. This status is typically accompanied by a UTR (Unique Transaction Reference) number in the webhook payload, confirming the instruction (NEFT/IMPS/RTGS) has been submitted to the banking network.
  </Accordion>

  <Accordion title="How can I confirm that settlement funds have actually been credited to my bank account?">
    Cashfree does not receive a real-time confirmation callback from banks for final credit. The `SETTLEMENT_SUCCESS` status combined with a UTR number is the terminal confirmation event from Cashfree. To confirm actual receipt, reconcile your bank statement against the UTR number provided in the `SETTLEMENT_SUCCESS` webhook payload.

    Typical credit timelines after `SETTLEMENT_SUCCESS`:

    | Payment rail | Typical credit time |
    | :- | :- |
    | IMPS | 0–30 minutes |
    | NEFT | 30 minutes to 2 hours (depending on batch timing) |
    | RTGS | Same banking day, usually within 2 hours |
  </Accordion>

  <Accordion title="What happens if a settlement fails or is reversed?">
    Cashfree provides webhooks for failure and reversal scenarios:

    * **SETTLEMENT\_FAILED**: Triggered if the bank rejects the instruction (for example, due to incorrect account details). Funds return to Cashfree's nodal account, and a re-settlement is typically attempted in the next cycle. This event fires within a few hours of failure.
    * **SETTLEMENT\_REVERSED**: Triggered if a previously successful settlement is reversed by the bank (for example, due to compliance holds). This typically occurs within 1–3 banking days.
  </Accordion>

  <Accordion title="How do I determine if a settlement is successful when the Settlement Reconciliation API has no status field?">
    The [Settlement Reconciliation API](/docs/api-reference/payments/latest/settlement-reconciliation/settlement-reconciliation) returns event-level reconciliation rows and does not include a dedicated `status` field on `settlement_details`. If `settlement_utr` is present, treat the settlement instruction as submitted for reconciliation. To read settlement status (`SUCCESS`, `PENDING`, `PENDING_WITH_CASHFREE`, `PENDING_WITH_BANK`, or `FAILED`), use the [Get All Settlements API](/docs/api-reference/payments/latest/settlement-reconciliation/get-all-settlements).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How are settlement reversals handled, and how can I track them?">
    The Settlement Reconciliation API does not return a reversal status. Subscribe to the `SETTLEMENT_REVERSED` webhook to track reversals. For the difference between `SETTLEMENT_FAILED` and `SETTLEMENT_REVERSED`, see [Settlement Webhooks](/docs/api-reference/payments/latest/settlements/settlement-webhooks).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How can I automate my transaction and settlement reconciliation process?">
    Reconciliation has two parts: confirming each customer payment, then matching the settlement credit in your bank statement to Cashfree's UTR. Automate both with webhooks for events, reconciliation APIs for line-item data, and scheduled reports if you prefer file delivery.

    To automate the process:

    1. Subscribe to [Payment Webhooks](/docs/api-reference/payments/latest/payments/webhooks) for transaction status, and to [Settlement Webhooks](/docs/api-reference/payments/latest/settlements/settlement-webhooks) for `SETTLEMENT_SUCCESS`, `SETTLEMENT_FAILED`, and `SETTLEMENT_REVERSED`. Treat `SETTLEMENT_SUCCESS` and `settlement_utr` as Cashfree's terminal event, then match that UTR to your bank statement.
    2. Call the [Settlement Reconciliation API](/docs/api-reference/payments/latest/settlement-reconciliation/settlement-reconciliation) after a settlement webhook, using the settlement ID, UTR, or date range. The response includes customer, order, payment, and `settlement_utr` on each event row. Use the [Get All Settlements API](/docs/api-reference/payments/latest/settlement-reconciliation/get-all-settlements) when you need settlement `status`.
    3. Use the [PG Reconciliation API](/docs/api-reference/payments/latest/pg-reconciliation/pg-reconciliation) when you need payment-account events for a date range.
    4. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and go to **Payment Gateway > Reports > Schedule Reports**. Schedule **Settlement Reconciliation** and **Transactions** reports over SFTP (Secure File Transfer Protocol) instead of polling APIs. See [Schedule Reports](/docs/payments/manage/schedule-reports).

       <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How do I use the Settlement Reconciliation API, and what version should I use?">
    Use the [Settlement Reconciliation API](/docs/api-reference/payments/latest/settlement-reconciliation/settlement-reconciliation) (`POST /settlement/recon`) to fetch settlement reconciliation details. It uses standard `x-client-id` and `x-client-secret` authentication. No separate enablement is required. Pass `x-api-version: 2026-01-01`.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are the rate limits and recommended date windows for the Settlement Reconciliation API?">
    The [Settlement Reconciliation API](/docs/api-reference/payments/latest/settlement-reconciliation/settlement-reconciliation) uses cursor-based pagination. The default `pagination.limit` is 10. The maximum is 1000, though your account configuration can set a lower maximum.

    For historical backfills, keep each date window short (for example, 1 to 7 days) and page through results using the cursor returned in the response.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How can I identify the MDR and GST charged for a specific transaction in the settlement reconciliation report?">
    In the Settlement Reconciliation API response, use the following fields:

    * `event_service_charge`: the MDR amount for that transaction.
    * `event_service_tax`: the GST charged on that MDR.

    The net settlement amount is calculated as:

    ```text theme={"dark"}
    event_settlement_amount = event_amount - event_service_charge - event_service_tax
    ```

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How do I verify the signature for Cashfree settlement webhooks?">
    Settlement webhooks use the same signature headers as other Cashfree Payments webhooks. Verify the `x-webhook-signature` against the timestamp and raw request body before you process the payload.

    For the full procedure and code samples, see [Webhook signature verification](/docs/payments/online/webhooks/signature-verification).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What event types are used in the Settlement Reconciliation API to distinguish between payments, refunds, and disputes?">
    The Settlement Reconciliation API uses the `event_type` field to categorise transactions. Possible values are:

    | `event_type` | Description |
    | - | - |
    | `PAYMENT` | Successful payment credit |
    | `REFUND` | Refund debit from settlement |
    | `REFUND_REVERSAL` | Reversal of a refund |
    | `DISPUTE` | Dispute debit |
    | `DISPUTE_REVERSAL` | Reversal of a dispute |
    | `CHARGEBACK` | Chargeback debit |
    | `CHARGEBACK_REVERSAL` | Reversal of a chargeback |
    | `OTHER_ADJUSTMENT` | Manual or other adjustments |

    For refund records, `sale_type` is `DEBIT` and `bank_reference` contains the refund UTR.

    <iframe title="FAQs feedback component" />
  </Accordion>
</AccordionGroup>


# Transaction Reports
Source: https://www.cashfree.com/docs/help/payments/transaction-reports/transaction-reports

Find answers to transaction report FAQs covering report types, custom filters, download formats, column definitions, and reconciling payment activity quickly.

<AccordionGroup>
  <Accordion title="What are the different transaction status in Cashfree?">
    When customers initiate a payment, there are various states that the transaction may go through before reaching your account. After the customer initiates a payment, the transaction can go to either of the following:

    * **SUCCESS**
    * **FAILURE**
    * **VOID**
    * **INCOMPLETE**
    * **PENDING**
    * **FLAGGED**
    * **CANCELLED**
    * **USER\_DROPPED**

    See the [payment lifecycle](/docs/payments/online/resources/payment-lifecycle) to know more about each of these states.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How do I track my transactions?">
    As soon as you log in to your Cashfree account, the Summary section in the payment gateway dashboard will give you instant context as to what is the amount of transaction that has happened on that particular day, and the settlement amount that you’re yet to receive. Besides this, Cashfree also provides a wide range of reports to analyse your business finances. The different reports that Cashfree provides you are,

    * Transactions Report
    * Settlement Reconciliation Report
    * Settlement Summary
    * Refunds Report
    * Ledger Report
    * Monthly Invoices

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I track the amount of daily transactions in Cashfree?">
    Yes. With Cashfree, you can receive specific reports such as **Transaction reports**, **Settlements**, and **Adjustment reports** directly into your own SFTP servers or Cashfree's SFTP servers at a set frequency every day.
    If you'd like Cashfree to push out the reports to your own SFTP servers, please fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can Cashfree send reports to my own SFTP servers?">
    Yes. With Cashfree, you can receive specific reports such as **Transaction reports**, **Settlements**, and **Adjustment reports** directly into your own SFTP servers or Cashfree's SFTP servers at a set frequency every day.
    If you'd like Cashfree to push out the reports to your own SFTP servers, please fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I add custom fields like roll number or institute code to a payment and see them in my reconciliation report?">
    Yes. Pass the fields you need as key-value pairs in the `order_tags` object when calling the [Create Order API](/docs/api-reference/payments/latest/orders/create). Up to three tags per order appear in the Settlement Recon Report under columns `Key_1`/`Value_1`, `Key_2`/`Value_2`, and `Key_3`/`Value_3` in the Transaction details section. Although you can pass up to 10 tags per order, only three are surfaced in the report. Use keys that match your reconciliation process—for example `institute_code`, `roll_number`, and `division` for education and multi-institute fees, or identifiers such as `branch_id`, `campaign_id`, or `invoice_ref` for other businesses. Include only the fields you need and keep your `order_tags` object to three keys.

    <iframe title="FAQs feedback component" />
  </Accordion>
</AccordionGroup>


# General
Source: https://www.cashfree.com/docs/help/payments/transactions/generalfaqs

Find general answers to Cashfree transaction FAQs about order creation, payment statuses, failure reasons, retries, and reconciliation across all channels.

<AccordionGroup>
  <Accordion title="Is Cashfree PCI DSS compliant?">
    The **Payment Card Industry Data Security Standard (PCI DSS)** is an information security standard for organisations that handle branded credit cards from major card schemes.

    The PCI Standard is mandated by the card brands and administered by the **Payment Card Industry Security Standards Council**. The standard was created to increase controls around cardholder data to reduce credit card fraud.

    **Cashfree** is PCI DSS compliant. Access the [PCI DSS certificate](https://cashfreelogo.cashfree.com/website/pdf/Cashfree-PCI-DSS-COC.pdf).

    While PCI DSS compliance is a pre-requisite for payment acceptance, we have gone a step further and incorporated a very robust **Risk Management System** developed with help from **PayPal**.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are the different payment methods supported by Cashfree's Payment Gateway?">
    **Cashfree Payment Gateway** supports multiple payment methods, giving greater flexibility to your customers to complete payments using the payment method of their choice.

    **Supported Payment Methods**

    * Credit/Debit Card/Prepaid
    * UPI
    * Netbanking
    * Wallets
    * PayPal
    * EMI
    * Pay Later

    **Customise Payment Methods**
    With Cashfree Payment Gateway, you can choose to display only the payment methods relevant to your business.\
    Fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) to add or remove any payment methods.\
    See [supported currencies](/docs/payments/global-collections/collection-accounts#supported-currencies) to see all the currencies supported.

    **Payment Response**
    You will receive responses for every payment made by your customers. These details can be viewed in the **dashboard** against each transaction.\
    See [payment methods](/docs/payments/manage/payment-methods/overview#supported-payment-methods) to view all possible payment response statuses.

    **Payment Modes**
    Below is a detailed list of all supported payment modes and their respective codes:

    | Code | Description |
    | - | - |
    | DEBIT\_CARD | Debit Card |
    | CREDIT\_CARD | Credit Card |
    | PREPAID\_CARD | Prepaid Card |
    | CREDIT\_CARD\_EMI | Credit Card EMI |
    | NET\_BANKING | Internet Banking |
    | UPI | UPI |
    | PayPal | PayPal |
    | PhonePe | PhonePe |
    | Paytm | Paytm |
    | AmazonPay | Amazon Pay |
    | AIRTEL\_MONEY | Airtel Money Wallet |
    | FreeCharge | Freecharge Wallet |
    | MobiKwik | MobiKwik Wallet |
    | OLA | Ola Wallet |
    | JioMoney | JioMoney Wallet |
    | ZestMoney | ZestMoney |
    | Instacred | Instacred |
    | LazyPay | LazyPay |
    | OlaPostpaid | Ola Postpaid |

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Where can I find test bank account numbers for the sandbox environment?">
    Find and test bank account numbers and other sandbox test data for cards, Netbanking, UPI, wallets, EMI, Pay Later, and Cardless EMI on the [Data to Test Integration](/docs/api-reference/payments/data-to-test-integration) page.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are the different payment response statuses for the payment?">
    There are various states that the payment goes through. The various states help you understand the status of the payment made by your customers.

    * **SUCCESS**
    * **FAILED**
    * **PENDING**
    * **CANCELLED**
    * **FLAGGED**
    * **INCOMPLETE**
    * **VOID**
    * **USER\_DROPPED**

    ### Payment Response Status

    Cashfree send responses against the payments made by your customers. The response against these payments made could contain one of the following statuses.

    | Case | Event name | Event status |
    | :- | :- | :- |
    | Successful Payment | PAYMENT\_RESPONSE | SUCCESS |
    | Payment Failed | PAYMENT\_RESPONSE | FAILED |
    | Pending Payment | PAYMENT\_RESPONSE | PENDING |
    | Payment cancelled by the user | PAYMENT\_RESPONSE | CANCELLED |
    | Payment successful but kept on hold by risk system | PAYMENT\_RESPONSE | FLAGGED |
    | Transactions are marked as Incomplete, which later changes to other states based on the responses from other entities. | PAYMENT\_RESPONSE | INCOMPLETE |
    | When we do not want to capture the transaction amount (pre-authorized transactions). | PAYMENT\_RESPONSE | VOID |
    | When customers drop out of the payment flow without completing the transaction. | PAYMENT\_RESPONSE | USER\_DROPPED |
    | Invalid inputs | VALIDATION\_ERROR | |

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What is the checkout experience offered by Cashfree's PG like?">
    A seamless checkout is key to customer trust. Redirects and pop-ups? They create confusion and hurt conversions. Big brands offer smooth payments, but not everyone has their resources.\
    That’s where Cashfree comes in! We provide easy integrations for a fast, hassle-free checkout—built for businesses of all sizes. Cashfree offers a seamless checkout experience with:

    No Redirects – Customer experiences checkout flow on your website without navigating to any third-party page

    Custom UI – You own the look and feel of the checkout flow or you can also use our ready-made beautiful UI components

    One-Click Checkout – Enable fast, hassle-free payments with a single click.

    [Sign-Up](https://merchant.cashfree.com/auth/login) to see our payment gateway in action!

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What is a Chargeback?">
    Businesses accepting payments via cards may face a situation where a **chargeback request** is raised for a refund to the customer.
    **What is a chargeback?**
    A chargeback is a request for the return of funds to a consumer, initiated by the consumer's card-issuing bank.
    It serves as a form of consumer protection against fraudulent activities committed by both merchants and individuals.

    <Note>
      It is best to avoid chargebacks as banks and card networks can label your business as high-risk. A high number of chargebacks may lead to banks holding remittances or banning your business's online payment services.
    </Note>

    **Key Parties Involved in a Chargeback**

    * **Cardholder:** The owner of the card involved in the transaction.
    * **Merchant:** The party who sold the goods or services being disputed.
    * **Issuer:** The bank that issued the card to the cardholder.
    * **Acquirer:** The bank tasked with acquiring payment on the merchant’s behalf.
    * **Card Association/Scheme:** The card brands (e.g., Visa, Mastercard) overseeing the process.
    * **Payment Gateway:** The payment gateway facilitating the payment.

    **Reasons for a Chargeback Request**
    A chargeback request may be raised for various reasons, such as:

    * Service or product not received.
    * The product doesn’t match the description or is damaged.

    **How Does the Chargeback Process Work?**

    1. The **cardholder** (Ms. X) disputes a transaction by contacting the **card issuer** (e.g., SBI).

    * The issuer contacts the **acquirer** (e.g., HDFC Bank) via the same network used for the transaction.
    * The acquirer reaches out to the **payment gateway** (e.g., Cashfree), which then contacts the **merchant** (e.g., merchant.com) for details.

    2. The merchant is given a **turnaround time** to respond.

    * If no response is provided, the chargeback will be ruled in favour of the cardholder.

    3. After submitting proof, banks take **21 to 45 days** (representation time) to conclude.

    4. The cardholder has **90-120 days** to raise a chargeback request.

    5. If a chargeback occurs, the disputed amount will be **blocked** from the merchant's unsettled funds and will be released or refunded based on the outcome.

    **Chargeback Scenarios**

    **Scenario 1: The merchant decides to respond**
    The merchant must provide evidence related to the transaction, such as:

    * Email conversations
    * Invoices

    This proof is passed to the **issuer (e.g., SBI)** for review.

    1. **If the issuer accepts the proof:**

    * The chargeback request is declined, but the cardholder can still raise a **Second Presentment, Second Chargeback (Mastercard)** or **Pre-Arbitration (Visa)**.

    2. **If the issuer rejects the proof:**

    * The chargeback is ruled valid, and funds are reversed to the cardholder’s account.

    **Scenario 2: The merchant decides not to respond**

    * The chargeback is automatically ruled in favour of the cardholder, and the amount is reversed.

    **Second Presentment, Second Chargeback, or Pre-Arbitration**
    If the initial chargeback is won by the merchant, the customer can raise the dispute again.

    * The **merchant must respond** with all possible evidence.
    * **If the merchant does not respond:** The chargeback will favour the cardholder, and funds will be reversed.

    **Documents Required to Dispute a Chargeback**
    Merchants should keep the following documents ready to tackle any chargeback:

    * **Proof of delivery:** Tracking numbers, shipping receipts, etc.

    <Tip>
      Prepare these documents from day one to efficiently handle potential chargebacks.
    </Tip>

    **Invoice copy**: This should include your company name, price, and description of the product, date, customer’s name and address, date.

    **Order confirmation email**: This email provides customers with post-purchase reassurance. It should mandatorily include confirmation of your customer’s request (booking, registration, subscription and order) and the order summary.

    **Tracking details**: Shipment tracking details provided by the courier delivery company (Not applicable for all).

    Finally, we are near the end of the chargeback process. The **issuer reviews the chargeback claim** and the merchant's evidence. Each card network requires specific information to prove or disprove a dispute. This information is typically listed in the network’s rules and regulations.

    Let’s say the merchant wins a chargeback. The cardholder could still dispute the outcome. This takes on various names depending on the card network. For example, Visa calls this **Pre-Arbitration**, while Mastercard calls it a **Second Chargeback**. However, the process is essentially the same, as detailed below:

    **Level 1/Phase 1: Chargeback**\
    The initial phase where the cardholder disputes the transaction.

    **Level 2/Phase 2: Second Presentment, Second Chargeback, or Pre-Arbitration**\
    This gives the acquirer and the issuer a second chance to resolve the dispute. An issuer may issue pre-arbitration for several reasons, including:

    * A reason code change.
    * The cardholder offers new information.
    * The issuer believes the acquirer’s evidence does not disprove the dispute.
    * Terms and Conditions or Return Policies were not properly disclosed during the transaction.

    **Level 3/Phase 3: Arbitration**\
    Explicit time limits exist for issuers and acquirers to file for and respond to arbitration chargebacks. For example, Mastercard gives issuers and acquirers **45 days** to file. However, documents must be submitted well in advance to allow for thorough review.

    For more information on arbitration rates, refer to the [link](https://chargebacks911.com/arbitration-chargeback/).

    There are **151 reason codes** used to categorise chargebacks across Visa, Mastercard, and American Express.

    Reason codes can be grouped into five main categories:

    * **Fraud/No Authorization**
    * **Cancel Recurring Billing**
    * **Products/Services**
    * **Liability Shift**
    * **Others**

    <Note>
      Fraud/No Authorization chargebacks account for the largest percentage of disputes, followed by Cancel Recurring Billing and Products/Services disputes. Liability Shift and Other chargebacks represent a smaller percentage.
    </Note>

    For a detailed breakdown, refer to the [link](https://chargeback.com/5-chargeback-reason-code-categories/).

    **As a business, how can I avoid chargebacks?**

    * Cardholders often have an advantage as banks and credit card companies prioritise consumer protection.
    * Always maintain proof/evidence to challenge disputes. Store these documents in an easily accessible location, like a desktop folder or Google Drive.
    * Respond promptly to disputes and chargebacks. If you miss the stipulated time frame, banks automatically process the chargeback.
    * Be prepared with an action plan to handle chargebacks efficiently.

    **Questions?**\
    We're always happy to help with any questions you might have. Search our documentation, [contact support](https://www.cashfree.com/en/report-issue/), or [connect with our sales team](https://www.cashfree.com/contact-sales/). You can also chat with our team via chat for real-time support.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How do I check, if I am eligible for accepting payments from Rupay credit cards on UPI payments?">
    Almost all businesses are by default eligible to receive payments via Rupay credit card.

    <Note>
      Merchants with MCCs such as mutual fund providers, stock brokers, loan
      repayment, etc., are not eligible to accept credit payments.
    </Note>

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Why doesn't UPI appear as a payment option for a high-value order?">
    NPCI (National Payments Corporation of India) sets UPI per-transaction limits that vary by merchant category code (MCC). For some categories, such as drug stores and pharmacies, the standard NPCI limit is ₹1 lakh per transaction. If the order amount exceeds the NPCI UPI limit for your MCC, UPI does not appear as a payment option at checkout. NPCI sets this limit, not Cashfree, and it cannot be overridden, so offer alternative payment methods for high-value transactions in affected categories.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What is Pre Authorization?">
    Pre-Authorization lets you block a customer’s funds and capture the payment only after fulfilling the order.

    Supported cards: Works with Mastercard and Visa credit or debit cards.

    Flexible captures: Capture the full or partial amount later.

    Void transactions: Release blocked funds if the order isn’t processed.

    Easy control: Manage captures and voids manually via the [Merchant Dashboard](https://merchant.cashfree.com/merchants).
    A smarter way to handle payments with more control.

    Interested in the Pre-Authorization feature?
    [Contact sales](https://www.cashfree.com/contact-sales/)

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Which are the sponsor banks live on pre-authorisation?">
    The following sponsor banks currently support the pre-authorisation feature on Cashfree:

    * Axis Bank
    * HDFC Bank
    * ICICI Bank
    * IndusInd Bank
    * Kotak Mahindra Bank
    * Yes Bank
    * Federal Bank
    * State Bank of India
  </Accordion>

  <Accordion title="How to fix Failed to Verify Credentials?">
    If you are getting this error, it usually means you are using Production credentials on the Cashfree Test server or Test credentials on the Production server. To fix this, do the following:

    * Go to the page where you get API credentials: [https://merchant.cashfree.com/merchant/pg#api-key](https://merchant.cashfree.com/merchant/pg#api-key)
    * Ensure that you get the appropriate set of credentials (Test or Production). Also, verify that there are no typos in the `appId`/`secretKey`.
    * Ensure that in your integration type, you are selecting the correct server (Test or Production) of Cashfree.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="I get a warning that my webhook endpoint did not respond properly to the test. Is my webhook broken?">
    No, this warning does not block your webhook from working. When you add a webhook endpoint URL in the Merchant Dashboard, Cashfree sends it a test POST request to confirm it is reachable and returns HTTP 200. If your endpoint returns a different response to that test request, this warning appears, but Cashfree still saves the webhook URL and delivers live events to it. Ensure your endpoint returns HTTP 200 to POST requests, including test payloads, to clear the warning.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How do I delete an existing webhook configuration from the Merchant Dashboard?">
    Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login), go to **Developers > Webhooks**, locate the webhook endpoint you want to remove, and select the delete option for that entry.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are the different ways I can set up the payment gateway for my business?">
    Cashfree lets you integrate your [website](/docs/payments/online/web/redirect) or [mobile app](/docs/payments/online/mobile/android) with our payment gateway to accept payments. Over and above this, we also offer [plugins](/docs/payments/plugins/overview) to major e-commerce sites like [Shopify](https://apps.shopify.com/cashfree-payments), [Magento](https://marketplace.magento.com/cashfree-magento2-payment.html), [WooCommerce](https://wordpress.org/plugins/cashfree/), [OpenCart](https://www.opencart.com/index.php?route=marketplace/extension/info\&extension_id=37574), [PrestaShop](https://addons.prestashop.com/en/payment-card-wallet/50547-cashfree.html), and [WHMCS](https://marketplace.whmcs.com/product/5045-cashfree-payment-gateway). See [Cashfree-hosted checkout](/docs/payments/online/web/redirect) to know more.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are the different web integrations possible with Cashfree?">
    There are three types of web integrations possible with Cashfree:

    * [Checkout Forms](https://www.cashfree.com/docs/payment-gateway/checkout-forms)
    * [Seamless Basic](https://www.cashfree.com/docs/payment-gateway/seamless-basic)
    * [Seamless Pro](https://www.cashfree.com/docs/payment-gateway/seamless-pro)

    You can instantly set up any of these based on your requirements.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How do I become eligible for the Server-to-Server (S2S) seamless payment flow or Checkout URL API?">
    <Warning>
      The eligibility criteria below are pending verification against the current API specification. Confirm the exact requirements with your Cashfree account manager before submitting documents.
    </Warning>

    Eligibility depends on the payment mode. For card payments, submit a PCI-DSS compliance certificate. For all other payment modes, submit a GST return showing an annual turnover of more than ₹1 crore. Once Cashfree verifies the relevant document, the team enables the corresponding S2S flag on your account. Without this, only the standard hosted checkout is available.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What does the 'S2S Integration' label mean in the dashboard's Order Source field?">
    Orders created through the [Create Order API](/docs/api-reference/payments/latest/orders/create) receive this label. This does not indicate that your account has an active Server-to-Server seamless payment flow enabled. Any order you create programmatically via the API gets this label, regardless of which checkout mode the customer uses to pay.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What is the difference between S2S Integration and Next Gen API integration types in the Merchant Dashboard?">
    In the Merchant Dashboard, the integration type reflects how the payment was initiated:

    * **Next Gen API**: The payment was completed via the Next Gen Checkout flow using a frontend Web SDK (for example, `cashfree.checkout()`) and a `payment_session_id`. The flow is: order created on the backend → checkout opened on the client using the JS SDK → customer pays.
    * **S2S Integration**: The payment was initiated server-to-server from your backend using the Seamless / Order Pay flow (for example, `POST /orders/{order_id}/pay`) instead of launching the frontend checkout SDK.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Why do I see different integration types like S2S and Next Gen API for payments in my account?">
    Mixed integration labels depend on how a specific payment attempt was initiated rather than the payment status. Common reasons include:

    1. Your codebase supports both flows and routes traffic differently based on the channel, app, or webview.
    2. The frontend SDK failed to load (due to network, CSP, or ad-blocker issues), causing your system to fall back to an S2S pay call.
    3. Different products or modules within your system are using different Cashfree integration methods.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="If a refund was not initiated manually, how can I identify its source?">
    If a refund is initiated through an API rather than the Merchant Dashboard, Cashfree sets the refund's `refund_type` field to `MERCHANT_INITIATED` in the [Create Refund API](/docs/api-reference/payments/latest/refunds/create-refund) response. Check your application logs, scheduled jobs, or automated workflows to identify which API key or service triggered the request.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How do I generate API keys for the Cashfree test environment?">
    Test environment API credentials are self-serve and can be generated directly from the Merchant Dashboard:

    1. Log in to your [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
    2. Switch to the Test/Sandbox environment.
    3. Navigate to the **API Keys / Developer Settings** section.
    4. Generate or copy the Client ID (App ID) and Client Secret.

    Ensure that test credentials are used only with sandbox/test API endpoints, and production credentials are used only with the production environment.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Why are some payment options like cards or net banking hidden on the checkout page?">
    Cashfree's checkout experience is optimised for conversion by showing the most popular methods such as UPI and COD upfront. Other payment modes such as Cards, Wallets, and Net Banking are accessible under the **More** or **Cards / Wallets / Netbanking & more** option. If a payment instrument is already saved with Cashfree, it may also be shown upfront.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I integrate Cashfree payment gateway to my Shopify website?">
    Yes, we provide a predefined plugin for [Shopify](/docs/payments/shopify/payments) that helps you set up the Cashfree payment gateway with your Shopify account in no time, and with absolutely no code.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I integrate Cashfree payment gateway to my Magento website?">
    Yes, we provide a predefined plugin for [Magento](/docs/payments/plugins/magento) that helps you set up the Cashfree payment gateway with your Magento account in no time, and with absolutely no code.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I integrate Cashfree payment gateway to my Woo-Commerce website?">
    Yes, we provide a predefined plugin for [WooCommerce](/docs/payments/plugins/woocommerce) that helps you set up the Cashfree payment gateway with your WooCommerce account in no time, and with absolutely no code.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I integrate Cashfree payment gateway to my OpenCart website?">
    Yes, we provide a predefined plugin for [OpenCart](https://www.cashfree.com/docs/plugins/opencart) that helps you set up the Cashfree payment gateway with your OpenCart account in no time, and with absolutely no code.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I integrate Cashfree payment gateway to my PrestaShop website?">
    Yes, we do provide a predefined plugin for [PrestaShop](/docs/payments/plugins/prestashop) that helps you set up the Cashfree payment gateway with your PrestaShop account in no time, and with absolutely no code.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I integrate Cashfree payment gateway to my WHMCS website?">
    Yes, we do provide a predefined plugin for [WHMCS](https://www.cashfree.com/docs/plugins/whmcs) that helps you set up the Cashfree payment gateway with your WHMCS account in no time, and with absolutely no code.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I receive payments from my customers without integrating Cashfree to my website?">
    You can use the [Cashfree Payment Gateway Dashboard](https://www.cashfree.com) to create orders and accept payments using a **payment link**. These links can be sent to your customers via email or SMS, without the need to integrate Cashfree into your website.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What documents to be submitted as a proof of delivery?">
    **Invoice copy:** Every invoice should include your company name, price, and description of the product, date, customer’s name, and address, contact information (Email and/or phone), and transaction date.
    **Order confirmation email:** Confirmation emails provide customers with the feeling of post-purchase reassurance. It should mandatorily include confirmation of your customer request (booking, registration, subscription, and order) and the order summary.
    **Tracking details:** Shipment tracking details provided by the courier delivery company. (Please note that this may not be applicable for all).

    The above mentioned supporting documents are the general proofs that we request. Depending upon the nature of business/line of business (LOB), we may ask for other details such as:

    * **Customer signed Proof of Delivery:** Customer signed copy of proof of delivery.
    * **Confirmation email from a customer:** An email from the customer confirming the delivery of the product or the service provided.
    * **Customer signed copy of invoice:** A signed copy of the invoice from a customer.

    **Questions?**
    We're always happy to help you with any questions that you might have. You can search our FAQs, documentation, contact our support team, [connect with our sales team](https://www.cashfree.com), or fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1). You could also chat with our team via Intercom for real-time support.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="I run an NGO. How can I use Cashfree to accept donations?">
    Cashfree provides you with the flexibility to create **Payment Forms**, a no-code solution that your customers can use to pay any amount of their choice to your account.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="I want to accept international payments. Can I use Cashfree to accept payments in other currencies?">
    Yes, Cashfree supports a wide range of international payment options via credit cards and also PayPal.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="I am an existing PayPal user. How do I connect my Paypal account with Cashfree?">
    Yes, if you already have an account with PayPal, you need to authorise Cashfree to collect payments. Visit the [Cashfree website](https://www.cashfree.com) to know more.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="When will the payment gateway charges be deducted for my transactions?">
    For every transaction processed through Cashfree, either of the following charges applies:

    1. Upfront TDR–A fixed charge collected at a predefined frequency.
       OR
    2. Non-Upfront TDR–A charge deducted as a percentage (TDR%) or a flat fee from the transaction amount, with the remaining balance settled to your bank account.

       For every transaction that your customers make through Cashfree, TDR will be deducted from the total amount and the remaining amount will be settled to your bank account.

       <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How long does it take to process refunds?">
    You can initiate a refund for a transaction from the payment gateway dashboard by going to **PG Dashboard** > **Refunds** > **NEW REFUND** and providing the corresponding transaction ID or order ID. Once the refund is initiated, it will take 5-7 business days for the amount to be credited to your account.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What documents to be submitted as a proof of delivery?">
    **Invoice copy:** Every invoice should include your company name, price, and description of the product, date, customer’s name, and address, contact information (Email and/or phone), and transaction date.

    **Order confirmation email:** Confirmation emails provide customers with the feeling of post-purchase reassurance. It should mandatorily include confirmation of your customer request (booking, registration, subscription, and order) and the order summary.

    **Tracking details:** Shipment tracking details provided by the courier delivery company. (Please note that this may not be applicable for all).

    The above-mentioned supporting documents are the general proofs that we request. Depending upon the nature of business/line of business (LOB), we may ask for other details such as:

    * **Customer signed Proof of Delivery:** Customer signed copy of proof of delivery.
    * **Confirmation email from a customer:** An email from the customer confirming the delivery of the product or the service provided.
    * **Customer signed copy of invoice:** A signed copy of the invoice from a customer.

    **Questions?**\
    We're always happy to help you with any questions that you might have. You can search our FAQs, documentation, contact our support team, [connect with our sales team](https://www.cashfree.com), or fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1). You could also chat with our team via Intercom for real-time support.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are terms and conditions for activating Payment Gateway">
    Before we activate Cashfree Payment Gateway on a website or mobile app, we need a few prerequisites in place.

    1. Your website should be live in the public domain.
    2. Your website should have:
    3. \[Contact Us] section showing a valid `<email Id>` and a `<phone number>`
    4. \[Privacy Policy] section
    5. \[Refund Policy] section
    6. \[Terms & Conditions] section.
    7. Dealing in banned items.

    At Cashfree, we do not support businesses that deal in certain prohibited items. If your business deals in any such items, Cashfree Payment Gateway Account will not be activated in such a scenario.

    * Drop-shipped merchandise.
    * Adult goods and services which includes pornography and other sexually suggestive materials (including literature, imagery, and other media); escort or prostitution services.
    * Alcohol which includes alcoholic beverages such as beer, liquor, wine, or champagne.
    * Body parts which includes organs or other body parts.
    * Bulk marketing tools which includes email lists, software, or other products enabling unsolicited email messages (spam).
    * Cable descramblers and black boxes which includes devices intended to obtain cable and satellite signals for free.
    * Child pornography which includes pornographic materials involving minors.
    * Copyright unlocking devices which includes Mod chips or other devices designed to circumvent copyright protection.
    * Copyrighted media which includes unauthorised copies of books, music, movies, and other licensed or protected materials.
    * Copyrighted software which includes unauthorised copies of software, video games, and other licensed or protected materials, including OEM or bundled software.
    * Counterfeit and unauthorised goods which includes replicas or imitations of designer goods; items without a celebrity endorsement that would normally require such an association, fake autographs, counterfeit stamps, and other potentially unauthorised goods.
    * Drugs and drug paraphernalia which includes illegal drugs and drug accessories, including herbal drugs like salvia and magic mushrooms.
    * Drug test circumvention aids which include drug cleansing shakes, urine test additives, and related items.
    * Endangered species which include plants, animals, or other organisms (including product derivatives) in danger of extinction.
    * Gaming/gambling which includes lottery tickets, sports bets, memberships/enrolment in online gambling sites, and related content.
    * Government IDs or documents which includes fake IDs, passports, diplomas, and noble titles.
    * Hacking and cracking materials which includes manuals, how-to guides, information, or equipment enabling illegal access to software, servers, websites, or other protected property.
    * Illegal goods which includes materials, products, or information promoting illegal goods or enabling illegal acts.
    * Miracle cures which includes unsubstantiated cures, remedies, or other items marketed as quick health fixes.
    * Offensive goods which includes literature, products or other materials that:\
      a) Defame or slander any person or groups of people based on race, ethnicity, national origin, religion, sex, or other factors\
      b) Encourage or incite violent acts\
      c) Promote intolerance or hatred.
    * Offensive goods, a crime which includes crime scene photos or items, such as personal belongings, associated with criminals.
    * Prescription drugs or herbal drugs or any kind of online pharmacies which includes drugs or other products requiring a prescription by a licensed medical practitioner.
    * Pyrotechnic devices and hazardous materials which include fireworks and related goods; toxic, flammable, and radioactive materials and substances.
    * Regulated goods which include airbags; batteries containing mercury; Freon or similar substances/refrigerants, chemical/industrial solvents, government uniforms, car titles or logos, license plates, police badges, and law enforcement equipment, lock-picking devices, pesticides; postage meters, recalled items, slot machines, surveillance equipment; goods regulated by government or other agency specifications.
    * Securities, which include stocks, bonds, or related financial products.
    * Tobacco and cigarettes which includes cigarettes, cigars, chewing tobacco, and related products.
    * Traffic devices which include radar detectors/jammers, license plate covers, traffic signal changers, and related products.
    * Weapons include firearms, ammunition, knives, brass knuckles, gun parts, and other armaments.
    * Wholesale currency which includes discounted currencies or currency exchanges.
    * Live animals or hides/skins/teeth, nails, and other parts, etc. of animals.
    * Multi-Level Marketing collection fees.
    * Matrix sites or sites using a matrix scheme approach.
    * Work-at-home information.
    * Any product or service which is not in compliance with all applicable laws and regulations whether federal, state, local, or international including the laws of India.
    * The Merchant shall not sell, purchase, provide or exchange a cardholder’s name or MasterCard/Visa account number information in any form obtained by reason of a MasterCard/Visa Card transaction to any third party other than its MasterCard/Visa acquiring Member-Citrus Pay, or pursuant to a government/statutory or competent body’s request.
    * Pyrotechnic devices, combustibles, corrosives, and hazardous materials which includes explosives, fireworks and related goods; toxic, flammable, and radioactive materials and substances.
    * Regulated goods which include airbags; batteries containing mercury; Freon or similar substances/refrigerants; chemical/industrial solvents; government uniforms; car titles; license plates; police badges and law enforcement equipment; lock-picking devices; pesticides; postage meters; recalled items; slot machines; surveillance equipment; goods regulated by government or other agency specifications.

    <Warning>
      In case the Cashfree Payment Gateway has been activated and later it is found that the business or the website does not comply with the terms and conditions, the account shall be deactivated at Cashfree's discretion.
    </Warning>

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are High Risk Transactions & High Risk Merchants">
    **What are high-risk transactions?**

    A particular transaction that may have the potential to attract a customer dispute or chargeback is identified by Cashfree as well as banking partners and marked as a high-risk transaction. The payment to the merchant against such a transaction is put on hold until the issue is resolved.

    **Who are high-risk merchants?**\
    As a payment gateway, Cashfree generally settles the collected amount within T+1\* or T+2\* days. However, some merchants may not qualify for the traditional payment processing agreements due to the inherent risk based on the nature of the business.

    In addition to the line of business, there may be instances where Cashfree receives frequent escalations from consumers or banks about the genuineness of transactions or financial credibility, based on risk analysis. In such cases, Cashfree may mark the business as a high-risk merchant and temporarily suspend the traditional payment settlement process.

    **High-risk merchants at the time of onboarding**\
    If the nature of the business is seen as risky, to protect the interest of the paying consumer, Cashfree monitors the merchant for a certain period after onboarding. During this period, all settlements by the high-risk merchant shall be subject to the submission of Proof of Delivery. Once the proofs are submitted, the settlements are processed. The time frame of monitoring may vary from merchant to merchant and scenario to scenario, and will be decided by Cashfree at the time of onboarding.

    **What are the documents required to prove delivery?**\
    As proof of delivery, you can share ANY ONE of the following supporting documents:

    1. **Invoice Copy**: Every invoice should include your company name, price, and description of the product, date, customer’s name and address, and transaction date.
    2. **Order Confirmation Email**: Confirmation emails provide customers with post-purchase reassurance. It should mandatorily include confirmation of your customer request (booking, registration, subscription, and order) and the order summary.
    3. **Tracking Details**: Shipment tracking details provided by the courier delivery company. (Please note that this may not be applicable for all).

    The above-mentioned supporting documents are general proofs we request. Depending on your business/line of business (LOB), we may ask for other details such as:

    * **Customer Signed Proof of Delivery**: A customer-signed copy of proof of delivery.
    * **Confirmation Email from a Customer**: An email from the customer confirming the delivery of the product or service.
    * **Customer-Signed Copy of Invoice**: A signed copy of the invoice from the customer.

    **Questions?**\
    We're always happy to help you with any questions that you might have. You can search our FAQs, documentation, contact our support team, [connect with our sales team](https://www.cashfree.com/contact-sales/), or fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1). You could also chat with our team via Intercom for real-time support.

    **Note**: Settlement cycle is subject to bank approval and can vary based on transaction type, business category/model, risk parameters, and other factors.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What is the checkout experience offered by Cashfree's PG like?">
    It is quite critical for a payment gateway to offer a **seamless experience** to the customers. Multiple redirects and ugly pop-ups lead to a confusing checkout experience and end up eroding the customer's confidence. A lot of websites do offer a beautiful checkout experience, but this lot is limited to big technology houses with abundant manpower.

    We at Cashfree have carefully tried to solve this problem. We offer multiple ways to integrate our payment gateway and render a seamless checkout experience to customers. Two basic aspects of our UI integration are:

    * **No Redirects**\
      Customer experiences the checkout flow on your website without navigating to any third-party page.

    * **Custom UI**\
      You own the look and feel of the checkout flow, or you can also use our ready-made beautiful UI components.

    [Sign-Up to see our PG in action](https://merchant.cashfree.com/merchants/signup)

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How does Subscription work?">
    Cashfree enables businesses to automate recurring payment collection from customers. Our system streamlines the payment process while providing flexibility in payment schedules and methods.

    Subscriptions help you to accept repeat online payments:

    1. Create custom plans for your customers and activate them with ease.
    2. Merchant add customer's payment details and subscribe to a plan.
    3. Customers have the ability to put it on hold/cancel subscription at any time.
       [Read more about subscriptions](/docs/payments/subscription/introduction)

    [Sign up on the Merchant Dashboard](https://merchant.cashfree.com/auth/login).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What is Third-Party Validation Feature for BFSI Sector Businesses?">
    **What is Third Party Validation? Why is it important?**

    Merchants in securities, broking, and mutual funds operating in the BFSI (Banking, Financial Services, and Insurance) sector are prone to cybercrimes, asset appropriation, identity thefts, money laundering, accounting frauds, etc. To reduce the risk, the Securities and Exchange Board of India (SEBI) has laid out guidelines for these merchants.

    As per the SEBI guidelines, all payments to such businesses must be made by their customers exclusively from pre-registered bank accounts. A pre-registered bank account is the one the customer shared during enrolment for schemes offered by businesses in these sectors.

    **Introducing Third-Party Validation feature by Cashfree**\
    Cashfree now supports Third-Party Validation on Payment Gateway. Using Cashfree’s Third-Party Validation feature, businesses can comply with the SEBI guidelines by ensuring that payments are made only from customers' registered bank accounts.

    Some of the primary use cases of Third-Party Validation feature include:

    * **BFSI sector**: Brokers and other online businesses can now sign up for Cashfree services and securely transact with customers in real-time.
    * **Loan repayments**: Merchants in the loan repayment sector can use Third-Party Validation to prevent discrepancies in payments and dispute cases.

    **Features**\
    When a customer transacts with the Cashfree Payment Gateway (with the TVP feature enabled), their bank account number or CRN (Customer Relationship Number) is mapped to lock the transaction, ensuring the payment is processed only from their registered bank account.

    **Advantages**

    * TPV is compliant with SEBI guidelines.
    * It serves as a one-stop solution for merchants in the BFSI sector to meet compliance requirements and start transacting securely with their customers.

    **Benefits**\
    When you enable the TVP feature on your Cashfree Payment Gateway, Cashfree matches the account number provided by the customer during registration against the account used for the transaction. If a non-registered account number is used, Cashfree marks the transaction as FAILED and provides an appropriate failure reason.

    To know more about the feature and how it can help your business, contact your Cashfree Account manager. If you are new to Cashfree, please [sign up to contact us](https://merchant.cashfree.com/merchants/signup). We would love to talk to you.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What is Rupay Credit Card on UPI payments mean for my business?">
    Your customers can now make payments using their Rupay credit cards via UPI apps like BHIM, PhonePe, and Google Pay. This enables seamless, fast, and convenient transactions directly through UPI.
  </Accordion>

  <Accordion title="What card subtypes are available in the webhook and API responses?">
    The available card subtypes are:

    * P – Premium

    * E – Elite

    * C – Corporate

    * R – Retail
  </Accordion>

  <Accordion title="How a customer can make payments via Rupay credit card on UPI Apps?">
    Steps to Make a Payment Using a RuPay Credit Card on UPI:

    1. Scan the merchant’s UPI QR Code OR Enter the UPI ID using any UPI-enabled app.
    2. Enter the payment amount.
    3. Select the linked RuPay credit card account as the payment method.
    4. Enter the UPI PIN to authorize the transaction.
    5. Receive payment confirmation upon successful transaction.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What is PayPal Express Checkout on Cashfree Payment Gateway?">
    PayPal is one of the world’s most popular payment modes used by 350+ mn users across 200+ countries worldwide.
    Cashfree has integrated directly with PayPal to enable seamless merchant onboarding with PayPal and to allow a faster checkout experience using PayPal Express Checkout integration.
    Cashfree Payment Gateway merchants can now add the PayPal Express Checkout button on their website or mobile app.
    **Benefits of PayPal Express Checkout**

    * Accept payments from international customers in 100 currencies using PayPal.
    * Faster customer payment checkout with PayPal Express Checkout button.
    * 24/7 transaction monitoring, fraud prevention, and seller protection that help you keep your business PCI compliant.
    * Easy integration. Enable PayPal on your Cashfree Checkout in just a few steps \[refer to PayPal API integration steps here]. No separate integration required.

    **How do I integrate PayPal with my Cashfree account?**

    PayPal Express Checkout is available for all Cashfree Payment Gateway merchants.

    * If you are an existing Cashfree Payment Gateway merchant and want to enable PayPal Express Checkout as a checkout mode, follow the \[PayPal API integration steps here]. For any queries related to integration, contact your Cashfree Account Manager or fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1), and we’ll get in touch with you.
    * If you’re not an existing Cashfree merchant, [sign up](https://www.cashfree.com) now to enable PayPal and other 120+ payment modes including net banking, debit cards, Paytm, UPI, and start collecting online payments.

    **Please note**: PayPal is a payment mode and is only available on request. It is not enabled by default. Raise a request with your Account Manager to enable this feature.

    **Other International Payment Options on Cashfree**\
    With Cashfree Payment Gateway, you can offer your customers a range of international checkout options, including PayPal and international cards such as Visa, Mastercard, American Express, and Diners Club.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Is there any limit to the number of Aadhaar cards that can be verified in a day?">
    No, there is no limit to the number of Aadhaar cards that can be verified in a day.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How do I check, if I am eligible for accepting payments from Rupay credit cards on UPI payments?">
    Almost all businesses are by default eligible to receive payments via Rupay credit card.

    <Note>
      Except for the merchant MCCs such as mutual fund providers, stock brokers, loan repayment etc, are not eligible to accept credit payments.
    </Note>

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What is Rupay Credit Card on UPI payments mean for my business?">
    Your customers now will be able to make payments from their Rupay credit cards of the issuing banks which are live on via their preferred UPI apps like BHIM, PhonePe and Google Pay.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How a customer can make payments via Rupay credit card on UPI Apps?">
    **To make the payment with RuPay Credit Card on UPI, a customer must follow these steps:**

    1. Scan the merchant UPI QR code.
    2. Enter the amount and select the credit account.
    3. Select the RuPay credit card account followed by the UPI PIN to authorize the payment.
    4. Transaction successful.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How to link RuPay Credit Card on UPI apps?">
    **To link RuPay Credit Card on UPI App, follow these steps:**

    1. Open your preferred UPI app (currently supported on BHIM, PhonePe, and Google Pay).
    2. Navigate to the option to **Add Bank Account** or **Add Payment Method**.
    3. Select **Credit Card** as the account type.
    4. Choose your credit card issuer bank.
    5. Select your RuPay Credit Card.
    6. Confirm the card details.
    7. Set a UPI PIN for the card.

    Your RuPay Credit Card is now successfully linked to your UPI app.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How can this feature be enabled?">
    This is a request-based feature, available only to PCI-DSS-compliant merchants. To enable it, reach out to your account manager or submit a [Support Form](https://merchant.cashfree.com/auth/login).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How can checkout merchants build this functionality?">
    Cashfree-hosted Checkout merchants use Cashfree’s [offer engine](/docs/payments/checkout/offers) to run offers. To set up risk checks, merchants leverage Cashfree’s [RiskShield](/docs/payments/risk-shield/overview) solution. Both offerings allow merchants to set up offer targeting strategies and risk rules through a self-serve flow on the Cashfree dashboard, making implementation easy and effective.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What is a capture call in Pre-Authorization?">
    Capture call is performed after authorization. It is a merchant-initiated request (via API) to collect the previously authorized funds. This step debits the amount from the customer.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What is the validity of capture?">
    If not captured within 7 days, the authorization expires, and the funds are released back to the customer.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can a merchant capture a partial amount?">
    Yes, merchants can capture a partial amount of the authorized funds.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Is MDR charged on the authorized or captured amount?">
    MDR is always applied only on the captured amount.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Which cards support pre-authorization?">
    All Visa, Mastercard and Rupay credit and debit cards support pre-authorization.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What is void in Pre-Authorization?">
    A void call cancels the authorization before capture, releasing the hold on funds.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can a merchant void a partial amount?">
    No, voiding must be for the entire authorized amount.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are some common use cases for Pre-Authorization?">
    Here are some common use cases:

    <ul>
      <li>**Ticket Bookings** – Airlines, concerts, and events often place a hold on a credit card to ensure funds are available before finalising the booking. This is useful if confirmation is pending or for refundable ticket options.</li>
      <li>**Car Rentals** – Rental companies use pre-authorisation to secure a deposit in case of damages, late returns, or additional charges. The hold is released if no extra fees are incurred.</li>
      <li>**Hotel Reservations** – Hotels pre-authorise a guest’s credit card at check-in to cover potential incidentals, damages, or unpaid charges, ensuring payment security before checkout.</li>
    </ul>

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How does settlement occur in a pre-authorization transaction?">
    Settlement occurs when the merchant finalises a pre-authorized transaction by capturing the funds.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="When does the merchant receive the funds in a pre-authorization transaction?">
    Merchants typically receive funds from pre-authorized transactions as per their normal settlement cycle, i.e., T+x days after a successful capture.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What happens if a customer disputes a settled transaction?">
    A dispute may result in a chargeback, requiring the merchant to provide proof of authorization and service fulfilment.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Does Cashfree support EMI recommendations?">
    Cashfree allows merchants to configure EMI options for their customers. However, we currently do not provide a built-in EMI recommendation engine.

    If you want to suggest EMI plans to your users, you can implement your own recommendation logic externally, based on factors such as tenure, interest rate, and total payable amount.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How does Cashfree handle chargebacks?">
    The chargeback process is as follows:

    1. The customer raises a dispute with their issuing bank.
    2. The issuing bank communicates with the acquiring bank via the card network.
    3. The acquiring bank notifies Cashfree.
    4. Cashfree contacts the merchant for supporting documentation.
    5. The merchant must respond within the stipulated time.

    **Merchant response options:**

    * **Accept the dispute:** The amount is refunded, and the dispute is marked as *Closed (Merchant Accepted)*.
    * **Contest the dispute:** The merchant provides evidence, such as invoices, delivery proof, or communication logs.

    **Best practices:**

    * Maintain comprehensive transaction records.
    * Respond to chargebacks within the required timelines.
    * Clearly communicate refund and cancellation policies on your website.

    The final resolution may take 21–45 days depending on the banks involved.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are the transaction limits on Cashfree?">
    Cashfree applies transaction limits based on your account activation stage:

    * **Partial activation:** ₹50,000 per month
    * **Full activation:** Limits are set by your bank and are not controlled by Cashfree.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Does Cashfree share success rate and SLA data?">
    Yes. We share PG-wise success rate (SR) data periodically. Please note that this data includes only a subset of payment modes and gateways and may not represent the entire system’s performance.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Which billing and ERP systems does Cashfree support?">
    Cashfree supports a wide range of integrations, including:

    **E-commerce platforms:**

    * Shopify
    * WooCommerce
    * Magento
    * OpenCart
    * PrestaShop
    * WHMCS
    * WIX
    * Zoho
    * StoreHippo
    * CScart

    **ERP and SaaS platforms:**

    * Education, travel, restaurant, and hospitality ERPs
    * Accounting software
    * Lending, checkout, and POS SaaS products
    * CRMs and financial service platforms

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How to withdraw funds from Cashfree?">
    Cashfree supports fund withdrawals through different products. The process varies depending on whether you're using Payments (PG), Payouts, or SecureID.

    **Payments (PG)**
    To initiate an on-demand withdrawal from Payments Gateway:

    1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
    2. In the left navigation panel, go to Settlements.
    3. Select On-demand from the dropdown.
    4. Click **Withdraw Now** next to the available balance.
    5. A list of previously initiated withdrawals is also displayed on this screen.

    **Payouts**

    To initiate withdrawal funds from your Cashfree Payouts wallet:

    1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
    2. Navigate to Fund Sources > Cashfree Wallet.
    3. Under the Overview section, click Withdraw next to Last Withdrawal.
    4. Enter the withdrawal Amount and Remarks, then click **Withdraw**.

    **SecureID**

    To withdraw funds from your SecureID account:

    1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
    2. In the left navigation panel, go to Accounts.
    3. A summary of your account transactions will be displayed.
    4. Click **Withdraw** to initiate the fund withdrawal.

    **Withdrawal guidelines:**

    * Maximum 3 withdrawals allowed per day.
    * Funds are credited only to your registered business bank account.
    * Processing time is between 8:00 AM and 6:45 PM, Monday to Saturday except 2nd and 4th Saturdays.
    * Withdrawals are non-reversible once submitted.
    * It may take 30 minutes to a few hours for the credit to reflect.

    <iframe title="FAQ feedback: Withdraw funds" />
  </Accordion>

  <Accordion title="How can a partner use the S2S flow for their merchants if S2S is enabled at the partner level?">
    If S2S is enabled at the partner level, create the order with partner authentication headers instead of the merchant `x-client-id` and `x-client-secret`. Pass `x-partner-apikey` and `x-partner-merchantid` as described in [API authentication](/docs/api-reference/authentication).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How can I fetch the latest payment status for a specific transaction or order?">
    Use the [Get Payments for an Order API](/docs/api-reference/payments/latest/payments/get-payments-for-an-order) to retrieve every payment attempt for an order and determine the latest state. Verify the status on your server after the customer returns from checkout, and use this API as a fallback if a webhook has not arrived.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How should I handle PENDING payments and what is the recommended approach for timeouts?">
    Treat `PENDING` as a non-terminal state. Do not fulfil the order or mark the payment as `SUCCESS` or `FAILED` while it remains `PENDING`. Rely on payment webhooks for asynchronous updates, and use the [Get Payments for an Order API](/docs/api-reference/payments/latest/payments/get-payments-for-an-order) as a fallback. Do not use a fixed client-side timeout to mark a pending transaction as failed, because a late authorisation can still confirm the payment. See [Payment Lifecycle](/docs/payments/online/resources/payment-lifecycle).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How should I update my system to handle the change in cf_payment_id and other identifier lengths?">
    Cashfree identifiers such as `cf_payment_id`, `cf_order_id`, and `cf_refund_id` are variable-length strings and can be up to 19 characters. To stay compatible, complete the following updates:

    1. **Update data types**: Treat these identifiers as variable-length strings (`VARCHAR`) in your database schema and application logic. Do not store them as integers or fixed-length numeric types.
    2. **Remove fixed-length assumptions**: Accept identifiers up to 19 characters.
    3. **Set the API version**: Send `x-api-version` as `2023-08-01` or later (for example, `2025-01-01` or `2026-01-01`) so identifiers are returned as strings.
    4. **Check deprecation headers**: Monitor the `x-deprecated-at` header in API responses to track when your current API version is deprecated.

       <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How do I generate a HAR file to help debug a technical issue with Cashfree support?">
    To generate a HAR (HTTP Archive) file, complete the following steps:

    1. Open your web browser (for example, Chrome or Firefox) and go to the page where the issue occurs.
    2. Open Developer Tools. Right-click the page and select **Inspect**, or press F12, Ctrl+Shift+I (Windows), or Command+Option+I (macOS).
    3. Open the **Network** tab and confirm that recording is active.
    4. Reproduce the issue on the page.
    5. Right-click anywhere in the Network panel and select **Save all as HAR with content**.
    6. Save the file and attach it when you submit the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1).

       <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Where can I find the Cashfree Payment Gateway integration and API documentation?">
    You can refer to the following links for Cashfree Payment Gateway integration and API references:

    **Integration guides**

    * [Integration Overview](/docs/payments/overview)
    * [Web Integration](/docs/payments/online/web/redirect)
    * [Android SDK](/docs/payments/online/mobile/android)
    * [iOS SDK](/docs/payments/online/mobile/ios)
    * [React Native](/docs/payments/online/mobile/react-native)
    * [Flutter](/docs/payments/online/mobile/flutter)
    * [Data to Test Integration](/docs/api-reference/payments/data-to-test-integration)
    * [Dev Studio (Integration Preview)](https://www.cashfree.com/devstudio/preview/pg/web/checkout)

    **API references**

    * [API Endpoints Overview](/docs/api-reference/payments/latest/overview)
    * [Create Order API](/docs/api-reference/payments/latest/orders/create-order)
    * [Get Order Details](/docs/api-reference/payments/latest/orders/get-order)
    * [Get Payments for an Order](/docs/api-reference/payments/latest/payments/get-payments-for-an-order)
    * [Create Refund](/docs/api-reference/payments/latest/refunds/create-refund)
    * [Webhooks Configuration](/docs/api-reference/payments/latest/payments/webhooks)

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How can I test Cashfree APIs before my account is fully activated?">
    To complete integration and testing before your account is activated, use the Cashfree Sandbox environment via the Merchant Dashboard.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How can I implement a seamless integration to collect payment information on my own frontend and complete the payment from the backend?">
    To collect payment information on your own frontend and complete the payment from the backend, use the [Cashfree Order Pay API](/docs/api-reference/payments/latest/payments/order-pay).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How can I restrict specific payment methods for a single order in the Hosted Checkout integration?">
    For standard Hosted Checkout integrations, you can use the `order_meta.payment_methods` parameter in the [Create Order API](/docs/api-reference/payments/latest/orders/create-order) to restrict the available payment modes for a specific order. For example, passing `"payment_methods": "cc,dc"` shows only credit and debit card options. This provides order-level control without changing your global account settings.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I use the payment_methods parameter to enable or disable Cash on Delivery (COD) for an order?">
    No. Cashfree handles COD separately, so don't pass it in the `order_meta.payment_methods` parameter. You manage COD availability through [COD rules](/docs/payments/checkout/cod/overview), which let you set eligibility based on order amount, pincode, product restrictions, or return-to-origin (RTO) intelligence.

    <iframe title="FAQs feedback component" />
  </Accordion>
</AccordionGroup>


# Transactions
Source: https://www.cashfree.com/docs/help/payments/transactions/transactions

Get answers to Cashfree transactions FAQs covering capture flows, authorisation holds, partial refunds, dispute handling, and status updates from the dashboard.

<AccordionGroup>
  <Accordion title="How do I initiate refunds in Cashfree?">
    You can initiate refunds through our [APIs](https://www.cashfree.com/docs/api-reference/payments/latest/refunds/create-refund#create-refund) or directly from the [Merchant Dashboard](https://merchant.cashfree.com/merchants).

    To initiate a refund from the dashboard:

    Navigate to Payment Gateway Dashboard → Transactions → Payments.
    Select the specific transaction you want to refund.
    If you have the Transaction ID or Order ID, you can search and initiate the refund directly from the dashboard.

    <Note>
      Refunds can only be processed for successful transactions.
    </Note>

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How do I check the status of a transaction?">
    As soon as you log in to your Cashfree account, the Summary section in the payment gateway dashboard will give
    you instant context as to what is the amount of transaction that has happened on that particular day, and the
    settlement amount that you’re yet to receive. Besides this, Cashfree also provides a wide range of reports to
    analyse your business finances. The different reports that Cashfree provides you are,

    * Transactions Report
    * Settlement Reconciliation Report
    * Settlement Summary
    * Refunds Report
    * Ledger Report
    * Monthly Invoices

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I track the amount of daily transactions in Cashfree?">
    The Cashfree Dashboard provides a real-time overview of your daily transactions and finances. You can instantly track the total transactions for the day and the unsettled amount pending from Cashfree.

    [Click here to learn more](https://merchant.cashfree.com/merchants/pg/summary/overview)

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can Cashfree send reports to my own SFTP servers?">
    Yes. With Cashfree, you can receive specific reports such as Transaction reports, Settlements and
    Adjustment reports, directly into your own SFTP servers or Cashfree's SFTP servers at a set frequency
    everyday.

    If you'd like Cashfree to push out the reports to your own SFTP servers, please fill out this
    [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) with your requirements.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What is a dispute?">
    A dispute arises when there is a disagreement over a transaction, initiated by your customer with their issuing bank or directly with Cashfree. Customers may also report fraudulent transactions to cyber cells, while suspicious transaction disputes are often raised directly by banks.

    As a merchant, you have the option to either defend the dispute by providing sufficient evidence or accept the dispute if you agree with the claim. If you accept the dispute, the amount will be refunded to the customer.

    [Read more on disputes](/docs/payments/manage/disputes/overview).

    1. Product Quality Issues – The delivered product is defective, damaged, or does not match the description.
    2. Incorrect Product – The customer received a different item than what was ordered.
    3. Unauthorised Charges – Additional fees were applied without the customer’s consent.
    4. Non-Delivery – The product or service was not delivered as promised.
    5. Billing Errors – Mistakes in the amount charged, duplicate transactions, or incorrect billing details.
    6. Fraudulent Transactions – The customer did not authorise the transaction (potential fraud or misuse).
       <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Why am I debited for a dispute and When will I get the amount back?">
    When a dispute is raised, the disputed amount is debited from the merchant’s account, as banks debit Cashfree to provide provisional credit to the customer.

    The final refund depends on the dispute outcome:
    If the dispute is resolved in your favour, the amount will be credited back to your account.
    If the dispute is ruled in the customer’s favour, the amount will remain with the customer.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What is a POD QR Code and how does the TTL (Time to Live) feature work?">
    A POD (Pay on Demand) QR code allows merchants to generate payment QR codes that remain valid for an extended period of up to 30 days. This Time to Live (TTL) duration is configured via the PG Config settings, and it gives customers the flexibility to complete the payment at any time within the configured TTL window.
    For example, a merchant may print a POD QR code on a physical receipt and hand it to a customer. The customer can scan and pay later, within the 30-day TTL.
    During the TTL period:
    -The payment status will not be marked as “Failed” even if payment hasn't been received. It will be marked as incomplete
    -The system waits for a successful payment until TTL expires.
    -If no payment is made after 30 days, the transaction is marked as USER\_DROPPED.

    This ensures better control over delayed payment flows while reducing refund-related complications.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How will I be notified if my customer has raised a dispute?">
    Email notifications can be configured from the [Merchant Dashboard](https://merchant.cashfree.com/merchants). Emails on which the merchant wants to receive these notifications can be configured from the [Merchant Dashboard](https://merchant.cashfree.com/merchants) by following the below steps:

    Go to Payment Gateway Dashboard > Settings > Email Notifications > Dispute Emails.

    Emails are triggered on following events:
    New Dispute Created – Get notified when a customer raises a dispute.

    1. Dispute Phase/Type Change – Receive updates when the dispute moves between phases like Pre-arbitration or Arbitration.
    2. State Change – Stay informed when the dispute transitions between states, e.g., Action Required → Under Review.
    3. Comment Updated – Get alerts when a new comment is added to the dispute.
    4. Reminder Email – Receive a notification when the dispute deadline approaches.
       <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are the various types of dispute?">
    In Cashfree, Disputes can be of the following types:

    **Dispute**
    Raised for end-customer complaints, fraudulent, or suspicious transactions reported by law enforcement or banks.

    **Retrieval**
    Soft chargebacks initiated when the customer queries a transaction with their issuing bank before an actual chargeback occurs.

    **Chargeback**
    Raised when a customer disputes a transaction due to non-delivery of services or transaction issues, following a retrieval request.

    **Pre-Arbitration**
    The second level of chargeback, where the customer decides whether to pursue further dispute based on the evidence provided.

    **Arbitration**
    The final stage of the chargeback, where both parties submit evidence, and the card network or NPCI makes the final decision.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are the deadlines for various disputes?">
    Following are the representation deadlines given to merchants depending on the type of dispute:

    * **Disputes:** 3 calendar days. In certain cases, such as real-time fraudulent transactions, a 1-day deadline may apply.
    * **Retrieval:** 3 calendar days.
    * **Chargeback:** 3 calendar days.
    * **Pre-arbitration:** 2 calendar days.
    * **Arbitration:** 1 calendar day.
      <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Why did a transaction marked as Failed later show as Success?">
    In rare cases, a transaction initially marked as "Failed" may later move to "Success" status during the bank reconciliation process. This typically happens when the bank confirms the settlement of funds after the initial failure was recorded.

    <iframe title="FAQs feedback component" />
  </Accordion>
</AccordionGroup>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/help/account/access-management-faqs">Account Access Management FAQs</a></li>
  </ul>
</div>


# Cashgram
Source: https://www.cashfree.com/docs/help/payouts/Cashgram

Find answers to common Cashgram questions about generating payout links, redeeming funds, expiry policies, refunds, and supported beneficiary payment modes.

<AccordionGroup>
  <Accordion title="How to assign approver to verify bulk Cashgrams?">
    When you create a large number of Cashgrams using the `Bulk Cashgram` feature, you may want approval from the approver in your company before sending it to the customers. An approver can verify and approve the Cashgrams, and then send them to the customers.

    One of the users in your company can add all the customer details in the file and upload the file and later another user can approve the Cashgrams. The approver has the option to accept or reject the Cashgrams. After approval, the Cashgrams are sent to customers, and you can view the status of the Cashgram in the Payout Dashboard.

    The option to create multiple users and assign permissions can be done from the Payout Dashboard. See the [Approve Cashgrams documentation](https://docs.cashfree.com/docs/approve-cashgrams) for more information. Fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1), if you want to use the Approve Bulk Cashgrams feature.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What happens if the customer enters an incorrect bank account while redeeming a Cashgram?">
    If the customer enters an invalid bank account number or IFSC code we will notify him on the web page. But if the customer enters a valid but incorrect account number the money will be transferred to that bank account.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What is a Cashgram?">
    Cashgram is an instant payout link used by businesses to send money to their customers, vendors, or partners, even if you do not know their bank account details. Users can access the payment link sent via WhatsApp, email, or SMS, provide their details, and choose a payment method to receive the amount.
    Merchants can create a single Cashgram or create a larger number of Cashgrams at a time using the dashboard.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Detailed Walkthrough of the new Cashgram changes">
    Cashgram helps businesses to instantly send money to users when bank account details are not known. With Cashgram, you can pay your vendors, partners, customers, or others instantly when you only know their mobile number or email address.

    What changes in the new Cashgram?
    Creating a Cashgram
    With this new upgrade, you can now specify the type of disbursal you are doing with the Payout Type field (Example - refunds, reimbursements, rewards) and a brief note on why the disbursal is being made in the Payout Reason field.

    Customising your Cashgram checkout page:
    You can now customise your checkout page with logos and colours that reflect your brand. Here’s how you do it,

    Login to the Cashgram dashboard
    Click on Settings > General > Branding
    Once in, you can upload your logo, add your brand colour to customise your Cashgrams, and enhance the experience for the end-user

    Here\`s how the checkout experience will look like for your end-users:

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How to generate a Cashgram?">
    You can create Cashgrams via the Payouts Dashboard or APIs. Ensure your Payouts account has sufficient balance, as funds are deducted from it to send money to beneficiaries.

    Steps to create a Cashgram:

    Navigate to:
    Payouts Dashboard > Cashgram > Create Cashgram.

    Fill in the details:

    Cashgram ID: A unique identifier to track the Cashgram.
    Payout Type: Select from Refunds, Reimbursements, Rewards, or add custom types.
    Beneficiary Details: Name, Phone Number, Email, and Transfer Amount.
    Validity: Set the expiry date for the Cashgram link.
    Reason & Remarks: Remarks will appear in the beneficiary’s bank statement if supported.
    Notification Mode: Choose Email, SMS, or WhatsApp to notify the beneficiary.
    Click "Create":
    The Cashgram link is sent to the beneficiary. They can click the link, provide details, and receive the funds.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How to generate bulk Cashgrams?">
    When you have to create and send Cashgrams to a large number of customers you can use the ‘Bulk Cashgram’ feature. You can upload the file with the details using the ‘Upload File’ button in the Payouts Dashboard.
    You can view the status of the uploaded files and also download them to view further details.

    To upload a batch file:

    1. Go to Payouts Dashboard > Cashgram > Batch > click Upload File.
    2. Click Choose a File to select the file you want to upload and then click Upload. The uploaded file will be visible in the Batch section.
    3. Click on the file to view the individual Cashgram details uploaded in the file.
       **Note**- Maximum file size allowed is 5 MB, and a maximum of 10000 records can be included in the file.

       <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How secure is Cashgram?">
    Cashgram is a secure way to transfer money to your customers. Once you create a Cashgram for a user only that user with the provided phone number can use that Cashgram. Cashgram is also active only for a limited amount of time, you can control the expiry time of each Cashgram. Post expiry, no one will be able to view/redeem the Cashgram.

    Once a Cashgram has been redeemed or expired, the customer will not be able to view it again.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How do I let a user know that I have generated a Cashgram for them?">
    You can use the dashboard to notify the user about their Cashgram. We will notify the customer over email or SMS.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Is it possible to edit or deactivate an active Cashgram?">
    You can't edit an active Cashgram. However, you can deactivate it at any time.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="I deactivated a Cashgram link, but a new one was triggered for the same customer. How do I stop this?">
    Deactivating a Cashgram link stops only that specific link. It does not prevent new Cashgram links from being created. Cashfree does not automatically re-trigger or regenerate Cashgram links; your refund automation workflow initiates new ones. To stop new Cashgram links for a customer, review and update your refund automation so it does not create a new Cashgram after deactivation.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Why is a customer’s Cashgram status showing as pending?">
    Once the customer submits their bank details to redeem a Cashgram we will initiate a bank transfer from Merchant’s account to the customer’s bank account. When the transfer status is yet to be confirmed, the Cashgram is in the Pending state. At this point, the partner bank could be processing the payout, and no further action is required from your end.
    The Pending state can transition into:

    * Redeemed state, if the Cashgram is successfully redeemed.
    * Failed state, if the Cashgram could not be redeemed.

      <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What happens if the user fails to get money using Cashgram?">
    If a beneficiary fails to redeem a Cashgram, it will appear as Failed on your dashboard. The Failed state is final and cannot transition to any other state.

    Common reasons for failure include:

    1. Incorrect beneficiary account details.

    2. Insufficient balance in your Payouts account. Enable Low Balance Alerts to get notified when your balance falls below a set threshold.

    3. Downtime or issues with partner or beneficiary bank servers.

    4. Most failures occur due to exceeding OTP limits. Ensure accurate details and sufficient balance to minimise such occurrences.

       <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are Payout links?">
    A Payout Links is a way to instantly send money to your beneficiaries without knowing their bank account details. You can simply create a payout link from the Cashfree dashboard, and send it to your vendors/ customers on their email id or mobile number.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Will I be notified if the Cashgram I generated is used?">
    Once the customer redeems a Cashgram its status changes from ACTIVE to REDEEMED instantly. You will be able to view this on the dashboard. You will also be notified over email once a Cashgram has been successfully redeemed, if merchant has opted for the email notification.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How do I use a Cashgram?">
    To use a Cashgram you need to have a Cashfree account. From your Cashfree dashboard, you can create a new Cashgram for a customer. The typical process is listed below-

    The merchant creates a Cashgram filling in the customer’s phone number.
    The customer receives SMS and email notification about this Cashgram generated by the Merchant.
    The customer visits the Cashgram link, authenticates, and enters their bank details.
    The money is instantly transferred from Merchant’s account to the customer’s bank account.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How can I start using Cashgram?">
    To start using Cashgram you will need to sign-up with Cashfree. If you already have a Payout account you can instantly start using Cashgram using the dashboard. Click on the “Cashgram” tab in the Payout dashboard.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="My Cashgram link is not working. What do I do?">
    A Cashgram link may not work if it is in an Expired, Failed, or Reversed state. Cashgrams remain Active for up to 30 days or the specified duration and can transition to states like Redeemed, Expired, Failed, or Reversed.
    Check the Cashgram status on the Payouts Dashboard. If the Cashgram link sent to you has expired. Please get in touch with the merchant to get a new Cashgram.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can the customer view and redeem a Cashgram any time?">
    Yes, the Cashgram recipient will be able to view and redeem their Cashgram at any time.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What happens if the Cashgram is never used?">
    Every Cashgram has an expiry date. If the Cashgram is not redeemed before this expiry date, the Cashgram will become inactive. No one will be able to view/redeem such an inactive Cashgram.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How will you verify user identity for Cashgram?">
    We authenticate users using OTP so that only authorised users can view/redeem a Cashgram. Without a valid OTP, nobody can view/redeem a particular Cashgram.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can customers also redeem money to their UPI account?">
    If you have UPI enabled in your Smart Payout account your customers will be able to redeem a Cashgram to their UPI account.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can customers also redeem money to their PayTM account?">
    If you have PayTM enabled in your Smart Payout account your customers will be able to redeem a Cashgram to their PayTM account.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are the advantages of using a Cashgram?">
    Cashgram simplifies money transfers by removing the need for bank details or manual processing. Users are notified via WhatsApp, email, or SMS and can redeem payments anytime using a secure link.\
    **Key Benefits:**

    * Instant refunds for COD payments, cash prizes, and security deposits.
    * No need to collect bank details; users choose from multiple payment methods.
    * Saves time with automated payment processing.
    * Supports single or bulk Cashgram creation via the dashboard.

      <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Is Cashgram different from Payout links?">
    Cashgram is a payout link with many additional features. You can customise your Cashgram links with your company logo and colour to reflect your brand. You can also set up a link expiry time and verify the beneficiary's name before sending out the money.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="I am not able to receive the OTP.">
    Please verify your mobile number with the merchant. You can receive the OTP via SMS or WhatsApp. If one method does not work, we recommend trying the alternative. In case you are still not receiving the OTP, please [report the issue to us](https://www.cashfree.com/en/report-issue/).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What is a Payout link?">
    A Payout Link is a way to instantly send money to your beneficiaries without knowing their bank account details. You can simply create a payout link from the Cashfree dashboard, and send it to your vendors/ customers on their email id or mobile number.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="I received a Cashgram on email but the mobile number mentioned on the Cashgram is incorrect. How do I proceed?">
    It seems that the Merchant entered a different mobile number while generating the Cashgram. Please reach out to the merchant to get this changed.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="My Cashgram transfer is showing successful but I have not received the money in my account?">
    The money should be transferred into your account in some time. If you do not receive the amount within one hour please fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1). Do mention your email id, phone number, Cashgram Id, and merchant name in your email.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="My Cashgram transfer failed, what do I do now?">
    A Cashgram can fail due to:

    1. Incorrect beneficiary account details.
    2. Insufficient balance in your Payouts account. To avoid this, set a Low Balance Alert to receive notifications when the balance falls below a specified amount.
    3. Downtime in partner or beneficiary bank servers.\
       Please reach out to the merchant so that they can generate a new Cashgram for you.

       <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What all details do I need to redeem a Cashgram?">
    Cashgram can be redeemed to your bank account, UPI VPA, or PayTM. If any of the above modes is not enabled for you, please get in touch with the merchant.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are the charges for using Cashgram?">
    Cashfree doesn't publish a standard rate card for Cashgram. Pricing is customised based on your transaction volume and business category.

    To get pricing for your business, submit this [Contact Sales form](https://www.cashfree.com/contact-sales/).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="My Cashgram transfer is pending, when will the money be credited into my account?">
    When the transfer status is yet to be confirmed, the Cashgram is in the Pending state. At this point, the partner bank could be processing the payout, and no further action is required from your end.

    The Pending state can transition into:

    1. Redeemed state, if the Cashgram is successfully redeemed.
    2. Failed state, if the Cashgram could not be redeemed.

    Please wait for 24 hours, if you still have not received the money in your account, reach us by filling out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1). Do mention your email id, phone number, Cashgram Id, and merchant name in the support form.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="My Cashgram is not showing PayTM or UPI?">
    If any of the above modes is not enabled for you, please get in touch with the merchant.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How can I provide a new user with access to Cashgram Payouts in the Merchant Dashboard?">
    To provide a user with access to Cashgram Payouts, the Primary Admin must create an Alias Account and assign the appropriate role:

    1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
    2. Go to **Settings** in the top navigation panel.
    3. Under the **General** tab, click **Access Management**.
    4. Click **+ Invite New User** and enter the user's email address to create the Alias Account.
    5. Once the account is added, navigate to **Role Management** and assign the required permissions for Cashgram Payouts.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I re-trigger or re-hit a Cashgram status webhook?">
    Cashfree does not provide a separate URL to re-hit or re-trigger Cashgram webhooks. Cashgram uses event-based webhooks — `CASHGRAM_TRANSFER_SUCCESS`, `CASHGRAM_TRANSFER_FAILED`, and `CASHGRAM_EXPIRED` — that are sent to the URL configured in your Payouts Dashboard. If you need to verify the current status of a Cashgram, use the Get Cashgram Status API.

    <iframe title="FAQs feedback component" />
  </Accordion>
</AccordionGroup>


# Payouts
Source: https://www.cashfree.com/docs/help/payouts/general-faqs

Find answers to general Cashfree Payouts questions on transfer reversals, beneficiary errors, processing timelines, IFSC validation, and bank technical issues.

<AccordionGroup>
  <Accordion title="Transaction is successful, but the amount is not received by the customer">
    In this case, the amount may reverse to your payouts account within 24 hours of the transfer status changing to successful, if the customer's account details are incorrect or if the beneficiary bank has any technical issues.

    If the status has not changed to reversed post the above-mentioned time, fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1)

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What is Payouts and its key features?">
    It is a comprehensive payment disbursal solution that allows businesses to efficiently send and manage payments for various use cases, including vendor payouts, customer refunds, and salary distributions. It eliminates the need for complex Excel uploads to corporate banking portals for bulk transfers.

    Key Features:

    1. Multiple Payout Methods: Supports IMPS, NEFT, RTGS, UPI, Mastercard (MoneySend), Visa (Visa Direct), and digital wallets (Amazon Pay, Paytm).

    2. Do instant payouts, 24x7, even on bank holidays.

    3. Add or delete any number of beneficiary accounts.

    4. Do bulk payments instantly (up to 10,000 transactions in a minute).

    5. Track each account separately using the dashboard.

    6. Automatic reconciliations.

       See the [Payouts introduction](/docs/payouts/payouts/introduction) to know more about how you can use Payouts efficiently for your business.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Why is my transaction showing as Pending?">
    A transaction can show as Pending if it's still being processed by either the Partner Bank or the Beneficiary Bank (your customer’s bank). This means the transfer has been initiated, but we’re waiting for the bank to confirm it.

    Please wait up to 72 hours from the time the transfer was started to see the final status.

    Here’s how long transfers typically take based on the payout mode:

    UPI – 99% are completed within 15 minutes
    IMPS – 99% are completed within 15 minutes
    RTGS – 99% are completed within 1–2 hours
    NEFT – 99% are completed within 6 hours

    If the status is still pending after 72 hours, you can reach out for support.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How to generate new API Keys and remove existing ones?">
    You can add or delete API keys and IP addresses under the 'Developers' tab.
    Select API Keys or IP Whitelist as per your need.
    Steps: Go to [Merchant Dashboard](https://merchant.cashfree.com/auth/login) - Developers tab - API Keys - Generate API Keys

    <Note>
      You can generate and use up to 3 API Keys at any point in time.
    </Note>

    Know more:

    <iframe title="Payouts by Cashfree | Send Instant Bulk Payouts 24*7 even on bank holiday" />

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How does Payouts by Cashfree work?">
    Step 1: Link banks to the account.
    Sign up on Cashfree and initiate Payouts Account activation through the [Merchant Dashboard](https://merchant.cashfree.com/auth/login). Once activated, link your bank account(s) with your Payouts Account. Refer to the Payouts documentation to know more about linking your bank account with Payouts.

    Step 2: Add beneficiary.
    Add beneficiary to your Payout account(s) using our Dashboard or APIs. Cashfree allows you to instantly validate the account details. Know more about beneficiary addition here.

    Step 3: Start paying out
    Start paying out to your beneficiaries. Cashfree supports multiple payment modes: IMPS, NEFT, UPI VPA, and digital wallets(Amazon Pay and Paytm). Know more about making a payout to your beneficiaries here.

    Step 4: Get notified and automate reconciliation.
    Get event notifications via email or webhooks. You can also use your [Merchant Dashboard](https://merchant.cashfree.com/auth/login) to view detailed reports.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Important Update | Paytm Policy change. Steps to continue Paytm Payouts via Cashfree.">
    This document is for Cashfree Payouts and Cashgram merchants who use Paytm as a payment mode.

    As per new policies adopted by Paytm, Payouts and Cashgram merchants will be required to have a Paytm business account to do payments to Paytm wallets. Here is how you can set up your Paytm business account and continue doing payments to Paytm wallets via Cashfree.

    1. Create a [Paytm business account](https://dashboard.paytm.com/login/) (if you already do not have one), enter your business details, and upload the scanned copies of [documents](https://business.paytm.com/document-requirements) based on your business type.

    2. Once your Paytm account has been created, you will get User Acceptance Testing (UAT) credentials that can be used to do test transactions in a staging environment before going live.

    3. You can share the UAT credentials with Cashfree at [Support team](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) along with your merchant ID. Cashfree will do test transactions on your behalf and reply to your email with the test transactions’ details.

    4. Share the test transactions’ details with Paytm. Paytm will generate production credentials for your account.

    5. Share the production credentials with Cashfree. On receiving the production credentials, Cashfree will enable Payouts/Cashgram payments to Paytm wallets for your account.

    Maintaining funds in your Paytm wallet.

    Your Cashfree Dashboard will show the available Paytm wallet balance separately. In order to add funds to your Paytm wallet, you will have to log in to your Paytm business account and recharge your wallet. Once recharged, you can come back to your Cashfree dashboard and carry out transactions.

    Pricing

    As applicable to your Paytm business account. No additional charges.
    Alternative to maintaining a Paytm business account.

    * If you would prefer not to maintain a Paytm business account, you can:

    * Use alternative payment modes such as bank transfer, card, UPI or AmazonPay

    * If you are a Payouts user and do not have recipients’ payment details, you can use Cashgram payout links to transfer money to your users without having to collect their payment details. Learn more in the [Cashgram documentation](/docs/payouts/cashgram/cashgram). Cashgram is activated by default for Payout users.

    Here is a quick video to show how Cashgram works.

    <iframe title="Cashgram By Cashfree | Smart Payouts Links for your business" />

    If you have any questions, please contact your Account Manager, or you can fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1). Thank you for using Cashfree.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What is the difference in making a payout using a Recharge account and Payouts Direct?">
    The primary difference between a Payouts recharge account and Payouts Direct is that a Payouts recharge account gives merchants the flexibility to make payments to their customers using any method that they are comfortable with, namely bank, card, UPI, and wallet payments.

    Payouts Direct allows you to make instant and automated payments directly from your bank account. Cashfree’s Payouts Direct integrates directly with your bank account, eliminating the need to maintain funds in the Recharge account. The balance in your account is available to make the payments. However, payout methods such as cards, UPI, and wallet payments will not be available for disbursals.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How can I start using Payouts?">
    Steps to activate your Payouts account and start using Payouts to do single or bulk transfers:

    Step 1: Sign up on [Cashfree](https://www.cashfree.com/) and complete your KYC
    Step 2: Once your account is activated, you will get an account activation success email.
    Step 3: Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and start transferring money using the [Merchant Dashboard](https://merchant.cashfree.com/auth/login). You can use a sample Excel file to do bulk transfers or use [API](/docs/api-reference/payouts/overview).

    Watch - How to use Payouts by Cashfree:

    <iframe title="Payouts by Cashfree | Send Instant Bulk Payouts 24*7 even on bank holiday" />

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How can I recharge my Payouts account?">
    Here is how you can add funds to your Cashfree Payout wallet:
    Step 1: Log in to your Cashfree Dashboard.
    Step 2: Select **Payouts**.
    Step 3: Select **Fund Sources** and then select the fund source that you wish to recharge.
    Step 4: Scroll down and you should be able to see virtual bank accounts that you can use to recharge your Cashfree payout account.
    Step 5: Add any of them as a beneficiary from your Net Banking portal and initiate a bank transfer. Please add them as "Other Bank" and not "Same Bank", even if your account is with the same bank.
    Please note that all the recharges must be initiated from the whitelisted bank accounts.
    Recommendation: - Please add both of these virtual bank accounts as a beneficiary at your end so that, if there is a downtime with one of these banks, you can send the funds to the other virtual bank account.
    Once you've done this, the amount will be added to your account.

    Know more about 'Accounts':

    <iframe title="Payouts by Cashfree | Send Instant Bulk Payouts 24*7 even on bank holiday" />

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Why is my Payouts transfer in Pending or Initiated state?">
    If the beneficiary bank doesn’t provide a transfer acknowledgement in real-time, the transaction is marked as **Pending/Initiated**. The final status (Success or Failure) is typically updated within 3 working days. If there’s no update after this period, kindly reach out to the merchant for support.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How many banks can Cashfree send payouts to? Can payouts be processed on holidays?">
    For Payouts, we support transfers to 160+ banks in India.

    Payouts can be processed 24\*7 even on bank holidays with all leading banks. For the rest, the transfer will get settled on the next working day.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title=" Does the payout transfer happen instantly?">
    Payouts happen instantly for small amounts (up to a few lakhs) and can take
    1-2 hours for higher amounts. Sometimes banks face downtime with their
    platforms. Payouts are queued and dispatched once it's up and running again.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How to view the current webhook endpoint?">
    Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and go to **Payouts > Developers > Webhooks > Add Webhook URL**

    Know more:

    <iframe title="Payouts by Cashfree | Send Instant Bulk Payouts 24*7 even on bank holiday" />

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title=" Can I use more than one Payouts account?">
    Cashfree supports multiple payout accounts to support your business use cases.

    For example, If there are two distinct use cases for Payouts, such as in the case of Swiggy where they need to process payouts for both restaurants and delivery partners, they may require two separate accounts to manage these transactions efficiently then Cashfree will create an additional Payout account.

    Talk to your account manager or fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) to know more. You can switch between the accounts by selecting 'SWITCH ACCOUNTS' in the Payouts Dashboard.

    Know more about 'Accounts':

    <iframe title="Payouts by Cashfree | Send Instant Bulk Payouts 24*7 even on bank holiday" />

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How can I add a beneficiary?">
    You can add your customers, vendors, or partners as beneficiaries using their bank account details or UPIs to make instant and automated payments. You can also add them using the wallet details or a beneficiary’s card details. You can also upload Beneficiary details in Bulk.
    Once beneficiary payment details are added, all future payouts can happen using the beneficiary ID without entering other details.

    Steps: Go to [Merchant Dashboard](https://merchant.cashfree.com/auth/login) - Payouts - Beneficiaries - All/Batch - Add Beneficiary

    Know more:

    <iframe title="Payouts by Cashfree | Send Instant Bulk Payouts 24*7 even on bank holiday" />

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Do I need to be a registered business to use Cashfree Payouts?">
    Yes, Payouts can be used only by registered businesses.

    If you are not yet registered as a business but plan to start soon, you can sign up and explore the product in the test environment.

    We can also set up an account with limits on payout volume after understanding your business and future needs.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Why did my transfer request fail?">
    Bank Transfer: Bank transfers can fail if the beneficiary bank is unable to
    process the transfer request in real-time. You can re-try the transfer
    attempts in such cases after a few minutes. Learn more in the [transfer lifecycle: failed transfers guide](/docs/payouts/payouts/make-payouts/lifecycle#failed).
    If this issue persists, please reach out to us with the bank account number
    and IFSC code.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How can I transfer funds from one Payout account to another?">
    You can transfer funds from one Cashfree Payout account to another using the Internal Transfer option.

    You will see the Internal Transfer option in the Payouts Dashboard once you have more than one Payouts account enabled.

    Select **Transfer** > **Quick Transfer** > Select the **Account** and enter the **Amount** > Select **Transfer** to transfer the amount.

    Write to the Cashfree team at [support team](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1), if you want to use more than one Payouts account.

    Know more:

    <iframe title="Payouts by Cashfree | Send Instant Bulk Payouts 24*7 even on bank holiday" />

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Transaction status is showing as 'Failed'. When will I receive the funds?">
    If the status is 'Failed', kindly re-initiate the transfer.

    In this case, ideally, the amount will not be debited from your payouts account. If debited, money will be reversed to you by the remitter bank within 24hrs.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How to make a Batch transfer of funds to beneficiaries using file upload?">
    You can use the ‘Batch Transfer’ feature to create and initiate a large number of transfers to the beneficiaries.

    * Select **Download sample file** to find out the details required to be filled in the batch file.

    * Add all the required details in the sample downloaded and click **Upload File** to upload the Batch transfer file.

    * You can also use various filters like **Processing**, **Pending Approval**, **Rejected** and **Cancelled** etc. to search the transfers.

    * If you wish to download a **Transfer Report**, click the **Download** button to do the same.

    Know more:

    <iframe title="Payouts by Cashfree | Send Instant Bulk Payouts 24*7 even on bank holiday" />

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Customer initiated a withdrawal, but the amount was not received?">
    The transfer will be done instantly.

    If the status is Queued, our partner bank wouldn't have shared with us a response regarding the status of the transfer.

    If the status has not changed post 24 hours of the withdrawal initiation, please fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Transaction status is 'Reversed' but I have not yet received funds">
    Funds ideally get credited immediately.
    If not, please wait for 72 hrs as the amount would be with the beneficiary bank which is supposed to be reversed to your Payouts account.

    Post 24hrs, if the amount is not credited to you, please fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1)

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Do you support payouts to and from other countries?">
    Yes, it is possible to send bulk payouts to beneficiaries in India from another country using Global Payouts. The funds can be added by the businesses in USD, EUR and other freely convertible currencies. The purpose of the payment must be known while setting up the account.

    An Indian business can also send a payout to other countries. However, there are restrictions around the volume of payments and the purpose of payments. [Get in touch](https://www.cashfree.com/contact-sales/) with us to learn more.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Transaction was successful, but later showing as reversed">
    If the status changed to Reversed after Successful, inform the customer to check the details below:

    * Incorrect account details.
    * Reversal by the clearinghouse.
    * Reversal by the beneficiary bank due to technical issues.

    Here, Cashfree credits the original amount to your Payouts account.
    Select a transfer that has been reversed to view more details about the transaction.

    <Note>
      Reversed is a final state and does not allow transitioning to any other state.
    </Note>

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Where can I find my reversed transfers?">
    After a successful transaction, in rare cases, a transaction can be reversed by the bank a few days after a successful transaction. It is known as 'Reversed transfer'
    You can view all the transfers that have been reversed on a particular day/week by the bank under the ‘Reversed’ tab.

    This helps the merchant ensure that the transfer reversal is not missed and appropriate next steps can be taken. You can download all the transfers by clicking the **Export** button.

    Know more:

    <iframe title="Payouts by Cashfree | Send Instant Bulk Payouts 24*7 even on bank holiday" />

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How to make a quick transfer of funds to your beneficiaries?">
    You can make a ‘Quick transfer’ to your beneficiary using the Transfer feature.
    You can also check the status of recent payouts made to your beneficiaries.
    To make a quick transfer:

    1. Go to Payouts Dashboard > Transfers > select **Quick Transfer**.
    2. Enter the Beneficiary ID, select the Fund Source from which you want to transfer funds, and select the Transfer Method.
    3. Enter the Transfer ID, Amount, and Remarks.

    See [Quick Transfer](/docs/payouts/payouts/make-payouts/customers#quick-transfer) to know more about Quick Transfers.

    Know more:

    <iframe title="Payouts by Cashfree | Send Instant Bulk Payouts 24*7 even on bank holiday" />

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How is Payouts different from using banks for bulk payouts?">
    Bulk payouts via bank accounts happen by manually adding every beneficiary before transferring or by uploading a spreadsheet on the banking portal. Cashfree automates bulk payouts fully via APIs and offers a much simpler alternative.

    Unlike banks, where a single error in a payout file can block all the bulk payouts, using Cashfree, even if there are invalid records in a file, valid transfers go through. Reconciliation for failed and invalid transfers is automated so you always know which transfer failed out of hundreds of payouts, and why. At Cashfree, new beneficiary addition and activation is instant.

    Cashfree also allows you to send money to any Paytm Wallet, Amazon Pay Wallet, UPI ID or native wallets in addition to bank accounts, even on holidays. Lastly, all of this can be automated and built into your product or internal systems using our powerful Payouts APIs.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Transaction status is showing 'sent to beneficiary'">
    In most cases, the transfer status changes to successful, and the amount will be credited to the customer (or reversed if the customer's account details are incorrect or if the beneficiary bank encounters technical issues) within 24 hours of initiation. However, in rare cases, it may take up to 72 hours, depending on the beneficiary bank.

    If the status remains unchanged after 72 hours, please fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) for further assistance.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Is it simpler to send bulk payouts file uploads or via APIs?">
    Using bulk file uploads or manual transfers requires no technical expertise and is the quickest way to get started.
    However, if you want to automate the payouts from your product or ERP, APIs should be used.

    Integrating the API can take a day or two, depending on the complexity of the integration.

    Many businesses start by using the bulk file upload or manual transfer option, and gradually automate operations by integrating the API.

    View the [batch transfer developer documentation](/docs/api-reference/payouts/v1/batch-transfer).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Do Payout v1 and v2 use the same base URL?">
    No. For Payout v2, the production base URL is `api.cashfree.com/payout` and the sandbox base URL is `sandbox.cashfree.com/payout`. The v1 base URLs, `payout-api.cashfree.com` for production and `payout-gamma.cashfree.com` for test, belong to the deprecated v1 API. Do not mix v1 base URLs with v2 endpoint paths, since this causes 404 errors. When you migrate from v1 to v2, update both the base URLs and the endpoint paths together.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What happens in case the account details are incorrect">
    Transfers to incorrect account details fail instantly.
    For certain banks, it may take up to 24 hours to receive a confirmation of failure.

    To ensure that account details are correct, you can activate Cashfree Bank Account Verification and verify the beneficiary account validity and beneficiary name at the bank.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Why is a payout transfer rejected even though the account number and IFSC are correct?">
    Some banks store the account holder's name with a title prefix, such as Mr., Mrs., or Dr. To register a beneficiary correctly:

    1. Run a penny drop or [Bank Account Validation](/docs/secure-id/kyc-stack/verify-bank-account) to retrieve the name as recorded by the bank.
    2. Register the beneficiary in Cashfree using that exact name, including any title prefix.

    The registered name must match the bank-verified name to pass validation.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are the different types of reports and how to access them?">
    Cashfree offers a wide range of ‘Payouts Reports’ such as:

    * Transfer reports - Here you can view details of the Payouts made and Cashgrams that are redeemed for the date range selected.

    * Account Statement -In this report, you can view details of all the credits and debits in your Payouts account.

    * Reversed Transfers - Here you can view details like date, time, and reason of all transfers that are reversed.

    Other reports like Cashgram, PAN Verification and Bank Validation are also available.

    To download a report → Just select the ‘Report type’ → You can use various filters to generate your report as per your preference
    Now, click **Generate Report** to generate the report. You can now download the generated report or delete it.
    You can also search and filter the generated reports.

    Know more:

    <iframe title="Payouts by Cashfree | Send Instant Bulk Payouts 24*7 even on bank holiday" />

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I edit beneficiary details?">
    The feature to edit beneficiaries is not available on the dashboard.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How to assign approver to verify Bulk Transfers?">
    The Batch Transfers need approval before the amount gets transferred to the respective beneficiaries.

    Therefore, under the ‘Approve Batch’ tab, the same can be accepted or rejected.

    It is an optional feature, which can be enabled upon request.

    Go to the ‘Approve Batch’ tab → Select a file → And you can Approve or Reject the transfers.

    Approvals can work at a ‘transfer level’ as well as ‘file level’ - where all or partial transfers can be approved at once.

    Know more:

    <iframe title="Payouts by Cashfree | Send Instant Bulk Payouts 24*7 even on bank holiday" />

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="I am unable to upload the batch file in beneficiaries and transfers?">
    We regret the inconvenience caused. Please fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1)
    from your registered email ID.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How do I delete a beneficiary?">
    To delete a beneficiary:

    1. Go to Payouts Dashboard > Beneficiaries.
    2. Select the beneficiary you want to delete, then select **Delete** on the right of the dashboard.
    3. You cannot initiate payouts to beneficiaries after you have deleted them.

       <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How to enable email updates for daily reports and transfers notifications?">
    You can configure the different categories for which you want to receive emails for
    notifications from Cashfree, like Set email preference for daily
    reports and transfer notifications, enable or disable transfer initiation
    email, etc. To enable the email notifications: 1. Log in to the Payouts
    dashboard using your credentials, and select **Settings** from the top navigation
    pane. 2. Select [Email
    Notifications](https://merchant.cashfree.com/payouts/settings/email-notifications)
    under the Payouts card. Learn more in the [email notifications guide](/docs/payouts/payouts/dashboard/set-email-notifications).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Payouts transfer initiated but not credited to the customer?">
    The transfer will be done instantly.

    If the customer states that the money is not credited, please check the status of the transfer as follows:
    Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and go to **Payouts > Transfers** to check the **Status** of the respective transfer.

    Pending: The payout is in progress and awaiting confirmation from the bank.

    Sent to Beneficiary: Inform the customer to wait for 24 hours as the money is with the remitter bank.

    Success: When the remitter's bank has completed the transfer, the payout is in the Success state. Kindly Share the UTR with the customer to check with their respective bank.

    Processing: The payout request has been received and is being processed.

    Failed: Transfers to incorrect account details fail instantly. For certain banks, it may take up to 24 hours to receive a confirmation of failure. Kindly re-initiate the transfer.

    Reversed: A payout can be in the Reversed state due to various reasons, such as:

    * Incorrect account details
    * Reversal by the clearinghouse
    * Reversal by the beneficiary bank
      Reversed is a final state and does not allow transitioning to any other state. Cashfree credits the original amount to your Payouts account.

      <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How can I whitelist IP addresses?">
    To whitelist your IP,

    Go to Payouts Dashboard > Developers section on the left-side navigation > Payouts > Two-Factor Authentication > IP Whitelist.
    Select **Add IP Address**.

    Enter the IP Address you want to whitelist and save the details. All the IP's you have whitelisted will be displayed as shown below.
    **Note**- You can whitelist a maximum of 10 IPs.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What do the different transfer statuses mean?">
    A payout moves through several statuses before it reaches a final state. See [Payouts lifecycle](/docs/payouts/payouts/make-payouts/lifecycle) for the product states, and [Get Transfer Status API](/docs/api-reference/payouts/v2/transfers-v2/get-transfer-status-v2) for the `status` and `status_code` values returned by the API.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Does Cashfree have visibility into my bank account entries for Connected Banking transactions?">
    No. Cashfree cannot see your bank account or the corresponding debit and credit entries at the bank. To confirm whether funds were debited or credited for Connected Banking transfers, check your bank statement. See [Add a bank account as a fund source](/docs/payouts/payouts/fund-management/bank-account).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How to withdraw funds from Cashfree?">
    Cashfree supports fund withdrawals through different products. The process varies depending on whether you're using Payments (PG), Payouts, or SecureID.

    **Payments (PG)**
    To initiate an on-demand withdrawal from Payments Gateway:

    1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
    2. In the left navigation panel, go to Settlements.
    3. Select On-demand from the dropdown.
    4. Select **Withdraw Now** next to the available balance.
    5. A list of previously initiated withdrawals is also displayed on this screen.

    **Payouts**

    To initiate withdrawal funds from your Cashfree Payouts wallet:

    1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
    2. Navigate to Fund Sources > Cashfree Wallet.
    3. Under the Overview section, select **Withdraw** next to Last Withdrawal.
    4. Enter the withdrawal Amount and Remarks, then select **Withdraw**.

    **SecureID**

    To withdraw funds from your SecureID account:

    1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
    2. In the left navigation panel, go to Accounts.
    3. A summary of your account transactions will be displayed.
    4. Select **Withdraw** to initiate the fund withdrawal.

    **Withdrawal guidelines:**

    * Maximum 3 withdrawals allowed per day.
    * Funds are credited only to your registered business bank account.
    * Processing time is between 8:00 AM and 6:45 PM, Monday to Saturday except 2nd and 4th Saturdays.
    * Withdrawals are non-reversible once submitted.
    * It may take 30 minutes to a few hours for the credit to reflect.

    <iframe title="FAQ feedback: Withdraw funds" />
  </Accordion>

  <Accordion title="What are the charges for using Cashfree Payouts?">
    Cashfree doesn't publish a standard rate card for Payouts. Pricing is customised based on your transaction volume, payout modes used, and business category.

    To get pricing for your business, submit this [Contact Sales form](https://www.cashfree.com/contact-sales/).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How do I configure webhooks for Payouts in the sandbox and production environments?">
    Payouts webhooks are specific to each environment. Configure a webhook in test for sandbox events, and configure a separate webhook in production for live events. Complete these steps:

    1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
    2. Go to **Payouts**.
    3. Select **Switch to Test** for sandbox, or select **Switch to Prod** for production.
    4. Go to **Developers > Webhook** in the **Payouts** section.
    5. Select **Add Webhook URL**.
    6. Enter the URL where you want to receive payout event updates.
    7. Select **Test & Add Webhook**.

    When you select **Test & Add Webhook**, Cashfree sends a `LOW_BALANCE_ALERT` event to confirm that the endpoint is reachable and returns HTTP `200 OK`. After the endpoint is validated, Cashfree delivers subsequent webhook events to that URL.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How do I enable Payouts on my Cashfree account?">
    To enable Payouts, submit the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1). Cashfree reviews the request and enables Payouts on your account.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How can I fetch my fund source balance via API?">
    Use the [Get Balance V1.2 API](/docs/api-reference/payouts/v1/get-balance-v12) to retrieve the ledger balance and available balance of your account. Generate a bearer token with the [Authorize API](/docs/api-reference/payouts/v1/authorize) and pass it in the `Authorization` header.

    `paymentInstrumentId` is an optional query parameter. Omit it to fetch the default fund source balance. Pass `paymentInstrumentId` only when you need the balance of a specific fund source.

    <iframe title="FAQs feedback component" />
  </Accordion>
</AccordionGroup>


# IP Whitelist and Public Key
Source: https://www.cashfree.com/docs/help/payouts/ip-whitelist

Learn why Cashfree Payouts requires IP whitelisting and a public key, how to register them, and how these controls add an extra layer of API authentication.

<AccordionGroup>
  <Accordion title="Why do I have to whitelist the IP address or generate a public key?">
    Whitelisting the IP address or generating a public key provides a layer of authentication. These cybersecurity techniques prevent anonymous or unknown disbursement requests and allow only verified requests.
  </Accordion>

  <Accordion title="What is an IP address?">
    A string of characters that identifies each computer using the Internet Protocol to communicate over a network. Computers use IP addresses to communicate with each other over the internet.
  </Accordion>

  <Accordion title="What does it mean to whitelist an IP?">
    Whitelisted IPs are an index of approved entities. A whitelist approves a list of email addresses, IP addresses for communication.
  </Accordion>

  <Accordion title="What happens after I whitelist my IP address?">
    The Cashfree production server allows your API requests.
  </Accordion>

  <Accordion title="How many IP addresses can I whitelist?">
    You can whitelist a maximum of 25 IP addresses.
  </Accordion>

  <Accordion title="Does Cashfree support IPv6?">
    No, we only support API requests from IPv4 at the moment.
  </Accordion>

  <Accordion title="Why does an IP whitelisting error occur even after whitelisting an IP, and how can it be resolved?">
    An IP whitelisting error can occur if multiple Payout accounts exist and the IP address is whitelisted only on one account, but the API keys in use belong to a different account. To resolve this, whitelist the IP address on all Payout accounts and ensure the correct set of API keys is used for the intended account. Switching to the appropriate account usually fixes the issue and prevents further authentication errors.
  </Accordion>

  <Accordion title="When do I use a public key?">
    If your IP address is not static, generate a public key in the Cashfree portal.
  </Accordion>

  <Accordion title="How to generate a public key from the Cashfree portal?">
    1. In the Cashfree dashboard, select **Developers** from the navigation panel on the left.
    2. Click **Two-Factor Authentication** from the **Payouts** card.
    3. Select **Public Key** from the **Select 2FA Method** dropdown menu.
    4. Click **Generate Public Key**.
    5. The public key is downloaded to your computer. Use your registered email ID to access the key.

       <img alt="" />
  </Accordion>

  <Accordion title="How many public keys can I generate at a time?">
    One. You can generate only 1 public key at a time.
  </Accordion>

  <Accordion title="How to use the public key to send API requests?">
    You need to generate a signature and proceed with the API requests.

    Below are the steps to generate the signature:

    1. Retrieve your client ID.
    2. Append this with CURRENT UNIX timestamp separated by a period (.).
    3. Encrypt this data with the generated public key using RSA encryption - this is the signature.
    4. Pass this signature in the header X-CF-Signature.
  </Accordion>

  <Accordion title="Do Payment Gateway (PG) APIs require IP whitelisting?">
    No. Payment Gateway APIs do not require IP whitelisting. Other Cashfree products can require IP whitelisting as part of their API authentication. Check the documentation for the product whose API you are calling.

    If you receive a `Broken Link` or `not enabled` error during testing, confirm that you are not applying another product's IP whitelist requirement to a Payment Gateway API call.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Which Client ID should I use for Public Key Signature Authentication, and how do I resolve a 'Signature Mismatched' error?">
    For the Public Key Signature Authentication flow, use the oldest (first) Client ID created for the account. To check the creation dates of your API keys, log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and go to **Developers > Two-Factor Authentication**.

    To resolve a `Signature Mismatched` error, verify the following:

    * Pass the oldest (first) Client ID in the `X-Client-Id` header.
    * Form the string as `clientId.unixTimestamp` (Client ID, a dot, then the current UNIX timestamp).
    * Encrypt the string using RSA with OAEP padding and the public key downloaded from the Merchant Dashboard. Base64-encode the result and pass it in the `X-Cf-Signature` header.
    * Generate a new signature every 5 minutes. The signature is valid for 5 minutes. See [2FA: IP Whitelisting and Public Keys](/docs/payouts/payouts/integrations/payouts-2fa).
    * Use a Client ID and public key from the same environment (for example, the same Payouts or Secure ID account).

      <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Which Cashfree IP addresses should I whitelist in my server firewall?">
    To receive Payouts webhooks, whitelist Cashfree's IP addresses on your server. See the list in [IPs to whitelist](/docs/api-reference/payouts/v2/webhooks/webhooks-v2#ips-to-whitelist).
  </Accordion>
</AccordionGroup>


# Aadhaar Verification
Source: https://www.cashfree.com/docs/help/secure-id/aadhaar-verification

Find answers to Aadhaar verification FAQs covering supported APIs, consent requirements, masking rules, response codes, and accepted document formats.

<AccordionGroup>
  <Accordion title="What Aadhaar verification methods does Cashfree offer?">
    Cashfree offers two primary Aadhaar verification methods:

    * **DigiLocker verification**: Secure, government-approved verification where users share documents directly from their DigiLocker account with consent
    * **OCR verification**: Image-based verification using optical character recognition technology to extract details from uploaded Aadhaar documents

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Which verification method should a business choose?">
    The choice depends on specific requirements:

    * **Choose DigiLocker verification** to prioritise security, compliance, and user experience. It's government-verified, requires no document uploads, and is DPDPA compliant
    * **Choose OCR verification** to handle physical documents or workflows that require image-based verification

    DigiLocker is generally recommended for most businesses due to its superior security and user experience.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What if a customer doesn't have a DigiLocker account?">
    Yes, customers can still use DigiLocker verification even without an existing account. If a customer doesn't have a DigiLocker account, they can create one during the verification process. The system will guide them through:

    * Creating a new DigiLocker account using their Aadhaar-linked mobile number
    * Setting up a PIN for account security
    * Providing consent to share their Aadhaar document

    This typically takes 2-3 minutes and only needs to be done once.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What happens if a customer's Aadhaar isn't linked to DigiLocker?">
    If the Aadhaar isn't linked to DigiLocker, the verification can't proceed through DigiLocker. In this case, you can:

    * Use the OCR verification method instead
    * Advise the customer to link their Aadhaar to DigiLocker through the official DigiLocker website
    * Check with the customer if they have an existing DigiLocker account with different credentials

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Do I have to pay in advance, or can I pay after the Aadhaar verification is done?">
    There is an option to pay either way - pre-paid or post-paid. Please get in
    touch with our sales team to find the best suitable method for you.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What is OTP-based Aadhaar Verification?">
    OTP-based Aadhaar verification is discontinued. Use the [Verify DigiLocker Account API](/docs/api-reference/vrs/v2/digilocker/verify-digilocker-account) for Aadhaar verification. See [Aadhaar Verification](/docs/secure-id/kyc-stack/verify-aadhaar) for the supported methods.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Does Cashfree support OKYC (Offline KYC) for Aadhaar verification?">
    No, OKYC (Offline KYC) isn't supported for Aadhaar verification.

    For Aadhaar verification, we recommend using:

    * **Smart OCR API**: Extract and verify Aadhaar details from document images
    * **DigiLocker integration**: Verify Aadhaar through government-backed DigiLocker platform
    * **Video KYC**: Complete verification through live agent-assisted video calls

    These alternatives provide secure and compliant Aadhaar verification without requiring OKYC.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What all details can be verified through OTP-based Aadhaar Verification?">
    The following details can be verified through OTP-based Aadhaar Verification, by Cashfree:

    * Registered Name

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How can you track if DigiLocker verification was successful?">
    You can track the verification status through multiple methods:

    * **Real-time status checks**: Use the Get Verification Status API to check current progress
    * **Webhook notifications**: Receive instant updates when status changes (PENDING, AUTHENTICATED, EXPIRED, CONSENT\_DENIED)
    * **Final document retrieval**: Once successful, use the Get Document API to retrieve the verified Aadhaar details

    The entire process typically completes within 2-3 minutes.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How to handle blurry Aadhaar image uploads?">
    For OCR verification, image quality is crucial. If the image is blurry:

    * Ask the customer to retake the photo ensuring good lighting and focus
    * Verify the Aadhaar number is clearly visible and not scratched or damaged
    * Ensure the image captures the entire document without cutting off edges
    * Avoid including other objects in the photo

    Consider switching to DigiLocker verification to avoid image quality issues entirely.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can you verify someone's Aadhaar using only their name?">
    No, you can't verify an Aadhaar card using only the person's name. For security and privacy reasons, Aadhaar verification requires:

    * The complete 12-digit Aadhaar number for both DigiLocker and OCR verification methods
    * User consent (explicit for DigiLocker, implied for OCR verification)
    * Proper authentication through the respective verification flow

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Is DigiLocker verification legally compliant for KYC requirements?">
    Yes, DigiLocker verification is fully compliant with regulatory requirements:

    * **Government-approved**: DigiLocker is an official government platform
    * **DPDPA compliant**: Meets Digital Personal Data Protection Act (DPDPA) 2023 requirements
    * **User consent-based**: Explicit user consent is obtained before accessing documents
    * **Audit trail**: Complete verification history is maintained for compliance

    This makes it suitable for KYC requirements across banking, lending, insurance, and fintech sectors.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What details are accessible after successful Aadhaar verification?">
    The accessible details depend on the verification method used:

    **DigiLocker verification provides:**

    * Full name as registered
    * Complete address
    * Date of birth
    * Gender
    * Aadhaar number
    * Father's name (if available)

    **OCR verification extracts:**

    * Aadhaar number
    * Name
    * Address
    * Other visible details from the document image

    DigiLocker typically provides more comprehensive and accurate information.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Is upfront payment required for Aadhaar verification services?">
    Cashfree offers flexible payment options to suit business needs:

    * **Prepaid**: Pay in advance and use credits for verification
    * **Postpaid**: Pay after using the verification services based on usage

    Contact the sales team to discuss the most suitable payment model for business volume and requirements.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How secure is DigiLocker verification for privacy-conscious customers?">
    DigiLocker verification offers the highest level of privacy and security:

    * **Government-managed**: DigiLocker is owned and operated by the Government of India
    * **Explicit consent**: Documents are shared only after user provides clear consent
    * **No document storage**: Cashfree doesn't store physical document copies
    * **Secure transmission**: All data transfers use encrypted channels
    * **Limited access**: Only specific requested details are shared

    You can assure customers that this method is more secure than sharing physical document copies.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What happens if verification fails or times out?">
    Different scenarios can cause verification issues:

    **DigiLocker verification failures:**

    * **EXPIRED**: Link expired (10-minute validity) - generate a new link
    * **CONSENT\_DENIED**: User rejected consent - try document processing method
    * **Network issues**: Retry after some time or use alternative method

    **OCR verification failures:**

    * **Poor image quality**: Request better quality images
    * **Invalid document**: Verify it's a genuine Aadhaar card
    * **Processing errors**: Retry or contact support

    Always implement fallback mechanisms and proper error handling in your integration.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Are there any volume limits for Aadhaar verification?">
    Cashfree supports high-volume verification requirements:

    * **Rate limits**: Standard API rate limits apply - contact support for higher limits
    * **Daily volumes**: No specific daily caps, but enterprise customers get priority processing
    * **Concurrent requests**: Multiple parallel verifications supported
    * **Bulk processing**: Available for large-scale verification needs

    For high-volume requirements (10,000+ verifications per day), contact the sales team for optimised pricing and performance.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What is the validity of the received OTP?">
    The generated OTP will be valid for 10 minutes.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How fast do verification results come back?">
    Response times vary by verification method:

    **DigiLocker verification:**

    * Initial API response: Immediate (URL generation)
    * User completion time: 2-3 minutes (depends on user actions)
    * Final document retrieval: 1-2 seconds after user consent

    **OCR verification:**

    * Image upload processing: 30-60 seconds
    * Data extraction: Near real-time
    * Verification result: Within 1-2 minutes

    Use webhooks for real-time notifications instead of polling for status updates.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can verification be integrated into mobile applications?">
    Yes, both verification methods work seamlessly in mobile applications:

    **DigiLocker on mobile:**

    * Use WebView or in-app browser to load DigiLocker consent URL
    * Handle redirect URLs to capture completion status
    * Optimised mobile interface provided by DigiLocker

    **OCR verification on mobile:**

    * Camera integration for document capture
    * Image quality validation before upload
    * Real-time feedback for better user experience

    SDKs and mobile-specific documentation available for popular platforms (Android, iOS, React Native, Flutter).

    <iframe title="FAQs feedback component" />
  </Accordion>
</AccordionGroup>


# Bank Account Verification
Source: https://www.cashfree.com/docs/help/secure-id/bav

Get answers to bank account verification FAQs about penny-drop checks, name match logic, response codes, supported banks, and resolving verification failures.

<AccordionGroup>
  <Accordion title="I want to use Cashfree marketplace settlement for paying vendors. Do I need to take verification feature separately?">
    Yes, if you are using Cashfree marketplace settlement and want to use verification API as well, you need to opt for the feature separately. Our payment experts will help you with integration and you will be able to use the Cashfree marketplace settlement and Secure ID together.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How can I use Bank Account Verification API for KYC?">
    KYC or “Know Your Customer” is a process to be undertaken by businesses especially financial institutions to obtain information about the identity and address of the customers. One of the key documents is bank account details as the same is regarded as valid proof of the identity of a person/entity.

    While onboarding vendors, delivery partners, or even employees, an organisation needs to do a bank account verification. Using Cashfree API, this process can be automated by integrating with the company's existing internal system so that the bank verification process happens smoothly, without exposing the data to any third party. You can also verify PAN, Aadhaar and GSTIN of users or businesses with our Verification Suite.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="For how many banks, can I do the verification?">
    The verification can be done for all the a/c of recognised Indian banks including all public banks, private banks, and 126+ co-operative banks\*.

    <Note>
      Verification may not be possible for some cooperative bank accounts.
    </Note>

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How to verify a/c number on Cashfree for multiple individuals?">
    On Cashfree, you can do verification for any number of Indian bank accounts via two modes:

    1. Manual entry on Cashfree Bank Account Verification dashboard:
       Here you will be required to enter only two details: Indian bank account number and IFSC. If you want to do bulk verification, You can access the bulk upload feature on the dashboard where you can submit a CSV/XSLX file with required details and get a quick response.

    2. Using Bank Account Verification API:
       This is an integrated automated way to do single/bulk verification. The API can be integrated with the existing company internal system or ERP and then the request can be pushed directly using APIs.

       <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Why is Bank Account Verification important?">
    Our Plug and Play integrated a/c number Verification API helps you confirm bank account validity instantly. By accessing updated data, the risk of identity fraud and incorrect/incomplete data is reduced. The result such as the account holder’s name shown to you will be exactly as it appears in bank records.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Why does Bank Account Verification return a successful result even when the IFSC looks wrong?">
    The API validates the account using a penny drop over IMPS (Immediate Payment Service). IMPS reads only the first 5 characters of the submitted IFSC to identify the bank, not the full branch-specific code. As a result, verification can return a successful result even when the branch-specific part of the IFSC is incorrect. A successful response confirms the account can receive funds, not that the exact IFSC is correct for that branch. See [Verify a bank account](/docs/secure-id/kyc-stack/verify-bank-account) for more detail on this behaviour.

    As an optional additional check, some merchants make a small test payout through the [Payouts API](/docs/api-reference/payouts/overview) to confirm delivery before relying solely on Bank Account Verification.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Why does the Bank Account Verification v1 API return a 422 error?">
    The Bank Account Verification v1 API is deprecated in favour of the v2 API. A 422 error from the v1 endpoint reflects this deprecated status. Migrate to the current Bank Account Verification v2 API. See [Verify a bank account](/docs/secure-id/kyc-stack/verify-bank-account) for the current integration guide.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="I am planning to opt for Cashfree Payouts for bulk disbursals. Do I need to go for verification API separately?">
    Yes, Payouts is different. Users can integrate Bank Account Verification to do the validation and will be charged separately.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are the other use cases of this(BAV) feature?">
    The capability to verify a/c can be used in multiple business scenarios such as:

    1. A crucial part of the verification process before providing loans of all kinds (education, health, business, car etc)

    2. Employee background check: A recruitment agency can use the feature for a candidate's background check

    3. Vendor onboarding: A marketplace splitting commission with different vendors can use the feature to verify the a/c details at the time of onboarding the vendor, this also helps in correct payments later on.

    The ability to integrate the API with existing ERP helps in reducing operational effort and saves cost by 90%.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Is there any limit on the total number of Bank Account Verification requests per day?">
    No, there is no such limit. You can use this feature to verify any number of bank accounts in a day 24\*7.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How much time does verification take?">
    On Cashfree, you can verify a/c numbers instantly. As you submit the request, our API gives an instant response.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Is there any limit on the total number of UPI requests per day?">
    No, there is no such limit. You can use the feature to verify any number of UPI IDs in a day 24\*7.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="I am planning to opt for Cashfree Payouts for bulk disbursals on UPI ID. Do I need to go for Verification API separately?">
    If you are a Payouts merchant, the Secure ID products such as Bank Account Verification (including UPI), Aadhaar Verification, GSTIN Verification, and PAN Verification will be automatically enabled for you. However, you will be charged separately for each validation.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How to verify UPI ID on Cashfree for multiple individuals?">
    On Cashfree, you can do verification for any number of UPI IDs of individuals or entities via two modes:

    1. Manual entry on Cashfree UPI ID verification dashboard.
       Here you will be required to enter only one detail: UPI ID (eg abc\@okaxis)

    2. Using API
       An integrated automated way to do UPI Verification. The API can be integrated with the company's existing internal system or ERP and the request can be pushed directly using APIs.

       <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What is UPI ID Verification?">
    UPI ID (also called Virtual Payment Address or VPA) is a unique ID you need to create to send and accept money via UPI. Once a UPI address is created and mapped against your existing bank account, you can simply share your UPI address (eg. abc\@okaxis) with the payer.

    As a business, verifying a UPI ID comes in handy. The different use cases can be

    * Background verification at the time of onboarding a new user/vendor
    * Before releasing payment to a UPI ID

    With Cashfree instantly verify if the UPI ID is valid, For a Valid UPI ID cross-verify the name of the account holder

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How much time does the Verification take?">
    On Cashfree, you can verify any number of UPI IDs instantly. As you submit the request, our API gives an instant response.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are the required parameters for the Bank Account Verification API and how should the phone number be formatted?">
    Both the v1 and v2 Bank Account Verification APIs accept a phone number. You can omit `phone` in either version if you do not need to pass it.

    For the v1 API (`/payout/v1/validation/bankDetails` and `/payout/v1.2/validation/bankDetails`), `bankAccount` and `ifsc` are required. `name`, `phone`, and `remarks` are optional. If you include `phone`, it must contain digits only and be 8 to 12 characters long. See [Bank Verification Sync V1.2](/docs/api-reference/vrs/v1/bank-account-verification/bank-verification-sync-v12).

    For the v2 API, `bank_account` and `ifsc` are required. If you include `phone`, it must contain digits only and be 8 to 13 characters long. See [Bank Account Verification Sync V2](/docs/api-reference/vrs/v2/bav-v2/bank-account-verification-sync-v2).

    <iframe title="FAQs feedback component" />
  </Accordion>
</AccordionGroup>


# Secure ID
Source: https://www.cashfree.com/docs/help/secure-id/general-faqs

Browse Cashfree Secure ID FAQs covering supported verification APIs, onboarding requirements, pricing models, sandbox testing, and rate-limit guidelines.

<AccordionGroup>
  <Accordion title="How to withdraw funds from Cashfree?">
    Cashfree supports fund withdrawals through different products. The process varies depending on whether you're using Payments (PG), Payouts, or SecureID.

    **Payments (PG)**
    To initiate an on-demand withdrawal from Payments Gateway:

    1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
    2. In the left navigation panel, go to Settlements.
    3. Select On-demand from the dropdown.
    4. Click **Withdraw Now** next to the available balance.
    5. A list of previously initiated withdrawals is also displayed on this screen.

    **Payouts**

    To initiate withdrawal funds from your Cashfree Payouts wallet:

    1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
    2. Navigate to Fund Sources > Cashfree Wallet.
    3. Under the Overview section, click Withdraw next to Last Withdrawal.
    4. Enter the withdrawal Amount and Remarks, then click **Withdraw**.

    **SecureID**

    To withdraw funds from your SecureID account:

    1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
    2. In the left navigation panel, go to Accounts.
    3. A summary of your account transactions will be displayed.
    4. Click **Withdraw** to initiate the fund withdrawal.

    **Withdrawal guidelines:**

    * Maximum 3 withdrawals allowed per day.
    * Funds are credited only to your registered business bank account.
    * Processing time is between 8:00 AM and 6:45 PM, Monday to Saturday except 2nd and 4th Saturdays.
    * Withdrawals are non-reversible once submitted.
    * It may take 30 minutes to a few hours for the credit to reflect.

    <iframe title="FAQ feedback: Withdraw funds" />
  </Accordion>

  <Accordion title="What are the charges for using Secure ID?">
    Cashfree doesn't publish a standard rate card for Secure ID verification APIs. Pricing is customised based on the verification APIs you use and your monthly volume.

    To get pricing for your business, submit this [Contact Sales form](https://www.cashfree.com/contact-sales/).

    <iframe title="FAQ feedback: Secure ID pricing" />
  </Accordion>
</AccordionGroup>


# GSTIN Verification
Source: https://www.cashfree.com/docs/help/secure-id/gstin-verification

Find answers to GSTIN verification FAQs on validating business identifiers, retrieving company details, handling cancelled GSTINs, and decoding response codes.

<AccordionGroup>
  <Accordion title="What are the details that I will be able to see on verifying the GSTIN of an entity?">
    The system will return whether the GSTIN is valid or not along with the following details (if valid):

    * The legal name of the business
    * GSTIN status
    * Taxpayer type
    * Date of registration
    * GSTIN
    * Nature of business
    * Business principal address

      <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Is there any limit to the number of GSTINs that can be verified in a day?">
    No, there is no limit to the number of GST numbers that can be verified in a day.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I verify the GSTIN by just knowing the name of the person?">
    No, to verify a GSTIN, it is mandatory to enter the GST number.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Which businesses can benefit from GSTIN verification?">
    With GSTIN verification, businesses can now verify the GST number of an entity instantly. The following businesses can benefit from this feature:

    * Ecommerce marketplaces
    * B2B Reseller Companies
    * B2B Ecommerce
    * Tax processing and return filing platforms
    * Lending and micro-financing platforms
    * Insurance providers
    * Banks
    * Identity verification companies

      <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Do I need to pay in advance for GSTIN verification?">
    Yes, GSTIN verification requires prepaid payment. Please get in touch with our sales team to set up your account and find the best suitable plan for you.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are the details I need to input to verify a GSTIN?">
    All you need to input is the 15-digit GSTIN number of the business and you will get an instant verification status and other business details.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What is online GSTIN verification?">
    Online GSTIN verification lets businesses validate and verify the authenticity of their customer/vendor/employee’s GSTIN details to avoid identity theft or dealing with fraudsters.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What is the average response time for the GSTIN Api?">
    The average response time is less than a second.

    <iframe title="FAQs feedback component" />
  </Accordion>
</AccordionGroup>


# PAN Verification
Source: https://www.cashfree.com/docs/help/secure-id/pan-verification

Find answers to PAN verification FAQs covering basic and advanced API checks, name match rules, response codes, and accepted document formats during KYC.

<AccordionGroup>
  <Accordion title="How much time does PAN verification take?">
    On Cashfree you can verify up to 10,000 PANs instantly. As you submit the request, our API gives an instant response.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Which businesses can benefit from PAN Verification?">
    The PAN verification feature can be used to identify the person/businesses during onboarding as well as before initiating the transaction.

    Following business categories can use PAN verification to speed up their onboarding, KYC and payment process:

    * Lending platforms
    * Insurance providers and platforms
    * Investment portals
    * Wallets
    * EMI/instalments providers
    * Any form of credit providers
    * Offline and online marketplaces to onboard vendors, sellers
    * Large corporations for onboarding employees
    * Payments and fintech companies

      <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How to verify PAN using Cashfree for multiple PAN cards?">
    With Cashfree, you can do verification for any number of PAN via two modes:

    1. Via Dashboard
       You can use the dashboard to not only do single PAN verification, but you can also download the sample template, add PAN of users and upload the file and get instant response for up to 10,000+ PANs at a time.
    2. Using API
       This is an integrated automated way to do bulk verification. The API can be integrated with existing company internal systems or ERP and then requests can be pushed directly using API.

       <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="I want to use EasySplit - Cashfree marketplace settlement product for paying vendors. Do I need to take the PAN verification feature separately for vendor KYC?">
    Yes, if you are using EasySplit and want to use the PAN verification API as well, you need to opt for the feature separately. Our experts will help you with integration and you will be able to use EasySplit and PAN verification features together.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="I am planning to opt for Cashfree Payouts for bulk disbursals. Do I need to go for PAN verification API separately?">
    If you are a Payouts user, you can visit the dashboard to activate PAN verification for your account. PAN verification will be charged separately.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Is there any limit on the total number of PAN verification requests per day?">
    No, there is no such limit. You can use the feature to verify any number of PANs in a day 24\*7.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Why is PAN verification important?">
    PAN is a means of identifying various taxpayers in the country. The PAN system of identification is a computer-based system that assigns a unique identification number to every Indian tax-paying entity.

    Through this method, all tax-related information for a person is recorded against a single PAN number which acts as the primary key for the storage of information. This is shared across the country and hence no two people on tax paying entities can have the same PAN.

    Our Plug and Play integrated PAN verification API helps you confirm if PAN is valid or not, and match the name provided with the name registered with NSDL, the PAN issuing institution.

    By accessing updated data, the risk of identity fraud and incorrect/incomplete data is reduced.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What is online PAN verification?">
    Online PAN verification enables merchants to verify their users’ PAN card details, get the status of the PAN card, and check whether it belongs to a business or an individual.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are the details that I will be able to see on verifying a PAN?">
    You will be able to see whether the PAN is valid or not along with the following details (if valid):

    * PAN number
    * Name provided
    * Verification ID
    * PAN type
    * Name registered

      <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I verify the PAN card by just knowing the name of the person?">
    No, to verify a PAN, it is mandatory to enter the PAN number.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are the other use cases of PAN Verification feature?">
    The capability to verify PAN can be used in multiple business scenarios such as

    1. Employee background check: a recruitment agency can use the feature for a candidate's background check

    2. Vendor onboarding: a marketplace splitting commission with different vendors can use the feature to verify the a/c details at the time of onboarding the vendor, this also helps in correct payments later on. The ability to integrate the API with existing ERP helps in reducing operational effort and saves cost.

       <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How can I use the PAN verification API for KYC?">
    KYC or “Know Your Customer” is a process undertaken by businesses, especially financial institutions to obtain information about the identity of customers. One of the key documents required is PAN as the same is regarded as valid proof for the financial identity of a person/entity.

    While onboarding vendors, delivery partners, or even employees, an organisation needs to do a PAN verification. Using Cashfree API, this process can be automated and integrated with existing company internal systems so that the verification process happens smoothly, without exposing the data to any third party.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Why is an incorrect or different name returned in the PAN verification response?">
    If you use the [Verify PAN Sync API](/docs/api-reference/vrs/v2/pan/verify-pan-sync), the name can differ because Cashfree receives it from sync gateways. Use the [PAN Lite API](/docs/api-reference/vrs/v2/pan/pan-lite) when you need the registered name from the Income Tax Department.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Why is the Name Match information missing from my PAN verification API response even though it is visible on the Merchant Dashboard?">
    The Name Match feature in PAN verification is a chargeable service and must be explicitly enabled for your account. To activate this feature and get details on pricing, contact your Account Manager or fill in the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Why is the aadhaar_seeding_status field missing in the PAN verification API response?">
    To receive the <code>aadhaar\_seeding\_status</code> field in the PAN verification API response, pass the <code>x-api-version</code> header with a date after 2022-09-12. Cashfree recommends using API version <code>2024-08-01</code>.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Why is the father_name field blank in the PAN verification API response?">
    The <code>father\_name</code> field may appear blank because it is not received consistently from the source. Ignore this field in the API response for the time being, as it may be updated in the future.

    <iframe title="FAQs feedback component" />
  </Accordion>
</AccordionGroup>


# Reverse Penny Drop
Source: https://www.cashfree.com/docs/help/secure-id/reverse-penny-drop

Get answers to reverse penny drop FAQs covering verification flow, supported banks, customer experience, refund handling, and integration prerequisites for KYC.

<Accordion title="What is reverse penny drop verification?">
  Reverse penny drop verification is a service provided by Cashfree that allows you to verify bank account details by requesting a small transaction of one rupee from the account holder. After successful verification, the amount is refunded to the customer's account within 48 hours. Users can verify their bank account by launching any UPI app installed on their device.
</Accordion>

<Accordion title="What are the benefits of using reverse penny drop for businesses?">
  **Enhanced Security**: Adds an extra layer of security to the customer verification process. It ensures that the bank account belongs to the user and reduces the risk of fraudulent activities.

  **Reduced Chargebacks**: By confirming the authenticity of the bank account, businesses can significantly reduce the likelihood of chargebacks due to unauthorised transactions or incorrect bank details.

  **Compliance**: Many industries, especially in finance and fintech, are subject to regulatory requirements that necessitate thorough identity and account verification. Reverse penny drop helps businesses stay compliant with these regulations.

  **Improved User Experience**: It simplifies the verification process for users, making it convenient and efficient. Users don't need to provide extensive documentation, and verification can often be completed within minutes.

  **Cost Savings**: By reducing the need for manual verification processes and minimising the risk of fraudulent accounts, businesses can save on operational costs and potential financial losses.
</Accordion>

<Accordion title="What are the benefits of using reverse penny drop for users?">
  **Quick and Easy Verification**: Users can verify their bank accounts without the need for lengthy paperwork or physical visits to a bank branch. It's a hassle-free process that can be completed online.

  **Increased Trust**: Users can have greater confidence in the business they are dealing with, knowing that their bank account details have been verified, which can lead to higher trust levels in the platform or service.

  **Security**: Knowing that their bank account is protected against unauthorised access or fraud provides peace of mind to users, making them more comfortable with sharing their banking information.

  **Faster Access to Services**: Verified users can access and use services more quickly, as they don't have to wait for manual verification processes to be completed.

  **Reduced Errors**: The penny drop method ensures that the bank account details provided are accurate, reducing the chances of errors in financial transactions.
</Accordion>

<Accordion title="Can all lines of business use reverse penny drop?">
  At the moment, Cashfree reverse penny drop verification feature is available only for specific MCC codes:

  * **7322**: NBFC (debt collecting agencies)
  * **6012**: Mutual Funds (financial institutions - merchandise and services)
  * **6211**: Security Brokers/Dealers (merchants that buy, sell, and broker securities, stocks, bonds, commodities, and mutual funds)
  * **6300**: Insurance Sales, Underwriting, and Premiums

  This service isn't permitted for online gaming and e-commerce industries as per current RBI regulations.
</Accordion>

<Accordion title="How long is the reverse penny drop link valid?">
  The reverse penny drop link generated through the API is valid for 10 minutes. The customer must complete the verification within this time. If the customer does not complete the payment within 10 minutes, the link expires, and Cashfree updates the verification status to `EXPIRED` and sends a `RPD_BANK_ACCOUNT_VERIFICATION_EXPIRED` webhook event. Generate a new request for the customer to retry. See [Reverse penny drop webhooks](/docs/api-reference/vrs/v2/reverse-penny-drop/webhooks-reverse-penny).
</Accordion>

<Accordion title="Can I redirect users to a custom URL after payment completion?">
  Yes, you can optionally provide a `redirect_url` parameter when creating the reverse penny drop request. This URL specifies where the user should be redirected after completing the payment on the webpage. If you do not provide a `redirect_url`, users will be automatically redirected to `www.google.com` by default.
</Accordion>

<Accordion title="What information do I receive after successful verification?">
  After successful verification, you receive:

  * Bank account number
  * IFSC code
  * Virtual Payment Address (VPA) used for the transaction
  * Verification status and transaction details
  * URL link to the webpage containing the generated UPI link and QR code for the reverse penny drop request

  <Note>
    To enable the URL link field, fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) or contact your account manager.
  </Note>
</Accordion>

<Accordion title="How long does the refund process take?">
  The ₹1 verification amount is automatically refunded to the customer's account within 48 hours of successful verification.
</Accordion>

<Accordion title="What happens if the verification fails?">
  If the verification fails, the API returns a `FAILURE` status. Common reasons for failure include:

  * Network connectivity issues during payment
  * Insufficient balance in the customer's account
  * Payment timeout or cancellation by the user
  * Technical issues with the UPI infrastructure

  In case of failure, no amount is deducted from the customer's account.
</Accordion>

<Accordion title="Can users verify accounts from any bank?">
  Yes, users can verify accounts from any bank that supports UPI transactions. Since reverse penny drop works through the UPI infrastructure, any bank account linked to UPI can be verified using this method.
</Accordion>

<Accordion title="Is there a limit on the number of verification attempts?">
  There's no specific limit on verification attempts, but each attempt requires generating a new reverse penny drop request through the API. However, we recommend implementing reasonable rate limiting in your application to prevent abuse.
</Accordion>

<Accordion title="How do I handle the verification status in my application?">
  The API returns four possible status values:

  * `CREATED`: Request created but payment not yet made
  * `SUCCESS`: Verification completed successfully
  * `FAILURE`: Verification attempt failed
  * `EXPIRED`: Link expired (10 minutes) without payment

  Design your application flow to handle these status appropriately and provide clear feedback to users.
</Accordion>

<Accordion title="What security measures are in place to protect user data?">
  Cashfree implements multiple security layers:

  * All API communications use HTTPS encryption
  * Bank account information is transmitted securely through UPI rails
  * Data is stored with industry-standard encryption
  * Access to verification data is logged and monitored
  * Compliance with PCI DSS and other security standards
</Accordion>


# SoftPOS
Source: https://www.cashfree.com/docs/help/softpos/softpos

Find answers to SoftPOS FAQs on tap-to-pay setup on Android phones, supported card networks, transaction limits, settlement timelines, and device requirements.

## General

These FAQs cover what Offline Payments is, the three collection models, account prerequisites, and how to activate the product.

<AccordionGroup>
  <Accordion title="What are Cashfree Offline Payments and what are the benefits?">
    Cashfree Offline Payments is a solution that allows businesses to collect, track, and reconcile payments across in-person and remote collection journeys. With Offline Payments activated for your account, you can do the following:

    * Collect payments in-store or on the go.
    * Enable agents to collect payments on your behalf.
    * Track every transaction, including cash and digital, in one place.
    * Offer your customers more than 100 payment options.

    You also benefit from the following:

    * **Coverage across collection models**: Storefront, Agent (softPOS), and Customer VPA, depending on what you enable.
    * **Broad payment mode support**: Including UPI, cards, net banking, wallets, and more.
    * **Unified visibility**: Cash and digital payments together in one workflow.
    * **Simplified reconciliation**: Reporting aligned to how you collect.
  </Accordion>

  <Accordion title="What are the different types of Offline Payments services from Cashfree?">
    Cashfree Offline Payments offers three flexible ways to collect payments, depending on your business model:

    1. **Storefront**: Static QR codes and in-store collection for **physical stores** and fixed retail locations where customers pay at the counter.
    2. **Customer VPA**: A dedicated UPI identity or QR per customer when you run **recurring or tracked payments** and need payer-level visibility for reconciliation.
    3. **Agent (softPOS)**: Staff or agents collect on your behalf using the softPOS application on their devices for **field collections**, deliveries.
  </Accordion>

  <Accordion title="What is a storefront?">
    **Storefront** enablement helps you generate **static QR codes** for physical stores and collect payments directly into your account. It is suited to fixed retail locations where customers pay at the counter.
  </Accordion>

  <Accordion title="What is an agent (softPOS)?">
    **Agent (softPOS)** enablement lets your staff or agents collect payments on your behalf using **softPOS** on their **Android** devices. It is suited to field collections, deliveries.
  </Accordion>

  <Accordion title="What is a Customer VPA?">
    **Customer VPA** enablement lets you create a **unique UPI ID or QR code for each customer** so you can track who paid, how much, and when. It is suited to recurring collections, fees, instalments, or any flow where payer-level traceability matters.
  </Accordion>

  <Accordion title="Which collection model should I choose for my business?">
    Match your operating pattern to one of the models below.

    * **Storefront**: Physical stores and fixed checkout.
    * **Agent (softPOS)**: Field collections, deliveries.
    * **Customer VPA**: Recurring or individually tracked payments.
  </Accordion>

  <Accordion title="Can I use multiple collection methods at the same time (Storefront, Agent, and Customer VPA)?">
    Yes. You can enable and use **Storefront**, **Agent (softPOS)**, and **Customer VPA** together whenever your use case requires it.
  </Accordion>

  <Accordion title="Do I need an existing Cashfree Payment Gateway account?">
    Yes. You must have an **active Cashfree Payment Gateway relationship** before you can activate Offline Payments. If you do not have one yet, [create your account](https://merchant.cashfree.com/merchants/signup) and complete Payment Gateway onboarding first.
  </Accordion>

  <Accordion title="Can I get Offline Payments if I do not have a Payment Gateway with Cashfree?">
    No. Offline Payments is available only to merchants with an active Cashfree Payment Gateway relationship. [Create your account](https://merchant.cashfree.com/merchants/signup) if you are new to Cashfree.
  </Accordion>

  <Accordion title="How do I activate Offline Payments?">
    Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login). Open **Offline Payments** from the navigation, start **Activate Offline Payments**, and complete the steps shown on screen. You receive an **email confirmation** once Offline Payments is active for your account.
  </Accordion>

  <Accordion title="Are there any transaction limits for Storefront, Agent, or Customer VPA?">
    There are **no daily transaction count limits** across the Offline Payments product suite. **Per-transaction amount limits** still apply, and they depend on the **payment mode** in use. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login), open the **Payment Method** settings for the product you use, and customise limits there. For **softPOS**, open [softPOS payment method settings](https://merchant.cashfree.com/merchants/pg/softpos/payment-methods) or select **softPOS** > **Payment Method**.
  </Accordion>
</AccordionGroup>

## softPOS application

These FAQs cover the softPOS Android application, device requirements, pricing, receipt support, and available payment options.

<AccordionGroup>
  <Accordion title="Is the softPOS application available on iOS?">
    No. The Cashfree softPOS application is **not** available on the **iOS App Store**. It is available only on **Android** via the **Google Play Store** (Android 6.0 Marshmallow or above).
  </Accordion>

  <Accordion title="How many agents can a single merchant add?">
    There is **no limit**. You can add an **unlimited** number of agents under a single merchant account.
  </Accordion>

  <Accordion title="Are there any extra charges to use the softPOS application? Is there a monthly, yearly, or service fee?">
    No. The application is **free** to download and use. Cashfree charges **only for transactions** processed through softPOS, as per your pricing agreement. There is **no** monthly fee, yearly fee, maintenance fee, or registration fee for the application itself.
  </Accordion>

  <Accordion title="Can I print receipts using softPOS?">
    softPOS does **not** support built-in invoice or receipt printing. You can integrate **third-party software or hardware** if you need printed receipts.
  </Accordion>

  <Accordion title="Can I customise digital receipts on softPOS?">
    **Digital receipt customisation** is **not** currently available in the Cashfree softPOS application.
  </Accordion>

  <Accordion title="What payment options are available for collecting payments on the softPOS app?">
    The softPOS application supports the following collection options:

    * **Static QR**
    * **Dynamic QR**
    * **Payment links**
    * **Cash** (ledger entry only)
    * **Tap to Pay**
    * **Cardless EMI**

    Which options appear in your build can depend on account configuration and product rollout.
  </Accordion>

  <Accordion title="What payment options do my customers have?">
    Your customers can use **more than 120 payment options**, including cards, net banking, UPI, wallets, and more, depending on the collection method you choose (for example payment links expose the full hosted checkout range).
  </Accordion>
</AccordionGroup>

## QR codes, payment links, and cash

These FAQs cover the difference between static and dynamic QR codes, how payment links are shared, and how cash transactions are recorded.

<AccordionGroup>
  <Accordion title="What is the difference between a static QR code and a dynamic QR code?">
    The difference is **who enters the amount** and **how much flexibility** the payer has at scan time.

    **Dynamic QR code**

    * The **agent enters the amount** the customer must pay.
    * The agent can add **order context** such as the **customer mobile number**, **invoice number**, and **order note** before generating the code.

    **Static QR code**

    * The **customer scans** the code with a UPI application, **enters the amount**, and completes the payment.
  </Accordion>

  <Accordion title="What happens if the timer runs out before my customer can complete the transaction?">
    If the timer expires before the customer finishes:

    * If the customer has **not scanned** the QR code yet, **regenerate the order** by re-entering all details on the **New Payment** tab.
    * If the customer has **already scanned** the QR code, they can **continue** the payment flow. Check status in the **Payments** tab by **pulling down to refresh**.
  </Accordion>

  <Accordion title="How do I share a payment link?">
    Cashfree sends the payment link by **SMS** to the **customer mobile number** the agent entered when creating the payment.
  </Accordion>

  <Accordion title="Will I be able to see cash transactions in the transaction report?">
    Yes. You can see **all transactions**, including those recorded as **cash**, in the **transaction report** and in the **Payments** view for reconciliation.
  </Accordion>

  <Accordion title="What does the Cash option do?">
    The **Cash** option lets the agent record a **ledger entry** for a cash collection when a service is rendered. **No payment processing** runs through Cashfree for that leg. Entries still appear in the **Payments** tab and in **reports** for reconciliation.
  </Accordion>

  <Accordion title="Can I generate a Dynamic UPI QR code without using the S2S or Seamless flow?">
    Yes. If your account is not eligible for S2S or Seamless UPI enablement, generate a Dynamic UPI QR code with the SoftPOS (Offline Payments) flow. This also applies to in-app POS and invoice collection use cases where you need to display a dynamic UPI QR without using Cashfree Checkout. To generate a dynamic UPI QR code:

    1. [Create a Terminal](/docs/api-reference/payments/latest/offline-payments/create-terminal).
    2. [Create an Order](/docs/api-reference/payments/latest/orders/create-order) and include the terminal details in the request body.
    3. [Create a Terminal Transaction](/docs/api-reference/payments/latest/offline-payments/create-terminal-transaction) and pass `payment_method` as `QR_CODE`.

    Upon successful payment, you receive a payment success webhook containing the terminal details.

    You can also use the [Web Element SDK](/docs/payments/online/element/introduction) UPI QR component to build a custom checkout UI.
  </Accordion>

  <Accordion title="What does the error 's2s_enabled_not_approved' mean when using the /orders/pay API?">
    The error `s2s_enabled_not_approved` (HTTP 400) indicates that the S2S (Server-to-Server) or seamless payment capability for the [Order Pay API](/docs/api-reference/payments/latest/payments/order-pay) is not enabled or approved for your account. If your account is ineligible for S2S UPI enablement, you can use the [Elements SDK](/docs/payments/online/element/introduction) or the Offline Payments solution for dynamic QR use cases.
  </Accordion>
</AccordionGroup>

## Storefronts, agents, and Customer VPAs

These FAQs cover adding and managing collection points, resolving KYC issues, and how customers receive payment confirmations.

<AccordionGroup>
  <Accordion title="Can I add a single mobile number for multiple storefronts or agents?">
    Yes. **One mobile number** can be used when onboarding **multiple storefronts** or **multiple agents**, as long as each record meets Cashfree validation rules for that collection point.
  </Accordion>

  <Accordion title="What if an agent does not receive the KYC verification SMS?">
    Take the following steps:

    * **Resend** the verification SMS from the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) using the agent-management workflow for your collection points.
    * **Confirm** the mobile number on file for the agent is correct before you resend.
  </Accordion>

  <Accordion title="Can I deactivate or delete a storefront, agent, or Customer VPA?">
    Yes. You can **disable or deactivate** a storefront, agent, or Customer VPA from the [Merchant Dashboard](https://merchant.cashfree.com/auth/login). **Past transactions remain available** in reports after you change the status.
  </Accordion>

  <Accordion title="Will customers receive a payment confirmation?">
    Yes. Customers can receive confirmation through the following channels:

    * **Issuer bank**: Standard bank or card issuer notifications for the payment instrument they used.
    * **Cashfree SMS**: For payments completed through a **payment link**, Cashfree also sends an **SMS** confirmation to the customer's mobile number where applicable.
  </Accordion>

  <Accordion title="What should I do if a collection agent is unable to log in to a terminal?">
    First, ensure the agent has logged out from any previous devices before attempting to log in on a new device.

    If the agent still cannot log in (for example, due to a device reset or being unable to access the previous device), contact the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) to request a manual logout from all devices.
  </Accordion>
</AccordionGroup>

## Reports and settlements

These FAQs cover how to generate transaction reports, what fields they include, and when settlements are processed.

<AccordionGroup>
  <Accordion title="Where can I see reports for transactions?">
    Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login). Go to **Reports**, open **Download Reports**, click **Generate New Report**, choose your **file type**, select **softPOS Transactions** as the report type (the dashboard may still show **Offline Payment Transactions** for the same export in some accounts), and set the **date range**. For a guided walkthrough, see [Settlements and reports](/docs/payments/softpos/settlements-reports#transaction-reports).
  </Accordion>

  <Accordion title="What details are covered in the transaction report?">
    The transaction report includes **end-to-end transaction fields** at collection-point level. Examples include:

    * **Agent name**
    * **Terminal ID**
    * **Payment method**
    * **Amounts and status fields** (and other columns Cashfree exposes for that report type)

    The exact column set can vary slightly by export format and configuration.
  </Accordion>

  <Accordion title="When are settlements processed?">
    By default, Cashfree processes settlements on **T+2 bank working days**. **T** is the calendar day the payment succeeds. Settlement runs on **bank working days** only. For schedules, bank accounts, and reconciliation depth, see [Manage settlements](/docs/payments/manage/settlements).
  </Accordion>
</AccordionGroup>

## Support

Policy documents and contact details for Cashfree support, grievances, and dispute escalation.

<AccordionGroup>
  <Accordion title="How do I get more information on Cashfree or its policies?">
    For policy documents and Cashfree contact details, use the following:

    * [Grievance Redressal Policy](https://www.cashfree.com/grievance-redressal-policy/)
    * [Terms and Conditions](https://www.cashfree.com/tnc/)
    * [Privacy Policy](https://www.cashfree.com/privacypolicy/)

    **Grievance Officer**: Mr. Vaibhav Kaushal\
    **Email**: [grievances@cashfree.com](mailto:grievances@cashfree.com)\
    **Address**: Cashfree India Pvt Ltd, RMZ Ecoworld, Building 7, 10th Floor, Devarabeesanahalli, Marathahalli Outer Ring Road, Bengaluru – 560103

    **Nodal Officer**: Mr. Shaik Mohammed Aftab Alam\
    **Email**: [dispute@cashfree.com](mailto:dispute@cashfree.com)\
    **Address**: Cashfree India Pvt Ltd, RMZ Ecoworld, Building 7, 10th Floor, Devarabeesanahalli, Marathahalli Outer Ring Road, Bengaluru – 560103
  </Accordion>
</AccordionGroup>


# Subscriptions
Source: https://www.cashfree.com/docs/help/subscriptions/faqs/faqs

Find answers to subscriptions FAQs covering recurring payment modes, mandate setup, NACH and UPI AutoPay support, retry logic, and mandate cancellation steps.

<AccordionGroup>
  <Accordion title="What are the different ways that I can use Cashfree to collect recurring payments or payments for subscriptions from my customers?">
    Cashfree offers four different payment methods, each with specific limits on the allowed subscription amounts, as outlined below.

    * UPI AutoPay
    * Cards
    * eNach
    * Physical Mandate

    [Learn more about these payment modes](/docs/payments/subscription/payment-modes).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Is the Cashfree Subscriptions solution compliant with the new Digital Lending Guidelines by RBI?">
    Yes, it is fully compliant with the new Digital Lending Guidelines by RBI. NBFCs and Fintechs can use Cashfree to collect repayments, disburse credit, and co-lend without a hassle.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Who can benefit from using Cashfree Subscriptions?">
    Cashfree Subscriptions caters to various industries with diverse use cases. Some of the top ones include:

    NBFCs and Digital Lending Apps
    OTT Platforms
    Ed-Tech Platforms
    E-commerce Companies
    Investment Firms
    Insurance Providers

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How to create a subscriptions plan on Cashfree dashboard?">
    1. Go to **Subscription Dashboard** > **All subscriptions** > **Create Subscriptions**

    2. Enter details – Add customer info, subscription ID, recurring amount, due date, and max debits.

       <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How to create a UPI AutoPay plan?">
    To create a new subscription from the dashboard, Go to Subscriptions Dashboard > All Subscriptions > Create Subscription.

    You can also create multiple subscriptions at once using the dashboard. Go to Subscriptions Dashboard > Batch Subscriptions > Upload File to upload a file that contains all the information required for multiple subscriptions.

    [Learn more](/docs/payments/subscription/create)

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What is the Bulk Payments tab on the Subscriptions dashboard?">
    For On-Demand subscriptions, when you want to initiate a large number of payments for multiple subscriptions, you can use the Bulk Payments feature.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I migrate my mandate data from another payment aggregator to Cashfree?">
    Cashfree supports importing of mandate information for a subscription. You can move any historical mandate data to Cashfree and continue the transactions in Cashfree. Steps to initiate the porting process-
    Cashfree ensures a smooth mandate porting experience.

    1. Contact Cashfree Support – Initiate the porting process by nominating Cashfree as your payment processing partner for your Utility Code or mandates.
    2. Partner Bank Coordination – Share the mandate list with your partner bank to update their systems. Our team will guide you through the process.
    3. Import Mandates – Upload the updated mandate list into Cashfree’s system.
    4. Start Processing Payments – Once imported, you can begin processing payments seamlessly through Cashfree.
       [Learn more about importing subscriptions](/docs/payments/subscription/import).

       <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are the various eNACH transaction failure reasons?">
    Once the eMandate is successfully created, the corresponding transactions can get declined due to the reasons listed below:

    | Transaction failure reason | Detailed description | Resolution |
    | - | - | - |
    | Balance Insufficient | This error is displayed when the end-customer does not have sufficient balance in their account. In this case, due to payment failure, the end-customer will be asked to pay a fine of amount equivalent to the cheque bounce charges by the destination bank. | The merchant can present the transaction again. It is recommended to contact the end-customer before retrying the failed transaction. A total of 3 retries are allowed before the start of the next cycle. |
    | Not Arranged For or Exceeds arrangement | This error is displayed when the end-customer does not have sufficient balance in their overdraft account. | The merchant can present the transaction again. It is recommended to contact the end-customer before retrying the failed transaction. A total of 3 retries are allowed before the start of the next cycle. |
    | Customer to refer to the branch | This error is displayed when the reason for the decline is unclear and the destination bank is expecting the end-customer to contact them for further clarification. | Merchant can contact the end-customer and recommend the end-customer to contact the bank and provide further clarification. |
    | Account Closed | This error is displayed when the account has been closed and thus all the associated mandates were deactivated. | Further action cannot be taken in this scenario. The merchant can create another mandate for the end-customer to continue with the debit. |
    | Invalid UMRN or Inactive Mandate | This error is displayed when the mandate has been de-activated by the NPCI's system. Usually when the mandate has not been debited over a prolonged period of time. | Further action cannot be taken in this scenario. The merchant can create another mandate for the end-customer to continue with the debit. |
    | Mandate Cancelled | This error is displayed when the mandate has been cancelled. This can be merchant initiated or end-customer initiated. | Further action cannot be taken in this scenario. The merchant would have to create another mandate for the end-customer to continue with the debit. |
    | No Such Account | This error is displayed when the account has been closed or no longer available. Thus all the associated mandates were deactivated. | Further action cannot be taken in this scenario. The merchant would have to create another mandate for the end-customer to continue with the debit. |
    | A/c Blocked or Frozen | This error is displayed when all the withdrawals, purchases or transfers have been halted for this account. Hence, the presentation is not successful. | The merchant must contact the end-customer to resolve this issue. |
    | Payment Stopped by Drawer | This error is displayed when the presentation has been stopped at the request of the end-customer. | The merchant must contact the end-customer to resolve this issue. |
    | Payment Stopped under Court Order/Account Under Litigation | This error is displayed when the presentation has been stopped at a Court order. | The merchant must contact the end-customer to resolve this issue. |
    | Customer name mismatch | This error is displayed when the account holder's name provided during mandate creation does not match the account holder's name at the time of presentation. | Since the mandate cannot be edited, the merchant must create a new mandate with the end-customer. |
    | Network Failure (CBS) | This error is displayed when the Core Banking System(CBS) of the destination bank has a network failure. Generally, all the presentations for the affected bank would fail for the day. | The merchant can try to present the transaction again. The transaction is expected to go through once the system is up. |
    | Returned as per customer request | This error is displayed when the presentation has been stopped at the request of the customer. | The merchant must contact the end-customer to resolve this issue. |
    | KYC Documents Pending | Typically end-customer is expected to do a KYC for the bank account at least once in 3 years. On such cases, the presentation could be stopped by the bank, and this error message is displayed. | The end-customer must complete the KYC post which the merchant can try to present the transaction. |
    | Documents Pending for Account Holder turning Major | This error is displayed when the documentation is pending. | End customer must complete the documentation process at the bank. |
    | Account Inoperative | This error is displayed when there are no transactions in an account for the last 3 months. All the associated mandates are deactivated. | Further action cannot be taken in this scenario. The merchant would have to create another mandate for the end-customer to continue with the debit. |
    | Dormant Account | This error is displayed when there are no transactions in an account for the last 6 months. Account is dormant and all the associated mandates are deactivated. | Further action cannot be taken in this scenario. The merchant would have to create another mandate for the end-customer to continue with the debit. |
    | Small account, First Transaction to be from Base Branch | For a bank account type - small account, the first transaction must happen at the home branch. | |
    | Account reached maximum Debit limit set on account by Bank | This error is displayed when the end-customer has sufficient balance in their account but the account has already reached the maximum limitation set for security reasons. | The merchant must contact the end-customer to increase the limit and then they try to do another presentation. |
    | Account Holder Expired | This error message is displayed when the account holder has expired. | - |
    | Account under litigation | This error is displayed when an account is currently under legal action. | Further debits are not possible for this bank account. A new mandate must be created with a different bank account to take this forward. |
    | Aadhaar number not mapped to the account number | This error is displayed when the end customer Aadhaar number is not linked to the bank account. | The end-customer must link the Aadhaar number with the bank account post which the merchant can try to do another presentation. |
    | Customer Insolvent / Insane | - | Further action cannot be taken for this error message. The merchant would have to create another mandate with a different bank account. |
    | Item cancelled | This error is displayed when the end-customer has cancelled the presentation. | The merchant must contact the end-customer to get this resolved post which the merchant can try to do another presentation. |

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What is the Bulk Payments tab on the Subscriptions dashboard?">
    For on-demand subscriptions, use the bulk payments feature to initiate a large number of payments for multiple subscriptions.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Multiple authorisations will be present if the customer has attempted the transaction multiple times?">
    Multiple auths will appear if the customer attempts the transaction more than once.

    <iframe title="FAQs feedback component" />
  </Accordion>
</AccordionGroup>


# Token Vault
Source: https://www.cashfree.com/docs/help/token-vault/faqs

Get answers to Token Vault FAQs about card tokenisation, RBI-mandated guest checkout flows, saved-card storage, network token usage, and migration steps.

<AccordionGroup>
  <Accordion title="What is card tokenisation?">
    Card tokenisation replaces sensitive card details (number, expiry, CVV) with a secure, random token. This token is used for payments, keeping actual card data safe and reducing the risk of fraud.
  </Accordion>

  <Accordion title="What are the RBI guidelines on tokenisation?">
    The RBI guidelines on card tokenisation are as follows,

    * Payment aggregator, payment gateway or merchants cannot store card numbers on their servers even if they are PCI/DSS compliant
    * Card networks and Issuing banks can only store card numbers and offer token provisioning services to other entities in payment industry
    * The deadline for compliance of these guidelines is 31st of December 2021
  </Accordion>

  <Accordion title="Why do I need Token Vault by Cashfree?">
    A Token Vault securely stores card tokens, enabling customers to make quick, hassle-free payments with saved cards. We generate interoperable network tokens, meaning they can be used across multiple payment providers for seamless transactions. Learn more about [Token Vault](/docs/payments/features/token-vault).
  </Accordion>

  <Accordion title="What all card details can I save once with tokenisation in place?">
    Merchants are allowed to store only the last 4 digits of the actual card number, card scheme and issuing bank name. They cannot store other details like card bin, card expiry or CVV.
  </Accordion>

  <Accordion title="Is there any impact of tokenisation on the card payments where the customer enters complete card number?">
    No, there is no impact as such on card payments where the customer enters the complete card number details. Only in those cases where merchants or PA/PGs were saving cards will be affected.
  </Accordion>

  <Accordion title="Can I retrieve the actual card number using the card network token?">
    No, merchants will not be able to get the actual card number back from the tokenised cards. Only schemes and issuing banks will be able to do so.
  </Accordion>

  <Accordion title="Can I provision card network token without taking consent from customer?">
    No, explicit consent of customer is mandatory while provisioning token for the card.
  </Accordion>

  <Accordion title="Can I provision card network token without the customer completing 2FA?">
    If 2FA fails even after the customer had given consent to tokenise the card, merchants will not be able to provision token and save the card.
  </Accordion>

  <Accordion title="Does tokenisation affect any other payment mode other than cards? Which all card transactions are affected?">
    No, tokenisation is limited only for card payments. All card payments like credit, debit, prepaid and corporate credit cards are impacted.
  </Accordion>

  <Accordion title="If a merchant is PCI/DSS compliant and was saving cards on their own server how can they meet RBI’s compliance requirement?">
    If you are a merchant who already PCI/DSS compliant, here is what you need to do to stay RBI compliant,

    1. Merchants who were saving the card number on their own servers, will also have to either integrate with individual card schemes and become a token requestor themselves or integrate with Token Vault where Cashfree will be a token requestor on merchant’s behalf.

    2. PCI/DSS compliant merchants have to delete the already saved cards with them as RBI does not allow bulk tokenisation of cards.
  </Accordion>

  <Accordion title="Does a merchant need to re-provision the already saved cards on another PA/PG if they wish to shift from Cashfree to some other PA/PG?">
    Yes, the token reference number of tokens provisioned through Cashfree will be saved with Cashfree only. However, merchants can fetch the card network tokens from Cashfree and use them for payment on any other PA/PG. It is not possible to migrate cards provisioned through Cashfree on another PG.
  </Accordion>
</AccordionGroup>


# Cashfree Developer Documentation
Source: https://www.cashfree.com/docs/index

Get started with Cashfree documentation, APIs, SDKs, and integration guides for payments, payouts, and identity verification products.

<div>
  <div />

  <div>
    <div>
      <div>
        <h1>Payments</h1>

        <p>
          Get started with documentation and APIs to start integrating Cashfree products.
        </p>

        <div>
          <a href="/docs/payments">
            Get Started With Payments
          </a>

          <a href="/docs/payments/other-products">
            Other Products
          </a>
        </div>
      </div>
    </div>

    <div>
      <CodeGroup>
        ```html checkout.html theme={"dark"}
        <html>
            <head>
                <title>Checkout</title>
                <script src="https://sdk.cashfree.com/js/v3/cashfree.js"></script>
            </head>
            <body>
                <button onclick="initiateCheckout()">Initiate Checkout</button>
            </body>
        </html>
        ```

        ```javascript checkout.js theme={"dark"}
        function initiateCheckout(){
            const cashfree = Cashfree({
                "mode":"sandbox"
            });
            cashfree.checkout({
                paymentSessionId: "your-payment-session-id",
                redirectTarget: "_modal"
            });
        }
        ```
      </CodeGroup>
    </div>
  </div>

  <div>
    <div>
      <div>
        <h4>Hosted Solution </h4>

        <p>
          <a href="/docs/payments/online/web/redirect">Accept one time payment</a>
        </p>

        <p>
          <a href="/docs/payments/flowwise/overview">Orchestrate with multiple PGs</a>
        </p>

        <p>
          <a href="/docs/payments/subscription/introduction">Accept recurring payments</a>
        </p>
      </div>
    </div>

    <div>
      <div>
        <h4>No Code</h4>

        <p>
          <a href="/docs/payments/no-code/payment-link">Share a payment link</a>
        </p>

        <p>
          <a href="/docs/payments/no-code/payment-forms">Create a payment form</a>
        </p>

        <p>
          <a href="/docs/payments/shopify/overview">Install Shopify Plugin</a>
        </p>
      </div>
    </div>

    <div>
      <div>
        <h4>Developers</h4>

        <p>
          <a href="https://www.cashfree.com/devstudio">Dev Studio</a>
        </p>

        <p>
          <a href="https://github.com/cashfree/">GitHub</a>
        </p>

        <p>
          <a href="/docs/api-reference/postman-collections">Postman Collections</a>
        </p>
      </div>
    </div>
  </div>
</div>

<div>
  <div>
    <div>
      <div>
        <h1>Payouts</h1>

        <p>
          Get started with the documentation and APIs to integrate Cashfree Payouts. Automate and manage payouts for vendors, refunds, loans, and more.
        </p>

        <div>
          <a href="/docs/payouts/payouts/introduction">
            Get Started With Payouts
          </a>
        </div>
      </div>
    </div>

    <div>
      <img />
    </div>
  </div>
</div>

<div>
  <div>
    <div>
      <div>
        <h1>Secure ID</h1>

        <p>
          Get started with the documentation and APIs to integrate Cashfree Secure ID. Simplify user onboarding with a compliant, scalable, and customisable identity verification platform.
        </p>

        <div>
          <a href="/docs/secure-id/introduction">
            Get Started With Secure ID
          </a>
        </div>
      </div>
    </div>

    <div>
      <img />
    </div>
  </div>
</div>

<div>
  <br />
</div>

<div>
  <div>
    <p>
      <a href="https://www.cashfree.com/contact-sales/">
        <Icon icon="envelope" />

        <span>Questions? Contact Sales</span>
      </a>
    </p>

    <p>
      <a href="https://www.cashfree.com/devstudio">
        <Icon icon="plug" />

        <span>Try Integrations on Dev Studio</span>
      </a>
    </p>

    <p>
      <a href="/docs/help/overview">
        <Icon icon="book" />

        <span>Knowledge Base</span>
      </a>
    </p>

    <p>
      <a href="https://play.google.com/store/apps/details?id=com.cashfree.merchant">
        <Icon icon="play" />

        <span>Checkout our Android App</span>
      </a>
    </p>
  </div>

  <div>
    <div>
      Subscribe to Developer Updates:
    </div>

    <div>
      <iframe title="Subscribe to Developer Updates" />
    </div>

    <div>
      <a href="https://github.com/cashfree">
        <img alt="GitHub Icon" />

        GitHub
      </a>

      <a href="/docs/api-reference/postman-collections">
        <img alt="Postman Icon" />

        Postman Collections
      </a>

      <a href="https://www.youtube.com/channel/UCxO0W7xVngh7TfkChPa_nwg">
        <img alt="YouTube Icon" />

        YouTube
      </a>

      <a href="https://www.cashfree.com/blog/category/engineering/">
        <img alt="Blog Icon" />

        Blog
      </a>

      <a href="https://discord.com/invite/w97HT9RKCF">
        <img alt="Discord Icon" />

        Discord
      </a>
    </div>
  </div>
</div>


# Merchants Integration
Source: https://www.cashfree.com/docs/partners/affiliates/assist-merchant/merchants-integration

Help referred merchants complete Cashfree integration by choosing the right product, configuring checkout, and going live faster as an Affiliate Partner.

Once payments are activated for your merchants, help them choose from a range of business-friendly solutions to seamlessly integrate and accept payments.

Cashfree offers the following integration options:

* **Web integrations**: Add payment capabilities to websites using the JavaScript SDK.
* **Mobile app integrations**: Integrate payments into Android, iOS, React Native, and Flutter apps using platform-specific SDKs.
* **E-commerce plugins**: Install ready-to-use plugins on platforms such as Shopify, WooCommerce, WordPress, and others.
* **No-code solutions**: Use the Cashfree Dashboard to create Payment Links and Forms—no coding or development required.

[View feature and technical details for all solutions](/docs/payments/overview)

Help your merchants choose the solution that best fits their needs—and start earning on every transaction.

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related Topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/payments/latest/overview">Payment Gateway API Overview</a></li>
    <li><a href="/docs/payments/overview">Payments Overview</a></li>
    <li><a href="/docs/partners/affiliates/assist-merchant/merchants-kyc">Merchants KYC</a></li>
    <li><a href="/docs/partners/affiliates/refer-merchants">Refer and Onboard Merchants</a></li>
  </ul>
</div>


# Merchants KYC
Source: https://www.cashfree.com/docs/partners/affiliates/assist-merchant/merchants-kyc

Help your referred merchants complete the Cashfree KYC process by submitting documents, verifying bank details, and activating their account quickly.

Help your merchants get started quickly by assisting with their Know Your Customer (KYC) process. This improves their onboarding experience and reduces the time it takes to activate their account.

You can assist merchants with KYC in one of the following ways:

* Complete the KYC process for the merchant using your dashboard.

* Share the onboarding link with the merchant.

* Ask the merchant to complete KYC using their [Cashfree Merchant](https://merchant.cashfree.com/auth/login) Dashboard.

<Note>
  After KYC submission, eligible merchants are activated instantly and can start accepting payments.
</Note>

## Complete KYC using your dashboard

To complete the merchant's KYC on their behalf:

1. Login to the [Affiliate Partner](https://partner.cashfree.com/auth/login) dashboard using your credentials.
2. Go to the **Merchants** section.
3. Select **Complete KYC** for the merchant.
4. A new tab opens with the merchant’s onboarding form.
5. Enter the required onboarding details, following the instructions on the page.

At the final step, the merchant must enter their Aadhaar number and verify it using a one-time password (OTP). You can fill in the details up to this step. Then, share the onboarding link with the merchant to complete Aadhaar verification.

## Share the onboarding link

To share the onboarding link with the merchant:

1. Login to the [Affiliate Partner](https://partner.cashfree.com/auth/login) dashboard using your credentials.
2. Go to the **Merchants** section.
3. Select the **Copy** icon next to the KYC button for the merchant.
4. Share the link using WhatsApp, Instagram, or another messaging platform.
5. Ask the merchant to log in using their Cashfree credentials or select **Login using OTP** to receive an OTP.
6. Once logged in, the onboarding page opens. The merchant can complete the onboarding steps.

<Tip>
  For help with merchant KYC, contact your Partner Account Manager or submit a [Support Form](https://merchant.cashfree.com/auth/login).
</Tip>

## Track merchant status

Track the KYC and product activation status of your referred merchants in the Merchants section of the [Affiliate Partner](https://partner.cashfree.com/auth/login).

### Product status

| **Status** | **Description** |
| - | - |
| **Pending** | Payments aren’t activated yet. KYC is still pending. |
| **Active** | The merchant is activated and can accept payments. |
| **Rejected** | The requested products can’t be activated for this business. |

### KYC status

| **Status** | **Description** |
| - | - |
| **Complete KYC (KYC pending)** | The default status for new merchants. Next step: complete KYC. |
| **Under review** | The KYC has been submitted and is under review. |
| **Resubmit KYC (KYC rejected)** | The submitted KYC has discrepancies. Resubmission is required. |
| **Blocked** | The requested products can’t be activated for this business. |
| **Completed** | KYC has been approved. |

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related Topics</span>
  </p>

  <ul>
    <li><a href="https://partner.cashfree.com/auth/login">Partners Dashboard</a></li>
    <li><a href="https://merchant.cashfree.com/auth/login">Merchant Dashboard</a></li>
  </ul>
</div>


# Get Started as Affiliate Partner
Source: https://www.cashfree.com/docs/partners/affiliates/become-cashfree-affiliate

Sign up for the Cashfree Affiliate Partner program, access the Affiliate Dashboard, refer merchants, track activations, and earn commissions on payments.

Visit the [Cashfree website](https://www.cashfree.com/affiliate-program/) and signup for our affiliate program. After you complete the signup process, you will get access to the Affiliate Partner Dashboard. You can add merchants, keep a check on your commissions, get a snapshot of your business with Cashfree, and more within the Affiliate Partner Dashboard.

## Signup for the affiliate program

To become an Affiliate Partner, you must first create an Affiliate Partner account with Cashfree.

1. Go to the [Cashfree Affiliate Partner website](https://www.cashfree.com/affiliate-program/) and click **Become A Partner**.

2. In the **Become a Partner** window, enter your business email and create a password for your account or signup using your Gmail account.
   <img alt="" />

3. In the **Create Partner Account** window, enter your brand name and valid mobile number. Cashfree will verify the mobile number by sending an OTP.
   <img alt="" />

4. [Login](https://www.cashfree.com/affiliate-program/) to the Affiliate Partner Dashboard using the same credentials.

## Activate affiliate account

After signing up, you must complete the KYC process to activate your affiliate account. We’ll verify your submitted details and enable your account for commission payouts.

<Note> Commission earnings are activated only after KYC verification. Complete the KYC process at the earliest. </Note>

### To activate your account:

1. Login to the [Affiliate Partner](https://partner.cashfree.com/auth/login) dashboard using your credentials.
2. On the **Summary** page, go to the **Complete your KYC** banner and select **Complete Now**.
3. In the KYC form:
   * Fill in your business details.
   * Fill in your business verification details.
   * Fill in your bank account details.
4. Select **Submit**.

Cashfree will review your submission. While your KYC is under review, you can begin referring merchants. The review process typically takes fewer than **3 business days**.

* You will be notified via **email** and **WhatsApp** once the review is complete. You can also track the status on your **Partner Dashboard**.
* If any discrepancies are found, they will be displayed on your dashboard. Please correct and resubmit the details.
* Once your KYC is approved, you will be eligible to withdraw any earned commissions.

<div>
  **Info:** Offer Cashfree product suite to your clients. You can refer merchants using your Dashboard. Once referred, you can assist them with their KYC and Payment Integration. Learn how to [refer new merchants](/docs/partners/affiliates/refer-merchants) using your Affiliate Partner Dashboard.
</div>

<Note>
  **Note**: Offer Cashfree product suite to your clients. You can refer merchants using your Dashboard. Once referred, you can assist them with their KYC and Payment Integration. Learn how to [refer new merchants](/docs/partners/affiliates/refer-merchants) using your Affiliate Partner Dashboard.
</Note>

## Partner activation checklist

The following documents are required for KYC verification, based on your business type:

| **Business type** | **Requirement** | **Details or accepted documents** |
| - | - | - |
| **Individual (unregistered)** | Business identity proof | Personal PAN |
| | Business owner identity proof | Aadhaar (of owner) |
| | Business bank account proof | Owner’s bank account |
| **Sole proprietorship** | Business identity proof | Personal PAN |
| | Business registration proof | GSTIN or one of:<br />• Municipal certificate<br />• Shop establishment certificate<br />• Udyog Aadhaar |
| | Business owner identity proof | Aadhaar (of owner) |
| | Business bank account proof | Business bank account |
| **Private or public limited** | Business identity proof | Company PAN |
| | Business registration proof | CIN or GSTIN |
| | Business owner identity proof | PAN and Aadhaar (of owner) |
| | Business bank account proof | Business bank account |
| **Partnership** | Business identity proof | Company PAN |
| | Business registration proof | Registered partnership deed |
| | Business owner identity proof | PAN and Aadhaar (of owner) |
| | Business bank account proof | Business bank account |
| **LLP** | Business identity proof | Company PAN |
| | Business registration proof | LLPIN or GSTIN |
| | Business owner identity proof | PAN and Aadhaar (of owner) |
| | Business bank account proof | Business bank account |
| **Hindu Undivided Family (HUF)** | Business identity proof | Company PAN |
| | Business registration proof | Registered HUF deed |
| | Business owner identity proof | PAN and Aadhaar (of owner) |
| | Business bank account proof | Business bank account |
| **Others** | Business identity proof | Company PAN |
| | Business registration proof | Registered business proof or GSTIN |
| | Business owner identity proof | PAN and Aadhaar (of owner) |
| | Business bank account proof | Business bank account |

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related Topics</span>
  </p>

  <ul>
    <li><a href="https://www.cashfree.com/affiliate-program/">Affiliate Program Website</a></li>
    <li><a href="/docs/api-reference/platforms/latest/merchant-onboarding/create-embeddable-onboarding-link-does-not-require-login">Create Embeddable Onboarding Link API</a></li>
    <li><a href="/docs/partners/affiliates/refer-merchants">Refer and Onboard Merchants</a></li>
    <li><a href="/docs/partners/affiliates/dashboard">Affiliate Partner Dashboard</a></li>
  </ul>
</div>


# Affiliate Partner Dashboard
Source: https://www.cashfree.com/docs/partners/affiliates/dashboard

Explore the Cashfree Affiliate Partner Dashboard to add and manage referred merchants, track commissions, monitor activations, and analyse business performance.

The Affiliate Dashboard is a feature-rich user interface that helps you to add and manage your merchants effectively. Analyse your business progress, monitor your commissions and more within the dashboard.

## Dashboard components

* [Summary](/docs/partners/affiliates/dashboard#summary)
* [Merchants](/docs/partners/affiliates/dashboard#merchants)
* [PG Orders](/docs/partners/affiliates/dashboard#pg-orders)
* [Commission](/docs/partners/affiliates/dashboard#commission)

### Summary

The **Summary** screen gives you details about your daily transactions, like the current-day transaction count, the value of the transactions made by your merchants, and the last commission amount you received from Cashfree as per the referral program.

The following details are available on this page:

* Number of Transactions Today - Total number of PG and Payout transactions done by your merchants.
* Value of Today's Transactions - Total value of PG and Payout transactions done by your merchants today.
* Merchant Stats - Number of merchants you have added and activated.
* Referral Link - Copy and share your unique Referral Link with your clients or merchants for sign up and activation.
* Partner Logo - Use the Cashfree Affiliate Partner badge on your website or marketing assets visible to your clients or merchants.
  <img alt="referral_link" />

### Merchants

The **Merchants** section in the Affiliate Partner Dashboard allows you to efficiently onboard and manage referred merchants.

You can:

* **Add a single merchant** by entering:
  * Business name
  * Contact details (email address and phone number)
  * Optional KYC information for faster verification

* **Bulk upload merchants** using a predefined file format to add multiple businesses at once. For more information, refer [
  Onboarding](/docs/partners/affiliates/refer-merchants#bulk-referral).

* **Track onboarding status** after submission:
  * Merchants receive a verification email
  * Status updates are shown on the Dashboard

For more information, refer [Track merchant status](/docs/partners/affiliates/assist-merchant/merchants-kyc#track-merchant-status).

<img alt="Merchant Homepage" />

<Note> Use this section to monitor your referred merchants and support them through activation and KYC. </Note>

### PG orders

The PG Orders screen gives you merchant-wise details about the PG transactions. Details available are:

* Merchant Name
* Transaction Count
* Transaction Amount
* Total Commission

By default, the report shows details for the last 7 days. You can filter and view the details as per your requirement. Click on a particular transaction to view more details about it.

### Commission

The Commission screen gives you details of all the commissions you have earned month-wise. This screen displays the volume of transactions, the total transaction amount, and your earned commission. Cashfree settles the commission amount to your account monthly. For more information, refer [Commissions and Invoices](/docs/partners/affiliates/partner-commissions-and-invoices).

<img alt="Commission" />

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related Topics</span>
  </p>

  <ul>
    <li><a href="/docs/partners/affiliates/refer-merchants">Refer and Onboard Merchants</a></li>
    <li><a href="/docs/partners/affiliates/partner-commissions-and-invoices">Partner Earnings Guide</a></li>
    <li><a href="/docs/partners/affiliates/assist-merchant/merchants-kyc#track-merchant-status">Track Merchant Status</a></li>
    <li><a href="/docs/partners/affiliates/overview">Affiliate Program Overview</a></li>
  </ul>
</div>


# FAQs
Source: https://www.cashfree.com/docs/partners/affiliates/faqs

Find answers to common questions about the Cashfree Affiliate Partner program, including signup, commission payouts, merchant onboarding, and dashboard usage.

<AccordionGroup>
  <Accordion title="What is Cashfree Affiliate Program?">
    The Cashfree Affiliate Program is a referral program through which you can offer the Cashfree product suite to your clients or customers and get rewarded. You can simplify the payments experience for your customers and earn a commission for every transaction your customer makes.

    Becoming an affiliate enables you to provide a seamless onboarding experience for your customers and offer them a complete suite of payment solutions for all their payment needs.
  </Accordion>

  <Accordion title="How to become a Cashfree Affiliate?">
    Visit the <a href="https://partner.cashfree.com/partner-ui/authentication/signup">Cashfree website</a> and signup for our affiliate program. After you complete the signup process you will get access to the Affiliate Dashboard. You can add merchants, keep a check on your commissions, get a snapshot of your business with Cashfree, and more within the Affiliate Dashboard.
  </Accordion>

  <Accordion title="What are the next steps after sign-up?">
    After you complete the sign-up process, you must activate your account and send us the scanned copies of the documents for KYC verification.
  </Accordion>

  <Accordion title="Who can be a Cashfree Affiliate?">
    Any individual, proprietary firm, partnership firm (including LLP) or private limited company, that requires an online payment solution for their clients, can register with Cashfree as an Affiliate.
  </Accordion>

  <Accordion title="How to activate my Affiliate account?">
    You need to complete KYC to activate your account. Follow the above steps to activate your account. In case you are not able to contact to Cashfree team on call, you can contact us at [partner@cashfree.com](mailto:partner@cashfree.com) or fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) We would be happy to assist.
  </Accordion>

  <Accordion title="What are the benefits for Cashfree Affiliates?">
    Offer payment solutions to your customers for all the payment issues on a single platform - Payment Gateway, Easy Split, Payment Links, Subscriptions, Payouts, Verification Suite (Bank Accounts, IFSC, UPI VPA, PAN), and more.

    **Earn Rewards**: You get commissions for every transaction your customers make. There are two types of commission structures - flat rate and percentage of the transaction value.

    **Powerful Dashboard**: A separate dashboard to add and manage all your customers. Get detailed reports about transactions, the value of transactions made, commission amount, and more.

    **Extensive Affiliate Support**: Dedicated support to solve all your integration queries.

    **Multi-Currency Support**: More than 100+ currency types are supported.
  </Accordion>

  <Accordion title="How can I refer merchants?">
    You can refer merchants using one of the following ways below:

    * **Refer merchants using the Cashfree Affiliate Partner badge**

    1. Go to **[Affiliate Dashboard](https://www.cashfree.com/affiliate-program/)** > **Summary**.
    2. Click **Copy Code** in the **Affiliate Logo**section. Add this code to your website or application.

    * **Refer merchants using Cashfree Affiliate Referral Links**

    1. Go to **[Affiliate Dashboard](https://www.cashfree.com/affiliate-program/)** > **Summary**.
    2. Copy the referral link in the **Referral Link** section. Share your unique Affiliate Referral Link with your clients. Once your merchants' signup using the referral link, they will be added as your referred merchant on the dashboard.

    * **[Add merchants directly on your affiliate dashboard- single upload](/docs/partners/embedded/add-merchants#adding-merchant-from-dashboard)**

    * **[Add merchants directly on your affiliate dashboard- bulk upload](/docs/partners/embedded/add-merchants#add-merchants-using-batch-upload)**
  </Accordion>

  <Accordion title="How do I retrieve my password?">
    To reset your password, follow these steps:

    1. Go to the [Merchant Dashboard](https://merchant.cashfree.com/).
    2. Click **Forgot Password** on the login screen.
    3. Enter your registered email address.
    4. Follow the instructions sent to your email to create a new password.
  </Accordion>

  <Accordion title="What is the onboarding process for referred merchants?">
    After you add the merchant details, Cashfree will notify the merchant to accept the invite and verify their email ID. The merchant must submit the business details and upload the required documents.

    If the merchants did not verify their email ID, you can resend the verification email to them by clicking **Resend verification email**. To make the merchant onboarding faster, you can also submit business details of your merchants and upload the required documents on your merchants' behalf by following the steps below:

    1. Click the ‘**Activate**’ option shown for your merchant entries in the Affiliate dashboard.

       <img alt="" />

    2. You would be directed to the merchant account activation page where you can fill in all required business details of your referred merchant and upload their business documents.

       <img alt="" />

    <Note>
      Activate option will be shown only for merchants who have verified their email addresses.
    </Note>
  </Accordion>

  <Accordion title="How to resend the verification mail to merchants again?">
    If the merchants did not verify their email ID, you can resend the verification email to them by clicking **Resend Email**.

    <img alt="" />
  </Accordion>

  <Accordion title="How to track the status of the referred merchants?">
    1. Go to **Affiliate Dashboard** > **Merchants**.
    2. Check the status of your referred merchants. You will see the below statuses:\
       **Resend Email**: The merchant has not verified their email address. You can select this option to resend the verification email.\
       **Activate**: The merchant has not uploaded the documents. You can select this option to activate the merchant.\
       **Activated**: The merchant account is active now, the merchant can now start transacting via Cashfree.
  </Accordion>

  <Accordion title="How can I track the Payment Gateway and Payout transactions made by my referrals?">
    To track payment gateway transactions by your merchants, navigate to **PG Orders** on the left panel. You can view the number of transactions, total transaction amount, and commission earned by you on those transactions for every merchant

    Similarly, you can navigate to **Payouts Transfers** on the left panel to keep track of all transfers made by your merchants using Cashfree Payouts and check the total commission earned on the transactions.

    <Note>
      Both Payment Gateway and Payout transactions will reflect on the dashboard after 24 hours of initiating the transactions.
    </Note>
  </Accordion>

  <Accordion title="When will I get my commission?">
    The commission is earned when any PG or payout transaction is done by your referred merchants via Cashfree.

    In the case of Payment Gateway collections, when any customer makes a transaction on your referred merchant’s website/app and the amount is settled to Cashfree, the commission on that transaction is reflected on your Affiliate dashboard.

    In the case of Payout disbursals, when your referred merchant makes a payout for vendor payments, processing refunds or disbursing loans etc., using Cashfree, the commission on that transaction is reflected on your Affiliate dashboard.
  </Accordion>

  <Accordion title="How to track my commission?">
    1. Go to **Affiliate Dashboard** > **Summary** to check total daily transactions and daily transaction volume
    2. To track payment gateway transactions by your merchants, go to PG Orders on the left panel. You would be able to view the number of transactions, total transaction amount and commission earned by you on those transactions for every merchant
    3. Similarly, you can navigate to ‘Payouts transfer’ on the left panel to keep track of all transfers made by your merchants using Cashfree Payouts, and check the total commission earned on the transactions
    4. You can also keep a track of the total commission earned on transactions for a particular period by navigating to ‘Commissions’.
  </Accordion>

  <Accordion title="How is my commission calculated?">
    Refer to [Commissions and Invoices](/docs/partners/embedded/commissions-and-invoices) section
  </Accordion>

  <Accordion title="How will I get my commission in my bank account?">
    Refer to [Commissions and Invoices](/docs/partners/embedded/commissions-and-invoices) section

    <Note>
      You will be able to claim your commission only if your Affiliate KYC is complete and the commission structure is configured on your Cashfree Affiliate account.
    </Note>

    In case the commission structure is not configured on your Affiliate account, please reach out to [partnership.support@cashfree.com](mailto:partnership.support@cashfree.com).
  </Accordion>
</AccordionGroup>


# Marketing Kit
Source: https://www.cashfree.com/docs/partners/affiliates/marketing-kit

Download the Cashfree Affiliate Marketing Kit for ready-made collateral, product brochures, banners, and pitch decks that help you onboard merchants faster.

As a Cashfree Affiliate Partner, you have access to marketing resources that help you promote Cashfree to your clients and network. Use these collaterals to explain features, build trust, and onboard more merchants.

Available resources:

| **Title** | **Description** | **Resource** |
| - | - | - |
| Payment Gateway brochure | Help businesses understand and adopt a leading digital payment solution. | [View / Download](https://bit.ly/marketing_affiliate_1) |


# Overview
Source: https://www.cashfree.com/docs/partners/affiliates/overview

Explore the Cashfree Affiliate Program, a referral initiative that lets you recommend Cashfree products to merchants and earn commissions on every transaction.

The Cashfree Affiliate Program is a referral initiative that allows you to promote Cashfree products to your clients or customers and earn rewards. Help your customers streamline their payment experience while you earn a commission on every transaction they complete.

As an affiliate, you can offer referred businesses access to a complete suite of payment solutions.

## Key features

<CardGroup>
  <Card title="Become an Affiliate" href="/docs/partners/affiliates/become-cashfree-affiliate" icon="user-check">
    Sign up and get started with the affiliate program.
  </Card>

  <Card title="Refer Merchants" href="/docs/partners/affiliates/refer-merchants" icon="share">
    Share referral links and send merchant invitations.
  </Card>

  <Card title="Partner Dashboard" href="/docs/partners/affiliates/dashboard" icon="chart-line">
    Track referrals, commissions, and performance metrics.
  </Card>

  <Card title="Commission & Invoices" href="/docs/partners/affiliates/partner-commissions-and-invoices" icon="coins">
    Manage earnings and download commission invoices.
  </Card>

  <Card title="Marketing Kit" href="/docs/partners/affiliates/marketing-kit" icon="briefcase">
    Access promotional materials and marketing resources.
  </Card>

  <Card title="Merchant Assistance" href="/docs/partners/affiliates/assist-merchant/merchants-integration" icon="handshake">
    Help merchants with KYC and payment integration.
  </Card>
</CardGroup>

### Benefits of the affiliate program

* **All-in-one payment platform**\
  Provide your clients with a wide range of online payment options, including:
  * Payment gateway (UPI, credit card, debit card, Buy Now Pay Later, net banking, and more)
  * Payment links and forms
  * Additional payment tools

* **Earn industry best rewards**\
  Receive commission on every transaction completed by your referred customers.

* **Quick merchant onboarding**\
  Help your clients get started instantly with 100% paperless onboarding.

* **Affiliate Partner Dashboard**\
  Use a dedicated dashboard to manage referrals, track transactions, view commission earnings, and monitor performance.

* **Support for international payments**\
  Accept payments in over 100 currencies from customers around the world.

### Who can join?

Any registered business or individual can join the affiliate program, including:

* **Web and app developers, freelancers, and agencies**\
  Recommend Cashfree and earn commissions on transactions.

* **Coworking spaces, accelerators, and incubators**\
  Offer built-in payment solutions to startups in your network.

* **Associations and ecosystem enablers**\
  Equip your community with full-stack payment processing solutions.

* **Influencers and bloggers**\
  Promote Cashfree to your audience and earn passive income.

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related Topics</span>
  </p>

  <ul>
    <li><a href="/docs/partners/affiliates/become-cashfree-affiliate">Get Started as Affiliate Partner</a></li>
    <li><a href="/docs/partners/affiliates/refer-merchants">Refer and Onboard Merchants</a></li>
    <li><a href="/docs/partners/affiliates/dashboard">Affiliate Partner Dashboard</a></li>
    <li><a href="/docs/partners/affiliates/marketing-kit">Marketing Kit</a></li>
    <li><a href="/docs/partners/affiliates/faqs">Affiliate FAQs</a></li>
  </ul>
</div>


# Partner Earnings Guide
Source: https://www.cashfree.com/docs/partners/affiliates/partner-commissions-and-invoices

Understand how Cashfree Affiliate Partner commissions are calculated, when payouts are issued, and how to download invoices for referred merchant transactions.

Become a Cashfree Affiliate, offer payment solutions to your merchants, and earn a commission for every transaction your customers make.

## Commissions

As a **Cashfree Affiliate Partner**, you offer payment solutions to your merchants and earn a commission on each transaction they make. You can view your commissions in the **Partner Dashboard**. To receive your monthly payout, you need to create and submit an invoice through the dashboard.

### How Cashfree calculates commissions

Cashfree calculates your commission based on the difference between the merchant pricing and the partner pricing. Here are some key terms:

* **Merchant pricing**: The fee Cashfree charges the merchant for each transaction. This is either a percentage of the transaction amount or a flat fee.
* **Partner pricing**: The fee defined for you during onboarding, based on the merchant’s pricing.
* **Partner commission**: The difference between the merchant pricing and the partner pricing. This is what you earn per transaction.

Refer to the sample scenario below:

You refer an e-commerce merchant, **ABC Ltd.** The following pricing applies:

* **Merchant pricing for UPI**: 1.95%
* **Partner pricing for UPI**: 1.70%
* **Commission earned**: 1.95% – 1.70% = 0.25%

For a single transaction of ₹10,000:

* **Transaction amount**: ₹10,000
* **Fee charged to the merchant**: 1.95% × ₹10,000 = ₹195
* **Your commission**: 0.25% × ₹10,000 = ₹25

If ABC Ltd. processes 100 such transactions in a month, you earn:\
₹25 × 100 = ₹2,500

<Note>
  **Notes**:

  * Commission rates vary based on the merchant and partner pricing agreed upon during onboarding.
  * The system aggregates commissions monthly and displays them in the **Partner Dashboard**.
</Note>

### View commissions

You can track all your commissions from the affiliate dashboard.

1. Login to your dashboard using your credentials. Select **Commission** to view the total commission earned on transactions for a particular period.

<img alt="" />

2. To track payment gateway transactions by your merchants, select **PG Orders** in the navigation section on the left. You can view the number of transactions, total transaction amount, and commission earned by you on those transactions for every merchant.

### Commission for GST registered and unregistered affiliates

If you are GST registered and shared the GSTIN details with Cashfree, you will see the GST component in the **Commission** section. This information is not visible to the unregistered affiliates.

All GST-registered affiliates must share their GSTIN with Cashfree as per compliance requirements. Please update your GST details via the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1).

<img alt="" />

### Receive commission amount

Cashfree generates and displays commissions every month. You see the commission for the previous month by the 5th of the current month. To start the settlement process, you create an invoice.

#### Eligibility requirements

You receive a commission if:

* You have at least two transacting merchants in the month.
* Your Partner KYC is complete.
* Your commission amount is more than ₹1.

If you meet all the requirements but don’t receive your commission, raise a ticket through the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1).

## Invoices

To receive the commission amount for the previous months: you must create an invoice, specify the mandatory details, and upload the invoice.

To raise an invoice,

1. Login to the [Affiliate Partner](https://partner.cashfree.com/auth/login) dashboard using your credentials.
2. Select **Commission** > **Invoice**.
3. Click **Add Invoice**.

<img alt="" />

3. Select the months for which you want to create an invoice.
4. If you use an accounting system and want to upload an invoice using the same system, you can click **Upload Invoice**. Ensure your company's GSTIN and Cashfree GSTIN are specified in the invoice.\
   Alternatively, you can click **Generate Invoice** if you need help with creating the invoice. Cashfree automatically creates an invoice. You can enter the mandatory details and send the invoice.

<img alt="" />

5. Upload or generate the invoice and enter the mandatory details. Click **Approve and Send Invoice** to send the invoice to Cashfree for further processing of the commission amount.

<img alt="" />

### Invoice statuses

| Status | Description |
| :- | :- |
| Under Review | The invoice status is yet to be verified by Cashfree. |
| Approved | The invoice is verified and approved for processing the commission amount. |
| Payout in Progress | The commission amount is initiated for payout by Cashfree. |
| Paid | The commission amount is settled in your bank account registered with Cashfree. |
| Rejected | The invoice is rejected by Cashfree. |

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related Topics</span>
  </p>

  <ul>
    <li><a href="https://partner.cashfree.com/auth/login">Partners Dashboard</a></li>
    <li><a href="/docs/partners/affiliates/refer-merchants">Refer and Onboard Merchants</a></li>
  </ul>
</div>


# Refer and Onboard Merchants
Source: https://www.cashfree.com/docs/partners/affiliates/refer-merchants

Learn how Cashfree Affiliate Partners can refer businesses, assist with KYC verification, and guide them through integration to earn commissions on activations.

As a Cashfree Affiliate Partner, you can refer businesses to use Cashfree. You can also help them with KYC verification and integration to simplify onboarding.

After you sign in to your Affiliate Partner Dashboard, you can refer merchants in the following ways:

* [Share your referral link](/docs/partners/affiliates/refer-merchants#share-a-referral-link): Copy and share your unique referral link through email, messaging apps, or social media.

* [Send an email invitation](/docs/partners/affiliates/refer-merchants#send-an-email-invitation): Add the merchant’s details and send an invitation directly to their email address.

## Share a referral link

To share your referral link:

1. Login to the [Affiliate Partner](https://partner.cashfree.com/auth/login) dashboard using your credentials.
2. Go to the **Summary** page in your dashboard.
3. Copy your unique **Referral Link** and share it with merchants or clients via **WhatsApp**, **Instagram**, or other channels.

<img alt="referral_link" />

## Send an email invitation

To add a merchant via an email invitation:

1. Login to the [Affiliate Partner](https://partner.cashfree.com/auth/login) dashboard using your credentials.

2. Go to the **Affiliate Dashboard** > **Merchants** > **All** and click **Add Merchant**.

3. On the Add a New Merchant screen, under Basic Details, fill in the merchant's information:

* Merchant Name
* Merchant ID (Optional)
* Email Address
* Mobile Number
* Accept the terms and conditions.

<img alt="" />

3. Click **Add Merchant & Exit** or click **Proceed** to enable faster onboarding and KYC verification by submitting the merchant's basic KYC details.

   **Business Details (Optional)**:

   * Business Type
   * Business Model
   * Business PAN Details
   * Bank Account Details
   * Business Category and subcategory
   * Website and application link
   * Authorised signatory PAN details
   * Name as per Authorised Signatory PAN
   * GSTIN

<img alt="" />

4. Click **Add Merchant**.

Cashfree sends a verification email to the merchant and updates the onboarding status after successful verification.

<Note>
  If your merchant hasn't received the email, click the **Resend Email** option
  in the **Merchants** screen to resend the verification email to the merchant.
</Note>

## Bulk referral

To onboard multiple merchants at once, upload their details using a file in the format specified by Cashfree.

**To upload merchant details in bulk:**

1. Login to the [Affiliate Partner](https://partner.cashfree.com/auth/login) dashboard using your credentials.

2. Go to **Merchants**, and then select **Bulk upload merchants**.

3. Select **Upload File**, and choose the file you want to upload.\
   Ensure the following mandatory fields are filled:

   * Business Name
   * Registered Email
   * Phone Number
   * Merchant ID

   You can also include optional fields such as business details, PAN, and bank account details for KYC verification.

4. After upload, the system displays a summary of:

   * Total merchants added
   * Valid and invalid entries
   * Upload status

   You can download the file, correct any errors, and re-upload it.

[Download sample upload file](https://cashfreepublic.s3.ap-south-1.amazonaws.com/payoutsample/Bulk-Upload-Format.csv)

<img alt="Bulk Upload" />

<Note>
  **Note**:

  * Help merchants get started by assisting with their KYC process. For more information, refer [Merchants KYC](/docs/partners/affiliates/assist-merchant/merchants-kyc).
  * After payment activation, guide merchants in selecting business-friendly solutions to integrate and accept payments. For more information, refer [Merchants Integration](/docs/partners/affiliates/assist-merchant/merchants-integration).
</Note>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related Topics</span>
  </p>

  <ul>
    <li><a href="https://partner.cashfree.com/auth/login">Partners Dashboard</a></li>
    <li><a href="/docs/partners/affiliates/assist-merchant/merchants-kyc">Merchants KYC</a></li>
    <li><a href="/docs/partners/affiliates/assist-merchant/merchants-integration">Merchants Integration</a></li>
    <li><a href="/docs/partners/affiliates/dashboard">Affiliate Dashboard</a></li>
  </ul>
</div>


# Adding Merchants with Embedded Payments
Source: https://www.cashfree.com/docs/partners/embedded/add-merchants

Onboard new merchants from your Embedded Payments dashboard or APIs, activate their Cashfree accounts, and manage their transactions inside your platform.

## Overview

As part of Embedded Payments offerings, you can add and onboard your businesses as Merchants and manage their Cashfree accounts. After you activate the account, you can manage their transactions within your platform. You can add a merchant from the Embedded Payments Dashboard or using our APIs. The Merchant homepage has the following options:

* Merchant Name
* Merchant Email
* Merchant Added On Time
* Merchant Onboarding Status
* Min KYC Status
* Dashboard Access
* Action

<img alt="" />

## Adding merchant from dashboard

To add a merchant,

1. Go to the **Embedded Payments Dashboard** > **Merchants** > **Add Merchant**.

2. In the **Add New Merchant** screen, enter the merchant **Business Name**, **Registered Email**, **Phone Number**, and **Merchant ID**. Merchant ID is a unique alphanumeric identifier for the merchants. The system auto-generates it if you do not provide one. The maximum length is 40 characters. (Hyphen and underscore allowed.)

3. For faster onboarding and KYC verification, you can submit the merchants' basic KYC details.

   **Details Required (Optional)**:

   * Business Type
   * Business Model
   * Business PAN Details
   * Bank Account Details
   * Business Category and subcategory
   * Website and application link
   * Authorised signatory PAN details
   * Name as per Authorised Signatory PAN
   * GSTIN

4. Accept the terms and conditions, and click **Submit**.

<img alt="" />

Cashfree sends a verification email to the merchant and updates the onboarding status after successful verification.

## Add merchants using batch upload

To onboard many merchants at once, you can add all the details in a file (format specified by Cashfree) and upload it.

<img alt="" />

To bulk upload merchant details,

1. Go to the **Embedded Payments Dashboard** > **Merchants** > click **Bulk upload merchants**.

2. Click **Upload File** and choose the file you want to upload. Ensure all the details are provided as per the sample file. Fill in the mandatory fields - Business Name, Registered Email, Phone Number, and Merchant ID.\
   You can also specify the business details, PAN, and bank account details of the merchants for KYC verification, if required.

3. After you upload the file, the system displays the number of merchants added, how many are valid or invalid, and the upload status. You can download the file and correct any errors in the file and upload it again.

<img alt="" />

Sample file is available <a href="https://cashfreepublic.s3.ap-south-1.amazonaws.com/payoutsample/Bulk-Upload-Format.csv">here</a>.

## Add merchant using APIs

You can add a merchant using our APIs. Use these APIs to create a merchant and onboard merchants from your platform. There are other actions you can do with these APIs such as:

* Updating merchant details
* Fetching the merchant onboarding status
* Creating onboarding link

### List of merchant APIs

| API name | Description |
| :- | :- |
| [Create Merchant](/docs/api-reference/platforms/latest/merchant-onboarding/create-merchant) | Use this API to create a new merchant account. |
| [Update Merchant](/docs/api-reference/platforms/latest/merchant-onboarding/update-merchant) | Use this API to update the merchant details. |
| [Get Merchant Status](/docs/api-reference/platforms/latest/merchant-onboarding/update-merchant) | Use this API to view merchant details. |
| [Create Onboarding Link](/docs/api-reference/platforms/latest/merchant-onboarding/create-embeddable-onboarding-link-does-not-require-login) | Use this API to create a new onboarding link. |

Listen to merchant activation events using [Merchant Onboarding Webhooks](api-reference/platforms/latest/merchant-onboarding/webhooks).

<Note>
  If your merchant hasn't received the email, click the **Resend Email** option in the **Merchants** screen to resend the verification email to the merchant.
</Note>

## Activation lifecycle

#### Onboarding status

**Pending Email Verification**: The Merchant must first verify their registered email address. An email is sent automatically from Cashfree to the merchant email ID you specified when you added the merchant details.\
If the merchant hasn't received the email in their Primary inbox, please ask them to check it in the Spam folder. If the merchant has not received the email you can use the Resend Email email to send the verification email again.

**Email Verified**: This means that Merchant has verified their email address, and can now start their KYC verification process.

#### Product KYC status

* **Min KYC Pending**: Merchant must submit the required KYC details and documents.
* **Min KYC Submitted**: Merchant has submitted their KYC details and documents and the documents are being reviewed by Cashfree
* **Min KYC Rejected**: Merchant KYC has discrepancies and corresponding KYC details and documents need to be provided.
* **Min KYC Approved**: Merchant KYC has been approved and **Payment Gateway** product is activated.

<Tip>
  If your merchants have verified their email you can fill out the KYC on behalf
  of your merchant and activate the account for your merchants.
</Tip>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related Topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/platforms/latest/merchant-onboarding/create-merchant">Create Merchant API</a></li>
    <li><a href="/docs/api-reference/platforms/latest/merchant-onboarding/update-merchant">Update Merchant API</a></li>
    <li><a href="/docs/api-reference/platforms/latest/merchant-onboarding/get-merchant-status">Get Merchant Status API</a></li>
    <li><a href="/docs/api-reference/platforms/latest/merchant-onboarding/webhooks">Merchant Onboarding Webhooks</a></li>
  </ul>
</div>


# Commissions and Invoices
Source: https://www.cashfree.com/docs/partners/embedded/commissions-and-invoices

Track Embedded Payments commissions, review monthly payout cycles, and download partner invoices for transactions processed by your referred merchants.

## Commissions

### How does it work?

For Payment Gateway collections: your commission reflects on your partner dashboard when a customer makes a transaction on your referred merchant’s website/app and Cashfree settles the amount.

### Calculate commissions

Commissions are calculated in two ways:

* Flat rate
* Percentage of the transaction amount

**Commission as a flat rate**\
Flat rate pricing involves charging a fixed rate for a transaction. It does not alter or fluctuate regardless of the transaction amount.

For example, let us say you are an e-commerce automation platform, and you help e-commerce businesses in converting COD orders to pre-paid. You have offered Cashfree's Payment Gateway to one of your clients, ABC Ltd., at a markup of ₹100 over Cashfree's base rate (the minimum amount that goes to Cashfree). This example uses an illustrative base rate of 3%; see the [Cashfree payment gateway charges](https://www.cashfree.com/payment-gateway-charges/) page for Cashfree's actual rates. Here is the calculation for the transaction that ABC Ltd. collected ₹10,000 using Cashfree.

| Transaction amount (A) | Cashfree's charge (illustrative base rate) (B) | Your markup (C) | GST (D) | Total amount paid by your client |
| :- | :- | :- | :- | :- |
| ₹10,000 | 3% (10,000\*3%) = ₹300 | ₹100 | (300+100)\*18% = ₹72 | B+C+D = ₹472 |

**Commission as a percentage of the transaction amount**\
Percentage pricing involves charging a specific percentage for a transaction.

For example, let us say you have offered Cashfree’s payment gateway to ABC Ltd. at a markup of 1% instead of INR 100 over Cashfree’s base rate (the minimum amount that goes to Cashfree). This example uses the same illustrative base rate of 3% as above; see the [Cashfree payment gateway charges](https://www.cashfree.com/payment-gateway-charges/) page for Cashfree's actual rates.

| Transaction amount (a) | Cashfree's charge (illustrative base rate) (b) | Your markup (c) | GST (D) | Total amount paid by your client |
| :- | :- | :- | :- | :- |
| ₹10,000 | 3% (10,000\*3%) = ₹300 | 1% (10,000\*1%) = ₹100 | (300+100)\*18% = ₹72 | B+C+D = ₹472 |

### View commissions

You can track all your commissions from the embedded payments dashboard.

1. Login to your dashboard using your credentials. Select **Commission** to view the total commission earned on transactions for a particular period.

<img alt="" />

2. To track payment gateway transactions by your merchants, select **PG Orders** in the navigation section on the left. You can view the number of transactions, total transaction amount, and commission earned by you on those transactions for every merchant.

### Commission for GST registered and unregistered partners

If you are GST registered and shared the GSTIN details with Cashfree, you will see the GST component in the **Commission** section. Unregistered partners cannot see this information.

All GST-registered partners must share their GSTIN with Cashfree as per compliance requirements. Fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) to update your GST details.

<img alt="" />

### Receive commission amount

To initiate your commission settlement process for the previous month, you must create an invoice. See [Invoices](#invoices) for more information on how to create an invoice.

<Info>
  To claim your commission, ensure Partner KYC is complete, and the commission
  structure is configured on your Cashfree Partner account. If the
  commission structure is not configured on your Partner account, write to
  [partnership.support@cashfree.com](mailto:partnership.support@cashfree.com).
</Info>

This process is applicable for invoices from September 2022 onwards.

## Invoices

To receive the commission amount for the previous months: you must create an invoice, specify the mandatory details, and upload the invoice.

To raise an invoice,

1. Login to the partner dashboard using your credentials. Select **Commission** > **Invoice**.
2. Click **Add Invoice**.

<img alt="" />

3. Select the months for which you want to create an invoice.
4. If you use an accounting system and want to upload an invoice using the same system, you can click **Upload Invoice**. Ensure your company's GSTIN and Cashfree GSTIN are specified in the invoice.\
   Alternatively, you can click **Generate Invoice** if you need help with creating the invoice. Cashfree automatically creates an invoice. You can enter the mandatory details and send the invoice.

<img alt="" />

5. Upload or generate the invoice and enter the mandatory details. Click **Approve and Send Invoice** to send the invoice to Cashfree for further processing of the commission amount.

<img alt="" />

### Invoice statuses

| Status | Description |
| :- | :- |
| Under Review | The invoice status is yet to be verified by Cashfree. |
| Approved | The invoice is verified and approved for processing the commission amount. |
| Payout in Progress | The commission amount is initiated for payout by Cashfree. |
| Paid | The commission amount is settled in your bank account registered with Cashfree. |
| Rejected | The invoice is rejected by Cashfree. |

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related Topics</span>
  </p>

  <ul>
    <li><a href="/docs/partners/embedded/dashboard">Embedded Payments Dashboard</a></li>
    <li><a href="/docs/partners/embedded/add-merchants">Adding Merchants</a></li>
    <li><a href="/docs/partners/embedded/reports/reports">Embedded Payments Reports</a></li>
  </ul>
</div>


# Embedded Payments Dashboard
Source: https://www.cashfree.com/docs/partners/embedded/dashboard

Navigate the Cashfree Embedded Payments Partner Dashboard to manage merchants, view transactions, track settlements, and access reports from one workspace.

## Summary

The **Summary** screen gives you details about your daily transactions, like the current-day transaction count, the value of the transactions made by your merchants, and the last commission amount you received from Cashfree as per the referral program.

The following details are available on this page:

* Number of Transactions Today - Total number of PG and Payout transactions done by your merchants.
* Value of Today's Transactions - Total value of PG and Payout transactions done by your merchants today.
* Last Commission Amount - The last month's commission amount to be settled to your bank account.
* Merchant Stats - Number of merchants you have added and activated.
* Referral Link - Send this to your merchants for signing up.
* Partner Logo - To showcase that you are Cashfree Verified Affiliate Partner, a partner logo is available on the Summary screen. Copy and Download the Logo.
* PG Transaction Value
* Payouts Count
* Commission Summary

<img />

## PG orders

The PG Orders screen gives you merchant-wise details about the PG transactions. Details available are:

* Merchant Name
* Transaction Count
* Transaction Amount
* Total Commission

By default, the report shows details for the last 7 days. You can filter and view the details as per your requirement. Click on a particular transaction to view more details about it.

## Payout transfer

The Payout Transfer screen gives you details about the payout transactions done by your merchants. Details available are:

* Merchant Name
* Transfer Count
* Transfer Amount
* Total Commission

Click on a particular payout transaction to view more details about it.

## Developers

The developers section contains resources for developers to build and monitor their integration of APIs into their platform. This section shows the API keys, Webhooks, and Onboarding Webhooks.

<img />

### API keys

You can view the API keys and the time it was generated. You can also reset the API keys using the **Reset API key** option.

<img />

### Webhook

Add and define webhooks for individual events and get notified for each action on the URLs configured.

#### Add webhook endpoint

To add a new webhook,

1. Go to **Embedded Payment Dashboard** > **Developers**.
2. Click **Add Webhook Endpoint** to create a new webhook. Enter the endpoint URL and select the required action events and click **Add Webhook**.

<img />

1. Click the pencil icon beside each webhook to update the webhook. Edit the webhook URL, add/remove events from the list and click **Update Webhook**.

<img />

#### Onboarding webhook

Add onboarding webhooks to build webhooks for your partners so that you can get the merchant lifecycle webhook events.

To Add Onboarding Webhook,

1. Go to **Embedded Payment Dashboard** > **Developers**.
2. Click **Add Webhook URL** to create a new webhook. Enter the endpoint URL and click **Add Webhook**.

<img />

## Reports

Now generate various reports from the Embedded Payments Dashboard. The Reports homepage has the following options:

* Report Type
* Report Name
* Merchants Count (Click on it to view the merchant names)
* Report Size
* Generated At
* Download Report
* Delete Report

<img />

The following are the report types available in Embedded Payments:

* Transaction
* Settlement
* Refund
* Dispute

To generate a report,

1. Go to **Embedded Payment Dashboard** > **Reports**. Choose the required report from the **Report Type** drop-down and click **Generate Report**. You can also apply filter and view reports as per your requirement.

To view the merchant's list, click the number available on the corresponding merchant.

<img />

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related Topics</span>
  </p>

  <ul>
    <li><a href="/docs/partners/embedded/add-merchants">Adding Merchants</a></li>
    <li><a href="/docs/partners/embedded/reports/reports">Embedded Payments Reports</a></li>
    <li><a href="/docs/partners/embedded/commissions-and-invoices">Commissions and Invoices</a></li>
  </ul>
</div>


# Embedded Merchant Onboarding for Platforms
Source: https://www.cashfree.com/docs/partners/embedded/embedded-merchant-onboarding

Enable your platform to onboard and activate merchants on Cashfree without leaving your interface using embedded KYC collection and verification workflows.

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](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) to initiate the partnership process.
* **Obtain partner API key**: Log in to the [Partner Dashboard](https://partner.cashfree.com/auth/login) 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](#step-1-create-a-merchant)
2. [Update merchant details as information becomes available](#step-2-update-merchant-details)
3. [Upload KYC documents for verification](#step-3-upload-kyc-documents)
4. [Generate and display the embeddable onboarding link](#step-4-generate-the-embeddable-onboarding-link)
5. [Monitor merchant onboarding status through APIs](#step-5-monitor-merchant-status)
6. [Subscribe to onboarding webhooks for status updates](#step-6-subscribe-to-merchant-onboarding-webhooks)

## Step 1: Create a merchant

Create a merchant record in Cashfree using the [Create Merchant API](/docs/api-reference/platforms/latest/merchant-onboarding/create-merchant) 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](/docs/api-reference/platforms/latest/merchant-onboarding/update-merchant) 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](/docs/api-reference/platforms/latest/merchant-onboarding/upload-documents) as they become available.

The `document_type` field accepts the following values;

* `PAN`
* `AADHAAR`
* `GSTIN`
* `CIN`
* `BANK_STATEMENT`

## Step 4: Generate the embeddable onboarding link

Generate an embeddable onboarding link for merchants to complete remaining KYC and Aadhaar verification using the [Create Embeddable Onboarding Link API](/docs/api-reference/platforms/latest/merchant-onboarding/create-embeddable-onboarding-link-does-not-require-login).

<Info>
  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.
</Info>

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](/docs/api-reference/platforms/latest/merchant-onboarding/get-merchant-status):

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](/docs/api-reference/platforms/latest/merchant-onboarding/webhooks) to receive real-time notifications of status changes. Configure your webhook URL in the [Partner Dashboard](https://partner.cashfree.com/auth/login) under **Developers > Webhooks**.

Cashfree sends a single `MERCHANT_ONBOARDING_STATUS` event whenever the merchant's onboarding status changes (for example, when KYC is approved or the account is activated). Check the `data.onboarding_status` field in the payload for the current stage.

<Info>Verify webhook signatures using your partner API key before processing events. This prevents unauthorised requests from external sources.</Info>

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

<img alt="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 PAN | business\_type |
| - | - |
| P | Individual, Proprietorship |
| C | Private Limited, Public Limited |
| F | LLP, Partnership |
| T | Trust |
| H | Hindu Undivided Family (HUF) |
| A | Association of Persons (AOP) |
| B | Society |
| L | Local Authority |
| J | Artificial Juridical Person |
| G | Government |

## Test in sandbox

Use the following test credentials to test the onboarding flow end-to-end in the sandbox environment.

<AccordionGroup>
  <Accordion title="Individual or proprietor (without GST)">
    Use the following test credentials to validate the individual or proprietor onboarding flow in the sandbox environment:

    | Field | Test value |
    | - | - |
    | **Business PAN** | ABCPV1234D |
    | **Business Legal Name** | John Doe |
    | **Business Type** | Individual |
    | **Business Model** | B2C |
    | **Business Category** | Ecommerce/Retail |
    | **Business Subcategory** | Other goods |
    | **MCC** | 5199 |
    | **Non-GST Declaration** | My annual turnover is less than GST prescribed limit |
    | **Business Address** | Trial Address |
    | **City/PIN/State** | Mumbai / 400067 / Maharashtra |
    | **Aadhaar Number** | 655675523712 |
    | **Aadhaar OTP** | 111000 |
    | **Bank Account** | 026291800001191 |
    | **Bank IFSC** | YESB0000262 |
  </Accordion>

  <Accordion title="Private or public limited">
    Use the following test credentials to validate the private or public limited onboarding flow in the sandbox environment:

    | Field | Test value |
    | - | - |
    | **Business PAN** | ABCCD8000T |
    | **Business Legal Name** | John Doe Industries |
    | **Owner PAN** | ABCPV1234D |
    | **Owner Name as per PAN** | John Doe |
    | **Business Type** | Private Limited |
    | **Business Description** | I want to use payment gateway to collect payments... |
    | **MCC** | 5199 |
    | **Country** | India |
    | **Business Non-GST Declaration** | My business category is exempted from GST |
    | **CIN** | U72900KA2015PTC082989 |
    | **GSTIN** | 29AAICP2912R1ZR |
    | **Business Address** | Trial Address |
    | **City/PIN/State** | Mumbai / 400067 / Maharashtra |
    | **Aadhaar Number** | 655675523712 |
    | **Aadhaar OTP** | 111000 |
    | **Bank Account** | 026291800001191 |
    | **Bank IFSC** | YESB0000262 |
  </Accordion>
</AccordionGroup>

## Production deployment

Before deploying to production, update your API endpoint and credentials:

| Environment | API endpoint |
| - | - |
| **Sandbox** | `https://api-sandbox.cashfree.com` |
| **Production** | `https://api.cashfree.com` |

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related Topics</span>
  </p>

  <ul>
    <li><a href="/docs/partners/embedded/oauth-flow">OAuth Integration Flow</a></li>
    <li><a href="/docs/partners/embedded/dashboard">Partner Dashboard Guide</a></li>
    <li><a href="/docs/partners/embedded/overview">Embedded Payments Overview</a></li>
    <li><a href="/docs/api-reference/platforms/latest/merchant-onboarding/getting-started">Merchant Onboarding API</a></li>
  </ul>
</div>


# Get Started with Embedded Payments
Source: https://www.cashfree.com/docs/partners/embedded/get-started

Sign up for Cashfree Embedded Payments, activate your partner account, and access the dashboard to onboard merchants and integrate the payment gateway.

Signup for Embedded Payments to get started with the product. After you complete the signup and activation process, you will get access to the Embedded Payments Partner Dashboard. You can add merchants, integrate our Payment Gateway solution, keep a check on your commissions, get a snapshot of your business with Cashfree, and more within the Embedded Payments Dashboard.

## Signup for embedded payments

To use Embedded Payments, you must first create an Embedded Payments Partner account with Cashfree.

1. Go to the Embedded Payments [sign up page](https://partner.cashfree.com/partner-ui/authentication/signup?product=embedded).
2. In the **Create Account** screen, enter your Business Information and create a password for your account.
3. Click **Signup**.

<img alt="" />

4. You can [login](https://partner.cashfree.com/partner-ui/authentication/login) to the Embedded Payments Dashboard using the same credentials.

## Activate embedded payments account

After you complete the signup process, you will receive a welcome email from Cashfree. To complete the activation of your account, you have to send us the documents listed below to complete the KYC for your account. We will verify all the details and enable your account within 48 hours of submitting all documents.

You can <a href="https://partner.cashfree.com/partner-ui/authentication/login">Login</a> to your Embedded Payments Dashboard with the email ID and password entered during sign-up and explore your Embedded Payments Dashboard.

If you face any issues or need further support you can contact us at **[Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1)**.

### Documents required for KYC verification

**Business Details**

* Website URL
* Official email ID
* Official contact name and phone number
* Bank account details - name, account number, and IFSC

| For proprietorship | For partnership/LLP | For Private Ltd./Public Ltd. entities |
| :- | :- | :- |
| Business registration proof (GST certificate/Shop act licence/labour licence/ MSME certificate/Trade licence) | Business reg. proof (Partnership Deed/ LLP COI) | Certificate of Incorporation |
| Proprietor's PAN card | Business PAN card | Business PAN card |
| Proprietor's address proof (DL/Voter ID/Passport) | Authorised signatory PAN card | Authorised signatory/director's PAN card |
| Cancelled cheque or bank statement | Authorised signatory - address proof (DL/Voter ID/Passport) | Authorised signatory - address proof (DL/Voter ID/Passport) |
| | Cancelled cheque or bank statement | Cancelled cheque or bank statement |
| | | Memorandum of Association (MOA) and Articles of Association (AOA) |

<Tip>
  Commissions will be enabled only after completing KYC verification for your
  account. Please ensure you share the required documents on time.
</Tip>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related Topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/platforms/latest/merchant-onboarding/getting-started">Merchant Onboarding API Overview</a></li>
    <li><a href="/docs/api-reference/platforms/latest/merchant-onboarding/create-merchant">Create Merchant API</a></li>
    <li><a href="/docs/api-reference/platforms/latest/merchant-onboarding/update-merchant">Update Merchant API</a></li>
    <li><a href="/docs/api-reference/platforms/latest/merchant-onboarding/get-merchant-status">Get Merchant Status API</a></li>
    <li><a href="/docs/api-reference/platforms/latest/merchant-onboarding/webhooks">Merchant Onboarding Webhooks</a></li>
  </ul>
</div>


# Embedded Payment Gateway Integration
Source: https://www.cashfree.com/docs/partners/embedded/integration/gateway-integration

Integrate the Cashfree Embedded Payment Gateway to let your merchants accept cards, UPI, NetBanking, wallets, EMI, and Pay Later through a single checkout.

Cashfree Payment Gateway accepts domestic and international payments, and supports a wide range of payment options. Integrate Embedded Payment Gateway to easily enable your businesses to collect payments from their customers. Use our pre-built checkout integration, or customise the payment flow as per your requirements. You can also use our SDKs to easily integrate your mobile applications with our gateway. You can easily collect payments using popular Payment Methods like Cards, UPI, Netbanking, Wallets, PayPal, EMI, and Pay Later options.

<Info>
  You can build and try out the integration in the [sandbox environment](/docs/partners/embedded/integration/gateway-sandbox-environment).
</Info>

## Partner API keys

To get started with Partner API requests, you must first generate partner API keys from your [Partner Dashboard](https://partner.cashfree.com/partner-ui/authentication/login).

<Note>
  Partner API keys are available only for accounts onboarded under the Embedded Partner model. Accounts onboarded as a Reseller or Affiliate partner type do not have access to Partner API keys, and this cannot be enabled for those account types. If your integration requires programmatic access to manage Cashfree capabilities, your account must be onboarded under the Embedded Partner model. This is an account-level configuration.
</Note>

1. Go to **Partner Dashboard** > **Developers** section.
2. In the **Developers** Section, click **Generate API Key**.

<img alt="" />

<Frame>
  <img />
</Frame>

3. Copy and download the API keys for all API requests and future reference.

## Payment gateway APIs

All the Payment Gateway APIs that you find in [this](/docs/api-reference/payments/latest/overview) document can be used using partner authentication for your merchants.

### Partner authentication

To use Payment Gateway APIs for Partner Auth integration, **x-client-id** and **x-client-secret** headers will not be used anymore, please use the following headers:

* **x-partner-apikey**: This is the common API Key generated and unique for each Partner.
* **x-partner-merchantid**: This is the unique merchant ID for each merchant associated with the Partner. To know the merchant ID, go to **Partner Dashboard** > **Merchants** section, and copy the **Merchant ID** of the merchant you want to transact with.

### Payment gateway SDKs

We support the following SDK integrations:

| Integration types |
| :- |
| [JS Integration](/docs/payments/online/element/overview) |
| [Web Integration](/docs/payments/online/web/redirect) |
| [Android Integration](/docs/payments/online/mobile/android) |
| [iOS Integration](/docs/payments/online/mobile/ios) |
| [React Native Integration](/docs/payments/online/mobile/react-native) |
| [Cordova Integration](/docs/payments/online/mobile/cordova) |
| [Flutter Integration](/docs/payments/online/mobile/flutter) |

## Partner webhooks

To configure partner webhook,

1. Go to **Partner Dashboard** > **Developers** > **Webhooks**.

<img alt="" />

2. Click **Add Webhook URL** and enter the URL where you want to receive the updates.
3. Select the events for which you want to configure the webhooks to receive updates, and click **Add Webhook**.

<img alt="" />

4. Your webhook is now added successfully. You can also edit the added webhook using the edit option from the Webhook homepage.

Cashfree sends notifications to your configured endpoint as a POST request with the body containing the various parameters specifying the details of each event. Each request contains an event parameter that identifies its type.

We support webhooks in both encoded and JSON formats.

### How to use Cashfree webhooks?

### 1. Create an endpoint URL

To receive event notifications, you need to create an endpoint in your server that can accept requests from Cashfree. The endpoint URL can be HTTP in your local machine for testing purposes while developing. However, it should be HTTPS for the production environment.\
You receive webhook event notifications on the specified URLs. You can use one URL to handle different event types at once or specify individual URLs for specific events.

### 2. Select events to subscribe

You can configure webhooks to receive notifications for the following events:

* [Payment Success](/docs/api-reference/payments/latest/payments/webhooks#payment-success-webhook)
* [User Dropped](/docs/api-reference/payments/latest/payments/webhooks#payment-user-dropped-webhook)
* [Payment Failed](/docs/api-reference/payments/latest/payments/webhooks#payment-failed-webhook)
* [Refunds](/docs/api-reference/payments/latest/refunds/webhooks)
* [Settlement Webhooks](/docs/payments/split/webhooks)

<Info>
  An additional object **merchant** is sent in partner webhook payload to
  identify the merchants.
</Info>

```json json theme={"dark"}
{
"merchant": {
"merchant_id": {{merchant identifier}}
},
"data": {
...
},
"event_time": ...,
"type": ...
}
```

### 3. Test webhooks

Test your webhooks in the sandbox environment before going live to check payloads and integration. Configuring your webhooks, from the dashboard, in the test environment and events triggered in test transactions will send webhooks to the configured endpoint.

You can create endpoint URLs and test webhooks using tools like [webhook.site](https://webhook.site) or create a tunnel to your localhost using tools like [ngrok](https://ngrok.com).

### 4. Verify webhooks

It's a best practice to verify webhooks so that your server isn't manipulated by other requests acting as Cashfree webhooks. Use webhook signatures to verify Cashfree webhooks and perform further actions only after verifying the webhook.

#### Webhook signature

Use the signature to verify if the request hasn't been tampered with. To verify the signature at your end, you need your Cashfree Payment Gateway secret key along with the payload.

* The timestamp is present in the header `x-webhook-timestamp`.
* The actual signature is present in the header `x-webhook-signature`.

The signature creation logic is as below:

```text Signature theme={"dark"}
timestamp := 1617695238078;
signedPayload := $timestamp.$payload;
expectedSignature := Base64Encode(HMACSHA256($signedPayload, $partnerApiKey));
```

For sample codes, see [Manual Verification](/docs/payments/online/webhooks/overview#manual-verification-custom-approach).

<Note>
  Use **\$partnerApiKey** instead of **\$merchantSecretKey** to verify the webhooks.
</Note>

<Info>
  Sometimes you may receive the same webhook more than once. It's recommended to ensure that your implementation of the webhook is idempotent. Also, your endpoint should return a 2xx response for a successful webhook delivery from our end. Please ensure the response is quick before performing other logic, which could cause a timeout.
</Info>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related Topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/payments/latest/overview">Payment Gateway API Overview</a></li>
    <li><a href="/docs/payments/online/element/overview">JS Integration</a></li>
    <li><a href="/docs/api-reference/payments/latest/payments/webhooks">Payment Webhooks</a></li>
    <li><a href="https://partner.cashfree.com/auth/login">Partner Dashboard </a></li>
  </ul>
</div>


# Sandbox Environment for Embedded Payments Partners
Source: https://www.cashfree.com/docs/partners/embedded/integration/gateway-sandbox-environment

Use the Cashfree Embedded Payments sandbox to test gateway integrations, onboarding APIs, and webhooks safely before going live in the production environment.

Build and safely test your Embedded Payment Gateway Integration in our Sandbox ('Test') Environment developed exclusively for Embedded Payments Partners. Our aim is to streamline the integration process for developers seeking to incorporate our Payments and/or Onboarding APIs and Webhooks into their software platforms.

This dedicated testing environment provides you with a robust space to experiment, simulate, and code our development solutions within your platforms. Use the sandbox environment to test and validate your API and webhook integrations before going live in production.

## Advantages

* **Safe Testing**: You can conduct thorough testing without affecting real transactions. This safeguards your live environment while refining payment flows.
* **Realistic Simulations**: You can mimic real-world scenarios with our realistic simulations. You can as well test various payment methods, edge cases, and user interactions effortlessly.
* **Enhanced Debugging**: You can diagnose and troubleshoot issues effectively with detailed error reporting. Identify and resolve potential challenges before you impact your live users.

## How to simulate working environment in sandbox?

To begin with, login to your **Partner Dashboard** > and click the **Switch to Test** option. The dashboard will switch to the Test Environment (sandbox). There will be a visible label at the top to let you identify that you are in the Test Environment.

<img alt="" />

When you are in the test environment, the "Switch to Test" button will change to “Switch to Prod”. You can use it to switch back to the live environment.

In the test environment, you can simulate essential features of the payment gateway. You can replicate and test the functionalities required for the payment gateway system to operate seamlessly.

You can add new merchants from the **Merchants** section through the **Add Merchant** option. The system enables the added merchant in the test environment with the payment gateway activated and default pricing.

<Warning>
  Only Business Name, Registered Email and Phone Number are mandatory when adding a merchant in the test environment. You can then select the checkbox "I agree to the terms and conditions" and submit the form.<br />

  This activation takes up to 5 mins. Refresh the Merchants tab to recheck the activation status.<br />

  Please note that KYC is required for activating merchants in the live environment.
</Warning>

<img alt="" />

You can access the **Developers** tab, and generate Partner API Key and configure Partner Webhooks as well. Once done, you can follow integration steps mentioned in the [Embedded Payment Gateway Integration guide](/docs/partners/embedded/integration/gateway-integration).

To access your test API keys directly, go to **[Partner Dashboard > Developers > API Keys (test environment)](https://partner.cashfree.com/partner-ui/dashboard/developers/api-keys?env=test)**.

<img alt="" />

Sample request to **Create an Order** -

```Text curl theme={"dark"}
curl --location 'https://sandbox.cashfree.com/pg/orders' \
--header 'x-partner-apikey: {{partnerAPIKey}}' \
--header 'x-partner-merchantid: {{partnermerchantId}}'
--header 'x-api-version: 2022-09-01' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
  "order_amount": "10",
  "order_currency": "INR",
  "customer_details": {
    "customer_id": "USER123",
    "customer_name": "joe",
    "customer_email": "joe.s@cashfree.com",
    "customer_phone": "+919876543210"
  },
  "order_meta": {
    "return_url": "https://b8af79f41056.eu.ngrok.io?order_id={order_id}",
    "notify_url": "https://b8af79f41056.eu.ngrok.io/webhook.php",
  }
}'
```

Sample request to **Get Order** details -

```Text curl theme={"dark"}
curl --request GET \
     --url https://sandbox.cashfree.com/pg/orders/{{order_id}}\
     --header 'x-partner-apikey: {{partnerAPIKey}}' \
     --header 'x-partner-merchantid: {{partnermerchantId}}'
     --header 'accept: application/json' \
     --header 'x-api-version: 2022-09-01'
```

Apart from this, you can simulate payments using payments methods such as Card, UPI, and other payment modes that are part of the integration. Other features like Summary, PG Orders, Reports will also work in Test Environment

<Note>
  The data between Live and Test environments is completely isolated. Any data changes (eg. merchant addition, order creation etc.) in this environment will not happen in Live, and vice versa. These are not live transactions, these are just simulations. No fund movement will occur.
</Note>

## Partner webhooks

You can also configure webhooks in the test environment. To configure partner webhook,

1. Go to **Partner Dashboard** > **Developers** > **Webhooks**.

<img alt="" />

2. Click **Add Webhook URL** and enter the URL where you want to receive the updates.
3. Select the events for which you want to configure the webhooks to receive updates, and click **Add Webhook**.

<img alt="" />

Notifications will be sent to your configured endpoint as a POST request with the body containing the various parameters specifying the details of each event. Each request contains an event parameter that identifies its type.

We support webhooks in both encoded and JSON formats.


# Partner Platform OAuth Integration
Source: https://www.cashfree.com/docs/partners/embedded/oauth-flow

Enable businesses to securely connect their Cashfree payment accounts to your partner platform using OAuth and process payments on their behalf.

Integrate Cashfree's OAuth authentication to enable businesses using your partner platform to securely authorise payment processing through their Cashfree accounts. This integration allows businesses to offer payment capabilities to their customers without sharing sensitive credentials.

<Note>
  This integration uses OAuth 2.0. Cashfree handles authentication and issues access tokens that your platform uses to call Payment APIs on the business's behalf no credential sharing required.
</Note>

## Prerequisites

Before integrating OAuth with Cashfree, complete the following requirements:

* **Become a software partner**: Register your application as a software partner with Cashfree. [Contact Cashfree support](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) to initiate the partnership process.
* **Access Partner Dashboard**: Log in to the [Partner Dashboard](https://partner.cashfree.com/auth/login) and navigate to **Developers** to access OAuth configuration tools.
* **Obtain partner credentials**: You will need:
  * **Partner API Key**: Private key for authenticating your platform's API calls.
  * **OAuth Client ID**: Public identifier for your OAuth application.
* **Configure Webhook URL**: Provide a valid webhook URL where Cashfree will send payment status updates and account linking events.

## Integration flow

Use the following steps to complete the OAuth integration of the partner platform:

1. [Create an OAuth application and collect credentials](#step-1-create-an-oauth-application)
2. [Implement OAuth authorisation and token exchange](#step-2-implement-the-oauth-authorisation-flow)
3. [Refresh expired access tokens securely](#step-3-refresh-expired-access-tokens)
4. [Create orders and process customer payments](#step-4-create-orders-and-process-payments)
5. [Track payment outcomes using API and webhooks](#step-5-check-payment-status)

## Key benefits

OAuth integration provides the following benefits:

* **Secure credential handling**: Businesses never share passwords, OAuth tokens have limited scope.
* **Simple onboarding**: Businesses link accounts in minutes without manual verification.
* **Account management**: Businesses can unlink accounts anytime via [Merchant Dashboard](https://merchant.cashfree.com/auth/login) or API.
* **Real-time notifications**: Webhooks provide immediate payment status updates.

## Step 1: Create an OAuth application

Create an OAuth application in the Partner Dashboard to obtain your OAuth credentials, using the following steps:

<Steps>
  <Step title="Create the application">
    Navigate to **[Partner Dashboard](https://partner.cashfree.com/auth/login) > Developers > OAuth App** and complete the application form with the following details:

    | Field | Description |
    | - | - |
    | **App Name** | Internal identifier for your application (for example, "partner platform"). |
    | **App Brand Name** | Name shown to businesses during authorisation (for example, "Acme partner platform"). |
    | **Logo** | Upload a logo in PNG or JPG format (maximum 2 MB, square 1:1 aspect ratio recommended). |
    | **Redirect URL** | Your platform's endpoint that receives the authorisation code after consent (for example, `https://yourplatform.com/oauth/callback`). |
  </Step>

  <Step title="Retrieve your OAuth client ID">
    After creating the application, Cashfree displays your `oauth-client-id` in the response. Store this value securely, you will use it for all OAuth API requests.
  </Step>
</Steps>

## Step 2: Implement the OAuth authorisation flow

Guide businesses through Cashfree's authorisation flow to obtain merchant credentials.

<Steps>
  <Step title="Generate the authorisation link">
    Create an authorisation link that directs businesses to Cashfree's consent screen. Your platform calls the authorisation endpoint with the business's unique identifier.

    The request supports the following parameters:

    | Parameter | Type | Required | Description |
    | - | - | - | - |
    | `response_type` | string | Yes | Always set to `"code"` for authorisation code flow. |
    | `scope` | string | Yes | Set to `"read_write"` to allow payment processing on behalf of the business. |
    | `state` | string | Optional | Arbitrary string (8-64 characters) for CSRF protection; returned in redirect URL. |
    | `merchant_id` | string | Optional | Your internal reference ID for the business; helps track which business authorised the request. |

    <Note>The `auth_link` is valid for 1 hour. Redirect the business to this link to begin authorisation.</Note>
  </Step>

  <Step title="Business authorisation">
    The business logs in with their Cashfree credentials and reviews the permissions your platform is requesting:

    * **Allowed**: Manage payments (including refunds, settlements, disputes).
    * **Allowed**: View account information (basic details).
    * **Not allowed**: Modify sensitive information (bank account, email, phone number).

    After authorisation, Cashfree redirects the business back to your configured redirect URL with an authorisation code.
  </Step>

  <Step title="Redirect URL format">
    Use the following redirect URL format to capture the authorisation response:

    ```
    https://yourplatform.com/oauth/callback
      ?merchant_id=business_reference_id
      &code=auth_code_valid_for_5_minutes
      &state=secure_random_string
      &scope=read_write
    ```
  </Step>

  <Step title="Exchange authorisation code for access token">
    Immediately after receiving the authorisation code, exchange it for an access token. This token grants your platform the ability to call Cashfree APIs on the business's behalf.

    Store the following credentials securely for subsequent API calls:

    * `access_token`: Use for Cashfree API calls, valid for 24 hours.
    * `refresh_token`: Use to obtain a new access token after expiry, valid for 90 days.
    * `merchant_id`: Your reference ID for the linked business.

    <Info>The authorisation code is valid for only 5 minutes. If the code expires before you exchange it, the business must authorise again.</Info>
  </Step>
</Steps>

## Step 3: Refresh expired access tokens

Access tokens expire after 24 hours. Use the refresh token to obtain a new access token without requiring the business to authorise again.

<Warning>A new refresh token is generated with each access token refresh. The previous refresh token becomes invalid immediately. Always store the new refresh token to avoid losing access.</Warning>

## Step 4: Create orders and process payments

After obtaining the access token, use Cashfree's payment APIs to create orders and process payments on behalf of the business.

<Steps>
  <Step title="Create an order">
    Create an order to represent a transaction the business wants to process using the [Create Order API](/docs/api-reference/payments/latest/orders/create-order).

    Store the `payment_session_id` and `cf_order_id` you will need both to initiate payment.
  </Step>

  <Step title="Offer payment methods to customers">
    After creating an order, present payment options to the customer. Cashfree supports two payment flows:

    <Tabs>
      <Tab title="UPI Intent (Seamless)">
        Customers complete UPI payment directly within your platform without redirecting to Cashfree.

        Initiate UPI Intent payment using the [Order Pay API](/docs/api-reference/payments/latest/payments/order-pay):

        Display these UPI links to customers. They can click any link to open their preferred UPI app and complete payment.
      </Tab>

      <Tab title="Hosted Checkout (Flexible)">
        Customers are redirected to Cashfree's secure checkout page, which supports cards, net banking, wallets, and UPI.

        **Include Cashfree SDK**

        **Initialise and open checkout**

        Cashfree displays the checkout page with all available payment options. After payment, the customer is redirected to your `return_url` (configured during order creation).
      </Tab>
    </Tabs>
  </Step>
</Steps>

## Step 5: Check payment status

Retrieve payment status using either synchronous API queries or asynchronous webhooks. For production integrations, use webhooks for real-time updates.

Query payment status using the [Get Payments for Order API](/docs/api-reference/payments/latest/payments/get-payments-for-an-order):

Receive webhooks (asynchronous) using [Payment Webhooks API](/docs/api-reference/payments/latest/payments/webhooks). Cashfree sends webhook events to your configured webhook URL for payment status changes and account unlinking events. Configure your webhook URL in **[Partner Dashboard](https://partner.cashfree.com/auth/login) > Developers > Webhooks**.

Once configured, Cashfree sends the following webhook event types to your webhook URL:

* `payment.success`: Payment completed successfully.
* `payment.failed`: Payment declined or timed out.
* `merchant.unlinked`: Business unlinked their account from your platform.

<Info>Verify webhook signatures using your partner API key before processing webhook events. This prevents unauthorised requests from external sources.</Info>

## Manage account linking

Use the following endpoints to check account linking status and revoke access when needed. Unlinking can be initiated by the business via [Merchant Dashboard](https://merchant.cashfree.com/auth/login) or by your platform via API.

### Check merchant status

Retrieve the linking status and onboarding details for a business using the [Get Merchant Status API](/docs/api-reference/platforms/latest/merchant-onboarding/get-merchant-status).

### Unlink a business account

Revoke your platform's access to a business's Cashfree account. This immediately invalidates all access tokens and refresh tokens for that merchant.

<Warning>After unlinking, your platform cannot process payments for this business until they authorise again. Store previous access and refresh tokens securely if needed for compliance or audit purposes.</Warning>

## Production deployment

Update the following endpoints and credentials before deploying to production:

| Environment | API endpoint |
| - | - |
| **Sandbox** | `https://api-sandbox.cashfree.com` and `https://sandbox.cashfree.com` |
| **Production** | `https://api.cashfree.com` and `https://cashfree.com` |

Replace your `oauth-client-id`, `x-partner-apikey`, and API endpoints with production credentials and URLs. Ensure you have configured your production webhook URL in the [Partner Dashboard](https://partner.cashfree.com/auth/login) and successfully tested the entire authorisation and payment flow.

## Support and resources

Use the resources below for OAuth implementation guidance and support:

<CardGroup>
  <Card title="Partner Dashboard" icon="grid-2" href="https://partner.cashfree.com/auth/login">
    Access OAuth credentials and configure webhook settings.
  </Card>

  <Card title="Payment Gateway API Reference" icon="book-open" href="/docs/api-reference/payments/latest/orders/create-order">
    Review endpoint details for creating orders and processing payments.
  </Card>

  <Card title="Request support" icon="headset" href="https://merchant.cashfree.com/merchants/landing?env=prod&raise_issue=1">
    Get help with onboarding and technical issues from the Cashfree support team.
  </Card>
</CardGroup>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related Topics</span>
  </p>

  <ul>
    <li><a href="/docs/partners/embedded/embedded-merchant-onboarding">Merchant Onboarding for Platforms</a></li>
    <li><a href="/docs/partners/embedded/overview">Embedded Payments Overview</a></li>
    <li><a href="/docs/partners/embedded/commissions-and-invoices">Commissions and Invoices</a></li>
    <li><a href="/docs/api-reference/payments/latest/orders/create-order">Payment Gateway API </a></li>
  </ul>
</div>


# Embedded Payments Overview
Source: https://www.cashfree.com/docs/partners/embedded/overview

Discover how Cashfree Embedded Payments lets platforms, ERPs, and SaaS providers offer compliant in-product payments with built-in merchant onboarding.

Embedded Payments by Cashfree lets platforms enable direct, compliant payments between businesses and their customers, with seamless onboarding built in. Ideal for ERPs, SaaS, and software platforms embedding payments into their product.

## Key features

<CardGroup>
  <Card title="Merchant Onboarding" href="/docs/partners/embedded/add-merchants" icon="user-plus">
    Onboard businesses with automated KYC and compliance checks.
  </Card>

  <Card title="Payment Gateway Integration" href="/docs/partners/embedded/integration/gateway-integration" icon="credit-card">
    Integrate payment processing with UPI, cards, and wallets.
  </Card>

  <Card title="Business Dashboard" href="/docs/partners/embedded/dashboard" icon="chart-line">
    Manage transactions, reporting, and payment analytics.
  </Card>

  <Card title="Commission Management" href="/docs/partners/embedded/commissions-and-invoices" icon="coins">
    Track commission earnings with automated invoicing.
  </Card>

  <Card title="Advanced Reports" href="/docs/partners/embedded/reports/reports" icon="file-chart-column">
    Access settlement, transaction, and reconciliation reports.
  </Card>

  <Card title="Sandbox Environment" href="/docs/partners/embedded/integration/gateway-sandbox-environment" icon="flask">
    Test integrations in a complete sandbox environment.
  </Card>
</CardGroup>

**ERPs and SaaS**:
Embed payments in ERP and SaaS products across education, hospitality, POS, accounting, billing, and checkout systems.

**Platforms**:
Enable end-to-end payment flows inside e-commerce, CRM, and financial platforms.

## Advantages of embedded payments

Embedded Payments provides the following advantages:

* **Payment solutions**: Offer payment solutions to businesses on your platform, such as payment gateway, easy split, payment links, and subscriptions.
* **Onboarding businesses**: Use pre-built or custom flows to onboard businesses onto Cashfree.
* **Managing payments**: Provide businesses and their customers with the best payment experience using Cashfree's product suite.
* **Ensuring compliance**: Simplify compliance requirements across onboarding, KYC, payments, and post-payment journeys.
* **API-first product**: Use robust APIs to scale your platform and support more businesses without operational overhead.
* **Powerful dashboard**: Access a separate dashboard to add and manage businesses, view detailed transaction reports, and monitor commission amounts.
* **Unlocking new revenue**: Earn commissions for every transaction across onboarded businesses.

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related Topics</span>
  </p>

  <ul>
    <li><a href="/docs/partners/embedded/add-merchants">Adding Merchants</a></li>
    <li><a href="/docs/partners/embedded/integration/gateway-integration">Gateway Integration</a></li>
    <li><a href="/docs/partners/embedded/reports/reports">Embedded Payments Reports Overview</a></li>
    <li><a href="/docs/partners/embedded/commissions-and-invoices">Commissions and Invoices</a></li>
  </ul>
</div>


# Dispute Report
Source: https://www.cashfree.com/docs/partners/embedded/reports/dispute-reports

View the Cashfree Embedded Payments dispute report to track disputed transactions, chargeback statuses, and resolution timelines for any selected date range.

Through the dispute report, you can view the list of disputed transactions for the selected time period.

## Generate dispute report

Follow these steps to generate and download a dispute report:

1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
2. Navigate to **Payment Gateway** > **Reports** > **Download Reports**.
3. Click the **Generate New Report** button.
4. Configure your report settings:
   * **Report Type**: Select **Disputes** from the dropdown.
   * **Date Range**: Choose the time period for the report.
   * **File Format**: Select CSV or XLSX.
   * **File Name**: Modify if needed, this is optional.
5. Click **Generate Report**.
6. Once generated, click the **three dots (⋮)** next to your report.
7. Click **Download Report** to save the file.
8. Click **Share Report** to share the report via email or mobile number and set the validity period.
   <img alt="" />

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related Topics</span>
  </p>

  <ul>
    <li><a href="/docs/partners/embedded/reports/reports">Embedded Payments Reports Overview</a></li>
    <li><a href="/docs/partners/embedded/reports/transaction-reports">Transaction Reports</a></li>
    <li><a href="/docs/partners/embedded/reports/settlement-reports">Settlement Reports</a></li>
    <li><a href="/docs/partners/embedded/dashboard">Embedded Payments Dashboard</a></li>
  </ul>
</div>


# Ledger Report
Source: https://www.cashfree.com/docs/partners/embedded/reports/ledger-reports

Review the Cashfree Embedded Payments ledger report to see every credit and debit on your partner account for any selected date range and reconcile balances.

The ledger report summarises all the debits and credits that have happened in your account for the selected time period.

## Generate ledger report

Follow these steps to generate and download a ledger report:

1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
2. Navigate to **Payment Gateway** > **Reports** > **Download Reports**.
3. Click the **Generate New Report** button.
4. Configure your report settings:
   * **Report Type**: Select **Ledger** from the dropdown.
   * **Date Range**: Choose the time period for the report.
   * **File Format**: Select CSV or XLSX.
   * **File Name**: Modify if needed, this is optional.
5. Click **Generate Report**.
6. Once generated, click the **three dots (⋮)** next to your report.
7. Click **Download Report** to save the file.
8. Click **Share Report** to share the report via email or mobile number and set the validity period.
   <img alt="" />

## Ledger report specification

The following table describes the parameters available in the ledger report:

| Parameter | Sample value | Flag | Description |
| - | - | - | - |
| Ledger ID | 130872636 | id | Unique identifier assigned by Cashfree to each ledger entry. |
| Sale Type | DEBIT | enum | Indicates whether this ledger entry decreases or increases your balance. Possible values include: **DEBIT** - amount deducted from balance and **CREDIT** - amount added to balance. |
| Event | REFUND | enum | The type of event that generated this ledger entry. The common values are: **REFUND**, **FUND\_SWEEP**, **SETTLEMENT\_COMPUTE**, **CORRECTION\_CREDIT**. |
| Amount | 3.00 | amount | The monetary value of this ledger transaction. This amount is either added to or subtracted from your balance based on the **Sale Type** (CREDIT or DEBIT). |
| Event ID | 98307625 | id | The identifier for the underlying event associated with this ledger entry. For example, for **REFUND** events this corresponds to the Refund ID. |
| Added On | 2025-10-31 15:49:41 | datetime | Date and time at which this ledger entry was recorded in the ledger. |
| Closing Balance | -17.52 | amount | Ledger balance immediately after applying this entry. Reading the report in sequence allows you to follow how your balance evolves over time. |

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related Topics</span>
  </p>

  <ul>
    <li><a href="/docs/partners/embedded/reports/reports">Embedded Payments Reports Overview</a></li>
    <li><a href="/docs/partners/embedded/reports/settlement-recon-reports">Settlement Recon Reports</a></li>
    <li><a href="/docs/partners/embedded/reports/settlement-reports">Settlement Reports</a></li>
    <li><a href="/docs/partners/embedded/dashboard">Embedded Payments Dashboard</a></li>
  </ul>
</div>


# Refunds Report
Source: https://www.cashfree.com/docs/partners/embedded/reports/refunds-reports

Use the Cashfree Embedded Payments refunds report to view initiated refunds with order IDs, refund IDs, ARN, transaction amounts, and processing dates.

‌The refunds report gives you details of all the refunds that are initiated in the selected time period. The report includes refund ID, order ID, transaction and refund amount, date, corresponding refund ID, ARN and more.

## Generate refunds report

Follow these steps to generate and download a refunds report:

1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
2. Navigate to **Payment Gateway** > **Reports** > **Download Reports**.
3. Click the **Generate New Report** button.
4. Configure your report settings:
   * **Report Type**: Select **Refunds** from the dropdown.
   * **Date Range**: Choose the time period for the report.
   * **File Format**: Select CSV or XLSX.
   * **File Name**: Modify if needed, this is optional.
5. Click **Generate Report**.
6. Once generated, click the **three dots (⋮)** next to your report.
7. Click **Download Report** to save the file.
8. Click **Share Report** to share the report via email or mobile number and set the validity period.
   <img alt="" />

## Refund report specification

The following table describes the parameters available in the refunds report:

| Parameter | Sample value | Flag | Description |
| - | - | - | - |
| Refund ID | 95110239 | id | Unique identifier assigned to each refund transaction. This ID can be used to track and reference specific refunds across different reports and systems. |
| Order ID | ORDER\_12345 | id | Unique ID generated by the merchant to identify the order or transaction. This links the refund back to its corresponding order in the merchant’s internal systems. |
| Order Note | Payment against products shipped. | text | Additional notes or comments added to the original order. This may contain merchant-specific information. |
| Reference ID | 4400566852 | id | Unique identifier generated by Cashfree for the original payment transaction. Use this ID to track and reference the payment across Cashfree systems and reports. |
| Currency | INR | currency | The currency used for the refund transaction. All amounts in this row are in this currency. |
| Transaction Amount | 10.5 | amount | The total amount of the original payment transaction before any refunds were processed. This helps understand the original transaction value. |
| Refund Amount | 10.5 | amount | The actual amount being refunded to the customer. This may be a partial or full refund of the original transaction amount. |
| Initiated On | 2025-10-10 17:15:21 | datetime | The date and time at which the **merchant** initiated the refund. |
| Status | SUCCESS | enum | Current status of the refund transaction. Possible values include: **SUCCESS**, **PENDING**, **REJECTED**, **CANCELLED**. |
| Processed On | 2025-10-10 17:31:18 | datetime | The date and time when the refund was actually processed and completed by the payment gateway or bank. |
| Refund ARN | 629715852835 | text | Acquirer Reference Number: a unique reference provided by the acquiring bank for the refund transaction. This can be used for bank-level tracking and reconciliation. |
| Refund Note | The customer requested a refund for a damaged product. | text | Additional notes or comments specific to the refund request, such as the reason for the refund. |
| Current Speed | INSTANT | enum | The processing speed tier currently assigned to the refund. This affects how quickly the refund reaches the customer. Example: **STANDARD** or **INSTANT**. |
| Service Charge | 1.2 | amount | Instant refund charges applied if the refund was processed via the instant refund (IR) rails. If the refund is processed via the standard rails, no instant refund charges are applied to the merchant. |
| Service Tax | 0.22 | amount | Tax amount applied on the service charge for the refund transaction, as per applicable tax regulations. |
| Requested Speed | STANDARD | enum | The refund processing speed originally requested by the merchant when initiating the refund. Example: **STANDARD** or **INSTANT**. |
| Speed Change Reason | | enum | If the refund speed was changed from the originally requested speed, this field explains the reason for the change. |
| Vendor ID 1 | VENDOR\_001\_ELECTRONICS | id | Vendor ID from which the refund amount has been debited. |
| Vendor Amount 1 | 6.5 | amount | The amount that has been debited from the balance of the corresponding vendor. |
| Vendor ID 2 | VENDOR\_002\_SHIPPING | id | Vendor ID from which the refund amount has been debited. |
| Vendor Amount 2 | 2.0 | amount | The amount that has been debited from the balance of the corresponding vendor. |
| Vendor ID 3 | VENDOR\_003\_INSURANCE | id | Vendor ID from which the refund amount has been debited. |
| Vendor Amount 3 | 1.5 | amount | The amount that has been debited from the balance of the corresponding vendor. |

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related Topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/payments/latest/refunds/create-refund">Refunds API Overview</a></li>
    <li><a href="/docs/partners/embedded/reports/reports">Embedded Payments Reports Overview</a></li>
    <li><a href="/docs/partners/embedded/reports/transaction-reports">Transaction Reports</a></li>
    <li><a href="/docs/partners/embedded/dashboard">Embedded Payments Dashboard</a></li>
  </ul>
</div>


# Overview
Source: https://www.cashfree.com/docs/partners/embedded/reports/reports

Browse the Cashfree Embedded Payments reports suite to reconcile transactions, review adjustments, analyse settlements, and download data for any date range.

Cashfree supports various reports. These reports help you reconcile transactions, view adjustments and settlements, analyse your business transactions, and more. You can view these reports day-wise, week-wise or for a custom date range. You also have the option to download the reports.

<Note>
  While generating a report, you can get consolidated reports across your merchants.
</Note>

Embedded Payment Gateway reports include the following:

* [Transactions](/docs/partners/embedded/reports/transaction-reports)
* [Settlements](/docs/partners/embedded/reports/settlement-reports)
* [Refunds](/docs/partners/embedded/reports/refunds-reports)
* [Disputes](/docs/partners/embedded/reports/dispute-reports)
* [Settlement Recon](/docs/partners/embedded/reports/settlement-recon-reports)

<img alt="" />

<Note>
  To map any report entry to the related merchant, we've introduced an additional column - Partner Merchant Reference ID in the respective reports. This ID is same as the Merchant ID in Merchants tab.
</Note>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related Topics</span>
  </p>

  <ul>
    <li><a href="/docs/partners/embedded/reports/transaction-reports">Transaction Reports</a></li>
    <li><a href="/docs/partners/embedded/reports/settlement-reports">Settlement Reports</a></li>
    <li><a href="/docs/partners/embedded/reports/refunds-reports">Refunds Reports</a></li>
    <li><a href="/docs/partners/embedded/reports/dispute-reports">Dispute Reports</a></li>
  </ul>
</div>


# Settlement Recon Report
Source: https://www.cashfree.com/docs/partners/embedded/reports/settlement-recon-reports

Reconcile every Cashfree settlement with the partner Settlement Recon report, which lists transactions, adjustments, refunds, and disputes per settlement cycle.

The **Settlement Recon** report helps you reconcile all types of settlements for a selected date range. It lists settlements received in the specified date range, along with detailed information about transactions, adjustments/refunds against transactions, disputes, and more.

## Generate settlement recon report

Follow these steps to generate and download a Settlement Recon report:

1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
2. Navigate to **Payment Gateway** > **Reports** > **Download Reports**.
3. Click the **Generate New Report** button.
4. Configure your report settings:
   * **Report Type**: Select **Settlement Recon** from the dropdown.
   * **Date Range**: Choose the time period for the report.
   * **File Format**: Select CSV or XLSX.
   * **File Name**: Modify if needed, this is optional.
5. Click **Generate Report**.
6. Once generated, click the **three dots (⋮)** next to your report.
7. Click **Download Report** to save the file.
8. Click **Share Report** to share the report via email or mobile number and set the validity period.
   <img alt="" />

## Settlement recon report specification

<Tabs>
  <Tab title="Settlements">
    The **Settlements** section provides one row per settlement batch, showing what was settled, when it was processed, and the final amount credited to your bank account.

    The following table describes the parameters available in the settlements section of the settlement recon report:

    | Parameter | Sample value | Flag | Description |
    | - | - | - | - |
    | ID | 208386848 | id | Unique ID for the settlement generated by Cashfree. Use this ID to cross-reference the settlement in other reports. |
    | Total Transaction Amount | 110.00 | amount | Sum of all eligible transaction amounts considered for this settlement before any charges, taxes, refunds, chargebacks, or other adjustments. |
    | Settlement Amount | 20.00 | amount | Amount left after deducting Cashfree’s charges and other fees from the total transaction amount, before applying adjustments. |
    | Adjustment | 14.32 | amount | Net effect of all adjustments linked to this settlement, such as chargebacks, refunds, and other adjustments. Can be positive or negative. |
    | Net Settlement Amount | 14.32 | amount | Final amount credited to your bank account for this settlement after charges, taxes, and adjustments. This should match the credit seen in your bank statement. |
    | From | 2025-10-08 18:18:03 | datetime | Date and time of the earliest transaction included in this settlement batch. |
    | Till | 2025-10-08 18:18:03 | datetime | Date and time of the latest transaction included in this settlement batch. |
    | Status | Processed | enum | Current status of the settlement for example: **Processed**, **Pending**, **Failed**. |
    | UTR No. | AXISCN1169361047 | id | Bank reference number (UTR) for this settlement payout. You can use this to match the settlement with the entry in your bank statement. |
    | Settlement Date | 2025-10-08 18:18:03 | datetime | Date and time when the settlement was successfully processed and confirmed. |
    | Settlement Type | STANDARD | enum | Type of settlement, such as **STANDARD**, **INSTANT**, or **ON\_DEMAND**. |
    | Settlement Charge | 20.00 | amount | Total settlement-level charges applied for this settlement batch. |
    | Settlement Tax | 10.00 | amount | Tax amount applied on the settlement charges. |
    | Remarks | Settled | text | Any additional comments or notes added to the settlement, usually to highlight exceptions or special handling. |
  </Tab>

  <Tab title="Transaction details">
    The **Transaction details** section shows detailed information for each individual transaction and event included in the settlements. Each row represents a specific event such as payment, refund, or chargeback.

    The following table describes the parameters available in the transaction details section of the settlement recon report:

    | Parameter | Sample value | Flag | Description |
    | - | - | - | - |
    | Event ID | 4387450090 | id | Unique ID for the event in Cashfree systems such as: payment, refund, chargeback, dispute, or adjustment. This ID is always generated by Cashfree. |
    | Event Type | PAYMENT | enum | Category of the event. Typical values include **PAYMENT**, **REFUND**, **CHARGEBACK**, **CHARGEBACK\_REVERSE**, **DISPUTE**, **DISPUTE\_REVERSE**, **RISK**, **RISK\_REVERSE**, **OTHER\_ADJUSTMENT**, etc. |
    | Sale Type | CREDIT | enum | Indicates whether the event increases or decreases the amount eligible for settlement. **CREDIT** increases the amount; **DEBIT** decreases it. |
    | Event Currency | INR | currency | Currency in which the event amount is recorded. For payments, this is the transaction currency. |
    | Event Time | 2025-09-26 15:05:12 | datetime | Date and time when the event actually occurred (for example, when the payment was created or the refund initiated). |
    | Processed On | 2025-10-08 15:35:50 | datetime | Date and time when this event was processed for settlement. |
    | Status | SUCCESS | enum | Status of the event. Important for events such as refunds, disputes and chargebacks for example: **SUCCESS**, **PENDING**, **FAILED**, **N/A**. |
    | Event Amount | 3.00 | amount | Original amount of the event in the event currency. |
    | Event Settlement Amount | 3.00 | amount | Portion of the event amount that is considered for settlement after applying relevant charges and taxes. |
    | Settlement Date | 2025-10-08 15:35:50 | datetime | Date on which this event was included in a settlement. |
    | UTR | AXISCN1169361047 | id | UTR of the settlement in which this event was included. Use this to link the event to the settlement in the summary section and your bank statement. |
    | Refund Type | – | enum | For refund events, shows whether the refund is standard or instant. Blank for non-refund events. |
    | Refund ARN | – | id | ARN/RRN for refund transactions, when available (usually for card or UPI refunds). Blank for non-refund events. |
    | Adjustment Remarks | – | text | Notes explaining an **OTHER\_ADJUSTMENT** or similar event. Blank for regular payment or refund events. |
    | Merchant Reference ID | CFPay\_r9291pj3m5bg\_1ka6odkrf4 | id | Order ID sent by you while creating the payment in the Create Order API. Use this to map the event to your internal systems. |
    | Customer Reference ID | CUST123 | id | Customer identifier that you provided for the transaction for example; your internal customer ID. |
    | Cashfree Reference ID | 4273894975 | id | Unique payment ID generated by Cashfree. Useful for matching the event with payment-specific reports. |
    | Customer Name | Ravi Kumar | text | Customer name sent by you for the transaction. |
    | Customer Phone | 917837674034 | text | Customer phone number sent by you for the transaction. |
    | Customer Email | [ravi@example.com](mailto:ravi@example.com) | text | Customer email address sent by you for the transaction. |
    | Currency | INR | currency | Currency in which the order was created with Cashfree. |
    | Transaction Amount | 3.00 | amount | Amount charged to the customer for the payment. |
    | Transaction Service Charge | 5.10 | amount | Service charges applied on this transaction. |
    | Txn ST/GST | 0.92 | amount | Tax applied on the transaction service charge. |
    | Net Settlement Amount | 3.00 | amount | Amount from this transaction that is eligible for settlement after deducting transaction-level charges and taxes. |
    | Transaction Time | 2025-09-26 15:05:12 | datetime | Date and time when the payment was successfully completed. |
    | Payment Mode | UPI | enum | Mode used for the payment, such as **CARD**, **NETBANKING**, **WALLET**, **UPI**, etc. |
    | Bank Name | HDFC Bank | text | For card and net-banking payments, the issuing bank name. For UPI payments, the UPI channel or app name. |
    | Auth ID | 123456 | id | Authorisation ID for card transactions, when available. Empty for non-card payments. |
    | Card Type (Scheme) | visa | enum | Card network used for the transaction, such as **visa**, **mastercard**, **rupay**, **amex**, **diners**, **maestro**. Applies only to card payments. |
    | Vendor ID 1 | ani\_vendor\_1 | id | ID of the first vendor to whom part of the transaction amount was split using Cashfree Easy Split. |
    | Vendor Amount 1 | 100.00 | amount | Amount allocated to the first vendor under Easy Split. |
    | Vendor ID 2 | – | id | ID of the second vendor for the same transaction, if the amount was split further. |
    | Vendor Amount 2 | – | amount | Amount allocated to the second vendor. |
    | Vendor ID 3 | – | id | ID of the third vendor, if applicable. |
    | Vendor Amount 3 | – | amount | Amount allocated to the third vendor. |
    | Vendor ID 4 | – | id | ID of the fourth vendor, if applicable. |
    | Vendor Amount 4 | – | amount | Amount allocated to the fourth vendor. |
    | Vendor ID 5 | – | id | ID of the fifth vendor, if applicable. |
    | Vendor Amount 5 | – | amount | Amount allocated to the fifth vendor. |
    | Key\_1 | cf\_link\_id | text | Name of the first custom key that you passed in `order_tags` while creating the order. |
    | Value\_1 | 111908804 | text | Value of the first custom key from `order_tags`. |
    | Key\_2 | – | text | Name of the second custom key from `order_tags`, if present. |
    | Value\_2 | – | text | Value of the second custom key from `order_tags`, if present. |
    | Key\_3 | – | text | Name of the third custom key from `order_tags`, if present. |
    | Value\_3 | – | text | Value of the third custom key from `order_tags`, if present. |
    | Order Amount | 3.00 | amount | Order-level amount associated with this payment, as specified when the order was created. |
    | Payment Mode SubType | UPI | enum | More specific classification of the payment mode, if applicable for example, corporate credit card. |
  </Tab>
</Tabs>

## Custom reconciliation fields (`order_tags`)

Use the `order_tags` object on the [Create Order API](/docs/api-reference/payments/latest/orders/create-order) to attach custom string key-value pairs to an order. Each key and value must be between 1 and 255 characters. You can pass up to 10 tags per order.

The first three key-value pairs from `order_tags` surface in the **Transaction details** section of this report as `Key_1`/`Value_1`, `Key_2`/`Value_2`, and `Key_3`/`Value_3`. Additional tags remain on the order but don't appear in the Settlement Recon export.

Use `order_tags` for any business-specific identifiers you need at settlement time—for example branch or outlet ID, campaign code, internal invoice reference, or membership tier. Pass only the fields you need for reconciliation and limit `order_tags` to three keys so they map clearly to `Key_1` through `Key_3`.

<Note>
  The first three keys in your request determine which columns appear in the report. Name keys consistently across orders so finance teams can filter and pivot on `Value_1`, `Value_2`, and `Value_3`.
</Note>

**Example: education and multi-institute fee collection**

```json theme={"dark"}
"order_tags": {
  "institute_code": "INST001",
  "roll_number": "2024001234",
  "division": "A"
}
```

After settlement, filter or pivot the downloaded report on `Value_1`, `Value_2`, or `Value_3` to reconcile collections by institute, student, or division. The same approach applies to other use cases using different key names.

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related Topics</span>
  </p>

  <ul>
    <li><a href="/docs/partners/embedded/reports/reports">Embedded Payments Reports Overview</a></li>
    <li><a href="/docs/partners/embedded/reports/settlement-reports">Settlement Reports</a></li>
    <li><a href="/docs/partners/embedded/reports/transaction-reports">Transaction Reports</a></li>
    <li><a href="/docs/partners/embedded/dashboard">Embedded Payments Dashboard</a></li>
  </ul>
</div>


# Settlement Reports
Source: https://www.cashfree.com/docs/partners/embedded/reports/settlement-reports

View the Cashfree partner Settlement Report to see each settlement ID, status, date, and UTR so you can confirm credits for merchants over any selected period.

Through the settlement reports you can view settlement details like Settlement ID, Status, Date and UTR for the date range selected.

## Generate settlement report

Follow these steps to generate and download a settlement report:

1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
2. Navigate to **Payment Gateway** > **Reports** > **Download Reports**.
3. Click the **Generate New Report** button.
4. Configure your report settings:
   * **Report Type**: Select **Settlements** from the dropdown.
   * **Date Range**: Choose the time period for the report.
   * **File Format**: Select CSV or XLSX.
   * **File Name**: Modify if needed, this is optional.
5. Click **Generate Report**.
6. Once generated, click the **three dots (⋮)** next to your report.
7. Click **Download Report** to save the file.
8. Click **Share Report** to share the report via email or mobile number and set the validity period.
   <img alt="" />

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related Topics</span>
  </p>

  <ul>
    <li><a href="/docs/partners/embedded/reports/reports">Embedded Payments Reports Overview</a></li>
    <li><a href="/docs/partners/embedded/reports/transaction-reports">Transaction Reports</a></li>
    <li><a href="/docs/partners/embedded/reports/settlement-recon-reports">Settlement Recon Reports</a></li>
    <li><a href="/docs/partners/embedded/dashboard">Embedded Payments Dashboard</a></li>
  </ul>
</div>


# Transactions Report
Source: https://www.cashfree.com/docs/partners/embedded/reports/transaction-reports

Use the Cashfree partner Transactions Report to review customer details, payment methods, transaction statuses, settled amounts, and vendor splits per period.

The transaction report gives you details of all the transactions that were made for the period selected. Customer details, transaction amount, payment method, transaction status, settlement amount if the settlement is complete, and more, are available in this report. If the transaction involves goods/services from two or more vendors, the vendor-wise payment split is also available in the transactions report.

## Generate transactions report

Follow these steps to generate and download a transactions report:

1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
2. Navigate to **Payment Gateway** > **Reports** > **Download Reports**.
3. Click the **Generate New Report** button.
4. Configure your report settings:
   * **Report Type**: Select **Transactions** from the dropdown.
   * **Date Range**: Choose the time period for the report.
   * **File Format**: Select CSV or XLSX.
   * **Status**: Select the transaction status you want to view (for example, Success, Failed, Dropped, Incomplete, or All).
   * **File Name**: Modify if needed, this is optional.
5. Click **Generate Report**.
6. Once generated, click the **three dots (⋮)** next to your report.
7. Click **Download Report** to save the file.
8. Click **Share Report** to share the report via email or mobile number and set the validity period.
   <img alt="" />

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related Topics</span>
  </p>

  <ul>
    <li><a href="/docs/partners/embedded/reports/reports">Embedded Payments Reports Overview</a></li>
    <li><a href="/docs/partners/embedded/reports/settlement-reports">Settlement Reports</a></li>
    <li><a href="/docs/partners/embedded/reports/refunds-reports">Refunds Reports</a></li>
    <li><a href="/docs/partners/embedded/dashboard">Embedded Payments Dashboard</a></li>
  </ul>
</div>


# Introduction
Source: https://www.cashfree.com/docs/partners/introduction

Discover Cashfree's Partners and Platforms programs, designed to help SaaS providers, ERPs, and affiliates monetise payment integrations and merchant referrals.

Partners and Platforms by Cashfree is a comprehensive growth ecosystem designed to help businesses expand their reach and revenue through two powerful programs. This solution enables platforms, ERPs, SaaS providers, and partners to offer complete payment solutions while earning commissions through merchant referrals and transaction processing.

Partners and Platforms products are designed to maximise revenue opportunities while providing seamless integration, robust merchant management tools, and comprehensive support that meets business growth requirements.

## Core partnership models

<CardGroup>
  <Card title="Embedded Payments" href="/docs/partners/embedded/overview" icon="layer-group">
    End-to-end payments product for platforms, ERPs, and SaaS to facilitate direct payments between businesses and customers.
  </Card>

  <Card title="Affiliate Program" href="/docs/partners/affiliates/overview" icon="handshake">
    Referral initiative to promote Cashfree products to clients and earn commission on every transaction they complete.
  </Card>
</CardGroup>

Cashfree offers two partnership models for IT solution providers:

1. **Embedded Payments**: Designed for platforms, ERPs, and SaaS providers to facilitate direct payments for clients. You can onboard sub-merchants via the Partner Dashboard or APIs and manage settlements and KYC.
2. **Affiliate Program**: A referral model where you onboard merchants, help with KYC and integration, and earn commissions on their transactions. It features 100% paperless onboarding.

Both models allow you to manage merchants and monitor transactions from a dedicated Partner Dashboard.

To sign up for the Cashfree Partner program, use this [sign-up link](https://partner.cashfree.com/partner-ui/authentication/signup?source-action=Embedded%20Payments\&action=Sign%20Up\&button-id=StartNow_Hero).

## Key benefits

Partners and Platforms provide the following advantages for your business growth:

* **Merchant management**: Add and onboard merchants through the dashboard or APIs, manage their Cashfree accounts, and track their onboarding status and KYC compliance.
* **Commission tracking**: Earn and track commissions on every transaction processed by your onboarded merchants with detailed reporting and invoicing.
* **Dashboard access**: Access dedicated partner dashboards to manage merchants, view transaction reports, and monitor your partnership performance.
* **Flexible partnership models**: Choose between deep platform integration with Embedded Payments or simple referral-based earning through the Affiliate Program.
* **Marketing resources**: Get access to marketing kits, promotional materials, and dedicated partner support to maximise your referral success.

## Getting started

Use the following resources to set up your partnership model:

<CardGroup>
  <Card title="Embedded Payment Gateway Integration" href="/docs/partners/embedded/integration/gateway-integration" icon="diagram-project">
    Learn how to integrate the Embedded Payments gateway into your platform.
  </Card>

  <Card title="Affiliate Program Setup" href="/docs/partners/affiliates/refer-merchants" icon="users">
    Learn how to refer and onboard merchants to start earning commissions.
  </Card>
</CardGroup>


# Bills
Source: https://www.cashfree.com/docs/payments/bbps-billers/dashboard-actions/bills

View and manage BBPS bills on Cashfree from the Merchant Dashboard, including bill upload, customer queries, payment status, and refund handling.

The bills section displays all the bills that were uploaded as csv files. Details mentioned below are available in this section:

* Bill Date - Date the bill was generated.
* Bill Reference ID - Unique identifier of the bill generated by the merchant/biller.
* Bill Number - Number of the bill.
* Customer Name - Name of the customer.
* Due Date - Date on which the bill is due next.
* Bill Period - The frequency of the bill.
* Bill Amount - Amount of the bill.
* Bill Status - Status of the bill.
* Action - Action that can be performed on the bill.

<img alt="" />

# Cancel Bills

Click the Cancel button from the Actions tab to cancel the bill. Note that any payment for this bill won't be accepted post this.

<img alt="" />

# Bulk Bills

You can upload multiple bills at once using the Upload Batch Bill File functionality. Details such as:

* Uploaded At - The time at which the bill was uploaded.
* Uploaded By - The person who uploaded the bill.
* File Name - Name of the file.
* File ID - ID of the file.
* Total Records - Number of records in the file.
* Invalid Records - Number of invalid records.
* Failure Reason - Reason why the upload failed.
* File Status - Upload status.

<img alt="" />

To upload a file,

Go to **Bulk Bills** > **Upload File** > **Choose File** > **Upload**. Ensure that the file you are uploading is as per the format in the sample file.

<img alt="" />

You can download the sample file using the **Download Sample File** option. You can also download the sample file using the **Download** option from the Bulk Bills section.


# Summary Homepage
Source: https://www.cashfree.com/docs/payments/bbps-billers/dashboard-actions/summary

View the BBPS Biller summary homepage on Cashfree for a quick snapshot of bill volumes, transaction value, settlement status, and key biller metrics.

The summary page in BBPS Billers gives you an overview of the following activities:

* Today's Transaction - The count of the total number of transactions that took place today along with the amount.
* Transaction Summary - A graphical representation of sum of total payments that came in for a particular day over the time range that is specified in the filter above. Hover over the graph to view the transaction amount. Clicking on the arrow mark will redirect you to the Transactions page.
* Average Transaction Value - A graphical representation of day wise average transaction value over the time range that is specified in the filter above. Clicking on the arrow mark will redirect you to the Transactions page.
* Transaction Status - Pie Chart representation which demonstrates the split of successful, pending and failed transactions. Hover your mouse over a particular region to view the success/failed/pending status. Clicking on the arrow mark will redirect you to the Transactions page.

<img alt="" />


# Transaction
Source: https://www.cashfree.com/docs/payments/bbps-billers/dashboard-actions/transaction

View BBPS Biller transactions on Cashfree from the Merchant Dashboard, filter by customer, status, or date, and reconcile bills against bank settlements.

The Transaction page displays all the transactions made by your customers based on the filter you have applied. Details that are mentioned below are available in the transactions section such as:

* Date and Time of the transaction
* BBPS Transaction ID - A unique identifier of the payment received. This is generated by NPCI.
* Bill Reference ID - A unique identifier of the bill. This is generated by the merchant/biller.
* Amount Received - The amount received from your customer.
* Bill Payment Status - Status of the bill payment.

You can apply search on the following parameters: BBPS Transaction ID and Biller Reference ID

You can apply filter on Bill Payment Status.

<img alt="" />


# BBPS Billers - FAQs
Source: https://www.cashfree.com/docs/payments/bbps-billers/faqs

Browse BBPS Billers FAQs covering onboarding, listing on BBPS, settlement timelines, supported categories, reports, and common biller integration questions.

<AccordionGroup>
  <Accordion title="What is BBPS">
    Bharat Bill Pay System (BBPS) is an integrated online ecosystem that connects 35 lakhs offline collection centres and 150+ digital payment channels including major UPI apps for all kinds of bill payments. A single integration, often facilitated by payment aggregators like Cashfree gives you access to this huge network which enables you to provide multiple payment options for your customers, both online and offline.
  </Accordion>

  <Accordion title="Who is a biller?">
    The billers are entities that generate the recurring bills to be paid. A few common examples are:

    * Electricity boards with the electricity bills
    * NBFCs with loan repayment
    * Insurance companies with premium payments
    * Housing facilities with rents
    * Clubs and associations with membership charges
    * Broadband and cable TVs with usage bills
  </Accordion>

  <Accordion title="How can I collect bill payments from UPI apps like Paytm, PhonePe, Google Pay etc.?">
    Cashfree’s Biller solution for BBPS helps you collect bills from all major UPI apps like Paytm, PhonePe, Google Pay, and more with a single integration that connects you to the BBPS network. You can start the integration process with the following steps:

    1. [Express your interest using the BBPS onboarding form](https://form.typeform.com/to/fLAObAhk?typeform-source=www.cashfree.com).
    2. Our BBPS expert will reach out to you at the earliest to take the next steps on onboarding agreement and provide you complete integration support.
    3. Post integration, the Cashfree team supports you to do end-to-end testing and enables you to start collecting bill payments on the BBPS network within 3 weeks.
  </Accordion>

  <Accordion title="Is there any transaction limit for payments through BBPS?">
    The transaction limits are dependent on the mode of payment. For example, if the customer is making the payment through an UPI app, the UPI transaction limits would be applicable for the BBPS transaction.
  </Accordion>

  <Accordion title="What is the settlement cycle for BBPS?">
    BBPS works on a T+1\* settlement cycle. The billers get fast and guaranteed settlements for transactions through BBPS within 24 hours after the payment is made.

    <Info>
      T+x\*: Settlement cycle is subject to bank approval and can vary based on transaction type, business category/model, risk parameters, and other factors.
    </Info>
  </Accordion>

  <Accordion title="How long does it take to be live on the BBPS network as a biller?">
    With Cashfree’s Biller solution for BBPS, you can integrate and go live as a biller in less than 3 weeks. To start integrating, reach out to our BBPS expert here
  </Accordion>

  <Accordion title="What are the charges for using BBPS to collect your bill payments?">
    The charges per transaction vary from category to category. To get the best pricing for your business category, please [reach out to us using the BBPS onboarding form](https://form.typeform.com/to/fLAObAhk?typeform-source=www.cashfree.com).
  </Accordion>
</AccordionGroup>


# Getting Onboarded and Listed on BBPS
Source: https://www.cashfree.com/docs/payments/bbps-billers/onboarding

Get your business onboarded as a BBPS Biller with Cashfree, complete category mapping, share required documents, and go live on the Bharat BillPay network.

There are three steps involved to start collecting bill payments using BBPS Biller -

**Step 1**: Fill in the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) to get in touch with our team and finalise the commercials.

**Step 2** -  Basis your preference, you can integrate BBPS Billers Solution via APIs or use our no-code solution to start sooner.

**Step 3**: Your onboarding on the BBPS platform will be taken care by Cashfree.

**Step 4**: Once a biller is live on the BBPS platform as a biller, following timelines are usual for you to be visible to your customers.

* BHIM (Immediately)
* Google Pay (Within 1 week)
* PhonePe and other UPI platforms as well as offline platforms (2 weeks)

**Step 5** Now your customers can use any application to view their latest bill and you can use Cashfree Dashboard to see realtime reporting of transactions coming through BBPS.


# Overview
Source: https://www.cashfree.com/docs/payments/bbps-billers/overview

Use Cashfree BBPS-Biller to collect recurring bills across 150+ digital channels and 35 lakh offline centres through the Bharat Bill Payment System network.

The Cashfree BBPS-Biller solution enables billers organisations that collect recurring bills from customers to reach payers across digital and offline channels using the Bharat Bill Payment System infrastructure.

## Understanding the Bharat Bill Payment System (BBPS)

Bharat Bill Payment System (BBPS) is an integrated online ecosystem that provides a unified platform for bill payments across India.

It connects over 150 digital payment channels, including major UPI apps like Google Pay, PhonePe, Paytm, and Amazon Pay, along with phone banking applications and net banking websites. Additionally, it integrates with over 35 lakh offline collection centres. A single integration through Cashfree provides access to these channels and can help reduce operational costs. These platforms support multiple payment modes, including UPI, debit and credit cards, net banking, and cash.

## Benefits for billers

Use the BBPS platform to automate your collection workflows and increase operational efficiency. The solution offers the following benefits:

* **Expansive network**: Access over 150 digital channels and more than 35 lakh physical outlets for efficient collection.
* **Modernise collections**: Effortlessly update your collection process with our digital-first solutions.
* **Wider presence**: Expand your reach across all BBPS enabled collection channels seamlessly.
* **Faster settlements**: Accelerate dues collection with multiple daily settlement cycles, ensuring swifter liquidity.
* **Quick onboarding**: Go live in less than three weeks with our streamlined integration process.
* **Multiple payment modes**: Offer customers more than 12 payment modes for enhanced convenience.
* **Regulatory compliance**: Follows RBI regulatory standards, ensuring full compliance at every step.

## Use cases

BBPS-Biller supports various industries by providing tailored solutions for the following billing and payment collection requirements:

* **Utilities**: Efficient payment solutions for electricity and water bills catered specifically to distribution companies (DISCOMs), water supply boards, and municipal corporations.
* **Loan repayments**: Streamline partial and complete loan repayments for non-banking financial companies (NBFCs), loan servicing platforms (LSPs), and other lending institutions.
* **Broadband and DTH**: Tailored solutions for managing broadband, cable, and DTH bills, including advance payments for local cable operators (LCOs) and multiple system operators (MSOs).
* **Telecommunications**: Simplified solutions for seamless recharges of landline and mobile postpaid services for network operators and service providers.
* **B2B invoices**: Streamline the payment collection process for B2B invoice payments.
* **Insurance**: Comprehensive solutions for insurance providers and aggregators to facilitate hassle-free premium payments online and offline.
* **Gas and LPG**: Specialised solutions for city gas distribution networks and LPG providers.
* **Rental services**: Efficient payment management for PGs, co-living spaces, hostels, and other rental service providers.

<Accordion title="Supported BBPS categories (as of November 2024)">
  The BBPS ecosystem supports various business categories. Any biller operating within the following sectors can integrate with BBPS:

  **Utilities**: Enable utility providers including distribution companies (DISCOMs), water boards, and municipal corporations to collect payments for:

  * Electricity, water, and gas
  * LPG and prepaid meter recharges
  * Municipal services and taxes

  **Finance and insurance**: Enable lenders, insurance providers, and asset managers to collect payments for:

  * Credit card and loan repayments
  * Insurance premiums and National Pension System (NPS) contributions
  * Recurring deposits

  **Telecom and media**: Enable network operators, broadband providers, and broadcasters to collect payments for:

  * Mobile recharges (postpaid and prepaid)
  * Broadband postpaid and cable TV
  * DTH services

  **Transport**: Enable highway authorities and transport operators to collect toll and fare payments through:

  * FASTag recharges
  * NCMC recharges

  **Education and living**: Enable educational institutions, co-living operators, and residential societies to collect fees and charges for:

  * Education fees
  * Housing society maintenance and rental payments

  **Collections and others**: Support diverse collection use cases including:

  * Agent collections and B2B payments
  * Donations and subscriptions
</Accordion>

<Note>
  If your business category or use case does not fit into the categories listed above, please [reach out to us](https://www.cashfree.com/contact-sales/) to discuss onboarding on the BBPS platform.
</Note>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/other-apis/bbps/overview">BBPS API Overview</a></li>
    <li><a href="/docs/payments/bbps-billers/faqs">BBPS Biller FAQs</a></li>
  </ul>
</div>


# Reports
Source: https://www.cashfree.com/docs/payments/bbps-billers/reports

Download BBPS Biller reports from the Cashfree dashboard to reconcile bills, transactions, refunds, and settlements across the Bharat BillPay biller network.

There are various reports that can be generated from BBPS Billers. These reports help you to analyse your business transactions, and much more. You can view these reports day-wise, week-wise or for a custom date range. You also have the option to download the reports.

There are two reports you can generate from the BBPS Billers Report Dashboard : Transactions Report

* Bill Status Report

The Transactions report has details such as Transaction ID, Status, Issuer Name and Transaction Date for the date range selected.

Through the Bill Status report you can view the details of the uploaded bills through No-Code like bill amount, paid amount, payment date, status, etc.

To generate a new report,

1. Go to **BBPS Billers Dashboard** > **Reports** > **Generate Report**.

<img alt="" />

2. Select the **Report Type**, **Date Range**, and provide a **File Name**. Once done, click **Generate Report**.

<img alt="" />

3. You can also download your report. Click the ellipsis icon on the report you want to download and select **Download Report**.

<img alt="" />


# Abandoned Checkout
Source: https://www.cashfree.com/docs/payments/checkout/abandoned-checkout/abandoned-checkout

Capture Cashfree abandoned checkout data in real time and forward it to your WhatsApp business service provider to retarget drop-off shoppers and recover sales.

Cashfree Abandoned Checkout helps merchants recover lost sales by capturing abandoned checkout data and sharing it with Business Service Providers (BSPs) in real-time. This allows merchants to retarget customers who leave the checkout process without completing their purchase.

## Purpose

Shopify no longer supports direct updates of abandoned checkout data from third-party providers. As a result, merchants can’t automatically track where customers drop off. Cashfree Abandoned Checkout addresses this by ensuring merchants receive abandoned cart data instantly, helping them re-engage customers and increase conversions.

## Shopify abandoned cart visibility

Shopify no longer supports third-party providers pushing abandoned checkout data directly, which is why Cashfree's Abandoned Checkout feature exists as a workaround. Cashfree One Click Checkout (OCC) creates abandoned cart records in both the Cashfree system and Shopify, but Shopify only displays a record after the customer provides at least an email address or phone number during checkout, and only if the store does not have **Login Required** enabled (which blocks guest checkout data capture).

If a record does not appear in Shopify Admin, it is still visible in the Merchant Dashboard, under the OCC section. Since Shopify's own abandoned-cart API is deprecated for third parties, rely on Cashfree's `ABANDONED_CHECKOUT` webhook (see [Abandoned checkout webhook](/docs/payments/checkout/abandoned-checkout/webhook)) as the reliable source of this data, including for passing it to retargeting or third-party services.

## Data flow and captured information

Cashfree uses real-time webhooks to send abandoned checkout data directly to BSPs. The captured data includes:

* Customer details: Phone number and email, even if partially filled.
* Address details: Any entered address, including partial entries (for example, ZIP code).
* Cart details: Complete cart contents.
* OCC checkout URL: A dynamic link that lets customers resume checkout.
* Marketing opt-in status: Indicates whether the customer agreed to receive marketing communications.

## Benefits

* Immediate retargeting: Reach high-intent customers quickly through BSP channels, such as WhatsApp.
* No data loss: Capture customer details even if they abandon the process early.
* Automated workflow: After setup, no manual intervention is required.
* Flexible checkout options: Supports both Shopify checkout links and Cashfree OCC checkout links.
* Secure data handling: Each merchant receives a unique token to ensure secure and authenticated data sharing with BSPs.


# Ecom360 Webhook
Source: https://www.cashfree.com/docs/payments/checkout/abandoned-checkout/ecom360

Configure the Cashfree Ecom360 webhook to push abandoned checkout payloads to your WhatsApp service provider for automated retargeting on Shopify and OCC.

Configure Ecom360 webhook notifications to send data directly to your WhatsApp Business Service Provider (BSP). Once set up, the webhook sends structured JSON payloads to the BSP’s callback URL whenever a customer abandons a checkout.

The payload includes customer contact details, cart contents, a dynamic link to resume checkout, and other relevant metadata. This enables BSPs to automatically trigger WhatsApp messages for timely retargeting.

This setup supports both Shopify and Cashfree OCC checkout flows. After configuration, the process runs automatically with no manual input required.

## Setting up webhook notifications for WhatsApp provider

Follow these steps to subscribe to the `abandonedCheckout` webhook topic:

1. Get the callback URL where you want to receive event notifications from the webhook consumer (e.g., business service providers such as Spur, LimeChat, Gupshup, Whitespeed, or BiteSpeed).

2. Generate the webhook key using the below steps:

   * Go to the [Ecom Dashboard](https://brands.zecpe.com/login).

   * Enter the callback URL.

   * Generate the webhook key.

3. Share the generated webhook key to the webhook consumer.

4. Share the [integration steps](/docs/payments/checkout/abandoned-checkout/ecom360#integration-steps) with the WhatsApp provider.

### Integration steps

The **Ecom 360 Webhook** monitors key events, such as abandoned checkouts, in real time. When a merchants subscribes to this webhook, it receives structured JSON payloads containing customer and order details. This allows businesses to automate actions such as sending reminders or promotional offers.

#### Subscribing to a webhook topic

To subscribe to the `abandonedCheckout` topic, provide the following details:

* **Topic name**: `abandonedCheckout`
* **Callback URL**: The URL where you want to receive event notifications.
* **Webhook version**: `v1`
* **Secret key**: Cashfree provides this key to verify the authenticity of received events.

After subscribing, the webhook sends real-time notifications to the specified callback URL when an event occurs.

#### Sample webhook event payload

When the `abandonedCheckout` event triggers, the webhook sends the following payload:

```json theme={"dark"}
{
  "event": "ABANDONED_CHECKOUT",
  "data": {
    "cart_id": "cart_123456",
    "store_url": "my-store.myshopify.com",
    "platform": "SHOPIFY",
    "cart_token": "abc123token",
    "email": "customer@example.com",
    "phone": "+1234567890",
    "abandoned_checkout_url": "https://my-store.myshopify.com/checkouts/abc123token",
    "original_total_price": 10000,
    "total_price": 8500,
    "total_discount": 1500,
    "utm_parameters": {
      "fbclid": "fbclid_123",
      "utm_campaign": "summer_sale"
    },
    "line_items": [
      {
        "product_id": "prod_001",
        "variant_id": "var_001",
        "sku": "SKU001",
        "price": 5000,
        "quantity": 2,
        "gram": 200,
        "title": "T-Shirt - Blue"
      },
      {
        "product_id": "prod_002",
        "variant_id": "var_002",
        "sku": "SKU002",
        "price": 3000,
        "quantity": 1,
        "gram": 150,
        "title": "Cap - Black"
      }
    ],
    "promotions": [
      {
        "code": "WELCOME10",
        "value": 1000
      },
      {
        "code": "SUMMER2025",
        "value": 500
      }
    ],
    "customer": {
      "email": "customer@example.com",
      "first_name": "John",
      "last_name": "Doe",
      "shipping_address": {
        "first_name": "John",
        "last_name": "Doe",
        "address1": "123 Elm Street",
        "address2": "Apt 4B",
        "city": "New York",
        "province": "NY",
        "country": "US",
        "zip": "10001",
        "phone": "+1234567890",
        "name": "John Doe",
        "province_code": "NY",
        "country_code": "US"
      }
    }
  }
}
```

#### Webhook headers

Each webhook request includes the following headers to help businesses identify and validate the request:

| **Header key** | **Description** |
| - | - |
| `x-store-url` | Specifies the store URL associated with the event |
| `x-webhook-topic` | Indicates the subscribed topic |
| `x-webhook-version` | Displays the webhook version |
| `x-webhook-signature` | Provides the HMAC signature to verify authenticity |
| `x-request-id` | Assigns a unique identifier for the request |
| `User-Agent` | Identifies the request as `Ecom360-v1` |
| `Content-Type` | Defines the payload format (`application/json`) |

<Note>
  **Note**: For assistance with setup or further inquiries, contact your Cashfree Account Manager or fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1)
</Note>


# Abandoned Checkout Webhook
Source: https://www.cashfree.com/docs/payments/checkout/abandoned-checkout/webhook

Subscribe BSP endpoints to the Cashfree One Click Checkout abandoned cart webhook to receive real-time customer, address, and cart payloads for retargeting.

Cashfree One Click Checkout (OCC) webhooks notify Communications and WhatsApp Business Service Providers (BSPs) in real time when customers create abandoned carts. BSPs can add their webhook URLs to receive these events.

## How Cashfree defines an abandoned checkout

OCC checkout progresses through four steps. Cashfree uses this progression to decide when a checkout counts as abandoned, and which customer details it can include in the webhook payload.

1. **Checkout initiated**: The customer starts the checkout flow.
2. **Login completed**: Cashfree captures the customer's phone number.
3. **Address submitted**: Cashfree captures the customer's phone number, address, and email address.
4. **Order placed**: The customer completes the order. Cashfree doesn't treat this checkout as abandoned.

Cashfree marks a checkout as abandoned when a customer drops off anywhere between step 1 and step 4 and remains inactive for 30 minutes.

When a customer drops off at any point during checkout, Cashfree OCC creates an abandoned cart record in both Shopify and the Cashfree system. The record always includes the cart contents and store URL, and adds customer details as the shopper progresses:

* **Dropped after step 1 (not logged in)**: cart and store details only; no phone number or customer block.
* **Dropped after step 2 (login completed)**: phone number is included.
* **Dropped after step 3 (address submitted)**: phone number plus the full `customer` block (name, email, shipping address).

Merchants can use this data to retarget customers. See [Sample webhook event payload](#sample-webhook-event-payload) for examples of each variant.

Abandoned cart records can include the following fields:

| Field | Description | Included |
| - | - | - |
| **Store URL** (`storeUrl`) | Identifies the Shopify store. | Always |
| **Cart details** (`lineItems`) | The items in the cart. | Always |
| **UTM parameters** (`utmParameters`) | Marketing parameters captured when the customer initiated checkout. | Always |
| **Abandoned checkout URL** (`abandonedCheckoutUrl`) | Link to the merchant's Shopify store with the OCC page preloaded and previous information pre-filled. Use this URL for retargeting. | Always |
| **Total price** (`totalPrice`) | Final payable amount for the customer. | Always |
| **Phone number** (`phone`) | Customer's phone number. | Only if the customer completed login (dropped off at step 2 or later) |
| **Customer details** (`customer`) | Name, email address, and shipping address. | Only if the customer submitted the complete address (dropped off at step 3) |
| **Promotions** (`promotions`) | List of discounts, if the customer applied any. | If the customer applied a discount |

Cashfree OCC triggers webhooks only for abandoned carts, not for completed checkouts. Once a BSP adds a webhook URL, it begins receiving events. To enable this, merchants must ask the BSP to share the webhook URL where Cashfree should send data.

<Note>
  Cashfree doesn't send abandoned checkouts to Shopify if a login is required in the native checkout settings.
</Note>

## Adding a webhook endpoint

To start receiving abandoned cart webhooks from Cashfree One Click Checkout (OCC), follow these steps.

<Steps>
  <Step title="Log in to the Merchant Dashboard">
    Log in to the **[Merchant Dashboard](https://merchant.cashfree.com/auth/login)**.
  </Step>

  <Step title="Open the webhooks configuration page">
    Go to **Payment Gateway > Developers > Webhooks > Configuration > Payment Gateway** tab.
  </Step>

  <Step title="Add a webhook endpoint">
    On the **Webhooks** page, select **Add Webhook Endpoints**.
  </Step>

  <Step title="Enter the endpoint details">
    In the **Endpoint Details** section:

    * Enter the **endpoint URL** where you want to receive webhook data.
    * Select **Test** to verify the URL.
    * From the drop-down menu, select **Webhook Version: 2025-01-01**.
    * Select **Continue**.

    <Frame>
      <img alt="Endpoint Details section showing the endpoint URL field, Test button, and webhook version drop-down" />
    </Frame>
  </Step>

  <Step title="Add a retry policy and select events">
    In the **Add Policy** section:

    * Choose a **retry policy**. The default policy includes **3 retries**.
    * Select the relevant **events** to subscribe to.
    * Optionally, add another **retry policy** if needed.
    * Select **Continue**.

    <Frame>
      <img alt="Add Policy section showing retry policy options and selected events, including abandoned checkout" />
    </Frame>
  </Step>

  <Step title="Review and save">
    In the **Summary** section:

    * Review the configuration.
    * Select **Update Secret Key**, then select **Update** in the confirmation pop-up. This generates the custom secret key that Cashfree uses to sign this webhook's payload. This key is separate from your Cashfree PG secret key.
    * Select **Save**.

    <Frame>
      <img alt="Summary section showing the configuration review and Update Secret Key button" />
    </Frame>
  </Step>
</Steps>

For an optional recap, watch the following video walkthrough of this process.

<iframe title="YouTube video player" />

## Sample webhook event payload

The payload varies depending on the step where the customer dropped off. Select the tab that matches your scenario.

<Note>
  Unlike other Cashfree webhooks, which sign payloads with your Cashfree PG secret key, the abandoned checkout webhook uses a separate custom secret key. Generate or rotate this key from the **Summary** section when you [add the webhook endpoint](#adding-a-webhook-endpoint) by selecting **Update Secret Key**. Use this custom secret key, not your PG secret key, together with the payload to verify the `x-webhook-signature` header.
</Note>

<Tabs>
  <Tab title="Not logged in">
    Customer dropped off before logging in (after step 1). The payload omits `phone` and `customer` because Cashfree hasn't captured the shopper's identity yet.

    ```json theme={"dark"}
        {
          "data": {
            "cart_id": "32868848",
            "store_url": "gcf-test-101.myshopify.com",
            "cart_token": "hWN6DkSJe6sGaGkHft0es77c?key=61ff137efca84c5de49a6b3304be4d6c",
            "abandoned_checkout_url": "https://api.cashfree.com/pg/view/sessions/checkout/web/N0o4OEpDiqSdBVY0KlYt",
            "original_total_price": 201,
            "total_price": 1,
            "total_discount": 0,
            "utm_parameters": {
              "fbclid": "",
              "utm_campaign": "",
              "utm_medium": "",
              "utm_content": "",
              "utm_source": ""
            },
            "line_items": [
              {
                "reference": "9652835221780",
                "variant_id": "49734122930452",
                "sku_name": "",
                "name": "Goku great shirt",
                "description": "",
                "details_url": "",
                "image_url": "https://cdn.shopify.com/s/files/1/0000/0001/0002/files/goku-great-shirt.webp",
                "image_url_cashfree_s3": "https://cashfree-checkoutcartimages-prod.cashfree.com/50279842/checkoutcartitem1",
                "original_unit_price": 201,
                "discounted_unit_price": 201,
                "currency": "INR",
                "quantity": 1,
                "discounts": []
              }
            ],
            "promotions": [
              {
                "code": "SHOE_AUTOMATIC",
                "value": 200
              }
            ]
          },
          "event_time": "2025-12-09T12:00:00+05:30",
          "type": "ABANDONED_CHECKOUT"
        }
    ```
  </Tab>

  <Tab title="Address submitted">
    Customer logged in and submitted a complete address before dropping off (after step 3).

    ```json theme={"dark"}
        {
          "data": {
            "cart_id": "32868848",
            "store_url": "merchant-demo-store.myshopify.com",
            "cart_token": "hWN6DkSJe6sGaGkHft0es77c?key=61ff137efca84c5de49a6b3304be4d6c",
            "phone": "+91 98765 43210",
            "abandoned_checkout_url": "https://api.cashfree.com/pg/view/sessions/checkout/web/N0o4OEpDiqSdBVY0KlYt",
            "original_total_price": 1200,
            "total_price": 1000,
            "total_discount": 200,
            "utm_parameters": {
              "fbclid": "",
              "utm_campaign": "",
              "utm_medium": "",
              "utm_content": "",
              "utm_source": ""
            },
            "line_items": [
              {
                "reference": "9652835221780",
                "variant_id": "49734122930452",
                "sku_name": "",
                "name": "Running Shoes - Blue",
                "description": "",
                "details_url": "",
                "image_url": "https://cdn.shopify.com/s/files/1/0000/0001/0002/files/running-shoes-blue.webp",
                "image_url_cashfree_s3": "https://cashfree-checkoutcartimages-prod.cashfree.com/1234567890/checkoutcartitem1",
                "original_unit_price": 1200,
                "discounted_unit_price": 1000,
                "currency": "INR",
                "quantity": 1,
                "discounts": []
              }
            ],
            "promotions": [
              {
                "code": "SHOE_AUTOMATIC",
                "value": 200
              }
            ],
            "customer": {
              "email": "aditi.sharma@example.com",
              "first_name": "Aditi",
              "last_name": "Sharma",
              "shipping_address": {
                "customer_name": "Aditi Sharma",
                "address1": "221B, MG Road",
                "address2": "",
                "city": "Bengaluru",
                "province": "Karnataka",
                "country": "India",
                "zip": "560001",
                "email": "aditi.sharma@example.com",
                "phone": "+91 98765 43210",
                "province_code": "KA",
                "country_code": "IN"
              }
            }
          },
          "event_time": "2025-12-09T12:00:00+05:30",
          "type": "ABANDONED_CHECKOUT"
        }
    ```
  </Tab>

  <Tab title="Login completed">
    Customer logged in but dropped off before submitting an address (after step 2).

    ```json theme={"dark"}
        {
          "data": {
            "cart_id": "32868848",
            "store_url": "merchant-demo-store.myshopify.com",
            "cart_token": "hWN6DkSJe6sGaGkHft0es77c?key=61ff137efca84c5de49a6b3304be4d6c",
            "phone": "+91 98765 43210",
            "abandoned_checkout_url": "https://api.cashfree.com/pg/view/sessions/checkout/web/N0o4OEpDiqSdBVY0KlYt",
            "original_total_price": 1200,
            "total_price": 1000,
            "total_discount": 200,
            "utm_parameters": {
              "fbclid": "",
              "utm_campaign": "",
              "utm_medium": "",
              "utm_content": "",
              "utm_source": ""
            },
            "line_items": [
              {
                "reference": "9652835221780",
                "variant_id": "49734122930452",
                "sku_name": "",
                "name": "Running Shoes - Blue",
                "description": "",
                "details_url": "",
                "image_url": "https://cdn.shopify.com/s/files/1/0000/0001/0002/files/running-shoes-blue.webp",
                "image_url_cashfree_s3": "https://cashfree-checkoutcartimages-prod.cashfree.com/1234567890/checkoutcartitem1",
                "original_unit_price": 1200,
                "discounted_unit_price": 1000,
                "currency": "INR",
                "quantity": 1,
                "discounts": []
              }
            ],
            "promotions": [
              {
                "code": "SHOE_AUTOMATIC",
                "value": 200
              }
            ]
          },
          "event_time": "2025-12-09T12:00:00+05:30",
          "type": "ABANDONED_CHECKOUT"
        }
    ```
  </Tab>
</Tabs>

## Webhook headers

Each webhook request contains the following headers for validation and tracing.

| **Header key** | **Description** |
| - | - |
| `x-datadog-sampling-priority` | Indicates trace sampling priority. A value of 1 means the trace is retained. |
| `x-datadog-parent-id` | ID of the parent span in a distributed trace. |
| `x-datadog-trace-id` | Unique ID for the trace across services. |
| `content-length` | Size of the request body in bytes. |
| `x-webhook-attempt` | Number of delivery attempts. |
| `content-type` | MIME type of the request body (`application/json`). |
| `x-webhook-signature` | Cryptographic signature for payload integrity. |
| `x-idempotency-key` | Unique key to prevent duplicate processing. |
| `x-webhook-timestamp` | Unix timestamp (in milliseconds) indicating when the webhook was sent. |
| `x-webhook-version` | Version of the webhook payload (for example, `2025-01-01`). |
| `accept` | Acceptable media types in the response (`*/*`). |
| `host` | Receiving server domain (for example, `webhook.site`). |
| `user-agent` | Client software sending the request (for example, `ReactorNetty/1.1.11`). |


# Customer Login and Address-Prefilling
Source: https://www.cashfree.com/docs/payments/checkout/address-prefill

Reduce 30% checkout drop-offs with Cashfree One Click Checkout customer login and address prefilling, which speed up returning shopper experiences.

E-commerce businesses typically experience a 30% drop-off rate during the login and address collection steps. Customer Login and Address Prefilling on checkout helps address this issue.

Cashfree helps e-commerce brands in the following ways:

* Reduces cart abandonment at the login and address stages.
* Streamlines the conversion funnel for a seamless purchase experience.
* Encourages customers to complete their purchases with minimal friction.

## Customer login

The Customer Login feature simplifies the checkout process for repeat customers and increases conversion rates.

* Cashfree Customer Login enables repeat customers to bypass the login process, taking them directly to the address stage. Returning customers on **Cashfree’s network of over 2,500 brands** don't need to log in again; they proceed directly to the address step.
* As a result, Cashfree automatically logs in 50% of customers in its network, leading to conversion rates twice as high as those achieved with traditional login methods.

## Address prefilling

The Address Prefilling feature helps customers complete their purchases by reducing friction at the address entry stage.

* The address stage often results in a 22% cart drop-off rate due to lengthy forms. Cashfree Address Prefilling reduces this friction by automatically filling in address details, thereby increasing order completion rates.
* Cashfree Address Prefilling reduces cart abandonment by auto filling addresses for returning customers, ensuring a quick and accurate checkout using data from over **100 million shoppers**.
* For new customers, entering a postcode fills in 40% of the address fields (city and county), requiring only essential details such as name, address line, and email. This approach speeds up checkout and reduces drop-offs.

## How it works

Follow these steps to use Customer Login and Address Prefilling:

1. The customer logs into the checkout using their phone number. If the customer has already logged in with any merchant on the Cashfree network, they skip this step.
2. Cashfree fetches the address associated with this phone number. If the address isn't available, the customer can enter their address details and proceed.

<Note>
  This feature is available as part of **One Click Checkout**. To activate this product, go to the **[Merchant Dashboard](https://merchant.cashfree.com/auth/login)** and go to **PG Products > [One Click Checkout](https://merchant.cashfree.com/merchants/pg/one-click-checkout)**.

  * **Shopify Integration** for One Click Checkout
  * **Custom Integration** for One Click Checkout
</Note>


# Payment Analytics
Source: https://www.cashfree.com/docs/payments/checkout/after/analytics

Use Cashfree Intelligence to optimise checkout, find conversion drop-offs, reduce costs, and surface patterns that grow online sales for your store.

Payments Intelligence helps you optimise payments, boost sales, and reduce costs. Discover patterns, fix issues, and enhance customer experience to drive growth.

<Note>
  You can access analytics in the **[Merchant Dashboard](https://merchant.cashfree.com/auth/login)** and go to **Payment Gateway > Summary > Analytics**.
</Note>

## Payment analytics

Payment analytics reveals buying patterns and key customer segments.

* **Customer journey insights**\
  Track repeat and new customers’ buying behaviour to improve targeting.

  <img alt="" />

* **Identify high-value customers**\
  Find loyal buyers and potential repeat customers to boost engagement.

  <img alt="" />

## Success rate analytics

Success rate shows the percentage of successful transactions. Tracking success rate helps you spot payment issues and create a smoother checkout.

### Transaction analytics

* **Monitor success rates by payment method**\
  See which payment methods work best, for example UPI and card, and identify issues.

  <img alt="" />

* **Detailed gateway and method insights**\
  Check success rate by each gateway to understand and optimise your payment options.

  <img alt="" />

## Volume analytics

Volume analytics shows how much each payment method contributes to total sales.

* **View payment volume across methods**\
  Understand which payment types your customers prefer, for example, UPI or wallet.

  <img alt="" />

* **Customer payment preferences**\
  Use these insights to adjust payment options based on customer trends.

  <img alt="" />

## Regional insights

Regional insights provide visibility into where your customers are transacting from. The dashboard displays the successful transaction volumes segmented by states and regions, helping you track business performance geographically.

<Note>
  Locations are derived from IP addresses. These are estimates and may not always reflect the actual origin for server-to-server traffic.
</Note>

* **Trend visualisation**: Track successful transactions over time across selected regions.

* **State and district level breakdown**: Within each state, you can drill down to view transaction volumes at the district or regional level.

* **Comparison view**: Select multiple states to compare transaction performance side by side.

  <img alt="" />

**Example**\
In the example shown above, Maharashtra contributed the highest transaction volume with 13,741 successful transactions. Delhi, Gujarat, Uttar Pradesh, and West Bengal each recorded five successful transactions, while Karnataka recorded four successful transactions during the same period.

Use these insights to identify high-performing regions, optimise marketing spend, and understand customer behaviour across geographies.

<snippet>snippets/related-topics-loader.mdx</snippet>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/payments/manage/reports">Payment Reports</a></li>
    <li><a href="/docs/payments/manage/monitor">Payment Monitoring</a></li>
  </ul>
</div>


# Customer Hub
Source: https://www.cashfree.com/docs/payments/checkout/after/customer-hub

Give shoppers a single Customer Hub portal to manage Cashfree payments, saved cards, refunds, and order history without contacting your support team.

The **Customer Hub** is a simple portal where customers can handle everything related to their Cashfree in one place. They can check payments, saved cards, refunds, and more.

<Note>**Try it out here**: [Cashfree Customer Hub](https://www.cashfree.com/customers)</Note>

## Why merchants should use Customer Hub

The Customer Hub helps merchants by making things easier for their customers. Here’s why it’s great for merchants:

* **Fewer Support Calls**\
  Since customers can find answers on their own (like checking payments or refunds), they don’t need to contact support as much. This means merchants get fewer calls and can focus on other things.

* **Better Customer Trust**\
  When customers can see their information and manage it easily, they feel more in control. This builds trust and makes them more likely to come back.

* **Accurate Data**\
  Customers can update their own details, like billing addresses or payment methods, so merchants have the latest info without needing to do it themselves.

* **Simple Compliance**\
  With the Customer Hub, customers have access to their own data, helping merchants stay compliant with data privacy rules.

* **Clear, Real-Time Updates**\
  Customers can check the Hub anytime for real-time updates on payments and refunds, so they’re always in the loop. This builds transparency and trust.

## Manage saved payment methods

To manage saved payment methods in Customer Hub:

1. Log in to the [Customer Hub](https://www.cashfree.com/customers/) using your mobile number.

2. Under Manage, select **Payment Methods**.

3. Select the payment method you want to manage: **Cards** or **UPI**.

4. Add, edit, or delete the payment method as needed.


# External Analytics
Source: https://www.cashfree.com/docs/payments/checkout/after/external-analytics

Send Cashfree Checkout, Payment Links, and Payment Forms events to Google Analytics and other platforms to track behaviour and optimise conversions.

## Supported platforms

Cashfree supports integration with the following analytics platforms:

* [Google Analytics 4 (GA4)](/docs/payments/checkout/after/external-analytics#google-analytics-4-ga4)
* [Meta Pixel](/docs/payments/checkout/after/external-analytics#meta-pixel)
* [Mixpanel](/docs/payments/checkout/after/external-analytics#mixpanel)
* [Google Ads (via GA4 linking) ](/docs/payments/checkout/after/external-analytics#ga4-google-ads)
* [Meta Ads (via Meta Pixel linking) ](/docs/payments/checkout/after/external-analytics#meta-pixel-meta-ads)

<Note>
  If your analytics provider is not listed, contact [Cashfree support](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1).
</Note>

## Configure external analytics

To configure external analytics integration, follow these steps:

1. Log in to the **[Merchant Dashboard](https://merchant.cashfree.com/auth/login)**.
2. In the **Payment Gateway** section, select **Access**.
3. In the left navigation pane, select **Developers > Checkout Analytics**.
4. Under the **Actions** column, select the **Edit** icon.
5. In the **External Analytics Configuration** modal, configure the integration as described in the setup sections below.
6. Select **Save** to apply your changes.

<Frame>
  <img />
</Frame>

## Event categories

Events are organised into different categories based on where they are triggered and what they track. You can track customer interactions in your integration by using the following event categories:

* Checkout
* One Click Checkout (OCC)

### Checkout events

Use these events to track customer interactions in the standard checkout flow, including checkout pages, payment links, and payment forms.

#### Client-side checkout events

Client-side events are triggered in the browser or app when customers interact with the checkout interface.

| Event name | Description |
| - | - |
| `cf_checkout_load` | Checkout loaded successfully. |
| `cf_checkout_transaction_initiate` | Customer initiated a transaction. |
| `cf_transaction_success` | Transaction completed successfully. |
| `cf_transaction_failure` | Transaction failed. |
| `cf_retry_checkout` | Redirected to checkout after failure. |
| `cf_return_to_merchant` | Customer redirected back to merchant page. |

#### Client-side payment link and payment form events

| Event name | Description |
| - | - |
| `cf_pl_load` | Payment link loaded successfully. |
| `cf_pf_load` | Payment form loaded successfully. |
| `cf_checkout_initiated` | Checkout initiated from a payment link or form. |
| `cf_purchase_completed` | Payment completed successfully. |

### One click checkout (OCC) events

Use these events to track customer interactions in the One Click Checkout (OCC) flow. OCC events are available for server-side and client-side tracking.

Cashfree uses a server-to-server integration to share event data with analytics and advertising platforms.

#### Server-side events

Server-side events are pushed to Google Analytics 4 (GA4) and Meta Facebook.

| GA4 event | Meta Facebook event |
| - | - |
| `begin_checkout` (standard event) | `InitiateCheckout` (standard event) |
| `cf_checkout_login_otp_sent` | `cf_checkout_login_otp_sent` |
| `cf_checkout_login_verify` | `cf_checkout_login_verify` |
| `add_shipping_info` (standard) | `cf_checkout_address_collected` |
| `cf_checkout_payment_info_displayed` | `cf_checkout_payment_info_displayed` |
| `add_payment_info` (standard) | `AddPaymentInfo` (standard event) |
| `purchase` (standard) | `purchase` (standard event) |

#### Client-side events

Client-side events are triggered in the browser or app when customers interact with OCC pages.

| Event name | Description |
| - | - |
| `cf_checkout_occ_load` | First page or login page loaded. |
| `cf_checkout_login_verify` | OTP verified. |
| `cf_checkout_login_otp_sent` | OTP sent. |
| `cf_checkout_address_load` | Addresses loaded. |
| `cf_checkout_address_collected` | Address save or continue clicked. |
| `cf_checkout_load` | Payment page opened. |
| `cf_checkout_transaction_initiate` | Order payment transaction initiated. |
| `cf_checkout_offer_apply` | Offer applied. |
| `cf_checkout_offer_remove` | Offer removed. |
| `cf_checkout_order_cancelled` | Order cancelled. |
| `cf_checkout_address_deleted` | Address deleted. |
| `cf_checkout_address_updated` | Address updated. |
| `transaction_success` | Triggered only for non-Shopify integrations. |

## Setup instructions

Follow the platform-specific instructions below to configure your analytics integration.

<Accordion title="Google Analytics 4 (GA4)" icon="google">
  To set up GA4 integration, complete the following steps:

  1. Sign in to your [GA4 account](https://analytics.google.com/).
  2. Go to **Admin** (bottom left).
  3. Select **Data Streams** and open the relevant stream.
  4. Copy the **Measurement ID**.
  5. In Cashfree’s External Analytics Configuration modal, enable **Broadcast events to Google**.
  6. Enter the **Measurement ID**.
  7. Generate an API token:
     * In GA4 Admin, select **Measurement Protocol API secrets**.
     * Create a new API secret and copy the value.
  8. Enter the **Access Token** in Cashfree’s configuration modal.
  9. Select **Save**.

  <img alt="" />

  **Verification**:

  * In GA4, go to **Reports > Realtime Overview**.
  * Perform a test transaction.
  * Events should appear in real time.

  <Note>
    The 24–48 hour monitoring window applies to Google Ads event attribution and overall conversion reporting, not to the GA4 Realtime Overview. Realtime events appear immediately; attribution data in Google Ads and standard GA4 reports can take up to 48 hours to reflect accurately.
  </Note>
</Accordion>

<Accordion title="Meta Pixel" icon="meta">
  To set up Meta Pixel integration, complete the following steps:

  1. Sign in to [Meta Events Manager](https://www.facebook.com/events_manager2).
  2. Select your Pixel from **Data Sources**.
  3. Copy the **Pixel ID** from **Settings**.
     <img alt="Meta Pixel ID" />
  4. Generate an **Access Token**:
     * Scroll to **Conversions API**.
     * Select **Generate Access Token**.\\
       <img alt="Meta generate access token" />
  5. In Cashfree’s configuration modal, enter the Pixel ID and Access Token.
  6. Select **Save**.
  7. In the [Merchant Dashboard](https://merchant.cashfree.com/auth/login), go to **Developers > Checkout Analytics > Meta** and toggle on the **Purchase events** option.

  <Note>
    Cashfree sends Meta Purchase events as server-side events. These events will not appear in Meta’s **Test Events** section or in browser-based tools like the Meta Pixel Helper extension. Monitor the **Events Overview** section of your Meta Events Manager instead.
  </Note>

  **Verification**:

  1. Navigate to **Data Source** tab under Events Manager.
  2. Select your particular Pixel ID and click on **Overview**.

  Here, you see the list of events coming, if there is some activity on the OCC.

  <img alt="" />

  ### Event verification

  Use this section to confirm that Meta Pixel receives your Purchase events successfully. Verify event delivery directly in Meta Events Manager rather than in other tracking interfaces, because Meta Events Manager is the only source that reflects the data Meta actually receives.

  <Note>
    If you configure a new Meta Pixel, wait approximately 30 minutes to 1 hour before you verify event delivery. Event data can take this long to appear in Meta Events Manager.
  </Note>

  To verify Purchase events in Meta Events Manager:

  1. Log in to [Meta Events Manager](https://www.facebook.com/events_manager2).
  2. Navigate to the relevant Pixel or data set.
  3. Apply the date and time filter for the period you want to review.
  4. Review the number of Purchase events recorded for that period.
  5. Open the Shopify Admin and navigate to the **Orders** section.
  6. Filter the orders for the same period.
  7. Count the number of orders processed through the OCC channel during that period.
  8. Compare the Purchase events shown in Meta Events Manager with the OCC orders from Shopify for the same period.

  This comparison provides the most accurate way to confirm that Meta receives your Purchase events successfully.

  <Note>
    If you are a Shopify merchant using OCC, disable the **purchase** event in Cashfree Meta Pixel setup. This prevents double-counting if Facebook and Instagram sales channels are active in your Shopify store.
  </Note>
</Accordion>

<Accordion title="Mixpanel" icon="https://cdn.brandfetch.io/idr_rhI2FS/w/800/h/764/theme/dark/symbol.webp?c=1bxid64Mup7aczewSAYMX&t=1717143416035">
  To set up Mixpanel integration, complete the following steps:

  1. Sign in to your [Mixpanel account](https://mixpanel.com/).
  2. Go to **Project Settings**.
  3. Copy the **Project Token**.
  4. Enter it in the Cashfree configuration modal.
  5. Select **Save**.
</Accordion>

## Linking with ad platforms

You can link your analytics platforms with advertising platforms to enhance tracking and optimisation.

<Accordion title="GA4 + Google Ads" icon="google">
  Link Google Ads and GA4

  ### Step 1: Mark the purchase event as a conversion in GA4

  GA4 imports only events that are marked as key events. Mark the purchase event as a key event before you import it into Google Ads.

  1. Sign in to your GA4 property.
  2. Select **Admin** (bottom-left).
  3. Under **Data display**, select **Events**.
  4. Find the **purchase** event in the list of collected events.
  5. Check for the star icon to confirm the purchase event is marked as a key event (purchase events are usually marked by default).

  ### Step 2: Link Google Analytics 4 to Google Ads

  Linking creates the connection that lets data flow between the two platforms.

  1. In your GA4 property, open **Admin**.
  2. Under **Product links**, select **Google Ads links**.

  <img alt="GA4 Google Ads links" />

  3. Select **Link** (top-right).
  4. Select **Google Ads accounts** and pick the account(s) you want to link.
  5. Select the checkbox next to the account and select **Confirm**.
  6. On the next screen, ensure **Enable personalised advertising** and **Enable auto tagging** are turned on (they should be on by default). Keep both enabled where possible.

  * Personalised advertising lets you use GA4 audiences for remarketing in Google Ads.

  * Auto tagging adds the gclid parameter to your ad URLs so GA4 can attribute clicks and conversions to Google Ads campaigns.

  7. Select **Next**, review the settings, then select **Submit**.

  Allow up to 24 hours for data to start flowing between the two platforms.

  ### Step 3: Import the purchase conversion into Google Ads

  After linking and once data has synced, import the GA4 conversion into Google Ads.

  1. Sign in to your Google Ads account.
  2. From the left menu, select **Goals**.
  3. Under **Conversion**, select **Summary**.
  4. Select **+ Create conversion action**.
  5. Select **Import**.
  6. Select **Google Analytics 4 properties**, select **Web**, then select **Continue**.

  <img alt="" />

  7. Select the **purchase** event (or other conversions you want to track) from the list of GA4 key events.
  8. Select **Import and continue**, then select **Done**.

  ### Step 4: Configure the purchase conversion in Google Ads

  1. On the **Conversions** summary page, find the purchase conversion you imported.
  2. Select the conversion name to edit settings.
  3. Set **Value** to **Use the value from Google Analytics** so the purchase amount is passed into Google Ads dynamically.
  4. Set **Action optimisation** to **Primary action** so Google Ads can use this conversion for bidding optimisation.

  When setup is complete, start analysing conversion data in both platforms.

  <Note>
    Changes to conversion tracking apply only to future orders and events and won’t be applied retroactively to historical data. Allow up to 48 hours for the new conversion data to appear in GA4 and Meta reporting dashboards.
  </Note>
</Accordion>

<Accordion title="Meta Pixel + Meta Ads" icon="meta">
  Once you have configured Meta Pixel integration with Cashfree, you can link it with Meta Ads Manager to enhance your advertising campaigns with conversion tracking and optimisation.

  ### Prerequisites

  Before linking Meta Pixel with Meta Ads, ensure you have:

  * A configured Meta Pixel with Cashfree integration
  * An active Meta Ads Manager account
  * Admin access to your Meta Business account

  ### Step 1: Access your Meta Ads Manager

  1. Sign in to [Meta Ads Manager](https://www.facebook.com/adsmanager/).
  2. Navigate to **Events Manager** from the main menu.
  3. Select your configured Pixel from the **Data Sources** list.

  ### Step 2: Verify pixel events

  1. In **Events Manager**, go to your Pixel's **Overview** tab.
  2. Verify that Cashfree events such as `purchase` and `InitiateCheckout` are appearing.
  3. Verify event data quality using the **Diagnostics** tab.

  ### Step 3: Create custom conversions

  1. In **Events Manager**, select **Custom Conversions** from the left menu.
  2. Select **Create Custom Conversion**.
  3. Define conversion rules based on Cashfree events:
     * For purchase tracking: use the `purchase` event
     * For checkout initiation: use the `InitiateCheckout` event
     * For payment info collection: use the `AddPaymentInfo` event
  4. Set conversion values and attribution windows as needed.
  5. Save the custom conversion.

  ### Step 4: Use conversions in Meta Ads campaigns

  1. In [Meta Ads Manager](https://www.facebook.com/adsmanager/), create or edit a campaign.
  2. In the **Optimisation & Delivery** section, select your custom conversion as the optimisation goal.
  3. Set appropriate bid strategies based on your conversion objectives.
  4. Launch your campaign to begin using Cashfree conversion data for optimisation.

  ### Step 5: Monitor performance

  * Use **[Ads Reporting](https://www.facebook.com/adsmanager/reporting/)** to view conversion metrics from Cashfree events.
  * Monitor attribution data in **Events Manager** to understand the customer journey.
  * Adjust campaign targeting and bidding based on Cashfree conversion insights.
</Accordion>

## Verification and troubleshooting

* Allow up to 48 hours for new configurations.
* Ensure IDs and tokens are correct.
* For Shopify merchants, disable duplicate purchase events.
* Use provider-specific real-time or debug views.

<Note>
  If you are a Shopify merchant using One Click Checkout, disable the purchase event in Cashfree Meta Pixel setup. This prevents double-counting if Facebook and Instagram sales channels are active in your Shopify store.
</Note>

## FAQs

<AccordionGroup>
  <Accordion title="I am not able to see events in the Meta Pixel Helper (Meta Pixel Ad Helper). Why?">
    Cashfree External Analytics integration supports server-side events only, which are pushed directly to the Meta Events Manager dashboard instead of the browser. As a result, events do not appear in the Meta Pixel Helper, but they are visible in the Meta Events Manager dashboard.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How long does it take for events to appear in Meta Pixel?">
    * After configuration in the Merchant Dashboard, events may take approximately **30 minutes to 1 hour** to appear in the Meta Events Manager.
    * It may take **24–48 hours** for the same events to become visible in Meta Ads reporting.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How long does it take for GA4 data to appear after configuring it in Cashfree OCC?">
    After configuring GA4 in Cashfree OCC, monitor the data for approximately **24–48 hours** to allow a sufficient sample size to accumulate. Note that only events generated after the configuration is enabled will be sent. Orders or events created prior to the configuration will not be available.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What should I do if I am receiving duplicate events in Meta Pixel?">
    If you are receiving duplicate purchase events in the Meta Events Manager, events may be getting triggered from multiple sources.

    To avoid duplication, disable the `purchase` event from the Merchant Dashboard. This prevents Cashfree from sending the purchase event and resolves the duplication issue.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Where can I find documentation to set up Meta Pixel and GA4 tracking for Cashfree checkout?">
    You can configure external analytics from the [Merchant Dashboard](https://merchant.cashfree.com/auth/login). For setup instructions, see:

    * [Google Analytics 4 (GA4)](/docs/payments/checkout/after/external-analytics#google-analytics-4-ga4)
    * [Meta Pixel](/docs/payments/checkout/after/external-analytics#meta-pixel)

    After setup, monitor the event flow for 24–48 hours to ensure events are being tracked correctly.

    <iframe title="FAQs feedback component" />
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Can Cashfree push conversion data back to the Shopify dashboard when using One Click Checkout?">
    Shopify does not allow Cashfree to push conversion data back to the Shopify dashboard when One Click Checkout is active. Use the Merchant Dashboard for analytics insights, or use external tools like Google Analytics to view your data.
  </Accordion>
</AccordionGroup>

<snippet>snippets/related-topics-loader.mdx</snippet>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/payments/manage/reports">Payment Reports</a></li>
  </ul>
</div>


# Business Customisation
Source: https://www.cashfree.com/docs/payments/checkout/bussiness-customisation

Configure Cashfree One Click Checkout business settings, payment method ordering, and social proofing to optimise conversions on your storefront within an hour.

Business customisation feature allows you to configure various aspects of your checkout page, including general settings, payment method ordering, and social proofing elements. Changes reflect on your checkout page within one hour of saving.

This page covers the following topics:

* [General settings](#general-settings): Configure offers banner and failure state action
* [Payment method ordering](#payment-method-ordering): Customise payment method sequence and enable AI personalisation
* [Social proofing](#social-proofing): Display credibility indicators to build customer trust

## Access the business customisation page

To access the PG Business Customisation page:

1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
2. Go to **Payment Gateway > One Click Checkout > Customisation**.
3. Select the **PG Business Customisation** tab.

<img alt="Business Customisation" />

## General settings

The General Settings section allows you to configure basic checkout page preferences.

### Offers banner

The Offers Banner displays available offers to customers during checkout.

To enable the Offers Banner, toggle the **Offers Banner** switch to the ON position.

When enabled, customers see an offer code section with applicable offers on the checkout page.

<Note>
  The banner displays offers that are currently active and applicable to the customer's transaction.
</Note>

### Failure state action

This setting determines how the checkout page responds when a payment fails. You can choose from the following options:

* **Return to merchant page**: Redirects the customer back to your website or application.
* **Retry payment**: Keeps the customer on the checkout page to attempt payment again.

To configure this setting:

1. Under **Failure state action**, select your preferred option.
2. Click **Save** to apply your changes.

<Tip>
  Selecting the **Retry payment** option can help recover failed transactions without redirecting customers away from the checkout page.
</Tip>

## Payment method ordering

This section allows you to customise the order in which payment methods appear on the checkout page.

### Enable checkout personalisation

When enabled, an intelligent model dynamically reorders payment methods based on customer preferences and historical success rates. This feature is recommended for optimising conversion rates.

To enable this feature, toggle the **Enable Checkout AI Personalisation** switch to the ON position.

<Tip>
  Use the checkout AI personalisation feature to let intelligent algorithms optimise payment method ordering based on customer behaviour.
</Tip>

### Payment apps ordering

You can customise the order in which UPI payment apps appear to customers.

To configure UPI app ordering:

1. In the **Payment Method Customisation** section, locate **UPI Apps ordering**.
2. Click **Select UPI App** to view available UPI payment apps.
3. Choose from the available options such as Google Pay, Paytm, PhonePe, Cred, WhatsApp, Amazon Pay, Airtel, Bhim, Mobikwik, Navi, and Popclub.
4. Use the drag handles (**:::**) on the left side of each payment method to reorder them by dragging up or down.
5. Click **Save** to apply your ordering preferences.

<Note>
  The order you set here determines the sequence in which UPI apps appear on the customer-facing checkout page.
</Note>

<Tip>
  Place the most commonly used payment methods at the top of your ordering list to reduce friction.
</Tip>

## Social proofing

Social proofing builds trust by displaying credibility indicators on your checkout page. This feature helps boost conversions by showcasing your business's reliability and popularity.

To enable social proofing:

1. In the left navigation menu, select **Social Proofing**.
2. Toggle the **Social Proofing** switch to the ON position.

When enabled, social proofing displays the following elements on your checkout page:

* Real validation metrics such as live purchases and customer served counts
* Order volumes and reliability indicators to boost your brand image

<Tip>
  Enable social proofing to display credibility indicators that build trust and increase conversion rates.
</Tip>

## Save and preview

The customisation page includes a live preview panel on the right side. This panel displays how your checkout page appears to customers in real time as you make changes.

To save your changes, click the **Save** button at the bottom of each section after configuring your preferences.

A confirmation message appears: "PG business customisation updated successfully. It will start reflecting in 1 hour."

<Warning>
  Changes take approximately one hour to reflect on your live checkout page.
</Warning>

<Tip>
  Use the preview panel to verify how your checkout page appears before saving changes.
</Tip>

## Troubleshooting

If you encounter issues with the customisation feature, review the following solutions:

| Issue | Solution |
| - | - |
| Changes not reflecting | Allow up to one hour for changes to propagate to your live checkout page. |
| Unable to save settings | Ensure all required fields are completed before clicking **Save**. |
| Preview not updating | Refresh the customisation page and try again. The preview updates automatically as you make changes. |

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/payments/checkout/customise-checkout">Visual Customisation</a></li>
    <li><a href="/docs/payments/checkout/one-click-checkout">One Click Checkout</a></li>
  </ul>
</div>


# Recovering Abandoned Orders via WhatsApp
Source: https://www.cashfree.com/docs/payments/checkout/cart-recovery

Recover up to 4% of abandoned orders with Cashfree's WhatsApp and SMS cart recovery flow, which retargets dropped-off shoppers with payment reminders.

Customers drop off at checkout due to multiple reasons like lack of clarity on pricing, delivery, payment issues, and others. To convert these high-intent customers, we have released a workflow via WhatsApp and SMS that can recover up to **4%** of these lost orders.

## Key features

* **UPI payments**: Customers complete payments directly within WhatsApp using the UPI intent flow, without leaving the app.
* **Additional offer**: Apply a merchant-funded offer that is auto-applied at checkout to increase conversion.
* **Verified WhatsApp messages**: Payment messages are delivered from Cashfree's verified WhatsApp account, building trust with your customers.

<img />

## Abandoned orders report

The abandoned orders report lists orders where a payment was initiated but not completed. Use this report to identify drop-offs, follow up with customers, or reconcile incomplete transactions.

To generate an abandoned orders report, complete the following steps:

1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
2. Navigate to **Payment Gateway** > **Reports** > **Download Reports**.
3. Select **Generate New Report**.
4. Configure your report settings:
   * **Report Type**: Select **Abandoned Orders** from the dropdown.
   * **Date Range**: Choose the time period for the report.
   * **File Format**: Select **CSV** or **XLSX**.
   * **File Name**: Modify if needed (optional).
5. Select **Generate Report**.

## Activation

To activate WhatsApp abandoned orders, submit a request using the [support form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) with the following details:

* The delay duration after which the WhatsApp message should be sent to the customer.
* The offer details to apply at checkout, either as a flat amount or a percentage discount (optional).


# Go Live Checklist
Source: https://www.cashfree.com/docs/payments/checkout/checklist

Use this Cashfree One Click Checkout go-live checklist for Shopify Preview Stores to validate configurations and maximise conversions before launch.

After Cashfree One Click Checkout is successfully integrated with your Shopify Preview Store, ensure and verify the following configurations to get the maximum conversions on the Checkout.

## Shopify dashboard

### Products

Ensure Cashfree is added as Sales Channel for all your products in Shopify.

1. Navigate to **Products** > All in your Shopify store admin.
2. Select all the products and click **Include in sales channels**.
3. Select **Cashfree-OCC-** sales channel and click **Include products** to save.

<Frame>
  <img />
</Frame>

Once done, Cashfree Checkout will open for all these products when added in the cart and proceeding to checkout.

### Taxes

Ensure **Inclusive Taxes** is set up since Cashfree Checkout is compatible with this setting.

1. Navigate to **Settings > Taxes and duties** in your Shopify store admin.
2. Scroll to **Global settings** and select the **Include sales tax in product price and shipping rate** check box. Click **Save**.

<Frame>
  <img />
</Frame>

## Cashfree dashboard

### Payments

* Verify **Online Payments** are set up for your account.
* Check that the Online Payment Gateway is activated. Note that Payment Gateway is shown in Products Activated section on Merchant Dashboard.
* Check that online payment methods like **UPI** and **Cards** are activated in the **[Merchant Dashboard](https://merchant.cashfree.com/auth/login)** and go to **Payment Gateway > Settings > Payment Methods**.

### COD and RTO

* Verify **COD** is set up for your account.
* Configure **COD** (or **Partial COD**) rules. Learn more about [COD management](/docs/payments/checkout/cod/overview).
* Set up **RTO Intelligence** and COD configurations to manage RTO. Learn more about [RTO tools](/docs/payments/checkout/cod/blacklist-cod).\
  <Note>You can configure COD and set up RTO rules in the **[Merchant Dashboard](https://merchant.cashfree.com/auth/login)** and go to **PG Products > One Click Checkout > COD & RTO**.</Note>

## Ads and analytics tracking

To maintain accurate ROAS, Conversion metrics and performance, ensure your ads and analytics setup is complete. Your ROAS and Conversion metrics will drop if this isn't set up correctly.

1. Configure **Meta Pixel tracking** to get Checkout and Conversion events.

   * Know more about the setup here:**[External Analytics OCC](/docs/payments/checkout/after/external-analytics#meta-pixel).**
   * You can set up analytics tracking in the **[Merchant Dashboard](https://merchant.cashfree.com/auth/login)** and go to **Payment Gateway > Developers > Checkout Analytics**.

   <Warning>If “Facebook and Instagram” sales channel is activated in your Shopify store, ensure the **Purchase** event is disabled in Cashfree during the Meta Pixel Analytics setup.</Warning>

2. Configure **Google Analytics (GA4) tracking** to get Checkout and Conversion events.
   * Know more about the setup here: **[External Analytics OCC](/docs/payments/checkout/after/external-analytics#google-analytics-4-ga4).**
   * You can set up analytics tracking in the **[Merchant Dashboard](https://merchant.cashfree.com/auth/login)** and go to **Payment Gateway > Developers > Checkout Analytics**.

3. Configure **Google Ads conversion tracking via GA4**.
   * Know more about the setup here: **[External Analytics OCC](/docs/payments/checkout/after/external-analytics#ga4-google-ads).**

## Shipping and delivery

Ensure your **Shipping Rates and Delivery Time** is correctly configured to avoid drop-offs at the address stage.

* Set up your **Shipping Rules, COD Availability, and Shipping Charges** to ease your delivery operations.
* Learn more about the [shipping setup steps](/docs/payments/checkout/shipping-overview).
* You can set up the shipping rules in the **[Merchant Dashboard](https://merchant.cashfree.com/auth/login)** and go to **PG Products > One Click Checkout > Shipping & Delivery**.

<Note>Shoppers are increasingly conscious of **Expected Delivery Time**. Ensure this is added during setup to avoid drop-offs.</Note>

<Warning>Shopify Shipping Rules **won't be shown** on Cashfree OCC. Set these up in Cashfree as per the above.</Warning>

## Discounts and offers

Ensure your Discounts and Offers are synced from Shopify or created in Cashfree to boost your customer acquisition and repeat purchases.

* Setup your Shopify Discounts to be displayed on Checkout.
* For Shopify discounts to work with Cashfree Checkout, the **Cashfree-OCC-\*** sales channel must be added. Learn more about [Shopify discounts](/docs/payments/checkout/offers/shopify).
* Create Prepaid, Payment Method, and other special offers to drive conversions.
  You can import Shopify discounts and create Cashfree offers in the **[Merchant Dashboard](https://merchant.cashfree.com/auth/login)** and go to **PG Products > One Click Checkout > Offers**.

## Branding and customisation

Customise the checkout experience to match your brand identity.

* You can customise your **Brand Logo** and **Colours** on checkout in the **[Merchant Dashboard](https://merchant.cashfree.com/auth/login)** and go to **PG Products > One Click Checkout > Customisation**.

<Note>Ensure your **Brand Name** is visible on Checkout. Submit a request through the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) for this.</Note>

## Abandoned checkout recovery

Set up recovery flows to recover dropped shoppers.

1. **Abandoned Checkout**:
   * This is created and available in Shopify dashboard and no configuration required.
   * Connect your **Recovery Provider** on Shopify to target these shoppers.\
     <Note>Only sessions that have reached the **Payments page** and dropped are created in Shopify.</Note>

2. **WhatsApp via Cashfree webhooks**:
   * Configure your WhatsApp Provider to get notified via **Abandoned Checkout webhooks**. Learn more about [Abandoned Checkout webhooks](/docs/payments/checkout/abandoned-checkout/webhook).\
     <Note> Sessions that completed the **Login step** (verified phone number is available) and dropped are notified via webhook.</Note>

## Final checkout flow

* Verify and experience the final checkout flow in your **Preview Theme** on Shopify.

## OCC analytics

* Check OCC **Sales and Performance** in the **[Merchant Dashboard](https://merchant.cashfree.com/auth/login)** and go to **PG Products > One Click Checkout > Funnel Analytics**.

## Special flow handling

### Bundler apps

* Check your bundled product information and amount are correctly captured in **Cart Summary** and when **Order is Placed via OCC**.
* If your current Bundler app isn't working, try one of these integrated and tested apps:
  * [Shopify Bundles](https://apps.shopify.com/shopify-bundles)
  * [Bundler Product Bundles](https://apps.shopify.com/bundler-product-bundles)
  * [Pumper Product Bundles](https://apps.shopify.com/pumper-quantity-breaks-product-bundles-discounts)
  * [Essential Post-Purchase Upsell](https://apps.shopify.com/essential-post-purchase-upsell)
  * [Revy Product Bundles](https://apps.shopify.com/product-bundles-discounts-by-revy)
  * [Koala Product Bundles](https://apps.shopify.com/profitkoala-upsell-bundle)

### Sidecart apps

* Check product, amount, and discount information is correctly captured during OCC Checkout.
* OCC works with vanilla Shopify Sidecart. If your current app doesn’t work, try one of these:
  * [iCart](https://apps.shopify.com/icart)
  * [Slide Cart](https://apps.shopify.com/slide-cart)
  * [Sticky Cart by Qikify](https://apps.shopify.com/sticky-cart-by-qikify)
  * [CornerCart](https://apps.shopify.com/cornercart)
  * [XB Sticky Add To Cart + Upsell](https://apps.shopify.com/xb-sticky-add-to-cart-upsell)
  * [Monster Cart Upsell+Free Gifts](https://apps.shopify.com/monster-upsells)

If you use a third-party side cart plugin and OCC does not trigger, the Cashfree technical team typically needs to adjust your configuration so checkout triggers correctly from both the side cart and the Buy button. Contact the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) to request this configuration.

### International orders

* OCC doesn't support International Orders and Currency.
* To facilitate the same, we can add a custom CTA above/below your Checkout button which redirects such shoppers to Shopify Checkout.

<Frame>
  <img />
</Frame>

Submit a request through the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) for this configuration.

### Gift card and store credit apps

* OCC doesn't support Shopify or custom Gift Card and Store Credit Apps.
* Add a **custom CTA** above/below Checkout button to redirect shoppers to Shopify Checkout.

<Frame>
  <img />
</Frame>

Submit a request through the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) for this configuration.

### Loyalty and rewards apps

* OCC doesn't support third-party Loyalty Apps.
* Add a **custom CTA** above/below Checkout button to redirect shoppers to Shopify Checkout.

<Frame>
  <img />
</Frame>

Submit a request through the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) for this configuration.

## Merchant Dashboard quick links

Use the following links to open key One Click Checkout configuration pages:

* [COD and RTO setup](https://merchant.cashfree.com/merchants/pg/one-click-checkout-activated/cod)
* [Shipping profiles](https://merchant.cashfree.com/merchants/pg/one-click-checkout-activated/shipping-delivery)
* [Checkout analytics](https://merchant.cashfree.com/merchants/pg/developers/checkout-analytics)


# Go Live Checklist
Source: https://www.cashfree.com/docs/payments/checkout/checklist-deprecated

Verify your legacy Cashfree One Click Checkout configurations against this deprecated go-live checklist before switching traffic to the production environment.

<div>
  <div>
    <div>
      <div>
        <svg>
          <path />
        </svg>
      </div>

      <span>Have you checked if UPI and other payment modes are working?</span>
    </div>

    <div>
      <button>Yes</button>
      <button>No</button>
      <button>N/A</button>
    </div>
  </div>

  <div>
    <svg>
      <path />
    </svg>

    <span>Test this on your Preview Store in [Shopify](https://admin.shopify.com/).</span>
  </div>
</div>

<div>
  <div>
    <div>
      <div>
        <svg>
          <path />
        </svg>
      </div>

      <span>Have you enabled COD/Partial COD, and is it working as expected?</span>
    </div>

    <div>
      <button>Yes</button>
      <button>No</button>
      <button>N/A</button>
    </div>
  </div>

  <div>
    <svg>
      <path />
    </svg>

    <span>You can set up COD on the [Merchant Dashboard](https://merchant.cashfree.com/merchants/pg/one-click-checkout-activated/cod).</span>
  </div>
</div>

<div>
  <div>
    <div>
      <div>
        <svg>
          <path />
        </svg>
      </div>

      <span>Have you set up any blocking on COD?</span>
    </div>

    <div>
      <button>Yes</button>
      <button>No</button>
      <button>N/A</button>
    </div>
  </div>

  <div>
    <svg>
      <path />
    </svg>

    <span>You can set up blocking on COD on the [Merchant Dashboard](https://merchant.cashfree.com/merchants/pg/one-click-checkout-activated/cod/blacklist-details?blackListItem=customers).</span>
  </div>
</div>

<div>
  <div>
    <div>
      <div>
        <div>
          <svg>
            <path />
          </svg>
        </div>

        <span>Are you using RTO intelligence?</span>
      </div>

      <div>
        <button>Yes</button>
        <button>No</button>
        <button>N/A</button>
      </div>
    </div>

    <div>
      <svg>
        <path />
      </svg>

      <span>You can enable RTO intelligence from [Merchant Dashboard](https://merchant.cashfree.com/merchants/pg/one-click-checkout-activated/cod).</span>
    </div>
  </div>

  <div>
    <div>
      <div>
        <div>
          <svg>
            <path />
          </svg>
        </div>

        <span>Have you added shipping provider credentials for advanced RTO capability?</span>
      </div>

      <div>
        <button>Yes</button>
        <button>No</button>
        <button>N/A</button>
      </div>
    </div>

    <div>
      <svg>
        <path />
      </svg>

      <span>You can connect your shipping provider on the [Merchant Dashboard](https://merchant.cashfree.com/merchants/pg/one-click-checkout-activated/cod).</span>
    </div>
  </div>

  <div>
    <div>
      <div>
        <div>
          <svg>
            <path />
          </svg>
        </div>

        <span>Has Facebook Pixel, Google Analytics, or Google Ads been set up correctly and configured on the dashboard?</span>
      </div>

      <div>
        <button>Yes</button>
        <button>No</button>
        <button>N/A</button>
      </div>
    </div>

    <div>
      <svg>
        <path />
      </svg>

      <span>You can configure event tracking on the [Merchant Dashboard](https://merchant.cashfree.com/merchants/pg/developers/checkout-analytics).</span>
    </div>
  </div>
</div>

<div>
  <div>
    <div>
      <div>
        <div>
          <svg>
            <path />
          </svg>
        </div>

        <span>Have additional tracking scripts been added in [Shopify](https://admin.shopify.com/) settings?</span>
      </div>

      <div>
        <button>Yes</button>
        <button>No</button>
        <button>N/A</button>
      </div>
    </div>

    <div>
      <svg>
        <path />
      </svg>

      <span>You can configure event tracking on the [Merchant Dashboard](https://merchant.cashfree.com/merchants/pg/developers/checkout-analytics).</span>
    </div>
  </div>

  <div>
    <div>
      <div>
        <div>
          <svg>
            <path />
          </svg>
        </div>

        <span>Has the Google Analytics Server-to-Server setup been completed?</span>
      </div>

      <div>
        <button>Yes</button>
        <button>No</button>
        <button>N/A</button>
      </div>
    </div>

    <div>
      <svg>
        <path />
      </svg>

      <span>You can configure event tracking on the [Merchant Dashboard](https://merchant.cashfree.com/merchants/pg/developers/checkout-analytics).</span>
    </div>
  </div>
</div>

<div>
  <div>
    <div>
      <div>
        <svg>
          <path />
        </svg>
      </div>

      <span>Is conversion data being updated correctly on the dashboard?</span>
    </div>

    <div>
      <button>Yes</button>
      <button>No</button>
      <button>N/A</button>
    </div>
  </div>

  <div>
    <svg>
      <path />
    </svg>

    <span>You can check conversion data on the [Merchant Dashboard](https://merchant.cashfree.com/merchants/pg/one-click-checkout-activated/analytics).</span>
  </div>
</div>

<div>
  <div>
    <div>
      <div>
        <svg>
          <path />
        </svg>
      </div>

      <span>Is abandoned checkout data being pushed correctly?</span>
    </div>

    <div>
      <button>Yes</button>
      <button>No</button>
      <button>N/A</button>
    </div>
  </div>

  <div>
    <svg>
      <path />
    </svg>

    <span>Check this on the [Shopify](https://admin.shopify.com/) dashboard.</span>
  </div>
</div>

<div>
  <div>
    <div>
      <div>
        <svg>
          <path />
        </svg>
      </div>

      <span>Are you using recovery campaign functionality?</span>
    </div>

    <div>
      <button>Yes</button>
      <button>No</button>
      <button>N/A</button>
    </div>
  </div>

  <div>
    <svg>
      <path />
    </svg>

    <span>You can set up a recovery campaign on the [Merchant Dashboard](https://merchant.cashfree.com/merchants/pg/one-click-checkout-activated/recovery-campaign).</span>
  </div>
</div>

<div>
  <div>
    <div>
      <div>
        <svg>
          <path />
        </svg>
      </div>

      <span>Are discounts working as expected?</span>
    </div>

    <div>
      <button>Yes</button>
      <button>No</button>
      <button>N/A</button>
    </div>
  </div>

  <div>
    <svg>
      <path />
    </svg>

    <span>You can check Cashfree offers and promotions on the [Merchant Dashboard](https://merchant.cashfree.com/merchants/pg/one-click-checkout-activated/offersV2).</span>
  </div>
</div>

<div>
  <div>
    <div>
      <div>
        <svg>
          <path />
        </svg>
      </div>

      <span>Are shipping rates correctly set up and visible to customers?</span>
    </div>

    <div>
      <button>Yes</button>
      <button>No</button>
      <button>N/A</button>
    </div>
  </div>

  <div>
    <svg>
      <path />
    </svg>

    <span>You can set up shipping rates on the [Merchant Dashboard](https://merchant.cashfree.com/merchants/pg/one-click-checkout-activated/shipping-delivery).</span>
  </div>
</div>

<div>
  <div>
    <div>
      <div>
        <svg>
          <path />
        </svg>
      </div>

      <span>Is notifications and other messages working as expected?</span>
    </div>

    <div>
      <button>Yes</button>
      <button>No</button>
      <button>N/A</button>
    </div>
  </div>

  <div>
    <svg>
      <path />
    </svg>

    <span>You can check this on the [Shopify](https://admin.shopify.com/) dashboard.</span>
  </div>
</div>

<div>
  <div>
    <div>
      <div>
        <svg>
          <path />
        </svg>
      </div>

      <span>Are checkout-related third-party apps working as expected?</span>
    </div>

    <div>
      <button>Yes</button>
      <button>No</button>
      <button>N/A</button>
    </div>
  </div>

  <div>
    <svg>
      <path />
    </svg>

    <span>You can check this on the [Shopify](https://admin.shopify.com/) dashboard.</span>
  </div>
</div>

<div>
  <div>
    <div>
      <div>
        <svg>
          <path />
        </svg>
      </div>

      <span>Are supported bundling apps functioning correctly?</span>
    </div>

    <div>
      <button>Yes</button>
      <button>No</button>
      <button>N/A</button>
    </div>
  </div>

  <div>
    <svg>
      <path />
    </svg>

    <span>You can check this on the [Shopify](https://admin.shopify.com/) dashboard.</span>
  </div>
</div>

<div>
  <div>
    <div>
      <div>
        <svg>
          <path />
        </svg>
      </div>

      <span>Are supported loyalty apps working as intended?</span>
    </div>

    <div>
      <button>Yes</button>
      <button>No</button>
      <button>N/A</button>
    </div>
  </div>

  <div>
    <svg>
      <path />
    </svg>

    <span>You can check this on the [Shopify](https://admin.shopify.com/) dashboard.</span>
  </div>
</div>


# Blacklist Cash on Delivery (COD)
Source: https://www.cashfree.com/docs/payments/checkout/cod/blacklist-cod

Reduce RTO losses by blacklisting risky shoppers from Cash on Delivery on Cashfree One Click Checkout using customer details, phone numbers, or pin codes.

The Blacklisting feature in Cashfree helps merchants reduce losses from Return to Origin (RTO), where customers refuse to accept COD orders. RTOs increase costs due to shipping and inventory handling.

Secure your business by blocking high-risk customers, limiting COD for select products, and managing delivery zones prone to issues. Customise your store’s operations to reduce risks, minimise losses, and ensure smooth, efficient order fulfilment.

## Key features

* Block high-risk customers using advanced risk models
* Restrict certain products from COD eligibility
* Manage pin codes with a history of delivery issues

## Blacklisting COD

Use the Blacklist feature to restrict COD based on products, customers, or pincodes.

### To access the blacklist:

1. Log in to the **[Merchant Dashboard](https://merchant.cashfree.com/auth/login)**.

2. Under One-Click Checkout, select Access.

3. In the left pane, select COD & RTO.

4. Select the Blacklist tab.

5. Select Add to Blacklist.

<img />

### To blacklist by product:

1. In the Add Product ID to Blacklist window:
   * To block a single product, select Single Product ID and enter the product ID.
   * To block multiple products, select Multiple Product IDs and upload a .csv file containing product IDs.
     <Note>
       The file must be under 500 KB. The `productid` field is required.
     </Note>
2. Select Proceed.

### To blacklist by customer:

1. In the Add Phone Number to Blacklist window:
   * To block a single customer, select Single Phone Number and enter the phone number.
   * To block multiple customers, select Multiple Phone Numbers, and upload a .csv file with phone numbers.
     <Note>
       The file must be under 500 KB. The `phonenumber` field is required.
     </Note>
2. Select Proceed.

<img />

### To blacklist by pincode:

1. In the Add Pincodes to Blacklist window:
   * To block a single pincode, select Single Pincode and enter the pincode.
   * To block multiple pincodes, select Multiple Pincodes and upload a .csv file with pincode values.
     <Note>
       The file must be under 500 KB. The `pincode` field is required.
     </Note>
2. Select Proceed.

<img />


# Configure Cash on Delivery
Source: https://www.cashfree.com/docs/payments/checkout/cod/configure

Configure Cashfree Cash on Delivery rules: set transaction amount thresholds, COD types, handling fees, and partial-payment collection to lift conversions.

Cashfree lets you set rules for handling COD transactions. You can define rules based on transaction amount, specify COD types, apply handling fees, and enable partial payment collection. These configurations give customers more flexibility and help increase conversions.

## Key features

* **Partial COD support**: Collect a flat amount or a percentage of the order value upfront. This helps reduce RTOs, improve order reliability, and manage risk for high-value or first-time orders—while offering customers flexible payment options and protecting your business.
* **Flexible COD rules**: Set minimum and maximum order amounts to control COD eligibility.
* **Custom transaction types**: Choose between full COD or Partial COD based on your business needs.
* **Handling fee configuration**: Apply handling fees for COD orders to offset delivery risks or costs.
* **Tiered rule setup**: Create multiple slabs to apply different COD rules for different order ranges.

## Configuring COD and RTO

To configure COD:

1. Log in to the **[Merchant Dashboard](https://merchant.cashfree.com/auth/login)**.

2. Under **One-Click Checkout**, select **Access**.

3. In the left pane, select **COD & RTO**.

4. Select the **Configuration** tab.

5. Under **Configure COD Rules**, do the following:

   * In **Transaction Amount**, set the **Min Amount** and **Max Amount** for COD.

   * Under **Transaction Type**, choose one of the following:

     * **COD**: Enter a value in the **Handling Fee** field.

     * **Partial COD**: Specify the advance amount to collect. Choose a **Flat Amount** or **Percentage** of the order value.

<img />

6. To define more COD rules, select **Add Another Slab**.

7. Select **Confirm** to save your settings.

<Note>
  **Note**: If a transaction amount doesn’t match any rule, COD is disabled and the payment defaults to prepaid. Create custom slabs as needed.
</Note>

## FAQs

<AccordionGroup>
  <Accordion title="Can I add a handling fee for Partial COD orders?">
    Yes. For standard COD, enter a value in the **Handling Fee** field when configuring your COD rules (see step 5 above). For Partial COD, the Merchant Dashboard only lets you set the advance collection as a **Flat Amount** or **Percentage**, with no handling fee field. To add a handling fee for Partial COD orders, contact the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) to apply the required configuration changes on your account.
  </Accordion>
</AccordionGroup>


# Overview
Source: https://www.cashfree.com/docs/payments/checkout/cod/overview

Manage Cash on Delivery on Cashfree One Click Checkout: enable, configure, and optimise COD for the 70% of Indian shoppers who prefer it at checkout.

Cash on Delivery (COD) is one of the most widely used payment methods in Indian e-commerce, often accounting for over 70% of orders. It builds trust—especially among new users—by allowing payment only at the time of delivery.

Cashfree’s One-Click Checkout provides powerful tools to help you manage COD efficiently, reduce losses from Return to Origin (RTO), and improve delivery success rates.

## How COD works with Cashfree?

Setting up and managing COD with Cashfree is simple:

* **Order confirmation** – When a customer selects COD at checkout, Cashfree records the payment mode as **Cash on Delivery** with a **SUCCESS** status.
* **Order status** – The order appears as **PENDING** in Shopify. For custom integrations, use webhooks to monitor and update the order status.

<Note>
  Cashfree does not collect cash from customers.
</Note>

## Manage COD with Cashfree

Use the Cashfree Dashboard to customise COD operations based on your business goals:

* **Add or remove fees** – Configure convenience fees or waive them as needed. Learn how to [configure Cash on Delivery](/docs/payments/checkout/cod/configure).

* **Set restrictions** – Blacklist specific pincodes, product IDs, or customer phone numbers to control COD availability. Learn how to [blacklist Cash on Delivery](/docs/payments/checkout/cod/blacklist-cod).

* **Use RTO Intelligence** – Automatically hide the COD option for high-risk customers based on historical shipping and order data. Learn how to [configure RTO Intelligence](/docs/payments/checkout/cod/rto).

* **Enable Partial COD** – Collect a flat amount or a percentage of the order value in advance. This helps reduce RTO risk, particularly for high-value or first-time orders. Learn how to [configure Partial COD](/docs/payments/checkout/cod/configure#configuring-cod-and-rto).

* **Track payments** – View and manage both COD and prepaid orders in a single dashboard with analytics tools for insights and reporting.

You can also configure these settings directly in the Merchant Dashboard:

* **COD setup**: Navigate to **One Click Checkout > COD & RTO** in the [Merchant Dashboard](https://merchant.cashfree.com/merchants/pg/one-click-checkout-activated/cod).
* **Shipping & Delivery Profiles**: Navigate to **One Click Checkout > Shipping & Delivery** in the [Merchant Dashboard](https://merchant.cashfree.com/merchants/pg/one-click-checkout-activated/shipping-delivery/cashfree-shipping).

<Warning>
  Always check the order status and details for COD using [webhooks](/docs/api-reference/payments/latest/payments/webhooks) or [status APIs](/docs/api-reference/payments/latest/orders/get-order) to keep the order status updated.
</Warning>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/payments/latest/orders/get-order">Get Order Status API</a></li>
    <li><a href="/docs/payments/checkout/cod/configure">Configure COD</a></li>
    <li><a href="/docs/payments/checkout/cod/blacklist-cod">Blacklist COD</a></li>
    <li><a href="/docs/payments/checkout/cod/rto">RTO Intelligence</a></li>
    <li><a href="/docs/api-reference/payments/latest/payments/webhooks">Payment Webhooks</a></li>
  </ul>
</div>


# RTO Intelligence
Source: https://www.cashfree.com/docs/payments/checkout/cod/rto

Use Cashfree RTO Intelligence to disable Cash on Delivery for high-risk shoppers automatically, lowering returns and protecting margins on every order.

Cashfree’s AI-powered Return to Origin (RTO) Intelligence reduces return orders and fraud by disabling Cash on Delivery for high-risk customers. Integrated with One-Click Checkout, it uses machine learning to predict RTO risk, improving delivery rates and reducing costs.

## Key features

* **Smarter RTO risk prediction**: Uses a machine learning model that goes beyond historical order count to improve the accuracy and precision of RTO risk assessment.
* **Enriched data inputs**: Enhances model performance by combining customer phone numbers, shipping addresses, cart items, merchant transaction history, and 10+ other parameters.
* **Shipping provider integration**: Connects with shipping partners such as Delhivery and Selloship to provide end-to-end order visibility, enabling more accurate risk prediction.

## Activate RTO intelligence

To activate RTO Intelligence:

1. Log in to the **[Merchant Dashboard](https://merchant.cashfree.com/auth/login)**.
2. Under **One-Click Checkout**, select **Access**.
3. In the left pane, select **COD & RTO**.
4. Select the **RTO Intelligence** tab.
5. Turn on the toggle in the top-right corner.

<Note>
  **Note**: You can't turn on the toggle if no shipping provider credentials are linked.
</Note>

6. In the **Link a Shipping Provider** modal:

   1. Select the shipping company from the **Shipping Company** dropdown.

   2. Enter your **Username**.

   3. Enter your **Password**.

   4. Select **Add Now**.

<img />

After linking a shipping provider, contact Cashfree to complete the RTO Intelligence configuration. You must provide the risk score ranges for Low, Medium, and High-risk customers, along with the specific payment modes that should be disabled for each risk category. The Cashfree team will configure the rules based on the information you supply.

## Restrict high-risk orders to prepaid only

To restrict high-risk or high-RTO orders to prepaid payment only, enable RTO Intelligence by following the steps in [Activate RTO intelligence](#activate-rto-intelligence). Then submit the rules you want applied on the backend through the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1).


# Visual Customisation
Source: https://www.cashfree.com/docs/payments/checkout/customise-checkout

Match Cashfree One Click Checkout to your brand: configure logo, colours, button styles, layout, and typography for a consistent visual experience.

The **Customisation** dashboard lets you configure the visual aspects of the checkout page—including your logo, brand colours, button styles, and typography—to maintain a consistent appearance with your platform and ensure visual continuity between your site and the payment page.

The Customisation page includes two tabs:

* **Visual Customisation.** Controls the appearance of the checkout page, including branding, layout, and UI components.
* **[Business Customisation](/docs/payments/checkout/bussiness-customisation).** Controls business-level payment gateway settings, such as payment methods, ordering, and related behaviour.

This topic describes **Visual Customisation** only.

## Access the visual customisation page

To access and edit the checkout appearance:

1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) with your credentials.
2. Go to **Payments** > **One Click Checkout** > **Settings** > **Customisation**.
3. Select the **Visual Customisation** tab.
4. Do one of the following:
   * For a quick setup, use the **Basic** options.
   * For detailed control over individual UI components, turn on **Advanced Customisation**.
5. In the **Preview** panel on the right, verify how the checkout page appears to customers.
6. Select **Save** to apply your changes.

<Note>
  The **Preview** panel updates in real time as you change settings, so you can confirm the appearance of the checkout page before you save.
</Note>

## Configuration options

Select a tab to view the configuration options available for each mode.

<Tabs>
  <Tab title="Basic">
    Basic configuration applies minimal branding quickly. The following options are available when **Advanced Customisation** is off.

    * **Logo:** Enter your brand logo URL in the **Logo** field. The logo appears in the checkout header. The supported logo dimensions are 256 px × 256 px. Upload your logo in this format to ensure it displays correctly. To remove the logo, select the **×** icon next to the URL.

    * **Primary brand colour:** Enter a hex colour code for your primary brand colour. This colour applies to the header and primary action buttons across the checkout page. To restore the default, select the reset control next to the colour field.

      <img alt="Basic customisation" />
  </Tab>

  <Tab title="Advanced">
    Turn on **Advanced Customisation** for granular control. The left navigation includes **Layout and Typography**, **Header**, and **Buttons**.

    <img alt="Advanced customisation" />

    ### Layout and typography

    Use this section to control the overall structure and text styling of the checkout page.

    * **Corner radius:** Use the slider or numeric field to set the corner radius for applicable UI elements. A value of `0` produces square corners; higher values increase rounding.

    * **Primary text colour:** Enter a hex code for the most prominent text on the checkout page, such as headings and key labels.

    <Warning>
      If the colour you choose does not meet contrast requirements against the checkout background or card colours, the dashboard displays an inline warning. Adjust the colour to keep text easy to read.
    </Warning>

    * **Secondary text colour:** Enter a hex code for supporting text, such as descriptions and secondary labels.

    <Warning>
      The dashboard checks secondary text for contrast as well. If a warning appears, change the colour to improve readability.
    </Warning>

    ### Header

    The header is the top section of the checkout page and displays your brand identity.

    * **Logo:** Enter the URL of your brand logo. This is the same **Logo** field as in basic configuration. To remove the logo, select the **×** icon.

    * **Header colour:** Enter a hex code for the header background. Select the reset control to return to the default.

    * **Header text colour:** Enter a hex code for text displayed in the header.

    <Warning>
      If the header text and header background colours do not meet contrast standards, the dashboard displays an inline warning. Adjust one or both colours until the warning clears.
    </Warning>

    * **Brand display:** Choose how your brand appears in the header:

      * **Show Both Logo and Name:** Displays both the logo image and the brand name.
      * **Show Logo Only:** Displays only the logo image.
      * **Show Name Only:** Displays only the brand name as text.

    Once Cashfree reviews and approves your brand name update request, you will see **Verified Successfully** under **Visual Customisation > Header** in the Merchant Dashboard.

    ### Buttons

    Buttons let customers perform actions on the checkout page. There are three button types, listed in order of emphasis.

    #### Primary buttons

    Primary buttons use a solid fill and represent the most important actions, such as completing a payment.

    * **Active primary button:** Active buttons are selectable by the customer and can inherit your primary brand colour.
      * **Button colour:** Background colour of the active primary button.
      * **Text colour:** Label colour of the active primary button.

    <Warning>
      If the label and background colours fail contrast checks, the dashboard displays an inline warning. Adjust the colours to keep the label readable.
    </Warning>

    * **Disabled primary button:** Disabled buttons are visible but unavailable while an action cannot be performed.
      * **Button colour:** Background colour of the disabled primary button.
      * **Text colour:** Label colour of the disabled primary button.

    #### Secondary buttons

    Secondary buttons are outlined and represent the next most important actions.

    * **Active secondary button**

      * **Text colour:** Label colour of the active secondary button.
      * **Border colour:** Outline colour of the active secondary button.

    <Warning>
      If the text colour fails contrast checks against the checkout page background, the dashboard displays an inline warning. Adjust the colour as needed.
    </Warning>

    * **Disabled secondary button**

      * **Text colour:** Label colour of the disabled secondary button.
      * **Border colour:** Outline colour of the disabled secondary button.

    #### Tertiary buttons

    Tertiary buttons are text only, with no fill or border, and are used for lower-emphasis actions.

    * **Active tertiary button:** Active tertiary buttons are selectable and can inherit the primary brand colour.

      * **Text colour:** Label colour of the active tertiary button.

    * **Disabled tertiary button:** Disabled tertiary buttons are visible but unavailable while an action cannot be performed.

      * **Text colour:** Label colour of the disabled tertiary button.

    #### Button shadow

    Turn on **Button Shadow** to add a drop shadow to buttons. Enter a hex colour code for the shadow to add depth to button elements on the checkout page.
  </Tab>
</Tabs>

## FAQs

<AccordionGroup>
  <Accordion title="Where can I check the status of my brand name update request?">
    Once your brand name update request is reviewed and approved, the status shows as **Verified Successfully** in the Merchant Dashboard under **Visual Customisation > Header**.
  </Accordion>
</AccordionGroup>


# Integrations
Source: https://www.cashfree.com/docs/payments/checkout/integration-one-click-checkout

Integrate Cashfree One Click Checkout on Shopify, a custom website, or your mobile app using step-by-step platform guides covering OTP login, COD, and offers.

Select the integration workflow for your platform to set up Cashfree One Click Checkout (OCC).

* **Shopify**: Add One Click Checkout to your Shopify store with OTP sign-in, pre-filled address details, UPI and card payments, cash on delivery (COD), and abandoned cart recovery..
* **Custom website**: Enable One Click Checkout on your existing Cashfree integration by extending the [Create Order API](/docs/api-reference/payments/latest/orders/create-order) and retrieving order details after payment.
* **Mobile app**: Extend One Click Checkout to your Shopify mobile app using the native Cashfree extension in Appmaker.

<Warning>
  Ensure the One Click Checkout product is activated. To activate it, **Log in** to the **[Merchant Dashboard](https://merchant.cashfree.com/auth/login)** and go to **Payment Gateway > PG Products > One Click Checkout**.
</Warning>

<Tabs>
  <Tab title="Shopify">
    Complete setup in the following phases:

    | Phase | Description |
    | - | - |
    | **Onboarding** | Send your Shopify collaborator request code to the Cashfree team. You will receive an app installation link within 48 hours. |
    | **Installation** | Install the Cashfree OCC app using the link, then connect it to your **[Merchant Dashboard](https://merchant.cashfree.com/auth/login)**. |
    | **Theme configuration** | Add a Cashfree snippet to your `theme.liquid` file to activate the checkout experience. |

    Before launching, configure shipping rules, COD settings, discounts, and branding in the **[Merchant Dashboard](https://merchant.cashfree.com/auth/login)**.

    Follow these steps to onboard and activate One Click Checkout (OCC) on your Shopify store.

    ### Prerequisites

    Before proceeding with the installation, complete the following steps:

    1. Complete the [Cashfree support form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) or contact your account manager.
    2. Create and share the collaborator request code. Use these steps:

       1. **Log in** to your Shopify store using your admin credentials.

       2. Navigate to **Settings > Users and permissions**.

       3. Scroll down to the **Collaborators** section and copy the collaborator request code.

       4. Share your Shopify store URL.

    <Note>
      To approve a collaborator request in Shopify: log in to your Shopify Admin dashboard, navigate to **Settings > Users and Permissions**, scroll to the **Collaborators** section, and click **Review requests** to view pending requests. Select the specific request, check the permissions under the **Roles** section, and approve the request. If you see an error stating "The role name already exists", delete the auto-generated role and assign an existing one instead.
    </Note>

    3. Within 48 hours, you receive an app installation link, dashboard details, and setup instructions from Cashfree at your registered email address.

    ### Installation

    To install the OCC app on Shopify:

    1. Open the installation link, then **Log in** to Shopify to complete the installation.

    2. Shopify redirects you to the **[Merchant Dashboard](https://merchant.cashfree.com/auth/login)** to finalise the installation.

    3. To confirm the installation, check the installed apps in Shopify. The app should be listed as `cashfree-occ-<brand>`.

    4. You can now access your One Click Checkout dashboard.

    <Frame>
      <video>
        <source type="video/mp4" />

        Your browser does not support the video tag.
      </video>
    </Frame>

    ### Configure theme

    Follow these steps to configure checkout on Shopify:

    1. **Log in** to Shopify using your credentials.

    2. Navigate to **Sales channels > Online Store > Themes**.

    3. Select the ellipsis (⋮) next to the live theme, then select **Duplicate** to create a copy.

    4. Select the ellipsis (⋮) next to the duplicated theme, then select **Edit code**.

    5. Search for and open the `theme.liquid` file.

    6. Add the following code before the `</head>` tag:

       ```liquid theme={"dark"}
       {% render 'cashfree' %}
       ```

    7. Select the ellipsis (⋮) next to the duplicated theme, then select **Preview**. Review and confirm the checkout.

    8. Select **Publish** to set the updated theme as live.

    <Frame>
      <video>
        <source type="video/mp4" />

        Your browser does not support the video tag.
      </video>
    </Frame>

    <Note>
      OCC setup is specific to your Shopify theme. If you change your store's theme, fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) to have Cashfree re-configure One Click Checkout on the new theme. International order redirection also needs separate re-configuration on the new theme.
    </Note>

    ## Frequently asked questions

    For answers to common questions about COD and shipping profile setup, Shopify conversion-data syncing, and native checkout fallback scenarios, see the [One Click Checkout FAQs](/docs/payments/checkout/one-click-checkout-faq).

    To verify your configuration before launch, complete the [Go Live Checklist](/docs/payments/checkout/checklist).

    If you have questions about the Shopify integration, submit a request through the [Cashfree support form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1).

    1. **Order Creation Requirements**: Ensure the following parameters are passed when [creating an order](/docs/api-reference/payments/latest/orders/create-order):
  </Tab>

  <Tab title="Custom website">
    Complete setup in the following phases:

    | Phase | Description |
    | - | - |
    | **Create order** | Add `products.one_click_checkout` and `cart_details` so the checkout session includes OCC features and cart line items. |
    | **Order details** | After payment, call the [Get Order Extended API](/docs/api-reference/payments/latest/orders/get-order-extended) for customer context, addresses, and applied offers. |

    <Info>
      You must have an existing Cashfree web or app checkout integration before enabling OCC. If you haven't set one up, see [Cashfree Checkout Integration Overview](/docs/payments/overview).
    </Info>

    Before launching, validate Create Order payloads and extended order handling in Sandbox, then replicate the same configuration in Production.

    Follow these steps to add OCC fields to order creation and to retrieve extended order data after payment:

    1. **Add OCC parameters to the [Create Order API](/docs/api-reference/payments/latest/orders/create-order) request**

       Include the following two additional objects in the Create Order API request:

       * **`products.one_click_checkout`**: Enables OCC and specifies which features to allow, such as address collection and authentication.
       * **`cart_details`**: Provides cart item information to populate the checkout summary.

       ```bash title="Request sample" theme={"dark"}
       curl --location 'https://sandbox.cashfree.com/pg/orders' \
       --header 'X-Client-Id: {{clientId}}' \
       --header 'X-Client-Secret: {{clientSecret}}' \
       --header 'x-api-version: 2025-01-01' \
       --header 'Content-Type: application/json' \
       --header 'Accept: application/json' \
       --data '{
           "order_amount": 1,
           "order_currency": "INR",
           "customer_details": {
               "customer_id": "USER123",
               "customer_name": "Joe Smith",
               "customer_email": "joe.s@cashfree.com",
               "customer_phone": "+919999999999"
           },
           "order_meta": {
               "return_url": "https://yourwebsite.com/payment/return?order_id={order_id}"
           },
           "products": {
               "one_click_checkout": {
                   "enabled": true,
                   "conditions": [
                      {
                          "action": "ALLOW",
                          "values": [
                              "checkoutCollectAddress",
                              "checkoutAuthenticate"
                          ],
                          "key": "features"
                      }
                  ]
               }
           },
           "cart_details": {
               "cart_items": [
                   {
                       "item_id": "cart_id_1",
                       "item_name": "T Shirt",
                       "item_description": "Test Description",
                       "item_details_url": "https://example.com/product/t-shirt",
                       "item_image_url": "https://example.com/product/t-shirt.jpg",
                       "item_original_unit_price": 1,
                       "item_discounted_unit_price": 1,
                       "item_quantity": 1,
                       "item_currency": "INR"
                   }
               ]
           }
       }'
       ```

       In the example above, note the following key parameters:

       * `products.one_click_checkout.enabled`: Set to `true` to enable OCC.
       * `conditions.values`: Specify the features to allow, such as `checkoutCollectAddress` and `checkoutAuthenticate`.
       * `cart_details.cart_items`: Specify the product information to display in the checkout summary.

    2. **Retrieve extended order details**

       Use the [Get Order Extended API](/docs/api-reference/payments/latest/orders/get-order-extended) endpoint after payment to fetch OCC-specific data. The response includes:

       * **Customer details**: Information about the logged-in user.
       * **Shipping and billing addresses**: Recipient details collected during checkout.
       * **Applied offers**: Discounts applied at the time of payment.

       <Note>
         The `customer_details` object identifies the logged-in user who placed the order. The `shipping_address` object identifies the delivery recipient. These values may differ if the customer enters a different delivery address during checkout.
       </Note>
  </Tab>

  <Tab title="Mobile app">
    Complete setup in the following phases:

    | Phase | Description |
    | - | - |
    | **Onboarding** | Send your collaborator request code to the Cashfree team. You will receive an app installation link within 48 hours. |
    | **Installation** | Install the Cashfree OCC app using the link, then connect it to your **[Merchant Dashboard](https://merchant.cashfree.com/auth/login)**. |
    | **Configuration** | Set **Environment** to **Production**, save changes, and create a new app build so customers receive the updated checkout behaviour. |

    Before launching, confirm the Shopify OCC app is connected in the **[Merchant Dashboard](https://merchant.cashfree.com/auth/login)** and verify checkout in a staging build where possible.

    Follow these steps to install the extension, configure the Production environment, and create a new build:

    1. In the [Appmaker Dashboard](https://partners.appmaker.xyz), go to **Extensions**.
       <Frame>
         <img alt="Appmaker Dashboard showing the Extensions menu" />
       </Frame>
    2. Search for and select **Cashfree One Click Checkout**.
       <Frame>
         <img alt="Search results showing the Cashfree One Click Checkout extension in Appmaker" />
       </Frame>
    3. Select **Install and activate** in the top-right corner.
    4. Open the **Settings** tab and set **Environment** to **Production**.
    5. Select **Save Changes**.
       <Frame>
         <img alt="Cashfree One Click Checkout settings tab with Environment set to Production" />
       </Frame>
    6. Create a new app build for the changes to take effect.

    <Note>
      To track in-app purchase analytics, set up Firebase and install the **Firebase Extension** in Appmaker. See the [Firebase Extension documentation](https://docs.appmaker.xyz/docs/Extensions/firebase/) for setup steps.
    </Note>

    For more information, see the [Appmaker documentation](https://docs.appmaker.xyz/docs/integrations/Cashfree/).
  </Tab>
</Tabs>

<snippet>snippets/related-topics-loader.mdx</snippet>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/payments/latest/orders/create-order">Create Order API</a></li>
    <li><a href="/docs/api-reference/payments/latest/orders/get-order-extended">Get Order Extended API</a></li>
    <li><a href="https://docs.appmaker.xyz/docs/integrations/Cashfree/">Appmaker Cashfree One Click Checkout</a></li>
  </ul>
</div>


# Managing Cash on Delivery
Source: https://www.cashfree.com/docs/payments/checkout/managing-cod

Manage Cash on Delivery in Cashfree One Click Checkout, the dominant Indian ecommerce method, by configuring rules, blacklists, and RTO controls in one place.

COD is the most widely used payment method in Indian e-commerce, accounting for **over 70% of orders** for several businesses. By allowing customers to pay only upon delivery, COD builds trust, especially among consumers new to your brand or to online shopping.

## How COD works with Cashfree

With Cashfree, COD is simple to set up and manage. Here's how it works:

1. **Order completion**: The customer selects COD at checkout, and Cashfree records the transaction with a status of `SUCCESS` for the payment mode Cash on Delivery.

2. **Status update**: Shopify marks the order status as `PENDING`. For custom integrations, you can check the order status using webhooks and update accordingly.

<Note>
  Cashfree **does not provide** services for physically collecting cash payments
  from customers.
</Note>

## Managing COD with Cashfree

Cashfree enhances COD with flexible management options to suit your business needs:

1. **Add or remove fees**:
   Adjust COD fees directly through the Cashfree Dashboard, allowing you to add a convenience fee or waive it based on your strategy.

2. **Set restrictions**:
   Customise COD availability by blacklisting specific pincodes, customers (based on phone numbers), or products. This ensures COD is only offered where it aligns with your business goals.

3. **RTO Intelligence**:
   Cashfree’s RTO Intelligence analyses historical shipping data and hides COD for high-risk customers automatically.

4. **Unified payment tracking**:
   Track both COD and online payments from one dashboard, using Cashfree’s analytics tools to gain deeper insights.

## Setting up cash on delivery

### Step 1: Displaying COD on checkout

1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
2. Navigate to **Payment Gateway > PG PRODUCTS > One Click Checkout** page to activate it for your account.
3. Navigate to the **COD & RTO** section, and set the amount range where COD should be available. You can also set a convenience fee for COD here.

### Step 2: Set restrictions on COD

1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
2. Go to **COD & RTO > Blacklisting**.
3. Choose to blacklist pincodes, customer phone numbers or products.
4. You can add individual entries or upload a bulk list of pincodes, customer phone numbers, or products.
   * For products, ensure the product identifier matches that in your Shopify store.
   * For custom integrations, pass the same identifier as `item_id` while creating an order with Cashfree.

### Step 3: Enabling RTO Intelligence

1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
2. Go to **COD & RTO > Configurations > Enable RTO Intelligence**.
3. Enter your shipping company and credentials so that Cashfree can fetch shipping details and improve your overall RTO Intelligence.

## Integrating COD with One Click Checkout

1. **Shopify integration**: Follow the steps to set up One Click Checkout on Shopify.
2. **Custom integration**: For custom integration follow the steps here.

<Warning>
  Ensure to check order status and details for Cash on Delivery using
  [webhooks](/docs/api-reference/payments/latest/payments/webhooks) or [status APIs](/docs/api-reference/payments/latest/orders/get-order) to
  keep the order status updated.
</Warning>


# Managing Offers
Source: https://www.cashfree.com/docs/payments/checkout/offers

Create Cashfree promotional discounts, cashbacks, no-cost EMIs, and incentives to lift sales, average order value, and customer acquisition for your store.

Offers are promotional incentives you can create to encourage customer purchases and boost sales. These include discounts (flat or percentage-based), cashbacks, free gifts, and special financing options like no-cost EMI.

You can set up offers to automatically apply at checkout, appear as selectable options for customers, or require coupon codes. Each offer can be targeted to specific customer segments, payment methods, or product categories to maximise effectiveness.

The Cashfree Offers Engine helps you create and manage these promotions from a unified dashboard, with proven results including up to 30% higher checkout conversions and improved customer acquisition cost (CAC) and customer lifetime value (LTV).

## Key features

The Cashfree Offers Engine provides the following capabilities to enhance your promotional strategies:

* **Flexible offer constructs**: Build over 300 types of offers including free gifts, prepaid discounts, cashbacks, and No Cost EMIs.
* **Smart offer visibility**: Automatically surface the best value offer to customers on the checkout page (eliminating manual code entry), boosting conversions by up to 25%.
* **Unified dashboard control**: Create and manage all offers from a single view with advanced targeting, velocity checks, and upper caps to manage discount burn.
* **Deep Shopify integration**: Full support for stacked discounts, automatic Shopify discounts, Buy X Get Y (BxGy), and product/collection level discounts directly synced with Shopify.

## Benefits

Implementing a strategic offer programme delivers immediate business value through the following outcomes:

| Benefit | Description |
| - | - |
| Improve conversion rates | Incentivise purchase completion to boost checkout conversion by approximately 25%. |
| Increase Average Order Value (AOV) | Drive higher cart values through threshold-based discount structures and EMI options. |
| Boost prepaid share | Run specific discounts on prepaid methods to reduce Cash on Delivery (COD) risk and costs and improve prepaid share to 65%. |
| Targeted marketing | Precise targeting based on customer behaviour, segments, and payment methods. |
| Build loyalty | Encourage repeat behaviour through cashbacks and exclusive bank offers. |

## Supported offer types

You can configure a wide variety of offers to suit different inventory and sales goals. The following offer types are available:

* **Order level discounts**: Run flat discounts such as ₹100 off or percentage discounts such as 10% off. You can set a maximum discount cap to control burn.
* **Product and collection discounts** (Only via Shopify): Target specific items or collections to clear inventory or promote new arrivals.
* **Prepaid discounts**: Exclusive discounts applied only when a customer selects a prepaid payment method. This is highly effective for reducing Return to Origin (RTO) by discouraging COD.
* **Cashbacks**: Customers receive money back in their source account or wallet after a successful purchase. This builds loyalty and encourages repeat purchases.
* **Free gift on cart**: Customers receive complementary products when cart conditions such as "Spend ₹2000" are met. This increases perceived value and clears inventory without devaluing the primary product.
* **Buy X Get Y** (Only via Shopify): Customers receive additional items at discounted rates or for free when purchasing specified quantities. Increases order quantity and moves bulk inventory.
* **No Cost EMI**: Customers purchase high-value items on EMI without bearing the interest cost (merchant bears the interest). Enables aspirational purchases and significantly increases Average Order Value (AOV).

## Offer targeting and conditions

To prevent excessive discounting and ensure the right offers reach the right users, you can apply strict conditions through the following mechanisms:

### Customer and velocity controls

Use these controls to manage offer usage and prevent abuse:

* **Customer segments**: Restrict offers to specific segments of customers (list of customers to be uploaded).

Apply the following velocity checks to manage offer usage:

* **Customer velocity**: Limit how many times a user can redeem an offer within a specific timeframe.
* **Card velocity**: Track usage per card to prevent abuse of bank-specific offers.
* **Redemption limits**: Set a global "Upper Cap" on the total number of times an offer can be used across the entire site.
* **Day restrictions**: Limit offers to specific days of the week such as "Wednesday Sale" or specific hours (Flash Sales).

### Payment and bank identification targeting

Target offers based on the specific financial instrument used through these options:

**Payment locking:**  Configure payment locking using these options:

* **Prepaid only**: Lock offers to exclude COD.
* **Method specific**: Restrict offers to specific payment groups such as UPI only, Credit Card only.

**Bank Identification Number (BIN) based offers:** Target specific card types using these options:

* **Issuer**: Create exclusive offers for specific banks such as HDFC, ICICI.
* **Network**: Target specific networks such as Visa, Mastercard, RuPay.

## Checkout experience

You can control how offers are presented to the customer during the payment process using these visibility options:

* **Auto applied**: The offer is applied automatically to eligible carts without manual intervention. Best for seamless UX.
* **Listed on checkout**: Available offers are listed on the payment page. The engine highlights the "Best Value" offer to the customer for one-click redemption. You can import and sync Shopify discounts if you want these discounts to be listed on checkout.
* **Hidden (Coupon Code)**: The offer is invisible on the checkout UI. The customer must manually enter a code shared via marketing channels (Email/SMS).

<Note>
  **Offer combination**: Only one offer created on Cashfree can be applied per order. However, one or more Shopify-created offers can be applied simultaneously based on the combination setup done on Shopify.
</Note>

<Frame>
  <img />
</Frame>

## Setting up offers

You can create offers through two methods:

* [Using the Merchant Dashboard](#offer-creation-through-merchant-dashboard).
* [Using API](#api-based-creation).

### Offer creation through merchant dashboard

The merchant dashboard provides an intuitive workflow for merchants. Follow these steps to create an offer:

<Steps>
  <Step title="Access offers and create new offer">
    1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com).
    2. Go to **Payments > One Click Checkout > Offers**.
    3. Select **Create Offer** to start the offer creation process.
  </Step>

  <Step title="Select offer type">
    Select the type of offer based on your promotional strategy:

    * Discount on order value
    * Discount on products
    * Cashback on order value
    * Cashback on products
  </Step>

  <Step title="Define offer details">
    Define the offer details such as flat discount or percentage, then select **Next**.
  </Step>

  <Step title="Configure offer conditions">
    Define the offer conditions such as:

    * Customer selects an offer.
    * Customer enters offer code.
    * Auto apply the offer.

    Set the customer eligibility and usage limit, redemption limit for this offer and select **Next**.
  </Step>

  <Step title="Set validity dates">
    Define the offer validity dates from the available calendar.
  </Step>

  <Step title="Confirm and activate">
    Select **Confirm Offer** to make the offer live for customers.
  </Step>
</Steps>

<Frame>
  <img />
</Frame>

#### Importing Shopify discounts

If you are using Shopify, you can import existing discounts directly into the Cashfree Offers Engine to synchronise them with your checkout page.

1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
2. Navigate to **Payments > One Click Checkout > Offers**.
3. Select **Import from Shopify**.
4. Enter the Shopify discount code and select the **Add** button.
5. The system imports the Shopify discount and lists it in the Offers section.

<Frame>
  <img />
</Frame>

### API-based creation

For custom checkout flows and advanced integrations, offers can be managed programmatically using the following APIs:

* **[Create Offer API](/docs/api-reference/payments/latest/offers/create-offer)**: Set up new offers with complex configurations.
* **[Get Offer API](/docs/api-reference/payments/latest/offers/get-offer-by-id)**: Retrieve offer details, status, and validity in real-time.

<snippet>snippets/related-topics-loader.mdx</snippet>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/payments/latest/offers/create-offer">Create Offer API</a></li>
    <li><a href="/docs/api-reference/payments/latest/offers/get-offer-by-id">Get Offers API</a></li>
    <li><a href="/docs/payments/checkout/one-click-checkout">One Click Checkout</a></li>
    <li><a href="/docs/payments/checkout/offers/no-cost-emi">No Cost EMI Overview</a></li>
  </ul>
</div>


# No Cost EMIs
Source: https://www.cashfree.com/docs/payments/checkout/offers/no-cost-emi

Use Cashfree No Cost EMIs to let shoppers split payments into interest-free monthly instalments while you cover the financing cost to lift average order value.

No Cost EMI lets customers split payments into monthly instalments without interest, with merchants covering the interest cost.

### Benefits

The benefits of No Cost EMI offered by Cashfree are as follows:

* **Increased sales**: Appeals to price-sensitive customers.
* **Higher conversion**: Reduces upfront cost barriers.
* **Competitive advantage**: Differentiates your business with flexible payment options.

### Setting up no cost EMI

Steps to set up No Cost EMI are as follows:

1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login), go to **Offers**, and select **Create No Cost EMI**.
2. Add a **Title**, **Offer Code**, and **Description**.
3. Set the **Start and End dates** from the calendar dropdown.
4. Define the **Terms & Conditions** to avail No Cost EMI.
5. Select the **EMI type**. That is Credit card, Debit Card EMI or Cardless EMI, participating banks, and duration. For example: 3, 6 or 9 months.
6. Set the **Transaction limits** to avail the No Cost EMI. Limit the number of times the offer can be availed and ensure the offer is active for customers.

<Frame>
  <img />
</Frame>

### Customer view of no cost EMI

At checkout, customers select **No Cost EMI**, pick their bank and duration, then proceed with payment. The total is divided into monthly instalments without interest.

<Note>
  **Note**:

  * It is the responsibility of the Merchant to cover the interest cost as an upfront discount.
  * Some banks may still charge GST on the interest component.
  * Ensure agreements with banks are in place before enabling the No Cost EMI.
</Note>


# Offers FAQs
Source: https://www.cashfree.com/docs/payments/checkout/offers/offers-faqs

Find answers to common questions about creating, targeting, and combining Cashfree checkout offers including discounts, cashbacks, no-cost EMIs, and codes.

<AccordionGroup>
  <Accordion title="What is the Offers Section in Merchant Dashboard?">
    Boost Sales with Discounts & Cashback! Attract customers, increase AOV, and drive conversions with easy-to-set-up offers.
    Cashfree lets you create discounts and cashback deals across multiple payment methods for a seamless shopping experience.
    See [overview of offers](/docs/payments/checkout/offers) to know more

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How can I create and show offers to my customers on checkout?">
    Offer discounts and cashback to attract customers and improve sales when they make payments on your website or apps. You can specify different offers on various payment methods and give your customers the flexibility to pay from the payment method they choose.

    When you create the offers, you can:

    * Specify the offer code and offer type (Discount or Cashback).

    * Select the payment methods on which the offers should be applicable.

    * Reduce the total amount a customer pays by a percentage or a flat amount.

    * Specify the maximum number of transactions allowed per payment method.

    * Define the offer validity period.

    * View a consolidated report for each offer you created.

    Offers will automatically be applicable for businesses using Cashfree hosted checkout pages and plugins, and no additional integration effort is required. You can create Offers using our Payment Gateway Dashboard.
    **Create Offers**

    **To create an offer:**

    1. Go to **Payment Gateway Dashboard > Offers > Create New Offer**.

    2. Specify the offer details:

    * Enter a title for the offer that the customers can relate to.

    * Add an offer code and an offer description. These details will be visible to customers on your checkout page or plugin during payment.

    3. Specify the offer's start and end dates and its terms and conditions:

    * You can link your business's terms and conditions or add a short description.

    4. Select the offer category that applies to your business:

    * Provide discounts, cashback, or both to your customers.

    5. Select the discount type:

    * Provide discounts at a flat rate or as a percentage.

    * Specify the maximum discount amount or discount percentage for the selected type.

    6. Select the payment modes for which the offers apply:

    * Choose all or specific payment modes.

    * Optionally, specify the banks and card types relevant to the offer.

    * Click **Create**.

    The offer is now active and available in the **Offers** section. You can activate or deactivate the offer at any time.

    **Offers Shown to Customers**

    When customers initiate a payment, all available offers are listed on your checkout page. Offer details like the description and code will be visible to customers, so ensure you clearly explain your offer's context using these fields.

    Customers can select an offer and proceed with the payment. The reduced amount is displayed on the checkout page, and the customer completes the payment with the final amount.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How to create No Cost EMI offer on Cashfree?">
    Log in to **Cashfree** > **Offers** > **Create No-Cost EMI**
    Enter Details – Add a title, offer code, and description.
    Set Timeline – Define start and end dates.
    Choose EMI Options – Select credit/debit card EMI, banks, and duration (3, 6, 9 months).
    Set Limits – Control how many times the offer can be used.
    Activate – Ensure the offer is live for customers.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I deactivate a running offer anytime?">
    Yes, you can deactivate an offer at any point in time. To change the status of
    an offer, select the toggle button in the **Status** (Active/Inactive). Click
    on a particular offer to view the offer details. You can **Deactivate** the
    ongoing offer, and if you want to create a similar offer, select the
    **Duplicate** option.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Do I need any additional integration to use offers?">
    Offers will automatically be applicable for businesses using Cashfree hosted checkout pages and plugins, and no additional integration effort is required. You can create Offers using our Payment Gateway Dashboard. Merchants who are using the upfront TDR model will not be allowed to create offers.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How can I highlight a prepaid discount offer during checkout?">
    To highlight an offer on the checkout page, create an automatic or manual offer in the Merchant Dashboard without restricting payment methods. Restricting payment methods prevents the offer from being highlighted at checkout. Also confirm that the offer banner is turned on in the Merchant Dashboard. A disabled offer banner can hide automatic and manual offers from customers. See [Checkout experience](/docs/payments/checkout/offers#checkout-experience).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How can I prevent multiple discount codes from being stacked with a Cashfree prepaid offer?">
    To prevent stacking, create non-combinable offers on Shopify. Cashfree-created offers (such as PREPAID10) cannot be combined with other discounts created within the Cashfree system. Setting the Shopify offer to be non-combinable ensures it will not stack with other Shopify-based discounts, while the Cashfree offer remains applicable.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What is the prerequisite for enabling Snapmint on my Cashfree account?">
    One Click Checkout (OCC) is a prerequisite for enabling Snapmint. You must have OCC enabled on your account before Snapmint activation can proceed.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How do I stop an old discount code from being applied by customers?">
    If you have discontinued a marketing campaign or an offer, you must disable or inactivate the offer on both the Shopify dashboard and the Merchant Dashboard to prevent customers from using the discount code.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How do I complete the Snapmint setup on Cashfree?">
    To complete Snapmint setup, submit a request through the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Why am I unable to find a One Click Checkout (OCC) order when searching by customer email or phone number?">
    For One Click Checkout (OCC) transactions, searching by customer email or phone number may not always yield results because a dummy email might be passed during the transaction flow. Search using the Cashfree Order ID or Transaction ID instead.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I delete a paused offer on the Merchant Dashboard?">
    Offers can be inactivated on the Merchant Dashboard. If the offer was created via Shopify, it should be deleted on the Shopify dashboard.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Why are offers appearing on my checkout page even though I have not created any discount coupons?">
    The offers displayed on the checkout page may be offers that Cashfree funds directly. These offers are enabled by default and are displayed to all eligible merchant accounts, so the offers section can appear even if you have not created any coupons or offers yourself.
  </Accordion>
</AccordionGroup>


# Shopify Discounts
Source: https://www.cashfree.com/docs/payments/checkout/offers/shopify

Apply Shopify discounts on Cashfree One Click Checkout without migration: combine codes, auto-apply offers, Buy X Get Y deals, and product-level discounts.

Cashfree's One Click Checkout fully integrates with Shopify’s discount system, so you don’t need to migrate your existing Shopify discounts. This integration supports various discount types, multiple discount combinations, and analytics capabilities.

<Note>
  * While creating an offer in Shopify, even if the 'Do not combine with other offers' option is selected, the order can still be combined with one applicable Cashfree offer.
  * Auto-applied offers created in Shopify will automatically be applied at checkout.
  * If a hidden offer is created through the Cashfree Merchant Dashboard, it will not be displayed at checkout, but can still be applied when the offer code is entered manually.
  * Offers created in Shopify will not appear in the offers section at checkout by default, but can still be applied if the offer code is entered manually.
</Note>

## Setting up the sales channel

For any Shopify discount to work with Cashfree Checkout, the **Cashfree-OCC-MerchantName** sales channel must be added to the discount.

### Adding the sales channel to new discounts

1. Log in to your [Shopify admin dashboard](https://admin.shopify.com/).
2. Navigate to **Products > Discounts**.
3. Click **Create discount**.
4. Set up your discount details (type, value, eligibility, etc.).
5. In the **Sales channels** section, click **Add sales channel**.
6. Select **Cashfree-OCC-MerchantName** from the dropdown.
7. Complete the discount setup and click **Save**.

### Adding the sales channel to existing discounts

1. Go to **Products > Discounts** in your Shopify admin.
2. Find and click the existing discount you want to enable.
3. Scroll to the **Sales channels** section.
4. Click **Add sales channel**.
5. Select **Cashfree-OCC-MerchantName**.
6. Click **Save** to apply the changes.

<Warning>
  For automatically applied discounts, you must delete the existing offer and
  recreate it with the **Cashfree-OCC-MerchantName** sales channel added. Simply
  editing the existing automatic discount will not enable it for One Click
  Checkout.
</Warning>

## Discount application methods on checkout

### 1. Automatically applied discounts

Automatic Shopify discounts are applied at checkout without any customer action, provided the eligibility criteria are met.

**Customer flow:**

1. When a customer proceeds to checkout, eligible automatic discounts are applied instantly.
2. The discount amount is clearly shown in the order summary.
3. The final order total reflects the reduced amount.
4. Customers can see which items received the discount.

### 2. Manual discount codes

Customers can enter discount codes during checkout starting from the login page.

**Customer flow:**

1. On the Cashfree checkout page, customers will see an **Offers** section.
2. Clicking this reveals a text field.
3. The customer enters the discount code and clicks **Apply**.
4. If valid, the discount is applied instantly to the order.
5. The order summary updates to show the discounted amount.

<Note>For customer-specific or segment-specific discounts, customers must be logged in to apply the discount code. The system will verify their eligibility before applying the discount.</Note>

<Frame>
  <img />
</Frame>

### 3. Displaying Shopify offers on checkout

Merchants can highlight specific offers directly on the checkout page to increase visibility and conversions.

**Importing Shopify offers:**
To import Shopify offers, follow the below steps:

1. Create offers in Shopify and ensure each has the **Cashfree** sales channel added.
2. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
3. Go to Payment Gateway > PG Products > One Click Checkout > Offers and Promotions.
4. On the Offers and Promotions modal, click Create Offer and select Import Shopify Offer.
5. View the imported offer details and summary.

**Requirements:**

* Each featured offer must have the Cashfree sales channel configured.
* The offer must not be an automatic discount.
* The offer should not be created via a third-party app.
* The offer must not include customer-level eligibility conditions.

**Customer flow:**

1. Featured offers appear prominently on the checkout page.
2. Customers can view available discounts without searching.
3. Eligible automatic discounts are already applied.
4. Manual discounts can be applied with a single click.

## Multiple offer support

Cashfree supports applying multiple Shopify discounts to a single order, enabling flexible discount strategies.

**Setting up multiple offer support in Shopify:**

1. For a given discount, under **Combinations**, select applicable combinations with order, product, or shipping discounts.
2. Add the Cashfree sales channel to each discount.
3. Click **Save**.

## Cross-platform combinations:

* Offers created on Cashfree can always be combined with Shopify offers.
* This allows for complex discount strategies using both platforms.
* Example: A Shopify 10% product discount can be combined with a Cashfree ₹100 order discount.

<Frame>
  <img />
</Frame>

## Reporting and analytics

For each order in Shopify, you can view:

* Applied discounts
* Discount amount
* Final order amount
* Discount analytics will no longer be available in Shopify. Instead, use the Cashfree Dashboard.
* Download transaction reports with offer or No-cost EMI data from the Cashfree Dashboard. These reports include:
  * Offer ID
  * Offer Code
  * Offer Title
  * Offer Type
  * Offer Terms and Conditions
  * Offer Description
  * Redemption Amount

## Troubleshooting

Having trouble with discounts at checkout? Here are some common issues and quick ways to fix them.

### Discounts not appearing at checkout

* Verify that the **Cashfree-OCC-MerchantName** sales channel is added.
* For automatic discounts, ensure they were newly created (not just edited).
* Confirm that all discount eligibility criteria are satisfied.
* Check that the discount's activation dates are valid.

### Multiple discounts not combining

* Ensure all discounts are set to be combinable in Shopify.
* Look for conflicting discount conditions.
* Confirm that order minimums are still met after the first discount is applied.

### Customer-specific discounts not working

* Ensure the customer is logged in.
* Verify that the customer belongs to the correct segment or group.
* Double-check for typos in manually entered discount codes.

## Limitations

* Offers created by third-party Shopify apps cannot be imported or displayed in Cashfree Checkout.
* Customer-level or segment-specific offers cannot be featured upfront at checkout.
* Discounts with usage limits are not supported.

## FAQs

<AccordionGroup>
  <Accordion title="How can I apply an offer when any one of several specified products is in the cart?">
    Create the offer directly in Shopify and then import it into Cashfree. To do this, navigate to **One Click Checkout > Offers > Import from Shopify** in the [Merchant Dashboard](https://merchant.cashfree.com/auth/login). Once imported, the offer will be visible on the One Click Checkout offers banner.
  </Accordion>

  <Accordion title="How can I restrict a Buy 1 Get 1 (BOGO) offer to prepaid orders only?">
    To restrict a BOGO offer to prepaid orders, you must first create it as a manual discount code in Shopify. Then import it into Cashfree by navigating to **One Click Checkout > Offers > Import from Shopify** in the [Merchant Dashboard](https://merchant.cashfree.com/auth/login). Once imported, share the Offer ID or Offer Code via the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) to have it configured to exclude Cash on Delivery (COD).

    Note that automatic discounts and customer segment-based offers cannot be imported for this configuration.
  </Accordion>
</AccordionGroup>


# One Click Checkout
Source: https://www.cashfree.com/docs/payments/checkout/one-click-checkout

Cashfree One Click Checkout transforms ecommerce checkout into a single seamless flow with login, address prefill, COD intelligence, and offers built in.

Transform your checkout into a seamless one-click experience with Cashfree. This end-to-end solution revolutionises the entire payment journey, from customer login to final confirmation.

<CardGroup>
  <Card title="Complete checkout automation" icon="cart-shopping" href="/docs/payments/checkout/address-prefill">
    Instant OTP verification and smart address pre-filling from 100M+ saved addresses.
  </Card>

  <Card title="Maximised conversions" icon="chart-line-up" href="/docs/payments/checkout/cart-recovery">
    25% faster checkout completion and abandoned cart recovery tools.
  </Card>

  <Card title="Reduced returns (RTO)" icon="box-check" href="/docs/payments/checkout/managing-cod">
    AI-powered risk assessment for COD orders, customisable pincode blocking, and phone number and product ID filtering.
  </Card>

  <Card title="Brand-perfect experience" icon="palette" href="/docs/payments/checkout/customise-checkout">
    Fully customisable interface with flexible payment method sorting and display.
  </Card>
</CardGroup>


# One Click Checkout FAQs
Source: https://www.cashfree.com/docs/payments/checkout/one-click-checkout-faq

Browse Cashfree One Click Checkout FAQs covering COD and shipping profile setup, Shopify conversion-data syncing, and native checkout fallback scenarios.

<AccordionGroup>
  <Accordion title="How can I set up COD and shipping profiles for One Click Checkout?">
    To configure these settings:

    1. Log in to the **[Merchant Dashboard](https://merchant.cashfree.com/auth/login)**.
    2. Go to **PG Products > One Click Checkout**.
    3. Select **[COD](https://merchant.cashfree.com/merchants/pg/one-click-checkout-activated/cod)** to configure your Cash on Delivery settings, select **COD & RTO** to configure RTO settings, or select **[Shipping & Delivery](https://merchant.cashfree.com/merchants/pg/one-click-checkout-activated/shipping-delivery)** to configure your shipping and delivery profiles.

    To view checkout event tracking and analytics, go to **[Checkout Analytics](https://merchant.cashfree.com/merchants/pg/developers/checkout-analytics)**.

    For a full configuration checklist, see the [Go Live Checklist](/docs/payments/checkout/checklist).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Does Shopify sync conversion data back to the Shopify dashboard when using One Click Checkout?">
    Shopify does not allow Cashfree to push conversion data back to the Shopify dashboard when One Click Checkout is active. Use the Merchant Dashboard for analytics insights, or use external tools such as Google Analytics to view your data.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Does One Click Checkout for Shopify forward custom cart attributes to the Abandoned Checkout webhook?">
    Cashfree One Click Checkout for Shopify forwards a fixed set of fields to the Abandoned Checkout webhook payload (such as `cart_token`, `abandoned_checkout_url`, and UTM parameters). It does not support forwarding arbitrary custom Shopify cart attributes into the webhook payload.

    To track custom data such as marketing consent, use `cart_token` or `cart_id` as a join key. Store the mapping of `cart_token` to your custom attribute on your server, and look up that mapping when the `ABANDONED_CHECKOUT` webhook is received.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Why are some of my Shopify orders being redirected to the native Shopify Checkout instead of Cashfree Checkout?">
    Orders may fall back to the native Shopify Checkout in the following scenarios:

    * **Inventory issues**: Unavailable inventory or items with zero quantity.
    * **Network interruptions**: Technical connectivity issues can cause the system to default to the native checkout flow.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Do I need to publish products to the Cashfree-OCC sales channel in Shopify?">
    No. The Cashfree-OCC sales channel does not need to be separately configured or published for individual products. Once One Click Checkout is activated and the required integration is configured, it applies to all eligible products by default.
  </Accordion>

  <Accordion title="I don't see OCC listed under Sales Channels in Shopify while updating products. Will it still work?">
    Yes. The One Click Checkout (OCC) integration works even if OCC is not visible as an option under Sales Channels while updating your products. When you activate OCC, it's added automatically, and you don't need to take any further action.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I make the email field non-mandatory in the One Click Checkout (OCC) flow?">
    No. Making the email field non-mandatory in the OCC flow is not currently supported.

    <iframe title="FAQs feedback component" />
  </Accordion>
</AccordionGroup>


# Managing Shipping and Delivery
Source: https://www.cashfree.com/docs/payments/checkout/shipping-managing-creation

Create and manage Cashfree One Click Checkout shipping rules from the Merchant Dashboard to automate delivery options and rates per customer location.

## Accessing the shipping and delivery section

1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
2. Go to the **PG PRODUCTS** section and select [One Click Checkout](https://merchant.cashfree.com/merchants/pg/one-click-checkout-activated/funnel-analytics).
3. Click on [Shipping & Delivery](https://merchant.cashfree.com/merchants/pg/one-click-checkout-activated/shipping-delivery/cashfree-shipping). You’ll be directed to the **Shipping Rules** modal.

## Use cases for shipping rules

Shipping rules allow merchants to customise delivery charges and availability based on specific business needs and customer order behaviour. Below are key use cases supported by the system:

* **Charging an extra fee on Cash on Delivery (COD)**:
  Merchants can configure different shipping charges based on the selected payment method, allowing them to apply an additional fee for COD orders. This helps offset the higher operational costs and risks associated with cash handling and failed deliveries, while encouraging customers to opt for prepaid options by offering lower or no shipping fees.

* **Charging more based on product quantity or weight**:
  When customers add more products to their cart, shipping costs may increase due to the added weight. With weight-based rules, merchants can apply tiered fees, ensuring accurate cost coverage for heavier shipments.

* **Restricting delivery to specific pincodes**:
  To manage service availability or avoid high-risk zones, merchants can block or allow shipping only to a defined list of pincodes. This ensures smooth logistics and avoids delivery issues in unsupported regions. To block non-serviceable PIN codes, log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login), navigate to **One Click Checkout > Shipping and Delivery**, and select **Add New Rule**. Add the specific PIN codes you wish to restrict based on your logistics serviceability.

* **Disabling express shipping**:
  To ensure that the **express shipping** option is not displayed to customers during checkout, you can simply remove all rules defined under the Express shipping rule set. If no valid Express shipping rule applies to the customer's cart, the Express shipping option will not be shown on the checkout page. This allows merchants to temporarily or conditionally disable Express shipping without deleting the entire rule set or affecting other shipping methods.

## Creating a shipping rule

Shipping rules can be created directly from the **One Click Checkout** section in the **Payment Gateway** dashboard.

1. **Access the shipping and delivery section**

   * From the left-hand sidebar, expand the **PG PRODUCTS** section.
   * Under **One Click Checkout**, select **[Shipping & Delivery](https://merchant.cashfree.com/merchants/pg/one-click-checkout-activated/shipping-delivery/cashfree-shipping)**.

2. **Create a shipping rule**

You will be directed to a form titled **Create a rule for \[Shipping Type]**, where you can define the details of the shipping method.

3. **Configure shipping rule settings**

* **Display name**
  * **Purpose:** This is the label your customers will see at checkout.
  * **Example:** Express, Same-Day Delivery, Standard
    <Note> If you're renaming an existing rule, a message may appear indicating all rules of that type will adopt the new display name.</Note>

* **Shipping fee**
  Select one of the following options:
  * **Free (₹ 0):** No shipping charge will be applied.
  * **Add Shipping Charge:** Enables a field to enter the shipping cost.
    * **Input Field:** Enter the applicable fee.
    * **Example:** ₹ 10, ₹ 50

* **Estimated delivery time (Optional)**
  * **Purpose:** Enter an estimated delivery window that customers can expect.
  * **Format Example:** 3-5 days, 1 day, Within 24 hours

* **Applicable payment modes**:
  Select the payment methods supported for this shipping rule:
  * COD (Cash on Delivery)
  * Prepaid
  * Partial Payment

<Note> Only one payment mode can be selected per rule.</Note>

4. **Review the checkout preview**

A preview panel on the right shows how your shipping method will appear to customers during checkout. This includes:

* Display name
* Address section
* Shipping fee
* Available options and action buttons

## Define shipping fee conditions

Click **"Add a condition"** to set rules for how and when the shipping fee is applied. Available condition types include:

| Condition type | Description |
| - | - |
| **Order Value** | Apply fees based on the total price of a customer’s order. Useful for free shipping above a certain amount. |
| **Pincodes** | Apply fees to deliveries targeting specific postal codes. Helps manage location-based shipping costs. |
| **Products** | Apply fees to specific products. Useful for high-value or bulky items. |
| **Product Weight** | Apply fees based on the total weight of items in the cart. Ideal for logistics-based pricing. |

<Note>
  **Important Notes:**

  * You can mix and match multiple conditions as needed. If no condition is added, the shipping will be free by default.
  * If any rules overlap, the one with the highest shipping fee takes priority.
</Note>

## Managing existing shipping rules

Once saved, all configured rules appear in a table under the respective shipping tab (e.g., **Standard Shipping Rules**).

**Table overview**

| **Field** | **Description** |
| - | - |
| **Payment Mode** | COD, Prepaid, or Partial |
| **Amount Range** | Order value range to which the rule applies |
| **Standard Shipping Fee** | Fee charged for shipping |
| **Pincodes** | Count of blocked regions |
| **Products** | Specific products (if applicable) |
| **Weight** | Weight-based rule (if applicable) |
| **Status** | Active/Inactive toggle |
| **Actions** | Edit or delete rule |

## Express shipping

**Express Shipping** is a premium delivery option designed to provide faster order fulfilment than standard shipping. It caters to customers who are willing to pay an additional fee to receive their orders more quickly.

### Key features of express shipping:

* **Faster delivery times:** Orders are prioritised and shipped via expedited logistics partners to ensure quicker arrival.
* **Custom pricing:** Merchants can define separate shipping fees for express delivery based on order value, weight, product type, or customer location.
* **Selective availability:** Express shipping can be restricted to specific pincodes or product categories, depending on service coverage and inventory readiness.
* **Improved customer satisfaction:** By offering a faster delivery option, merchants can appeal to time-sensitive buyers, enhancing their overall shopping experience.


# Overview
Source: https://www.cashfree.com/docs/payments/checkout/shipping-overview

Set up and automate shipping on Cashfree One Click Checkout with dynamic rules by cart value, pincode, product, and order weight from one dashboard.

Shipping and delivery logistics are critical to the success of any e-commerce business, especially for fast-growing D2C brands. Cashfree now offers an enhanced and intelligent Shipping & Delivery configuration system as part of its merchant dashboard, allowing businesses to set up, automate, and optimise delivery operations with ease.

## Dynamic shipping rule

Merchants can define customised shipping fee rules based on key variables:

<CardGroup>
  <Card title="Order Value">
    Set shipping fees by cart total—offering free shipping above certain thresholds or tiered fees for lower-value orders to boost average order values.
  </Card>

  <Card title="Pincodes">
    Define location-specific shipping fees by entering regional pincodes. This helps manage regional delivery costs and restrict shipping to high-risk or non-serviceable areas.
  </Card>

  <Card title="Products">
    Apply shipping charges based on specific products or product categories, ideal for handling bulky, fragile, or special inventory items.
  </Card>

  <Card title="Order Weight">
    Automatically calculate fees by the total weight of the order, perfect for businesses whose courier partners follow weight-based pricing.
  </Card>
</CardGroup>

These rules allow full control over how shipping costs are applied and displayed at checkout, making the experience more transparent and personalised for customers.

## Integration with multiple shipping providers

Cashfree further enhances merchant flexibility by allowing integration with multiple third-party shipping providers. Merchants can:

* Compare rates across providers based on weight, volume, and delivery zones.
* Choose between lower-cost, slower delivery options or faster fulfilment at premium rates, based on customer expectations or margin strategy.
* Factor in additional COD handling charges, helping merchants make better pricing decisions on cash-on-delivery orders.

This flexibility ensures cost-efficiency and improved operational planning, while still providing timely delivery options for end customers.


# Social Proofing
Source: https://www.cashfree.com/docs/payments/checkout/social-proofing

Boost trust and reduce abandonment with Cashfree social proofing, which shows order volumes, recent activity, and FOMO triggers on your checkout page.

Cashfree social proofing enhances customer trust and reduces checkout abandonment. It uses social validation psychology, encouraging action by showcasing metrics like order volume, customers served, and recent activity. This creates urgency and FOMO (fear of missing out), prompting quicker purchase decisions.

<Frame>
  <img />
</Frame>

## Benefits of social proofing

Social proofing offers the following benefits to merchants:

* Enhance brand credibility
* Increase customer confidence in the merchant and products
* Encourage customers to complete purchases
* Reduce hesitation during the checkout process
* Highlight the popularity of products and services

## How social proofing works

Social proofing displays anonymised metrics about customer activity on your store. These metrics are shown in real time or based on recent data. The messages are non-intrusive and integrate seamlessly with the checkout experience to enhance the purchasing process.

Social proofing displays the following metrics:

| **Metric type** | **Sample message** |
| - | - |
| Order volume | 5L+ orders fulfilled by this merchant |
| Customers served | 5,000+ customers have purchased from this store |
| Years with Cashfree | Serving customers for 3 years with Cashfree |
| Recent activity | 100+ recent orders in the last 24 hours |
| Last purchase | Last purchase made 10 minutes ago |

## Setup requirements

Social proofing is available to all Cashfree merchants using Cashfree Checkout. No additional setup or configuration is required. The feature is automatically enabled for eligible merchants and displays relevant metrics based on your transaction history and customer activity.


# Cashfree Trusted Badge
Source: https://www.cashfree.com/docs/payments/checkout/trusted-badge

Display the Cashfree Trusted Badge on your checkout page to verify your business, build shopper credibility, and lift payment completion rates with confidence.

Cashfree trusted badge is a credibility badge displayed on the checkout page to reassure customers while completing payments. It indicates that the merchant has been verified and trusted by Cashfree based on multiple reliability parameters.

By showcasing this badge, merchants can:

* Build trust and credibility with new customers.
* Improve checkout conversions by reducing payment hesitation.
* Stand out as a reliable business backed by Cashfree.

When customers land on your checkout page, they will see the **“Trusted by Cashfree”** badge alongside your business name. This reduces payment anxiety and increases the likelihood of order completion.

## Eligibility criteria

The Cashfree trusted badge is automatically enabled for merchants who demonstrate consistent reliability and safe payment practices on our platform.

Cashfree considers the following factors:

* A proven track record of successful transactions and steady business activity.
* Low-risk profile, with minimal chargebacks and disputes.
* Operation in trusted business categories as defined by industry standards.

Our risk team continuously evaluates these parameters. The badge is enabled automatically for businesses that meet the required benchmarks. No additional setup or request is needed.

## Benefits for merchants

The benefits of the Cashfree trusted badge are as follows:

* **Higher conversions**: Customers are more likely to trust and pay businesses backed by Cashfree.
* **Reduced payment drop-offs**: Builds confidence in completing transactions, especially for first-time buyers.
* **Enhanced brand image**: Positions your business as a verified and reliable entity.

## FAQs

<AccordionGroup>
  <Accordion title="Do I need to apply for the trusted badge?">
    No. The Trusted Badge is automatically enabled if your account qualifies based on Cashfree’s internal parameters.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Will the badge show for all customers?">
    Yes. The Trusted Badge is displayed on your checkout page for all paying customers.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I request re-evaluation if I don't see the badge?">
    Yes. You can submit a [Support Form](https://merchant.cashfree.com/auth/login) to request re-evaluation for the Cashfree Trusted Badge.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How can I disable trusted badge?">
    You can contact our support team by submitting a [Support Form](https://merchant.cashfree.com/auth/login) to get the trust badge disabled.
  </Accordion>
</AccordionGroup>


# WooCommerce
Source: https://www.cashfree.com/docs/payments/checkout/woocommerce

Integrate Cashfree One Click Checkout with WooCommerce stores to provide a fast, branded payment experience for WordPress-based ecommerce shops.

<div>
  <iframe title="YouTube video player" />
</div>

Accept payments instantly on your WooCommerce store with the Cashfree no-code payment gateway. The following major payment methods are supported:

* UPI
* Credit cards
* Debit cards
* Net banking
* Wallets
* Buy Now Pay Later (BNPL)

<Steps>
  <Step title="Sign up and set up">
    1. **[Sign up with Cashfree](https://merchant.cashfree.com/merchants/signup?source-action=docs%20page\&action=Sign%20Up\&button-id=StartNow_EcomPluginWooCom)** if you don't have an account.
    2. Submit the [required documents](https://knowledgebase.cashfree.com/support/solutions/articles/48001146022-what-are-the-documents-needed-for-activating-my-cashfree-account-).
  </Step>

  <Step title="Install the Cashfree plugin">
    1. **[Download the plugin](https://wordpress.org/plugins/cashfree)** from WordPress.
    2. Log in to your WordPress Admin Dashboard.
    3. Upload and install the plugin in `/wp-content/plugins`.
    4. Activate the Cashfree Plugin from the Plugins page.
  </Step>

  <Step title="Configure Cashfree in WooCommerce">
    1. Go to **WooCommerce > Settings > Checkout**.
    2. Select **Cashfree** under Payment Gateways.
    3. Enable Cashfree by checking the **Enable/Disable** box.
  </Step>

  <Step title="Enter your credentials">
    1. Enter your **App ID** and **Secret Key** from Cashfree in the plugin settings.
    2. Configure optional settings:
       * **Sandbox Mode**: Enable to use test mode.
       * **In-Context Payment**: Enable to avoid redirection during payment.
    3. Click **Save Changes**.

    <Warning>
      **Note**: If you encounter an "Authentication Failed" error, clear the "Enable Cashfree Sandbox" checkbox.
    </Warning>
  </Step>

  <Step title="Whitelist your domain">
    To complete the integration, request domain whitelisting:

    1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
    2. Navigate to **Developers > Whitelisting**.
    3. Follow the [whitelisting guide](/docs/payments/online/go-live/whitelist).
  </Step>
</Steps>

## Buy Now Pay Later plus integration

<Steps>
  <Step title="Setup guide">
    1. **Upgrade Cashfree Plugin**: Go to **WooCommerce Admin > Plugins** and update to the latest version.
    2. **Enable BNPL Options**: Go to **Settings** and activate offers, pay later, or EMI options as desired.

       <img alt="BNPL Settings Page" />

       <img alt="BNPL Plus Display on Product Page" />

    BNPL Plus will now display on your product pages.
  </Step>

  <Step title="Troubleshooting">
    **Common errors and solutions**

    * **"Authentication Failed"**: Ensure Sandbox Mode is disabled in settings.
    * **Domain error**: Verify the domain is whitelisted in the Merchant Dashboard.
  </Step>
</Steps>

**Learn how to use other features to improve conversion using [offers](/docs/payments/checkout/offers) and [cart recovery](/docs/payments/checkout/cart-recovery).**

<div>
  <p>Affiliate partner program</p>

  <p>As a developer building payment experiences for your clients, you can earn additional income while providing them with industry-leading payment solutions.</p>

  <p>Join the <a href="https://partner.cashfree.com/partner-ui/authentication/signup?source-action=Affiliate%20Program%20LP&action=Sign%20Up&button-id=StartNow_CashfreeAffiliatePartnerProgram">Cashfree affiliate partner program</a> and get rewarded every time your clients use Cashfree.</p>

  <p>**What you get:**</p>

  <ul>
    <li>Earn up to 0.25% commission on every transaction.</li>
    <li>Become a trusted fintech partner for your clients.</li>
    <li>Access to a dedicated partner manager for expert support.</li>
  </ul>

  <p>**What your clients get:**</p>

  <ul>
    <li>Instant activation and go live in minutes.</li>
    <li>Industry-best success rate across all payment modes.</li>
    <li>Effortless acceptance of international payments in 140+ currencies.</li>
  </ul>

  <p>Get started today. <a href="https://partner.cashfree.com/partner-ui/authentication/signup?source-action=Affiliate%20Program%20LP&action=Sign%20Up&button-id=StartNow_BecomeAPartner">Become a partner now</a>.</p>
</div>


# Web Dashboard
Source: https://www.cashfree.com/docs/payments/dashboard

Use the Cashfree Merchant Dashboard to track transactions, settlements, and refunds, configure payment links and virtual accounts, and manage fraud controls.

The Payment Gateway Merchant Dashboard provides a comprehensive interface for managing your payment operations. Access real-time insights, transaction data, settlement information, and configuration options through an intuitive navigation structure designed for efficient payment management.

<Steps>
  <Step title="Log in to the Merchant Dashboard.">
    Go to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and log in to your Cashfree account. If you don't have a Cashfree account, [sign up for a Cashfree account](https://merchant.cashfree.com/merchants/signup?source-action=docs%20page\&action=Sign%20Up\&button-id=StartNow_Navbar). Refer to [account onboarding](/docs/help/account/account-activation), for more information.
  </Step>

  <Step title="Access Payment Gateway.">
    Navigate to **Payment Gateway** and click **Access** to proceed to the dashboard.
  </Step>
</Steps>

## Summary

The Summary section provides essential insights into your payment operations through two key pages:

<AccordionGroup>
  <Accordion title="Overview" icon="chart-line">
    The Overview page provides a real-time snapshot of your account's financial health and performance metrics.

    **Key metrics**

    * **Recent Settled Amount**: Displays the latest **Offline** and **Online** settled amounts with their respective settlement dates.
    * **Open Disputes**: Tracks dispute amounts and counts categorised by **Action Required** and **Under Review**.
    * **Risky Transactions**: Monitors fraud data from [RiskShield](/docs/payments/risk-shield/overview), showing **Blocked** and **Flagged for Review** transaction amounts and counts.

    **Performance charts**

    Visualises transaction trends over a selected time range, for example, the last 7 days:

    * **Total Transactions**: Graph showing transaction volume and total amounts over time.
    * **Total Refunds**: Detailed view of refund amounts and counts.
    * **Average Transaction Value**: Trend line of the average value per transaction.
    * **Preferred Payment Methods**: Pie chart distribution of used payment modes, for example, UPI.
  </Accordion>

  <Accordion title="Analytics" icon="chart-bar">
    The Analytics section offers detailed reports to help you track performance and optimise your payment flows. It is organised into three main tabs:

    **Business trends**

    Analyse transaction performance over time with:

    * **Success Rate**: Graph displaying transaction success percentages filtered by payment modes. For example, Bank Transfer, UPI, Net Banking, Card, or Wallet.
    * **Number of Transactions**: View total successful transaction counts with comparative insights, for example, compared to last month.

    **Conversion rate**

    Understand your user journey and payment efficiency with:

    * **Payment Funnel Report**: Bar chart comparing "Number of orders created" versus "Payment attempted" versus "Paid Orders".
    * **Conversion Rate**: Visual gauge showing the overall percentage of successful conversions.
    * **Customer Insights**: Metrics for **Unique Customers** and **Repeat Customers** over selected time periods.
    * **Auto Retry**: Statistics on transactions saved via auto-retry mechanisms, including "Number of Auto Retry Transactions" and "Successful Transactions after Auto Retry".

    **Payment failure**

    Identify and resolve payment issues with:

    * **Payment Failure Insight**: Timeline graph showing failure rates across different hours or days.
    * **Average Payment Failures**: Chart highlighting failure sources, for example, Customer or Bank.
    * **Top Failure Reasons**: Detailed list of failure descriptions, rates, sources, and affected payment modes.

    For more information, refer to [Analytics](/docs/payments/checkout/after/external-analytics).
  </Accordion>
</AccordionGroup>

## Transactions

The [Transactions](/docs/payments/manage/transactions) section provides comprehensive details on all payment activities:

<AccordionGroup>
  <Accordion title="Payments" icon="credit-card">
    The Payments section displays all payment transactions processed through your Payment Gateway account. Use this section to track, filter, and export payment data for your transactions.

    Each payment entry includes the following details:

    * **Date and Time**: When the payment transaction was initiated.
    * **Transaction ID**: Unique identifier for the payment transaction.
    * **Transaction Amt.**: Payment amount in Indian Rupees (₹).
    * **Payment Method**: Payment mode used for the transaction, for example, UPI, NET BANKING, or CREDIT CARD.
    * **Status**: Current payment state, for example, User Dropped, Success, or Failed.
    * **Customer's Phone No.**: Customer's contact phone number.
    * **Order ID**: Your system's unique order identifier.
    * **Order Amt.**: Original order amount in Indian Rupees (₹).
    * **Customer Ref ID**: Customer reference identifier from your system.
  </Accordion>

  <Accordion title="Orders" icon="shopping-cart">
    The Orders section displays all payment orders created through your Payment Gateway account. Each order entry includes the following details:

    * **Date and Time**: When the order was created.
    * **Order ID**: Your system's unique order identifier.
    * **Order Amount**: Transaction amount in Indian Rupees (₹).
    * **CF Order ID**: Cashfree generated unique identifier.
    * **Order Type**: Payment gateway product used.
    * **Integration Type**: API integration method.
    * **Customer Name**: Customer who placed the order.
    * **Customer Phone**: Customer's contact number.
    * **Customer Email**: Customer's email address.
    * **Status**: Current order state, for example, Expired, Paid, or Pending.
  </Accordion>

  <Accordion title="Refunds" icon="rotate-left">
    The Refunds section displays all refund transactions processed through your Payment Gateway account. Use this section to track, manage, and export refund data across different refund types.

    The Refunds page is organised into three tabs:

    * **Initiated Refunds**: Manually triggered refund transactions.
    * **Batch Refunds**: Bulk refund operations processed together.
    * **Auto Refunds**: Automatically processed refunds based on predefined rules.

    Each refund entry includes the following details:

    * **Date and Time**: When the refund was initiated.
    * **Order ID**: Your system's unique order identifier.
    * **Refund Amt.**: Refund amount in Indian Rupees (₹).
    * **Order Amt.**: Original order amount in Indian Rupees (₹).
    * **CF Refund ID**: Cashfree generated unique refund identifier.
    * **Refund ARN**: Acquirer Reference Number for the refund transaction.
    * **Payment Mode**: Method used for the original payment, for example, NET BANKING or CREDIT CARD.
    * **Refund Speed**: Processing speed category, for example, Normal.
    * **Status**: Current refund state, for example, Onhold, Success, or Failed.
  </Accordion>

  <Accordion title="Disputes" icon="gavel">
    The Disputes section displays all payment disputes raised by customers through their banks or payment networks. Use this section to track, manage, and respond to disputes across different status categories.

    The Disputes page is organised into four tabs:

    * **Action Required**: Disputes that need immediate attention and response.
    * **Under Review**: Disputes currently being evaluated by the payment network or bank.
    * **Closed**: Disputes that have been resolved or finalised.
    * **All Disputes**: Complete list of all disputes across all statuses.

    The Action Required tab displays summary cards that show the urgency and volume of disputes requiring attention:

    * **Due Today**: Disputes marked as urgent that require response today, with total count and amount.
    * **Due Tomorrow**: Disputes marked as critical that require response by the next business day, with total count and amount.
    * **Insufficient Evidence**: Disputes that need additional supporting documentation, with total count and amount.

    Each dispute entry includes the following details:

    * **Updated On**: Date when the dispute was last modified.
    * **Created On**: Date when the dispute was initiated.
    * **Dispute ID**: Unique identifier for the dispute case.
    * **Order ID**: Your system's unique order identifier.
    * **Transaction ID**: Unique identifier for the disputed transaction.
    * **Type**: Dispute category or reason code.
    * **Dispute Amt.**: Amount being disputed in Indian Rupees (₹).
    * **Respond By**: Deadline for submitting your response.
    * **Action**: Available actions you can take on the dispute.
  </Accordion>

  <Accordion title="Suspicious Transactions" icon="shield-exclamation">
    The Suspicious Transactions section displays all payment transactions flagged by the system's fraud detection mechanisms. Use this section to monitor, investigate, and manage potentially fraudulent or high-risk transactions.

    Each suspicious transaction entry includes the following details:

    * **Created On**: Date when the transaction was flagged as suspicious.
    * **Order ID**: Your system's unique order identifier.
    * **Transaction ID**: Unique identifier for the flagged transaction.
    * **Suspicious Amt.**: Transaction amount flagged as suspicious in Indian Rupees (₹).
    * **Case ID**: Unique identifier assigned to the fraud investigation case.
    * **Status**: Current state of the investigation, for example, Under Review, Cleared, or Blocked.
  </Accordion>
</AccordionGroup>

## Settlements

The [Settlements](/docs/payments/manage/settlements) section displays settlement transactions for funds processed through your Payment Gateway account. Use this section to track settlement cycles, view upcoming settlements, and monitor the status of funds being transferred to your bank account.

<AccordionGroup>
  <Accordion title="Online Settlements" icon="laptop">
    Track settlements for transactions processed through online payment methods, including verified transactions ready for settlement, transactions currently being processed, and completed settlements with currency details and dates.
  </Accordion>

  <Accordion title="Offline Settlements" icon="money-bill">
    Monitor settlements for transactions processed through offline payment methods, with the same level of detail as online settlements including transaction status, processing stages, and completion records.
  </Accordion>
</AccordionGroup>

The online and offline settlement pages display the following summary cards with key information about your funds:

* **Unsettled Amount**: Total amount pending settlement, displayed in Indian Rupees (₹). This card also displays your current settlement cycle, the time frame for fund settlement, for example, 2 working days.
* **Upcoming Settlement**: Next scheduled settlement amount in Indian Rupees (₹). This card also displays expected settlement by, the date when the next settlement is expected to be processed.

The online and offline settlement sections include the following types:

<AccordionGroup>
  <Accordion title="Standard" icon="file-invoice">
    Regular settlement transactions based on your configured settlement cycle. Each standard settlement entry includes the following details:

    * **Initiated At**: Date and time when the settlement was initiated.
    * **Transaction Period**: Date range of transactions included in the settlement.
    * **UTR**: Unique Transaction Reference number for the bank transfer.
    * **Settled Amt.**: Settlement amount transferred in Indian Rupees (₹).
    * **Status**: Current settlement state, for example, Processed, Skipped, or Pending.
  </Accordion>

  <Accordion title="Vendor" icon="store">
    Settlement transactions related to vendor or sub-merchant accounts. Each vendor settlement entry includes the following details:

    * **Date and Time**: When the settlement was initiated.
    * **Period**: Date range of transactions included in the settlement.
    * **Type**: Settlement type. AUTOM for automatic settlements or MANUAL for manually initiated settlements.
    * **Vendor ID**: Unique identifier for the vendor or sub-merchant account.
    * **Settlement ID**: Unique identifier for the settlement transaction.
    * **UTR No.**: Unique Transaction Reference number for the bank transfer.
    * **Adjustment Amt.**: Any adjustment amount applied to the settlement in Indian Rupees (₹).
    * **Settled Amt.**: Final settlement amount transferred in Indian Rupees (₹).
    * **Status**: Current settlement state, for example, SUCCESS or FAILED.
    * **Failure Reason**: Explanation if the settlement failed.
  </Accordion>
</AccordionGroup>

<Tip>
  To check dates when settlements are not processed due to bank holidays, select **View Settlement Holidays** in the upper-right corner.
</Tip>

## Virtual bank account configuration

The [Virtual Bank Account](/docs/payments/vba/overview) Configuration section manages virtual bank accounts for automated payment reconciliation:

<AccordionGroup>
  <Accordion title="VBA Accounts" icon="building-columns">
    The VBA Accounts section displays all virtual bank accounts associated with your account. Use this section to view, search, and manage your virtual accounts.

    Each account card displays the following information:

    * **Virtual ID**: Unique identifier for the account.
    * **Name**: Name assigned to the virtual account.
    * **Status**: Current account state, **Active** or **Inactive**.
    * **A/c**: Virtual account number.
    * **IFSC**: Bank branch IFSC code.

    To create a new virtual bank account, select **Create VBA Account**.
  </Accordion>

  <Accordion title="Notification groups" icon="bell">
    The Notification Groups section allows you to manage teams that receive alerts regarding payments to your Virtual Bank Accounts (VBAs). These groups get notified by WhatsApp and email when payments are received.

    **Manage notification groups**

    * **View Groups**: See all configured notification groups with their assigned names and recipient counts.
    * **Create Group**: Select **Create Notification Group** to set up a new alert group.

    **Group details**

    Each notification group card displays:

    * **Group Name**: Name assigned to the notification group, for example, test\_group.
    * **Recipients**: Number of users in the group receiving notifications.

    To create a new notification group, select **Create Notification Group**.
  </Accordion>
</AccordionGroup>

## Payment links

The [Payment Links](/docs/payments/no-code/payment-link) section enables creation and management of payment requests sent to customers:

<AccordionGroup>
  <Accordion title="All payment links" icon="link">
    The All Payment Links section displays all payment links, including batch links, generated through your account. Use this section to create new links, track their status, and monitor customer payments.

    **Manage payment links**

    * **Create Link**: Select **Create Payment Link** to generate a new payment request.
    * **Filter & Search**: Use the date dropdown (for example, Last Month) and **Search & Filter** to find specific links.
    * **View Options**: Adjust the number of rows displayed per page (default is 10).

    **Payment link details**

    The table displays the following information for each link:

    * **Created At**: Date and time when the link was generated.
    * **Created By**: User who created the link.
    * **Link ID**: Unique identifier for the payment link.
    * **CF Link ID**: Cashfree generated unique link identifier.
    * **Amount**: Requested payment amount in Indian Rupees (₹).
    * **Phone No.**: Customer's contact number associated with the link.
    * **Email ID**: Customer's email address associated with the link.
    * **Link Type**: Configuration of the link, for example, One-time (All methods).
    * **Status**: Current state of the link, for example, Active, Paid, or Expired.
  </Accordion>

  <Accordion title="Orders" icon="receipt">
    The Orders section displays all orders across all payment links. Use this section to track payments and monitor order statuses.

    **Manage orders**

    * **Filter & Search**: Use the date dropdown (for example, Last Month) and **Search & Filter** to find specific orders.
    * **View Options**: Adjust the number of rows displayed per page (default is 10).

    **Order details**

    The table displays the following information for each order:

    * **Date & Time**: Date and time when the order was created.
    * **Order ID**: Unique identifier for the order.
    * **Transaction ID**: Unique identifier for the transaction associated with the order.
    * **CF Link ID**: Cashfree generated unique link identifier associated with the order.
    * **Link ID**: Unique identifier for the payment link.
    * **Amount**: Order amount in Indian Rupees (₹).
    * **Phone No.**: Customer's contact number.
    * **Email ID**: Customer's email address.
    * **Status**: Current status of the order, for example, Success, User Dropped.

    For more information, refer to [Orders](/docs/payments/no-code/payment-link#faqs).
  </Accordion>
</AccordionGroup>

## Apps

The [Apps](/docs/payments/other-products) section provides access to integrated applications and services that extend your payment gateway functionality.

* **Ecommerce Apps**: Install and manage direct integrations with ecommerce platforms like **Shopify** and **Shopify Onsite Card Payments**. Use these apps to accept payments directly on your store fronts.
* **Software Vendors**: Connect and manage relationships with Independent Software Vendors (ISVs). View available vendors, **Connect** new partners, or **Disconnect** existing integrations.
* **Other Apps**: Integrate with productivity and communication tools. For example, install the **Slack** app to receive notifications directly in your team's communication channels.

## Customers

The Customers section provides comprehensive insights into your customer base:

<AccordionGroup>
  <Accordion title="Active" icon="user-check">
    Displays customers who have successfully transacted in the selected time range. Each entry includes:

    * **Phone No.**: Customer's contact number.
    * **Latest Email**: Most recent email address used by the customer.
    * **Total Spends**: Total amount spent by the customer to date.
    * **Total Paid Txns**: Number of successful transactions completed.
    * **Last Transacted At**: Date and time of the most recent successful transaction.
    * **Preferred Mode**: Payment method most frequently used by the customer, for example, UPI or NET\_BANKING.
    * **Tags**: Custom labels assigned to the customer.
  </Accordion>

  <Accordion title="Unfulfilled" icon="user-clock">
    Shows customers who initiated a transaction but didn't make any successful transaction in the selected time range. Each entry includes:

    * **Phone No.**: Customer's contact number.
    * **Latest Email**: Most recent email address provided.
    * **Potential Spends**: Total value of attempted but incomplete transactions.
    * **Total Unpaid Txns**: Number of transaction attempts that were not completed.
    * **Last Attempted At**: Date and time of the most recent transaction attempt.
  </Accordion>
</AccordionGroup>

## Payment gateway products

Access additional [Payment Gateway products](/docs/payments/other-products) that extend your payment capabilities:

<AccordionGroup>
  <Accordion title="One Click Checkout" icon="bolt">
    Enable faster transactions by saving customer payment information for
    streamlined repeat purchases. For more information, refer to [One Click Checkout](/docs/payments/checkout/one-click-checkout).
  </Accordion>

  <Accordion title="Easy Split" icon="arrows-split-up-and-left">
    Automate payment distribution across multiple accounts or vendors for
    complex payment workflows. For more information, refer to [Easy Split](/docs/payments/split/overview).
  </Accordion>

  <Accordion title="Payment Forms" icon="file-lines">
    Generate customised forms for specific customer segments, distributed via
    WhatsApp, email, and SMS channels. For more information, refer to [Payment Forms](/docs/payments/no-code/payment-forms/overview).
  </Accordion>

  <Accordion title="Payment Buttons" icon="square-check">
    Create embeddable payment buttons for websites and applications with
    seamless integration capabilities. For more information, refer to [Payment Button](/docs/payments/no-code/payment-button).
  </Accordion>

  <Accordion title="SoftPOS" icon="mobile">
    Software Point of Sale solution with Collection Point Management for
    physical and virtual locations, and payment methods configuration for
    contactless payment acceptance. For more information, refer to [SoftPOS](/docs/payments/softpos/introduction).
  </Accordion>

  <Accordion title="flowWise" icon="route">
    Advanced payment routing and optimisation tools for enhanced transaction
    processing efficiency. For more information, refer to [flowWise](/docs/payments/flowwise/overview).
  </Accordion>
</AccordionGroup>

## RiskShield

RiskShield provides comprehensive fraud prevention using machine learning technology:

<AccordionGroup>
  <Accordion title="Overview" icon="shield">
    Dashboard summary showing total risky transactions detected, blocked
    transactions, and overall fraud prevention performance metrics. For more information, refer to [RiskShield overview](/docs/payments/risk-shield/overview).
  </Accordion>

  <Accordion title="Risky transactions" icon="triangle-exclamation">
    Detailed transaction information with risk scores, flagging reasons, and
    comprehensive analysis for security decision-making. For more information, refer to [Risky transactions](/docs/payments/risk-shield/risky-transactions).
  </Accordion>

  <Accordion title="Smart rules" icon="wand-magic-sparkles">
    Configure and manage automated rules for suspicious transaction
    identification, with effectiveness tracking for fraud prevention
    optimisation. For more information, refer to [Smart rules](/docs/payments/risk-shield/smart-rules).
  </Accordion>

  <Accordion title="Custom lists" icon="list-check">
    Create and manage custom lists of blocked or allowed customers, payment methods, and other parameters. Works with [Transactions](#transactions) monitoring. For more information, refer to [Blacklists](/docs/payments/risk-shield/my-blacklists).
  </Accordion>
</AccordionGroup>

## Reports

The [Reports](/docs/payments/manage/reports) section provides comprehensive reporting tools:

<AccordionGroup>
  <Accordion title="Download reports" icon="download">
    Generate reports by selecting date ranges and report types, then download in
    preferred formats for immediate analysis and record-keeping. For more information, refer to [Download Reports](/docs/payments/manage/reports#steps-to-download-reports-from-the-merchant-dashboard).
  </Accordion>

  <Accordion title="Schedule reports" icon="calendar-clock">
    Automate report generation and delivery with customisable frequency (daily,
    weekly, monthly), report types, and delivery preferences. For more information, refer to [Schedule Reports](/docs/payments/manage/schedule-reports).
  </Accordion>
</AccordionGroup>

## Developers

The Developers section provides technical integration tools and resources:

<AccordionGroup>
  <Accordion title="API Keys" icon="key">
    Generate and manage Application Programming Interface (API) keys required for payment gateway integration with your applications and websites. For more information, refer to [authentication](/docs/api-reference/authentication#generate-api-keys).
  </Accordion>

  <Accordion title="API Logs and Alerts" icon="scroll">
    View detailed logs of all API calls for comprehensive debugging, integration issue resolution, and usage monitoring. For more information, refer to [API Logs](/docs/payments/online/go-live/api-logs).
  </Accordion>

  <Accordion title="Webhooks" icon="webhook">
    Configure web hook endpoints to receive real-time notifications about payment events, enabling automated workflows and system integration. For more information, refer to [Webhooks](/docs/payments/webhooks).
  </Accordion>

  <Accordion title="Rate Limits" icon="gauge">
    Monitor and manage API rate limits to ensure optimal performance, prevent service disruptions, and maintain system stability. For more information, refer to [Rate Limits](/docs/api-reference/payments/rate-limits).
  </Accordion>

  <Accordion title="Whitelisting" icon="shield-check">
    Configure IP allow listing to restrict API access to specific addresses, enhancing security and controlling system access. For more information, refer to [Whitelisting](/docs/payments/online/go-live/whitelist).
  </Accordion>

  <Accordion title="Checkout Analytics" icon="chart-pie">
    Access detailed analytics about checkout performance including abandonment rates, completion times, and user behaviour insights. For more information, refer to [Checkout Analytics](/docs/payments/checkout/after/external-analytics#one-click-checkout-occ-events).
  </Accordion>
</AccordionGroup>

## Downtimes

The [Downtimes](/docs/payments/manage/downtimes) section monitors payment gateway availability and maintenance schedules:

<AccordionGroup>
  <Accordion title="Active Downtimes" icon="circle-exclamation">
    View current downtimes affecting the payment gateway, categorised by severity levels:

    * **High**: Critical issues (red indicators).
    * **Medium**: Moderate impacts (orange indicators).
    * **Low**: Minor issues (blue indicators).
  </Accordion>

  <Accordion title="Upcoming Downtimes (next 2 days)" icon="calendar-days">
    Monitor planned maintenance and scheduled downtimes for the next two days, helping you prepare for potential service interruptions and plan business operations accordingly.
  </Accordion>
</AccordionGroup>

<Note>
  Access complete downtime history and use filtering options for searches for specific time periods through the **View All** functionality.
</Note>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li>
      <a href="/docs/payments/risk-shield/overview">RiskShield Overview</a>
    </li>

    <li>
      <a href="/docs/payments/vba/overview">Virtual Bank Account Overview</a>
    </li>

    <li>
      <a href="/docs/payments/no-code/payment-link">Payment Links Overview</a>
    </li>

    <li>
      <a href="/docs/payments/checkout/one-click-checkout">One Click Checkout</a>
    </li>

    <li>
      <a href="/docs/payments/split/overview">Easy Split Overview</a>
    </li>
  </ul>
</div>


# Android Changelog
Source: https://www.cashfree.com/docs/payments/developers/changelog/android

Track every release of the Cashfree Android SDK, covering new features, fixes, breaking changes, and supported Android versions across each release.

<Update label="v.2.4.0" description="v.2.4.0 - 22nd May, 2026">
  * Android 16 migration
  * UPI Intent App reordering support in UPI IntentCheckout
  * Performance and QoS improvements
</Update>

<Update label="v.2.3.3" description="v.2.3.3 - 4th May, 2026">
  * Subscription Card Component for Non-PCI merchants
  * Performance and QoS improvements
</Update>

<Update label="v.2.3.2" description="v.2.3.2 - 25th March, 2026">
  * Performance and QoS improvements
</Update>

<Update label="v.2.3.0" description="v.2.3.0 - 11th March, 2026">
  * Cred Card tokenisation
  * Performance and QoS improvements
</Update>

<Update label="v.2.2.9" description="v.2.2.9 - 2nd Feb, 2026">
  * Subscription Payment Support for Card, eNach, UPI Intent
  * Performance and QoS improvements
</Update>

<Update label="v.2.2.8" description="v.2.2.8 - 23rd July, 2025">
  * Android SDK compatibility update to API level 35
  * Performance and QoS improvements
</Update>

<Update label="v.2.2.4" description="v.2.2.4 - 12th June, 2025">
  * Performance and QoS improvements
</Update>

<Update label="v.2.2.2" description="v.2.2.2 - 15th April, 2025">
  * Performance and QoS improvements
</Update>

<Update label="v.2.2.0" description="v.2.2.0 - 25th March, 2025">
  * Introduced new feature PayFast in WebCheckout flow
  * Performance and QoS improvements
</Update>

<Update label="v.2.1.27" description="v.2.1.27 - 25th Feb, 2025">
  * Fix: Dropdown issue for international card number in WebCheckout
  * Performance and QoS improvements
</Update>

<Update label="v.2.1.26" description="v.2.1.26 - 12th Feb, 2025">
  * Subscription checkout support
  * Performance and QoS improvements
</Update>

<Update label="v.2.1.25" description="v.2.1.25 - 19th Dec, 2024">
  * Auto OTP read in Card payment
  * Performance and QoS improvements
</Update>

<Update label="v.2.1.24" description="v.2.1.24 - 29th Nov, 2024">
  * Performance and QoS improvements
</Update>

<Update label="v.2.1.23" description="v.2.1.23 - 22nd Nov, 2024">
  * GooglePlay Integrity version update
  * Performance and QoS improvements
</Update>

<Update label="v.2.1.22" description="v.2.1.22 - 15th Oct, 2024">
  * Performance and QoS improvements
</Update>

<Update label="v.2.1.21" description="v.2.1.21 - 25th Sep, 2024">
  * Performance and QoS improvements
</Update>

<Update label="v.2.1.20" description="v.2.1.20 - 11th Sep, 2024">
  * Auto OTP capture in Card payment - Performance and QoS improvements
</Update>

<Update label="v.2.1.19" description="v.2.1.19 - 9th Aug, 2024">
  * Showing Cashfree branding loader on while loading. - Performance and QoS
    improvements
</Update>

<Update label="v.2.1.18" description="v.2.1.18 - 19th July, 2024">
  * Card Component for Non-PCI merchants
  * Performance and QoS improvements
</Update>

<Update label="v.2.1.17" description="v.2.1.17 - 3rd July, 2024">
  * UPI collect flow improvement
  * Performance and QoS improvements
</Update>

<Update label="v.2.1.15" description="v.2.1.15 - 25th June, 2024">
  * Added NPCI UPI collect logo on the timer screen. - Disabling card payment
    screen recording. - Fix the theme issue for the status bar on the verification
    page. - Performance and QoS improvements
</Update>

<Update label="v.2.1.14" description="v.2.1.14 - 4th June, 2024">
  * QR payment close popup issue - Fix the crash while opening the verification
    page - Performance and QoS improvements
</Update>

<Update label="v.2.1.13" description="v.2.1.13 - 20th May, 2024">
  * Fix ANR issue - Performance and QoS improvements
</Update>

<Update label="v.2.1.11" description="v.2.1.11 - 18th April, 2024">
  * Performance and QoS improvements
</Update>

<Update label="v.2.1.9" description="v.2.1.9 - 12th March, 2024">
  * Added support for newer order pay API version - Fix crash for Android 7 &
    below version - Performance and QoS improvements
</Update>

<Update label="v.2.1.8" description="v.2.1.8 - 1st March, 2024">
  * Amex Card support - Performance and QoS improvements
</Update>

<Update label="v.2.1.7" description="v.2.1.7 - 17th Feb, 2024">
  * WebCheckout flow improvements - Performance and QoS improvements
</Update>

<Update label="v.2.1.6" description="v.2.1.6 - 21st Dec, 2023">
  * UPI intent flow improvements - Performance and QoS improvements
</Update>

<Update label="v.2.1.5" description="v.2.1.5 - 21st Sep, 2023">
  * Cashfree Integrity for Web Checkout Flow - Performance and QoS improvements
</Update>

<Update label="v.2.1.4" description="v.2.1.4 - 18th Aug, 2023">
  * Fixed UnsupportedOperationException in Web Checkout flow - Performance and
    QoS improvements
</Update>

<Update label="v.2.1.3" description="v.2.1.3 - 14th Aug, 2023">
  * Intent Redirection security - Performance and QoS improvements
</Update>

<Update label="v.2.1.2" description="v.2.1.2 - 7th Aug, 2023">
  * NFC Card reader feature in Web Checkout flow - OTP Auto read in the Web
    Checkout flow - PhonePe Wallet Intent SDKless in Web Checkout flow - Fixed
    bugs and crashes - Performance and QoS improvements
</Update>

<Update label="v.2.1.1" description="v.2.1.1 - 21st July, 2023">
  * NFC Card reader feature - Performance and QoS improvements. - Fixed bugs &
    crashes
</Update>

<Update label="v.2.0.9" description="v.2.0.9 - 22nd June, 2023">
  * PhonePe Wallet Intent SDKless flow - UPI UI design enhancement - Performance
    and QoS improvements.
</Update>

<Update label="v.2.0.8" description="v.2.0.8 - 27th April, 2023">
  * Support Mobikwik Wallet payment flow for UPI apps - Checkout screen UI theme
    bug fixes - Performance and QoS improvements.
</Update>

<Update label="v.2.0.7" description="v.2.0.7 - 6th April, 2023">
  * Fixed Memory Leak in EMI payment mode for Drop payment. - Fixed Issue where
    Net banking is shown when UPI payment mode is passed to the SDK and the
    payment mode is disabled for Drop payment. - Fixed EMI error when only EMI as
    payment mode available and order is not eligible for EMI for Drop payment. -
    Fix saved cards showing when Card payment Mode is not available for Drop
    payment .
</Update>

<Update label="v.2.0.6" description="v.2.0.6 - 2nd March, 2023">
  * Added Card Tokenisation and Saved Cards functionality for Drop payment. -
    Performance and QoS improvements.
</Update>

<Update label="v.2.0.5" description="v.2.0.5 - 4th February, 2023">
  * Fixed OTP flow for Simpl wallet payment for Drop payment and Element
    payment. - Fixed NullPointerException for payment failure response for Drop
    payment and Element payment. - Fixed AndroidRuntimeException due to calling
    **doPayment** using application or service context and added checks to prevent
    the same for Drop payment and Element payment. - Fixed wallet payment not
    showing when **payment mode "app"** is passed in **order create API** for Drop
    payment. - Performance and QoS improvements.
</Update>

<Update label="v.2.0.4" description="v.2.0.4 - 11th January, 2023">
  * Fixed dependency missing issue in SDK version v2.0.3
</Update>

<Update label="v.2.0.3" description="v.2.0.3 - 28th December, 2022">
  * Fixed SQLiteException on database downgrade for Drop payment and Element
    payment.
</Update>

<Update label="v.2.0.2" description="v.2.0.2 - 21st December, 2022">
  * Fixed UPI modal pay button in Drop payment.
</Update>

<Update label="v.2.0.1" description="v.2.0.1 - 15th December, 2022">
  * Added Telemetry support which can we subscribed to using the following
    [documentation](/docs/payments/online/mobile/android#other-options).
  * Fixed Callbacks not getting triggered in UPI Collect Flow in Element
    payment. - Fixed NullPointerException in UPI Collect Flow for Drop payment and
    Element payment. - Fixed NumberFormatException in Drop payment and Element
    payment. - Fixed BadTokenException in Drop payment. - Fixed RuntimeException
    in Drop payment. - Fixed IllegalStateException Element payment. - Performance
    and QoS improvements.
</Update>

<Update label="v.2.0.0" description="v.2.0.0 - 2nd October, 2022">
  * **Added a new UPI Intent payment flow with bottom sheet implementation.**
  * **Replaced order token with Session ID.**
  * **Added Web checkout payment mode for merchants who want to use features (like
    offers, saved cards) in native SDK.**
  * Fixed NullPointerException in UPI Collect Flow for Drop payment and
    Element payment.
</Update>

<Update label="v.1.1.7" description="v.1.1.7 - 29th April, 2024">
  * Fixed Null pointer exception for Drop payment and Element payment while
    sending callback
</Update>

<Update label="v.1.1.6" description="v.1.1.6 - 21st February, 2023">
  * Fixed SQLiteException on database downgrade for Drop payment and Element
    payment.
</Update>

<Update label="v.1.1.5" description="v.1.1.5 - 21st December, 2022">
  * Fixed UPI Bottom Sheet in Drop Payment.
</Update>

<Update label="v.1.1.4" description="v.1.1.4 - 15th December, 2022">
  * Fixed Callbacks not getting triggered in UPI Collect Flow in Element payment.
  * Fixed NullPointerException in UPI Collect Flow for Drop payment and Element payment.
  * Fixed NumberFormatException in Drop payment and Element payment. - Fixed BadTokenException
    in Drop payment. - Fixed RuntimeException in Drop payment. - Fixed IllegalStateException
    Element payment. - Performance and QoS improvements.
</Update>

<Update label="v.1.1.3" description="v.1.1.3 - 15th November, 2022">
  * Fixed NullPointerException in UPI Collect Flow for Drop payment and Element
    payment.
</Update>

<Update label="v.1.1.0" description="v.1.1.0 - 14th October, 2022">
  * Shifted payment verification logic for UPI from Drop payment to Element
    payment.
  * Added Card EMI support in Drop payment.
  * Added Play Integrity Check in Element Payment.
  * Quick checkout separate data for Environment in Drop payment. - Added payment
    verification to UPI intent success scenario in Element payment. - Fixed payment
    page getting stuck in loading if merchant logo is missing or corrupted in Drop
    payment. - Fixed payment mode showing even if no payment options are present (Net
    Banking, Wallet, Pay Later) in Drop payment. - Updated images for payment modes
    in Drop payment. - Added support for initiating Drop payment using JSON string.
  * Added support to save card as per RBI guidelines in Element Payment. - Performance
    and QoS improvements.
</Update>

<Update label="v.1.0.11" description="v.1.0.11 - 18th July, 2022">
  * Fixed payment page stuck on loading when no payment mode is enabled in Drop
    payment. - Fixed IllegalStateException on UPI Collect Verification in Drop
    payment. - Fixed NetworkOnMainThreadException in Drop and Element Payment. -
    Fixed NullPointerException in CircleImageView in Drop payment. - Fixed
    visibility of UPI Collect flow when it is not enabled in Drop payment. -
    Improved platform versioning in Drop and Element payment. - Updated images for
    banks, wallets in Drop payment. - Added UPI QR code support for tablets in
    Drop payment. - Added Quick Checkout in Drop payment. - Performance and QoS
    improvements.
</Update>

<Update label="v.1.0.10" description="v.1.0.10 - 21st June, 2022">
  * Fixed payment page is stuck on loading when CASH payment mode is enabled. -
    Added handling to only show payment modes sent in the create order request. -
    Added check for orderID mismatch in Drop payment. - Fixed NullPointerException
    in Drop payment. - Added platform handling in Element payment. - Performance
    and QoS improvements.
</Update>

<Update label="v.1.0.9" description="v.1.0.9 - 7th June, 2022">
  * Fixed theming for exit dialog on 2 FA screen. - Fixed callback not triggered
    on Activity Restart. - Fixed NullPointerException crash on Drop Checkout. -
    Fixed UPI Activity Crash for Android 8.0.0. - Fixed UI interact-able while the
    loader is showing. - Fixed crash on passing invalid colour code to the SDK. -
    Performance and QoS improvements.
</Update>

<Update label="v.1.0.8" description="v.1.0.8 - 25th May, 2022">
  * Fixed callbacks getting triggered twice in UI SDK. - Fixed No callback from
    the Element Checkout when the user cancels the transaction. - Fixed possible
    ANR on application crash. - Fixed Drop Checkout crashes on API level 19. -
    Performance and QoS improvements.
</Update>

<Update label="v.1.0.7" description="v.1.0.7 - 10th May, 2022">
  * Fixed issue when a very long orderID is given to the SDK.
</Update>

<Update label="v.1.0.6" description="v.1.0.6 - 6th May, 2022">
  * SDK Callbacks will be triggered on the main thread.
</Update>

<Update label="v.1.0.5" description="v.1.0.5 - 3rd May, 2022">
  * Fixed SQLException recorded in the logcat.
</Update>


# Cordova Changelog
Source: https://www.cashfree.com/docs/payments/developers/changelog/cordova

Track every release of the Cashfree Cordova SDK with the Cordova changelog, covering new features, fixes, breaking changes, and supported platforms per release.

<Update label="v.1.0.12" description="1.0.12 - 3rd March, 2026">
  * new IOS PSP UPI Apps supported
  * Performance and QoS improvements
</Update>

<Update label="v.1.0.11" description="1.0.11 - 4th August, 2025">
  * Subscription checkout support
  * Performance and QoS improvements
</Update>

<Update label="v.1.0.10" description="1.0.10 - 1st August, 2025">
  * Android 15 migration
  * Performance and QoS improvements
</Update>

<Update label="v.1.0.8" description="1.0.8 - 1st Apr, 2025">
  * Introduced new feature PayFast in WebCheckout flow in both iOS & Android
  * Performance and QoS improvements
</Update>

<Update label="v.1.0.7" description="1.0.7 - 20th Dec, 2024">
  * Auto OTP read in Card payment
  * GooglePlay Integrity version update
  * Performance and QoS improvements
</Update>


# .NET SDK Changelog
Source: https://www.cashfree.com/docs/payments/developers/changelog/dotnet

Track every release of the Cashfree .NET SDK, including the NuGet package rename, new features, and fixes across each version.

<Update label="v6.0.7" description="v6.0.7 - 16th July, 2026">
  **New NuGet package ID: `cashfree-dotnet-pg`**

  The .NET SDK is now published under a new NuGet package ID starting from this version.

  * **New package:** `cashfree-dotnet-pg` (from v6.0.7 onwards)
  * **Previous package:** `cashfree_pg` (final version: 5.0.6, no longer updated)

  To install:

  ```bash theme={"dark"}
  dotnet add package cashfree-dotnet-pg
  ```

  No code changes are required beyond updating the package reference. Future .NET SDK releases will be published only under `cashfree-dotnet-pg`.
</Update>


# Flutter Changelog
Source: https://www.cashfree.com/docs/payments/developers/changelog/flutter

Track every release of the Cashfree Flutter SDK, covering new features, fixes, breaking changes, and supported Flutter versions across each release.

<Update label="v2.4.0+52" description="Version 2.4.0+52  - 22nd May, 2026">
  * Android 16 migration
  * UPI Intent App reordering support in UPI IntentCheckout
  * iOS:FlutterImplicitEngineDelegate support
  * iOS:Back button support on bank page
  * Performance and QoS improvements
</Update>

<Update label="v2.3.4+51" description="Version 2.3.4+51  - 4th May, 2026">
  * Performance and QoS improvements
</Update>

<Update label="v2.3.3+50" description="Version 2.3.3+50  - 13th April, 2026">
  * FlutterImplicitEngineDelegate support
  * Performance and QoS improvements
</Update>

<Update label="v2.3.2+49" description="Version 2.3.2+49  - 2nd April, 2026">
  * Subscription Element API Support
  * Performance and QoS improvements
</Update>

<Update label="v2.2.10+48" description="Version 2.2.10+48  - 6th March, 2026">
  * new IOS PSP UPI Apps supported
  * Performance and QoS improvements
</Update>

<Update label="v2.2.9+47" description="Version 2.2.9+47  - 24th July, 2025">
  * Android SDK compatibility update to API level 35
  * Performance and QoS improvements
</Update>

<Update label="v2.2.8+46" description="Version 2.2.8+46  - 12th June, 2025">
  * iOS Subscription Checkout flow
  * Performance and QoS improvements
</Update>

<Update label="v2.2.7+45" description="Version 2.2.7+45  - 21st May, 2025">
  * Android Subscription Checkout flow
  * Performance and QoS improvements
</Update>

<Update label="v2.2.6+44" description="Version 2.2.6+44  - 16th April, 2025">
  * Performance and QoS improvements
</Update>

<Update label="v2.2.5+43" description="Version 2.2.5+43">
  * Introduced new feature PayFast in WebCheckout flow in both iOS & Android
  * Performance and QoS improvements
</Update>

<Update label="v2.2.4+42" description="Version 2.2.4+42">
  * Fix: Dropdown issue for international card number in WebCheckout
  * Updated iOS sdk to 2.1.0
  * Performance and QoS improvements
</Update>

<Update label="v2.2.3+41" description="Version 2.2.3+41">
  * Deprecated message for Drop Payments in the class initialization.
</Update>

<Update label="v2.2.2+40" description="Version 2.2.2+40">
  * Introduced Auto OTP read in Android.
</Update>

<Update label="v2.2.1+39" description="Version 2.2.1+39">
  * Cashfree Android SDK updated to latest version.
  * Google Play Integrity Library updated.
</Update>

<Update label="v2.2.0+38" description="Version 2.2.0+38">
  * Added UPI only payment flow with the UI powered by Cashfree.
</Update>

<Update label="v2.1.7+37" description="Version 2.1.7+37">
  * Updated iOS sdk to 2.0.18
</Update>

<Update label="v2.1.6+36" description="Version 2.1.6+36">
  * OTP Auto Read functionality for card component in android.
</Update>

<Update label="v2.1.5+35" description="Version 2.1.5+35">
  * OTP Auto Read functionality for card component in android.
</Update>

<Update label="v2.1.4+34" description="Version 2.1.4+34">
  * OTP Auto Read functionality for card component in android.
</Update>

<Update label="v2.1.3+33" description="Version 2.1.3+33">
  * Android status bar theme bug fix. - NPCI logo changes in Android recon view
</Update>

<Update label="v2.1.2+32" description="Version 2.1.2+32">
  * Flutter Android UPI icon fetch error fixed.
</Update>

<Update label="v2.1.1+31" description="Version 2.1.1+31">
  * Addressed namespace build issue with Android CompileSdk 34.
</Update>

<Update label="v2.1.0+30" description="Version 2.1.0+30">
  * Android SDK updated to 2.1.6
</Update>

<Update label="v2.0.26+29" description="Version 2.0.26+29">
  * Now the SDK supports making payments with saved cards.
</Update>

<Update label="v2.0.25+28" description="Version 2.0.25+28">
  * Screen restart issue handle in Android SDK.
</Update>

<Update label="v2.0.24+27" description="Version 2.0.24+27">
  * Changed the card listener response.
</Update>

<Update label="v2.0.23+26" description="Version 2.0.23+26">
  * Added multiple card icons.
</Update>

<Update label="v2.0.22+25" description="Version 2.0.22+25">
  * Added Rupay card icon.
</Update>

<Update label="v2.0.21+24" description="Version 2.0.21+24">
  * Card Component GetTDR Bug Fix
</Update>

<Update label="v2.0.20+23" description="Version 2.0.20+23">
  * Netbanking Element component in flutter - Save Card in Card Component
</Update>

<Update label="v2.0.19+22" description="Version 2.0.19+22">
  * Added TDR and Card Bin Functionality for Card.
</Update>

<Update label="v2.0.18+21" description="Version 2.0.18+21">
  * Upgraded android compile sdk version to 34 - Key matching for android and
    ios in get installed upi apps
</Update>

<Update label="v2.0.17+20" description="Version 2.0.17+20">
  * Upgraded android compile sdk version to 34 - Key matching for android and
    ios in get installed upi apps
</Update>

<Update label="v2.0.16+19" description="Version 2.0.16+19">
  * Added CFTheme in web checkout for android
</Update>

<Update label="v2.0.15+18" description="Version 2.0.15+18">
  * Added card widget. Now non PCI DSS compliant merchants can use the SDK to
    integrate card payments. - Added seamless upi intent and collect. Now
    merchants can build their own ui and make payments using the SDK for upi.
</Update>

<Update label="v2.0.14+17" description="Version 2.0.14+17">
  * Bug Fix in android for auto read OTP.
</Update>

<Update label="v2.0.13+16" description="Version 2.0.13+16">
  * A new version of android sdk has been added. - Now android users can make
    payment by tapping their card on the phone with the NFC feature.
</Update>

<Update label="v2.0.10+13" description="Version 2.0.10+13">
  * Android Bug fix where Netbanking was shown when UPI was sent as payment
    component.
</Update>

<Update label="v2.0.9+12" description="Version 2.0.9+12">
  * Added Redirect Flow in Flutter Web - Flutter web drop js fix
</Update>

<Update label="v2.0.8+11" description="Version 2.0.8+11">
  * Added webcheckout flow in Android and iOS - Flutter web bug fix
</Update>

<Update label="v2.0.7+10" description="Version 2.0.7+10">
  * Multiple result call fix in Android.
</Update>

<Update label="v2.0.6+9" description="Version 2.0.6+9">
  * Android component builder bug fix.
</Update>

<Update label="v2.0.5+8" description="Version 2.0.5+8">
  * Fixed iOS crash issue in recon. - Fixed iOS native OTP issue for cards.
</Update>

<Update label="v2.0.4+7" description="Version 2.0.4+7">
  * Fixed dependency missing issue in Android SDK version.
</Update>

<Update label="v2.0.3+6" description="Version 2.0.3+6">
  * Android integrity bug fix. - Flutter Web blank screen bug fix.
</Update>

<Update label="v2.0.2+5" description="Version 2.0.2+5">
  * Android UPI Intent pay button issue fix
</Update>

<Update label="v2.0.1+4" description="Version 2.0.1+4">
  * iOS podspec file error fix.
</Update>

<Update label="v2.0.0+3" description="Version 2.0.0+3">
  * Support for payment\_session\_id - Refer [Android](/docs/payments/developers/changelog/android) and
    [iOS](/docs/payments/developers/changelog/ios)
</Update>

<Update label="v0.0.2+2" description="Version 0.0.2+2">
  * Android Bug Fixes
</Update>

<Update label="v0.0.1+1" description="Version 0.0.1+1">
  * This is the initial release of the new integration provided by Cashfree
    Payments.
</Update>


# iOS Changelog
Source: https://www.cashfree.com/docs/payments/developers/changelog/ios

Track every release of the Cashfree iOS SDK, covering new features, fixes, breaking changes, and supported iOS versions across each published release.

<Update label="v.2.4.0" description="v.2.4.0 - 20th May March, 2026">
  * Back button support on bank page
  * Performance and QoS improvements
</Update>

<Update label="v.2.3.7" description="v.2.3.7 - 4th May March, 2026">
  * Subscription Custom Card Component for Non-PCI Merchants
  * Performance and QoS improvements
</Update>

<Update label="v.2.3.2" description="v.2.3.2 - 25th March, 2026">
  * Added support for Whatsapp and Simplypay UPI App
  * Subscription Payment Support for Card, eNach, UPI Intent
  * Performance and QoS improvements
</Update>

<Update label="v.2.2.7" description="v.2.2.7 - 6th February, 2026">
  * Added new UPI Apps
  * Performance and QoS improvements
</Update>

<Update label="v.2.2.4" description="v.2.2.4 - 29th May, 2025">
  * Subscription checkout Integration
  * Performance and QoS improvements
</Update>

<Update label="v.2.2.1" description="v.2.2.1 - 27th March, 2025">
  * Performance and QoS improvements
</Update>

<Update label="v.2.2.0" description="v.2.2.0 - 25th March, 2025">
  * Introduced new feature PayFast in WebCheckout flow
  * Framework built with xcode-16
</Update>

<Update label="v.2.1.0" description="v.2.1.0 - 6th January, 2025">
  * Deprecated message for Drop Payments in the class initialization.
</Update>

<Update label="v.2.0.19" description="v.2.0.19 - 14th October, 2024">
  * Configuration to choose full screen loader in element sdks.
</Update>

<Update label="v.2.0.18" description="v.2.0.18 - 23rd September, 2024">
  * iOS minimum version is set to **iOS 12** and **swift\_version** set to **5.10**
  * Added new upi apps - **amazonpay**, **whatsapp** and **cred**
</Update>

<Update label="v.2.0.15" description="v.2.0.15 - 29th July, 2024">
  * Card Component in iOS SDK
</Update>

<Update label="v.2.0.12" description="v.2.0.12 - 24th June, 2024">
  * Added configuration to enable/disable background blur in recon screen
</Update>

<Update label="v.2.0.11" description="v.2.0.11 - 7th June, 2024">
  * Added configuration to enable/disable recon screen.
</Update>

<Update label="v.2.0.8" description="v.2.0.8 - 6th July, 2023">
  * Added CredPay support in iOS WebCheckout flow. Add "credpay" to your info.plist file and your customers will have access to Cred Intent in web checkout
</Update>

<Update label="v.2.0.7" description="v.2.0.7 - 18th May, 2023">
  * Crash Fix when merchant logo URL is present but the image does not download.
</Update>

<Update label="v.2.0.6" description="v.2.0.6 - 28th April, 2023">
  * You can now subscribe to Cashfree generated events from the SDK for analytics.
  * Users can now make payments using saved cards from the SDK.
  * UI Improvements and bug fixes.
</Update>

<Update label="v.2.0.5" description="v.2.0.5 - 25th April, 2023">
  * You can now subscribe to Cashfree generated events from the SDK for analytics.
  * Users can now make payments using saved cards from the SDK.
</Update>

<Update label="v.2.0.4" description="v.2.0.4 - 25th February, 2023">
  * Added web-checkout payment mode to iOS SDK
</Update>

<Update label="v.2.0.3" description="v.2.0.3 - 1st February, 2023">
  * Fixed recon crash when timer runs out.
  * Fixed headless OTP issue.
</Update>

<Update label="v.2.0.1" description="v.2.0.1 - 1st December, 2022">
  * Bug fixes
</Update>

<Update label="v.2.0.0" description="v.2.0.0 - 25th November, 2022">
  * **Deprecated** setOrderToken() method in CFSession builder method
  * Added support for **payment\_session\_id**
  * Headless OTP support for card payments.
  * Added save\_instrument to drop and element SDK.
  * Recon is now part of element SDK for UPI Payments.
</Update>

<Update label="v.1.1.3" description="v.1.1.3 - 19th August, 2022">
  * Web View redirection bug fix.
</Update>

<Update label="v.1.1.2" description="v.1.1.2 - 28th July, 2022">
  * Visibility of UPI Collect flow when it is not enabled in Drop payment.
  * Added UPI QR code support for tablets in Drop payment.
  * Performance and QoS improvements.
</Update>

<Update label="v.1.1.1" description="v.1.1.1 - 18th June, 2022">
  * Added handling to only show payment modes sent in the create order request.
  * Added check for orderID mismatch in Drop payment.
  * Send failed response, if any, from 2FA.
  * Timeout Bug Fix.
</Update>

<Update label="v.1.1.0" description="v.1.1.0 (internal module changes) - 26th May, 2022">
  * Order Expiry check in Drop Checkout
</Update>

<Update label="v.1.1.0" description="v.1.1.0 (internal module changes) - 18th May, 2022">
  * Fixed header length issue which was exceeding 255 characters
  * Fixed Axis Bank redirection issue
  * Handling invalid URL in web view fix.
  * UI Bug fixes in Wallet and Paylater payment modes.
</Update>

<Update label="v.1.1.0" description="v.1.1.0 - 7th April, 2022">
  * One Single callback for all payment modes.
  * Added 2FA screen to Element SDK.
</Update>

<Update label="v.1.0.0" description="v.1.0.0 - 28th March, 2022">
  * First Beta Release
</Update>


# React Native Changelog
Source: https://www.cashfree.com/docs/payments/developers/changelog/react-native

Track every release of the Cashfree React Native SDK, covering features, fixes, breaking changes, and supported versions across each published release.

<Update label="v.2.4.0" description="v.2.4.0 - 21st May, 2026">
  * Android 16 migration
    * UPI Intent App reordering support in UPI IntentCheckout
  * iOS:Back button support on bank page
  * Performance and QoS improvements
</Update>

<Update label="v.2.3.1" description="v.2.3.1 - 5th May, 2026">
  * Subscription custom card component for non-PCI merchants
  * Performance and QoS improvements
</Update>

<Update label="v.2.3.0" description="v.2.3.0 - 2nd April, 2026">
  * Subscription payment support for card, eNach, UPI Intent
  * Performance and QoS improvements
</Update>

<Update label="v.2.2.6" description="v.2.2.6 - 2nd March, 2026">
  * new IOS PSP UPI Apps supported
  * Performance and QoS improvements
</Update>

<Update label="v.2.2.5" description="v.2.2.5 - 25th July, 2025">
  * Android 15 compatibility updated
  * Expo compatibility tested and updated
  * Performance and QoS improvements
</Update>

<Update label="v.2.2.4" description="v.2.2.4 - 27th June, 2025">
  * Android and iOS Subscription Checkout flow
  * Performance and QoS improvements
</Update>

<Update label="v.2.2.2" description="v.2.2.2 - 16th April, 2025">
  * Performance and QoS improvements
</Update>

<Update label="v.2.2.0" description="v.2.2.0 - 27th March, 2025">
  * Introduced new feature PayFast in WebCheckout flow in both iOS & Android
  * Performance and QoS improvements
</Update>

<Update label="v.2.1.21" description="v.2.1.21 - 25th Feb, 2025">
  * Performance and QoS improvements
</Update>

<Update label="v.2.1.20" description="v.2.1.20 - 20th Feb, 2025">
  * Performance and QoS improvements
</Update>

<Update label="v.2.1.19" description="v.2.1.19 - 19th Feb, 2025">
  * Performance and QoS improvements
</Update>

<Update label="v.2.1.18" description="v.2.1.18 - 20th Dec, 2024">
  * Auto OTP read in Card payment
  * GooglePlay Integrity version update
  * Performance and QoS improvements
</Update>

<Update label="v.2.1.17" description="v.2.1.17 - 16th Oct, 2024">
  * Performance and QoS improvements
</Update>

<Update label="v.2.1.16" description="v.2.1.16 - 25th Sep, 2024">
  * Performance and QoS improvements
</Update>

<Update label="v.2.1.15" description="v.2.1.15 - 17th Sep, 2024">
  * Performance and QoS improvements
</Update>

<Update label="v.2.1.14" description="v.2.1.14 - 15th July, 2024">
  * Performance and QoS improvements
</Update>

<Update label="v.2.1.12" description="v.2.1.12 - 25th June, 2024">
  * Performance and QoS improvements
</Update>

<Update label="v.2.1.11" description="v.2.1.11 - 30th April, 2024">
  * Performance and QoS improvements
</Update>

<Update label="v.2.1.10" description="v.2.1.10 - 23th April, 2024">
  * TypeScript definition Error fixed.
  * Performance and QoS improvements
</Update>

<Update label="v.2.1.9" description="v.2.1.9 - 12th Feb, 2024">
  * Support for headless UPI & Card payment flow in iOS
  * Performance and QoS improvements
</Update>

<Update label="v.2.1.8" description="v.2.1.8 - 22nd Jan, 2024">
  * Support for headless UPI payment
  * Performance and QoS improvements
</Update>

<Update label="v.2.1.7" description="v.2.1.7 - 21st Dec, 2023">
  * UPI intent flow improvement
  * Performance and QoS improvements
</Update>

<Update label="v.2.1.6" description="v.2.1.6 - 6th Dec, 2023">
  * Support for headless Card payment and saved card payment support
</Update>

<Update label="v.2.1.4" description="v.2.1.4 - 21st Sep, 2023">
  * Cashfree Integrity for Web Checkout Flow
  * Performance and QoS improvements
</Update>

<Update label="v.2.1.3" description="v.2.1.3 - 14th Aug, 2023">
  * UPI Intent functionality.
</Update>

<Update label="v.2.1.2" description="v.2.1.2 - 22th Aug, 2023">
  * Fixed crash in auto OTP read in Android Webcheckout flow
</Update>

<Update label="v.2.1.1" description="v.2.1.1 - 14th Aug, 2023">
  * Intent Redirection Security added
  * Performance and QoS improvements
</Update>

<Update label="v.2.1.0" description="v.2.1.0 - 10th Aug, 2023">
  * NFC Card reader feature in Web Checkout flow
  * OTP Auto read in the Web Checkout flow
  * PhonePe Wallet Intent SDKless in Web Checkout flow
  * Fixed bugs and crashes
  * Performance and QoS improvements
</Update>

<Update label="v.2.0.10" description="v.2.0.10 - 7th July, 2023">
  * Added CredPay support in iOS WebCheckout flow. Add "credpay" to your info.plist file and your customers will have access to Cred Intent in the web checkout.
</Update>

<Update label="v.2.0.9" description="v.2.0.9 - 26th June, 2023">
  * Project compilation issue fixed for the newer React native version (0.72.0)
  * PhonePe wallet in-app flow integration
  * UPI UI enhancement
</Update>

<Update label="v.2.0.8" description="v.2.0.8 - 22nd May, 2023">
  * Updated the iOS SDK to version v2.0.7.
</Update>

<Update label="v.2.0.7" description="v.2.0.7 - 7th April, 2023">
  * Fixed Card Payment Mode not showing when no payment modes are passed to the SDK.
  * Updated the Android SDK to version v2.0.8.
  * Updated the iOS SDK to version v2.0.6.
</Update>

<Update label="v.2.0.6" description="v.2.0.6 - 7th April, 2023">
  * Updated the Android SDK to version v2.0.7.
</Update>

<Update label="v.2.0.5" description="v.2.0.5 - 30th March, 2023">
  * Added Web checkout support in both Android and iOS platform
  * Updated the iOS SDK to version v2.0.4.
</Update>

<Update label="v.2.0.3" description="v.2.0.3 - 10th March, 2023">
  * Updated the Android SDK to version v2.0.6.
</Update>

<Update label="v.2.0.2" description="v.2.0.2 - 4th February, 2023">
  * Updated the Android SDK to version v2.0.5.
  * Updated the iOS SDK to version v2.0.3.
</Update>

<Update label="v.2.0.1" description="v.2.0.1 - 15th December, 2022">
  * Replaced order token with Session ID.
  * Added Telemetry support which can we subscribed to using the following documentation.
  * Updated cashfree-pg-api-contract to v2.0.0.
  * Updated the Android SDK to version v2.0.1.
  * Updated the iOS SDK to v2.0.1.
</Update>

<Update label="v.1.0.6" description="v.1.0.6 - 29th April, 2024">
  * Updated the Android SDK to version v1.1.6.
</Update>

<Update label="v.1.0.5" description="v.1.0.5 - 21st February, 2023">
  * Updated the Android SDK to version v1.1.6.
</Update>

<Update label="v.1.0.4" description="v.1.0.4 - 15th December, 2022">
  * Updated the Android SDK to version v1.1.4.
  * Updated the iOS SDK to v1.1.3.
</Update>

<Update label="v.1.0.2" description="v.1.0.2 - 3rd August, 2022">
  * Updated the Android SDK to version v1.0.11
  * Updated the iOS SDK to v1.1.2
  * Fixed EventEmitter.removeSubscription(...): Method has been deprecated
  * Fixed Module CashfreePgApi requires main queue
</Update>

<Update label="v.1.0.1" description="v.1.0.1 - 5th July, 2022">
  * Updated cashfree-pg-api-contract version to v1.0.0
</Update>

<Update label="v.1.0.0" description="v.1.0.0 - 5th July, 2022">
  * Initial release
</Update>


# Banking Connect
Source: https://www.cashfree.com/docs/payments/features/banking-connect

Use Banking Connect on Cashfree to deliver faster, mobile-first netbanking payments with a standardised checkout experience across supported partner banks.

Banking Connect is an enhanced Netbanking experience powered by NBBL (NPCI Bharat BillPay Ltd.) that enables faster, more seamless payments. It supports mobile-first customer journeys alongside traditional browser-based Netbanking flows.

Banking Connect creates a single, streamlined integration rail between banks and payment aggregators. This approach improves interoperability, scalability, and consistency whilst retaining the familiar Netbanking experience for customers and merchants.

## Current netbanking experience

Netbanking is widely used for high-value transactions in sectors such as investments, insurance, and education. However, the experience varies significantly across banks:

* Customers are redirected to bank web pages even on mobile journeys.
* Customers face a multi-step process and hassle to remember user ID password.
* Inconsistent bank implementations result in varied checkout experiences.

These factors contribute to higher drop-off rates compared to other payment methods.

Refund timelines, complaint handling, and dispute resolution may also vary across banks due to the absence of a unified operating framework.

Banking Connect addresses these gaps while keeping existing flows fully supported.

## What's changing with Banking Connect

Banking Connect introduces standardised customer journeys through the NBBL ecosystem using three primary flows.

### App-based intent flow (mobile)

Customers authenticate payments directly inside their bank's mobile app.

* Authentication uses biometrics, PIN, or bank app verification, depending on bank support.
* Manual credential entry is reduced where supported.

<Card>
  <div>
    <img alt="App-based intent flow" />
  </div>
</Card>

### QR code flow (desktop or cross-device)

Customers scan a QR code using their bank's mobile app.

* Authentication and confirmation happen inside the bank app.
* This flow bridges desktop checkout and mobile authentication.

<Card>
  <div>
    <img alt="QR code flow" />
  </div>
</Card>

### Existing netbanking redirect flows

Traditional browser-based Netbanking flows remain fully supported.

<Note>Banking Connect is initially available for non-TPV retail transactions. Support for TPV and corporate Netbanking journeys will be introduced in subsequent phases.</Note>

## Integration and enablement

To enable Banking Connect flows, reach out to Cashfree support first. We will obtain the necessary credentials from NBBL on your behalf, which typically takes 3–5 working days. Once enabled, choose the integration path below.

Choose the following integration path to get started with Banking Connect.

<Tabs>
  <Tab title="Cashfree Checkout">
    No action is required. Banking Connect is gradually rolled out across supported banks. Once enabled, eligible customers automatically see the updated Netbanking flows at checkout.
  </Tab>

  <Tab title="Seamless or API">
    Banking Connect works with your existing Netbanking integration. Only the [Order Pay API](/docs/api-reference/payments/latest/payments/order-pay) requires small changes; the [Create Order API](/docs/api-reference/payments/latest/orders/create-order) stays the same.

    ### API changes overview

    **Create Order API**: No changes required.

    **Order Pay API**: Pass the Netbanking `channel` and `netbanking_bank_code` in the payment method object:

    * **channel**: Use `link` for redirection, `intent` for app-based flow, or `qr` for QR-based flow.
    * **netbanking\_bank\_code**: Use a [bank-specific code](/docs/payments/manage/payment-methods/netbanking#list-of-netbanking-with-codes-and-tpv-supported-flags) for `link`. For `intent` and `qr`, use `3136` as a placeholder — since these journeys work across multiple supported banks and the bank through which the customer completes the payment is not known upfront. The payment success webhook and Get Payment API return the actual `netbanking_bank_code` and `netbanking_bank_name` used by the customer.

    ### Sample request

    The following example calls the Order Pay (sessions) endpoint with Netbanking channel `link` and a bank code. For intent or QR, set `channel` to `intent` or `qr` and `netbanking_bank_code` to `3136`.

    ```bash theme={"dark"}
    curl --location 'https://sandbox.cashfree.com/pg/orders/sessions' \
    --header 'Content-Type: application/json' \
    --header 'X-Api-Version: 2021-05-21' \
    --header 'X-client-id: 1abcdefg1' \
    --header 'x-client-secret: 1abcdefg1' \
    --data '{
        "payment_session_id": "session_idabcdefgh234567",
        "payment_method": {
            "netbanking": {
                "channel": "link",
                "netbanking_bank_code": 3021
            }
        }
    }'
    ```

    ### Sample responses

    The response structure depends on the requested `channel`. The following examples show the main fields returned for each flow.

    **Link (redirect)**\
    The response includes `action: "link"` and a `data.url` for redirecting the customer to the bank page.

    ```json theme={"dark"}
    {
      "action": "link",
      "cf_payment_id": "5114920732939",
      "channel": "link",
      "data": {
        "url": "https://sandbox.cashfree.com/pg/view/gateway/session_...",
        "payload": null,
        "content_type": null,
        "method": null
      },
      "payment_amount": 1.00,
      "payment_method": "netbanking"
    }
    ```

    **Intent (app-based)**\
    The response includes `action: "custom"` and `channel: "intent"`. Use `data.payload.default` (the intent URL) to open the customer’s bank app.

    ```json theme={"dark"}
    {
      "action": "custom",
      "cf_payment_id": "5114920732879",
      "channel": "intent",
      "data": {
        "url": null,
        "payload": {
          "default": "nb://pay?ver=1.0&mode=INTENT&orgId=..."
        },
        "content_type": null,
        "method": null
      },
      "payment_amount": 1.00,
      "payment_method": "netbanking"
    }
    ```

    **QR**\
    The response includes `action: "custom"` and `channel: "qr"`. Use `data.payload.qrcode` (base64 image data) to display the QR code for the customer to scan with their bank app.

    ```json theme={"dark"}
    {
      "action": "custom",
      "cf_payment_id": "5114920732875",
      "channel": "qr",
      "data": {
        "url": null,
        "payload": {
          "qrcode": "data:image/png;base64,iVBORw0KGgo..."
        },
        "content_type": null,
        "method": null
      },
      "payment_amount": 1.00,
      "payment_method": "netbanking"
    }
    ```

    ### Customer checkout experience

    #### Mobile flow (intent-based authentication)

    <Accordion title="On Android">
      * Installed bank apps that support the new journeys are detected using `nb://` deep links provided in the Order Pay response.
      * A native app picker, similar to UPI intent, may appear.
    </Accordion>

    <Accordion title="On iOS">
      * Implement bank-specific intent URL handling in your app and show a native bank selection sheet to the customer.
      * Example intent URL schemes: HDFC Bank `hdfcbanknb://`, AU `aunb://`, etc. Yes Bank, Federal Bank, and SBI Bank use their own schemes. Confirm the latest URL schemes with Cashfree before implementing.
    </Accordion>

    #### Desktop or cross-device flow

    To support QR-based authentication:

    * Display a QR code alongside the traditional Netbanking redirect option.
    * Customers scan the QR code using a bank mobile app that supports the new journeys.
    * Authentication and confirmation happen inside the bank app.
    * Show Bharat Connect branding and supported bank app logos in QR journeys.
    * Always provide traditional Netbanking redirect as a fallback option.

    #### Recommended interface elements

    Use **Netbanking (Banking Connect)** as the payment method label on paymode selection screen on checkout. Include **Powered by NBBL** messaging near the QR code and on the intent flow page.
  </Tab>
</Tabs>

## Get help with integration

For implementation guidance, configuration setup, supported bank updates, or rollout timelines, contact Cashfree technical support using the [support form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1).

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/payments/manage/payment-methods/netbanking#list-of-netbanking-with-codes-and-tpv-supported-flags">List of Netbanking banks with codes and TPV supported flags</a></li>
  </ul>
</div>


# Card BIN Details
Source: https://www.cashfree.com/docs/payments/features/card-bin-details

Use the Cashfree Card BIN API to identify card network, type, issuer, and country in real time so you can validate cards and tailor checkout experiences.

**Card BIN** (Bank Identification Number) refers to the first eight digits of a card number, which identify details such as the issuing bank, card type, country of issuance, and card scheme.

## Use cases for card BIN

Card BIN details can be used for the following purposes:

* **Checkout customisations**: Merchants can display the bank name or scheme indicator for customer familiarity. They can also restrict unsupported cards by showing an error when the customer enters the card BIN.
* **Offer targeting**: Check offer eligibility based on card BIN, for example, 10% off on Axis Bank credit cards.
* **Risk and fraud management**: Block or apply strict usage limits on suspicious cards like those of high-risk countries.

## Card BIN API

When customers start entering their card details at checkout, merchants can use Cashfree’s [Get Card BIN Details API](/docs/api-reference/payments/latest/utilities/get-card-bin-details) to fetch information such as issuing bank, card country, card scheme, card type, and sub-type. Merchants can then build their use case on top of this data.
<Note>This API provides two types of responses, depending on your access level. To enable the detailed response for your account, use the [raise an issue support form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1). </Note>

<CodeGroup>
  ```json Filtered Response theme={"dark"}
  {
    "bank_name": "canara bank",
    "country_code": "in",
    "scheme": "visa",
    "sub_type": "filtered",
    "type": "filtered"
  }
  ```

  ```json Detailed Response theme={"dark"}
  {
    "bank_name": "canara bank",
    "country_code": "in",
    "scheme": "visa",
    "sub_type": "retail",
    "type": "credit"
  }
  ```
</CodeGroup>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/payments/latest/utilities/get-card-bin-details">Get Card BIN Details API</a></li>
  </ul>
</div>


# Card Link
Source: https://www.cashfree.com/docs/payments/features/card-link

Enable frictionless card payments with Cashfree Card Link, using device-tokenised cards that work across merchants without re-entering card details at checkout.

Cashfree's Card Link feature enables cards saved on third-party apps, such as Cred, Google Pay, and Samsung Pay, to automatically appear on merchant checkouts, eliminating the need for manual card entry. This feature works through device tokenisation.

### What are device tokens

Device tokens are network-issued tokens, which replace sensitive card details with a secure device-bound token. The customer goes to save the card on their trusted third-party app (TPAPs), creating a device token for the card, which can then be used to make payment on any merchant checkout on that device.

The following table compares the key characteristics of Card on File (CoF) tokens and device tokens.

| CoF token | Device token |
| - | - |
| CoF tokens are merchant specific | Device tokens are device-specific and merchant-agnostic. |
| Customers have to save card on each merchant and it can only be used for repeat payments on that merchant | Customers save card on third-party apps, such as Cred and Google Pay, once, which can be used to make payments on any merchant on that device. |
| Customers have to manually enter card details on every new merchant | Cards can be securely pulled from third-party apps and displayed on merchant checkouts on that device, eliminating the need for manual card entry. |

### Benefits of the Card Link feature

The Card Link feature provides several advantages for both merchants and customers:

* **Faster checkout**: Prefetched cards eliminate manual card entry, making payments up to three times faster.
* **Higher payment success rates**: Tokenised payments reduce manual input errors and improve approval rates, leading to approximately 5% higher success rates.
* **Improved conversion**: Faster checkout reduces friction and can lead to approximately 10% lower payment drop-offs.
* **Unified feature**: Card Link feature gives you access to saved cards from all supported third-party apps, as apps launch this functionality.
* **Future ready**: Designed to support upcoming biometric authentication on device tokens.

## User journey

The following steps describe the customer experience when using the Card Link feature:

1. Customer lands on merchant checkout.
2. Cashfree detects the third-party apps installed on the customer's device and checks the list of saved cards available on each of those apps.
3. Device tokens from third-party apps are displayed on merchant checkout, powered by Card Link feature.
4. Customer selects a device token and that third-party app opens.
5. The third-party app securely gives token and cryptogram to the payment aggregator for payment processing.
6. Customer enters one-time password (OTP) on the third-party app for authentication.
7. The system reads and submits the OTP automatically.
8. Once the payment is successful, the customer returns to the merchant checkout.

<Frame>
  <img alt="Card Link Experience on Checkout" />
</Frame>

## How to enable the Card Link feature

Merchants can enable the Card Link feature using various integration methods depending on their setup.

### Cashfree hosted checkout merchants

Merchants using Cashfree Hosted Checkout can get started with the following considerations:

* Merchants using Cashfree Hosted Checkout (web) in mWeb, will have Card Link feature enabled by default.
* Merchants using Native SDK to open Cashfree Hosted Checkout in webview in the native app will have to upgrade the SDK to the latest version.
* Merchants using Cashfree Hosted Checkout (web) in the native app, without using the Native SDK, will either have to render the checkout in Chrome custom tab or do additional handling on webview to support this feature.

### Seamless checkout merchants

For merchants using seamless checkout, the following integration options are available:

* Merchants using Seamless APIs of Cashfree will have to pass some additional parameters in the [Fetch All Saved Card Instruments API](/docs/api-reference/payments/latest/token-vault/fetch-all-saved-card-instrument), such as customer phone number. Cashfree will do eligibility check from different third-party apps and return the list of apps or device tokens to the merchant, along with the list of CoF tokens saved with Cashfree.
* Merchants using Cashfree Payment Gateway SDK will have to upgrade the SDK to the latest version, post which the SDK performs eligibility checks from different third-party apps and return the list of apps or device tokens to the merchant, in addition to CoF tokens saved with Cashfree.
* Merchants not using Cashfree Payment Gateway SDK, but having a native app, can use Card Link SDK. On checkout load, the merchant invokes the SDK and passes parameters such as customer phone number. SDK performs eligibility checks from different third-party apps and return the list of apps or device tokens to the merchant. The merchant can then process payment with any payment aggregator of their choice.

<Frame>
  <img alt="Card Link Experience on Seamless Checkout" />
</Frame>

## Frequently asked questions

Refer to the following frequently asked questions for more information on the Card Link feature.

<Accordion title="Which apps are supported on this flow?">
  This feature is currently live on Cred and will be soon made available on other third-party apps, as and when they’re ready with this functionality.
</Accordion>

<Accordion title="What are the supported platforms for Card Link?">
  Card Link feature works on Android for both web and native app checkouts. This feature will soon be made available on iOS by these third-party apps.
</Accordion>

<Accordion title="Who handles payment processing?">
  For the customer, authentication is performed within the third-party app’s trusted environment, but at the back-end payment processing is done by the merchant's payment aggregator itself.
</Accordion>

<Accordion title="When do saved cards from third-party apps appear on the checkout?">
  Device tokens can only be fetched if the third-party app is present on the same device where checkout is opened, customer is logged in on the app and customer has a saved card available on that app. Cashfree does these eligibility checks, and only then device tokens are surfaced on the checkout.
</Accordion>

<snippet>snippets/related-topics-loader.mdx</snippet>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/payments/features/token-vault">Token Vault Overview</a></li>
    <li><a href="/docs/payments/checkout/one-click-checkout">One Click Checkout</a></li>
    <li><a href="/docs/api-reference/payments/overview">API Overview</a></li>
    <li><a href="/docs/api-reference/payments/latest/token-vault/fetch-all-saved-card-instrument">Fetch All Saved Instruments API</a></li>
  </ul>
</div>


# Show Purchase Context on Checkout
Source: https://www.cashfree.com/docs/payments/features/contextual-checkout

Show a short purchase description on Cashfree checkout so customers can confirm what they are paying for before they complete the payment.

Checkout displays the merchant name, payment amount, and available payment methods. Use Contextual Checkout to add a short purchase description so customers can confirm what they are paying for before they complete the payment.

<Note>
  Contextual Checkout is available on request. Contact your Cashfree account manager or submit the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) to enable it on your account.
</Note>

If you pass a valid `checkout_context` value, checkout displays a context card above the payment methods. If the key is missing, the value is invalid, or Contextual Checkout is not enabled for your account, checkout does not display the context card.

The following tabs show checkout scenarios with and without a context card:

<Tabs>
  <Tab title="With context card">
    <Frame>
      <img alt="Cashfree checkout for BookYourFlight showing a context card with Flight booking DEL to BOM, 12 JUN at 14:30 above Offers and Coupons" />
    </Frame>
  </Tab>

  <Tab title="Without context card">
    <Frame>
      <img alt="Cashfree checkout for BookYourFlight showing merchant name, amount, and payment methods without a context card" />
    </Frame>
  </Tab>
</Tabs>

## Add checkout context

Pass a `checkout_context` key in the existing `order_tags` object when you call the [Create Order API](/docs/api-reference/payments/latest/orders/create-order). This requires no new endpoint, SDK upgrade, or extra integration step.

You control the text shown in the context card. Use it for a route, booking reference, invoice number, or any other short description the customer can recognise.

<Note>
  **Context card rule**: If `checkout_context` is invalid, checkout ignores the value and does not display the context card.
</Note>

```json theme={"dark"}
{
  "order_amount": 9300.00,
  "order_currency": "INR",
  "customer_details": {
    "customer_id": "<CUSTOMER_ID>",
    "customer_phone": "<CUSTOMER_PHONE>"
  },
  "order_tags": {
    "checkout_context": "Flight booking DEL to BOM, 12 JUN at 14:30"
  }
}
```

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/payments/latest/orders/create-order">Create Order API</a></li>
    <li><a href="/docs/payments/online/web/redirect">Hosted checkout Web Integration</a></li>
    <li><a href="/docs/payments/online/mobile/android">Hosted checkout Android Integration</a></li>
  </ul>
</div>


# CVV-Less Card Payments
Source: https://www.cashfree.com/docs/payments/features/cvv-less

Offer CVV-less card payments on Cashfree for returning customers with tokenised cards, reducing checkout steps while staying compliant with card network rules.

CVV-less payments allow customers to complete transactions using saved card details without entering the Card Verification Value (CVV).
This enhances the user experience by streamlining the checkout process while maintaining transaction security through tokenisation and other protective measures.

CVV-less payments support tokenised transactions using **Visa**, **Mastercard**, **RuPay**, **American Express (Amex)**, and **Diners Club** cards.

<Tip>
  CVV-less boosts success rates by approximately 5%.
</Tip>

<Frame>
  <img alt="Description" />
</Frame>

## Benefits and security considerations

* **Broader network support:** Available across Visa, Mastercard, Amex, RuPay, and Diners networks.

* **Higher conversion and success rates:** CVV-less payments for tokenised cards typically improve success rates by approximately 5%.

* **Enabled from day 0:** Enabled by default across all networks for tokenised cards from day 0.

* **CVV-less indicator:** Saved cards display a **No CVV Required** label during checkout on the Cashfree Checkout.

  <img alt="" />

* **Faster checkout and reduced friction:** Customers do not need to remember or enter CVV details for saved cards.

* **Secure and compliant:** Transactions are protected by tokenisation, OTP validation, 3D Secure authentication, and real-time risk checks. Fully compliant with PCI DSS, RBI regulations, and card network guidelines.

## Using CVV-less payments with Cashfree payment gateway

CVV-less payments integrate seamlessly with Cashfree’s infrastructure. Depending on your integration method, minimal changes may be required.

### For merchants on seamless API integration

For saved card transactions across supported networks, the `card_cvv`  field is optional by default. To enable CVV-less payments, exclude this field from your payment request.

**Sample [Order Pay API](/docs/api-reference/payments/latest/payments/order-pay) request**

<CodeGroup>
  ```javascript For external card tokens theme={"dark"}
  curl --request POST \
    --url https://sandbox.cashfree.com/pg/orders/sessions \
    --header 'Content-Type: application/json' \
    --header 'x-api-version: <x-api-version>' \
    --data '{
    "payment_session_id": "session__CvcEmNKDkmERQrxnx39ibhJ3Ii034pjc8ZVxf3qcgEXCWlgDDlHRgz2XYZCqpajDQSXMMtCusPgOIxYP2LZx0-05p39gC2Vgmq1RAj--gcn",
    "payment_method": {
      "card": {
        "channel": "link",
        "card_number": "4111111111111111",
        "card_expiry_mm": "03",
        "card_expiry_yy": "26",
        "cryptogram": "AQBBBBBBZatIlaIAmWKSghwBBBB=",
        "card_cvv": "900",  // Optional
        "token_requestor_id": "22457512314",
        "card_holder_name": "Tushar Gupta",
        "card_display": "3243"

      }
    }
  }'
  ```

  ```javascript For Cashfree tokens theme={"dark"}
  curl --request POST \
    --url https://sandbox.cashfree.com/pg/orders/sessions \
    --header 'Content-Type: application/json' \
    --header 'x-api-version: <x-api-version>' \
    --data '{
    "payment_session_id": "session__CvcEmNKDkmERQrxnx39ibhJ3Ii034pjc8ZVxf3qcgEXCWlgDDlHRgz2XYZCqpajDQSXMMtCusPgOIxYP2LZx0-05p39gC2Vgmq1RAj--gcn",
    "payment_method": {
      "card": {
        "channel": "link",
        "instrument_id": "54deabb4-ba45-4a60-9e6a-9c016fe7ab10",
        "card_cvv": "900" // Optional
      }
    }
  }'
  ```
</CodeGroup>

**Update your checkout UI**

Update your checkout interface to stop collecting CVV for saved card payments.

* For tokenised cards on Visa, Mastercard, Amex, RuPay, and Diners, remove the `card_cvv` field from the card object.

<Note>
  CVV input is optional only for tokenised card transactions (transactions using saved cards). For plain card or guest checkout transactions, CVV input is mandatory.
</Note>

### For merchants using Cashfree checkout UI

Cashfree enables CVV-less payments by default for all saved card transactions across supported networks. You don't need to configure anything additionally.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="What is a CVV-less card payment?">
    A CVV-less card payment allows customers to complete a card transaction without entering the Card Verification Value (CVV)—a 3- or 4-digit security code typically required at checkout.
  </Accordion>

  <Accordion title="How is the transaction secured without CVV?">
    CVV-less transactions maintain security through 3D Secure (3DS), OTP (One-Time Password) authentication, secure encryption of card data, and additional risk checks such as real-time fraud detection.
  </Accordion>

  <Accordion title="Are CVV-less payments compliant with regulatory guidelines (like RBI or PCI DSS)?">
    Yes. CVV-less payments are compliant as long as they involve tokenised cards and adhere to the card network and RBI guidelines for authentication.
  </Accordion>

  <Accordion title="Why should a merchant allow CVV-less payments?">
    CVV-less payments reduce friction at checkout, improving conversion rates and enhancing customer experience, especially for a returning user base in mobile-first markets.
  </Accordion>

  <Accordion title="What are the pre-requisites for CVV-less payments?">
    CVV-less card payment experience is available only for tokenised cards, meaning the card is securely saved with a merchant.
  </Accordion>

  <Accordion title="Will offering CVV-less payments increase my payment success rates?">
    Yes, the CVV-less card payment feature improves success rates by approximately 5% on average.
  </Accordion>

  <Accordion title="Which card networks support CVV-less payments?">
    CVV-less flow supports tokenized payments on Visa, Mastercard, RuPay, Amex, and Diners.
  </Accordion>

  <Accordion title="Is CVV-less payment possible via Payment Links and Payment Forms?">
    Yes. Both Payment Links (PL) and Payment Forms (PF) support CVV-less payments.
  </Accordion>

  <Accordion title="Is CVV-less by default enabled?">
    Yes. From day 0, merchants can enable CVV-less payments for their customers (only on tokenised cards).
  </Accordion>
</AccordionGroup>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/payments/latest/payments/order-pay">Order Pay API</a></li>
  </ul>
</div>


# Native OTP
Source: https://www.cashfree.com/docs/payments/features/native-otp

Authenticate Cashfree card payments natively in your website or app so customers stay in your flow during OTP entry to lift checkout conversion.

In a typical card payment flow, the bank’s page collects the OTP after the payment gateway redirects the customer. With Cashfree’s Native OTP functionality, you can collect the OTP directly on your website or app, improving the customer experience.

**Benefits of Native OTP**

* **No redirects, no friction**: Eliminates redirects and reduces payment failures due to drop-offs or slow network.
* **Single-click OTP experience**: Provides seamless single-click experience to customers via auto-read and auto-submit functionality.

<Tip> Native OTP boosts success rates by approximately 5%. </Tip>

<Frame>
  <img alt="Bank ACS vs Cashfree Native OTP" />
</Frame>

<Note>Use the [raise an issue support form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) to request enabling this feature for your account.</Note>

## Cashfree-hosted checkout

Native OTP functionality is supported by default on Cashfree checkout. Cashfree displays the Native OTP page directly within the checkout, allowing customers to submit the OTP without redirection.

<Frame>
  <img alt="Native OTP experience on Cashfree checkout" />
</Frame>

<Tip> Cashfree's Native OTP is also enriched with **OTP auto-read and auto-submit** functionality, enabling **single-click OTP experience** for customers. </Tip>

## Seamless checkout

To implement Native OTP on seamless checkout, merchants must build their own custom Native OTP interface and use Cashfree’s APIs to perform authentication.

**Best practices for designing a Native OTP page**

Seamless merchants can draw inspiration from Cashfree’s Native OTP design, which adheres to EMV 3DS user experience guidelines, thereby enhancing customer familiarity and trust.\
The UI should include the following elements:

* OTP input field and submit button.
* OTP auto-read and auto-submit functionality.
* Display of bank and scheme logos.
* Resend OTP option, allowed twice, enabled after 30 seconds each, per bank limits.
* Option to complete the transaction on the bank’s website.
* 5-minute session timeout, in accordance with bank timeout.

<Steps>
  <Step title="Initiate Native OTP request">
    Call the [Order Pay API](/docs/api-reference/payments/latest/payments/order-pay) with `"channel": "post"` to request for Native OTP flow for authentication.

    ```shell Native OTP request {9} theme={"dark"}
    curl --request POST \
      --url https://sandbox.cashfree.com/pg/orders/sessions \
      --header 'Content-Type: application/json' \
      --header 'x-api-version: <latest-version>' \
      --data '{
      	"payment_session_id": "session_Cke8Y9LKs2CQP9KuTzsomExG1x5CKBLo8MynNCv8QT",
      	"payment_method":{
      		"card":		{
              "channel":"post",	
              "card_number": "4111111111111111",
              "card_expiry_mm": "03",
              "card_expiry_yy": "25"	
              "card_cvv": "326", 
              "card_holder_name": "john"
      		}
      	}
      }'
    ```
  </Step>

  <Step title="Collect OTP">
    If Native OTP flow is enabled and supported for a given transaction, the Order Pay API response will return `"action": "post"`. Render the native OTP UI to collect the OTP and submit it on the link provided in the `data.url` field for authentication.

    ```json Collect OTP response {2,6,10} theme={"dark"}
    {
       "action": "post",
       "cf_payment_id": "3991346241",
       "channel": "post",
       "data": {
           "url": "https://api.cashfree.com/pg/orders/pay/authenticate/3991346241",
           "payload": null,
           "content_type": "application/json",
           "method": "post",
           "redirect_to_bank": "https://api.cashfree.com/pg/view/redirecttobank/MV47yJlEMkr8X_Er5YDZ-uiKHU7IGrK2kH7CTtcjeaU8v10fAeLoLL9osqoUQrmBxnbV809FFzyQTKQy"
       },
       "payment_amount": 1.00,
       "payment_method": "card"
    }
    ```

    <Note>It is advisable to keep 10 seconds of max timeout for the Order Pay API response, as our Native OTP response is subject to bank ACS load time.</Note>

    <AccordionGroup>
      <Accordion title="Handling API response for Native OTP flow">
        When `channel = 'post'` is sent in Order Pay API request for Native OTP flow:

        * If Native OTP is supported, you'll receive `channel = "post"` and `action = "post"` in response → render Native OTP UI and submit OTP to `data.url`; If user clicks on redirect to bank page, then redirect the user to `data.redirect_to_bank`.

        ```json Sample response {2,6,10} theme={"dark"}
        {
           "action": "post",
           "cf_payment_id": "3991346241",
           "channel": "post",
           "data": {
               "url": "https://api.cashfree.com/pg/orders/pay/authenticate/3991346241",
               "payload": null,
               "content_type": "application/json",
               "method": "post",
               "redirect_to_bank": "https://api.cashfree.com/pg/view/redirecttobank/MV47yJlEMkr8X_Er5YDZ-uiKHU7IGrK2kH7CTtcjeaU8v10fAeLoLL9osqoUQrmBxnbV809FFzyQTKQy"
           },
           "payment_amount": 1.00,
           "payment_method": "card"
        }
        ```

        * If Native OTP isn't supported, you'll receive `channel = "post"` and `action = "link"` in response → redirect the user to `data.url` or `data.redirect_to_bank` (both will have the same URL).

        ```json Sample response {2,6} theme={"dark"}
        {
           "action": "link",
           "cf_payment_id": "3991389813",
           "channel": "post",
           "data": {
               "url": "https://api.cashfree.com/pg/view/gateway/session_N45NkEY97Jwp--7qMG88UI6gZ5etAqlxHAe-LqJf-tWCguYEZUehSvDhTeXoTFGEvHI1TzQ0Z1qHgTC9mBup0Zxn3NCYEvzo4kLajub-98c4QuN2bLnDWKdZ2a3dcde9-7080-451b-9dff-b57f03873c68",
               "payload": null,
               "content_type": null,
               "method": null,
               "redirect_to_bank": "https://api.cashfree.com/pg/view/gateway/session_N45NkEY97Jwp--7qMG88UI6gZ5etAqlxHAe-LqJf-tWCguYEZUehSvDhTeXoTFGEvHI1TzQ0Z1qHgTC9mBup0Zxn3NCYEvzo4kLajub-98c4QuN2bLnDWKdZ2a3dcde9-7080-451b-9dff-b57f03873c68"
           },
           "payment_amount": 1.00,
           "payment_method": "card"
        }
        ```

        When `channel = 'link'` is sent in Order Pay API request for non-Native OTP flow:

        * Redirect the user to `data.url` which will be the bank ACS page or [Cashfree ACS](/docs/payments/features/native-otp#cashfree-acs) page if Cashfree ACS is enabled; `data.redirect_to_bank` won't be present in this case.

        ```json Sample response {2,6} theme={"dark"}
        {
           "action": "link",
           "cf_payment_id": "3991367114",
           "channel": "link",
           "data": {
               "url": "https://api.cashfree.com/pg/view/gateway/session_N45NkEY97Jwp--7qMG88UI6gZ5etAqlxHAe-LqJf-tWCguYEZUehSvDhTeXoTFGEvHI1TzQ0Z1qHgTC9mBup0Zxn3NCYEvzo4kLajub-98c4QuN2bLnDWKdZ4d4ecf9d-328a-4460-964b-df8d8096be6f",
               "payload": null,
               "content_type": null,
               "method": null
           },
           "payment_amount": 1.00,
           "payment_method": "card"
        }
        ```
      </Accordion>
    </AccordionGroup>

    <Tip> Seamless merchants can also leverage **Cashfree's seamless Native OTP SDK** which offers customisable UI and in-built **auto-read and auto-submit functionality**, enabling **single-click OTP experience** for customers.</Tip>

    <Frame>
      <img alt="Seamless Native OTP experience with Cashfree SDK" />
    </Frame>

    On the Native OTP page, it is advisable to provide an option for customers to complete the transaction on the bank’s website. If the customer clicks on this option, another transaction is created in the backend and processed on the bank ACS page. In this scenario, the merchant receives two webhooks—one for the primary transaction and another for the secondary transaction created during the redirection.\
    Merchants should consume these webhooks based on their `order_id`. For reconciliation of order status, always use the [Get Payments for an Order API](/docs/api-reference/payments/latest/payments/get-payments-for-an-order). If any transaction for the order is successful, the order status should be considered paid.
  </Step>

  <Step title="Submit OTP">
    After merchant collects the OTP on Native OTP page, they can submit it to Cashfree using the [Submit OTP API](/docs/api-reference/payments/latest/payments/submit-or-resend-otp).

    ```bash Submit OTP {8-9} theme={"dark"}
    curl --request POST \
         --url https://sandbox.cashfree.com/pg/orders/pay/authenticate/{payment_id} \
         --header 'accept: application/json' \
         --header 'content-type: application/json' \
         --header 'x-api-version: <latest-version>' \
         --data '
    {
      "action": "SUBMIT_OTP",
      "otp": "111000"
    }'
    ```

    Also, give an option to resend OTP on your Native OTP page by calling this same API with `"action": "RESEND_OTP"`.

    ```bash Resend OTP {8} theme={"dark"}
    curl --request POST \
         --url https://sandbox.cashfree.com/pg/orders/pay/authenticate/{payment_id} \
         --header 'accept: application/json' \
         --header 'content-type: application/json' \
         --header 'x-api-version: <latest-version>' \
         --data '
    {
      "action": "RESEND_OTP"
    }'
    ```
  </Step>
</Steps>

## Cashfree ACS

For merchants who prefer not to build a custom Native OTP interface, Cashfree provides an ACS page where customers can submit the OTP. This page offers a standardised experience with auto-read and auto-submit functionality for a smoother payment flow.

Call the [Order Pay API](/docs/api-reference/payments/latest/payments/order-pay) with `"channel": "link"` to request Cashfree ACS for authentication → redirect the user to `data.url` to open Cashfree ACS page. Cashfree will collect and submit the OTP for authentication.

```json Sample response {2,6} theme={"dark"}
{
   "action": "link",
   "cf_payment_id": "3991367114",
   "channel": "link",
   "data": {
       "url": "https://api.cashfree.com/pg/view/gateway/session_N45NkEY97Jwp--7qMG88UI6gZ5etAqlxHAe-LqJf-tWCguYEZUehSvDhTeXoTFGEvHI1TzQ0Z1qHgTC9mBup0Zxn3NCYEvzo4kLajub-98c4QuN2bLnDWKdZ4d4ecf9d-328a-4460-964b-df8d8096be6f",
       "payload": null,
       "content_type": null,
       "method": null
   },
   "payment_amount": 1.00,
   "payment_method": "card"
}
```

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/payments/latest/payments/order-pay">Order Pay API</a></li>
    <li><a href="/docs/api-reference/payments/latest/payments/submit-or-resend-otp">Submit OTP API</a></li>
    <li><a href="/docs/api-reference/payments/latest/payments/get-payments-for-an-order">Get Payments for Order API</a></li>
  </ul>
</div>


# PayFast
Source: https://www.cashfree.com/docs/payments/features/payfast

PayFast intelligently pre-selects preferred payment methods for returning Cashfree customers, reducing checkout steps and improving conversion rates.

PayFast is a one-click payment solution that simplifies the checkout process for returning customers. By intelligently pre-selecting preferred payment methods and streamlining the payment flow, PayFast reduces steps, minimises drop-offs, and boosts conversions for businesses.

<img />

## Key features

* **One-click payments:** Allows returning customers to complete transactions instantly without multiple payment steps

* **Smart payment selection:** Automatically selects the most relevant payment method based on the customer’s transaction history

* **Contextual checkout experience:** Appears as a compact bottom-sheet interface on the merchant’s website, ensuring a smooth, lightweight checkout process without redirection.

* **Optimised for conversions:** Reduces friction at checkout, improving success rates and customer retention

## Benefits

For businesses:

* **Higher conversions:** Reduces cart abandonment with instant payments.
* **Faster repeat purchases:** Makes checkout seamless for loyal customers.
* **Enhanced customer experience:** Provides a smooth, intelligent payment flow that builds trust and retention.

For customers:

* **No hassle:** Eliminates the need to enter payment details repeatedly.
* **Faster payments:** Enables one-click checkout for quicker transactions.

## Supported payment methods

PayFast currently supports:

* UPI (saved VPAs and UPI intent)
* Saved debit and credit cards
* Net banking
* Wallets

<Note> Additional payment methods will be added soon.</Note>

## Availability

* **Devices:** Available on mobile.
* **Integration:** Works seamlessly with the Cashfree checkout experience.
* **Activation:** Auto-enabled for select merchants.

<Note> Fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) if you do not wish to continue using PayFast.
For further assistance, contact your Cashfree account manager or fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1). </Note>


# Payment Account Reference
Source: https://www.cashfree.com/docs/payments/features/payment-account-reference

Use Payment Account Reference (PAR) on Cashfree to track tokenised cards across networks and stay compliant with RBI card-on-file storage rules.

A Payment Account Reference (PAR) is a unique value linked to each Primary Account Number (PAN), which is the card number printed on the card. According to RBI regulations, only card networks and issuing banks can store card details. However, many use cases require identifying a card without storing its actual details, such as:

* Targeted promotions
* Risk assessments

PAR addresses this requirement by providing a unique one-to-one identifier for each card, ensuring consistency whilst remaining compliant.

## Use cases for PAR

You can use PAR for the following purposes:

* **Offers and loyalty:** Merchants can use PAR to verify offer availability, such as ensuring that an offer can be availed only once per card.
  * Example: HDFC Bank Visa Credit Card offers a 10% discount on flight bookings, valid once a week.
* **Risk management:** Merchants can use PAR to gather data on transaction patterns, analyse potential risks, and build custom risk checks, such as limiting transaction amount or number of transaction attempts per day.
  * Example: A specific card can only be used to purchase gift cards up to a maximum amount of INR 20,000 per month.

## Cashfree’s PAR as a service

Cashfree provides APIs to help you use PAR effectively.

### Get PAR before a transaction

Retrieve PAR against a plain card or saved card before initiating a transaction.

Use [Get PAR API](/docs/api-reference/payments/latest/utilities/get-par) to get the corresponding PAR by passing plain card details to Cashfree. This works for all major card schemes such as Visa, Mastercard, RuPay, American Express, and Diners.

<CodeGroup>
  ```bash Sample request theme={"dark"}
  curl --location 'https://api.cashfree.com/pg/utilities/pars' \
  --header 'Content-Type: application/json' \
  --header 'X-client-id: <x-client-id>' \
  --header 'X-client-secret: <x-client-secret>' \
  --header 'x-api-version: 2025-01-01' \
  --header 'x-request-id: sIP3A1Vi9swEi8KF02cU' \
  --data '{
      "card_number": "4111111111111111",
      "card_cvv": "123",
      "card_expiry_mm": "12",
      "card_expiry_yy": "27",
      "card_type": "PLAIN_CARD"
  }'
  ```

  ```json Sample response theme={"dark"}
  {
    "par": "V0010014623022637739353641436"
  }
  ```
</CodeGroup>

When you fetch saved cards from Cashfree to display on your checkout, provided Cashfree is the Token Requestor (TR), the [Get All Saved Card Instrument API](/docs/api-reference/payments/latest/token-vault/fetch-all-saved-card-instrument) includes PAR in the response. Once a card is tokenised, the [Card Token Webhook](/docs/api-reference/payments/previous/v2023-08-01/token-vault/webhooks#instrument-active-webhook) also sends the PAR.

If you use an external Token Requestor (TR), then you'll have to get PAR from your TR.

### Get PAR for completed transactions

Retrieve the PAR of the card used for a successful transaction, if required for reconciliation purposes. Pass a transaction identifier as input in [Get Payments for Order API](/docs/api-reference/payments/latest/payments/get-payments-for-an-order) or [Get Payment by Transaction ID API](/docs/api-reference/payments/latest/payments/get-payment-by-id). PAR is also passed in [Payment Status Webhook](/docs/api-reference/payments/latest/payments/webhooks).

## FAQs

<AccordionGroup>
  <Accordion title="How can this feature be enabled?">
    This is a request-based feature, available only to PCI-DSS-compliant merchants. To enable it, reach out to your account manager or use the [raise an issue support form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1).
  </Accordion>

  <Accordion title="How can checkout merchants build this functionality?">
    Cashfree-hosted Checkout merchants use Cashfree’s [Offer Engine](/docs/payments/checkout/offers) to run offers. To set up risk checks, merchants leverage Cashfree’s [RiskShield](/docs/payments/risk-shield/overview) solution. Both offerings allow merchants to set up offer targeting strategies and risk rules through a self-serve flow on the Cashfree [Merchant Dashboard](https://merchant.cashfree.com/merchants), making implementation easy and effective.
  </Accordion>
</AccordionGroup>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/payments/latest/utilities/get-par">Get PAR API</a></li>
    <li><a href="/docs/api-reference/payments/latest/token-vault/fetch-all-saved-card-instrument">Get All Saved Instruments API</a></li>
    <li><a href="/docs/api-reference/payments/latest/payments/get-payments-for-an-order">Get Payments for Order API</a></li>
    <li><a href="/docs/payments/checkout/offers">Offer Engine</a></li>
    <li><a href="/docs/api-reference/payments/latest/payments/webhooks">Payment Status Webhook</a></li>
  </ul>
</div>


# Preauthorisation
Source: https://www.cashfree.com/docs/payments/features/pre-authorisation

Use Cashfree preauthorisation to hold funds on a customer's card now and capture or release them later, ideal for travel, rentals, and reservation use cases.

**Preauthorisation** (pre-auth) allows you to temporarily block funds on a customer’s card or account and capture the payment later, typically after order fulfilment. This helps secure funds without charging the customer immediately.

Cashfree Payment Gateway (PG) supports preauthorisation for the following payment methods:

* UPI
* Visa credit, debit, and prepaid cards
* Mastercard credit, debit, and prepaid cards
* Rupay credit, debit, and prepaid cards

## How preauthorisation works

Preauthorisation allows you to manage payments flexibly in the following ways:

* Authorise an amount on a customer’s card or account without immediate capture.
* Capture the authorised amount later—either fully or partially—when required.
* Void the authorisation to release the blocked funds if the order is not fulfilled.

Unlike standard transactions, where funds are instantly captured, preauthorisation provides flexibility in payment processing.

## Preauthorisation flow

1. The customer initiates the payment.
2. The bank blocks the amount on the customer’s card or account after successful payment completion.
3. You can:

* Either Capture the full or partial amount.\
  **OR**
* Void the authorisation to release the blocked funds to the customer.

<Note>
  **Note**: If not captured within seven days, the funds are automatically released.
</Note>

<Frame>
  <img />
</Frame>

## Preauthorisation feature request

<Note>Please use the [raise an issue support form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) to request this feature to be enabled for your account.</Note>

## Managing preauthorisation transactions

You can capture or void preauthorisation transactions from the **[Merchant Dashboard](https://merchant.cashfree.com/auth/login)** or integrate the capture and void APIs to automate the process.

<Note>
  **Note**

  >

  * You must capture or void a preauthorisation transaction within seven days of authorisation.
  * A transaction can only be captured or voided once.
  * Once captured, a transaction cannot be voided.
  * Once voided, a transaction cannot be captured.
  * Transactions not captured within seven days are automatically released back to the customer.
  * Voided transactions return funds to the customer immediately.
  * After preauthorisation is enabled for your account, ensure all preauthorisation transactions are either captured or voided.
  * For UPI, you can capture the transaction for up to one year or until the expiry date, whichever occurs first.
</Note>

## Supported payment instruments for preauthorisation

Cashfree Payment Gateway supports preauthorisation workflow on cards and UPI (Unified Payments Interface).

### Cards

Once preauthorisation is enabled for your account, every card payment will be preauthorised by default, you do not need to provide any additional parameters while initiating the payment.

Below is a sample [Order Pay API](/docs/api-reference/payments/latest/payments/order-pay) request and response:

<CodeGroup>
  ```json Sample request theme={"dark"}
  curl --request POST \
    --url https://sandbox.cashfree.com/pg/orders/sessions \
    --header 'Content-Type: application/json' \
    --header 'x-api-version: <x-api-version>' \
    --data '{
    "payment_session_id": "session__CvcEmNKDkmERQrxnx39ibhJ3Ii034pjc8ZVxf3qcgEXCWlgDDlHRgz2XYZCqpajDQSXMMtCusPgOIxYP2LZx0-05p39gC2Vgmq1RAj--gcn",
    "payment_method": {
      "card": {
        "channel": "link",
        "card_number": "4111111111111111",
        "card_expiry_mm": "06",
        "card_expiry_yy": "22",
        "card_cvv": "900",
        "card_holder_name": "Tushar Gupta"
      }
    },
    "save_instrument": true
  }'

  ```

  ```json Sample response theme={"dark"}
  {
     "action": "link",
     "cf_payment_id": "4105073870",
     "channel": "link",
     "data": {
         "url": "https://api.cashfree.com/pg/view/gateway/session_FEeYTISZ-xOJcuR7YeOZOm1MhVIrjHa2l1G79Pg_ZktVJxPSdu7oAKf9RTFZQlR19lkBU7VGIh8dARedu9otO8VstZVT3-HpjLpIn75v-hKCNOxYuEOV_wJ975ed89f2-ad57-4094-8728-7cff9f1928f2",
         "payload": null,
         "content_type": null,
         "method": null
     },
     "payment_amount": 1.00,
     "payment_method": "card"
  }
  ```
</CodeGroup>

### UPI

For UPI pre-auth, you need to pass additional parameters in the `/orders/pay` API request. Once you have created the order, invoke the [Order Pay API](/docs/api-reference/payments/latest/payments/order-pay) call with the `authorize_only`, `authorization` parameters.

The `authorization` object contains the following attributes:

* `approve_by` - The time by when customer needs to approve this one time mandate request.
* `start_time` - The time when the mandate should start.
* `end_time` - The time until when the mandate hold will be on customer’s bank account. You can call capture and void until this time.

#### UPI collect

Below is a sample UPI Collect request and response:

<CodeGroup>
  ```json UPI preauthorisation payment request theme={"dark"}
  curl --request POST \
    --url https://api.cashfree.com/pg/orders/sessions \
    --header 'Content-Type: application/json' \
    --data '{
  	"payment_session_id": "HTIdYxfOYgqKyYM3rLCZ",
  	"payment_method" : {
  		"upi" : { 
  			"channel": "collect",
  			"upi_id": "rohit@okicici",
  			"authorize_only": true,
  			"authorization" : {
            "approve_by": "2022-02-08T19:20:12+05:30",
            "start_time": "2022-02-09T12:34:34Z",
            "end_time": "2022-02-10T12:34:34Z"
         }			
  		}
  	}
  }'
  ```

  ```json Response theme={"dark"}
  {
  	"payment_method": "upi",
  	"channel": "collect",
  	"action": "custom",
  	"data": {
  		"url": null,
  		"payload": null,
  		"content_type": null,
  		"method": null
  	},
  	"cf_payment_id": 749079622
  }
  ```
</CodeGroup>

#### UPI intent

Below is a sample UPI Intent request and response:

<CodeGroup>
  ```json UPI preauthorisation payment request theme={"dark"}
  curl --request POST \
    --url https://api.cashfree.com/pg/orders/sessions \
    --header 'Content-Type: application/json' \
    --data '{
  	"payment_session_id": "HTIdYxfOYgqKyYM3rLCZ",
  	"payment_method" : {
  		"upi" : { 
  			"channel": "link",
  			"authorize_only": true,
  			"authorization" : {
            "approve_by": "2022-02-08T19:20:12+05:30",
            "start_time": "2022-02-09T12:34:34Z",
            "end_time": "2022-02-10T12:34:34Z"
         }			
  		}
  	}
  }'
  ```

  ```json Response theme={"dark"}
  {
    "action": "custom",
    "cf_payment_id": 2333615254,
    "channel": "link",
    "data": {
      "url": null,
      "payload": {
        "bhim": "bhim://upi/mandate?pa=MerchantVPA@Bank&pn=MerchantName&tr=transactionref1234&am=5.00&cu=INR&orgid=400011&mc=4722&purpose=01&tn=Cashfree%20Payments&validitystart=19122023&validityend=28122023&amrule=MAX&recur=ONETIME&rev=N&share=Y&block=Y&txnType=CREATE&mode=13",
        "default": "upi://mandate?pa=MerchantVPA@Bank&pn=MerchantName&tr=transactionref1234&am=5.00&cu=INR&orgid=400011&mc=4722&purpose=01&tn=Cashfree%20Payments&validitystart=19122023&validityend=28122023&amrule=MAX&recur=ONETIME&rev=N&share=Y&block=Y&txnType=CREATE&mode=13",
        "gpay": "tez://upi/mandate?pa=MerchantVPA@Bank&pn=MerchantName&tr=transactionref1234&am=5.00&cu=INR&orgid=400011&mc=4722&purpose=01&tn=Cashfree%20Payments&validitystart=19122023&validityend=28122023&amrule=MAX&recur=ONETIME&rev=N&share=Y&block=Y&txnType=CREATE&mode=13",
        "paytm": "paytmmp://upi/mandate?pa=MerchantVPA@Bank&pn=MerchantName&tr=transactionref1234&am=5.00&cu=INR&orgid=400011&mc=4722&purpose=01&tn=Cashfree%20Payments&validitystart=19122023&validityend=28122023&amrule=MAX&recur=ONETIME&rev=N&share=Y&block=Y&txnType=CREATE&mode=13",
        "phonepe": "phonepe://upi/mandate?pa=MerchantVPA@Bank&pn=MerchantName&tr=transactionref1234&am=5.00&cu=INR&orgid=400011&mc=4722&purpose=01&tn=Cashfree%20Payments&validitystart=19122023&validityend=28122023&amrule=MAX&recur=ONETIME&rev=N&share=Y&block=Y&txnType=CREATE&mode=13",
        "web": "https://api.cashfree.com/pg/view/upi/25hg94m.ZUlx19KgZ48TXh82GrsNamC20vVw0QVK17xLE2BFOo.708f026c-5f7d-4c49-9"
      },
      "content_type": null,
      "method": null
    },
    "payment_amount": 5,
    "payment_method": "upi"
  }
  ```
</CodeGroup>

### Capture

The capture workflow helps you to capture the payment and move the authorised amount partially or completely from customers bank account to your bank account, by calling [Pre-Authorisation API](/docs/api-reference/payments/latest/payments/preauthorisation) for capture.

<CodeGroup>
  ```json Capture request theme={"dark"}
  curl --request POST \
    --url https://api.cashfree.com/pg/orders/:order_id/authorization \
    --header 'Content-Type: application/json' \
    --header 'x-api-version: <<api_version>>' \
    --header 'x-client-id: <<app_id>>' \
    --header 'x-client-secret: <<secret_key>>' \
    --data '{
    "action": "CAPTURE",
    "amount": "2.00"
  }'
  ```

  ```json Capture response - Cards theme={"dark"}
  {
    "auth_id": "016381",
    "authorization": {
      "action": "CAPTURE",
      "status": "SUCCESS",
      "captured_amount": 1,
      "start_time": "2025-07-15T16:40:24+05:30",
      "end_time": "2025-07-18T16:40:24+05:30",
      "approve_by": null,
      "action_reference": "7525782703466058805917",
      "action_time": "2025-07-15T16:47:50.285775"
    },
    "bank_reference": "519611740779",
    "cf_payment_id": "4129256397",
    "entity": "payment",
    "error_details": null,
    "international_payment": {
      "international": false
    },
    "is_captured": true,
    "order_amount": 1,
    "order_currency": "INR",
    "order_id": "abhishek-287",
    "payment_amount": 1,
    "payment_completion_time": "2025-07-15T16:40:51+05:30",
    "payment_currency": "INR",
    "payment_gateway_details": {
      "gateway_name": "CASHFREE",
      "gateway_order_id": null,
      "gateway_payment_id": null,
      "gateway_order_reference_id": null,
      "gateway_status_code": null,
      "gateway_settlement": "cashfree",
      "gateway_reference_name": null
    },
    "payment_group": "debit_card",
    "payment_message": "PRE_AUTH|Transaction Success",
    "payment_method": {
      "card": {
        "card_bank_name": "KOTAK MAHINDRA BANK",
        "card_country": "IN",
        "card_network": "visa",
        "card_network_reference_id": null,
        "card_number": "XXXXXXXXXXXX4738",
        "card_sub_type": "R",
        "card_type": "debit_card",
        "channel": "link"
      }
    },
    "payment_offers": null,
    "payment_status": "SUCCESS",
    "payment_surcharge": null,
    "payment_time": "2025-07-15T16:40:24+05:30"
  }
  ```

  ```json Capture response - UPI theme={"dark"}

  {
  	"auth_id": "203924176048",
  	"authorization": {
  		"action": "CAPTURE",
  		"status": "SUCCESS",
  		"captured_amount": 2.00,
  		"start_time": "2022-02-09T18:04:34+05:30",
  		"end_time": "2022-02-10T18:04:34+05:30",
  		"approve_by": "2022-02-08T19:20:12+05:30"
  	},
  	"bank_reference": "203924176048",
  	"cf_payment_id": 7079622,
  	"entity": "payment",
  	"is_captured": false,
  	"order_amount": 3.00,
  	"order_id": "order_184824oxmihLPJhERptCzgR08YGOan2",
  	"payment_amount": 3.00,
  	"payment_currency": "INR",
  	"payment_group": "upi",
  	"payment_message": "PRE_AUTH|Transaction initiated",
  	"payment_method": {
  		"upi": {
  			"channel": "collect",
  			"upi_id": "rohit@okicici"
  		}
  	},
  	"payment_status": "SUCCESS",
  	"payment_time": "2022-02-08T14:31:56+05:30"
  }

  ```
</CodeGroup>

### Void

The void workflow helps you to release the entire authorised amount back to the customer, by calling [Pre-Authorisation API](/docs/api-reference/payments/latest/payments/preauthorisation) for void.

<CodeGroup>
  ```json Void request theme={"dark"}
  curl --request POST \
    --url https://api.cashfree.com/pg/orders/:order_id/authorization \
    --header 'Content-Type: application/json' \
    --header 'x-api-version: <<api_version>>' \
    --header 'x-client-id: <<app_id>>' \
    --header 'x-client-secret: <<secret_key>>' \
    --data '{
    "action": "VOID"
  }'
  ```

  ```json Void response - Cards theme={"dark"}
  {
    "auth_id": "023166",
    "authorisation": {
      "action": "VOID",
      "status": "SUCCESS",
      "captured_amount": null,
      "start_time": "2025-07-15T16:49:06+05:30",
      "end_time": "2025-07-18T16:49:06+05:30",
      "approve_by": null,
      "action_reference": "7525784179616489005910",
      "action_time": "2025-07-15T16:50:17.911008"
    },
    "bank_reference": "519611251479",
    "cf_payment_id": "4129285491",
    "entity": "payment",
    "error_details": null,
    "international_payment": {
      "international": false
    },
    "is_captured": false,
    "order_amount": 1,
    "order_currency": "INR",
    "order_id": "abhishek-288",
    "payment_amount": 1,
    "payment_completion_time": "2025-07-15T16:49:40+05:30",
    "payment_currency": "INR",
    "payment_gateway_details": {
      "gateway_name": "CASHFREE",
      "gateway_order_id": null,
      "gateway_payment_id": null,
      "gateway_order_reference_id": null,
      "gateway_status_code": null,
      "gateway_settlement": "cashfree",
      "gateway_reference_name": null
    },
    "payment_group": "debit_card",
    "payment_message": "PRE_AUTH|Transaction Success",
    "payment_method": {
      "card": {
        "card_bank_name": "KOTAK MAHINDRA BANK",
        "card_country": "IN",
        "card_network": "visa",
        "card_network_reference_id": null,
        "card_number": "XXXXXXXXXXXX4738",
        "card_sub_type": "R",
        "card_type": "debit_card",
        "channel": "link"
      }
    },
    "payment_offers": null,
    "payment_status": "VOID",
    "payment_surcharge": null,
    "payment_time": "2025-07-15T16:49:06+05:30"
  }
  ```

  ```json Void response - UPI theme={"dark"}
  {
  	"auth_id": null,
  	"authorisation": {
  		"action": "VOID",
  		"status": "SUCCESS",
  		"captured_amount": null,
  		"start_time": "2022-02-09T18:04:34+05:30",
  		"end_time": "2022-02-10T18:04:34+05:30",
  		"approve_by": "2022-02-08T19:20:12+05:30"
  	},
  	"bank_reference": "203924193623",
  	"cf_payment_id": 749235871,
  	"entity": "payment",
  	"is_captured": false,
  	"order_amount": 3.00,
  	"order_id": "order_184824pANPV12CVRkdxHi3mrPZ9KOcg",
  	"payment_amount": 3.00,
  	"payment_currency": "INR",
  	"payment_group": "upi",
  	"payment_message": "PRE_AUTH|Transaction initiated",
  	"payment_method": {
  		"upi": {
  			"channel": "collect",
  			"upi_id": "rsedwardian@okicici"
  		}
  	},
  	"payment_status": "VOID",
  	"payment_time": "2022-02-08T16:15:23+05:30"
  }
  ```
</CodeGroup>

## FAQs

<AccordionGroup>
  <Accordion title="What is a capture call in preauthorisation?">
    Capture call is performed after authorisation. It is a merchant-initiated request (via API or Merchant Dashboard) to collect the previously authorised funds. This step debits the amount from the customer.
  </Accordion>

  <Accordion title="What is the validity of capture?">
    If not captured within 7 days, the authorisation expires, and the funds are released back to the customer.
  </Accordion>

  <Accordion title="Can a merchant capture a partial amount?">
    Yes, merchants can capture a partial amount of the authorised funds.
  </Accordion>

  <Accordion title="Is MDR charged on the authorised or captured amount?">
    MDR is always applied only on the captured amount.
  </Accordion>

  <Accordion title="Which cards support preauthorisation?">
    All Visa, Mastercard and RuPay credit, debit and prepaid cards support preauthorisation.
  </Accordion>

  <Accordion title="What is void in preauthorisation?">
    A void call cancels the authorisation before capture, releasing the hold on funds.
  </Accordion>

  <Accordion title="Can a merchant void a partial amount?">
    No, voiding must be for the entire authorised amount.
  </Accordion>

  <Accordion title="What are some common use cases for preauthorisation?">
    Here are some common use cases:

    <ul>
      <li>**Ticket Bookings** – Airlines, concerts, and events often place a hold on a credit card to ensure funds are available before finalising the booking. This is useful if confirmation is pending or for refundable ticket options.</li>
      <li>**Car Rentals** – Rental companies use preauthorisation to secure a deposit in case of damages, late returns, or additional charges. The hold is released if no extra fees are incurred.</li>
      <li>**Hotel Reservations** – Hotels preauthorise a guest’s credit card at check-in to cover potential incidentals, damages, or unpaid charges, ensuring payment security before checkout.</li>
    </ul>
  </Accordion>

  <Accordion title="Is preauthorisation feasible via payment links and payment forms?">
    Yes, preauthorisation is feasible on both payment links and payment forms.

    <h3>Payment Links</h3>
    **How it works:**

    <ol>
      <li>The merchant generates a payment link on a preauthorisation-enabled account.</li>
      <li>The customer selects the link and enters payment details.</li>
      <li>The payment is authorised (funds are held but not captured immediately).</li>
      <li>The merchant can capture the payment later when needed.</li>
      <li>If the order is cancelled, the hold can be released without charging the card.</li>
    </ol>

    <h3>Payment Forms</h3>
    **How it works:**

    <ul>
      <li>The customer enters payment details in the form.</li>
      <li>The system processes an authorisation-only request.</li>
      <li>The merchant can capture the funds later or release the authorisation if the transaction is voided.</li>
    </ul>
  </Accordion>

  <Accordion title="How does settlement occur in a preauthorisation transaction?">
    Settlement occurs when the merchant finalises a preauthorised transaction by capturing the funds.
  </Accordion>

  <Accordion title="When does the merchant receive the funds in a preauthorisation transaction?">
    Merchants typically receive funds from preauthorised transactions as per their normal settlement cycle, i.e., T+x days after a successful capture.
  </Accordion>

  <Accordion title="What happens if a customer disputes a settled transaction?">
    A dispute may result in a chargeback, requiring the merchant to provide proof of authorisation and service fulfilment.
  </Accordion>

  <Accordion title="Is the preauthorisation feature supported on American Express and Diners cards?">
    Currently, the preauthorisation feature is not supported for American Express and Diners cards due to limitations imposed by the respective card networks. We are actively monitoring any changes in network policies and will update our services accordingly if support becomes available in the future.
  </Accordion>

  <Accordion title="Is preauthorisation supported in the WooCommerce plugin?">
    No. Preauthorisation is not supported as a standard feature in the WooCommerce plugin. To use the preauthorisation flow, you must implement it via custom API integration using the Cashfree API directly.
  </Accordion>

  <Accordion title="Which are the sponsor banks live on preauthorisation?">
    The following sponsor banks currently support the preauthorisation feature on Cashfree:

    * Axis Bank
    * HDFC Bank
    * ICICI Bank
    * IndusInd Bank
    * Kotak Mahindra Bank
    * Yes Bank
    * Federal Bank
    * State Bank of India
  </Accordion>
</AccordionGroup>

<snippet>snippets/related-topics-loader.mdx</snippet>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/payments/latest/payments/order-pay">Order Pay API</a></li>
    <li><a href="/docs/api-reference/payments/latest/payments/preauthorisation">Pre-Authorisation API</a></li>
  </ul>
</div>


# Token Vault
Source: https://www.cashfree.com/docs/payments/features/token-vault

Securely process saved card payments with Cashfree Token Vault, an RBI-compliant tokenisation service that protects cardholder data on every order.

Cashfree's Token Vault is an industry-leading solution that enables you to offer customers a secure save card functionality whilst remaining RBI compliant. The solution provides a fast and secure checkout experience that delivers higher conversion rates and improved payment success rates.

<Tip>Saved card transactions have approximately 10% better success rates compared to guest checkout transactions.</Tip>

### Key benefits of Cashfree's token vault

The following features make Cashfree's Token Vault solution comprehensive:

* **Full compliance**: Cashfree is a certified and compliant Token Requestor supporting all card types and schemes (Visa, Mastercard, RuPay, AmEx, Diners).
* **Enhanced performance**: Saved card payments deliver \~10% better success rates and increased conversions.
* **Seamless experience**: Integration with [CVV-Less](/docs/payments/features/cvv-less) and [Native OTP](/docs/payments/features/native-otp) features for frictionless checkout.
* **Interoperability**: Support for cross-platform scenarios where you can save cards via one payment aggregator and process via another.

## Tokenisation

Tokenisation is the process of replacing sensitive card details such as card number, expiry, and CVV with a unique, non-sensitive identifier called a token. This process ensures that actual card data is never stored or exposed during transactions.

### Key concepts

Understanding these terms helps you implement tokenisation effectively:

* **Token Requestor**: The merchant or payment gateway (like Cashfree) that initiates tokenisation requests on behalf of merchants
* **Token Service Provider**: The card network or issuing bank that generates and manages tokens
* **Token**: A unique identifier specific to each combination of card, merchant, customer, and Token Requestor

Each token is cryptographically secure and can't be reverse-engineered to reveal the original card details, unlike standard encryption methods.

<Frame>
  <img />
</Frame>

### Customer journey

The tokenisation process provides a seamless experience for customers across their payment lifecycle:

<Frame>
  <img />
</Frame>

#### First-time payment with guest checkout

The initial tokenisation process works as follows:

1. Customer enters full card details and consents to save the card
2. Customer completes payment authentication using OTP
3. Cashfree generates an Alt ID and cryptogram to process the transaction
4. After successful transaction processing, Cashfree tokenises the card with the card network/issuer
5. Cashfree receives the token and the card is saved for future use

#### Repeat payment with saved card

Subsequent payments use the saved token for enhanced security and speed:

1. Saved cards appear at checkout with identifiers (last 4 digits, issuing bank, card network)
2. Customer selects a previously saved card
3. Cashfree fetches the token and generates a cryptogram from the network/issuer
4. Customer completes OTP authentication
5. Payment processes securely using the token without exposing actual card data

## Integrating with Cashfree's Token Vault

Cashfree offers different integration methods for its Token Vault:

### Merchants with CF-hosted checkout

Merchants using Cashfree hosted checkout will be able to use tokenisation functionality with zero additional effort. It's enabled by default for all checkout merchants, and Cashfree handles tokenisation and payment processing end-to-end.

* Customers can save their card by opting for tokenisation on the checkout. The checkout also displays a nudge highlighting the benefits of saving the card.

<Frame>
  <img />
</Frame>

* For repeat customers there's OTP based authentication for the first time, before displaying saved cards, for added layer of security.
* Repeat customers can select a saved card and have a [CVV-Less](/docs/payments/features/cvv-less) payment experience with just a single click!

### Seamless merchants with merchant-hosted checkout

Merchants using the seamless flow, can integrate Cashfree's Token Vault APIs with their platform. Once integrated, Cashfree handles both saving cards and processing payments via saved cards.

#### Saving the card with Cashfree as Token Requestor

* In [Create Order API](/docs/api-reference/payments/latest/orders/create-order), merchant needs to pass `customer_id`, against which the token would be generated and stored.
* For card payments ask for customer consent on the UI to save the card, and then in [Order Pay API](/docs/api-reference/payments/latest/payments/order-pay) pass `save_instrument: true`. Merchants can also add a nudge stating benefits of tokenisation to prompt users to save the card.

```bash cURL {17} theme={"dark"}
curl --request POST \
  --url https://sandbox.cashfree.com/pg/orders/sessions \
  --header 'Content-Type: application/json' \
  --header 'x-api-version: <x-api-version>' \
  --data '{
  "payment_session_id": "session__someidwhichislongandhasnumbers1232132andcharacterscn",
  "payment_method": {
    "card": {
      "channel": "link",
      "card_number": "4111111111111111",
      "card_expiry_mm": "06",
      "card_expiry_yy": "22",
      "card_cvv": "900",
      "card_holder_name": "Tushar Gupta"
    }
  },
  "save_instrument": true
}'
```

* Cashfree first processes the plain card transaction via alt ID and cryptogram. If the transaction succeeds, Cashfree tokenises and saves the card. If the transaction fails, Cashfree does not attempt tokenisation or save the card, because a successfully authenticated transaction is a prerequisite for tokenisation.
* You can also configure [tokenisation webhooks](/docs/api-reference/payments/latest/token-vault/webhooks) to receive callbacks on whether the card was saved.

#### Using Cashfree as Token Requestor and processing payment via Cashfree

* In order to display saved cards for a customer on checkout, call [Fetch All Saved Card Instruments](/docs/api-reference/payments/previous/v2023-08-01/token-vault/get-all) API with `customer_id`, merchant will get complete details of all cards saved for that customer like card type, issuing bank, card scheme, last 4 digits of card - which they can display on checkout so that customer can identify its cards and select one of them for payment.
* To process payment via saved card, call [Order Pay](/docs/api-reference/payments/latest/payments/order-pay) API and pass `instrument_id` received in response of [Fetch All Saved Card Instruments](/docs/api-reference/payments/previous/v2023-08-01/token-vault/get-all) API, corresponding to the card that was selected by the customer on checkout. Cashfree would fetch the token and cryptogram against that card and process the payment.

```bash cURL {10} theme={"dark"}
curl --request POST \
  --url https://sandbox.cashfree.com/pg/orders/sessions \
  --header 'Content-Type: application/json' \
  --header 'x-api-version: <x-api-version>' \
  --data '{
  "payment_session_id": "session__CvcEmNKDkmERQrxnx39ibhJ3Ii034pjc8ZVxf3qcgEXCWlgDDlHRgz2XYZCqpajDQSXMMtCusPgOIxYP2LZx0-05p39gC2Vgmq1RAj--gcn",
  "payment_method": {
    "card": {
      "channel": "link",
      "instrument_id": "54deabb4-ba45-4a60-9e6a-9c016fe7ab10",
	  "card_cvv": "900" // Optional
    }
  }
}'
```

* Saved cards don't require CVV to process the payment. For a more seamless checkout experience, avoid collecting CVV for saved cards. For more information, refer to [CVV-Less Card Payments](/docs/payments/features/cvv-less).

<Tip>CVV-less flow has approximately 5% better success rates for saved cards.</Tip>

#### Using external Token Requestor and processing payment via Cashfree

* Cashfree's Token Vault solution is interoperable. If you use an external **Token Requestor**, you can still process those tokenised cards through Cashfree.

For external guest checkout transaction:

* Once a customer enters plain card on Checkout, the merchant needs to get the Alt ID and cryptogram from its *Token Requestor*.
* In [Order Pay](/docs/api-reference/payments/latest/payments/order-pay) API pass alt id number, alt id expiry, cryptogram, cvv generated by your *Token Requestor* against the plain card details. Cashfree would use Alt ID and cryptogram to process the payment.

```bash cURL {10,11,12,13,14,15} theme={"dark"}
curl --request POST \
  --url https://sandbox.cashfree.com/pg/orders/sessions \
  --header 'Content-Type: application/json' \
  --header 'x-api-version: <x-api-version>' \
  --data '{
  "payment_session_id": "session__CvcEmNKDkmERQrxnx39ibhJ3Ii034pjc8ZVxf3qcgEXCWlgDDlHRgz2XYZCqpajDQSXMMtCusPgOIxYP2LZx0-05p39gC2Vgmq1RAj--gcn",
  "payment_method": {
    "card": {
      "channel": "link",
      "card_number": "4111111111111111", // alt id number
      "card_expiry_mm": "03", // alt id expiry mm
      "card_expiry_yy": "26", // alt id expiry yy
      "cryptogram": "AQBBBBBBZatIlaIAmWKSghwBBBB=",
      "card_cvv": "900",
      "token_type": "NETWORK_GC_TOKEN",
      "card_holder_name": "Tushar Gupta", //optional
      "card_display": "3243", // optional
      "token_reference_id": "22457512314" // conditional, required only for diners
    }
  }
}'
```

For external saved card transaction:

* To process payment with cards saved via an external *Token Requestor*, fetch all saved cards from the *Token Requestor* and display it on checkout. Once a customer selects a saved card, merchant needs to get the token and cryptogram from its *Token Requestor* as only the *Token Requestor* is allowed to generate cryptogram required for transaction processing.
* In [Order Pay](/docs/api-reference/payments/latest/payments/order-pay) API pass token number, token expiry, cryptogram of the card that was selected by the customer on checkout. Cashfree would use that token and cryptogram to process the payment.

```bash cURL {10,11,12,13,14} theme={"dark"}
curl --request POST \
  --url https://sandbox.cashfree.com/pg/orders/sessions \
  --header 'Content-Type: application/json' \
  --header 'x-api-version: <x-api-version>' \
  --data '{
  "payment_session_id": "session__CvcEmNKDkmERQrxnx39ibhJ3Ii034pjc8ZVxf3qcgEXCWlgDDlHRgz2XYZCqpajDQSXMMtCusPgOIxYP2LZx0-05p39gC2Vgmq1RAj--gcn",
  "payment_method": {
    "card": {
      "channel": "link",
      "card_number": "4111111111111111", // token number
      "card_expiry_mm": "03", // token expiry mm
      "card_expiry_yy": "26", // token expiry yy
      "cryptogram": "AQBBBBBBZatIlaIAmWKSghwBBBB=",
      "token_requestor_id": "22457512314", 
      "card_cvv": "900", // optional
      "card_holder_name": "Tushar Gupta" // optional
      "card_display": "3243" // optional
    }
  }
}'
```

* Saved cards don't require CVV to process the payment. For a more seamless checkout experience, avoid collecting CVV for saved cards. CVV is an optional field in the API request. For more information about the CVV-less flow, refer to [CVV-Less Card Payments](/docs/payments/features/cvv-less).

#### Using Cashfree as Token Requestor and processing payment externally

* Cashfree's Token Vault solution is interoperable. To process payment with an external PA for a card saved with Cashfree, merchant needs to get the token and cryptogram from Cashfree, as only the *Token Requestor*, Cashfree in this case, is allowed to generate cryptogram required for transaction processing.
* Call [Fetch All Saved Card Instruments](/docs/api-reference/payments/previous/v2023-08-01/token-vault/get-all) API with `customer_id`, merchant will get complete details of all cards saved for that customer to display it on checkout.
* Once customer selects one of these cards, merchant needs to call [Fetch Cryptogram for a Saved Card Instrument](/docs/api-reference/payments/latest/token-vault/fetch-cryptogram-for-a-saved-card-instrument) API with `customer_id` and `instrument_id` to get the cryptogram.
* Merchant can then use this token and cryptogram to process the payment with any Payment Aggregator.

## FAQs

<AccordionGroup>
  <Accordion title="What all card details can the merchant save under tokenisation guidelines?">
    Merchants are allowed to store only the **card BIN**, **last 4 digits of the actual card number**, and **card expiry**.

    They can't store the entire plain card number or CVV.
  </Accordion>

  <Accordion title="Can a card be saved without a successful transaction?">
    No. A successfully authenticated transaction is a **pre-requisite** for tokenising the card.
  </Accordion>

  <Accordion title="Can a tokenised card be processed by any payment aggregator?">
    Yes. Cashfree's **token vault solution is interoperable**.

    A token generated with one payment aggregator can be processed via any PA, provided that the same PA generates and provides the **cryptogram** from the card network. That token + cryptogram can then be used by any PA to process the payment.
  </Accordion>

  <Accordion title="Can tokens created with another provider be migrated to Cashfree?">
    No. Tokens **aren't portable** due to the ecosystem limitations.

    * Merchants can continue using their existing token vault and get the **token + cryptogram** from it to process with Cashfree.
    * Or, merchants must ask customers to **save cards again**, which would then be stored in Cashfree's token vault.
  </Accordion>

  <Accordion title="Does Cashfree offer TSP capability for token vault?">
    Yes. Cashfree offers a **standalone, plug and play token vault solution**.

    * The merchant can act as the ***Token Requestor*** by procuring their own **TRID (*Token Requestor* ID)** directly from the card networks.
    * Cashfree enables merchants to tokenise cards, generate and retrieve cryptograms, and process transactions seamlessly through **any payment aggregator (including Cashfree)**.
    * This ensures flexibility whilst maintaining compliance with **network tokenisation standards**.
  </Accordion>
</AccordionGroup>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/payments/latest/orders/create-order">Create Order API</a></li>
    <li><a href="/docs/api-reference/payments/latest/payments/order-pay">Order Pay API</a></li>
    <li><a href="/docs/api-reference/payments/latest/token-vault/fetch-all-saved-card-instrument">Fetch All Saved Instruments API</a></li>
    <li><a href="/docs/payments/features/cvv-less">CVV-Less</a></li>
    <li><a href="/docs/payments/features/native-otp">Native OTP</a></li>
  </ul>
</div>


# Third Party Validation
Source: https://www.cashfree.com/docs/payments/features/tpv

Learn how to verify customer payments through specific bank accounts using TPV, including multi-bank support for UPI, NetBanking, and bank transfers (Challans).

For merchants with Third-Party Validation (TPV) enabled on UPI or NetBanking, Cashfree shares the customer's bank account details with the issuing bank, which checks that the payment is sent from the expected account.

For [bank transfers](/docs/payments/manage/payment-methods/bank-transfers) (Challans), Cashfree validates the incoming IMPS, NEFT, or RTGS transfer against the order and the account details you pass when TPV is enabled.

TPV applies across these payment methods: the values you pass in `customer_bank_account_number` and `customer_bank_ifsc` (and `customer_bank_code` for NetBanking TPV) must match how the customer actually pays.

<Tip>
  Fill this [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) or contact your account manager to enable TPV for your account.
</Tip>

To process a TPV payment through Cashfree, include specific customer details in the Create Order API request. During checkout (UPI or NetBanking) or when the bank transfer is received (Challan), Cashfree checks these details against the payer or remitter information for that payment. The required fields are `customer_bank_account_number` and `customer_bank_ifsc`, where the IFSC is an alphanumeric code (for example, `SBIN000001`) that uniquely identifies a bank branch in India.

## Implement a TPV-enabled order

To process a payment with bank account verification (TPV), pass the customer account number (`customer_bank_account_number`) and IFSC (`customer_bank_ifsc`) with every Create Order request. If you want the customer to pay through NetBanking, also pass `customer_bank_code`. For [bank transfers](/docs/payments/manage/payment-methods/bank-transfers) (Challans), the customer pays to a Virtual Bank Account; Cashfree validates the remitter account and IFSC against the same TPV fields when the transfer is received.

<CodeGroup>
  ```shell cURL request {13-15} theme={"dark"}
  curl --request POST \
    --url https://sandbox.cashfree.com/pg/orders \
    --header 'Content-Type: application/json' \
    --header 'x-api-version: 2022-09-01' \
    --header 'x-client-id: xxxx' \
    --header 'x-client-secret: xxxx' \
    --data '{
      "customer_details": {
          "customer_email": "test@cashfree.com",
          "customer_id": "LD09755CSCON10092021",
          "customer_name": "Rohit",
          "customer_phone": "9999911111",
          "customer_bank_ifsc": "CITI0000001",
          "customer_bank_account_number": "1518121112",
          "customer_bank_code": "3044"
      },
      "order_amount": 1,
      "order_currency": "INR"
    }'
  ```

  ```json Response {13-14} theme={"dark"}
  {
    "cf_order_id": 621203980,
    "order_id": "order_1065211zDHKtAsflTH9dczd6itFy1wFv8",
    "entity": "order",
    "order_currency": "INR",
    "order_amount": 2.00,
    "order_expiry_time": "2021-11-07T12:17:57+05:30",
    "customer_details": {
      "customer_id": "LD09755CSCON10092021",
      "customer_name": "Rohit",
      "customer_email": "test@cashfree.com",
      "customer_phone": "9999911111",
      "customer_bank_ifsc": "CITI0000001",
      "customer_bank_account_number": "1518121112"
    },
    "order_meta": {
      "return_url": null,
      "notify_url": null,
      "payment_methods": null
    },
    "order_status": "ACTIVE",
    "payment_session_id": "NLfmvDBT3dfdflkjlu1JNHDcSDFACAsEqEdKMLuW",
    "order_note": "5% club",
    "order_tags": null,
    "order_splits": []
  }
  ```
</CodeGroup>

## Pre-built UI

To process a TPV payment using the pre-built UI, [open checkout](/docs/payments/online/web/redirect) using the `payment_session_id` from the Create Order API response. The customer can then complete payment only through their linked account using an enabled method such as UPI, NetBanking, or a [bank transfer](/docs/payments/manage/payment-methods/bank-transfers) (Challan). If the customer attempts to pay from a different account, the payment fails and the order remains in an `ACTIVE` state.

## Custom UI

To process TPV payments with your own UI. You will have to either integrate the javascript elements SDK or use the `/orders/sessions` API. There is no change in this api request and you can read about the API contract [here](/docs/api-reference/payments/latest/payments/order-pay).

To process TPV payments using your own UI, integrate either the JavaScript Elements SDK or use the `/orders/sessions` API. There is no change to the API request. You can read about the [API contract for the payments pay endpoint](/docs/api-reference/payments/latest/payments/order-pay). Offer UPI, NetBanking, and [bank transfers](/docs/payments/manage/payment-methods/bank-transfers) (Challans) according to the payment methods enabled on your account.

## TPV with payment links

You can process TPV payments using Payment Links through the Payment Link API, a bulk CSV file upload, or the Cashfree Dashboard. Pass `customer_bank_account_number` and `customer_bank_ifsc` for every TPV link; include `customer_bank_code` when you expect the customer to pay with NetBanking. Field usage for [bank transfers](/docs/payments/manage/payment-methods/bank-transfers) (Challans) differs from NetBanking; see the "Implement a TPV-enabled order" and "Multi-bank TPV" sections on this page. Which payment methods appear on the link depends on what you enable for that link.

### Bulk upload

When using a CSV file to bulk-create payment links, pass the customer bank details using the Notes columns. Use the following column mapping:

* **Note 1:** `customer_bank_code`
* **Note 2:** `customer_bank_account_number`
* **Note 3:** `customer_bank_ifsc`

The following sample file illustrates the expected format. In this example, `Note 1 Title` is set to `customer_bank_code` and the corresponding value appears in `Note 1 Description`.

<Accordion title="Sample CSV">
  ```csv theme={"dark"}
  Link Id,Expiry Time,Currency,Amount,Min Amount,Description,Customer Name,Customer Phone,Customer Email,Note 1 Title,Note 1 Description,Note 2 Title,Note 2 Description,Note 3 Title,Note 3 Description,Webhook URL

  Order-12zzsa,2023-02-11,INR,22.5,10,Payment for order,John Doe,9999999999,John.doe@cashfree.com,customer_bank_code,3044,customer_bank_account_number,37866911583,customer_bank_ifsc,SBIN0001882,https://cashfree.com/callback-webhook
  Order-12zsdca,2023-02-11,INR,22.5,10,Payment for order,John Doe,9999999999,John.doe@cashfree.com,customer_bank_code,3026,customer_bank_account_number,6633835901,customer_bank_ifsc,IDIB000V018,https://cashfree.com/callback-webhook
  ```
</Accordion>

### Payment Link API

To use TPV with the Payment Link API, pass the customer bank details in the `customer_details` object. See the request and response below for reference.

<CodeGroup>
  ```bash cURL request {12-14} theme={"dark"}
  curl --request POST \
    --url https://api.cashfree.com/pg/links \
    --header 'Content-Type: application/json' \
    --header 'x-api-version: 2025-01-01' \
    --header 'x-client-id: xxxx' \
    --header 'x-client-secret: xxxx' \
    --data '{
       "customer_details": {
            "customer_phone": "9908734803",
            "customer_email": "customer@example.com",
            "customer_name": "Rohit",
            "customer_bank_account_number": "78123123",
            "customer_bank_ifsc": "SBIN0000001",
            "customer_bank_code": "3044"
       },
       "link_notify": {
            "send_sms": true
       },
       "link_id": "testlink12354",
       "link_amount": 4,
       "link_currency": "INR",
       "link_purpose": "Test for TPV"
    }'
  ```

  ```json Response {24-28} theme={"dark"}
  {
    "cf_link_id": 14796319,
    "link_id": "testlink12354",
    "link_status": "ACTIVE",
    "link_currency": "INR",
    "link_amount": 4,
    "link_amount_paid": 0,
    "link_partial_payments": false,
    "link_minimum_partial_amount": null,
    "link_purpose": "Test for TPV",
    "link_created_at": "2023-02-09T23:25:16+05:30",
    "customer_details": {
      "customer_name": "Rohit",
      "country_code": "+91",
      "customer_phone": "9908734803",
      "customer_email": "customer@example.com"
    },
    "link_meta": {
      "payment_methods": "",
      "upi_intent": "false"
    },
    "link_url": "https://payments.cashfree.com/links/U4dfsav0ug50",
    "link_expiry_time": "2023-03-11T23:25:16+05:30",
    "link_notes": {
      "customer_bank_account_number": "5178191812",
      "customer_bank_code": "3044",
      "customer_bank_ifsc": "CITI0000001"
    },
    "link_auto_reminders": false,
    "link_notify": {
      "send_email": false,
      "send_sms": true
    }
  }
  ```
</CodeGroup>

## Multi-bank TPV

Multi-bank TPV allows you to pass up to four customer bank accounts in a single payment request. Customers can select their preferred account at checkout, which increases the likelihood of a successful payment.

Multi-bank TPV is supported on the following payment methods:

* UPI
* NetBanking
* [Bank transfers](/docs/payments/manage/payment-methods/bank-transfers) (Challans)

<Note>
  For bank transfers (Challans), the `customer_bank_account_number` and `customer_bank_ifsc` fields are used to validate the remitter when the transfer reaches the Virtual Bank Account.
</Note>

To pass multiple accounts, use pipe-separated values (`|`) in the `customer_bank_account_number` and `customer_bank_ifsc` fields within the `customer_details` object. The mapping between accounts and IFSC codes is index-based, so the order of values in both fields must match.

The following example shows a Create Order request with three bank accounts:

```json theme={"dark"}
"customer_details": {
  "customer_id": "customer_1",
  "customer_email": "customer@email.com",
  "customer_phone": "+919999999999",
  "customer_bank_account_number": "1234567891|1234567892|1234567893",
  "customer_bank_ifsc": "SBIN000000001|ICIC000000002|HDFC000000003"
}
```

### Key rules

Follow these rules when passing multiple bank accounts for **multi-bank UPI or NetBanking** TPV. They do not describe multi-account selection for [bank transfers](/docs/payments/manage/payment-methods/bank-transfers) (Challans); use a single expected remitter account and IFSC for Challan TPV unless Cashfree confirms otherwise for your account.

* You can pass a maximum of four bank accounts per request.
* The `customer_bank_account_number` and `customer_bank_ifsc` fields must contain the same number of pipe-separated values. Account 1 maps to IFSC 1, account 2 maps to IFSC 2, and so on.

### UPI

Multi-bank TPV for UPI is supported on select UPI rails. Contact the Cashfree team to get the required rails enabled for your account.

### NetBanking

When using multi-bank TPV with NetBanking, do not pass a value in `customer_details.customer_bank_code`. Cashfree automatically populates the bank list on the checkout page based on the IFSC codes you provide. The checkout page displays both retail and corporate banking options, depending on the modes enabled for your account.

If you pass multiple accounts from the same bank, only the first account is used for TPV.

### Bank transfers

For [bank transfers](/docs/payments/manage/payment-methods/bank-transfers) (Challans), pass the remitter account number and IFSC you expect the customer to use in `customer_bank_account_number` and `customer_bank_ifsc`. Do not rely on `customer_bank_code`; that field applies to NetBanking TPV. When the customer sends IMPS, NEFT, or RTGS to the order Virtual Bank Account, Cashfree validates the transfer against those TPV fields.

<Note>
  Fill this [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) or contact your account manager to enable multi-bank TPV for your account.
</Note>

## Supported banks

The following tables list the banks that support TPV through NetBanking and UPI. [Bank transfers](/docs/payments/manage/payment-methods/bank-transfers) (Challans) do not use the NetBanking bank code list; TPV for those payments relies on the account number and IFSC you pass at order creation and on the remitter details returned with the incoming transfer.

<Accordion title="NetBanking supported banks">
  | Sr | Bank code | Bank name |
  | - | - | - |
  | 1 | 3087 | AU Small Finance Bank |
  | 2 | 3003 | Axis Bank |
  | 3 | 3088 | Bandhan Bank - Retail Banking |
  | 4 | 3060 | Bank of Baroda - Corporate |
  | 5 | 3005 | Bank of Baroda - Retail Banking |
  | 6 | 3006 | Bank of India |
  | 7 | 3061 | Bank of India - Corporate |
  | 8 | 3009 | Canara Bank |
  | 9 | 3098 | Capital Small Finance Bank |
  | 10 | 3012 | City Union Bank |
  | 11 | 3083 | City Union Bank - Corporate |
  | 12 | 3097 | Cosmos Bank |
  | 13 | 3010 | CSB Bank Limited |
  | 14 | 3018 | DCB Bank - Retail |
  | 15 | 3016 | Deutsche Bank |
  | 16 | 3019 | Dhanlakshmi Bank |
  | 17 | 3020 | Federal Bank |
  | 18 | 3021 | HDFC Bank |
  | 19 | 3092 | HSBC Retail NetBanking |
  | 20 | 3022 | ICICI Bank |
  | 21 | 3023 | IDBI Bank |
  | 22 | 3124 | IDBI Bank - Corporate |
  | 23 | 3024 | IDFC FIRST Bank |
  | 24 | 3026 | Indian Bank |
  | 25 | 3027 | Indian Overseas Bank |
  | 26 | 3081 | Indian Overseas Bank - Corporate |
  | 27 | 3028 | IndusInd Bank |
  | 28 | 3029 | Jammu and Kashmir Bank |
  | 29 | 3102 | Jana Small Finance Bank |
  | 30 | 3030 | Karnataka Bank Ltd |
  | 31 | 3031 | Karur Vysya Bank |
  | 32 | 3032 | Kotak Mahindra Bank |
  | 33 | 3134 | Kotak Mahindra Bank - Corporate |
  | 34 | 3037 | Punjab & Sind Bank |
  | 35 | 3038 | Punjab National Bank - Retail Banking |
  | 36 | 3039 | RBL Bank |
  | 37 | 3040 | Saraswat Bank |
  | 38 | 3115 | SBM Bank India |
  | 39 | 3086 | Shivalik Small Finance Bank |
  | 40 | 3042 | South Indian Bank |
  | 41 | 3043 | Standard Chartered Bank |
  | 42 | 3044 | State Bank Of India |
  | 43 | 3066 | State Bank of India - Corporate |
  | 44 | 3052 | Tamilnad Mercantile Bank Ltd |
  | 45 | 3090 | The Surat Peoples Co-operative Bank Limited |
  | 46 | 3117 | The Sutex Co-op Bank Ltd |
  | 47 | 3054 | UCO Bank |
  | 48 | 3126 | Ujjivan Small Finance Bank |
  | 49 | 3055 | Union Bank of India |
  | 50 | 3067 | Union Bank of India - Corporate |
  | 51 | 3089 | Utkarsh Small Finance Bank |
  | 52 | 3058 | Yes Bank Ltd |
</Accordion>

<Accordion title="UPI supported apps">
  All UPI apps support bank account validation.
</Accordion>

## Troubleshooting

<Accordion title="Payer bank account details missing in payment response or webhooks">
  If payer bank account details (account number and IFSC) are missing in the payment response or webhooks, it is likely because TPV (Third Party Validation) is not enabled or not configured for your account with the banking partner. Cashfree requires this enablement to receive remitter details from the bank. Contact your account manager or use the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) to enable TPV.
</Accordion>

<Accordion title="Error: &#x22;The UPI request failed due to incorrect or incomplete information sent&#x22; with code bank_processing_failure">
  This error is often accompanied by the error code `TRANSACTION_DECLINED` and reason `debit_failed`. It indicates that the payment attempt was declined at the bank or UPI processing layer, typically due to a failure during bank-side processing rather than a Cashfree server-side issue.
</Accordion>


# UPI App Priority Reordering
Source: https://www.cashfree.com/docs/payments/features/upi-app-reordering

Reorder UPI apps on the Cashfree checkout page to prioritise preferred apps such as GPay, PhonePe, or Paytm and improve UPI conversion for Indian shoppers.

UPI App Priority Reordering allows merchants to configure the order in which UPI apps are displayed on the checkout page. By controlling the display order, merchants can prioritise apps that align with business preferences or customer behaviour and drive higher conversion rates.

## Platform behaviour

The display and ordering of UPI apps vary by platform; SDK (Android or iOS) and mobile web each apply different rules.

### SDK (Android or iOS)

For mobile SDK integrations, UPI apps are displayed based on:

* **Merchant-defined priority order**
* **App installation status** on the customer's device

Only **installed apps** are displayed. Among them, **display order follows the configured priority** (e.g. Google Pay, then PhonePe, then Paytm).

### MWeb

For MWeb integrations, UPI apps are displayed based on:

* **Top 3 display:** The top 3 apps from the configured priority list are always displayed.
* **Universal access:** These apps are shown irrespective of whether they are installed on the device.
* **iOS MWeb:** The full list of PSPs is shown according to the configured priority order in **Pay via any**.

## Configuration methods

Merchants can configure UPI app priority using one of the following methods. If multiple configurations exist, precedence rules apply.

<CardGroup>
  <Card title="Create Order API" icon="code" href="/docs/api-reference/payments/latest/orders/create-order">
    Set priority per order via `order_meta`.
  </Card>

  <Card title="Merchant Dashboard" icon="sliders" href="/docs/payments/checkout/bussiness-customisation#payment-apps-ordering">
    Configure the preferred top five UPI apps in one place.
  </Card>
</CardGroup>

### Create order API (highest precedence)

Set UPI app priority per order using the `order_meta` object in the [Create Order API](/docs/api-reference/payments/latest/orders/create-order). The UPI app order can be customised per order.

### Create order API example

The following is an example of how to send UPI app priority in the Create Order API:

```json theme={"dark"}
{
  "order_meta": {
    "upi_app_priority": ["gpay", "phonepe", "paytm", "navi", "cred", "supermoney", "amazonpay", "bhim", "mobikwik", "airtel", "popclub", "kiwi"]
  }
}
```

### Merchant Dashboard

Configure the preferred top five UPI apps through the Cashfree Merchant Dashboard for a consistent experience across all transactions. See [payment apps ordering](/docs/payments/checkout/bussiness-customisation#payment-apps-ordering) for configuration steps.

### Supported UPI apps

The following UPI apps can be included when configuring priority via the Dashboard or API:

* Google Pay
* PhonePe
* Navi
* BHIM
* Paytm
* CRED
* Amazon Pay
* MobiKwik
* Airtel Payments Bank
* Popclub
* Kiwi
* Supermoney

## Configuration precedence

If multiple configurations are present, the system applies them in the following order of priority:

<Steps>
  <Step title="Create Order API configuration">
    Highest precedence; overrides all other settings when present in the API call. See [Create Order API](/docs/api-reference/payments/latest/orders/create-order).
  </Step>

  <Step title="Merchant Dashboard configuration">
    Used when no API-level configuration is sent for the order.
  </Step>

  <Step title="Cashfree default priority">
    Used when no custom configuration is set by the merchant.
  </Step>
</Steps>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/payments/latest/orders/create-order">Create Order API</a></li>
    <li><a href="/docs/payments/manage/payment-methods/upi">UPI Payment Methods</a></li>
    <li><a href="/docs/payments/checkout/bussiness-customisation">Checkout Business Customisation</a></li>
  </ul>
</div>


# Add a Gateway
Source: https://www.cashfree.com/docs/payments/flowwise/add-gateway

Connect payment gateway partners in Cashfree FlowWise to enable smart routing, lift success rates, and manage transactions from one dashboard.

Cashfree FlowWise is a payments orchestration platform. It lets you integrate and manage multiple payment gateway partners, also known as Payment Service Providers (PSPs) or acquirers, from a single integration point. By connecting these partners, you can dynamically route transactions based on custom rules or AI models to maximise payment success rates and reduce transaction costs.

To configure and route transactions through FlowWise, you must first connect your payment gateway partners to your FlowWise account by adding their respective credentials.

## Prerequisites

Before you connect a payment gateway partner to FlowWise, verify that you have the following in place:

* A [Cashfree merchant account](/docs/help/account/account-activation) with **Collect Payments** enabled. If you do not have an account, [sign up for Cashfree](https://merchant.cashfree.com/merchants/signup?source-action=docs%20page\&action=Sign%20Up\&button-id=StartNow_Navbar).
* Active merchant accounts with each payment gateway partner you plan to add (PayU, Razorpay, Paytm, Cashfree, and others).
* API credentials, keys, and identifiers from each partner, ready to enter during setup. See the [Supported gateways](#supported-gateways) configuration guides for required fields per partner.

<Note>
  - For **Cashfree** as a gateway partner, linking your logged-in account does not require manual credentials. See the [Cashfree gateway guide](/docs/payments/flowwise/gateways/cashfree) for same-account and multi-account setup.
  - To link a different Cashfree account, use that account's Payment Gateway **App ID** and **Secret Key**. [Generate API keys](/docs/api-reference/authentication#generate-api-keys) from **Payment Gateway** > **Developers** > **API Keys** in the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
</Note>

## Adding a gateway partner

To add and connect a payment gateway partner in FlowWise, follow these steps:

1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login). On the home page, select **Payment Gateway**, then select **FlowWise** from the left navigation menu.
2. In the FlowWise sub-menu on the left navigation menu, select **Gateways** to open the configured gateways list.
3. Select **Add Gateways** in the top-right corner of the screen.
4. Select your payment gateway partner from the drop-down list. Enter a unique name and a brief description for this gateway configuration to help you identify it in your routing rules. Select **Next** to continue.
5. Select the environment for this gateway partner configuration:
   * **Production (PROD)**: Select this option for live transactions in your production environment.
   * **Test (TEST)** or **Sandbox**: Select this option to run test transactions and validate your integration.
6. Enter the required keys, secrets, or identifiers for your chosen payment gateway partner. The required fields vary depending on the partner you select. Select **Submit** or **Link Account** to save the configuration.

<Note>
  Each payment gateway has specific credential requirements and settings (such as seamless mode or webhook configurations) that you must enable on the partner dashboard before routing live traffic.
</Note>

## Supported gateways

The following table lists supported payment gateway partners, links to configuration guides, and payment modes for each partner (including Unified Payments Interface (UPI), Buy Now, Pay Later (BNPL), and Equated Monthly Instalment (EMI)).

| Payment gateway | Supported payment modes | Configuration guide |
| :- | :- | :- |
| **Cashfree** | Cards, UPI, Netbanking, Wallets, Affordability | [Cashfree Guide](/docs/payments/flowwise/gateways/cashfree) |
| **PayU** | Cards, UPI, Netbanking, Wallets, BNPL | [PayU Guide](/docs/payments/flowwise/gateways/payu) |
| **Paytm** | Cards, UPI, Netbanking, Wallets, Paytm Postpaid | [Paytm Guide](/docs/payments/flowwise/gateways/paytm) |
| **Razorpay** | Cards, UPI, Netbanking, Wallets, EMI | [Razorpay Guide](/docs/payments/flowwise/gateways/razorpay) |
| **Easebuzz** | Cards, UPI, Netbanking, Wallets | [Easebuzz Guide](/docs/payments/flowwise/gateways/easebuzz) |
| **CCAvenue** | Cards, UPI, Netbanking, Wallets | [CCAvenue Guide](/docs/payments/flowwise/gateways/ccavenue) |
| **Plural (PineLabs)** | Cards, UPI, Netbanking | [Plural Guide](/docs/payments/flowwise/gateways/plural) |
| **Billdesk** | Cards, UPI, Netbanking | [Billdesk Guide](/docs/payments/flowwise/gateways/billdesk) |
| **HDFC Bank** | UPI only | [HDFC Bank Guide](/docs/payments/flowwise/gateways/hdfc) |
| **Lyra (ICICI)** | Cards only | [Lyra Guide](/docs/payments/flowwise/gateways/lyra) |

## Next steps

After you successfully connect your payment gateway partners, you can configure your routing rules. See the [Add a New Configuration](/docs/payments/flowwise/routing/add-rules) guide to manage transaction routing.


# Flowwise FAQs
Source: https://www.cashfree.com/docs/payments/flowwise/flowwise-faq

Browse Cashfree FlowWise FAQs covering payment orchestration, smart routing, supported gateways, settlements, refunds, reconciliation, and merchant onboarding.

<AccordionGroup>
  <Accordion title="What is FlowWise?">
    FlowWise is a Payments Management System built for growing or large businesses to enable smarter, easier, and more efficient use of multiple payment gateways.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What payment gateways does FlowWise support?">
    FlowWise currently supports the following payment gateways:

    * Cashfree
    * Razorpay
    * Paytm
    * PayU
    * Techprocess / Ingenico / Worldline
    * PhonePe
    * Plural (PineLabs)
    * Easebuzz
    * PineLabs
    * Stripe
    * Atom (WIP)
    * PayG
    * Billdesk (WIP)
    * CCAvenue

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are the different payment modes does FlowWise support?">
    * Cards
    * Netbanking
    * UPI
    * Wallets
    * EMI or BNPL providers

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How does FlowWise increase the success rate?">
    FlowWise monitors success rates across payment gateways for all payment modes. Whenever a dip in success rate is seen on one payment gateway, FlowWise automatically routes the transaction through the next preferred payment gateway.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How to process refunds in FlowWise?">
    FlowWise manages back end orchestration effortlessly. You can initiate refunds from Cashfree dashboard without having to integrate with other aggregators.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What is payment gateway distribution?">
    When setting up a payment configuration, you can define the gateway distribution percentage to allocate transaction volume across multiple payment gateways or aggregators, such as PayU, Paytm, and Razorpay.

    For example, you can distribute transactions based on percentage, volume, or specific networks like Visa or Mastercard to a designated payment gateway. You can also set a priority gateway, ensuring that most transactions are routed through it.

    If there is any success rate (SR) fluctuation or downtime in the primary gateway, transactions are automatically redirected to the next preferred gateway based on the assigned priority.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I delete a rule in FlowWise?">
    No, you cannot delete a rule. You can only enable/disable a rule.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are the options based on which we can create rules in FlowWise?">
    You can create rules based on:

    * Order currency
    * Amount
    * Payment mode
    * Card scheme
    * Card country
    * Card bin
    * Issuing bank

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How many rules can I create in FlowWise?">
    There is no limit on the number of rules you can create in FlowWise.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How to enable seamless option on FlowWise?">
    To use FlowWise, the Payment Gateway account you are choosing should have seamless option enabled. To activate seamless option write to your corresponding payment gateway relationship manager asking to enable seamless mode for your account. Mention that you are using Cashfree as the technology company to handle sensitive card data.

    <iframe title="FAQs feedback component" />
  </Accordion>
</AccordionGroup>


# Billdesk
Source: https://www.cashfree.com/docs/payments/flowwise/gateways/billdesk

Connect a Billdesk account to Cashfree FlowWise to route cards, UPI, netbanking, and wallet payments alongside other partners in one orchestration.

* [x] Cards (credit, debit and prepaid)
* [x] UPI
* [x] Netbanking (all major banks)
* [x] Wallets

1. Once you decide that you want to add BillDesk, we will initiate a new merchant onboarding request with BillDesk that you will use flowWise.
2. From your end, you must enable the APIs that we use for BillDesk integration. Find the LIVE API details below:

| API name | Endpoint | Payment modes |
| :- | :- | :- |
| Create Transaction (One time/SI) | [https://api.billdesk.com/payments/ve1\_2/transactions/create](https://api.billdesk.com/payments/ve1_2/transactions/create) | All |
| Retrieve Transaction | [https://api.billdesk.com/payments/ve1\_2/transactions/get](https://api.billdesk.com/payments/ve1_2/transactions/get) | - |

* The webhook URL for transactions response - `https://push-test.cashfree.com/push/v1/pg/pa_billdeskpg`

3. Write to your BillDesk relationship manager that you use flowWise as the technology company to handle sensitive card data and with the following requests:

   * Enable seamless/S2S mode for your account.
   * Enable cards, UPI, wallet, and net banking methods.
   * Configure the common BillDesk certificate used by flowWise merchants.
   * Configure the following webhooks: Production URL `https://push-test.cashfree.com/push/v1/pg/pa_billdeskpg`

4. Enable the following if you intend to use UPI as a payment method: UPI Intent and UPI Collect

5. Whitelist the following IPs to make the API calls (Initiate Transaction, Authorization API call, Verify Transaction, Refund Initiation, Verify Refund). Share the below IPs with BillDesk for whitelisting.\
   3.109.102.144\
   13.202.107.37\
   18.60.134.245\
   18.60.183.142\
   3.29.193.209\
   35.154.157.84\
   51.112.82.196\
   52.66.101.190


# Cashfree
Source: https://www.cashfree.com/docs/payments/flowwise/gateways/cashfree

Connect your Cashfree Payment Gateway account inside FlowWise to route cards, UPI, netbanking, wallets, and affordability instruments through orchestration.

* [x] Cards (credit, debit and prepaid)
* [x] UPI
* [x] Netbanking (all banks)
* [x] Wallets
* [x] Affordability

Flowwise allows you to link multiple Cashfree accounts, so you can accept payments via Flowwise for the account you are on, and also add any other Cashfree accounts that you may have with us.

The steps to add both types of accounts are listed below.

## How to add Cashfree gateway on Flowwise

1. Login to your Cashfree Dashboard

2. On the home page, click ‘Payment Gateway’, then select Flowwise from left navbar. Select ‘Gateways’

3. On the top right, click **Add Gateways**. Select Cashfree from the dropdown, and add a unique name and description for the gateway, then click **Next**.

4. You can either link the same account or add credentials from another account.

<Tabs>
  <Tab title="Same account">
    1) Select prod environment
    2) Select '**Add Credentials for this account**' and hit submit.

    <img />
  </Tab>

  <Tab title="Link another account">
    5. If you want to add another Cashfree account to Flowwise to use through this account,

       1. select '**Add credentials for another Cashfree account (MID)**' and hit submit.
       2. Add your **app-id** and **secretKey** for the other account that you are adding on Flowwise.

       <img />
  </Tab>
</Tabs>

You have now successfully linked a Cashfree account to Flowwise.


# CCAvenue
Source: https://www.cashfree.com/docs/payments/flowwise/gateways/ccavenue

Connect a CCAvenue account to Cashfree FlowWise to route credit and debit cards, UPI, netbanking, and wallet transactions through smart orchestration rules.

* [x] Cards (Credit, Debit and Prepaid)
* [x] UPI
* [x] Netbanking (all major banks)
* [x] Wallets

## Required steps

To be able to use CC Avenue on Flowwise, you will need to get the following items implemented for your CC Avenue account from your CC Avenue Account Manager:

1. Ensure that CCAvenue has enabled S2S (server-to-server) access on your merchant account. Drop an email to your CCAvenue account manager/SPOC for this (read email below).

2. Get <Tooltip>auto retry disabled</Tooltip> at CCAvenue for a seamless transaction journey for the user.

3. You will need to get Cashfree IPs and header whitelisted. This is required so that transaction requests on CCAvenue can be made through Cashfree’s Router. Please get the following IPs whitelisted from CCAvenue:
   1. Production: 52.66.101.190
   2. UAT: `52.66.25.127` and `15.206.45.168`

4. To get the IPs and header whitelisted, you need to write a mail to CCAvenue ([service@ccavenue.com](mailto:service@ccavenue.com)) with the following details:
   1. CCAvenue Merchant ID (received in Step 1)
   2. Username
   3. Referrer Header: Please get the following headers whitelisted from CCAvenue
      1. `payments-test.cashfree.com`
      2. `payments.cashfree.com`
      3. `api.cashfree.com`

Once the IPs and Header are whitelisted, you can start using CCAvenue as a Gateway for transactions routing on our Cashfree Router.

<Warning>
  CC Avenue attempts a retry on the CC Avenue checkout page by default. Disable this when using CC Avenue via Flowwise, as you must route all payments through Flowwise (Cashfree) and its checkout. If retry is enabled, Cashfree cannot track the payment status, which may lead to incorrect payment information and mismatches.

  Since, disabling retry when not live on Flowwise might affect your standard integration with CC Avenue, you can request CC Avenue AM to disable auto-retry once you have tested your CC Avenue integration with Flowwise and want to start routing.
</Warning>

## Email to CCAvenue

Send the following email to CCAvenue to enable the correct settings.

<Accordion title="Email" icon="email">
  Dear Account Manager,\
  We are using Flowwise as a technology service provider to manage our integration with CC Avenue for account `Merchant/Account ID`.

  In order to use this TSP, we require certain configurations to be enabled as mentioned below:

  1. Please share MID, Secret Key and Access Code for my account.
  2. Enable S2S/seamless integration for the above MID.
  3. Disablement of the ‘auto retry’ option for all methods.
  4. Configure below end points for transaction callbacks for production and stage:\
     For production - `https://push.cashfree.com/push/v1/pg/pa_ccavenuepg`
     For sandbox/gamma - `https://push-test.cashfree.com/push/v1/pg/pa_ccavenuepg`
  5. Whitelist the followings IPs:\
     Prod: 52.66.101.190\
     UAT: 52.66.25.127\
     VPN IP: 15.206.45.168
  6. Whitelist the follower referer headers at your head:\
     payments-test.cashfree.com\
     payments.cashfree.com\
     api.cashfree.com

  Regards,
</Accordion>

## How to add CCAvenue gateway on Flowwise

1. Log in to the **[Merchant Dashboard](https://merchant.cashfree.com/auth/login)**

2. On the home page, click ‘Payment Gateway’, then select Flowwise from left navbar.\
   Select ‘Gateways’

3. On the top right, click **Add Gateways**.

4. Select CC Avenue from dropdown, and add a unique name and description for the gateway.\
   Then hit ‘next’

5. Select 'PROD' environment and add your **MID**, **Secret Key** and **Access Code** and hit submit.

You have successfully added CC Avenue to Flowwise.


# Easebuzz
Source: https://www.cashfree.com/docs/payments/flowwise/gateways/easebuzz

Link your Easebuzz account with Cashfree FlowWise to route cards, UPI, netbanking, and wallet transactions across longtail banks and acquirer networks.

* [x] Cards (CC, DC, PP)
* [x] UPI
* [x] Netbanking (all major and longtail banks)
* [x] Wallets

## Required steps

To be able to use Easebuzz on Flowwise, you will need to get the following settings activated for your Easebuzz account from your account manager:

1. Enable seamless mode for your account. Mention that you use Flowwise (Cashfree) as the technology service provider (TSP) to handle sensitive card data.
2. Get webhooks configured correctly with correct website name for the webhook (read below email for webhook details).

To configure some of these settings you need to send an email with the details to Easebuzz. You can find the same email below.

## Email to Easebuzz

Send the following email to Easebuzz to <Tooltip>enable the configurations for your account.</Tooltip>

<Accordion title="Email template" icon="email">
  Dear `Account Manager`,\
  We are using Flowwise as a technology service provider to manage our integration with Easebuzz for account `Merchant/Account ID`.

  In order to use this TSP, we require the following configuration changes:

  1. Kindly enable S2S mode (seamless mode) for our account.
  2. Provide the production Key and Salt for my account.
  3. Please enable the relevant payment methods for my account (cards, upi, nb etc.)
  4. Configuration of the below end points for transaction callbacks for production: Production URL: `https://push.cashfree.com/push/v1/pg/pa_easebuzzpg`

  Please share a list of the enabled banks for netbanking and networks for cards payments methods so that this can be configured at our end.

  Regards,
</Accordion>

## How to add Easebuzz gateway on Flowwise

1. Log in to the **[Merchant Dashboard](https://merchant.cashfree.com/auth/login)**
2. On the home page, click ‘Payment Gateway’, then select Flowwise from left navbar. Select ‘Gateways’
3. On the top right, click **Add Gateways**
4. Select Easebuzz from dropdown, and add a unique name and description for the gateway. Then hit ‘next’
5. Select PROD environment, if you are testing production credentials, and then input **Key** and **Salt**.

You are now live on Easebuzz via Flowwise.


# HDFC
Source: https://www.cashfree.com/docs/payments/flowwise/gateways/hdfc

Connect HDFC Bank as a payment partner inside Cashfree FlowWise to enable UPI routing alongside other acquirers from a single orchestration integration.

* [ ] Cards (credit, debit and prepaid)
* [x] UPI
* [ ] Netbanking (all major banks)
* [ ] Wallets

## How to add HDFC UPI gateway on Flowwise

1. Log in to the **[Merchant Dashboard](https://merchant.cashfree.com/auth/login)**.
2. On the home page, click ‘Payment Gateway’, then select flowWise from left navbar. Select ‘Gateways’
3. On the top right, click **Add Gateways**
4. Select HDFC UPI from dropdown, and add a unique name and description for the gateway. Then hit ‘next’


# Lyra
Source: https://www.cashfree.com/docs/payments/flowwise/gateways/lyra

Add Lyra as a payment partner in Cashfree FlowWise to route credit, debit, and prepaid card transactions alongside other gateway partners from one dashboard.

* [x] Cards (credit, debit and prepaid)
* [ ] UPI
* [ ] Netbanking (all major banks)
* [ ] Wallets

## How to add Lyra gateway on Flowwise

1. Log in to the **[Merchant Dashboard](https://merchant.cashfree.com/auth/login)**.
2. On the home page, click ‘Payment Gateway’, then select flowWise from left navbar. Select ‘Gateways’
3. On the top right, click **Add Gateways**
4. Select LyraICICI from dropdown, and add a unique name and description for the gateway. Then hit ‘next’


# Paytm
Source: https://www.cashfree.com/docs/payments/flowwise/gateways/paytm

Connect a Paytm Payment Gateway account to Cashfree FlowWise to orchestrate transactions across Paytm and other acquirers using shared routing rules.

Payment Methods supported:

* [x] Cards (Credit, Debit and Prepaid)
* [x] UPI
* [x] Netbanking (all banks)
* [x] Wallets

## Required steps

To be able to use Paytm on Flowwise, you will need to get the following items implemented for your Paytm account from your Paytm Account Manager:

1. Enable seamless mode for your account. Mention that you use Flowwise (Cashfree) as the technology service provider (TSP) to handle sensitive card data.
2. Get webhooks configured correctly with proper website name for the webhooks.

To enable flags needed from Paytm so that you can use Flowwise seamlessly, you can send the following mail to your account manager or support team at Paytm.

## Email to Paytm

The following email needs to be sent to Paytm to <Tooltip>enable the configurations for your account.</Tooltip>

<Accordion title="Email template" icon="email">
  Dear `_Account Manager_`,\
  We are using Flowwise as a technology service provider to manage our integration with Paytm for account `Merchant/Account ID`.

  In order to use this TSP, we require the following configuration changes:

  1. Kindly enable S2S mode/ custom flow(native JSON Request) for our account.
  2. Configuration of the below end points for transaction callbacks for production and stage:\
     Website Name: **Cashfree**\
     Production URL: `https://push.cashfree.com/push/v1/pg/pa_paytmpg`
     Sandbox/Gamma URL: `https://push-test.cashfree.com/push/v1/pg/pa_paytmpg`
  3. Enable webhooks for failed and bounced transactions.
  4. Enable API-based refunds on our account at Paytm.
  5. Enable the account for card and netbanking transactions.\*\*
  6. Enable UPI Intent and UPI Collect flows for this account.\*\*

  Also, please share **MID** and **Secret Key** (Live environment for my account)

  Please share a list of the enabled banks for netbanking and networks for cards payments methods so that this can be configured at Flowwise's end.

  Regards
</Accordion>

## How to add Paytm gateway on Flowwise

1. Log in to the **[Merchant Dashboard](https://merchant.cashfree.com/auth/login)**
2. On the home page, click ‘Payment Gateway’, then select Flowwise from left navbar.\
   Select ‘Gateways’
3. On the top right, click on ‘Add Gateways’
4. Select Paytm from dropdown, and add a unique name and description for the gateway.\
   Then hit ‘next’
5. Select ‘PROD’ environment if you are configuring your production **MID** and **Secret Key**.\
   If your account at Paytm requires third-party validation to accept UPI and Netbanking transactions, enter 1 in ‘TPV’, else enter 0, or leave it blank.\
   Click ‘Submit’.
6. You have now added Paytm on to Flowwise.

<img />

## How to find Paytm key and salt

There are two ways of obtaining your key and salt:

1. Your Paytm Account manager will provide you the details on the mail.

2. You can find your key and salt on your dashboard.
   1. Login to your [Paytm dashboard](https://dashboard.paytm.com)
   2. Under ‘Developer Settings', click on ‘API Keys’.
   3. Click on ‘Production API Details’. You will find Merchant ID and Secret Key.


# PayU
Source: https://www.cashfree.com/docs/payments/flowwise/gateways/payu

Connect a PayU account to Cashfree FlowWise to orchestrate cards, UPI, netbanking, and wallet payments through unified rule-based and AI-driven routing.

Payment Methods supported:

* [x] Cards (Credit, Debit and Prepaid)
* [x] UPI
* [x] Netbanking (all banks)
* [x] Wallets
* [x] BNPL

## Required steps:

1. Enable seamless mode for your account. Mention that you use Flowwise (Cashfree) as the technology company to handle sensitive card data.
2. Disable <Tooltip>Auto-retry</Tooltip> on failed transactions.
3. Configure Flowwise webhooks to receive all payment related event information
4. Enable the payment modes you want to use on Flowwise
5. Provide to PayU (if required), necessary documents for card data handling, duly provided by Cashfree. Please let your Cashfree AM know of this requirement.

## Configuration

<Warning>
  Reason for disabling `Auto-retry`: If retry is enabled, Cashfree will not know about the status of the payment, and it may lead to incorrect payment information and mismatches.
</Warning>

Since, disabling retry when not live on Flowwise might affect your standard integration with PayU, you can request PayU AM to disable auto-retry once you have tested your PayU integration with Flowwise and want to start routing.

Please send the below mail to your SPOC at PayU to enable the required flags for Flowwise.

## Email to PayU

The following email needs to be sent to PayU to <Tooltip>enable the configurations for your account.</Tooltip>

<Accordion title="Email template" icon="email">
  Dear `Account Manager`,\
  We are using Flowwise as a technology service provider to manage our integration with PayU for account `Merchant/Account ID`.

  In order to use this TSP, we require certain configurations to be enabled as mentioned below:

  1. Enablement of S2S/seamless integration for the above MID.
  2. Disablement of the ‘auto retry’ option for all methods.
  3. Configuration of the below end points for transaction callbacks for production and stage:\
     For production -  `https://push.cashfree.com/push/v1/pg/pa_payupg`
     For sandbox/gamma - `https://push-test.cashfree.com/push/v1/pg/pa_payupg`
  4. Enable webhooks for failed and bounced transactions.
  5. Enable ‘ws\_callback’ to get status updates for delayed success transactions.
  6. Enablement of UPI (both Intent and Collect), Cards, Wallet and Netbanking. \*\*\*
  7. Enable Method UPI on S2S with txn\_s2s\_flow = 4 and also enable UPI Intent. \*\*\*
  8. Enable Method txn\_s2s\_flow = 1 at PayU’s end. (This is an internal flag at PayU’s end for UPI intent transactions)
  9. Please enable UPI intent for my account if it is not enabled already.

  Additionally, please share the **KEY** and **SALT** for the account so that we can complete the integration.

  Regards,
</Accordion>

## Steps to add PayU gateway on Flowwise

1. Log in to the **[Merchant Dashboard](https://merchant.cashfree.com/auth/login)**
2. On the home page, click ‘Payment Gateway’, then select Flowwise from left navbar.
3. Select ‘Gateways’
4. On the top right, click **Add Gateways**
   Select PayU from dropdown, and add a unique name and description for the gateway.\
   Then hit ‘next’
5. Select ‘PROD’ environment if you are configuring your production Key and Salt.\
   Click ‘Submit’.
6. You have now added PayU on to Flowwise.

## How to find your key and salt

There are two ways of obtaining your key and salt

<Tabs>
  <Tab title="Do it yourself">
    1. Login to your PayU dashboard
    2. Select Payment Gateway under Collect Payments from the menu on the left-pane.
    3. Scroll down to Key Salt Details section.
    4. You will be able to find the credentials

    <img />
  </Tab>

  <Tab title="Ask your account manager">
    1. Your PayU Account manager will provide you the details on the mail.
  </Tab>
</Tabs>


# Plural
Source: https://www.cashfree.com/docs/payments/flowwise/gateways/plural

Add Pine Labs Plural to Cashfree FlowWise to route cards, UPI, netbanking, and wallet payments across acquirers from one orchestration integration.

* [x] Cards (credit, debit and prepaid)
* [x] UPI
* [x] Netbanking (all major banks)
* [x] Wallets

## Required steps

To be able to use Plural on Flowwise, you will need to get the following configurations enabled on your account.

1. Enable all the required payment methods and refunds. Mention that you are using Cashfree as the technology company to handle sensitive card data.
2. Enable the Aggregator model. Otherwise, RRN and other attributes are not returned in the callback response of card payment initialisation. Cashfree supports only the aggregator model for Pine Labs Plural card integration.
3. Enable the `INQUIRY API` for your Pine Labs Plural account to check the payment status.
4. Allow dynamic URL in return URL. This is required since Plural only supports static URL (`merchant_return_url`) and Flowwise has a dynamic return URL.

## Email to Plural

<Accordion title="Email" icon="email">
  Dear `Account Manager`,

  We are using Flowwise as a technology service provider to manage our integration with Plural (Pine Labs) for account `Merchant/Account ID`.

  In order to use this TSP, we require the following configuration changes:

  1. Enable s2s/seamless mode for my MID.
  2. Allow Dynamic URL in redirection/return URL (Configure the production database to support dynamic URL).
  3. Configure the below webhook to receive payment-related events:
     1. Production URL: `https://push.cashfree.com/push/v1/pg/pa_pluralpg`
  4. Enable the INQUIRY API to check the payment status.
  5. Please enable relevant payment modes like UPI, cards, netbanking and walletss for my account.

  Please share a list of the enabled banks for netbanking and networks for cards payments methods so that this can be configured at our end.

  Regards,
</Accordion>

## How to add Plural to Flowwise

1. Log in to the **[Merchant Dashboard](https://merchant.cashfree.com/auth/login)**.
2. On the home page, click ‘Payment Gateway’, then select Flowwise from left navbar. Select ‘Gateways’
3. On the top right, click **Add Gateways**
4. Select Razorpay from dropdown, and add a unique name and description for the gateway. Then hit ‘next’
5. Select ‘PROD’ environment if you are configuring your production MID, Access Code and Secret Key. Enter your salt and key. Click ‘Submit’.

You have now successfully linked Plural with Flowwise.


# Razorpay
Source: https://www.cashfree.com/docs/payments/flowwise/gateways/razorpay

Link your Razorpay account inside Cashfree FlowWise to orchestrate cards, UPI, netbanking, and wallet payments alongside other gateway partners.

* [x] Cards (Credit, Debit and Prepaid)
* [x] UPI
* [x] Netbanking (all banks)
* [x] Wallets

We offer two guides: one for non-S2S merchants and another for S2S merchants. If you don’t have a PCI certificate and S2S enablement isn’t available with Razorpay, you can still easily accept payments on FlowWise with just a few simple steps.

<Tabs>
  <Tab title="S2S not available">
    You can setup this integration without having S2S enabled.

    1. Log in to the **[Merchant Dashboard](https://merchant.cashfree.com/auth/login)**.
    2. On the home page, click ‘Payment Gateway’, then select Flowwise from left navbar. Select ‘Gateways’
    3. On the top right, click **Add Gateways**
    4. Select Razorpay from dropdown, and add a unique name and description for the gateway. Then click **Next**
    5. Select ‘PROD’ environment if you are configuring your production **KeyID** and **Secret Key**. Click ‘Submit’.

    You have now added Razorpay on to Flowwise.

    ## Configure webhooks

    To configure Flowwise webhooks on Razorpay dashboard to receive updates about all payment events

    1. Go to razorpay dashboard
    2. Under ‘Accounts and Settings’, click **Webhooks**.
    3. Add `https://push.cashfree.com/push/v1/pg/pa_razorpaypg`, and under Secret, add your Razorpay secret key (steps to obtain secret key written below).
    4. Under Active Events, select payment.authorized, payment.failed, payment.captured and order.paid
  </Tab>
</Tabs>

## How to find your key and salt

There are three ways of obtaining your key and salt

<Tabs>
  <Tab title="Ask your account manager">
    1. Your Razorpay Account manager will provide you the details on the mail.
  </Tab>

  <Tab title="Search your existing integration">
    Look into your current integration with Razorpay, and find the **keyId** and **secret** from the integration code at your backend. You would also have them saved somewhere on your system.
  </Tab>

  <Tab title="Generate a new pair">
    You can also generate a new KeyID and Secrey Key from [Razorpay’s Dashboard](https://dashboard.razorpay.com/).

    <Warning>
      Generating new credentials will render your old credentials invalid, so it might affect your integration with Razorpay’s standard checkout APIs. Only generate new keys just before going live on flowWise.
    </Warning>

    1. Login into your Razorpay Dashboard (Razorpay Dashboard )
    2. Under Accounts and Settings, you will find an option to ‘Generate new key’
  </Tab>
</Tabs>


# Overview
Source: https://www.cashfree.com/docs/payments/flowwise/overview

Cashfree FlowWise is a payments orchestration platform for managing multiple gateway partners, smart routing, refunds, and reconciliation in one place.

FlowWise is a payments orchestration platform that gives you one integration to work with multiple payment partners. The routing is controlled by rules such as percentage-level splits across partners using over 40 parameters or by AI/ML logic that improves success rates. Refunds, settlements, and reconciliation are managed from a single dashboard, and low-code or no-code flows let merchants go live quickly without building separate integrations for each partner.

FlowWise offers merchants the following key benefits:

<CardGroup>
  <Card title="Expertise at your fingertips" icon="lightbulb">
    Leverage our expertise in payments across 3 Lakh+ businesses over 8 years, while you focus on your business.
  </Card>

  <Card title="20% Growth in Revenue" icon="chart-line">
    Reduce cart abandonment by 10% and avoid 20% of all failed payments to drive business growth.
  </Card>

  <Card title="Cloud Native Orchestration" icon="server">
    Opt for FlowWise Native, the first of its kind in India, to get ultimate flexibility and data security.
  </Card>

  <Card title="Completely Customisable" icon="sliders">
    Use multiple PGs, banks, and partners to offer all payment modes to your customers without additional integrations.
  </Card>
</CardGroup>

## Supported integrations

FlowWise offers extensive integration options across payment providers, bank gateways, and payment modes to give you maximum flexibility.

### Payment providers

FlowWise integrates with leading payment providers across India and internationally.

The following payment providers are supported:

* Paytm
* PayU
* Cashfree
* Razorpay
* Techprocess / Ingenico / Worldline
* PhonePe
* Plural (PineLabs)
* Easebuzz
* CCAvenue
* Stripe
* PayG

<Note>
  Atom and Billdesk integrations are currently in progress.
</Note>

### Bank gateways

FlowWise offers direct integrations with bank gateways.

The following bank gateways are supported:

* HDFC (UPI)
* Lyra ICICI (Cards)

### Payment modes

FlowWise supports a comprehensive range of payment methods to accommodate various customer preferences.

The following payment modes are available:

* **Cards:** Credit, debit, corporate, and prepaid cards
* **UPI (Unified Payments Interface):** Intent, collect, QR code, in-app, and RuPay credit card
* **Net banking:** Support for 70+ leading banks in India
* **Digital wallets:** Various wallet providers
* **EMI and BNPL (Buy Now, Pay Later):** Credit card EMI, debit card EMI, cardless EMI, and pay later options

## Get started

Explore the following resources to get started with FlowWise and discover how it can optimise your payment infrastructure.

<CardGroup>
  <Card title="Learn more about FlowWise" icon="link" href="https://flowwise.com/">
    Visit the FlowWise website for detailed information and features.
  </Card>

  <Card title="Contact Sales" icon="phone" href="https://www.cashfree.com/contact-sales/?source-action=PG%20Page&action=Contact%20Sales&button-id=ContactSales_FlowWise">
    Get in touch with our sales team to discuss your payment needs.
  </Card>
</CardGroup>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/payments/overview">Payments Overview</a></li>
    <li><a href="/docs/payments/manage/payment-methods/overview">Payment Methods</a></li>
    <li><a href="/docs/payments/manage/downtimes">Manage Payments</a></li>
    <li><a href="/docs/payments/general-faqs">Payments FAQs</a></li>
  </ul>
</div>


# Add a New Configuration
Source: https://www.cashfree.com/docs/payments/flowwise/routing/add-rules

Configure Cashfree FlowWise routing rules visually to split traffic across payment partners using percentages, conditions, and over 40 routing parameters.

Flowwise rules visually can be understood with the below diagram:

<img />

## Adding a new configuration

A Configuration object reprepsents the set of routing rules that will be invoked by Cashfree for every payment. Our first step is to just create a new configuration. To get started:

1. Log in to your Cashfree Dashboard, navigate to Payment Gateway, and select FlowWise.
2. In the Configure screen, click Add Configuration and enter a unique Name and Description to identify the rule.

You will now land on the screen to add `Rules` to this `Configuration` object. A `rule` objects represents a condition like:

<Info>IF Payment Mode is `CREDIT CARD` AND IF Bank is `HDFC Bank`</Info>

There are two type of rules:

1. Simple Rule: This must always be set as this is the default rule for a `Configuration` object.
2. Advanced Rule: This is optional and should be used for advanced routing configuration.

## Add a simple rule

To configure a simple rule, just select a payment gateway from your configured gateways.

## Adding an advanced rule

Advanced rule can be used when you want to route payments based on various parameters such as payment method, bank, card networks, and more. For example: you may want to send all UPI transactions through Cashfree and PayU, and want to ensure routing such that Flowwise ensures the best gateway at any point in time.

Let's assume we want to add create the following rule: <i>Create a configuration which routes netbanking transactions for major banks (HDFC, ICICI, YES, SBI, AXIS, KOTAK) to PayU and Razorpay, and all other banks to PayTM. Route all other types of transactions to Cashfree (such as UPI, Cards etc)</i>

<Steps>
  <Step title="Step 1">
    Select `Rule 1` and set `When Payment Method IS Net Banking`
  </Step>

  <Step title="Add conditions to this rule">
    Add a conditional (AND) within Rule 1, since we need netbanking as well as bank names `AND When Issuing Bank IN HDFC, ICICI, YES, SBI, AXIS, KOTAK`
  </Step>

  <Step title="Add conditions to this rule">
    Add a conditional (AND) within Rule 1, since we need netbanking as well as bank names `AND When Issuing Bank IN HDFC, ICICI, YES, SBI, AXIS, KOTAK`
  </Step>

  <Step title="Decide Routing">
    Now, that we have a rule we need to add gateways to this rule. Since we wanted to add PayU and Razorpay to this rule, we also need to decide how should routing take place between these two gateways. Recall our [dynamic routing](/docs/payments/flowwise/routing/dynamic-routing) options. Let's assume that we decide on ‘Smart Routing’ because we want to maximise the success rate.
    We select ‘Smart Routing’ since we want maximum success rate.
  </Step>

  <Step title="Add gateways">
    From dropdown in ‘Select Gateways’, we select PayU and Razorpay. We need to ensure that both gateways are active. This completes Rule #1.
  </Step>

  <Step title="Add Rule 2">
    Now we are left with routing rule for other banks. As in step 2 above, we now add the following rule `When Payment Method IS Net Banking AND When Issuing Bank NOT IN HDFC, ICICI, YES, SBI, AXIS, KOTAK`. Note that we are using the `NOT IN` operator since we want to exclude these banks.
  </Step>

  <Step title="Add gateway for Rule 2">
    From dropdown in ‘Select Gateways’, we select PayTm
  </Step>
</Steps>

We now have the Advanced Logic ready to be used in Flowwise.


# Dynamic Routing
Source: https://www.cashfree.com/docs/payments/flowwise/routing/dynamic-routing

Use Cashfree FlowWise dynamic routing to direct each transaction to the best-performing acquirer in real time using machine learning on live success-rate data.

Dynamic Routing helps intelligently direct payments to the most efficient acquiring bank or payment gateway in real-time. Leveraging machine learning rules, we identify the best-performing gateway based on multiple live parameters to ensuring we get the highest possible success rates. This helps improve payment success rates and reduces transaction failures, and minimises costs.

Unlike traditional single-gateway reliance, you can now apply intelligent rules to distribute transactions across multiple gateways based on individual performance.

## Dynamic routing options on Flowwise

### Smart routing

With Smart Routing, Flowwise automatically directs payments to the best gateway based on success rates over recent timeframes (e.g., last 15 or 30 minutes). Simply define your selected gateways in a rule set, and Flowwise handles the rest.

<i>Example: To optimise UPI transactions between PayU and Cashfree, define Smart Routing to dynamically choose the highest-performing gateway.</i>

<img />

### Smart routing with weights

This option allows you to set weighted preferences for each gateway in addition to success rates, optimising the balance of traffic based on your needs.

<i>Example: For Credit Card transactions, if you want 60% routed through Cashfree and 40% through PayU while prioritising success, select this routing option.</i>

<img />

### Threshold routing

Ideal for scenarios with a preferred primary gateway, this routing applies a minimum success rate threshold. If success drops below the threshold, Flowwise switches to Smart Routing for optimal fallback.

<i>Example: Example: If Cashfree is preferred with a threshold of 70%, transactions will route to PayU as backup if Cashfree’s success rate dips below this level.</i>

<img />

### Volume-based routing

Distributes transaction volume across gateways in defined percentages, regardless of performance metrics. This method offers predictable, controlled traffic distribution.

<i>Example: Example: To equally distribute NetBanking transactions between Cashfree, PayU, and PayTm, set weights at 33.33% each.</i>

<img />


# Payments: General FAQs
Source: https://www.cashfree.com/docs/payments/general-faqs

Browse general FAQs about Cashfree covering account setup, integration basics, supported payment methods, settlements, refunds, and merchant support.

<AccordionGroup>
  <Accordion title="Is Cashfree PCI DSS compliant?">
    The **Payment Card Industry Data Security Standard (PCI DSS)** is an information security standard for organisations that handle branded credit cards from major card schemes.

    The PCI Standard is mandated by the card brands and administered by the **Payment Card Industry Security Standards Council**. The standard was created to increase controls around cardholder data to reduce credit card fraud.

    **Cashfree** is PCI DSS compliant. Access the [PCI DSS certificate](https://cashfreelogo.cashfree.com/website/pdf/Cashfree-PCI-DSS-COC.pdf).

    While PCI DSS compliance is a pre-requisite for payment acceptance, we have gone a step further and incorporated a very robust **Risk Management System** developed with help from **PayPal**.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are the different payment methods supported by Cashfree's Payment Gateway?">
    **Cashfree Payment Gateway** supports multiple payment methods, giving greater flexibility to your customers to complete payments using the payment method of their choice.

    **Supported Payment Methods**

    * Credit/Debit Card/Prepaid
    * UPI
    * Netbanking
    * Wallets
    * PayPal
    * EMI
    * Pay Later

    **Customise Payment Methods**
    With Cashfree Payment Gateway, you can choose to display only the payment methods relevant to your business.\
    Fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) to add or remove any payment methods.\
    See [supported currencies](/docs/payments/global-collections/collection-accounts#supported-currencies) to see all the currencies supported.

    **Payment Response**
    You will receive responses for every payment made by your customers. These details can be viewed in the **dashboard** against each transaction.\
    See [payment methods](/docs/payments/manage/payment-methods/overview#supported-payment-methods) to view all possible payment response statuses.

    **Payment Modes**
    Below is a detailed list of all supported payment modes and their respective codes:

    | Code | Description |
    | - | - |
    | DEBIT\_CARD | Debit Card |
    | CREDIT\_CARD | Credit Card |
    | PREPAID\_CARD | Prepaid Card |
    | CREDIT\_CARD\_EMI | Credit Card EMI |
    | NET\_BANKING | Internet Banking |
    | UPI | UPI |
    | PayPal | PayPal |
    | PhonePe | PhonePe |
    | Paytm | Paytm |
    | AmazonPay | Amazon Pay |
    | AIRTEL\_MONEY | Airtel Money Wallet |
    | FreeCharge | Freecharge Wallet |
    | MobiKwik | MobiKwik Wallet |
    | OLA | Ola Wallet |
    | JioMoney | JioMoney Wallet |
    | ZestMoney | ZestMoney |
    | Instacred | Instacred |
    | LazyPay | LazyPay |
    | OlaPostpaid | Ola Postpaid |

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Where can I find test bank account numbers for the sandbox environment?">
    Find and test bank account numbers and other sandbox test data for cards, Netbanking, UPI, wallets, EMI, Pay Later, and Cardless EMI on the [Data to Test Integration](/docs/api-reference/payments/data-to-test-integration) page.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are the different payment response statuses for the payment?">
    There are various states that the payment goes through. The various states help you understand the status of the payment made by your customers.

    * **SUCCESS**
    * **FAILED**
    * **PENDING**
    * **CANCELLED**
    * **FLAGGED**
    * **INCOMPLETE**
    * **VOID**
    * **USER\_DROPPED**

    ### Payment Response Status

    Cashfree send responses against the payments made by your customers. The response against these payments made could contain one of the following statuses.

    | Case | Event name | Event status |
    | :- | :- | :- |
    | Successful Payment | PAYMENT\_RESPONSE | SUCCESS |
    | Payment Failed | PAYMENT\_RESPONSE | FAILED |
    | Pending Payment | PAYMENT\_RESPONSE | PENDING |
    | Payment cancelled by the user | PAYMENT\_RESPONSE | CANCELLED |
    | Payment successful but kept on hold by risk system | PAYMENT\_RESPONSE | FLAGGED |
    | Transactions are marked as Incomplete, which later changes to other states based on the responses from other entities. | PAYMENT\_RESPONSE | INCOMPLETE |
    | When we do not want to capture the transaction amount (pre-authorized transactions). | PAYMENT\_RESPONSE | VOID |
    | When customers drop out of the payment flow without completing the transaction. | PAYMENT\_RESPONSE | USER\_DROPPED |
    | Invalid inputs | VALIDATION\_ERROR | |

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What is the checkout experience offered by Cashfree's PG like?">
    A seamless checkout is key to customer trust. Redirects and pop-ups? They create confusion and hurt conversions. Big brands offer smooth payments, but not everyone has their resources.\
    That’s where Cashfree comes in! We provide easy integrations for a fast, hassle-free checkout—built for businesses of all sizes. Cashfree offers a seamless checkout experience with:

    No Redirects – Customer experiences checkout flow on your website without navigating to any third-party page

    Custom UI – You own the look and feel of the checkout flow or you can also use our ready-made beautiful UI components

    One-Click Checkout – Enable fast, hassle-free payments with a single click.

    [Sign-Up](https://merchant.cashfree.com/auth/login) to see our payment gateway in action!

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What is a Chargeback?">
    Businesses accepting payments via cards may face a situation where a **chargeback request** is raised for a refund to the customer.
    **What is a chargeback?**
    A chargeback is a request for the return of funds to a consumer, initiated by the consumer's card-issuing bank.
    It serves as a form of consumer protection against fraudulent activities committed by both merchants and individuals.

    <Note>
      It is best to avoid chargebacks as banks and card networks can label your business as high-risk. A high number of chargebacks may lead to banks holding remittances or banning your business's online payment services.
    </Note>

    **Key Parties Involved in a Chargeback**

    * **Cardholder:** The owner of the card involved in the transaction.
    * **Merchant:** The party who sold the goods or services being disputed.
    * **Issuer:** The bank that issued the card to the cardholder.
    * **Acquirer:** The bank tasked with acquiring payment on the merchant’s behalf.
    * **Card Association/Scheme:** The card brands (e.g., Visa, Mastercard) overseeing the process.
    * **Payment Gateway:** The payment gateway facilitating the payment.

    **Reasons for a Chargeback Request**
    A chargeback request may be raised for various reasons, such as:

    * Service or product not received.
    * The product doesn’t match the description or is damaged.

    **How Does the Chargeback Process Work?**

    1. The **cardholder** (Ms. X) disputes a transaction by contacting the **card issuer** (e.g., SBI).

    * The issuer contacts the **acquirer** (e.g., HDFC Bank) via the same network used for the transaction.
    * The acquirer reaches out to the **payment gateway** (e.g., Cashfree), which then contacts the **merchant** (e.g., merchant.com) for details.

    2. The merchant is given a **turnaround time** to respond.

    * If no response is provided, the chargeback will be ruled in favour of the cardholder.

    3. After submitting proof, banks take **21 to 45 days** (representation time) to conclude.

    4. The cardholder has **90-120 days** to raise a chargeback request.

    5. If a chargeback occurs, the disputed amount will be **blocked** from the merchant's unsettled funds and will be released or refunded based on the outcome.

    **Chargeback Scenarios**

    **Scenario 1: The merchant decides to respond**
    The merchant must provide evidence related to the transaction, such as:

    * Email conversations
    * Invoices

    This proof is passed to the **issuer (e.g., SBI)** for review.

    1. **If the issuer accepts the proof:**

    * The chargeback request is declined, but the cardholder can still raise a **Second Presentment, Second Chargeback (Mastercard)** or **Pre-Arbitration (Visa)**.

    2. **If the issuer rejects the proof:**

    * The chargeback is ruled valid, and funds are reversed to the cardholder’s account.

    **Scenario 2: The merchant decides not to respond**

    * The chargeback is automatically ruled in favour of the cardholder, and the amount is reversed.

    **Second Presentment, Second Chargeback, or Pre-Arbitration**
    If the initial chargeback is won by the merchant, the customer can raise the dispute again.

    * The **merchant must respond** with all possible evidence.
    * **If the merchant does not respond:** The chargeback will favour the cardholder, and funds will be reversed.

    **Documents Required to Dispute a Chargeback**
    Merchants should keep the following documents ready to tackle any chargeback:

    * **Proof of delivery:** Tracking numbers, shipping receipts, etc.

    <Tip>
      Prepare these documents from day one to efficiently handle potential chargebacks.
    </Tip>

    **Invoice copy**: This should include your company name, price, and description of the product, date, customer’s name and address, date.

    **Order confirmation email**: This email provides customers with post-purchase reassurance. It should mandatorily include confirmation of your customer’s request (booking, registration, subscription and order) and the order summary.

    **Tracking details**: Shipment tracking details provided by the courier delivery company (Not applicable for all).

    Finally, we are near the end of the chargeback process. The **issuer reviews the chargeback claim** and the merchant's evidence. Each card network requires specific information to prove or disprove a dispute. This information is typically listed in the network’s rules and regulations.

    Let’s say the merchant wins a chargeback. The cardholder could still dispute the outcome. This takes on various names depending on the card network. For example, Visa calls this **Pre-Arbitration**, while Mastercard calls it a **Second Chargeback**. However, the process is essentially the same, as detailed below:

    **Level 1/Phase 1: Chargeback**\
    The initial phase where the cardholder disputes the transaction.

    **Level 2/Phase 2: Second Presentment, Second Chargeback, or Pre-Arbitration**\
    This gives the acquirer and the issuer a second chance to resolve the dispute. An issuer may issue pre-arbitration for several reasons, including:

    * A reason code change.
    * The cardholder offers new information.
    * The issuer believes the acquirer’s evidence does not disprove the dispute.
    * Terms and Conditions or Return Policies were not properly disclosed during the transaction.

    **Level 3/Phase 3: Arbitration**\
    Explicit time limits exist for issuers and acquirers to file for and respond to arbitration chargebacks. For example, Mastercard gives issuers and acquirers **45 days** to file. However, documents must be submitted well in advance to allow for thorough review.

    For more information on arbitration rates, refer to the [link](https://chargebacks911.com/arbitration-chargeback/).

    There are **151 reason codes** used to categorise chargebacks across Visa, Mastercard, and American Express.

    Reason codes can be grouped into five main categories:

    * **Fraud/No Authorization**
    * **Cancel Recurring Billing**
    * **Products/Services**
    * **Liability Shift**
    * **Others**

    <Note>
      Fraud/No Authorization chargebacks account for the largest percentage of disputes, followed by Cancel Recurring Billing and Products/Services disputes. Liability Shift and Other chargebacks represent a smaller percentage.
    </Note>

    For a detailed breakdown, refer to the [link](https://chargeback.com/5-chargeback-reason-code-categories/).

    **As a business, how can I avoid chargebacks?**

    * Cardholders often have an advantage as banks and credit card companies prioritise consumer protection.
    * Always maintain proof/evidence to challenge disputes. Store these documents in an easily accessible location, like a desktop folder or Google Drive.
    * Respond promptly to disputes and chargebacks. If you miss the stipulated time frame, banks automatically process the chargeback.
    * Be prepared with an action plan to handle chargebacks efficiently.

    **Questions?**\
    We're always happy to help with any questions you might have. Search our documentation, [contact support](https://www.cashfree.com/en/report-issue/), or [connect with our sales team](https://www.cashfree.com/contact-sales/). You can also chat with our team via chat for real-time support.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How do I check, if I am eligible for accepting payments from Rupay credit cards on UPI payments?">
    Almost all businesses are by default eligible to receive payments via Rupay credit card.

    <Note>
      Merchants with MCCs such as mutual fund providers, stock brokers, loan
      repayment, etc., are not eligible to accept credit payments.
    </Note>

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Why doesn't UPI appear as a payment option for a high-value order?">
    NPCI (National Payments Corporation of India) sets UPI per-transaction limits that vary by merchant category code (MCC). For some categories, such as drug stores and pharmacies, the standard NPCI limit is ₹1 lakh per transaction. If the order amount exceeds the NPCI UPI limit for your MCC, UPI does not appear as a payment option at checkout. NPCI sets this limit, not Cashfree, and it cannot be overridden, so offer alternative payment methods for high-value transactions in affected categories.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What is Pre Authorization?">
    Pre-Authorization lets you block a customer’s funds and capture the payment only after fulfilling the order.

    Supported cards: Works with Mastercard and Visa credit or debit cards.

    Flexible captures: Capture the full or partial amount later.

    Void transactions: Release blocked funds if the order isn’t processed.

    Easy control: Manage captures and voids manually via the [Merchant Dashboard](https://merchant.cashfree.com/merchants).
    A smarter way to handle payments with more control.

    Interested in the Pre-Authorization feature?
    [Contact sales](https://www.cashfree.com/contact-sales/)

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Which are the sponsor banks live on pre-authorisation?">
    The following sponsor banks currently support the pre-authorisation feature on Cashfree:

    * Axis Bank
    * HDFC Bank
    * ICICI Bank
    * IndusInd Bank
    * Kotak Mahindra Bank
    * Yes Bank
    * Federal Bank
    * State Bank of India
  </Accordion>

  <Accordion title="How to fix Failed to Verify Credentials?">
    If you are getting this error, it usually means you are using Production credentials on the Cashfree Test server or Test credentials on the Production server. To fix this, do the following:

    * Go to the page where you get API credentials: [https://merchant.cashfree.com/merchant/pg#api-key](https://merchant.cashfree.com/merchant/pg#api-key)
    * Ensure that you get the appropriate set of credentials (Test or Production). Also, verify that there are no typos in the `appId`/`secretKey`.
    * Ensure that in your integration type, you are selecting the correct server (Test or Production) of Cashfree.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="I get a warning that my webhook endpoint did not respond properly to the test. Is my webhook broken?">
    No, this warning does not block your webhook from working. When you add a webhook endpoint URL in the Merchant Dashboard, Cashfree sends it a test POST request to confirm it is reachable and returns HTTP 200. If your endpoint returns a different response to that test request, this warning appears, but Cashfree still saves the webhook URL and delivers live events to it. Ensure your endpoint returns HTTP 200 to POST requests, including test payloads, to clear the warning.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How do I delete an existing webhook configuration from the Merchant Dashboard?">
    Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login), go to **Developers > Webhooks**, locate the webhook endpoint you want to remove, and select the delete option for that entry.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are the different ways I can set up the payment gateway for my business?">
    Cashfree lets you integrate your [website](/docs/payments/online/web/redirect) or [mobile app](/docs/payments/online/mobile/android) with our payment gateway to accept payments. Over and above this, we also offer [plugins](/docs/payments/plugins/overview) to major e-commerce sites like [Shopify](https://apps.shopify.com/cashfree-payments), [Magento](https://marketplace.magento.com/cashfree-magento2-payment.html), [WooCommerce](https://wordpress.org/plugins/cashfree/), [OpenCart](https://www.opencart.com/index.php?route=marketplace/extension/info\&extension_id=37574), [PrestaShop](https://addons.prestashop.com/en/payment-card-wallet/50547-cashfree.html), and [WHMCS](https://marketplace.whmcs.com/product/5045-cashfree-payment-gateway). See [Cashfree-hosted checkout](/docs/payments/online/web/redirect) to know more.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are the different web integrations possible with Cashfree?">
    There are three types of web integrations possible with Cashfree:

    * [Checkout Forms](https://www.cashfree.com/docs/payment-gateway/checkout-forms)
    * [Seamless Basic](https://www.cashfree.com/docs/payment-gateway/seamless-basic)
    * [Seamless Pro](https://www.cashfree.com/docs/payment-gateway/seamless-pro)

    You can instantly set up any of these based on your requirements.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How do I become eligible for the Server-to-Server (S2S) seamless payment flow or Checkout URL API?">
    <Warning>
      The eligibility criteria below are pending verification against the current API specification. Confirm the exact requirements with your Cashfree account manager before submitting documents.
    </Warning>

    Eligibility depends on the payment mode. For card payments, submit a PCI-DSS compliance certificate. For all other payment modes, submit a GST return showing an annual turnover of more than ₹1 crore. Once Cashfree verifies the relevant document, the team enables the corresponding S2S flag on your account. Without this, only the standard hosted checkout is available.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What does the 'S2S Integration' label mean in the dashboard's Order Source field?">
    Orders created through the [Create Order API](/docs/api-reference/payments/latest/orders/create) receive this label. This does not indicate that your account has an active Server-to-Server seamless payment flow enabled. Any order you create programmatically via the API gets this label, regardless of which checkout mode the customer uses to pay.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What is the difference between S2S Integration and Next Gen API integration types in the Merchant Dashboard?">
    In the Merchant Dashboard, the integration type reflects how the payment was initiated:

    * **Next Gen API**: The payment was completed via the Next Gen Checkout flow using a frontend Web SDK (for example, `cashfree.checkout()`) and a `payment_session_id`. The flow is: order created on the backend → checkout opened on the client using the JS SDK → customer pays.
    * **S2S Integration**: The payment was initiated server-to-server from your backend using the Seamless / Order Pay flow (for example, `POST /orders/{order_id}/pay`) instead of launching the frontend checkout SDK.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Why do I see different integration types like S2S and Next Gen API for payments in my account?">
    Mixed integration labels depend on how a specific payment attempt was initiated rather than the payment status. Common reasons include:

    1. Your codebase supports both flows and routes traffic differently based on the channel, app, or webview.
    2. The frontend SDK failed to load (due to network, CSP, or ad-blocker issues), causing your system to fall back to an S2S pay call.
    3. Different products or modules within your system are using different Cashfree integration methods.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="If a refund was not initiated manually, how can I identify its source?">
    If a refund is initiated through an API rather than the Merchant Dashboard, Cashfree sets the refund's `refund_type` field to `MERCHANT_INITIATED` in the [Create Refund API](/docs/api-reference/payments/latest/refunds/create-refund) response. Check your application logs, scheduled jobs, or automated workflows to identify which API key or service triggered the request.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How do I generate API keys for the Cashfree test environment?">
    Test environment API credentials are self-serve and can be generated directly from the Merchant Dashboard:

    1. Log in to your [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
    2. Switch to the Test/Sandbox environment.
    3. Navigate to the **API Keys / Developer Settings** section.
    4. Generate or copy the Client ID (App ID) and Client Secret.

    Ensure that test credentials are used only with sandbox/test API endpoints, and production credentials are used only with the production environment.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Why are some payment options like cards or net banking hidden on the checkout page?">
    Cashfree's checkout experience is optimised for conversion by showing the most popular methods such as UPI and COD upfront. Other payment modes such as Cards, Wallets, and Net Banking are accessible under the **More** or **Cards / Wallets / Netbanking & more** option. If a payment instrument is already saved with Cashfree, it may also be shown upfront.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I integrate Cashfree payment gateway to my Shopify website?">
    Yes, we provide a predefined plugin for [Shopify](/docs/payments/shopify/payments) that helps you set up the Cashfree payment gateway with your Shopify account in no time, and with absolutely no code.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I integrate Cashfree payment gateway to my Magento website?">
    Yes, we provide a predefined plugin for [Magento](/docs/payments/plugins/magento) that helps you set up the Cashfree payment gateway with your Magento account in no time, and with absolutely no code.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I integrate Cashfree payment gateway to my Woo-Commerce website?">
    Yes, we provide a predefined plugin for [WooCommerce](/docs/payments/plugins/woocommerce) that helps you set up the Cashfree payment gateway with your WooCommerce account in no time, and with absolutely no code.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I integrate Cashfree payment gateway to my OpenCart website?">
    Yes, we provide a predefined plugin for [OpenCart](https://www.cashfree.com/docs/plugins/opencart) that helps you set up the Cashfree payment gateway with your OpenCart account in no time, and with absolutely no code.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I integrate Cashfree payment gateway to my PrestaShop website?">
    Yes, we do provide a predefined plugin for [PrestaShop](/docs/payments/plugins/prestashop) that helps you set up the Cashfree payment gateway with your PrestaShop account in no time, and with absolutely no code.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I integrate Cashfree payment gateway to my WHMCS website?">
    Yes, we do provide a predefined plugin for [WHMCS](https://www.cashfree.com/docs/plugins/whmcs) that helps you set up the Cashfree payment gateway with your WHMCS account in no time, and with absolutely no code.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I receive payments from my customers without integrating Cashfree to my website?">
    You can use the [Cashfree Payment Gateway Dashboard](https://www.cashfree.com) to create orders and accept payments using a **payment link**. These links can be sent to your customers via email or SMS, without the need to integrate Cashfree into your website.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What documents to be submitted as a proof of delivery?">
    **Invoice copy:** Every invoice should include your company name, price, and description of the product, date, customer’s name, and address, contact information (Email and/or phone), and transaction date.
    **Order confirmation email:** Confirmation emails provide customers with the feeling of post-purchase reassurance. It should mandatorily include confirmation of your customer request (booking, registration, subscription, and order) and the order summary.
    **Tracking details:** Shipment tracking details provided by the courier delivery company. (Please note that this may not be applicable for all).

    The above mentioned supporting documents are the general proofs that we request. Depending upon the nature of business/line of business (LOB), we may ask for other details such as:

    * **Customer signed Proof of Delivery:** Customer signed copy of proof of delivery.
    * **Confirmation email from a customer:** An email from the customer confirming the delivery of the product or the service provided.
    * **Customer signed copy of invoice:** A signed copy of the invoice from a customer.

    **Questions?**
    We're always happy to help you with any questions that you might have. You can search our FAQs, documentation, contact our support team, [connect with our sales team](https://www.cashfree.com), or fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1). You could also chat with our team via Intercom for real-time support.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="I run an NGO. How can I use Cashfree to accept donations?">
    Cashfree provides you with the flexibility to create **Payment Forms**, a no-code solution that your customers can use to pay any amount of their choice to your account.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="I want to accept international payments. Can I use Cashfree to accept payments in other currencies?">
    Yes, Cashfree supports a wide range of international payment options via credit cards and also PayPal.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="I am an existing PayPal user. How do I connect my Paypal account with Cashfree?">
    Yes, if you already have an account with PayPal, you need to authorise Cashfree to collect payments. Visit the [Cashfree website](https://www.cashfree.com) to know more.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="When will the payment gateway charges be deducted for my transactions?">
    For every transaction processed through Cashfree, either of the following charges applies:

    1. Upfront TDR–A fixed charge collected at a predefined frequency.
       OR
    2. Non-Upfront TDR–A charge deducted as a percentage (TDR%) or a flat fee from the transaction amount, with the remaining balance settled to your bank account.

       For every transaction that your customers make through Cashfree, TDR will be deducted from the total amount and the remaining amount will be settled to your bank account.

       <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How long does it take to process refunds?">
    You can initiate a refund for a transaction from the payment gateway dashboard by going to **PG Dashboard** > **Refunds** > **NEW REFUND** and providing the corresponding transaction ID or order ID. Once the refund is initiated, it will take 5-7 business days for the amount to be credited to your account.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What documents to be submitted as a proof of delivery?">
    **Invoice copy:** Every invoice should include your company name, price, and description of the product, date, customer’s name, and address, contact information (Email and/or phone), and transaction date.

    **Order confirmation email:** Confirmation emails provide customers with the feeling of post-purchase reassurance. It should mandatorily include confirmation of your customer request (booking, registration, subscription, and order) and the order summary.

    **Tracking details:** Shipment tracking details provided by the courier delivery company. (Please note that this may not be applicable for all).

    The above-mentioned supporting documents are the general proofs that we request. Depending upon the nature of business/line of business (LOB), we may ask for other details such as:

    * **Customer signed Proof of Delivery:** Customer signed copy of proof of delivery.
    * **Confirmation email from a customer:** An email from the customer confirming the delivery of the product or the service provided.
    * **Customer signed copy of invoice:** A signed copy of the invoice from a customer.

    **Questions?**\
    We're always happy to help you with any questions that you might have. You can search our FAQs, documentation, contact our support team, [connect with our sales team](https://www.cashfree.com), or fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1). You could also chat with our team via Intercom for real-time support.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are terms and conditions for activating Payment Gateway">
    Before we activate Cashfree Payment Gateway on a website or mobile app, we need a few prerequisites in place.

    1. Your website should be live in the public domain.
    2. Your website should have:
    3. \[Contact Us] section showing a valid `<email Id>` and a `<phone number>`
    4. \[Privacy Policy] section
    5. \[Refund Policy] section
    6. \[Terms & Conditions] section.
    7. Dealing in banned items.

    At Cashfree, we do not support businesses that deal in certain prohibited items. If your business deals in any such items, Cashfree Payment Gateway Account will not be activated in such a scenario.

    * Drop-shipped merchandise.
    * Adult goods and services which includes pornography and other sexually suggestive materials (including literature, imagery, and other media); escort or prostitution services.
    * Alcohol which includes alcoholic beverages such as beer, liquor, wine, or champagne.
    * Body parts which includes organs or other body parts.
    * Bulk marketing tools which includes email lists, software, or other products enabling unsolicited email messages (spam).
    * Cable descramblers and black boxes which includes devices intended to obtain cable and satellite signals for free.
    * Child pornography which includes pornographic materials involving minors.
    * Copyright unlocking devices which includes Mod chips or other devices designed to circumvent copyright protection.
    * Copyrighted media which includes unauthorised copies of books, music, movies, and other licensed or protected materials.
    * Copyrighted software which includes unauthorised copies of software, video games, and other licensed or protected materials, including OEM or bundled software.
    * Counterfeit and unauthorised goods which includes replicas or imitations of designer goods; items without a celebrity endorsement that would normally require such an association, fake autographs, counterfeit stamps, and other potentially unauthorised goods.
    * Drugs and drug paraphernalia which includes illegal drugs and drug accessories, including herbal drugs like salvia and magic mushrooms.
    * Drug test circumvention aids which include drug cleansing shakes, urine test additives, and related items.
    * Endangered species which include plants, animals, or other organisms (including product derivatives) in danger of extinction.
    * Gaming/gambling which includes lottery tickets, sports bets, memberships/enrolment in online gambling sites, and related content.
    * Government IDs or documents which includes fake IDs, passports, diplomas, and noble titles.
    * Hacking and cracking materials which includes manuals, how-to guides, information, or equipment enabling illegal access to software, servers, websites, or other protected property.
    * Illegal goods which includes materials, products, or information promoting illegal goods or enabling illegal acts.
    * Miracle cures which includes unsubstantiated cures, remedies, or other items marketed as quick health fixes.
    * Offensive goods which includes literature, products or other materials that:\
      a) Defame or slander any person or groups of people based on race, ethnicity, national origin, religion, sex, or other factors\
      b) Encourage or incite violent acts\
      c) Promote intolerance or hatred.
    * Offensive goods, a crime which includes crime scene photos or items, such as personal belongings, associated with criminals.
    * Prescription drugs or herbal drugs or any kind of online pharmacies which includes drugs or other products requiring a prescription by a licensed medical practitioner.
    * Pyrotechnic devices and hazardous materials which include fireworks and related goods; toxic, flammable, and radioactive materials and substances.
    * Regulated goods which include airbags; batteries containing mercury; Freon or similar substances/refrigerants, chemical/industrial solvents, government uniforms, car titles or logos, license plates, police badges, and law enforcement equipment, lock-picking devices, pesticides; postage meters, recalled items, slot machines, surveillance equipment; goods regulated by government or other agency specifications.
    * Securities, which include stocks, bonds, or related financial products.
    * Tobacco and cigarettes which includes cigarettes, cigars, chewing tobacco, and related products.
    * Traffic devices which include radar detectors/jammers, license plate covers, traffic signal changers, and related products.
    * Weapons include firearms, ammunition, knives, brass knuckles, gun parts, and other armaments.
    * Wholesale currency which includes discounted currencies or currency exchanges.
    * Live animals or hides/skins/teeth, nails, and other parts, etc. of animals.
    * Multi-Level Marketing collection fees.
    * Matrix sites or sites using a matrix scheme approach.
    * Work-at-home information.
    * Any product or service which is not in compliance with all applicable laws and regulations whether federal, state, local, or international including the laws of India.
    * The Merchant shall not sell, purchase, provide or exchange a cardholder’s name or MasterCard/Visa account number information in any form obtained by reason of a MasterCard/Visa Card transaction to any third party other than its MasterCard/Visa acquiring Member-Citrus Pay, or pursuant to a government/statutory or competent body’s request.
    * Pyrotechnic devices, combustibles, corrosives, and hazardous materials which includes explosives, fireworks and related goods; toxic, flammable, and radioactive materials and substances.
    * Regulated goods which include airbags; batteries containing mercury; Freon or similar substances/refrigerants; chemical/industrial solvents; government uniforms; car titles; license plates; police badges and law enforcement equipment; lock-picking devices; pesticides; postage meters; recalled items; slot machines; surveillance equipment; goods regulated by government or other agency specifications.

    <Warning>
      In case the Cashfree Payment Gateway has been activated and later it is found that the business or the website does not comply with the terms and conditions, the account shall be deactivated at Cashfree's discretion.
    </Warning>

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are High Risk Transactions & High Risk Merchants">
    **What are high-risk transactions?**

    A particular transaction that may have the potential to attract a customer dispute or chargeback is identified by Cashfree as well as banking partners and marked as a high-risk transaction. The payment to the merchant against such a transaction is put on hold until the issue is resolved.

    **Who are high-risk merchants?**\
    As a payment gateway, Cashfree generally settles the collected amount within T+1\* or T+2\* days. However, some merchants may not qualify for the traditional payment processing agreements due to the inherent risk based on the nature of the business.

    In addition to the line of business, there may be instances where Cashfree receives frequent escalations from consumers or banks about the genuineness of transactions or financial credibility, based on risk analysis. In such cases, Cashfree may mark the business as a high-risk merchant and temporarily suspend the traditional payment settlement process.

    **High-risk merchants at the time of onboarding**\
    If the nature of the business is seen as risky, to protect the interest of the paying consumer, Cashfree monitors the merchant for a certain period after onboarding. During this period, all settlements by the high-risk merchant shall be subject to the submission of Proof of Delivery. Once the proofs are submitted, the settlements are processed. The time frame of monitoring may vary from merchant to merchant and scenario to scenario, and will be decided by Cashfree at the time of onboarding.

    **What are the documents required to prove delivery?**\
    As proof of delivery, you can share ANY ONE of the following supporting documents:

    1. **Invoice Copy**: Every invoice should include your company name, price, and description of the product, date, customer’s name and address, and transaction date.
    2. **Order Confirmation Email**: Confirmation emails provide customers with post-purchase reassurance. It should mandatorily include confirmation of your customer request (booking, registration, subscription, and order) and the order summary.
    3. **Tracking Details**: Shipment tracking details provided by the courier delivery company. (Please note that this may not be applicable for all).

    The above-mentioned supporting documents are general proofs we request. Depending on your business/line of business (LOB), we may ask for other details such as:

    * **Customer Signed Proof of Delivery**: A customer-signed copy of proof of delivery.
    * **Confirmation Email from a Customer**: An email from the customer confirming the delivery of the product or service.
    * **Customer-Signed Copy of Invoice**: A signed copy of the invoice from the customer.

    **Questions?**\
    We're always happy to help you with any questions that you might have. You can search our FAQs, documentation, contact our support team, [connect with our sales team](https://www.cashfree.com/contact-sales/), or fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1). You could also chat with our team via Intercom for real-time support.

    **Note**: Settlement cycle is subject to bank approval and can vary based on transaction type, business category/model, risk parameters, and other factors.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What is the checkout experience offered by Cashfree's PG like?">
    It is quite critical for a payment gateway to offer a **seamless experience** to the customers. Multiple redirects and ugly pop-ups lead to a confusing checkout experience and end up eroding the customer's confidence. A lot of websites do offer a beautiful checkout experience, but this lot is limited to big technology houses with abundant manpower.

    We at Cashfree have carefully tried to solve this problem. We offer multiple ways to integrate our payment gateway and render a seamless checkout experience to customers. Two basic aspects of our UI integration are:

    * **No Redirects**\
      Customer experiences the checkout flow on your website without navigating to any third-party page.

    * **Custom UI**\
      You own the look and feel of the checkout flow, or you can also use our ready-made beautiful UI components.

    [Sign-Up to see our PG in action](https://merchant.cashfree.com/merchants/signup)

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How does Subscription work?">
    Cashfree enables businesses to automate recurring payment collection from customers. Our system streamlines the payment process while providing flexibility in payment schedules and methods.

    Subscriptions help you to accept repeat online payments:

    1. Create custom plans for your customers and activate them with ease.
    2. Merchant add customer's payment details and subscribe to a plan.
    3. Customers have the ability to put it on hold/cancel subscription at any time.
       [Read more about subscriptions](/docs/payments/subscription/introduction)

    [Sign up on the Merchant Dashboard](https://merchant.cashfree.com/auth/login).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What is Third-Party Validation Feature for BFSI Sector Businesses?">
    **What is Third Party Validation? Why is it important?**

    Merchants in securities, broking, and mutual funds operating in the BFSI (Banking, Financial Services, and Insurance) sector are prone to cybercrimes, asset appropriation, identity thefts, money laundering, accounting frauds, etc. To reduce the risk, the Securities and Exchange Board of India (SEBI) has laid out guidelines for these merchants.

    As per the SEBI guidelines, all payments to such businesses must be made by their customers exclusively from pre-registered bank accounts. A pre-registered bank account is the one the customer shared during enrolment for schemes offered by businesses in these sectors.

    **Introducing Third-Party Validation feature by Cashfree**\
    Cashfree now supports Third-Party Validation on Payment Gateway. Using Cashfree’s Third-Party Validation feature, businesses can comply with the SEBI guidelines by ensuring that payments are made only from customers' registered bank accounts.

    Some of the primary use cases of Third-Party Validation feature include:

    * **BFSI sector**: Brokers and other online businesses can now sign up for Cashfree services and securely transact with customers in real-time.
    * **Loan repayments**: Merchants in the loan repayment sector can use Third-Party Validation to prevent discrepancies in payments and dispute cases.

    **Features**\
    When a customer transacts with the Cashfree Payment Gateway (with the TVP feature enabled), their bank account number or CRN (Customer Relationship Number) is mapped to lock the transaction, ensuring the payment is processed only from their registered bank account.

    **Advantages**

    * TPV is compliant with SEBI guidelines.
    * It serves as a one-stop solution for merchants in the BFSI sector to meet compliance requirements and start transacting securely with their customers.

    **Benefits**\
    When you enable the TVP feature on your Cashfree Payment Gateway, Cashfree matches the account number provided by the customer during registration against the account used for the transaction. If a non-registered account number is used, Cashfree marks the transaction as FAILED and provides an appropriate failure reason.

    To know more about the feature and how it can help your business, contact your Cashfree Account manager. If you are new to Cashfree, please [sign up to contact us](https://merchant.cashfree.com/merchants/signup). We would love to talk to you.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What is Rupay Credit Card on UPI payments mean for my business?">
    Your customers can now make payments using their Rupay credit cards via UPI apps like BHIM, PhonePe, and Google Pay. This enables seamless, fast, and convenient transactions directly through UPI.
  </Accordion>

  <Accordion title="What card subtypes are available in the webhook and API responses?">
    The available card subtypes are:

    * P – Premium

    * E – Elite

    * C – Corporate

    * R – Retail
  </Accordion>

  <Accordion title="How a customer can make payments via Rupay credit card on UPI Apps?">
    Steps to Make a Payment Using a RuPay Credit Card on UPI:

    1. Scan the merchant’s UPI QR Code OR Enter the UPI ID using any UPI-enabled app.
    2. Enter the payment amount.
    3. Select the linked RuPay credit card account as the payment method.
    4. Enter the UPI PIN to authorize the transaction.
    5. Receive payment confirmation upon successful transaction.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What is PayPal Express Checkout on Cashfree Payment Gateway?">
    PayPal is one of the world’s most popular payment modes used by 350+ mn users across 200+ countries worldwide.
    Cashfree has integrated directly with PayPal to enable seamless merchant onboarding with PayPal and to allow a faster checkout experience using PayPal Express Checkout integration.
    Cashfree Payment Gateway merchants can now add the PayPal Express Checkout button on their website or mobile app.
    **Benefits of PayPal Express Checkout**

    * Accept payments from international customers in 100 currencies using PayPal.
    * Faster customer payment checkout with PayPal Express Checkout button.
    * 24/7 transaction monitoring, fraud prevention, and seller protection that help you keep your business PCI compliant.
    * Easy integration. Enable PayPal on your Cashfree Checkout in just a few steps \[refer to PayPal API integration steps here]. No separate integration required.

    **How do I integrate PayPal with my Cashfree account?**

    PayPal Express Checkout is available for all Cashfree Payment Gateway merchants.

    * If you are an existing Cashfree Payment Gateway merchant and want to enable PayPal Express Checkout as a checkout mode, follow the \[PayPal API integration steps here]. For any queries related to integration, contact your Cashfree Account Manager or fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1), and we’ll get in touch with you.
    * If you’re not an existing Cashfree merchant, [sign up](https://www.cashfree.com) now to enable PayPal and other 120+ payment modes including net banking, debit cards, Paytm, UPI, and start collecting online payments.

    **Please note**: PayPal is a payment mode and is only available on request. It is not enabled by default. Raise a request with your Account Manager to enable this feature.

    **Other International Payment Options on Cashfree**\
    With Cashfree Payment Gateway, you can offer your customers a range of international checkout options, including PayPal and international cards such as Visa, Mastercard, American Express, and Diners Club.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Is there any limit to the number of Aadhaar cards that can be verified in a day?">
    No, there is no limit to the number of Aadhaar cards that can be verified in a day.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How do I check, if I am eligible for accepting payments from Rupay credit cards on UPI payments?">
    Almost all businesses are by default eligible to receive payments via Rupay credit card.

    <Note>
      Except for the merchant MCCs such as mutual fund providers, stock brokers, loan repayment etc, are not eligible to accept credit payments.
    </Note>

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What is Rupay Credit Card on UPI payments mean for my business?">
    Your customers now will be able to make payments from their Rupay credit cards of the issuing banks which are live on via their preferred UPI apps like BHIM, PhonePe and Google Pay.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How a customer can make payments via Rupay credit card on UPI Apps?">
    **To make the payment with RuPay Credit Card on UPI, a customer must follow these steps:**

    1. Scan the merchant UPI QR code.
    2. Enter the amount and select the credit account.
    3. Select the RuPay credit card account followed by the UPI PIN to authorize the payment.
    4. Transaction successful.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How to link RuPay Credit Card on UPI apps?">
    **To link RuPay Credit Card on UPI App, follow these steps:**

    1. Open your preferred UPI app (currently supported on BHIM, PhonePe, and Google Pay).
    2. Navigate to the option to **Add Bank Account** or **Add Payment Method**.
    3. Select **Credit Card** as the account type.
    4. Choose your credit card issuer bank.
    5. Select your RuPay Credit Card.
    6. Confirm the card details.
    7. Set a UPI PIN for the card.

    Your RuPay Credit Card is now successfully linked to your UPI app.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How can this feature be enabled?">
    This is a request-based feature, available only to PCI-DSS-compliant merchants. To enable it, reach out to your account manager or submit a [Support Form](https://merchant.cashfree.com/auth/login).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How can checkout merchants build this functionality?">
    Cashfree-hosted Checkout merchants use Cashfree’s [offer engine](/docs/payments/checkout/offers) to run offers. To set up risk checks, merchants leverage Cashfree’s [RiskShield](/docs/payments/risk-shield/overview) solution. Both offerings allow merchants to set up offer targeting strategies and risk rules through a self-serve flow on the Cashfree dashboard, making implementation easy and effective.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What is a capture call in Pre-Authorization?">
    Capture call is performed after authorization. It is a merchant-initiated request (via API) to collect the previously authorized funds. This step debits the amount from the customer.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What is the validity of capture?">
    If not captured within 7 days, the authorization expires, and the funds are released back to the customer.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can a merchant capture a partial amount?">
    Yes, merchants can capture a partial amount of the authorized funds.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Is MDR charged on the authorized or captured amount?">
    MDR is always applied only on the captured amount.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Which cards support pre-authorization?">
    All Visa, Mastercard and Rupay credit and debit cards support pre-authorization.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What is void in Pre-Authorization?">
    A void call cancels the authorization before capture, releasing the hold on funds.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can a merchant void a partial amount?">
    No, voiding must be for the entire authorized amount.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are some common use cases for Pre-Authorization?">
    Here are some common use cases:

    <ul>
      <li>**Ticket Bookings** – Airlines, concerts, and events often place a hold on a credit card to ensure funds are available before finalising the booking. This is useful if confirmation is pending or for refundable ticket options.</li>
      <li>**Car Rentals** – Rental companies use pre-authorisation to secure a deposit in case of damages, late returns, or additional charges. The hold is released if no extra fees are incurred.</li>
      <li>**Hotel Reservations** – Hotels pre-authorise a guest’s credit card at check-in to cover potential incidentals, damages, or unpaid charges, ensuring payment security before checkout.</li>
    </ul>

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How does settlement occur in a pre-authorization transaction?">
    Settlement occurs when the merchant finalises a pre-authorized transaction by capturing the funds.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="When does the merchant receive the funds in a pre-authorization transaction?">
    Merchants typically receive funds from pre-authorized transactions as per their normal settlement cycle, i.e., T+x days after a successful capture.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What happens if a customer disputes a settled transaction?">
    A dispute may result in a chargeback, requiring the merchant to provide proof of authorization and service fulfilment.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Does Cashfree support EMI recommendations?">
    Cashfree allows merchants to configure EMI options for their customers. However, we currently do not provide a built-in EMI recommendation engine.

    If you want to suggest EMI plans to your users, you can implement your own recommendation logic externally, based on factors such as tenure, interest rate, and total payable amount.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How does Cashfree handle chargebacks?">
    The chargeback process is as follows:

    1. The customer raises a dispute with their issuing bank.
    2. The issuing bank communicates with the acquiring bank via the card network.
    3. The acquiring bank notifies Cashfree.
    4. Cashfree contacts the merchant for supporting documentation.
    5. The merchant must respond within the stipulated time.

    **Merchant response options:**

    * **Accept the dispute:** The amount is refunded, and the dispute is marked as *Closed (Merchant Accepted)*.
    * **Contest the dispute:** The merchant provides evidence, such as invoices, delivery proof, or communication logs.

    **Best practices:**

    * Maintain comprehensive transaction records.
    * Respond to chargebacks within the required timelines.
    * Clearly communicate refund and cancellation policies on your website.

    The final resolution may take 21–45 days depending on the banks involved.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are the transaction limits on Cashfree?">
    Cashfree applies transaction limits based on your account activation stage:

    * **Partial activation:** ₹50,000 per month
    * **Full activation:** Limits are set by your bank and are not controlled by Cashfree.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Does Cashfree share success rate and SLA data?">
    Yes. We share PG-wise success rate (SR) data periodically. Please note that this data includes only a subset of payment modes and gateways and may not represent the entire system’s performance.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Which billing and ERP systems does Cashfree support?">
    Cashfree supports a wide range of integrations, including:

    **E-commerce platforms:**

    * Shopify
    * WooCommerce
    * Magento
    * OpenCart
    * PrestaShop
    * WHMCS
    * WIX
    * Zoho
    * StoreHippo
    * CScart

    **ERP and SaaS platforms:**

    * Education, travel, restaurant, and hospitality ERPs
    * Accounting software
    * Lending, checkout, and POS SaaS products
    * CRMs and financial service platforms

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How to withdraw funds from Cashfree?">
    Cashfree supports fund withdrawals through different products. The process varies depending on whether you're using Payments (PG), Payouts, or SecureID.

    **Payments (PG)**
    To initiate an on-demand withdrawal from Payments Gateway:

    1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
    2. In the left navigation panel, go to Settlements.
    3. Select On-demand from the dropdown.
    4. Click **Withdraw Now** next to the available balance.
    5. A list of previously initiated withdrawals is also displayed on this screen.

    **Payouts**

    To initiate withdrawal funds from your Cashfree Payouts wallet:

    1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
    2. Navigate to Fund Sources > Cashfree Wallet.
    3. Under the Overview section, click Withdraw next to Last Withdrawal.
    4. Enter the withdrawal Amount and Remarks, then click **Withdraw**.

    **SecureID**

    To withdraw funds from your SecureID account:

    1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
    2. In the left navigation panel, go to Accounts.
    3. A summary of your account transactions will be displayed.
    4. Click **Withdraw** to initiate the fund withdrawal.

    **Withdrawal guidelines:**

    * Maximum 3 withdrawals allowed per day.
    * Funds are credited only to your registered business bank account.
    * Processing time is between 8:00 AM and 6:45 PM, Monday to Saturday except 2nd and 4th Saturdays.
    * Withdrawals are non-reversible once submitted.
    * It may take 30 minutes to a few hours for the credit to reflect.

    <iframe title="FAQ feedback: Withdraw funds" />
  </Accordion>

  <Accordion title="How can a partner use the S2S flow for their merchants if S2S is enabled at the partner level?">
    If S2S is enabled at the partner level, create the order with partner authentication headers instead of the merchant `x-client-id` and `x-client-secret`. Pass `x-partner-apikey` and `x-partner-merchantid` as described in [API authentication](/docs/api-reference/authentication).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How can I fetch the latest payment status for a specific transaction or order?">
    Use the [Get Payments for an Order API](/docs/api-reference/payments/latest/payments/get-payments-for-an-order) to retrieve every payment attempt for an order and determine the latest state. Verify the status on your server after the customer returns from checkout, and use this API as a fallback if a webhook has not arrived.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How should I handle PENDING payments and what is the recommended approach for timeouts?">
    Treat `PENDING` as a non-terminal state. Do not fulfil the order or mark the payment as `SUCCESS` or `FAILED` while it remains `PENDING`. Rely on payment webhooks for asynchronous updates, and use the [Get Payments for an Order API](/docs/api-reference/payments/latest/payments/get-payments-for-an-order) as a fallback. Do not use a fixed client-side timeout to mark a pending transaction as failed, because a late authorisation can still confirm the payment. See [Payment Lifecycle](/docs/payments/online/resources/payment-lifecycle).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How should I update my system to handle the change in cf_payment_id and other identifier lengths?">
    Cashfree identifiers such as `cf_payment_id`, `cf_order_id`, and `cf_refund_id` are variable-length strings and can be up to 19 characters. To stay compatible, complete the following updates:

    1. **Update data types**: Treat these identifiers as variable-length strings (`VARCHAR`) in your database schema and application logic. Do not store them as integers or fixed-length numeric types.
    2. **Remove fixed-length assumptions**: Accept identifiers up to 19 characters.
    3. **Set the API version**: Send `x-api-version` as `2023-08-01` or later (for example, `2025-01-01` or `2026-01-01`) so identifiers are returned as strings.
    4. **Check deprecation headers**: Monitor the `x-deprecated-at` header in API responses to track when your current API version is deprecated.

       <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How do I generate a HAR file to help debug a technical issue with Cashfree support?">
    To generate a HAR (HTTP Archive) file, complete the following steps:

    1. Open your web browser (for example, Chrome or Firefox) and go to the page where the issue occurs.
    2. Open Developer Tools. Right-click the page and select **Inspect**, or press F12, Ctrl+Shift+I (Windows), or Command+Option+I (macOS).
    3. Open the **Network** tab and confirm that recording is active.
    4. Reproduce the issue on the page.
    5. Right-click anywhere in the Network panel and select **Save all as HAR with content**.
    6. Save the file and attach it when you submit the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1).

       <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Where can I find the Cashfree Payment Gateway integration and API documentation?">
    You can refer to the following links for Cashfree Payment Gateway integration and API references:

    **Integration guides**

    * [Integration Overview](/docs/payments/overview)
    * [Web Integration](/docs/payments/online/web/redirect)
    * [Android SDK](/docs/payments/online/mobile/android)
    * [iOS SDK](/docs/payments/online/mobile/ios)
    * [React Native](/docs/payments/online/mobile/react-native)
    * [Flutter](/docs/payments/online/mobile/flutter)
    * [Data to Test Integration](/docs/api-reference/payments/data-to-test-integration)
    * [Dev Studio (Integration Preview)](https://www.cashfree.com/devstudio/preview/pg/web/checkout)

    **API references**

    * [API Endpoints Overview](/docs/api-reference/payments/latest/overview)
    * [Create Order API](/docs/api-reference/payments/latest/orders/create-order)
    * [Get Order Details](/docs/api-reference/payments/latest/orders/get-order)
    * [Get Payments for an Order](/docs/api-reference/payments/latest/payments/get-payments-for-an-order)
    * [Create Refund](/docs/api-reference/payments/latest/refunds/create-refund)
    * [Webhooks Configuration](/docs/api-reference/payments/latest/payments/webhooks)

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How can I test Cashfree APIs before my account is fully activated?">
    To complete integration and testing before your account is activated, use the Cashfree Sandbox environment via the Merchant Dashboard.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How can I implement a seamless integration to collect payment information on my own frontend and complete the payment from the backend?">
    To collect payment information on your own frontend and complete the payment from the backend, use the [Cashfree Order Pay API](/docs/api-reference/payments/latest/payments/order-pay).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How can I restrict specific payment methods for a single order in the Hosted Checkout integration?">
    For standard Hosted Checkout integrations, you can use the `order_meta.payment_methods` parameter in the [Create Order API](/docs/api-reference/payments/latest/orders/create-order) to restrict the available payment modes for a specific order. For example, passing `"payment_methods": "cc,dc"` shows only credit and debit card options. This provides order-level control without changing your global account settings.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I use the payment_methods parameter to enable or disable Cash on Delivery (COD) for an order?">
    No. Cashfree handles COD separately, so don't pass it in the `order_meta.payment_methods` parameter. You manage COD availability through [COD rules](/docs/payments/checkout/cod/overview), which let you set eligibility based on order amount, pincode, product restrictions, or return-to-origin (RTO) intelligence.

    <iframe title="FAQs feedback component" />
  </Accordion>
</AccordionGroup>


# Collection Accounts
Source: https://www.cashfree.com/docs/payments/global-collections/collection-accounts

Open Cashfree Global Collections accounts to receive international payments in major currencies and settle funds in INR with transparent FX and lower fees.

Collection accounts help you accept and receive payments internationally. The Collection Accounts screen lists the account details that you can share with your customers to receive payments. Each collection account is applicable for a particular currency and payment mode. For example, if your customer wants to send the payment through USD in ACH payment type, you can send the corresponding collection account details to them.

You can copy the account details from the dashboard and share them with your customers. Any payment received on this collection account will reflect in the [Transactions screen](/docs/payments/global-collections/transactions). The copied collection account details will look like this:

```js theme={"dark"}
Account Holder Name: JOHN DOE CORP.
Account No.: 83127126461
ACH Routing Code : 026033150
Bank Name: Community Federal Savings Bank
Bank Address: 810 Seventh Avenue, New York, NY 10019, US
Bank Country: US
For successful transfer, please make a payment only via Local - ACH mode
```

The account number and the routing code are different for each currency.

<Frame>
  <img />
</Frame>

The Collection Accounts screen has the following details:

* **Account No.**: This represents the account number or IBAN code for the respective currency and payment mode combination.
* **Account Type**: This represents the type of collection account (account number or IBAN).
* **Payment Type**: This represents the mode of payment that the collection account can receive payments. We currently support 4 local rails and SWIFT payment types. Refer to the [supported payment types](#supported-payment-types).
* **Currency**: This represents the currency supported for the corresponding collection account. We use standard ISO codes to refer to the currency.
* **Country**: This represents the country the collection account belongs to.
* **Bank Name**: This represents the name of the bank to which the collection account belongs to.
* **Bank Address**: This represents the address of the bank where this collection account is located.
* **Routing Code**: This represents the routing or sort code for the respective payment mode and bank.
* **Code Type**: This represents the type of routing code for the bank. It can be a sort code, SWIFT code, ACH Routing code, or just routing code.

## Supported currencies

| Currency name | ISO code |
| :- | :- |
| United Arab Emirates Dirham | AED |
| Australian Dollar | AUD |
| Canadian Dollar | CAD |
| Swiss Franc | CHF |
| Chinese Yuan Renminbi | CNY |
| European Euro | EUR |
| Pound Sterling | GBP |
| Hong Kong Dollar | HKD |
| Japanese Yen | JPY |
| Norwegian Krone | NOK |
| New Zeland Dollar | NZD |
| Qatari Riyal | QAR |
| Saudi Arabian Riyal | SAR |
| Singapore Dollar | SGD |
| Thai Baht | THB |
| United States Dollar | USD |
| South African Rand | ZAR |

## Supported payment types

| Payment type | Description |
| :- | :- |
| Local - ACH | ACH Payment mode in the United States. |
| Local - SEPA | Single Euro Payments Area payment mode in Europe. |
| Local - EFT | Electronic Fund Transfer payment mode in Canada. |
| Local - FPS | Faster Payments Service payment mode for Pound Sterling in GB. |
| SWIFT | Society for Worldwide Interbank Financial Telecommunications. |

Use the **Search & Filter** option to view the collection accounts. Apply filters for account type, payment type, and currency from the drop-down menu.


# Global Collections FAQs
Source: https://www.cashfree.com/docs/payments/global-collections/faqs

Browse Cashfree Global Collections FAQs covering account setup, supported currencies, FX rates, settlement timelines, compliance documents, and limits.

<Accordion title="What is Global Collections and when should I use it?">
  Global Collections allows your customers to pay for your products in their native currency, and the amount is settled to your account in INR. Cashfree handles the currency conversion and other hassles.
</Accordion>

<Accordion title="What is Foreign Inward Remittance?">
  Foreign inward remittance refers to the transfer of money to India from anywhere outside India. For example, when you receive money in your regional bank account from a business or an individual abroad, it is called foreign inward remittance.
</Accordion>

<Accordion title="For what kind of transactions can I use Global Collections accounts?">
  If you are selling goods or services outside of India and have an invoice value of up to USD 10,000, you can use Global Collection accounts. The payer can be an individual or a business, as long as the payment is for the sale of goods or for the rendering of service(s).
</Accordion>

<Accordion title="What currencies do Global Collections support?">
  | Currency name |
  | :- |
  | United Arab Emirates Dirham |
  | Australian Dollar |
  | Canadian Dollar |
  | Swiss Franc |
  | Chinese Yuan Renminbi |
  | European Euro |
  | Pound Sterling |
  | Hong Kong Dollar |
  | Japanese Yen |
  | Norwegian Krone |
  | New Zealand Dollar |
  | Qatari Riyal |
  | Saudi Arabian Riyal |
  | Singapore Dollar |
  | Thai Baht |
  | United States Dollar |
  | South African Rand |
</Accordion>

<Accordion title="Does Cashfree issue Foreign Inward Remittance Statements (FIRS)?">
  Yes, Cashfree’s AD-1 partner issues eFIRS on a T+1\* basis. T is the day on which the beneficiary receives the payment in their bank account in India.

  To obtain your eFIRS, submit a request through the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) or contact your Cashfree account manager.
</Accordion>

<Accordion title="Is Global Collections FEMA compliant?">
  Yes, here is the [OPGSP guideline](https://www.rbi.org.in/Scripts/NotificationUser.aspx?Id=10037) for your reference.
</Accordion>


# Overview
Source: https://www.cashfree.com/docs/payments/global-collections/introduction

Use Cashfree Global Collections to accept international payments from clients abroad, hold foreign currency balances, and settle to your Indian bank.

With Global Collections, you can now accept international payments from your customers. The payments that are received from your customers are converted to INR and settled into your bank account automatically. You can accept international payments in more than 17 currencies from 180+ countries. Cashfree takes care of the currency conversion in real-time; you need not worry about it.

## Global collections flow

<Frame>
  <img />
</Frame>

## Advantages

* International payment support - receive payments from any part of the world.
* Support for major currencies such as USD, GBP, EUR etc.
* Scale up your business in terms of size and complexity.
* Simplified Foreign Inward Remittance Statement (e-FIRS) issuance.
* Save more than 50% on international wire transfers.
* Higher success rate when processing international transactions.

<Warning>
  Make sure that you are a registered business in India. You can start accepting international payments only after we review your documents which typically takes around 24-48 hours. We will contact you for any additional documents required for activation.
</Warning>

To get started with [Global Collections](https://www.cashfree.com/international-payments/international-wire-transfer/), click **Contact Sales**. If you are an existing merchant, contact your respective account manager.

**The following articles help you understand Global Collections in detail:**

* [Collection Accounts](/docs/payments/global-collections/collection-accounts)
* [Transactions](/docs/payments/global-collections/transactions)
* [FAQs](/docs/payments/global-collections/faqs)


# Transactions
Source: https://www.cashfree.com/docs/payments/global-collections/transactions

Review every Global Collections transaction in Cashfree, filter by currency, account, or status, and reconcile international receipts to INR settlements.

The Transactions screen covers the payments made in foreign currencies and does not represent the settlement made in INR. You can view all the payments done by your customers along with other details such as:

* **Initiated At**: This represents when the transaction was initiated by your customer.
* **CF Transaction ID**: This represents the transaction ID generated by Cashfree to identify each transaction.
* **Account**: This represents the collection account in which the payment is received.
* **Account Type**: This represents the account type of the collection account.
* **Payment Type**: This represents the payment mode in which the payment is received.
* **Amount**: This represents the amount and currency of the transaction.
* **Remitter Account**: This represents the account number from which the payment is made.
* **Remitter Name**: This represents the name of the person who made the payment.
* **Status**: This represents the status of the transaction.

<Frame>
  <img />
</Frame>

The table below explains the various transaction status:

| Transaction status | Description |
| :- | :- |
| FAILED | The transaction has failed and the amount has been returned to the remitter. |
| SUCCESS | The foreign currency leg of this transaction was successful and the payment is eligible for INR settlement. |

## Transaction details

Click on a transaction to view the complete details of the transaction along with the remitter details.

<Frame>
  <img />
</Frame>


# Overview
Source: https://www.cashfree.com/docs/payments/international-payments/collect-from-india/overview

Use Cashfree to accept cross-border payments from India to overseas merchants while staying compliant with RBI PA-CB guidelines on verification and reporting.

Cashfree provides India’s first PA-CB-compliant Imports solution which helps Foreign Merchants (based outside India) to
collect funds from Indian customers for the various goods and services they are selling. Merchants can offer their
customers to pay funds using any of the Indian payment methods such as UPI, Credit Card, Debit Card, Net Banking,
Virtual Accounts, etc. Funds collected by Cashfree from the Indian customers upon successful verification of transactions
will be settled in the overseas bank account of the Foreign Merchant.

Cashfree offers India’s first PA-CB-compliant payment collection solution, enabling foreign merchants (based outside
India) to collect payments from Indian customers for a variety of goods and services. Merchants can provide their
customers with the flexibility to pay using popular Indian payment methods such as UPI, credit cards, debit cards, net
banking, and virtual accounts. Once transactions are successfully verified, the funds collected from Indian customers
are seamlessly settled into the foreign merchant's overseas bank account.

<img />

<Tip>Install [Cashfree Agent Skills](/docs/tools-ai/cashfree-agent-skills) to bring Cashfree product knowledge into your AI coding assistant (Claude Code, Cursor, VS Code Copilot, Gemini CLI, and more) to answer integration questions and generate accurate code without leaving your editor.</Tip>

## Key benefits of Cashfree’s import collection solution

* Diverse Payment Options: Offer a variety of payment methods including UPI, credit/debit cards net banking, and Virtual Accounts..
* Flexible Integration Options: Choose between our no-code solution for quick setup or our robust API or webhook stack for full customisation or combine both to suit your business needs.
* Faster Settlements: With Cashfree, transactions can settle as early as T+2 days, ensuring improved cash flow and operational efficiency.
* Centralised transaction monitoring: Cashfree provides a centralised dashboard for enhanced transaction monitoring and reconciliation.
* Risk and Fraud Protection: With built-in risk and fraud detection/prevention mechanisms we have got you covered and you can focus now on growing your business.
* Expanded Use Cases: Our solution can be used to process transactions across various use cases of Digital Goods, Physical Goods and Digital Services.
* Centralised transaction monitoring: Cashfree provides a centralised dashboard for enhanced transaction monitoring and reconciliation.
* Risk and Fraud Protection: With built-in risk and fraud detection/prevention mechanisms we have got you covered and you can focus now on growing your business.
* Expanded Use Cases: Our solution can be used to process transactions across various use cases of Digital Goods, Physical Goods & Digital Services.

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/payments/latest/international-payments/collect-from-india/overview">Collect from India API Overview</a></li>
  </ul>
</div>


# Transaction Verification
Source: https://www.cashfree.com/docs/payments/international-payments/collect-from-india/transaction-verification

Submit transaction verification details on Cashfree for cross-border collections from India to comply with RBI PA-CB guidelines on reporting and verification.

To comply with PA-CB (Payment Aggregator Cross Border) guidelines, you must submit specific information and documents so Cashfree can complete due diligence on the importer and the transaction.

The following table lists the verification parameters you submit for cross-border payment transactions:

| Verification parameter | Field key | Description |
| - | - | - |
| Buyer name | `importer_name` | Name of the Indian customer who is buying the product or service. |
| Goods description | `goods_description` | Description of the product or service you are selling. |
| Invoice number | `imports_invoice_number` | Unique invoice number generated for the customer invoice. |
| Address | `importer_address_line` | Complete address of the Indian customer. |
| Postal code | `importer_address_postal_code` | Postal code of the Indian customer. |
| HSN | `hs_code` | Harmonized System of Nomenclature (HSN) code as per [DGFT](https://www.dgft.gov.in/CP/?opt=itchs). |
| Payer PAN | `importer_pan` | Permanent Account Number (PAN) of the payer. |
| Payer date of birth | `importer_dob` | Date of birth of the payer as recorded in their PAN details. Use DD-MM-YYYY format. |
| LRS TCS limit | `lrs_tcs_limit` | Indicates whether the transaction breaches the customer's ₹10 lakh Liberalised Remittance Scheme (LRS) limit for the current financial year. Valid values: `YES` or `NO`. |
| LRS and TCS declaration | `lrs_tcs_declaration` | Indicates whether the LRS and Tax Collected at Source (TCS) declaration was shown to the customer. Valid values: `YES` or `NO`. |

You can submit verification details in either of the following ways:

* During order creation or subscription charge
* After the transaction is completed

## Submit verification details during order creation

You can include verification details when you create an order or charge a customer for a subscription.

### Create an order with verification details

To include verification details when creating an order, add the `order_tags` parameter in the Create Order API request.

For more information about the Create Order API, see [Create Order](/docs/api-reference/payments/latest/orders/create-order#body-order-tags).

**Example request:**

```json theme={"dark"}
"order_tags": {
    "imports_importer_name": "JOHN DOE INDUSTRIES",
    "imports_importer_address_postal_code": "533103",
    "imports_goods_description": "chocolates",
    "imports_invoice_number": "52300"
}
```

### Charge a subscription with verification details

To include verification details when charging a subscription, pass the `payment_tags` parameter in your subscription charge request.

**Example request:**

```bash theme={"dark"}
curl --location 'https://api.cashfree.com/pg/subscriptions/pay' \
--header 'Content-Type: application/json' \
--header 'x-api-version: 2025-01-01' \
--header 'x-client-id: <CLIENT_ID>' \
--header 'x-client-secret: <CLIENT_SECRET>' \
--data '{
    "subscription_id": "substest",
    "payment_id": "paymenttest",
    "payment_type": "CHARGE",
    "payment_amount": 1,
    "payment_schedule_date": "2025-07-12T10:00:00+05:30",
    "payment_tags": {
        "imports_goods_description": "chocolates",
        "imports_importer_address_postal_code": "560075",
        "imports_importer_name": "John Doe"
    }
}'
```

## Submit verification details after the transaction

If the transaction is already complete, or you need to provide additional clarification, submit verification details after the transaction.

To submit verification details after a transaction is completed, use the Upload Payment Verification Details API.

For more information, see [Upload Payment Verification Details](/docs/api-reference/payments/latest/international-payments/collect-from-india/upload-payment-verification-details).

## Verification update statuses

After you submit verification details, Cashfree updates the status of your request. The following table describes each verification status:

| Status | Description |
| :- | :- |
| Action Required | You must provide additional information or documents to continue verification. |
| In Review | The verification team is reviewing the submitted documents. |
| Verified | Cashfree has completed verification and approved the submitted documents. |

These statuses appear in the payment verification details update webhook. For more information, see [Collect from India webhooks](/docs/api-reference/payments/latest/international-payments/collect-from-india/import-webhooks).


# Collection Accounts
Source: https://www.cashfree.com/docs/payments/international-payments/global-collections/collection-accounts

Open Cashfree Global Collections accounts to receive international payments in major currencies and settle in INR with transparent FX and predictable fees.

Collection accounts help you accept and receive payments internationally. The Collection Accounts screen lists the account details that you can share with your customers to receive payments. Each collection account is applicable for a particular currency and payment mode. For example, if your customer wants to send the payment through USD in ACH payment type, you can send the corresponding collection account details to them.

You can copy the account details from the dashboard and share them with your customers. Any payment received on this collection account will reflect in the [Transactions screen](/docs/payments/global-collections/transactions). The copied collection account details will look like this:

```js theme={"dark"}
Account Holder Name: JOHN DOE CORP.
Account No.: 83127126461
ACH Routing Code : 026033150
Bank Name: Community Federal Savings Bank
Bank Address: 810 Seventh Avenue, New York, NY 10019, US
Bank Country: US
For successful transfer, please make a payment only via Local - ACH mode
```

The account number and the routing code are different for each currency.

<Frame>
  <img />
</Frame>

The Collection Accounts screen has the following details:

* **Account No.**: This represents the account number or IBAN code for the respective currency and payment mode combination.
* **Account Type**: This represents the type of collection account (account number or IBAN).
* **Payment Type**: This represents the mode of payment that the collection account can receive payments. We currently support 4 local rails and SWIFT payment types. Refer to the [supported payment types](#supported-payment-types).
* **Currency**: This represents the currency supported for the corresponding collection account. We use standard ISO codes to refer to the currency.
* **Country**: This represents the country the collection account belongs to.
* **Bank Name**: This represents the name of the bank to which the collection account belongs to.
* **Bank Address**: This represents the address of the bank where this collection account is located.
* **Routing Code**: This represents the routing or sort code for the respective payment mode and bank.
* **Code Type**: This represents the type of routing code for the bank. It can be a sort code, SWIFT code, ACH Routing code, or just routing code.

## Supported currencies

| Currency name | ISO code |
| :- | :- |
| United Arab Emirates Dirham | AED |
| Australian Dollar | AUD |
| Canadian Dollar | CAD |
| Swiss Franc | CHF |
| Chinese Yuan Renminbi | CNY |
| European Euro | EUR |
| Pound Sterling | GBP |
| Hong Kong Dollar | HKD |
| Japanese Yen | JPY |
| Norwegian Krone | NOK |
| New Zeland Dollar | NZD |
| Qatari Riyal | QAR |
| Saudi Arabian Riyal | SAR |
| Singapore Dollar | SGD |
| Thai Baht | THB |
| United States Dollar | USD |
| South African Rand | ZAR |

## Supported payment types

| Payment type | Description |
| :- | :- |
| Local - ACH | ACH Payment mode in the United States. |
| Local - SEPA | Single Euro Payments Area payment mode in Europe. |
| Local - EFT | Electronic Fund Transfer payment mode in Canada. |
| Local - FPS | Faster Payments Service payment mode for Pound Sterling in GB. |
| SWIFT | Society for Worldwide Interbank Financial Telecommunications. |

Use the **Search & Filter** option to view the collection accounts. Apply filters for account type, payment type, and currency from the drop-down menu.


# Global Collections FAQs
Source: https://www.cashfree.com/docs/payments/international-payments/global-collections/faqs

Browse Cashfree Global Collections FAQs in the IPG section covering account setup, currencies, FX rates, settlements, compliance, and transaction limits.

<Accordion title="What is Global Collections and when should I use it?">
  Global Collections allows your customers to pay for your products in their native currency, and the amount is settled to your account in INR. Cashfree handles the currency conversion and other hassles.
</Accordion>

<Accordion title="What is Foreign Inward Remittance?">
  Foreign inward remittance refers to the transfer of money to India from anywhere outside India. For example, when you receive money in your regional bank account from a business or an individual abroad, it is called foreign inward remittance.
</Accordion>

<Accordion title="For what kind of transactions can I use Global Collections accounts?">
  If you are selling goods or services outside of India and have an invoice value of up to USD 10,000, you can use Global Collection accounts. The payer can be an individual or a business, as long as the payment is for the sale of goods or for the rendering of service(s).
</Accordion>

<Accordion title="What currencies do Global Collections support?">
  | Currency name |
  | :- |
  | United Arab Emirates Dirham |
  | Australian Dollar |
  | Canadian Dollar |
  | Swiss Franc |
  | Chinese Yuan Renminbi |
  | European Euro |
  | Pound Sterling |
  | Hong Kong Dollar |
  | Japanese Yen |
  | Norwegian Krone |
  | New Zealand Dollar |
  | Qatari Riyal |
  | Saudi Arabian Riyal |
  | Singapore Dollar |
  | Thai Baht |
  | United States Dollar |
  | South African Rand |
</Accordion>

<Accordion title="Does Cashfree issue Foreign Inward Remittance Statements (FIRS)?">
  Yes, Cashfree’s AD-1 partner issues eFIRS on a T+1\* basis. T is the day on which the beneficiary receives the payment in their bank account in India.

  To obtain your eFIRS, submit a request through the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) or contact your Cashfree account manager.
</Accordion>

<Accordion title="Is Global Collections FEMA compliant?">
  Yes, here is the [OPGSP guideline](https://www.rbi.org.in/Scripts/NotificationUser.aspx?Id=10037) for your reference.
</Accordion>


# Overview
Source: https://www.cashfree.com/docs/payments/international-payments/global-collections/introduction

Use Cashfree Global Collections to accept international payments from clients abroad, hold foreign currency balances, and settle to your Indian bank account.

With Global Collections, you can now accept international payments from your customers. The payments that are received from your customers are converted to INR and settled into your bank account automatically. You can accept international payments in more than 17 currencies from 180+ countries. Cashfree takes care of the currency conversion in real-time; you need not worry about it.

## Global collections flow

<Frame>
  <img />
</Frame>

## Advantages

* International payment support - receive payments from any part of the world.
* Support for major currencies such as USD, GBP, EUR etc.
* Scale up your business in terms of size and complexity.
* Simplified Foreign Inward Remittance Statement (e-FIRS) issuance.
* Save more than 50% on international wire transfers.
* Higher success rate when processing international transactions.

<Warning>
  Make sure that you are a registered business in India. You can start accepting international payments only after we review your documents which typically takes around 24-48 hours. We will contact you for any additional documents required for activation.
</Warning>

To get started with [Global Collections](https://www.cashfree.com/international-payments/international-wire-transfer/), click **Contact Sales**. If you are an existing merchant, contact your respective account manager.

**The following articles help you understand Global Collections in detail:**

* [Collection Accounts](/docs/payments/global-collections/collection-accounts)
* [Transactions](/docs/payments/global-collections/transactions)
* [FAQs](/docs/payments/global-collections/faqs)

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/payments/latest/international-payments/global-collections/overview">Global Collections API Overview</a></li>
    <li><a href="/docs/payments/international-payments/global-collections/collection-accounts">Collection Accounts</a></li>
    <li><a href="/docs/payments/international-payments/global-collections/transactions">Transactions</a></li>
    <li><a href="/docs/payments/international-payments/global-collections/faqs">Global Collections FAQs</a></li>
  </ul>
</div>


# Transactions
Source: https://www.cashfree.com/docs/payments/international-payments/global-collections/transactions

Review IPG Global Collections transactions in Cashfree, filter by currency, account, or status, and reconcile international receipts to INR settlement payouts.

The Transactions screen covers the payments made in foreign currencies and does not represent the settlement made in INR. You can view all the payments done by your customers along with other details such as:

* **Initiated At**: This represents when the transaction was initiated by your customer.
* **CF Transaction ID**: This represents the transaction ID generated by Cashfree to identify each transaction.
* **Account**: This represents the collection account in which the payment is received.
* **Account Type**: This represents the account type of the collection account.
* **Payment Type**: This represents the payment mode in which the payment is received.
* **Amount**: This represents the amount and currency of the transaction.
* **Remitter Account**: This represents the account number from which the payment is made.
* **Remitter Name**: This represents the name of the person who made the payment.
* **Status**: This represents the status of the transaction.

<Frame>
  <img />
</Frame>

The table below explains the various transaction status:

| Transaction status | Description |
| :- | :- |
| FAILED | The transaction has failed and the amount has been returned to the remitter. |
| SUCCESS | The foreign currency leg of this transaction was successful and the payment is eligible for INR settlement. |

## Transaction details

Click on a transaction to view the complete details of the transaction along with the remitter details.

<Frame>
  <img />
</Frame>

## FAQs

<AccordionGroup>
  <Accordion title="How do I initiate refunds in Cashfree?">
    You can initiate refunds through our [APIs](https://www.cashfree.com/docs/api-reference/payments/latest/refunds/create-refund#create-refund) or directly from the [Merchant Dashboard](https://merchant.cashfree.com/merchants).

    To initiate a refund from the dashboard:

    Navigate to Payment Gateway Dashboard → Transactions → Payments.
    Select the specific transaction you want to refund.
    If you have the Transaction ID or Order ID, you can search and initiate the refund directly from the dashboard.

    <Note>
      Refunds can only be processed for successful transactions.
    </Note>

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How do I check the status of a transaction?">
    As soon as you log in to your Cashfree account, the Summary section in the payment gateway dashboard will give
    you instant context as to what is the amount of transaction that has happened on that particular day, and the
    settlement amount that you’re yet to receive. Besides this, Cashfree also provides a wide range of reports to
    analyse your business finances. The different reports that Cashfree provides you are,

    * Transactions Report
    * Settlement Reconciliation Report
    * Settlement Summary
    * Refunds Report
    * Ledger Report
    * Monthly Invoices

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I track the amount of daily transactions in Cashfree?">
    The Cashfree Dashboard provides a real-time overview of your daily transactions and finances. You can instantly track the total transactions for the day and the unsettled amount pending from Cashfree.

    [Click here to learn more](https://merchant.cashfree.com/merchants/pg/summary/overview)

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can Cashfree send reports to my own SFTP servers?">
    Yes. With Cashfree, you can receive specific reports such as Transaction reports, Settlements and
    Adjustment reports, directly into your own SFTP servers or Cashfree's SFTP servers at a set frequency
    everyday.

    If you'd like Cashfree to push out the reports to your own SFTP servers, please fill out this
    [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) with your requirements.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What is a dispute?">
    A dispute arises when there is a disagreement over a transaction, initiated by your customer with their issuing bank or directly with Cashfree. Customers may also report fraudulent transactions to cyber cells, while suspicious transaction disputes are often raised directly by banks.

    As a merchant, you have the option to either defend the dispute by providing sufficient evidence or accept the dispute if you agree with the claim. If you accept the dispute, the amount will be refunded to the customer.

    [Read more on disputes](/docs/payments/manage/disputes/overview).

    1. Product Quality Issues – The delivered product is defective, damaged, or does not match the description.
    2. Incorrect Product – The customer received a different item than what was ordered.
    3. Unauthorised Charges – Additional fees were applied without the customer’s consent.
    4. Non-Delivery – The product or service was not delivered as promised.
    5. Billing Errors – Mistakes in the amount charged, duplicate transactions, or incorrect billing details.
    6. Fraudulent Transactions – The customer did not authorise the transaction (potential fraud or misuse).
       <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Why am I debited for a dispute and When will I get the amount back?">
    When a dispute is raised, the disputed amount is debited from the merchant’s account, as banks debit Cashfree to provide provisional credit to the customer.

    The final refund depends on the dispute outcome:
    If the dispute is resolved in your favour, the amount will be credited back to your account.
    If the dispute is ruled in the customer’s favour, the amount will remain with the customer.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What is a POD QR Code and how does the TTL (Time to Live) feature work?">
    A POD (Pay on Demand) QR code allows merchants to generate payment QR codes that remain valid for an extended period of up to 30 days. This Time to Live (TTL) duration is configured via the PG Config settings, and it gives customers the flexibility to complete the payment at any time within the configured TTL window.
    For example, a merchant may print a POD QR code on a physical receipt and hand it to a customer. The customer can scan and pay later, within the 30-day TTL.
    During the TTL period:
    -The payment status will not be marked as “Failed” even if payment hasn't been received. It will be marked as incomplete
    -The system waits for a successful payment until TTL expires.
    -If no payment is made after 30 days, the transaction is marked as USER\_DROPPED.

    This ensures better control over delayed payment flows while reducing refund-related complications.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How will I be notified if my customer has raised a dispute?">
    Email notifications can be configured from the [Merchant Dashboard](https://merchant.cashfree.com/merchants). Emails on which the merchant wants to receive these notifications can be configured from the [Merchant Dashboard](https://merchant.cashfree.com/merchants) by following the below steps:

    Go to Payment Gateway Dashboard > Settings > Email Notifications > Dispute Emails.

    Emails are triggered on following events:
    New Dispute Created – Get notified when a customer raises a dispute.

    1. Dispute Phase/Type Change – Receive updates when the dispute moves between phases like Pre-arbitration or Arbitration.
    2. State Change – Stay informed when the dispute transitions between states, e.g., Action Required → Under Review.
    3. Comment Updated – Get alerts when a new comment is added to the dispute.
    4. Reminder Email – Receive a notification when the dispute deadline approaches.
       <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are the various types of dispute?">
    In Cashfree, Disputes can be of the following types:

    **Dispute**
    Raised for end-customer complaints, fraudulent, or suspicious transactions reported by law enforcement or banks.

    **Retrieval**
    Soft chargebacks initiated when the customer queries a transaction with their issuing bank before an actual chargeback occurs.

    **Chargeback**
    Raised when a customer disputes a transaction due to non-delivery of services or transaction issues, following a retrieval request.

    **Pre-Arbitration**
    The second level of chargeback, where the customer decides whether to pursue further dispute based on the evidence provided.

    **Arbitration**
    The final stage of the chargeback, where both parties submit evidence, and the card network or NPCI makes the final decision.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are the deadlines for various disputes?">
    Following are the representation deadlines given to merchants depending on the type of dispute:

    * **Disputes:** 3 calendar days. In certain cases, such as real-time fraudulent transactions, a 1-day deadline may apply.
    * **Retrieval:** 3 calendar days.
    * **Chargeback:** 3 calendar days.
    * **Pre-arbitration:** 2 calendar days.
    * **Arbitration:** 1 calendar day.
      <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Why did a transaction marked as Failed later show as Success?">
    In rare cases, a transaction initially marked as "Failed" may later move to "Success" status during the bank reconciliation process. This typically happens when the bank confirms the settlement of funds after the initial failure was recorded.

    <iframe title="FAQs feedback component" />
  </Accordion>
</AccordionGroup>


# Currencies
Source: https://www.cashfree.com/docs/payments/international-payments/ipg/currencies-supported

Explore the 140+ currencies supported by Cashfree’s International Payment Gateway, including decimal and zero-decimal options for seamless global payments.

# Supported Currencies

Cashfree’s International Payment Gateway supports **140+ currencies**, enabling Indian merchants to accept payments from customers worldwide with ease. From major currencies like **USD**, **EUR**, and **GBP** to emerging market options like **AED**, **BRL**, and **ZMW**, we’ve got you covered. Pair this with our **Pay Native (DCC)** feature to let customers pay in their local currency while you settle in INR.

## Decimal support

We handle currencies with precision:

* **Currencies with decimals**: Accept amounts like **12.00 INR**, **5.50 USD**, or **99.99 EUR** for flexible pricing.
* **Zero-decimal currencies**: Limited to whole amounts, e.g., **1 JPY**, **500 VND**, ensuring compliance with currency standards.

<Callout type="info" title="Why Decimals Matter">
  Decimal support lets you price competitively in markets like India (e.g., 12.00 INR), while zero-decimal currencies like JPY align with local conventions (e.g., 1 JPY = 1 yen, no cents).
</Callout>

***

## Full currency list

Below is the complete list of supported currencies, including their codes, decimal handling, and the minimum order amount allowed for each currency.

<Note>
  Cashfree previously required a minimum order amount of 1 whole unit for all currencies. This minimum has since been lowered to `0.01` or `0.1` for the currencies listed below. All other currencies continue to require a minimum order amount of 1 unit.
</Note>

| Currency | Code | Decimal support | Minimum order amount | Example |
| - | - | - | - | - |
| Afghan Afghani | AFN | 2 | 1 | 12.23 AFN |
| Albanian Lek | ALL | 2 | 1 | 12.23 ALL |
| Algerian Dinar | DZD | 2 | 1 | 12.23 DZD |
| Angolan Kwanza | AOA | 2 | 1 | 12.23 AOA |
| Argentine Peso | ARS | 2 | 1 | 12.23 ARS |
| Armenian Dram | AMD | 2 | 1 | 12.23 AMD |
| Aruban Florin | AWG | 2 | 0.1 | 12.23 AWG |
| Australian Dollar | AUD | 2 | 0.1 | 12.23 AUD |
| Azerbaijani Manat | AZN | 2 | 0.1 | 12.23 AZN |
| Bahamian Dollar | BSD | 2 | 0.1 | 12.23 BSD |
| Bahrain Dinar | BHD | 3 | 0.01 | 12.234 BHD |
| Bangladesh Taka | BDT | 2 | 1 | 12.23 BDT |
| Barbadian Dollar | BBD | 2 | 0.1 | 12.23 BBD |
| Belize Dollar | BZD | 2 | 0.1 | 12.23 BZD |
| Bermudian Dollar | BMD | 2 | 0.1 | 12.23 BMD |
| Bhutanese Ngultrum | BTN | 2 | 1 | 12.23 BTN |
| Bolivian Boliviano | BOB | 2 | 1 | 12.23 BOB |
| Bosnia Convertible Mark | BAM | 2 | 0.1 | 12.23 BAM |
| Botswana Pula | BWP | 2 | 1 | 12.23 BWP |
| Brazilian Real | BRL | 2 | 0.1 | 12.23 BRL |
| Brunei Dollar | BND | 2 | 0.1 | 12.23 BND |
| Bulgarian Lev | BGN | 2 | 0.1 | 12.23 BGN |
| Burundian Franc | BIF | 0 | 1 | 12 BIF |
| Cambodian Riel | KHR | 2 | 1 | 12.23 KHR |
| Canadian Dollar | CAD | 2 | 0.1 | 12.23 CAD |
| Cape Verdean Escudo | CVE | 2 | 1 | 12.23 CVE |
| Cayman Islands Dollar | KYD | 2 | 0.01 | 12.23 KYD |
| Central African CFA Franc | XAF | 0 | 1 | 12 XAF |
| CFP Franc | XPF | 0 | 1 | 12 XPF |
| Chilean Peso | CLP | 0 | 1 | 12 CLP |
| Colombian Peso | COP | 2 | 1 | 12.23 COP |
| Comorian Franc | KMF | 0 | 1 | 12 KMF |
| Congolese Franc | CDF | 2 | 1 | 12.23 CDF |
| Costa Rican Colon | CRC | 2 | 1 | 12.23 CRC |
| Czech Koruna | CZK | 2 | 1 | 12.23 CZK |
| Danish Krone | DKK | 2 | 0.1 | 12.23 DKK |
| Djiboutian Franc | DJF | 0 | 1 | 12 DJF |
| Dominican Peso | DOP | 2 | 1 | 12.23 DOP |
| East Caribbean Dollar | XCD | 2 | 0.1 | 12.23 XCD |
| Egyptian Pound | EGP | 2 | 1 | 12.23 EGP |
| Eritrean Nakfa | ERN | 2 | 1 | 12.23 ERN |
| Eswatini Lilangeni | SZL | 2 | 1 | 12.23 SZL |
| Ethiopian Birr | ETB | 2 | 1 | 12.23 ETB |
| Euro | EUR | 2 | 0.01 | 12.23 EUR |
| Falkland Islands Pound | FKP | 2 | 0.01 | 12.23 FKP |
| Fijian Dollar | FJD | 2 | 0.1 | 12.23 FJD |
| Gambian Dalasi | GMD | 2 | 1 | 12.23 GMD |
| Georgian Lari | GEL | 2 | 0.1 | 12.23 GEL |
| Ghanaian Cedi | GHS | 2 | 1 | 12.23 GHS |
| Gibraltar Pound | GIP | 2 | 0.01 | 12.23 GIP |
| Guatemalan Quetzal | GTQ | 2 | 0.1 | 12.23 GTQ |
| Guinean Franc | GNF | 0 | 1 | 12 GNF |
| Guyanese Dollar | GYD | 2 | 1 | 12.23 GYD |
| Haitian Gourde | HTG | 2 | 1 | 12.23 HTG |
| Honduran Lempira | HNL | 2 | 1 | 12.23 HNL |
| Hong Kong Dollar | HKD | 2 | 0.1 | 12.23 HKD |
| Hungarian Forint | HUF | 2 | 1 | 12.23 HUF |
| Icelandic Krona | ISK | 0 | 1 | 12 ISK |
| Indian Rupee | INR | 2 | 1 | 12.23 INR |
| Indonesian Rupiah | IDR | 2 | 1 | 12.23 IDR |
| Iraqi Dinar | IQD | 3 | 1 | 12.234 IQD |
| Jamaican Dollar | JMD | 2 | 1 | 12.23 JMD |
| Japanese Yen | JPY | 0 | 1 | 12 JPY |
| Jordanian Dinar | JOD | 3 | 0.01 | 12.234 JOD |
| Kazakhstani Tenge | KZT | 2 | 1 | 12.23 KZT |
| Kenya Shilling | KES | 2 | 1 | 12.23 KES |
| Kuwaiti Dinar | KWD | 3 | 0.01 | 12.234 KWD |
| Kyrgyzstani Som | KGS | 2 | 1 | 12.23 KGS |
| Lao Kip | LAK | 2 | 1 | 12.23 LAK |
| Lebanese Pound | LBP | 2 | 1 | 12.23 LBP |
| Liberian Dollar | LRD | 2 | 1 | 12.23 LRD |
| Libyan Dinar | LYD | 3 | 0.1 | 12.234 LYD |
| Macanese Pataca | MOP | 2 | 0.1 | 12.23 MOP |
| Macedonian Denar | MKD | 2 | 1 | 12.23 MKD |
| Malagasy Ariary | MGA | 2 | 1 | 12.23 MGA |
| Malawian Kwacha | MWK | 2 | 1 | 12.23 MWK |
| Malaysian Ringgit | MYR | 2 | 0.1 | 12.23 MYR |
| Maldivian Rufiyaa | MVR | 2 | 1 | 12.23 MVR |
| Mauritanian Ouguiya | MRU | 2 | 1 | 12.23 MRU |
| Mauritius Rupee | MUR | 2 | 1 | 12.23 MUR |
| Mexican Peso | MXN | 2 | 1 | 12.23 MXN |
| Moldovan Leu | MDL | 2 | 1 | 12.23 MDL |
| Mongolian Togrog | MNT | 2 | 1 | 12.23 MNT |
| Moroccan Dirham | MAD | 2 | 0.1 | 12.23 MAD |
| Mozambican Metical | MZN | 2 | 1 | 12.23 MZN |
| Namibian Dollar | NAD | 2 | 1 | 12.23 NAD |
| Nepalese Rupee | NPR | 2 | 1 | 12.23 NPR |
| New Israeli Sheqel | ILS | 2 | 0.1 | 12.23 ILS |
| New Taiwan Dollar | TWD | 2 | 1 | 12.23 TWD |
| New Zealand Dollar | NZD | 2 | 0.1 | 12.23 NZD |
| Nicaraguan Cordoba | NIO | 2 | 1 | 12.23 NIO |
| Nigerian Naira | NGN | 2 | 1 | 12.23 NGN |
| Norwegian Krone | NOK | 2 | 0.1 | 12.23 NOK |
| Papua New Guinea Kina | PGK | 2 | 0.1 | 12.23 PGK |
| Paraguayan Guarani | PYG | 0 | 1 | 12 PYG |
| Peruvian Sol | PEN | 2 | 0.1 | 12.23 PEN |
| Philippine Peso | PHP | 2 | 1 | 12.23 PHP |
| Polish Zloty | PLN | 2 | 0.1 | 12.23 PLN |
| Pound Sterling | GBP | 2 | 0.01 | 12.23 GBP |
| Qatari Rial | QAR | 2 | 0.1 | 12.23 QAR |
| Renminbi (Yuan) | CNY | 2 | 0.1 | 12.23 CNY |
| Rial Omani | OMR | 3 | 0.01 | 12.234 OMR |
| Romanian Leu | RON | 2 | 0.1 | 12.23 RON |
| Russian Ruble | RUB | 2 | 1 | 12.23 RUB |
| Rwandan Franc | RWF | 0 | 1 | 12 RWF |
| Saint Helena Pound | SHP | 2 | 0.01 | 12.23 SHP |
| Samoan Tala | WST | 2 | 0.1 | 12.23 WST |
| Saudi Riyal | SAR | 2 | 0.1 | 12.23 SAR |
| Serbian Dinar | RSD | 2 | 1 | 12.23 RSD |
| Seychellois Rupee | SCR | 2 | 1 | 12.23 SCR |
| Sierra Leonean Leone | SLL | 2 | 1 | 12.23 SLL |
| Singapore Dollar | SGD | 2 | 0.1 | 12.23 SGD |
| Solomon Islands Dollar | SBD | 2 | 0.1 | 12.23 SBD |
| Somali Shilling | SOS | 2 | 1 | 12.23 SOS |
| South African Rand | ZAR | 2 | 1 | 12.23 ZAR |
| South Korean Won | KRW | 0 | 1 | 12 KRW |
| Sri Lanka Rupee | LKR | 2 | 1 | 12.23 LKR |
| Surinamese Dollar | SRD | 2 | 1 | 12.23 SRD |
| Swedish Krona | SEK | 2 | 0.1 | 12.23 SEK |
| Swiss Franc | CHF | 2 | 0.01 | 12.23 CHF |
| Tajikistani Somoni | TJS | 2 | 0.1 | 12.23 TJS |
| Tanzanian Shilling | TZS | 2 | 1 | 12.23 TZS |
| Thai Baht | THB | 2 | 1 | 12.23 THB |
| Tongan Paanga | TOP | 2 | 0.1 | 12.23 TOP |
| Trinidad and Tobago Dollar | TTD | 2 | 0.1 | 12.23 TTD |
| Tunisian Dinar | TND | 3 | 0.1 | 12.234 TND |
| Turkish Lira | TRY | 2 | 1 | 12.23 TRY |
| Turkmenistan Manat | TMT | 2 | 0.1 | 12.23 TMT |
| UAE Dirham | AED | 2 | 0.1 | 12.23 AED |
| Ugandan Shilling | UGX | 0 | 1 | 12 UGX |
| Ukrainian Hryvnia | UAH | 2 | 1 | 12.23 UAH |
| Uruguayan Peso | UYU | 2 | 1 | 12.23 UYU |
| US Dollar | USD | 2 | 0.1 | 12.23 USD |
| Uzbekistani Som | UZS | 2 | 1 | 12.23 UZS |
| Vanuatu Vatu | VUV | 0 | 1 | 12 VUV |
| Vietnam Dong | VND | 0 | 1 | 12 VND |
| West African CFA Franc | XOF | 0 | 1 | 12 XOF |
| Yemeni Rial | YER | 2 | 1 | 12.23 YER |
| Zambian Kwacha | ZMW | 2 | 1 | 12.23 ZMW |


# Overview
Source: https://www.cashfree.com/docs/payments/international-payments/ipg/overview

Scale Indian businesses globally with the Cashfree International Payment Gateway, with Pay Native DCC, 140+ currencies, and high success rates.

# Accept Global Payments with Ease

Cashfree's **IPG (International Payment Gateway)** empowers Indian merchants to break into global markets effortlessly. Accept payments from customers worldwide using major international cards—Visa, Mastercard, American Express, and more—in **140+ currencies**. With our standout feature, **Pay Native** (Dynamic Currency Conversion), your customers pay in their home currency while you settle in INR, all with transparent, real-time exchange rates.

From **instant Foreign Information Return Statements (FIRS)** for compliance to **industry-best success rates and uptime**, we’ve built a solution that simplifies cross-border payments. Whether you’re selling digital goods, physical products, or services, Cashfree delivers security, speed, and scalability for your global ambitions.

<Tip>Install [Cashfree Agent Skills](/docs/tools-ai/cashfree-agent-skills) to bring Cashfree product knowledge into your AI coding assistant (Claude Code, Cursor, VS Code Copilot, Gemini CLI, and more) to answer integration questions and generate accurate code without leaving your editor.</Tip>

## Key benefits

<CardGroup>
  <Card title="Pay Native (DCC)" icon="currency-dollar">
    Customers pay in their currency (e.g., USD, EUR) with locked-in rates, boosting trust and conversions. You settle in INR, risk-free.
  </Card>

  <Card title="140+ Currencies" icon="globe-alt">
    Reach more markets with support for USD, EUR, GBP, SGD, JPY, and beyond—far more than competitors.
  </Card>

  <Card title="Instant FIRS" icon="document-text">
    Get Foreign Information Return Statements instantly for every transaction, simplifying tax compliance.
  </Card>

  <Card title="Top Success Rates" icon="check-circle">
    Enjoy industry-leading transaction success and 99.99% uptime, even during peak demand.
  </Card>
</CardGroup>

<Callout type="success" title="Industry-Leading Reliability">
  Achieve higher conversions with **optimised payment routing** and **99.99% uptime**, ensuring your business thrives even during high-traffic events like Black Friday.
</Callout>

## Integration made simple

<Accordion title="No-Code Plugins" icon="plug">
  Get started in minutes with plugins for **Shopify**, **WooCommerce**, **Magento**, and more. Perfect for businesses without technical resources.
</Accordion>

<Accordion title="Custom APIs and Webhooks" icon="code">
  Build tailored solutions with our **robust APIs** and **webhooks**, offering full control over your payment flows.
</Accordion>

<Accordion title="Hybrid Approach" icon="sliders">
  Combine no-code and custom integrations to suit your unique needs—flexibility at its best.
</Accordion>

## More benefits

* **Fast settlements**: Receive funds in your Indian bank account within **T+2 days**, even on holidays, for better cash flow.
* **Fraud protection**: PCI DSS compliance, **3DS 2.0**, and **AI-driven fraud detection** keep your transactions secure and chargebacks low.
* **Unified dashboard**: Monitor, reconcile, and analyse payments with real-time insights, MCC-aligned reporting, and instant FIRS access.
* **Transparent pricing**: No setup fees, competitive rates, and custom plans for high-volume merchants to maximise profits.

<Note>
  Indian merchants can now process foreign currency transactions using cards issued in India. This feature is not supported for subscription-based transactions. To disable this feature, contact [care@cashfree.com](mailto:care@cashfree.com)
</Note>

<Callout type="info" title="Versatile Use Cases">
  Perfect for **e-commerce**, **SaaS**, **education**, **travel**, **freelancing**, and more—expand your reach across global industries.
</Callout>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/payments/latest/international-payments/global-collections/overview">Global Collections API Overview</a></li>
    <li><a href="/docs/payments/international-payments/ipg/pay-native">Pay Native (DCC)</a></li>
    <li><a href="/docs/payments/international-payments/ipg/currencies-supported">Currencies Supported</a></li>
    <li><a href="/docs/payments/international-payments/ipg/paypal">PayPal</a></li>
  </ul>
</div>


# Pay in Native Currency
Source: https://www.cashfree.com/docs/payments/international-payments/ipg/pay-native

Enable your Indian business to accept international card payments with Cashfree’s Pay Native, offering real-time currency conversion in 140+ currencies.

## Accept international payments with Pay Native

Cashfree’s **Pay Native** empowers Indian merchants to take their products and services to the global stage. With our International Payment Gateway, you can accept payments from customers worldwide using international credit and debit cards (Visa, Mastercard, Amex, and more) in **140+ currencies**. Our Dynamic Currency Conversion feature, branded as **Pay Native**, lets your customers pay in their home currency with real-time exchange rates, while you receive settlements in INR—no additional integration required.

***

## How it works

Here’s how Pay Native simplifies international payments:

1. **Customer Visits Your Platform**: A user (domestic or international) browses your website or app and adds goods/services to their cart.
2. **Checkout with International Card**: They enter an international card details and click “Pay Now.”
3. **Currency Choice**: On the payment screen, they choose to pay in their home currency (e.g., USD, EUR) or INR, with real-time conversion rates displayed.
4. **Payment Completion**:
   * If they pick their home currency, our banking partner’s conversion markup is added, and they’re charged the exact amount shown (e.g., USD 104).
   * If they choose INR, their card issuer converts it, potentially adding a separate forex fee.
5. **Authentication**: The user completes 2-factor authentication (if required by the issuer).
6. **Settlement**: You receive the order amount in INR as per your settlement schedule, with no currency risk.

<Callout type="info" title="Real-Time Exchange Rates">
  Exchange rates are updated every 15 mins by our banking partners, ensuring accuracy at checkout. Rates may vary slightly for future transactions.
</Callout>

***

## Key benefits

<CardGroup>
  <Card title="Boost Conversions" icon="arrow-up">
    Transparent pricing in customers’ home currencies reduces cart abandonment and builds trust.
  </Card>

  <Card title="140+ Currencies Accepted" icon="globe">
    Accept payments in USD, EUR, GBP, JPY, AED, and more — cater to a global audience effortlessly.
  </Card>

  <Card title="No Integration Hassle" icon="plug">
    Pay Native works out of the box—no API changes needed.
  </Card>
</CardGroup>

***

### Sample transaction

* **Order Amount**: INR 8500
* **Customer Currency**: USD
* **Exchange Rate**: 1 USD = 85.00 INR
* **Displayed Amount**: USD 101 (includes banking partner’s markup)
* **Settled to You**: INR 8500

<Callout type="success" title="No Hidden Fees for Merchants">
  Currency conversion markups are borne by the customer. You receive the full INR amount you set, hassle-free.
</Callout>

***

## Eligibility and restrictions

* **Who Can Use It?**: Registered businesses in India with a valid website/app can enable Pay Native for international cards (domestic or foreign-issued). Contact us to check eligibility.
* **Restricted Businesses**: Certain sectors (e.g., gambling, dating, alcohol) may not qualify due to banking partner policies. Reach out for details.
* **Approval Process**: Post your request, our onboarding team will coordinate with banking partners for risk assessment and activation.
* **Restricted Regions**: Cashfree Payment Gateway access is currently restricted in the following countries: Belarus, Cuba, Iran, Sudan, Syria, Russia, Iraq, Pakistan, and Afghanistan. Customers in these regions cannot access the checkout.

***

## Supported currencies

Pay Native supports **140+ currencies**, from AED to ZWL. Check the full list for details on decimal and zero-decimal options.

<Button href="payments/international-payments/ipg/currencies-supported">View Supported Currencies</Button>

***


# Paypal for International Payments
Source: https://www.cashfree.com/docs/payments/international-payments/ipg/paypal

Accept international payments in one click via PayPal on Cashfree, the world's leading wallet payment provider, and settle funds in INR to your bank.

<img />

### Worried about paying 8-10 percent of your revenue in PayPal costs?

Introducing industry-first Forex Markup feature that allows you to offset your costs by up to 75 percent on international transactions via Paypal.

<img />

Watch below how to activate this from your merchant dashboard.

<Frame>
  <iframe title="Setting up Paypal" />
</Frame>

### Getting started

Head over to your Cashfree merchant dashboard and connect your PayPal seller account today.

For more details, see [Activating PayPal from the dashboard](/docs/payments/manage/payment-methods).


# Introduction
Source: https://www.cashfree.com/docs/payments/introduction

Discover how Cashfree helps Indian and global businesses accept payments online, on mobile, and offline through a single API and dashboard.

Cashfree automates the entire payment lifecycle from collection to settlement across web, mobile, and offline channels. The platform maximises conversions while ensuring PCI DSS compliance and regulatory adherence.

## Core payment solutions

Explore the range of payment solutions available to help you accept payments.

<CardGroup>
  <Card title="Accept payments online" href="/docs/payments/overview" icon="globe">
    Integrate a secure, pre-built checkout interface supporting 120+ payment methods.
  </Card>

  <Card title="No-code payment collection" href="/docs/payments/no-code/overview" icon="link">
    Payment links and forms that require zero coding skills to start accepting payments.
  </Card>

  <Card title="Optimise checkout experience" href="/docs/payments/checkout/one-click-checkout" icon="chart-line">
    One-click checkout with instant OTP verification and smart address pre-filling.
  </Card>

  <Card title="Automate recurring payments" href="/docs/payments/subscription/introduction" icon="calendar-days">
    Collect recurring payments using cards, eNACH, UPI auto pay, and physical NACH.
  </Card>

  <Card title="Collect from global customers" href="/docs/payments/international-payments/collect-from-india/overview" icon="earth-americas">
    PA-CB-compliant solution for foreign merchants to collect from Indian customers.
  </Card>

  <Card title="Split payments automatically" href="/docs/payments/split/overview" icon="share-from-square">
    Automate payment distribution between you and your vendors with detailed reporting.
  </Card>

  <Card title="Accept payments in-person" href="/docs/payments/softpos/introduction" icon="mobile">
    Android application for digital payments using QR codes, cards, and 100+ payment options.
  </Card>

  <Card title="Prevent fraudulent transactions" href="/docs/payments/risk-shield/overview" icon="shield-check">
    AI-powered fraud detection to reduce financial losses and payment disputes.
  </Card>

  <Card title="Manage multiple gateways" href="/docs/payments/flowwise/overview" icon="route">
    Payment management system to use multiple payment gateways efficiently.
  </Card>
</CardGroup>

## Key benefits

Cashfree provides the following benefits to help you grow your business:

* **Universal acceptance**: Support for all major Indian and international payment methods including UPI, cards, net banking, and wallets.
* **Developer-friendly**: Easy-to-integrate APIs, SDKs, and comprehensive no-code solutions.
* **Maximum uptime**: Industry-leading reliability with intelligent fail-over and backup payment methods.
* **Advanced security**: PCI DSS-compliant infrastructure with real-time fraud monitoring.
* **Real-time insights**: Comprehensive analytics, reporting, and reconciliation tools.
* **Global reach**: Accept payments worldwide while maintaining local compliance.

## Getting started

Use the following resources to begin your integration with Cashfree:

<CardGroup>
  <Card title="Start with web payments" href="/docs/payments/online/web/redirect" icon="rocket">
    Integrate secure hosted checkout with 120+ payment methods
  </Card>

  <Card title="Payment Gateway API" href="/docs/api-reference/payments/overview" icon="code">
    Explore comprehensive API documentation and integration examples
  </Card>

  <Card title="Test in Sandbox" href="/docs/payments/online/resources/sandbox-environment" icon="flask">
    Test your integration with supported payment modes before going live
  </Card>

  <Card title="Go live checklist" href="/docs/payments/online/go-live/checklist" icon="list-check">
    Verify your integration with this comprehensive pre-production checklist
  </Card>
</CardGroup>

<div>
  <p>Affiliate partner program</p>

  <p>As a developer building payment experiences for your clients, you can earn additional income while providing them with industry-leading payment solutions.</p>

  <p>Join the <a href="https://partner.cashfree.com/partner-ui/authentication/signup?source-action=Affiliate%20Program%20LP&action=Sign%20Up&button-id=StartNow_CashfreeAffiliatePartnerProgram">Cashfree affiliate partner program</a> and get rewarded every time your clients use Cashfree.</p>

  <p>**What you get:**</p>

  <ul>
    <li>Earn up to 0.25% commission on every transaction.</li>
    <li>Become a trusted fintech partner for your clients.</li>
    <li>Access to a dedicated partner manager for expert support.</li>
  </ul>

  <p>**What your clients get:**</p>

  <ul>
    <li>Instant activation and go live in minutes.</li>
    <li>Industry-best success rate across all payment modes.</li>
    <li>Effortless acceptance of international payments in 140+ currencies.</li>
  </ul>

  <p>Get started today. <a href="https://partner.cashfree.com/partner-ui/authentication/signup?source-action=Affiliate%20Program%20LP&action=Sign%20Up&button-id=StartNow_BecomeAPartner">Become a partner now</a>.</p>
</div>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/payments/latest/overview">Payment Gateway API Overview</a></li>
    <li><a href="/docs/payments/general-faqs">General FAQs</a></li>
    <li><a href="/docs/payments/quick-guide/payment">Quick Payment Guide</a></li>
    <li><a href="/docs/payments/online/resources/payment-lifecycle">Payment Lifecycle</a></li>
  </ul>
</div>


# Dashboard Actions
Source: https://www.cashfree.com/docs/payments/manage/disputes/dashboard-actions

Manage Cashfree disputes from the Merchant Dashboard by accepting, contesting, or uploading evidence, and track every action taken against each chargeback case.

You can view the disputes from the dashboard. To view a dispute from the dashboard, go to **Payment Gateway Dashboard** > **Transactions** > and go to the **Disputes** section.

There are four sections that show the various phases of the disputes.

| Section name | Description |
| :- | :- |
| Action Required | This section lists all the disputes to which you much respond. |
| Under Review | This section lists the disputes that are under review. |
| Closed | This section lists all the disputes that are closed. |
| All Disputes | This section lists all the disputes irrespective of their status. |

## Action required

The **Action Required** page lists all the disputes to which you must respond and take action. There are placards that show the disputes that are due today, tomorrow, or if the evidence submitted is insufficient.

Apart from this, you have other information such as:

* Created On
* Dispute ID
* Order ID
* Transaction ID
* Dispute Type
* Dispute Amount
* Deadline
* Take Action

<Frame>
  <img />
</Frame>

When you click a particular placard say for example "Due Today", all the disputes that are due today will be filtered and displayed. A filtered dispute is shown below for your reference.

<Frame>
  <img />
</Frame>

### Responding to a dispute (take action)

To respond to a dispute click the **Take Action** option.

<Frame>
  <img />
</Frame>

When you click the Take Action option, you will get a pop-up from which you can either

* Accept the dispute

(Or)

* Contest the dispute and submit evidence

<Frame>
  <img />
</Frame>

### Accept a dispute

You can accept a dispute if you agree with the claim submitted by customer. To accept a dispute, select the **Take Action** option. From the Take Action pop-up, select the **Accept Dispute** option. Add any remarks if needed.

<Frame>
  <img />
</Frame>

Once you click **Accept Dispute** you will get a message that you have accepted the dispute successfully along with the refund amount. The amount will be refunded to your customer.

<Frame>
  <img />
</Frame>

### Contest a dispute

You can contest the dispute if you feel the dispute was raised wrongly and if you have the required evidence.

<Note>
  When a dispute reaches the ARBITRATION stage, you cannot upload new evidence from the Merchant Dashboard. Use the [Contest Arbitration API](/docs/api-reference/payments/latest/disputes/contest-arbitration-by-dispute-id) to contest the dispute. Pre-arbitration evidence is automatically carried forward.
</Note>

To challenge a dispute,

1. Select the **Take Action** option. From the Take Action pop-up, select the \*\*Contest Dispute and Submit Evidence \*\* option.
2. Add Additional Evidence if needed and add any remarks if needed.

<Frame>
  <img />
</Frame>

3. Click on **Submit Evidence** on done uploading the required evidence. You will get a message stating that you have contested the case successfully.

<Frame>
  <img />
</Frame>

### Upload evidence

If the evidence you have submitted is insufficient, you will see the Upload Evidence option beside the dispute. Click the **Upload Evidence** option and upload the required evidence.

<Frame>
  <img />
</Frame>

Provide any additional remarks if needed. The previously uploaded proofs will be visible for your reference. Once done click **Submit Evidence**.

<Frame>
  <img />
</Frame>

You will get a message stating you have submitted the evidence successfully.

<Frame>
  <img />
</Frame>

## Under review

The Under Review section lists all the disputes that are submitted for review. A dispute can move from Under Review either to Closed or Action Required based on the decision the banks take. You can upload more evidence by clicking the **Upload More Evidence** icon.

<Frame>
  <img />
</Frame>

## Closed

The closed section gives an overview of the disputes that are closed (Disputes have won, lost, and accepted) in the form of a placard along with the date and time it was resolved and the result.

<Frame>
  <img />
</Frame>

For example, if you click the Total Disputes Won placard, all the disputes that you have won will alone be filtered and displayed.

<Frame>
  <img />
</Frame>

## All disputes

The all dispute section shows all the disputes that are raised by your customer irrespective of the dispute status. You can respond to a dispute or upload further evidence from this section.

<Frame>
  <img />
</Frame>

## Dispute details

You can view further details of a dispute from the dispute details page. Click the dispute of which you want to view the dispute details. The following options are available on this page:

* Dispute Timeline
* Dispute ID
* Dispute Details - order ID, transaction ID, transaction amount, dispute amount, payment method, dispute reason, dispute type, and deadline date.
* Take Action/ Upload Evidence
* Message Cashfree

<Frame>
  <img />
</Frame>


# Disputes Actions
Source: https://www.cashfree.com/docs/payments/manage/disputes/disputes-actions

Understand actions you can take on Cashfree disputes, including accepting chargebacks, contesting with evidence, and responding to pre-arbitration cases.

You can accept a dispute, contest it with evidence, or contest it at the arbitration stage. Review the reason for the dispute and the evidence you have before you choose an action.

## Scenario 1: Merchant accepts the dispute

Before you accept a dispute, confirm why the customer raised it. Check whether the claim is valid and whether you have enough evidence to contest it. If you do not have the evidence, accept the dispute.

If you accept the dispute, Cashfree refunds the amount to the customer's account. Accepting the dispute is sometimes the most appropriate option.

<Frame>
  <img />
</Frame>

## Scenario 2: Merchant contests the dispute

After you understand why the customer raised the dispute, you can accept it or contest it. This scenario describes the contest flow.

Review the following points before you contest a dispute:

* Collect the complete set of documents before you upload them. See the [documents required for dispute representation](/docs/payments/manage/disputes/reason-codes#general-documents-required-for-the-representation-of-disputes).
* Upload only valid documents. The issuing bank reviews every file you submit.
* Do not contest every dispute. Pre-arbitration and arbitration can attract a high penalty.
* A dispute can take about 3 months to conclude.
* If you do not respond, you lose the dispute and Cashfree refunds the customer.
* Check the dispute status regularly in the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).

<Frame>
  <img />
</Frame>

## Scenario 3: Merchant contests an arbitration dispute

When a dispute reaches the `ARBITRATION` stage, you cannot submit new evidence with the [Submit Evidence API](/docs/api-reference/payments/latest/disputes/submit-evidence-to-contest-the-dispute-by-dispute-id). Use the [Contest Arbitration API](/docs/api-reference/payments/latest/disputes/contest-arbitration-by-dispute-id) to contest the dispute.

<Warning>
  Arbitration disputes can attract a high penalty. Evaluate the case before you contest.
</Warning>

Review the following points before you contest an arbitration dispute:

* Do not upload documents. Cashfree forwards the pre-arbitration evidence you already submitted to the card network or NPCI (National Payments Corporation of India) for a final decision.
* You can optionally include a `note` with the contest request.
* After you submit the request, the dispute status changes to `ARBITRATION_CONTEST_REQUESTED`.


# Disputes APIs
Source: https://www.cashfree.com/docs/payments/manage/disputes/disputes-apis

Use Cashfree dispute APIs to list, fetch, accept, or contest disputes, including ARBITRATION cases that do not require document upload.

## List of dispute APIs

The table below lists all the dispute APIs along with their description:

| API name | Description |
| :- | :- |
| [Get Disputes by Order ID](/docs/api-reference/payments/latest/disputes/get-disputes-by-order-id) | Use this API to get all dispute details by specifying the order ID. |
| [Get Disputes by Dispute ID](/docs/api-reference/payments/latest/disputes/get-disputes-by-dispute-id) | Use this API to get dispute details by specifying the dispute ID. |
| [Get Disputes by Payment ID](/docs/api-reference/payments/latest/disputes/get-disputes-by-payment-id) | Use this API to get all dispute details by specifying the payment ID. |
| [Accept Dispute](/docs/api-reference/payments/latest/disputes/accept-dispute-by-dispute-id) | Use this API to accept a dispute by specifying the dispute ID. |
| [Contest Dispute by Submitting Evidence](/docs/api-reference/payments/latest/disputes/submit-evidence-to-contest-the-dispute-by-dispute-id) | Use this API to submit evidence to contest a dispute by specifying the dispute ID. Not applicable for ARBITRATION disputes. |
| [Contest Arbitration](/docs/api-reference/payments/latest/disputes/contest-arbitration-by-dispute-id) | Use this API to contest an ARBITRATION dispute without uploading documents. Pre-arbitration evidence is automatically carried forward to the card network or NPCI (National Payments Corporation of India). |


# Disputes FAQs
Source: https://www.cashfree.com/docs/payments/manage/disputes/disputes-faqs

Browse FAQs about Cashfree disputes and chargebacks: dispute types, response procedures, supporting documents, deadlines, and resolution timelines.

This page answers common questions about handling disputes and chargebacks, including dispute types, response procedures, documentation requirements, and deadlines.

<AccordionGroup>
  <Accordion title="What is a dispute?">
    A dispute is a situation in which there is a disagreement for a particular transaction that is initiated by your customer with the issuing bank or with Cashfree directly. Your customers can also go to cyber cells to report fraudulent transactions. Suspicious transaction disputes are often initiated directly by banks.

    As a merchant, you can either defend the dispute by providing sufficient evidence or accept the dispute if you agree with the claim. When you accept the dispute, the amount will be refunded to the customer.

    Read more on disputes in the [Disputes Overview](/docs/payments/manage/disputes/overview).
  </Accordion>

  <Accordion title="What are the various dispute types?">
    In Cashfree, disputes can be of the following types:

    * **Dispute**: End-customer complaints, fraudulent or suspicious transactions reported by law enforcement authorities and banks are raised as disputes.
    * **Retrieval**: These are soft chargebacks that occur even before we receive an actual chargeback.
    * **Chargeback**: A chargeback is a type of dispute raised on a transaction by the customer. It's a refund request that is demanded through their bank.
    * **Pre-arbitration**: This is the second level of chargeback.
    * **Arbitration**: This is the final stage of the chargeback.

    Read more on the various dispute types in [Dispute Types](/docs/payments/manage/disputes/disputes-types).
  </Accordion>

  <Accordion title="What is the flow of chargeback stages?">
    * **Retrieval**: These are soft chargebacks that occur even before an actual chargeback is received. They are raised when your customer raises a query with their issuing bank on the transaction.
    * **Chargeback**: If your customer feels that the transaction was not done by them, they can raise a chargeback on top of the retrieval request. Chargebacks can be raised directly without going through the retrieval state.
    * **Pre-arbitration**: The second level of chargeback. Your customer has a limited period of time within which they should respond on whether they are disputing the transaction further or not after reviewing the documents shared by you at the chargeback level.
    * **Arbitration**: The final stage of the chargeback. Your customer has a limited period of time within which they should respond on whether they are disputing the transaction further or not after reviewing the documents shared by you at the pre-arbitration stage. Both parties submit their documents, and the card networks or NPCI takes the final decision on the dispute, depending on the payment mode.
  </Accordion>

  <Accordion title="What are the different dispute states?">
    In Cashfree, disputes can be in the following states:

    * **Action Required**: This indicates that the dispute has been created, and action needs to be taken from your end. If the evidence submitted by you is found insufficient, the disputes will be visible under the Action Required section.
    * **Under Review**: This indicates that you have submitted the documents, and Cashfree has forwarded your documents to the concerned authorities.
    * **Closed (Merchant Won)**: This indicates that the authorities or customer accepts the documents, and you win the dispute.
    * **Closed (Merchant Lost)**: This status indicates that the proofs submitted are rejected by the concerned authorities or customer, and you have lost the dispute.
    * **Merchant Accepted**: This status indicates you have accepted the dispute raised by your customer.

    Read more on the various dispute states in [Dispute States](/docs/payments/manage/disputes/disputes-states).

    <Note>
      Your customer can raise a pre-arbitration or an arbitration, even for a chargeback (first-level) that is closed as Merchant Won.
    </Note>
  </Accordion>

  <Accordion title="How do disputes affect your business, and why is it important to resolve them?">
    Disputes can hurt your business as they damage your reputation, cost you money, and disrupt your operations.

    A high number of disputes often indicates that your customers are not satisfied and something needs to be improved in your business's operations, products, or services. It can also lead to card networks labelling your business as high-risk and holding remittances for your business.
  </Accordion>

  <Accordion title="What is meant by dispute reason?">
    Dispute reason helps you identify and categorise all the various disputes. Customers can raise disputes for various reasons, some of which are:

    * If you deliver a poor-quality product and it does not meet the expectation
    * If you have delivered the wrong product
    * If you levy extra charges for your services
    * If you haven't delivered the product
    * Billing errors
    * If it's a fraudulent transaction (unauthorised transaction)

    Read more on dispute reasons in [Reason Codes](/docs/payments/manage/disputes/reason-codes).
  </Accordion>

  <Accordion title="How will I be notified if my customer has raised a dispute?">
    You will be notified about disputes through emails or webhooks. Read more about notifications in [Dispute Notifications](/docs/payments/manage/disputes/disputes-notifications).
  </Accordion>

  <Accordion title="What should I do when my customer initiates a dispute?">
    There are two actions that you can take when a dispute is raised:

    * Accept the dispute if you agree with the dispute claim, and the amount will be refunded to the customer.
    * Challenge the dispute with the required documents.

    The dispute will be ruled in favour of the customer if you don't respond to the dispute.
  </Accordion>

  <Accordion title="How do I upload the documents for contesting a case, and what are the documents required?">
    All the disputes where action needs to be taken can be found on the Disputes page under the **Action Required** tab.

    1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
    2. Go to **Payment Gateway > Transactions > Disputes > Action Required > Take Action > Upload Documents**.

    **Documents required:**

    | Document name | Description |
    | :- | :- |
    | Delivery or Service Proof | Proof that the cardholder or customer did, in fact, receive the goods or services, such as a signed delivery confirmation. |
    | Shipping Proof | Proof that the address was validated via authorisation and goods were shipped to that address. |
    | Statement of Service | Account statement of wallet where funds were loaded by customer. |
    | Proof of Service Used | Customer acknowledgement of services used in case of a recurring transaction. |
    | Cancellation of Service Proof | Document to support that you were able to provide the merchandise or service and that the cardholder or customer cancelled prior to the delivery date. |
    | Refund Proof | Refund details to the customer if done via any other mode. |
    | Business model explanation | Generic letter elaborating how the merchant's business operates once a payment is made by the customer. |
    | Extra Charges Declaration | Terms and conditions stating that the customer would be held accountable for extra charges. |
    | Terms and Conditions | Terms and conditions elaborating refund or cancellation policies of the merchant. |
    | Customer Withdrawal Letter | Proof stating that the cardholder or customer no longer disputes the transaction, or the issue was resolved with the customer. |
    | Certificate of Authenticity | Original purchase receipts issued by the manufacturer that show the products you have sold are genuine. |
    | Reseller Agreement | A legal document that authorises you to sell the manufacturer's products. |
  </Accordion>

  <Accordion title="Why am I debited for a dispute? When will I get the amount back?">
    Whenever a dispute is created, Cashfree debits merchants with the disputed amount, as banks debit Cashfree on behalf of the merchant to provide provisional credit to the customer. You will get the amount back depending on the dispute result. If the dispute is closed in your favour, the amount will be returned. Otherwise, it will be credited to your customer.
  </Accordion>

  <Accordion title="When do multiple disputes occur on the same transaction?">
    Multiple disputes occur when there are partial disputes created on a transaction. For example, if the transaction amount was Rs. 100, and the customer has raised a dispute for Rs. 30 initially for a product, the remaining amount of Rs. 70 would be eligible for creating disputes later at some point in time.
  </Accordion>

  <Accordion title="What are the deadlines for various disputes?">
    The following are the representation deadlines given to merchants depending on the type of dispute:

    | Dispute type | Deadline |
    | :- | :- |
    | Disputes | 3 calendar days. In some special cases, for real-time fraudulent transaction disputes, a 1-day deadline is given. |
    | Retrieval | 3 calendar days |
    | Chargeback | 3 calendar days |
    | Pre-arbitration | 2 calendar days |
    | Arbitration | 1 calendar day |
  </Accordion>
</AccordionGroup>


# Disputes Notifications
Source: https://www.cashfree.com/docs/payments/manage/disputes/disputes-notifications

Get email and webhook notifications for Cashfree disputes whenever a new case is created, evidence is requested, a deadline nears, or a verdict lands.

When your customer files a dispute against a payment, the issuing bank informs us of the dispute and we notify you through Email Notifications or [Webhooks](/docs/api-reference/payments/latest/disputes/dispute-webhooks).

## Email notifications

Email notifications can be configured from the [Merchant Dashboard](https://merchant.cashfree.com/merchants). Emails on which the merchant wants to receive these notifications can be configured from the [Merchant Dashboard](https://merchant.cashfree.com/merchants) by following the below steps:

Go to **Payment Gateway Dashboard** > **Settings** > **Email Notifications** > **Dispute Emails**.

<Frame>
  <img />
</Frame>

We notify you through email in the following scenarios:

| Scenarios | Description |
| :- | :- |
| Dispute created | You will be notified when there is a new dispute that your customer raises. |
| Dispute phase/type change | You will be notified when there is a change in the dispute phase (Pre-arbitration, Arbitration). |
| States change | You will be notified when there is a change in the dispute state, for example, Action Required -> Under Review. |
| Comment updated | You will be notified when there is a comment updated. |
| Reminder email | You will be notified when the dispute has reached the deadline day. |

***

## Webhooks

Dispute webhooks can be configured to receive automated notifications when disputes are created, updated and closed.

To add a new webhook,

1. Go to **Payment Gateway Dashboard** > **Developers** or click the **Developers** option from the homepage.
2. The following events apply to dispute webhooks:
   * dispute created
   * dispute closed
   * dispute updated
3. Click **Add Webhook Endpoint** to create a new webhook. Enter the **endpoint URL** and select the **webhook version** using the drop-down menu. The available API versions are 2021-09-21, 2022-09-01. Click on **Test** to verify if the webhook endpoint returns a response. Once done, click **Next**.
4. Select the respective event and click **Add Webhook**.

<Frame>
  <img />
</Frame>

6. The webhook is added successfully. You can test the webhook and edit it from the webhook homepage.

### Test webhook endpoint

You can test the URL at any time using the Test option. Click the **Test** option in the Test Webhook Endpoint pop-up. Click **Done** once you get a successful response.

<Frame>
  <img />
</Frame>

### Edit webhook endpoint

You also have the option of editing a webhook. Click the **Edit** option on the webhook that is to be edited and select the events you want to add/remove to the webhook. Once done click **Save**.

<Frame>
  <img />
</Frame>

Read more about the [different types of dispute webhooks](/docs/api-reference/payments/latest/disputes/dispute-webhooks), along with their sample payloads.


# Dispute Process Flow
Source: https://www.cashfree.com/docs/payments/manage/disputes/disputes-process-flow

Walk through the Cashfree dispute process flow from chargeback creation to representment, pre-arbitration, and final resolution, with deadlines for each stage.

## Parties involved

There are several parties involved in a dispute. They are mentioned in the table below:

| Parties involved | Description |
| :- | :- |
| Customer | The person who has availed your service and raised the dispute. |
| You (merchant) | The party whose goods or services are disputed. |
| Issuing Bank | The bank that issued the card to the customer. |
| Acquiring Bank | The bank that is tasked with acquiring the payment on your behalf. |
| Card Scheme | The card networks(Visa, Mastercard, Rupay, etc) and NPCI. |
| Payment Gateway | Cashfree is the payment gateway that manages your transaction. |

## Dispute lifecycle

<Frame>
  <img />
</Frame>

<Warning>In the final stage of chargeback i.e arbitration the decision is taken by the card networks or NPCI considering the evidence submitted by both the parties (customer and merchant).</Warning>

### Stage 1: Dispute received

The first stage in the dispute process is that the customer raises the dispute and you are informed of the dispute. The customer visits your website, searches for the required goods and pays for the product. The customer has an issue with the product and approaches their card issuer and files a dispute. The card issuer now gets in touch with the issuing bank (acquirer) and informs of the dispute.

The issuing bank contacts Cashfree and informs us of the dispute. We then gather the required information and notify you about the dispute along with the reason provided by your customer. You receive a turnaround time and in the case of a chargeback, the verdict lies with the issuer bank.

### Stage 2: Responding to the dispute

After you receive the dispute, you can choose from the following options:

* **Accept the dispute**: If you find your customer's reason valid, you can accept the dispute and the amount will be refunded automatically to the customer's account. This is sometimes the most appropriate option. The dispute is closed in the customer's favour and the status is marked as closed (merchant accepted). For more information, review [accepting a dispute](/docs/payments/manage/disputes/disputes-actions#scenario-1-merchant-accepts-the-dispute).
* **Contest the dispute**: If you feel that the customer has initiated a dispute wrongly, you can challenge the dispute. Ensure that you have the required documents before you contest the dispute. For more information, review [contesting a dispute](/docs/payments/manage/disputes/disputes-actions#scenario-2-merchant-contests-the-dispute).
* **Contest an ARBITRATION dispute**: When the dispute reaches the ARBITRATION stage, you cannot upload new evidence. For more information, review [contesting an ARBITRATION dispute](/docs/payments/manage/disputes/disputes-actions#scenario-3-merchant-contests-an-arbitration-dispute).

### Stage 3: Issuing bank gives verdict

After submitting proof, the issuing bank reviews the documents you have shared with the customer. Your customer can revert back if they want to raise any further action. Post this the issuing bank makes a decision on the dispute.

**Possible outcomes:**

* **Dispute won**: The dispute is closed in your favour and the status is marked as closed(merchant won).
* **Dispute lost**: The dispute is closed in your customer's favour and the status is marked as closed(merchant lost). The amount is refunded to your customer.


# Disputes States
Source: https://www.cashfree.com/docs/payments/manage/disputes/disputes-states

Track every Cashfree dispute through its lifecycle states, from creation to representment and final resolution, with descriptions of each chargeback stage.

After a dispute is created, it moves through several states until it is resolved. The state changes when you, the customer, or the issuing authority take a decision.

## Dispute states

The following table describes each dispute state:

| Dispute state | Description |
| - | - |
| Action Required | The dispute is open and you must act. Accept the dispute, contest it, or upload documents again if the evidence is insufficient. |
| Under Review | You submitted documents and Cashfree forwarded them to the authority that takes the final decision. |
| Contest Requested | You contested an `ARBITRATION` dispute with the [Contest Arbitration API](/docs/api-reference/payments/latest/disputes/contest-arbitration-by-dispute-id). Cashfree forwards your existing pre-arbitration evidence to the card network or NPCI (National Payments Corporation of India) for a final decision. |
| Closed (Merchant Won) | The authority or the customer accepts your documents. You win the dispute and the case is closed. |
| Closed (Merchant Lost) | The authority or the customer rejects your evidence. You lose the dispute. |
| Closed (Merchant Accepted) | You accept the dispute. Cashfree refunds the customer from your balance. |

<Warning>A customer can raise a pre-arbitration or arbitration case even after the dispute is Closed (Merchant Won).</Warning>

### Dispute states workflow

The following diagram shows how a dispute moves between states:

<Frame>
  <img />
</Frame>

<Note>
  When you contest an `ARBITRATION` dispute, the state changes from Action Required to Contest Requested, then to Under Review.
</Note>

<Warning>If you do not respond before the deadline, you lose the dispute and Cashfree refunds the customer.</Warning>


# Disputes Types
Source: https://www.cashfree.com/docs/payments/manage/disputes/disputes-types

Understand the different chargeback and dispute types in Cashfree, with representment timelines, resolution timelines, and outcomes for each category.

## Types of disputes in Cashfree

| Chargeback states | Description | Representation time | Resolution time |
| - | - | - | - |
| Dispute | End-customer complaints, fraudulent or suspicious transactions reported by law enforcement authorities and banks are raised as disputes. | 3 calendar days  \nIn some special cases, real-time fraudulent transaction disputes take 1 day. | Disputes will typically take 5-7 business days in case of end-customer complaints. Fraud and suspicious transaction disputes may take months to get resolved since funds are held by banks in some cases. Wallet and Netbanking disputes typically take around 30 days to reach a resolution. |
| Retrieval | These are soft chargebacks that occur even before we receive an actual chargeback. They are raised when your customer raises a query with their issuing bank on the transaction. | 3 calendar days | If the retrieval is contested, there is a waiting period of 30-45 days for the customer to raise further Chargeback. If the retrieval is accepted it will take around 10 days. |
| Chargeback | If the customer feels the services were not delivered, or if they have any issue with the transaction, they can raise a Chargeback after the retrieval request. | 3 calendar days | If the dispute is contested, the Chargeback typically takes 30-45 days and there is a waiting period for the customer to raise further pre-arbitration depending on the network. UPI cases typically take 15-20 days. |
| Pre-arbitration | The second level of chargeback. Your customer has a limited period of time within which they should revert back on whether they are further disputing the transaction. If your customers are satisfied with the proofs/evidence submitted by you on the first level the dispute is closed, else we receive a pre-arbitration request. | 2 calendar days | If the dispute is contested, Pre-arbitration typically takes 30-45 days. There is a waiting period for customers to raise further Arbitration depending on the network. UPI cases typically take 15-20 days. |
| Arbitration | The final stage of the chargeback. Both parties submit their documents and the card networks or NPCI takes the final decision on the dispute depending on the payment mode.  \nIf the chargeback reaches this stage, it can become costly for you as there is a hefty fee involved for the losing party. This stage can also take a long time to arrive at a conclusion. | 1 calendar day | It takes around 15 days for the final verdict for both UPI and cards. |


# Overview
Source: https://www.cashfree.com/docs/payments/manage/disputes/overview

Manage Cashfree disputes and chargebacks end-to-end from the Merchant Dashboard, with notifications, evidence uploads, APIs, and reporting for each case.

A dispute arises when a customer disagrees with a transaction and raises it with either their bank or Cashfree. Customers may also report fraudulent transactions to cybercells, and banks often initiate disputes over suspicious transactions directly. We will notify you over email whenever a new dispute is created, changes state or there is a new update from Cashfree.

To get real-time notifications for a dispute raised by a customer, configure your email on the dashboard:

1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
2. Go to **Payment Gateway Dashboard > Settings > Notifications > Merchant Notifications > Dispute Emails** and click the **Add Recipient** button to add the email addresses that should receive dispute notifications then select the **Disputes** email category and click **Submit**.

<Tip>Install [Cashfree Agent Skills](/docs/tools-ai/cashfree-agent-skills) to bring Cashfree product knowledge into your AI coding assistant (Claude Code, Cursor, VS Code Copilot, Gemini CLI, and more) to answer integration questions and generate accurate code without leaving your editor.</Tip>

## Chargeback types

| State | Description | Response time | Resolution time |
| - | - | - | - |
| Dispute | Initial complaints from customers or fraud alerts from banks/authorities | 3 days (1 day for fraud cases) | • Customer complaints: 5-7 business days<br />• Fraud cases: Up to several months<br />• Wallet/Netbanking: \~30 days |
| Retrieval | Preliminary query raised by customer with their bank | 3 days | • If contested: 30-45 days waiting period<br />• If accepted: \~10 days |
| Chargeback | Customer formally disputes transaction after retrieval | 3 days | • Cards: 30-45 days<br />• UPI: 15-20 days |
| Pre-arbitration | Second level dispute if customer disagrees with evidence | 2 days | • Cards: 30-45 days<br />• UPI: 15-20 days |
| Arbitration | Final stage where card networks/NPCI makes decision | 1 day | \~15 days for final verdict |

<Warning>
  * Your customer can raise a pre-arbitration or an arbitration even for a dispute that is Closed (Merchant Won).
  * Response Time: Maximum days allowed to respond to the dispute
  * Resolution Time: Typical time taken to reach a final decision
  * Arbitration involves additional fees for the losing party
  * Timelines may vary based on payment method and case complexity
</Warning>

## Chargeback process states

<Frame>
  <img />

  <img />
</Frame>

## Manage chargebacks

Learn in detail about the various scenarios involved in disputes.

<AccordionGroup>
  <Accordion title="Scenario 1: You accept the dispute">
    If you accept a dispute and agree that the customer raised a valid dispute, Cashfree refunds the amount to the customer's account. This is sometimes the most appropriate option.
  </Accordion>

  <Accordion title="Scenario 2: You contest the dispute">
    Keep the following points in mind before you decide to contest the dispute:

    Have the complete set of documents available before you upload them. Learn more about the [documents required during the upload process](/docs/payments/manage/disputes/disputes-process-flow).
    The issuing bank reviews all documents, so ensure you upload valid documents.
    It is not necessary to contest every dispute. In some cases like pre-arbitration and arbitration, there is a high penalty involved.
    The entire dispute may take around 3 months to conclude.
    If you do not respond, you lose the dispute and Cashfree refunds the customer.
  </Accordion>

  <Accordion title="Scenario 3: You contest an ARBITRATION dispute">
    When a dispute reaches the ARBITRATION stage, you cannot upload new evidence. Use the [Contest Arbitration API](/docs/api-reference/payments/latest/disputes/contest-arbitration-by-dispute-id) to contest the dispute. Pre-arbitration evidence is automatically carried forward. For more information, review [contesting an ARBITRATION dispute](/docs/payments/manage/disputes/disputes-actions#scenario-3-merchant-contests-an-arbitration-dispute).
  </Accordion>
</AccordionGroup>

## Webhooks

You can subscribe to the following asynchronous webhook events for disputes. Read more about [dispute webhooks](/docs/api-reference/payments/latest/disputes/dispute-webhooks).

* `DISPUTE_CREATED`
* `DISPUTE_UPDATED`
* `DISPUTE_CLOSED`

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/payments/latest/disputes/get-disputes-by-order-id">Get Disputes by Order ID API</a></li>
    <li><a href="/docs/api-reference/payments/latest/disputes/contest-arbitration-by-dispute-id">Contest Arbitration API</a></li>
    <li><a href="/docs/payments/manage/disputes/disputes-faqs">FAQs</a></li>
  </ul>
</div>


# Reason Codes and Documents
Source: https://www.cashfree.com/docs/payments/manage/disputes/reason-codes

Refer to Cashfree dispute reason codes and required documents for representment so you can respond to each chargeback with the correct evidence, on time.

## General documents required for the representation of disputes

| Document name | Description |
| :- | :- |
| Delivery or service proof | Proof that the cardholder or customer did, in fact, receive the goods or services, such as a signed delivery confirmation. |
| Shipping proof | Proof that the address was validated via authorisation and that the goods were shipped to that address. |
| Statement of service | Account statement of the wallet where funds were loaded by the customer. |
| Proof of service used | Customer acknowledgement of services used in case of a recurring transaction. |
| Cancellation of service proof | Document to support that you were able to provide merchandise or service and that the cardholder or customer cancelled before the delivery date. |
| Refund proof | Refund details to the customer if done via any other mode. |
| Business model explanation | Generic letter elaborating how your business operates once a payment is made by the customer. |
| Extra Charges Declaration | Terms and conditions stating the customer would be held accountable for extra charges. |
| Terms & Conditions | Terms and conditions elaborating your refund or cancellation policies. |
| Customer Withdrawal Letter | Proof stating that the cardholder or customer no longer disputes the transaction, or the issue was resolved with the customer. |
| Certificate of Authenticity | Original purchase receipts issued by the manufacturer that show the products you've sold are genuine. |
| Reseller Agreement | A legal document that authorises you to sell the manufacturer's products. |

## Dispute reason codes and their categories

### VISA reason codes

| Reason code | Description | External category |
| :- | :- | :- |
| 10.1 | EMV Liability Shift Counterfeit Fraud | Fraud |
| 10.2 | EMV Liability Shift Non-Counterfeit Fraud | Fraud |
| 10.3 | Other Fraud: Card-Present Environment | Fraud |
| 10.4 | Other Fraud: Card-Absent Environment | Fraud |
| 10.5 | Visa Fraud Monitoring Program | Fraud |
| 11.1 | Card Recovery Bulletin | Authorisation |
| 11.2 | Declined Authorisation | Authorisation |
| 11.3 | No Authorisation | Authorisation |
| 12.1 | Late Presentment | Processing errors |
| 12.2 | Incorrect Transaction Code | Processing errors |
| 12.3 | Incorrect Currency | Processing errors |
| 12.4 | Incorrect Account Number | Processing errors |
| 12.5 | Incorrect Amount | Processing errors |
| 12.6 | Duplicate Processing/Paid by Other Means | Processing errors |
| 12.7 | Invalid Data | Processing errors |
| 13.1 | Merchandise / Services Not Received | Consumer disputes |
| 13.2 | Cancelled Recurring Transaction | Consumer disputes |
| 13.3 | Not as Described or Defective Merchandise / Services | Consumer disputes |
| 13.4 | Counterfeit Merchandise | Consumer disputes |
| 13.5 | Misrepresentation | Consumer disputes |
| 13.6 | Credit Not Processed | Consumer disputes |
| 13.7 | Cancelled Merchandise / Services | Consumer disputes |
| 13.8 | Original Credit Transaction Not Accepted | Consumer disputes |
| 13.9 | Non-Receipt of Cash or Load Transaction Value | Consumer disputes |

### MASTERCARD reason codes

| Reason code | Description | External category |
| :- | :- | :- |
| 4808 | Authorisation related chargeback | Authorisation |
| 4834 | Point of interaction error | Point of interaction error |
| 4837 | No Cardholder Authorisation | No cardholder authorisation or fraud |
| 4840 | Fraudulent processing of transactions | No cardholder authorisation or fraud |
| 4849 | Questionable merchant activity | No cardholder authorisation or fraud |
| 4850 | Instalment billing dispute | Instalment billing dispute |
| 4853 | Cardholder disputes | Cardholder disputes |
| 4854 | Cardholder dispute not classified elsewhere (US) | Cardholder dispute not classified elsewhere |
| 4855 | Goods or services not provided | Cardholder disputes |
| 4860 | Credit not processed | Cardholder disputes |
| 4870 | Chip liability shift | No cardholder authorisation or fraud |
| 4871 | Chip or PIN Liability Shift-Lost or Stolen or Never Received Issue (NRI) fraud | No cardholder authorisation or fraud |

### AMEX reason codes

| Reason Code | Description | External category |
| :- | :- | :- |
| 4507 | Incorrect charge amount or currency discrepancy | Processing errors |
| 4512 | Duplicate charge | Processing errors |
| 4513 | Credit not processed or no show | Cardmember dispute |
| 4516 | No reply | Inquiry or miscellaneous R03 |
| 4521 | Charge amount exceeds authorisation amount or no valid authorisation | Insufficient reply |
| 4523 | Unassigned card number | Authorisation |
| 4533 | Goods or services not as described or damaged or defective | Processing errors |
| 4534 | Missing signature | Cardmember dispute |
| 4536 | Late submission | Fraud |
| 4540 | Card not present | Processing errors |
| 4544 | Cancelled recurring billing | Fraud |
| 4554 | Goods or services not received or only partially received C14 paid by other means | Cardmember dispute |
| 4750 | Vehicle rental - capital damages | Cardmember dispute |
| 4752 | Credit processed as charge | Processing errors |
| 4755 | No cardmember authorisation | Fraud |
| 4763 | Fraud full recourse program | Fraud |
| 4798 | EMV counterfeit | Fraud |
| 4799 | EMV list, stolen or non-received | Fraud |

### DINERS reason codes

| Reason Code | Description | External category |
| :- | :- | :- |
| A02 | Authorisation processing errors | Processing errors |
| A06 | Unissued account number | Authorisation |
| B24 | Late presentation | Processing errors |
| B25 | Duplicate charge | Processing errors |
| B26 | Alternate settlement currency incorrect exchange rates | Processing errors |
| B27 | Incorrect currency | Processing errors |
| C41 | Fraud - Card present transaction | Fraud |
| C42 | Fraud - Card not present transaction | Fraud |
| C46 | Multiple charges at service establishment fraudulent transaction | Fraud |
| C53 | Fraud – chip card counterfeit transaction | Fraud |
| C54 | Fraud – lost or stolen chip and PIN card transaction | Fraud |
| D61 | Altered amount | Processing errors |
| D62 | Non-receipt of goods or services | Consumer disputes |
| D66 | Credit not processed | Consumer disputes |
| D67 | Cardmember paid by other means | Processing errors |
| D69 | Cancelled recurring transactions | Consumer disputes |
| D70 | Cardmember does not recognise | Consumer disputes |

### DISCOVER reason codes

| Reason Code | Description | External category |
| :- | :- | :- |
| 4534 | Duplicate Processing | Processing error |
| 4541 | Recurring Payment | Consumer disputes |
| 4542 | Late Presentation | Processing error |
| 4550 | Credit/ Debit Posted Incorrectly | Processing error |
| 4553 | Cardholder Disputes Quality of Goods or Services | Consumer disputes |
| 4586 | Altered Amount | Processing error |
| 4865 | Paid by Other Means | Processing error |
| 4752 | Does not Recognise | Consumer eisputes |
| 4753 | Invalid Cardholder Number | Authorisation |
| 4755 | Non-Receipt of Goods or Services | Fraud |
| 4866 | Fraud Chip Card Counterfeit Transaction | Fraud |
| 4867 | Fraud Chip Card and PIN Transaction | Fraud |
| 7010 | Fraud Card Present Transaction | Fraud |
| 7030 | Fraud Card Not Present Transaction | Fraud |
| 8002 | Credit Not Processed | Consumer disputes |

### RUPAY reason codes

| Reason code | Description | External category |
| :- | :- | :- |
| 108 | The remitter account is debited, but the beneficiary account was not credited | Chargeback Raise |
| 109 | The remitter bank customer still disputes that the beneficiary account is not credited | Pre-arbitration Raise |
| 121 | TCC has been raised, but the customer is still complaining that the Beneficiary account is not credited | Deferred Chargeback Raise |
| 128 | Chargeback on Fraudulent Transaction | Fraud Chargeback Raise |
| 1061 | Credit not processed for cancelled or returned goods and services | Chargeback Raise |
| 1062 | Goods and Services not as described or defective | Chargeback Raise |
| 1063 | Paid by alternate means | Chargeback Raise |
| 1064 | Goods or Services Not Provided / Not Received | Chargeback Raise |
| 1065 | Account debited but transaction confirmation not received at the merchant location | Chargeback Raise |
| 1081 | Transaction not steeled within the specified timeframes | Chargeback Raise |
| 1084 | Duplicate /Multiple Transaction | Chargeback Raise |
| 1085 | Cardholder was charged more than the transaction amount | Chargeback Raise |
| 1097 | The customer is still claiming that services are not delivered | Pre-arbitration Raise |

### UPI reason codes

| Reason code | Description | External category |
| :- | :- | :- |
| 1061 | Credit not processed for cancelled or returned goods and services | Chargeback Raise |
| 1062 | Goods and Services not as described or defective | Chargeback Raise |
| 1063 | Paid by alternate means | Chargeback Raise |
| 1064 | Goods or Services Not Provided / Not Received | Chargeback Raise |
| 1065 | Account debited but transaction confirmation not received at the merchant location | Chargeback Raise |
| 1081 | Transaction not steeled within the specified timeframes | Chargeback Raise |
| 1084 | Duplicate /Multiple Transaction | Chargeback Raise |
| 1085 | Cardholder was charged more than the transaction amount | Chargeback Raise |
| 1097 | The customer is still claiming that services are not delivered | Pre-arbitration Raise |

### Cashfree internal reason codes

| Reason code | Description | External category |
| :- | :- | :- |
| 1401 | Fraud Transaction | Fraud |
| 1402 | Duplicate Processing | Processing Error |
| 1403 | Services Not Rendered | Customer Dispute |
| 1404 | End Customer Escalation | Customer Dispute |
| 1405 | Suspicious Transaction | Fraud |


# Downtimes
Source: https://www.cashfree.com/docs/payments/manage/downtimes

Monitor Cashfree downtimes for cards, UPI, netbanking, and wallets in real time, then route or notify customers to maintain payment conversion during incidents.

## What are downtimes?

Downtimes are periods when specific payment methods or banking services experience issues that can affect transaction success rates. Downtimes can be:

* **Scheduled downtime**: Planned outages announced by banks or payment processors.
* **Unscheduled downtime**: Unexpected technical issues affecting payment services.

### Why downtimes matter

Payment downtimes directly affect your business:

* **Protect conversion rates**: Proactively manage payment options to maintain successful transactions.
* **Improve customer experience**: Prevent failed transactions and reduce customer frustration.
* **Optimise revenue**: Redirect transactions to working payment methods during outages.
* **Increase operational efficiency**: Reduce support tickets from failed payment attempts.

<Note>
  Businesses that use downtime intelligence can see up to a **5%–15% improvement** in conversion rates during payment ecosystem issues.
</Note>

## Get started

You can stay informed about downtimes in three ways and integrate this information into your payment flow.

### 1. Use the API

Use the Downtimes API to programmatically fetch active incidents and integrate downtime information directly into your checkout.

<Card title="Fetch active downtimes" icon="code" href="/docs/api-reference/payments/latest/downtime/fetch-all-downtimes">
  Get all active and upcoming downtime incidents across the payment ecosystem.
</Card>

<Card title="Fetch downtime by ID" icon="code" href="/docs/api-reference/payments/latest/utilities/incidents/fetch-downtime-by-id">
  Get details about a specific incident using its unique ID.
</Card>

The API supports filters for impact type, payment method, status, time, and more.

### 2. Use webhooks

Subscribe to real-time downtime notifications to get instant updates when incidents are created, updated, or resolved.

<Card title="Downtime webhook documentation" icon="webhook" href="/docs/api-reference/payments/latest/utilities/incidents/incident-webhook">
  Learn how to set up downtime webhooks for real-time updates.
</Card>

### 3. Use dashboard monitoring

Monitor downtimes directly in your Cashfree dashboard.

Log in to the [**Merchant Dashboard**](https://merchant.cashfree.com/auth/login) and go to **Payment Gateway > Downtimes**. You can also monitor the Cashfree status page at [statuspage.cashfree.com](https://statuspage.cashfree.com/).

<Frame>
  <img />
</Frame>

The dashboard helps you:

* **Check real-time status**: See all active and upcoming incidents.
* **Assess impact**: Understand severity levels and affected payment methods.
* **Review history**: Track past incidents and their durations.

You can also monitor payment service status at [statuspage.cashfree.com](https://statuspage.cashfree.com).

## Best practices

Follow these strategies based on downtime severity to maintain optimal conversion rates.

### Low and medium impact incidents

**Recommended action**: Use visual cues and offer alternatives.

For incidents with manageable impact:

* **Show visual indicators**: Use subtle cues like reduced opacity or warning icons.
* **Add messages**: Display banners to inform users about possible issues.
* **Reorder methods**: Prioritise unaffected payment methods.
* **Offer alternatives**: Suggest other payment methods as the first choice.
* **Use progressive disclosure**: Show more prominent warnings for medium impact incidents while keeping the method active.

### High impact incidents

**Recommended action**: Temporarily disable affected methods.

For severe issues that strongly affect success rates:

* **Disable temporarily**: Turn off severely impacted payment methods to avoid failed payments.
* **Communicate clearly**: Inform customers about the temporary unavailability.
* **Highlight alternatives**: Show working payment methods first.
* **Guide users**: Direct users to reliable payment methods with clear calls to action.

## Related resources

<CardGroup>
  <Card title="Downtimes API reference" icon="code" href="/docs/api-reference/payments/latest/downtime/fetch-all-downtimes">
    View the complete API documentation with examples.
  </Card>

  <Card title="Downtime webhooks guide" icon="webhook" href="/docs/api-reference/payments/latest/utilities/incidents/incident-webhook">
    Learn how to set up real-time notifications for your system.
  </Card>
</CardGroup>

<snippet>snippets/related-topics-loader.mdx</snippet>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/payments/latest/downtime/fetch-all-downtimes">Fetch Active Downtimes API</a></li>
    <li><a href="/docs/api-reference/payments/latest/utilities/incidents/fetch-downtime-by-id">Fetch Downtime by ID API</a></li>
    <li><a href="/docs/api-reference/payments/latest/utilities/incidents/incident-webhook">Downtime Webhook</a></li>
  </ul>
</div>


# Monitoring and Observability
Source: https://www.cashfree.com/docs/payments/manage/monitor

Use Cashfree monitoring and observability tools to track payment success rates, error patterns, and gateway health in real time across your integration stack.

Cashfree sends you notifications that contain alerts and notices about your accounts, Cashfree's systems, and more. In your Notification Area, you can configure how you receive notifications.

## How it works

Cashfree notifications give you important information about the status of Cashfree's platform, for example scheduled maintenance or service downtime. You can also refer to status.cashfree.com for updates on Cashfree's platform.
Cashfree provides the following alerts:

<CardGroup>
  <Card href="#success-rate-alerts" title="Success Rate Alerts">
    Get notified if there is any drop in your payment success rate.
  </Card>

  <Card href="#api-alerts" title="API Alerts">
    Get notified if there are failures in your API success rate.
  </Card>
</CardGroup>

## Success rate alerts

We notify you when your transaction success rate falls below your set threshold. This helps you analyse the factors that lead to the decline, such as payment failures, system errors, or fraudulent activities, and take corrective actions. You can configure your preferred channels to receive these alerts from the dashboard.

**How to create a success rate alert rule?**

You can set this up from:

Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and go to **Payment Gateway > Settings > Notifications > Success Rate Alerts**.

<img />

## API alerts

We notify you about the success rate of your APIs. This ensures you are promptly notified of API errors, high latencies, or rate-limiting issues so you can maintain smooth payment operations.

**Alert types**

1. API starts experiencing **4XX errors**
2. API usage reaches close to its configured rate limit (**Rate Limit Warning Alert**)
3. API latency goes above **1s**

You can set up custom rules tailored to your specific needs. You can specify threshold, API, time range, etc. Example: Alert when "1% of total API calls on 'GET /api/v1/orders/:order\_id' faces 4XX error in last 2 minutes for a minimum API calls of 1".

**How to create an API alert rule?**

You can set this up from:

Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and go to **Developers > API Logs and Alerts**.


# Payment Method Eligibility
Source: https://www.cashfree.com/docs/payments/manage/payment-method-eligibility

Configure Cashfree payment method eligibility rules to control which methods appear at checkout based on order amount, customer, and transaction context.

The Payment Method Eligibility feature allows you to specify which payment methods are available to customers during a transaction, letting you restrict customer payment options to a selected subset from all the available payment methods.

## Supported payment methods

Payment method eligibility is widely used for the cards payment method, supporting a range of card types:

* Credit cards
* Debit cards
* Prepaid cards
* Credit card EMI
* Debit card EMI

## Configuring eligibility

Payment eligibility is defined at the order level using the `payment_methods_filters` parameter in the [Create Order API](/docs/api-reference/payments/latest/orders/create-order) request.
This allows for fine-tuned control over which payment methods are available for each transaction.

## Sample configuration

The following example demonstrates how to configure payment eligibility using the `payment_methods_filters` parameter.\
You can customise this filter by choosing specific payment methods and applying relevant restrictions.

```json Sample code theme={"dark"}
{
  "payment_methods_filters": {
    "methods": {
      "action": "ALLOW",
      "values": [
        "credit_card",
        "debit_card",
        "prepaid_card",
        "credit_card_emi",
        "debit_card_emi"
      ]
    },
    "filters": {
      "card_schemes": {
        "action": "ALLOW",
        "values": ["VISA"]
      },
      "card_suffix": {
        "action": "ALLOW",
        "values": ["1936"]
      },
      "card_issuing_bank": {
        "action": "ALLOW",
        "values": ["AXIS"]
      },
      "card_bins": {
        "action": "ALLOW",
        "values": ["451457"]
      },
      "card_emi_schemes": {
        "action": "ALLOW",
        "values": ["VISA", "MASTERCARD"]
      },
      "card_emi_suffix": {
        "action": "ALLOW",
        "values": ["1936"]
      },
      "card_emi_issuing_bank": {
        "action": "ALLOW",
        "values": ["AXIS"]
      },
      "card_emi_tenure": {
        "action": "ALLOW",
        "values": [3]
      },
      "card_emi_bins": {
        "action": "ALLOW",
        "values": ["451457"]
      }
    }
  }
}
```

## Configuration guidelines

Follow these guidelines to ensure proper use and configuration of the Payment Method Eligibility feature:

* **Action field**: Always use `ALLOW` for the action field.

* **Card schemes**: Values must be in uppercase. For example, `VISA`or `RUPAY`.

* **Issuing bank**: Refer to Cashfree’s [list of valid issuing banks](#view-supported-issuing-banks).

* **Card BINs**: Only valid BINs should be used in the `card_bins` and `card_emi_bins` filters.

* **Card suffix**: The last four digits of the card number must be specified for restrictions.

* **EMI filters**: These should only be used if `credit_card_emi` or `debit_card_emi` is included in methods.

* **Filter order**: Filters can be defined in any order within the `filters` object.

* **Default behaviour**: If `payment_methods_filters` is not defined, all payment methods are supported without restrictions.

* **EMI tenure range**: The range for `card_emi_tenure` is from 3 to 36 months.

### Supported card networks and issuing banks

The following card networks are supported:

<Accordion title="View supported card networks">
  | Sr. no. | Card network |
  | - | - |
  | 1 | RUPAY |
  | 2 | VISA |
  | 3 | DINERS |
  | 4 | MASTERCARD |
  | 5 | AMEX |
</Accordion>

The following banks, listed in the table below, can be used to define the `card_issuing_bank` filter within the `payment_methods_filters` parameter of the [Create Order API](/docs/api-reference/payments/latest/orders/create-order).

<Accordion title="View supported issuing banks">
  | Sr. no. | Bank name |
  | - | - |
  | 1 | State Bank of India |
  | 2 | HDFC Bank |
  | 3 | ICICI Bank |
  | 4 | Axis Bank |
  | 5 | Kotak Mahindra Bank |
  | 6 | RBL Bank |
  | 7 | Union Bank of India |
  | 8 | Bank of Baroda |
  | 9 | IndusInd Bank |
  | 10 | Punjab National Bank |
  | 11 | Canara Bank |
  | 12 | IDFC First Bank |
  | 13 | Yes Bank |
  | 14 | IDBI Bank |
  | 15 | Federal Bank |
  | 16 | Citibank |
  | 17 | Citibank N.A. |
  | 18 | Bank of India |
  | 19 | American Express |
  | 20 | Standard Chartered Bank |
  | 21 | AU Small Finance Bank |
  | 22 | HSBC Bank |
  | 23 | Indian Overseas Bank |
  | 24 | Indian Bank |
  | 25 | Central Bank of India |
  | 26 | UCO Bank |
  | 27 | Jammu & Kashmir Bank |
  | 28 | India Post Payments Bank |
  | 29 | South Indian Bank |
  | 30 | Paytm Payments Bank |
  | 31 | DBS Bank |
  | 32 | SBI Cards and Payment Services Limited |
  | 33 | Karur Vysya Bank |
  | 34 | Airtel Payments Bank |
  | 35 | Karnataka Bank |
  | 36 | City Union Bank |
  | 37 | NPCI |
  | 38 | Punjab & Sind Bank |
  | 39 | Bandhan Bank |
  | 40 | Saraswat Co-operative Bank |
  | 41 | Tamilnad Mercantile Bank |
  | 42 | BOB Financial Solutions Limited (BFSL) |
  | 43 | CSB Bank (Catholic Syrian Bank) |
  | 44 | SBM Bank India |
  | 45 | Ujjivan Bank |
  | 46 | Abhyudaya Co-operative Bank |
  | 47 | Equitas Small Finance Bank |
  | 48 | Fino Payments Bank |
  | 49 | TDCB |
  | 50 | State Bank of Mauritius |
  | 51 | Cosmos Co-operative Bank |
  | 52 | Bank of Maharashtra |
  | 53 | Thane Janata Sahakari Bank |
  | 54 | Diners Club International |
  | 55 | Bassein Catholic Co-operative Bank |
  | 56 | DCB Bank |
  | 57 | Shamrao Vithal Co-operative Bank |
  | 58 | Fincare Small Finance Bank |
  | 59 | Bobcard Limited |
  | 60 | Dhanlaxmi Bank |
  | 61 | JP Morgan Chase Bank N.A. |
  | 62 | Bharat Co-operative Bank Mumbai |
  | 63 | Parsik Janata Sahakari Bank |
  | 64 | Utkarsh Small Finance Bank |
  | 65 | ESAF Small Finance Bank |
  | 66 | NSDL Payments Bank |
  | 67 | Tamil Nadu State Co-operative Bank |
  | 68 | Jana Small Finance Bank |
  | 69 | NKGSB Co-operative Bank |
  | 70 | Apna Sahakari Bank |
  | 71 | Kalyan Janata Sahakari Bank |
  | 72 | SVC Co-operative Bank |
  | 73 | MUBL (Mehsana Urban Co-operative Bank Ltd.) |
  | 74 | West Bengal State Co-operative Bank |
  | 75 | Gujarat State Co-operative Bank |
  | 76 | Dombivili Nagari Sahakari Bank |
  | 77 | NDCI |
  | 78 | Janata Sahakari Bank |
  | 79 | Greater Bombay Co-operative Bank |
  | 80 | Kalupur Commercial Co-operative Bank |
  | 81 | Commonwealth Bank of Australia |
  | 82 | Citizencredit Co-operative Bank |
  | 83 | Capital One, National Association |
  | 84 | Bank of Nova Scotia |
  | 85 | Tangerine Bank |
  | 86 | Rajkot Nagarik Sahakari Bank |
  | 87 | Revolut Ltd |
</Accordion>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/payments/latest/orders/create-order">Create Order API</a></li>
    <li><a href="/docs/api-reference/payments/latest/eligibility/get-eligible-payment-methods">Get Eligible Payment Methods API</a></li>
    <li><a href="/docs/payments/online/element/payment-options">Configuring Payment Options</a></li>
  </ul>
</div>


# Payment Methods
Source: https://www.cashfree.com/docs/payments/manage/payment-methods

Expand checkout reach with Cashfree's six payment-method categories: cards, UPI, netbanking, bank transfers, wallets, and pay-later, all from one integration.

We categorise payment methods into the following six groups:

* [Cards - Indian and International + Apple Pay](#cards)
* [UPI](#upi)
* [Net banking](#net-banking)
* [Wallets](#wallets)
* [Pay later and cardless EMIs](#pay-later-and-cardless-emis)
* [Bank transfer](#bank-transfer)

All payment methods have similar integrations and common checkout experiences. After you’ve integrated one payment method, you can add another within the same family with minimal changes to your integration.

<AccordionGroup>
  <Accordion title="Activating payment methods from the dashboard">
    1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
    2. Go to **Settings > Payment Gateway > Payment Methods**.
    3. View all enabled payment modes on your account. You can also initiate a request for any payment mode directly from the dashboard.

    <img />
  </Accordion>

  <Accordion title="Activating PayPal from the dashboard">
    <img />
  </Accordion>
</AccordionGroup>

## Cards

Cards are a widely used payment method for both consumers and businesses, whether online or in person. Cashfree supports both global and local card networks. Explore the card brands supported by Cashfree.

You can accept payments from your customers using debit or credit cards from all international providers. Check the various capabilities we offer with Cards:

<CardGroup>
  <Card icon="lock" title="3D Secure 2.0">
    Enhanced security protocol that provides real-time risk assessment and
    authentication for online transactions.
  </Card>

  <Card icon="bolt" title="CVV less flow">
    Remove the need for entering the CVV for cards saved with Cashfree
  </Card>

  <Card icon="cc-visa" title="Save Cards">
    Securely store and tokenise cards in a PCI-compliant vault
  </Card>

  <Card icon="command" title="Recurring Payments">
    Automated billing system for subscriptions and recurring charges with
    flexible scheduling options.
  </Card>

  <Card icon="apple" title="Apple Pay Payments">
    Seamless Apple Pay-based card payments for eligible cards and transactions
  </Card>

  <Card icon="lock" title="Credit Card EMI">
    Support for EMI payments on credit cards with more than 10 banks.
  </Card>
</CardGroup>

We support the following card networks:

<CardGroup>
  <Card title="Visa" icon="cc-visa" />

  <Card title="Rupay" icon="credit-card-blank" />

  <Card title="Mastercard" icon="cc-mastercard" />

  <Card title="American Express" icon="cc-amex" />

  <Card title="Diners" icon="cc-diners-club" />
</CardGroup>

## UPI

UPI is the most popular payment method in India. UPI lets customers transfer money directly from their bank account or an alternate funding source (such as a credit card or pre-paid wallet) using an authenticating intermediary like a phone number.

<CardGroup>
  <Card icon="qrcode" title="UPI Intent, QR and Collect">
    Collect UPI payments using intent, QR, or collect.
  </Card>

  <Card icon="bolt" title="Flash UPI">
    Add the UPI SDK to your app to power in-app payments.
  </Card>

  <Card icon="command" title="Recurring Payments">
    Support for UPI one-time mandates and recurring payments.
  </Card>
</CardGroup>

## Net banking

Cashfree can accept payments from your customers using **net banking**. This method is available by default. You can view which net banking banks are enabled for your account in the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).

```mermaid theme={"dark"}
sequenceDiagram
    autonumber
    actor Customer
    Merchant-->>Cashfree: Payment Initiation
    Merchant -->> Customer: Payment Initiation Response
    Customer -->> Bank: Redirect to Bank
    Bank -->> Cashfree: Payment Result
    Cashfree -->> Merchant: Payment Result
```

<br />

<Accordion title="List of net banking with codes and TPV supported flags">
  For testing purposes in sandbox mode merchant can use below bank code
  "customer\_bank\_code": 3333

  | Bank name | Code | TPV\_supported | Bank code |
  | - | - | :-: | - |
  | Airtel Payments Bank | 3123 | No | AIRPR |
  | Andhra Pragathi Grameena Bank | 3094 | No | APGBR |
  | AU Small Finance Bank | 3087 | Yes | AUBLR |
  | Axis Bank | 3003 | Yes | UTIBR |
  | Axis Bank - Corporate | 3071 | No | UTIBC |
  | Bandhan Bank - Retail Banking | 3088 | Yes | BDBLR |
  | Bank of Bahrain and Kuwait | 3095 | No | BBKMR |
  | Bank of Baroda - Corporate | 3060 | Yes | BARBC |
  | Bank of Baroda - Retail Banking | 3005 | Yes | BARBR |
  | Bank of India | 3006 | Yes | BKIDR |
  | Bank of India - Corporate | 3061 | Yes | BKIDC |
  | Bank of Maharashtra | 3007 | No | MAHBR |
  | Barclays - Corporate | 3080 | No | BARCC |
  | Canara Bank | 3009 | Yes | CNRBR |
  | Capital Small Finance Bank | 3098 | Yes | CLBLR |
  | Central Bank of India | 3011 | No | CBINR |
  | City Union Bank | 3012 | Yes | CIUBR |
  | City Union Bank - Corporate | 3083 | Yes | CIUBC |
  | Cosmos Bank | 3097 | Yes | COSBR |
  | CSB Bank Limited | 3010 | Yes | CSBKR |
  | DBS Bank Ltd | 3017 | No | DBSSR |
  | DCB Bank - Retail | 3018 | Yes | DCBLR |
  | Deutsche Bank | 3016 | Yes | DEUTR |
  | Dhanlakshmi Bank | 3019 | Yes | DLXBR |
  | Dhanlaxmi Bank - Corporate | 3072 | No | DLXBC |
  | Equitas Small Finance Bank | 3076 | No | ESFBR |
  | ESAF Small Finance Bank | 3100 | No | ESMFR |
  | Federal Bank | 3020 | Yes | FDRLR |
  | Fincare Bank | 3101 | No | FSFBR |
  | Gujarat State Co-operative Bank Limited | 3091 | No | GSCBR |
  | HDFC Bank | 3021 | Yes | HDFCR |
  | HDFC Corporate | 3084 | No | HDFCC |
  | ICICI Bank | 3022 | Yes | ICICR |
  | ICICI Bank - Corporate | 3073 | No | ICICC |
  | IDBI Bank | 3023 | Yes | IBKLR |
  | IDBI Bank - Corporate | 3124 | Yes | IBKLC |
  | IDFC FIRST Bank | 3024 | Yes | IDFBR |
  | Indian Bank | 3026 | Yes | IDIBR |
  | Indian Overseas Bank | 3027 | Yes | IOBAR |
  | Indian Overseas Bank - Corporate | 3081 | Yes | IOBAC |
  | IndusInd Bank | 3028 | Yes | INDBR |
  | Jammu and Kashmir Bank | 3029 | Yes | JAKAR |
  | Jana Small Finance Bank | 3102 | Yes | JSFBR |
  | Janata Sahakari Bank Ltd Pune | 3104 | No | JSBPR |
  | Kalyan Janata Sahakari Bank | 3105 | No | KJSBR |
  | Karnataka Bank Ltd | 3030 | Yes | KARBR |
  | Karnataka Gramin Bank | 3113 | No | PKGBR |
  | Karnataka Vikas Grameena Bank | 3107 | No | KVGBR |
  | Karur Vysya Bank | 3031 | Yes | KVBLR |
  | Kotak Mahindra Bank | 3032 | Yes | KKBKR |
  | Kotak Mahindra Bank - Corporate | 3134 | Yes | KKBKC |
  | Maharashtra Gramin Bank | 3108 | No | MAHGR |
  | Mehsana urban Co-op Bank | 3109 | No | MSNUR |
  | NKGSB Co-op Bank | 3111 | No | NKGSR |
  | Nutan Nagarik Sahakari Bank Limited | 3112 | No | NNSBR |
  | Punjab & Sind Bank | 3037 | Yes | PSIBR |
  | Punjab National Bank - Corporate | 3065 | No | PUNBC |
  | Punjab National Bank - Retail Banking | 3038 | Yes | PUNBR |
  | RBL Bank | 3039 | Yes | RATNR |
  | RBL Bank Limited - Corporate | 3114 | No | RATNC |
  | Saraswat Bank | 3040 | Yes | SRCBR |
  | SBM Bank India | 3115 | Yes | STCBR |
  | Shamrao Vithal Bank - Corporate | 3075 | No | SVCBC |
  | Shamrao Vitthal Co-operative Bank | 3041 | No | SVCBR |
  | Shivalik Small Finance Bank | 3086 | Yes | SMCBR |
  | South Indian Bank | 3042 | Yes | SIBLR |
  | Standard Chartered Bank | 3043 | Yes | SCBLR |
  | State Bank Of India | 3044 | Yes | SBINR |
  | State Bank of India - Corporate | 3066 | Yes | SBINC |
  | Suryoday Small Finance Bank | 3116 | No | SURYR |
  | Tamil Nadu State Co-operative Bank | 3051 | No | TNSCR |
  | Tamilnad Mercantile Bank Ltd | 3052 | Yes | TMBLR |
  | Thane Bharat Sahakari Bank Ltd | 3118 | No | TBSBR |
  | The Kalupur Commercial Co-Operative Bank | 3106 | No | KCCBR |
  | The Surat Peoples Co-operative Bank Ltd | 3090 | Yes | SPCBR |
  | The Sutex Co-op Bank Ltd | 3117 | Yes | SUTBR |
  | TJSB Bank | 3119 | No | TJSBR |
  | UCO Bank | 3054 | Yes | UCBAR |
  | UCO Bank Corporate | 3122 | No | UCBAC |
  | Ujjivan Small Finance Bank | 3126 | Yes | UJVNR |
  | Union Bank of India | 3055 | Yes | UBINR |
  | Union Bank of India - Corporate | 3067 | Yes | UBINC |
  | Utkarsh Small Finance Bank | 3089 | Yes | UTKSR |
  | Varachha Co-operative Bank Limited | 3120 | No | VARAR |
  | Yes Bank - Corporate | 3077 | No | YESBC |
  | Yes Bank Ltd | 3058 | Yes | YESBR |
  | Zoroastrian Co-Operative Bank Ltd | 3121 | No | ZCBLR |
</Accordion>

## Wallets

Cashfree supports a wide range of wallets to receive payments.

| Wallet name | Activation |
| - | - |
| FreeCharge | <span aria-label="Automatic Activation">AUTOMATIC</span> |
| PayPal | <span aria-label="Self Activate from Dashboard">SELF-ACTIVATE</span> |
| MobiKwik | <span aria-label="Automatic Activation">AUTOMATIC</span> |
| Ola Money | <span aria-label="Automatic Activation">AUTOMATIC</span> |
| Airtel Money | <span aria-label="Automatic Activation">AUTOMATIC</span> |
| Amazon Pay | <span aria-label="Automatic Activation">AUTOMATIC</span> |
| PhonePe | <span aria-label="Automatic Activation">AUTOMATIC</span> |

## Pay later and cardless EMIs

Cashfree supports payment options with EMI and pay later methods. Seamlessly integrate Cashfree's platform to offer a range of credit and debit card EMIs, along with diverse pay later providers, enhancing the checkout experience.

### Credit card EMI

Cashfree supports credit card EMI payment method. You can use different EMI providers on our platform. Below is a list of supported providers and their payment codes for a seamless flow. If you are using a Cashfree hosted integration, we will automatically show all these options to eligible users on the checkout page.

Here is a sample of the request that you need to send to `/orders/sessions` to process a seamless EMI payment. [Read more here](/docs/api-reference/payments/latest/payments/order-pay).

```javascript theme={"dark"}

{	      "payment_session_id":"session_mdCizuqcgJWbIhdJ4rjONvpCB1B31muN7Tev9p2kdlEQpj9mem5yF5gbUju4kdgN6-31FJnGK3yaEcqG0GZUsrbzOLDFPfA30iYduwiNmBk",
"payment_method" : {
		"emi": {
			"channel": "link",
			"card_number": "4111111111111111",
			"card_expiry_mm": "12",
			"card_expiry_yy": "22",
			"card_cvv": "123",
			"card_bank_name": "hdfc",
			"emi_tenure": 3
		}
	}
}

```

We support varying tenures for each of these: 3, 6, 9, 12, 14, 18, 24, 36, 48 depending on the issuing bank.

<Accordion title="The following card issuers are supported for card-based EMIs.">
  Please send the exact values in the `card_bank_name` parameter. We support varying tenures for each of these: 3, 6, 9, 12, 14, 18, 24, 36, 48 depending on the issuing bank.

  ### Credit card EMI plans

  | Card type | Type of EMI | Bank | Card\_bank\_name | Minimum amount | Maximum amount | Annual interest rate | Tenure | Processing fees | Remarks |
  | - | - | - | - | - | - | - | - | - | - |
  | Credit | Standard | ICICI Bank | icici | 1500 | 9999999 | 15.99 | 3 | 2.99% + GST, maximum up to ₹299 + GST | - |
  | Credit | Standard | ICICI Bank | icici | 1500 | 9999999 | 15.99 | 6 | 2.99% + GST, maximum up to ₹299 + GST | - |
  | Credit | Standard | ICICI Bank | icici | 1500 | 9999999 | 15.99 | 9 | 2.99% + GST, maximum up to ₹299 + GST | - |
  | Credit | Standard | ICICI Bank | icici | 1500 | 9999999 | 15.99 | 12 | 2.99% + GST, maximum up to ₹299 + GST | - |
  | Credit | Standard | ICICI Bank | icici | 1500 | 9999999 | 15.99 | 18 | 2.99% + GST, maximum up to ₹299 + GST | - |
  | Credit | Standard | ICICI Bank | icici | 1500 | 9999999 | 15.99 | 24 | 2.99% + GST, maximum up to ₹299 + GST | - |
  | Credit | Standard | AU Small Finance Bank | au | 2000 | - | 14 | 3 | ₹199 + GST | - |
  | Credit | Standard | AU Small Finance Bank | au | 2000 | - | 14 | 6 | ₹199 + GST | - |
  | Credit | Standard | AU Small Finance Bank | au | 2000 | - | 14 | 9 | ₹199 + GST | - |
  | Credit | Standard | AU Small Finance Bank | au | 2000 | - | 14 | 12 | ₹199 + GST | - |
  | Credit | Standard | AU Small Finance Bank | au | 2000 | - | 14 | 18 | ₹199 + GST | - |
  | Credit | Standard | AU Small Finance Bank | au | 2000 | - | 14 | 24 | ₹199 + GST | - |
  | Credit | Standard | Axis Bank | axis | 2500 | 1000000 | 17 | 3 | ₹299 + GST below ₹50,000; ₹599 + GST above ₹50,000 | - |
  | Credit | Standard | Axis Bank | axis | 2500 | 1000000 | 17 | 6 | ₹299 + GST below ₹50,000; ₹599 + GST above ₹50,000 | - |
  | Credit | Standard | Axis Bank | axis | 2500 | 1000000 | 17 | 9 | ₹299 + GST below ₹50,000; ₹599 + GST above ₹50,000 | - |
  | Credit | Standard | Axis Bank | axis | 2500 | 1000000 | 17 | 12 | ₹299 + GST below ₹50,000; ₹599 + GST above ₹50,000 | - |
  | Credit | Standard | Axis Bank | axis | 2500 | 1000000 | 17 | 18 | ₹299 + GST below ₹50,000; ₹599 + GST above ₹50,000 | - |
  | Credit | Standard | Axis Bank | axis | 2500 | 1000000 | 17 | 24 | ₹299 + GST below ₹50,000; ₹599 + GST above ₹50,000 | - |
  | Credit | Standard | Bank of Baroda | bob | 2500 | - | 16 | 3 | ₹199 + GST | Available tenures: 2, 3, 4, 5, 6, 7, 8, 9, 12, 18, 24, 36. See Bank of Baroda EMI terms below. |
  | Credit | Standard | Bank of Baroda | bob | 2500 | - | 16 | 6 | ₹199 + GST | Available tenures: 2, 3, 4, 5, 6, 7, 8, 9, 12, 18, 24, 36. See Bank of Baroda EMI terms below. |
  | Credit | Standard | Bank of Baroda | bob | 2500 | - | 16 | 9 | ₹199 + GST | Available tenures: 2, 3, 4, 5, 6, 7, 8, 9, 12, 18, 24, 36. See Bank of Baroda EMI terms below. |
  | Credit | Standard | Bank of Baroda | bob | 2500 | - | 16 | 12 | ₹199 + GST | Available tenures: 2, 3, 4, 5, 6, 7, 8, 9, 12, 18, 24, 36. See Bank of Baroda EMI terms below. |
  | Credit | Standard | Bank of Baroda | bob | 2500 | - | 16 | 18 | ₹199 + GST | Available tenures: 2, 3, 4, 5, 6, 7, 8, 9, 12, 18, 24, 36. See Bank of Baroda EMI terms below. |
  | Credit | Standard | Bank of Baroda | bob | 2500 | - | 16 | 24 | ₹199 + GST | Available tenures: 2, 3, 4, 5, 6, 7, 8, 9, 12, 18, 24, 36. See Bank of Baroda EMI terms below. |
  | Credit | Standard | Bank of Baroda | bob | 2500 | - | 16 | 36 | ₹199 + GST | Available tenures: 2, 3, 4, 5, 6, 7, 8, 9, 12, 18, 24, 36. See Bank of Baroda EMI terms below. |
  | Credit | Standard | RBL Bank | rbl | 2500 | - | 14 | 3 | ₹150 + GST up to ₹10,000; 1.5% + GST above ₹10,000 | - |
  | Credit | Standard | RBL Bank | rbl | 2500 | - | 14 | 6 | ₹150 + GST up to ₹10,000; 1.5% + GST above ₹10,000 | - |
  | Credit | Standard | RBL Bank | rbl | 2500 | - | 15 | 9 | ₹150 + GST up to ₹10,000; 1.5% + GST above ₹10,000 | - |
  | Credit | Standard | RBL Bank | rbl | 2500 | - | 15 | 12 | ₹150 + GST up to ₹10,000; 1.5% + GST above ₹10,000 | - |
  | Credit | Standard | RBL Bank | rbl | 2500 | - | 15 | 18 | ₹150 + GST up to ₹10,000; 1.5% + GST above ₹10,000 | - |
  | Credit | Standard | RBL Bank | rbl | 2500 | - | 15 | 24 | ₹150 + GST up to ₹10,000; 1.5% + GST above ₹10,000 | - |
  | Credit | Standard | Standard Chartered | standard\_chartered | 2000 | - | 11.88 | 3 | 1% | - |
  | Credit | Standard | Standard Chartered | standard\_chartered | 2000 | - | 14 | 6 | 1% | - |
  | Credit | Standard | Standard Chartered | standard\_chartered | 2000 | - | 15 | 9 | 1% | - |
  | Credit | Standard | Standard Chartered | standard\_chartered | 2000 | - | 15 | 12 | 1% | - |
  | Credit | Standard | Standard Chartered | standard\_chartered | 2000 | - | 15 | 18 | 1% | - |
  | Credit | Standard | Standard Chartered | standard\_chartered | 2000 | - | 15 | 24 | 1% | - |
  | Credit | Standard | Yes Bank | yes | 1500 | 999999999 | 16 | 3 | ₹299 + GST | - |
  | Credit | Standard | Yes Bank | yes | 1500 | 999999999 | 16 | 6 | ₹299 + GST | - |
  | Credit | Standard | Yes Bank | yes | 1500 | 999999999 | 16 | 9 | ₹299 + GST | - |
  | Credit | Standard | Yes Bank | yes | 1500 | 999999999 | 16 | 12 | ₹299 + GST | - |
  | Credit | Standard | Yes Bank | yes | 1500 | 999999999 | 16 | 18 | ₹299 + GST | - |
  | Credit | Standard | Yes Bank | yes | 1500 | 999999999 | 16 | 24 | ₹299 + GST | - |
  | Credit | Standard | American Express | amex | 5000 | - | 14 | 3 | ₹199 + GST | [American Express EMI terms](https://www.americanexpress.com/en-in/benefits/emi/terms-and-conditions/index.html) |
  | Credit | Standard | American Express | amex | 5000 | - | 14 | 6 | ₹199 + GST | [American Express EMI terms](https://www.americanexpress.com/en-in/benefits/emi/terms-and-conditions/index.html) |
  | Credit | Standard | American Express | amex | 5000 | - | 14 | 9 | ₹199 + GST | [American Express EMI terms](https://www.americanexpress.com/en-in/benefits/emi/terms-and-conditions/index.html) |
  | Credit | Standard | American Express | amex | 5000 | - | 14 | 12 | ₹199 + GST | [American Express EMI terms](https://www.americanexpress.com/en-in/benefits/emi/terms-and-conditions/index.html) |
  | Credit | Standard | American Express | amex | 5000 | - | 15 | 18 | ₹199 + GST | [American Express EMI terms](https://www.americanexpress.com/en-in/benefits/emi/terms-and-conditions/index.html) |
  | Credit | Standard | American Express | amex | 5000 | - | 15 | 24 | ₹199 + GST | [American Express EMI terms](https://www.americanexpress.com/en-in/benefits/emi/terms-and-conditions/index.html) |
  | Credit | Standard | HDFC Bank | hdfc | 1000 | 999000 | 18 | 3 | ₹299 + GST | [HDFC Bank EasyEMI credit card](https://www.hdfc.bank.in/easyemi/credit-card). Available tenures: 3, 6, 9, 12, 18, 24, 36, 48. |
  | Credit | Standard | HDFC Bank | hdfc | 1000 | 999000 | 17 | 6 | ₹299 + GST | [HDFC Bank EasyEMI credit card](https://www.hdfc.bank.in/easyemi/credit-card). Available tenures: 3, 6, 9, 12, 18, 24, 36, 48. |
  | Credit | Standard | HDFC Bank | hdfc | 1000 | 999000 | 17 | 9 | ₹299 + GST | [HDFC Bank EasyEMI credit card](https://www.hdfc.bank.in/easyemi/credit-card). Available tenures: 3, 6, 9, 12, 18, 24, 36, 48. |
  | Credit | Standard | HDFC Bank | hdfc | 1000 | 999000 | 17 | 12 | ₹299 + GST | [HDFC Bank EasyEMI credit card](https://www.hdfc.bank.in/easyemi/credit-card). Available tenures: 3, 6, 9, 12, 18, 24, 36, 48. |
  | Credit | Standard | HDFC Bank | hdfc | 1000 | 999000 | 17 | 18 | ₹299 + GST | [HDFC Bank EasyEMI credit card](https://www.hdfc.bank.in/easyemi/credit-card). Available tenures: 3, 6, 9, 12, 18, 24, 36, 48. |
  | Credit | Standard | HDFC Bank | hdfc | 1000 | 999000 | 17 | 24 | ₹299 + GST | [HDFC Bank EasyEMI credit card](https://www.hdfc.bank.in/easyemi/credit-card). Available tenures: 3, 6, 9, 12, 18, 24, 36, 48. |
  | Credit | Standard | HDFC Bank | hdfc | 1000 | 999000 | 17 | 36 | ₹299 + GST | [HDFC Bank EasyEMI credit card](https://www.hdfc.bank.in/easyemi/credit-card). Available tenures: 3, 6, 9, 12, 18, 24, 36, 48. |
  | Credit | Standard | HDFC Bank | hdfc | 1000 | 999000 | 17 | 48 | ₹299 + GST | [HDFC Bank EasyEMI credit card](https://www.hdfc.bank.in/easyemi/credit-card). Available tenures: 3, 6, 9, 12, 18, 24, 36, 48. |
  | Credit | Standard | Kotak Mahindra Bank | kotak | 1000 | - | 16 | 3 | ₹249 + GST | Available tenures: 3, 6, 9, 12, 18, 20, 24, 30, 36. Foreclosure fee of 2% on the principal amount + GST. |
  | Credit | Standard | Kotak Mahindra Bank | kotak | 2500 | - | 16 | 6 | ₹249 + GST | Available tenures: 3, 6, 9, 12, 18, 20, 24, 30, 36. Foreclosure fee of 2% on the principal amount + GST. |
  | Credit | Standard | Kotak Mahindra Bank | kotak | 2500 | - | 16 | 9 | ₹249 + GST | Available tenures: 3, 6, 9, 12, 18, 20, 24, 30, 36. Foreclosure fee of 2% on the principal amount + GST. |
  | Credit | Standard | Kotak Mahindra Bank | kotak | 2500 | - | 16 | 12 | ₹249 + GST | Available tenures: 3, 6, 9, 12, 18, 20, 24, 30, 36. Foreclosure fee of 2% on the principal amount + GST. |
  | Credit | Standard | Kotak Mahindra Bank | kotak | 2500 | - | 16 | 18 | ₹249 + GST | Available tenures: 3, 6, 9, 12, 18, 20, 24, 30, 36. Foreclosure fee of 2% on the principal amount + GST. |
  | Credit | Standard | Kotak Mahindra Bank | kotak | 2500 | - | 16 | 20 | ₹249 + GST | Available tenures: 3, 6, 9, 12, 18, 20, 24, 30, 36. Foreclosure fee of 2% on the principal amount + GST. |
  | Credit | Standard | Kotak Mahindra Bank | kotak | 2500 | - | 16 | 24 | ₹249 + GST | Available tenures: 3, 6, 9, 12, 18, 20, 24, 30, 36. Foreclosure fee of 2% on the principal amount + GST. |
  | Credit | Standard | Kotak Mahindra Bank | kotak | 2500 | - | 16 | 30 | ₹249 + GST | Available tenures: 3, 6, 9, 12, 18, 20, 24, 30, 36. Foreclosure fee of 2% on the principal amount + GST. |
  | Credit | Standard | Kotak Mahindra Bank | kotak | 2500 | - | 16 | 36 | ₹249 + GST | Available tenures: 3, 6, 9, 12, 18, 20, 24, 30, 36. Foreclosure fee of 2% on the principal amount + GST. |
  | Credit | Standard | SBI | sbi | 2500 | - | 17.25 | 3 | - | - |
  | Credit | Standard | SBI | sbi | 2500 | - | 17.00 | 6 | ₹45 for transactions of ₹20,000 or more | - |
  | Credit | Standard | SBI | sbi | 2500 | - | 17.00 | 9 | ₹69 for transactions of ₹20,000 or more | - |
  | Credit | Standard | SBI | sbi | 2500 | - | 17.00 | 12 | ₹89 for transactions of ₹20,000 or more | - |
  | Credit | Standard | SBI | sbi | 2500 | - | 17.00 | 18 | ₹129 for transactions of ₹20,000 or more | - |
  | Credit | Standard | SBI | sbi | 2500 | - | 17.00 | 24 | ₹169 for transactions of ₹20,000 or more | - |
  | Credit | Standard | IDFC Bank | idfc | 1500 | - | 16 | 3 | ₹249 + GST | Foreclosure fee of 3% of outstanding amount + GST |
  | Credit | Standard | IDFC Bank | idfc | 1500 | - | 16 | 6 | ₹249 + GST | Foreclosure fee of 3% of outstanding amount + GST |
  | Credit | Standard | IDFC Bank | idfc | 1500 | - | 16 | 9 | ₹249 + GST | Foreclosure fee of 3% of outstanding amount + GST |
  | Credit | Standard | IDFC Bank | idfc | 1500 | - | 16 | 12 | ₹249 + GST | Foreclosure fee of 3% of outstanding amount + GST |
  | Credit | Standard | IDFC Bank | idfc | 1500 | - | 16 | 18 | ₹249 + GST | Foreclosure fee of 3% of outstanding amount + GST |
  | Credit | Standard | IDFC Bank | idfc | 1500 | - | 16 | 24 | ₹249 + GST | Foreclosure fee of 3% of outstanding amount + GST |
  | Credit | Standard | IDFC Bank | idfc | 1500 | - | 16 | 36 | ₹249 + GST | Foreclosure fee of 3% of outstanding amount + GST |
  | Credit | Standard | IndusInd Bank | indus | 2000 | - | 17 | 3 | ₹249 + GST | [IndusInd Easy EMI terms](https://www.indusind.bank.in/in/en/personal/indus-easy-emi-tnc.html) |
  | Credit | Standard | IndusInd Bank | indus | 2000 | - | 16 | 6 | ₹249 + GST | [IndusInd Easy EMI terms](https://www.indusind.bank.in/in/en/personal/indus-easy-emi-tnc.html) |
  | Credit | Standard | IndusInd Bank | indus | 2000 | - | 16 | 9 | ₹249 + GST | [IndusInd Easy EMI terms](https://www.indusind.bank.in/in/en/personal/indus-easy-emi-tnc.html) |
  | Credit | Standard | IndusInd Bank | indus | 2000 | - | 16 | 12 | ₹249 + GST | [IndusInd Easy EMI terms](https://www.indusind.bank.in/in/en/personal/indus-easy-emi-tnc.html) |
  | Credit | Standard | IndusInd Bank | indus | 2000 | - | 16 | 18 | ₹249 + GST | [IndusInd Easy EMI terms](https://www.indusind.bank.in/in/en/personal/indus-easy-emi-tnc.html) |
  | Credit | Standard | IndusInd Bank | indus | 2000 | - | 16 | 24 | ₹249 + GST | [IndusInd Easy EMI terms](https://www.indusind.bank.in/in/en/personal/indus-easy-emi-tnc.html) |
  | Credit | Standard | IndusInd Bank | indus | 2000 | - | 16 | 36 | ₹249 + GST | [IndusInd Easy EMI terms](https://www.indusind.bank.in/in/en/personal/indus-easy-emi-tnc.html) |

  <Note>
    For Bank of Baroda EMI, the following terms must appear in all T\&C documents and on the payment page of campaigns that include EMI:

    1. I have understood and accept the T\&C of EMI as available on the website ([www.bobcard.co.in](https://www.bobcard.co.in)) and the applicable charges mentioned.
    2. I understand that in the event of the merchant or me cancelling my EMI transaction, I am responsible for notifying BOBCARD to cancel the EMI that was booked for the cancelled transaction.
    3. Processing fee of ₹199 plus applicable taxes will be charged for each EMI.
  </Note>
</Accordion>

### Debit card EMI

Cashfree supports HDFC Bank debit card EMI. This option is available to customers who are pre-approved by this issuing bank.

Here’s a sample request to send to `/orders/sessions` for processing a seamless EMI payment [read more here](/docs/api-reference/payments/latest/payments/order-pay). In case of a native OTP flow, Cashfree provides a [Submit OTP API](/docs/api-reference/payments/latest/payments/submit-or-resend-otp) that you must integrate into your checkout page.

<CodeGroup>
  ```Text Request theme={"dark"}
  {
       "payment_method": {
            "emi": {
                 "channel": "post",
                 "card_number": "4280901212123121",
                 "card_holder_name": "Tushar Gupta",
                 "card_expiry_mm": "09",
                 "card_expiry_yy": "23",
                 "card_cvv": "900",
                 "emi_tenure": 12,
                 "card_bank_name": "hdfc",
                 "phone": 8714268343
            }
       },
      "payment_session_id": "session__CvcEmNKDkmERQrxnx39ibhJ3Ii034pjc8ZVxf3qcgEXCWlgDDlHRgz2XYZCqpajDQSXMMtCusPgOIxYP2LZx0-05p39gC2Vgmq1RAj--gcn"
  }
  ```

  ```Text Response (Native OTP) theme={"dark"}
  {
      "action": "post",
      "cf_payment_id": 1491777871,
      "channel": "link",
      "data": {
          "url": "https://sandbox.cashfree.com/pg/orders/pay/authenticate/1491777871",
          "payload": null,
          "content_type": "application/json",
          "method": "post"
      },
      "payment_amount": 6000.00,
      "payment_method": "emi"
  }
  ```

  ```Text Submit OTP Request theme={"dark"}
  curl --request POST \
       --url https://sandbox.cashfree.com/pg/orders/pay/authenticate/1111111 \
       --header 'accept: application/json' \
       --header 'content-type: application/json' \
       --header 'x-api-version: 2022-09-01' \
       --data '
  {
    "action": "SUBMIT_OTP",
    "otp": "1234"
  }
  '
  ```
</CodeGroup>

<Accordion title="The following 1 card issuer is supported for card-based EMIs. ">
  Please send the exact values in the `card_bank_name` parameter.

  | Bank name | Native OTP |
  | :- | :- |
  | HDFC Bank | Yes |

  ### Debit card EMI plans

  | Card type | Type of EMI | Bank | Card\_bank\_name | Minimum amount | Maximum amount | Annual interest rate | Tenure | Processing fees | Remarks |
  | - | - | - | - | - | - | - | - | - | - |
  | Debit | Standard | HDFC Bank | hdfc | 3000 | 400000 | 16 | 3 | ₹299 + GST | [HDFC Bank EasyEMI debit card](https://www.hdfc.bank.in/easyemi/debit-card). Available tenures: 3, 6, 9, 12, 18, 24, 36, 48. |
  | Debit | Standard | HDFC Bank | hdfc | 3000 | 400000 | 16 | 6 | ₹299 + GST | [HDFC Bank EasyEMI debit card](https://www.hdfc.bank.in/easyemi/debit-card). Available tenures: 3, 6, 9, 12, 18, 24, 36, 48. |
  | Debit | Standard | HDFC Bank | hdfc | 3000 | 400000 | 16 | 9 | ₹299 + GST | [HDFC Bank EasyEMI debit card](https://www.hdfc.bank.in/easyemi/debit-card). Available tenures: 3, 6, 9, 12, 18, 24, 36, 48. |
  | Debit | Standard | HDFC Bank | hdfc | 3000 | 400000 | 16 | 12 | ₹299 + GST | [HDFC Bank EasyEMI debit card](https://www.hdfc.bank.in/easyemi/debit-card). Available tenures: 3, 6, 9, 12, 18, 24, 36, 48. |
  | Debit | Standard | HDFC Bank | hdfc | 3000 | 400000 | 16 | 18 | ₹299 + GST | [HDFC Bank EasyEMI debit card](https://www.hdfc.bank.in/easyemi/debit-card). Available tenures: 3, 6, 9, 12, 18, 24, 36, 48. |
  | Debit | Standard | HDFC Bank | hdfc | 3000 | 400000 | 16 | 24 | ₹299 + GST | [HDFC Bank EasyEMI debit card](https://www.hdfc.bank.in/easyemi/debit-card). Available tenures: 3, 6, 9, 12, 18, 24, 36, 48. |
  | Debit | Standard | HDFC Bank | hdfc | 3000 | 400000 | 16 | 36 | ₹299 + GST | [HDFC Bank EasyEMI debit card](https://www.hdfc.bank.in/easyemi/debit-card). Available tenures: 3, 6, 9, 12, 18, 24, 36, 48. |
  | Debit | Standard | HDFC Bank | hdfc | 3000 | 400000 | 16 | 48 | ₹299 + GST | [HDFC Bank EasyEMI debit card](https://www.hdfc.bank.in/easyemi/debit-card). Available tenures: 3, 6, 9, 12, 18, 24, 36, 48. |
</Accordion>

### Cardless EMI plans

Customers can pay using non-card based EMI providers. A sample request is provided for reference.

The available providers include FlexMoney, which offers cardless EMI options from HDFC Bank, ICICI Bank, IDFC Bank, LazyPay, TVS Credit, and Home Credit, as well as ZestMoney.

```javascript Request theme={"dark"}
curl --request POST \
     --url https://api.cashfree.com/pg/orders/sessions \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --data '
{
     "payment_method": {
          "cardless_emi": {
               "channel": "link",
               "provider": "flexmoney",
               "phone": "77891212345"
          }
     },
     "payment_session_id": "session_mdCizuqcgJWbIhdJ4rjON-vpCB1B31muN7Tev9p2kdlEQpj9mem5yF5gbUju4kdgN6-31FJnGK3yaEcqG0GZUsrbzOLDFPfA30iYduwiNmBk"
}
```

**Provider parameters:**

* flexmoney—FlexMoney; (powers cardless EMI from HDFC Bank, ICICI Bank, IDFC Bank, LazyPay, TVS Credit, and Home Credit).
* zestmoneyv2-ZestMoney; (powers ZestMoney Cardless EMI).

<Accordion title="Cardless EMI plans">
  | Card type | Type of EMI | Bank | Provider | Minimum amount | Maximum amount | Annual interest rate | Tenure | Processing fees | Remarks |
  | - | - | - | - | - | - | - | - | - | - |
  | Cardless | Standard | HDFC Bank | hdfc | 3000 | 500000 | 16 | 3 | ₹299 + GST | - |
  | Cardless | Standard | HDFC Bank | hdfc | 5000 | 500000 | 16 | 6 | ₹299 + GST | - |
  | Cardless | Standard | HDFC Bank | hdfc | 5000 | 500000 | 16 | 9 | ₹299 + GST | - |
  | Cardless | Standard | HDFC Bank | hdfc | 5000 | 500000 | 16 | 12 | ₹299 + GST | - |
  | Cardless | Standard | HDFC Bank | hdfc | 5000 | 500000 | 16 | 18 | ₹299 + GST | - |
  | Cardless | Standard | HDFC Bank | hdfc | 5000 | 500000 | 16 | 24 | ₹299 + GST | - |
  | Cardless | Standard | ICICI Bank | icici | 7000 | 500000 | 18 | 3 | - | - |
  | Cardless | Standard | ICICI Bank | icici | 7000 | 500000 | 18 | 6 | - | - |
  | Cardless | Standard | ICICI Bank | icici | 7000 | 500000 | 18 | 9 | - | - |
  | Cardless | Standard | ICICI Bank | icici | 7000 | 500000 | 18 | 12 | - | - |
  | Cardless | Standard | IDFC Bank | idfc | 5000 | 60000 | 24 | 3 | - | - |
  | Cardless | Standard | IDFC Bank | idfc | 5000 | 60000 | 24 | 6 | - | - |
  | Cardless | Standard | IDFC Bank | idfc | 5000 | 60000 | 24 | 9 | - | - |
  | Cardless | Standard | IDFC Bank | idfc | 5000 | 60000 | 24 | 12 | - | - |
  | Cardless | Standard | LazyPay | lazypay | 3000 | 100000 | 20 | 3 | ₹199 + GST | - |
  | Cardless | Standard | LazyPay | lazypay | 3000 | 100000 | 20 | 6 | ₹199 + GST | - |
  | Cardless | Standard | LazyPay | lazypay | 3000 | 100000 | 20 | 9 | ₹199 + GST | - |
  | Cardless | Standard | LazyPay | lazypay | 3000 | 100000 | 20 | 12 | ₹199 + GST | - |
  | Cardless | Standard | TVS Credit | tvs | 3000 | 50000 | 22 | 3 | 2.36% | Available tenures: 3, 6, 9, 12, 15, 18, 24 |
  | Cardless | Standard | TVS Credit | tvs | 3000 | 50000 | 22 | 6 | 4.72% | Available tenures: 3, 6, 9, 12, 15, 18, 24 |
  | Cardless | Standard | TVS Credit | tvs | 3000 | 50000 | 27 | 9 | 4.72% | Available tenures: 3, 6, 9, 12, 15, 18, 24 |
  | Cardless | Standard | TVS Credit | tvs | 3000 | 50000 | 27 | 12 | 4.72% | Available tenures: 3, 6, 9, 12, 15, 18, 24 |
  | Cardless | Standard | TVS Credit | tvs | 3000 | 50000 | 27 | 15 | 4.72% | Available tenures: 3, 6, 9, 12, 15, 18, 24 |
  | Cardless | Standard | TVS Credit | tvs | 3000 | 50000 | 27 | 18 | 4.72% | Available tenures: 3, 6, 9, 12, 15, 18, 24 |
  | Cardless | Standard | TVS Credit | tvs | 3000 | 50000 | 27 | 24 | 4.72% | Available tenures: 3, 6, 9, 12, 15, 18, 24 |
  | Cardless | Standard | Home Credit | homecredit | 4000 | 75000 | 25 | 3 | ₹299 + GST | - |
  | Cardless | Standard | Home Credit | homecredit | 4000 | 75000 | 25 | 6 | ₹299 + GST | - |
  | Cardless | Standard | ZestMoney | zestmoney | 3000 | 200000 | 20 | 3 | 1.75% | Bounce and late payment charges are provided in the KFS. Customers with an active credit line are eligible within the allocated limit. 3-month tenure is enabled for subvention cases only. |
  | Cardless | Standard | ZestMoney | zestmoney | 3000 | 200000 | 24.90 | 6 | 1.50% | Bounce and late payment charges are provided in the KFS. Customers with an active credit line are eligible within the allocated limit. |
  | Cardless | Standard | ZestMoney | zestmoney | 3000 | 200000 | 24.90 | 9 | 2.00% | Bounce and late payment charges are provided in the KFS. Customers with an active credit line are eligible within the allocated limit. |
</Accordion>

### Pay later providers

Customers can also make payments using the following pay later provider:

* Lazypay

| Provider parameter | Name of the provider |
| :- | :- |
| lazypay | LazyPay (applicable for orders with a minimum value of ₹100 and a maximum value of ₹5,000) |

<CodeGroup>
  ```curl lazypay request theme={"dark"}
  curl --request POST
      --url https://api.cashfree.com/pg/orders/sessions
      --header 'Accept: application/json'
      --header 'Content-Type: application/json'
      --data '{
      "payment_method": {
          "paylater":{
              "channel": "link",
              "provider": "lazypay",
              "phone": "999999999"
          }
      },
      "payment_session_id": "session_0_7R8dKzYmdby5xKkADpF8id7LgIZk3pv7faZ9-2v7s_cA34F2YKjVCSG4D8gOjzmlYFSgtn3q9txW3uKFC_IM5wE289t3137ITsZPqPynCB-ip8rCq6Y70_0Qwpayment"
  }'
  ```

  ```curl response (new customer) theme={"dark"}
  {
      "payment_method": "paylater",
      "channel": "link",
      "action": "link",
      "data": {
          "url": "https://prod.cashfree.com/pgnextgenapi-test/api/v1/view/gateway/FyQrZyVNFqABzPzbj9fJ389252b2c7b4e0b2e11380b550c81cc6",
          "payload": null,
          "content_type": null,
          "method": null
      },
      "cf_payment_id": 1316274816,
      "payment_amount": 1.00
  }
  ```

  ```curl response (repeat customer) theme={"dark"}
  {
      "payment_method": "paylater",
      "channel": "post",
      "action": "post",
      "data": {
          "url": "https://prod.cashfree.com/pgnextgenapi-test/api/v1/orders/pay/authenticate/1316030207",
          "payload": null,
          "content_type": "application/json",
          "method": "post"
      },
      "cf_payment_id": 1316030207,
      "payment_amount": 1.00
  }
  ```

  ```curl submit otp request theme={"dark"}
  curl --request POST \
       --url https://sandbox.cashfree.com/pg/orders/pay/authenticate/1111111 \
       --header 'accept: application/json' \
       --header 'content-type: application/json' \
       --header 'x-api-version: 2022-09-01' \
       --data '
  {
    "action": "SUBMIT_OTP",
    "otp": "1234"
  }
  '
  ```
</CodeGroup>

## Bank transfer

The Bank Transfer method lets customers pay using NEFT, RTGS, or IMPS to the Virtual Bank Account (VBA) provided by Cashfree. This method is ideal for B2B, education, real estate, and government transactions.

Customers must complete payments within the Time-to-Live (TTL) period that you set for the transaction. If you don't specify a TTL, it defaults to 5 days.

When a customer initiates a bank transfer, Cashfree validates the transaction against the order details, including the amount and account information (if TPV is enabled). If the details match, the payment is accepted, and you receive a notification to process the order. If the details don't match, the payment is rejected, and any debited amount is automatically refunded to the customer.

### Customer-specific bank transfer

By default, each Bank Transfer transaction is assigned a unique VBA. For recurring payments, Customer-Specific Bank Transfer assigns the same VBA to a customer to simplify repeat payments.
When a payment is received, Cashfree matches it to an active order with a pending transaction of the same amount and marks it as successful.


# Bank Transfers (Challans)
Source: https://www.cashfree.com/docs/payments/manage/payment-methods/bank-transfers

Accept IMPS, NEFT, and RTGS bank transfers via Cashfree virtual accounts with real-time reconciliation for B2B, education, and government collections.

Bank Transfers (Challans) let customers pay using NEFT, RTGS, or IMPS through a Virtual Bank Account (VBA) issued by Cashfree. This method is suited for B2B, education, real estate, and government transactions.

## How it works

For each order, Cashfree generates a unique VBA. The customer transfers funds to this VBA, and Cashfree validates the payment before confirming the order.

1. When an [order is created](/docs/api-reference/payments/latest/orders/create-order), Cashfree generates a unique VBA for the transaction.
2. The customer adds the VBA as a beneficiary in their bank and transfers the payment amount using IMPS, NEFT, or RTGS.
3. Cashfree validates the incoming transfer against the following:
   * Order amount
   * Account details (if [TPV (Third-Party Validation)](/docs/payments/features/tpv) is enabled)

If both details match, the payment is marked as successful and you receive a notification to fulfil the order. If the details do not match, the payment is rejected and the debited amount is automatically refunded to the customer.

## Time-to-live (TTL)

Each bank transfer order has a TTL, which is the window within which the customer must complete the payment. The default TTL is 5 days. To change the TTL for your account, contact [Cashfree Support](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1).

## Customer-specific bank transfer

By default, Cashfree generates a new VBA for every bank transfer transaction.

For recurring payment use cases, you can enable Customer-Specific Bank Transfer. This option provides the following benefits:

* The same VBA is reused for a customer across multiple transactions.
* Repeat payments are faster because the customer does not need to wait for a new beneficiary to be activated.

### How customer-specific bank transfer works

When this feature is enabled, Cashfree assigns a fixed VBA to each customer based on their phone number. Incoming payments are automatically matched to active orders with a pending transaction of the same amount.

1. A fixed VBA is assigned to the customer using the `customer_details.customer_phone` value provided during [order creation](/docs/api-reference/payments/latest/orders/create-order) or when creating a [payment link](/docs/payments/no-code/payment-link). The same phone number always maps to the same VBA.
2. When a payment is received on the customer's fixed VBA, Cashfree looks for an active order with a pending transaction matching the transferred amount.
3. If a match is found, the order is marked as successful.

### Enable customer-specific bank transfer

Customer-Specific Bank Transfer requires activation by the Cashfree team. Fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) to request Fixed VBA (Challan) for your account.

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/payments/latest/orders/create-order">Create Order API</a></li>
    <li><a href="/docs/api-reference/payments/latest/payment-links/create-payment-link">Create Payment Link API</a></li>
    <li><a href="/docs/payments/no-code/payment-link">Payment Links</a></li>
    <li><a href="/docs/payments/features/tpv">Third-Party Validation (TPV)</a></li>
  </ul>
</div>


# Cashfree Decrypts Apple Pay Using Cashfree's Apple Account
Source: https://www.cashfree.com/docs/payments/manage/payment-methods/credit-and-debit-cards/apple-pay/custom-checkout/cashfree-decrypts/no-account

Integrate Apple Pay on a custom web checkout with no Apple Developer account required, using Cashfree's own Apple credentials.

Cashfree manages all Apple Pay credentials, domain registration, and merchant validation on your behalf. You do not need an Apple Developer account. Cashfree also handles decryption and authorisation.

<Warning>
  This option is for web checkout only. If you need Apple Pay in an iOS app, you must have your own Apple Developer account. See [Cashfree Decrypts, Own Apple Account](/docs/payments/manage/payment-methods/credit-and-debit-cards/apple-pay/custom-checkout/cashfree-decrypts/own-account).
</Warning>

<Info>
  No PCI DSS compliance is required for decryption, and no Apple Developer account is required. Cashfree manages all Apple credentials and certificates.
</Info>

## Prerequisites

Before implementing Apple Pay with this option, ensure you meet the following requirements.

* HTTPS-enabled website.
* Valid SSL/TLS certificate.
* Technical capability to implement the Apple Pay JS SDK.

## Set up Apple Pay on the Cashfree Merchant Dashboard

Complete the following setup process on the Merchant Dashboard.

<Steps>
  <Step title="Add your checkout domains">
    1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
    2. Navigate to **Settings > Payment Methods > Apple Pay**.
    3. Select **Custom Checkout > Cashfree Decrypts > I don't have an Apple Developer Account**.
    4. Add all your checkout domains where you want to accept Apple Pay as a payment option, for example `checkout.yourstore.com`. You can add multiple domains; each is registered separately with Apple.
  </Step>

  <Step title="Host the domain verification file">
    1. Select **Download Verification File** in the Merchant Dashboard.
    2. Host the file at this exact path on each of your domains:

    ```text theme={"dark"}
    https://<YOUR_DOMAIN>/.well-known/apple-developer-merchantid-domain-association
    ```

    The file must be publicly accessible, with no login and no redirect, served over HTTPS. The path must match exactly; Apple does not accept variations.

    <Warning>
      Domain registration fails if the verification file is not accessible at the correct path. Ensure the file is live before selecting **Verify** in the next step.
    </Warning>
  </Step>

  <Step title="Verify your domain">
    1. Return to the Merchant Dashboard.
    2. Select **Activate**. Cashfree registers your domains with Apple, and Apple Pay is enabled for each of those domains.
  </Step>
</Steps>

<Note>
  If you add new checkout domains in future, repeat the file-hosting and verification steps for each new domain. Apple Pay does not work on unregistered domains.
</Note>

## Implement Apple Pay on web

Implement Apple Pay in your web application using the following JavaScript steps.

<Steps>
  <Step title="Check Apple Pay availability">
    ```javascript theme={"dark"}
    // Check if the Apple Pay JS API is available on this device/browser
    if (!window.ApplePaySession) {
      // Apple Pay not supported — hide button
      return;
    }

    // Check device capability
    if (!ApplePaySession.canMakePayments()) {
      // Device does not support Apple Pay
      return;
    }

    // Check if the customer has an active card in Wallet.
    // Use Cashfree's merchant identifier here.
    const merchantIdentifier = '<cashfree_merchant_identifier>';
    const status = await ApplePaySession.applePayCapabilities(merchantIdentifier);
    if (status.paymentCredentialStatus === 'paymentCredentialsAvailable') {
      document.getElementById('apple-pay-button').style.display = 'block';
    }
    ```
  </Step>

  <Step title="Load the Apple Pay button">
    ```html theme={"dark"}
    <!-- Include the Apple Pay JS SDK -->
    <script src="https://applepay.cdn-apple.com/jsapi/1.latest/apple-pay-sdk.js"></script>

    <!-- Render the Apple Pay button -->
    <apple-pay-button buttonstyle="black" type="buy" locale="en-IN"></apple-pay-button>
    ```
  </Step>

  <Step title="Create the payment request and initiate the session">
    ```javascript theme={"dark"}
    const paymentRequest = {
      countryCode: 'IN',
      currencyCode: 'INR',
      supportedNetworks: ['visa', 'masterCard', 'amex'],
      supportedCountries: ['IN'],
      merchantCapabilities: ['supports3DS', 'supportsCredit', 'supportsDebit'],
      total: {
        label: 'Your Store Name',
        amount: '100.00',
        type: 'final'
      }
    };
    const session = new ApplePaySession(3, paymentRequest);
    ```
  </Step>

  <Step title="Handle merchant validation through Cashfree">
    You must call Cashfree to handle the session request during merchant validation, as it requires Cashfree's Apple credentials.

    ```javascript theme={"dark"}
    session.onvalidatemerchant = async (event) => {
      // Call Cashfree's merchant validation API.
      // Cashfree handles the Apple session request on your behalf.
      const response = await fetch('https://api.cashfree.com/pg/applepay/validate-merchant', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          payment_session_id: '<payment_session_id>',
          validation_url: event.validationURL,
          domain_name: window.location.hostname
        })
      });
      const merchantSession = await response.json();
      session.completeMerchantValidation(merchantSession);
    };
    ```
  </Step>

  <Step title="Handle payment authorisation">
    After the customer authenticates with Face ID or Touch ID, Apple Pay fires the `onpaymentauthorized` event with the encrypted payment token. Pass the encrypted token to your server, then call the Cashfree [Authorisation Only API](/docs/api-reference/payments/latest/payments/order-pay-authorise-only) with the encrypted data. Cashfree decrypts it and processes authorisation on your behalf.

    ```javascript theme={"dark"}
    session.onpaymentauthorized = async (event) => {
      // Forward the encrypted token to Cashfree for decryption and authorisation.
      const response = await fetch('https://api.cashfree.com/pg/orders/sessions/pay', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          payment_session_id: '<payment_session_id>',
          encrypted_token: event.payment.token,
          transaction_type: 'APPLE_PAY'
        })
      });
      const result = await response.json();

      if (result.payment_status === 'SUCCESS') {
        session.completePayment(ApplePaySession.STATUS_SUCCESS);
      } else {
        session.completePayment(ApplePaySession.STATUS_FAILURE);
      }
    };

    session.begin();
    ```
  </Step>
</Steps>

## Decryption and authorisation via Cashfree

Pass the encrypted payment object received from Apple Pay to process the payment with Cashfree using the [Authorisation Only API](/docs/api-reference/payments/latest/payments/order-pay-authorise-only). Cashfree decrypts it and processes authorisation on your behalf.

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/payments/latest/payments/order-pay-authorise-only">Authorisation Only API</a></li>
    <li><a href="/docs/payments/manage/payment-methods/credit-and-debit-cards/apple-pay/custom-checkout/overview">Apple Pay Custom Checkout Overview</a></li>
    <li><a href="/docs/payments/manage/payment-methods/credit-and-debit-cards/apple-pay/custom-checkout/cashfree-decrypts/own-account">Cashfree Decrypts, Own Apple Account</a></li>
  </ul>
</div>


# Cashfree Decrypts Apple Pay Using Your Own Apple Account
Source: https://www.cashfree.com/docs/payments/manage/payment-methods/credit-and-debit-cards/apple-pay/custom-checkout/cashfree-decrypts/own-account

Integrate Apple Pay on a custom checkout where Cashfree handles decryption for you, using an Apple Developer account and Merchant ID you already own.

You manage the Apple Pay session and merchant validation using your own Apple credentials. Cashfree provides the Payment Processing Certificate, so it can decrypt the payment token on your behalf. This option supports both app and web checkout.

<Info>
  No PCI DSS compliance is required for decryption. Cashfree handles the decrypted payment data on your behalf.
</Info>

## Prerequisites

Before implementing Apple Pay with this option, ensure you meet the following requirements.

* Active Apple Developer Program membership.
* Registered Apple Merchant ID.
* HTTPS-enabled website or mobile application.
* Valid SSL/TLS certificate.
* Merchant Identity Certificate (web only), which you set up yourself.
* Technical capability to implement the Apple Pay SDK.

## Set up certificates with Apple and Cashfree

Complete the following setup process across your Apple Developer account and the Cashfree Merchant Dashboard.

<Steps>
  <Step title="Create Apple Merchant ID">
    1. Log in to your **Apple Developer account**.
    2. Navigate to **Certificates, Identifiers & Profiles > Identifiers**.
    3. Select **+** to create a new **Merchant ID**.
    4. Select **Merchant IDs** and select **Continue**.
    5. Enter a unique identifier and description.
    6. Select **Register** to create your **Merchant ID**.
  </Step>

  <Step title="Download the CSR from the Cashfree Merchant Dashboard">
    1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
    2. Navigate to **Settings > Payment Methods > Apple Pay**.
    3. Select **Custom Checkout > Cashfree Decrypts > I have my own Apple Developer Account**.
    4. Select **Download CSR**. Cashfree generates a unique CSR for your merchant account.
  </Step>

  <Step title="Upload the CSR to Apple and download the signed certificate">
    1. In your Apple Developer account, navigate to your **Merchant ID** settings.
    2. Find **Apple Pay Payment Processing Certificate > Create Certificate**.
    3. Upload the CSR file downloaded from the Merchant Dashboard.
    4. Download the signed certificate (`.cer` file) from Apple.
  </Step>

  <Step title="Upload the signed certificate to the Cashfree Merchant Dashboard">
    1. Return to the Merchant Dashboard.
    2. Upload the signed `.cer` file.
    3. Cashfree validates the certificate and activates Apple Pay for your account.
  </Step>

  <Step title="Set up the Merchant Identity Certificate (web only)">
    1. In your **Merchant ID** settings on the Apple Developer portal, find **Apple Pay Merchant Identity Certificate**.
    2. Select **Create Certificate**.
    3. Generate a CSR using OpenSSL:

    ```bash theme={"dark"}
    openssl req -new -newkey rsa:2048 -nodes -out merchant_id.csr -keyout merchant_id.key
    ```

    4. Upload the CSR to Apple, and download the signed certificate (`.cer` file).
    5. Install the Merchant Identity Certificate on your server. It is used for two-way TLS with Apple during merchant validation.
  </Step>

  <Step title="Register your domain (web only)">
    1. In your **Merchant ID** settings on the Apple Developer portal, navigate to **Merchant Domains**.
    2. Add your checkout domains where you want to accept Apple Pay as a payment option.
    3. Download the domain verification file from Apple.
    4. Host the file at this exact path on your domain:

    ```text theme={"dark"}
    https://<YOUR_DOMAIN>/.well-known/apple-developer-merchantid-domain-association
    ```

    5. Select **Verify** in the Apple Developer portal to register the domains with Apple.
  </Step>
</Steps>

## Implement Apple Pay on web and iOS

Implement Apple Pay using the following steps, depending on your platform.

<Tabs>
  <Tab title="Web">
    Implement Apple Pay in your web application using the following JavaScript steps:

    <Steps>
      <Step title="Check Apple Pay availability">
        ```javascript theme={"dark"}
        // Check if the Apple Pay JS API is available on this device/browser
        if (!window.ApplePaySession) {
          // Apple Pay not supported — hide button
          return;
        }

        // Check device capability
        if (!ApplePaySession.canMakePayments()) {
          // Device does not support Apple Pay
          return;
        }

        // Check if the customer has an active card in Wallet
        const merchantIdentifier = 'merchant.com.yourcompany';
        const status = await ApplePaySession.applePayCapabilities(merchantIdentifier);
        if (status.paymentCredentialStatus === 'paymentCredentialsAvailable') {
          document.getElementById('apple-pay-button').style.display = 'block';
        }
        ```
      </Step>

      <Step title="Load the Apple Pay button">
        ```html theme={"dark"}
        <!-- Include the Apple Pay JS SDK -->
        <script src="https://applepay.cdn-apple.com/jsapi/1.latest/apple-pay-sdk.js"></script>

        <!-- Render the Apple Pay button -->
        <apple-pay-button buttonstyle="black" type="buy" locale="en-IN"></apple-pay-button>
        ```
      </Step>

      <Step title="Create the payment request and initiate the session">
        ```javascript theme={"dark"}
        const paymentRequest = {
          countryCode: 'IN',
          currencyCode: 'INR',
          supportedNetworks: ['visa', 'masterCard', 'amex'],
          supportedCountries: ['IN'],
          merchantCapabilities: ['supports3DS', 'supportsCredit', 'supportsDebit'],
          total: {
            label: 'Your Store Name',
            amount: '100.00',
            type: 'final'
          }
        };
        const session = new ApplePaySession(3, paymentRequest);
        ```
      </Step>

      <Step title="Handle merchant validation">
        Your server calls Apple's merchant session API directly, using your own Merchant Identity Certificate over a two-way TLS connection.

        ```javascript theme={"dark"}
        session.onvalidatemerchant = async (event) => {
          // Call your own server to perform merchant validation.
          // Your server uses your Merchant Identity Certificate
          // to make a two-way TLS call to Apple's session API.
          const merchantSession = await fetch('/your-server/validate-merchant', {
            method: 'POST',
            body: JSON.stringify({ validationURL: event.validationURL })
          }).then(r => r.json());
          session.completeMerchantValidation(merchantSession);
        };
        ```
      </Step>

      <Step title="Handle payment authorisation">
        After the customer authenticates with Face ID or Touch ID, Apple Pay fires the `onpaymentauthorized` event with the encrypted payment token. Pass the encrypted token to your server, then call the Cashfree [Authorisation Only API](/docs/api-reference/payments/latest/payments/order-pay-authorise-only) with the encrypted data. Cashfree decrypts it and processes authorisation on your behalf.

        ```javascript theme={"dark"}
        session.onpaymentauthorized = async (event) => {
          // Forward the encrypted token to your server.
          // Your server forwards it to Cashfree for decryption and processing.
          const result = await fetch('/your-server/process-apple-pay', {
            method: 'POST',
            body: JSON.stringify({
              payment_session_id: '<payment_session_id>',
              encrypted_token: event.payment.token
            })
          }).then(r => r.json());

          if (result.payment_status === 'SUCCESS') {
            session.completePayment(ApplePaySession.STATUS_SUCCESS);
          } else {
            session.completePayment(ApplePaySession.STATUS_FAILURE);
          }
        };

        session.begin();
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="iOS">
    Integrate Apple Pay into your iOS application using Swift and the PassKit framework:

    <Steps>
      <Step title="Configure the Xcode project">
        1. Open your project in Xcode.
        2. Navigate to **Signing & Capabilities**.
        3. Add the **Apple Pay** capability.
        4. Select your **Merchant ID**. This is added as a signed entitlement to your app binary.
      </Step>

      <Step title="Check device compatibility">
        ```swift theme={"dark"}
        import PassKit

        if PKPaymentAuthorizationViewController.canMakePayments(
          usingNetworks: [.visa, .masterCard, .amex]) {
          // Show Apple Pay button
        }
        ```
      </Step>

      <Step title="Create the payment request">
        ```swift theme={"dark"}
        let request = PKPaymentRequest()
        request.merchantIdentifier = "merchant.com.yourcompany.app"
        request.supportedNetworks = [.visa, .masterCard, .amex]
        request.merchantCapabilities = .capability3DS
        request.countryCode = "IN"
        request.currencyCode = "INR"
        request.paymentSummaryItems = [
          PKPaymentSummaryItem(
            label: "Total",
            amount: NSDecimalNumber(string: "100.00")
          )
        ]
        ```
      </Step>

      <Step title="Handle payment authorisation">
        After the customer authenticates with Face ID or Touch ID, Apple Pay fires the payment authorization callback with the encrypted payment token. Pass the encrypted token to your server, then call the Cashfree [Authorisation Only API](/docs/api-reference/payments/latest/payments/order-pay-authorise-only) with the encrypted data. Cashfree decrypts it and processes authorisation on your behalf.

        ```swift theme={"dark"}
        func paymentAuthorizationController(
          _ controller: PKPaymentAuthorizationController,
          didAuthorizePayment payment: PKPayment,
          handler completion: @escaping (PKPaymentAuthorizationResult) -> Void) {
          // Forward the encrypted token to your server.
          // Your server sends it to Cashfree for decryption and authorisation.
          forwardTokenToCashfree(payment.token) { success in
            completion(PKPaymentAuthorizationResult(
              status: success ? .success : .failure,
              errors: nil
            ))
          }
        }
        ```
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Decryption and authorisation via Cashfree

Pass the encrypted payment object received from Apple Pay to process the payment with Cashfree using the [Authorisation Only API](/docs/api-reference/payments/latest/payments/order-pay-authorise-only). Cashfree decrypts it and processes authorisation on your behalf.

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/payments/latest/payments/order-pay-authorise-only">Authorisation Only API</a></li>
    <li><a href="/docs/payments/manage/payment-methods/credit-and-debit-cards/apple-pay/custom-checkout/overview">Apple Pay Custom Checkout Overview</a></li>
    <li><a href="/docs/payments/manage/payment-methods/credit-and-debit-cards/apple-pay/custom-checkout/cashfree-decrypts/no-account">Cashfree Decrypts, Cashfree's Apple Account</a></li>
  </ul>
</div>


# Merchant Decrypts Apple Pay
Source: https://www.cashfree.com/docs/payments/manage/payment-methods/credit-and-debit-cards/apple-pay/custom-checkout/merchant-decrypts

Integrate Apple Pay on a custom checkout where you manage decryption and merchant validation yourself, using your own Apple Developer account.

You manage the entire Apple Pay experience, including the eligibility check, payment sheet, merchant validation, and token decryption, on your own servers. You send the decrypted payment details to Cashfree only for authorisation.

<Warning>
  PCI DSS compliance is required to handle decrypted payment data. Ensure your infrastructure meets PCI DSS requirements before implementing this integration.
</Warning>

## Prerequisites

Before implementing Apple Pay with this option, ensure you meet the following requirements.

* Active Apple Developer Program membership.
* Registered Apple Merchant ID.
* HTTPS-enabled website or mobile application.
* Valid SSL/TLS certificate.
* PCI DSS compliance for handling decrypted payment data.
* Apple Pay Payment Processing Certificate.
* Merchant Identity Certificate (web only).
* Technical capability to implement the Apple Pay SDK.

## Set up your Apple Developer account

Complete the following setup process in your Apple Developer account.

<Steps>
  <Step title="Create Apple Merchant ID">
    1. Log in to your **Apple Developer account**.
    2. Navigate to **Certificates, Identifiers & Profiles > Identifiers**.
    3. Select **+** to create a new **Merchant ID**.
    4. Select **Merchant IDs** and select **Continue**.
    5. Enter a unique identifier and description.
    6. Select **Register** to create your **Merchant ID**.
  </Step>

  <Step title="Create payment processing certificate">
    1. In your **Merchant ID** settings, find **Apple Pay Payment Processing Certificate**.
    2. Select **Create Certificate**.
    3. Generate a CSR using OpenSSL:

    ```bash theme={"dark"}
    openssl ecparam -out apple_pay_private.key -name prime256v1 -genkey
    openssl req -new -sha256 -key apple_pay_private.key -out apple_pay.csr
    ```

    4. Upload the CSR file to Apple.
    5. Download the signed certificate (`.cer` file).
    6. Store the signed certificate and private key securely on your servers.
  </Step>

  <Step title="Create Merchant Identity Certificate (web only)">
    1. In your **Merchant ID** settings, find **Apple Pay Merchant Identity Certificate**.
    2. Select **Create Certificate**.
    3. Generate a CSR using OpenSSL:

    ```bash theme={"dark"}
    openssl req -new -newkey rsa:2048 -nodes -out merchant_id.csr -keyout merchant_id.key
    ```

    4. Upload the CSR file to Apple.
    5. Download the signed certificate (`.cer` file).
    6. Install this certificate on your server. It is used for two-way TLS when calling Apple's merchant session API.
  </Step>

  <Step title="Register your domain (web only)">
    1. In your **Merchant ID** settings, navigate to **Merchant Domains**.
    2. Add your checkout domains where you want to accept Apple Pay as a payment option.
    3. Download the domain verification file from Apple.
    4. Host the file at this exact path on your domain:

    ```text theme={"dark"}
    https://<YOUR_DOMAIN>/.well-known/apple-developer-merchantid-domain-association
    ```

    5. Select **Verify** in the Apple Developer portal to register the domains with Apple.
  </Step>
</Steps>

## Implement Apple Pay on web and iOS

Implement Apple Pay using the following steps, depending on your platform.

<Tabs>
  <Tab title="Web">
    Implement Apple Pay in your web application using the following JavaScript steps:

    <Steps>
      <Step title="Check Apple Pay availability">
        ```javascript theme={"dark"}
        // Check if the Apple Pay JS API is available on this device/browser
        if (!window.ApplePaySession) {
          // Apple Pay not supported — hide button
          return;
        }

        // Check device capability
        if (!ApplePaySession.canMakePayments()) {
          // Device does not support Apple Pay
          return;
        }

        // Check if the customer has an active card in Wallet
        const merchantIdentifier = 'merchant.com.yourcompany';
        const status = await ApplePaySession.applePayCapabilities(merchantIdentifier);
        if (status.paymentCredentialStatus === 'paymentCredentialsAvailable') {
          document.getElementById('apple-pay-button').style.display = 'block';
        }
        ```
      </Step>

      <Step title="Load the Apple Pay button">
        ```html theme={"dark"}
        <!-- Include the Apple Pay JS SDK -->
        <script src="https://applepay.cdn-apple.com/jsapi/1.latest/apple-pay-sdk.js"></script>

        <!-- Render the Apple Pay button -->
        <apple-pay-button buttonstyle="black" type="buy" locale="en-IN"></apple-pay-button>
        ```
      </Step>

      <Step title="Create the payment request and initiate the session">
        ```javascript theme={"dark"}
        const paymentRequest = {
          countryCode: 'IN',
          currencyCode: 'INR',
          supportedNetworks: ['visa', 'masterCard', 'amex'],
          supportedCountries: ['IN'],
          merchantCapabilities: ['supports3DS', 'supportsCredit', 'supportsDebit'],
          total: {
            label: 'Your Store Name',
            amount: '100.00',
            type: 'final'
          }
        };
        const session = new ApplePaySession(3, paymentRequest);
        ```
      </Step>

      <Step title="Handle merchant validation">
        Your server calls Apple's merchant session API directly, using your Merchant Identity Certificate over a two-way TLS connection.

        ```javascript theme={"dark"}
        session.onvalidatemerchant = async (event) => {
          // Call your own server to perform merchant validation.
          // Your server uses your Merchant Identity Certificate
          // to make a two-way TLS call to Apple's session API.
          const merchantSession = await fetch('/your-server/validate-merchant', {
            method: 'POST',
            body: JSON.stringify({ validationURL: event.validationURL })
          }).then(r => r.json());
          session.completeMerchantValidation(merchantSession);
        };
        ```
      </Step>

      <Step title="Handle payment authorisation">
        After the customer authenticates with Face ID or Touch ID, Apple Pay fires the `onpaymentauthorized` event with the encrypted payment token. Send the encrypted payment token to your server for decryption.

        ```javascript theme={"dark"}
        session.onpaymentauthorized = async (event) => {
          // Send the encrypted token to your server for decryption and Cashfree authorisation.
          const result = await fetch('/your-server/process-apple-pay', {
            method: 'POST',
            body: JSON.stringify({ token: event.payment.token })
          }).then(r => r.json());

          if (result.success) {
            session.completePayment(ApplePaySession.STATUS_SUCCESS);
          } else {
            session.completePayment(ApplePaySession.STATUS_FAILURE);
          }
        };

        session.begin();
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="iOS">
    Integrate Apple Pay into your iOS application using Swift and the PassKit framework:

    <Steps>
      <Step title="Configure the Xcode project">
        1. Open your project in Xcode.
        2. Navigate to **Signing & Capabilities**.
        3. Add the **Apple Pay** capability.
        4. Select your **Merchant ID** in the capabilities section. This is added as a signed entitlement to your app binary.
      </Step>

      <Step title="Check device compatibility">
        ```swift theme={"dark"}
        import PassKit

        if PKPaymentAuthorizationViewController.canMakePayments(
          usingNetworks: [.visa, .masterCard, .amex]) {
          // Show Apple Pay button
        }
        ```
      </Step>

      <Step title="Create the payment request">
        ```swift theme={"dark"}
        let request = PKPaymentRequest()
        request.merchantIdentifier = "merchant.com.yourcompany.app"
        request.supportedNetworks = [.visa, .masterCard, .amex]
        request.merchantCapabilities = .capability3DS
        request.countryCode = "IN"
        request.currencyCode = "INR"
        request.paymentSummaryItems = [
          PKPaymentSummaryItem(
            label: "Total",
            amount: NSDecimalNumber(string: "100.00")
          )
        ]
        ```
      </Step>

      <Step title="Handle payment authorisation">
        After the customer authenticates with Face ID or Touch ID, Apple Pay fires the payment authorization callback with the encrypted payment token. Send the encrypted payment token to your server for decryption.

        ```swift theme={"dark"}
        func paymentAuthorizationController(
          _ controller: PKPaymentAuthorizationController,
          didAuthorizePayment payment: PKPayment,
          handler completion: @escaping (PKPaymentAuthorizationResult) -> Void) {
          // Send the token to your server for decryption.
          // Your server decrypts it and calls the Cashfree authorisation API.
          processPaymentOnYourServer(payment.token) { success in
            completion(PKPaymentAuthorizationResult(
              status: success ? .success : .failure,
              errors: nil
            ))
          }
        }
        ```
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Decrypt on your server and authorise via Cashfree

Decrypt the Apple Pay token on your servers, following Apple's decryption specification.

```python theme={"dark"}
# Requires: your own Apple Pay decryption implementation, per Apple's specification
def decrypt_apple_pay_token(encrypted_token, private_key):
    # Extract payment data, verify signatures
    # Return decrypted payment details
    pass
```

After decryption, pass the decrypted fields to process the payment with Cashfree using the [Authorisation Only API](/docs/api-reference/payments/latest/payments/order-pay-authorise-only). Map the decrypted payment data fields received from Apple with the request payload for Cashfree's Authorisation Only API.

```bash theme={"dark"}
curl --request POST \
  --url https://api.cashfree.com/pg/orders/sessions/authorize \
  --header 'Content-Type: application/json' \
  --header 'x-api-version: 2026-01-01' \
  --data '{
    "payment_session_id": "<payment_session_id>",
    "authorization_data": {
      "authentication_token": "<onlinePaymentCryptogram from decrypted token>",
      "token_number": "<applicationPrimaryAccountNumber from decrypted token>",
      "token_expiry_year": "<expiry year, YY, from applicationExpirationDate>",
      "token_expiry_month": "<expiry month, MM, from applicationExpirationDate>",
      "eci": "<eciIndicator from decrypted token, if provided by wallet>",
      "transaction_type": "APPLE_PAY"
    }
  }'
```

## Enable on the Merchant Dashboard

Complete the following steps to enable Apple Pay for your Merchant ID at Cashfree.

<Steps>
  <Step title="Log in">
    Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
  </Step>

  <Step title="Navigate to Apple Pay settings">
    Navigate to **Settings > Payment Methods > Apple Pay**.
  </Step>

  <Step title="Select Merchant Decrypts">
    Select **Custom Checkout > Merchant Decrypts**.
  </Step>

  <Step title="Activate">
    Select **Activate**. Apple Pay gets enabled for your Merchant ID.
  </Step>
</Steps>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/payments/latest/payments/order-pay-authorise-only">Authorisation Only API</a></li>
    <li><a href="/docs/payments/manage/payment-methods/credit-and-debit-cards/apple-pay/custom-checkout/overview">Apple Pay Custom Checkout Overview</a></li>
    <li><a href="/docs/payments/manage/payment-methods/credit-and-debit-cards/apple-pay/custom-checkout/cashfree-decrypts/own-account">Cashfree Decrypts, Own Apple Account</a></li>
  </ul>
</div>


# Apple Pay Via Orchestrator
Source: https://www.cashfree.com/docs/payments/manage/payment-methods/credit-and-debit-cards/apple-pay/custom-checkout/orchestrator

Enable Apple Pay when you integrate through a payment orchestrator, and route authorisation for Apple Pay transactions to Cashfree.

If you are enabling Apple Pay through a payment orchestrator, contact your orchestrator to configure Apple Pay within their platform. Ensure that Cashfree is set up as the payment processor on the orchestrator's dashboard, and request that they enable Apple Pay routing through Cashfree.

Once you've set up the first leg of the flow, which is the eligibility check, loading the payment sheet, authentication, and payment data decryption, you can call Cashfree to perform the authorisation via your payment orchestrator.

## Enable on the Merchant Dashboard

Complete the following steps to enable Apple Pay for your Merchant ID at Cashfree.

<Steps>
  <Step title="Log in">
    Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
  </Step>

  <Step title="Navigate to Apple Pay settings">
    Navigate to **Settings > Payment Methods > Apple Pay**.
  </Step>

  <Step title="Select Merchant Decrypts">
    Select **Custom Checkout > Merchant Decrypts**.
  </Step>

  <Step title="Activate">
    Select **Activate**. Apple Pay gets enabled for your Merchant ID.
  </Step>
</Steps>

Ensure your orchestrator has set routing to Cashfree for processing authorisation on Apple Pay transactions. Your orchestrator passes decrypted payment data by calling the Cashfree [Authorisation Only API](/docs/api-reference/payments/latest/payments/order-pay-authorise-only).

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/payments/latest/payments/order-pay-authorise-only">Authorisation Only API</a></li>
    <li><a href="/docs/payments/manage/payment-methods/credit-and-debit-cards/apple-pay/custom-checkout/overview">Apple Pay Custom Checkout Overview</a></li>
    <li><a href="/docs/payments/manage/payment-methods/credit-and-debit-cards/apple-pay/custom-checkout/merchant-decrypts">Merchant Decrypts</a></li>
  </ul>
</div>


# Apple Pay Custom Checkout
Source: https://www.cashfree.com/docs/payments/manage/payment-methods/credit-and-debit-cards/apple-pay/custom-checkout/overview

Compare the different ways to add Apple Pay to a custom checkout, based on decryption and whether you need your own Apple Developer account.

Custom checkout gives you full control over the Apple Pay experience on your website or app. There are two ways to add Apple Pay to a custom checkout: integrate directly, or route through a payment orchestrator.

## Direct Integration

If you integrate directly, choose one of the following options based on your PCI DSS readiness, whether you already have an Apple Developer account, and which channels you need to support.

| | [Merchant Decrypts](/docs/payments/manage/payment-methods/credit-and-debit-cards/apple-pay/custom-checkout/merchant-decrypts) | [Cashfree Decrypts, Own Apple Account](/docs/payments/manage/payment-methods/credit-and-debit-cards/apple-pay/custom-checkout/cashfree-decrypts/own-account) | [Cashfree Decrypts, Cashfree's Apple Account](/docs/payments/manage/payment-methods/credit-and-debit-cards/apple-pay/custom-checkout/cashfree-decrypts/no-account) |
| - | - | - | - |
| Apple Developer account needed | Yes | Yes | No |
| PCI DSS compliance needed | Yes | No | No |
| Supported channels | App and web | App and web | Web only |
| Who handles decryption | You | Cashfree | Cashfree |
| Who handles merchant validation | You | You | Cashfree |
| Setup complexity | High | Medium | Low |

<Tip>
  If you are not PCI DSS compliant and want Cashfree to manage decryption, choose Cashfree Decrypts, Own Apple Account when you already have an Apple Developer account, or Cashfree Decrypts, Cashfree's Apple Account if you only need web checkout and want to use Cashfree's Apple credentials entirely.
</Tip>

## Via Payment Orchestrator

If you are enabling Apple Pay through a payment orchestrator, see [Orchestrator](/docs/payments/manage/payment-methods/credit-and-debit-cards/apple-pay/custom-checkout/orchestrator).

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/payments/latest/payments/order-pay-authorise-only">Authorisation Only API</a></li>
    <li><a href="/docs/payments/manage/payment-methods/credit-and-debit-cards/apple-pay/overview">Apple Pay Overview</a></li>
    <li><a href="/docs/payments/manage/payment-methods/credit-and-debit-cards/apple-pay/hosted-checkout">Apple Pay Hosted Checkout</a></li>
  </ul>
</div>


# Apple Pay Hosted Checkout
Source: https://www.cashfree.com/docs/payments/manage/payment-methods/credit-and-debit-cards/apple-pay/hosted-checkout

Enable Apple Pay on Cashfree-hosted checkout through both redirect checkout or pop-up and in-line checkout on your website or app.

Cashfree-hosted checkout uses Cashfree's pre-built checkout page, where customers can select Apple Pay as a payment option. Depending on how you render the checkout, choose one of the following flows.

<Tabs>
  <Tab title="Redirect checkout">
    This is the quickest way to enable Apple Pay for your customers. If you redirect to Cashfree-hosted checkout on `api.cashfree.com`, no additional integration work is required. Apple Pay is automatically displayed for eligible customers, and Cashfree ensures seamless processing of Apple Pay transactions.

    Redirect checkout offers the following benefits:

    * Minimal development effort: No Apple Pay-specific coding required.
    * Automatic updates: New Apple Pay features are automatically available.
    * Reduced maintenance: Cashfree manages certificates and compliance.
    * Enhanced security: All sensitive data handled by Cashfree's PCI-compliant infrastructure.

    ### Implement redirect checkout

    Follow these steps to implement Apple Pay with redirect checkout.

    <Steps>
      <Step title="Create an order">
        Create an order using the [Create Order API](/docs/api-reference/payments/latest/orders/create-order):

        ```bash theme={"dark"}
        curl -X POST 'https://api.cashfree.com/pg/orders' \
          -H 'Content-Type: application/json' \
          -H 'x-api-version: 2023-08-01' \
          -H 'x-client-id: <CLIENT_ID>' \
          -H 'x-client-secret: <CLIENT_SECRET>' \
          -d '{
            "order_id": "order_001",
            "order_amount": 100.00,
            "order_currency": "INR",
            "customer_details": {
              "customer_id": "customer_001",
              "customer_name": "John Doe",
              "customer_email": "john@example.com",
              "customer_phone": "+919876543210"
            }
          }'
        ```
      </Step>

      <Step title="Redirect to checkout">
        Redirect your customers to the checkout address returned in the order creation response. Apple Pay is automatically displayed for eligible customers.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Pop-up / in-line checkout">
    Since pop-up and in-line checkout render on your own domain, minimal setup is required to make Apple Pay work.

    ### Enable pop-up and in-line checkout

    <Steps>
      <Step title="Go to Payment Methods settings">
        Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and navigate to **Settings > Payment Methods**.
      </Step>

      <Step title="Open Apple Pay settings">
        Navigate to **Payment Methods > Apple Pay > Pop-Up/In-Line Checkout**.
      </Step>

      <Step title="Download the domain verification file">
        Select **Download Domain Verification File** on the Merchant Dashboard.
      </Step>

      <Step title="Host the domain verification file">
        Host the downloaded file at the following exact path on your domain:

        ```text theme={"dark"}
        https://<YOUR_DOMAIN>/.well-known/apple-developer-merchantid-domain-association
        ```
      </Step>

      <Step title="Enter your domains">
        Enter each domain where you want to enable Apple Pay as a payment option.
      </Step>

      <Step title="Activate">
        Select **Activate**. Cashfree registers your domains with Apple. On successful registration, Apple Pay gets enabled for you and is automatically displayed for eligible customers.
      </Step>
    </Steps>

    <Note>
      Apple Pay will not load on pop-up or in-line checkout until the domain verification file is hosted correctly.
    </Note>
  </Tab>
</Tabs>

See [Compatibility](/docs/payments/manage/payment-methods/credit-and-debit-cards/apple-pay/overview#compatibility) for the full list.

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/payments/latest/orders/create-order">Create Order API</a></li>
    <li><a href="/docs/payments/manage/payment-methods/credit-and-debit-cards/apple-pay/overview">Apple Pay Overview</a></li>
    <li><a href="/docs/payments/manage/payment-methods/credit-and-debit-cards/apple-pay/custom-checkout/overview">Apple Pay Custom Checkout</a></li>
  </ul>
</div>


# Apple Pay
Source: https://www.cashfree.com/docs/payments/manage/payment-methods/credit-and-debit-cards/apple-pay/overview

Accept Apple Pay payments for domestic and international cards through Cashfree-hosted checkout or custom checkout on your website or app.

Apple Pay provides a secure and seamless payment method that enables your customers to pay using their iPhone, iPad, Apple Watch, or Mac devices. Cashfree supports Apple Pay for both domestic and international cards. Learn how to implement Apple Pay with Cashfree based on your technical requirements and business needs.

<Card title="Apple Pay at checkout" icon="apple">
  <div>
    <img alt="Animated walkthrough of a customer selecting Apple Pay and completing payment at checkout" />
  </div>

  <p>
    Apple Pay checkout flow from payment selection to completion
  </p>
</Card>

## Benefits of Apple Pay

Offering Apple Pay at checkout gives customers a one-tap payment experience, which improves both payment success and checkout conversion.

* **Higher success rate**: Apple Pay authenticates with Face ID, Touch ID, or a device passcode and uses a device-specific token instead of card details, removing common failure points such as mistyped card numbers, expired OTPs, and retries.
* **Better conversion**: Checkout completes in a single tap, from cart to paid, with no card form and no OTP step, so customers spend less time between adding to cart and completing payment.
* **Saved card experience for first-time buyers**: Cards are saved in Apple Wallet at the device level rather than with an individual merchant, so customers get a saved-card checkout experience, with no manual typing, even on their first purchase with you.
* **Lower drop-offs**: Removing manual card entry, long checkout forms, and OTP authentication reduces the number of steps a customer needs to complete a payment, which lowers cart abandonment.

Cashfree offers the following methods to integrate Apple Pay:

* **Cashfree-hosted checkout**: Use Cashfree's pre-built checkout page where customers can select Apple Pay as a payment option. See [Hosted Checkout](/docs/payments/manage/payment-methods/credit-and-debit-cards/apple-pay/hosted-checkout).
* **Custom checkout**: Use your custom-built checkout and offer Apple Pay as a payment option, either through a direct integration or through a payment orchestrator. See [Custom Checkout](/docs/payments/manage/payment-methods/credit-and-debit-cards/apple-pay/custom-checkout/overview).

To enable Apple Pay for your customers, log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and navigate to **Settings > Payment Methods > Apple Pay**. You can also contact your Cashfree account manager or submit the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1).

## Compatibility

Apple Pay payment options work for customers using the following supported devices:

* iPhone with Touch ID or Face ID.
* iPad with Touch ID or Face ID.
* Apple Watch paired with eligible Apple devices.
* Mac with Touch ID or Mac paired with eligible Apple devices.
* Windows PC or third-party browsers by scanning a QR code from eligible Apple devices.

Apple Pay availability also depends on issuer support and the shopper's country or region. See Apple's resources for the latest details:

* [Countries and regions](https://support.apple.com/en-us/102775) where Apple Pay is available.
* [Issuers and participating banks](https://support.apple.com/en-us/109524) that support Apple Pay.
* [Supported devices and browsers](https://support.apple.com/en-us/102896) for Apple Pay on the web and in apps.

Apple Pay appears as a payment option when the shopper has added an eligible card to Apple Wallet and is using a compatible device and browser in a supported region.

## Best practices

Follow Apple's official guidance for both design and technical implementation when enabling Apple Pay. Ensure that the UI, button usage, flows, and web and app behaviours meet Apple's Human Interface Guidelines and implementation standards.

Also follow these practices for optimal Apple Pay implementation:

* Progressive enhancement: Show Apple Pay only when available.
* Clear labelling: Use Apple's official button designs and guidelines.
* Error handling: Provide clear feedback for failed transactions.
* Performance: Minimise steps between button tap and payment completion.

## Security and compliance

Apple Pay integration requires attention to security best practices and compliance requirements.

### Certificate management

* Apple Pay certificates expire every 25 months.
* Store private keys in hardware security modules when possible.
* Limit certificate access to authorised personnel only.

### Data protection

* Apple Pay uses device-specific tokens instead of actual card numbers.
* Transactions require Touch ID, Face ID, or device passcode.
* All communications use TLS encryption.

### Compliance

* PCI DSS compliance is required only for the Merchant Decrypts option under custom checkout, where you decrypt the payment data yourself. See [Custom Checkout](/docs/payments/manage/payment-methods/credit-and-debit-cards/apple-pay/custom-checkout/overview).
* Avoid storing Apple Pay tokens; they are single-use.
* Ensure compliance with local payment regulations.

## Troubleshooting

Review these common issues and their resolutions when implementing Apple Pay.

### Apple Pay button not appearing

* Verify device and browser compatibility.
* Check Apple Pay wallet has cards added.
* Ensure HTTPS is enabled on your domain.

### Certificate errors

* If you use your own Apple Developer account, regenerate the CSR from there.
* Verify the certificate has not expired (25-month validity).
* Ensure correct merchant ID association.

### Payment failures

* Check 3DS authentication requirements.
* Verify supported networks match customer's card.
* Validate payment amounts and currency codes.

### Error codes

| Error code | Description | Resolution |
| - | - | - |
| `INVALID_MERCHANT_ID` | Merchant ID not recognised | Verify Apple Pay configuration with Cashfree |
| `CERTIFICATE_EXPIRED` | Payment processing certificate expired | Renew certificate through Apple Developer portal |
| `UNSUPPORTED_DEVICE` | Device does not support Apple Pay | Guide customer to supported payment methods |

For additional support or questions about Apple Pay integration, contact the Cashfree support team through the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) or see the [Apple Pay API documentation](/docs/api-reference/payments/latest/payments/order-pay-authorise-only).

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/payments/latest/payments/order-pay-authorise-only">Authorisation Only API</a></li>
    <li><a href="/docs/payments/manage/payment-methods/credit-and-debit-cards/apple-pay/hosted-checkout">Apple Pay Hosted Checkout</a></li>
    <li><a href="/docs/payments/manage/payment-methods/credit-and-debit-cards/apple-pay/custom-checkout/overview">Apple Pay Custom Checkout</a></li>
    <li><a href="/docs/payments/manage/payment-methods/credit-and-debit-cards/google-pay">Google Pay</a></li>
  </ul>
</div>


# Google Pay
Source: https://www.cashfree.com/docs/payments/manage/payment-methods/credit-and-debit-cards/google-pay

Integrate Google Pay with Cashfree using Hosted checkout to accept tokenised (CRYPTOGRAM_3DS) and non-tokenised (PAN_ONLY) card payments.

Google Pay lets customers pay using a card stored in their Google Account, without re-entering card details. Cashfree supports Google Pay as a payment method on [Hosted checkout](/docs/payments/online/web/redirect) and the Dynamic Currency Conversion (DCC) screen.

Cashfree supports both Google Pay authentication methods:

* **`CRYPTOGRAM_3DS`** (tokenised): a card tokenised in Google Wallet. Google sends a DPAN (device Primary Account Number) and a one-time cryptogram instead of the raw card number. Cashfree doesn't apply additional 3D Secure (3DS) authentication solely because the payment came from Google Pay.
* **`PAN_ONLY`** (non-tokenised): a card saved to the customer's Google Account. Google sends the card's Primary Account Number (PAN) instead of a device token. Standard Cashfree card 3DS and step-up rules apply.

To enable Google Pay for your account, contact your Cashfree account manager or submit the [support form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1).

<Note>
  When you use Google Pay on Hosted checkout, you must adhere to the [Google Pay and Wallet API Acceptable Use Policy](https://payments.developers.google.com/terms/aup) and accept the [Google Pay API Terms of Service](https://payments.developers.google.com/terms/sellertos).
</Note>

## Integrating Google Pay

Cashfree currently offers Google Pay only through Hosted checkout. There's no separate Android or iOS SDK for merchants to integrate, and this requires no additional Google Pay-specific development work from you. If you use `api.cashfree.com`, create an order and redirect to checkout as you do today, and Cashfree processes Google Pay as part of the existing checkout flow.

Hosted checkout offers the following benefits:

* **Minimal development effort**: No Google Pay-specific coding required. You don't load the Google Pay JavaScript library, and you don't send the encrypted Google Pay token to Cashfree yourself.
* **Automatic updates**: New Google Pay features are automatically available.
* **Reduced maintenance**: Cashfree manages certificates, decryption, and compliance.
* **Enhanced security**: All sensitive data is handled by Cashfree's **PCI-compliant** infrastructure.

For Hosted checkout branding and reviewer context, see Google's own references:

* [Google Pay Web developer documentation](https://developers.google.com/pay/api/web/overview)
* [Google Pay Web integration checklist](https://developers.google.com/pay/api/web/guides/test-and-deploy/integration-checklist)
* [Google Pay Web brand guidelines](https://developers.google.com/pay/api/web/guides/brand-guidelines)

Follow these steps to implement Google Pay with Hosted checkout:

<Steps>
  <Step title="Create an order">
    Create an order using the [Create Order API](/docs/api-reference/payments/latest/orders/create-order):

    ```bash theme={"dark"}
    curl -X POST 'https://api.cashfree.com/pg/orders' \
      -H 'Content-Type: application/json' \
      -H 'x-api-version: 2026-01-01' \
      -H 'x-client-id: YOUR_CLIENT_ID' \
      -H 'x-client-secret: YOUR_CLIENT_SECRET' \
      -d '{
        "order_id": "order_001",
        "order_amount": 100.00,
        "order_currency": "INR",
        "customer_details": {
          "customer_id": "customer_001",
          "customer_name": "John Doe",
          "customer_email": "john@example.com",
          "customer_phone": "+919876543210"
        }
      }'
    ```
  </Step>

  <Step title="Redirect to checkout">
    Redirect your customers to the checkout URL returned in the order creation response. Google Pay is automatically displayed for eligible users on Hosted checkout and, where applicable, on the DCC screen.
  </Step>
</Steps>

## How it works

A Google Pay payment on Hosted checkout follows these steps:

1. The customer selects Google Pay on Hosted checkout or the DCC screen.
2. The customer confirms the payment in the Google Pay sheet and chooses a saved card.
3. Google returns an encrypted payment token to the page, scoped to Cashfree as the processor. The encrypted payload is in `paymentMethodData.tokenizationData.token`. Merchants using Hosted checkout never receive or forward this token.
4. Cashfree decrypts and validates the token.
5. Cashfree authorises the payment with the card network and issuing bank:
   * For `CRYPTOGRAM_3DS`, Cashfree uses the tokenised card (DPAN) and cryptogram.
   * For `PAN_ONLY`, Cashfree applies the same risk-based 3DS (step-up) criteria used for normal card transactions. The customer may be asked to complete 3DS when those criteria require it.
6. The customer sees the payment result on the same page. No redirect to a separate wallet app is required, except when 3DS is triggered for a `PAN_ONLY` payment.

## Gateway configuration

On Hosted checkout, merchants don't configure Google Pay themselves. Cashfree uses the Google Pay API `PAYMENT_GATEWAY` integration type and decrypts on your behalf, with the following processor configuration:

| Parameter | Value |
| - | - |
| `gateway` | `cashfree` |
| `gatewayMerchantId` | `cashfree` |
| `allowedAuthMethods` | `["CRYPTOGRAM_3DS", "PAN_ONLY"]` |
| `allowedCardNetworks` | `VISA`, `MASTERCARD`, `AMEX` |

`gateway` is the gateway ID registered with Google during Cashfree's technical onboarding. `gatewayMerchantId` is Cashfree's shared Google Pay processor ID. It isn't a per-merchant MID, and you don't need to configure it.

Cashfree uses the following configuration in the Google Pay `TokenizationSpecification` object:

```json theme={"dark"}
"tokenizationSpecification": {
  "type": "PAYMENT_GATEWAY",
  "parameters": {
    "gateway": "cashfree",
    "gatewayMerchantId": "cashfree"
  }
}
```

Hosted checkout doesn't require merchants to request a Google Pay billing address (`billingAddressRequired`). Address collection, where needed (for example, address verification checks on the DCC screen), follows Cashfree's existing checkout fields, not Google Pay `BillingAddressParameters`.

## Supported authentication methods

Cashfree supports both Google Pay authentication methods:

| Authentication method | Support | 3DS | What it means |
| - | - | - | - |
| `CRYPTOGRAM_3DS` (tokenised) | Supported | No extra 3DS solely because it's Google Pay. Authentication is in the cryptogram. | A card tokenised in Google Wallet. Cashfree receives a DPAN, a cryptogram, and an optional ECI (Electronic Commerce Indicator), then authorises it as a tokenised card payment. |
| `PAN_ONLY` (non-tokenised) | Supported | Yes, the same risk-based 3DS and step-up rules as a normal card. | A card saved to the customer's Google Account, not a device token. Cashfree decrypts the PAN and applies the same risk-based 3DS and step-up rules used for normal card transactions. |

Customers can pay with either:

* a card enrolled for tokenised payments in Google Wallet (`CRYPTOGRAM_3DS`), or
* a card saved to their Google Account (`PAN_ONLY`).

### 3D Secure (step-up) for PAN\_ONLY

`PAN_ONLY` payloads aren't treated as already-authenticated device tokens. Cashfree applies its existing criteria to selectively trigger 3DS (step-up authentication) for Google Pay `PAN_ONLY` transactions, based on the same risk rules used for normal card transactions.

* **`CRYPTOGRAM_3DS`**: processed as a tokenised wallet payment using the cryptogram. Cashfree doesn't apply additional 3DS solely because the payment came from Google Pay.
* **`PAN_ONLY`**: processed like a regular card. If Cashfree's risk rules would step up a normal card payment, the same step-up applies here. Merchants don't turn this on separately. It follows the 3DS settings already configured on the Cashfree account for cards.

Merchants using Hosted checkout don't need to implement a separate 3DS integration for Google Pay. Cashfree handles this in the checkout flow.

## Device and browser compatibility

Google Pay is shown automatically for customers using a supported configuration:

* HTTPS checkout.
* A supported browser on desktop, Android, or iOS, with Google Pay available (Chrome, Safari, Firefox, or Edge).
* A Google Account with at least one eligible card:
  * a tokenised card in Google Wallet (`CRYPTOGRAM_3DS`), or
  * a card saved to the Google Account (`PAN_ONLY`).

Tokenised cards (`CRYPTOGRAM_3DS`) are available only in markets and on devices where Google Wallet tokenisation is supported. `PAN_ONLY` can still be offered where a card is saved to the Google Account. Settlement follows the merchant's Cashfree account, typically India for Cashfree PG merchants.

## Testing

Test Google Pay in Cashfree's sandbox the same way as other Hosted checkout methods:

1. Create the order against the sandbox API with sandbox credentials.
2. Open the sandbox Hosted checkout URL returned in the response.
3. Complete Google Pay using a Google Account that has at least one test or eligible card.

Sandbox uses Google Pay's `TEST` environment, and production Hosted checkout uses Google Pay's production environment. You don't pass a Google Pay `environment` field in the Create Order API.

## Security and compliance

### Data protection

Cashfree protects Google Pay transaction data as follows:

* Google returns an encrypted payment token to Cashfree. The merchant never receives the raw PAN, DPAN, or cryptogram.
* Cashfree decrypts and validates the payload centrally. The encrypted token is never exposed to or stored by the merchant.
* For `CRYPTOGRAM_3DS`, Google Pay returns a tokenised card number and cryptogram instead of the raw card number.
* For `PAN_ONLY`, Cashfree decrypts the payload and processes it under the same card security and 3DS controls as a normal card payment.
* All communications use TLS encryption.

### Compliance

Enabling Google Pay has the following compliance implications for your integration:

* Enabling Google Pay on Hosted checkout doesn't add PCI DSS scope to your integration, because Cashfree handles decryption and validation.
* Ensure compliance with local payment regulations applicable to your business, including 3DS and Strong Customer Authentication requirements where they apply. Cashfree applies its existing card 3DS rules to `PAN_ONLY` transactions.
* Using Google Pay on Hosted checkout is subject to the Google Pay Acceptable Use Policy and Terms of Service referenced earlier in this topic.

## Troubleshooting

### Google Pay option not appearing

If Google Pay doesn't appear as a payment option for a customer, check the following:

* Verify the customer's browser and device are supported and Google Pay is set up.
* Confirm the customer has at least one eligible card in their Google Account, either a tokenised Wallet card, a saved card, or both.
* Ensure HTTPS is enabled on your checkout domain.
* Confirm Google Pay is enabled on your Cashfree account.

### Payment failures

The following scenarios cause a Google Pay payment to fail:

| Scenario | What happens |
| - | - |
| Token fails signature or decryption validation | Payment fails immediately; no authorisation request is sent. |
| Token has expired | Payment fails validation before authorisation. |
| `PAN_ONLY` payment requires 3DS based on risk | The customer is asked to complete 3DS, same as a normal card. If they cancel or fail 3DS, the payment fails. |
| Card network or issuer declines the authorisation | Standard decline response, same as any other card payment. |

## Best practices

* **Progressive enhancement**: Google Pay is shown automatically only to eligible customers. No additional logic is required on your side.
* **Clear labelling**: Hosted checkout uses Google's official Google Pay button assets and [brand guidelines](https://developers.google.com/pay/api/web/guides/brand-guidelines).
* **Error handling**: Provide clear feedback for failed transactions, with a fallback to other payment methods.
* **Receipts**: Show Google Pay as the payment method on success pages and notifications, without printing full card details.

For additional support or questions about Google Pay integration, contact the Cashfree support team through the [support form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) or see the [Payment Gateway API Overview](/docs/api-reference/payments/latest/overview).

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/payments/latest/orders/create-order">Create Order API</a></li>
    <li><a href="/docs/api-reference/payments/latest/overview">Payment Gateway API Overview</a></li>
  </ul>
</div>


# Overview
Source: https://www.cashfree.com/docs/payments/manage/payment-methods/credit-and-debit-cards/overview

Accept credit and debit card payments on Cashfree across Visa, Mastercard, Rupay, American Express, and Diners with tokenisation, EMI, and CVV-less options.

Cards are a common way for consumers and businesses to pay online or in person. Cashfree supports global and local card networks. See the card brands that Cashfree supports.

You can accept payments from your customers using debit or credit cards from all international providers. Check the various capabilities we offer with Cards:

<CardGroup>
  <Card icon="lock" title="3D Secure 2.0">
    Enhanced security protocol that provides real-time risk assessment and
    authentication for online transactions.
  </Card>

  <Card icon="bolt" title="CVV less flow">
    Remove the need for entering the CVV for cards saved with Cashfree
  </Card>

  <Card icon="cc-visa" title="Save Cards">
    Securely store and tokenise cards in a PCI-compliant vault
  </Card>

  <Card icon="command" title="Recurring Payments">
    Automated billing system for subscriptions and recurring charges with
    flexible scheduling options.
  </Card>

  <Card icon="apple" title="Apple Pay Payments">
    Seamless Apple Pay-based card payments for eligible cards and transactions
  </Card>

  <Card icon="google" title="Google Pay Payments">
    Tokenised card payments through Google Pay using CRYPTOGRAM\_3DS authentication
  </Card>

  <Card icon="lock" title="Credit Card EMI">
    Support for EMI payments on credit cards with more than 10 banks.
  </Card>
</CardGroup>

We support the following card networks.

<CardGroup>
  <Card title="Visa" icon="cc-visa" />

  <Card title="Rupay" icon="credit-card-blank" />

  <Card title="Mastercard" icon="cc-mastercard" />

  <Card title="American Express" icon="cc-amex" />

  <Card title="Diners" icon="cc-diners-club" />
</CardGroup>


# Netbanking
Source: https://www.cashfree.com/docs/payments/manage/payment-methods/netbanking

Accept netbanking payments on Cashfree from major Indian banks with a streamlined checkout, real-time status updates, and dashboard tools to monitor it.

Cashfree can accept payments from your customers using Netbanking. This method is available by default. You can view which all net banking banks are enabled for your account in the **[Merchant Dashboard](https://merchant.cashfree.com/auth/login)**.

<Tip>Explore [Banking Connect](/docs/payments/features/banking-connect) for an enhanced Netbanking experience powered by NBBL, offering mobile-first customer journeys and seamless payment flows.</Tip>

```mermaid theme={"dark"}
sequenceDiagram
    autonumber
    actor Customer
    Merchant-->>Cashfree: Payment Initiation
    Merchant -->> Customer: Payment Initiation Response
    Customer -->> Bank: Redirect to Bank
    Bank -->> Cashfree: Payment Result
    Cashfree -->> Merchant: Payment Result
```

<br />

<Accordion title="List of Netbanking with codes and TPV supported flags">
  For testing purposes in sandbox mode merchant can use below bank code
  "customer\_bank\_code": 3333

  | Bank name | Code | TPV\_Supported | Bank code |
  | - | - | :-: | - |
  | Airtel Payments Bank | 3123 | No | AIRPR |
  | Andhra Pragathi Grameena Bank | 3094 | No | APGBR |
  | AU Small Finance Bank | 3087 | Yes | AUBLR |
  | Axis Bank | 3003 | Yes | UTIBR |
  | Axis Bank - Corporate | 3071 | No | UTIBC |
  | Bandhan Bank - Retail Banking | 3088 | Yes | BDBLR |
  | Bank of Bahrain and Kuwait | 3095 | No | BBKMR |
  | Bank of Baroda - Corporate | 3060 | Yes | BARBC |
  | Bank of Baroda - Retail Banking | 3005 | Yes | BARBR |
  | Bank of India | 3006 | Yes | BKIDR |
  | Bank of India - Corporate | 3061 | Yes | BKIDC |
  | Bank of Maharashtra | 3007 | No | MAHBR |
  | Barclays - Corporate | 3080 | No | BARCC |
  | Canara Bank | 3009 | Yes | CNRBR |
  | Capital Small Finance Bank | 3098 | Yes | CLBLR |
  | Central Bank of India | 3011 | No | CBINR |
  | City Union Bank | 3012 | Yes | CIUBR |
  | City Union Bank - Corporate | 3083 | Yes | CIUBC |
  | Cosmos Bank | 3097 | Yes | COSBR |
  | CSB Bank Limited | 3010 | Yes | CSBKR |
  | DBS Bank Ltd | 3017 | No | DBSSR |
  | DCB Bank - Retail | 3018 | Yes | DCBLR |
  | Deutsche Bank | 3016 | Yes | DEUTR |
  | Dhanlakshmi Bank | 3019 | Yes | DLXBR |
  | Dhanlaxmi Bank - Corporate | 3072 | No | DLXBC |
  | Equitas Small Finance Bank | 3076 | No | ESFBR |
  | ESAF Small Finance Bank | 3100 | No | ESMFR |
  | Federal Bank | 3020 | Yes | FDRLR |
  | Fincare Bank | 3101 | No | FSFBR |
  | Gujarat State Co-operative Bank Limited | 3091 | No | GSCBR |
  | HDFC Bank | 3021 | Yes | HDFCR |
  | HDFC Corporate | 3084 | No | HDFCC |
  | ICICI Bank | 3022 | Yes | ICICR |
  | ICICI Bank - Corporate | 3073 | No | ICICC |
  | IDBI Bank | 3023 | Yes | IBKLR |
  | IDBI Bank - Corporate | 3124 | Yes | IBKLC |
  | IDFC FIRST Bank | 3024 | Yes | IDFBR |
  | Indian Bank | 3026 | Yes | IDIBR |
  | Indian Overseas Bank | 3027 | Yes | IOBAR |
  | Indian Overseas Bank - Corporate | 3081 | Yes | IOBAC |
  | IndusInd Bank | 3028 | Yes | INDBR |
  | Jammu and Kashmir Bank | 3029 | Yes | JAKAR |
  | Jana Small Finance Bank | 3102 | Yes | JSFBR |
  | Janata Sahakari Bank Ltd Pune | 3104 | No | JSBPR |
  | Kalyan Janata Sahakari Bank | 3105 | No | KJSBR |
  | Karnataka Bank Ltd | 3030 | Yes | KARBR |
  | Karnataka Gramin Bank | 3113 | No | PKGBR |
  | Karnataka Vikas Grameena Bank | 3107 | No | KVGBR |
  | Karur Vysya Bank | 3031 | Yes | KVBLR |
  | Kotak Mahindra Bank | 3032 | Yes | KKBKR |
  | Kotak Mahindra Bank - Corporate | 3134 | Yes | KKBKC |
  | Maharashtra Gramin Bank | 3108 | No | MAHGR |
  | Mehsana urban Co-op Bank | 3109 | No | MSNUR |
  | NKGSB Co-op Bank | 3111 | No | NKGSR |
  | Nutan Nagarik Sahakari Bank Limited | 3112 | No | NNSBR |
  | Punjab & Sind Bank | 3037 | Yes | PSIBR |
  | Punjab National Bank - Corporate | 3065 | No | PUNBC |
  | Punjab National Bank - Retail Banking | 3038 | Yes | PUNBR |
  | RBL Bank | 3039 | Yes | RATNR |
  | RBL Bank Limited - Corporate | 3114 | No | RATNC |
  | Saraswat Bank | 3040 | Yes | SRCBR |
  | SBM Bank India | 3115 | Yes | STCBR |
  | Shamrao Vithal Bank - Corporate | 3075 | No | SVCBC |
  | Shamrao Vitthal Co-operative Bank | 3041 | No | SVCBR |
  | Shivalik Small Finance Bank | 3086 | Yes | SMCBR |
  | South Indian Bank | 3042 | Yes | SIBLR |
  | Standard Chartered Bank | 3043 | Yes | SCBLR |
  | State Bank Of India | 3044 | Yes | SBINR |
  | State Bank of India - Corporate | 3066 | Yes | SBINC |
  | Suryoday Small Finance Bank | 3116 | No | SURYR |
  | Tamil Nadu State Co-operative Bank | 3051 | No | TNSCR |
  | Tamilnad Mercantile Bank Ltd | 3052 | Yes | TMBLR |
  | Thane Bharat Sahakari Bank Ltd | 3118 | No | TBSBR |
  | The Kalupur Commercial Co-Operative Bank | 3106 | No | KCCBR |
  | The Surat Peoples Co-operative Bank Ltd | 3090 | Yes | SPCBR |
  | The Sutex Co-op Bank Ltd | 3117 | Yes | SUTBR |
  | TJSB Bank | 3119 | No | TJSBR |
  | UCO Bank | 3054 | Yes | UCBAR |
  | UCO Bank Corporate | 3122 | No | UCBAC |
  | Ujjivan Small Finance Bank | 3126 | Yes | UJVNR |
  | Union Bank of India | 3055 | Yes | UBINR |
  | Union Bank of India - Corporate | 3067 | Yes | UBINC |
  | Utkarsh Small Finance Bank | 3089 | Yes | UTKSR |
  | Varachha Co-operative Bank Limited | 3120 | No | VARAR |
  | Yes Bank - Corporate | 3077 | No | YESBC |
  | Yes Bank Ltd | 3058 | Yes | YESBR |
  | Zoroastrian Co-Operative Bank Ltd | 3121 | No | ZCBLR |
</Accordion>


# Payment Methods
Source: https://www.cashfree.com/docs/payments/manage/payment-methods/overview

Explore the payment methods supported by Cashfree Payment Gateway, including cards, UPI, netbanking, bank transfers, wallets, and pay-later integrations.

The sections below explain how to integrate each payment method category on the [Payment Gateway](/docs/payments/overview). To enable, configure, or check eligibility, see [Manage payment methods](#manage-payment-methods).

<Tip>Payment methods in the same category follow a similar integration flow. Once you integrate one method, you can enable others in the same category with minimal configuration changes.</Tip>

## Supported payment methods

Payment methods are grouped into six categories. Each category has different capabilities and integration requirements.

<CardGroup>
  <Card title="Cards" icon="credit-card" href="/docs/payments/manage/payment-methods/credit-and-debit-cards/overview">
    Support for Indian and international cards, and Apple Pay.
  </Card>

  <Card title="UPI" icon="qrcode" href="/docs/payments/manage/payment-methods/upi">
    Support for UPI intent, QR, and collect flows.
  </Card>

  <Card title="Netbanking" icon="building-columns" href="/docs/payments/manage/payment-methods/netbanking">
    Support for more than 50 major Indian banks.
  </Card>

  <Card title="Bank transfer" icon="money-bill-transfer" href="/docs/payments/manage/payment-methods/bank-transfers">
    Support for NEFT, RTGS, and IMPS bank transfers.
  </Card>

  <Card title="Wallets" icon="wallet" href="/docs/payments/manage/payment-methods/wallets">
    Support for digital wallets including PhonePe, Amazon Pay, and MobiKwik.
  </Card>

  <Card title="Pay Later and cardless EMI" icon="hand-holding-dollar" href="/docs/payments/manage/payment-methods/paylaters-and-cardless-emis">
    Support for cardless EMI and Pay Later methods.
  </Card>
</CardGroup>

## Manage payment methods

You can enable, disable, and configure payment methods based on your business requirements.

<Tabs>
  <Tab title="Dashboard">
    You can manage all enabled payment modes directly from the Merchant Dashboard. To manage payment methods, follow these steps:

    1. Log in to the **[Merchant Dashboard](https://merchant.cashfree.com/auth/login)**.
    2. Go to **Settings > Payment Gateway > Payment Methods**.
    3. View all active payment modes.
    4. To enable a new payment mode, select **Request** and follow the on-screen instructions.

    <img alt="Animated walkthrough of requesting a new payment mode from the Merchant Dashboard" />
  </Tab>

  <Tab title="API">
    Use the Cashfree APIs to manage and check [payment method eligibility](/docs/payments/manage/payment-method-eligibility) for specific orders.

    ### Eligibility API

    Before displaying the checkout page, use the [Get Eligible Payment Methods API](/docs/api-reference/payments/latest/eligibility/get-eligible-payment-methods) to identify the payment methods available for a specific customer or order amount.

    | API endpoint | Description | Documentation |
    | :- | :- | :- |
    | `/eligibility/payment_methods` | Identify eligible payment methods for an order. | [Get Eligible Payment Methods API](/docs/api-reference/payments/latest/eligibility/get-eligible-payment-methods) |
    | `/eligibility/cardless_emi` | Check eligibility for cardless EMI. | [Get Eligible Cardless EMI Payment Methods API](/docs/api-reference/payments/latest/eligibility/get-eligible-cardless-emi-payment-methods-for-a-customer-on-an-order) |
  </Tab>
</Tabs>

## Advanced payment features

The following features depend on the payment method and may require additional configuration:

* **[International payments](/docs/payments/international-payments/ipg/overview):** Accept payments in more than 140 currencies using international cards.
* **[Recurring payments](/docs/payments/subscription/introduction):** Set up recurring payments and subscriptions through UPI mandates, card tokenisation, and Netbanking e-mandates.
* **[Pre-authorisation](/docs/payments/features/pre-authorisation):** Reserve funds on a card before fulfilment and capture them once the order is confirmed.
* **[Third-party validation (TPV)](/docs/payments/features/tpv):** Verify that payments originate from authorised bank accounts for Netbanking and UPI transactions.

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/payments/latest/overview">Payment Gateway API overview</a></li>
    <li><a href="/docs/payments/online/resources/payment-lifecycle">Payment Lifecycle</a></li>
    <li><a href="/docs/payments/general-faqs">General FAQs</a></li>
  </ul>
</div>


# Paylater and Cardless EMIs
Source: https://www.cashfree.com/docs/payments/manage/payment-methods/paylaters-and-cardless-emis

Offer pay-later and cardless EMI options at Cashfree checkout, including LazyPay, Simpl, and EMI partners, to improve affordability and lift order conversion.

Cashfree supports payment options with EMI and Pay Later methods. Seamlessly integrate Cashfree's platform to offer a range of credit and debit card EMIs, along with diverse Pay Later providers, enhancing the checkout experience.

For custom or server-to-server (S2S) checkouts, Cashfree supports Credit Card EMI, Debit Card EMI, Cardless EMI, and Pay Later/BNPL. You can use the Payment Methods Eligibility APIs to determine which modes are available for a specific order or customer. These payment modes must be activated for your merchant account before use. Contact your Account Manager or submit a [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) to activate them.

### Credit card EMI

Cashfree supports Credit Card EMI payment method. You can use different EMI providers on our platform. Below is a list of supported providers and their payment codes for a seamless flow. If you are using a Cashfree hosted integration, we will automatically show all these options to eligible users on the checkout page.

Here is a sample of the request that you need to send to `/orders/sessions` to process a seamless EMI payment. [Read more here](/docs/api-reference/payments/latest/payments/order-pay).

```javascript theme={"dark"}

{	      "payment_session_id":"session_mdCizuqcgJWbIhdJ4rjONvpCB1B31muN7Tev9p2kdlEQpj9mem5yF5gbUju4kdgN6-31FJnGK3yaEcqG0GZUsrbzOLDFPfA30iYduwiNmBk",
"payment_method" : {
		"emi": {
			"channel": "link",
			"card_number": "4111111111111111",
			"card_expiry_mm": "12",
			"card_expiry_yy": "22",
			"card_cvv": "123",
			"card_bank_name": "hdfc",
			"emi_tenure": 3
		}
	}
}

```

We support varying tenures for each of these: 3, 6, 9, 12, 14, 18, 24, 36, 48 depending on the issuing bank.

<Accordion title="The following card issuers are supported for card-based EMIs.">
  Please send the exact values in the `card_bank_name` parameter. We support varying tenures for each of these: 3, 6, 9, 12, 14, 18, 24, 36, 48 depending on the issuing bank.

  ### Credit card EMI plans

  | Card type | Type of EMI | Bank | card\_bank\_name | Minimum amount | Maximum amount | Annual interest rate | Tenure | Processing fees | Remarks |
  | - | - | - | - | - | - | - | - | - | - |
  | Credit | Standard | ICICI Bank | icici | 1500 | 9999999 | 15.99 | 3 | 2.99% + GST, maximum up to ₹299 + GST | - |
  | Credit | Standard | ICICI Bank | icici | 1500 | 9999999 | 15.99 | 6 | 2.99% + GST, maximum up to ₹299 + GST | - |
  | Credit | Standard | ICICI Bank | icici | 1500 | 9999999 | 15.99 | 9 | 2.99% + GST, maximum up to ₹299 + GST | - |
  | Credit | Standard | ICICI Bank | icici | 1500 | 9999999 | 15.99 | 12 | 2.99% + GST, maximum up to ₹299 + GST | - |
  | Credit | Standard | ICICI Bank | icici | 1500 | 9999999 | 15.99 | 18 | 2.99% + GST, maximum up to ₹299 + GST | - |
  | Credit | Standard | ICICI Bank | icici | 1500 | 9999999 | 15.99 | 24 | 2.99% + GST, maximum up to ₹299 + GST | - |
  | Credit | Standard | AU Small Finance Bank | au | 2000 | - | 14 | 3 | ₹199 + GST | - |
  | Credit | Standard | AU Small Finance Bank | au | 2000 | - | 14 | 6 | ₹199 + GST | - |
  | Credit | Standard | AU Small Finance Bank | au | 2000 | - | 14 | 9 | ₹199 + GST | - |
  | Credit | Standard | AU Small Finance Bank | au | 2000 | - | 14 | 12 | ₹199 + GST | - |
  | Credit | Standard | AU Small Finance Bank | au | 2000 | - | 14 | 18 | ₹199 + GST | - |
  | Credit | Standard | AU Small Finance Bank | au | 2000 | - | 14 | 24 | ₹199 + GST | - |
  | Credit | Standard | Axis Bank | axis | 2500 | 1000000 | 17 | 3 | ₹299 + GST below ₹50,000; ₹599 + GST above ₹50,000 | - |
  | Credit | Standard | Axis Bank | axis | 2500 | 1000000 | 17 | 6 | ₹299 + GST below ₹50,000; ₹599 + GST above ₹50,000 | - |
  | Credit | Standard | Axis Bank | axis | 2500 | 1000000 | 17 | 9 | ₹299 + GST below ₹50,000; ₹599 + GST above ₹50,000 | - |
  | Credit | Standard | Axis Bank | axis | 2500 | 1000000 | 17 | 12 | ₹299 + GST below ₹50,000; ₹599 + GST above ₹50,000 | - |
  | Credit | Standard | Axis Bank | axis | 2500 | 1000000 | 17 | 18 | ₹299 + GST below ₹50,000; ₹599 + GST above ₹50,000 | - |
  | Credit | Standard | Axis Bank | axis | 2500 | 1000000 | 17 | 24 | ₹299 + GST below ₹50,000; ₹599 + GST above ₹50,000 | - |
  | Credit | Standard | Bank of Baroda | bob | 2500 | - | 16 | 3 | ₹199 + GST | Available tenures: 2, 3, 4, 5, 6, 7, 8, 9, 12, 18, 24, 36. See Bank of Baroda EMI terms below. |
  | Credit | Standard | Bank of Baroda | bob | 2500 | - | 16 | 6 | ₹199 + GST | Available tenures: 2, 3, 4, 5, 6, 7, 8, 9, 12, 18, 24, 36. See Bank of Baroda EMI terms below. |
  | Credit | Standard | Bank of Baroda | bob | 2500 | - | 16 | 9 | ₹199 + GST | Available tenures: 2, 3, 4, 5, 6, 7, 8, 9, 12, 18, 24, 36. See Bank of Baroda EMI terms below. |
  | Credit | Standard | Bank of Baroda | bob | 2500 | - | 16 | 12 | ₹199 + GST | Available tenures: 2, 3, 4, 5, 6, 7, 8, 9, 12, 18, 24, 36. See Bank of Baroda EMI terms below. |
  | Credit | Standard | Bank of Baroda | bob | 2500 | - | 16 | 18 | ₹199 + GST | Available tenures: 2, 3, 4, 5, 6, 7, 8, 9, 12, 18, 24, 36. See Bank of Baroda EMI terms below. |
  | Credit | Standard | Bank of Baroda | bob | 2500 | - | 16 | 24 | ₹199 + GST | Available tenures: 2, 3, 4, 5, 6, 7, 8, 9, 12, 18, 24, 36. See Bank of Baroda EMI terms below. |
  | Credit | Standard | Bank of Baroda | bob | 2500 | - | 16 | 36 | ₹199 + GST | Available tenures: 2, 3, 4, 5, 6, 7, 8, 9, 12, 18, 24, 36. See Bank of Baroda EMI terms below. |
  | Credit | Standard | RBL Bank | rbl | 2500 | - | 14 | 3 | ₹150 + GST up to ₹10,000; 1.5% + GST above ₹10,000 | - |
  | Credit | Standard | RBL Bank | rbl | 2500 | - | 14 | 6 | ₹150 + GST up to ₹10,000; 1.5% + GST above ₹10,000 | - |
  | Credit | Standard | RBL Bank | rbl | 2500 | - | 15 | 9 | ₹150 + GST up to ₹10,000; 1.5% + GST above ₹10,000 | - |
  | Credit | Standard | RBL Bank | rbl | 2500 | - | 15 | 12 | ₹150 + GST up to ₹10,000; 1.5% + GST above ₹10,000 | - |
  | Credit | Standard | RBL Bank | rbl | 2500 | - | 15 | 18 | ₹150 + GST up to ₹10,000; 1.5% + GST above ₹10,000 | - |
  | Credit | Standard | RBL Bank | rbl | 2500 | - | 15 | 24 | ₹150 + GST up to ₹10,000; 1.5% + GST above ₹10,000 | - |
  | Credit | Standard | Standard Chartered | standard chartered | 2000 | - | 11.88 | 3 | 1% | - |
  | Credit | Standard | Standard Chartered | standard chartered | 2000 | - | 14 | 6 | 1% | - |
  | Credit | Standard | Standard Chartered | standard chartered | 2000 | - | 15 | 9 | 1% | - |
  | Credit | Standard | Standard Chartered | standard chartered | 2000 | - | 15 | 12 | 1% | - |
  | Credit | Standard | Standard Chartered | standard chartered | 2000 | - | 15 | 18 | 1% | - |
  | Credit | Standard | Standard Chartered | standard chartered | 2000 | - | 15 | 24 | 1% | - |
  | Credit | Standard | Yes Bank | yes | 1500 | 999999999 | 16 | 3 | ₹299 + GST | - |
  | Credit | Standard | Yes Bank | yes | 1500 | 999999999 | 16 | 6 | ₹299 + GST | - |
  | Credit | Standard | Yes Bank | yes | 1500 | 999999999 | 16 | 9 | ₹299 + GST | - |
  | Credit | Standard | Yes Bank | yes | 1500 | 999999999 | 16 | 12 | ₹299 + GST | - |
  | Credit | Standard | Yes Bank | yes | 1500 | 999999999 | 16 | 18 | ₹299 + GST | - |
  | Credit | Standard | Yes Bank | yes | 1500 | 999999999 | 16 | 24 | ₹299 + GST | - |
  | Credit | Standard | American Express | amex | 5000 | - | 14 | 3 | ₹199 + GST | [American Express EMI terms](https://www.americanexpress.com/en-in/benefits/emi/terms-and-conditions/index.html) |
  | Credit | Standard | American Express | amex | 5000 | - | 14 | 6 | ₹199 + GST | [American Express EMI terms](https://www.americanexpress.com/en-in/benefits/emi/terms-and-conditions/index.html) |
  | Credit | Standard | American Express | amex | 5000 | - | 14 | 9 | ₹199 + GST | [American Express EMI terms](https://www.americanexpress.com/en-in/benefits/emi/terms-and-conditions/index.html) |
  | Credit | Standard | American Express | amex | 5000 | - | 14 | 12 | ₹199 + GST | [American Express EMI terms](https://www.americanexpress.com/en-in/benefits/emi/terms-and-conditions/index.html) |
  | Credit | Standard | American Express | amex | 5000 | - | 15 | 18 | ₹199 + GST | [American Express EMI terms](https://www.americanexpress.com/en-in/benefits/emi/terms-and-conditions/index.html) |
  | Credit | Standard | American Express | amex | 5000 | - | 15 | 24 | ₹199 + GST | [American Express EMI terms](https://www.americanexpress.com/en-in/benefits/emi/terms-and-conditions/index.html) |
  | Credit | Standard | HDFC Bank | hdfc | 1000 | 999000 | 18 | 3 | ₹299 + GST | [HDFC Bank EasyEMI credit card](https://www.hdfc.bank.in/easyemi/credit-card). Available tenures: 3, 6, 9, 12, 18, 24, 36, 48. |
  | Credit | Standard | HDFC Bank | hdfc | 1000 | 999000 | 17 | 6 | ₹299 + GST | [HDFC Bank EasyEMI credit card](https://www.hdfc.bank.in/easyemi/credit-card). Available tenures: 3, 6, 9, 12, 18, 24, 36, 48. |
  | Credit | Standard | HDFC Bank | hdfc | 1000 | 999000 | 17 | 9 | ₹299 + GST | [HDFC Bank EasyEMI credit card](https://www.hdfc.bank.in/easyemi/credit-card). Available tenures: 3, 6, 9, 12, 18, 24, 36, 48. |
  | Credit | Standard | HDFC Bank | hdfc | 1000 | 999000 | 17 | 12 | ₹299 + GST | [HDFC Bank EasyEMI credit card](https://www.hdfc.bank.in/easyemi/credit-card). Available tenures: 3, 6, 9, 12, 18, 24, 36, 48. |
  | Credit | Standard | HDFC Bank | hdfc | 1000 | 999000 | 17 | 18 | ₹299 + GST | [HDFC Bank EasyEMI credit card](https://www.hdfc.bank.in/easyemi/credit-card). Available tenures: 3, 6, 9, 12, 18, 24, 36, 48. |
  | Credit | Standard | HDFC Bank | hdfc | 1000 | 999000 | 17 | 24 | ₹299 + GST | [HDFC Bank EasyEMI credit card](https://www.hdfc.bank.in/easyemi/credit-card). Available tenures: 3, 6, 9, 12, 18, 24, 36, 48. |
  | Credit | Standard | HDFC Bank | hdfc | 1000 | 999000 | 17 | 36 | ₹299 + GST | [HDFC Bank EasyEMI credit card](https://www.hdfc.bank.in/easyemi/credit-card). Available tenures: 3, 6, 9, 12, 18, 24, 36, 48. |
  | Credit | Standard | HDFC Bank | hdfc | 1000 | 999000 | 17 | 48 | ₹299 + GST | [HDFC Bank EasyEMI credit card](https://www.hdfc.bank.in/easyemi/credit-card). Available tenures: 3, 6, 9, 12, 18, 24, 36, 48. |
  | Credit | Standard | Kotak Mahindra Bank | kotak | 1000 | - | 16 | 3 | ₹249 + GST | Available tenures: 3, 6, 9, 12, 18, 20, 24, 30, 36. Foreclosure fee of 2% on the principal amount + GST. |
  | Credit | Standard | Kotak Mahindra Bank | kotak | 2500 | - | 16 | 6 | ₹249 + GST | Available tenures: 3, 6, 9, 12, 18, 20, 24, 30, 36. Foreclosure fee of 2% on the principal amount + GST. |
  | Credit | Standard | Kotak Mahindra Bank | kotak | 2500 | - | 16 | 9 | ₹249 + GST | Available tenures: 3, 6, 9, 12, 18, 20, 24, 30, 36. Foreclosure fee of 2% on the principal amount + GST. |
  | Credit | Standard | Kotak Mahindra Bank | kotak | 2500 | - | 16 | 12 | ₹249 + GST | Available tenures: 3, 6, 9, 12, 18, 20, 24, 30, 36. Foreclosure fee of 2% on the principal amount + GST. |
  | Credit | Standard | Kotak Mahindra Bank | kotak | 2500 | - | 16 | 18 | ₹249 + GST | Available tenures: 3, 6, 9, 12, 18, 20, 24, 30, 36. Foreclosure fee of 2% on the principal amount + GST. |
  | Credit | Standard | Kotak Mahindra Bank | kotak | 2500 | - | 16 | 20 | ₹249 + GST | Available tenures: 3, 6, 9, 12, 18, 20, 24, 30, 36. Foreclosure fee of 2% on the principal amount + GST. |
  | Credit | Standard | Kotak Mahindra Bank | kotak | 2500 | - | 16 | 24 | ₹249 + GST | Available tenures: 3, 6, 9, 12, 18, 20, 24, 30, 36. Foreclosure fee of 2% on the principal amount + GST. |
  | Credit | Standard | Kotak Mahindra Bank | kotak | 2500 | - | 16 | 30 | ₹249 + GST | Available tenures: 3, 6, 9, 12, 18, 20, 24, 30, 36. Foreclosure fee of 2% on the principal amount + GST. |
  | Credit | Standard | Kotak Mahindra Bank | kotak | 2500 | - | 16 | 36 | ₹249 + GST | Available tenures: 3, 6, 9, 12, 18, 20, 24, 30, 36. Foreclosure fee of 2% on the principal amount + GST. |
  | Credit | Standard | SBI | sbi | 2500 | - | 17.25 | 3 | - | - |
  | Credit | Standard | SBI | sbi | 2500 | - | 17.00 | 6 | ₹45 for transactions of ₹20,000 or more | - |
  | Credit | Standard | SBI | sbi | 2500 | - | 17.00 | 9 | ₹69 for transactions of ₹20,000 or more | - |
  | Credit | Standard | SBI | sbi | 2500 | - | 17.00 | 12 | ₹89 for transactions of ₹20,000 or more | - |
  | Credit | Standard | SBI | sbi | 2500 | - | 17.00 | 18 | ₹129 for transactions of ₹20,000 or more | - |
  | Credit | Standard | SBI | sbi | 2500 | - | 17.00 | 24 | ₹169 for transactions of ₹20,000 or more | - |
  | Credit | Standard | IDFC Bank | idfc | 1500 | - | 16 | 3 | ₹249 + GST | Foreclosure fee of 3% of outstanding amount + GST |
  | Credit | Standard | IDFC Bank | idfc | 1500 | - | 16 | 6 | ₹249 + GST | Foreclosure fee of 3% of outstanding amount + GST |
  | Credit | Standard | IDFC Bank | idfc | 1500 | - | 16 | 9 | ₹249 + GST | Foreclosure fee of 3% of outstanding amount + GST |
  | Credit | Standard | IDFC Bank | idfc | 1500 | - | 16 | 12 | ₹249 + GST | Foreclosure fee of 3% of outstanding amount + GST |
  | Credit | Standard | IDFC Bank | idfc | 1500 | - | 16 | 18 | ₹249 + GST | Foreclosure fee of 3% of outstanding amount + GST |
  | Credit | Standard | IDFC Bank | idfc | 1500 | - | 16 | 24 | ₹249 + GST | Foreclosure fee of 3% of outstanding amount + GST |
  | Credit | Standard | IDFC Bank | idfc | 1500 | - | 16 | 36 | ₹249 + GST | Foreclosure fee of 3% of outstanding amount + GST |
  | Credit | Standard | IndusInd Bank | indus | 2000 | - | 17 | 3 | ₹249 + GST | [IndusInd Easy EMI terms](https://www.indusind.bank.in/in/en/personal/indus-easy-emi-tnc.html) |
  | Credit | Standard | IndusInd Bank | indus | 2000 | - | 16 | 6 | ₹249 + GST | [IndusInd Easy EMI terms](https://www.indusind.bank.in/in/en/personal/indus-easy-emi-tnc.html) |
  | Credit | Standard | IndusInd Bank | indus | 2000 | - | 16 | 9 | ₹249 + GST | [IndusInd Easy EMI terms](https://www.indusind.bank.in/in/en/personal/indus-easy-emi-tnc.html) |
  | Credit | Standard | IndusInd Bank | indus | 2000 | - | 16 | 12 | ₹249 + GST | [IndusInd Easy EMI terms](https://www.indusind.bank.in/in/en/personal/indus-easy-emi-tnc.html) |
  | Credit | Standard | IndusInd Bank | indus | 2000 | - | 16 | 18 | ₹249 + GST | [IndusInd Easy EMI terms](https://www.indusind.bank.in/in/en/personal/indus-easy-emi-tnc.html) |
  | Credit | Standard | IndusInd Bank | indus | 2000 | - | 16 | 24 | ₹249 + GST | [IndusInd Easy EMI terms](https://www.indusind.bank.in/in/en/personal/indus-easy-emi-tnc.html) |
  | Credit | Standard | IndusInd Bank | indus | 2000 | - | 16 | 36 | ₹249 + GST | [IndusInd Easy EMI terms](https://www.indusind.bank.in/in/en/personal/indus-easy-emi-tnc.html) |

  <Note>
    For Bank of Baroda EMI, the following terms must appear in all T\&C documents and on the payment page of campaigns that include EMI:

    1. I have understood and accept the T\&C of EMI as available on the website ([www.bobcard.co.in](https://www.bobcard.co.in)) and the applicable charges mentioned.
    2. I understand that in the event of the merchant or me cancelling my EMI transaction, I am responsible for notifying BOBCARD to cancel the EMI that was booked for the cancelled transaction.
    3. Processing fee of ₹199 plus applicable taxes will be charged for each EMI.
  </Note>
</Accordion>

### Debit card EMI

Cashfree supports HDFC Bank Debit Card EMI payment method. This option is available to customers who are pre-approved by this issuing bank.

Here is a sample of the request that you need to send to `/orders/sessions` to process a seamless EMI payment. [Read more here](/docs/api-reference/payments/latest/payments/order-pay). Incase of a native OTP flow , Cashfree provides a [submit OTP API](/docs/api-reference/payments/latest/payments/submit-or-resend-otp) which needs to be integrated on your checkout page.

<CodeGroup>
  ```Text Request theme={"dark"}
  {
       "payment_method": {
            "emi": {
                 "channel": "post",
                 "card_number": "4280901212123121",
                 "card_holder_name": "Tushar Gupta",
                 "card_expiry_mm": "09",
                 "card_expiry_yy": "23",
                 "card_cvv": "900",
                 "emi_tenure": 12,
                 "card_bank_name": "hdfc",
                 "phone": 8714268343
            }
       },
      "payment_session_id": "session__CvcEmNKDkmERQrxnx39ibhJ3Ii034pjc8ZVxf3qcgEXCWlgDDlHRgz2XYZCqpajDQSXMMtCusPgOIxYP2LZx0-05p39gC2Vgmq1RAj--gcn"
  }
  ```

  ```Text Response (Native OTP) theme={"dark"}
  {
      "action": "post",
      "cf_payment_id": 1491777871,
      "channel": "link",
      "data": {
          "url": "https://sandbox.cashfree.com/pg/orders/pay/authenticate/1491777871",
          "payload": null,
          "content_type": "application/json",
          "method": "post"
      },
      "payment_amount": 6000.00,
      "payment_method": "emi"
  }
  ```

  ```Text Submit OTP Request theme={"dark"}
  curl --request POST \
       --url https://sandbox.cashfree.com/pg/orders/pay/authenticate/1111111 \
       --header 'accept: application/json' \
       --header 'content-type: application/json' \
       --header 'x-api-version: 2022-09-01' \
       --data '
  {
    "action": "SUBMIT_OTP",
    "otp": "1234"
  }
  '
  ```
</CodeGroup>

<Accordion title="The following 1 card issuer is supported for card-based EMIs. ">
  Please send the exact values in the `card_bank_name` parameter.

  | Bank name | Native OTP |
  | :- | :- |
  | HDFC Bank | Yes |

  ### Debit card EMI plans

  | Card type | Type of EMI | Bank | card\_bank\_name | Minimum amount | Maximum amount | Annual interest rate | Tenure | Processing fees | Remarks |
  | - | - | - | - | - | - | - | - | - | - |
  | Debit | Standard | HDFC Bank | hdfc | 3000 | 400000 | 16 | 3 | ₹299 + GST | [HDFC Bank EasyEMI debit card](https://www.hdfc.bank.in/easyemi/debit-card). Available tenures: 3, 6, 9, 12, 18, 24, 36, 48. |
  | Debit | Standard | HDFC Bank | hdfc | 3000 | 400000 | 16 | 6 | ₹299 + GST | [HDFC Bank EasyEMI debit card](https://www.hdfc.bank.in/easyemi/debit-card). Available tenures: 3, 6, 9, 12, 18, 24, 36, 48. |
  | Debit | Standard | HDFC Bank | hdfc | 3000 | 400000 | 16 | 9 | ₹299 + GST | [HDFC Bank EasyEMI debit card](https://www.hdfc.bank.in/easyemi/debit-card). Available tenures: 3, 6, 9, 12, 18, 24, 36, 48. |
  | Debit | Standard | HDFC Bank | hdfc | 3000 | 400000 | 16 | 12 | ₹299 + GST | [HDFC Bank EasyEMI debit card](https://www.hdfc.bank.in/easyemi/debit-card). Available tenures: 3, 6, 9, 12, 18, 24, 36, 48. |
  | Debit | Standard | HDFC Bank | hdfc | 3000 | 400000 | 16 | 18 | ₹299 + GST | [HDFC Bank EasyEMI debit card](https://www.hdfc.bank.in/easyemi/debit-card). Available tenures: 3, 6, 9, 12, 18, 24, 36, 48. |
  | Debit | Standard | HDFC Bank | hdfc | 3000 | 400000 | 16 | 24 | ₹299 + GST | [HDFC Bank EasyEMI debit card](https://www.hdfc.bank.in/easyemi/debit-card). Available tenures: 3, 6, 9, 12, 18, 24, 36, 48. |
  | Debit | Standard | HDFC Bank | hdfc | 3000 | 400000 | 16 | 36 | ₹299 + GST | [HDFC Bank EasyEMI debit card](https://www.hdfc.bank.in/easyemi/debit-card). Available tenures: 3, 6, 9, 12, 18, 24, 36, 48. |
  | Debit | Standard | HDFC Bank | hdfc | 3000 | 400000 | 16 | 48 | ₹299 + GST | [HDFC Bank EasyEMI debit card](https://www.hdfc.bank.in/easyemi/debit-card). Available tenures: 3, 6, 9, 12, 18, 24, 36, 48. |
</Accordion>

### Cardless EMI plans

Your customers can pay using non-card-based EMI providers. A sample request is provided for reference.

The available providers include FlexMoney, which offers cardless EMI from HDFC Bank, ICICI Bank, IDFC Bank, LazyPay, TVS Credit, and Home Credit, as well as ZestMoney.

```javascript Request theme={"dark"}
curl --request POST \
     --url https://api.cashfree.com/pg/orders/sessions \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --data '
{
     "payment_method": {
          "cardless_emi": {
               "channel": "link",
               "provider": "flexmoney",
               "phone": "77891212345"
          }
     },
     "payment_session_id": "session_mdCizuqcgJWbIhdJ4rjON-vpCB1B31muN7Tev9p2kdlEQpj9mem5yF5gbUju4kdgN6-31FJnGK3yaEcqG0GZUsrbzOLDFPfA30iYduwiNmBk"
}
```

**Provider details**

Provider parameter: flexmoney
Provider name: FlexMoney (powers cardless EMI from HDFC Bank, ICICI Bank, IDFC Bank, LazyPay, TVS Credit, and Home Credit)
Minimum amount: 500 onwards

<Accordion title="Cardless EMI Plans">
  | Card type | Type of EMI | Bank | provider | Minimum amount | Maximum amount | Annual interest rate | Tenure | Processing fees | Remarks |
  | - | - | - | - | - | - | - | - | - | - |
  | Cardless | Standard | HDFC Bank | hdfc | 3000 | 500000 | 16 | 3 | ₹299 + GST | - |
  | Cardless | Standard | HDFC Bank | hdfc | 5000 | 500000 | 16 | 6 | ₹299 + GST | - |
  | Cardless | Standard | HDFC Bank | hdfc | 5000 | 500000 | 16 | 9 | ₹299 + GST | - |
  | Cardless | Standard | HDFC Bank | hdfc | 5000 | 500000 | 16 | 12 | ₹299 + GST | - |
  | Cardless | Standard | HDFC Bank | hdfc | 5000 | 500000 | 16 | 18 | ₹299 + GST | - |
  | Cardless | Standard | HDFC Bank | hdfc | 5000 | 500000 | 16 | 24 | ₹299 + GST | - |
  | Cardless | Standard | ICICI Bank | icici | 7000 | 500000 | 18 | 3 | - | - |
  | Cardless | Standard | ICICI Bank | icici | 7000 | 500000 | 18 | 6 | - | - |
  | Cardless | Standard | ICICI Bank | icici | 7000 | 500000 | 18 | 9 | - | - |
  | Cardless | Standard | ICICI Bank | icici | 7000 | 500000 | 18 | 12 | - | - |
  | Cardless | Standard | IDFC Bank | idfc | 5000 | 60000 | 24 | 3 | - | - |
  | Cardless | Standard | IDFC Bank | idfc | 5000 | 60000 | 24 | 6 | - | - |
  | Cardless | Standard | IDFC Bank | idfc | 5000 | 60000 | 24 | 9 | - | - |
  | Cardless | Standard | IDFC Bank | idfc | 5000 | 60000 | 24 | 12 | - | - |
  | Cardless | Standard | LazyPay | lazypay | 3000 | 100000 | 20 | 3 | ₹199 + GST | - |
  | Cardless | Standard | LazyPay | lazypay | 3000 | 100000 | 20 | 6 | ₹199 + GST | - |
  | Cardless | Standard | LazyPay | lazypay | 3000 | 100000 | 20 | 9 | ₹199 + GST | - |
  | Cardless | Standard | LazyPay | lazypay | 3000 | 100000 | 20 | 12 | ₹199 + GST | - |
  | Cardless | Standard | TVS Credit | tvs | 3000 | 50000 | 22 | 3 | 2.36% | Available tenures: 3, 6, 9, 12, 15, 18, 24 |
  | Cardless | Standard | TVS Credit | tvs | 3000 | 50000 | 22 | 6 | 4.72% | Available tenures: 3, 6, 9, 12, 15, 18, 24 |
  | Cardless | Standard | TVS Credit | tvs | 3000 | 50000 | 27 | 9 | 4.72% | Available tenures: 3, 6, 9, 12, 15, 18, 24 |
  | Cardless | Standard | TVS Credit | tvs | 3000 | 50000 | 27 | 12 | 4.72% | Available tenures: 3, 6, 9, 12, 15, 18, 24 |
  | Cardless | Standard | TVS Credit | tvs | 3000 | 50000 | 27 | 15 | 4.72% | Available tenures: 3, 6, 9, 12, 15, 18, 24 |
  | Cardless | Standard | TVS Credit | tvs | 3000 | 50000 | 27 | 18 | 4.72% | Available tenures: 3, 6, 9, 12, 15, 18, 24 |
  | Cardless | Standard | TVS Credit | tvs | 3000 | 50000 | 27 | 24 | 4.72% | Available tenures: 3, 6, 9, 12, 15, 18, 24 |
  | Cardless | Standard | Home Credit | homecredit | 4000 | 75000 | 25 | 3 | ₹299 + GST | - |
  | Cardless | Standard | Home Credit | homecredit | 4000 | 75000 | 25 | 6 | ₹299 + GST | - |
  | Cardless | Standard | ZestMoney | zestmoney | 3000 | 200000 | 20 | 3 | 1.75% | Bounce and late payment charges are provided in the KFS. Customers with an active credit line are eligible within the allocated limit. 3-month tenure is enabled for subvention cases only. |
  | Cardless | Standard | ZestMoney | zestmoney | 3000 | 200000 | 24.90 | 6 | 1.50% | Bounce and late payment charges are provided in the KFS. Customers with an active credit line are eligible within the allocated limit. |
  | Cardless | Standard | ZestMoney | zestmoney | 3000 | 200000 | 24.90 | 9 | 2.00% | Bounce and late payment charges are provided in the KFS. Customers with an active credit line are eligible within the allocated limit. |
</Accordion>

### Cardless EMI eligibility check

To check whether a customer is eligible for cardless EMI before presenting the option at checkout, use the [eligibility API](/docs/api-reference/payments/latest/eligibility/get-eligible-cardless-emi-payment-methods-for-a-customer-on-an-order). If the customer is not eligible, the API returns null data for that provider.

### Paylater providers

Your customers can also pay through the following Paylater providers:

* Lazypay

| Provider parameter | Name of the provider |
| :- | :- |
| lazypay | LazyPay (applicable for orders with a minimum value of ₹100 and a maximum value of ₹5,000) |

```curl lazypay request theme={"dark"}
curl --request POST
    --url https://api.cashfree.com/pg/orders/sessions
    --header 'Accept: application/json'
    --header 'Content-Type: application/json'
    --data '{
    "payment_method": {
        "paylater":{
            "channel": "link",
            "provider": "lazypay",
            "phone": "999999999"
        }
    },
    "payment_session_id": "session_0_7R8dKzYmdby5xKkADpF8id7LgIZk3pv7faZ9-2v7s_cA34F2YKjVCSG4D8gOjzmlYFSgtn3q9txW3uKFC_IM5wE289t3137ITsZPqPynCB-ip8rCq6Y70_0Qwpayment"
}'
```

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/payments/latest/eligibility/get-eligible-payment-methods">Get Eligible Payment Methods API</a></li>
    <li><a href="/docs/api-reference/payments/latest/payments/order-pay">Order Pay API</a></li>
    <li><a href="/docs/api-reference/payments/latest/payments/submit-or-resend-otp">Submit OTP API</a></li>
  </ul>
</div>


# UPI Payments
Source: https://www.cashfree.com/docs/payments/manage/payment-methods/upi

Accept UPI payments on Cashfree across Intent, Collect, AutoPay, and QR flows with deep links to major UPI apps and real-time success-rate monitoring tools.

UPI is the most popular payment method in India. UPI lets customers directly transfer money from their bank account or alternate funding source (like credit cards, Pre-paid wallet) using an authenticating intermediary, like a phone number.

<CardGroup>
  <Card icon="qrcode" title="UPI Intent, QR and Collect">
    Collect UPI payments using intent, QR or collect.
  </Card>

  <Card icon="bolt" title="Flash UPI">
    Add the UPI SDK to your app to power in-app payments.
  </Card>

  <Card icon="command" title="Recurring Payments">
    Support for UPI one-time mandates and recurring payments.
  </Card>
</CardGroup>

<Note>UPI Collect flow for P2M transactions is being deprecated as per NPCI guidelines. Merchants are advised to migrate to UPI Intent and UPI QR flows. For more details, refer to the [UPI Collect Flow Deprecation](/docs/payments/manage/payment-methods/upi-collect) document.</Note>


# UPI AutoPay Interoperability
Source: https://www.cashfree.com/docs/payments/manage/payment-methods/upi-autopay-interoperability

Learn how UPI AutoPay interoperability works, how to migrate existing mandates to Cashfree, and what actions are required from you as a merchant.

UPI AutoPay is the recurring payments framework built on the Unified Payments Interface (UPI). It supports subscriptions, loan EMIs, insurance premiums, utility bills, and similar recurring payment types. By default, most payment service providers (PSPs) bind AutoPay mandates to the gateway that originally created them. When you switch your acquiring bank or payment gateway, those mandates become invalid and your customers must set them up again.

UPI AutoPay Interoperability removes this dependency. It allows you to move mandates across payment gateways without interruption, and gives your customers greater visibility and control over their recurring payments.

<Info>
  Cashfree validates merchants using a persistent Merchant Identifier Code (MIC) rather than your Payee UPI ID. The MIC is derived from your corporate PAN and remains consistent regardless of which payment gateway or bank you use.
</Info>

## Key features

UPI AutoPay Interoperability provides the following capabilities that allow you to migrate mandates while keeping recurring payments active.

* **Acquiring-side interoperability**: A different payment aggregator or acquiring bank can execute mandates on behalf of the one that originally created them.
* **Payer-side interoperability**: Users can view active mandates across UPI apps and port mandates without disrupting recurring debits.
* **Gateway migration support**: You can change payment gateways without forcing customers to recreate mandates.

## Use cases

UPI AutoPay Interoperability is suited to the following scenarios.

* Migrate your payment processing from one gateway to another without disrupting recurring mandates.
* Keep subscriptions, loan EMIs and insurance premium collections active when you switch settlement partners.
* Support recurring utility bill payments across multiple UPI apps and remitting banks.
* Maintain recurring payment continuity during merchant migration, acquisitions or platform changes.

## What this means for you

If you have active UPI AutoPay mandates with another payment aggregator, you can migrate your processing to Cashfree without disrupting your customers' mandates. The table below shows the change:

| Aspect | Before interoperability | After interoperability |
| - | - | - |
| Switching payment gateways | Mandates break and users must re-create | Mandates migrate seamlessly |
| Mandate visibility for users | Only within the originating UPI app | Viewable across any UPI app |
| Dynamic routing for mandate executions | Not allowed | Now allowed |
| User re-authentication needed? | Yes, required if gateway changes | No, existing UPI PIN suffices |

## Eligibility for mandate migration

Because this is new functionality that has not yet been widely adopted, not all banks and UPI apps have implemented the required changes. You can migrate mandates only when all three entities, the payee PSP (the PSP collecting payments on your behalf), the payer PSP (the customer's UPI app), and the remitting bank, have implemented the interoperability framework.

Eligibility depends on both the remitting bank (the customer's bank) and the payer's UPI app (PSP) being certified for UPI AutoPay Interoperability.

### Eligible remitting banks

You can migrate mandates only when the customer's bank account is held at one of these banks:

| Bank name | Status |
| - | - |
| HDFC Bank | Live on UPI interoperability |
| Punjab National Bank (PNB) | Live on UPI interoperability |
| IndusInd Bank | Live on UPI interoperability |
| Yes Bank | Live on UPI interoperability |
| IDFC FIRST Bank | Live on UPI interoperability |
| Cosmos Bank | Live on UPI interoperability |

Mandates linked to banks not in this list are not yet eligible. Cashfree updates this list as more banks complete certification.

### Eligible payer PSPs (UPI apps)

Your customer's UPI app must also be certified for interoperability. The following payer PSPs are currently eligible:

| UPI app or PSP | UPI handle |
| - | - |
| Paytm | `@ptyes` |
| BHIM | `@upi` |
| INDmoney | `@inhdfc` |

You can migrate a mandate only when both the remitting bank and the payer PSP are on these lists.

## How mandate migration works

The following steps describe the migration flow involving your existing payment aggregator (PA1), Cashfree and NPCI's UPI switch. PA1 is the payment aggregator that originally created your mandates and upgrades them before Cashfree begins execution.

You can enable UPI Autopay Interoperability by contacting your Cashfree account manager or filling out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1).

For related subscription mandate APIs, see the [Create Subscription API](/docs/api-reference/payments/latest/subscription/create-subscription).

<Steps>
  <Step title="Migrate mandates to the interoperability framework">
    Before Cashfree executes your mandates, your existing mandates, which were created under the old framework using purpose code `14`, must be upgraded to the interoperability framework by PA1.
    During this step:

    * PA1 initiates a `ReqMandate` API call with `type='UPDATE'` and purpose code `AZ` for each eligible mandate.
    * PA1 updates the `sid` tag in the mandate with your Merchant Identifier Code (MIC).
    * Customers do not need to enter their UPI PIN for this upgrade.
  </Step>

  <Step title="Receive mandate details from PA1">
    Once PA1 moves eligible mandates to the interoperability framework, it shares a list of migrated mandates with you. This file contains:

    * **UMN** (Unique Mandate Number): the primary identifier for the mandate.
    * **MIC** (Merchant Identifier Code): the 20-character hexadecimal code derived from your corporate PAN using SHAKE-256 hashing.
    * **SeqNum** (Sequence Number): the current sequence number of the mandate, required for pre-debit notifications and execution ordering.
    * Other mandate metadata required for execution, including mandate max amount, frequency, start date, and end date.
  </Step>

  <Step title="Share mandate details with Cashfree">
    After you receive the mandate data from PA1, share it with Cashfree. This handoff lets Cashfree take over mandate execution for your customers.

    <Warning>
      You are responsible for ensuring the mandate data from PA1 is accurate. Any discrepancy in MIC, UMN, or SeqNum causes mandate execution to fail.
    </Warning>
  </Step>

  <Step title="Cashfree validates and begins execution">
    Once Cashfree receives your mandate data, Cashfree validates the mandate and begins execution:

    * Cashfree maps the MIC against your Payee UPI ID.
    * Cashfree associates the new payee with all migrated mandates.
    * Cashfree begins executing mandates on the specified due dates.
  </Step>
</Steps>

## What is required from you

These merchant actionables describe the steps you must complete before Cashfree can begin executing migrated mandates.

| Action | Details |
| - | - |
| Confirm mandate eligibility with PA1 | Work with PA1 to identify which of your existing mandates are on eligible remitting banks and payer PSPs. Mandates on non-eligible banks or PSPs cannot be migrated yet. |
| Request SID updation from PA1 | Formally ask PA1 to initiate the interoperability migration using `ReqMandate` with purpose code `AZ` for all eligible mandates. This is a prerequisite. Cashfree cannot execute mandates until this is done. |
| Collect mandate data file from PA1 | After migration is complete, collect the mandate data file from PA1 containing UMN, MIC, SeqNum, mandate max amount, frequency, start date, and end date for every migrated mandate. |
| Share mandate data with Cashfree | Provide the mandate data file to Cashfree’s onboarding and integrations team for validation and ingestion. |
| Coordinate go-live date | Agree on a go-live date with Cashfree. Ensure PA1 stops executing the same UMN once Cashfree takes over to avoid duplicate debits. |

## Migration checklist

Use this checklist to track your migration progress.

<div>
  <div>
    <div>
      <div>
        <svg>
          <path />
        </svg>
      </div>

      <span>Have you identified all active UPI AutoPay mandates on your current payment aggregator?</span>
    </div>

    <div>
      <button>Yes</button>
      <button>No</button>
      <button>N/A</button>
    </div>
  </div>

  <div>
    <svg>
      <path />
    </svg>

    <span>List every active mandate before moving forward. Missing mandates can delay the migration.</span>
  </div>

  <div>
    <svg>
      <path />
    </svg>

    <span>Work with PA1 to extract your active mandate list and confirm the source UPI app and remitting bank for each mandate.</span>
  </div>
</div>

<div>
  <div>
    <div>
      <div>
        <svg>
          <path />
        </svg>
      </div>

      <span>Have you filtered mandates by eligible remitting banks?</span>
    </div>

    <div>
      <button>Yes</button>
      <button>No</button>
      <button>N/A</button>
    </div>
  </div>

  <div>
    <svg>
      <path />
    </svg>

    <span>Only mandates with eligible remitting banks can migrate under current interoperability coverage.</span>
  </div>

  <div>
    <svg>
      <path />
    </svg>

    <span>Eligible banks today include HDFC Bank, PNB, IndusInd Bank, Yes Bank, IDFC FIRST Bank and Cosmos Bank.</span>
  </div>
</div>

<div>
  <div>
    <div>
      <div>
        <svg>
          <path />
        </svg>
      </div>

      <span>Have you filtered mandates by eligible payer PSPs?</span>
    </div>

    <div>
      <button>Yes</button>
      <button>No</button>
      <button>N/A</button>
    </div>
  </div>

  <div>
    <svg>
      <path />
    </svg>

    <span>Only payer PSPs certified under interoperability can support migrated mandates today.</span>
  </div>

  <div>
    <svg>
      <path />
    </svg>

    <span>Eligible payer PSPs today include Paytm, BHIM and INDmoney.</span>
  </div>
</div>

<div>
  <div>
    <div>
      <div>
        <svg>
          <path />
        </svg>
      </div>

      <span>Have you requested PA1 to initiate interoperability migration for eligible mandates?</span>
    </div>

    <div>
      <button>Yes</button>
      <button>No</button>
      <button>N/A</button>
    </div>
  </div>

  <div>
    <svg>
      <path />
    </svg>

    <span>Cashfree cannot execute mandates until PA1 updates them with purpose code AZ.</span>
  </div>

  <div>
    <svg>
      <path />
    </svg>

    <span>Ask PA1 to initiate `ReqMandate` with `type='UPDATE'` and purpose code `AZ` for eligible mandates.</span>
  </div>
</div>

<div>
  <div>
    <div>
      <div>
        <svg>
          <path />
        </svg>
      </div>

      <span>Have you collected the migrated mandate data from PA1?</span>
    </div>

    <div>
      <button>Yes</button>
      <button>No</button>
      <button>N/A</button>
    </div>
  </div>

  <div>
    <svg>
      <path />
    </svg>

    <span>Ensure the data includes UMN, MIC, SeqNum, mandate max amount, frequency, start date and end date.</span>
  </div>

  <div>
    <svg>
      <path />
    </svg>

    <span>Collect all required mandate metadata before sharing it with Cashfree.</span>
  </div>
</div>

<div>
  <div>
    <div>
      <div>
        <svg>
          <path />
        </svg>
      </div>

      <span>Have you shared the mandate data with Cashfree?</span>
    </div>

    <div>
      <button>Yes</button>
      <button>No</button>
      <button>N/A</button>
    </div>
  </div>

  <div>
    <svg>
      <path />
    </svg>

    <span>Notify Cashfree onboarding and integrations so they can validate and ingest your mandate data.</span>
  </div>

  <div>
    <svg>
      <path />
    </svg>

    <span>Share the file with Cashfree promptly so your migrated mandates can move to production smoothly.</span>
  </div>
</div>

<div>
  <div>
    <div>
      <div>
        <svg>
          <path />
        </svg>
      </div>

      <span>Have you agreed on a go-live date with Cashfree and arranged a clean cutover?</span>
    </div>

    <div>
      <button>Yes</button>
      <button>No</button>
      <button>N/A</button>
    </div>
  </div>

  <div>
    <svg>
      <path />
    </svg>

    <span>Without a clean cutover, you may risk duplicate mandate executions between PA1 and Cashfree.</span>
  </div>

  <div>
    <svg>
      <path />
    </svg>

    <span>Confirm the go-live date with Cashfree and ensure PA1 stops executing migrated mandates before Cashfree begins.</span>
  </div>
</div>

## Current limitations and considerations

The limitations and risks applicable during the migration process are as follows:

* **POC stage**: Interoperability is in an early proof-of-concept phase. Complete full testing before live migration.
* **Limited bank and PSP coverage**: Only 6 remitting banks and 3 payer PSPs are currently eligible. Mandates outside this scope cannot migrate yet.
* **SeqNum conflicts**: If PA1 and Cashfree execute the same mandate at the same time, you risk duplicate debit attempts. Ensure a clean cutover with no overlap.

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/payments/subscription/payment-modes#upi-autopay">UPI Autopay</a></li>
    <li><a href="/docs/api-reference/payments/latest/subscription/create-subscription">Create Subscription API</a></li>
  </ul>
</div>


# UPI Collect Flow Deprecation
Source: https://www.cashfree.com/docs/payments/manage/payment-methods/upi-collect

Understand the UPI Collect flow, its deprecation timeline, and how to migrate to compliant UPI payment methods on Cashfree in line with NPCI guidelines.

The National Payments Corporation of India (NPCI) has mandated a phased deprecation of the UPI Collect flow for P2M (Person-to-Merchant) transactions to enhance security and reduce fraud. This change impacts all merchants using UPI Collect for payments.

### What's changing

NPCI has mandated the following changes for UPI P2M transactions:

* **UPI Collect flow phase-out**: UPI Collect for P2M transactions must be discontinued.
* **Migration to secure flows**: Merchants must prioritise UPI Intent (mobile) and UPI QR (desktop) as primary payment methods.
* **Device-specific enforcement**: Different rules apply based on customer device type.

<Note>
  UPI Collect was previously sunset for P2P transactions. These changes now extend to merchant payments to address rising fraud instances.
</Note>

### Understanding UPI payment flows

Cashfree supports the following UPI payment flows:

<Accordion title="UPI Collect flow">
  1. Customer enters their UPI ID (VPA).
  2. Collect request is sent to the customer's UPI app.
  3. Customer authorises the payment using their UPI PIN.
</Accordion>

<Accordion title="UPI Intent and QR flow">
  1. On mobile, the customer is redirected to their preferred UPI app by clicking the app icon on checkout.
  2. On desktop, the customer scans a dynamically generated QR code using their UPI app.
  3. Payment is completed securely within the UPI app without manually entering a VPA.
</Accordion>

<Note>
  UPI Intent and QR flows are now the dominant payment methods in the ecosystem due to enhanced security and user experience.
</Note>

### Device-specific UPI rules

The following table shows NPCI's mandated UPI flows by device type:

| Device or platform | Allowed UPI flows | UPI collect status |
| - | - | - |
| Android mobile | UPI Intent | Deprecated (no longer in use) |
| Desktop (Web) | UPI QR | Deprecated (no longer in use) |
| iOS mobile | UPI Intent + UPI Collect | Temporarily allowed |

<Note>iOS is currently exempted by NPCI and will continue to support UPI Collect until further notice.</Note>

### Required actions by integration type

<Accordion title="Non-seamless merchants (Cashfree Hosted Checkout)">
  **Applies to**: Mobile web and native SDK integrations using standard [Cashfree Hosted Checkout](/docs/payments/online/web/redirect)

  **Action required**: No action needed

  **Impact**: Cashfree has removed the Collect option from hosted checkout on Android and desktop. Alternate flows (Intent and QR) are already supported, so customers won't experience disruptions. iOS still allows Collect until further notice.
</Accordion>

<Accordion title="Non-seamless merchants using WebView">
  **Applies to**: Android or iOS mobile WebView integrations using Cashfree Checkout

  **Action required**: The following scenarios determine your required actions:

  * **Scenario A** (Not using standard Checkout): No action required.
  * **Scenario B** (Using standard Checkout in WebView): Implement specific code changes to ensure UPI Intent displays correctly. Refer to the [Android Custom Checkout](/docs/payments/online/mobile/misc/upi_intent_support_js_sdk) documentation for WebView integration details.
</Accordion>

<Accordion title="Seamless merchants (Custom checkout or API-based integration)">
  **Applies to**: Direct API integrations using [custom checkout](/docs/payments/online/element/overview) or [Order Pay API](/docs/api-reference/payments/latest/payments/order-pay)

  <Warning>
    Critical actions are required for seamless merchants to ensure compliance with NPCI guidelines.
  </Warning>

  #### Migrate from Collect to Intent or QR

  Update your checkout logic to prioritise the following flows:

  * **Mobile**: Enable UPI Intent.
  * **Desktop**: Use UPI QR.
  * **Deprecate**: Remove UPI Collect as a payment option according to device rules above.

  #### Pass client environment details

  Cashfree requires visibility into the customer’s device to enforce NPCI rules. You must pass the following headers in your [Order Pay API](/docs/api-reference/payments/latest/payments/order-pay) and [Get Eligible Payment Methods](/docs/api-reference/payments/latest/eligibility/get-eligible-payment-methods) request:

  | Header | Example value | Requirement |
  | - | - | - |
  | `x-client-device` | `mobile` | Required |
  | `x-client-os` | `ios` | Required |
  | `x-client-rendering-type` | `mweb` | Required (when device=mobile) |
  | `x-client-browser` | `safari` | Required |

  **Header values:**

  | Header | Accepted values | Description |
  | - | - | - |
  | `x-client-device` | `mobile`, `desktop`, `tablet` | Type of device used by customer |
  | `x-client-os` | `android`, `ios`, `windows`, `macos`, `linux`, `others` | Operating system of customer's device |
  | `x-client-rendering-type` | `mweb`, `webview`, `native` | How the checkout is being rendered |
  | `x-client-browser` | `safari`, `chrome`, `firefox`, `edge`, `others` | Browser used by customer |

  **Merchant type and rendering type details:**

  | Merchant type | Rendering type | What does it mean | Impact or required changes |
  | - | - | - | - |
  | Non-seamless merchants using Cashfree checkout | Native | Payment rendered natively within the merchant's mobile app using Android and iOS SDKs | Cashfree has removed UPI Collect from hosted checkout on Android and desktop. Alternate flows (UPI Intent and QR) are already supported. iOS still allows Collect until further notice, with no customer disruption. |
  | Non-seamless merchants using Cashfree checkout | MWeb | Payment rendered in a mobile browser using JS SDK (browser on a mobile device) | Cashfree has removed UPI Collect from hosted checkout on Android and desktop. Alternate flows (UPI Intent and QR) are already supported. iOS still allows Collect until further notice, with no customer disruption. |
  | Non-seamless merchants using Cashfree checkout | WebView | Payment rendered inside an in-app browser using JS SDK (WebView within a merchant app) | Using standard Checkout in WebView requires code changes to ensure UPI Intent displays correctly. Refer to the [WebView integration documentation](/docs/payments/online/mobile/misc/upi_intent_support_js_sdk) for required changes. |
  | Seamless merchants using custom checkout or API-based integration | Not applicable | Mobile and Desktop flows | **Mobile**: Enable and prioritise UPI Intent. Remove UPI Collect as a payment option based on device rules.<br />**Desktop**: Use UPI QR. Remove UPI Collect.<br /><br />Cashfree requires visibility into the customer's device to enforce NPCI rules. You must pass the required headers in your [Order Pay API](/docs/api-reference/payments/latest/payments/order-pay) request as detailed in the header values table above. |

  <Info>
    If headers aren't passed, Cashfree assumes full migration to Intent or QR flows. UPI Collect is allowed only in permitted environments (iOS and exempt transaction categories).
  </Info>
</Accordion>

### Timeline and compliance

| Item | Details |
| - | - |
| **Recommended timeline** | UPI Collect was deprecated on Android and desktop |
| **Current status** | Deprecated on Android and desktop. No longer in use except on iOS and exempt categories. |
| **iOS support** | Continues until further notice |

<Note>
  Cashfree has blocked UPI Collect on Android and desktop from **February 28, 2026**. Use UPI Intent on mobile and UPI QR on desktop.
</Note>

### Product-level exemptions

The following transaction categories are exempted from UPI Collect sunset:

| Category | Details |
| - | - |
| **IPO and Secondary Market** | IPO (Creation, Execution and Revoke) and Secondary Market use cases (Payee MCC 6012, 6211) |
| **UPI Mandates** | All UPI based Mandates (OTM, Autopay) (Execution, Modification and Revoke) |
| **eRupi voucher** | eRupi voucher transactions |
| **PACB Merchants** | PACB-related transaction flows |
| **iOS transactions** | iOS mobile App and mobile Web based transactions |

### Implementation checklist

Use this checklist to track your compliance progress:

<div>
  <div>
    <div>
      <div>
        <svg>
          <path />
        </svg>
      </div>

      <span>Have you identified your integration type (Non-seamless or Seamless)?</span>
    </div>

    <div>
      <button>Yes</button>
      <button>No</button>
      <button>N/A</button>
    </div>
  </div>

  <div>
    <svg>
      <path />
    </svg>

    <span>Your integration type (Non-seamless or Seamless) determines the actions you must take for UPI Collect deprecation compliance.</span>
  </div>

  <div>
    <svg>
      <path />
    </svg>

    <span>Review the [Required actions by integration type](#required-actions-by-integration-type) section above to determine which category your implementation falls under.</span>
  </div>
</div>

<div>
  <div>
    <div>
      <div>
        <svg>
          <path />
        </svg>
      </div>

      <span>Have you ensured that UPI Intent and QR flows are enabled and functional?</span>
    </div>

    <div>
      <button>Yes</button>
      <button>No</button>
      <button>N/A</button>
    </div>
  </div>

  <div>
    <svg>
      <path />
    </svg>

    <span>UPI Intent and QR flows are now the dominant and secure payment methods. Ensure both are fully enabled and tested before deprecating UPI Collect.</span>
  </div>

  <div>
    <svg>
      <path />
    </svg>

    <span>Refer to the [Understanding UPI payment flows](#understanding-upi-payment-flows) section for flow descriptions, or contact your Account manager for assistance in enabling these flows.</span>
  </div>
</div>

<div>
  <div>
    <div>
      <div>
        <svg>
          <path />
        </svg>
      </div>

      <span>Have you deprecated UPI Collect in non-exempt environments (Android or Desktop)?</span>
    </div>

    <div>
      <button>Yes</button>
      <button>No</button>
      <button>N/A</button>
    </div>
  </div>

  <div>
    <svg>
      <path />
    </svg>

    <span>UPI Collect is deprecated on Android and desktop devices. Ensure your checkout removes this option for non-exempt transaction types.</span>
  </div>

  <div>
    <svg>
      <path />
    </svg>

    <span>Review the [Device-specific UPI rules](#device-specific-upi-rules) table and [Product-level exemptions](#product-level-exemptions) section to confirm which flows to deprecate for your use case.</span>
  </div>
</div>

<div>
  <div>
    <div>
      <div>
        <svg>
          <path />
        </svg>
      </div>

      <span>Have you updated the Order Pay API with client environment headers (seamless merchants only)?</span>
    </div>

    <div>
      <button>Yes</button>
      <button>No</button>
      <button>N/A</button>
    </div>
  </div>

  <div>
    <svg>
      <path />
    </svg>

    <span>Seamless merchants must pass client environment headers to allow Cashfree to enforce NPCI device-specific rules correctly.</span>
  </div>

  <div>
    <svg>
      <path />
    </svg>

    <span>Review the API documentation section above to see required and optional headers, or consult the [Order Pay API](/docs/api-reference/payments/latest/payments/order-pay) documentation for implementation details.</span>
  </div>
</div>

<div>
  <div>
    <div>
      <div>
        <svg>
          <path />
        </svg>
      </div>

      <span>Are you monitoring Cashfree updates for final NPCI enforcement dates?</span>
    </div>

    <div>
      <button>Yes</button>
      <button>No</button>
      <button>N/A</button>
    </div>
  </div>

  <div>
    <svg>
      <path />
    </svg>

    <span>NPCI enforcement timelines are subject to change. Stay updated to ensure your implementation remains compliant with the latest regulatory requirements.</span>
  </div>

  <div>
    <svg>
      <path />
    </svg>

    <span>Review the [Timeline and compliance](#timeline-and-compliance) section above, or contact your Account manager for the latest enforcement date information.</span>
  </div>
</div>

### Frequently asked questions

The following questions cover UPI Collect behaviour on Cashfree mobile SDKs.

<Accordion title="Does UPI Collect work on Android devices using the Cashfree SDK?">
  UPI Collect is deprecated and no longer in use on Android. Use [UPI Intent](/docs/payments/online/mobile/android) on Android, and UPI QR on desktop.

  iOS still allows UPI Collect until NPCI gives further notice. Some transaction categories remain exempt on Android, including IPO, UPI mandates, eRupi vouchers, and PACB flows. See [Device-specific UPI rules](#device-specific-upi-rules).

  If you use Cashfree Hosted Checkout, Cashfree has removed Collect from checkout on Android and desktop. If you use a custom checkout or the Order Pay API, remove Collect for non-exempt Android and desktop traffic and upgrade to the latest SDK so UPI Intent is available.
</Accordion>

<Accordion title="Does the UPI Collect deprecation apply in Sandbox as well?">
  Yes. The same UPI Collect deprecation rules apply in both the sandbox and production environments. This is a regulatory change and is not specific to individual accounts.

  To test UPI in sandbox, use **UPI QR Code** (scan with a mobile device) or **UPI Intent** (test on a mobile device or emulated WebView). For device-specific exceptions, see [Does UPI Collect work on Android devices using the Cashfree SDK?](#does-upi-collect-work-on-android-devices-using-the-cashfree-sdk).
</Accordion>

<Accordion title="Why is the option to send a UPI payment collect request to a customer's VPA no longer available?">
  The ability to send a payment collect request to a customer's UPI ID (where the customer enters their VPA and receives a request on their UPI app) is discontinued for merchant payments (P2M) in line with NPCI and RBI guidelines. This regulatory change applies to all payment gateways in India, and Cashfree can't re-enable it. The discontinuation covers both customers entering their UPI ID on the checkout page and merchants sending collect requests from the Merchant Dashboard.

  For alternatives, use UPI QR on desktop and UPI Intent on mobile. See [Device-specific UPI rules](#device-specific-upi-rules).
</Accordion>

<Accordion title="Why do customers only see a QR code and not UPI app icons on mobile?">
  If customers only see a QR code instead of UPI app icons (UPI Intent), the cause is usually the integration environment. For mobile apps using a WebView, UPI Intent requires specific handling to intercept UPI scheme URLs (such as `upi://`, `gpay://`, or `phonepe://`) to launch the respective apps. If your WebView doesn't implement this handling, only the QR code appears.

  For Cashfree Hosted Checkout on mobile browsers, UPI app icons appear automatically. See [UPI Intent in WebView](/docs/payments/online/mobile/misc/upi_intent_support_js_sdk) for implementation details.
</Accordion>

### Support

For questions or technical clarifications, contact Cashfree through the following channels:

* **Support**: [Cashfree support form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1).
* **Account manager**: Reach out to your designated Account manager.

<snippet>snippets/related-topics-loader.mdx</snippet>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/payments/latest/payments/order-pay">Order Pay API</a></li>
    <li><a href="/docs/payments/online/web/custom-checkout-android">Android Custom Checkout</a></li>
    <li><a href="/docs/payments/manage/payment-methods/upi">UPI Overview</a></li>
    <li><a href="/docs/payments/manage/payment-methods/upi">UPI FAQs</a></li>
  </ul>
</div>


# Wallets
Source: https://www.cashfree.com/docs/payments/manage/payment-methods/wallets

Accept wallet payments on Cashfree from popular Indian wallets like Paytm, PhonePe, Amazon Pay, and Mobikwik with one integration and unified reconciliation.

Cashfree supports a wide range of wallets to receive payments.

| Wallet name | Activation |
| - | - |
| Cashfree Pay | <span aria-label="Automatic Activation">AUTOMATIC</span> |
| FreeCharge | <span aria-label="Automatic Activation">AUTOMATIC</span> |
| PayPal | <span aria-label="Self Activate from Dashboard">SELF-ACTIVATE</span> |
| MobiKwik | <span aria-label="Automatic Activation">AUTOMATIC</span> |
| Ola Money | <span aria-label="Automatic Activation">AUTOMATIC</span> |
| Airtel Money | <span aria-label="Automatic Activation">AUTOMATIC</span> |
| Amazon Pay | <span aria-label="Automatic Activation">AUTOMATIC</span> |
| PhonePe | <span aria-label="Automatic Activation">AUTOMATIC</span> |

<AccordionGroup>
  <Accordion title="Activating PayPal from the dashboard">
    <img />
  </Accordion>
</AccordionGroup>


# Instant Refund
Source: https://www.cashfree.com/docs/payments/manage/refunds/instant-refunds

Enable Cashfree instant refunds from the dashboard so customers get their money back in minutes instead of days, improving support experience for returns.

Cashfree allows you to process refunds instantly to your customers. Instant refunds cut down the waiting time for your customers by processing refunds instantly rather than having them wait for 5-7 days. Instant refunds provide a hassle-free customer experience.

Cashfree charges a small instant refund fee to process instant refunds. Instant refunds are currently available on UPI.

## Initiate instant refund from dashboard

1. Log in to the **[Merchant Dashboard](https://merchant.cashfree.com/auth/login)** and go to **Payment Gateway > Transactions > Payments**.
2. Search for the transaction you want to initiate an instant refund, and click **Refund**.
3. Enter the **Refund Amount**, and add a remark if required. You can do a partial or full refund. Click the info icon to view more details on the refund charges.
4. Click **Initiate Refund** to initiate the refund to your customer instantly. Note that the refund amount cannot exceed the maximum amount allowed.

Once you have initiated the refund, you will get a success message on your screen.

You can also initiate an instant refund via API. Click [here](/docs/api-reference/payments/latest/refunds/create-refund) to read more on how to initiate instant refunds.


# Overview
Source: https://www.cashfree.com/docs/payments/manage/refunds/overview

Initiate refunds with Cashfree using the Merchant Dashboard or refund APIs, run batch refunds, and configure webhooks for real-time refund status updates.

You can refund payments to customers when necessary, such as for returned items or cancelled orders. Refunds can be initiated from the Merchant Dashboard or through the API.

When you submit a refund request, the system accepts it instantly. However, you receive the outcome of the refund asynchronously through a refund webhook.

<Tip>Install [Cashfree Agent Skills](/docs/tools-ai/cashfree-agent-skills) to bring Cashfree product knowledge into your AI coding assistant (Claude Code, Cursor, VS Code Copilot, Gemini CLI, and more) to answer integration questions and generate accurate code without leaving your editor.</Tip>

## Refund options

You can process the following types of refunds:

* **Full refund**: Refund the entire captured amount.
* **Partial refund**: Refund a portion of the captured amount.
* **Multiple partial refunds**: Process multiple partial refunds for a single payment. The total of all partial refunds can't exceed the captured amount.

<Note>Some payment methods don't support partial refunds.</Note>

After you initiate a refund, it can take 7 to 10 business days for the funds to be returned to the customer's account, depending on the payment method.

## Refund lifecycle

The refund lifecycle shows the different stages of a refund from when it is initiated until the customer receives the funds.

<img />

## Refund a payment

Cashfree supports two types of refunds:

* **Merchant-initiated refunds**: Refunds that you initiate from your dashboard or API.
* **Auto refunds**: Funds that are reversed to the customer when the payment TTL is breached. For more information, view [Transaction time limit (TTL)](/docs/payments/online/resources/payment-lifecycle#transaction-time-limit).

<Tabs>
  <Tab title="Dashboard">
    ### Single refund

    You can initiate a refund for individual transactions directly from the dashboard. Use this option to process refunds for specific payments that require customer service or order corrections.

    To initiate a single refund:

    1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
    2. Go to **Payment Gateway > Transactions > Payments**.
    3. Search for the transaction that you want to refund.
    4. Select the **Refund** option, enter the refund amount (full or partial), and click **Initiate Refund**.

    <Note>The refund option is only visible for successful transactions that have been settled. Voided or failed transactions will not display the refund option.</Note>

    ### Batch refunds

    Use the Batch Refunds feature to initiate refunds for a large number of payments at a time. Add all the required refund details in a single file as per the required format and upload the file.

    To initiate a batch refund:

    1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
    2. Go to **Payment Gateway > Transactions > Refunds > Batch Refunds > Upload File**.
    3. Download the sample file to know the refund details required in the batch file.
    4. Read the upload instructions before you upload the file.
    5. If the file is not in the suggested format, it will not be uploaded. Resolve any errors in the uploaded file and reupload it.

    ### Auto refunds

    You can track and view all automatic refunds initiated by Cashfree directly from the dashboard. Use this option to monitor refunds triggered for failed payment attempts or other automated scenarios.

    To view auto refunds:

    1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
    2. Go to **Payment Gateway > Transactions > Refunds**.
    3. Select the **Auto Refunds** tab.
  </Tab>

  <Tab title="API">
    ### Prerequisites

    Before you use the refund APIs, ensure that you have the following:

    * A valid Cashfree account.
    * API keys generated from the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
    * The order ID for the refund that you want to process.

    ### Refund APIs

    Use the following APIs to manage refunds:

    * **Create a refund**: Initiate a refund for a successful payment. You can refund the full amount or a partial amount.
    * **Get refund status**: Retrieve the current status and details of a refund.

    | API endpoint | Method | Documentation link |
    | - | - | - |
    | `/pg/orders/{order_id}/refunds` | POST | [Create Refund API](/docs/api-reference/payments/latest/refunds/create-refund) |
    | `/pg/orders/{order_id}/refunds/{refund_id}` | GET | [Get Refund API](/docs/api-reference/payments/latest/refunds/get-refund) |

    ### Refund webhook

    Configure refund webhooks to receive real-time notifications for refund status updates. This enables you to build systems to update refund statuses and send customer communications.

    To set up refund webhooks:

    1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
    2. Go to **Payment Gateway > Developers > Webhooks**.
    3. Add the webhook address and select refund-related events.
    4. Save the webhook configuration.

    For more information, view [Refund webhooks](https://docs.cashfree.com/docs/api-reference/payments/latest/refunds/webhooks).
  </Tab>
</Tabs>

## Auto refunds

Auto refunds are refunds triggered automatically for unsuccessful payments, disputes, duplicate payments, or instances where payments are received directly to your VPA, regardless of whether an order has been generated.

Auto refunds usually occur when customers:

1. Make a payment after the order has reached a terminal state.
2. Make a direct payment to the UPI ID.

Auto refunds differ from standard refunds because they handle refunds that occur automatically (such as failed payment attempts) rather than manual refunds tied to specific orders. Since these automatic refunds may occur before an order is created, they don't contain the usual order-related data fields that are mandatory in standard refund webhooks. For more information, view [Auto-refund webhooks](/docs/api-reference/payments/latest/refunds/webhooks#auto-refund-webhook-payload).

## Refund communication

Customers are kept informed about their refund status and stay up to date on every stage of the process. Refunds, as reversals, involve multiple stages: initiation, processing, cancellation, and potential delays that are essential to monitor. With refund communication, customers receive timely notifications, helping build trust and satisfaction. Customers can also use Cashfree Customer Hub to track these refunds better.

## Refund wallet

<Tip>A refund wallet is a dedicated balance pool for processing customer refunds, separate from your main settlement account. This separation streamlines refund management and improves cash flow control.</Tip>

Refund wallets offer a streamlined and efficient solution for managing your refund process. The following table provides more information:

| Scenario | Without refund wallet | With refund wallet | Advantages |
| - | - | - | - |
| You want to initiate a refund of ₹500 | Current balance = 0<br /><br />Refund goes on hold | Current balance = 0<br /><br />Refund wallet balance = ₹5000<br /><br />Refund successfully processed | Refunds without delays |
| Receive your settlements in full | Current balance = ₹5000<br /><br />Refund adjustments = ₹4300<br /><br />Settled amount = ₹700 | Current balance = ₹5000<br /><br />Settled amount = ₹5000 | Effortless reconciliation |

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/payments/latest/refunds/create-refund">Create Refund API</a></li>
    <li><a href="/docs/api-reference/payments/latest/refunds/get-refund">Get Refund API</a></li>
    <li><a href="/docs/help/end-customer/refunds">FAQs</a></li>
  </ul>
</div>


# Refund Details
Source: https://www.cashfree.com/docs/payments/manage/refunds/refund-details

View Cashfree refund details from the Merchant Dashboard, including status, refund mode, customer payout timeline, and audit logs of every action on the refund.

This guide provides step-by-step instructions on how to view refund and auto refund-related information using the **[Merchant Dashboard](https://merchant.cashfree.com/auth/login)**.

## Viewing refund details

1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).

2. Select **Payment Gateway** from the home page.

3. Under the **Transaction Data** section, select **Refunds**.

4. Select the applicable refunds tab. You can view the following refund tabs:
   * **Initiated Refunds**: View all initiated refunds
   * **Batch Refunds**: Access details of refunds processed in batches
   * **Auto Refunds**: Access details of auto refunds processed by Cashfree

5. Apply the following filters as needed to refine search results:
   * **Timeframe**: Filter refunds within a specific period.
   * **Transaction ID**: Find refund data for a particular transaction.
   * **Refund ID**: Retrieve details for a specific refund.
   * **Order ID**: Search for refunds associated with a specific order.
   * **Customer Phone Number**: Look up refunds by customer phone number.
   * **Email**: Fetch refund details linked to a specific email ID.
   * **Refund Status**: Filter refunds based on their status (**Pending**, **Processed**, **Failed**, etc.).
   * **Refund ARN**: Search using the Acquirer Reference Number.

6. Click on the **Refund ID** to open the detailed refund information section to view the following details:

   * **Refund ETA** (For pending refunds)
   * **Order ID**
   * **Customer Details**
   * **Refund Status**
   * **Refund ID**
   * **Refund ARN** (Acquirer Reference Number)
   * **Refund Speed** (**Instant** / **Standard**)
   * **Refund Processed Date**

   <img />

## Additional features

Use the following options to refine results on the transaction details page:

* **Date Range**: Filter results by a specific date range.
* **Search**: Search the transactions using the following:
  * **Order ID**
  * **Transaction ID**
  * **Refund ID**
  * **CF Refund ID**
  * **Refund ARN**
  * **Email ID**
* **Filters**: Narrow down transactions using the following status:
  * **Refunded**
  * **Pending**
  * **Onhold**
  * **Cancelled**

<Note>
  **Note**

  * Verify your filters and timeframe selection if you cannot find refund data.
  * Contact the [support team](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) for assistance if you encounter any discrepancies.
</Note>


# Reports
Source: https://www.cashfree.com/docs/payments/manage/reports

Download Cashfree Payment Gateway reports for transactions, settlements, refunds, and disputes to reconcile finances and track key business metrics with ease.

To ensure accurate accounting of funds, you can use Cashfree-generated reports for your bookkeeping and reconciliation processes. You can generate those reports automatically according to a specific schedule, or manually on-demand.

Before you start generating reports and building your reconciliation flow, it's important to understand:

* The reports that you can use for reconciliation.
* How various payments are reflected in the reports.
* The types of fees that you can track in the reports.

<Note>
  - All reports can be downloaded in CSV and XLSX format.
  - Reports can be accessed via Dashboard or API.
  - Historical data is available for lifetime and can be downloaded year-wise.
  - Custom date ranges are supported for all reports.
</Note>

## Reports overview

### Steps to download reports from the merchant dashboard

1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
2. From the left navigation menu, select **Reports**.
3. Click on **Generate New Report**.
4. Apply filters such as:
   * **Date Range**: Select the reporting period for example today, last 7 days, this month.
   * **File Name**: Enter a name for the generated report file.
   * **File Format**: Select the output format, either CSV or XLSX.
5. Click **Generate Report**.
6. Once the report is generated, click **Download** to save it.

<Frame>
  <img />
</Frame>

## Report types

Below are the different reports available in the Cashfree Merchant Dashboard. Select a report type to view its details.

<AccordionGroup>
  <Accordion title="Transactions report">
    The transactions report gives you details of all the transactions made during the selected period. This report includes customer details, transaction amount, payment method, transaction status, settlement amount (if the settlement is complete), and more.

    If the transaction involves goods or services from two or more vendors, the transactions report also shows the vendor-wise payment split.

    To generate a new transactions report, fill in the following fields:

    * **Date Range**: Select the reporting period such as today, last 7 days, or this month.
    * **File Name**: Enter a name for the generated report file.
    * **File Format**: The format in which the report has to be generated such as CSV, XLSX.
    * **Status**: The status of the transaction. Possible values: **Success**, **Failed**.
    * **Gateways**: Stripe, etc.
    * Other flags
  </Accordion>

  <Accordion title="Settlement recon report">
    This report has two sections: **Summary** and **Reconciliation Details**.

    * **Summary**: Provides a summarised view of all the settlements received from Cashfree for the selected time period. It includes details like total transaction amount, settlement amount, adjustments, UTR, settlement type, and charges.
    * **Reconciliation Details**: Shows all individual events associated with settlements for the selected time period. Events such as Payments, Refunds, Settlements, and Disputes, along with details for each event, are included in this section.

    Since all events linked to a single settlement are available in one place, reconciliation becomes faster and simpler.

    ### Custom reconciliation fields (`order_tags`)

    Pass custom key-value pairs in the `order_tags` object when you call the [Create Order API](/docs/api-reference/payments/latest/orders/create-order). Each key and value must be a string between 1 and 255 characters. You can add up to 10 tags per order.

    The first three tags you send appear in the **Reconciliation Details** section of the Settlement Recon report as `Key_1`/`Value_1`, `Key_2`/`Value_2`, and `Key_3`/`Value_3`. Tags beyond the first three are stored on the order but aren't shown in this report.

    Choose keys that match how you reconcile payouts in your books—for example branch or outlet ID, campaign or product code, internal invoice reference, or customer segment. Pass only the fields you need in the report and keep `order_tags` to three keys so the correct values map to `Key_1` through `Key_3`.

    **Example: education and multi-institute fee collection**

    ```json theme={"dark"}
    "order_tags": {
      "institute_code": "INST001",
      "roll_number": "2024001234",
      "division": "A"
    }
    ```

    You can filter the Settlement Recon report on `Value_1`, `Value_2`, or `Value_3` to reconcile by institute, student, or division.

    For column definitions and sample values, see the [Settlement Recon report specification](/docs/partners/embedded/reports/settlement-recon-reports#settlement-recon-report-specification).

    Custom fields passed in `order_tags` are populated in the transaction report as well as the Settlement Recon report. To include these fields in settlement reports, you can configure the customization directly from your Merchant Dashboard, or contact the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) to schedule a customized settlement report (daily, weekly, or monthly) with those fields included.

    When using a Partner or Platform integration, pass `order_tags` in the Create Order request body along with the `x-partner-apikey` and `x-partner-merchantid` headers to create an order in the respective merchant's context. These tags will be associated with the transaction and can be consumed via applicable webhook events, depending on the specific webhook's payload schema.
  </Accordion>

  <Accordion title="Settlements report">
    The settlement summary report gives you a consolidated view of all the settlements received from Cashfree for the selected time-period. It includes details like total transaction amount, settlement amount, adjustments, UTR, settlement type, and more. This provides a quick high-level overview of your settlement activity.
  </Accordion>

  <Accordion title="Refunds report">
    The refunds report gives you details of all refunds initiated during the selected time-period. The report includes information such as refund ID, order ID, transaction and refund amount, initiation date, ARN, and refund status. This helps you track customer refunds, monitor timelines, and reconcile refund amounts.
  </Accordion>

  <Accordion title="Ledger report">
    The ledger report summarises all the debits and credits that have occurred in your account for the selected time-period. For every **SETTLEMENT\_COMPUTE (Credit)** entry in the ledger, you can view and reconcile the transaction-level details in the settlement reconciliation report. This report is useful for auditing, tracking cash flow, and verifying your account balance.
  </Accordion>

  <Accordion title="Payment link transactions report">
    This report provides details of all payments received via **Payment Links**. You can view information such as customer details, payment method, transaction amount, payment status, and settlement details. The report helps you track link-based collections, monitor customer payment behaviour, and reconcile Payment Link transactions with your settlements.
  </Accordion>

  <Accordion title="Payment form orders report">
    The Payment Form Orders report provides details of all orders created using **Payment Forms**. It includes customer details, order amount, payment status, settlement details, and timelines. This report helps you track order-level activity, monitor form performance, and reconcile order payments with settlements. If the customer paid through a Payment Form link that includes supported UTM parameters, the captured values appear with the order. See [UTM tracking for Payment Forms](/docs/payments/no-code/payment-forms/utm-tracking).
  </Accordion>

  <Accordion title="softPOS transactions report">
    The softPOS transactions report captures all transactions processed via Cashfree’s **softPOS devices**. You can view details such as payment method (UPI, card), transaction amount, customer details, status, and settlement details. This report is useful for reconciling in-person payments, tracking device usage, and auditing softPOS collections.
  </Accordion>

  <Accordion title="Paytm report">
    The Paytm report provides details of all transactions processed through **Paytm Wallet or Paytm UPI**. It includes information such as transaction ID, order ID, customer details, transaction amount, status, and settlement details. The report helps you track Paytm payments, monitor success or failure rates, and reconcile Paytm transactions with settlements and bank statements.
  </Accordion>

  <Accordion title="Disputes report">
    The disputes report gives you complete visibility into all payment disputes and chargebacks raised by customers. It includes details such as dispute ID, order ID, reason code, dispute amount, date raised, and current status. This report helps you monitor open or pending disputes, review reasons for disputes, and track resolution outcomes.
  </Accordion>

  <Accordion title="Settlement recon offline report">
    This report provides reconciliation details for **offline settlements** that are manually recorded outside Cashfree’s automated systems. It includes settlement amounts, adjustments, UTRs, charges, and associated transaction details. The report helps you match offline settlement activity with Cashfree records and ensures accuracy in reconciliation.
  </Accordion>

  <Accordion title="Settlements offline report">
    The settlements offline report gives you a summarised view of settlements processed outside the automated settlement cycle. It includes settlement date, UTR, settlement amount, and adjustments. This report helps you monitor and reconcile manually handled settlements with bank credits.
  </Accordion>

  <Accordion title="Ledger offline report">
    The ledger offline report tracks offline credits and debits applied to your account. It provides details of balance adjustments, reasons for adjustments, and reconciliation data. This report helps you monitor non-automated ledger entries and ensures accurate financial records.
  </Accordion>

  <Accordion title="Riskshield transactions report">
    The Riskshield transactions report captures transactions flagged by **Cashfree’s Riskshield system**. It includes details such as transaction ID, customer information, risk category, reason for flagging, and status. This report helps you track potentially fraudulent or suspicious activity, monitor fraud detection alerts, and take preventive action.
  </Accordion>

  <Accordion title="Vendor split settlements report">
    This report provides details of settlements split across multiple vendors for a single transaction. It includes order ID, vendor IDs, vendor share amounts, settlement UTR, and adjustments. The report helps you monitor vendor payouts, ensure payout accuracy, and reconcile vendor settlements with your overall transaction flow.
  </Accordion>

  <Accordion title="Vendor recon report">
    The vendor recon report provides reconciliation details for vendor-specific settlements. It includes vendor IDs, transaction IDs, settlement amounts, adjustments, and UTRs. This report helps you match vendor transactions with settlements, verify calculations, and reconcile vendor records.
  </Accordion>

  <Accordion title="Vendor order recon report">
    This report provides reconciliation at the **order level** for vendors. It includes order ID, vendor ID, transaction details, settlement amounts, and adjustments. The report helps you verify accuracy for each vendor order, track discrepancies, and reconcile orders with settlements.
  </Accordion>

  <Accordion title="Subscription payments report">
    The subscription payments report provides detailed information on recurring payments processed via subscriptions. It includes subscription ID, order ID, cycle date, transaction amount, status, and settlement details. This report helps you monitor recurring payments, track failures, and reconcile subscription collections.
  </Accordion>

  <Accordion title="Subscription report">
    The subscription report provides details of all active, inactive, and expired subscriptions. It includes subscription ID, customer details, start and end dates, renewal information, payment method, and status. This report helps you manage subscription lifecycles, track renewals and cancellations, and analyse subscription trends.
  </Accordion>
</AccordionGroup>


# Schedule Reports
Source: https://www.cashfree.com/docs/payments/manage/schedule-reports

Schedule recurring Cashfree reports for transactions, settlements, and refunds to land in your inbox or SFTP automatically and remove manual reconciliation.

Use the **Schedule Reports** dashboard to automate the generation and delivery of reports. You can schedule reports to run daily, weekly, or monthly, and choose your preferred report types and formats. The system delivers reports through the Secure File Transfer Protocol (SFTP). You can also generate a sample report in this dashboard before finalising your schedule. These features help you streamline report management and access critical data on time.

## Navigation

To access the Schedule Reports dashboard:

1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
2. Navigate to **Payment Gateway** > **Reports** > **Schedule Reports**.

The **Schedule Reports** dashboard includes the following sections:

* **Daily Reports**: View reports scheduled to run every day. These reports provide insights into daily performance.

* **Weekly Reports**: View reports scheduled to run every week. Use these for weekly reconciliations and tracking.

* **Monthly Reports**: View reports scheduled to run every month. Use these to review monthly business performance, identify emerging trends, and make informed business decisions.

<img />

<Note>
  If you don't have the Admin role, request access to the Schedule Reports and SFTP Configuration pages through the **User Management** section.

  <Accordion title="How to request access?">
    Enable **SFTP Configuration** and **Schedule Reports** from the **User Management** > **Active Users** page.

    <img />

    For more information, see [Access Management](/docs/help/account/access-management)
  </Accordion>
</Note>

### Features

The dashboard offers the following features:

* **Search and filter**: Find reports by using keywords or filters. Filter options include report type, format, and more.

* **Generate now**: Generate a report instantly. Use this option to preview the reports sent to your SFTP.

## Schedule a report

To schedule a report, follow these steps:

1. Select **Schedule Reports** to open the scheduling pop-up window.

2. In the **Report Details** section, complete the following fields, and then select **Next**:

   * **Report Type**: Select the type of report. Available options include:
     * **Transactions**
     * **Settlement Reconciliation**
     * **Disputes**
     * **Refunds**
     * **Ledger**

   * **File Name**: Enter a name for the report file. The system will automatically append the date range of the report to the file name.

   * **File format**: Select a file format: `.csv` or `.xlsx`.

3. In the **Delivery schedule** section, complete the following fields, and then select **Next**:

   * **Frequency**: Select how often the report is delivered. Options include **Daily**, **Weekly**, or **Monthly**.

   * **Data Time Frame**: Select the time for the report data. For example, **Previous Month** or **Current Month**.

   * **Time**: Specify the time of day and day of the week (if applicable) for the report delivery.

4. In the **Delivery Channel** section, verify the SFTP details, and then select **Next**.

<Note>
  **Note**:

  * Complete the SFTP server configuration with **Cashfree** before scheduling reports.
  * If your SFTP server is already configured, proceed to the next step.
  * To configure your SFTP server, see [Configuring SFTP server](/docs/payments/manage/schedule-reports#configure-the-sftp-server).
</Note>

5. Select **Create Schedule** to save your report schedule.

<CardGroup>
  <Card />

  <Card />

  <Card />
</CardGroup>

## Configure the SFTP server

Follow these steps to configure your SFTP server for report delivery.

1. Add the following Cashfree IP addresses to your SFTP server’s firewall allowlist:
   * `52.66.101.190`
   * `3.109.102.144`
   * `18.60.134.245`
   * `18.60.183.142`

2. Enter the following SFTP server details:

   * Host and port
   * Username and password
   * Target directory for report uploads

<Note>
  The SFTP user must have write permissions for the specified directory.
</Note>

3. Select **Test Configuration** to verify that the SFTP integration is working correctly.

4. To update the SFTP configuration:
   * Select **Edit SFTP Configuration** at the top-right corner of the page.
   * Update the required fields in the pop-up form.

5. After editing the details, repeat **Step 3** to confirm that the updated configuration works as expected.

<Note>
  Changes to the SFTP configuration apply to all existing scheduled reports.
</Note>


# Settlements
Source: https://www.cashfree.com/docs/payments/manage/settlements

Track Cashfree settlements, view payout schedules, configure instant settlements, and reconcile balances credited to your bank from the Merchant Dashboard.

Settlements refer to the process of transferring funds to your bank account. Cashfree aggregates the transaction amount and deducts applicable charges and adjustments such as refunds and chargebacks before transferring.

By streamlining the transfer of funds and providing detailed transaction information, Cashfree helps you manage your finances efficiently and effectively.

<Tip>Install [Cashfree Agent Skills](/docs/tools-ai/cashfree-agent-skills) to bring Cashfree product knowledge into your AI coding assistant (Claude Code, Cursor, VS Code Copilot, Gemini CLI, and more) to answer integration questions and generate accurate code without leaving your editor.</Tip>

```mermaid theme={"dark"}
flowchart TD
    note1[Payment is queued to settlement engine]
    PS[Payment Successful] --> note1
    note1 --> SE[Settlement Engine]
    
    SE -->|Compute| D{How Much and When?}
    note2[A series of decisions are made on when to settle the transaction, how much to settle]
    D --> note2
    
    D -->|Payout| MB[Your &lpar;Merchant&rpar; Bank Account]
    
    SE -.-> EA[Cashfree Escrow Bank Account]
    note4[Acquiring bank settles money to Cashfree]
    note4 --> EA
    
    
    EA -.-> MB
    
    style PS fill:#e6e6fa
    style SE fill:#e6e6fa
    style EA fill:#e6e6fa,stroke-dasharray: 5 5
    style MB fill:#ffb6c1
    style note1 fill:transparent,stroke:none
    style note2 fill:transparent,stroke:none
    style note4 fill:transparent,stroke:none
```

<Tip>
  By default Cashfree processes your settlements with a frequency of T+2 bank
  working days for a payment done on day T. You can get this updated by filling out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1).
</Tip>

## Instant settlements

Cashfree's Instant Settlements lets you receive funds almost instantly instead of waiting for the standard T+1 or T+2 settlement cycles. This helps if you need urgent access to your funds.
To be eligible for Instant Settlements, you must meet specific criteria. To learn more about Instant Settlements, fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1).

## Settlement reversals

There are scenarios when a payout initiated from Cashfree's bank account to your bank account might get reversed. In these scenarios, we mark those settlements as reversed. We also initiate a [webhook to you once a settlement reversal happens](/docs/api-reference/payments/latest/settlements/settlement-webhooks).

Here are some common reasons which can lead to a settlement reversal.

<Accordion title="Settlement reversal reasons">
  | Reasons | |
  | - | - |
  | Due to some technical issues at the bank, your amount will be settled in the next settlement cycle. | |
  | The IFSC you have provided for the bank account is invalid, Fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) with the valid IFSC. | |
  | Bank account details you have provided are invalid, Fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) with the updated account details. | |
  | Due to some technical error at the bank, your amount will be settled in the next settlement cycle. | |
  | Due to some technical issues, your amount will be settled in the next settlement cycle. | |
  | Settlements to NRE bank accounts is currently not possible, Fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) with the updated account details. | |
  | Bank account details you have provided isn't active, Fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) with the updated account details. | |
  | You have exceeded the transfer limit for this settlement cycle. Cashfree processes your settlement in the next settlement cycle. | |
  | Beneficiary name you have provided is incorrect, Fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) with the updated details. | |
  | Unable to settle amount to this beneficiary account, Fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) with the updated account details. | |
  | Your bank account details or the IFSC you have provided is invalid, Fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) with the updated details. | |
  | Bank account details you have provided is invalid, Fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) with the updated details. | |
</Accordion>

## FAQs

<AccordionGroup>
  <Accordion title="What are settlements?">
    Settlements refer to the process of transferring funds to your (merchant) bank account after aggregating the transaction amount and deducting our applicable charges and adjustments (Refunds, Chargebacks, etc). [Learn more about settlements](/docs/payments/manage/settlements).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are the different types of settlements?">
    The different types of settlements are as follows:

    1. **Standard settlements (Default)**: Standard settlements are processed on a T+1 or T+2 basis, depending on your configured settlement cycle:
       * T+1: The amount is settled on the next business day after the transaction.
       * T+2: The amount is settled two business days after the transaction.
         <Note>Business days exclude weekends and bank holidays. If the scheduled settlement day falls on a non-working day, the settlement will occur on the next working day.</Note>

    For example:

    * If a transaction occurs on Friday, June 3:
      * For T+1 settlement, funds will be settled on Monday, June 6, as Saturday and Sunday are non-working days.
      * For T+2 settlement, funds will be settled on Tuesday, June 7.

    2. **Instant settlements**: Instant Settlements enable you to access your funds within 15 minutes, significantly faster than the standard T+2 settlement cycle.

    3. **On-demand settlements**: On-demand settlements allow instant fund transfers to your bank 24x7, including holidays, for a small fee. Activation is required, as the default cycle is T+2 days.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How do I check settlements in my bank account?">
    Each settlement includes a Unique Transaction Reference (UTR) provided by our banking partners. You can view this number in the settlement section by clicking on a specific settlement ID. Additionally, Settlement Reports can be downloaded from the Reports section to access the UTR, which serves as a unique reference across banks for tracking specific settlements in your bank account.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Which account receives the settlement amount, and how can I view it?">
    Settlements are credited to the bank account you add when you set up your merchant account. Settlements include the total transaction value minus any applicable charges and adjustments.

    To view or manage your settlement bank account, go to **[Payment Gateway Dashboard](https://merchant.cashfree.com/merchants/pg/settings/bank-accounts?env=prod) > Settings > Bank Accounts** in your .

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="My Settlement isn't credited yet, what do I do?">
    If your settlement is scheduled for today, please wait until the end of the day (EOD).
    In the rare case of a delay from the bank’s side (such as due to network issues or public holidays), we’ll keep you informed and share updates as soon as possible.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="If my settlement failed previously, can it be attempted again?">
    If your settlement fails, it will automatically be reattempted during your next settlement cycle.
    The settlement will reinitiate only if you are an active transacting merchant, which means you must have at least one successful transaction during that cycle.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="The status of my settlement shows as failed on the Dashboard. What do I do?">
    Based on the settlement’s failure reason, take the corrective actions and this will get settled in the next settlement cycle.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How does on-demand settlement work, and what are the steps to activate it?">
    With on-demand settlements, you can request settlements to your bank account on any day and at any time 24x7, including holidays.

    You can specify the amount you want to withdraw as per your requirement. A small fee is applicable to process these settlements. On-demand settlements enable you to receive the unsettled amount to your bank account instantly 24x7 including holidays.

    By default, the settlement cycle is t+2\* days, where 't' is the day of the transaction. To use on-demand settlements, the feature must be enabled.

    <img alt="1200" />

    On-Demand Settlement Flow

    ### Activate on-demand settlements

    To enable instant settlement from the Cashfree dashboard:

    1. Go to the Payment Gateway Dashboard.
    2. Navigate to the Settlements section.
    3. Look for the On-Demand Settlements option.
       If you're eligible, you'll see options to configure On-Demand settlements.

    After activation, you can request settlements instantly 24x7 including holidays.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How to initiate On-Demand Settlements?">
    1. Go to Payment Gateway Dashboard > Settlements > On-Demand.

    2. In the On-Demand settlement screen, click Request Activation. The feature activation request will be sent to your Cashfree account manager, and they will enable it for you. You will receive an email after the feature has been activated.

    After activation, you can request settlements instantly 24x7 including holidays.

    ### Initiate on-demand settlement

    To initiate an on-demand settlement, you must first get the feature activated. After activation, you can request settlements instantly 24x7 including holidays.

    To initiate on-demand settlement,

    1. Go to Payment Gateway Dashboard > Settlements > On-Demand > click Settle Now.

    2. In the On-Demand Settlement screen, specify the amount you want to withdraw and click Confirm. You will see the amount you are allowed to withdraw and the additional charges applicable is also shown.

       <img alt="3584" />

    Settlement Amount
    You will see a success screen as shown below:

    <img alt="3584" />

    Settlement Success

    You will see all the settlements received in the Settlements > On-Demand screen. You can click the individual settlements to know more details.

    <Note>
      Settlement cycle is subject to bank approval and can vary based on transaction type, business category/model, risk parameters and other factors.
    </Note>

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Is there a bank holidays list I can refer to for settlement purpose?">
    At Cashfree, we follow the RBI's bank holiday list for Mumbai. You can refer to the [RBI bank holiday list](https://www.rbi.org.in/Scripts/HolidayMatrixDisplay.aspx). There can be other holidays that banks may observe which may vary bank to bank and state to state. We send regular updates related to settlements, to receive the emails, you can get your email ID for settlement notifications using your Cashfree Dashboard.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title=" How are settlements processed?">
    Cashfree offers you the fastest settlement cycle. By default the settlement cycle will be T+2\* days, which means a payment captured on Monday, will be credited to your account on Wednesday i.e three working days.

    <Note>
      The settlements aren't processed on banking holidays. You can refer to the [RBI's bank holiday list](https://www.rbi.org.in/Scripts/HolidayMatrixDisplay.aspx).
    </Note>

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What is an instant settlement?">
    Cashfree’s instant settlements enable businesses to receive funds almost instantly, with cycles starting from 15 minutes, reducing the standard T+1 or T+2 settlement periods. Eligibility requires meeting specific criteria. For more information, fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1).

    Instant settlement is an advanced payment gateway feature offered by Cashfree that lets you access your funds within 15 minutes of payment capture from the customer. This will help you to respond faster to new business opportunities, and get complete control over your working capital.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How instant settlements will help you grow your businesses?">
    * Manage your working capital better: With instant access to your funds, you can plan your business expenditure better and drive your business towards growth. This can also help avoid the dependency on costly short-term loans to meet business needs.

    - Make fool-proof projections: You can now plan your short-term business goals better without the need to assume the revenue you are yet to receive. You can take calculated risks based on your liquidity and not shoot in the dark.

    - Handle refunds and chargebacks better: The uncertainty around the usual settlement cycles often affect transactions where the customer has requested for a refund or a chargeback immediately. With instant settlements, you get instant access to those funds and in case of refunds or chargebacks, you can happily reverse the payments instantly, without the need to incur any loss for those transactions.

      <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Are there any processing fees for instant settlements?">
    Yes, a nominal fee is applied for processing instant settlements.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Is there any limit on instant settlements?">
    Yes, we've introduced limits on instant settlements to streamline the settlement process and meet your daily needs. With limits, you can:

    * Settle a specified amount up to the assigned limit until the next working day.

    * Benefit from faster and higher success rates throughout the working day.

    For any queries, fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1)

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title=" How do I enable instant settlements?">
    To activate instant settlements (IS) for your account, please follow the steps below:

    * Your account already comes with a ₹50,000/- settlement limit auto-activated for instant settlements.
    * If you want to increase this limit, you can [request activation on the Merchant Dashboard](https://merchant.cashfree.com/merchants/pg/settlements/standard) for your account.
    * Once the request is submitted, your account will be reviewed and, if eligible, instant settlements will be enabled for you.

    If you have any further queries, please reach out to us through the 24/7 [Chatbot](https://merchant.cashfree.com/common/settings?open=chat) on the Merchant Dashboard.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are the eligibility criteria and activation requirements for instant settlements?">
    To be eligible for instant settlements, the following conditions must be met:

    * Your merchant account must be fully onboarded and KYC-verified (business details, bank account, etc).

    * Your transaction history, business category, risk profile and bank approval must satisfy the criteria for instant settlements.

    * The feature is subject to the account being configured and the merchant being deemed eligible; once your request is submitted, it will be reviewed and enabled where applicable.

    Once enabled, you'll see the instant settlement limits and usage in **Merchant Dashboard → Payment Gateway → Settlements → Online**.

    After activation or limit-increase, you will be able to use instant settlements (funds credited within \~15 minutes) instead of the standard T+1/T+2 settlement cycle.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How do I check unsettled amount?">
    You can check the unsettled amount from the **Summary and Settlement** sections of the Merchant Dashboard.

    1. Log in to your account on the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
    2. Navigate to the **Summary** section on the Payment Gateway module. This section displays:
       * The total transaction amount for the day.
       * The amount to be settled (unsettled amount).
    3. For a detailed view:

       1. Navigate to the **Settlement** section.
       2. Select the Standard option.

       The unsettled amount will be displayed on the screen.

       <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What fields are included in Cashfree settlement reconciliation reports?">
    Cashfree settlement reconciliation reports and APIs include transaction and settlement-related details. The data contains fields such as Settlement ID, UTR, Order ID, Cashfree Payment ID, Transaction Amount, Settlement Amount, Service Charges, GST, Payment Mode, Settlement Status, and Customer Details. This allows for reconciliation at an individual order level.

    You can access settlement reconciliation data from:

    * The [Settlement Reconciliation API](/docs/api-reference/payments/latest/settlement-reconciliation/settlement-reconciliation)
    * Downloadable reports from your Merchant Dashboard under **Payment Gateway > Reports**
  </Accordion>

  <Accordion title="What do the SETTLEMENT_INITIATED and SETTLEMENT_SUCCESS statuses mean?">
    * **SETTLEMENT\_INITIATED**: This is an internal Cashfree status indicating that the settlement cycle has been triggered and the batch is being prepared. The transfer instruction has not yet been sent to the bank. Do not trigger downstream payouts based on this status.

    * **SETTLEMENT\_SUCCESS**: This means Cashfree has sent the settlement instruction to the bank and the bank has acknowledged it. This status is typically accompanied by a UTR (Unique Transaction Reference) number in the webhook payload, confirming the instruction (NEFT/IMPS/RTGS) has been submitted to the banking network.
  </Accordion>

  <Accordion title="How can I confirm that settlement funds have actually been credited to my bank account?">
    Cashfree does not receive a real-time confirmation callback from banks for final credit. The `SETTLEMENT_SUCCESS` status combined with a UTR number is the terminal confirmation event from Cashfree. To confirm actual receipt, reconcile your bank statement against the UTR number provided in the `SETTLEMENT_SUCCESS` webhook payload.

    Typical credit timelines after `SETTLEMENT_SUCCESS`:

    | Payment rail | Typical credit time |
    | :- | :- |
    | IMPS | 0–30 minutes |
    | NEFT | 30 minutes to 2 hours (depending on batch timing) |
    | RTGS | Same banking day, usually within 2 hours |
  </Accordion>

  <Accordion title="What happens if a settlement fails or is reversed?">
    Cashfree provides webhooks for failure and reversal scenarios:

    * **SETTLEMENT\_FAILED**: Triggered if the bank rejects the instruction (for example, due to incorrect account details). Funds return to Cashfree's nodal account, and a re-settlement is typically attempted in the next cycle. This event fires within a few hours of failure.
    * **SETTLEMENT\_REVERSED**: Triggered if a previously successful settlement is reversed by the bank (for example, due to compliance holds). This typically occurs within 1–3 banking days.
  </Accordion>

  <Accordion title="How do I determine if a settlement is successful when the Settlement Reconciliation API has no status field?">
    The [Settlement Reconciliation API](/docs/api-reference/payments/latest/settlement-reconciliation/settlement-reconciliation) returns event-level reconciliation rows and does not include a dedicated `status` field on `settlement_details`. If `settlement_utr` is present, treat the settlement instruction as submitted for reconciliation. To read settlement status (`SUCCESS`, `PENDING`, `PENDING_WITH_CASHFREE`, `PENDING_WITH_BANK`, or `FAILED`), use the [Get All Settlements API](/docs/api-reference/payments/latest/settlement-reconciliation/get-all-settlements).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How are settlement reversals handled, and how can I track them?">
    The Settlement Reconciliation API does not return a reversal status. Subscribe to the `SETTLEMENT_REVERSED` webhook to track reversals. For the difference between `SETTLEMENT_FAILED` and `SETTLEMENT_REVERSED`, see [Settlement Webhooks](/docs/api-reference/payments/latest/settlements/settlement-webhooks).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How can I automate my transaction and settlement reconciliation process?">
    Reconciliation has two parts: confirming each customer payment, then matching the settlement credit in your bank statement to Cashfree's UTR. Automate both with webhooks for events, reconciliation APIs for line-item data, and scheduled reports if you prefer file delivery.

    To automate the process:

    1. Subscribe to [Payment Webhooks](/docs/api-reference/payments/latest/payments/webhooks) for transaction status, and to [Settlement Webhooks](/docs/api-reference/payments/latest/settlements/settlement-webhooks) for `SETTLEMENT_SUCCESS`, `SETTLEMENT_FAILED`, and `SETTLEMENT_REVERSED`. Treat `SETTLEMENT_SUCCESS` and `settlement_utr` as Cashfree's terminal event, then match that UTR to your bank statement.
    2. Call the [Settlement Reconciliation API](/docs/api-reference/payments/latest/settlement-reconciliation/settlement-reconciliation) after a settlement webhook, using the settlement ID, UTR, or date range. The response includes customer, order, payment, and `settlement_utr` on each event row. Use the [Get All Settlements API](/docs/api-reference/payments/latest/settlement-reconciliation/get-all-settlements) when you need settlement `status`.
    3. Use the [PG Reconciliation API](/docs/api-reference/payments/latest/pg-reconciliation/pg-reconciliation) when you need payment-account events for a date range.
    4. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and go to **Payment Gateway > Reports > Schedule Reports**. Schedule **Settlement Reconciliation** and **Transactions** reports over SFTP (Secure File Transfer Protocol) instead of polling APIs. See [Schedule Reports](/docs/payments/manage/schedule-reports).

       <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How do I use the Settlement Reconciliation API, and what version should I use?">
    Use the [Settlement Reconciliation API](/docs/api-reference/payments/latest/settlement-reconciliation/settlement-reconciliation) (`POST /settlement/recon`) to fetch settlement reconciliation details. It uses standard `x-client-id` and `x-client-secret` authentication. No separate enablement is required. Pass `x-api-version: 2026-01-01`.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are the rate limits and recommended date windows for the Settlement Reconciliation API?">
    The [Settlement Reconciliation API](/docs/api-reference/payments/latest/settlement-reconciliation/settlement-reconciliation) uses cursor-based pagination. The default `pagination.limit` is 10. The maximum is 1000, though your account configuration can set a lower maximum.

    For historical backfills, keep each date window short (for example, 1 to 7 days) and page through results using the cursor returned in the response.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How can I identify the MDR and GST charged for a specific transaction in the settlement reconciliation report?">
    In the Settlement Reconciliation API response, use the following fields:

    * `event_service_charge`: the MDR amount for that transaction.
    * `event_service_tax`: the GST charged on that MDR.

    The net settlement amount is calculated as:

    ```text theme={"dark"}
    event_settlement_amount = event_amount - event_service_charge - event_service_tax
    ```

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How do I verify the signature for Cashfree settlement webhooks?">
    Settlement webhooks use the same signature headers as other Cashfree Payments webhooks. Verify the `x-webhook-signature` against the timestamp and raw request body before you process the payload.

    For the full procedure and code samples, see [Webhook signature verification](/docs/payments/online/webhooks/signature-verification).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What event types are used in the Settlement Reconciliation API to distinguish between payments, refunds, and disputes?">
    The Settlement Reconciliation API uses the `event_type` field to categorise transactions. Possible values are:

    | `event_type` | Description |
    | - | - |
    | `PAYMENT` | Successful payment credit |
    | `REFUND` | Refund debit from settlement |
    | `REFUND_REVERSAL` | Reversal of a refund |
    | `DISPUTE` | Dispute debit |
    | `DISPUTE_REVERSAL` | Reversal of a dispute |
    | `CHARGEBACK` | Chargeback debit |
    | `CHARGEBACK_REVERSAL` | Reversal of a chargeback |
    | `OTHER_ADJUSTMENT` | Manual or other adjustments |

    For refund records, `sale_type` is `DEBIT` and `bank_reference` contains the refund UTR.

    <iframe title="FAQs feedback component" />
  </Accordion>
</AccordionGroup>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/payments/latest/settlement-reconciliation/settlement-reconciliation">Settlement Reconciliation API</a></li>
    <li><a href="/docs/api-reference/payments/latest/settlements/settlement-webhooks">Settlement Webhooks</a></li>
    <li><a href="/docs/payments/manage/reports">Payment Reports</a></li>
  </ul>
</div>


# Transactions
Source: https://www.cashfree.com/docs/payments/manage/transactions

View, search, and export Cashfree transactions from the Merchant Dashboard, filter by status, payment method, and customer, and dive into order details.

This guide provides step-by-step instructions on how to view transaction details using the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).

## Viewing transaction details

1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).

2. Select **Payment Gateway** from the home page.

3. Select **Payments** under the **Transaction** section. This displays the transaction dashboard.

4. Click on the **Transaction ID** to view the following details:

   * **Order ID**: A unique identifier assigned to the order.
   * **Order Note**: Additional information or comments related to the order.
   * **Customer Details**
     * **Name**: The name of the customer.
     * **Email**: The customer's registered email address.
     * **Phone Number**: The customer's contact number.
     * **Customer Reference ID**: A unique identifier assigned to the customer.
     * **IP Address**: The IP address from which the transaction was initiated.
   * **Timeline**: Provides a detailed record of the transaction's progress, including
     * **Bank Reference Number**: A unique identifier assigned by the bank for the transaction.
     * **Transaction Status**: Indicates whether the transaction was **Success**, **Pending**, or **Failed**.
     * **Error Description**: A message explaining why the payment was declined.
     * **Error Source**: Identifies the origin of the error, such as the bank.
     * **Transaction Message**: A message explaining the reason for transaction rejection, such as Transaction Rejected due to potential risk.
     * **Error Code**: A specific code associated with the transaction failure, such as **TRANSACTION\_DECLINED**.
     * **Error Reason**: The underlying cause of the failure, such as **debit\_failed**.
   * **Transaction Logs**: A record of all transaction-related activities for troubleshooting and auditing purposes.

   <img />

## Additional features

Use the following options to refine results on the transaction details page:

* **Date Range**: Filter results by a specific date range.
* **Search & Filters**: Narrow down transactions using the following criteria:
  * **Order ID**
  * **Transaction ID**
  * **Customer Reference ID**
  * **Phone Number**
  * **Customer's Phone Number**
  * **Email ID**
  * **Bank Reference Number**
* **Filters**: Narrow down transactions using the following:
  * **Status**: Filter the transactions using status such as **Success**, **Pending**, **Failed**, **User Dropped**.
  * **Payment Methods**: Filter the transactions using payment methods.

<Note>
  **Note**

  * Verify your filters and timeframe selection if you cannot find refund data.
  * Contact the support team for assistance if you encounter any discrepancies.
</Note>


# Migration to Version 2023-08-01
Source: https://www.cashfree.com/docs/payments/migration/migration

Migrate from older Cashfree Payment Gateway APIs to the 2023-08-01 version using mapping tables, request and response changes, and upgrade instructions.

This migration guide is for merchants on version V1 or V2. **Merchants using version V3 (2022-09-01) don't need to use this as their migration guide**. Please check the [migration overview](/docs/payments/migration/overview) for changes from V3.

## New payment gateway integration flow

### 1. Change API version

Change x-api-version in header to **2023-08-01**

### 2. Create order from backend

You'll get payment\_session\_id in the response of [create order](/docs/api-reference/payments/latest/orders/create-order) (instead of order\_token and payment\_link)

Below is the request and response you get when you create an order.

**Request**

<CodeGroup>
  ```typescript Typescript theme={"dark"}
  import { Cashfree } from "cashfree-pg"; 

  Cashfree.XClientId = {Client ID};
  Cashfree.XClientSecret = {Client Secret Key};
  Cashfree.XEnvironment = Cashfree.Environment.PRODUCTION;

  function createOrder() {
    var request = {
      "order_amount": "1",
      "order_currency": "INR",
      "customer_details": {
        "customer_id": "node_sdk_test",
        "customer_name": "",
        "customer_email": "example@gmail.com",
        "customer_phone": "9999999999"
      },
      "order_meta": {
        "return_url": "https://test.cashfree.com/pgappsdemos/return.php?order_id=order_123"
      },
      "order_note": ""
    }

    Cashfree.PGCreateOrder("2023-08-01", request).then((response) => {
      var a = response.data;
      console.log(a)
    })
      .catch((error) => {
        console.error('Error setting up order request:', error.response.data);
      });
  }
  ```

  ```python Python theme={"dark"}
  from cashfree_pg.models.create_order_request import CreateOrderRequest
  from cashfree_pg.api_client import Cashfree
  from cashfree_pg.models.customer_details import CustomerDetails


  Cashfree.XClientId = {Client ID}
  Cashfree.XClientSecret = {Client Secret Key}
  Cashfree.XEnvironment = Cashfree.XSandbox
  x_api_version = "2023-08-01"

  def create_order():
          customerDetails = CustomerDetails(customer_id="123", customer_phone="9999999999")
          createOrderRequest = CreateOrderRequest(order_amount=1, order_currency="INR", customer_details=customerDetails)
          try:
              api_response = Cashfree().PGCreateOrder(x_api_version, createOrderRequest, None, None)
              print(api_response.data)
          except Exception as e:
              print(e)
  ```

  ```java Java theme={"dark"}
  import com.cashfree.*;

  Cashfree.XClientId = {Client Key};
  Cashfree.XClientSecret = {Client Secret Key};
  Cashfree.XEnvironment = Cashfree.SANDBOX;

  static void createOrder() {
    CustomerDetails customerDetails = new CustomerDetails();
    customerDetails.setCustomerId("123");
    customerDetails.setCustomerPhone("9999999999");

    CreateOrderRequest request = new CreateOrderRequest();
    request.setOrderAmount(1.0);
    request.setOrderCurrency("INR");
    request.setCustomerDetails(customerDetails);
    try {
      Cashfree cashfree = new Cashfree();
      ApiResponse<OrderEntity> response = cashfree.PGCreateOrder("2023-08-01", request, null, null, null);
      System.out.println(response.getData().getOrderId());

    } catch (ApiException e) {
      throw new RuntimeException(e);
    }
  }
  ```

  ```go Go theme={"dark"}
  import (
    cashfree "github.com/cashfree/cashfree-pg/v3"
  )

  func createOrder() {

  clientId := {Client ID}
  clientSecret := {Client Secret Key}
  cashfree.XClientId = &clientId
  cashfree.XClientSecret = &clientSecret
  cashfree.XEnvironment = cashfree.SANDBOX

  request := cashfree.CreateOrderRequest{
  		OrderAmount: 1,
  		CustomerDetails: cashfree.CustomerDetails{
  			CustomerId:    "1",
  			CustomerPhone: "9999999999",
  		},
  		OrderCurrency: "INR",
  		OrderSplits:   []cashfree.VendorSplit{},
  	}
  	version := "2023-08-01"
  	response, httpResponse, err := cashfree.PGCreateOrder(&version, &request, nil, nil, nil)
  	if err != nil {
  		fmt.Println(err.Error())
  	} else {
  		fmt.Println(httpResponse.StatusCode)
  		fmt.Println(response)
  }

  }
  ```

  ```csharp C# theme={"dark"}
  using cashfree_pg.Client;

  using cashfree_pg.Model;

  Cashfree.XClientId = {Client ID};

  Cashfree.XClientSecret = {Client Secret Key};

  Cashfree.XEnvironment = Cashfree.PRODUCTION;

  var cashfree = new Cashfree();

  var xApiVersion = "2023-08-01";

  void CreateOrder() {
      var customerDetails = new CustomerDetails("123", null, "9999999999");
      var createOrdersRequest = new CreateOrderRequest(null, 1.0, "INR", customerDetails);
      try {
          // Create Order
          var result = cashfree.PGCreateOrder(xApiVersion, createOrdersRequest, null, null, null);
          Console.WriteLine(result);
          Console.WriteLine(result.StatusCode);
          Console.WriteLine((result.Content as OrderEntity));
      } catch (ApiException e) {
          Console.WriteLine("Exception when calling PGCreateOrder: " + e.Message);
          Console.WriteLine("Status Code: " + e.ErrorCode);
          Console.WriteLine(e.StackTrace);
      }
  }
  ```

  ```php PHP theme={"dark"}
  \Cashfree\Cashfree::$XClientId = "<x-client-id>";
  \Cashfree\Cashfree::$XClientSecret = "<x-client-secret>";
  \Cashfree\Cashfree::$XEnvironment = Cashfree\Cashfree::$SANDBOX;

  $cashfree = new \Cashfree\Cashfree();

  $x_api_version = "2023-08-01";
  $create_orders_request = new \Cashfree\Model\CreateOrdersRequest();
  $create_orders_request->setOrderAmount(1.0);
  $create_orders_request->setOrderCurrency("INR");
  $customer_details = new \Cashfree\Model\CustomerDetails();
  $customer_details->setCustomerId("123");
  $customer_details->setCustomerPhone("9999999999");
  $create_orders_request->setCustomerDetails($customer_details);

  try {
      $result = $cashfree->PGCreateOrder($x_api_version, $create_orders_request);
      print_r($result);
  } catch (Exception $e) {
      echo 'Exception when calling PGCreateOrder: ', $e->getMessage(), PHP_EOL;
  }
  ```

  ```curl cURL theme={"dark"}
  curl --location 'https://sandbox.cashfree.com/pg/orders' \
  --header 'X-Client-Secret: {{clientKey}}' \
  --header 'X-Client-Id: {{clientId}}' 
  --header 'x-api-version: 2023-08-01' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data-raw '{
    "order_amount": 10.10,
    "order_currency": "INR",
    "customer_details": {
      "customer_id": "USER123",
      "customer_name": "joe",
      "customer_email": "joe.s@cashfree.com",
      "customer_phone": "+919876543210"
    },
    "order_meta": { 
      "return_url": "https://b8af79f41056.eu.ngrok.io?order_id=order_123"
    }

  }'
  ```
</CodeGroup>

**Response**

```
{
  "cf_order_id": "1539553",
  "created_at": "2021-07-19T16:13:35+05:30",
  "customer_details": {
    "customer_id": "7112AAA812234",
    "customer_name": null,
    "customer_email": "john@cashfree.com",
    "customer_phone": "9908734801",
    "customer_uid": null
  },
  "entity": "order",
  "order_amount": 5.01,
  "order_currency": "INR",
  "order_expiry_time": "2021-08-18T16:13:34+05:30",
  "order_id": "order_271vWwzSQOHe01ZVXpEcguVxQSRqr",
  "order_meta": {
    "return_url": "https://b8af79f41056.eu.ngrok.io?order_id=order_123",
    "payment_methods": null
  },
  "order_note": null,
  "order_status": "PAID",
  "payment_session_id": "session_7NvteR73Fh11P3f3bNdcubIAJgBJJgGK9diC6U5jvr_jfWBS8o-Z2iPf20diqBMVfWDwvARGrISZRCPoDSWjw4Eb1GrKtoZZQT_BWyXW25fD"
}
```

If you want to create a split order - create a order with Split from backend. You will get the 'payment\_session\_id' in the response of [create order](/docs/api-reference/payments/latest/orders/create-order) (instead of order\_token and payment\_link).

Below is the request and the response when you create an order with split.

<CodeGroup>
  ```curl Create Order with Split Request theme={"dark"}
  curl --request POST \
       --url https://sandbox.cashfree.com/pg/orders \
       --header 'accept: application/json' \
       --header 'content-type: application/json' \
       --header 'x-api-version: 2023-08-01' \
       --header 'x-client-id: xxxx' \
       --header 'x-client-secret: xxxx' \
       --data '
  {
       "customer_details": {
            "customer_id": "7112AAA812234",
            "customer_email": "john@cashfree.com",
            "customer_phone": "9908734801",
            "customer_bank_ifsc": "CITI0000001",
            "customer_bank_account_number": "1518121112",
            "customer_bank_code": 3333
       },
       "order_splits": [
            {
                 "vendor_id": "Vendor01",
                 "amount": 100
            },
            {
                 "vendor_id": "Vendor02",
                 "amount": 200
            }
       ],
       "order_amount": 400.15,
       "order_id": "386752t78",
       "order_currency": "INR",
       "order_expiry_time": "2023-02-29T00:00:00Z",
       "order_note": "Test order"
  }
  '
  ```

  ```json Create Order with Split Response theme={"dark"}
  {
    "cf_order_id": "3615229",
    "created_at": "2023-02-03T16:00:25+05:30",
    "customer_details": {
      "customer_id": "7112AAA812234",
      "customer_name": null,
      "customer_email": "john@cashfree.com",
      "customer_phone": "9908734801",
      "customer_uid":null
    },
    "entity": "order",
    "order_amount": 400.15,
    "order_currency": "INR",
    "order_expiry_time": "2023-02-27T05:30:00+05:30",
    "order_id": "386752t78",
    "order_meta": {
      "return_url": null,
      "notify_url": null,
      "payment_methods": null
    },
    "order_note": "Test order",
    "order_splits": [
      {
        "vendor_id": "kyc10",
        "amount": 100,
        "percentage": null
      },
      {
        "vendor_id": "11testkyc",
        "amount": 200,
        "percentage": null
      }
    ],
    "order_status": "ACTIVE",
    "order_tags": null,
    "payment_session_id": "session_2C6iky7TTw6eOy4MCNQjJvw0ZR3qXK_xedGM-7uBGlF8oZiKeji8-oCMqdcIy5WL-GEoKB0o5ivP9SHoD47I8FW8L2PgdXqM7kqf-CVF3dCa",
    "terminal_data": null
  }
  ```
</CodeGroup>

### 3. Use new JS SDK to redirect to pre-built checkout

Once you receive payment\_session\_id from create order response, you need to use Cashfree’s [JS SDK](/docs/payments/online/element/sdks).

#### Step 1: Include our SDK in your client code

Including the Script Tag. Import the URL in the snippet below to your HTML file.

```Text HTML theme={"dark"}
<script src="https://sdk.cashfree.com/js/v3/cashfree.js"></script>
```

OR

Install from npm

```Text Shell theme={"dark"}
npm install @cashfreepayments/cashfree-js
```

#### Step 2: Initialize the SDK

You need to initialise the variable using the `Cashfree()` function. There are two modes applicable for this - **"sandbox"** or **"production"**. Sandbox is used for test environment, whereas production is used for production mode.

```javascript theme={"dark"}
const cashfree = Cashfree({
    mode:"sandbox" //or production
});
```

#### Step 3: Redirect to checkout

To open the checkout, you can use `cashfree.checkout()`method.

```javascript theme={"dark"}
cf.checkout();
```

### 4. Handle redirection and confirm status

1. Check [status](/docs/api-reference/payments/latest/orders/get-order) of the order.
2. Redirection to return\_url happens the same way as before. However, format of return\_url doesn't contain order-token now.\
   New format `https://test.cashfree.com/pgappsdemos/return.php?order_id={order_id}`

### 5. Whitelist domain

New integration will require whitelisting of the domain which is used to open the checkout page. You can request for a domain whitelisting via developers>whitelisting in your merchant dashboard or submit a [Support Form](https://merchant.cashfree.com/auth/login).\
You can check the step-by-step process of [making a whitelisting request](/docs/payments/online/go-live/whitelist#submitting-a-whitelist-request).

<Note>
  New integration only supports opening of the checkout page via the whitelisted domain. Any other domain used to open the checkout page will be blocked by Cashfree and checkout page will not open.
</Note>


# Overview
Source: https://www.cashfree.com/docs/payments/migration/overview

Plan your upgrade from older Cashfree Payment Gateway V3 APIs to V4 with this overview of breaking changes, new capabilities, and recommended migration steps.

If you're migrating from the last version i.e. 2022-09-01 (V3), following are the key changes made in this latest version 2023-08-01 (V4).

1. **Cashfree IDs type change**  \[BREAKING]\
   All cashfree IDs like `cf_order_id`, `cf_payment_id`, `cf_refund_id` etc are now in **string** format instead of **integer** (in older versions).

2. **Order Entity Changes**
   1. We have removed payments, refunds, settlements urls from order entity.
   2. `customer_uid` part of customer\_details in order entity. This is the unique identifier of the customer created at Cashfree. You can create customer at cashfree using [Create Customer API](/docs/api-reference/payments/latest/customers/create-customer-at-cashfree)
   3. `order_status` can have two more values - "TERMINATED" and "TERMINATION\_REQUESTED".

3. \*\*New Order Termination API \*\*\
   We have released a new API to terminate an Order. Find API details - [Order Termination API.](/docs/api-reference/payments/latest/orders/terminate-order)

4. **New Customer APIs**\
   We have released Customer APIs to let merchants create and manager their customers. Find more about this here - [Customer Management](/docs/api-reference/payments/latest/customers/create-customer-at-cashfree)

5. **CF Refund IDs**\
   Earlier cf\_refund\_id used to start with a prefix "refund\_". In this version, you will not get that prefix and cf\_refund\_id will be directly be the id without any prefix. Example - OLD cf\_refund\_id = "refund\_41805719", NEW cf\_refund\_id = "41805719"

## Migration from version V1 or V2

In the this latest version, we have revamped the integration method for using our pre-built checkout and made some changes in our SDKs.

Following are the key changes made in the latest version. Please check respective pages for detailed changes.

1. **Create Order API Change**\
   Deprecated use of order\_token and payment\_link from our APIs and instead introduced `payment_session_id` in response of [Create Order](/docs/api-reference/payments/latest/orders/create-order) APIs. Hence, you cannot redirect the customer to the checkout page just by using the API. You'll need to use our JS SDK for starting checkout.
2. **New Javascript SDK**\
   Released new improvised JS SDK which will take in `payment_session_id` to redirect to checkout. This is a single SDK which can be used to either redirect the customer to checkout or render components check [JS Component Integration](/docs/payments/online/element/introduction).
3. **New Order Pay API**\
   New endpoint for [order pay API](/docs/api-reference/payments/latest/payments/order-pay) is released. This will take `payment_session_id` as body parameter instead of `order_token`
4. **New SDKs**\
   Going forward, all SDKs will use `payment_session_id` instead of `order_token` to complete the payment.
5. **Whitelisting of domain name/package name**\
   All new integrations require whitelisting of domain or app package from where the checkout page is being opened. If you're using web integration, please whitelist your website domain name. If you're using a mobile app, please whitelist the app package name.\
   You can check the step-by-step process of [making a whitelisting request](/docs/payments/online/go-live/whitelist#submitting-a-whitelist-request).
6. **Cashfree IDs type change**\
   All cashfree IDs like `cf_order_id`, `cf_payment_id`, `cf_refund_id` etc are now in **string** format instead of integer (in older versions).

## Benefits

* **Performance Enhancement**: We've rebuilt our APIs with state-of-the-art technologies to ensure low latency and high Transactions Per Second (TPS).
* **Simplified Integration**: The v3 APIs now support JSON payload, providing a more user-friendly alternative to form-encoded data.
* **Payment Mode Visibility**: Easily identify the payment modes enabled for your account using the v3 APIs.
* **Offer Suite Integration**: Create offers directly from your server across various payment modes using our offer suite.
* **Expanded Payment Methods**: V3 APIs support newer payment methods such as Buy Now Pay Later and Cardless EMI.
* **Wider Card EMI Support**: Enjoy support for 10+ banks on card EMI transactions including Debit Cards.
* **Streamlined Error Handling**: We've enhanced error handling for clearer and more concise messages.
* **Entity-Based Responses**: All v3 responses are entity-based, consolidating details for a specific entity (e.g., order) in a single JSON response.
* **Order Termination API**: Stop an order from accepting payments using the v3 API's order termination capability.\
  Improved Webhooks: Our webhooks provide more comprehensive details about your orders and transactions.
* **Bank Error**: Introducing error codes directly from our banking partners for better troubleshooting.
* **Customer Eligibility Check:** Easily check customer eligibility on different pay-later and cardless modes using their phone number.
* **Customer Management**: Create customers at Cashfree and save their favourite payment methods with v3 APIs.
* **SDK Support**: We've developed SDKs for Go, Java, NodeJS/Typescript, PHP, C#, and Python.
* **Whitelisting**: Critical flow like Checkout and Payment can now be whitelisted to be only initiated from a particular domain or app.

### New tools

* **Devtools**: Monitor errors, webhook responses, and Rate limits in your API calls.
* **Integration Usage**: Gain insights into your integration through detailed reports.
* **Customer Dashboard**: Analyse patterns and payment trends of your customers.


# Mobile Dashboard
Source: https://www.cashfree.com/docs/payments/mobile-dashboard

Manage payments on the go with the Cashfree Pulse app: track transactions, monitor settlements, create payment links, and review performance on mobile.

The Cashfree Pulse app helps you manage your business from your mobile device. You can monitor performance, track transactions, initiate settlements, and maintain payment and customer records. The app is available for iOS and Android.

<Note>
  **Prerequisites**: You need an active Cashfree account to use the mobile dashboard. If you don't have an account, [sign up for a Cashfree account](https://merchant.cashfree.com/merchants/signup?source-action=docs%20page\&action=Sign%20Up\&button-id=StartNow_Navbar) before downloading the app.
</Note>

## Getting started

Download the app from the following locations:

<AccordionGroup>
  <Accordion title="iOS on App Store" icon="apple">
    Scan this QR code with your iPhone or iPad camera to download the app directly from the App Store.

    <img alt="iOS App QR Code" />

    **Download Link:** [Cashfree Business App](https://apps.apple.com/in/app/cashfree-payments-business-app/id1658841415)
  </Accordion>

  <Accordion title="Android on Google Play Store" icon="android">
    Scan this QR code with your Android device camera to download the app directly from Google Play Store.

    <img alt="Android App QR Code" />

    **Download Link:** [Cashfree Business App](https://play.google.com/store/apps/details?id=com.cashfree.merchant\&hl=en_IN)
  </Accordion>
</AccordionGroup>

To begin using the Cashfree Mobile Dashboard:

1. Sign in with your registered email address and password.
2. If you don't have a Cashfree account, [sign up for a Cashfree account](https://merchant.cashfree.com/merchants/signup?source-action=docs%20page\&action=Sign%20Up\&button-id=StartNow_Navbar).
3. (Optional) Enable biometric authentication from your profile settings for added convenience and security.

<Info>
  For enhanced security, enable biometric authentication (fingerprint or face recognition) after your initial login.
</Info>

## Key features

The Cashfree Mobile Dashboard includes the following features:

| Feature | Capabilities |
| :- | :- |
| [Track and manage payments](#monitor-business-performance) | <ul><li>Monitor your financial performance at a glance</li><li>Real-time sales data and transaction summaries</li><li>Generate payment links to send to customers</li><li>Share your unique payment handle for quick transfers</li></ul> |
| [View insights](#analyse-business-insights) | <ul><li>Analytics for orders, total sales, customer count, and sales by location</li><li>Payment method usage insights</li><li>Advanced business metrics and performance tracking</li><li>Compare data across specific time periods</li></ul> |
| [Transaction History](#view-transaction-history) | <ul><li>Complete record of payments, orders, disputes, and refunds</li><li>Search and filter transactions by status or date range</li><li>View transaction details including order IDs and customer information</li></ul> |
| [Settlement Management](#manage-settlements) | <ul><li>Track fund transfers to your bank account</li><li>Initiate on-demand settlements within daily limits</li><li>Monitor settlement schedules and processing status</li><li>View pending and completed settlement amounts</li></ul> |

## Monitor business performance

The Home screen provides a quick glimpse of key business metrics through charts and summaries that help you monitor your financial performance at a glance.

<Card title="Home screen" icon="home">
  <div>
    <img alt="Home screen with business metrics showing sales data and quick actions" />
  </div>

  <p>
    View sales data, settlements, recent payments, and quick actions
  </p>
</Card>

The following metrics are available on the Home screen:

| Metric | Description |
| - | - |
| **Today's sales** | View the amount and number of transactions for the current day. |
| **Upcoming settlements** | Check your settlement status and expected transfer dates. |
| **Recent payments** | View recent payment amounts, status, and customer names from the past 7 days. Select a payment to view additional details such as order ID, transaction details, and customer information. |
| **Sales comparison** | Compare your current sales data with previous day or week data. |
| **Quick actions** | Create a payment link or share your payment handle to receive payments. |

### Manage payments

Create payment links and share payment handles directly from the Home screen.

#### Create a payment link

Create payment links to request payments from your customers. Share the link via SMS or email, and customers can complete transactions securely.

To create a payment link:

1. On the Home screen, select **Create Payment Link**.
2. On the Create Payment Link screen, select the currency from the dropdown list, and then enter the payment amount.
3. Under **Payment Description**, enter a description that explains what the payment is for. This description appears to the customer.
4. Under **Phone Number**, select the country code from the dropdown list, and then enter the customer's phone number.
5. Optionally add:
   * Customer's name under **Name**.
   * Customer's email address under **Email Address**.
6. Expand **Additional Options** to configure settings such as:
   * **Send Payment Link**: Select **SMS** or **Email** to send the payment link to the customer.
   * **Allow Partial Payments**: Enable customers to make partial payments against the total amount.
   * **Minimum Amount**: If you allow partial payments, enter the minimum amount that customers can pay.
   * **Set Link Validity**: Select the expiry date and time for the payment link.
   * **Link ID**: Enter a unique identifier for the payment link.
   * **Add Notes**: Enter any additional notes or instructions for your reference.
7. Select **Create** to generate the payment link.

<Tip>
  Select **Allow UPI payment only** at the top of the screen to restrict the payment method to UPI transactions only.
</Tip>

#### Share a payment handle

Share your unique payment handle with customers to accept payments.

To share a payment handle:

1. On the Home screen, select **Share Payment Handle**.
2. Select **Preview** to view the payment handle before sharing.
3. Select **Copy** or **Share Now**.
4. Select your preferred sharing method, and then share the payment handle.

## Analyse business insights

The Insights screen provides detailed business performance analysis, tracking, and comparison across different time periods. Access comprehensive business metrics and performance data with advanced filtering and comparison options. Each insight displays a **View all** option for additional detailed information.

<Card title="Insights screen" icon="chart-line">
  <div>
    <img alt="Insights screen with business analytics showing sales metrics and performance data" />
  </div>

  <p>
    Analytics for sales, orders, customers, geography, and payment methods
  </p>
</Card>

To view your insights:

On the bottom navigation bar, select the **Insights** tab.

| Metric type | Description |
| - | - |
| **Sales Metrics** | View your total sales and compare them with a previous period, such as the last 30 days. Select a date range from the dropdown menu to compare data across specific time periods. |
| **Order Analytics** | View the total number of orders and compare them with previous periods. Also view the average order value, the highest order value, and percentage changes compared to the previously selected date. |
| **Customer Insights** | View the total number of customers served and compare this data with previous periods. Track the number of new customers and returning customers. |
| **Geographic Data** | View the geographic distribution of your customers and see which locations generate the most orders. |
| **Payment Methods** | View a percentage breakdown of payment methods used by your customers and identify the most frequently used payment mode. |

## View transaction history

Use the History tab to view and manage all transaction-related activities within your account. Access detailed information about payments, orders, disputes, and refunds, and use search and filter capabilities to locate specific transactions.

<Card title="Transaction screen" icon="clock">
  <div>
    <img alt="History screen with transaction records showing payments, orders, disputes and refunds" />
  </div>

  <p>
    Manage payments, orders, disputes, and refunds with search and filters
  </p>
</Card>

To view your transaction history:

On the bottom navigation bar, select the **History** icon (clock symbol).

Each transaction category provides specific filter options to help you locate transactions.

The History tab organises transactions into four main categories:

| Category | Description | Filter options |
| - | - | - |
| **Payments** | View all payment transactions processed through your account, including transaction identifiers, timestamps, amounts, and current status. Filter results by payment status. | <ul><li>**Status**: Success, Failed, Pending, User dropped, Void, Incomplete, Cancelled</li></ul> |
| **Orders** | View a comprehensive list of all order-related transactions, including order IDs, transaction times, amounts, and order status. Filter results by order status and order type. | <ul><li>**Order Status**: Paid, Active, Expired</li><li>**Order Type**: Product link, POS, Payment gateway, Payment link, Subscription, Payment gateway API</li></ul> |
| **Disputes** | View transactions where you or the issuing bank has questioned payment validity. Disputes may arise from unauthorised charges, failure to deliver goods or services as promised, or similar payment-related issues. Filter results by dispute status. | <ul><li>**Dispute Status**: Action required, Under review, Closed, Lost, Won, Accepted</li></ul> |
| **Refunds** | View all refund transactions and track their processing status. Filter results by refund status. | <ul><li>**Refund Status**: Refunded, Pending, Onhold, Cancelled</li></ul> |

### Manage disputes

Take action on payment disputes directly from the History tab when disputes require your response.

To contest a dispute and submit evidence:

1. On the History tab, select **Disputes**.
2. Select the dispute that shows "Action required" status.
3. Review the dispute details including dispute ID, reason, transaction amount, and dispute type.
4. Select **Take Actions** to respond to the dispute.
5. On the response screen, choose your action:
   * **Accept dispute**: Accept the dispute without contesting
   * **Contest dispute and submit evidence**: Challenge the dispute with supporting documentation
6. If contesting, upload relevant evidence documents:
   * **Delivery/Service Proof**: Documentation showing successful delivery or service completion
   * **Cancellation of Service Proof**: Evidence of service cancellation or modification
   * **Refund Proof**: Documentation of refunds processed to the customer
   * **Extra Charges Declaration**: Justification for additional charges applied
7. Select **Submit Evidence** to complete your response.

<Note>
  Supported file formats for evidence: JPG, JPEG, PNG, PDF. Maximum file size: 20 MB per document.
</Note>

### Initiate refunds

Initiate refunds for successful payment transactions directly from the History tab. The refund process provides detailed transaction information and allows you to process full or partial refunds with optional notes.

To process a refund:

1. On the History tab, select **Payments**.
2. Select the successful payment transaction you want to refund.
3. Review the transaction details including:
   * Transaction ID and amount
   * Customer details (phone number and IP address)
   * Payment timeline with creation and success timestamps
4. Select **Initiate Refund** at the bottom of the transaction details screen.
5. Review the refund information:
   * **Processing time**: 2-3 business days
   * **Eligible refund amount**: Maximum amount available for refund
6. Configure the refund details:
   * **Currency**: Confirm the refund currency (automatically set to transaction currency)
   * **Amount**: Enter the refund amount (partial or full amount up to the eligible limit)
   * **Add note**: Optionally provide a reason or note for the refund
7. Select **Initiate Refund** to confirm and process the refund request.

<Info>
  Refund processing times are typically 2-3 business days. The eligible refund amount may be less than the original transaction amount if partial refunds have already been processed.
</Info>

**Search for transactions**

Locate specific transactions by entering relevant identifiers or customer information. Available search criteria vary by transaction category.

To search for a transaction:

1. Select the appropriate category tab.
2. Select the search field dropdown to choose your search criteria.
3. Enter the search value in the text field. Results display automatically as you type.

**Filter transactions by status**

Refine your transaction view by filtering based on the current status.

To filter transactions:

1. In the upper-right corner, select the filter icon.
2. Select one or more status options.
3. Select **Apply filters**.

To clear all filters, select **Reset**.

<Note>
  Available filter options vary by transaction category.
</Note>

**Select a date range**

By default, the History tab displays transactions from the past 30 days. To customise the date range, select the date dropdown and choose your preferred timeframe.

## Manage settlements

Use the Settlements tab to track and manage fund transfers to your bank account. View settlement schedules, monitor processing status, and initiate on-demand withdrawals when needed.

<Card title="Settlement screen" icon="credit-card">
  <div>
    <img alt="Settlements screen with fund transfer management showing settlement types and balances" />
  </div>

  <p>
    Track fund transfers, settlement schedules, and on-demand withdrawals
  </p>
</Card>

To access your settlements, select the **Settlements** icon on the bottom navigation bar.

### Settlement types

Choose the settlement method that best fits your cash flow needs:

<Tabs>
  <Tab title="Standard settlements">
    **Best for:** Regular business operations with predictable cash flow needs.

    Automatic settlements processed according to your default settlement schedule. Funds are transferred to your bank account at regular intervals.

    **Features:**

    * Automated processing
    * Regular transfer schedule
    * No daily limits
    * Processed based on your business agreement
  </Tab>

  <Tab title="On-demand settlements">
    **Best for:** Immediate cash flow needs or urgent fund requirements.

    Immediate fund withdrawals within your available daily limits. Use on-demand settlements to access your funds before the next scheduled settlement.

    **Features:**

    * Instant fund access
    * Subject to daily limits
    * Available within business hours
    * Manual initiation required
  </Tab>
</Tabs>

### View settlement summary

The Settlements screen displays key information about your account balance and settlement status:

* **Pending settlement amount**: The total amount to be settled to your bank account, including the expected settlement date.
* **Last settlement**: The amount and timestamp of your most recent completed settlement.
* **Unsettled balance**: The current balance available for settlement.

Settlement transactions are organised by month. To view detailed information about a specific settlement, select the transaction entry from the list.

**Search and filter settlements**

Locate specific settlement transactions using the Unique Transaction Reference (UTR) number, which is a unique identifier assigned to each settlement transaction.

To search for a settlement:

1. Select the appropriate tab (Standard or On-Demand).
2. In the search field, enter the UTR number. Results appear automatically as you type.

To filter settlements by processing status:

1. In the upper-right corner, select the filter icon.
2. Select one or more status options (Processed, Failed, or In Progress).
3. Select **Apply filters**.

To clear all filters, select **Reset**.

**Select a date range**

By default, the Settlements tab displays transactions from the past 30 days. To customise the date range, select the date dropdown and choose your preferred timeframe.

### Withdraw funds on demand

Access your funds immediately within your available daily limits. The daily withdrawal limit shows the remaining amount available for on-demand settlements. This limit resets daily based on your account configuration.

To withdraw funds on demand:

1. Select the **On-Demand** tab.
2. Review your available balance and remaining daily limit.
3. Select **Settle Now**.
4. Follow the on-screen instructions to complete the withdrawal.

## Additional features

The mobile dashboard provides navigation and account management features from the Home screen.

### Access notifications

To view notifications:

1. On the Home screen, select the bell icon in the upper-right corner.
2. Review your notifications for transaction updates, settlement alerts, and account information.

### Get help

Access support through the Cashfree Care support system.

To open the support chat:

1. On the Home screen, select the help icon (?) in the upper-right corner.
2. Browse suggested questions or enter your question in the text field.

The support system answers questions about payment gateway transactions, refund status, payout transfers, and other account-related topics.

### Manage your profile

Access and update your account settings, security preferences, and app configurations through the Profile screen.

To access your profile:

On the Home screen, select the profile icon in the upper-left corner.

The Profile screen provides the following options:

| Section | Description |
| - | - |
| **User Information** | View your account details and profile information. |
| **Security** | Change your password or enable biometric authentication (fingerprint on Android or Face ID on iOS). |
| **Help & Support** | Chat with support, request features, or contact your account manager. |
| **Settings** | Manage push notification preferences. |

**Change your password**

To change your password:

1. On the Profile screen, under **Security**, select **Change Password**.
2. Follow the on-screen instructions to update your password.

**Enable biometric authentication**

To enable biometric authentication:

1. On the Profile screen, under **Security**, select the **Biometric Authentication** toggle.
2. Follow the prompts to set up fingerprint (Android) or Face ID (iOS) authentication.

<Info>
  The biometric authentication option displays a fingerprint icon on Android devices and a Face ID icon on iOS devices.
</Info>

**Access support options**

To access help and support:

1. On the Profile screen, under **Help & Support**, select one of the following options:
   * **Chat with support**: Open the Cashfree Care support system for instant help.
   * **Request a feature**: Submit feature requests or suggestions.
   * **Your Account Manager**: Contact your dedicated account manager.

### Configure push notifications

Manage notification preferences to receive alerts for account activities.

To configure push notifications:

1. On the Profile screen, under **Settings**, select **Push Notifications**.
2. On the Manage Notifications screen, configure the following options:
   * **Transaction Success**: Receive notifications for each successful payment.
   * **Settlement Updates**: Receive alerts for settlements, upcoming holidays, and key updates.
3. Select the toggle switch to enable or disable each notification type.

<Note>
  If notification permission is disabled on your device, you must enable it from your device settings to receive push notifications from the app.
</Note>

### Sign out

To sign out of your account:

1. On the Profile screen, scroll to the bottom of the screen.
2. Select **Log out**.

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/payments/dashboard">Desktop Dashboard</a></li>
    <li><a href="/docs/payments/no-code/payment-link">Payment Links</a></li>
    <li><a href="/docs/payments/webhooks">Webhooks</a></li>
    <li><a href="/docs/api-reference/payments/latest/settlement-reconciliation/settlement-reconciliation">Get Settlement API</a></li>
  </ul>
</div>


# Cancel Payment Link
Source: https://www.cashfree.com/docs/payments/no-code/customize/cancel-payment-link

Cancel Cashfree payment links from the Merchant Dashboard or API to stop further payments and notify customers when an order or invoice is no longer valid.

If you no longer want to receive payments from a particular payment link, you can cancel it.

To cancel a payment link:

1. Click the **ellipsis icon** near the respective payment link from the payment link homepage and select **Cancel**.
2. From the pop-up window, click **Cancel**.
   You can also cancel the payment link by clicking on a particular payment link from the homepage and click **Cancel** from the payment link details page.

<img alt="Cancel Payment Link" />


# Copy Link
Source: https://www.cashfree.com/docs/payments/no-code/customize/copy-link

Copy a Cashfree payment link URL or QR code from the Merchant Dashboard so you can share it with customers over email, SMS, WhatsApp, or chat tools quickly.

Copy the link of the payment link you have created and share it with your customers. You can copy the link either by clicking the **ellipsis icon** near the respective payment link from the payment link homepage and select **Copy Link**.

<img alt="Copy Link" />

You can also copy the payment link by clicking on a particular payment link from the homepage and copy the link from the payment link details page.

<img alt="" />


# Custom Domain
Source: https://www.cashfree.com/docs/payments/no-code/customize/custom-domain

Configure a custom domain for Cashfree payment links so customers see your branded URL instead of the default Cashfree domain when paying invoices and orders.

Brand your payment experience by using your own domain for payment pages instead of Cashfree's default URL.

How It Works?

Transform your payment URL from:

`https://payments.cashfree.com/yourpage` to `https://your-website.com/pay`

This helps you maintain brand consistency and build customer trust with a seamless user experience.

Before you start accepting payments, you need to prove you own the domain. This CNAME record:

* Verifies your domain ownership
* Allows Cashfree to issue an SSL certificate
* Enables secure HTTPS connections

## Setup steps

<AccordionGroup>
  <Accordion title="Step 1: Add Main CNAME Record">
    Update CNAME entry to point your custom subdomain to Cashfree's servers. This routes payment traffic to Cashfree's infrastructure.

    ```
    Your subdomain: pay.yourwebsite.com
    Name: pay
    Target: tf-lb-20240305135606644700000001-442215710.ap-south-1.elb.amazonaws.com
    ```
  </Accordion>

  <Accordion title="Add SSL Verification CNAME Record">
    Add this record to enable HTTPS:

    ```
    Name: _2246c8630409cf6021133086afba7e89.pay
    Target: _2a65ff2f36643d8fdc502f0e1753c21e.djqtsrsxkq.acm-validations.aws
    ```
  </Accordion>
</AccordionGroup>

That's it! Your customers now see your domain throughout the entire payment process.

<Note> Domain linking is easy to set up and requires only a simple DNS configuration. Need help? Our [Support team](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) is ready to assist.</Note>


# Custom SMS Message
Source: https://www.cashfree.com/docs/payments/no-code/customize/custom-sms

Customise the SMS message Cashfree sends with payment links so the sender ID, copy, and branding reflect your business and improve customer payment conversion.

When creating payment links, you can personalise the SMS messages sent to your customers. Instead of using generic payment reminders, craft messages that reflect your brand voice and include specific payment details.
Your custom SMS can include the payment amount, purpose, due date, company name, and any special instructions. For instance, a basic payment request might read:

`{CompanyName}: Pay Rs. {amount} using {link}. Valid till {dueDate}." For invoice payments, you could say: "Your invoice #{invoiceNo} for Rs. {amount} is due. Pay securely: {link}.`

To create effective payment SMS notifications, keep your messages concise while including essential details. Always mention your brand name, the payment amount, and a clear call-to-action. Adding the link validity period creates urgency and helps prevent expired link attempts.

## Use your own communication provider

Want more control over your payment communications? You can send payment link notifications through your preferred channels:

* Use your existing SMS provider (like Gupshup) to maintain consistent sender IDs
* Keep all customer communications within your existing setup

To enable custom SMS or WhatsApp integration, fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1).

<Warning>All messages must comply with SMS regulations and character limits. The payment link will be automatically included in your custom message, so focus on crafting the context that will motivate your customer to pay.</Warning>


# Edit Payment Link
Source: https://www.cashfree.com/docs/payments/no-code/customize/edit-payment-link

Edit active Cashfree payment links from the Merchant Dashboard or API to update amount, expiry, customer details, or notes without recreating the original link.

You can edit a payment link after it's created—for example, to **change the amount**, update the payment reason, or adjust customer details.

### Edit from the payment links list

1. In the [Merchant Dashboard](https://merchant.cashfree.com/auth/login), open **Payment Gateway** and go to **Payment Links** > **All**.

2. Find the link in the table and click the **ellipsis (⋮)** on that row, then select **Edit**.

3. In the **Edit Payment Link** dialog, update any fields that apply:

   * **Payment link type:** **All payment methods** or **Only UPI**
   * **Payment reason:** text shown to the customer on the checkout page and in email
   * **Amount:** currency and value (enter a higher or lower amount to change what you collect)
   * **Allow partial payment:** optional; enable if customers can pay in parts
   * **Customer details:** phone number, **Send SMS**, email, **Send email**, name

   Depending on the link, you may also see **link expiry**, **redirect URL**, **custom thanks message**, or **notes** in the same form.

4. Click **Update**. The dashboard shows a confirmation when the link is saved (for example, **Payment link updated successfully!**), and the **Amount** column in the list reflects the new value.

You can also open a specific payment link from the list and use **Edit** from its details page, when that option is available.

<img alt="Edit Payment Link" />


# Customer Verification on Payment Forms
Source: https://www.cashfree.com/docs/payments/no-code/customize/identity

Verify customers on Cashfree payment forms using Aadhaar, PAN, GST, or email field verification to collect accurate customer data.

Cashfree payment forms let you verify customer credentials before a payment is completed. You can validate Aadhaar for identity proof, PAN for tax identification, or GST for business registration. You can also opt in to email verification on the payment form email field to collect a verified email address from the customer.

## Available verification types

The following verification types are available on payment forms. Enable the types that match your business requirements.

| Verification type | Purpose | Description |
| - | - | - |
| PAN verification | Confirm tax identity | Validates PAN during payment so tax identification details are accurate from the start. For example, donation platforms can confirm donor PAN details for benefits such as 80G claims, and accurate PAN data helps streamline year-end tax filing. |
| Aadhaar verification | Confirm identity | Verifies Aadhaar during payment when customers make online reservations. You receive verified identity details before check-in, which supports a smoother paperless arrival process. |
| GST verification | Confirm business registration | Validates GST details in real time as customers pay in B2B transactions. Each business transaction then starts with verified registration credentials. |
| Email verification | Collect a verified email | Verifies the email address entered on the payment form when enabled, so you collect only legitimate email addresses. |

## Pricing

Verification services are charged separately from standard payment processing fees. To use these features, maintain a sufficient balance in your Secure ID wallet. Current rates are available on the [Merchant Dashboard](https://merchant.cashfree.com/verificationsuite/home).

For custom pricing on high transaction volumes, submit a request through the [support form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1).

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/payments/no-code/payment-forms/overview">Payment Forms Overview</a></li>
    <li><a href="/docs/payments/no-code/payment-forms/webhooks">Webhooks for Payment Forms</a></li>
    <li><a href="/docs/payments/no-code/payment-forms/personalise-payment-form">Personalise Payment Form</a></li>
    <li><a href="/docs/secure-id/introduction">Secure ID Overview</a></li>
  </ul>
</div>


# Overview
Source: https://www.cashfree.com/docs/payments/no-code/customize/overview

Customise Cashfree payment links and forms to match your brand and workflow with SMS templates, custom domains, customer data capture, and webhooks.

Once you have created a payment link, there are several actions you can perform on it to manage and optimise your payment collection process.

## Payment link management

After creating a payment link, you have access to various management options to enhance your payment collection workflow:

### Available actions

* [Send Reminder](/docs/payments/no-code/customize/send-reminder) - Send payment reminders to customers.
* [Copy Link](/docs/payments/no-code/customize/copy-link) - Easily copy and share your payment links.
* [Edit Payment Link](/docs/payments/no-code/customize/edit-payment-link) - Modify payment link details and settings.
* [Cancel Payment Link](/docs/payments/no-code/customize/cancel-payment-link) - Deactivate payment links when needed.

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/payments/latest/payment-links/create-payment-link">Create Payment Link API</a></li>
    <li><a href="/docs/api-reference/payments/latest/payment-links/fetch-payment-link-details">Fetch Payment Link Details API</a></li>
    <li><a href="/docs/api-reference/payments/latest/payment-links/cancel-payment-link">Cancel Payment Link API</a></li>
  </ul>
</div>


# Send Reminder
Source: https://www.cashfree.com/docs/payments/no-code/customize/send-reminder

Send automated Cashfree payment link reminders over SMS, email, or WhatsApp so customers complete pending invoices without manual follow-up by your team.

With Cashfree Payment Links, you can send auto-reminders to your customers about the payment via SMS and email. When you create Payment Links and if the option Send Auto Reminders is enabled, by default, reminders will be sent 1 day after creating the payment link, the subsequent day, and 1 day before the payment link expires. All reminders will be sent between 12 PM to 6 PM.

You can also decide when to remind your customers based on your business requirements. You can send a maximum of three reminders for a particular payment link. Contact your account manager to set the required payment reminder options for your account.

<img alt="Send Reminder" />

You can send any 3 payment reminders from the following available options:

* Based on payment link **creation date** - 1, 2, 3, 7, 14 days after creating the link
* Based on payment link **expiry date** - 1, 2, 3, 7, 14 days before the payment link expires

Example: A payment link is created on the 1st of September, and the expiry date is the 30th of September. You can send a maximum of three reminders to customers. You can select to send the reminders from the dates specified here - 1st, 2nd, 3rd, 7th, 14th day of creating the payment link/before the payment link expires.

<img alt="Payment Link Send Reminder - 1" />

You can also send a reminder by clicking on a particular payment link from the homepage and click **Send Reminder** from the payment link details page.

<img alt="Payment Link Send Reminder - 2" />


# Webhooks for Payment Links and Forms
Source: https://www.cashfree.com/docs/payments/no-code/customize/webhooks

Configure Cashfree webhooks for payment links and forms so your backend receives real-time events when submissions are paid, partially paid, expired, or failed.

Use webhooks to get notifications about Payment Links and Payment Forms. Core webhooks notify you of payment updates. These include:

* `payment_link_payment`: triggered when a customer makes a payment using a payment link.
* `payment_form_payment`: triggered when a customer makes a payment using the payment form.


# Overview
Source: https://www.cashfree.com/docs/payments/no-code/overview

Accept payments and manage business-wide payment flows without writing code by combining Cashfree payment links, forms, buttons, and WhatsApp payment tools.

Cashfree’s no-code payment tools allow you to accept payments without writing or maintaining code. These tools support both individual, one-to-one payment requests and large-scale, public-facing payment flows. This page explains the purpose of each tool and helps you select the option that best fits your business scenario.

<CardGroup>
  <Card title="Payment links" icon="link" href="/docs/payments/no-code/payment-link">
    Request payments from a specific customer by sharing a secure link through WhatsApp, email, SMS, or social media.
  </Card>

  <Card title="Payment forms" icon="file-lines" href="/docs/payments/no-code/payment-forms/overview">
    Collect payments from multiple or unknown users using a reusable, customisable form that can be embedded or shared publicly.
  </Card>

  <Card title="Payment button" icon="rectangle" href="/docs/payments/no-code/payment-button">
    Embed a simple HTML code snippet on your website or blog to accept payments without any technical setup.
  </Card>
</CardGroup>

## Payment links vs payment forms

The table below summarises the differences to help you choose the right no-code solution.

| Aspect | Payment links | Payment forms |
| :- | :- | :- |
| **Definition** | A shareable link to request payment from a specific, known customer. | A reusable form to collect payments and data from multiple or unknown users. |
| **Primary purpose** | One-to-one, individual payment collection. | Public, high-volume collection with structured data. |
| **Audience** | Identified customers. | Broad or unknown users. |
| **Sharing method** | Sent directly via WhatsApp, SMS, email, or chat. | Embedded on websites or shared as a public link. |
| **Data collection** | Minimal details required. | Supports structured, multi-field inputs. |
| **Customisation** | Basic (amount, description, expiry). | Advanced (branding, layout, custom fields). |
| **Usage** | Transaction-specific or customer-specific. | Ongoing, repeatable, open to many users. |
| **Best for** | Invoices, order confirmations, individual fees, and targeted donations. | Donations at scale, registrations, educational fees, healthcare onboarding, and membership payments. |
| **Limitations** | Restricted for use by many unknown users. | Challenging for personalised amounts or individual customer targeting. |

<Tabs>
  <Tab title="Payment links">
    Payment links are shareable, one-time or reusable URLs that allow you to request payment from a specific individual. They are suitable when you know the payer, the payment amount, and the context of the transaction. You can generate a link for each customer and send it through any communication channel.

    ### When to use

    Payment links are most effective in the following scenarios:

    * Requesting payment from an identified customer for a confirmed order or service.
    * Sending post-service payment requests for consultation, repair, or professional work.
    * Collecting deposits, booking amounts, or outstanding balances from a known customer.
    * Converting a cash-on-delivery order into a prepaid payment.
    * Sharing invoice-based payment requests with clients.
    * Collecting targeted donations from specific donors.
    * Requesting student-specific fees or payments that vary by individual.

    ### Key capabilities

    Payment links provide various features to simplify your payment collection process:

    * **Create-to-collect**: Create Payment Links easily with a few clicks and share them with customers.
    * **No setup required**: Create and share Payment Links without building a website or technical integration.
    * **Automatic sharing**: Customers receive a Payment Link via SMS or email for quick payment.
    * **Partial payments**: Allow your customers to make partial payments and decide the first instalment amount.
    * **Set reminders**: Send automated SMS to your customers to remind them about outstanding payments.
    * **Easy integration**: Seamlessly integrate Payment Links with your systems using APIs.
  </Tab>

  <Tab title="Payment forms">
    Payment forms are customisable, reusable forms designed for collecting payments from multiple or unknown users. They are suitable when you need to gather structured information from the payer or expect high-volume or public-facing payment activity. Forms can be embedded on your website or shared as standalone URLs.

    ### When to use

    Payment forms are ideal for the following scenarios:

    * Collecting donations from a broad audience without identifying each payer.
    * Managing admission, tuition, and event-related fee collection for educational institutions.
    * Handling event registrations or ticket payments.
    * Collecting onboarding information and consultation fees for healthcare services.
    * Processing course, subscription, or program payments for online education businesses.
    * Gathering client details before initiating service-based billing.
    * Managing membership or recurring community organisation payments.
    * Providing a reusable, branded payment page for small businesses.

    ### Key capabilities

    Payment forms offer a wide range of features for comprehensive data and payment collection:

    * **Public access**: Accessible by anyone with the link, no authentication required.
    * **Unlimited submissions**: Suitable for ongoing use with unlimited form submissions over time.
    * **Advanced data collection**: Supports custom fields, structured input, and document collection.
    * **Visual customisation**: Allows full customisation including layout, branding, colours, and design elements.
    * **Detailed analytics**: Provides comprehensive analytics on form submissions and payment activity.
    * **Flexible embedding**: Can be embedded directly on websites or shared as standalone pages.
  </Tab>
</Tabs>


# Payment Button
Source: https://www.cashfree.com/docs/payments/no-code/payment-button

Embed Cashfree Payment Buttons by copy-pasting auto-generated HTML into your website or blog to accept secure online payments without writing any code.

Cashfree payment button provides a simple HTML code that you can copy and paste on your website, blog, or any HTML page. The system-generated code offers a professional and secure way to collect payments for any use case, as shown in the following example.

<Tabs>
  <Tab title="Visual preview">
    <div>
      <img alt="payment button preview" />
    </div>
  </Tab>

  <Tab title="Code snippet">
    <div>
      <CodeGroup>
        ```html HTML theme={"dark"}
        <form>
          <a href="https://payments.cashfree.com/forms/gsdjkljlk" target="_parent">
            <div class="button-container" style="background: #000000">
              <div>
                <img src="https://cashfreelogo.cashfree.com/cashfreepayments/logosvgs/Group_4355.svg" alt="logo" class="logo-container">
              </div>
              <div class="text-container">
                <div style="font-family: Arial; color: #fff; margin-bottom: 5px; font-size: 14px;">Pay Now</div>
                <div style="font-family: Arial; color: #fff; font-size: 10px;">
                    <span>Powered By Cashfree</span>
                    <img src="https://cashfreelogo.cashfree.com/cashfreepayments/logosvgs/Group_4355.svg" alt="logo" class="seconday-logo-container">
                </div>
              </div>
            </div>
          </a>
         <style>
          .button-container{ border: 1px solid black; border-radius: 15px; display: flex; padding: 10px; width: fit-content; cursor: pointer; }
          .text-container{ display: flex; flex-direction: column; align-items: center; margin: 0 10px; justify-content: center; }
          .logo-container{ width: 40px; height: 40px; }
          .seconday-logo-container{ width: 16px; height: 16px; vertical-align: middle; }
          a{ text-decoration:none; }
        </style>
        </form>
        ```
      </CodeGroup>
    </div>
  </Tab>
</Tabs>

## Key benefits

The payment button streamlines your collection process with several automated features:

* **Fast setup**: Accept payments in a matter of minutes by simply embedding a code snippet.
* **Custom information collection**: Collect information based on your case, such as donations, events, selling physical or digital products, etc.
* **Automated redirects**: Redirect back to your website by using the **Return URL** feature after a transaction.
* **Instant invoicing**: Send invoices after successful payment to your customers automatically.

## Use cases

You can deploy the payment button across various business models to handle transactions efficiently.

* **E-commerce**: Sell physical or digital products on any custom website or blog.
* **Donations**: Collect funds for social causes or NGOs with a simple Donate Now button.
* **Events**: Manage registrations and payments for workshops, webinars, or local events.
* **Service bookings**: Allow customers to pay for appointments or reservations using custom CTA text such as Book Now or Reserve Now.

## Creating a payment button

Follow these steps to log in, configure, and generate your custom payment button within the Merchant Dashboard:

1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).

2. Go to **Payment Gateway Dashboard** > **Payment Button** > click **Create Payment Button**.

3. Enter the **Button Text** (Call to Action) and specify with examples such as Pay Now, Donate Now, Book Now, or Reserve Now.

4. Customise the **Button Text Colour**, **Background Colour**, **Select Font Style**, and **Select Form Code** according to your website or blog. You can view the preview directly in the editor.

5. You need a **Payment form** to create a payment button. These forms let you collect customer information such as name, address, and other details specific to your use case.

6. Create your form in the [**Payment Form Dashboard**](https://merchant.cashfree.com/merchants/pg/payment-forms/all) and link it to your payment button using the **Form Code**. We recommend using a readable form code in the personalised URL section during creation; you can find this code listed against each form in the dashboard.

7. After you click **Create**, copy the generated HTML snippet and paste it into your website.

<img alt="Payment Button Creation" />

## Platform integration guides

Choose your website hosting platform below to see specific instructions for embedding your payment button code accordingly:

<Tabs>
  <Tab title="Google Sites">
    Follow the steps given below to integrate the payment button with Google Sites:

    1. Log in to your [Google Site](https://sites.google.com/) and switch to **Editor mode**.
    2. Navigate to the page on which you want to place the button.
    3. Navigate to **Insert** → **Embed** → **Embed Code** and paste the Cashfree button code from the dashboard.
    4. **Publish** to view the button on your Google Site.
  </Tab>

  <Tab title="GoDaddy">
    Follow the steps given below to add an HTML section for your payment button on GoDaddy:

    1. Log in to your [GoDaddy website](https://www.godaddy.com/) and switch to **Editor mode**.
    2. Navigate to the page on which you want to place the button.
    3. **Add a section**, select **HTML**, and click **Add**. Paste the Cashfree button code.
    4. Add a pixel length of **1000** in **Forced Height** field and **Publish** the site.
  </Tab>

  <Tab title="Weebly">
    Follow the steps given below to add the payment button using the Embed Code element on Weebly:

    1. Log in to your [Weebly website](https://www.weebly.com/login) and switch to **Editor mode**.
    2. Navigate to the page on which you want to place the button.
    3. Navigate to **Build** → **Individual Elements** → **Embed Code**.
    4. Drag and drop an element and select **Click to set Custom HTML** box.
    5. Select **Edit Custom HTML** and add the Cashfree payment button code.
    6. **Publish** to view changes.
  </Tab>

  <Tab title="Blogger">
    Follow the steps given below to add the payment button code in the HTML view on Blogger:

    1. Log in to your [Blogger website](https://www.blogger.com/) and switch to **Editor mode**.
    2. Navigate to the page on which you want to place the button.
    3. Select **HTML view**, add the Cashfree payment button code, and **Publish**.
  </Tab>
</Tabs>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/payments/latest/payment-links/create-payment-link">Create Payment Link API</a></li>
    <li><a href="/docs/api-reference/payments/latest/payment-links/fetch-payment-link-details">Get Payment Link API</a></li>
    <li><a href="/docs/api-reference/payments/latest/payment-links/webhooks">Payment Link Webhooks</a></li>
  </ul>
</div>


# Frequently Asked Questions
Source: https://www.cashfree.com/docs/payments/no-code/payment-forms/faq

Browse Cashfree Payment Forms FAQs covering form creation, field configuration, partial payments, submission webhooks, settlements, refunds, and access.

<AccordionGroup>
  <Accordion title="What is a Payment Form and how does it work?">
    Payment Forms let you collect online payments via 120+ methods like UPI and net banking—no payment gateway needed! Customise the form, accept domestic and international payments, and collect customer details. Set a fixed or flexible amount and share the form via SMS, email, WhatsApp, or your website to start receiving payments instantly.
    See [Creating a payment form](/docs/payments/no-code/payment-forms/overview#creating-a-payment-form) to see how

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How do I create a Payment Form?">
    To create a payment form:

    1. Go to **Payment Gateway Dashboard** > **Payment Forms** > click **Create Payment Form**.
    2. In the **Payment For** field, explain the purpose of payment to the customer. Keep this text short and precise. This information is necessary for customers to understand the purpose of payment.
    3. Configure amount fields. You can specify a single or multiple amounts.
    4. Personalise the URL to include your brand name for easy identification.
    5. Specify the payment form validity time. (Validity time supported: 1, 2, 7, 14, 30 days, or set as No Expiry to keep it active always).

    **Add Payment Details**
    **Add Customer Details**
    **Add Business Details**

    Save and create the payment form. The payment form created will be active to collect payments. Share the payment form URL with your customers and start collecting payments instantly.

    All the payment forms created will be visible in the **Payment Forms** screen. You can edit, cancel, activate a cancelled payment form, and also share the payment form details with your customers after you create it. You can see and track the payment statuses in the **Orders** section.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I generate a report for all payment form transactions?">
    Yes, you can generate a report for all Payment Form transactions.

    The payment form report has the list and details of orders and payments made against the payment forms in the period selected. Order details, customer details, transaction amount, payment method, card details, and more are available in this report.

    To generate the payment form report,‌

    1. Go to Payment Gateway Dashboard > Reports.
    2. In the Search & Filter field, select Payment Form, and click Generate.
    3. Select the date range for which you want to view the report, and click Generate.
    4. The report will be generated based on the criteria you have filtered. You can download the report after it has been generated.

       <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How do I know when a payment is made via a Payment Form?">
    You will be notified about the payments made using the payment form via webhooks.

    The Payment Form webhook will be triggered when your customers make a complete payment using the payment form you shared.

    To start receiving webhook event notifications:

    1. Go to **Payment Gateway Dashboard** > click **Developers** in the left navigation.
    2. Select **Webhooks** in the **Payment Gateway** section.
    3. Click **Add Webhook URL** and select the event you want to be notified about.
    4. Enter the URL where you want to receive the webhook notifications, and click **Add**.

    You will start to receive webhook event notifications on the URLs you have specified. You can use one URL to handle several different event types at once or specify individual URLs for specific events.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I use the same Payment Form for multiple products or services?">
    Yes, the same form can be set up to take in different product information and pricing. The customer can select and pay for the product/service he/she is interested in.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What is a Subscription Payment Form?">
    A Subscription Payment Form collects recurring payments through a hosted checkout. You can publish the form with a single plan, or add multiple plans to the same form. On a single-plan form, customers complete mandate registration for that plan. On a multi-plan form, they choose one plan at checkout. Cashfree creates a mandate and a subscription only for the plan used at checkout. See [Subscription Payment Form](/docs/payments/no-code/payment-forms/subscription-payment-form).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I add more than one subscription plan to a Payment Form?">
    Yes. A Subscription Payment Form needs at least one plan. Click **Add Plan** to include more plans on the same form. Customers then see every available plan and select one at checkout. Cashfree creates a mandate and a subscription only for the selected plan. For setup steps, see [Subscription Payment Form](/docs/payments/no-code/payment-forms/subscription-payment-form).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can a customer subscribe to more than one plan from the same Payment Form?">
    No. The customer selects one plan and completes mandate registration for that plan only. Customers cannot switch plans after the subscription is created. Create a new subscription if the customer needs a different plan.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Do all subscription plans on a Payment Form need the same currency?">
    Yes. Every plan on a Payment Form must use the same currency. Use a separate Payment Form if you need to collect in another currency.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="I am using a hosted payment form and cannot call the Create Order API directly. How do I pass custom fields for reconciliation?">
    Collect the custom fields your reconciliation needs on your own page before the customer reaches the hosted payment form, for example institute code, roll number, or division for education and multi-institute fees, or other identifiers such as branch, campaign, or invoice reference. Submit those values to your backend, create the order server-side using the [Create Order API](/docs/api-reference/payments/latest/orders/create) with the fields mapped into `order_tags`, and then redirect the customer to the Cashfree payment session using the returned `payment_session_id`. This ensures the tags are always set correctly and appear in the Settlement Recon Report.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Why is my Payment Form not automatically redirecting after payment even though I set a redirect URL?">
    To ensure automatic redirection after a payment on a Payment Form, pass the `return_url` in the `order_meta` object during order creation.

    If your Payment Form is not redirecting and instead shows a success page with a **Download Invoice** button, disable the **Download Invoice** option in your Invoice Settings in the Merchant Dashboard. When this option is active, customers stay on the Cashfree success page to view the invoice instead of being redirected to the configured return URL.
  </Accordion>
</AccordionGroup>


# Intelliforms
Source: https://www.cashfree.com/docs/payments/no-code/payment-forms/intelliforms-docs

Use Cashfree Intelliforms to build smart payment forms that collect customer data, calculate amounts, and accept payments without writing or hosting code.

<div>
  <iframe title="YouTube video player" />
</div>

Cashfree Intelliforms are intelligent payment forms designed for businesses dealing with a predefined group of known customers. These forms streamline payment collection by allowing customers to identify themselves using unique identifiers and make personalised payments, all through a single shared link. In other words, Intelliforms helps you collect personalised payments from the customers using a single shared form.

## Use cases

This section provides an insight on the scenarios where Intelliforms are applicable.

* **School or College Fees**: Students pay semester-wise fees using their admission number.
* **Housing Societies**: Residents pay rent or maintenance using flat numbers.
* **Memberships and Events**: Members pay using a membership ID.
* **Recurring Dues**: Collect periodic payments with built-in expiry and late fee rules.

## Key benefits

This section provides an insight on the key benefits offered by Intelliforms.

* **Single payment link**: Share one link with all customers instead of generating individual links.
* **Personalised payments**: Based on uploaded data, customers can view their specific payment amount.
* **Secure access**: Optional One-Time Password (OTP) verification helps secure access by validating the customer’s identity before displaying payment details.
* **Custom rules**: Configure late fees, discounts, and customer-level expirations with ease.

## How Intelliforms work

This section provides a brief overview of how Intelliforms work.

1. **Merchant creates form**: Define fields such as identifiers, personal details, and payment amount.
2. **Upload customer data**: Upload an CSV file with customer information matching the form’s structure.
3. **Customer accesses link**: The customer identifies themselves using their unique identifiers.
4. **Verification and payment**: The system verifies the identifier, displays payment details, and accepts the payment.

## Creating an Intelliform

Follow these steps to create and configure a new Intelliform through the **Merchant Dashboard**:

<Steps>
  <Step title="Log in to the Merchant Dashboard">
    * Log in to the [**Merchant Dashboard**](https://merchant.cashfree.com/auth/login).
  </Step>

  <Step title="Navigate to the Intelliforms section">
    * From the dashboard sidebar, select **Intelliforms** under the **Payment Forms** category.
    * Click **Create New Intelliform**.
  </Step>

  <Step title="Enter form details">
    * Provide a **Form Description** to define the purpose of the form such as Semester Fee Collection.
    * Set a **Personalised URL** (shortcode) that uniquely identifies the form.
    * Select an **Expiry Date** after which the form becomes inactive.
    * Add a **Redirect URL** to guide users to a specific page after successful or failed payment.
  </Step>

  <Step title="Define form fields and structure">
    * Add required form fields:
      * **Unique Identifiers** such as Admission Number, Flat Number.
      * **Personal Details** such as Phone Number, Email, Parent’s Name.
      * **Row Identifiers** such as Semester Name, if applicable.
      * **Payment Amount**
      * **Collection Fields** such as optional inputs like remarks or reference numbers.
  </Step>

  <Step title="Configure customisations (optional)">
    * Set up **Late Fee Rules**:
      * Flat amount
      * Per-day penalty
      * Custom logic-based rules
    * Define **Discount Rules** such as loyalty or merit-based discounts.
    * Enable **Data Upload Reminders** via SMS or email for incomplete uploads.
    * Toggle **OTP Validation** to restrict access and verify users via mobile/email.
  </Step>

  <Step title="Enable customer-level expiration (optional)">
    * Activate **User-Level Expiration** if you want each customer link to expire individually.
    * Specify expiration dates within the uploaded data if required.
  </Step>

  <Step title="Save form">
    * Review the form and click **Continue**.
    * The form will be created and saved.
    * Share the form link with your customers to begin collecting payments.
  </Step>
</Steps>

<Frame>
  <img />
</Frame>

## Uploading customer data

Follow these steps to upload customer data from the **Merchant Dashboard**:

<Steps>
  <Step title="Log in to the Merchant Dashboard"> Log in to the [**Merchant Dashboard**](https://merchant.cashfree.com/auth/login). </Step>
  <Step title="Navigate to the Intelliforms section"> From the dashboard sidebar, select **Intelliforms** under the **Payment Forms** category. </Step>
  <Step title="Download sample CSV"> Download the sample CSV file by clicking *Download sample file* from the respective form present in the dashboard. </Step>
  <Step title="Fill in customer details"> Fill in customer details following the predefined format. </Step>
  <Step title="Upload the completed file"> Upload the duly filled CSV file. </Step>
  <Step title="System validation and processing"> The system validates the file based on matching headers and processes valid entries. </Step>
</Steps>

<Frame>
  <img />
</Frame>


# Overview
Source: https://www.cashfree.com/docs/payments/no-code/payment-forms/overview

Create Cashfree Payment Forms to collect customer details and payments through hosted forms with conditional fields, partial payments, and no-code setup.

Accept payments instantly with customisable payment forms - no coding needed. Brand your form, collect customer details, and receive money directly in your bank account. Share via any channel or embed on your website. Supports 120+ payment methods including UPI, cards, and net banking. Set fixed amounts or let customers decide. Get started in minutes.

## Use cases

Payment forms support a wide range of business scenarios for payment collection and customer data gathering:

<CardGroup>
  <Card title="Collect Fees" href="https://payments-test.cashfree.com/forms/fees-demo">
    Ideal for the educational sector to collect fees from parents and students.
  </Card>

  <Card title="Accept Donations" href="https://payments-test.cashfree.com/forms/donation-demo">
    Ideal for non-profit organisations looking to raise money for a good cause.
  </Card>

  <Card title="Events and Webinar Registrations" href="https://payments-test.cashfree.com/forms/webinar-demo">
    Ideal for event or webinar organisers to collect fee from the participants.
  </Card>

  <Card title="Booking and Payment Reservations" href="https://payments-test.cashfree.com/forms/booking-demo">
    Ideal for hospitality sectors to collect customer details and payments.
  </Card>

  <Card title="Esign and Pay" href="https://payments-test.cashfree.com/forms/esignandpaydemo">
    Ideal for SEBI-registered RAs and IAs to collect payments and authenticate customer's acceptance of terms and conditions.
  </Card>

  <Card title="Recurring Subscriptions" href="/docs/payments/no-code/payment-forms/subscription-payment-form">
    Ideal for recurring donations, courses, and memberships. Use a single plan, or add multiple plans so customers choose one at checkout.
  </Card>
</CardGroup>

## Creating a payment form

You can create an unlimited number of payment forms and share them with your customers, and easily track all the payments.

Follow these steps to create a payment form through the Merchant Dashboard:

1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
2. Go to **Payment Gateway > Payment Forms > All**.
3. Click the **Create a Payment Form** button.
4. Complete the form details:
   * **Payment For**: Enter a brief description such as the product name. For example, Headphones for audio equipment.
   * **Amount configuration**: Choose single amount for fixed pricing or multiple amounts for customer choice.
   * **Amount title**: Enter a title like Final amount.
   * **Currency and amount**: Select currency type and enter the payment amount.
   * **Description**: Add brief payment details (optional).
   * **GST and service charges**: Set rates if applicable to your business (optional).
   * **Redirect URL**: Add where customers go after payment completion (optional).
5. Configure form settings:
   * **Personalised URL**: Create a custom URL slug for easy sharing.
   * **Form validity**: Set expiration date for the form.
   * **Thank you message**: Customise the post-payment message.
   * **Form ID**: Create unique identifier for tracking (optional).
6. Set up customer data collection:
   * **Required fields**: Enable name, phone number, and email address.
   * **Address field**: Enable if required for your business (optional).
7. Enhance form functionality:
   * **Description**: Add business or payment purpose information.
   * **Invoice option**: Enable automatic invoice generation after payment.
   * **Terms and conditions**: Add legal terms customers must accept.
8. Add business contact information:
   * **Contact details**: Email, phone, WhatsApp number, website URL, and support link.
9. Connect social media profiles:
   * **Social links**: Add Twitter, Instagram, Facebook, and LinkedIn URLs (optional).
10. Click **Create** to finalise and publish your payment form.

<Note>
  To send a customer a payment form with their personal details pre-filled, see [personalised payment forms](/docs/payments/no-code/payment-forms/personalise-payment-form). To collect recurring payments with a single plan or multiple plans, see [subscription payment forms](/docs/payments/no-code/payment-forms/subscription-payment-form).
</Note>

<img />

<Note>
  Payment forms are required to create [payment buttons](/docs/payments/no-code/payment-button). Use the form code from your personalised URL to link forms with buttons.
</Note>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/payments/no-code/payment-forms/webhooks">Payment Form Webhooks</a></li>
    <li><a href="/docs/payments/no-code/payment-forms/faq">Payment Forms FAQs</a></li>
  </ul>
</div>


# Personalised Payment Form
Source: https://www.cashfree.com/docs/payments/no-code/payment-forms/personalise-payment-form

Send customers a pre-filled payment form with their details already populated, using a personalised link generated from your Cashfree Merchant Dashboard.

As a merchant, you can send a specific customer a payment form that already has their details filled in. Instead of sharing a generic payment form link, you generate a personalised URL from your dashboard with that customer's name, contact, and address details embedded. When the customer opens the link, their information is pre-populated and they can proceed directly to payment.

<Note>
  Personalised form links can only be generated for payment forms that already exist on your account. If you have not created a payment form yet, see how to [create a payment form](/docs/payments/no-code/payment-forms/overview#creating-a-payment-form).
</Note>

## Generate a personalised link for a customer

Use the following steps to create and share a personalised payment form with a customer:

<Steps>
  <Step title="Open your payment form">
    Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and navigate to **Payment Forms > All**. Select the payment form you want to personalise from the list of created forms.
  </Step>

  <Step title="Select Personalise Form">
    On the form detail page, click the **Personalise Form** button. The personalize payment form panel will then open as an overlay.
  </Step>

  <Step title="Enter the personalised details">
    Enter the customer details you want pre-populated on the payment form. Fill in only the fields relevant to your customer's requirements.
  </Step>

  <Step title="Copy and share the link">
    The **Personalized Form** field at the bottom of the panel shows the generated URL with your entered details as query parameters.
    If you want to notify the customer directly, enable **Send SMS**, **Send Email**, or both this changes the action button from **Copy** to **Copy and Share**.

    * If you enabled **Send SMS** or **Send Email** via the respective check boxes, click the **Copy and Share** button to copy the link and notify your customer simultaneously.
    * If neither option is enabled, click the **Copy** button to copy the link to your clipboard and share it manually via WhatsApp, email, SMS, or any other channel.
  </Step>
</Steps>

<Note>
  The pre-filled fields are editable by the customer. They can update their details on the form, if needed before completing the payment.
</Note>

<img alt="GIF walkthrough pf" />

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/payments/no-code/payment-forms/overview">Payment Forms Overview</a></li>
    <li><a href="/docs/payments/no-code/payment-forms/faq">Payment Forms FAQs</a></li>
    <li><a href="/docs/payments/no-code/payment-forms/webhooks">Payment Form Webhooks</a></li>
  </ul>
</div>


# Subscription Payment Form
Source: https://www.cashfree.com/docs/payments/no-code/payment-forms/subscription-payment-form

Create a Cashfree Subscription Payment Form to collect recurring payments through a hosted checkout with single-plan or multi-plan options.

A Subscription Payment Form is a hosted checkout that collects recurring payments without code. Use a single recurring plan when you offer one recurring amount. Use multiple recurring plans when customers need to choose an option, such as Basic, Pro, and Enterprise plans, or several donation amounts.

When the customer completes [mandate](/docs/payments/subscription/introduction#whats-a-mandate) registration, Cashfree creates a subscription for the plan they used at checkout.

## Use cases

Use a Subscription Payment Form to collect recurring payments through a shared link. The following examples cover both single-plan and multi-plan forms:

* **Donations**: One monthly contribution, or several amounts such as ₹301, ₹500, and ₹1,200.
* **Education**: A single course fee, or multiple course and coaching plans.
* **Memberships and software**: One membership, or multiple tiers such as Basic, Pro, and Enterprise.
* **Fitness and communities**: One membership tier, or several tiers with different benefits and billing frequencies.

## How it works

To see how checkout works, compare the two form types:

| Form type | Plans on the form | What the customer does |
| - | - | - |
| **Single-plan** | One | Completes mandate registration for that plan. Checkout does not show a plan selection step. |
| **Multi-plan** | Two or more | Reviews every available plan, selects one, then completes mandate registration for that plan. |

Each plan you add to the form becomes a separate [subscription plan](/docs/payments/subscription/introduction#plans). You configure the subscription type separately for each plan, and set a frequency for each Periodic plan.

<Warning>
  If the customer leaves before mandate registration is complete, Cashfree does not create a subscription. Share the form again so they can retry.
</Warning>

## Prerequisites

To create a Subscription Payment Form, you need an active Cashfree account. If you don't have one, [sign up for a Cashfree account](https://merchant.cashfree.com/merchants/signup?source-action=docs%20page\&action=Sign%20Up\&button-id=StartNow_Navbar). You also need:

* Access to the Merchant Dashboard.
* The plan name, amount, and subscription type for each plan. Periodic plans also need a billing frequency.

## Create a Subscription Payment Form

To create a Subscription Payment Form, follow these steps:

<Steps>
  <Step title="Open Payment Forms">
    Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login). Go to **Payment Gateway > Payment Forms > All**.

    <Frame>
      <img alt="Merchant Dashboard Payment Forms page with Payment Forms All and Create Payment Form highlighted" />
    </Frame>
  </Step>

  <Step title="Start a new form">
    Click **Create a Payment Form**, select **Subscription** as the payment form type, and enter the form details, such as the form name and purpose of payment.

    <Frame>
      <img alt="Create Payment Form page with Subscription selected, plan details on the left, and a form preview on the right" />
    </Frame>
  </Step>

  <Step title="Add a plan">
    Configure each plan with a name, amount, and subscription type, and add a minimum of one subscription plan. Set a frequency only when the subscription type is Periodic.

    | Field | Required | Description |
    | - | - | - |
    | **Plan name** | Yes | Name shown to the customer at checkout and during mandate authorisation. |
    | **Amount** | Yes | Amount charged for the plan. |
    | **Subscription type** | Yes | `Periodic` for a fixed amount at a fixed interval. `On-Demand` for amounts you charge when required. |
    | **Frequency** | Periodic plans only | How often you charge a Periodic plan. Cashfree supports intervals in days, weeks, months, or years. |
    | **Description** | No | Short text that explains the plan. On a multi-plan form, use this to help customers compare options. |

    <Note>
      All plans on one form must use the same currency. Plans with the same name or amount are allowed. Periodic plans on the same form can use different frequencies.
    </Note>

    For the frequencies supported by each payment method, see [Subscriptions FAQs](/docs/payments/subscription/faq).
  </Step>

  <Step title="Add more plans (optional)">
    Click **Add Plan** for each extra option you want on the same form. Configure every additional plan with the same fields. You can add as many plans as you need.
  </Step>

  <Step title="Review and publish">
    Edit or delete any plan before you publish. Confirm that every plan uses the same currency, then publish the form and share the URL.
  </Step>
</Steps>

Share the form URL through your website, WhatsApp, email, SMS, or any other channel.

## Next steps

To manage subscriptions after customers subscribe, refer to the following topics:

* View and manage subscriptions from [Manage Subscriptions](/docs/payments/subscription/manage).
* Charge On-Demand subscriptions after the mandate is active. See [charge a subscription](/docs/payments/subscription/charge).
* Receive subscription updates through [subscription webhooks](/docs/payments/subscription/webhooks).

## Limitations

To avoid unexpected behaviour, note the following limitations:

* Customers cannot subscribe to more than one plan in a single checkout.
* Customers cannot switch plans after the subscription is created. Create a new subscription if they need a different plan.

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/payments/latest/subscription/create-a-plan">Create Plan API</a></li>
    <li><a href="/docs/payments/subscription/manage">Manage Subscriptions</a></li>
    <li><a href="/docs/payments/subscription/charge">Charge a Subscription</a></li>
    <li><a href="/docs/payments/subscription/webhooks">Subscription Webhooks</a></li>
    <li><a href="/docs/payments/subscription/faq">Subscription FAQs</a></li>
  </ul>
</div>


# UTM Tracking on Payment Forms
Source: https://www.cashfree.com/docs/payments/no-code/payment-forms/utm-tracking

Track campaign and channel sources on Cashfree payment forms using UTM parameters to see which shared link produced each payment.

Cashfree payment forms let you track the source of each payment by adding Urchin Tracking Module (UTM) parameters to the form URL. UTM parameters are standard query parameters such as source, placement, and campaign that you append before you share the link.

You can add UTM parameters only to a payment form that already exists on your account. If you have not created a payment form yet, see how to [create a payment form](/docs/payments/no-code/payment-forms/overview#creating-a-payment-form).

<Note>
  Cashfree stores UTM values only when a customer pays from a URL that includes supported UTM parameters.
</Note>

## Use cases

Use UTM parameters when you share the same payment form in more than one place and need to see which place produced the payment. Typical scenarios include the following:

* **Collect fees**: Share one form in a campaign email, a WhatsApp group, and a social post.
* **Accept donations**: Use different UTM values for each public donation link.
* **Events and webinar registrations**: Compare registration payments from a story link, a banner, and an email.
* **Direct-to-consumer campaigns**: Place the same form on Instagram, Facebook, and your website.

## How UTM tracking works

Cashfree captures UTM values in this order:

1. You add UTM parameters to the form link, then share a different version on each channel.
2. The customer opens that link and completes the payment.
3. Cashfree stores the UTM values with that payment.
4. You open the Payment Form Orders report to see the source of each payment.

You see which channel produced a payment, not how many people viewed the form. Missing or skipped UTM values do not stop the payment.

UTM tracking is available on payment forms only. A payment link is created for a specific customer and sent on a known channel, so Cashfree does not read UTM parameters from payment link URLs.

## Supported UTM parameters

Cashfree stores only the parameters in the following table. Each name must start with `utm_`. Any other query parameter is ignored for tracking.

| Parameter | Description | Example |
| - | - | - |
| `utm_source` | Where the customer came from | `instagram`, `google`, `facebook` |
| `utm_medium` | Where you placed the link | `social`, `email`, `bio` |
| `utm_campaign` | Which campaign or activity | `june_sale`, `course_launch` |
| `utm_term` | Which search keyword | `online_course` |
| `utm_content` | Which version of the link | `banner_a`, `story_link` |

You can include any combination of these parameters.

<Note>
  Each UTM parameter value can be a maximum of 50 characters. If one value exceeds this limit, Cashfree does not store that value. Other valid UTM parameters on the same URL are still stored.
</Note>

## Add UTM parameters to your link

Complete these steps to add UTM parameters to a payment form link and share it. The examples use a courses payment form. Add the UTM parameters at the end of the form URL without changing the form path.

<Steps>
  <Step title="Open the payment form">
    Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and go to **Payment Gateway > Payment Forms > All**. Open the form.
  </Step>

  <Step title="Copy the form link">
    Copy the form link from the form detail page. The following is a sample form link:

    ```text theme={"dark"}
    https://payments.cashfree.com/forms?code=courses
    ```
  </Step>

  <Step title="Add UTM parameters">
    Append the UTM parameters to the copied URL. If the link already contains `?`, add each parameter with `&`. If it does not, start the first parameter with `?`. The following is a sample link to share on Instagram:

    ```text theme={"dark"}
    https://payments.cashfree.com/forms?code=courses&utm_source=instagram&utm_medium=bio&utm_campaign=june_batch
    ```

    The following table explains the UTM values in this sample Instagram link:

    | Parameter | Value | What it records |
    | - | - | - |
    | `utm_source` | `instagram` | The customer came from Instagram. |
    | `utm_medium` | `bio` | The link was in the profile bio. |
    | `utm_campaign` | `june_batch` | The payment is from the June batch campaign. |
  </Step>

  <Step title="Share a different link per channel">
    * Change the UTM values for each place you share the form, such as Instagram, WhatsApp, or email. Keep the form URL the same and change only the UTM values. The following is a sample link to share on WhatsApp:

      ```text theme={"dark"}
      https://payments.cashfree.com/forms?code=courses&utm_source=whatsapp&utm_medium=chat&utm_campaign=june_batch
      ```

    * Some form links use a short path, such as `https://payments.cashfree.com/forms/courses`. Start the first UTM parameter with `?`. The following is a sample short form URL with the Instagram UTM values:

      ```text theme={"dark"}
      https://payments.cashfree.com/forms/courses?utm_source=instagram&utm_medium=bio&utm_campaign=june_batch
      ```
  </Step>
</Steps>

You now have a tagged form link for each channel.

You can also add these parameters to a [personalised payment form](/docs/payments/no-code/payment-forms/personalise-payment-form) link before you share it.

## Payment Form Orders report

Follow these steps to generate the Payment Form Orders report and view the UTM values with each payment. In the report list, this report appears as **Payment Form**.

1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
2. From the left navigation menu, select **Reports**.
3. Click **Generate New Report**.
4. Select **Payment Form**, then choose the date range, file name, and file format.
5. Click **Generate Report**.
6. After the report is generated, click **Download**.

For other report types, see [Reports](/docs/payments/manage/reports).

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/payments/manage/reports">Payment Gateway Reports</a></li>
    <li><a href="/docs/payments/no-code/payment-forms/overview">Payment Forms Overview</a></li>
    <li><a href="/docs/payments/no-code/payment-forms/personalise-payment-form">Personalise Payment Form</a></li>
    <li><a href="/docs/help/payment-forms/faqs/faqs">Payment Forms FAQs</a></li>
  </ul>
</div>


# Webhooks
Source: https://www.cashfree.com/docs/payments/no-code/payment-forms/webhooks

Configure Cashfree Payment Form webhooks from the Merchant Dashboard to receive event notifications whenever submissions are paid, partially paid, or failed.

**Configure Webhooks**

To start receiving webhook event notifications,

1. Go to **Payment Gateway Dashboard** > click **Developers** in the left navigation.
2. Select **Webhooks** in the **Payment Gateway** section.
3. Click **Add Webhook URL** and select the event you want to be notified about.
4. Enter the URL where you want to receive the webhook notifications, and click **Add**.

You will start to receive webhook event notifications on the URLs you have specified. You can use one URL to handle several different event types at once or specify individual URLs for specific events.

<Frame>
  <img />
</Frame>

## Webhook events

Payment Forms trigger webhooks for the following events:

* **payment\_form\_order\_webhook**: Triggered when a customer makes a payment using a payment form

## Webhook headers

Your webhook endpoint will receive the following headers for signature verification. For comprehensive security measures including IP whitelisting and authentication, refer to the [Webhook Security Checklist](/docs/payments/online/webhooks/security-checklist).

| Header name | Description | Example |
| - | - | - |
| `x-webhook-signature` | HMAC-SHA256 signature for verifying authenticity | `f5oTYzpxzHmPBMmGDSjbAKZTleL4=` |
| `x-webhook-timestamp` | Timestamp when the webhook was sent | `1746426425612` |
| `x-webhook-version` | API version used for the webhook | `2023-08-01` |
| `content-type` | Content type of the payload | `application/json` |

## Payment forms sample payload

```json theme={"dark"}
{
    "data": {
        "form": {
            "form_id": "my-form-1",
            "cf_form_id": 2011640,
            "form_url": "https://payments-test.cashfree.com/forms/webhook-trial-1",
            "form_currency": "INR"
        },
        "order": {
            "order_amount": 22.00,
            "order_id": "CFPay_U1mgll3c0e9g_ehdcjjbtckf",
            "order_status": "PAID",
            "transaction_id": 1021206,
            "customer_details": {
                "customer_phone": "9999999999",
                "customer_email": "john@gmail.com",
                "customer_name": "John Doe",
                "customer_fields": [
                    {
                        "title": "Zoom ID",
                        "value": "john"
                    },
                    {
                        "title": "Company Designation",
                        "value": ""
                    }
                ]
            },
            "amount_details": [
                {
                    "title": "Webinar Tickets",
                    "value": 398,
                    "quantity": 2
                },
                {
                    "title": "Zoom Platform Fee",
                    "value": 10
                },
                {
                    "title": "Buy me a coffee :)",
                    "value": 0
                },
                {
                    "title": "Amount Dropdown Trial",
                    "value": 50,
                    "selectedoption": "Option 1"
                }
            ]
        }
    },
    "event_time": "2023-07-12T09:20:55+05:30",
    "type": "PAYMENT_FORM_ORDER_WEBHOOK"
}
```

## Webhook signature verification

<Warning>
  Verifying webhook signatures is essential for production environments to ensure the authenticity of webhook notifications and prevent fraudulent requests.
</Warning>

The signature must be verified to confirm the webhook originates from Cashfree. You'll need your Cashfree Payment Gateway secret key and the raw payload.

* The timestamp is in the header `x-webhook-timestamp`
* The signature is in the header `x-webhook-signature`

**Verification process:**

1. Concatenate the timestamp and raw request body: `timestamp + rawBody`
2. Generate HMAC-SHA256 hash using your secret key
3. Base64-encode the hash
4. Compare with the `x-webhook-signature` header value

<Tabs>
  <Tab title="Node.js">
    ```javascript theme={"dark"}
    function verifyWebhookSignature(timestamp, rawBody, signature, secretKey) {
        const signatureString = timestamp + rawBody;
        const computedSignature = crypto
            .createHmac('sha256', secretKey)
            .update(signatureString)
            .digest('base64');
        
        return computedSignature === signature;
    }
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={"dark"}
    import hmac
    import hashlib
    import base64

    def verify_webhook_signature(timestamp, raw_body, signature, secret_key):
        signature_string = timestamp + raw_body
        computed_signature = base64.b64encode(
            hmac.new(
                secret_key.encode(), 
                signature_string.encode(), 
                hashlib.sha256
            ).digest()
        ).decode()
        
        return computed_signature == signature
    ```
  </Tab>
</Tabs>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/payments/online/webhooks/signature-verification">Webhook Signature Verification</a></li>
    <li><a href="/docs/api-reference/payments/latest/payments/webhooks">Payment Webhooks API</a></li>
    <li><a href="/docs/payments/no-code/customize/webhooks">Payment Links and Forms Webhooks Overview</a></li>
    <li><a href="/docs/help/payment-forms/faqs/faqs">Payment Forms FAQs</a></li>
  </ul>
</div>


# Payment Handle
Source: https://www.cashfree.com/docs/payments/no-code/payment-handle

Create a Cashfree Payment Handle to share one reusable payment link, with custom amount input and automatic order reconciliation in the Merchant Dashboard.

The Cashfree Payment app's **Payment Handle** feature lets you create and share easily memorable payment handles. You can generate payment handles using your business name as a unique identifier and share them on any messaging platform.

## Generating a payment handle

1. Open the Cashfree Merchant app on your mobile device.

2. Tap **Create Your Payment Handle** on the home page.

3. In the Payment Handles modal, enter your unique payment short link in the following format: `cf.pay/<business_name>`. For example, `cf.pay/@dream11`.

4. Tap **Proceed** to generate the payment handle.

5. Tap **Preview** to view the payment link form.

6. Tap **Share Now** and share it with customers via SMS, WhatsApp, email, or any other messaging platform.

<Frame>
  <img />
</Frame>

Customers can enter the amount (if it isn't pre-set) and complete the payment when they tap the link. You receive real-time payment notifications after the payment completes.


# Payment Links
Source: https://www.cashfree.com/docs/payments/no-code/payment-link

Create and share Cashfree Payment Links via SMS, email, or WhatsApp to collect payments instantly with auto reminders and no-code product setup.

To create a payment link, first add your product and customer details. You can then share the payment link via SMS, email, WhatsApp, or any other platform. You can also set auto reminders to receive the payment.

<video type="video/webm" />

## Create a payment link

You can create an unlimited number of payment links to collect payments from customers and track their payment status easily.

<Tabs>
  <Tab title="Dashboard">
    Follow these steps to create a payment link through the Merchant Dashboard:

    1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
    2. Navigate to the **Payment Links Dashboard > All**.
    3. Click the **Create Payment Link** button.
    4. Select the payment link type:
       * **All payment methods**: Allows customers to pay using any available payment method.
       * **Only UPI**: Restricts payment to UPI methods only.
    5. Fill in the **Payment reason** field with a description of the payment. For example, enter shoes if you are selling footwear.
    6. Fill in the amount details:
       * Select the currency type.
       * Enter the exact amount to be paid.
       * Optionally, enable **Allow partial payment** and set a minimum amount if you want to accept partial payments.
    7. Complete the customer details section:
       * **Phone number** (required): Enter the customer's mobile number. This will be used to send SMS notifications and payment confirmations.
       * Select the notification preferences:
         * Check the **Send SMS** checkbox to send the payment link via SMS.
         * Check the **Send WhatsApp** checkbox to send the payment link via WhatsApp. For more information, refer to [WhatsApp Payment Links](/docs/payments/no-code/whatsapp-payment-links).
       * **Email ID** (optional): Enter the customer's email address to send payment link and receipt via email.
       * **Name** (optional): Enter the customer's full name for personalised communication and record keeping.
    8. Click the **Create & Send** button to create the payment link and share it with your customer.

    <img />
  </Tab>

  <Tab title="API">
    You can create payment links programmatically using the Cashfree API. This allows you to automate payment collection and integrate payment links into your business workflows.

    ### Prerequisites

    * A valid Cashfree Merchant account.
    * API keys generated from the [Merchant Dashboard](https://merchant.cashfree.com/dashboard/developers/api-keys).

    ### API endpoints

    The following table lists the available API endpoints for payment links:

    | API endpoint | Method | Description | Docs link |
    | - | - | - | - |
    | `/pg/links` | POST | Create a payment link | [Create Payment Link API](/docs/api-reference/payments/latest/payment-links/create-payment-link) |
    | `/pg/links/{link_id}` | GET | Fetch payment link details | [Fetch Payment Link Details API](/docs/api-reference/payments/latest/payment-links/fetch-payment-link-details) |
    | `/pg/links/{link_id}/cancel` | POST | Cancel a payment link | [Cancel Payment Link API](/docs/api-reference/payments/latest/payment-links/cancel-payment-link) |
    | `/pg/links/{link_id}/orders` | GET | Get orders for a payment link | [Get Orders for a Payment Link API](/docs/api-reference/payments/latest/payment-links/get-orders-for-a-payment-link) |

    #### Create payment link API flow

    Use this endpoint to generate a payment link instantly for a customer.

    <Accordion title="Create payment link request example">
      ```json theme={"dark"}
      {
        "customer_details": {
          "customer_phone": "9876543210",
          "customer_email": "johndoe@example.com",
          "customer_name": "John Doe"
        },
        "link_amount": 100.00,
        "link_currency": "INR",
        "link_purpose": "Payment for order #123",
        "link_partial_payments": false
      }
      ```
    </Accordion>

    <Accordion title="Create payment link response example">
      ```json theme={"dark"}
      {
        "cf_link_id": 123456789,
        "link_id": "link_123",
        "link_status": "ACTIVE",
        "link_currency": "INR",
        "link_amount": 100.00,
        "link_url": "https://payments.cashfree.com/links/link_123",
        "link_expiry_time": "2023-10-01T12:00:00+05:30",
        "customer_details": {
          "customer_phone": "9876543210",
          "customer_email": "johndoe@example.com",
          "customer_name": "John Doe"
        }
      }
      ```
    </Accordion>

    #### Fetch payment link details API flow

    Use this endpoint to retrieve details of a specific payment link using its `link_id`.

    <Accordion title="Fetch payment link details request example">
      ```http theme={"dark"}
      GET /pg/links/link_123
      ```
    </Accordion>

    <Accordion title="Fetch payment link details response example">
      ```json theme={"dark"}
      {
        "cf_link_id": 123456789,
        "link_id": "link_123",
        "link_status": "ACTIVE",
        "link_currency": "INR",
        "link_amount": 100.00,
        "link_url": "https://payments.cashfree.com/links/link_123",
        "link_expiry_time": "2023-10-01T12:00:00+05:30",
        "customer_details": {
          "customer_phone": "9876543210",
          "customer_email": "johndoe@example.com",
          "customer_name": "John Doe"
        }
      }
      ```
    </Accordion>

    #### Cancel payment link API flow

    Use this endpoint to cancel an active payment link.

    <Accordion title="Cancel payment link request example">
      ```http theme={"dark"}
      POST /pg/links/link_123/cancel
      ```
    </Accordion>

    <Accordion title="Cancel payment link response example">
      ```json theme={"dark"}
      {
        "link_id": "link_123",
        "link_status": "CANCELLED",
        "message": "Payment link cancelled successfully."
      }
      ```
    </Accordion>

    #### Get orders for a payment link API flow

    Use this endpoint to fetch all orders created for a specific payment link.

    <Accordion title="Get orders for a payment link request example">
      ```http theme={"dark"}
      GET /pg/links/link_123/orders
      ```
    </Accordion>

    <Accordion title="Get orders for a payment link response example">
      ```json theme={"dark"}
      {
        "link_id": "link_123",
        "orders": [
          {
            "order_id": "order_001",
            "order_status": "PAID",
            "order_amount": 100.00,
            "order_currency": "INR",
            "order_time": "2023-10-01T12:10:00+05:30"
          },
          {
            "order_id": "order_002",
            "order_status": "FAILED",
            "order_amount": 100.00,
            "order_currency": "INR",
            "order_time": "2023-10-01T12:15:00+05:30"
          }
        ]
      }
      ```
    </Accordion>

    ### Payment link webhook

    Configure payment link webhooks to receive real-time notifications for payment link status updates. This enables you to build systems to update payment statuses and send customer communications.

    To set up payment link webhooks:

    1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
    2. Go to **Payment Gateway > Developers > Webhooks**.
    3. Add the webhook address and select payment link-related events.
    4. Save the webhook configuration.

    For more information, see [Payment Link Webhooks](/docs/api-reference/payments/latest/payment-links/webhooks).

    <Accordion title="Webhook payload example">
      ```json theme={"dark"}
      {
        "event": "PAYMENT_LINK_PAID",
        "link_id": "link_123",
        "order_id": "order_001",
        "order_status": "PAID",
        "order_amount": 100.00,
        "order_currency": "INR",
        "payment_time": "2023-10-01T12:10:00+05:30"
      }
      ```
    </Accordion>
  </Tab>
</Tabs>

## UPI payment link

UPI payment links are unique URLs that let customers instantly pay using any UPI app (like Google Pay, PhonePe, or BHIM). When clicked, these links automatically open the customer's preferred UPI app with all payment details pre-filled.

To create a UPI payment link, follow these steps:

1. Navigate to **Payment Gateway > Payment Links > Create Payment Link**.
2. Under **Payment link type** select **One-time (UPI only)**.

## Payment link options

<AccordionGroup>
  <Accordion title="Send automatic reminders">
    To send payment reminders automatically to your customers. Contact your Account Manager to activate auto reminders.

    When you create payment links with **Send Auto Reminders** enabled, Cashfree sends reminders 1 day after you create the payment link, on the subsequent day, and 1 day before the payment link expires. Cashfree sends all reminders between 12 PM and 6 PM.

    You can send any 3 payment reminders from the following available options:

    * Based on payment link **creation date** - 1, 2, 3, 7, 14 days after creating the link
    * Based on payment link **expiry date** - 1, 2, 3, 7, 14 days before the payment link expires

    Example: A payment link is created on the 1st of September, and the expiry date is the 30th of September. You can send a maximum of three reminders to customers. You can select to send the reminders from the dates specified here - 1st, 2nd, 3rd, 7th, 14th day of creating the payment link/before the payment link expires.
  </Accordion>

  <Accordion title="Custom thank you message">
    You can either choose from the available messages or create a custom message.
  </Accordion>
</AccordionGroup>

## Create via batch upload

To use the batch feature, fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) with your business requirements. Cashfree verifies the details and activates the feature for your account. While the feature is being activated, you can test the flow in the test environment.

Use the batch feature to create multiple payment links at once. Add all required details in a single file following the specified format, and upload it in the batch section. Download the sample file to check the required fields for the batch upload.

<Note>
  Cashfree doesn't send SMS and email notifications instantly for batch uploads. Instead, notifications are scheduled randomly between 5 and 50 minutes after your upload. This prevents potential issues when you upload large batches, such as 50,000 entries at once.
</Note>

## Track orders and payments

Each time a customer opens a payment link and attempts a payment, a new order is created for that link. This lets you track how many times the customer clicked the link before completing the full payment.

You can use this information to follow up with customers and improve your conversion rate.

To view order details for a payment link:

* Navigate to **Payment Gateway Dashboard > Payment Links > Orders**.

You can filter the list by date range. You can also filter by status: **Success**, **Pending**, **Failed**, **User Dropped**, or **Incomplete**.

<img />

## Payment link lifecycle

A payment link moves through different states from creation to completion. Here's what each status means:

| State | Description |
| - | - |
| `ACTIVE` | Default state upon creation. Link is valid and ready to accept payments until cancelled or expired. |
| `PAID` | Payment completed in full. Link becomes inactive. |
| `PARTIALLY_PAID` | Partial payment received. Additional payments allowed. Customer reminders available. |
| `EXPIRED` | Link has exceeded its validity period. No longer accepts payments. |
| `CANCELLED` | Link manually cancelled by merchant. No longer accepts payments. |

The link starts as `ACTIVE` and transitions to other states based on payment activity or administrative actions.

<img />

<div>
  <iframe title="YouTube video player" />
</div>

## FAQs

<AccordionGroup>
  <Accordion title="How do I start using Payment Links with Cashfree?">
    Simply sign up for a Payment Links account, and Cashfree Payment Gateway will be automatically activated for your account. The Payment Links feature will be available inside the **Payment Gateway** product.\
    All payments collected via the payment links are automatically updated in the **Reports** and **Transactions** module in Cashfree Payment Gateway.

    Know more in the [Payment Links documentation](/docs/payments/no-code/payment-link).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title=" Can I create a payment link for a restricted time period?">
    Yes, you can create a payment link in the Cashfree Payment Gateway Dashboard with an expiry limit to ensure you get paid within a specific timeframe.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What information do I need to provide to create Payment Links?">
    Enter the customer’s phone or email, amount, and purpose, then share the link. You can also enable SMS & Email notifications, set an expiry date, and allow partial payments for added flexibility.

    See [Payment Links](/docs/payments/no-code/payment-link) to know more

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How do I increase my payment link amount?">
    To update the amount on an existing payment link, follow these steps.

    1. Sign in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
    2. Go to **Payment Gateway** > **Payment Links** > **All**.
    3. Find the payment link in the table and click the **more options** icon (⋮) on that row.
    4. Click **Edit**.
    5. In the **Edit Payment Link** dialog, enter the new value in the **Amount** field.
    6. Click **Update**.

    **Result:** A confirmation message appears and the Amount column updates to reflect the new value.

    For a complete list of fields you can edit, including payment reason and customer details, see [Edit Payment Link](/docs/payments/no-code/customize/edit-payment-link).

    <Note>
      Each Unified Payments Interface (UPI) payment link supports a maximum collection of ₹1 lakh. To collect a higher amount, select **All payment methods** instead of **Only UPI**, or distribute the total across multiple links or payments.
    </Note>

    If an account or transaction limit prevents the update, raise a request using the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I create Payment Links in bulk?">
    Yes, you can create Payment Links in bulk using the Batch feature. Simply fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) with your business requirements, and we’ll verify and activate it for your account. Meanwhile, you can test the flow in the sandbox.

    Once activated, upload a file with the required details in the Batch section. Download the sample file to check the format.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can my customers make multiple partial payments on Payment Links?">
    Yes, you can enable **Partial Payments** and provide the minimum amount you
    wish to collect for a Payment Link. The customer can choose to make multiple
    payments, between the minimum amount and the link amount. Cashfree will notify
    you of all partial payments done.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Are international payments supported on Payment Link?">
    Yes, it is possible to enable international payments on Cashfree Payment
    Links. Talk to us and help us understand your business for quick activation.
    If you have a **Paypal** account, connect **Paypal** to Cashfree and start
    offering Paypal as a checkout option on the payment page instantly.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are Orders?">
    Each time your customer opens a payment Link and attempts payment, a new
    Order is created against that link. This gives you the information on how
    many times the customer has visited the link before completely paying the full
    amount. You can follow up with such customers and try to improve your
    conversion rate.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are Cashfree Payment Links and why should I use them?">
    Payment Links by Cashfree is the easiest way to receive payments from your customers for any goods or services, without taking them to any app or website.

    Payment Link can be shared with the customer via different channels like WhatsApp, SMS, email, etc., and upon clicking the link, your customers can pay using all available payment methods. Cashfree will notify you when payment(s) are made using the link.

    Payment Links are a **no-code solution** that are used to accept online payments without any payment gateway integration required. Any business can create a payment link and collect online payments. No website required.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How can I create payment links for my business?">
    1. Go to **Payment Gateway Dashboard** > **Payment links** > **Create Payment Link**
    2. List the reason, the amount and the customer details.
    3. You can also select an expiry time for the link, a custom thank you message, add a note in the more section.
    4. Click create and all set!

       <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How can I create UPI payment links for my business?">
    Create and share UPI payment links with your customers to accept payments via UPI applications. To create a UPI payment link, you first need to add your product and customer details. You can share the payment link via SMS, email, WhatsApp, or any other platform. To make payments, customers must click the URL that you have sent, and a list of UPI apps installed on their mobile will be displayed. Customers can select any UPI app and complete the payment. A maximum amount of rupees 1 Lakh can be collected using the UPI payment link.

    To create a UPI payment link:

    1. Go to **Payment Gateway Dashboard** > **Payment Links** > click **Create Payment Link**.
    2. Select the option **Create UPI Link**.
    3. In the **Payment For** field, explain what the customer is making the payment for. Keep this text short and clear. This information is important for customers to understand the purpose of payment. Partial payments are not allowed for the UPI payment method.
    4. Set the **Link Expiry** limit.
    5. Enter the customer details (phone number and email ID) to send the payment link.
    6. Select the option **Send Auto Reminders** to send payment reminders automatically to your customers.
    7. Enable **Send Auto Reminders** option to notify your customers about the payment. See [Payment Links](/docs/payments/no-code/payment-link) to know more.
    8. You can add the **Link ID** and additional description for your reference. This will not be visible to your customers.

       <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What information is required to create a Payment Link?">
    To quickly request payment from your customer via Payment Link, you simply need to provide the customer’s phone or email information, and the amount and purpose for the link. Once the details are entered, the link can be shared with the customer.

    While creating a Payment Link, you can:

    * Enable the **Send SMS** and **Email** checkboxes, and Cashfree will send the link to the customer on the provided contact information.
    * Set the **expiry** for the link.
    * Enable **partial payments** if you want the customer to make payments in parts.

      <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I generate a report of all payment link transactions?">
    Yes, you can generate a report of all payment link transactions.\
    The payment link orders report provides the list and details of orders and payments made against all payment links within the selected period. This includes order details, customer details, transaction amount, payment method, transaction status, settlement UTR (if the settlement is complete), and more.

    To generate the payment link orders report:

    1. Go to **Payment Gateway Dashboard** > **Reports**.
    2. In the **Report Type** field, select **Payment Link Transactions**, and click **Generate**.
    3. Select the date range for which you want to view the report, and click **Generate**.

    The report will be generated based on your selected criteria. You can download the report after it has been generated.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Do I get notified when a payment is made on a payment link?">
    Yes, you can use webhooks to get notified about different events such as orders, payments, and settlements.

    The **Payment Link webhook** will be triggered when your customer makes a complete or partial payment using the payment link you shared. You will also be notified via the same webhook when the payment link gets cancelled or expired.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How to cancel or delete a payment link?">
    You can’t permanently delete a payment link, but you can cancel it to stop receiving payments.

    From the [Merchant Dashboard](https://merchant.cashfree.com/auth/login), click the **ellipsis (⋮)** icon next to the link and select **Cancel**.
    From API: Use POST /links//cancel (works only for ACTIVE links).
    Once cancelled, no further payments can be made.

    See [Cancel a payment link](/docs/payments/no-code/customize/cancel-payment-link) to know more.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I create a payment link for a restricted time period?">
    Yes, you can create a payment link in the Cashfree payment gateway dashboard, with an expiry limit to make sure you get paid within a specific timeframe.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How to share a Payment Link?">
    The payment link can be shared via SMS, email, Whatsapp or any other platform.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How do I create a TPV payment link from the dashboard?">
    To create a TPV (Third-Party Validation) payment link from the Merchant Dashboard,
    the TPV feature must be enabled on your MID (Merchant ID). If it isn't enabled yet,
    see the Note below before proceeding.

    1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
    2. Navigate to **Payment Gateway** > **Payment Links** > **Create Payment Link**.
    3. Fill in the payment link details, such as amount, purpose, and customer details.
    4. In the **Add Notes** section, enter the following TPV parameters:
       * `customer_bank_account_number`: The customer's bank account number.
       * `customer_bank_ifsc`: The customer's bank IFSC code.
       * `customer_bank_code` (optional): The customer's bank code.
    5. Click **Create & Send** to generate and share the payment link.

    When the customer pays using this link, the payment is validated against
    the bank account details you provided.

    <Note>
      The TPV feature must be activated on your MID before you can use this flow.
      Contact your Account Manager or submit a request through the
      [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1)
      to enable it.
    </Note>
  </Accordion>

  <Accordion title="Is there a character limit on the Payment Link link_id?">
    Yes. The `link_id` field has a maximum length of 50 characters. If your generated `link_id` exceeds this limit, the Payment Link creation API returns a `link_id_invalid` validation error.

    Shorten the `link_id` to 50 characters or fewer; this limit cannot currently be increased.
  </Accordion>

  <Accordion title="Can I customise the Order Note for orders generated through the Payment Link API?">
    When you create payment links through the API, Cashfree generates the Order Note as part of the payment link creation flow. You cannot customise or modify it.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How can I add custom information like a purpose or notes when creating a Payment Link through the API?">
    When you create payment links through the [Create Payment Link API](/docs/api-reference/payments/latest/payment-links/create-payment-link), pass additional information in `link_purpose` and `link_notes`. These details appear in the Payment Links section of the Merchant Dashboard.

    <iframe title="FAQs feedback component" />
  </Accordion>
</AccordionGroup>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/payments/latest/payment-links/create-payment-link">Create Payment Link API</a></li>
    <li><a href="/docs/api-reference/payments/latest/payment-links/fetch-payment-link-details">Get Payment Link API</a></li>
    <li><a href="/docs/api-reference/payments/latest/payment-links/webhooks">Payment Link Webhooks</a></li>
  </ul>
</div>


# WhatsApp Payment Links
Source: https://www.cashfree.com/docs/payments/no-code/whatsapp-payment-links

Send Cashfree WhatsApp payment links as interactive cards so customers can pay directly inside their chat, without being redirected to an external page.

WhatsApp payment links enable businesses to send payment requests to customers directly within WhatsApp as an interactive card. Customers can view payment details and complete transactions in-app, without being redirected to an external payment page.

## Key benefits

WhatsApp payment links offer the following advantages over standard payment links:

* **In-app payments**: Customers pay directly within WhatsApp without being redirected to an external page or browser. Each payment card displays your verified business name and logo for a branded checkout experience.
* **Clear payment details**: Payment details such as amount, description, and business name are displayed clearly in a single interactive card, making it easy for customers to review before paying.
* **Improved conversion**: A prominent **Pay Now** call-to-action button gives customers a clear, immediate action, reducing drop-off at the payment step.

<Note>
  WhatsApp payment links is a paid feature available only to selected merchants. If this option is not visible in your dashboard and you would like to enable it, contact your Cashfree account manager or fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1).
</Note>

## Customer payment experience

When you create a payment link and enable WhatsApp notifications, Cashfree sends it to your customer as an interactive card in WhatsApp. The card displays your verified business name, payment amount, and description, along with a **Pay Now** button. Customers can complete the transaction without leaving WhatsApp, through the Cashfree checkout flow.

Follow these steps to understand the end-to-end customer journey:

<Steps>
  <Step title="Card appears in WhatsApp chat">
    The customer receives a branded payment card in their WhatsApp chat showing the amount, description, and a **Pay Now** button.
  </Step>

  <Step title="Customer selects a payment method">
    The customer taps **Pay Now** and selects a payment method from the available options, such as UPI apps, cards, net banking, or other supported methods.
  </Step>

  <Step title="Customer confirms the payment">
    The customer reviews the merchant name, amount, and selected payment method, then confirms the payment.
  </Step>

  <Step title="Payment is successful">
    The customer receives a confirmation message with a transaction ID. The merchant receives a payment notification and can view the transaction details in the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
  </Step>
</Steps>

<Card>
  <img />
</Card>

## Set up WhatsApp payment links delivery

You can enable WhatsApp payment link delivery via one of two options:

* [Cashfree WhatsApp Business Account](#cashfree-waba): Payment links are sent from Cashfree's WhatsApp Business Account (WABA), with Cashfree shown as the sender. No BSP (Business Solution Provider) coordination or WABA setup required.
* [Merchant WhatsApp Business Account](#merchant-waba): Payment links are sent from your own WABA, with your business name shown as the sender. Requires BSP coordination and WABA setup.

The following table compares both options to help you choose the right setup for your business:

| | Cashfree WABA | Merchant WABA |
| - | - | - |
| **Who sends the message** | Cashfree WABA | Your own WABA |
| **Sender shown to customer** | Cashfree | Your business name |
| **Onboarding setup** | Add `send_whatsapp` to your API request. | No API changes, but WABA setup required on your side. |
| **What you share with us** | Confirmation that you want this enabled. | Your WABA ID, BSP name, and daily volume. |
| **Time to go live** | 4–5 working days. | \~1 week (subject to Meta's whitelisting). |

Follow these steps to create and send a WhatsApp payment link from the Merchant Dashboard:

1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
2. Navigate to **Payment Links Dashboard > All**.
3. Select **Create Payment Link**.
4. Choose the payment link type:
   * **All payment methods**: Allows the customer to pay using any available payment method.
   * **Only UPI**: Restricts payment to UPI methods only.
5. In the **Payment reason** field, enter a description of the payment.
6. Enter the amount details:
   * Select the currency.
   * Enter the exact amount to be collected.

<Note>
  WhatsApp payment links do not support partial payments. If you create a payment link with the `partial_payments` option enabled, the payment fails when the customer attempts to open or pay through the WhatsApp channel.
</Note>

7. Complete the customer details:
   * **Phone number** (required): Enter the customer's mobile number. This is used to send SMS notifications and payment confirmations.
   * **Email ID** (optional): Enter the customer's email address to send the payment link and receipt by email.
   * **Name** (optional): Enter the customer's full name for personalised communication and record-keeping.
8. Under notification preferences:
   * Select **Send SMS** to deliver the payment link via SMS.
   * Select **Send WhatsApp** to deliver the payment link via WhatsApp.
9. Select **Create & Send** to generate and deliver the payment link.

<img />

To complete setup, select your WABA option below:

<Tabs>
  <Tab title="Cashfree WABA">
    Payment links are delivered from Cashfree's WABA, with **Cashfree** shown as the sender. No BSP coordination or WABA setup is required from your side.

    #### Onboard with Cashfree's WABA

    Complete the following steps to enable WhatsApp payment links via Cashfree's WABA. Cashfree handles the configuration on your account once you confirm enablement.

    <Steps>
      <Step title="Confirm enablement">
        Contact your Cashfree account manager to confirm that you want WhatsApp enabled as a notification channel.
      </Step>

      <Step title="Account configuration">
        Cashfree enables WhatsApp as a notification channel on your merchant account. Once enabled, the option is visible on your Merchant Dashboard.
      </Step>

      <Step title="Activation">
        Payment links generated from your account can now be delivered to customers over WhatsApp through Cashfree's WABA.
      </Step>
    </Steps>

    **Time to go live:** 4–5 working days.

    #### Send a payment link via the API

    To deliver a payment link over WhatsApp, set `link_notify.send_whatsapp` to `true` in your request body when calling the [Create Payment Link](/docs/api-reference/payments/latest/payment-links/create-payment-link) API.

    #### Request example

    The following example shows a request body that sends the payment link via WhatsApp and email:

    ```json theme={"dark"}
        {
          "customer_details": {
            "customer_phone": "9876543210",
            "customer_email": "johndoe@example.com",
            "customer_name": "John Doe"
          },
          "link_amount": 100.00,
          "link_currency": "INR",
          "link_purpose": "Payment for order #123",
          "link_partial_payments": false,
          "link_notify": {
            "send_sms": false,
            "send_email": true,
            "send_whatsapp": true
          }
        }
    ```

    #### Parameters

    The following table describes the notification parameters relevant to WhatsApp delivery:

    | Parameter | Type | Description |
    | - | - | - |
    | `link_notify.send_whatsapp` | boolean | Set to `true` to send the payment link via WhatsApp. Default: `false`. |
    | `link_notify.send_sms` | boolean | Set to `true` to send the payment link via SMS. |
    | `link_notify.send_email` | boolean | Set to `true` to send the payment link via email. |

    For more information on the list of request and response parameters, refer to the [Create Payment Link API](/docs/api-reference/payments/latest/payment-links/create-payment-link).
  </Tab>

  <Tab title="Merchant WABA">
    Payment links are delivered from your own WABA, with your business name shown as the sender. This option is suited for merchants who already use their own WABA for customer communication.

    #### Onboard with your WABA

    Complete the following steps to enable WhatsApp payment links via your own WABA. This process involves coordination with your BSP and Meta's whitelisting approval.

    <Steps>
      <Step title="Submit intake details">
        Share the following details with your Cashfree account manager:

        * Your active WABA ID.
        * Your BSP name.
        * Your estimated daily payment link volume.

        <Note>Your WABA must be on the messages endpoint, with MMLite disabled.</Note>
      </Step>

      <Step title="Meta whitelisting">
        Cashfree submits your WABA to Meta for whitelisting.
      </Step>

      <Step title="BSP template setup">
        Your BSP registers the enhanced payment link template under your WABA. The template must be approved as **Utility**.

        <Warning>Marketing-classified templates may fail to deliver to customers who have not recently messaged your WABA. If your template is classified as Marketing, contact your BSP to raise a re-classification request with Meta.</Warning>
      </Step>

      <Step title="User acceptance testing (UAT)">
        Cashfree sends test payment links from your WABA and validates rendering and delivery.
      </Step>

      <Step title="Go live">
        Resume normal payment link sending. Links now render as enhanced payment links from your WABA.
      </Step>
    </Steps>

    **Time to go live:** Approximately one week, subject to Meta's whitelisting turnaround.

    #### Send a payment link via your WABA

    Once your BSP and Meta setup is complete, payment links are automatically delivered as interactive cards from your WABA. No changes are required to your existing API or Merchant Dashboard workflow.
  </Tab>
</Tabs>

## FAQs

Refer to the following frequently asked questions for more information on WhatsApp payment links and setup:

<AccordionGroup>
  <Accordion title="Which payment link delivery option should I choose?">
    Both options deliver the same enhanced payment link experience to your customers. Choose based on your current setup:

    * **Cashfree WABA**: Suited for merchants without an active WABA. Cashfree handles the WhatsApp delivery on your behalf.
    * **Merchant WABA**: Suited for merchants who already use their own WABA for customer communication and want their business name shown as the sender.
  </Accordion>

  <Accordion title="Will the customer experience differ between the two options?">
    No, the payment card format and checkout flow are identical across both options. The only visible difference is the sender name on the WhatsApp message, which is either **Cashfree** (Cashfree WABA) or your business name (your WABA).
  </Accordion>

  <Accordion title="Will enabling this disrupt my existing payment link flow?">
    No, your existing payment link generation and reconciliation flow remains unchanged. Only the delivery channel changes.
  </Accordion>

  <Accordion title="What if my WhatsApp template is classified as Marketing?">
    This applies to the merchant WABA option only. Contact your BSP and request that they raise a re-classification request with Meta to move the template to **Utility**. Marketing-classified templates may fail to deliver to customers who have not recently messaged your WABA.
  </Accordion>

  <Accordion title="Can I test before going live?">
    Yes, UAT is included as part of the enablement flow for both options. Cashfree validates rendering and delivery before your account goes live.
  </Accordion>
</AccordionGroup>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/payments/latest/payment-links/create-payment-link">Create Payment Link API</a></li>
    <li><a href="/docs/payments/no-code/payment-link">Payment links overview</a></li>
    <li><a href="/docs/payments/no-code/customize/overview">Customise a payment link</a></li>
  </ul>
</div>


# BNPL Plus - Native Web
Source: https://www.cashfree.com/docs/payments/online/bnpl-plus

Integrate Cashfree BNPL Plus to display BNPL offers and flexible EMI options to shoppers before checkout, lifting average order value on your store.

You can now integrate BNPL Plus into your website and offer a good customer experience by letting them know about the various available offers and flexible payment options before they proceed to checkout.

## Integration steps

1. Embed the following file into your website:

```java Java  theme={"dark"}
<script src="https://sdk.cashfree.com/js/widget/1.0.2/cashfree-widget.prod.js"></script>
```

2. Add the following div near the product price section of your webpage. This indicates where BNPL Plus would appear.

```Java Java theme={"dark"}
<div id="cashfree-widget"></div>
```

3. Copy and paste the following snippet to the JS file and link it to your HTML file:

```Java Java theme={"dark"}
window.addEventListener("load", function () {
  const widgetConfig = {
    clientID: "<Your App Id>",// Mention the App ID 
    amount: "<Your Product Price>", // Pass the product price here
    //Customize the widget with Offers, PayLater and EMI
    offers: "true",
    payLater: "true",
    emi: "true",
    theme: {
      widgetColor: "#ccccff",
      linkColor: "#000000",
      cfLogoTheme: "dark",
      isLogoActive: true,
    }
  };

  // To initiate the widget
  const cashfree = CF_Widget(widgetConfig);
  cashfree.load();
});
```

You can now see BNPL Plus on your product page. Provide the app ID. Log in to the **[Merchant Dashboard](https://merchant.cashfree.com/auth/login)** and go to the **Developers > API Keys** section. Learn how to [view the App ID](/docs/api-reference/authentication#generate-api-keys). Paste the App ID in the above snippet as the client ID value.

<Note> BNPL Plus is compatible with all Javascript frameworks such as React, Vue, Angular and so on.</Note>

Here is an image of how BNPL Plus looks once you have successfully integrated it with your website.

<img alt="" />


# Appendix
Source: https://www.cashfree.com/docs/payments/online/element/appendix

Look up netbanking bank codes and names used by Cashfree APIs and Cashfree.js when integrating the Element SDK so you can map identifiers correctly on checkout.

## Netbanking code and names

* While using the API

```json theme={"dark"}
	netbanking_bank_code: 3087
```

or

```json theme={"dark"}
	netbanking_bank_name: 'AUBLR'
```

* While using cashfree.js

```json theme={"dark"}
	netBankingName: 'AUBLR'
```

| Display | Code | Name |
| - | - | - |
| AU Small Finance Bank | 3087 | AUBLR |
| Airtel Payments Bank | 3123 | AIRPR |
| Andhra Pragathi Grameena Bank | 3094 | APGBR |
| Axis Bank | 3003 | UTIBR |
| Axis Bank - Corporate | 3071 | UTIBC |
| Bandhan Bank - Retail Banking | 3088 | BDBLR |
| Bandhan Bank - Corporate Banking | 3079 | BDBLC |
| Bank of Bahrain and Kuwait | 3095 | BBKMR |
| Bank of Baroda - Corporate | 3060 | BARBC |
| Bank of Baroda - Retail Banking | 3005 | BARBR |
| Bank of India | 3006 | BKIDR |
| Bank of India - Corporate | 3061 | BKIDC |
| Bank of Maharashtra | 3007 | MAHBR |
| Barclays Corporate - Corporate Banking | 3080 | BARCC |
| Bassien Catholic Co-operative Bank | 3096 | BACBC |
| CSB Bank Limited | 3010 | CSBKR |
| Canara Bank | 3009 | CNRBR |
| Capital Small Finance Bank | 3098 | CLBLR |
| Central Bank of India | 3011 | CBINR |
| City Union Bank | 3012 | CIUBR |
| City Union Bank - Corporate | 3083 | CIUBC |
| Cosmos Bank | 3097 | COSBR |
| DBS Bank Ltd | 3017 | DBSSR |
| DCB Bank - Corporate | 3062 | DCBLC |
| DCB Bank - Personal | 3018 | DCBLR |
| Deutsche Bank | 3016 | DEUTR |
| Dhanlaxmi Bank | 3019 | DLXBR |
| Dhanlaxmi Bank - Corporate | 3072 | DLXBC |
| ESAF Small Finance Bank | 3100 | ESMFR |
| Equitas Small Finance Bank | 3076 | ESFBR |
| Federal Bank | 3020 | FDRLR |
| Fincare Bank | 3101 | FSFBR |
| Gujarat State Co-operative Bank Limited | 3091 | GSCBR |
| HDFC Bank | 3021 | HDFCR |
| HDFC Bank - Corporate | 3084 | HDFCC |
| HSBC Retail NetBanking | 3092 | HSBCR |
| ICICI Bank | 3022 | ICICR |
| ICICI Bank - Corporate NetBanking | 3073 | ICICC |
| IDBI Bank | 3023 | IBKLR |
| IDFC FIRST Bank | 3024 | IDFBR |
| Indian Bank | 3026 | IDIBR |
| Indian Overseas Bank | 3027 | IOBAR |
| Indian Overseas Bank - Corporate | 3081 | IOBAC |
| IndusInd Bank | 3028 | INDBR |
| Jammu and Kashmir Bank | 3029 | JAKAR |
| Jana Small Finance Bank | 3102 | JSFBR |
| Janata Sahakari Bank Ltd Pune | 3104 | JSBPR |
| Jio Payments Bank | 3103 | JIOPR |
| Kalyan Janata Sahakari Bank | 3105 | KJSBR |
| Karnataka Bank Ltd | 3030 | KARBR |
| Karnataka Gramin Bank | 3113 | PKGBR |
| Karnataka Vikas Grameena Bank | 3107 | KVGBR |
| Karur Vysya Bank | 3031 | KVBLR |
| Kotak Mahindra Bank | 3032 | KKBKR |
| Lakshmi Vilas Bank - Corporate | 3064 | LAVBC |
| Lakshmi Vilas Bank - Retail NetBanking | 3033 | LAVBR |
| Maharashtra Gramin Bank | 3108 | MAHGR |
| Mehsana Urban Co-operative Bank | 3109 | MSNUR |
| NKGSB Co-operative Bank | 3111 | NKGSR |
| North East Small Finance Bank Ltd | 3110 | NESFR |
| Nutan Nagarik Sahakari Bank Limited | 3112 | NNSBR |
| Punjab & Sind Bank | 3037 | PSIBR |
| Punjab National Bank - Corporate | 3065 | PUNBC |
| Punjab National Bank - Retail Banking | 3038 | PUNBR |
| RBL Bank | 3039 | RATNR |
| RBL Bank - Corporate Banking | 3114 | RATNC |
| SBM Bank India | 3115 | STCBR |
| Saraswat Bank | 3040 | SRCBR |
| Shamrao Vithal Bank - Corporate | 3075 | SVCBC |
| Shamrao Vithal Co-operative Bank | 3041 | SVCBR |
| Shivalik Bank | 3086 | SMCBR |
| South Indian Bank | 3042 | SIBLR |
| Standard Chartered Bank | 3043 | SCBLR |
| State Bank of India | 3044 | SBINR |
| State Bank of India - Corporate | 3066 | SBINC |
| Suryoday Small Finance Bank | 3116 | SURYR |
| TJSB Bank | 3119 | TJSBR |
| Tamil Nadu State Co-operative Bank | 3051 | TNSCR |
| Tamilnad Mercantile Bank Ltd | 3052 | TMBLR |
| Thane Bharat Sahakari Bank Ltd | 3118 | TBSBR |
| The Kalupur Commercial Co-operative Bank | 3106 | KCCBR |
| The Surat People's Co-operative Bank Limited | 3090 | SPCBR |
| The Sutex Co-operative Bank Ltd | 3117 | SUTBR |
| UCO Bank | 3054 | UCBAR |
| UCO Bank - Corporate | 3122 | UCBAC |
| Union Bank of India | 3055 | UBINR |
| Union Bank of India - Corporate | 3067 | UBINC |
| Utkarsh Small Finance Bank | 3089 | UTKSR |
| Varachha Co-operative Bank Limited | 3120 | VARAR |
| Yes Bank - Corporate | 3077 | YESBC |
| Yes Bank Ltd | 3058 | YESBR |
| Zoroastrian Co-operative Bank Ltd | 3121 | ZCBLR |

## UPI app list

```json theme={"dark"}

    upiApp: 'gpay'

```

| App name | upiApp | Description |
| - | - | - |
| PhonePe | phonepe | opens phone app |
| Google Pay | gpay | opens gpay app |
| Paytm | paytm | opens paytm app |
| Default | default | opens native intent drawer in Android, WhatsApp in iOS |
| Web | web | opens native intent drawer in Android, web page in iOS |

## Wallet providers

* api and cashfree.js

```json theme={"dark"}

	provider: "phonepe"

```

| Display | Provider |
| - | - |
| PhonePe | phonepe |
| Paytm | paytm |
| OLA money | ola |
| Amazon Pay | amazon |
| Airtel Money | airtel |
| Freecharge | freecharge |
| Mobikwik | mobikwik |
| Jio Money | jio |
| PayZapp | payzapp |

## Paylater providers

* api and cashfree.js

```json theme={"dark"}

	provider: "kotak"

```

| Display | Provider |
| - | - |
| Kotak | kotak |
| Flexipay or HDFC | flexipay |
| Zestmoney | zestmoney |
| Lazypay | lazypay |
| Ola | olapostpaid |
| Simpl | simpl |

## Cardless EMI providers

* api and cashfree.js

```json theme={"dark"}

	provider: "flexmoney"

```

| Display | Provider |
| - | - |
| Flexmoney | flexmoney |
| Zestmoney | zestmoney |

<br />

## Error

Error Structure

```json theme={"dark"}

	type: "error_type",
	code: "error_code",
	message: "error message"

```

| Error type | Description | Show error.message to user |
| - | - | - |
| `validation_error` | When input validation fails | Yes |
| `failed_payment_error` | When payment has failed | Yes |
| `incomplete_request_error` | When payment was aborted | Yes |
| `timeout_request_error` | When component could not be loaded | No |
| `invalid_request_error` | When component not properly initialized | No |
| `api_connection_error` | When cashfree is not reachable | No |
| `api_error` | When there is issue with cashfree api | No |
| `feature_not_enabled` | When certain features are not enabled | No |
| `rate_limit_error` | When cashfree api has hit rate limit | No |
| `idempotency_error` | When same idempotency key is used | No |

## Payment message

Once payment is successful for the `cashfree.pay` promise, you will receive the following message in `data`

```json theme={"dark"}

	paymentMessage: "Payment finished. Check status.", //string

```

## SDK JS versions

| Version | Release date | Change log |
| - | - | - |
| [cashfree-2023.03.08.js](https://sdk.cashfree.com/js/v3/cashfree-2023.03.08.js) | 2023-03-08 | Launch Day :rocket: |
| [cashfree-2023.03.16.js](https://sdk.cashfree.com/js/v3/cashfree-2023.03.16.js) | 2023-03-16 | Added `payInParts` option for `.pay()` in cardNumber |
| [cashfree-2023.03.20.js](https://sdk.cashfree.com/js/v3/cashfree-2023.03.20.js) | 2023-03-20 | Bug fixes for wallet component |
| [cashfree-2023.03.22.js](https://sdk.cashfree.com/js/v3/cashfree-2023.03.22.js) | 2023-03-22 | Added `savePaymentInstrument` component |
| [cashfree-2023.03.28.js](https://sdk.cashfree.com/js/v3/cashfree-2023.03.28.js) | 2023-03-28 | emi tenure in card component; card component hide brand icon; mode is now optional for checkout() and pay() and required for Cashfree(`{mode:"sandbox"}`), redirectDelay deprecated |
| [cashfree-2023.03.31.js](https://sdk.cashfree.com/js/v3/cashfree-2023.03.31.js) | 2023-03-31 | Increase timeout for all components, handling ad blockers |
| [cashfree-2023.04.12.js](https://sdk.cashfree.com/js/v3/cashfree-2023.04.12.js) | 2023-04-12 | payInParts now supports emi bank. Use `kotak,3` for kotak bank 3 months |
| [cashfree-2023.06.21.js](https://sdk.cashfree.com/js/v3/cashfree-2023.06.21.js) | 2023-06-21 | `returnUrl` is optional now |
| [cashfree-2023.06.28.js](https://sdk.cashfree.com/js/v3/cashfree-2023.06.28.js) | 2023-06-28 | fixed component.focus() not focusing bug |
| [cashfree-2023.12.18.js](https://sdk.cashfree.com/js/v3/cashfree-2023.12.18.js) | 2023-12-18 | Added Cashfree Interfaces |
| [cashfree-2024.03.06.js](https://sdk.cashfree.com/js/v3/cashfree-2024.03.06.js) | 2024-03-06 | Added complete, invalid and empty styles for Card Input Fields |
| [cashfree-2024.03.14.js](https://sdk.cashfree.com/js/v3/cashfree-2024.03.14.js) | 2024-03-14 | Added Flowwise Components |
| [cashfree-2024.04.15.js](https://sdk.cashfree.com/js/v3/cashfree-2024.04.15.js) | 2024-04-15 | Launched Popup Checkout Integration |
| [cashfree-2024.04.17.js](https://sdk.cashfree.com/js/v3/cashfree-2024.04.17.js) | 2024-04-17 | Fixed an issue where new window wouldn't open if the browser's popup blocker was enabled in popup checkout. |
| [cashfree-2024.05.07.js](https://sdk.cashfree.com/js/v3/cashfree-2024.05.07.js) | 2024-05-07 | Launched Embed Checkout Integration |
| [cashfree-2024.06.03.js](https://sdk.cashfree.com/js/v3/cashfree-2024.06.03.js) | 2024-06-03 | Removed Border Radius and Box Shadow in Embed Checkout Integration |
| [cashfree-2024.07.31.js](https://sdk.cashfree.com/js/v3/cashfree-2024.07.31.js) | 2024-07-31 | Added Subscriptions Checkout |


# Cards Component
Source: https://www.cashfree.com/docs/payments/online/element/cards

Use the Cashfree.js Cards Component to securely capture card numbers, expiry, and CVV from customers while staying PCI DSS compliant on your custom checkout.

There are four card components as listed below:

## cardNumber

A component to accept card number.

<ResponseField name="cardNumber" type="Card Number Object">
  <Expandable title="properties">
    <ParamField type="string">
      placeholder for your card number field
    </ParamField>

    <ParamField type="boolean">
      hide brand icons, default is `false`
    </ParamField>
  </Expandable>
</ResponseField>

<h4>Returned Value</h4>
You can get the value of a component by calling `component.data().value`. All returned
values of `component.data()` can be found in the [component overview reference](/docs/payments/online/element/component-overview#get-component-data)

<ResponseField name="cardNumber" type="Card Number Object">
  <Expandable title="properties">
    <ResponseField name="brand" type="string">
      contains the brand of the card visa, amex, mastercard, rupay
    </ResponseField>

    <ResponseField name="cvvLength" type="string">
      contains the cvv length for the given brand eg 4 for amex
    </ResponseField>
  </Expandable>
</ResponseField>

<Accordion title="Code Snippet for cardNumber component">
  ```javascript theme={"dark"}
  let cashfree = Cashfree({
    mode:"sandbox" //or production
  });
  let card = cashfree.create('cardNumber', {
  	values:{
  		placeholder: "Enter card number"
  	}
  });
  card.on('loaderror', function(data){
  	console.log(data.error)
  })
  card.mount("#mount-here");
  card.on('ready', function(d){
      console.log(card.data().value);  //{brand: 'visa', cvvLength: 3}
      //or
      //console.log(d.value) 
  })
  ```
</Accordion>

## cardHolder

A component to accept card holder's name.
You can pass values to a component using **options** cashfree.create('componentName', options)

<ResponseField name="cardNumber" type="Card Number Object">
  <Expandable title="properties">
    <ParamField type="string">
      name of the card holder
    </ParamField>
  </Expandable>
</ResponseField>

<h4>Returned Value</h4>
You can get the value of a component by calling `component.data().value`. All returned
values of `component.data()` can be found in the [component overview reference](/docs/payments/online/element/component-overview#get-component-data)

<ResponseField name="cardHolder" type="Card Holder Object">
  <Expandable title="properties">
    <ResponseField name="cardHolder" type="string">
      contains the name of the card holder
    </ResponseField>
  </Expandable>
</ResponseField>

<Accordion title="Code Snippet for cardHolder component">
  ```javascript theme={"dark"}
  let cashfree = Cashfree({
    mode:"sandbox" //or production
  });
  let cardHolder = cashfree.create('cardHolder', {
  	values:{
  		cardHolder: 'Jane Doe'
  	}
  });
  cardHolder.on('loaderror', function(data){
  	console.log(data.error)
  })
  cardHolder.mount("#mount-here");
  cardHolder.on('ready', function(d){
      console.log(cardHolder.data().value)//{cardHolder: 'Jane Doe'}
      //or
      //console.log(d.value);  
  })
  ```
</Accordion>

## cardExpiry

A component to accept card expiry. This component does not accept any parameters.

<h4>Returned Value</h4>
You can get the value of a component by calling `component.data().value`. All returned
values of `component.data()` can be found in the [component overview reference](/docs/payments/online/element/component-overview#get-component-data)

<ResponseField name="cardExpiry" type="Card Expiry Object">
  <Expandable title="properties">
    <ResponseField name="cardExpiry" type="string">
      Returns the card expiry in MM/YY format.
    </ResponseField>
  </Expandable>
</ResponseField>

<Accordion title="Code snippet for cardExpiry component">
  ```javascript theme={"dark"}
  let cashfree = Cashfree({
    mode:"sandbox" //or production
  });
  let cardExpiry = cashfree.create('cardExpiry', {
  	values:{
  		//does not accept any value
  	}
  });
  cardExpiry.on('loaderror', function(data){
  	console.log(data.error)
  })
  cardExpiry.mount("#mount-here");
  cardCvv.on('ready', function(d){
      console.log(cardCvv.data().value); //{cardExpiry: '12/26'}
      //or
      //console.log(d.value) 
  });
  ```
</Accordion>

## cardCvv

A component to accept card cvv/cvc. This component does not accept any parameters.

<h4>Returned Value</h4>
This is a secure field and you cannot get values from this field.

<Accordion title="Code snippet for cardCVV component">
  ```javascript theme={"dark"}
  let cashfree = Cashfree({
    mode:"sandbox" //or production
  });
  let cardCvv = cashfree.create('cardCvv', {});
  cardCvv.on('loaderror', function(data){
  	console.log(data.error)
  })
  cardCvv.mount("#mount-here");
  cardCvv.on('ready', function(d){
      console.log(cardCvv.data().value); //{cardCvv: '123'}
      //or
      //console.log(d.value) 
  });
  ```
</Accordion>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/payments/online/element/introduction">Element Introduction</a></li>
    <li><a href="/docs/payments/online/element/sdks">SDK Libraries</a></li>
    <li><a href="/docs/payments/online/element/component-overview">Component Overview</a></li>
    <li><a href="/docs/payments/online/element/upi">UPI Components</a></li>
    <li><a href="/docs/payments/online/element/other-components">Other Components</a></li>
  </ul>
</div>


# Overview
Source: https://www.cashfree.com/docs/payments/online/element/component-overview

Browse the Cashfree.js components available after SDK initialisation and learn how to use the create method to mount payment fields on your site.

Once you initialise the cashfree.js sdk, you can use the create method to create a component.

```javascript theme={"dark"}
let cashfree = Cashfree({mode: "sandbox"});
let options = {};
let component = cashfree.create("componentName", options);
```

## Component lifecycle

<Frame>
  <img />
</Frame>

## Methods

### Mount component

A component can be mounted in DOM container.

```
Syntax: `component.mount(querySelector)`
```

Example

```
component.mount("#componentContainer")
```

### Update component

The values of a component can be updated.

```
Syntax: `component.update(values)`
```

Example

```

let values = {
	keyName: "keyValue"
}
component.update(values)
```

### Unmount component

To unmount a component from DOM container. Use component.mount to mount again.

```
component.unmount()
```

### Get component data

To get the data and state of a component

```
let data = component.data()
```

#### Returns

```
{
    value: {},
	error:  undefined,
	message: {},
	invalid: undefined,
	empty: true,
	complete: false,
	ready: false,
	componentName: "componentName",
	node: null,
	mounted: false,
	loaderror: false,
	focus: false,
	disabled: false,
	kind: "string"
}
```

| Name | Description | Default |
| - | - | - |
| `value` | Contains the value of the component. | `{}` |
| `error` | Contains error that has occurred in the component | `undefined` |
| `message` | Contains any message that can be shown to the customer | `{}` |
| `invalid` | Is `true` if the component is invalid | `undefined` |
| `empty` | Is `true` if the component is empty | `false` |
| `complete` | Is `true` if the component is complete | `false` |
| `ready` | Is `true` if the component is ready for user input | `false` |
| `componentName` | Contains the type of the component | `componentName` |
| `node` | Contains the reference to the parent of the component | `null` |
| `mounted` | Is `true` if the component has been mounted | `false` |

### Blur component

Trigger blur on component. Can only be applied if `kind` of the component is `input`

```js theme={"dark"}
component.blur()
```

### Focus component

Trigger focus on component. Can only be applied if `kind` of the component is `input`

```js theme={"dark"}
component.focus()
```

### Clear component

Trigger clear on component to empty it. Can only be applied if `kind` of the component is `input`

```js theme={"dark"}
component.clear()
```

### Click component

Trigger click on component. Can only be applied if `kind` of the component is `button`

```js theme={"dark"}
component.click()
```

### Disable component

Disabling component will apply the `classes.disabled` and `style.base[":disabled"]` or `style.empty[":disabled"]` to the container and component respectively. Can be applied to `input` and `button`

```js theme={"dark"}
component.disable()
```

### Enable component

To enable a disabled component. Can be applied to `input` and `button`

```js theme={"dark"}
component.enable()
```

### Destroy component

To destroy a component. Once a component is destroyed it cannot be mounted again

```js theme={"dark"}
component.destroy()
```

## Events

You can register a callback function to various events that occur with a component. The basic syntax is `component.on(eventName, callBackFunction)`

### ready

Triggers when a component is ready for user interaction

```js theme={"dark"}
component.on('ready', function(data){
	//data is same as component.data()
})
```

### focus

Triggers on component `kind` `input` when focussed

```js theme={"dark"}
component.on('focus', function(data){
	//data is same as component.data()
})
```

### blur

Triggers on component `kind` `input` when blurred

```js theme={"dark"}
component.on('blur', function(data){
	//data is same as component.data()
})
```

### invalid

Triggers on component `kind` `input` when value entered by the user is invalid. Callback receives object that has the error. Read more about error here

```js theme={"dark"}
component.on('invalid', function(data){
	//data is same as component.data()
	//data.error has the actual error
	//you can use data.error.message to show to customer
})
```

### change

Triggers on component `kind` `input` whenever change happens for the value

```js theme={"dark"}
component.on('change', function(data){
	//data is same as component.data()
})
```

### empty

Triggers on component `kind` `input` when empty

```js theme={"dark"}
component.on('empty', function(data){
	//data is same as component.data()
})
```

### complete

Triggers on component `kind` `input` when value entered is complete and valid

```js theme={"dark"}
component.on('complete', function(data){
	//data is same as component.data()
})
```

### click

Triggers on component `kind` `button` when clicked

```js theme={"dark"}
component.on('click', function(data){
	//data is same as component.data()
})
```

### paymentrequested

Triggers on component payable components when payment has been successfully initiated

```js theme={"dark"}
component.on('paymentrequested', function(data){
	//data is same as component.data()
})
```

### loaderror

Triggers on component which could not be mounted. Callback receives object that has the error. Read more about error here

```js theme={"dark"}
component.on('loaderror', function(data){
	//data is same as component.data()
	//data.error has the actual error
	//you can use data.error.message to show to customer
})
```


# Components
Source: https://www.cashfree.com/docs/payments/online/element/components

Reference every component shipped with Cashfree.js, the initial state options accepted by each one, and which components are payable on a custom checkout.

Cashfree provides the following list of components along with the initial state that can be passed in `options.values`. Certain components are payable and might need other components to be mounted to be ready for payment

<Note>
  A component can only be mounted after `cashfree.js` has been initialized and
  DOM container is ready for mounting the component.
</Note>

## Card components

There are four card components as listed below:

### cardNumber

A component to accept card number

<h4>Parameters</h4>

<ResponseField name="cardNumber" type="Card Number Object">
  <Expandable title="properties">
    <ParamField type="string">
      placeholder for your card number field
    </ParamField>

    <ParamField type="boolean">
      hide brand icons, default is `false`
    </ParamField>
  </Expandable>
</ResponseField>

<h4>Returned Value</h4>
You can get the value of a component by calling `component.data().value`. All returned
values of `component.data()` can be found in the [components reference](/docs/payments/online/element/components)

<ResponseField name="cardNumber" type="Card Number Object">
  <Expandable title="properties">
    <ResponseField name="brand" type="string">
      contains the brand of the card visa, amex, mastercard, rupay
    </ResponseField>

    <ResponseField name="cvvLength" type="string">
      contains the cvv length for the given brand eg 4 for amex
    </ResponseField>
  </Expandable>
</ResponseField>

```js theme={"dark"}
let cashfree = Cashfree({
	mode: "sandbox", //or production
});
let card = cashfree.create("cardNumber", {
	values: {
		placeholder: "Enter card number",
	},
});
card.on("loaderror", function (data) {
	console.log(data.error);
});
card.mount("#mount-here");
card.on("ready", function (d) {
	console.log(card.data().value); //{brand: 'visa', cvvLength: 3}
	//or
	//console.log(d.value)
});
```

### cardHolder

A component to accept card holder's name

<span>
  <span>kind</span>
  <span>input</span>
</span>

<span>
  <span>payable</span>
  <span>false</span>
</span>

<div />

##### Accepted `values`

You can pass values to a component using [options](/docs/payments/online/element/customize#configuration-options) `cashfree.create('componentName', options)`

| key | description |
| - | - |
| placeholder `string` <span>OPTIONAL</span> | placeholder for your card number field |
| cardHolder `string` <span>OPTIONAL</span> | name of your customer |

<div />

##### Returned `value`

You can get the value of a component by calling `component.data().value`. All returned values of `component.data()` can be found in the [components reference](/docs/payments/online/element/components)

| key | description |
| - | - |
| cardHolder `string` | name of your customer |

Example

```js theme={"dark"}
let cashfree = Cashfree({
	mode: "sandbox", //or production
});
let cardHolder = cashfree.create("cardHolder", {
	values: {
		cardHolder: "Jane Doe",
	},
});
cardHolder.on("loaderror", function (data) {
	console.log(data.error);
});
cardHolder.mount("#mount-here");
cardHolder.on("ready", function (d) {
	console.log(cardHolder.data().value); //{cardHolder: 'Jane Doe'}
	//or
	//console.log(d.value);
});
```

### cardExpiry

A component to accept card expiry

<span>
  <span>kind</span>
  <span>input</span>
</span>

<span>
  <span>payable</span>
  <span>false</span>
</span>

<div />

##### Accepted `values`

Does not accept anything

<div />

##### Returned `value`

You can get the value of a component by calling `component.data().value`. All returned values of `component.data()` can be found in the [components reference](/docs/payments/online/element/components)

| key | description |
| - | - |
| cardExpiry `string` | card expiry in MM/YY format |

Example

```js theme={"dark"}
let cashfree = Cashfree({
	mode: "sandbox", //or production
});
let cardExpiry = cashfree.create("cardExpiry", {
	values: {
		//does not accept any value
	},
});
cardExpiry.on("loaderror", function (data) {
	console.log(data.error);
});
cardExpiry.mount("#mount-here");
cardCvv.on("ready", function (d) {
	console.log(cardCvv.data().value); //{cardExpiry: '12/26'}
	//or
	//console.log(d.value)
});
```

### cardCvv

A component to accept card cvv/cvc

<span>
  <span>kind</span>
  <span>input</span>
</span>

<span>
  <span>payable</span>
  <span>false</span>
</span>

<div />

##### Returned `value`

You can get the value of a component by calling `component.data().value`. All returned values of `component.data()` can be found in the [components reference](/docs/payments/online/element/components)

| key | description |
| - | - |
| cardCvv `number` | card cvv |

Example

```js theme={"dark"}
let cashfree = Cashfree({
	mode: "sandbox", //or production
});
let cardCvv = cashfree.create("cardCvv", {});
cardCvv.on("loaderror", function (data) {
	console.log(data.error);
});
cardCvv.mount("#mount-here");
cardCvv.on("ready", function (d) {
	console.log(cardCvv.data().value); //{cardCvv: '123'}
	//or
	//console.log(d.value)
});
```

## UPI components

List of UPI components

### upiCollect

A component to accept user's vpa/upi id

<span>
  <span>kind</span>
  <span>input</span>
</span>

<span>
  <span>payable</span>
  <span>true</span>
</span>

<div />

##### Accepted `values`

You can pass values to a component using [options](/docs/payments/online/element/customize#configuration-options) `cashfree.create('componentName', options)`

| key | description |
| - | - |
| placeholder `string` <span>OPTIONAL</span> | placeholder for enter vpa field |
| upiId `string` <span>OPTIONAL</span> | vpa/ upi id of the customer |

<div />

##### Returned `value`

You can get the value of a component by calling `component.data().value`. All returned values of `component.data()` can be found in the [components reference](/docs/payments/online/element/components)

| key | description |
| - | - |
| upiId `string` | vpa/ upi id of the customer |

Example

```js theme={"dark"}
let cashfree = Cashfree({
	mode: "sandbox", //or production
});
let upiCollect = cashfree.create("upiCollect", {
	values: {
		upiId: "janedoe1@okbankname",
	},
});
upiCollect.on("loaderror", function (data) {
	console.log(data.error);
});
upiCollect.mount("#mount-here");
upiCollect.on("ready", function (d) {
	console.log(upiCollect.data().value); //{upiId: 'janedoe1@okbankname'}
	//or
	//console.log(d.value)
});
```

### upiApp

A component to initiate UPI app/intent payment. Only works in mobile phones. If you mount it on desktop it will throw an error in `loaderror`

<span>
  <span>kind</span>
  <span>button</span>
</span>

<span>
  <span>payable</span>
  <span>true</span>
</span>

<Warning>
  Mobile only. Component will not mount on custom webview/inappbrowser Android. It
  will however mount in popular apps like Facebook, Instagram, Twitter. For iPhone
  it will always mount.
</Warning>

<div />

##### Accepted `values`

You can pass values to a component using [options](/docs/payments/online/element/customize#configuration-options) `cashfree.create('componentName', options)`

| key | description |
| - | - |
| upiApp `string` <span>Required</span> | name of the upi app |
| buttonText `string` <span>OPTIONAL</span> | Text for button, ex Google Pay for upiApp gpay |
| buttonIcon `bool` <span>OPTIONAL</span> | whether to show app icon or not |

View [available options for `upiApp` in the appendix](/docs/payments/online/element/appendix#upi-app-list)

<Info>
  In case `buttonText` is not provided the value of `buttonIcon` would be
  replaced to `true`. This has been done so that your customer always sees icon
  of the app.
</Info>

<div />

##### Returned `value`

You can get the value of a component by calling `component.data().value`. All returned values of `component.data()` can be found in the [components reference](/docs/payments/online/element/components)

| key | description |
| - | - |
| upiApp | name of the upi app |

Example

```js theme={"dark"}
let cashfree = Cashfree({
	mode: "sandbox", //or production
});
let upiApp = cashfree.create("upiApp", {
	values: {
		upiApp: "gpay",
		buttonText: "GPAY",
		buttonIcon: true,
	},
});
upiApp.on("loaderror", function (data) {
	console.log(data.error);
});
upiApp.mount("#mount-here");
upiApp.on("ready", function (d) {
	console.log(upiApp.data().value); //{upiApp: 'gpay'}
	//or
	//console.log(d.value)
});
```

##### [Example](/docs/payments/online/element/examples#upi-intent)

### upiQr

A component to show a UPI qr code

<span>
  <span>kind</span>
  <span>image</span>
</span>

<span>
  <span>payable</span>
  <span>true</span>
</span>

<div />

##### Accepted `values`

You can pass values to a component using [options](/docs/payments/online/element/customize#configuration-options) `cashfree.create('componentName', options)`

| key | description |
| - | - |
| size `string` <span>required</span> | size of the qr code. ex "220px" |

<div />

##### Returned `value`

You can get the value of a component by calling `component.data().value`. All returned values of `component.data()` can be found in the [components reference](/docs/payments/online/element/components)

| key | description |
| - | - |
| size `string` | size of the qr code. ex "220px" |

Example

```js theme={"dark"}
let cashfree = Cashfree({
	mode: "sandbox", //or production
});
let upiQr = cashfree.create("upiQr", {
	values: {
		size: "220px",
	},
});
upiQr.on("loaderror", function (data) {
	console.log(data.error);
});
upiQr.mount("#mount-here");
upiQr.on("ready", function (d) {
	console.log(upiQr.data().value); //{size: '220px'}
	//or
	//console.log(d.value)
});
```

***

## Wallet components

Wallet has only one component

### wallet

A component to initiate wallet payment.

<span>
  <span>kind</span>
  <span>button</span>
</span>

<span>
  <span>payable</span>
  <span>true</span>
</span>

<div />

##### Accepted `values`

You can pass values to a component using [options](/docs/payments/online/element/customize#configuration-options) `cashfree.create('componentName', options)`

| key | description |
| - | - |
| provider `string` <span>Required</span> | name of the wallet. ex `phonepe`. See [all wallet provider names in the appendix](/docs/payments/online/element/appendix#wallet-providers) |
| buttonText `string` <span>OPTIONAL</span> | Text for button, ex Google Pay for upiApp gpay |
| buttonIcon `bool` <span>OPTIONAL</span> | whether to show app icon or not |
| phone `string` <span>Required</span> | 10 digit phone number of your customer |

<Warning>
  In case `buttonText` is not provided the value of `buttonIcon` would be
  replaced to `true`. This has been done so that your customer always sees icon
  of the app.
</Warning>

##### Returned `value`

You can get the value of a component by calling `component.data().value`. All returned values of `component.data()` can be found in the [components reference](/docs/payments/online/element/components)

| key | description |
| - | - |
| provider `string` | name of the wallet. ex `phonepe`. See [all wallet provider names in the appendix](/docs/payments/online/element/appendix#wallet-providers) |
| phone `string` | 10 digit phone number of your customer |

Example

```js theme={"dark"}
let cashfree = Cashfree({
	mode: "sandbox", //or production
});
let wallet = cashfree.create("wallet", {
	values: {
		provider: "phonepe",
		phone: "94140905",
		buttonText: "PhonePe",
		buttonIcon: true,
	},
});
wallet.on("loaderror", function (data) {
	console.log(data.error);
});
wallet.mount("#mount-here");
wallet.on("ready", function (d) {
	console.log(wallet.data().value); //{provide: 'phonepe', phone: '94140905'}
	//or
	//console.log(d.value)
});
```

All possible values of `provider` can be found in the [wallet providers appendix](/docs/payments/online/element/appendix#wallet-providers)

***

## Netbanking components

Netbanking has only one component

### netbanking

A component to initiate Net Banking payment.

<span>
  <span>kind</span>
  <span>button</span>
</span>

<span>
  <span>payable</span>
  <span>true</span>
</span>

<div />

##### Accepted `values`

You can pass values to a component using [options](/docs/payments/online/element/customize#configuration-options) `cashfree.create('componentName', options)`

| key | description |
| - | - |
| netbankingBankName `string` <span>Required</span> | name of the bank. ex HDFCR. See [list](/docs/payments/online/element/appendix#netbanking-code-and-names) |
| buttonText `string` <span>OPTIONAL</span> | Text for button, ex Google Pay for upiApp gpay |
| buttonIcon `bool` <span>OPTIONAL</span> | whether to show app icon or not |

<Note>
  In case `buttonText` is not provided the value of `buttonIcon` would be
  replaced to `true`. This has been done so that your customer always sees icon
  of the app.
</Note>

##### Returned `value`

You can get the value of a component by calling `component.data().value`. All returned values of `component.data()` can be found in the [components reference](/docs/payments/online/element/components)

| key | description |
| - | - |
| netbankingBankName `string` | name of the bank |

Example

```js theme={"dark"}
let cashfree = Cashfree({
	mode: "sandbox", //or production
});
let netbanking = cashfree.create("netbanking", {
	values: {
		netbankingBankName: "HDFCR",
		buttonText: "HDFC Bank",
		buttonIcon: true,
	},
});
netbanking.on("loaderror", function (data) {
	console.log(data.error);
});
netbanking.mount("#mount-here");
netbanking.on("ready", function (d) {
	console.log(netbanking.data().value); //{netbankingBankName: 'HDFCR'}
	//or
	//console.log(d.value)
});
```

All possible values of `netbankingBankName` can be found in the [netbanking codes and names appendix](/docs/payments/online/element/appendix#netbanking-code-and-names)

***

## Paylater components

Paylater has only one component

### paylater

A component to initiate paylater payment.

<span>
  <span>kind</span>
  <span>button</span>
</span>

<span>
  <span>payable</span>
  <span>true</span>
</span>

<div />

##### Accepted `values`

You can pass values to a component using [options](/docs/payments/online/element/customize#configuration-options) `cashfree.create('componentName', options)`

| key | description |
| - | - |
| provider `string` <span>Required</span> | name of the wallet. ex `simpl`. See [all pay later provider names in the appendix](/docs/payments/online/element/appendix#paylater-providers) |
| buttonText `string` <span>OPTIONAL</span> | Text for button, ex Simpl |
| buttonIcon `bool` <span>OPTIONAL</span> | whether to show app icon or not |
| phone `string` <span>Required</span> | 10 digit phone number of your customer |

<Note>
  In case `buttonText` is not provided the value of `buttonIcon` would be
  replaced to `true`. This has been done so that your customer always sees icon
  of the app.
</Note>

##### Returned `value`

You can get the value of a component by calling `component.data().value`. All returned values of `component.data()` can be found in the [components reference](/docs/payments/online/element/components)

| key | description |
| - | - |
| provider `string` | name of the provider. ex `simpl`. See [all pay later provider names in the appendix](/docs/payments/online/element/appendix#paylater-providers) |
| phone `string` | 10 digit phone number of your customer |

Example

```js theme={"dark"}
let cashfree = Cashfree({
	mode: "sandbox", //or production
});
let p = cashfree.create("paylater", {
	values: {
		provider: "simpl",
		phone: "94140905",
		buttonText: "Use Simpl",
		buttonIcon: true,
	},
});
p.on("loaderror", function (data) {
	console.log(data.error);
});
p.mount("#mount-here");
p.on("ready", function (d) {
	console.log(d.value);
});
```

All possible values of `provider` can be found in the [pay later providers appendix](/docs/payments/online/element/appendix#paylater-providers)

***

***

## Cardless EMI components

Paylater has only one component

### cardlessEMI

A component to initiate Cardless EMI payment.

<span>
  <span>kind</span>
  <span>button</span>
</span>

<span>
  <span>payable</span>
  <span>true</span>
</span>

<div />

##### Accepted `values`

You can pass values to a component using [options](/docs/payments/online/element/customize#configuration-options) `cashfree.create('componentName', options)`

| key | description |
| - | - |
| provider `string` <span>Required</span> | name of the wallet. ex `flexmoney`. See [all cardless EMI provider names in the appendix](/docs/payments/online/element/appendix#cardless-emi-providers) |
| buttonText `string` <span>OPTIONAL</span> | Text for button, ex Flexmoney |
| buttonIcon `bool` <span>OPTIONAL</span> | whether to show app icon or not |
| phone `string` <span>Required</span> | 10 digit phone number of your customer |

<Note>
  In case `buttonText` is not provided the value of `buttonIcon` would be
  replaced to `true`. This has been done so that your customer always sees icon
  of the app.
</Note>

##### Returned `value`

You can get the value of a component by calling `component.data().value`. All returned values of `component.data()` can be found in the [components reference](/docs/payments/online/element/components)

| key | description |
| - | - |
| provider `string` | name of the provider. ex `flexmoney`. See [all cardless EMI provider names in the appendix](/docs/payments/online/element/appendix#cardless-emi-providers) |
| phone `string` | 10 digit phone number of your customer |

Example

```js theme={"dark"}
let cashfree = Cashfree({
	mode: "sandbox", //or production
});
let cl = cashfree.create("cardlessEMI", {
	values: {
		provider: "flexmoney",
		phone: "94140905",
		buttonText: "Flexmoney",
		buttonIcon: true,
	},
});
cl.on("loaderror", function (data) {
	console.log(data.error);
});
cl.mount("#mount-here");
cl.on("ready", function (d) {
	console.log(d.value);
});
```

All possible values of `provider` can be found in the [cardless EMI providers appendix](/docs/payments/online/element/appendix#cardless-emi-providers)

***

## Other components

### savePaymentInstrument

A component that can be used in `.pay()` to save a payment method for a customer. This works for only cards. This will tokenise your card

<span>
  <span>kind</span>
  <span>checkbox</span>
</span>

<span>
  <span>payable</span>
  <span>false</span>
</span>

<div />

##### Accepted `values`

You can pass values to a component using [options](/docs/payments/online/element/customize#configuration-options) `cashfree.create('componentName', options)`

| key | description |
| - | - |
| label `string` <span>OPTIONAL</span> | Label for the checkbox |

##### Returned `value`

You can get the value of a component by calling `component.data().value`. All returned values of `component.data()` can be found in the [components reference](/docs/payments/online/element/components)

| key | description |
| - | - |
| saveInstrument `bool` | does the user wants to save |


# Android Element Custom Card Component (Non-PCI)
Source: https://www.cashfree.com/docs/payments/online/element/custom-card/android-custom-card

Integrate the Cashfree Custom Card Component into your Android application to accept card payments without handling raw card data.

The Cashfree Custom Card Component lets you embed a secure, SDK-managed card input field directly into your Android application UI. Because the `CFCardNumberView` component captures and processes the card number entirely within the SDK, your application never receives the raw card number. This makes the integration suitable for non-PCI merchants, that is, merchants who are not certified to store, process, or transmit raw cardholder data, and who rely on the SDK to handle card data securely on their behalf.

<Note>
  This page covers the custom card component integration only. For the full Android Element integration, including net banking, wallet, and UPI, see [Android Integration](/docs/payments/online/element/mobile/android).
</Note>

## Prerequisites

Complete the following tasks before you start the integration:

* Create a [Cashfree Merchant Account](https://merchant.cashfree.com/merchants/signup).
* Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and generate an **App ID** and **Secret Key**. Learn how to [generate API keys](/docs/api-reference/authentication#generate-api-keys).
* Set your application's `minSdkVersion` to API level 19 or higher.

The integration consists of three steps:

<CardGroup>
  <Card title="Step 1" icon="money-bill-wave" href="/docs/payments/online/element/custom-card/android-custom-card#step-1-create-an-order-server-side">
    Create an order
  </Card>

  <Card title="Step 2" icon="desktop" href="/docs/payments/online/element/custom-card/android-custom-card#step-2-open-the-payment-page-client-side">
    Open the payment page
  </Card>

  <Card title="Step 3" icon="circle-check" href="/docs/payments/online/element/custom-card/android-custom-card#step-3-confirm-the-payment-server-side">
    Confirm the payment
  </Card>
</CardGroup>

## Step 1: Create an order <Badge>Server-side</Badge>

Create an order from your backend server before you process any payment.

<Note>This API requires your secret key. Create orders through your server only — do not call this API directly from your mobile application.</Note>

##### API request for creating an order

Here's a sample request for creating an order using your desired backend language. Cashfree offers backend [SDKs](/docs/api-reference/payments/sdk#server-sdk) to simplify the integration process.

<CodeGroup>
  ```bash curl theme={"dark"}
  curl --location 'https://sandbox.cashfree.com/pg/orders' \
  --header 'X-Client-Secret: {{clientKey}}' \
  --header 'X-Client-Id: {{clientId}}' \
  --header 'x-api-version: 2025-01-01' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data-raw '{
    "order_amount": 10.10,
    "order_currency": "INR",
    "customer_details": {
      "customer_id": "USER123",
      "customer_name": "joe",
      "customer_email": "joe.s@cashfree.com",
      "customer_phone": "+919876543210"
    },
    "order_meta": {
      "return_url": "https://b8af79f41056.eu.ngrok.io?order_id=order_123"
    }
  }'
  ```

  ```javascript nodejs theme={"dark"}
  import { Cashfree, CFEnvironment } from "cashfree-pg";

  const cashfree = new Cashfree(
  	CFEnvironment.PRODUCTION,
  	"{Client ID}",
  	"{Client Secret Key}"
  );

  function createOrder() {
  	var request = {
  		order_amount: "1",
  		order_currency: "INR",
  		customer_details: {
  			customer_id: "node_sdk_test",
  			customer_name: "",
  			customer_email: "example@gmail.com",
  			customer_phone: "9999999999",
  		},
  		order_meta: {
  			return_url:
  				"https://test.cashfree.com/pgappsdemos/return.php?order_id=order_123",
  		},
  		order_note: "",
  	};

  	cashfree
  		.PGCreateOrder(request)
  		.then((response) => {
  			console.log("Order created successfully:", response.data);
  		})
  		.catch((error) => {
  			console.error("Error setting up order request:", error.response.data);
  		});
  }
  ```

  ```python python theme={"dark"}
  from cashfree_pg.models.create_order_request import CreateOrderRequest
  from cashfree_pg.api_client import Cashfree
  from cashfree_pg.models.customer_details import CustomerDetails


  Cashfree.XClientId = {Client ID}
  Cashfree.XClientSecret = {Client Secret Key}
  Cashfree.XEnvironment = Cashfree.XSandbox
  x_api_version = "2023-08-01"

  def create_order():
          customerDetails = CustomerDetails(customer_id="123", customer_phone="9999999999")
          createOrderRequest = CreateOrderRequest(order_amount=1, order_currency="INR", customer_details=customerDetails)
          try:
              api_response = Cashfree().PGCreateOrder(x_api_version, createOrderRequest, None, None)
              print(api_response.data)
          except Exception as e:
              print(e)
  ```

  ```java java theme={"dark"}
  import com.cashfree.*;

  Cashfree.XClientId = {Client Key};
  Cashfree.XClientSecret = {Client Secret Key};
  Cashfree.XEnvironment = Cashfree.SANDBOX;

  static void createOrder() {
    CustomerDetails customerDetails = new CustomerDetails();
    customerDetails.setCustomerId("123");
    customerDetails.setCustomerPhone("9999999999");

    CreateOrderRequest request = new CreateOrderRequest();
    request.setOrderAmount(1.0);
    request.setOrderCurrency("INR");
    request.setCustomerDetails(customerDetails);
    try {
      Cashfree cashfree = new Cashfree();
      ApiResponse<OrderEntity> response = cashfree.PGCreateOrder("2023-08-01", request, null, null, null);
      System.out.println(response.getData().getOrderId());

    } catch (ApiException e) {
      throw new RuntimeException(e);
    }
  }
  ```

  ```go go theme={"dark"}
  import (
    cashfree "github.com/cashfree/cashfree-pg/v3"
  )

  func createOrder() {

  clientId := {Client ID}
  clientSecret := {Client Secret Key}
  cashfree.XClientId = &clientId
  cashfree.XClientSecret = &clientSecret
  cashfree.XEnvironment = cashfree.SANDBOX

  request := cashfree.CreateOrderRequest{
  		OrderAmount: 1,
  		CustomerDetails: cashfree.CustomerDetails{
  			CustomerId:    "1",
  			CustomerPhone: "9999999999",
  		},
  		OrderCurrency: "INR",
  		OrderSplits:   []cashfree.VendorSplit{},
  	}
  	version := "2023-08-01"
  	response, httpResponse, err := cashfree.PGCreateOrder(&version, &request, nil, nil, nil)
  	if err != nil {
  		fmt.Println(err.Error())
  	} else {
  		fmt.Println(httpResponse.StatusCode)
  		fmt.Println(response)
      }
  }
  ```

  ```csharp .net theme={"dark"}
  using cashfree_pg.Client;
  using cashfree_pg.Model;

  Cashfree.XClientId = {Client ID};
  Cashfree.XClientSecret = {Client Secret Key};
  Cashfree.XEnvironment = Cashfree.PRODUCTION;
  var cashfree = new Cashfree();
  var xApiVersion = "2023-08-01";

  void CreateOrder() {
      var customerDetails = new CustomerDetails("123", null, "9999999999");
      var createOrdersRequest = new CreateOrderRequest(null, 1.0, "INR", customerDetails);
      try {
          // Create Order
          var result = cashfree.PGCreateOrder(xApiVersion, createOrdersRequest, null, null, null);
          Console.WriteLine(result);
          Console.WriteLine(result.StatusCode);
          Console.WriteLine((result.Content as OrderEntity));
      } catch (ApiException e) {
          Console.WriteLine("Exception when calling PGCreateOrder: " + e.Message);
          Console.WriteLine("Status Code: " + e.ErrorCode);
          Console.WriteLine(e.StackTrace);
      }
  }
  ```

  ```php php theme={"dark"}
  \Cashfree\Cashfree::$XClientId = "<x-client-id>";
  \Cashfree\Cashfree::$XClientSecret = "<x-client-secret>";
  \Cashfree\Cashfree::$XEnvironment = Cashfree\Cashfree::$SANDBOX;

  $cashfree = new \Cashfree\Cashfree();

  $x_api_version = "2023-08-01";
  $create_orders_request = new \Cashfree\Model\CreateOrdersRequest();
  $create_orders_request->setOrderAmount(1.0);
  $create_orders_request->setOrderCurrency("INR");
  $customer_details = new \Cashfree\Model\CustomerDetails();
  $customer_details->setCustomerId("123");
  $customer_details->setCustomerPhone("9999999999");
  $create_orders_request->setCustomerDetails($customer_details);

  try {
      $result = $cashfree->PGCreateOrder($x_api_version, $create_orders_request);
      print_r($result);
  } catch (Exception $e) {
      echo 'Exception when calling PGCreateOrder: ', $e->getMessage(), PHP_EOL;
  }
  ```
</CodeGroup>

After successfully creating an order, you will receive a unique `order_id` and `payment_session_id` that you need for subsequent steps.

You can view the complete API request and response for `/orders` in the [Create Order API](/docs/api-reference/payments/latest/orders/create-order).

## Step 2: Open the payment page <Badge>Client-side</Badge>

After you create the order, set up the card component and open the payment page so the customer can provide their card details.

### 1. Set up the SDK

The Cashfree Android SDK is available on Maven Central. The latest version is [2.5.0](https://github.com/cashfree/nextgen-android). The SDK requires Android API level 19 or higher.

Add the following dependency to your app-level `build.gradle` file:

```gradle theme={"dark"}
implementation 'com.cashfree.pg:api:2.5.0'
```

### 2. Complete the payment

To complete the payment, follow these steps:

1. Add the `CFCardNumberView` component to your layout XML.
2. Initialise the card component in your activity or fragment.
3. Create a `CFSession` object.
4. Set up the `ICardInfo` callback.
5. Set up the payment callback.
6. Build the payment object and initiate the payment.

#### Add the card component to your layout

The `CFCardNumberView` component extends `TextInputLayout`, which means all standard `TextInputLayout` properties and methods apply to it. Add it to your layout XML file as follows:

```xml theme={"dark"}
<com.cashfree.pg.core.api.ui.CFCardNumberView
    android:id="@+id/cf_element_card"
    style="@style/Widget.MaterialComponents.TextInputLayout.OutlinedBox"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:layout_marginStart="16dp"
    android:layout_marginTop="16dp"
    android:layout_marginEnd="16dp"
    android:hint="@string/card_number"
    app:boxBackgroundColor="@color/white"
    app:boxStrokeColor="@color/color_cta"
    app:cf_card_error_text="Enter valid card number"
    app:cf_card_text_size="16sp"
    app:errorTextColor="@color/txt_error"
    app:helperTextTextColor="@color/color_cta"
    app:layout_constraintEnd_toEndOf="parent"
    app:layout_constraintStart_toStartOf="parent"
    app:layout_constraintTop_toTopOf="parent" />
```

The following XML attributes are available to customise the card component's appearance:

| Attribute | Description |
| - | - |
| `android:hint` | Hint text displayed on the card input field. |
| `app:boxBackgroundColor` | Background colour of the card input field. |
| `app:boxStrokeColor` | Stroke (border) colour of the card input field. |
| `app:errorTextColor` | Colour of the validation error message text. |
| `app:cf_card_error_text` | Custom error message shown when the card number is invalid. This is a Cashfree-provided attribute. |
| `app:cf_card_text_size` | Font size of the card number text. This is a Cashfree-provided attribute. |

Because `CFCardNumberView` extends `TextInputLayout`, you can also call standard `TextInputLayout` methods programmatically. The following example shows commonly used methods:

```java theme={"dark"}
cfElementCard.setError("Your error message");
cfElementCard.setEnabled(true);
cfElementCard.setErrorEnabled(false);
```

#### Initialise the card component

Obtain a reference to the `CFCardNumberView` in your activity or fragment:

```java theme={"dark"}
// Declare the variable
private CFCardNumberView cfElementCard;

// Get the view reference from the layout
cfElementCard = findViewById(R.id.cf_element_card);
```

#### Create a session

The `CFSession` object holds the session context for the payment. It accepts the `payment_session_id` and `order_id` obtained from [Step 1](#step-1-create-an-order-server-side), and the Cashfree environment (`.SANDBOX` or `.PRODUCTION`).

```java theme={"dark"}
CFSession cfSession = new CFSession.CFSessionBuilder()
        .setEnvironment(CFSession.Environment.SANDBOX) // or .PRODUCTION
        .setPaymentSessionID(paymentSessionID)
        .setOrderId(orderID)
        .build();
```

#### Set up the ICardInfo callback

Call the `initialize()` method on the `CFCardNumberView` object after you have created the session. The callback delivers card metadata to your application after each digit the customer enters.

```java theme={"dark"}
try {
    cfElementCard.initialize(cfSession, jsonObject -> {
        // Card metadata is delivered here after each digit is entered.
        Log.d("CFCARDVIEW", jsonObject.toString());
    });
} catch (CFException e) {
    e.printStackTrace();
}
```

The callback delivers a `JSONObject` with the following structure:

| Field | Available from | Description |
| - | - | - |
| `cardLength` | First digit | The number of digits entered so far. |
| `luhnCheckInfo` | First digit | Whether the current card number passes the Luhn algorithm check. Values: `SUCCESS` or `FAIL`. |
| `cardBinInfo` | 8th digit | Card network metadata. Only present after the 8th digit is entered. |
| `cardBinInfo.scheme` | 8th digit | Card network scheme (for example, `visa`, `mastercard`). |
| `cardBinInfo.bankName` | 8th digit | Issuing bank name (for example, `axis bank`). |
| `cardBinInfo.type` | 8th digit | Card type classification. |
| `cardBinInfo.subType` | 8th digit | Card sub-type classification. |
| `cardBinInfo.brand` | 8th digit | Card brand classification. |

<Warning>
  The `cardBinInfo` object is only present in the callback after the customer has entered at least 8 digits. Always check that the key exists in the `JSONObject` before accessing it to avoid a `JSONException`.
</Warning>

The following log output illustrates how the callback data evolves as the customer enters their card number:

```json theme={"dark"}
// After the 1st digit
{"cardLength": 1, "luhnCheckInfo": "FAIL"}

// After the 2nd digit
{"cardLength": 2, "luhnCheckInfo": "FAIL"}

// After the 8th digit — cardBinInfo becomes available
{
  "cardLength": 8,
  "luhnCheckInfo": "FAIL",
  "cardBinInfo": {
    "scheme": "visa",
    "type": "filtered",
    "subType": "filtered",
    "brand": "filtered",
    "bankName": "axis bank"
  }
}

// After all 16 digits — luhnCheckInfo passes
{
  "cardLength": 16,
  "luhnCheckInfo": "SUCCESS",
  "cardBinInfo": {
    "scheme": "visa",
    "type": "filtered",
    "subType": "filtered",
    "brand": "filtered",
    "bankName": "axis bank"
  }
}
```

#### Set up the payment callback

The SDK exposes an interface `CFCheckoutResponseCallback` to receive callbacks from the SDK once the payment flow ends. This interface consists of two methods:

```java theme={"dark"}
public void onPaymentVerify(String orderID)
public void onPaymentFailure(CFErrorResponse cfErrorResponse, String orderID)
```

<Tip>Register the callback in your activity's `onCreate` method. This configuration also handles activity restart cases correctly.</Tip>

The following example shows how to implement the callback in your activity:

```java theme={"dark"}
public class YourActivity extends AppCompatActivity implements CFCheckoutResponseCallback {

    @Override
    public void onPaymentVerify(String orderID) {
        Log.e("onPaymentVerify", "verifyPayment triggered");
    }

    @Override
    public void onPaymentFailure(CFErrorResponse cfErrorResponse, String orderID) {
        Log.e("onPaymentFailure " + orderID, cfErrorResponse.getMessage());
    }

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_element_checkout);

        cfElementCard = findViewById(R.id.cf_element_card);

        try {
            CFPaymentGatewayService.getInstance().setCheckoutCallback(this);
        } catch (CFException e) {
            e.printStackTrace();
        }

        try {
            CFSession cfSession = new CFSession.CFSessionBuilder()
                    .setEnvironment(CFSession.Environment.SANDBOX) // or .PRODUCTION
                    .setPaymentSessionID(paymentSessionID)
                    .setOrderId(orderID)
                    .build();

            cfElementCard.initialize(cfSession, jsonObject -> Log.d("CFCARDVIEW", jsonObject.toString()));
        } catch (CFException e) {
            e.printStackTrace();
        }
    }
}
```

#### Build the payment object and initiate payment

When the customer fills in their card details and taps the pay button, build the `CFCard` and `CFCardPayment` objects and call `doPayment()` on the `CFCardNumberView` instance.

<Warning>
  You must set `.setCfCard(true)` on the `CFCard` builder, and you must not call `setCardNumber`. Because the SDK manages the card number internally via `CFCardNumberView`, your application does not have access to the raw card number. Setting `.setCfCard(true)` tells the SDK to retrieve the card number from the component rather than expecting it from your code. Omitting this field causes the payment to fail. Never calling `setCardNumber` is what keeps your application out of PCI scope for card data.
</Warning>

```java theme={"dark"}
public void onElementPayClick(View view) {
    try {
        CFCard cfCard = new CFCard.CFCardBuilder()
                .setCardHolderName(cardHolderName)
                .setCardExpiryMonth(cardMM)
                .setCardExpiryYear(cardYY)
                .setCVV(cardCVV)
                .setCfCard(true) // Required for the custom card component. Do not call setCardNumber.
                .setChannel("post")
                .build();

        CFTheme theme = new CFTheme.CFThemeBuilder()
                .setNavigationBarBackgroundColor("#6A2222")
                .setNavigationBarTextColor("#FFFFFF")
                .setButtonBackgroundColor("#6Aaaaa")
                .setButtonTextColor("#FFFFFF")
                .setPrimaryTextColor("#11385b")
                .setSecondaryTextColor("#808080")
                .build();

        CFCardPayment cfCardPayment = new CFCardPayment.CFCardPaymentBuilder()
                .setSession(cfSession)
                .setCard(cfCard)
                .build();
        cfCardPayment.setTheme(theme);

        // doPayment is called on the CFCardNumberView object, not on CFCorePaymentGatewayService.
        cfElementCard.doPayment(ElementCheckoutActivity.this, cfCardPayment);
    } catch (CFException exception) {
        exception.printStackTrace();
    }
}
```

<Note>
  Call `doPayment()` on the `cfElementCard` object, not on `CFCorePaymentGatewayService`. This is different from the raw card flow described in the [Android Integration](/docs/payments/online/element/mobile/android) page.
</Note>

#### Sample code

The following example shows a complete custom card component payment flow, including session creation, card component initialisation, optional theme customisation, and payment initiation.

<AccordionGroup>
  <Accordion title="Custom card component payment sample">
    ```java theme={"dark"}
    private CFCardNumberView cfElementCard;
    private CFSession cfSession;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_element_checkout);

        cfElementCard = findViewById(R.id.cf_element_card);

        try {
            CFPaymentGatewayService.getInstance().setCheckoutCallback(this);
        } catch (CFException e) {
            e.printStackTrace();
        }

        try {
            cfSession = new CFSession.CFSessionBuilder()
                    .setEnvironment(CFSession.Environment.SANDBOX) // or .PRODUCTION
                    .setPaymentSessionID(paymentSessionID)
                    .setOrderId(orderID)
                    .build();

            cfElementCard.initialize(cfSession, jsonObject -> Log.d("CFCARDVIEW", jsonObject.toString()));
        } catch (CFException e) {
            e.printStackTrace();
        }
    }

    public void onElementPayClick(View view) {
        try {
            CFCard cfCard = new CFCard.CFCardBuilder()
                    .setCardHolderName(cardHolderName)
                    .setCardExpiryMonth(cardMM)
                    .setCardExpiryYear(cardYY)
                    .setCVV(cardCVV)
                    .setCfCard(true)
                    .setChannel("post")
                    .build();

            CFTheme theme = new CFTheme.CFThemeBuilder()
                    .setNavigationBarBackgroundColor("#6A2222")
                    .setNavigationBarTextColor("#FFFFFF")
                    .setButtonBackgroundColor("#6Aaaaa")
                    .setButtonTextColor("#FFFFFF")
                    .setPrimaryTextColor("#11385b")
                    .setSecondaryTextColor("#808080")
                    .build();

            CFCardPayment cfCardPayment = new CFCardPayment.CFCardPaymentBuilder()
                    .setSession(cfSession)
                    .setCard(cfCard)
                    .build();
            cfCardPayment.setTheme(theme);

            cfElementCard.doPayment(ElementCheckoutActivity.this, cfCardPayment);
        } catch (CFException exception) {
            exception.printStackTrace();
        }
    }

    @Override
    public void onPaymentVerify(String orderID) {
        Log.e("onPaymentVerify", "verifyPayment triggered");
    }

    @Override
    public void onPaymentFailure(CFErrorResponse cfErrorResponse, String orderID) {
        Log.e("onPaymentFailure " + orderID, cfErrorResponse.getMessage());
    }
    ```
  </Accordion>
</AccordionGroup>

#### Sample GitHub code

<AccordionGroup>
  <Accordion title="Android custom card component sample">
    [GitHub sample](https://github.com/cashfree/nextgen-android/blob/d65184fa0fad01d8916b758847973ac890db0591/app/src/main/java/com/cashfree/sdk_sample/java/ElementCheckoutActivity.java#L37)
  </Accordion>
</AccordionGroup>

## Step 3: Confirm the payment <Badge>Server-side</Badge>

After the SDK delivers a callback via `onPaymentVerify`, confirm the payment status from your backend before taking any action. The SDK callback signals only that the payment flow has ended. It does not guarantee a successful payment.

To verify an order you can call our `/pg/orders` endpoint from your backend. You can also use our SDK to achieve the same.

<CodeGroup>
  ```bash curl theme={"dark"}
  curl --request GET \
       --url https://sandbox.cashfree.com/pg/orders/{order_id} \
       --header 'accept: application/json' \
       --header 'x-api-version: 2025-01-01' \
       --header 'x-client-id: "YOUR APP ID GOES HERE"' \
       --header 'x-client-secret: "YOUR SECRET KEY GOES HERE"'
  ```

  ```javascript nodejs theme={"dark"}
  cashfree
  .PGFetchOrder("<order_id>")
  .then((response) => {
  	console.log("Order fetched successfully:", response.data);
  })
  .catch((error) => {
  	console.error("Error:", error.response.data.message);
  });
  ```

  ```python python theme={"dark"}
  from cashfree_pg.models.create_order_request import CreateOrderRequest
  from cashfree_pg.api_client import Cashfree
  from cashfree_pg.models.customer_details import CustomerDetails
  from cashfree_pg.models.order_meta import OrderMeta

  Cashfree.XClientId = "<x-client-id>"
  Cashfree.XClientSecret = "<x-client-secret>"
  Cashfree.XEnvironment = Cashfree.SANDBOX
  x_api_version = "2023-08-01"

  try:
      api_response = Cashfree().PGFetchOrder(x_api_version, "order_3242X4jQ5f0S9KYxZO9mtDL1Kx2Y7u", None)
      print(api_response.data)
  except Exception as e:
      print(e)

  ```

  ```java java theme={"dark"}
  import com.cashfree.*;
  //other code

  try {
      Cashfree.XClientId = "<x-client-id>";
      Cashfree.XClientSecret = "<x-client-secret>";
      Cashfree.XEnvironment = Cashfree.SANDBOX;

      Cashfree cashfree = new Cashfree();
      String xApiVersion = "2023-08-01";

      ApiResponse<OrderEntity> responseFetchOrder = cashfree.PGFetchOrder(xApiVersion, "<order_id>", null, null, null);
      System.out.println(response.getData().getOrderId());
  } catch (ApiException e) {
      throw new RuntimeException(e);
  }
  ```

  ```go go theme={"dark"}
  version := "2023-08-01"
  response, httpResponse, err := cashfree.PGFetchOrder(&version, "<order_id>", nil, nil, nil)
  if err != nil {
  	fmt.Println(err.Error())
  } else {
  	fmt.Println(httpResponse.StatusCode)
  	fmt.Println(response)
  }
  ```

  ```csharp .net theme={"dark"}
  using cashfree_pg.Client;
  using cashfree_pg.Model;

  Cashfree.XClientId = "<x-client-id>";
  Cashfree.XClientSecret = "<x-client-secret>";
  Cashfree.XEnvironment = Cashfree.SANDBOX;
  var cashfree = new Cashfree();
  var xApiVersion = "2023-08-01";

  try {
      var result = cashfree.PGFetchOrder(xApiVersion, "<order_id>>", null, null);
      Console.WriteLine(result);
      Console.WriteLine(result.StatusCode);
      Console.WriteLine((result.Content as OrderEntity));
  } catch (ApiException e) {
      Console.WriteLine("Exception when calling PGFetchOrder: " + e.Message);
      Console.WriteLine("Status Code: " + e.ErrorCode);
      Console.WriteLine(e.StackTrace);
  }
  ```

  ```php php theme={"dark"}
  $x_api_version = "2023-08-01";
  try {
      $response = $cashfree->PGFetchOrder($x_api_version, "<order_id>");
      print_r($response);
  } catch (Exception $e) {
      echo 'Exception when calling PGFetchOrder: ', $e->getMessage(), PHP_EOL;
  }
  ```
</CodeGroup>

<Note>
  Always verify the order status from your backend before you deliver goods or services to the customer. You can use the [Get Order API](/docs/api-reference/payments/latest/orders/get-order) for this. An order is successful when the `order_status` is `PAID`.
</Note>

## Error codes

To confirm the error returned in your Android application, you can view the error codes exposed by the SDK.

<Accordion title="Show error codes">
  The SDK validation errors are grouped by category as follows:

  ### Session errors

  | Error code | Message |
  | - | - |
  | `SESSION_OBJECT_MISSING` | The "session" is missing in the request. |
  | `PAYMENT_OBJECT_MISSING` | The "payment" is missing in the request. |
  | `ENVIRONMENT_MISSING` | The "environment" is missing in the request. |

  ### Card errors

  | Error code | Message |
  | - | - |
  | `CARD_OBJECT_MISSING` | The CFCard object is missing in the request. |
  | `CARD_EXPIRY_MONTH_MISSING` | The "card\_expiry\_mm" is missing in the request. |
  | `CARD_EXPIRY_YEAR_MISSING` | The "card\_expiry\_yy" is missing in the request. |
  | `CARD_CVV_MISSING` | The "card\_cvv" is missing in the request. |
  | `CHANNEL_MISSING` | The "channel" is missing in the request. |
  | `CARD_NUMBER_MISSING` | The "card\_number" is missing in the request. This flow does not call `setCardNumber`; confirm with Cashfree Support if you see this error. |

  ### Callback and general errors

  | Error code | Message |
  | - | - |
  | `MISSING_CALLBACK` | The callback is missing in the request. |
  | `INVALID_PAYMENT_OBJECT_SENT` | The payment object that's set doesn't match any payment mode. Set the correct payment mode and try again. |
  | `WRONG_CALLING_CONTEXT` | Calling context must be activity or fragment. |
</Accordion>

## Other options

The following optional configurations let you customise the payment screen appearance and enable SDK logging for troubleshooting.

<AccordionGroup>
  <Accordion title="(Optional) Customise the theme">
    Apply a custom theme to the payment screen to match your application's visual design. Use the `CFTheme` builder to set colours for the navigation bar, buttons, and text. Apply the theme to your payment object before you call `doPayment()`.

    ```java theme={"dark"}
    CFTheme theme = new CFTheme.CFThemeBuilder()
            .setNavigationBarBackgroundColor("#6A2222") // sets the status bar and toolbar colour
            .setNavigationBarTextColor("#FFFFFF")        // sets the toolbar text colour
            .setButtonBackgroundColor("#6Aaaaa")          // sets the primary button background colour
            .setButtonTextColor("#FFFFFF")                // sets the primary button text colour
            .setPrimaryTextColor("#11385b")               // sets the primary text colour
            .setSecondaryTextColor("#808080")             // sets the secondary text colour
            .build();

    cfCardPayment.setTheme(theme);
    ```
  </Accordion>

  <Accordion title="(Optional) Enable logging to debug issues">
    To enable SDK logging, add the following entry to your `values.xml` file:

    ```xml theme={"dark"}
    <integer name="cashfree_pg_logging_level">3</integer>
    ```

    The following logging levels are available, listed from least to most verbose:

    | Level | Value |
    | - | - |
    | VERBOSE | 2 |
    | DEBUG | 3 |
    | INFO | 4 |
    | WARN | 5 |
    | ERROR | 6 |
    | ASSERT | 7 |
  </Accordion>
</AccordionGroup>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/payments/latest/orders/create-order">Create Order API</a></li>
    <li><a href="/docs/api-reference/payments/latest/orders/get-order">Get Order API</a></li>
    <li><a href="/docs/payments/online/element/mobile/android">Android Integration (Full Element SDK)</a></li>
    <li><a href="https://github.com/cashfree/nextgen-android">Android SDK on GitHub</a></li>
  </ul>
</div>


# React Native Element Custom Card Component
Source: https://www.cashfree.com/docs/payments/online/element/custom-card/react-native-custom-card

Integrate the Cashfree Custom Card Component into your React Native application to accept card payments without handling raw card data.

The Cashfree Custom Card Component lets you embed a secure, SDK-managed card input field directly into your React Native application UI. Because the `CFCard` component captures and processes the card number entirely within the SDK, your application never receives the raw card number. This makes the integration suitable for non-PCI merchants, that is, merchants who are not certified to store, process, or transmit raw cardholder data, and who rely on the SDK to handle card data securely on their behalf.

<Note>
  This page covers the custom card component integration only. For the full React Native Element integration, including raw card, net banking, and UPI Intent, see [React Native Integration](/docs/payments/online/element/mobile/react-native).
</Note>

## Prerequisites

Complete the following tasks before you start the integration:

* Create a [Cashfree Merchant Account](https://merchant.cashfree.com/merchants/signup).
* Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and generate an **App ID** and **Secret Key**. Learn how to [generate API keys](/docs/api-reference/authentication#generate-api-keys).
* Use Cashfree React Native SDK version **2.4.0** or above. Get it from [npm](https://www.npmjs.com/package/react-native-cashfree-pg-sdk).
* Set your Android application's `minSdkVersion` to API level 19 or higher.
* Set your iOS minimum deployment target to 10.3 or higher.

The integration consists of three steps:

<CardGroup>
  <Card title="Step 1" icon="money-bill-wave" href="/docs/payments/online/element/custom-card/react-native-custom-card#step-1-create-an-order-server-side">
    Create an order
  </Card>

  <Card title="Step 2" icon="desktop" href="/docs/payments/online/element/custom-card/react-native-custom-card#step-2-open-the-payment-page-client-side">
    Open the payment page
  </Card>

  <Card title="Step 3" icon="circle-check" href="/docs/payments/online/element/custom-card/react-native-custom-card#step-3-confirm-the-payment-server-side">
    Confirm the payment
  </Card>
</CardGroup>

## Step 1: Create an order <Badge>Server-side</Badge>

Create an order from your backend server before you process any payment.

<Note>This API requires your secret key. Create orders through your server only. Do not call this API directly from your mobile application.</Note>

##### API request for creating an order

Here's a sample request for creating an order using your desired backend language. Cashfree offers backend [SDKs](/docs/api-reference/payments/sdk#server-sdk) to simplify the integration process.

<CodeGroup>
  ```bash curl theme={"dark"}
  curl --location 'https://sandbox.cashfree.com/pg/orders' \
  --header 'X-Client-Secret: {{clientKey}}' \
  --header 'X-Client-Id: {{clientId}}' \
  --header 'x-api-version: 2025-01-01' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data-raw '{
    "order_amount": 10.10,
    "order_currency": "INR",
    "customer_details": {
      "customer_id": "USER123",
      "customer_name": "joe",
      "customer_email": "joe.s@cashfree.com",
      "customer_phone": "+919876543210"
    },
    "order_meta": {
      "return_url": "https://b8af79f41056.eu.ngrok.io?order_id=order_123"
    }
  }'
  ```

  ```javascript nodejs theme={"dark"}
  import { Cashfree, CFEnvironment } from "cashfree-pg";

  const cashfree = new Cashfree(
  	CFEnvironment.PRODUCTION,
  	"{Client ID}",
  	"{Client Secret Key}"
  );

  function createOrder() {
  	var request = {
  		order_amount: "1",
  		order_currency: "INR",
  		customer_details: {
  			customer_id: "node_sdk_test",
  			customer_name: "",
  			customer_email: "example@gmail.com",
  			customer_phone: "9999999999",
  		},
  		order_meta: {
  			return_url:
  				"https://test.cashfree.com/pgappsdemos/return.php?order_id=order_123",
  		},
  		order_note: "",
  	};

  	cashfree
  		.PGCreateOrder(request)
  		.then((response) => {
  			console.log("Order created successfully:", response.data);
  		})
  		.catch((error) => {
  			console.error("Error setting up order request:", error.response.data);
  		});
  }
  ```

  ```python python theme={"dark"}
  from cashfree_pg.models.create_order_request import CreateOrderRequest
  from cashfree_pg.api_client import Cashfree
  from cashfree_pg.models.customer_details import CustomerDetails


  Cashfree.XClientId = {Client ID}
  Cashfree.XClientSecret = {Client Secret Key}
  Cashfree.XEnvironment = Cashfree.XSandbox
  x_api_version = "2023-08-01"

  def create_order():
          customerDetails = CustomerDetails(customer_id="123", customer_phone="9999999999")
          createOrderRequest = CreateOrderRequest(order_amount=1, order_currency="INR", customer_details=customerDetails)
          try:
              api_response = Cashfree().PGCreateOrder(x_api_version, createOrderRequest, None, None)
              print(api_response.data)
          except Exception as e:
              print(e)
  ```

  ```java java theme={"dark"}
  import com.cashfree.*;

  Cashfree.XClientId = {Client Key};
  Cashfree.XClientSecret = {Client Secret Key};
  Cashfree.XEnvironment = Cashfree.SANDBOX;

  static void createOrder() {
    CustomerDetails customerDetails = new CustomerDetails();
    customerDetails.setCustomerId("123");
    customerDetails.setCustomerPhone("9999999999");

    CreateOrderRequest request = new CreateOrderRequest();
    request.setOrderAmount(1.0);
    request.setOrderCurrency("INR");
    request.setCustomerDetails(customerDetails);
    try {
      Cashfree cashfree = new Cashfree();
      ApiResponse<OrderEntity> response = cashfree.PGCreateOrder("2023-08-01", request, null, null, null);
      System.out.println(response.getData().getOrderId());

    } catch (ApiException e) {
      throw new RuntimeException(e);
    }
  }
  ```

  ```go go theme={"dark"}
  import (
    cashfree "github.com/cashfree/cashfree-pg/v3"
  )

  func createOrder() {

  clientId := {Client ID}
  clientSecret := {Client Secret Key}
  cashfree.XClientId = &clientId
  cashfree.XClientSecret = &clientSecret
  cashfree.XEnvironment = cashfree.SANDBOX

  request := cashfree.CreateOrderRequest{
  		OrderAmount: 1,
  		CustomerDetails: cashfree.CustomerDetails{
  			CustomerId:    "1",
  			CustomerPhone: "9999999999",
  		},
  		OrderCurrency: "INR",
  		OrderSplits:   []cashfree.VendorSplit{},
  	}
  	version := "2023-08-01"
  	response, httpResponse, err := cashfree.PGCreateOrder(&version, &request, nil, nil, nil)
  	if err != nil {
  		fmt.Println(err.Error())
  	} else {
  		fmt.Println(httpResponse.StatusCode)
  		fmt.Println(response)
      }
  }
  ```

  ```csharp .net theme={"dark"}
  using cashfree_pg.Client;
  using cashfree_pg.Model;

  Cashfree.XClientId = {Client ID};
  Cashfree.XClientSecret = {Client Secret Key};
  Cashfree.XEnvironment = Cashfree.PRODUCTION;
  var cashfree = new Cashfree();
  var xApiVersion = "2023-08-01";

  void CreateOrder() {
      var customerDetails = new CustomerDetails("123", null, "9999999999");
      var createOrdersRequest = new CreateOrderRequest(null, 1.0, "INR", customerDetails);
      try {
          // Create Order
          var result = cashfree.PGCreateOrder(xApiVersion, createOrdersRequest, null, null, null);
          Console.WriteLine(result);
          Console.WriteLine(result.StatusCode);
          Console.WriteLine((result.Content as OrderEntity));
      } catch (ApiException e) {
          Console.WriteLine("Exception when calling PGCreateOrder: " + e.Message);
          Console.WriteLine("Status Code: " + e.ErrorCode);
          Console.WriteLine(e.StackTrace);
      }
  }
  ```

  ```php php theme={"dark"}
  \Cashfree\Cashfree::$XClientId = "<x-client-id>";
  \Cashfree\Cashfree::$XClientSecret = "<x-client-secret>";
  \Cashfree\Cashfree::$XEnvironment = Cashfree\Cashfree::$SANDBOX;

  $cashfree = new \Cashfree\Cashfree();

  $x_api_version = "2023-08-01";
  $create_orders_request = new \Cashfree\Model\CreateOrdersRequest();
  $create_orders_request->setOrderAmount(1.0);
  $create_orders_request->setOrderCurrency("INR");
  $customer_details = new \Cashfree\Model\CustomerDetails();
  $customer_details->setCustomerId("123");
  $customer_details->setCustomerPhone("9999999999");
  $create_orders_request->setCustomerDetails($customer_details);

  try {
      $result = $cashfree->PGCreateOrder($x_api_version, $create_orders_request);
      print_r($result);
  } catch (Exception $e) {
      echo 'Exception when calling PGCreateOrder: ', $e->getMessage(), PHP_EOL;
  }
  ```
</CodeGroup>

After successfully creating an order, you will receive a unique `order_id` and `payment_session_id` that you need for subsequent steps.

You can view the complete API request and response for `/orders` in the [Create Order API](/docs/api-reference/payments/latest/orders/create-order).

## Step 2: Open the payment page <Badge>Client-side</Badge>

After you create the order, set up the card component and open the payment page so the customer can provide their card details.

### 1. Set up the SDK

The React Native SDK is hosted on [npm](https://www.npmjs.com/). You can get the SDK [2.4.0](https://www.npmjs.com/package/react-native-cashfree-pg-sdk). The React Native SDK supports Android SDK version 19 and above and iOS minimum deployment target of 10.3 and above.

Install the SDK in your React Native project:

<CodeGroup>
  ```npm npm theme={"dark"}
  npm install react-native-cashfree-pg-sdk@2.4.0
  ```

  ```yarn yarn theme={"dark"}
  yarn add react-native-cashfree-pg-sdk@2.4.0
  ```

  ```expo expo theme={"dark"}
  npx expo install react-native-cashfree-pg-sdk
  npx expo install expo-dev-client
  npx expo prebuild
  npx expo run:android
  npx expo run:ios
  ```
</CodeGroup>

For iOS, run the following commands:

```bash theme={"dark"}
cd ios
pod install --repo-update
```

### 2. Complete the payment

To complete the payment, follow these steps:

1. Create a `CFSession` object.
2. Set up the payment callback.
3. Create a card number UI component (`CFCard`).
4. Build an `ElementCard` object and call `doPayment()` on the card component reference.

#### Create a session

The `CFSession` object holds the session context for the payment. It accepts the `payment_session_id` and `order_id` obtained from [Step 1](#step-1-create-an-order-server-side), and the Cashfree environment (`CFEnvironment.SANDBOX` or `CFEnvironment.PRODUCTION`).

```typescript theme={"dark"}
import {
  CFEnvironment,
  CFSession,
} from 'cashfree-pg-api-contract';

try {
  const session = new CFSession(
    '<PAYMENT_SESSION_ID>',
    '<ORDER_ID>',
    CFEnvironment.SANDBOX // or CFEnvironment.PRODUCTION
  );
} catch (e: any) {
  console.log(e.message);
}
```

#### Set up the payment callback

The SDK exposes a `CFCallback` interface to receive callbacks from the SDK once the payment flow ends. The callback supports two methods:

```typescript theme={"dark"}
onVerify(orderID: string): void
onError(error: CFErrorResponse, orderID: string): void
```

<Tip>
  Set the callback in `componentDidMount` and remove it in `componentWillUnmount`. This configuration also handles activity restart cases and prevents memory leaks.
</Tip>

```typescript theme={"dark"}
import { Component } from 'react';
import {
  CFErrorResponse,
  CFPaymentGatewayService,
} from 'react-native-cashfree-pg-sdk';

export default class App extends Component {
  componentDidMount() {
    CFPaymentGatewayService.setCallback({
      onVerify(orderID: string): void {
        // Verify the order status from your backend.
      },
      onError(error: CFErrorResponse, orderID: string): void {
        console.log(JSON.stringify(error), orderID);
      },
    });
  }

  componentWillUnmount() {
    CFPaymentGatewayService.removeCallback();
  }
}
```

#### Create a card number UI component

Pass a `cfSession` object and a `cardListener` callback to `CFCard`. Both parameters are mandatory. `CFCard` also accepts standard React Native `TextInput` props so you can style and control the input field.

```typescript theme={"dark"}
export type CardInputProps = {
  cfSession: CFSession;
  cardListener: (response: string) => void;
} & TextInputProps;
```

Create a reference for the card component so you can call `doPayment()` later:

```typescript theme={"dark"}
this.creditCardRef = React.createRef();
```

Add the `CFCard` component to your view:

```typescript theme={"dark"}
import { CFCard } from 'react-native-cashfree-pg-sdk';

const cfCard = (
  <CFCard
    cfSession={this.getSession()}
    cardListener={this.handleCFCardInput}
    ref={this.creditCardRef}
    style={{ flex: 1 }}
    placeholder="Enter Card Number"
    placeholderTextColor="#0000ff"
    underlineColorAndroid="transparent"
    cursorColor="gray"
    returnKeyType="next"
    onSubmitEditing={() => console.log('onSubmitEditing')}
    onEndEditing={() => console.log('onEndEditing')}
    onBlur={() => console.log('onBlur')}
    onFocus={() => console.log('onFocus')}
  />
);
```

##### Card listener response

The `cardListener` callback is invoked on every key press. Until the customer enters 8 digits, the response contains only Luhn status and card length, because a minimum of 8 digits is required to identify the card BIN (Bank Identification Number).

```json theme={"dark"}
{"luhn_check_info":"FAIL","card_length":1}
{"luhn_check_info":"FAIL","card_length":2}
{"luhn_check_info":"FAIL","card_length":3}
{"luhn_check_info":"FAIL","card_length":4}
{"luhn_check_info":"FAIL","card_length":5}
{"luhn_check_info":"FAIL","card_length":6}
{"luhn_check_info":"FAIL","card_length":7}
```

From the 8th digit onwards, the callback also includes `tdr_info`, `card_bin_info`, and `card_network`:

```json theme={"dark"}
{
  "tdr_info": {
    "upfrontTransactionAmount": 2,
    "paymentCode": 10014,
    "serviceCharge": 0,
    "serviceTax": 0
  },
  "card_bin_info": {
    "scheme": "visa",
    "type": "credit",
    "subType": "retail",
    "brand": "visa rewards",
    "bankName": "axis bank"
  },
  "card_network": "visa",
  "luhn_check_info": "FAIL",
  "card_length": 8,
  "last_four_digit": "1234"
}
```

| Field | Available from | Description |
| - | - | - |
| `card_length` | First digit | The number of digits entered so far. |
| `luhn_check_info` | First digit | Whether the current card number passes the Luhn algorithm check. Values: `SUCCESS` or `FAIL`. |
| `tdr_info` | 8th digit | Transaction discount rate metadata for the card BIN. |
| `card_bin_info` | 8th digit | Card network and issuer metadata. |
| `card_bin_info.scheme` | 8th digit | Card network scheme (for example, `visa`, `mastercard`). |
| `card_bin_info.bankName` | 8th digit | Issuing bank name (for example, `axis bank`). |
| `card_bin_info.type` | 8th digit | Card type classification (for example, `credit`). |
| `card_bin_info.subType` | 8th digit | Card sub-type classification. |
| `card_bin_info.brand` | 8th digit | Card brand classification. |
| `card_network` | 8th digit | Card network scheme string used for UI updates such as network icons. |
| `last_four_digit` | When Luhn passes | Last four digits of the card number. |

<Warning>
  `tdr_info`, `card_bin_info`, and `card_network` are only present after the customer has entered at least 8 digits. Always check that these keys exist before you access them.
</Warning>

Use the `card_network` value from the listener to update your UI. The following example shows how to map common networks:

```typescript theme={"dark"}
handleCFCardInput = (data: string) => {
  console.log('CFCardInput FROM SDK', data);
  const cardNetwork = JSON.parse(data)['card_network'];
  switch (cardNetwork) {
    case 'visa':
    case 'mastercard':
    case 'amex':
    case 'maestro':
    case 'rupay':
    case 'diners':
    case 'discover':
    case 'jcb':
      // Update your card network image in the UI.
      break;
    default:
      break;
  }
};
```

##### Sample card form UI

Collect the remaining card fields (holder name, expiry, and CVV) in your own UI. The SDK manages only the card number through `CFCard`.

```typescript theme={"dark"}
render() {
  const cfCard = (
    <CFCard
      cfSession={this.getSession()}
      style={{ flex: 1 }}
      cardListener={this.handleCFCardInput}
      placeholder="Enter Card Number"
      placeholderTextColor="#0000ff"
      underlineColorAndroid="transparent"
      cursorColor="gray"
      returnKeyType="next"
      ref={this.creditCardRef}
      onSubmitEditing={() => console.log('onSubmitEditing')}
      onEndEditing={() => console.log('onEndEditing')}
      onBlur={() => console.log('onBlur')}
      onFocus={() => console.log('onFocus')}
    />
  );

  return (
    <ScrollView>
      <View style={styles.container}>
        <View style={styles.cardContainer}>
          {cfCard}
        </View>
        <TextInput
          style={styles.input}
          placeholder="Holder Name"
          keyboardType="default"
          onChangeText={this.handleCardHolderName}
        />
        <View style={{ flexDirection: 'row', alignSelf: 'stretch' }}>
          <TextInput
            style={styles.input}
            placeholder="Expiry Month"
            keyboardType="numeric"
            maxLength={2}
            onChangeText={this.handleCardExpiryMM}
          />
          <TextInput
            style={styles.input}
            placeholder="Expiry Year"
            keyboardType="numeric"
            maxLength={2}
            onChangeText={this.handleCardExpiryYY}
          />
          <TextInput
            style={styles.input}
            placeholder="CVV"
            keyboardType="numeric"
            maxLength={3}
            secureTextEntry={true}
            onChangeText={this.handleCardCVV}
          />
        </View>
        <Button
          onPress={() => this.handleSubmit()}
          title="Card Payment"
        />
      </View>
    </ScrollView>
  );
}
```

#### Build the ElementCard object and initiate payment

When the customer enters all details and taps the pay button, create an `ElementCard` object and call `doPayment()` on the card component reference.

`ElementCard` does not include the card number. The SDK retrieves the card number from the `CFCard` component, which keeps your application out of PCI scope for card data.

| Field | Description |
| - | - |
| `cardHolderName` | Name printed on the card. |
| `cardExpiryMM` | Card expiry month in `MM` format. |
| `cardExpiryYY` | Card expiry year in `YY` format. |
| `cardCvv` | Card CVV. |
| `saveCard` | Set `true` to save the card for future payments. |

```typescript theme={"dark"}
import { ElementCard } from 'cashfree-pg-api-contract';

private handleSubmit = () => {
  if (this.creditCardRef.current) {
    const elementCard = new ElementCard(
      this.state.cardHolderName,
      this.state.cardExpiryMM,
      this.state.cardExpiryYY,
      this.state.cardCVV,
      false // set true to save the card
    );

    this.creditCardRef.current.doPayment(elementCard);
  }
};
```

<Note>
  Call `doPayment()` on the `creditCardRef` object, not on `CFPaymentGatewayService`. This is different from the raw card flow described in the [React Native Integration](/docs/payments/online/element/mobile/react-native) page.
</Note>

If you cannot create the order before rendering the card component, pass an initial session to `CFCard` for rendering, then call `doPaymentWithPaymentSessionId()` with the updated session when the customer pays:

```typescript theme={"dark"}
this.creditCardRef.current.doPaymentWithPaymentSessionId(
  elementCard,
  this.getSession()
);
```

#### Sample code

The following example shows a complete custom card component payment flow, including session creation, card component setup, listener handling, and payment initiation.

<AccordionGroup>
  <Accordion title="Custom card component payment sample">
    ```typescript theme={"dark"}
    import * as React from 'react';
    import { Component } from 'react';
    import {
      Button,
      ScrollView,
      StyleSheet,
      TextInput,
      View,
    } from 'react-native';
    import {
      CFCard,
      CFErrorResponse,
      CFPaymentGatewayService,
    } from 'react-native-cashfree-pg-sdk';
    import {
      CFEnvironment,
      CFSession,
      ElementCard,
    } from 'cashfree-pg-api-contract';

    export default class App extends Component {
      constructor() {
        super();
        this.creditCardRef = React.createRef();
        this.state = {
          cardHolderName: '',
          cardExpiryMM: '',
          cardExpiryYY: '',
          cardCVV: '',
          toggleCheckBox: false,
        };
      }

      handleCardHolderName = (name: string) => {
        this.setState({ cardHolderName: name });
      };

      handleCardExpiryMM = (month: string) => {
        this.setState({ cardExpiryMM: month });
      };

      handleCardExpiryYY = (year: string) => {
        this.setState({ cardExpiryYY: year });
      };

      handleCardCVV = (cvv: string) => {
        this.setState({ cardCVV: cvv });
      };

      handleCFCardInput = (data: string) => {
        console.log('CFCardInput FROM SDK', data);
        const cardNetwork = JSON.parse(data)['card_network'];
        // Update your card network icon using cardNetwork when available.
      };

      componentDidMount() {
        CFPaymentGatewayService.setCallback({
          onVerify(orderID: string): void {
            // Verify the order status from your backend.
            console.log('orderId is :' + orderID);
          },
          onError(error: CFErrorResponse, orderID: string): void {
            console.log(
              'exception is : ' + JSON.stringify(error) + '\norderId is :' + orderID
            );
          },
        });
      }

      componentWillUnmount() {
        CFPaymentGatewayService.removeCallback();
      }

      private getSession(): CFSession {
        return new CFSession(
          '<PAYMENT_SESSION_ID>',
          '<ORDER_ID>',
          CFEnvironment.SANDBOX
        );
      }

      private handleSubmit = () => {
        if (this.creditCardRef.current) {
          const elementCard = new ElementCard(
            this.state.cardHolderName,
            this.state.cardExpiryMM,
            this.state.cardExpiryYY,
            this.state.cardCVV,
            this.state.toggleCheckBox
          );
          this.creditCardRef.current.doPayment(elementCard);
        }
      };

      render() {
        const cfCard = (
          <CFCard
            cfSession={this.getSession()}
            style={{ flex: 1 }}
            cardListener={this.handleCFCardInput}
            placeholder="Enter Card Number"
            placeholderTextColor="#0000ff"
            underlineColorAndroid="transparent"
            cursorColor="gray"
            returnKeyType="next"
            ref={this.creditCardRef}
            onSubmitEditing={() => console.log('onSubmitEditing')}
            onEndEditing={() => console.log('onEndEditing')}
            onBlur={() => console.log('onBlur')}
            onFocus={() => console.log('onFocus')}
          />
        );

        return (
          <ScrollView>
            <View style={styles.container}>
              <View style={styles.cardContainer}>
                {cfCard}
              </View>
              <TextInput
                style={styles.input}
                placeholder="Holder Name"
                keyboardType="default"
                placeholderTextColor="#0000ff"
                underlineColorAndroid="transparent"
                cursorColor="gray"
                onChangeText={this.handleCardHolderName}
              />
              <View style={{ flexDirection: 'row', alignSelf: 'stretch' }}>
                <TextInput
                  style={styles.input}
                  placeholder="Expiry Month"
                  keyboardType="numeric"
                  maxLength={2}
                  placeholderTextColor="#0000ff"
                  underlineColorAndroid="transparent"
                  cursorColor="gray"
                  onChangeText={this.handleCardExpiryMM}
                />
                <TextInput
                  style={styles.input}
                  placeholder="Expiry Year"
                  keyboardType="numeric"
                  maxLength={2}
                  placeholderTextColor="#0000ff"
                  underlineColorAndroid="transparent"
                  cursorColor="gray"
                  onChangeText={this.handleCardExpiryYY}
                />
                <TextInput
                  style={styles.input}
                  placeholder="CVV"
                  keyboardType="numeric"
                  maxLength={3}
                  secureTextEntry={true}
                  onChangeText={this.handleCardCVV}
                />
              </View>
              <View style={styles.button}>
                <Button
                  onPress={() => this.handleSubmit()}
                  title="Card Payment"
                />
              </View>
            </View>
          </ScrollView>
        );
      }
    }

    const styles = StyleSheet.create({
      container: {
        padding: 24,
        backgroundColor: '#eaeaea',
        alignItems: 'center',
        flexDirection: 'column',
        flex: 1,
      },
      cardContainer: {
        flexDirection: 'row',
        borderWidth: 1,
        borderColor: '#000',
        justifyContent: 'center',
        alignItems: 'center',
        margin: 10,
        alignSelf: 'stretch',
      },
      input: {
        height: 40,
        margin: 12,
        borderWidth: 1,
        padding: 10,
        flex: 1,
      },
      button: {
        margin: 8,
        width: 200,
      },
    });
    ```
  </Accordion>
</AccordionGroup>

#### Sample GitHub code

You can explore a working integration example on GitHub:

[GitHub sample](https://github.com/cashfree/react-native-cashfree-pg-sdk/blob/18c84cbad48c4e622dd622d11a0281654e371ab4/example/src/App.tsx#L67)

## Step 3: Confirm the payment <Badge>Server-side</Badge>

After the SDK delivers a callback via `onVerify`, confirm the payment status from your backend before taking any action. The SDK callback signals only that the payment flow has ended. It does not guarantee a successful payment.

To verify an order you can call our `/pg/orders` endpoint from your backend. You can also use our SDK to achieve the same.

<CodeGroup>
  ```bash curl theme={"dark"}
  curl --request GET \
       --url https://sandbox.cashfree.com/pg/orders/{order_id} \
       --header 'accept: application/json' \
       --header 'x-api-version: 2025-01-01' \
       --header 'x-client-id: "YOUR APP ID GOES HERE"' \
       --header 'x-client-secret: "YOUR SECRET KEY GOES HERE"'
  ```

  ```javascript nodejs theme={"dark"}
  cashfree
  .PGFetchOrder("<order_id>")
  .then((response) => {
  	console.log("Order fetched successfully:", response.data);
  })
  .catch((error) => {
  	console.error("Error:", error.response.data.message);
  });
  ```

  ```python python theme={"dark"}
  from cashfree_pg.models.create_order_request import CreateOrderRequest
  from cashfree_pg.api_client import Cashfree
  from cashfree_pg.models.customer_details import CustomerDetails
  from cashfree_pg.models.order_meta import OrderMeta

  Cashfree.XClientId = "<x-client-id>"
  Cashfree.XClientSecret = "<x-client-secret>"
  Cashfree.XEnvironment = Cashfree.SANDBOX
  x_api_version = "2023-08-01"

  try:
      api_response = Cashfree().PGFetchOrder(x_api_version, "order_3242X4jQ5f0S9KYxZO9mtDL1Kx2Y7u", None)
      print(api_response.data)
  except Exception as e:
      print(e)

  ```

  ```java java theme={"dark"}
  import com.cashfree.*;
  //other code

  try {
      Cashfree.XClientId = "<x-client-id>";
      Cashfree.XClientSecret = "<x-client-secret>";
      Cashfree.XEnvironment = Cashfree.SANDBOX;

      Cashfree cashfree = new Cashfree();
      String xApiVersion = "2023-08-01";

      ApiResponse<OrderEntity> responseFetchOrder = cashfree.PGFetchOrder(xApiVersion, "<order_id>", null, null, null);
      System.out.println(response.getData().getOrderId());
  } catch (ApiException e) {
      throw new RuntimeException(e);
  }
  ```

  ```go go theme={"dark"}
  version := "2023-08-01"
  response, httpResponse, err := cashfree.PGFetchOrder(&version, "<order_id>", nil, nil, nil)
  if err != nil {
  	fmt.Println(err.Error())
  } else {
  	fmt.Println(httpResponse.StatusCode)
  	fmt.Println(response)
  }
  ```

  ```csharp .net theme={"dark"}
  using cashfree_pg.Client;
  using cashfree_pg.Model;

  Cashfree.XClientId = "<x-client-id>";
  Cashfree.XClientSecret = "<x-client-secret>";
  Cashfree.XEnvironment = Cashfree.SANDBOX;
  var cashfree = new Cashfree();
  var xApiVersion = "2023-08-01";

  try {
      var result = cashfree.PGFetchOrder(xApiVersion, "<order_id>>", null, null);
      Console.WriteLine(result);
      Console.WriteLine(result.StatusCode);
      Console.WriteLine((result.Content as OrderEntity));
  } catch (ApiException e) {
      Console.WriteLine("Exception when calling PGFetchOrder: " + e.Message);
      Console.WriteLine("Status Code: " + e.ErrorCode);
      Console.WriteLine(e.StackTrace);
  }
  ```

  ```php php theme={"dark"}
  $x_api_version = "2023-08-01";
  try {
      $response = $cashfree->PGFetchOrder($x_api_version, "<order_id>");
      print_r($response);
  } catch (Exception $e) {
      echo 'Exception when calling PGFetchOrder: ', $e->getMessage(), PHP_EOL;
  }
  ```
</CodeGroup>

<Note>
  Always verify the order status from your backend before you deliver goods or services to the customer. You can use the [Get Order API](/docs/api-reference/payments/latest/orders/get-order) for this. An order is successful when the `order_status` is `PAID`.
</Note>

## Testing

After you integrate the custom card component, verify that it behaves as expected. Follow these steps to test:

1. Enter a test card number in the `CFCard` field and confirm that `cardListener` returns BIN metadata after the 8th digit.
2. Enter the holder name, expiry, and CVV in your own input fields, then tap the pay button.
3. Confirm that `onVerify` or `onError` is called when the payment flow ends.

Use the [sandbox environment](/docs/payments/online/resources/sandbox-environment) to test payments before you go live.

## Error codes

To confirm the error returned in your React Native application, you can view the error codes exposed by the SDK.

<Accordion title="Show error codes">
  The following are some of the error codes that are exposed by the SDK:

  | Error code | Message |
  | - | - |
  | `MISSING_CALLBACK` | The callback is missing in the request. |
  | `ORDER_ID_MISSING` | The "order\_id" is missing in the request. |
  | `SESSION_OBJECT_MISSING` | The "session" is missing in the request. |
  | `PAYMENT_OBJECT_MISSING` | The "payment" is missing in the request. |
  | `ENVIRONMENT_MISSING` | The "environment" is missing in the request. |
  | `CARD_OBJECT_MISSING` | The card object is missing in the request. |
  | `CARD_EXPIRY_MONTH_MISSING` | The "card\_expiry\_mm" is missing in the request. |
  | `CARD_EXPIRY_YEAR_MISSING` | The "card\_expiry\_yy" is missing in the request. |
  | `CARD_CVV_MISSING` | The "card\_cvv" is missing in the request. |
</Accordion>

<div>
  <p>Affiliate partner program</p>

  <p>As a developer building payment experiences for your clients, you can earn additional income while providing them with industry-leading payment solutions.</p>

  <p>Join the <a href="https://partner.cashfree.com/partner-ui/authentication/signup?source-action=Affiliate%20Program%20LP&action=Sign%20Up&button-id=StartNow_CashfreeAffiliatePartnerProgram">Cashfree affiliate partner program</a> and get rewarded every time your clients use Cashfree.</p>

  <p>**What you get:**</p>

  <ul>
    <li>Earn up to 0.25% commission on every transaction.</li>
    <li>Become a trusted fintech partner for your clients.</li>
    <li>Access to a dedicated partner manager for expert support.</li>
  </ul>

  <p>**What your clients get:**</p>

  <ul>
    <li>Instant activation and go live in minutes.</li>
    <li>Industry-best success rate across all payment modes.</li>
    <li>Effortless acceptance of international payments in 140+ currencies.</li>
  </ul>

  <p>Get started today. <a href="https://partner.cashfree.com/partner-ui/authentication/signup?source-action=Affiliate%20Program%20LP&action=Sign%20Up&button-id=StartNow_BecomeAPartner">Become a partner now</a>.</p>
</div>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/payments/latest/orders/create-order">Create Order API</a></li>
    <li><a href="/docs/api-reference/payments/latest/orders/get-order">Get Order API</a></li>
    <li><a href="/docs/payments/online/element/mobile/react-native">React Native Integration (Full Element SDK)</a></li>
    <li><a href="https://github.com/cashfree/react-native-cashfree-pg-sdk">React Native SDK on GitHub</a></li>
  </ul>
</div>


# Customise Component
Source: https://www.cashfree.com/docs/payments/online/element/customize

Customise Cashfree.js components by configuring appearance, styling, and behaviour options to match your design system on a custom-built checkout page.

Each `Cashfree.js` component is initialised with a configuration object that allows you to customise both its behaviour and appearance and integrate it with your application's design system.

<Note>
  All configuration options are optional, components use default styles if not specified. The style object supports most CSS properties in camelCase format. Custom fonts in the `fonts` array are loaded automatically before the component renders. Use `disabled` to temporarily prevent user interaction (e.g., during form submission). Use `loader` to show or hide loading states while the component initialises.
</Note>

Configuration is passed as the second argument to `cashfree.create()`:

```javascript theme={"dark"}
const options = {
  classes:  { /* CSS class names by state */ },
  style:    { /* inline styles by state */   },
  fonts:    [ /* custom font definitions */  ],
  values:   { /* pre-filled values */        },
  disabled: false,
  loader:   true,
};

const component = cashfree.create("componentType", options);
component.mount("#container-id");
```

## Configuration options

Select an option below to jump to its detailed customisation guide.

<CardGroup>
  <Card title="classes" icon="code" href="#classes">
    CSS class names applied per state
  </Card>

  <Card title="style" icon="paintbrush" href="#style">
    Inline CSS styles applied per state
  </Card>

  <Card title="fonts" icon="font" href="#fonts">
    Custom fonts to load inside the component
  </Card>

  <Card title="values" icon="keyboard" href="#values">
    Initial values to pre-fill the component
  </Card>

  <Card title="disabled" icon="circle-exclamation" href="#disabled">
    Load the component in a disabled state
  </Card>

  <Card title="loader" icon="spinner" href="#loader">
    Show a skeleton loader during initialisation
  </Card>
</CardGroup>

## Appearance and styling

Use these options to define how the component looks and how it integrates with your application's design system.

### classes

Type: `object`

Apply CSS class names to the component container. The SDK automatically adds or removes classes based on the component's state. You do not need to add them to your HTML manually.

<Note>
  Define these classes in your application's CSS. The SDK applies them dynamically; do not add them to the DOM container yourself.
</Note>

#### States

Each state maps to a CSS class you define in your stylesheet. The SDK adds and removes these classes automatically as the component's state changes.

| State | When it is applied |
| - | - |
| `base` | Always applied. Use this for base or default styling |
| `complete` | Applied when the user has entered a valid value |
| `empty` | Applied when no value has been entered |
| `focus` | Applied when the component has keyboard focus |
| `invalid` | Applied when the component contains invalid data |
| `disabled` | Applied when the component is disabled |

#### Default values

If you do not supply your own class names, the SDK uses the following internal defaults. These classes are not exposed in your stylesheet, so override them by specifying custom names.

```json theme={"dark"}
{
  "base":     "cf-base-private",
  "complete": "cf-complete-private",
  "empty":    "cf-empty-private",
  "focus":    "cf-focus-private",
  "invalid":  "cf-invalid-private",
  "disabled": "cf-disabled-private"
}
```

#### Usage

Pass a `classes` object inside `options` when calling `cashfree.create()`. Only include the states you want to override; any omitted states fall back to their defaults.

```javascript theme={"dark"}
const options = {
  classes: {
    base:     "my-input",
    focus:    "input-focused",
    invalid:  "input-error",
    complete: "input-complete",
  },
};

const component = cashfree.create("cardNumber", options);
component.mount("#card-number-container");
```

#### CSS examples by state

Expand any state below to see a JavaScript snippet alongside a matching CSS example.

<AccordionGroup>
  <Accordion title="base: default styling">
    Applied to the container at all times. Use this for base or default styling. If you do not provide a value, the default `cf-base-private` is applied.

    ```javascript theme={"dark"}
    const options = {
      classes: { base: "my-base" },
    };
    ```

    ```css theme={"dark"}
    .my-base {
      padding: 5px;
      border: 1px solid #ccc;
      border-radius: 4px;
    }
    ```
  </Accordion>

  <Accordion title="complete: valid input">
    Applied when the user has entered a complete, valid value (for example, a valid card number). Note that not all components apply a complete class. Default is `cf-complete-private`.

    ```javascript theme={"dark"}
    const options = {
      classes: { complete: "my-complete" },
    };
    ```

    ```css theme={"dark"}
    .my-complete {
      border-color: #28a745;
      background-color: #f0f9f7;
    }
    ```
  </Accordion>

  <Accordion title="empty: no value entered">
    Applied when the component has no value, for example when the user has not yet typed anything. Default is `cf-empty-private`.

    ```javascript theme={"dark"}
    const options = {
      classes: { empty: "my-empty" },
    };
    ```

    ```css theme={"dark"}
    .my-empty {
      box-shadow: 1px 1px 4px rgba(0, 0, 0, 0.1);
    }
    ```
  </Accordion>

  <Accordion title="focus: component is focused">
    Applied when the component receives keyboard focus, for example when the user clicks into the card number input. Default is `cf-focus-private`.

    ```javascript theme={"dark"}
    const options = {
      classes: { focus: "my-focus" },
    };
    ```

    ```css theme={"dark"}
    .my-focus {
      border-color: #0066cc;
      box-shadow: 0 0 0 3px rgba(0, 102, 204, 0.1);
    }
    ```
  </Accordion>

  <Accordion title="invalid: invalid input">
    Applied when the component contains invalid data, for example when the user has entered an incorrect card number. Default is `cf-invalid-private`.

    ```javascript theme={"dark"}
    const options = {
      classes: { invalid: "my-invalid" },
    };
    ```

    ```css theme={"dark"}
    .my-invalid {
      border-color: #C1292E;
      color: #C1292E;
    }
    ```
  </Accordion>

  <Accordion title="disabled: component is disabled">
    Applied when you have disabled the component. The `classes.disabled` styling is combined with any `style.base[":disabled"]` rules you have set. Default is `cf-disabled-private`.

    ```javascript theme={"dark"}
    const options = {
      classes: { disabled: "my-disabled" },
    };
    ```

    ```css theme={"dark"}
    .my-disabled {
      opacity: 0.6;
      cursor: not-allowed;
    }
    ```
  </Accordion>
</AccordionGroup>

### style

Type: `object`

Apply inline CSS styles directly to the component's content. The style object supports most CSS properties in **camelCase** format (for example, `fontSize` instead of `font-size`). Styles can be defined per state: `base`, `complete`, `empty`, and `invalid`.

#### Default values

The SDK applies the following style defaults when no `style` option is provided. Only `base.fontSize` and `invalid.color` are set out of the box; all other states start empty.

```json theme={"dark"}
{
  "base":     { "fontSize": "16px" },
  "complete": {},
  "empty":    {},
  "invalid":  { "color": "#C1292E" }
}
```

#### Usage

Pass a `style` object inside `options` to override the default appearance for one or more states. You only need to include the states and properties you want to change.

```javascript theme={"dark"}
const options = {
  style: {
    base: {
      color:      "#333",
      fontSize:   "16px",
      fontFamily: "Roboto, sans-serif",
      padding:    "12px",
    },
    complete: {
      color: "#28a745",
    },
    invalid: {
      color: "#C1292E",
    },
  },
};

const component = cashfree.create("cardNumber", options);
component.mount("#card-number-container");
```

#### Pseudo-classes and pseudo-elements

You can target interactive states and placeholder text by nesting pseudo-class and pseudo-element keys inside any state object. Use these inside `style.base` (or any other state) as shown below. Supported values:

| Pseudo-class or element | Description |
| - | - |
| `:hover` | Cursor is over the component |
| `:focus` | Component has keyboard focus |
| `:disabled` | Component is disabled |
| `::placeholder` | Placeholder text |

```javascript theme={"dark"}
const options = {
  style: {
    base: {
      fontSize:        "16px",
      color:           "#333",
      backgroundColor: "#fff",
      "::placeholder": {
        color: "#999",
      },
      ":hover": {
        backgroundColor: "#f9f9f9",
      },
      ":focus": {
        outline:     "none",
        borderColor: "#0066cc",
      },
      ":disabled": {
        backgroundColor: "#f0f0f0",
        color:           "#999",
      },
    },
  },
};
```

### fonts

Type: `array`

Load custom fonts to match your application's typography. Fonts specified in the `fonts` array are loaded automatically before the component renders, and are injected into the component's iframe so they render correctly in the secure context.

#### Default value

When no fonts are specified, the component inherits whatever fonts are already available in the browser environment.

```javascript theme={"dark"}
[]
```

#### Option 1: CSS URL

Reference a CSS file that contains [@font-face](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face) definitions (for example, a Google Fonts URL):

```javascript theme={"dark"}
const options = {
  fonts: [
    {
      cssSrc: "https://fonts.googleapis.com/css?family=Open+Sans",
    },
  ],
};
```

#### Option 2: Font file with parameters

Specify individual font files with full parameters. Both `src` and `fontFamily` are required; all other properties are optional.

```javascript theme={"dark"}
const options = {
  fonts: [
    {
      fontFamily:   "Nova Mono",
      fontStyle:    "normal",
      fontWeight:   400,
      fontDisplay:  "swap",
      src:          "url(https://fonts.gstatic.com/s/novamono/v18/Cn-0JtiGWQ5Ajb--MRKvZ2ZZj9AtSw.woff2)",
      unicodeRange: "U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+2000-206F, U+2074, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD",
    },
  ],
};
```

You can specify multiple fonts and reference them by `fontFamily` name inside the `style` option.

## Behaviour and initialisation

Control the initial state, disabled status, and loading experience of your components.

### values

Type: `object`

Pre-fill a component with a starting value. The available keys depend on the component type. Visit sections under different [components](/docs/payments/online/element/upi) to get all the available keys.

#### Default value

If no initial values are provided, the component renders empty and waits for user input.

```javascript theme={"dark"}
{}
```

#### Usage

Pass the keys relevant to the component type you are creating. Keys that are not recognised by the component are silently ignored.

```javascript theme={"dark"}
const options = {
  values: {
    cardHolder: "Jane Doe",
  },
};

const component = cashfree.create("cardHolder", options);
component.mount("#cardholder-container");
```

#### Examples by component

Expand the component type below to see the accepted value keys and an example pre-filled value.

<AccordionGroup>
  <Accordion title="Card Holder">
    ```javascript theme={"dark"}
    const options = {
      values: {
        cardHolder: "Jane Doe",
      },
    };
    ```
  </Accordion>

  <Accordion title="UPI Collect">
    ```javascript theme={"dark"}
    const options = {
      values: {
        upiId: "testsuccess@gocash",
      },
    };
    ```
  </Accordion>
</AccordionGroup>

### disabled

Type: `boolean`

Load the component in a disabled state. Use this to temporarily prevent user interaction (e.g., during form submission). When `true`, the component applies `classes.disabled` and `style.base[":disabled"]` styling automatically.

#### Default value

Components load in an enabled (interactive) state by default.

```javascript theme={"dark"}
false
```

#### Usage

Set `disabled` to `true` when you need to prevent user interaction, for example during form submission or while an earlier step in your checkout flow is still loading.

```javascript theme={"dark"}
const options = {
  disabled: true,
};

const component = cashfree.create("cardNumber", options);
component.mount("#card-number-container");
```

### loader

Type: `boolean`

Show or hide a skeleton loader UI while the component initialises. Use this to control loading states during initialisation. Not all components support this option.

#### Default value

The skeleton loader is enabled by default, so users see a visual placeholder immediately while the component iframe initialises.

```javascript theme={"dark"}
true
```

#### Usage

Set `loader` to `false` if you prefer to handle the loading state yourself, or if the component does not support it.

```javascript theme={"dark"}
const options = {
  loader: true,
};

const component = cashfree.create("cardNumber", options);
component.mount("#card-number-container");
```

## Complete example

The following example demonstrates all configuration options used together to create a fully customised payment component:

```javascript theme={"dark"}
const cardNumberOptions = {
  classes: {
    base: "my-input",
    focus: "input-focused",
    invalid: "input-error",
    complete: "input-complete",
  },
  fonts: [
    {
      family: "Roboto",
      src: "https://fonts.googleapis.com/css2?family=Roboto",
    },
  ],
  style: {
    base: {
      color: "#333",
      fontSize: "16px",
      fontFamily: "Roboto, sans-serif",
      padding: "12px",
      backgroundColor: "#fff",
      border: "1px solid #ccc",
      borderRadius: "4px",
    },
    focus: {
      borderColor: "#0066cc",
    },
    invalid: {
      borderColor: "#ff3333",
      color: "#ff3333",
    },
  },
  disabled: false,
  loader: true,
};

const cardNumber = cashfree.create("cardNumber", cardNumberOptions);
cardNumber.mount("#card-number-container");
```

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/payments/online/element/introduction">Element SDK Introduction</a></li>
    <li><a href="/docs/payments/online/element/component-overview">Component Overview</a></li>
    <li><a href="/docs/payments/online/element/cards">Card Components</a></li>
    <li><a href="/docs/payments/online/element/upi">UPI Components</a></li>
    <li><a href="/docs/payments/online/element/payment-options">Payment Options</a></li>
  </ul>
</div>


# Overview
Source: https://www.cashfree.com/docs/payments/online/element/element-sdk

Build a custom, PCI DSS compliant checkout for cards, UPI, and other payment modes using the Cashfree Element SDK across web and mobile apps.

The Element SDK enables merchants to build a custom checkout experience while securely processing payments through Cashfree for multiple payment methods such as cards, UPI, net banking, wallets, and other supported methods.

While merchants can use Seamless APIs to process payments via their own fully customised UI, the Element SDK simplifies the implementation by offering ready-to-use secure components and utilities for collecting payment information and initiating transactions.

<Note>The Element SDK is available for both mobile (Android and iOS) and web-based flows.</Note>

## Why use the Element SDK

The Element SDK offers the following benefits:

* Create a fully customised checkout experience that aligns with your brand.
* Support multiple payment methods through a single integration.
* Simplify development compared to a fully API-driven integration.
* Maintain PCI compliance. If you're not PCI DSS compliant, use the SDK card number component to collect card details.

## How it works for card payments

The Element SDK handles card payments through two checkout flows: plain-card checkout for new card entries and saved-card checkout for returning customers.

### Plain-card checkout

The plain-card checkout process follows these steps:

1. If the merchant is PCI DSS compliant, they can build a custom checkout UI and collect card details such as the card number, CVV, and expiry on their checkout.
2. If the merchant isn't PCI DSS compliant, they can still build a custom checkout UI, but must use the Element SDK card number component to collect the card number and collect other card details such as CVV and expiry on their own checkout.
3. You can also display a checkbox requesting customer consent for saving the card.
4. Once the customer enters the card details, provides consent, and clicks submit, call the SDK with these details to initiate the payment.
5. For the OTP authentication stage, the SDK offers a Native OTP experience with auto read and auto submit functionality.

### Saved-card checkout

You have two options to render saved cards:

* Call the Element SDK to render the list of cards on your checkout and process payments.
* Use the [Get All Saved Cards API](/docs/api-reference/payments/latest/token-vault/fetch-all-saved-card-instrument) to fetch the list of saved instruments and render them yourself. Once the customer selects a card, pass its `instrument_id` to the [Order Pay API](/docs/api-reference/payments/latest/payments/order-pay).

Saved-card transactions support CVV-less and Native OTP with auto-read and auto-submit to ensure a truly seamless experience for customers.

The following sample checkout demonstrates a card number field powered by the Cashfree Elements SDK. The merchant owns and designs the rest of the checkout experience, which matches the quality of a fully seamless merchant-built checkout.

<Card title="Card number field powered by the Element SDK">
  <CardGroup>
    <div>
      <img alt="Card number field powered by the Element SDK" />
    </div>

    <div>
      <img alt="Card number field powered by the Element SDK" />
    </div>
  </CardGroup>
</Card>

## Additional merchant capabilities

The SDK provides the following capabilities for merchants:

* **Offer eligibility and payment availability**: The SDK sends card-BIN details in a callback. Use this data to check supported payment methods or offer eligibility.
* **Native OTP experience**: During the authentication stage, the Native OTP screen appears, which auto-reads the OTP from the SMS and auto-submits it. This works for both plain-card and saved-card flows.

The Element SDK enables merchants to build a fully customised checkout UI while maintaining compliance.

## Getting started

To get started with the Element SDK:

* Refer to the [Web Element SDK](/docs/payments/online/element/introduction) for platform-specific guides.
* Contact your Cashfree account manager to enable the Element SDK if it is not already active on your account.

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/payments/online/element/introduction">Web Element SDK</a></li>
    <li><a href="/docs/api-reference/payments/latest/token-vault/fetch-all-saved-card-instrument">Get All Saved Cards API</a></li>
    <li><a href="/docs/payments/features/native-otp">Native OTP</a></li>
    <li><a href="/docs/payments/features/cvv-less">CVV‑Less</a></li>
  </ul>
</div>


# Examples
Source: https://www.cashfree.com/docs/payments/online/element/examples

Browse runnable Cashfree Element code examples on CodePen for cards, UPI, netbanking, and wallet payment UIs, ready to fork and adapt for your integration.

The examples on this page support building a custom payment UI with Cashfree Element. Each is a complete, runnable implementation on CodePen that can be forked and adapted for an integration.

<div>
  <a href="https://www.cashfree.com/devstudio/preview/pg/web/card">
    <span>
      Try it in DevStudio

      <svg>
        <path />

        <path />
      </svg>
    </span>
  </a>
</div>

## Cards

Collect card payments (debit and credit) with a custom UI while keeping card data off the server. The example shows how to mount the card element, handle validation, and complete the payment flow.

<div>
  <Card href="https://codepen.io/cashfreepayments/pen/eYLWmzZ">
    Example for building a custom UI for card payments: fork the CodePen and plug in the session and config.
  </Card>
</div>

## UPI

The following examples cover the main UPI flows: intent (app redirect), collect (VPA), and QR code. Choose the one that matches the desired customer payment flow.

### UPI intent

UPI intent opens the customer UPI app to complete the payment. The example demonstrates creating the intent component, initiating the flow, and handling success or failure.

<div>
  <Card href="https://codepen.io/cashfreepayments/pen/eYLWmBz">
    Example for building a custom UI for UPI intent payments: redirect users to their UPI app and handle the callback.
  </Card>
</div>

### UPI collect

UPI collect lets customers pay by entering their UPI ID (VPA). The example shows how to render the collect component and process payments without leaving the checkout page.

<div>
  <Card href="https://codepen.io/cashfreepayments/pen/eYLEaJZ">
    Example for building a custom UI for UPI collect: collect VPA and complete the payment in the checkout.
  </Card>
</div>

### UPI QR code

UPI QR displays a QR code that customers scan with their UPI app. The example covers generating the QR, showing it in the UI, and listening for payment status.

<div>
  <Card href="https://codepen.io/cashfreepayments/pen/KKxmbpL">
    Example for building a custom UI for UPI QR payments: show a scannable QR and complete the payment flow.
  </Card>
</div>

## Net banking

Net banking allows customers to pay via their bank online banking page. The example shows how to list banks, let the user choose one, and redirect them to complete the payment.

<div>
  <Card href="https://codepen.io/cashfreepayments/pen/qBMmBad">
    Example for building a custom UI for net banking: bank selection and redirect to the bank payment page.
  </Card>
</div>

## Wallets

Wallet payments use supported mobile wallets (e.g. Paytm, PhonePe) for one-tap checkout. The example demonstrates listing wallets and handling the wallet payment flow.

<div>
  <Card href="https://codepen.io/cashfreepayments/pen/VwGbxYz">
    Example for building a custom UI for wallet payments: wallet selection and completion in the checkout.
  </Card>
</div>


# Web Element SDK
Source: https://www.cashfree.com/docs/payments/online/element/introduction

Get started with Cashfree.js Web Element SDK by creating, mounting, and paying with payment components in three steps to power a fully custom web checkout.

## `Cashfree.js`

Below are the methods that are available on the `cashfree` object. The three main steps of integrating Cashfree Element components:

1. First step creates the card component using the `create()` method
2. Second step mounts the component to a DOM element using `mount()` method
3. Final step initiates the payment using the `pay()` method

```mermaid theme={"dark"}
graph TD
    A[Start Integration] -->|Step 1| B[Create Card Component]
    B -->|"create()"| C[Card Component Created]

    C -->|Step 2| D[Mount Component]
    D -->|"mount('#card-element')"| E[Component Mounted in DOM]

    E -->|Step 3| F[Initiate Payment]
    F -->|"pay()"| G[Payment Flow Started]

    style B fill:#e1f5fe
    style D fill:#e1f5fe
    style F fill:#e1f5fe

    subgraph "Component Lifecycle"
        B
        C
        D
        E
        F
        G
    end
```

## `checkout()`

The checkout method redirects the user to a Cashfree hosted page. See [all supported options for configuring payments](/docs/payments/online/element/payment-options). You can find a [full example in the examples guide](/docs/payments/online/element/examples)

##### How to use

```js theme={"dark"}
let checkoutOptions = {
	paymentSessionId: "payment-session-id",
	returnUrl:
		"https://test.cashfree.com/pgappsdemos/v3success.php?myorder={order_id}",
};
cashfree.checkout(checkoutOptions).then(function (result) {
	if (result.error) {
		alert(result.error.message);
	}
	if (result.redirect) {
		console.log("Redirection");
	}
});
```

##### Returns

`cashfree.checkout` will return a `Promise` that resolves with either `result.error` when there is an error or `result.redirect` when there is redirection

***

## `create()`

Use `create()` to initialize a cashfree component for your HTML page.

##### How to use

Here is a small example demonstrating how to render a UPI collect component. We will see more detailed example in the UPI collect [example](/docs/payments/online/element/examples#upi-collect).

Refer to [this page](/docs/payments/online/element/upi) for all available components

```js theme={"dark"}
let options = {
	values: {
		upiId: "rohit@icici",
	},
};
let component = cashfree.create("upiCollect", options);
```

`create` takes two arguments. The first argument is the component name of type `string`. You can find [all the component names we provide in the UPI guide](/docs/payments/online/element/upi).\
The second argument is of type `object`. It contains details about the behaviour and look of the component. Find all the [details for the `options` object in the customise guide](/docs/payments/online/element/customize)

##### Returns

An instance of the component. A component has several methods that you can find in the [component overview](/docs/payments/online/element/overview)

***

## `mount()`

If you are building your own checkout page Cashfree provides a set of components. A component can be mounted in DOM container. Use `mount()` to mount the component.

##### How to use

Syntax: `component.mount(querySelector)`\
Example

```js theme={"dark"}
//let's create a div which will have our component
const div = document.createElement("div");
div.setAttribute("id", "componentContainer");
document.body.appendChild(div);

component.mount("#componentContainer");
```

***

## `pay()`

Use `pay()` to begin payment flow for a component. Not all components are payable. Check [all the components in the other components guide](/docs/payments/online/element/other-components). The pay method takes in a [paymentOption](/docs/payments/online/element/payment-options) object.

##### How to use

```js theme={"dark"}
let paymentOptions = {
	paymentMethod: component,
	paymentSessionId: "your-payment-session-id",
	returnUrl: "https://example.com?order={order_id}",
};
cashfree.pay(paymentOptions).then(function (result) {
	if (result.error) {
		//there is an error
		//message at result.error.message
	}
	if (result.redirect) {
		//console.log("User would be redirected");
	}
	if (result.paymentDetails) {
		//only when redirect = 'if_required' for UPI payment
		//payment is successful
		//message is at result.paymentDetails.paymentMessage
	}
});
```

Read more about [payment options and their configuration](/docs/payments/online/element/payment-options).

##### Returns

`cashfree.pay` will return a `Promise`.

Upon success, the promise will resolve with `result.paymentMessage` if the user has opted for a non redirection flow. example UPI, QR. Upon redirection, the promise will resolve with `result.redirect` If the payment fails, the `Promise` will resolve with an `result.error`. `error.type` will describe the failure. In some cases you can directly show the error.message to your user. Please refer to the [error types](/docs/api-reference/payments/errors).

<Note>
  `cashfree.pay` may take several seconds to complete. During that time, you
  should disable user interaction and show a waiting indicator like a spinner.
  If you receive an error result, you should be sure to show that error to the
  customer, re-enable user interaction, and hide the waiting indicator.
</Note>

## `version()`

Get the version of the sdk. A string, which references the current version that the sdk is using. This will help you understand which version of `cashfree.js` your site is using. This is helpful in understanding features available for a version. By default we will always upgrade your sdk to the latest version. But in some cases your customer's browser might cache the javascript for some amount of time. In that case your customers will not get the latest version. Check [all versions in the payments API overview](/docs/api-reference/payments/overview)

```js theme={"dark"}
let version = cashfree.version();
```

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/payments/online/element/sdks">SDK Libraries</a></li>
    <li><a href="/docs/payments/online/element/cards">Card Components</a></li>
    <li><a href="/docs/payments/online/element/upi">UPI Components</a></li>
    <li><a href="/docs/payments/online/element/payment-options">Payment Options</a></li>
    <li><a href="/docs/payments/online/element/examples">Examples</a></li>
  </ul>
</div>


# Android Element Integration
Source: https://www.cashfree.com/docs/payments/online/element/mobile/android

Integrate the Cashfree Payment Gateway Element SDK into your Android application to accept payments via card, net banking, wallet, and UPI.

The Cashfree Payment Gateway Element SDK lets you build a fully custom payment experience within your Android application. Unlike the hosted checkout, you collect payment details directly in your own UI and pass them to the SDK, giving you complete control over the look and feel of your payment flow.

The SDK supports four payment methods: card, net banking, wallet, and UPI Intent.

<Note>
  This page describes the raw card flow, where your application collects the card number directly and is responsible for PCI DSS compliance. To avoid handling raw card numbers, use the [Android Custom Card Component](/docs/payments/online/element/custom-card/android-custom-card) instead, which captures the card number inside an SDK-managed view.
</Note>

## Prerequisites

Complete the following tasks before you start the integration:

* Create a [Cashfree Merchant Account](https://merchant.cashfree.com/merchants/signup).
* Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and generate an **App ID** and **Secret Key**. Learn how to [generate API keys](/docs/api-reference/authentication#generate-api-keys).
* Set your application's `minSdkVersion` to API level 19 or higher.

The integration consists of three steps:

<CardGroup>
  <Card title="Step 1" icon="money-bill-wave" href="/docs/payments/online/element/mobile/android#step-1-create-an-order-server-side">
    Create an order
  </Card>

  <Card title="Step 2" icon="desktop" href="/docs/payments/online/element/mobile/android#step-2-open-the-payment-page-client-side">
    Open the payment page
  </Card>

  <Card title="Step 3" icon="circle-check" href="/docs/payments/online/element/mobile/android#step-3-confirm-the-payment-server-side">
    Confirm the payment
  </Card>
</CardGroup>

## Step 1: Create an order <Badge>Server-side</Badge>

Create an order from your backend server before you process any payment.

<Note>This API requires your secret key. Create orders through your server only — do not call this API directly from your mobile application.</Note>

##### API request for creating an order

Here's a sample request for creating an order using your desired backend language. Cashfree offers backend [SDKs](/docs/api-reference/payments/sdk#server-sdk) to simplify the integration process.

<CodeGroup>
  ```bash curl theme={"dark"}
  curl --location 'https://sandbox.cashfree.com/pg/orders' \
  --header 'X-Client-Secret: {{clientKey}}' \
  --header 'X-Client-Id: {{clientId}}' \
  --header 'x-api-version: 2025-01-01' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data-raw '{
    "order_amount": 10.10,
    "order_currency": "INR",
    "customer_details": {
      "customer_id": "USER123",
      "customer_name": "joe",
      "customer_email": "joe.s@cashfree.com",
      "customer_phone": "+919876543210"
    },
    "order_meta": {
      "return_url": "https://b8af79f41056.eu.ngrok.io?order_id=order_123"
    }
  }'
  ```

  ```javascript nodejs theme={"dark"}
  import { Cashfree, CFEnvironment } from "cashfree-pg";

  const cashfree = new Cashfree(
  	CFEnvironment.PRODUCTION,
  	"{Client ID}",
  	"{Client Secret Key}"
  );

  function createOrder() {
  	var request = {
  		order_amount: "1",
  		order_currency: "INR",
  		customer_details: {
  			customer_id: "node_sdk_test",
  			customer_name: "",
  			customer_email: "example@gmail.com",
  			customer_phone: "9999999999",
  		},
  		order_meta: {
  			return_url:
  				"https://test.cashfree.com/pgappsdemos/return.php?order_id=order_123",
  		},
  		order_note: "",
  	};

  	cashfree
  		.PGCreateOrder(request)
  		.then((response) => {
  			console.log("Order created successfully:", response.data);
  		})
  		.catch((error) => {
  			console.error("Error setting up order request:", error.response.data);
  		});
  }
  ```

  ```python python theme={"dark"}
  from cashfree_pg.models.create_order_request import CreateOrderRequest
  from cashfree_pg.api_client import Cashfree
  from cashfree_pg.models.customer_details import CustomerDetails


  Cashfree.XClientId = {Client ID}
  Cashfree.XClientSecret = {Client Secret Key}
  Cashfree.XEnvironment = Cashfree.XSandbox
  x_api_version = "2023-08-01"

  def create_order():
          customerDetails = CustomerDetails(customer_id="123", customer_phone="9999999999")
          createOrderRequest = CreateOrderRequest(order_amount=1, order_currency="INR", customer_details=customerDetails)
          try:
              api_response = Cashfree().PGCreateOrder(x_api_version, createOrderRequest, None, None)
              print(api_response.data)
          except Exception as e:
              print(e)
  ```

  ```java java theme={"dark"}
  import com.cashfree.*;

  Cashfree.XClientId = {Client Key};
  Cashfree.XClientSecret = {Client Secret Key};
  Cashfree.XEnvironment = Cashfree.SANDBOX;

  static void createOrder() {
    CustomerDetails customerDetails = new CustomerDetails();
    customerDetails.setCustomerId("123");
    customerDetails.setCustomerPhone("9999999999");

    CreateOrderRequest request = new CreateOrderRequest();
    request.setOrderAmount(1.0);
    request.setOrderCurrency("INR");
    request.setCustomerDetails(customerDetails);
    try {
      Cashfree cashfree = new Cashfree();
      ApiResponse<OrderEntity> response = cashfree.PGCreateOrder("2023-08-01", request, null, null, null);
      System.out.println(response.getData().getOrderId());

    } catch (ApiException e) {
      throw new RuntimeException(e);
    }
  }
  ```

  ```go go theme={"dark"}
  import (
    cashfree "github.com/cashfree/cashfree-pg/v3"
  )

  func createOrder() {

  clientId := {Client ID}
  clientSecret := {Client Secret Key}
  cashfree.XClientId = &clientId
  cashfree.XClientSecret = &clientSecret
  cashfree.XEnvironment = cashfree.SANDBOX

  request := cashfree.CreateOrderRequest{
  		OrderAmount: 1,
  		CustomerDetails: cashfree.CustomerDetails{
  			CustomerId:    "1",
  			CustomerPhone: "9999999999",
  		},
  		OrderCurrency: "INR",
  		OrderSplits:   []cashfree.VendorSplit{},
  	}
  	version := "2023-08-01"
  	response, httpResponse, err := cashfree.PGCreateOrder(&version, &request, nil, nil, nil)
  	if err != nil {
  		fmt.Println(err.Error())
  	} else {
  		fmt.Println(httpResponse.StatusCode)
  		fmt.Println(response)
      }
  }
  ```

  ```csharp .net theme={"dark"}
  using cashfree_pg.Client;
  using cashfree_pg.Model;

  Cashfree.XClientId = {Client ID};
  Cashfree.XClientSecret = {Client Secret Key};
  Cashfree.XEnvironment = Cashfree.PRODUCTION;
  var cashfree = new Cashfree();
  var xApiVersion = "2023-08-01";

  void CreateOrder() {
      var customerDetails = new CustomerDetails("123", null, "9999999999");
      var createOrdersRequest = new CreateOrderRequest(null, 1.0, "INR", customerDetails);
      try {
          // Create Order
          var result = cashfree.PGCreateOrder(xApiVersion, createOrdersRequest, null, null, null);
          Console.WriteLine(result);
          Console.WriteLine(result.StatusCode);
          Console.WriteLine((result.Content as OrderEntity));
      } catch (ApiException e) {
          Console.WriteLine("Exception when calling PGCreateOrder: " + e.Message);
          Console.WriteLine("Status Code: " + e.ErrorCode);
          Console.WriteLine(e.StackTrace);
      }
  }
  ```

  ```php php theme={"dark"}
  \Cashfree\Cashfree::$XClientId = "<x-client-id>";
  \Cashfree\Cashfree::$XClientSecret = "<x-client-secret>";
  \Cashfree\Cashfree::$XEnvironment = Cashfree\Cashfree::$SANDBOX;

  $cashfree = new \Cashfree\Cashfree();

  $x_api_version = "2023-08-01";
  $create_orders_request = new \Cashfree\Model\CreateOrdersRequest();
  $create_orders_request->setOrderAmount(1.0);
  $create_orders_request->setOrderCurrency("INR");
  $customer_details = new \Cashfree\Model\CustomerDetails();
  $customer_details->setCustomerId("123");
  $customer_details->setCustomerPhone("9999999999");
  $create_orders_request->setCustomerDetails($customer_details);

  try {
      $result = $cashfree->PGCreateOrder($x_api_version, $create_orders_request);
      print_r($result);
  } catch (Exception $e) {
      echo 'Exception when calling PGCreateOrder: ', $e->getMessage(), PHP_EOL;
  }
  ```
</CodeGroup>

After successfully creating an order, you will receive a unique `order_id` and `payment_session_id` that you need for subsequent steps.

You can view the complete API request and response for `/orders` in the [Create Order API](/docs/api-reference/payments/latest/orders/create-order).

## Step 2: Open the payment page <Badge>Client-side</Badge>

After you create the order, open the payment page so the customer can provide payment details.

### 1. Set up the SDK

The Cashfree Android SDK is available on Maven Central. The latest version is [2.5.0](https://github.com/cashfree/nextgen-android). The SDK requires Android API level 19 or higher.

Add the following dependency to your app-level `build.gradle` file:

```gradle theme={"dark"}
implementation 'com.cashfree.pg:api:2.5.0'
```

### 2. Select a payment method

The Element SDK supports the following payment methods:

<Tabs>
  <Tab title="Card">
    In this flow, the customer enters their card details directly in your application UI. Your application receives the raw card number and passes it to the SDK, so your application remains in PCI DSS scope for card data. To avoid handling raw card numbers, use the [Android Custom Card Component](/docs/payments/online/element/custom-card/android-custom-card) instead.
  </Tab>

  <Tab title="Net banking">
    In this flow, you identify the customer's bank using a bank code. The SDK opens Cashfree's hosted net banking screen so the customer can log in and authorise the payment.
  </Tab>

  <Tab title="Wallet">
    In this flow, the customer pays using a wallet provider (for example, PhonePe) linked to their registered phone number. The SDK opens Cashfree's hosted wallet screen to complete the payment.
  </Tab>

  <Tab title="UPI Intent">
    In this flow, the SDK discovers the UPI apps installed on the customer's device and launches the selected app so the customer can authorise the payment.
  </Tab>
</Tabs>

### 3. Complete the payment

To complete the payment, follow these steps:

1. Set up the payment callback.
2. Create a `CFSession` object.
3. Create the payment object for the selected payment method.
4. Optionally, customise the theme.
5. Initiate the payment using `doPayment()`.

#### Set up the payment callback

The SDK exposes an interface `CFCheckoutResponseCallback` to receive callbacks from the SDK once the payment flow ends. This interface consists of two methods:

```java theme={"dark"}
public void onPaymentVerify(String orderID)
public void onPaymentFailure(CFErrorResponse cfErrorResponse, String orderID)
```

<Tip>Register the callback in your activity's `onCreate` method. This configuration also handles activity restart cases correctly.</Tip>

The following example shows how to implement the callback in your activity:

```java theme={"dark"}
public class YourActivity extends AppCompatActivity implements CFCheckoutResponseCallback {

    @Override
    public void onPaymentVerify(String orderID) {
        Log.e("onPaymentVerify", "verifyPayment triggered");
    }

    @Override
    public void onPaymentFailure(CFErrorResponse cfErrorResponse, String orderID) {
        Log.e("onPaymentFailure " + orderID, cfErrorResponse.getMessage());
    }

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_element_checkout);
        try {
            // If you are using a fragment, add this line inside onCreate() of your Fragment.
            CFPaymentGatewayService.getInstance().setCheckoutCallback(this);
        } catch (CFException e) {
            e.printStackTrace();
        }
    }
}
```

#### Create a session

The `CFSession` object holds the session context for the payment. It accepts the `payment_session_id` and `order_id` obtained from [Step 1](#step-1-create-an-order-server-side), and the Cashfree environment (`.SANDBOX` or `.PRODUCTION`).

```java theme={"dark"}
CFSession cfSession = new CFSession.CFSessionBuilder()
        .setEnvironment(CFSession.Environment.SANDBOX) // or .PRODUCTION
        .setPaymentSessionID(paymentSessionID)
        .setOrderId(orderID)
        .build();
```

#### Create a payment object

The SDK provides a dedicated payment builder for each supported payment method. Build only the object that corresponds to the payment method your customer has selected.

<Tabs>
  <Tab title="Card">
    Use the following builders to create a card payment object. This is the raw card flow — your application passes the full card number to the SDK using `setCardNumber`.

    ```java theme={"dark"}
    CFCard cfCard = new CFCard.CFCardBuilder()
            .setCardHolderName(cardHolderName)
            .setCardNumber(cardNumber)
            .setCardExpiryMonth(cardMM)
            .setCardExpiryYear(cardYY)
            .setCVV(cardCVV)
            .setChannel("post")
            .build();

    CFCardPayment cfCardPayment = new CFCardPayment.CFCardPaymentBuilder()
            .setSession(cfSession)
            .setCard(cfCard)
            .build();
    ```

    <Note>
      `setChannel` is a required field on the card builder. The SDK uses this value to determine how to process the card payment. Contact [Cashfree Support](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) to confirm the correct channel value for flows that require native OTP authentication.
    </Note>
  </Tab>

  <Tab title="Net banking">
    The `setBankCode` field accepts the four-digit bank code of the customer's bank.

    ```java theme={"dark"}
    CFNetBanking cfNetBanking = new CFNetBanking.CFNetBankingBuilder()
            .setBankCode(bankCode) // required, 4-digit bank code
            .build();

    CFNetBankingPayment cfNetBankingPayment = new CFNetBankingPayment.CFNetBankingPaymentBuilder()
            .setSession(cfSession)
            .setCfNetBanking(cfNetBanking)
            .build();
    ```
  </Tab>

  <Tab title="Wallet">
    The `setProvider` field accepts the wallet provider identifier (for example, `phonepe`), and `setPhone` accepts the customer's registered phone number.

    ```java theme={"dark"}
    CFWallet cfWallet = new CFWallet.CFWalletBuilder()
            .setProvider(channel) // required, for example "phonepe"
            .setPhone(phone)      // required
            .build();

    CFWalletPayment cfWalletPayment = new CFWalletPayment.CFWalletPaymentBuilder()
            .setSession(cfSession)
            .setCfWallet(cfWallet)
            .build();
    ```

    <Note>
      Confirm the complete list of supported wallet provider values with [Cashfree Support](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) before you go live.
    </Note>
  </Tab>

  <Tab title="UPI Intent">
    Use the following builder to create a UPI Intent payment object. The `setUPIID` field accepts the package name of the UPI app your customer selected.

    ```java theme={"dark"}
    CFUPI cfupi = new CFUPI.CFUPIBuilder()
            .setMode(CFUPI.Mode.INTENT)
            .setUPIID(packageName)
            .build();

    CFUPIPayment cfupiPayment = new CFUPIPayment.CFUPIPaymentBuilder()
            .setSession(cfSession)
            .setCfUPI(cfupi)
            .build();
    ```

    <Note>
      To get the package name, use `CFUPIUtil.getInstalledUPIApps` to fetch the UPI apps installed on the customer's device:

      ```java theme={"dark"}
      CFUPIUtil.getInstalledUPIApps(this, new CFUPIUtil.UPIAppsCallback() {
          @Override
          public void onUPIAppsFetched(ArrayList<CFUPIApp> upiAppList) {
              if (upiAppList != null && !upiAppList.isEmpty()) {
                  CFUPIApp upiApp = upiAppList.get(0); // CFUPIApp exposes getDisplayName() and getAppId()
                  String packageName = upiApp.getAppId();
              }
          }
      });
      ```

      `onUPIAppsFetched` is invoked on a background thread. Wrap any UI updates in `runOnUiThread()`.
    </Note>
  </Tab>
</Tabs>

#### Customise the theme (optional)

Apply a custom theme to the payment screen to match your application's visual design. Use the `CFTheme` builder to set colours for the navigation bar, buttons, and text, then apply the theme to your payment object before you call `doPayment()`.

```java theme={"dark"}
CFTheme theme = new CFTheme.CFThemeBuilder()
        .setNavigationBarBackgroundColor("#6A2222") // sets the status bar and toolbar colour
        .setNavigationBarTextColor("#FFFFFF")        // sets the toolbar text colour
        .setButtonBackgroundColor("#6Aaaaa")          // sets the primary button background colour
        .setButtonTextColor("#FFFFFF")                // sets the primary button text colour
        .setPrimaryTextColor("#11385b")               // sets the primary text colour
        .setSecondaryTextColor("#808080")             // sets the secondary text colour
        .build();

cfCardPayment.setTheme(theme);
// or: cfNetBankingPayment.setTheme(theme);
// or: cfWalletPayment.setTheme(theme);
// or: cfupiPayment.setTheme(theme);
```

#### Initiate the payment

Call `doPayment()` to open the Cashfree payment screen for the selected method. The example below uses `cfCardPayment`. Replace it with `cfNetBankingPayment`, `cfWalletPayment`, or `cfupiPayment` for your selected payment method.

```java theme={"dark"}
// Replace YourActivity with your activity class name.
CFCorePaymentGatewayService.getInstance().doPayment(YourActivity.this, cfCardPayment);
```

#### Sample code

The following example shows a complete integration, including session creation, payment object setup for each method, and payment initiation.

<AccordionGroup>
  <Accordion title="Element checkout sample">
    ```java theme={"dark"}
    package com.cashfree.sdk_sample.java;

    import androidx.appcompat.app.AppCompatActivity;

    import android.os.Bundle;
    import android.util.Log;
    import android.view.View;

    import com.cashfree.pg.api.CFPaymentGatewayService;
    import com.cashfree.pg.core.api.CFCorePaymentGatewayService;
    import com.cashfree.pg.core.api.CFSession;
    import com.cashfree.pg.core.api.CFTheme;
    import com.cashfree.pg.core.api.callback.CFCheckoutResponseCallback;
    import com.cashfree.pg.core.api.card.CFCard;
    import com.cashfree.pg.core.api.card.CFCardPayment;
    import com.cashfree.pg.core.api.exception.CFException;
    import com.cashfree.pg.core.api.netbanking.CFNetBanking;
    import com.cashfree.pg.core.api.netbanking.CFNetBankingPayment;
    import com.cashfree.pg.core.api.upi.CFUPI;
    import com.cashfree.pg.core.api.upi.CFUPIPayment;
    import com.cashfree.pg.core.api.utils.CFErrorResponse;
    import com.cashfree.pg.core.api.utils.CFUPIApp;
    import com.cashfree.pg.core.api.utils.CFUPIUtil;
    import com.cashfree.pg.core.api.wallet.CFWallet;
    import com.cashfree.pg.core.api.wallet.CFWalletPayment;

    public class ElementCheckoutActivity extends AppCompatActivity implements CFCheckoutResponseCallback {

        String orderID = "ORDER_ID";
        String paymentSessionID = "PAYMENT_SESSION_ID";
        CFSession.Environment cfEnvironment = CFSession.Environment.SANDBOX;

        @Override
        protected void onCreate(Bundle savedInstanceState) {
            super.onCreate(savedInstanceState);
            setContentView(R.layout.activity_element_checkout);
            try {
                CFPaymentGatewayService.getInstance().setCheckoutCallback(this);
            } catch (CFException e) {
                e.printStackTrace();
            }
        }

        @Override
        public void onPaymentVerify(String orderID) {
            Log.e("onPaymentVerify", "verifyPayment triggered");
        }

        @Override
        public void onPaymentFailure(CFErrorResponse cfErrorResponse, String orderID) {
            Log.e("onPaymentFailure " + orderID, cfErrorResponse.getMessage());
        }

        public void doCardPayment(View view) {
            try {
                CFSession cfSession = new CFSession.CFSessionBuilder()
                        .setEnvironment(cfEnvironment)
                        .setPaymentSessionID(paymentSessionID)
                        .setOrderId(orderID)
                        .build();
                CFCard cfCard = new CFCard.CFCardBuilder()
                        .setCardHolderName(cardHolderName)
                        .setCardNumber(cardNumber)
                        .setCardExpiryMonth(cardMM)
                        .setCardExpiryYear(cardYY)
                        .setCVV(cardCVV)
                        .setChannel("post")
                        .build();
                CFTheme theme = new CFTheme.CFThemeBuilder()
                        .setNavigationBarBackgroundColor("#6A2222")
                        .setNavigationBarTextColor("#FFFFFF")
                        .setButtonBackgroundColor("#6Aaaaa")
                        .setButtonTextColor("#FFFFFF")
                        .setPrimaryTextColor("#11385b")
                        .setSecondaryTextColor("#808080")
                        .build();
                CFCardPayment cfCardPayment = new CFCardPayment.CFCardPaymentBuilder()
                        .setSession(cfSession)
                        .setCard(cfCard)
                        .build();
                cfCardPayment.setTheme(theme);
                CFCorePaymentGatewayService.getInstance().doPayment(ElementCheckoutActivity.this, cfCardPayment);
            } catch (CFException exception) {
                exception.printStackTrace();
            }
        }

        public void doNetBankingPayment(View view) {
            try {
                CFSession cfSession = new CFSession.CFSessionBuilder()
                        .setEnvironment(cfEnvironment)
                        .setPaymentSessionID(paymentSessionID)
                        .setOrderId(orderID)
                        .build();
                CFNetBanking cfNetBanking = new CFNetBanking.CFNetBankingBuilder()
                        .setBankCode(bankCode)
                        .build();
                CFTheme theme = new CFTheme.CFThemeBuilder()
                        .setNavigationBarBackgroundColor("#6A2222")
                        .setNavigationBarTextColor("#FFFFFF")
                        .setButtonBackgroundColor("#6Aaaaa")
                        .setButtonTextColor("#FFFFFF")
                        .setPrimaryTextColor("#11385b")
                        .setSecondaryTextColor("#808080")
                        .build();
                CFNetBankingPayment cfNetBankingPayment = new CFNetBankingPayment.CFNetBankingPaymentBuilder()
                        .setSession(cfSession)
                        .setCfNetBanking(cfNetBanking)
                        .build();
                cfNetBankingPayment.setTheme(theme);
                CFCorePaymentGatewayService.getInstance().doPayment(ElementCheckoutActivity.this, cfNetBankingPayment);
            } catch (CFException exception) {
                exception.printStackTrace();
            }
        }

        public void doWalletPayment(View view) {
            try {
                CFSession cfSession = new CFSession.CFSessionBuilder()
                        .setEnvironment(cfEnvironment)
                        .setPaymentSessionID(paymentSessionID)
                        .setOrderId(orderID)
                        .build();
                CFWallet cfWallet = new CFWallet.CFWalletBuilder()
                        .setProvider(channel)
                        .setPhone(phone)
                        .build();
                CFTheme theme = new CFTheme.CFThemeBuilder()
                        .setNavigationBarBackgroundColor("#6A2222")
                        .setNavigationBarTextColor("#FFFFFF")
                        .setButtonBackgroundColor("#6Aaaaa")
                        .setButtonTextColor("#FFFFFF")
                        .setPrimaryTextColor("#11385b")
                        .setSecondaryTextColor("#808080")
                        .build();
                CFWalletPayment cfWalletPayment = new CFWalletPayment.CFWalletPaymentBuilder()
                        .setSession(cfSession)
                        .setCfWallet(cfWallet)
                        .build();
                cfWalletPayment.setTheme(theme);
                CFCorePaymentGatewayService.getInstance().doPayment(ElementCheckoutActivity.this, cfWalletPayment);
            } catch (CFException exception) {
                exception.printStackTrace();
            }
        }

        public void doUPIIntentPayment(View view) {
            CFUPIUtil.getInstalledUPIApps(this, new CFUPIUtil.UPIAppsCallback() {
                @Override
                public void onUPIAppsFetched(ArrayList<CFUPIApp> upiAppList) {
                    // Invoked on a background thread — wrap UI updates in runOnUiThread().
                    if (upiAppList != null && !upiAppList.isEmpty()) {
                        CFUPIApp upiApp = upiAppList.get(0);
                        initiateUPIPayment(upiApp.getAppId());
                    }
                }
            });
        }

        private void initiateUPIPayment(String packageName) {
            try {
                CFSession cfSession = new CFSession.CFSessionBuilder()
                        .setEnvironment(cfEnvironment)
                        .setPaymentSessionID(paymentSessionID)
                        .setOrderId(orderID)
                        .build();
                CFUPI cfupi = new CFUPI.CFUPIBuilder()
                        .setMode(CFUPI.Mode.INTENT)
                        .setUPIID(packageName)
                        .build();
                CFTheme theme = new CFTheme.CFThemeBuilder()
                        .setNavigationBarBackgroundColor("#6A2222")
                        .setNavigationBarTextColor("#FFFFFF")
                        .setButtonBackgroundColor("#6Aaaaa")
                        .setButtonTextColor("#FFFFFF")
                        .setPrimaryTextColor("#11385b")
                        .setSecondaryTextColor("#808080")
                        .build();
                CFUPIPayment cfupiPayment = new CFUPIPayment.CFUPIPaymentBuilder()
                        .setSession(cfSession)
                        .setCfUPI(cfupi)
                        .build();
                cfupiPayment.setTheme(theme);
                cfupiPayment.setLoaderEnable(true);
                CFCorePaymentGatewayService.getInstance().doPayment(ElementCheckoutActivity.this, cfupiPayment);
            } catch (CFException exception) {
                exception.printStackTrace();
            }
        }

    }
    ```
  </Accordion>
</AccordionGroup>

#### Sample GitHub code

<AccordionGroup>
  <Accordion title="Android Element integration">
    [GitHub sample](https://github.com/cashfree/nextgen-android/blob/d65184fa0fad01d8916b758847973ac890db0591/app/src/main/java/com/cashfree/sdk_sample/java/ElementCheckoutActivity.java)
  </Accordion>
</AccordionGroup>

## Step 3: Confirm the payment <Badge>Server-side</Badge>

After the SDK delivers a callback via `onPaymentVerify`, confirm the payment status from your backend before taking any action. The SDK callback signals only that the payment flow has ended. It does not guarantee a successful payment.

To verify an order you can call our `/pg/orders` endpoint from your backend. You can also use our SDK to achieve the same.

<CodeGroup>
  ```bash curl theme={"dark"}
  curl --request GET \
       --url https://sandbox.cashfree.com/pg/orders/{order_id} \
       --header 'accept: application/json' \
       --header 'x-api-version: 2025-01-01' \
       --header 'x-client-id: "YOUR APP ID GOES HERE"' \
       --header 'x-client-secret: "YOUR SECRET KEY GOES HERE"'
  ```

  ```javascript nodejs theme={"dark"}
  cashfree
  .PGFetchOrder("<order_id>")
  .then((response) => {
  	console.log("Order fetched successfully:", response.data);
  })
  .catch((error) => {
  	console.error("Error:", error.response.data.message);
  });
  ```

  ```python python theme={"dark"}
  from cashfree_pg.models.create_order_request import CreateOrderRequest
  from cashfree_pg.api_client import Cashfree
  from cashfree_pg.models.customer_details import CustomerDetails
  from cashfree_pg.models.order_meta import OrderMeta

  Cashfree.XClientId = "<x-client-id>"
  Cashfree.XClientSecret = "<x-client-secret>"
  Cashfree.XEnvironment = Cashfree.SANDBOX
  x_api_version = "2023-08-01"

  try:
      api_response = Cashfree().PGFetchOrder(x_api_version, "order_3242X4jQ5f0S9KYxZO9mtDL1Kx2Y7u", None)
      print(api_response.data)
  except Exception as e:
      print(e)

  ```

  ```java java theme={"dark"}
  import com.cashfree.*;
  //other code

  try {
      Cashfree.XClientId = "<x-client-id>";
      Cashfree.XClientSecret = "<x-client-secret>";
      Cashfree.XEnvironment = Cashfree.SANDBOX;

      Cashfree cashfree = new Cashfree();
      String xApiVersion = "2023-08-01";

      ApiResponse<OrderEntity> responseFetchOrder = cashfree.PGFetchOrder(xApiVersion, "<order_id>", null, null, null);
      System.out.println(response.getData().getOrderId());
  } catch (ApiException e) {
      throw new RuntimeException(e);
  }
  ```

  ```go go theme={"dark"}
  version := "2023-08-01"
  response, httpResponse, err := cashfree.PGFetchOrder(&version, "<order_id>", nil, nil, nil)
  if err != nil {
  	fmt.Println(err.Error())
  } else {
  	fmt.Println(httpResponse.StatusCode)
  	fmt.Println(response)
  }
  ```

  ```csharp .net theme={"dark"}
  using cashfree_pg.Client;
  using cashfree_pg.Model;

  Cashfree.XClientId = "<x-client-id>";
  Cashfree.XClientSecret = "<x-client-secret>";
  Cashfree.XEnvironment = Cashfree.SANDBOX;
  var cashfree = new Cashfree();
  var xApiVersion = "2023-08-01";

  try {
      var result = cashfree.PGFetchOrder(xApiVersion, "<order_id>>", null, null);
      Console.WriteLine(result);
      Console.WriteLine(result.StatusCode);
      Console.WriteLine((result.Content as OrderEntity));
  } catch (ApiException e) {
      Console.WriteLine("Exception when calling PGFetchOrder: " + e.Message);
      Console.WriteLine("Status Code: " + e.ErrorCode);
      Console.WriteLine(e.StackTrace);
  }
  ```

  ```php php theme={"dark"}
  $x_api_version = "2023-08-01";
  try {
      $response = $cashfree->PGFetchOrder($x_api_version, "<order_id>");
      print_r($response);
  } catch (Exception $e) {
      echo 'Exception when calling PGFetchOrder: ', $e->getMessage(), PHP_EOL;
  }
  ```
</CodeGroup>

<Note>
  Always verify the order status from your backend before you deliver goods or services to the customer. You can use the [Get Order API](/docs/api-reference/payments/latest/orders/get-order) for this. An order is successful when the `order_status` is `PAID`.
</Note>

## Testing

After you integrate a payment method, verify that it behaves as expected. Follow these steps to test:

1. Trigger a payment using each method you've integrated.
2. Confirm that the SDK opens the correct payment screen for the method (Cashfree's hosted card, net banking, or wallet screen, or the selected UPI app).
3. Confirm that `onPaymentVerify` or `onPaymentFailure` is called when the payment flow ends.

Use the [sandbox environment](/docs/payments/online/resources/sandbox-environment) to test payments before you go live.

## Error codes

To confirm the error returned in your Android application, you can view the error codes exposed by the SDK.

<Accordion title="Show error codes">
  The SDK validation errors are grouped by category as follows:

  ### Session errors

  | Error code | Message |
  | - | - |
  | `SESSION_OBJECT_MISSING` | The "session" is missing in the request. |
  | `PAYMENT_OBJECT_MISSING` | The "payment" is missing in the request. |
  | `ENVIRONMENT_MISSING` | The "environment" is missing in the request. |
  | `ORDER_ID_MISSING` | The "order\_id" is missing in the request. |

  ### Card errors

  | Error code | Message |
  | - | - |
  | `CARD_OBJECT_MISSING` | The CFCard object is missing in the request. |
  | `CARD_NUMBER_MISSING` | The "card\_number" is missing in the request. |
  | `CARD_EXPIRY_MONTH_MISSING` | The "card\_expiry\_mm" is missing in the request. |
  | `CARD_EXPIRY_YEAR_MISSING` | The "card\_expiry\_yy" is missing in the request. |
  | `CARD_CVV_MISSING` | The "card\_cvv" is missing in the request. |
  | `CHANNEL_MISSING` | The "channel" is missing in the request. |

  ### Net banking errors

  | Error code | Message |
  | - | - |
  | `NETBANKING_OBJECT_MISSING` | The CFNetbanking object is missing in the request. |
  | `NB_BANK_CODE_MISSING` | The "bank\_code" is missing in the request. |

  ### Wallet errors

  | Error code | Message |
  | - | - |
  | `WALLET_OBJECT_MISSING` | The CFWallet object is missing in the request. |
  | `WALLET_CHANNEL_MISSING` | The "channel" is missing in the wallet payment request. |
  | `WALLET_PHONE_MISSING` | The "phone number" is missing in the wallet payment request. |

  ### UPI errors

  | Error code | Message |
  | - | - |
  | `UPI_OBJECT_MISSING` | The CFUPI object is missing in the request. |
  | `UPI_ID_MISSING` | The "upi\_id" is missing in the request. |
  | `INVALID_UPI_APP_ID_SENT` | The id sent is invalid. The value has to be one of the following: "tez://", "phonepe://", "paytm://", "bhim://". See the note in the CFUPI class for more details. |
  | `NO_UPI_APP_AVAILABLE` | You don't have any UPI apps installed or ready for payment. |

  ### Callback and general errors

  | Error code | Message |
  | - | - |
  | `MISSING_CALLBACK` | The callback is missing in the request. |
  | `INVALID_PAYMENT_OBJECT_SENT` | The payment object that's set doesn't match any payment mode. Set the correct payment mode and try again. |
  | `WRONG_CALLING_CONTEXT` | Calling context must be activity or fragment. |
</Accordion>

### Other options

The following optional configurations let you customise SDK behaviour and enable logging for troubleshooting.

<AccordionGroup>
  <Accordion title="(Optional) Custom initialisation of the SDK">
    If you want to initialise the SDK yourself, follow these steps. Initialise the SDK in your Application class to avoid runtime issues.

    <Steps>
      <Step title="Add the following to your values.xml file">
        `<bool name="cashfree_pg_core_auto_initialize_enabled">false</bool>`
      </Step>

      <Step title="Initialise the SDK yourself before attempting payment">
        ```java theme={"dark"}
        Executors.newSingleThreadExecutor().execute(() -> {
            CFPaymentGatewayService.initialize(getApplicationContext());
        });
        ```
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="(Optional) Enable logging to debug issues">
    To enable SDK logging, add the following entry to your `values.xml` file:

    `<integer name="cashfree_pg_logging_level">3</integer>`

    The following logging levels are available, listed from least to most verbose:

    | Level | Value |
    | - | - |
    | VERBOSE | 2 |
    | DEBUG | 3 |
    | INFO | 4 |
    | WARN | 5 |
    | ERROR | 6 |
    | ASSERT | 7 |
  </Accordion>
</AccordionGroup>

<div>
  <p>Affiliate partner program</p>

  <p>As a developer building payment experiences for your clients, you can earn additional income while providing them with industry-leading payment solutions.</p>

  <p>Join the <a href="https://partner.cashfree.com/partner-ui/authentication/signup?source-action=Affiliate%20Program%20LP&action=Sign%20Up&button-id=StartNow_CashfreeAffiliatePartnerProgram">Cashfree affiliate partner program</a> and get rewarded every time your clients use Cashfree.</p>

  <p>**What you get:**</p>

  <ul>
    <li>Earn up to 0.25% commission on every transaction.</li>
    <li>Become a trusted fintech partner for your clients.</li>
    <li>Access to a dedicated partner manager for expert support.</li>
  </ul>

  <p>**What your clients get:**</p>

  <ul>
    <li>Instant activation and go live in minutes.</li>
    <li>Industry-best success rate across all payment modes.</li>
    <li>Effortless acceptance of international payments in 140+ currencies.</li>
  </ul>

  <p>Get started today. <a href="https://partner.cashfree.com/partner-ui/authentication/signup?source-action=Affiliate%20Program%20LP&action=Sign%20Up&button-id=StartNow_BecomeAPartner">Become a partner now</a>.</p>
</div>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/payments/latest/orders/create-order">Create Order API</a></li>
    <li><a href="/docs/api-reference/payments/latest/orders/get-order">Get Order API</a></li>
    <li><a href="/docs/payments/online/element/custom-card/android-custom-card">Android Custom Card Component</a></li>
    <li><a href="/docs/payments/online/element/overview">Element Overview</a></li>
    <li><a href="https://github.com/cashfree/nextgen-android">Android SDK on GitHub</a></li>
  </ul>
</div>


# React Native Element Integration
Source: https://www.cashfree.com/docs/payments/online/element/mobile/react-native

Integrate the Cashfree Payment Gateway Element SDK into your React Native app to accept payments via card, net banking, and UPI Intent.

The Cashfree Payment Gateway Element SDK lets you build a fully custom payment experience within your React Native application. Unlike the hosted checkout, you collect payment details directly in your own UI and pass them to the SDK, giving you complete control over the look and feel of your payment flow.

The SDK supports three Element payment methods: card (including saved card), net banking, and UPI Intent. It runs on both Android and iOS from a single integration.

<Note>
  This page describes the raw card flow, where your application collects the card number directly and is responsible for PCI DSS (Payment Card Industry Data Security Standard) compliance. To avoid handling raw card numbers, use the [React Native Custom Card Component](/docs/payments/online/element/custom-card/react-native-custom-card) instead, which captures the card number inside an SDK-managed input field.
</Note>

## Prerequisites

Complete the following tasks before you start the integration:

* Create a [Cashfree Merchant Account](https://merchant.cashfree.com/merchants/signup).
* Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and generate an **App ID** and **Secret Key**. Learn how to [generate API keys](/docs/api-reference/authentication#generate-api-keys).
* Use Cashfree React Native SDK version **2.4.0** or above. Get it from [npm](https://www.npmjs.com/package/react-native-cashfree-pg-sdk).
* Set your Android application's `minSdkVersion` to API level 19 or higher.
* Set your iOS minimum deployment target to 10.3 or higher.

The integration consists of three steps:

<CardGroup>
  <Card title="Step 1" icon="money-bill-wave" href="/docs/payments/online/element/mobile/react-native#step-1-create-an-order-server-side">
    Create an order
  </Card>

  <Card title="Step 2" icon="desktop" href="/docs/payments/online/element/mobile/react-native#step-2-open-the-payment-page-client-side">
    Open the payment page
  </Card>

  <Card title="Step 3" icon="circle-check" href="/docs/payments/online/element/mobile/react-native#step-3-confirm-the-payment-server-side">
    Confirm the payment
  </Card>
</CardGroup>

## Step 1: Create an order <Badge>Server-side</Badge>

Create an order from your backend server before you process any payment.

<Note>This API requires your secret key. Create orders through your server only. Do not call this API directly from your mobile application.</Note>

##### API request for creating an order

Here's a sample request for creating an order using your desired backend language. Cashfree offers backend [SDKs](/docs/api-reference/payments/sdk#server-sdk) to simplify the integration process.

<CodeGroup>
  ```bash curl theme={"dark"}
  curl --location 'https://sandbox.cashfree.com/pg/orders' \
  --header 'X-Client-Secret: {{clientKey}}' \
  --header 'X-Client-Id: {{clientId}}' \
  --header 'x-api-version: 2025-01-01' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data-raw '{
    "order_amount": 10.10,
    "order_currency": "INR",
    "customer_details": {
      "customer_id": "USER123",
      "customer_name": "joe",
      "customer_email": "joe.s@cashfree.com",
      "customer_phone": "+919876543210"
    },
    "order_meta": {
      "return_url": "https://b8af79f41056.eu.ngrok.io?order_id=order_123"
    }
  }'
  ```

  ```javascript nodejs theme={"dark"}
  import { Cashfree, CFEnvironment } from "cashfree-pg";

  const cashfree = new Cashfree(
  	CFEnvironment.PRODUCTION,
  	"{Client ID}",
  	"{Client Secret Key}"
  );

  function createOrder() {
  	var request = {
  		order_amount: "1",
  		order_currency: "INR",
  		customer_details: {
  			customer_id: "node_sdk_test",
  			customer_name: "",
  			customer_email: "example@gmail.com",
  			customer_phone: "9999999999",
  		},
  		order_meta: {
  			return_url:
  				"https://test.cashfree.com/pgappsdemos/return.php?order_id=order_123",
  		},
  		order_note: "",
  	};

  	cashfree
  		.PGCreateOrder(request)
  		.then((response) => {
  			console.log("Order created successfully:", response.data);
  		})
  		.catch((error) => {
  			console.error("Error setting up order request:", error.response.data);
  		});
  }
  ```

  ```python python theme={"dark"}
  from cashfree_pg.models.create_order_request import CreateOrderRequest
  from cashfree_pg.api_client import Cashfree
  from cashfree_pg.models.customer_details import CustomerDetails


  Cashfree.XClientId = {Client ID}
  Cashfree.XClientSecret = {Client Secret Key}
  Cashfree.XEnvironment = Cashfree.XSandbox
  x_api_version = "2023-08-01"

  def create_order():
          customerDetails = CustomerDetails(customer_id="123", customer_phone="9999999999")
          createOrderRequest = CreateOrderRequest(order_amount=1, order_currency="INR", customer_details=customerDetails)
          try:
              api_response = Cashfree().PGCreateOrder(x_api_version, createOrderRequest, None, None)
              print(api_response.data)
          except Exception as e:
              print(e)
  ```

  ```java java theme={"dark"}
  import com.cashfree.*;

  Cashfree.XClientId = {Client Key};
  Cashfree.XClientSecret = {Client Secret Key};
  Cashfree.XEnvironment = Cashfree.SANDBOX;

  static void createOrder() {
    CustomerDetails customerDetails = new CustomerDetails();
    customerDetails.setCustomerId("123");
    customerDetails.setCustomerPhone("9999999999");

    CreateOrderRequest request = new CreateOrderRequest();
    request.setOrderAmount(1.0);
    request.setOrderCurrency("INR");
    request.setCustomerDetails(customerDetails);
    try {
      Cashfree cashfree = new Cashfree();
      ApiResponse<OrderEntity> response = cashfree.PGCreateOrder("2023-08-01", request, null, null, null);
      System.out.println(response.getData().getOrderId());

    } catch (ApiException e) {
      throw new RuntimeException(e);
    }
  }
  ```

  ```go go theme={"dark"}
  import (
    cashfree "github.com/cashfree/cashfree-pg/v3"
  )

  func createOrder() {

  clientId := {Client ID}
  clientSecret := {Client Secret Key}
  cashfree.XClientId = &clientId
  cashfree.XClientSecret = &clientSecret
  cashfree.XEnvironment = cashfree.SANDBOX

  request := cashfree.CreateOrderRequest{
  		OrderAmount: 1,
  		CustomerDetails: cashfree.CustomerDetails{
  			CustomerId:    "1",
  			CustomerPhone: "9999999999",
  		},
  		OrderCurrency: "INR",
  		OrderSplits:   []cashfree.VendorSplit{},
  	}
  	version := "2023-08-01"
  	response, httpResponse, err := cashfree.PGCreateOrder(&version, &request, nil, nil, nil)
  	if err != nil {
  		fmt.Println(err.Error())
  	} else {
  		fmt.Println(httpResponse.StatusCode)
  		fmt.Println(response)
      }
  }
  ```

  ```csharp .net theme={"dark"}
  using cashfree_pg.Client;
  using cashfree_pg.Model;

  Cashfree.XClientId = {Client ID};
  Cashfree.XClientSecret = {Client Secret Key};
  Cashfree.XEnvironment = Cashfree.PRODUCTION;
  var cashfree = new Cashfree();
  var xApiVersion = "2023-08-01";

  void CreateOrder() {
      var customerDetails = new CustomerDetails("123", null, "9999999999");
      var createOrdersRequest = new CreateOrderRequest(null, 1.0, "INR", customerDetails);
      try {
          // Create Order
          var result = cashfree.PGCreateOrder(xApiVersion, createOrdersRequest, null, null, null);
          Console.WriteLine(result);
          Console.WriteLine(result.StatusCode);
          Console.WriteLine((result.Content as OrderEntity));
      } catch (ApiException e) {
          Console.WriteLine("Exception when calling PGCreateOrder: " + e.Message);
          Console.WriteLine("Status Code: " + e.ErrorCode);
          Console.WriteLine(e.StackTrace);
      }
  }
  ```

  ```php php theme={"dark"}
  \Cashfree\Cashfree::$XClientId = "<x-client-id>";
  \Cashfree\Cashfree::$XClientSecret = "<x-client-secret>";
  \Cashfree\Cashfree::$XEnvironment = Cashfree\Cashfree::$SANDBOX;

  $cashfree = new \Cashfree\Cashfree();

  $x_api_version = "2023-08-01";
  $create_orders_request = new \Cashfree\Model\CreateOrdersRequest();
  $create_orders_request->setOrderAmount(1.0);
  $create_orders_request->setOrderCurrency("INR");
  $customer_details = new \Cashfree\Model\CustomerDetails();
  $customer_details->setCustomerId("123");
  $customer_details->setCustomerPhone("9999999999");
  $create_orders_request->setCustomerDetails($customer_details);

  try {
      $result = $cashfree->PGCreateOrder($x_api_version, $create_orders_request);
      print_r($result);
  } catch (Exception $e) {
      echo 'Exception when calling PGCreateOrder: ', $e->getMessage(), PHP_EOL;
  }
  ```
</CodeGroup>

After successfully creating an order, you will receive a unique `order_id` and `payment_session_id` that you need for subsequent steps.

You can view the complete API request and response for `/orders` in the [Create Order API](/docs/api-reference/payments/latest/orders/create-order).

## Step 2: Open the payment page <Badge>Client-side</Badge>

After you create the order, open the payment page so the customer can provide payment details.

### 1. Set up the SDK

The React Native SDK is hosted on [npm](https://www.npmjs.com/). You can get the SDK [2.4.0](https://www.npmjs.com/package/react-native-cashfree-pg-sdk). The React Native SDK supports Android SDK version 19 and above and iOS minimum deployment target of 10.3 and above.

Install the SDK in your React Native project:

<CodeGroup>
  ```npm npm theme={"dark"}
  npm install react-native-cashfree-pg-sdk@2.4.0
  ```

  ```yarn yarn theme={"dark"}
  yarn add react-native-cashfree-pg-sdk@2.4.0
  ```

  ```expo expo theme={"dark"}
  npx expo install react-native-cashfree-pg-sdk
  npx expo install expo-dev-client
  npx expo prebuild
  npx expo run:android
  npx expo run:ios
  ```
</CodeGroup>

#### iOS configuration

To provide UPI payments on iOS, add the following to your application's `info.plist` file:

```xml theme={"dark"}
<key>LSApplicationQueriesSchemes</key>
<array>
  <string>amazonpay</string>
  <string>upi</string>
  <string>credpay</string>
  <string>bhim</string>
  <string>paytmmp</string>
  <string>phonepe</string>
  <string>tez</string>
  <string>navipay</string>
  <string>mobikwik</string>
  <string>myairtel</string>
  <string>popclubapp</string>
  <string>super</string>
  <string>kiwi</string>
  <string>simplypayupi</string>
  <string>whatsapp</string>
</array>
```

For iOS, run the following commands:

```bash theme={"dark"}
cd ios
pod install --repo-update
```

### 2. Select a payment method

The Element SDK supports the following payment methods:

<Tabs>
  <Tab title="Card">
    In this flow, the customer enters their card details directly in your application UI. Your application receives the raw card number and passes it to the SDK, so your application remains in PCI DSS scope for card data. To avoid handling raw card numbers, use the [React Native Custom Card Component](/docs/payments/online/element/custom-card/react-native-custom-card) instead. You can also charge a previously saved card by passing the saved card instrument ID and CVV.
  </Tab>

  <Tab title="Net banking">
    In this flow, you identify the customer's bank using a bank code. The SDK opens Cashfree's hosted net banking screen so the customer can log in and authorise the payment.
  </Tab>

  <Tab title="UPI Intent">
    In this flow, the SDK discovers the UPI apps installed on the customer's device and launches the selected app so the customer can authorise the payment.
  </Tab>
</Tabs>

### 3. Complete the payment

To complete the payment, follow these steps:

1. Set up the payment callback.
2. Create a `CFSession` object.
3. Create the payment object for the selected payment method.
4. Initiate the payment using `makePayment()`.

#### Set up the payment callback

The SDK exposes a `CFCallback` interface to receive callbacks from the SDK once the payment flow ends. The callback supports two methods:

```typescript theme={"dark"}
onVerify(orderID: string): void
onError(error: CFErrorResponse, orderID: string): void
```

<Tip>
  Set the callback in `componentDidMount` and remove it in `componentWillUnmount`. This configuration also handles activity restart cases and prevents memory leaks.
</Tip>

<Tip>Always call `setCallback` before calling `makePayment`.</Tip>

```typescript theme={"dark"}
import { Component } from 'react';
import {
  CFErrorResponse,
  CFPaymentGatewayService,
} from 'react-native-cashfree-pg-sdk';

export default class App extends Component {
  componentDidMount() {
    CFPaymentGatewayService.setCallback({
      onVerify(orderID: string): void {
        // Verify the order status from your backend.
      },
      onError(error: CFErrorResponse, orderID: string): void {
        console.log(JSON.stringify(error), orderID);
      },
    });
  }

  componentWillUnmount() {
    CFPaymentGatewayService.removeCallback();
  }
}
```

#### Create a session

The `CFSession` object holds the session context for the payment. It accepts the `payment_session_id` and `order_id` obtained from [Step 1](#step-1-create-an-order-server-side), and the Cashfree environment (`CFEnvironment.SANDBOX` or `CFEnvironment.PRODUCTION`).

```typescript theme={"dark"}
import {
  CFEnvironment,
  CFSession,
} from 'cashfree-pg-api-contract';

try {
  const session = new CFSession(
    '<PAYMENT_SESSION_ID>',
    '<ORDER_ID>',
    CFEnvironment.SANDBOX // or CFEnvironment.PRODUCTION
  );
} catch (e: any) {
  console.log(e.message);
}
```

#### Create a payment object

The SDK provides a dedicated payment class for each supported payment method. Build only the object that corresponds to the payment method your customer has selected.

Card objects can be of two types: `Card` for a new card payment, and `SavedCard` for a previously saved instrument.

| Object | Fields |
| - | - |
| `Card` | `cardNumber`, `cardHolderName`, `cardExpiryMM`, `cardExpiryYY`, `cardCvv`, `saveCard` |
| `SavedCard` | `instrumentId`, `cardCvv` |

<Tabs>
  <Tab title="Card">
    Use the following code to create a card payment object. This is the raw card flow. Your application passes the full card number to the SDK.

    ```typescript theme={"dark"}
    import {
      Card,
      CFCardPayment,
      CFEnvironment,
      CFSession,
    } from 'cashfree-pg-api-contract';
    import { CFPaymentGatewayService } from 'react-native-cashfree-pg-sdk';

    async _startCardPayment() {
      try {
        const session = new CFSession(
          '<PAYMENT_SESSION_ID>',
          '<ORDER_ID>',
          CFEnvironment.SANDBOX
        );

        const card = new Card(
          '<CARD_NUMBER>',
          '<CARD_HOLDER_NAME>',
          '<CARD_EXPIRY_MM>',
          '<CARD_EXPIRY_YY>',
          '<CARD_CVV>',
          false // set true to save the card for future payments
        );

        const cardPayment = new CFCardPayment(session, card);
        CFPaymentGatewayService.makePayment(cardPayment);
      } catch (e: any) {
        console.log(e.message);
      }
    }
    ```
  </Tab>

  <Tab title="Saved card">
    Use `SavedCard` when the customer pays with a previously saved card instrument. Pass the saved card `instrumentId` and the card CVV.

    ```typescript theme={"dark"}
    import {
      CFCardPayment,
      CFEnvironment,
      CFSession,
      SavedCard,
    } from 'cashfree-pg-api-contract';
    import { CFPaymentGatewayService } from 'react-native-cashfree-pg-sdk';

    async _startSavedCardPayment() {
      try {
        const session = new CFSession(
          '<PAYMENT_SESSION_ID>',
          '<ORDER_ID>',
          CFEnvironment.SANDBOX
        );

        const card = new SavedCard(
          '<INSTRUMENT_ID>',
          '<CARD_CVV>'
        );

        const cardPayment = new CFCardPayment(session, card);
        CFPaymentGatewayService.makePayment(cardPayment);
      } catch (e: any) {
        console.log(e.message);
      }
    }
    ```
  </Tab>

  <Tab title="Net banking">
    The `CFNB` constructor accepts the bank code of the customer's bank.

    ```typescript theme={"dark"}
    import {
      CFEnvironment,
      CFNB,
      CFNBPayment,
      CFSession,
    } from 'cashfree-pg-api-contract';
    import { CFPaymentGatewayService } from 'react-native-cashfree-pg-sdk';

    async _makeNBPayment() {
      try {
        const session = new CFSession(
          '<PAYMENT_SESSION_ID>',
          '<ORDER_ID>',
          CFEnvironment.SANDBOX
        );

        const nb = new CFNB('<BANK_CODE>');
        CFPaymentGatewayService.makePayment(
          new CFNBPayment(session, nb)
        );
      } catch (e: any) {
        console.log(e.message);
      }
    }
    ```
  </Tab>

  <Tab title="UPI Intent">
    Use `getInstalledUpiApps()` to discover the UPI apps installed on the customer's device, then build a `CFUPI` object using the selected app identifier. On Android, pass the app package name. On iOS, pass the UPI app URI scheme (for example, `tez://`).

    ```typescript theme={"dark"}
    import {
      CFEnvironment,
      CFSession,
      CFUPI,
      CFUPIPayment,
      UPIMode,
    } from 'cashfree-pg-api-contract';
    import { CFPaymentGatewayService } from 'react-native-cashfree-pg-sdk';

    async _makeUpiIntentPayment() {
      try {
        const apps = await CFPaymentGatewayService.getInstalledUpiApps();
        let appId = '';
        JSON.parse(apps as string).forEach((item: any) => {
          appId = item.appPackage;
        });

        const session = new CFSession(
          '<PAYMENT_SESSION_ID>',
          '<ORDER_ID>',
          CFEnvironment.SANDBOX
        );

        const upi = new CFUPI(UPIMode.INTENT, appId);
        CFPaymentGatewayService.makePayment(
          new CFUPIPayment(session, upi)
        );
      } catch (e: any) {
        console.log(e.message);
      }
    }
    ```
  </Tab>
</Tabs>

#### Initiate the payment

Call `makePayment()` to open the Cashfree payment flow for the selected method. Pass the payment object you created in the previous step (`CFCardPayment`, `CFNBPayment`, or `CFUPIPayment`).

```typescript theme={"dark"}
CFPaymentGatewayService.makePayment(cardPayment);
// or: CFPaymentGatewayService.makePayment(nbPayment);
// or: CFPaymentGatewayService.makePayment(upiPayment);
```

<Note>
  `doCardPayment()` is deprecated. Use `makePayment()` for card, net banking, and UPI Element payments.
</Note>

#### Sample code

The following example shows a complete integration, including session creation, payment object setup for each method, and payment initiation.

<AccordionGroup>
  <Accordion title="Element checkout sample">
    ```typescript theme={"dark"}
    import { Component } from 'react';
    import {
      CFErrorResponse,
      CFPaymentGatewayService,
    } from 'react-native-cashfree-pg-sdk';
    import {
      Card,
      CFCardPayment,
      CFEnvironment,
      CFNB,
      CFNBPayment,
      CFSession,
      CFUPI,
      CFUPIPayment,
      SavedCard,
      UPIMode,
    } from 'cashfree-pg-api-contract';

    export default class App extends Component {
      componentDidMount() {
        CFPaymentGatewayService.setCallback({
          onVerify(orderID: string): void {
            // Verify the order status from your backend.
            console.log('orderId is :' + orderID);
          },
          onError(error: CFErrorResponse, orderID: string): void {
            console.log(
              'exception is : ' + JSON.stringify(error) + '\norderId is :' + orderID
            );
          },
        });
      }

      componentWillUnmount() {
        CFPaymentGatewayService.removeCallback();
      }

      getSession(): CFSession {
        return new CFSession(
          '<PAYMENT_SESSION_ID>',
          '<ORDER_ID>',
          CFEnvironment.SANDBOX
        );
      }

      async _startCardPayment() {
        try {
          const card = new Card(
            '<CARD_NUMBER>',
            '<CARD_HOLDER_NAME>',
            '<CARD_EXPIRY_MM>',
            '<CARD_EXPIRY_YY>',
            '<CARD_CVV>',
            false
          );
          CFPaymentGatewayService.makePayment(
            new CFCardPayment(this.getSession(), card)
          );
        } catch (e: any) {
          console.log(e.message);
        }
      }

      async _startSavedCardPayment() {
        try {
          const card = new SavedCard('<INSTRUMENT_ID>', '<CARD_CVV>');
          CFPaymentGatewayService.makePayment(
            new CFCardPayment(this.getSession(), card)
          );
        } catch (e: any) {
          console.log(e.message);
        }
      }

      async _makeNBPayment() {
        try {
          const nb = new CFNB('<BANK_CODE>');
          CFPaymentGatewayService.makePayment(
            new CFNBPayment(this.getSession(), nb)
          );
        } catch (e: any) {
          console.log(e.message);
        }
      }

      async _makeUpiIntentPayment() {
        try {
          const apps = await CFPaymentGatewayService.getInstalledUpiApps();
          let appId = '';
          JSON.parse(apps as string).forEach((item: any) => {
            appId = item.appPackage;
          });

          const upi = new CFUPI(UPIMode.INTENT, appId);
          CFPaymentGatewayService.makePayment(
            new CFUPIPayment(this.getSession(), upi)
          );
        } catch (e: any) {
          console.log(e.message);
        }
      }
    }
    ```
  </Accordion>
</AccordionGroup>

#### Sample GitHub code

You can explore a working integration example on GitHub:

[GitHub sample](https://github.com/cashfree/react-native-cashfree-pg-sdk/blob/d162bf61751e66eb848f3c612ce825d25c8a9941/example/App.tsx#L166)

[Sample UPI Test APK](/docs/payments/online/mobile/misc/cashfree_upi_simulator_apk)

## Step 3: Confirm the payment <Badge>Server-side</Badge>

After the SDK delivers a callback via `onVerify`, confirm the payment status from your backend before taking any action. The SDK callback signals only that the payment flow has ended. It does not guarantee a successful payment.

To verify an order you can call our `/pg/orders` endpoint from your backend. You can also use our SDK to achieve the same.

<CodeGroup>
  ```bash curl theme={"dark"}
  curl --request GET \
       --url https://sandbox.cashfree.com/pg/orders/{order_id} \
       --header 'accept: application/json' \
       --header 'x-api-version: 2025-01-01' \
       --header 'x-client-id: "YOUR APP ID GOES HERE"' \
       --header 'x-client-secret: "YOUR SECRET KEY GOES HERE"'
  ```

  ```javascript nodejs theme={"dark"}
  cashfree
  .PGFetchOrder("<order_id>")
  .then((response) => {
  	console.log("Order fetched successfully:", response.data);
  })
  .catch((error) => {
  	console.error("Error:", error.response.data.message);
  });
  ```

  ```python python theme={"dark"}
  from cashfree_pg.models.create_order_request import CreateOrderRequest
  from cashfree_pg.api_client import Cashfree
  from cashfree_pg.models.customer_details import CustomerDetails
  from cashfree_pg.models.order_meta import OrderMeta

  Cashfree.XClientId = "<x-client-id>"
  Cashfree.XClientSecret = "<x-client-secret>"
  Cashfree.XEnvironment = Cashfree.SANDBOX
  x_api_version = "2023-08-01"

  try:
      api_response = Cashfree().PGFetchOrder(x_api_version, "order_3242X4jQ5f0S9KYxZO9mtDL1Kx2Y7u", None)
      print(api_response.data)
  except Exception as e:
      print(e)

  ```

  ```java java theme={"dark"}
  import com.cashfree.*;
  //other code

  try {
      Cashfree.XClientId = "<x-client-id>";
      Cashfree.XClientSecret = "<x-client-secret>";
      Cashfree.XEnvironment = Cashfree.SANDBOX;

      Cashfree cashfree = new Cashfree();
      String xApiVersion = "2023-08-01";

      ApiResponse<OrderEntity> responseFetchOrder = cashfree.PGFetchOrder(xApiVersion, "<order_id>", null, null, null);
      System.out.println(response.getData().getOrderId());
  } catch (ApiException e) {
      throw new RuntimeException(e);
  }
  ```

  ```go go theme={"dark"}
  version := "2023-08-01"
  response, httpResponse, err := cashfree.PGFetchOrder(&version, "<order_id>", nil, nil, nil)
  if err != nil {
  	fmt.Println(err.Error())
  } else {
  	fmt.Println(httpResponse.StatusCode)
  	fmt.Println(response)
  }
  ```

  ```csharp .net theme={"dark"}
  using cashfree_pg.Client;
  using cashfree_pg.Model;

  Cashfree.XClientId = "<x-client-id>";
  Cashfree.XClientSecret = "<x-client-secret>";
  Cashfree.XEnvironment = Cashfree.SANDBOX;
  var cashfree = new Cashfree();
  var xApiVersion = "2023-08-01";

  try {
      var result = cashfree.PGFetchOrder(xApiVersion, "<order_id>>", null, null);
      Console.WriteLine(result);
      Console.WriteLine(result.StatusCode);
      Console.WriteLine((result.Content as OrderEntity));
  } catch (ApiException e) {
      Console.WriteLine("Exception when calling PGFetchOrder: " + e.Message);
      Console.WriteLine("Status Code: " + e.ErrorCode);
      Console.WriteLine(e.StackTrace);
  }
  ```

  ```php php theme={"dark"}
  $x_api_version = "2023-08-01";
  try {
      $response = $cashfree->PGFetchOrder($x_api_version, "<order_id>");
      print_r($response);
  } catch (Exception $e) {
      echo 'Exception when calling PGFetchOrder: ', $e->getMessage(), PHP_EOL;
  }
  ```
</CodeGroup>

<Note>
  Always verify the order status from your backend before you deliver goods or services to the customer. You can use the [Get Order API](/docs/api-reference/payments/latest/orders/get-order) for this. An order is successful when the `order_status` is `PAID`.
</Note>

## Testing

After you integrate a payment method, verify that it behaves as expected. Follow these steps to test:

1. Trigger a payment using each method you have integrated.
2. Confirm that the SDK opens the correct payment screen for the method (Cashfree's hosted card or net banking screen, or the selected UPI app).
3. Confirm that `onVerify` or `onError` is called when the payment flow ends.

Use the [sandbox environment](/docs/payments/online/resources/sandbox-environment) to test payments before you go live.

## Error codes

To confirm the error returned in your React Native application, you can view the error codes exposed by the SDK.

<Accordion title="Show error codes">
  The following are some of the error codes that are exposed by the SDK:

  | Error code | Message |
  | - | - |
  | `MISSING_CALLBACK` | The callback is missing in the request. |
  | `ORDER_ID_MISSING` | The "order\_id" is missing in the request. |
  | `SESSION_OBJECT_MISSING` | The "session" is missing in the request. |
  | `PAYMENT_OBJECT_MISSING` | The "payment" is missing in the request. |
  | `ENVIRONMENT_MISSING` | The "environment" is missing in the request. |
  | `ORDER_TOKEN_MISSING` | The "order\_token" is missing in the request. |
</Accordion>

<div>
  <p>Affiliate partner program</p>

  <p>As a developer building payment experiences for your clients, you can earn additional income while providing them with industry-leading payment solutions.</p>

  <p>Join the <a href="https://partner.cashfree.com/partner-ui/authentication/signup?source-action=Affiliate%20Program%20LP&action=Sign%20Up&button-id=StartNow_CashfreeAffiliatePartnerProgram">Cashfree affiliate partner program</a> and get rewarded every time your clients use Cashfree.</p>

  <p>**What you get:**</p>

  <ul>
    <li>Earn up to 0.25% commission on every transaction.</li>
    <li>Become a trusted fintech partner for your clients.</li>
    <li>Access to a dedicated partner manager for expert support.</li>
  </ul>

  <p>**What your clients get:**</p>

  <ul>
    <li>Instant activation and go live in minutes.</li>
    <li>Industry-best success rate across all payment modes.</li>
    <li>Effortless acceptance of international payments in 140+ currencies.</li>
  </ul>

  <p>Get started today. <a href="https://partner.cashfree.com/partner-ui/authentication/signup?source-action=Affiliate%20Program%20LP&action=Sign%20Up&button-id=StartNow_BecomeAPartner">Become a partner now</a>.</p>
</div>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/payments/latest/orders/create-order">Create Order API</a></li>
    <li><a href="/docs/api-reference/payments/latest/orders/get-order">Get Order API</a></li>
    <li><a href="/docs/payments/online/element/custom-card/react-native-custom-card">React Native Custom Card Component</a></li>
    <li><a href="/docs/payments/online/element/overview">Element Overview</a></li>
    <li><a href="https://github.com/cashfree/react-native-cashfree-pg-sdk">React Native SDK on GitHub</a></li>
  </ul>
</div>


# Wallets, Net Banking and BNPL Components
Source: https://www.cashfree.com/docs/payments/online/element/other-components

Add Cashfree.js components for wallets, netbanking, BNPL, and UPI QR codes to your custom checkout to support diverse payment methods on a single page.

## wallet

A component to show a UPI qr code

<ResponseField name="wallet" type="Wallet Object">
  <Expandable title="properties">
    <ParamField type="string">
      name of the wallet. ex `phonepe`. See [all wallet names in the appendix](/docs/payments/online/element/appendix#wallet-providers).
    </ParamField>

    <ParamField type="string">
      name of the wallet. ex `phonepe`.
    </ParamField>

    <ParamField type="boolean">
      Decide whether to show app icon or not
    </ParamField>

    <ParamField type="string">
      10 digit phone number of your customer
    </ParamField>
  </Expandable>
</ResponseField>

<h4>Returned Value</h4>
You can get the value of a component by calling `component.data().value`. All returned
values of `component.data()` can be found in the [components reference](/docs/payments/online/element/components).

<ResponseField name="wallet" type="Wallet Object">
  <Expandable title="properties">
    <ResponseField name="provider" type="string">
      name of the wallet. ex `PhonePe`
    </ResponseField>

    <ResponseField name="phone" type="string">
      10 digit phone number of your customer
    </ResponseField>
  </Expandable>
</ResponseField>

<Accordion title="Code snippet for wallet component">
  ```javascript theme={"dark"}
  let cashfree = Cashfree({
    mode:"sandbox" //or production
  });
  let wallet = cashfree.create('wallet', {
  	values:{
  		provider: 'phonepe',
  		phone: '94140905',
  		buttonText: 'PhonePe',
  		buttonIcon: true
  	}
  });
  wallet.on('loaderror', function(data){
  	console.log(data.error)
  })
  wallet.mount("#mount-here");
  wallet.on('ready', function(d){
      console.log(wallet.data().value); //{provide: 'phonepe', phone: '94140905'}
      //or
      //console.log(d.value) 
  })
   
  ```
</Accordion>

## netbanking

A component to initiate Net Banking payment.

<Note>
  In case `buttonText` is not provided the value of `buttonIcon` would be
  replaced to `true`. This has been done so that your customer always sees icon
  of the app.
</Note>

<ResponseField name="netbanking" type="Wallet Object">
  <Expandable title="properties">
    <ParamField type="string">
      name of the bank. ex HDFC. See [all bank names in the appendix](/docs/payments/online/element/appendix#netbanking-code-and-names).
    </ParamField>

    <ParamField type="string">
      Text for button. ex `HDFC Bank`.
    </ParamField>

    <ParamField type="boolean">
      Decide whether to show app icon or not
    </ParamField>
  </Expandable>
</ResponseField>

<h4>Returned Value</h4>
You can get the value of a component by calling `component.data().value`. All returned
values of `component.data()` can be found in the [components reference](/docs/payments/online/element/components)

<ResponseField name="netbanking" type="Netbanking Object">
  <Expandable title="properties">
    <ResponseField name="netbankingBankName" type="string">
      name of the bank
    </ResponseField>
  </Expandable>
</ResponseField>

<Accordion title="Code snippet for wallet component">
  ```javascript theme={"dark"}
  let cashfree = Cashfree({
    mode:"sandbox" //or production
  });
  let netbanking = cashfree.create('netbanking', {
  	values:{
  		netbankingBankName: 'HDFCR',
  		buttonText: 'HDFC Bank',
  		buttonIcon: true
  	}
  });
  netbanking.on('loaderror', function(data){
  	console.log(data.error)
  })
  netbanking.mount("#mount-here");
  netbanking.on('ready', function(d){
      console.log(netbanking.data().value); //{netbankingBankName: 'HDFCR'}
      //or
      //console.log(d.value) 
  })
  ```
</Accordion>

## paylater

A component to initiate paylater payment.

<ResponseField name="paylater" type="Paylater Object">
  <Expandable title="properties">
    <ParamField type="string">
      name of the wallet. ex simpl. See [all pay later provider names in the appendix](/docs/payments/online/element/appendix#paylater-providers).
    </ParamField>

    <ParamField type="string">
      Text for button, ex `Simpl`.
    </ParamField>

    <ParamField type="boolean">
      Decide whether to show app icon or not
    </ParamField>

    <ParamField type="string">
      10 digit phone number of your customer
    </ParamField>
  </Expandable>
</ResponseField>

<h4>Returned Value</h4>
You can get the value of a component by calling `component.data().value`. All returned
values of `component.data()` can be found in the [components reference](/docs/payments/online/element/components)

<ResponseField name="paylater" type="Paylater Object">
  <Expandable title="properties">
    <ResponseField name="provider" type="string">
      name of the wallet
    </ResponseField>

    <ResponseField name="phone" type="string">
      10 digit phone number
    </ResponseField>
  </Expandable>
</ResponseField>

<Accordion title="Code snippet for paylater component">
  ```javascript theme={"dark"}
  let cashfree = Cashfree({
    mode:"sandbox" //or production
  });
  let p = cashfree.create('paylater', {
  	values:{
  		provider: 'simpl',
  		phone: '94140905',
  		buttonText: 'Use Simpl',
  		buttonIcon: true
  	}
  });
  p.on('loaderror', function(data){
  	console.log(data.error)
  })
  p.mount("#mount-here");
  p.on('ready', function(d){
      console.log(d.value) 
  })
  ```
</Accordion>

## cardlessEMI

A component to initiate Cardless EMI payment.

<ResponseField name="cardlessemi" type="Cardless EMI Object">
  <Expandable title="properties">
    <ParamField type="string">
      name of the wallet. Example- flexmoney. See [all cardless EMI provider names in the appendix](/docs/payments/online/element/appendix#cardless-emi-providers)
    </ParamField>

    <ParamField type="string">
      Text for button, ex `Flexmoney`
    </ParamField>

    <ParamField type="boolean">
      Decide whether to show app icon or not
    </ParamField>

    <ParamField type="string">
      10 digit phone number of your customer
    </ParamField>
  </Expandable>
</ResponseField>

<h4>Returned Value</h4>
You can get the value of a component by calling `component.data().value`. All returned
values of `component.data()` can be found in the [components reference](/docs/payments/online/element/components)

<ResponseField name="cardlessemi" type="Cardless EMI Object">
  <Expandable title="properties">
    <ResponseField name="provider" type="string">
      name of the provider
    </ResponseField>

    <ResponseField name="phone" type="string">
      10 digit phone number
    </ResponseField>
  </Expandable>
</ResponseField>

<Accordion title="Code snippet for paylater component">
  ```javascript theme={"dark"}
  let cashfree = Cashfree({
    mode:"sandbox" //or production
  });
  let cl = cashfree.create('cardlessEMI', {
  	values:{
  		provider: 'flexmoney',
  		phone: '94140905',
  		buttonText: 'Flexmoney',
  		buttonIcon: true
  	}
  });
  cl.on('loaderror', function(data){
  	console.log(data.error)
  })
  cl.mount("#mount-here");
  cl.on('ready', function(d){
      console.log(d.value) 
  })
  ```
</Accordion>

## savePaymentInstrument

A component that can be used in `.pay()` to save a payment method for a customer. This works for only cards. This will tokenise your card

<ResponseField name="savePaymentInstrument" type="Save Payment Instrument Object">
  <Expandable title="properties">
    <ParamField type="string">
      Label for the checkbox
    </ParamField>
  </Expandable>
</ResponseField>

<h4>Returned Value</h4>
You can get the value of a component by calling `component.data().value`. All returned
values of `component.data()` can be found in the [components reference](/docs/payments/online/element/components)

<ResponseField name="savePaymentInstrument" type="Save Payment Instrument Object">
  <Expandable title="properties">
    <ResponseField name="saveInstrument" type="string">
      does the user wants to save
    </ResponseField>
  </Expandable>
</ResponseField>

<Accordion title="Code snippet for savePaymentInstrument component">
  ```javascript theme={"dark"}
  let saveOptions = {
  	values: {
  		label: "Save Card for later"
  	}
  };
  let savecard = cashfree.create("savePaymentInstrument", saveOptions);
  savecard.mount("#div-id");

  let cashfree = Cashfree();
  .....
  cashfree.pay({
  ...
  savePaymentInstrument: savecard
  })
  ```
</Accordion>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/payments/online/element/components">Element Components</a></li>
    <li><a href="/docs/payments/online/element/sdks">SDK Libraries</a></li>
    <li><a href="/docs/payments/online/element/cards">Card Components</a></li>
    <li><a href="/docs/payments/online/element/upi">UPI Components</a></li>
    <li><a href="/docs/payments/online/element/appendix">Payment Provider Codes</a></li>
  </ul>
</div>


# Overview
Source: https://www.cashfree.com/docs/payments/online/element/overview

Build customised payment experiences with pre-built, secure payment components that integrate seamlessly into your web application.

Cashfree custom web checkout lets you embed payment UI elements in your application and keep customers on your site throughout checkout. Cashfree captures and transmits sensitive payment data, which helps you reduce your PCI DSS (Payment Card Industry Data Security Standard) compliance scope.

## Key features

Custom web checkout provides the following capabilities:

* **Complete design control**: Design payment forms that match your brand identity with full control over styling, layout, and user experience.

* **PCI DSS compliant**: Payment data is securely captured and transmitted directly to Cashfree servers, reducing your PCI compliance scope.

* **Flexible integration**: Build custom payment flows with individual components or use the hosted checkout option based on your requirements.

* **Multiple payment methods**: Accept payments through cards (credit and debit), UPI (collect, intent, and QR), net banking, wallets, and Buy Now Pay Later options.

* **Enhanced user experience**: Keep customers on your website throughout the payment journey without redirecting to external pages.

* **Framework support**: Native libraries available for JavaScript, React, and Svelte for seamless integration.

## Prerequisites

Ensure you complete the following tasks before starting the integration:

* Create a [Cashfree Merchant Account](https://merchant.cashfree.com/merchants/signup).
* Log in to the [Merchant Dashboard](https://merchant.cashfree.com/merchants/pg/developers/api-keys) and generate an **App ID** and **Secret Key**. Learn how to [generate API keys](/docs/api-reference/authentication#generate-api-keys).
* Whitelist your website domain for integration. Learn more about [domain whitelisting](/docs/payments/online/go-live/whitelist).

## Integration steps

Follow these four steps to integrate custom web checkout:

<div>
  <a href="https://www.cashfree.com/devstudio/preview/pg/web/card">
    <span>
      Try it in DevStudio

      <svg>
        <path />

        <path />
      </svg>
    </span>
  </a>
</div>

<Accordion title="Step 1: Create an order" icon="money-bill-wave">
  <Badge>Server-side</Badge>

  To integrate the custom web checkout, you must first create an order. Complete this step before you process any payments. Configure an endpoint on your server to handle order creation. You can't call this API from the client-side.

  <Note>Create orders through your server as this API requires your secret key. Don't call it directly from the client-side.</Note>

  Here's a sample request for creating an order using your desired backend language. Cashfree offers backend [SDKs](/docs/api-reference/payments/sdk#server-sdk) to simplify the integration process.

  <CodeGroup>
    ```bash curl theme={"dark"}
    curl --location 'https://sandbox.cashfree.com/pg/orders' \
    --header 'X-Client-Secret: {{clientKey}}' \
    --header 'X-Client-Id: {{clientId}}' \
    --header 'x-api-version: 2025-01-01' \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json' \
    --data-raw '{
      "order_amount": 10.10,
      "order_currency": "INR",
      "customer_details": {
        "customer_id": "USER123",
        "customer_name": "joe",
        "customer_email": "joe.s@cashfree.com",
        "customer_phone": "+919876543210"
      },
      "order_meta": {
        "return_url": "https://b8af79f41056.eu.ngrok.io?order_id=order_123"
      }
    }'
    ```

    ```javascript nodejs theme={"dark"}
    import { Cashfree, CFEnvironment } from "cashfree-pg";

    const cashfree = new Cashfree(
    	CFEnvironment.PRODUCTION,
    	"{Client ID}",
    	"{Client Secret Key}"
    );

    function createOrder() {
    	var request = {
    		order_amount: "1",
    		order_currency: "INR",
    		customer_details: {
    			customer_id: "node_sdk_test",
    			customer_name: "",
    			customer_email: "example@gmail.com",
    			customer_phone: "9999999999",
    		},
    		order_meta: {
    			return_url:
    				"https://test.cashfree.com/pgappsdemos/return.php?order_id=order_123",
    		},
    		order_note: "",
    	};

    	cashfree
    		.PGCreateOrder(request)
    		.then((response) => {
    			console.log("Order created successfully:", response.data);
    		})
    		.catch((error) => {
    			console.error("Error setting up order request:", error.response.data);
    		});
    }
    ```

    ```python python theme={"dark"}
    from cashfree_pg.models.create_order_request import CreateOrderRequest
    from cashfree_pg.api_client import Cashfree
    from cashfree_pg.models.customer_details import CustomerDetails


    Cashfree.XClientId = {Client ID}
    Cashfree.XClientSecret = {Client Secret Key}
    Cashfree.XEnvironment = Cashfree.XSandbox
    x_api_version = "2023-08-01"

    def create_order():
            customerDetails = CustomerDetails(customer_id="123", customer_phone="9999999999")
            createOrderRequest = CreateOrderRequest(order_amount=1, order_currency="INR", customer_details=customerDetails)
            try:
                api_response = Cashfree().PGCreateOrder(x_api_version, createOrderRequest, None, None)
                print(api_response.data)
            except Exception as e:
                print(e)
    ```

    ```java java theme={"dark"}
    import com.cashfree.*;

    Cashfree.XClientId = {Client Key};
    Cashfree.XClientSecret = {Client Secret Key};
    Cashfree.XEnvironment = Cashfree.SANDBOX;

    static void createOrder() {
      CustomerDetails customerDetails = new CustomerDetails();
      customerDetails.setCustomerId("123");
      customerDetails.setCustomerPhone("9999999999");

      CreateOrderRequest request = new CreateOrderRequest();
      request.setOrderAmount(1.0);
      request.setOrderCurrency("INR");
      request.setCustomerDetails(customerDetails);
      try {
        Cashfree cashfree = new Cashfree();
        ApiResponse<OrderEntity> response = cashfree.PGCreateOrder("2023-08-01", request, null, null, null);
        System.out.println(response.getData().getOrderId());

      } catch (ApiException e) {
        throw new RuntimeException(e);
      }
    }
    ```

    ```go go theme={"dark"}
    import (
      cashfree "github.com/cashfree/cashfree-pg/v3"
    )

    func createOrder() {

    clientId := {Client ID}
    clientSecret := {Client Secret Key}
    cashfree.XClientId = &clientId
    cashfree.XClientSecret = &clientSecret
    cashfree.XEnvironment = cashfree.SANDBOX

    request := cashfree.CreateOrderRequest{
    		OrderAmount: 1,
    		CustomerDetails: cashfree.CustomerDetails{
    			CustomerId:    "1",
    			CustomerPhone: "9999999999",
    		},
    		OrderCurrency: "INR",
    		OrderSplits:   []cashfree.VendorSplit{},
    	}
    	version := "2023-08-01"
    	response, httpResponse, err := cashfree.PGCreateOrder(&version, &request, nil, nil, nil)
    	if err != nil {
    		fmt.Println(err.Error())
    	} else {
    		fmt.Println(httpResponse.StatusCode)
    		fmt.Println(response)
        }
    }
    ```

    ```csharp .net theme={"dark"}
    using cashfree_pg.Client;
    using cashfree_pg.Model;

    Cashfree.XClientId = {Client ID};
    Cashfree.XClientSecret = {Client Secret Key};
    Cashfree.XEnvironment = Cashfree.PRODUCTION;
    var cashfree = new Cashfree();
    var xApiVersion = "2023-08-01";

    void CreateOrder() {
        var customerDetails = new CustomerDetails("123", null, "9999999999");
        var createOrdersRequest = new CreateOrderRequest(null, 1.0, "INR", customerDetails);
        try {
            // Create Order
            var result = cashfree.PGCreateOrder(xApiVersion, createOrdersRequest, null, null, null);
            Console.WriteLine(result);
            Console.WriteLine(result.StatusCode);
            Console.WriteLine((result.Content as OrderEntity));
        } catch (ApiException e) {
            Console.WriteLine("Exception when calling PGCreateOrder: " + e.Message);
            Console.WriteLine("Status Code: " + e.ErrorCode);
            Console.WriteLine(e.StackTrace);
        }
    }
    ```

    ```php php theme={"dark"}
    \Cashfree\Cashfree::$XClientId = "<x-client-id>";
    \Cashfree\Cashfree::$XClientSecret = "<x-client-secret>";
    \Cashfree\Cashfree::$XEnvironment = Cashfree\Cashfree::$SANDBOX;

    $cashfree = new \Cashfree\Cashfree();

    $x_api_version = "2023-08-01";
    $create_orders_request = new \Cashfree\Model\CreateOrdersRequest();
    $create_orders_request->setOrderAmount(1.0);
    $create_orders_request->setOrderCurrency("INR");
    $customer_details = new \Cashfree\Model\CustomerDetails();
    $customer_details->setCustomerId("123");
    $customer_details->setCustomerPhone("9999999999");
    $create_orders_request->setCustomerDetails($customer_details);

    try {
        $result = $cashfree->PGCreateOrder($x_api_version, $create_orders_request);
        print_r($result);
    } catch (Exception $e) {
        echo 'Exception when calling PGCreateOrder: ', $e->getMessage(), PHP_EOL;
    }
    ```
  </CodeGroup>

  After successfully creating an order, you will receive a unique `order_id` and `payment_session_id` that you need for subsequent steps.

  You can view the complete API request and response for `/orders` in the [Create Order API](/docs/api-reference/payments/latest/orders/create-order).
</Accordion>

<Accordion title="Step 2: Include SDK" icon="cube">
  <Badge>Client-side</Badge>

  <Warning>
    You must [whitelist your domain](/docs/payments/online/go-live/whitelist) with Cashfree before you start this step.
  </Warning>

  Include the Cashfree SDK in your client-side code. You must load `cashfree.js` directly from the Cashfree CDN to maintain PCI compliance. Don't bundle or self-host this library.

  <Tabs>
    <Tab title="JavaScript">
      Use the CDN or NPM to include the SDK in your project.

      <CodeGroup>
        ```html CDN theme={"dark"}
        <script src="https://sdk.cashfree.com/js/v3/cashfree.js"></script>
        ```

        ```javascript NPM theme={"dark"}
        npm install @cashfreepayments/cashfree-js
        ```
      </CodeGroup>

      ### Initialise the SDK

      Initialise the SDK using the `Cashfree()` function with the appropriate mode:

      <CodeGroup>
        ```javascript CDN theme={"dark"}
        const cashfree = Cashfree({
            mode: "sandbox" // Use "production" for live environment
        });
        ```

        ```javascript NPM theme={"dark"}
        import { load } from "@cashfreepayments/cashfree-js";

        const cashfree = await load({
            mode: "sandbox" // Use "production" for live environment
        });
        ```
      </CodeGroup>
    </Tab>

    <Tab title="React">
      For React applications, refer to the [SDK documentation](/docs/payments/online/element/sdks#react-library) for React-specific setup and usage patterns.

      ```javascript NPM theme={"dark"}
      npm install @cashfreepayments/cashfree-js
      ```

      Import and initialise the SDK in your React component:

      ```javascript theme={"dark"}
      import { useState, useEffect } from "react";
      import { load } from "@cashfreepayments/cashfree-js";

      function PaymentComponent() {
          const [cashfree, setCashfree] = useState(null);

          useEffect(() => {
              const initializeSDK = async () => {
                  const cf = await load({
                      mode: "sandbox" // Use "production" for live
                  });
                  setCashfree(cf);
              };
              initializeSDK();
          }, []);

          // Your component logic
      }
      ```
    </Tab>

    <Tab title="Svelte">
      For Svelte applications, refer to the [SDK documentation](/docs/payments/online/element/sdks#svelte-library) for Svelte-specific setup and usage patterns.

      ```javascript NPM theme={"dark"}
      npm install @cashfreepayments/cashfree-js
      ```

      Import and use the SDK in your Svelte component:

      ```javascript theme={"dark"}
      import { load } from "@cashfreepayments/cashfree-js";
      import { onMount } from "svelte";

      let cashfree;

      onMount(async () => {
          cashfree = await load({
              mode: "sandbox" // Use "production" for live
          });
      });
      ```
    </Tab>
  </Tabs>

  ### Async and deferred loading

  Asynchronous loading of JavaScript is recommended as it improves your site's user experience by preventing the script from blocking DOM rendering during load time.

  You can load `cashfree.js` using the `async` or `defer` attribute on the script tag:

  ```html theme={"dark"}
  <!-- Using async attribute -->
  <script src="https://sdk.cashfree.com/js/v3/cashfree.js" async></script>

  <!-- Using defer attribute -->
  <script src="https://sdk.cashfree.com/js/v3/cashfree.js" defer></script>
  ```

  <Note>
    With asynchronous loading, you must make all SDK method calls only after the script execution completes. Ensure your code waits for the Cashfree SDK to load before initialising or calling any methods.
  </Note>
</Accordion>

<Accordion title="Step 3: Build payment interface" icon="layer-group">
  <Badge>Client-side</Badge>

  Build your payment interface using one of the following approaches:

  ### Option 1: Use hosted checkout

  Redirect customers to a Cashfree-hosted payment page that supports all payment methods. This is the quickest integration option.

  ```javascript theme={"dark"}
  let checkoutOptions = {
      paymentSessionId: "payment_session_id_from_step_1",
      returnUrl: "https://yourwebsite.com/payment-success?order_id={order_id}",
      redirectTarget: "_self" // or "_blank", "_modal" for popup
  };

  cashfree.checkout(checkoutOptions).then(function (result) {
      if (result.error) {
          console.error(result.error.message);
      }
      if (result.redirect) {
          console.log("Redirection");
      }
  });
  ```

  <Info>
    The `redirectTarget` parameter controls how the checkout opens:

    * `_self`: Opens in same window (default)
    * `_blank`: Opens in new tab
    * `_modal`: Opens in popup window
    * DOM element: Embeds inline
  </Info>

  ### Option 2: Build custom components

  Create custom payment forms using individual components for complete design control. Components are available for cards, UPI, net banking, and wallets.

  <CardGroup>
    <Card title="Card payments" icon="credit-card" href="/docs/payments/online/element/cards">
      Accept credit and debit card payments
    </Card>

    <Card title="UPI payments" icon="mobile" href="/docs/payments/online/element/upi">
      Support UPI collect, intent, and QR
    </Card>

    <Card title="Other methods" icon="wallet" href="/docs/payments/online/element/other-components">
      Net banking, wallets, and BNPL
    </Card>
  </CardGroup>

  **Component lifecycle**:

  ```mermaid theme={"dark"}
  graph TD
      A[Create Component] -->|cashfree.create()| B[Component Instance]
      B -->|component.mount()| C[Component Mounted]
      C -->|User Input| D[Component Data]
      D -->|cashfree.pay()| E[Payment Initiated]
      E --> F[Payment Complete]
      
      style A fill:#e3f2fd
      style C fill:#e8f5e9
      style E fill:#fff3e0
      style F fill:#f3e5f5
  ```

  For detailed component examples, refer to the [Examples](/docs/payments/online/element/examples) page.
</Accordion>

<Accordion title="Step 4: Confirm the payment" icon="circle-check">
  <Badge>Server-side</Badge>

  After the customer completes the payment, verify the payment status on your server before delivering services.

  ### Hosted checkout response

  For hosted checkout, customers redirect to the `returnUrl` you provided when creating the order. For popup and inline checkouts, the `cashfree.checkout()` function returns a promise with payment details.

  ### Custom component response

  When using custom components, the `cashfree.pay()` method returns a promise with the payment result.

  ### Order status verification

  To verify an order you can call our `/pg/orders` endpoint from your backend. You can also use our SDK to achieve the same.

  <CodeGroup>
    ```bash curl theme={"dark"}
    curl --request GET \
         --url https://sandbox.cashfree.com/pg/orders/{order_id} \
         --header 'accept: application/json' \
         --header 'x-api-version: 2025-01-01' \
         --header 'x-client-id: "YOUR APP ID GOES HERE"' \
         --header 'x-client-secret: "YOUR SECRET KEY GOES HERE"'
    ```

    ```javascript nodejs theme={"dark"}
    cashfree
    .PGFetchOrder("<order_id>")
    .then((response) => {
    	console.log("Order fetched successfully:", response.data);
    })
    .catch((error) => {
    	console.error("Error:", error.response.data.message);
    });
    ```

    ```python python theme={"dark"}
    from cashfree_pg.models.create_order_request import CreateOrderRequest
    from cashfree_pg.api_client import Cashfree
    from cashfree_pg.models.customer_details import CustomerDetails
    from cashfree_pg.models.order_meta import OrderMeta

    Cashfree.XClientId = "<x-client-id>"
    Cashfree.XClientSecret = "<x-client-secret>"
    Cashfree.XEnvironment = Cashfree.SANDBOX
    x_api_version = "2023-08-01"

    try:
        api_response = Cashfree().PGFetchOrder(x_api_version, "order_3242X4jQ5f0S9KYxZO9mtDL1Kx2Y7u", None)
        print(api_response.data)
    except Exception as e:
        print(e)

    ```

    ```java java theme={"dark"}
    import com.cashfree.*;
    //other code

    try {
        Cashfree.XClientId = "<x-client-id>";
        Cashfree.XClientSecret = "<x-client-secret>";
        Cashfree.XEnvironment = Cashfree.SANDBOX;

        Cashfree cashfree = new Cashfree();
        String xApiVersion = "2023-08-01";

        ApiResponse<OrderEntity> responseFetchOrder = cashfree.PGFetchOrder(xApiVersion, "<order_id>", null, null, null);
        System.out.println(response.getData().getOrderId());
    } catch (ApiException e) {
        throw new RuntimeException(e);
    }
    ```

    ```go go theme={"dark"}
    version := "2023-08-01"
    response, httpResponse, err := cashfree.PGFetchOrder(&version, "<order_id>", nil, nil, nil)
    if err != nil {
    	fmt.Println(err.Error())
    } else {
    	fmt.Println(httpResponse.StatusCode)
    	fmt.Println(response)
    }
    ```

    ```csharp .net theme={"dark"}
    using cashfree_pg.Client;
    using cashfree_pg.Model;

    Cashfree.XClientId = "<x-client-id>";
    Cashfree.XClientSecret = "<x-client-secret>";
    Cashfree.XEnvironment = Cashfree.SANDBOX;
    var cashfree = new Cashfree();
    var xApiVersion = "2023-08-01";

    try {
        var result = cashfree.PGFetchOrder(xApiVersion, "<order_id>>", null, null);
        Console.WriteLine(result);
        Console.WriteLine(result.StatusCode);
        Console.WriteLine((result.Content as OrderEntity));
    } catch (ApiException e) {
        Console.WriteLine("Exception when calling PGFetchOrder: " + e.Message);
        Console.WriteLine("Status Code: " + e.ErrorCode);
        Console.WriteLine(e.StackTrace);
    }
    ```

    ```php php theme={"dark"}
    $x_api_version = "2023-08-01";
    try {
        $response = $cashfree->PGFetchOrder($x_api_version, "<order_id>");
        print_r($response);
    } catch (Exception $e) {
        echo 'Exception when calling PGFetchOrder: ', $e->getMessage(), PHP_EOL;
    }
    ```
  </CodeGroup>

  <Note>
    Always verify the order status before you deliver services to the customer. Use the [Get Order API](/docs/api-reference/payments/latest/orders/get-order) for this. An order is successful when the `order_status` is `PAID`.
  </Note>
</Accordion>

## Developer resources

<CardGroup>
  <Card title="SDK Libraries" icon="book-open" href="/docs/payments/online/element/sdks">
    JavaScript, React, and Svelte libraries for seamless integration
  </Card>

  <Card title="Integration Examples" icon="file-code" href="/docs/payments/online/element/examples">
    Working code samples for cards, UPI, wallets, and multi-payment setups
  </Card>

  <Card title="Component Overview" icon="layer-group" href="/docs/payments/online/element/component-overview">
    Component lifecycle methods including mount, update, and unmount
  </Card>

  <Card title="Customise Styling" icon="paintbrush" href="/docs/payments/online/element/customize">
    Apply custom styles, fonts, and themes to match your brand
  </Card>

  <Card title="Card Payments" icon="credit-card" href="/docs/payments/online/element/cards">
    Build custom card payment forms with secure components
  </Card>

  <Card title="UPI Components" icon="mobile-screen" href="/docs/payments/online/element/upi">
    Integrate UPI collect, QR code, and intent-based payments
  </Card>

  <Card title="Other Payment Methods" icon="wallet" href="/docs/payments/online/element/other-components">
    Add net banking, wallets, and Buy Now Pay Later options
  </Card>

  <Card title="Payment Options" icon="sliders" href="/docs/payments/online/element/payment-options">
    Configure payment methods, filters, and checkout behaviour
  </Card>
</CardGroup>

## Testing

After integration, verify that your payment flow works correctly:

1. Open the **Network** tab in your browser developer tools.
2. Initiate a payment and check the console logs.
3. Ensure you pass the correct environment (`sandbox` or `production`) and `payment_session_id`.
4. Use `console.log()` to confirm data is passed correctly to the SDK methods.
5. Test with [sandbox credentials](/docs/payments/online/resources/sandbox-environment) before going live.

## FAQs

<AccordionGroup>
  <Accordion title="Which integration approach should I choose: hosted checkout or custom components?">
    **Use hosted checkout** if you want the quickest implementation with minimal code. It provides a ready-made payment page with all payment methods.

    **Use custom components** when you need:

    * Complete control over the payment form design
    * Seamless integration with your existing UI
    * Custom validation and error handling
    * Specific payment flow customizations
  </Accordion>

  <Accordion title="Is my website PCI DSS compliant when using custom web checkout?">
    Yes. When you use Cashfree's custom web checkout, payment card data is captured directly by secure components and transmitted to Cashfree servers. Your server never touches sensitive card information, which reduces your PCI DSS compliance scope significantly.

    However, you must:

    * Load the SDK from Cashfree's CDN (don't bundle or self-host)
    * Never log or store card data on your servers
    * Use HTTPS for all website pages
  </Accordion>

  <Accordion title="How do I handle payment failures and errors?">
    Always implement proper error handling:

    1. **Client-side**: Check for `result.error` in the promise returned by `cashfree.checkout()` or `cashfree.pay()`
    2. **Server-side**: Always verify the order status using the Get Order API before delivering services
    3. **Use webhooks**: Implement webhook handlers for real-time payment status notifications
    4. **Display clear messages**: Show user-friendly error messages to customers when payments fail
  </Accordion>

  <Accordion title="Can I use the same payment session for multiple payment attempts?">
    No. Payment sessions are single-use and expire after 30 minutes. For each new payment attempt, generate a fresh payment session through the Create Order API on your server.
  </Accordion>

  <Accordion title="What browsers are supported by the custom web checkout?">
    The Cashfree SDK supports all modern browsers:

    * Chrome 90+
    * Firefox 88+
    * Safari 14+
    * Edge 90+
    * Mobile browsers (iOS Safari 14+, Chrome Mobile 90+)

    The SDK automatically handles browser compatibility and provides fallbacks where needed.
  </Accordion>

  <Accordion title="Do I need to whitelist my domain?">
    Yes. Domain whitelisting is mandatory for security. You must whitelist:

    * Your website domain for web integrations
    * Your app package name for mobile apps

    Whitelist your domains in the [Merchant Dashboard](https://merchant.cashfree.com/merchants/pg/developers/api-keys) under **Settings > Developers > Domain Whitelisting**.
  </Accordion>

  <Accordion title="Can I customize the styling of payment components?">
    Yes. Custom components are fully styleable. You can customize:

    * Colors and fonts
    * Border styles and radius
    * Padding and spacing
    * Focus and error states
    * Placeholder text

    See the [Customise Styling](/docs/payments/online/element/customize) guide for detailed examples.
  </Accordion>

  <Accordion title="How do I test the integration before going live?">
    1. Use `sandbox` mode in the SDK initialization
    2. Generate test API keys from the sandbox environment
    3. Use [test card numbers](/docs/payments/online/resources/sandbox-environment) from the documentation
    4. Test all payment scenarios: success, failure, pending
    5. Verify webhook handling with test notifications
    6. Switch to `production` mode and use live API keys only when ready to go live
  </Accordion>

  <Accordion title="What happens if the SDK fails to load?">
    If the SDK fails to load:

    * Check browser console for errors
    * Verify the CDN address is correct
    * Ensure you're loading from `https://sdk.cashfree.com`
    * Check for network connectivity issues
    * Verify no browser extensions are blocking the script

    For async loading, ensure you wait for the SDK to load before making any method calls.
  </Accordion>

  <Accordion title="Can I save customer card details for future payments?">
    Yes. Use the `savePaymentInstrument` component in your card payment form. Customers can opt-in to save their card details securely. On subsequent payments, you can retrieve and use saved payment instruments through the Token Vault feature.

    Learn more in the [Token Vault documentation](/docs/payments/features/token-vault).
  </Accordion>
</AccordionGroup>

<div>
  <p>Affiliate partner program</p>

  <p>As a developer building payment experiences for your clients, you can earn additional income while providing them with industry-leading payment solutions.</p>

  <p>Join the <a href="https://partner.cashfree.com/partner-ui/authentication/signup?source-action=Affiliate%20Program%20LP&action=Sign%20Up&button-id=StartNow_CashfreeAffiliatePartnerProgram">Cashfree affiliate partner program</a> and get rewarded every time your clients use Cashfree.</p>

  <p>**What you get:**</p>

  <ul>
    <li>Earn up to 0.25% commission on every transaction.</li>
    <li>Become a trusted fintech partner for your clients.</li>
    <li>Access to a dedicated partner manager for expert support.</li>
  </ul>

  <p>**What your clients get:**</p>

  <ul>
    <li>Instant activation and go live in minutes.</li>
    <li>Industry-best success rate across all payment modes.</li>
    <li>Effortless acceptance of international payments in 140+ currencies.</li>
  </ul>

  <p>Get started today. <a href="https://partner.cashfree.com/partner-ui/authentication/signup?source-action=Affiliate%20Program%20LP&action=Sign%20Up&button-id=StartNow_BecomeAPartner">Become a partner now</a>.</p>
</div>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/payments/latest/orders/create-order">Create Order API</a></li>
    <li><a href="/docs/api-reference/payments/latest/orders/get-order">Get Order API</a></li>
    <li><a href="/docs/payments/online/element/sdks">SDK Libraries</a></li>
    <li><a href="/docs/payments/online/element/examples">Integration Examples</a></li>
  </ul>
</div>


# Configuring Payment Options
Source: https://www.cashfree.com/docs/payments/online/element/payment-options

Configure Cashfree.js payment options by passing the component, payment_session_id, returnUrl, and savePaymentInstrument flags to trigger a custom checkout.

Once you have the components ready you will need to pass on these components along with the `payment_session_id`to `cashfree.js`. Here is an example of a payment options. You can see there are three properties to it:

1. `paymentMethod`: This is the component which will be used for the payment.
2. `paymentSessionId`: This is the `payment_session_id` which you get once you have created an order.
3. Other attributes likes `returnUrl`, `savePaymentInstrument` etc.

```js theme={"dark"}
let paymentOptions = {
	paymentMethod: component,
	paymentSessionId: "your-payment-session-id",
	savePaymentInstrument: true,
};
```

### paymentOptions

<ResponseField name="paymentMethod" type="object">
  A reference to a payable component. Kindly note that the payable component should be ready and complete before invoking pay on it, otherwise it will throw an error. To get if a payable component is complete or not you can use component.`isComplete()` which returns a bool.

  There are scenarios when one component also requires other components, in that case you will have to also check the completeness of those other component. Example- to process card you would need to make sure cardNumber, cardExpiry, cardCvv and cardHolder are all complete.
</ResponseField>

<ResponseField name="paymentSessionId" type="string">
  To make payment you will need a paymentSessionId, you can get this by making a [create order API](/docs/api-reference/payments/latest/orders/create-order) call to `POST /orders`. Please make sure you are using the correct hostname for the environment you want to process the payment for.

  In the response of `POST /orders` you will find `payment_session_id`. Note that this is a backend call so you will need to have a server. Read how to generate `payment_session_id` [here](/docs/api-reference/payments/latest/orders/create-order)
</ResponseField>

<ResponseField name="returnUrl" type="string">
  This is the url where your customers will be redirected after they have
  complete the payment.
</ResponseField>

<ResponseField name="redirect" type="string">
  For certain `paymentMethod` you can choose to not redirect the customer to the `returnUrl` by passing `if_required`. Examples would be Card, UPI and QR. For payment method where redirection is required this flag will be completely ignored. If you decide not to redirect the customer then `pay()` promise resolves with `{paymentDetails: {paymentMessage: "Payment finished. Check status."}}`. To confirm the payment it is recommended that you always check the status of your order from your backend server with Cashfree.
</ResponseField>

<ResponseField name="redirectTarget" type="string">
  We also provide a way for you to decide how to redirect your customer. This takes all the values that are valid for hyperlink. Default is `_self`

  | Value | Description |
  | - | - |
  | `_blank` | Opens the linked document in a new window or tab |
  | `_self` | Opens the linked document in the same frame as it was clicked (this is default) |
  | `_parent` | Opens the linked document in the parent frame |
  | `_top` | Opens the linked document in the full body of the window |
  | `_framename_` | Opens the linked document in the named iframe |
</ResponseField>

<ResponseField name="savePaymentInstrument" type="object">
  Assign a `savePaymentInstrument` to this to save the payment method. Works only for card payment. Default is `null`.

  ```js theme={"dark"}
  let saveOptions = {
  	values: {
  		label: "Save Card for later"
  	}
  };
  let savecard = cashfree.create("savePaymentInstrument", saveOptions);
  savecard.mount("#div-id");

  let cashfree = Cashfree();
  .....
  cashfree.pay({
    ...
    savePaymentInstrument: savecard
  })
  ```
</ResponseField>

<ResponseField name="offerId" type="object">
  You can pass an offer in the object which you can fetch using the [get offer
  api](/docs/api-reference/payments/latest/eligibility/get-eligible-offers-for-an-order). Please note that you need to use the
  `offer_id` value only. It is a uuid.
</ResponseField>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/payments/latest/orders/create-order">Create Order API</a></li>
    <li><a href="/docs/api-reference/payments/latest/eligibility/get-eligible-offers-for-an-order">Get Eligible Offers API</a></li>
  </ul>
</div>


# SDK Libraries
Source: https://www.cashfree.com/docs/payments/online/element/sdks

Integrate Cashfree Payment Gateway using the JS, React, and Svelte Element SDK libraries with prebuilt UI components, payment methods, and custom styling.

Integrate Cashfree Payment Gateway into your web applications using our JS, React and Svelte SDKs. These component libraries simplify the payment workflow with prebuilt UI components and event handling. You can customise styling to match your app’s design and handle multiple payment methods with ease. Use these SDKs to build a secure, seamless, and developer-friendly payment experience.

### JS library

Offers a flexible and efficient payment experience with support for multiple payment methods, customisable styling, and robust event handling. The following payment methods are supported:

* Card payment
* EMI
* UPI QR code
* UPI app intent
* UPI collect
* Netbanking
* Wallets
* BNPL
* Cashfree hosted checkout

**To install the package use:**

<CodeGroup>
  ```javascript CDN theme={"dark"}
  <script src="https://sdk.cashfree.com/js/v3/cashfree.js"></script>
  ```

  ```javascript NPM theme={"dark"}
  npm install @cashfreepayments/cashfree-js
  ```
</CodeGroup>

**Import and set up the Cashfree card component**

**To install the package use:**

<CodeGroup>
  ```javascript HTML theme={"dark"}
  <!DOCTYPE html>
  <html lang="en">
      <head>
          <meta charset="UTF-8">
          <meta name="viewport" content="width=device-width, initial-scale=1.0">
          <title>Cashfree V3 Card</title>
          <script src="https://sdk.cashfree.com/js/v3/cashfree.js"></script>
      </head>
      <body>
          <div id="cardLayout" style="width:400px; padding: 20px; background:#f6f9fb">
             <div id="cardNumber" style="margin-bottom: 10px;"></div>
              <div id="cardHolder" style="margin-bottom: 10px;"></div>
              <div style="display: flex; margin-bottom: 10px;">
                  <div id="cardExpiry" style="margin-right: 1rem"></div>
                  <div id="cardCvv"></div>
              </div>
              <div id="save" style="margin-bottom: 10px;"></div>
              <button 
                  type="submit" id="payNow" 
                  style="width: 100%; height: 35px; cursor: pointer; border: 1px solid #2361d5; color: #2361d5; background: none; border-radius: 8px">
                  Pay Now
              </button>
              <p id="paymentMessage" style="color: #df1b41"></p>
          </div>
      </body>
      <script>
          const cashfree = Cashfree({
              mode: "sandbox",
          });

          let paymentBtn = document.getElementById("payNow");
          let paymentMessage = document.getElementById("paymentMessage");

          let styleObject = {
              fonts: [{
                  cssSrc: "https://fonts.googleapis.com/css2?family=Lato"
              }],
              base: {
                  fontSize: "16px",
                  fontFamily: "Lato",
                  backgroundColor: "#FFFFFF",
                  ":focus": {
                      border: "1px solid #2361d5",
                  },
                  border: "1px solid #e6e6e6",
                  borderRadius: "5px",
                  padding: "16px",
                  color: "#000000",
              },
              invalid: {
                  color: "#df1b41",
              },
          };

          let cardOptions = {
              values: {
                  placeholder: "Enter Card Number",
              },
              style: styleObject,
          };
          let cardComponent = cashfree.create("cardNumber", cardOptions);
          cardComponent.mount("#cardNumber");

          let cvvOptions = {
              style: styleObject,
          };
          let cvvComponent = cashfree.create("cardCvv", cvvOptions);
          cvvComponent.mount("#cardCvv");

          let cardHolderOptions = {
              values: {
                  placeholder: "Enter Card Holder Name",
              },
              style: styleObject,
          };
          let cardHolder = cashfree.create("cardHolder", cardHolderOptions);
          cardHolder.mount("#cardHolder");

          let cardExpiryOptions = {
              style: styleObject,
          };
          let cardExpiry = cashfree.create("cardExpiry", cardExpiryOptions);
          cardExpiry.mount("#cardExpiry");

          let saveOptions = {
              values: {
                  label: "Save Card for later",
              },
              style: styleObject,
          };
          let save = cashfree.create("savePaymentInstrument", saveOptions);
          save.mount("#save");

          cardExpiry.on("change", function (data) {
              toggleBtn();
          });
          cardHolder.on("change", function (data) {
              toggleBtn();
          });
          cardComponent.on("change", function (data) {
              cvvComponent.update({ cvvLength: data.value.cvvLength });
              toggleBtn();
          });
          cvvComponent.on("change", function (data) {
              toggleBtn();
          });

          function toggleBtn() {
              if (
                  cardExpiry.isComplete() &&
                  cardHolder.isComplete() &&
                  cardComponent.isComplete() &&
                  cvvComponent.isComplete()
              ) {
                  paymentBtn.disabled = false;
              } else {
                  paymentBtn.disabled = true;
              }
          }

          paymentBtn.addEventListener("click", function () {
              paymentBtn.disabled = true;
              cashfree.pay({
                  paymentMethod: cardComponent,
                  paymentSessionId: "your-payment-session-id",
                  savePaymentInstrument: save,
              }).then(function (data) {
                  if (data != null && data.error) {
                      paymentMessage.innerHTML = data.error.message;
                  }
                  paymentBtn.disabled = false;
              });
          });
      </script>
  </html>
  ```

  ```javascript ReactJS theme={"dark"}
  import { useRef } from "react";
  import { load } from "@cashfreepayments/cashfree-js";

  function V3Card() {
      let cashfree, cardComponent, cvvComponent, cardHolder, cardExpiry, save;
      let paymentBtn = useRef(null),
          paymentMessage = useRef(null);

      const renderCard = async () => {
          cashfree = await load({
              mode: "sandbox",
          });

          let styleObject = {
              fonts: [{
                  cssSrc: "https://fonts.googleapis.com/css2?family=Lato"
              }],
              base: {
                  fontSize: "16px",
                  fontFamily: "Lato",
                  backgroundColor: "#FFFFFF",
                  ":focus": {
                      border: "1px solid #2361d5",
                  },
                  border: "1px solid #e6e6e6",
                  borderRadius: "5px",
                  padding: "16px",
                  color: "#000000",
              },
              invalid: {
                  color: "#df1b41",
              },
          };

          let cardOptions = {
              values: {
                  placeholder: "Enter Card Number",
              },
              style: styleObject,
          };
          cardComponent = cashfree.create("cardNumber", cardOptions);
          cardComponent.mount("#cardNumber");

          let cvvOptions = {
              style: styleObject,
          };
          cvvComponent = cashfree.create("cardCvv", cvvOptions);
          cvvComponent.mount("#cardCvv");

          let cardHolderOptions = {
              values: {
                  placeholder: "Enter Card Holder Name",
              },
              style: styleObject,
          };
          cardHolder = cashfree.create("cardHolder", cardHolderOptions);
          cardHolder.mount("#cardHolder");

          let cardExpiryOptions = {
              style: styleObject,
          };
          cardExpiry = cashfree.create("cardExpiry", cardExpiryOptions);
          cardExpiry.mount("#cardExpiry");

          let saveOptions = {
              values: {
                  label: "Save Card for later",
              },
              style: styleObject,
          };
          save = cashfree.create("savePaymentInstrument", saveOptions);
          save.mount("#save");

          cardExpiry.on("change", function (data) {
              toggleBtn();
          });
          cardHolder.on("change", function (data) {
              toggleBtn();
          });
          cardComponent.on("change", function (data) {
              cvvComponent.update({ cvvLength: data.value.cvvLength });
              toggleBtn();
          });
          cvvComponent.on("change", function (data) {
              toggleBtn();
          });
      };

      renderCard();

      const toggleBtn = () => {
          if (
              cardExpiry.isComplete() &&
              cardHolder.isComplete() &&
              cardComponent.isComplete() &&
              cvvComponent.isComplete()
          ) {
              paymentBtn.current.disabled = false;
          } else {
              paymentBtn.current.disabled = true;
          }
      };

      const doPayment = () => {
          paymentBtn.current.disabled = true;
          cashfree.pay({
              paymentMethod: cardComponent,
              paymentSessionId: "your-payment-session-id",
              savePaymentInstrument: save,
          })
          .then(function (data) {
              if (data != null && data.error) {
                  paymentMessage.current.innerHTML = data.error.message;
              }
              paymentBtn.current.disabled = false;
          });
      };

      return (
          <div id="cardLayout" style={{ width: "400px", padding: "20px", background: "#f6f9fb" }}>
              <div id="cardNumber" style={{ marginBottom: "10px" }}></div>
              <div id="cardHolder" style={{ marginBottom: "10px" }}></div>
              <div style={{ marginBottom: "10px", display: "flex" }}>
                  <div id="cardExpiry" style={{ marginRight: "1rem" }}></div>
                  <div id="cardCvv"></div>
              </div>
              <div id="save" style={{ marginBottom: "10px" }}></div>
              <button type="submit" id="payNow" ref={paymentBtn} onClick={doPayment}
                  style={{width: "100%", height: "35px", cursor: "pointer", border: "1px solid #2361d5", color: "#2361d5", background: "none", borderRadius: "8px"}}
              >
                  Pay Now
              </button>
              <p id="paymentMessage" ref={paymentMessage} style={{ color: "#df1b41" }}></p>
          </div>
      );
  }

  export default V3Card;
  ```
</CodeGroup>

### Svelte library

Supports multiple payment methods, event handling, and customisable styling for a flexible and efficient payment experience.
We support the following payment methods:

* Card Payment
* UPI QR Code
* UPI App Intent
* UPI Collect
* Netbanking
* Wallets
* Cashfree hosted checkout

**To install the package use:**

```Text Shell theme={"dark"}
npm install @cashfreepayments/pg-svelte
```

**Import and set up the Cashfree card component**

```html theme={"dark"}
<script>
	import {
		Cashfree,
		CardNumber,
		CardHolder,
		CardExpiry,
		CardCVV,
		SaveInstrument
	} from '@cashfreepayments/pg-svelte';

	// Track payment component state
	let isReadyForPayment = false;

	function checkState(e) {
		// Check if all required fields are complete
		isReadyForPayment = e.detail.isComplete;
	}
</script>

<Cashfree bind:this={cashfreeCard} {mode} on:complete={checkState}>
	<div class="form-container">
		<div>
			<label>Card Number</label>
			<CardNumber class="input-text" placeholder="4111 XXXX XXXX 1111" />
		</div>
		<div>
			<label>Card Holder Name</label>
			<CardHolder class="input-text" />
		</div>
		<div class="expiry-cvv-container">
			<div>
				<label>Expiry</label>
				<CardExpiry class="input-text" />
			</div>
			<div>
				<label>CVV</label>
				<CardCVV class="input-text" />
			</div>
		</div>
		<div>
			<SaveInstrument label="Save this card for future payments" />
		</div>
		<button on:click={doPayment} disabled={!isReadyForPayment}>Pay Now</button>
	</div>
</Cashfree>
```

To learn more about this library, refer to [Svelte GitHub repository](https://github.com/cashfree/pg-svelte).

### React library

A lightweight and modular React component library for integrating Cashfree Payment Gateway built on top of the Cashfree JS SDK with full support for card input fields like Card Number, Expiry and more.

**To install the package use:**

```Text Shell theme={"dark"}
npm install @cashfreepayments/pg-react
```

**Import and set up the Cashfree Card component**

```html theme={"dark"}
import React, { useState } from "react";
import {
  Cashfree,
  CardNumber,
  CardHolder,
  CardExpiry,
  CardCVV,
  SaveInstrument,
} from "@cashfreepayments/pg-react";

const App: React.FC = () => {
  const [isComplete, setIsComplete] = useState(false);

  const handlePay = () => {
    alert("Payment processing...");
    // Trigger your payment logic here
  };

  return (
    <Cashfree
      theme="pastel"
      onComplete={(status) => {
        setIsComplete(status); // this is your local app state
      }}
    >
      <CardNumber />
      <CardHolder />
      <div style={{ display: "flex", gap: "10px", marginBottom: "10px" }}>
        <CardExpiry />
        <CardCVV />
      </div>
      <SaveInstrument />
      <div style={{ marginTop: "20px" }}>
        <button
          onClick={handlePay}
          disabled={!isComplete}
          style={{
            padding: "12px 24px",
            fontSize: "16px",
            cursor: isComplete ? "pointer" : "not-allowed",
            backgroundColor: isComplete ? "#2361d5" : "#a0a0a0",
            color: "#fff",
            border: "none",
            borderRadius: "6px",
            transition: "background-color 0.3s ease",
          }}
        >
          Pay Now
        </button>
      </div>
    </Cashfree>
  );
};

export default App;
```

To learn more about this library, refer to [React GitHub repository](https://github.com/cashfree/pg-react).

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/payments/online/element/introduction">Element Introduction</a></li>
    <li><a href="/docs/payments/online/element/cards">Card Components</a></li>
    <li><a href="/docs/payments/online/element/upi">UPI Components</a></li>
    <li><a href="https://github.com/cashfree/pg-react">React GitHub Repository</a></li>
    <li><a href="https://github.com/cashfree/pg-svelte">Svelte GitHub Repository</a></li>
  </ul>
</div>


# UPI Component
Source: https://www.cashfree.com/docs/payments/online/element/upi

Use the Cashfree.js UPI Component to collect VPAs, render UPI Intent buttons, and show UPI QR codes for payments on a fully custom checkout experience.

There are three UPI components as listed below:

## upiCollect

A component to accept user's vpa/upi id

<ResponseField name="upiCollect" type="UPI Collect Object">
  <Expandable title="properties">
    <ParamField type="string">
      placeholder for enter vpa field
    </ParamField>

    <ParamField type="string">
      vpa/upi id of the customer
    </ParamField>
  </Expandable>
</ResponseField>

<h4>Returned Value</h4>
You can get the value of a component by calling `component.data().value`. All returned
values of `component.data()` can be found in the [component overview](/docs/payments/online/element/component-overview#get-component-data)

<ResponseField name="upiCollect" type="UPI Collect Object">
  <Expandable title="properties">
    <ResponseField name="upiId" type="string">
      vpa/upi id of the customer
    </ResponseField>
  </Expandable>
</ResponseField>

<Accordion title="Code snippet for upiCollect component">
  ```js theme={"dark"}
  let cashfree = Cashfree({
    mode:"sandbox" //or production
  });
  let upiCollect = cashfree.create('upiCollect', {
  	values:{
  		upiId: 'janedoe1@okbankname'
  	}
  });
  upiCollect.on('loaderror', function(data){
  	console.log(data.error)
  })
  upiCollect.mount("#mount-here");
  upiCollect.on('ready', function(d){
      console.log(upiCollect.data().value); //{upiId: 'janedoe1@okbankname'}
      //or
      //console.log(d.value) 
  });
  ```
</Accordion>

## upiApp

A component to initiate UPI app/intent payment. Only works in mobile phones. If you mount it on desktop it will throw an error in loaderror

<Warning>
  Component will not mount on custom webview/inappbrowser Android. It will
  however mount in popular apps like Facebook, Instagram, Twitter. However,
  since iOS handles intent differently than android it will always mount in iOS
</Warning>

<ResponseField name="upiApp" type="UPI App Object">
  <Expandable title="properties">
    <ParamField type="string">
      name of the upi app
    </ParamField>

    <ParamField type="string">
      Text for button, ex Google Pay for upiApp gpay
    </ParamField>

    <ParamField type="bool">
      Indicate whether to show the app icon or not
    </ParamField>
  </Expandable>
</ResponseField>

<h4>Returned Value</h4>
You can get the value of a component by calling `component.data().value`. All returned
values of `component.data()` can be found in the [component overview](/docs/payments/online/element/component-overview#get-component-data)

<ResponseField name="upiApp" type="UPI App Object">
  <Expandable title="properties">
    <ResponseField name="upiApp" type="string">
      name of the upi app
    </ResponseField>
  </Expandable>
</ResponseField>

<Accordion title="Code snippet for the upiApp component">
  ```javascript theme={"dark"}
  let cashfree = Cashfree({
    mode:"sandbox" //or production
  });
  let upiApp = cashfree.create('upiApp', {
  	values:{
  		upiApp: 'gpay',
  		buttonText: 'GPAY',
  		buttonIcon: true
  	}
  });
  upiApp.on('loaderror', function(data){
  	console.log(data.error)
  })
  upiApp.mount("#mount-here");
  upiApp.on('ready', function(d){
      console.log(upiApp.data().value); //{upiApp: 'gpay'}
      //or
      //console.log(d.value) 
  });
  ```
</Accordion>

## upiQr

A component to show a UPI qr code

<ResponseField name="upiQr" type="UPI QR Object">
  <Expandable title="properties">
    <ParamField type="string">
      size of the qr code. ex "220px"
    </ParamField>
  </Expandable>
</ResponseField>

<h4>Returned Value</h4>
You can get the value of a component by calling `component.data().value`. All returned
values of `component.data()` can be found in the [component overview](/docs/payments/online/element/component-overview#get-component-data)

<ResponseField name="upiQr" type="UPI QR Object">
  <Expandable title="properties">
    <ResponseField name="size" type="string">
      size of the qr code. ex "220px"
    </ResponseField>
  </Expandable>
</ResponseField>

<Accordion title="Code snippet for upiQr component">
  ```javascript theme={"dark"}
  let cashfree = Cashfree({
    mode:"sandbox" //or production
  });
  let upiQr = cashfree.create('upiQr', {
  	values:{
  		size: "220px"
  	}
  });
  upiQr.on('loaderror', function(data){
  	console.log(data.error)
  })
  upiQr.mount("#mount-here");
  upiQr.on('ready', function(d){
      console.log(upiQr.data().value); //{size: '220px'}
      //or
      //console.log(d.value) 
  })
  ```
</Accordion>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/payments/online/element/introduction">Element Introduction</a></li>
    <li><a href="/docs/payments/online/element/sdks">SDK Libraries</a></li>
    <li><a href="/docs/payments/online/element/cards">Card Components</a></li>
    <li><a href="/docs/payments/online/element/other-components">Other Components</a></li>
    <li><a href="/docs/payments/online/element/component-overview">Component Overview</a></li>
  </ul>
</div>


# API Logs and Metrics
Source: https://www.cashfree.com/docs/payments/online/go-live/api-logs

Monitor your Cashfree Payment Gateway integration with API logs, alerts, and metrics in the Merchant Dashboard to troubleshoot errors and track endpoint health.

<Tip>
  Cashfree notifies you when a certain API threshold on an alert is crossed. For
  example, you might create an API alert to notify you when a certain API is
  responding with non 200 response more than 10% of time.
</Tip>

## API logs

API logs provide real-time visibility into your integration's API calls and their responses. The logging system captures detailed information about each request, making it easier to monitor and troubleshoot your implementation.

To access:

1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).

2. Select **Payment Gateway** on the home page.

3. Select **API Logs and Alerts** under the **Developers** section.

4. Select the **Logs** tab.

<img />

##### Error tracking

* Errors are categorised by **API Endpoint**
* Each error shows a count of occurrences
* Detailed error messages help identify the root cause
* Example error format: "risk\_data.customer\_ip is Invalid. Value received: 123.45.45.345"

## API alerts

Alerts can be configured to monitor API performance and notify you of potential issues. The alert system helps you proactively manage your integration.

To access:

1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).

2. Select **Payment Gateway** on the home page.

3. Select **API Logs and Alerts** under the **Developers** section.

4. Select the **Alerts** tab.

* **API Alert**: Monitor specific API endpoints
* **Rate Limit Warning**: Track API usage against rate limits

<img />

##### Alert details

* **Rule Name**: Custom identifier for the alert
* **Rule Type**: Choose between **API Alert** or **Rate Limit Warning**
* **Grouping Level**:
  * **All APIs**
  * **Selected API**

##### Severity levels

* **Low**
* **Medium**
* High

##### Threshold configuration

* **Error Percentage**: Set the threshold for error rate
* **Time Window**: Select the monitoring period
* **Minimum Sample Size**: Minimum number of API calls required
* **Self Resolve Time**: Duration after which alert auto-resolves
* **Resolve Wait Time**: Waiting period before marking as resolved

##### Alert management

* **Test**: Verify alert configuration
* **Edit**: Modify existing alert rules
* **Status**: Monitor active/inactive state
* **Actions**: Available actions for each alert rule

##### Best practices

1. Set appropriate threshold values based on your business requirements
2. Configure different severity levels for different types of issues
3. Maintain a minimum sample size to avoid false positives
4. Set reasonable self-resolve and wait times
5. Regularly review and update alert configurations

##### Communication

* Alerts are sent to recipients specified in communication preferences
* Multiple recipients can be configured for different alert types
* Alerts include detailed information about the triggering event


# Go Live Checklist
Source: https://www.cashfree.com/docs/payments/online/go-live/checklist

Verify your Cashfree Payment Gateway integration with this go-live checklist covering API keys, webhooks, refund flows, and production environment switches.

## Integration checklist

<div>
  <div>
    <div>
      <div>
        <svg>
          <path />
        </svg>
      </div>

      <span>Have you ensured that the checkout page reflects your brand colours and themes?</span>
    </div>

    <div>
      <button>Yes</button>
      <button>No</button>
      <button>N/A</button>
    </div>
  </div>

  <div>
    <svg>
      <path />
    </svg>

    <span>You must provide clear branding on the checkout page to ensure high conversion.</span>
  </div>

  <div>
    <svg>
      <path />
    </svg>

    <span>You can customise your checkout on the [Merchant Dashboard](https://merchant.cashfree.com/merchants/pg/settings/payment-methods?env=prod) or learn more about [customising checkout](/docs/payments/checkout/customise-checkout).</span>
  </div>
</div>

<div>
  <div>
    <div>
      <div>
        <svg>
          <path />
        </svg>
      </div>

      <span>Are you using the API keys for production and storing them carefully?</span>
    </div>

    <div>
      <button>Yes</button>
      <button>No</button>
      <button>N/A</button>
    </div>
  </div>

  <div>
    <svg>
      <path />
    </svg>

    <span>Get your API key and secret key from the Cashfree dashboard. These will be used for authentication, never expose in your app or frontend.</span>
  </div>

  <div>
    <svg>
      <path />
    </svg>

    <span>Log in to the **[Merchant Dashboard](https://merchant.cashfree.com/auth/login)** and go to **Payment Gateway > Developers > API Keys**</span>
  </div>
</div>

<div>
  <div>
    <div>
      <div>
        <svg>
          <path />
        </svg>
      </div>

      <span>Have you whitelisted your domain name or android package in production?</span>
    </div>

    <div>
      <button>Yes</button>
      <button>No</button>
      <button>N/A</button>
    </div>
  </div>

  <div>
    <svg>
      <path />
    </svg>

    <span>Our integrations require whitelisting of your domain or android package. Any other domain used to open the checkout page will be blocked by Cashfree.</span>
  </div>

  <div>
    <svg>
      <path />
    </svg>

    <span>Learn more in the [whitelisting guide](/docs/payments/online/go-live/whitelist).</span>
  </div>
</div>

<div>
  <div>
    <div>
      <div>
        <svg>
          <path />
        </svg>
      </div>

      <span>Before confirming a payment, are you verifying the final order status with Cashfree's server?</span>
    </div>

    <div>
      <button>Yes</button>
      <button>No</button>
      <button>N/A</button>
    </div>
  </div>

  <div>
    <svg>
      <path />
    </svg>

    <span> Implement server-side logic to verify the payment using Cashfree's order or payment validation API.</span>
  </div>

  <div>
    <svg>
      <path />
    </svg>

    <span>Learn more in the [order verification guide](/docs/payments/online/web/redirect#step-3-confirm-the-payment-server-side).</span>
  </div>
</div>

<div>
  <div>
    <div>
      <div>
        <svg>
          <path />
        </svg>
      </div>

      <span>Have you integrated with webhooks to be informed about payment success asynchronously?</span>
    </div>

    <div>
      <button>Yes</button>
      <button>No</button>
      <button>N/A</button>
    </div>
  </div>

  <div>
    <svg>
      <path />
    </svg>

    <span>We recommend using webhooks for event updates. After receiving a webhook, call the Get Status API to verify successful payment processing.</span>
  </div>

  <div>
    <svg>
      <path />
    </svg>

    <span>Learn more in the [payment gateway webhooks reference](/docs/api-reference/payments/latest/payments/webhooks).</span>
  </div>
</div>

<div>
  <div>
    <div>
      <div>
        <svg>
          <path />
        </svg>
      </div>

      <span>Have you subscribed to API and success rate alerts?</span>
    </div>

    <div>
      <button>Yes</button>
      <button>No</button>
      <button>N/A</button>
    </div>
  </div>

  <div>
    <svg>
      <path />
    </svg>

    <span>We recommend setting up API alerts on Cashfree dashboard to ensure seamless processing.</span>
  </div>

  <div>
    <svg>
      <path />
    </svg>

    <span>Log in to the **[Merchant Dashboard](https://merchant.cashfree.com/auth/login)** and go to **Payment Gateway > Developers > Rate Limits**</span>
  </div>
</div>

<div>
  <div>
    <div>
      <div>
        <svg>
          <path />
        </svg>
      </div>

      <span>Have you ensured that all payment methods are enabled for your account?</span>
    </div>

    <div>
      <button>Yes</button>
      <button>No</button>
      <button>N/A</button>
    </div>
  </div>

  <div>
    <svg>
      <path />
    </svg>

    <span>Ensure all payment methods are enabled for your account. Reach out to us by filling out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) if something is not correct.</span>
  </div>

  <div>
    <svg>
      <path />
    </svg>

    <span>Log in to the **[Merchant Dashboard](https://merchant.cashfree.com/auth/login)** and go to **Payment Gateway > Settings > Payment Methods**</span>
  </div>
</div>

<div>
  <div>
    <div>
      <div>
        <svg>
          <path />
        </svg>
      </div>

      <span>Have you checked for app integrity for testing in production?</span>
    </div>

    <div>
      <button>Yes</button>
      <button>No</button>
      <button>N/A</button>
    </div>
  </div>

  <div>
    <svg>
      <path />
    </svg>

    <span>Please follow the [steps in the integrity production testing guide](/docs/payments/online/mobile/misc/cashfree_integrity_prod_testing)</span>
  </div>

  <div>
    <svg>
      <path />
    </svg>

    <span>Read more about [Cashfree integrity](/docs/payments/online/mobile/misc/cashfree_integrity).</span>
  </div>
</div>


# Whitelist Your Website or App
Source: https://www.cashfree.com/docs/payments/online/go-live/whitelist

Whitelist your website domain or mobile app package with Cashfree Payment Gateway before collecting live payments to satisfy security and policy reviews.

Before using the checkout page for payment collection, you must whitelist your domain or app package for security purposes. This applies to:

* **Websites:** Domain whitelisting
* **Mobile apps:** Package name whitelisting

## Submitting a whitelist request

1. Go to **Payment Gateway Dashboard > Developers > Whitelisting**.
2. Click **Add New**.
3. Select the whitelisting type:
   * **Website URL** for websites.
   * **App Link** for mobile apps.
4. Enter the required value and click **Proceed**.
5. Ensure the following details are present on your website for whitelisting:
   * Policy pages:
     * **Contact Us**
     * **Terms and Conditions**
     * **Refunds and Cancellations**
   * Other details:
     * Products or services should be listed.
     * Product or service pricing should be in Indian Rupees (INR).
6. Click **Confirm & Proceed**. Your website or app will be reviewed and approved.

<Note>
  The line of business for the new domain must match your existing line of business. If you need to add a domain with a different line of business, you must create a new Cashfree account with a different email address.
</Note>

## Format guidelines

### Website domains

Only secure URLs beginning with `https://` are accepted. Custom ports and certain subdomains are not supported.

<img alt="Web Domain Example" />

| Example | Status | Notes |
| - | :-: | - |
| `https://www.croma.com` | Allowed | HTTPS required |
| `https://www.croma.com/` | Allowed | Trailing slash permitted |
| `https://www.croma.com/televisions-accessories/c/997` | Allowed | HTTPS with path allowed |
| `www.croma.com` | Not allowed | Missing HTTPS protocol |
| `http://www.croma.com` | Not allowed | HTTP not secure enough |
| `https://www.cashfree.com:8000/` | Not allowed | Custom ports not supported |
| `https://sandbox.cashfree.com` | Not allowed | Sandbox/test environments not allowed |

***

### Mobile apps

Only official app listing URLs from **Google Play Store** for Android or **Apple App Store** for iOS are allowed.

<img alt="App Package Example" />

| Example | Status | Notes |
| - | :-: | - |
| `https://play.google.com/store/apps/details?id=com.rapido.passenger` | Allowed | Google Play Store app link |
| `https://apps.apple.com/in/app/google-maps/id5850273` | Allowed | Apple App Store app link |
| `com.cashfree.merchant` | Not allowed | Package name alone not accepted |
| Third-party APK/IPA source links | Not allowed | Must be official stores |
| Shortened/redirected URLs | Not allowed | Destination cannot be verified |

***

## Tracking your request

You can track the status of your whitelisting request from the whitelisting homepage. The dashboard displays:

* Submission date and time.
* Domain or package name.
* Current status.

Use the dropdown menu to filter between domain and package name requests.

## Processing time

* **Standard processing time:** Most whitelisting requests are reviewed and approved **within 24 hours** of submission.
* **For urgent queries:** If you need expedited processing, please fill out the detailed [support form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) with your specific requirements.

<Frame>
  <img alt="Better Processing Time Example" />
</Frame>


# Android Integration
Source: https://www.cashfree.com/docs/payments/online/mobile/android

Integrate the Cashfree Payment Gateway Android SDK to add UPI Intent, web checkout, and seamless payment flows to your native Android app with minimal code.

<div>
  <iframe title="YouTube video player" />

  <a href="https://www.cashfree.com/devstudio/preview/pg/mobile/android">
    <span>
      Try it in DevStudio

      <svg>
        <path />

        <path />
      </svg>
    </span>
  </a>
</div>

Cashfree's Android SDK provides a comprehensive payment solution that integrates the payment gateway into your Android applications, supporting Android SDK version 19 and above. The SDK offers multiple checkout flows including web checkout and UPI Intent checkout.

## Key benefits

The Android SDK offers the following advantages for your payment integration:

* **Multiple checkout flows**: Provides web checkout and UPI Intent checkout options to suit different integration needs.

* **Native Android support**: Optimised for Android SDK version 19 and above with native UI components for UPI payments.

* **Customisable UI**: Allows customisation of themes, colours, and fonts to match your app's design.

* **Secure and compliant**: Securely handles payment processing with built-in security measures managed by the SDK.

## Prerequisites

Ensure you complete the following tasks before starting the integration:

* Create a [Cashfree Merchant Account](https://merchant.cashfree.com/merchants/signup).
* Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and generate an **App ID** and **Secret Key**. Learn how to [generate API keys](/docs/api-reference/authentication#generate-api-keys).
* Ensure your application complies with Cashfree's [Integrity standards](/docs/payments/online/mobile/misc/cashfree_integrity). Applications that don't meet the required integrity standards may be restricted from using production services.

The Android integration consists of three essential steps:

<CardGroup>
  <Card title="Step 1" icon="money-bill-wave" href="/docs/payments/online/mobile/android#step-1-create-an-order-server-side">
    Create an order
  </Card>

  <Card title="Step 2" icon="desktop" href="/docs/payments/online/mobile/android#step-2-open-the-checkout-page-client-side">
    Open the checkout page
  </Card>

  <Card title="Step 3" icon="circle-check" href="/docs/payments/online/mobile/android#step-3-confirm-the-payment-server-side">
    Confirm the payment
  </Card>
</CardGroup>

The step-by-step guide for each step of the integration process is as follows:

## Step 1: Create an order <Badge>Server-side</Badge>

To integrate the Cashfree Payment Gateway, you must first create an order. Complete this step before you process any payments. Configure an endpoint on your server to handle order creation. You can't call this API from the client-side.

<Note>Create orders through your server as this API requires your secret key. Don't call it directly from your mobile application.</Note>

##### API request for creating an order

Here's a sample request for creating an order using your desired backend language. Cashfree offers backend [SDKs](/docs/api-reference/payments/sdk#server-sdk) to simplify the integration process.

<CodeGroup>
  ```bash curl theme={"dark"}
  curl --location 'https://sandbox.cashfree.com/pg/orders' \
  --header 'X-Client-Secret: {{clientKey}}' \
  --header 'X-Client-Id: {{clientId}}' \
  --header 'x-api-version: 2025-01-01' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data-raw '{
    "order_amount": 10.10,
    "order_currency": "INR",
    "customer_details": {
      "customer_id": "USER123",
      "customer_name": "joe",
      "customer_email": "joe.s@cashfree.com",
      "customer_phone": "+919876543210"
    },
    "order_meta": {
      "return_url": "https://b8af79f41056.eu.ngrok.io?order_id=order_123"
    }
  }'
  ```

  ```javascript nodejs theme={"dark"}
  import { Cashfree, CFEnvironment } from "cashfree-pg";

  const cashfree = new Cashfree(
  	CFEnvironment.PRODUCTION,
  	"{Client ID}",
  	"{Client Secret Key}"
  );

  function createOrder() {
  	var request = {
  		order_amount: "1",
  		order_currency: "INR",
  		customer_details: {
  			customer_id: "node_sdk_test",
  			customer_name: "",
  			customer_email: "example@gmail.com",
  			customer_phone: "9999999999",
  		},
  		order_meta: {
  			return_url:
  				"https://test.cashfree.com/pgappsdemos/return.php?order_id=order_123",
  		},
  		order_note: "",
  	};

  	cashfree
  		.PGCreateOrder(request)
  		.then((response) => {
  			console.log("Order created successfully:", response.data);
  		})
  		.catch((error) => {
  			console.error("Error setting up order request:", error.response.data);
  		});
  }
  ```

  ```python python theme={"dark"}
  from cashfree_pg.models.create_order_request import CreateOrderRequest
  from cashfree_pg.api_client import Cashfree
  from cashfree_pg.models.customer_details import CustomerDetails


  Cashfree.XClientId = {Client ID}
  Cashfree.XClientSecret = {Client Secret Key}
  Cashfree.XEnvironment = Cashfree.XSandbox
  x_api_version = "2023-08-01"

  def create_order():
          customerDetails = CustomerDetails(customer_id="123", customer_phone="9999999999")
          createOrderRequest = CreateOrderRequest(order_amount=1, order_currency="INR", customer_details=customerDetails)
          try:
              api_response = Cashfree().PGCreateOrder(x_api_version, createOrderRequest, None, None)
              print(api_response.data)
          except Exception as e:
              print(e)
  ```

  ```java java theme={"dark"}
  import com.cashfree.*;

  Cashfree.XClientId = {Client Key};
  Cashfree.XClientSecret = {Client Secret Key};
  Cashfree.XEnvironment = Cashfree.SANDBOX;

  static void createOrder() {
    CustomerDetails customerDetails = new CustomerDetails();
    customerDetails.setCustomerId("123");
    customerDetails.setCustomerPhone("9999999999");

    CreateOrderRequest request = new CreateOrderRequest();
    request.setOrderAmount(1.0);
    request.setOrderCurrency("INR");
    request.setCustomerDetails(customerDetails);
    try {
      Cashfree cashfree = new Cashfree();
      ApiResponse<OrderEntity> response = cashfree.PGCreateOrder("2023-08-01", request, null, null, null);
      System.out.println(response.getData().getOrderId());

    } catch (ApiException e) {
      throw new RuntimeException(e);
    }
  }
  ```

  ```go go theme={"dark"}
  import (
    cashfree "github.com/cashfree/cashfree-pg/v3"
  )

  func createOrder() {

  clientId := {Client ID}
  clientSecret := {Client Secret Key}
  cashfree.XClientId = &clientId
  cashfree.XClientSecret = &clientSecret
  cashfree.XEnvironment = cashfree.SANDBOX

  request := cashfree.CreateOrderRequest{
  		OrderAmount: 1,
  		CustomerDetails: cashfree.CustomerDetails{
  			CustomerId:    "1",
  			CustomerPhone: "9999999999",
  		},
  		OrderCurrency: "INR",
  		OrderSplits:   []cashfree.VendorSplit{},
  	}
  	version := "2023-08-01"
  	response, httpResponse, err := cashfree.PGCreateOrder(&version, &request, nil, nil, nil)
  	if err != nil {
  		fmt.Println(err.Error())
  	} else {
  		fmt.Println(httpResponse.StatusCode)
  		fmt.Println(response)
      }
  }
  ```

  ```csharp .net theme={"dark"}
  using cashfree_pg.Client;
  using cashfree_pg.Model;

  Cashfree.XClientId = {Client ID};
  Cashfree.XClientSecret = {Client Secret Key};
  Cashfree.XEnvironment = Cashfree.PRODUCTION;
  var cashfree = new Cashfree();
  var xApiVersion = "2023-08-01";

  void CreateOrder() {
      var customerDetails = new CustomerDetails("123", null, "9999999999");
      var createOrdersRequest = new CreateOrderRequest(null, 1.0, "INR", customerDetails);
      try {
          // Create Order
          var result = cashfree.PGCreateOrder(xApiVersion, createOrdersRequest, null, null, null);
          Console.WriteLine(result);
          Console.WriteLine(result.StatusCode);
          Console.WriteLine((result.Content as OrderEntity));
      } catch (ApiException e) {
          Console.WriteLine("Exception when calling PGCreateOrder: " + e.Message);
          Console.WriteLine("Status Code: " + e.ErrorCode);
          Console.WriteLine(e.StackTrace);
      }
  }
  ```

  ```php php theme={"dark"}
  \Cashfree\Cashfree::$XClientId = "<x-client-id>";
  \Cashfree\Cashfree::$XClientSecret = "<x-client-secret>";
  \Cashfree\Cashfree::$XEnvironment = Cashfree\Cashfree::$SANDBOX;

  $cashfree = new \Cashfree\Cashfree();

  $x_api_version = "2023-08-01";
  $create_orders_request = new \Cashfree\Model\CreateOrdersRequest();
  $create_orders_request->setOrderAmount(1.0);
  $create_orders_request->setOrderCurrency("INR");
  $customer_details = new \Cashfree\Model\CustomerDetails();
  $customer_details->setCustomerId("123");
  $customer_details->setCustomerPhone("9999999999");
  $create_orders_request->setCustomerDetails($customer_details);

  try {
      $result = $cashfree->PGCreateOrder($x_api_version, $create_orders_request);
      print_r($result);
  } catch (Exception $e) {
      echo 'Exception when calling PGCreateOrder: ', $e->getMessage(), PHP_EOL;
  }
  ```
</CodeGroup>

After successfully creating an order, you will receive a unique `order_id` and `payment_session_id` that you need for subsequent steps.

You can view the complete API request and response for `/orders` in the [Create Order API](/docs/api-reference/payments/latest/orders/create-order).

<Note>
  To show a short purchase description on checkout, such as a booking reference or route, add `checkout_context` to the `order_tags` object in the Create Order request above.

  ```json theme={"dark"}
  "order_tags": {
    "checkout_context": "Flight booking DEL-BOM, 12 JUN at 14:30"
  }
  ```

  For details about how checkout displays this text in a context card, see [Contextual Checkout](/docs/payments/features/contextual-checkout).
</Note>

## Step 2: Open the checkout page <Badge>Client-side</Badge>

Once the order is created, the next step is to open the payment page so the customer can make the payment.

### 1. Set up the SDK

The Cashfree Android SDK is hosted on Maven Central. You can download the latest version [2.4.0](https://github.com/cashfree/nextgen-android). The Android SDK supports Android SDK version 19 and above.

Add the following dependency to your app's `build.gradle` file:

```gradle theme={"dark"}
implementation 'com.cashfree.pg:api:2.4.0'
```

On Android 11 and later (API level 30+), apps must declare which packages they intend to query before they can detect installed UPI applications. Add the following `<queries>` block to your `AndroidManifest.xml`:

```xml AndroidManifest.xml theme={"dark"}
<queries>
    <intent>
        <action android:name="android.intent.action.VIEW" />
        <data android:scheme="upi" />
    </intent>
    <intent>
        <action android:name="android.intent.action.VIEW" />
        <data android:scheme="tez" />
    </intent>
    <intent>
        <action android:name="android.intent.action.VIEW" />
        <data android:scheme="gpay" />
    </intent>
    <intent>
        <action android:name="android.intent.action.VIEW" />
        <data android:scheme="phonepe" />
    </intent>
    <intent>
        <action android:name="android.intent.action.VIEW" />
        <data android:scheme="paytmmp" />
    </intent>
    <intent>
        <action android:name="android.intent.action.VIEW" />
        <data android:scheme="credpay" />
    </intent>
</queries>
```

Without this declaration, `queryIntentActivities` returns an empty list on Android 11 and later, and UPI apps do not appear in UPI Intent checkout.

### 2. Select a payment flow

The Android SDK offers the following payment flows:

<AccordionGroup>
  <Accordion title="Web Checkout">
    In this flow, the SDK provides a webview-based checkout implementation to facilitate a quick integration with the payment gateway. Your customers can fill in the necessary details in the web page and complete the payment.
    This mode handles all the business logic and UI components to make the payment smooth and easy to use.
  </Accordion>

  <Accordion title="UPI Intent Checkout">
    This flow is for merchants who want to provide UPI Intent functionality using Cashfree's mobile SDK. In this flow, the SDK provides a pre-built native Android screen to facilitate integration with the payment gateway. Your customers see a list of UPI apps installed on their phone which they can select to initiate payment.
    This mode handles all the business logic and UI components to make the payment smooth and easy to use. The SDK allows you to customise the UI in terms of colour coding and fonts.
  </Accordion>
</AccordionGroup>

### 3. Complete the payment

To complete the payment, follow these steps:

1. Create a `CFSession` object.
2. Create a `CFTheme` object.
3. Create a `CFWebCheckoutPayment` or `CFUPIIntentCheckoutPayment` object.
4. Set up payment callback.
5. Initiate the payment using the payment object.

#### Create a session

This object contains essential information about the order, including the payment session ID (`payment_session_id`) and order ID (`order_id`) obtained from Step 1. It also specifies the environment (sandbox or production).

<CodeGroup>
  ```java java theme={"dark"}
  CFSession cfSession = new CFSession.CFSessionBuilder()
          .setEnvironment(CFSession.Environment.SANDBOX)
          .setPaymentSessionID("paymentSessionID")
          .setOrderId("orderID")
          .build();
  ```

  ```kotlin kotlin theme={"dark"}
  val cfSession = CFSessionBuilder()
      .setEnvironment(CFSession.Environment.SANDBOX)
      .setPaymentSessionID("paymentSessionID")
      .setOrderId("orderID")
      .build()
  ```
</CodeGroup>

#### Customise theme (optional)

You can customise the appearance of the checkout screen using CFTheme. This step is optional but can help maintain consistency with your app's design.

<AccordionGroup>
  <Accordion title="Web Checkout">
    <CodeGroup>
      ```java java theme={"dark"}
      CFWebCheckoutTheme cfTheme = new CFWebCheckoutTheme.CFWebCheckoutThemeBuilder()
          .setNavigationBarBackgroundColor("#6A3FD3")
          .setNavigationBarTextColor("#FFFFFF")
          .build();

      ```

      ```kotlin kotlin theme={"dark"}
      val cfTheme = CFWebCheckoutThemeBuilder()
          .setNavigationBarBackgroundColor("#000000")
          .setNavigationBarTextColor("#FFFFFF")
          .build()

      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="UPI Intent Checkout">
    <CodeGroup>
      ```java java theme={"dark"}
      CFIntentTheme cfTheme = new CFIntentTheme.CFIntentThemeBuilder()
          .setPrimaryTextColor("#000000")
          .setBackgroundColor("#FFFFFF")
          .build();

      ```

      ```kotlin kotlin theme={"dark"}
      val cfTheme = CFIntentThemeBuilder()
          .setPrimaryTextColor("#000000")
          .setBackgroundColor("#FFFFFF")
          .build()
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

#### Create checkout payment object

<AccordionGroup>
  <Accordion title="Web Checkout">
    This object combines all the configurations (session, theme) into a single checkout configuration. Finally, call `doPayment()` to open the Cashfree web checkout screen. This will present the user with the payment options and handle the payment process.

    <CodeGroup>
      ```java java theme={"dark"}
      CFWebCheckoutPayment cfWebCheckoutPayment = new CFWebCheckoutPayment.CFWebCheckoutPaymentBuilder()
          .setSession(cfSession)
          .setCFWebCheckoutUITheme(cfTheme)
          .build();
      ```

      ```kotlin kotlin theme={"dark"}
      val cfWebCheckoutPayment = CFWebCheckoutPaymentBuilder()
        .setSession(cfSession)
        .setCFWebCheckoutUITheme(cfTheme)
        .build()
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="UPI Intent Checkout">
    Use `CFUPIIntentCheckoutPayment` to create the payment object for UPI Intent flow. This object accepts a `CFSession` and theme configuration.

    <CodeGroup>
      ```java java theme={"dark"}
      CFUPIIntentCheckout cfupiIntentCheckout = new CFUPIIntentCheckout.CFUPIIntentBuilder()
              // Use either the enum or the application package names to order the UPI apps as per your needed
              // Remove both if you want to use the default order which cashfree provides based on the popularity
              // NOTE - only one is needed setOrder or setOrderUsingPackageName
              .setOrder(Arrays.asList(CFUPIIntentCheckout.CFUPIApps.BHIM, CFUPIIntentCheckout.CFUPIApps.PHONEPE))
              .setOrderUsingPackageName(Arrays.asList("com.dreamplug.androidapp", "in.org.npci.upiapp"))
              .build();

      CFUPIIntentCheckoutPayment cfupiIntentCheckoutPayment = new CFUPIIntentCheckoutPayment.CFUPIIntentPaymentBuilder()
              .setSession(cfSession)
              .setCfUPIIntentCheckout(cfupiIntentCheckout)
              .setCfIntentTheme(cfTheme)
              .build();
      ```

      ```kotlin kotlin theme={"dark"}
      val cfupiIntentCheckout = CFUPIIntentBuilder() // Use either the enum or the application package names to order the UPI apps as per your needed
              // Remove both if you want to use the default order which cashfree provides based on the popularity
              // NOTE - only one is needed setOrder or setOrderUsingPackageName
              .setOrderUsingPackageName(Arrays.asList("com.dreamplug.androidapp", "in.org.npci.upiapp"))
              .setOrder(Arrays.asList(CFUPIIntentCheckout.CFUPIApps.BHIM, CFUPIIntentCheckout.CFUPIApps.PHONEPE))
              .build()

      val cfupiIntentCheckoutPayment = CFUPIIntentPaymentBuilder()
              .setSession(cfSession)
              .setCfUPIIntentCheckout(cfupiIntentCheckout)
              .setCfIntentTheme(cfTheme)
              .build()
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

#### Set up payment callback

The SDK exposes an interface `CFCheckoutResponseCallback` to receive callbacks from the SDK once the payment journey ends.

This interface consists of 2 methods:

<CodeGroup>
  ```java java theme={"dark"}
  public void onPaymentVerify(String orderID)
  public void onPaymentFailure(CFErrorResponse cfErrorResponse, String orderID)
  ```

  ```kotlin kotlin theme={"dark"}
  fun onPaymentVerify(orderID: String)
  fun onPaymentFailure(cfErrorResponse: CFErrorResponse, orderID: String) 
  ```
</CodeGroup>

<Tip>Make sure to set the callback at activity's onCreate as this also handles the activity restart cases.</Tip>

<CodeGroup>
  ```java java theme={"dark"}
  public class YourActivity extends AppCompatActivity implements CFCheckoutResponseCallback {
      ...
      @Override
      public void onPaymentVerify(String orderID) {

      }

      @Override
      public void onPaymentFailure(CFErrorResponse cfErrorResponse, String orderID) {

      }

      @Override
      protected void onCreate(Bundle savedInstanceState) {
          super.onCreate(savedInstanceState);
          setContentView(R.layout.activity_upi_intent_checkout);
          try {
            // If you are using a fragment then you need to add this line inside onCreate() of your Fragment
              CFPaymentGatewayService.getInstance().setCheckoutCallback(this);
          } catch (CFException e) {
              e.printStackTrace();
          }
      }
      ...

  }

  ```

  ```kotlin kotlin theme={"dark"}
  class YourActivity : AppCompatActivity(), CFCheckoutResponseCallback {

      override fun onCreate(savedInstanceState: Bundle?) {
          super.onCreate(savedInstanceState)
          setContentView(R.layout.activity_drop_checkout)
          try {
              CFPaymentGatewayService.getInstance().setCheckoutCallback(this)
          } catch (e: CFException) {
              e.printStackTrace()
          }
      }

      override fun onPaymentVerify(orderID: String) {
          Log.d("onPaymentVerify", "verifyPayment triggered")
      }

      override fun onPaymentFailure(cfErrorResponse: CFErrorResponse, orderID: String) {
          Log.e("onPaymentFailure $orderID", cfErrorResponse.message)
      }
  ...
  }
  ```
</CodeGroup>

#### Initiate the payment

Finally, call `doPayment()` to open the Cashfree checkout screen. This will present the user with the payment options and handle the payment process.

<AccordionGroup>
  <Accordion title="Web Checkout">
    <CodeGroup>
      ```java java theme={"dark"}
      // replace the WebCheckoutActivity class with your class name
      CFPaymentGatewayService.getInstance().doPayment(WebCheckoutActivity.this, cfWebCheckoutPayment);
      ```

      ```kotlin kotlin theme={"dark"}
      // replace the WebCheckoutActivity class with your class name
      CFPaymentGatewayService.getInstance().doPayment(this@WebCheckoutActivity, cfWebCheckoutPayment)
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="UPI Intent Checkout">
    <CodeGroup>
      ```java java theme={"dark"}
      // replace the UPIIntentCheckoutActivity class with your class name
      CFPaymentGatewayService.getInstance().doPayment(UPIIntentCheckoutActivity.this, cfupiIntentCheckoutPayment);
      ```

      ```kotlin kotlin theme={"dark"}
      // replace the UPIIntentCheckoutActivity class with your class name
      CFPaymentGatewayService.getInstance().doPayment(this@UPIIntentCheckoutActivity, cfupiIntentCheckoutPayment)
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

#### Sample code

<AccordionGroup>
  <Accordion title="Web Checkout Sample code">
    <CodeGroup>
      ```java java theme={"dark"}
      package com.cashfree.sdk_sample;

      import android.content.Intent;
      import android.os.Bundle;
      import android.util.Log;

      import androidx.appcompat.app.AppCompatActivity;

      import com.cashfree.pg.api.CFPaymentGatewayService;
      import com.cashfree.pg.core.api.CFSession;
      import com.cashfree.pg.core.api.webcheckout.CFTheme;
      import com.cashfree.pg.core.api.callback.CFCheckoutResponseCallback;
      import com.cashfree.pg.core.api.exception.CFException;
      import com.cashfree.pg.core.api.utils.CFErrorResponse;
      import com.cashfree.pg.core.api.webcheckout.CFWebCheckoutPayment;
      import com.cashfree.pg.core.api.callback.CFCheckoutResponseCallback;

      public class WebCheckoutActivity extends AppCompatActivity implements CFCheckoutResponseCallback {

          String orderID = "ORDER_ID";
          String paymentSessionID = "TOKEN";
          CFSession.Environment cfEnvironment = CFSession.Environment.PRODUCTION;

          @Override
          protected void onCreate(Bundle savedInstanceState) {
              super.onCreate(savedInstanceState);
              setContentView(R.layout.activity_drop_checkout);
              try {
                  CFPaymentGatewayService.getInstance().setCheckoutCallback(this);
              } catch (CFException e) {
                  e.printStackTrace();
              }
          }

          @Override
          public void onPaymentVerify(String orderID) {
              Log.e("onPaymentVerify", "verifyPayment triggered");
             // Start verifying your payment
          }

          @Override
          public void onPaymentFailure(CFErrorResponse cfErrorResponse, String orderID) {
              Log.e("onPaymentFailure " + orderID, cfErrorResponse.getMessage());
          }

          public void doWebCheckoutPayment() {
              try {
                  CFSession cfSession = new CFSession.CFSessionBuilder()
                          .setEnvironment(cfEnvironment)
                          .setPaymentSessionID(paymentSessionID)
                          .setOrderId(orderID)
                          .build();
                  // Replace with your application's theme colors
                  CFWebCheckoutTheme cfTheme = new CFWebCheckoutTheme.CFWebCheckoutThemeBuilder()
                          .setNavigationBarBackgroundColor("#fc2678")
                          .setNavigationBarTextColor("#ffffff")
                          .build();
                  CFWebCheckoutPayment cfWebCheckoutPayment = new CFWebCheckoutPayment.CFWebCheckoutPaymentBuilder()
                          .setSession(cfSession)
                          .setCFWebCheckoutUITheme(cfTheme)
                          .build();
                  CFPaymentGatewayService.getInstance().doPayment(WebCheckoutActivity.this, cfWebCheckoutPayment);
              } catch (CFException exception) {
                  exception.printStackTrace();
              }
          }

      }
      ```

      ```kotlin kotlin theme={"dark"}

      package com.cashfree.sdk_sample.kotlin

      import androidx.appcompat.app.AppCompatActivity
      import com.cashfree.pg.core.api.callback.CFCheckoutResponseCallback
      import com.cashfree.pg.core.api.CFSession
      import android.os.Bundle
      import com.cashfree.sdk_sample.R
      import com.cashfree.pg.api.CFPaymentGatewayService
      import android.content.Intent
      import android.app.Activity
      import com.cashfree.pg.core.api.utils.CFErrorResponse
      import android.text.TextUtils
      import android.util.Log
      import android.widget.Toast
      import com.cashfree.pg.core.api.CFSession.CFSessionBuilder
      import com.cashfree.pg.core.api.exception.CFException
      import com.cashfree.pg.core.api.webcheckout.CFWebCheckoutTheme
      import com.cashfree.pg.core.api.webcheckout.CFWebCheckoutTheme.CFWebCheckoutThemeBuilder
      import com.cashfree.pg.core.api.webcheckout.CFWebCheckoutPayment
      import com.cashfree.pg.core.api.webcheckout.CFWebCheckoutPayment.CFWebCheckoutPaymentBuilder

      class WebCheckoutActivity : AppCompatActivity(), CFCheckoutResponseCallback { var orderID = "ORDER_ID" var paymentSessionID = "PAYMENT_SESSION_ID" var cfEnvironment = CFSession.Environment.PRODUCTION override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) setContentView(R.layout.activity_drop_checkout) try { CFPaymentGatewayService.getInstance().setCheckoutCallback(this) } catch (e: CFException) { e.printStackTrace() } }

          var cfEnvironment = CFSession.Environment.SANDBOX
          override fun onPaymentVerify(orderID: String) {
              Log.d("onPaymentVerify", "verifyPayment triggered")
          }

          override fun onPaymentFailure(cfErrorResponse: CFErrorResponse, orderID: String) {
              Log.e("onPaymentFailure $orderID", cfErrorResponse.message)
          }

          fun doWebCheckoutPayment() {
              try {
                  val cfSession = CFSessionBuilder()
                      .setEnvironment(cfEnvironment)
                      .setPaymentSessionID(paymentSessionID)
                      .setOrderId(orderID)
                      .build()
                  val cfTheme = CFWebCheckoutThemeBuilder()
                      .setNavigationBarBackgroundColor("#000000")
                      .setNavigationBarTextColor("#FFFFFF")
                      .build()
                  val cfWebCheckoutPayment = CFWebCheckoutPaymentBuilder()
                      .setSession(cfSession)
                      .setCFWebCheckoutUITheme(cfTheme)
                      .build()
                  CFPaymentGatewayService.getInstance().doPayment(this@WebCheckoutActivity, cfWebCheckoutPayment)
              } catch (exception: CFException) {
                  exception.printStackTrace()
              }
          }

      } 
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="UPI Intent Checkout Sample code">
    <CodeGroup>
      ```java java theme={"dark"}
      package com.cashfree.sdk_sample;

      import android.content.Intent;
      import android.os.Bundle;
      import android.util.Log;

      import androidx.appcompat.app.AppCompatActivity;

      import com.cashfree.pg.api.CFPaymentGatewayService;
      import com.cashfree.pg.core.api.CFSession;
      import com.cashfree.pg.core.api.CFTheme;
      import com.cashfree.pg.core.api.callback.CFCheckoutResponseCallback;
      import com.cashfree.pg.core.api.exception.CFException;
      import com.cashfree.pg.core.api.utils.CFErrorResponse;
      import com.cashfree.pg.ui.api.upi.intent.CFIntentTheme;
      import com.cashfree.pg.ui.api.upi.intent.CFUPIIntentCheckout;
      import com.cashfree.pg.ui.api.upi.intent.CFUPIIntentCheckoutPayment;

      public class UPIIntentCheckoutActivity extends AppCompatActivity implements CFCheckoutResponseCallback {

          String orderID = "ORDER_ID";
          String paymentSessionID = "PAYMENT_SESSION_ID";
          CFSession.Environment cfEnvironment = CFSession.Environment.SANDBOX;

          @Override
          protected void onCreate(Bundle savedInstanceState) {
              super.onCreate(savedInstanceState);
              setContentView(R.layout.activity_upi_intent_checkout);
              try {
                  CFPaymentGatewayService.getInstance().setCheckoutCallback(this);
              } catch (CFException e) {
                  e.printStackTrace();
              }
          }

          @Override
          public void onPaymentVerify(String orderID) {
              Log.e("onPaymentVerify", "verifyPayment triggered");
              // Start verifying your payment
          }

          @Override
          public void onPaymentFailure(CFErrorResponse cfErrorResponse, String orderID) {
              Log.e("onPaymentFailure " + orderID, cfErrorResponse.getMessage());
          }

          public void doUPIIntentCheckoutPayment() {
              try {
                  CFSession cfSession = new CFSession.CFSessionBuilder()
                          .setEnvironment(cfEnvironment)
                          .setOrderToken(token)
                          .setOrderId(orderID)
                          .build();
                  // Replace with your application's theme colors
                  CFIntentTheme cfTheme = new CFIntentTheme.CFIntentThemeBuilder()
                          .setButtonBackgroundColor("#6A3FD3")
                          .setButtonTextColor("#FFFFFF")
                          .setPrimaryTextColor("#000000")
                          .setSecondaryTextColor("#000000")
                          .build();

                  CFUPIIntentCheckout cfupiIntentCheckout = new CFUPIIntentCheckout.CFUPIIntentBuilder()
                          // Use either the enum or the application package names to order the UPI apps as per your needed
                          // Remove both if you want to use the default order which cashfree provides based on the popularity
                          // NOTE - only one is needed setOrder or setOrderUsingPackageName
                          .setOrder(Arrays.asList(CFUPIIntentCheckout.CFUPIApps.BHIM, CFUPIIntentCheckout.CFUPIApps.PHONEPE))
                          .setOrderUsingPackageName(Arrays.asList("com.dreamplug.androidapp", "in.org.npci.upiapp"))
                          .build();

                  CFUPIIntentCheckoutPayment cfupiIntentCheckoutPayment = new CFUPIIntentCheckoutPayment.CFUPIIntentPaymentBuilder()
                          .setSession(cfSession)
                          .setCfUPIIntentCheckout(cfupiIntentCheckout)
                          .setCfIntentTheme(cfTheme)
                          .build();
                  CFPaymentGatewayService.getInstance().doPayment(UPIIntentCheckoutActivity.this, cfupiIntentCheckoutPayment);
              } catch (CFException exception) {
                  exception.printStackTrace();
              }
          }

      }
      ```

      ```kotlin kotlin theme={"dark"}
      package com.cashfree.sdk_sample.kotlin

      import androidx.appcompat.app.AppCompatActivity
      import com.cashfree.pg.core.api.callback.CFCheckoutResponseCallback
      import com.cashfree.pg.core.api.CFSession
      import android.os.Bundle
      import com.cashfree.sdk_sample.R
      import com.cashfree.pg.api.CFPaymentGatewayService
      import android.content.Intent
      import android.app.Activity
      import com.cashfree.pg.core.api.utils.CFErrorResponse
      import android.text.TextUtils
      import android.util.Log
      import android.widget.Toast
      import com.cashfree.pg.core.api.CFSession.CFSessionBuilder
      import com.cashfree.pg.core.api.exception.CFException
      import com.cashfree.pg.ui.api.upi.intent.CFIntentTheme
      import com.cashfree.pg.ui.api.upi.intent.CFIntentTheme.CFIntentThemeBuilder
      import com.cashfree.pg.ui.api.upi.intent.CFUPIIntentCheckout
      import com.cashfree.pg.ui.api.upi.intent.CFUPIIntentCheckout.CFUPIIntentBuilder
      import com.cashfree.pg.ui.api.upi.intent.CFUPIIntentCheckoutPayment
      import com.cashfree.pg.ui.api.upi.intent.CFUPIIntentCheckoutPayment.CFUPIIntentPaymentBuilder

      class UPIIntentCheckoutActivity : AppCompatActivity(), CFCheckoutResponseCallback {
          var orderID = "ORDER_ID"
          var token = "TOKEN"
          var cfEnvironment = CFSession.Environment.SANDBOX
          override fun onCreate(savedInstanceState: Bundle?) {
              super.onCreate(savedInstanceState)
              setContentView(R.layout.activity_drop_checkout)
              try {
                  CFPaymentGatewayService.getInstance().setCheckoutCallback(this)
                  doDropCheckoutPayment()
              } catch (e: CFException) {
                  e.printStackTrace()
              }
          }

          override fun onPaymentVerify(orderID: String) {
              Log.d("onPaymentVerify", "verifyPayment triggered")
          }

          override fun onPaymentFailure(cfErrorResponse: CFErrorResponse, orderID: String) {
              Log.e("onPaymentFailure $orderID", cfErrorResponse.message)
          }

          fun doUPIIntentCheckoutPayment() {
              try {
                  val cfSession = CFSessionBuilder()
                      .setEnvironment(cfEnvironment)
                      .setPaymentSessionID(token)
                      .setOrderId(orderID)
                      .build()
                  val cfTheme = CFIntentThemeBuilder()
                      .setPrimaryTextColor("#000000")
                      .setBackgroundColor("#FFFFFF")
                      .build()
                  val cfupiIntentCheckout = CFUPIIntentBuilder() 
                      // Use either the enum or the application package names to order the UPI apps as per your needed
                      // Remove both if you want to use the default order which cashfree provides based on the popularity
                      // NOTE - only one is needed setOrder or setOrderUsingPackageName
                      .setOrderUsingPackageName(Arrays.asList("com.dreamplug.androidapp", "in.org.npci.upiapp"))
                      .setOrder(Arrays.asList(CFUPIIntentCheckout.CFUPIApps.BHIM, CFUPIIntentCheckout.CFUPIApps.PHONEPE))
                      .build()
                  val cfupiIntentCheckoutPayment = CFUPIIntentPaymentBuilder()
                      .setSession(cfSession)
                      .setCfUPIIntentCheckout(cfupiIntentCheckout)
                      .setCfIntentTheme(cfTheme)
                      .build()
                  CFPaymentGatewayService.getInstance().doPayment(this@UPIIntentActivity, cfupiIntentCheckoutPayment)
              } catch (exception: CFException) {
                  exception.printStackTrace()
              }
          }
      }
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

#### Sample GitHub code

<AccordionGroup>
  <Accordion title="Android Integration">
    [GitHub Sample](https://github.com/cashfree/nextgen-android)
  </Accordion>
</AccordionGroup>

## Step 3: Confirm the payment <Badge>Server-side</Badge>

After the customer completes the payment, you must confirm the payment status. Once the payment finishes, the user redirects back to your activity.

To verify an order you can call our `/pg/orders` endpoint from your backend. You can also use our SDK to achieve the same.

<CodeGroup>
  ```bash curl theme={"dark"}
  curl --request GET \
       --url https://sandbox.cashfree.com/pg/orders/{order_id} \
       --header 'accept: application/json' \
       --header 'x-api-version: 2025-01-01' \
       --header 'x-client-id: "YOUR APP ID GOES HERE"' \
       --header 'x-client-secret: "YOUR SECRET KEY GOES HERE"'
  ```

  ```javascript nodejs theme={"dark"}
  cashfree
  .PGFetchOrder("<order_id>")
  .then((response) => {
  	console.log("Order fetched successfully:", response.data);
  })
  .catch((error) => {
  	console.error("Error:", error.response.data.message);
  });
  ```

  ```python python theme={"dark"}
  from cashfree_pg.models.create_order_request import CreateOrderRequest
  from cashfree_pg.api_client import Cashfree
  from cashfree_pg.models.customer_details import CustomerDetails
  from cashfree_pg.models.order_meta import OrderMeta

  Cashfree.XClientId = "<x-client-id>"
  Cashfree.XClientSecret = "<x-client-secret>"
  Cashfree.XEnvironment = Cashfree.SANDBOX
  x_api_version = "2023-08-01"

  try:
      api_response = Cashfree().PGFetchOrder(x_api_version, "order_3242X4jQ5f0S9KYxZO9mtDL1Kx2Y7u", None)
      print(api_response.data)
  except Exception as e:
      print(e)

  ```

  ```java java theme={"dark"}
  import com.cashfree.*;
  //other code

  try {
      Cashfree.XClientId = "<x-client-id>";
      Cashfree.XClientSecret = "<x-client-secret>";
      Cashfree.XEnvironment = Cashfree.SANDBOX;

      Cashfree cashfree = new Cashfree();
      String xApiVersion = "2023-08-01";

      ApiResponse<OrderEntity> responseFetchOrder = cashfree.PGFetchOrder(xApiVersion, "<order_id>", null, null, null);
      System.out.println(response.getData().getOrderId());
  } catch (ApiException e) {
      throw new RuntimeException(e);
  }
  ```

  ```go go theme={"dark"}
  version := "2023-08-01"
  response, httpResponse, err := cashfree.PGFetchOrder(&version, "<order_id>", nil, nil, nil)
  if err != nil {
  	fmt.Println(err.Error())
  } else {
  	fmt.Println(httpResponse.StatusCode)
  	fmt.Println(response)
  }
  ```

  ```csharp .net theme={"dark"}
  using cashfree_pg.Client;
  using cashfree_pg.Model;

  Cashfree.XClientId = "<x-client-id>";
  Cashfree.XClientSecret = "<x-client-secret>";
  Cashfree.XEnvironment = Cashfree.SANDBOX;
  var cashfree = new Cashfree();
  var xApiVersion = "2023-08-01";

  try {
      var result = cashfree.PGFetchOrder(xApiVersion, "<order_id>>", null, null);
      Console.WriteLine(result);
      Console.WriteLine(result.StatusCode);
      Console.WriteLine((result.Content as OrderEntity));
  } catch (ApiException e) {
      Console.WriteLine("Exception when calling PGFetchOrder: " + e.Message);
      Console.WriteLine("Status Code: " + e.ErrorCode);
      Console.WriteLine(e.StackTrace);
  }
  ```

  ```php php theme={"dark"}
  $x_api_version = "2023-08-01";
  try {
      $response = $cashfree->PGFetchOrder($x_api_version, "<order_id>");
      print_r($response);
  } catch (Exception $e) {
      echo 'Exception when calling PGFetchOrder: ', $e->getMessage(), PHP_EOL;
  }
  ```
</CodeGroup>

<Note>
  Always verify the order status before you deliver services to the customer. You can use the [Get Order API](/docs/api-reference/payments/latest/orders/get-order) for this. An order is successful when the `order_status` is `PAID`.
</Note>

## Testing

After you integrate the checkout functionality, verify that it opens the Cashfree-hosted payment page. Follow these steps to test:

1. Click the checkout button.
2. Verify you're redirected to the Cashfree Checkout payment page.

## Error codes

To confirm the error returned in your Android application, you can view the error codes that are exposed by the SDK.

<Accordion title="Show error codes">
  | Error codes | Message |
  | - | - |
  | MISSING\_CALLBACK | The callback is missing in the request. |
  | ORDER\_ID\_MISSING | The "order\_id" is missing in the request. |
  | CARD\_EMI\_TENURE\_MISSING | The "emi\_tenure" is missing or invalid (It has to be greater than 0). |
  | INVALID\_UPI\_APP\_ID\_SENT | The id sent is invalid. The value has to be one of the following: "tez://","phonepe://","paytm://","bhim://. Please refer the note in CFUPI class for more details" |
  | INVALID\_PAYMENT\_OBJECT\_SENT | The payment object that's set doesn't match any payment mode. Please set the correct payment mode and try again. |
  | WALLET\_OBJECT\_MISSING | The CFWallet object is missing in the request |
  | NETBANKING\_OBJECT\_MISSING | The CFNetbanking object is missing in the request. |
  | UPI\_OBJECT\_MISSING | The CFUPI object is missing in the request. |
  | CARD\_OBJECT\_MISSING | The CFCard object is missing in the request. |
  | INVALID\_WEB\_DATA | The url seems to be corrupt. Please reinstantiate the order. |
  | SESSION\_OBJECT\_MISSING | The "session" is missing in the request |
  | PAYMENT\_OBJECT\_MISSING | The "payment" is missing in the request |
  | ENVIRONMENT\_MISSING | The "environment" is missing in the request. |
  | ORDER\_TOKEN\_MISSING | The "order\_token" is missing in the request. |
  | CHANNEL\_MISSING | The "channel" is missing in the request. |
  | CARD\_NUMBER\_MISSING | The "card\_number" is missing in the request. |
  | CARD\_EXPIRY\_MONTH\_MISSING | The "card\_expiry\_mm" is missing in the request. |
  | CARD\_EXPIRY\_YEAR\_MISSING | The "card\_expiry\_yy" is missing in the request. |
  | CARD\_CVV\_MISSING | The "card\_cvv" is missing in the request. |
  | UPI\_ID\_MISSING | The "upi\_id" is missing in the request |
  | WALLET\_CHANNEL\_MISSING | The "channel" is missing in the wallet payment request |
  | WALLET\_PHONE\_MISSING | The "phone number" is missing in the wallet payment request |
  | NB\_BANK\_CODE\_MISSING | The "bank\_code" is missing in the request |
  | WRONG\_CALLING\_CONTEXT | Calling context must be activity or fragment |
  | NO\_UPI\_APP\_AVAILABLE | You don't have any UPI apps installed or ready for payment. |
  | NO\_EMI\_PLAN\_AVAILABLE | This account doesn't have EMI plans configured, or the order amount is less than 2499 |
</Accordion>

### Other options

<AccordionGroup>
  <Accordion title="(Optional) Custom Initialisation of the SDK">
    If you require to initialise the SDK yourself then follow the steps below. Make sure to initialise the SDK in Application class to avoid any Runtime issues.

    <Steps>
      <Step title="Add the following to your values.xml file">
        `<bool name="cashfree_pg_core_auto_initialize_enabled">false</bool>`
      </Step>

      <Step title="Initialise the SDK yourself before attempting payment">
        <CodeGroup>
          ```java java theme={"dark"}
             Executors.newSingleThreadExecutor().execute(() -> { 
                  CFPaymentGatewayService.initialize(getApplicationContext());
             });
          ```

          ```kotlin kotlin theme={"dark"}
             Executors.newSingleThreadExecutor().execute {
                CFPaymentGatewayService.initialize(applicationContext)
             }
          ```
        </CodeGroup>
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="(Optional) Enable logging to debugging issues">
    To enable SDK logging add the following to your `values.xml` file.

    `<integer name="cashfree_pg_logging_level">3</integer>`

    Following are the Logging levels.

    * VERBOSE = 2
    * DEBUG = 3
    * INFO = 4
    * WARN = 5
    * ERROR = 6
    * ASSERT = 7
  </Accordion>

  <Accordion title="(Optional) Disable Quick Checkout in Payment Page">
    If you want to disable quick checkout flow in the payment journey you can add the following to your values.xml file.

    `<bool name="cf_quick_checkout_enabled">false</bool>`
  </Accordion>

  <Accordion title="(Optional) Disable Encrypted SharedPreference">
    Add the following to your values.xml file.

    `<bool name="cashfree_pg_core_encrypt_pref_enabled">false</bool>`
  </Accordion>
</AccordionGroup>

<div>
  <p>Affiliate partner program</p>

  <p>As a developer building payment experiences for your clients, you can earn additional income while providing them with industry-leading payment solutions.</p>

  <p>Join the <a href="https://partner.cashfree.com/partner-ui/authentication/signup?source-action=Affiliate%20Program%20LP&action=Sign%20Up&button-id=StartNow_CashfreeAffiliatePartnerProgram">Cashfree affiliate partner program</a> and get rewarded every time your clients use Cashfree.</p>

  <p>**What you get:**</p>

  <ul>
    <li>Earn up to 0.25% commission on every transaction.</li>
    <li>Become a trusted fintech partner for your clients.</li>
    <li>Access to a dedicated partner manager for expert support.</li>
  </ul>

  <p>**What your clients get:**</p>

  <ul>
    <li>Instant activation and go live in minutes.</li>
    <li>Industry-best success rate across all payment modes.</li>
    <li>Effortless acceptance of international payments in 140+ currencies.</li>
  </ul>

  <p>Get started today. <a href="https://partner.cashfree.com/partner-ui/authentication/signup?source-action=Affiliate%20Program%20LP&action=Sign%20Up&button-id=StartNow_BecomeAPartner">Become a partner now</a>.</p>
</div>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/payments/latest/orders/create-order">Create Order API</a></li>
    <li><a href="/docs/api-reference/payments/sdk">Payment SDK API Overview</a></li>
    <li><a href="https://github.com/cashfree/nextgen-android">Android SDK on GitHub</a></li>
  </ul>
</div>


# Cordova Integration
Source: https://www.cashfree.com/docs/payments/online/mobile/cordova

Integrate the Cashfree Payment Gateway Cordova SDK to add web checkout and UPI Intent flows to your hybrid Cordova or Capacitor app on Android and iOS.

Cashfree's Cordova SDK provides a payment solution that integrates the payment gateway into your Cordova and Capacitor applications, supporting both Android and iOS platforms. The SDK offers multiple checkout flows including web checkout and UPI Intent checkout.

<Note>
  This document includes instructions for both Cordova and Capacitor SDK integrations.
</Note>

## Key benefits

The Cordova SDK offers the following advantages for your payment integration:

* **Multiple checkout flows**: Provides web checkout and UPI Intent checkout options to suit different integration needs.

* **Cross-platform support**: Seamlessly supports Android (SDK version 19+) and iOS (deployment target 11+) platforms.

* **Secure and compliant**: Securely handles payment processing with built-in security measures managed by the SDK.

## Prerequisites

Ensure you complete the following tasks before starting the integration:

* Create a [Cashfree Merchant Account](https://merchant.cashfree.com/merchants/signup).
* Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and generate an **App ID** and **Secret Key**. Learn how to [generate API keys](/docs/api-reference/authentication#generate-api-keys).
* Ensure your application complies with Cashfree's [Integrity standards](/docs/payments/online/mobile/misc/cashfree_integrity). Applications that don't meet the required integrity standards may be restricted from using production services.

The Cordova integration consists of three essential steps:

<CardGroup>
  <Card title="Step 1" icon="money-bill-wave" href="/docs/payments/online/mobile/cordova#step-1-create-an-order-server-side">
    Create an order
  </Card>

  <Card title="Step 2" icon="desktop" href="/docs/payments/online/mobile/cordova#step-2-open-the-checkout-page-client-side">
    Open the checkout page
  </Card>

  <Card title="Step 3" icon="circle-check" href="/docs/payments/online/mobile/cordova#step-3-confirm-the-payment-server-side">
    Confirm the payment
  </Card>
</CardGroup>

The step-by-step guide for each step of the integration process is as follows:

## Step 1: Create an order <Badge>Server-side</Badge>

To integrate the Cashfree Payment Gateway, you must first create an order. Complete this step before you process any payments. Configure an endpoint on your server to handle order creation. You can't call this API from the client-side.

<Note>Create orders through your server as this API requires your secret key. Don't call it directly from your mobile application.</Note>

##### API request for creating an order

Here's a sample request for creating an order using your desired backend language. Cashfree offers backend [SDKs](/docs/api-reference/payments/sdk#server-sdk) to simplify the integration process.

<CodeGroup>
  ```bash curl theme={"dark"}
  curl --location 'https://sandbox.cashfree.com/pg/orders' \
  --header 'X-Client-Secret: {{clientKey}}' \
  --header 'X-Client-Id: {{clientId}}' \
  --header 'x-api-version: 2025-01-01' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data-raw '{
    "order_amount": 10.10,
    "order_currency": "INR",
    "customer_details": {
      "customer_id": "USER123",
      "customer_name": "joe",
      "customer_email": "joe.s@cashfree.com",
      "customer_phone": "+919876543210"
    },
    "order_meta": {
      "return_url": "https://b8af79f41056.eu.ngrok.io?order_id=order_123"
    }
  }'
  ```

  ```javascript nodejs theme={"dark"}
  import { Cashfree, CFEnvironment } from "cashfree-pg";

  const cashfree = new Cashfree(
  	CFEnvironment.PRODUCTION,
  	"{Client ID}",
  	"{Client Secret Key}"
  );

  function createOrder() {
  	var request = {
  		order_amount: "1",
  		order_currency: "INR",
  		customer_details: {
  			customer_id: "node_sdk_test",
  			customer_name: "",
  			customer_email: "example@gmail.com",
  			customer_phone: "9999999999",
  		},
  		order_meta: {
  			return_url:
  				"https://test.cashfree.com/pgappsdemos/return.php?order_id=order_123",
  		},
  		order_note: "",
  	};

  	cashfree
  		.PGCreateOrder(request)
  		.then((response) => {
  			console.log("Order created successfully:", response.data);
  		})
  		.catch((error) => {
  			console.error("Error setting up order request:", error.response.data);
  		});
  }
  ```

  ```python python theme={"dark"}
  from cashfree_pg.models.create_order_request import CreateOrderRequest
  from cashfree_pg.api_client import Cashfree
  from cashfree_pg.models.customer_details import CustomerDetails


  Cashfree.XClientId = {Client ID}
  Cashfree.XClientSecret = {Client Secret Key}
  Cashfree.XEnvironment = Cashfree.XSandbox
  x_api_version = "2023-08-01"

  def create_order():
          customerDetails = CustomerDetails(customer_id="123", customer_phone="9999999999")
          createOrderRequest = CreateOrderRequest(order_amount=1, order_currency="INR", customer_details=customerDetails)
          try:
              api_response = Cashfree().PGCreateOrder(x_api_version, createOrderRequest, None, None)
              print(api_response.data)
          except Exception as e:
              print(e)
  ```

  ```java java theme={"dark"}
  import com.cashfree.*;

  Cashfree.XClientId = {Client Key};
  Cashfree.XClientSecret = {Client Secret Key};
  Cashfree.XEnvironment = Cashfree.SANDBOX;

  static void createOrder() {
    CustomerDetails customerDetails = new CustomerDetails();
    customerDetails.setCustomerId("123");
    customerDetails.setCustomerPhone("9999999999");

    CreateOrderRequest request = new CreateOrderRequest();
    request.setOrderAmount(1.0);
    request.setOrderCurrency("INR");
    request.setCustomerDetails(customerDetails);
    try {
      Cashfree cashfree = new Cashfree();
      ApiResponse<OrderEntity> response = cashfree.PGCreateOrder("2023-08-01", request, null, null, null);
      System.out.println(response.getData().getOrderId());

    } catch (ApiException e) {
      throw new RuntimeException(e);
    }
  }
  ```

  ```go go theme={"dark"}
  import (
    cashfree "github.com/cashfree/cashfree-pg/v3"
  )

  func createOrder() {

  clientId := {Client ID}
  clientSecret := {Client Secret Key}
  cashfree.XClientId = &clientId
  cashfree.XClientSecret = &clientSecret
  cashfree.XEnvironment = cashfree.SANDBOX

  request := cashfree.CreateOrderRequest{
  		OrderAmount: 1,
  		CustomerDetails: cashfree.CustomerDetails{
  			CustomerId:    "1",
  			CustomerPhone: "9999999999",
  		},
  		OrderCurrency: "INR",
  		OrderSplits:   []cashfree.VendorSplit{},
  	}
  	version := "2023-08-01"
  	response, httpResponse, err := cashfree.PGCreateOrder(&version, &request, nil, nil, nil)
  	if err != nil {
  		fmt.Println(err.Error())
  	} else {
  		fmt.Println(httpResponse.StatusCode)
  		fmt.Println(response)
      }
  }
  ```

  ```csharp .net theme={"dark"}
  using cashfree_pg.Client;
  using cashfree_pg.Model;

  Cashfree.XClientId = {Client ID};
  Cashfree.XClientSecret = {Client Secret Key};
  Cashfree.XEnvironment = Cashfree.PRODUCTION;
  var cashfree = new Cashfree();
  var xApiVersion = "2023-08-01";

  void CreateOrder() {
      var customerDetails = new CustomerDetails("123", null, "9999999999");
      var createOrdersRequest = new CreateOrderRequest(null, 1.0, "INR", customerDetails);
      try {
          // Create Order
          var result = cashfree.PGCreateOrder(xApiVersion, createOrdersRequest, null, null, null);
          Console.WriteLine(result);
          Console.WriteLine(result.StatusCode);
          Console.WriteLine((result.Content as OrderEntity));
      } catch (ApiException e) {
          Console.WriteLine("Exception when calling PGCreateOrder: " + e.Message);
          Console.WriteLine("Status Code: " + e.ErrorCode);
          Console.WriteLine(e.StackTrace);
      }
  }
  ```

  ```php php theme={"dark"}
  \Cashfree\Cashfree::$XClientId = "<x-client-id>";
  \Cashfree\Cashfree::$XClientSecret = "<x-client-secret>";
  \Cashfree\Cashfree::$XEnvironment = Cashfree\Cashfree::$SANDBOX;

  $cashfree = new \Cashfree\Cashfree();

  $x_api_version = "2023-08-01";
  $create_orders_request = new \Cashfree\Model\CreateOrdersRequest();
  $create_orders_request->setOrderAmount(1.0);
  $create_orders_request->setOrderCurrency("INR");
  $customer_details = new \Cashfree\Model\CustomerDetails();
  $customer_details->setCustomerId("123");
  $customer_details->setCustomerPhone("9999999999");
  $create_orders_request->setCustomerDetails($customer_details);

  try {
      $result = $cashfree->PGCreateOrder($x_api_version, $create_orders_request);
      print_r($result);
  } catch (Exception $e) {
      echo 'Exception when calling PGCreateOrder: ', $e->getMessage(), PHP_EOL;
  }
  ```
</CodeGroup>

After successfully creating an order, you will receive a unique `order_id` and `payment_session_id` that you need for subsequent steps.

You can view the complete API request and response for `/orders` in the [Create Order API](/docs/api-reference/payments/latest/orders/create-order).

<Note>
  To show a short purchase description on checkout, such as a booking reference or route, add `checkout_context` to the `order_tags` object in the Create Order request above.

  ```json theme={"dark"}
  "order_tags": {
    "checkout_context": "Flight booking DEL-BOM, 12 JUN at 14:30"
  }
  ```

  For details about how checkout displays this text in a context card, see [Contextual Checkout](/docs/payments/features/contextual-checkout).
</Note>

## Step 2: Open the checkout page <Badge>Client-side</Badge>

Once the order is created, the next step is to open the payment page so the customer can make the payment.

### 1. Set up the SDK

The Cordova SDK is hosted on [npm](https://www.npmjs.com/). You can download the latest version [1.0.12](https://www.npmjs.com/package/cordova-plugin-cashfree-pg?activeTab=readme). The Cordova SDK supports Android SDK version 19 and above and iOS minimum deployment target of 11 and above.

<Note>
  **Capacitor SDK**: The code snippet below also includes Capacitor SDK integration instructions.
</Note>

Navigate to your project and run the following command:

<CodeGroup>
  ```shell cordova theme={"dark"}
  npm install cordova-plugin-cashfree-pg
  # or install with latest tag
  npm install cordova-plugin-cashfree-pg@latest

  # Add Plugin
  cordova plugin add cordova-plugin-cashfree-pg

  # With Ionic Cordova platform
  ionic cordova plugin add cordova-plugin-cashfree-pg 
  ```

  ```shell capacitor theme={"dark"}
  # Install with capacitor tag
  npm install cordova-plugin-cashfree-pg@capacitor

  # Ionic Capacitor setup

  # Install Core library (once per project)
  npm install @awesome-cordova-plugins/core
  # Install Awesome Cordova Plugins TypeScript wrapper for CashFree PG
  npm install @awesome-cordova-plugins/cashfree-pg
  # Update native platform project(s) to include newly added plugin
  ionic cap sync
  ```
</CodeGroup>

#### iOS configuration

Add this to your application's `info.plist` file:

```xml theme={"dark"}
<key>LSApplicationQueriesSchemes</key>
<array>
  <string>tez</string>
  <string>phonepe</string>
  <string>paytmmp</string>
	<string>credpay</string>
  <string>bhim</string>
  <string>amazonpay</string>
  <string>upi</string>
	<string>navipay</string>
	<string>mobikwik</string>
	<string>myairtel</string>
	<string>popclubapp</string>
	<string>super</string>
	<string>kiwi</string>
</array>
```

For iOS, run the following commands:

```bash theme={"dark"}
cd ios
pod install --repo-update
```

### 2. Select a payment flow

The Cordova SDK offers the following payment flows:

<AccordionGroup>
  <Accordion title="Web Checkout">
    In this flow, the SDK provides a webview-based checkout implementation to facilitate a quick integration with the payment gateway. Your customers can fill in the necessary details in the web page and complete the payment.
    This mode handles all the business logic and UI components to make the payment smooth and easy to use.
  </Accordion>

  <Accordion title="UPI Intent Checkout">
    This flow is for merchants who want to provide UPI Intent functionality using Cashfree's mobile SDK. In this flow, the SDK provides a pre-built native Android screen to facilitate integration with the payment gateway. Your customers see a list of UPI apps installed on their phone which they can select to initiate payment.
    This mode handles all the business logic and UI components to make the payment smooth and easy to use. The SDK allows you to customise the UI in terms of colour coding and fonts.
  </Accordion>
</AccordionGroup>

### 3. Complete the payment

To complete the payment, follow these steps:

1. Create a `CFSession` object.
2. Set up payment callback.
3. Initiate the payment using the payment object.

#### Create a session

This object contains essential information about the order, including the payment session ID (`payment_session_id`) and order ID (`order_id`) obtained from Step 1. It also specifies the environment (`SANDBOX` or `PRODUCTION`).

```typescript theme={"dark"}
let session = {
  payment_session_id: "payment_session_id",
  orderID: "order_id",
  environment: "SANDBOX", //"SANDBOX" or "PRODUCTION"
};
```

#### Set up the payment callback

The SDK exposes a `CFCallback` interface to receive callbacks from the SDK once the payment flow ends. The callback supports two methods:

```typescript theme={"dark"}
onVerify(result)
onError(error)
```

```typescript theme={"dark"}
function onDeviceReady() {
  const callbacks = {
    onVerify: function (result) {
      let details = {
        orderID: result.orderID,
      };
      console.log(details);
    },
    onError: function (error) {
      let errorObj = {
        orderID: error.orderID,
        status: error.status,
        code: error.code,
        type: error.type,
        message: error.message,
      };
      console.log(errorObj);
    },
  };
  CFPaymentGateway.setCallback(callbacks);
}
```

<Tip>Always call `setCallback` before calling the `doPayment` method of the SDK.</Tip>

#### Initiate the payment

<AccordionGroup>
  <Accordion title="Web Checkout">
    ```typescript theme={"dark"}
    let webCheckoutPaymentObject = {
      theme: {
        navigationBarBackgroundColor: "#E64A19",
        navigationBarTextColor: "#FFFFFF",
      },
      session: {
        payment_session_id: "payment_session_id",
        orderID: "order_id",
        environment: "SANDBOX", //"SANDBOX" or "PRODUCTION"
      },
    };

    function initiateWebPayment() {
      CFPaymentGateway.doWebCheckoutPayment(webCheckoutPaymentObject);
    }
    ```
  </Accordion>

  <Accordion title="UPI Intent Checkout">
    This flow is for merchants who want to provide UPI functionality using Cashfree's mobile SDK without handling other modes like cards or net banking.

    ```typescript theme={"dark"}
    let upiIntentCheckoutPaymentObject = {
      "theme": {
        "navigationBarBackgroundColor": "#E64A19", //ios
        "navigationBarTextColor": "#FFFFFF", //ios
        "buttonBackgroundColor": "#FFC107", //ios
        "buttonTextColor": "#FFFFFF", //ios
        "primaryTextColor": "#212121", 
        "secondaryTextColor": "#757575", //ios
        "backgroundColor": "#FFFFFF"
    	},
      "session": {
        "payment_session_id": "payment_session_id",
        "orderID": "order_id",
        "environment": "SANDBOX" //"SANDBOX" or "PRODUCTION"
    	}
    }

    function initiateUPIPayment() {
        CFPaymentGateway.doUPIPayment(upiIntentCheckoutPaymentObject)
    }
    ```
  </Accordion>
</AccordionGroup>

#### Sample code

Complete code examples demonstrating the implementation of both Web Checkout and UPI Intent Checkout flows are shown below:

<AccordionGroup>
  <Accordion title="Web Checkout">
    ```typescript theme={"dark"}
    document.addEventListener("deviceready", onDeviceReady, false);

    function onDeviceReady() {
      console.log("Running cordova-" + cordova.platformId + "@" + cordova.version);
      let webElement = document.getElementById("onWeb");
      webElement.addEventListener("click", (e) => initiateWebPayment());

      const callbacks = {
        onVerify: function (result) {
          let details = {
            orderID: result.orderID,
          };
          console.log(details);
        },
        onError: function (error) {
          let errorObj = {
            orderID: error.orderID,
            status: error.status,
            code: error.code,
            type: error.type,
            message: error.message,
          };
          console.log(errorObj);
        },
      };
      CFPaymentGateway.setCallback(callbacks);
    }

    function initiateWebPayment() {
      CFPaymentGateway.doWebCheckoutPayment({
        theme: {
          navigationBarBackgroundColor: "#E64A19",
          navigationBarTextColor: "#FFFFFF",
        },
        session: {
          payment_session_id: "payment_session_id",
          orderID: "order_id",
          environment: "SANDBOX",
        },
      });
    }
    ```
  </Accordion>

  <Accordion title="UPI Intent Checkout">
    ```typescript theme={"dark"}
    document.addEventListener('deviceready', onDeviceReady, false);

    function onDeviceReady() {
        console.log('Running cordova-' + cordova.platformId + '@' + cordova.version);
        let upiElement = document.getElementById("onUPI");
        upiElement.addEventListener("click", (e) => initiateUPIIntentCheckoutPayment());

        const callbacks = {
           onVerify: function (result) {
             let details = {
               "orderID": result.orderID
             }
             console.log(details);
           },
            onError: function (error){
              let errorObj = {
                "orderID": error.orderID,
                "status": error.status,
                "code": error.code,
                "type": error.type,
                "message": error.message
              }
              console.log(errorObj);
            }
        }
        CFPaymentGateway.setCallback(callbacks)
    }

    function initiateUPIIntentCheckoutPayment() {
        CFPaymentGateway.doUPIPayment({
          "theme": {
            "navigationBarBackgroundColor": "#E64A19", //ios
            "navigationBarTextColor": "#FFFFFF", //ios
            "buttonBackgroundColor": "#FFC107", //ios
            "buttonTextColor": "#FFFFFF", //ios
            "primaryTextColor": "#212121", 
            "secondaryTextColor": "#757575", //ios
            "backgroundColor": "#FFFFFF"
          },
          "session": {
            "payment_session_id": "payment_session_id",
            "orderID": "order_id",
            "environment": "SANDBOX" //"SANDBOX" or "PRODUCTION"
          }
        })
    }
    ```
  </Accordion>
</AccordionGroup>

#### Sample GitHub code

You can explore working integration examples for various frameworks on GitHub:

<AccordionGroup>
  <Accordion title="Cordova Integration">
    [GitHub Sample](https://github.com/cashfree/cordova-plugin-cashfree/tree/master/example-cordova)
  </Accordion>

  <Accordion title="Ionic Capacitor Integration">
    [GitHub Sample](https://github.com/kishan-cashfree/CFSampleCapacitor)
  </Accordion>

  <Accordion title="Ionic Angular Capacitor Integration">
    [GitHub Sample](https://github.com/kishan-cashfree/SampleIonicAngularCapacitor)
  </Accordion>

  <Accordion title="Next.js Capacitor Integration">
    [GitHub Sample](https://github.com/kishan-cashfree/NextjsCapacitorCashFreeSample)
  </Accordion>
</AccordionGroup>

[Sample UPI Test apk](https://docs.cashfree.com/docs/cashfree-upi-intent-simulator-apk)

<Note>
  Cashfree doesn't currently provide a dedicated SDK for the Capacitor framework. However, a Capacitor plugin has been developed that acts as a wrapper over the Cordova SDK. See the [sample Capacitor app](https://github.com/droiddevgeeks/CFSampleCapacitor/tree/main).
</Note>

## Step 3: Confirm the payment <Badge>Server-side</Badge>

Once the payment is completed, you need to confirm whether the payment was successful by checking the order status. Once the payment finishes, the user will be redirected back to your activity.

<Note>You must always verify payment status from your server. Before delivering the goods or services, ensure you check the order status from your server and verify it from your server endpoint.</Note>

To verify an order you can call our `/pg/orders` endpoint from your backend. You can also use our SDK to achieve the same.

<CodeGroup>
  ```bash curl theme={"dark"}
  curl --request GET \
       --url https://sandbox.cashfree.com/pg/orders/{order_id} \
       --header 'accept: application/json' \
       --header 'x-api-version: 2025-01-01' \
       --header 'x-client-id: "YOUR APP ID GOES HERE"' \
       --header 'x-client-secret: "YOUR SECRET KEY GOES HERE"'
  ```

  ```javascript nodejs theme={"dark"}
  cashfree
  .PGFetchOrder("<order_id>")
  .then((response) => {
  	console.log("Order fetched successfully:", response.data);
  })
  .catch((error) => {
  	console.error("Error:", error.response.data.message);
  });
  ```

  ```python python theme={"dark"}
  from cashfree_pg.models.create_order_request import CreateOrderRequest
  from cashfree_pg.api_client import Cashfree
  from cashfree_pg.models.customer_details import CustomerDetails
  from cashfree_pg.models.order_meta import OrderMeta

  Cashfree.XClientId = "<x-client-id>"
  Cashfree.XClientSecret = "<x-client-secret>"
  Cashfree.XEnvironment = Cashfree.SANDBOX
  x_api_version = "2023-08-01"

  try:
      api_response = Cashfree().PGFetchOrder(x_api_version, "order_3242X4jQ5f0S9KYxZO9mtDL1Kx2Y7u", None)
      print(api_response.data)
  except Exception as e:
      print(e)

  ```

  ```java java theme={"dark"}
  import com.cashfree.*;
  //other code

  try {
      Cashfree.XClientId = "<x-client-id>";
      Cashfree.XClientSecret = "<x-client-secret>";
      Cashfree.XEnvironment = Cashfree.SANDBOX;

      Cashfree cashfree = new Cashfree();
      String xApiVersion = "2023-08-01";

      ApiResponse<OrderEntity> responseFetchOrder = cashfree.PGFetchOrder(xApiVersion, "<order_id>", null, null, null);
      System.out.println(response.getData().getOrderId());
  } catch (ApiException e) {
      throw new RuntimeException(e);
  }
  ```

  ```go go theme={"dark"}
  version := "2023-08-01"
  response, httpResponse, err := cashfree.PGFetchOrder(&version, "<order_id>", nil, nil, nil)
  if err != nil {
  	fmt.Println(err.Error())
  } else {
  	fmt.Println(httpResponse.StatusCode)
  	fmt.Println(response)
  }
  ```

  ```csharp .net theme={"dark"}
  using cashfree_pg.Client;
  using cashfree_pg.Model;

  Cashfree.XClientId = "<x-client-id>";
  Cashfree.XClientSecret = "<x-client-secret>";
  Cashfree.XEnvironment = Cashfree.SANDBOX;
  var cashfree = new Cashfree();
  var xApiVersion = "2023-08-01";

  try {
      var result = cashfree.PGFetchOrder(xApiVersion, "<order_id>>", null, null);
      Console.WriteLine(result);
      Console.WriteLine(result.StatusCode);
      Console.WriteLine((result.Content as OrderEntity));
  } catch (ApiException e) {
      Console.WriteLine("Exception when calling PGFetchOrder: " + e.Message);
      Console.WriteLine("Status Code: " + e.ErrorCode);
      Console.WriteLine(e.StackTrace);
  }
  ```

  ```php php theme={"dark"}
  $x_api_version = "2023-08-01";
  try {
      $response = $cashfree->PGFetchOrder($x_api_version, "<order_id>");
      print_r($response);
  } catch (Exception $e) {
      echo 'Exception when calling PGFetchOrder: ', $e->getMessage(), PHP_EOL;
  }
  ```
</CodeGroup>

### Testing

You should now have a working checkout button that redirects your customer to Cashfree Checkout. If your integration isn’t working:

* Open the Network tab in your browser's developer tools.
* Click the button and check the console logs.
* Use `console.log(session)` inside your button click listener to confirm the correct error returned.

## Error codes

To confirm the error returned in your application, you can view the error codes that are exposed by the SDK.

<Accordion title="Click to show error codes">
  The following are some of the error codes that are exposed by the SDK:

  | Error codes | Message |
  | - | - |
  | MISSING\_CALLBACK | The callback is missing in the request. |
  | ORDER\_ID\_MISSING | The "order\_id" is missing in the request. |
  | CARD\_EMI\_TENURE\_MISSING | The "emi\_tenure" is missing or invalid (It has to be greater than 0). |
  | INVALID\_UPI\_APP\_ID\_SENT | The id sent is invalid. The value has to be one of the following: "tez://","phonepe://","paytm://","bhim://. Please refer the note in CFUPI class for more details |
  | INVALID\_PAYMENT\_OBJECT\_SENT | The payment object that is set doesn't match any payment mode. Please set the correct payment mode and try again. |
  | WALLET\_OBJECT\_MISSING | The CFWallet object is missing in the request |
  | NETBANKING\_OBJECT\_MISSING | The CFNetbanking object is missing in the request. |
  | UPI\_OBJECT\_MISSING | The CFUPI object is missing in the request. |
  | CARD\_OBJECT\_MISSING | The CFCard object is missing in the request. |
  | INVALID\_WEB\_DATA | The url seems to be corrupt. Please reinstantiate the order. |
  | SESSION\_OBJECT\_MISSING | The "session" is missing in the request |
  | PAYMENT\_OBJECT\_MISSING | The "payment" is missing in the request |
  | ENVIRONMENT\_MISSING | The "environment" is missing in the request. |
  | ORDER\_TOKEN\_MISSING | The "order\_token" is missing in the request. |
  | CHANNEL\_MISSING | The "channel" is missing in the request. |
  | CARD\_NUMBER\_MISSING | The "card\_number" is missing in the request. |
  | CARD\_EXPIRY\_MONTH\_MISSING | The "card\_expiry\_mm" is missing in the request. |
  | CARD\_EXPIRY\_YEAR\_MISSING | The "card\_expiry\_yy" is missing in the request. |
  | CARD\_CVV\_MISSING | The "card\_cvv" is missing in the request. |
  | UPI\_ID\_MISSING | The "upi\_id" is missing in the request |
  | WALLET\_CHANNEL\_MISSING | The "channel" is missing in the wallet payment request |
  | WALLET\_PHONE\_MISSING | The "phone number" is missing in the wallet payment request |
  | NB\_BANK\_CODE\_MISSING | The "bank\_code" is missing in the request |
</Accordion>

<snippet>snippets/related-topics-loader.mdx</snippet>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/payments/sdk">Payment SDKs</a></li>
    <li><a href="https://github.com/cashfree/cordova-plugin-cashfree/tree/master/example-cordova">Cordova GitHub Sample</a></li>
    <li><a href="https://github.com/kishan-cashfree/CFSampleCapacitor">Capacitor GitHub Sample</a></li>
    <li><a href="https://github.com/kishan-cashfree/SampleIonicAngularCapacitor">Ionic Angular GitHub Sample</a></li>
    <li><a href="https://github.com/kishan-cashfree/NextjsCapacitorCashFreeSample">Next.js Capacitor GitHub Sample</a></li>
  </ul>
</div>


# Flutter Integration
Source: https://www.cashfree.com/docs/payments/online/mobile/flutter

Use the Cashfree Payment Gateway Flutter SDK to embed a WebView-based checkout in your Flutter app, supporting payments on both Android and iOS targets.

Cashfree's Flutter SDK provides a streamlined payment solution that integrates the payment gateway into your Flutter applications through a WebView-based checkout implementation, supporting both Android and iOS platforms.

## Key benefits

The Flutter SDK offers the following advantages for your payment integration:

* **Simplified integration**: Provides a pre-built SDK that delivers an optimised payment experience for Flutter applications.

* **Cross-platform support**: Seamlessly supports Android (SDK version 19+) and iOS (deployment target 11+) platforms.

* **Secure and compliant**: Securely handles payment processing with built-in security measures managed by the SDK.

## Prerequisites

Ensure you complete the following tasks before starting the integration:

* Create a [Cashfree Merchant Account](https://merchant.cashfree.com/merchants/signup).
* Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and generate an **App ID** and **Secret Key**. Learn how to [generate API keys](/docs/api-reference/authentication#generate-api-keys).
* Ensure your application complies with Cashfree's [Integrity standards](/docs/payments/online/mobile/misc/cashfree_integrity). Applications that do not meet the required integrity standards may be restricted from using production services.

The Flutter integration consists of three essential steps:

<CardGroup>
  <Card title="Step 1" icon="money-bill-wave" href="/docs/payments/online/mobile/flutter#step-1-create-an-order-server-side">
    Create an order
  </Card>

  <Card title="Step 2" icon="desktop" href="/docs/payments/online/mobile/flutter#step-2-open-the-payment-page-client-side">
    Open the payment page
  </Card>

  <Card title="Step 3" icon="circle-check" href="/docs/payments/online/mobile/flutter#step-3-confirm-the-payment-server-side">
    Confirm the payment
  </Card>
</CardGroup>

The step-by-step guide for each step of the integration process is as follows:

<div>
  <iframe title="YouTube video player" />

  <a href="https://www.cashfree.com/devstudio/preview/pg/mobile/hybrid">
    <span>
      Try it in DevStudio

      <svg>
        <path />

        <path />
      </svg>
    </span>
  </a>
</div>

## Step 1: Create an order <Badge>Server-side</Badge>

To integrate the Cashfree Payment Gateway, you must first create an order. Complete this step before you process any payments. Configure an endpoint on your server to handle order creation. You can't call this API from the client-side.

<Note>Create orders through your server as this API requires your secret key. Don't call it directly from your mobile application.</Note>

##### API request for creating an order

Here's a sample request for creating an order using your desired backend language. Cashfree offers backend [SDKs](/docs/api-reference/payments/sdk#server-sdk) to simplify the integration process.

<CodeGroup>
  ```bash curl theme={"dark"}
  curl --location 'https://sandbox.cashfree.com/pg/orders' \
  --header 'X-Client-Secret: {{clientKey}}' \
  --header 'X-Client-Id: {{clientId}}' \
  --header 'x-api-version: 2025-01-01' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data-raw '{
    "order_amount": 10.10,
    "order_currency": "INR",
    "customer_details": {
      "customer_id": "USER123",
      "customer_name": "joe",
      "customer_email": "joe.s@cashfree.com",
      "customer_phone": "+919876543210"
    },
    "order_meta": {
      "return_url": "https://b8af79f41056.eu.ngrok.io?order_id=order_123"
    }
  }'
  ```

  ```javascript nodejs theme={"dark"}
  import { Cashfree, CFEnvironment } from "cashfree-pg";

  const cashfree = new Cashfree(
  	CFEnvironment.PRODUCTION,
  	"{Client ID}",
  	"{Client Secret Key}"
  );

  function createOrder() {
  	var request = {
  		order_amount: "1",
  		order_currency: "INR",
  		customer_details: {
  			customer_id: "node_sdk_test",
  			customer_name: "",
  			customer_email: "example@gmail.com",
  			customer_phone: "9999999999",
  		},
  		order_meta: {
  			return_url:
  				"https://test.cashfree.com/pgappsdemos/return.php?order_id=order_123",
  		},
  		order_note: "",
  	};

  	cashfree
  		.PGCreateOrder(request)
  		.then((response) => {
  			console.log("Order created successfully:", response.data);
  		})
  		.catch((error) => {
  			console.error("Error setting up order request:", error.response.data);
  		});
  }
  ```

  ```python python theme={"dark"}
  from cashfree_pg.models.create_order_request import CreateOrderRequest
  from cashfree_pg.api_client import Cashfree
  from cashfree_pg.models.customer_details import CustomerDetails


  Cashfree.XClientId = {Client ID}
  Cashfree.XClientSecret = {Client Secret Key}
  Cashfree.XEnvironment = Cashfree.XSandbox
  x_api_version = "2023-08-01"

  def create_order():
          customerDetails = CustomerDetails(customer_id="123", customer_phone="9999999999")
          createOrderRequest = CreateOrderRequest(order_amount=1, order_currency="INR", customer_details=customerDetails)
          try:
              api_response = Cashfree().PGCreateOrder(x_api_version, createOrderRequest, None, None)
              print(api_response.data)
          except Exception as e:
              print(e)
  ```

  ```java java theme={"dark"}
  import com.cashfree.*;

  Cashfree.XClientId = {Client Key};
  Cashfree.XClientSecret = {Client Secret Key};
  Cashfree.XEnvironment = Cashfree.SANDBOX;

  static void createOrder() {
    CustomerDetails customerDetails = new CustomerDetails();
    customerDetails.setCustomerId("123");
    customerDetails.setCustomerPhone("9999999999");

    CreateOrderRequest request = new CreateOrderRequest();
    request.setOrderAmount(1.0);
    request.setOrderCurrency("INR");
    request.setCustomerDetails(customerDetails);
    try {
      Cashfree cashfree = new Cashfree();
      ApiResponse<OrderEntity> response = cashfree.PGCreateOrder("2023-08-01", request, null, null, null);
      System.out.println(response.getData().getOrderId());

    } catch (ApiException e) {
      throw new RuntimeException(e);
    }
  }
  ```

  ```go go theme={"dark"}
  import (
    cashfree "github.com/cashfree/cashfree-pg/v3"
  )

  func createOrder() {

  clientId := {Client ID}
  clientSecret := {Client Secret Key}
  cashfree.XClientId = &clientId
  cashfree.XClientSecret = &clientSecret
  cashfree.XEnvironment = cashfree.SANDBOX

  request := cashfree.CreateOrderRequest{
  		OrderAmount: 1,
  		CustomerDetails: cashfree.CustomerDetails{
  			CustomerId:    "1",
  			CustomerPhone: "9999999999",
  		},
  		OrderCurrency: "INR",
  		OrderSplits:   []cashfree.VendorSplit{},
  	}
  	version := "2023-08-01"
  	response, httpResponse, err := cashfree.PGCreateOrder(&version, &request, nil, nil, nil)
  	if err != nil {
  		fmt.Println(err.Error())
  	} else {
  		fmt.Println(httpResponse.StatusCode)
  		fmt.Println(response)
      }
  }
  ```

  ```csharp .net theme={"dark"}
  using cashfree_pg.Client;
  using cashfree_pg.Model;

  Cashfree.XClientId = {Client ID};
  Cashfree.XClientSecret = {Client Secret Key};
  Cashfree.XEnvironment = Cashfree.PRODUCTION;
  var cashfree = new Cashfree();
  var xApiVersion = "2023-08-01";

  void CreateOrder() {
      var customerDetails = new CustomerDetails("123", null, "9999999999");
      var createOrdersRequest = new CreateOrderRequest(null, 1.0, "INR", customerDetails);
      try {
          // Create Order
          var result = cashfree.PGCreateOrder(xApiVersion, createOrdersRequest, null, null, null);
          Console.WriteLine(result);
          Console.WriteLine(result.StatusCode);
          Console.WriteLine((result.Content as OrderEntity));
      } catch (ApiException e) {
          Console.WriteLine("Exception when calling PGCreateOrder: " + e.Message);
          Console.WriteLine("Status Code: " + e.ErrorCode);
          Console.WriteLine(e.StackTrace);
      }
  }
  ```

  ```php php theme={"dark"}
  \Cashfree\Cashfree::$XClientId = "<x-client-id>";
  \Cashfree\Cashfree::$XClientSecret = "<x-client-secret>";
  \Cashfree\Cashfree::$XEnvironment = Cashfree\Cashfree::$SANDBOX;

  $cashfree = new \Cashfree\Cashfree();

  $x_api_version = "2023-08-01";
  $create_orders_request = new \Cashfree\Model\CreateOrdersRequest();
  $create_orders_request->setOrderAmount(1.0);
  $create_orders_request->setOrderCurrency("INR");
  $customer_details = new \Cashfree\Model\CustomerDetails();
  $customer_details->setCustomerId("123");
  $customer_details->setCustomerPhone("9999999999");
  $create_orders_request->setCustomerDetails($customer_details);

  try {
      $result = $cashfree->PGCreateOrder($x_api_version, $create_orders_request);
      print_r($result);
  } catch (Exception $e) {
      echo 'Exception when calling PGCreateOrder: ', $e->getMessage(), PHP_EOL;
  }
  ```
</CodeGroup>

After successfully creating an order, you will receive a unique `order_id` and `payment_session_id` that you need for subsequent steps.

You can view the complete API request and response for `/orders` in the [Create Order API](/docs/api-reference/payments/latest/orders/create-order).

<Note>
  To show a short purchase description on checkout, such as a booking reference or route, add `checkout_context` to the `order_tags` object in the Create Order request above.

  ```json theme={"dark"}
  "order_tags": {
    "checkout_context": "Flight booking DEL-BOM, 12 JUN at 14:30"
  }
  ```

  For details about how checkout displays this text in a context card, see [Contextual Checkout](/docs/payments/features/contextual-checkout).
</Note>

## Step 2: Open the payment page <Badge>Client-side</Badge>

Web Checkout is a streamlined payment solution that integrates Cashfree's payment gateway into your Flutter app through the SDK. This implementation uses a WebView to provide a secure, feature-rich payment experience.

Your customers are presented with a familiar web interface where they can enter their payment details and complete their transaction seamlessly. All payment logic, UI components, and security measures are managed by the SDK, eliminating the need for complex custom implementation.

### 1. Set up the SDK

The Flutter SDK is hosted on [pub.dev](https://pub.dev/). You can get the SDK [2.4.0+52](https://pub.dev/packages/flutter_cashfree_pg_sdk). The Flutter SDK supports Android SDK version 19 and above and iOS minimum deployment target of 11 and above.

Open your project's `pubspec.yaml` and add the following under dependencies:

```yaml theme={"dark"}
flutter_cashfree_pg_sdk: 2.4.0+52
```

#### iOS configuration

Add this to your application's `info.plist` file:

```xml theme={"dark"}
<key>LSApplicationQueriesSchemes</key>
<array>
  <string>amazonpay</string>
	<string>upi</string>
	<string>credpay</string>
	<string>bhim</string>
	<string>paytmmp</string>
	<string>phonepe</string>
	<string>tez</string>
	<string>navipay</string>
	<string>mobikwik</string>
	<string>myairtel</string>
	<string>popclubapp</string>
	<string>super</string>
	<string>kiwi</string>
  <string>simplypayupi</string>
  <string>whatsapp</string>
</array>
```

### 2. Complete the payment

To complete the payment, follow these steps:

1. Create a CFSession object.
2. Create a Web Checkout Payment object.
3. Set payment callback.
4. Initiate the payment using the payment object created.

#### Create a session

This object contains essential information about the order, including the payment session ID (`payment_session_id`) and order ID (`order_id`) obtained from Step 1. It also specifies the environment (sandbox or production).

```dart theme={"dark"}
try {
    var session = CFSessionBuilder().setEnvironment(environment).setOrderId(orderId).setPaymentSessionId(paymentSessionId).build();
    return session;
} on CFException catch (e) {
    print(e.message);
}
```

#### Create a web checkout payment object

Use `CFWebCheckoutPaymentBuilder` to create the payment object. This object accepts a `CFSession`, like the one created in the previous step.

```dart theme={"dark"}
var cfWebCheckout = CFWebCheckoutPaymentBuilder()
  .setSession(session!)
  .build();
```

#### Set up the callback

You need to set up callback handlers to handle events after payment processing.

```dart theme={"dark"}
void verifyPayment(String orderId) {
    print("Verify Payment");
  }

  void onError(CFErrorResponse errorResponse, String orderId) {
    print(errorResponse.getMessage());
    print("Error while making payment");
  }

var cfPaymentGatewayService = CFPaymentGatewayService();

  @override
  void initState() {
    super.initState();
    cfPaymentGatewayService.setCallback(verifyPayment, onError);
}
```

#### Sample code

```dart theme={"dark"}
class _MyAppState extends State<MyApp> {

  var cfPaymentGatewayService = CFPaymentGatewayService();

  @override
  void initState() {
    super.initState();
    cfPaymentGatewayService.setCallback(verifyPayment, onError);
  }

  void verifyPayment(String orderId) {
    print("Verify Payment");
  }

  void onError(CFErrorResponse errorResponse, String orderId) {
    print(errorResponse.getMessage());
    print("Error while making payment");
  }

  webCheckout() async {
    try {
      var session = createSession();
      var cfWebCheckout = CFWebCheckoutPaymentBuilder().setSession(session!).build();
      cfPaymentGatewayService.doPayment(cfWebCheckout);
    } on CFException catch (e) {
      print(e.message);
    }

  }

  CFSession? createSession() {
    try {
      var session = CFSessionBuilder().setEnvironment(environment).setOrderId(orderId).setPaymentSessionId(paymentSessionId).build();
      return session;
    } on CFException catch (e) {
      print(e.message);
    }
    return null;
  }
}
```

## Step 3: Confirm the payment <Badge>Server-side</Badge>

After the customer completes the payment, you must confirm the payment status. Once the payment finishes, the user redirects back to your activity.

To verify an order you can call our `/pg/orders` endpoint from your backend. You can also use our SDK to achieve the same.

<CodeGroup>
  ```bash curl theme={"dark"}
  curl --request GET \
       --url https://sandbox.cashfree.com/pg/orders/{order_id} \
       --header 'accept: application/json' \
       --header 'x-api-version: 2025-01-01' \
       --header 'x-client-id: "YOUR APP ID GOES HERE"' \
       --header 'x-client-secret: "YOUR SECRET KEY GOES HERE"'
  ```

  ```javascript nodejs theme={"dark"}
  cashfree
  .PGFetchOrder("<order_id>")
  .then((response) => {
  	console.log("Order fetched successfully:", response.data);
  })
  .catch((error) => {
  	console.error("Error:", error.response.data.message);
  });
  ```

  ```python python theme={"dark"}
  from cashfree_pg.models.create_order_request import CreateOrderRequest
  from cashfree_pg.api_client import Cashfree
  from cashfree_pg.models.customer_details import CustomerDetails
  from cashfree_pg.models.order_meta import OrderMeta

  Cashfree.XClientId = "<x-client-id>"
  Cashfree.XClientSecret = "<x-client-secret>"
  Cashfree.XEnvironment = Cashfree.SANDBOX
  x_api_version = "2023-08-01"

  try:
      api_response = Cashfree().PGFetchOrder(x_api_version, "order_3242X4jQ5f0S9KYxZO9mtDL1Kx2Y7u", None)
      print(api_response.data)
  except Exception as e:
      print(e)

  ```

  ```java java theme={"dark"}
  import com.cashfree.*;
  //other code

  try {
      Cashfree.XClientId = "<x-client-id>";
      Cashfree.XClientSecret = "<x-client-secret>";
      Cashfree.XEnvironment = Cashfree.SANDBOX;

      Cashfree cashfree = new Cashfree();
      String xApiVersion = "2023-08-01";

      ApiResponse<OrderEntity> responseFetchOrder = cashfree.PGFetchOrder(xApiVersion, "<order_id>", null, null, null);
      System.out.println(response.getData().getOrderId());
  } catch (ApiException e) {
      throw new RuntimeException(e);
  }
  ```

  ```go go theme={"dark"}
  version := "2023-08-01"
  response, httpResponse, err := cashfree.PGFetchOrder(&version, "<order_id>", nil, nil, nil)
  if err != nil {
  	fmt.Println(err.Error())
  } else {
  	fmt.Println(httpResponse.StatusCode)
  	fmt.Println(response)
  }
  ```

  ```csharp .net theme={"dark"}
  using cashfree_pg.Client;
  using cashfree_pg.Model;

  Cashfree.XClientId = "<x-client-id>";
  Cashfree.XClientSecret = "<x-client-secret>";
  Cashfree.XEnvironment = Cashfree.SANDBOX;
  var cashfree = new Cashfree();
  var xApiVersion = "2023-08-01";

  try {
      var result = cashfree.PGFetchOrder(xApiVersion, "<order_id>>", null, null);
      Console.WriteLine(result);
      Console.WriteLine(result.StatusCode);
      Console.WriteLine((result.Content as OrderEntity));
  } catch (ApiException e) {
      Console.WriteLine("Exception when calling PGFetchOrder: " + e.Message);
      Console.WriteLine("Status Code: " + e.ErrorCode);
      Console.WriteLine(e.StackTrace);
  }
  ```

  ```php php theme={"dark"}
  $x_api_version = "2023-08-01";
  try {
      $response = $cashfree->PGFetchOrder($x_api_version, "<order_id>");
      print_r($response);
  } catch (Exception $e) {
      echo 'Exception when calling PGFetchOrder: ', $e->getMessage(), PHP_EOL;
  }
  ```
</CodeGroup>

<Note>
  Always verify the order status before you deliver services to the customer. You can use the [Get Order API](/docs/api-reference/payments/latest/orders/get-order) for this. An order is successful when the `order_status` is `PAID`.
</Note>

### Testing

You should now have a working checkout button that redirects your customer to Cashfree payment page. If your integration isn’t working:

1. Open the Network tab in your browser’s developer tools.
2. Click the button and check the console logs.
3. Use `console.log(session)` inside your button click listener to confirm the correct error returned.

## Error codes

To confirm the error returned in your application, you can view the error codes that are exposed by the SDK.

<Accordion title="Show error codes">
  The following are some of the error codes that are exposed by the SDK:

  | Error codes | Message |
  | - | - |
  | MISSING\_CALLBACK | The callback is missing in the request. |
  | ORDER\_ID\_MISSING | The "order\_id" is missing in the request. |
  | CARD\_EMI\_TENURE\_MISSING | The "emi\_tenure" is missing or invalid (It has to be greater than 0). |
  | INVALID\_UPI\_APP\_ID\_SENT | The id sent is invalid. The value has to be one of the following: "tez://","phonepe://","paytm://","bhim://. Please refer the note in CFUPI class for more details |
  | INVALID\_PAYMENT\_OBJECT\_SENT | The payment object that is set does not match any payment mode. Please set the correct payment mode and try again. |
  | WALLET\_OBJECT\_MISSING | The CFWallet object is missing in the request |
  | NETBANKING\_OBJECT\_MISSING | The CFNetbanking object is missing in the request. |
  | UPI\_OBJECT\_MISSING | The CFUPI object is missing in the request. |
  | CARD\_OBJECT\_MISSING | The CFCard object is missing in the request. |
  | INVALID\_WEB\_DATA | The url seems to be corrupt. Please reinstantiate the order. |
  | SESSION\_OBJECT\_MISSING | The "session" is missing in the request |
  | PAYMENT\_OBJECT\_MISSING | The "payment" is missing in the request |
  | ENVIRONMENT\_MISSING | The "environment" is missing in the request. |
  | ORDER\_TOKEN\_MISSING | The "order\_token" is missing in the request. |
  | CHANNEL\_MISSING | The "channel" is missing in the request. |
  | CARD\_NUMBER\_MISSING | The "card\_number" is missing in the request. |
  | CARD\_EXPIRY\_MONTH\_MISSING | The "card\_expiry\_mm" is missing in the request. |
  | CARD\_EXPIRY\_YEAR\_MISSING | The "card\_expiry\_yy" is missing in the request. |
  | CARD\_CVV\_MISSING | The "card\_cvv" is missing in the request. |
  | UPI\_ID\_MISSING | The "upi\_id" is missing in the request |
  | WALLET\_CHANNEL\_MISSING | The "channel" is missing in the wallet payment request |
  | WALLET\_PHONE\_MISSING | The "phone number" is missing in the wallet payment request |
  | NB\_BANK\_CODE\_MISSING | The "bank\_code" is missing in the request |
</Accordion>

<div>
  <p>Affiliate partner program</p>

  <p>As a developer building payment experiences for your clients, you can earn additional income while providing them with industry-leading payment solutions.</p>

  <p>Join the <a href="https://partner.cashfree.com/partner-ui/authentication/signup?source-action=Affiliate%20Program%20LP&action=Sign%20Up&button-id=StartNow_CashfreeAffiliatePartnerProgram">Cashfree affiliate partner program</a> and get rewarded every time your clients use Cashfree.</p>

  <p>**What you get:**</p>

  <ul>
    <li>Earn up to 0.25% commission on every transaction.</li>
    <li>Become a trusted fintech partner for your clients.</li>
    <li>Access to a dedicated partner manager for expert support.</li>
  </ul>

  <p>**What your clients get:**</p>

  <ul>
    <li>Instant activation and go live in minutes.</li>
    <li>Industry-best success rate across all payment modes.</li>
    <li>Effortless acceptance of international payments in 140+ currencies.</li>
  </ul>

  <p>Get started today. <a href="https://partner.cashfree.com/partner-ui/authentication/signup?source-action=Affiliate%20Program%20LP&action=Sign%20Up&button-id=StartNow_BecomeAPartner">Become a partner now</a>.</p>
</div>

<snippet>snippets/related-topics-loader.mdx</snippet>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/payments/latest/orders/create-order">Create Order API</a></li>
    <li><a href="/docs/api-reference/payments/latest/orders/get-order">Get Order API</a></li>
    <li><a href="/docs/payments/online/mobile/misc/cashfree_integrity">Cashfree Integrity</a></li>
    <li><a href="https://pub.dev/packages/flutter_cashfree_pg_sdk">Flutter SDK on pub.dev</a></li>
  </ul>
</div>


# Integration FAQs
Source: https://www.cashfree.com/docs/payments/online/mobile/integration-faqs

Find answers to common questions about integrating Cashfree mobile SDKs across Android, iOS, Flutter, React Native, and Cordova for payment checkout flows.

<AccordionGroup>
  <Accordion title="How do I integrate Cashfree with my website or mobile app?">
    **Cashfree offers multiple integration APIs for:**

    * Website integration
    * Mobile SDK integration
    * Predefined plugins for major e-commerce platforms like:
      * [Shopify](https://www.shopify.com)
      * [Magento](https://magento.com)
      * [Woo-Commerce](https://woocommerce.com)
      * [OpenCart](https://www.opencart.com)
      * [WHMCS](https://www.whmcs.com)
      * [PrestaShop](https://www.prestashop.com)

    You can make use of these APIs to set up Cashfree payment gateway with your website or mobile app and start accepting payments.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are the different ways I can set up the payment gateway for my business?">
    Cashfree lets you integrate your [website](https://www.cashfree.com/payment-gateway-india/) or [mobile app](https://www.cashfree.com/payment-gateway-india/) with our payment gateway to accept payments. Over and above this, we also offer [plugins](https://www.cashfree.com/payment-gateway-india/) to major ecommerce sites like [Shopify](https://www.shopify.com), [Magento](https://magento.com), [Woo-commerce](https://woocommerce.com), [OpenCart](https://www.opencart.com), [PrestaShop](https://www.prestashop.com), [WHMCS](https://www.whmcs.com).
    [Click here to know more](/docs/payments/plugins/others#whmcs).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are the different web integrations possible with Cashfree?">
    There are three types of web integrations possible with Cashfree:

    1. [**Popup**](/docs/payments/online/web/redirect#3-open-cashfree-checkout)
    2. [**Cashfree Hosted**](/docs/payments/online/web/redirect)
    3. [**Element**](/docs/payments/online/element/overview)

    You can instantly set up any of these based on your requirements.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are the different mobile SDK integrations possible with Cashfree?">
    Cashfree offers a wide range of mobile SDK integrations such as:

    * [Android SDK](/docs/payments/online/mobile/android)
    * [iOS SDK](/docs/payments/online/mobile/ios)
    * [React Native SDK](/docs/payments/online/mobile/react-native)
    * [Flutter SDK](/docs/payments/online/mobile/flutter)
    * [Cordova SDK](/docs/payments/online/mobile/cordova)

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I test my app if it is not yet published on the Play Store or App Store?">
    Yes. In the sandbox environment, Cashfree Integrity does not enforce store verification, so you can test without a Play Store or App Store listing. For production testing, distribute your app through the Play Store's internal testing track instead of sideloading the APK directly. This satisfies Cashfree Integrity's store verification requirement without requiring a public release. For setup instructions, see [Integrity prod setup](/docs/payments/online/mobile/misc/cashfree_integrity_prod_testing).
  </Accordion>

  <Accordion title="What are the stores supported by Cashfree Integrity?">
    Google Play Store and Apple App Store are the stores currently supported by Cashfree Integrity.
  </Accordion>

  <Accordion title="When will the payment fail in Cashfree Integrity?">
    If an APK file is distributed through an unauthorised channel, Cashfree Integrity will block any payment happening through that application. If you are testing in production mode, payments will fail if the application is not installed from an authorised source. You can simulate production payments by doing a beta release of your application.
    [Setup for PROD test](/docs/payments/online/mobile/misc/cashfree_integrity_prod_testing)
  </Accordion>

  <Accordion title="What are the security mechanisms available in Cashfree Integrity?">
    Cashfree Integrity provides the following security mechanisms:

    * **Verified Package Names:** Transactions occur only through verified package names.
    * **Whitelisted Sources:** Package names are whitelisted to ensure applications are installed from verified stores.
  </Accordion>

  <Accordion title="Can I integrate Cashfree payment gateway to my Shopify website?">
    Yes, we do provide a predefined [plugin for WHMCS](/docs/payments/plugins/others#whmcs) that helps you set up Cashfree payment gateway with your [Shopify](https://www.shopify.com) account in no time, and with absolutely no code.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I integrate Cashfree payment gateway to my Magento website?">
    Yes, we provide a predefined [plugin for Magento](/docs/payments/plugins/magento) that helps you set up Cashfree payment gateway with your [Shopify](https://www.shopify.com) account in no time, and with absolutely no code.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I integrate Cashfree payment gateway to my Woo-Commerce website?">
    Yes, we provide a predefined plugin for [**Woo-Commerce**](/docs/payments/checkout/woocommerce) that
    helps you set up Cashfree payment gateway with your Woo-Commerce account in no
    time, and with absolutely no code.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I integrate Cashfree payment gateway to my OpenCart website?">
    Yes, we provide a predefined plugin for [**OpenCart**](/docs/payments/plugins/others#opencart) that helps
    you set up Cashfree payment gateway with your OpenCart account in no time, and
    with absolutely no code.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I integrate Cashfree payment gateway to my PrestaShop website?">
    Yes, we do provide a predefined plugin for [**PrestaShop**](/docs/payments/plugins/others#prestashop) that
    helps you set up Cashfree payment gateway with your PrestaShop account in no
    time, and with absolutely no code.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I integrate Cashfree payment gateway to my WHMCS website?">
    Yes, we do provide a predefined plugin for [WHMCS](/docs/payments/plugins/others#whmcs) that helps you set up Cashfree payment gateway with your Shopify account in no time, and with absolutely no code.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I integrate Cashfree with Shiprocket?">
    No. Cashfree does not currently support integration with Shiprocket. Integrations with other major e-commerce and platform partners are supported.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I integrate Cashfree payment gateway to Paytm?">
    Follow these steps to show Paytm as a payment option on your checkout page. You need to create a Paytm business account and connect Paytm with Cashfree. The process takes **24–48 hours**, after which Paytm will be available as a payment option for your customers.

    1. **Create a Paytm Business Account:**
       * Go to [Paytm Business](https://business.paytm.com/) and create a test account.

    2. **Receive Test Credentials:**
       1. After creating the test account, Paytm will send you an email with your *Merchant Staging Credentials*.
       2. Forward this email to the Cashfree team.
       3. Alternatively, you can find these details in your Paytm dashboard under the **Test API Details** tab.

    3. **Share Test Credentials:**
       1. Share your test credentials with your Cashfree Account Manager.
       2. To activate your production account, Cashfree will place **three test orders** on Paytm.
       3. Your account manager will share the status of these orders, which you need to forward to Paytm.

    4. **Receive Production Credentials:**
       * After verifying the test orders, Paytm will generate the following production credentials for your merchant account:
         * Website (for web)
         * Merchant ID
         * Merchant Key
         * Industry Type ID
         * Channel ID (for web)
         * Production Server URL

    5. **Activate Paytm on Cashfree:**
       * Share your production credentials with your Cashfree Account Manager.
       * Once this is done, the Paytm payment option will be activated on your account.

    For any queries, contact your Account Manager or submit a [Support Form](https://merchant.cashfree.com/auth/login).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Is the Drop-in Checkout flow still supported for mobile SDK integrations?">
    The Drop-in Checkout flow has been deprecated and is no longer under active development. Use the Web Checkout flow for mobile SDK integrations instead. See the [Android integration guide](/docs/payments/online/mobile/android) for setup instructions.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can we fetch the list of installed apps for mobile web integration?">
    No, it's not possible to fetch the list of installed apps from a mobile web environment. However, you can display the default UPI apps such as Google Pay, PhonePe, and Paytm on both Android and iOS devices.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Is Kotak-811 supported as a PSP app for UPI Intent flow?">
    Kotak-811 is currently not supported as a PSP app for the UPI Intent flow. For the currently supported UPI Intent applications and integration steps, see [UPI Intent in JS SDK](/docs/payments/online/mobile/misc/upi_intent_support_js_sdk).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Why is the UPI Intent option not appearing in my Android WebView checkout?">
    UPI Intent relies on redirection to a UPI application and is generally supported through mobile app flows. If you use a WebView checkout through the JS SDK, you must implement the intent redirection changes. Cashfree must also enable a feature flag on your account to display the supported UPI Intent apps in checkout. Submit a request through the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1). See [UPI Intent in JS SDK](/docs/payments/online/mobile/misc/upi_intent_support_js_sdk) for implementation details.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What should I do if my account is not eligible for S2S (Order Pay API) enablement?">
    If your account is not eligible for S2S (Server-to-Server) enablement or the [Order Pay API](/docs/api-reference/payments/latest/payments/order-pay), you can use the [Elements SDK](/docs/payments/online/element/introduction) as an alternative integration method.

    <iframe title="FAQs feedback component" />
  </Accordion>
</AccordionGroup>


# iOS Integration
Source: https://www.cashfree.com/docs/payments/online/mobile/ios

Integrate the Cashfree Payment Gateway iOS SDK to embed a WebView-based payment checkout in your iOS app, supporting deployment targets from iOS 11 onwards.

Cashfree's iOS SDK provides a streamlined payment solution that integrates the payment gateway into your iOS applications through a WebView-based checkout implementation, supporting iOS deployment target 11 and above.

## Key benefits

The iOS SDK offers the following advantages for your payment integration:

* **Simplified integration**: Provides a pre-built SDK that delivers an optimised payment experience for iOS applications.

* **Secure and compliant**: Securely handles payment processing with built-in security measures managed by the SDK.

* **Multiple integration methods**: Supports both Swift Package Manager (recommended) and CocoaPods for easy installation.

## Prerequisites

Ensure you complete the following tasks before starting the integration:

* Create a [Cashfree Merchant Account](https://merchant.cashfree.com/merchants/signup).
* Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and generate an **App ID** and **Secret Key**. Learn how to [generate API keys](/docs/api-reference/authentication#generate-api-keys).

The iOS integration consists of three essential steps:

<CardGroup>
  <Card title="Step 1" icon="money-bill-wave" href="/docs/payments/online/mobile/ios#step-1-create-an-order-server-side">
    Create an order
  </Card>

  <Card title="Step 2" icon="desktop" href="/docs/payments/online/mobile/ios#step-2-open-the-payment-page-client-side">
    Open the payment page
  </Card>

  <Card title="Step 3" icon="circle-check" href="/docs/payments/online/mobile/ios#step-3-confirm-the-payment-server-side">
    Confirm the payment
  </Card>
</CardGroup>

The step-by-step guide for each step of the integration process is as follows:

## Step 1: Create an order <Badge>Server-side</Badge>

To integrate the Cashfree Payment Gateway, you must first create an order. Complete this step before you process any payments. Configure an endpoint on your server to handle order creation. You can't call this API from the client-side.

<Note>Create orders through your server as this API requires your secret key. Don't call it directly from your mobile application.</Note>

##### API request for creating an order

Here's a sample request for creating an order using your desired backend language. Cashfree offers backend [SDKs](/docs/api-reference/payments/sdk#server-sdk) to simplify the integration process.

<CodeGroup>
  ```bash curl theme={"dark"}
  curl --location 'https://sandbox.cashfree.com/pg/orders' \
  --header 'X-Client-Secret: {{clientKey}}' \
  --header 'X-Client-Id: {{clientId}}' \
  --header 'x-api-version: 2025-01-01' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data-raw '{
    "order_amount": 10.10,
    "order_currency": "INR",
    "customer_details": {
      "customer_id": "USER123",
      "customer_name": "joe",
      "customer_email": "joe.s@cashfree.com",
      "customer_phone": "+919876543210"
    },
    "order_meta": {
      "return_url": "https://b8af79f41056.eu.ngrok.io?order_id=order_123"
    }
  }'
  ```

  ```javascript nodejs theme={"dark"}
  import { Cashfree, CFEnvironment } from "cashfree-pg";

  const cashfree = new Cashfree(
  	CFEnvironment.PRODUCTION,
  	"{Client ID}",
  	"{Client Secret Key}"
  );

  function createOrder() {
  	var request = {
  		order_amount: "1",
  		order_currency: "INR",
  		customer_details: {
  			customer_id: "node_sdk_test",
  			customer_name: "",
  			customer_email: "example@gmail.com",
  			customer_phone: "9999999999",
  		},
  		order_meta: {
  			return_url:
  				"https://test.cashfree.com/pgappsdemos/return.php?order_id=order_123",
  		},
  		order_note: "",
  	};

  	cashfree
  		.PGCreateOrder(request)
  		.then((response) => {
  			console.log("Order created successfully:", response.data);
  		})
  		.catch((error) => {
  			console.error("Error setting up order request:", error.response.data);
  		});
  }
  ```

  ```python python theme={"dark"}
  from cashfree_pg.models.create_order_request import CreateOrderRequest
  from cashfree_pg.api_client import Cashfree
  from cashfree_pg.models.customer_details import CustomerDetails


  Cashfree.XClientId = {Client ID}
  Cashfree.XClientSecret = {Client Secret Key}
  Cashfree.XEnvironment = Cashfree.XSandbox
  x_api_version = "2023-08-01"

  def create_order():
          customerDetails = CustomerDetails(customer_id="123", customer_phone="9999999999")
          createOrderRequest = CreateOrderRequest(order_amount=1, order_currency="INR", customer_details=customerDetails)
          try:
              api_response = Cashfree().PGCreateOrder(x_api_version, createOrderRequest, None, None)
              print(api_response.data)
          except Exception as e:
              print(e)
  ```

  ```java java theme={"dark"}
  import com.cashfree.*;

  Cashfree.XClientId = {Client Key};
  Cashfree.XClientSecret = {Client Secret Key};
  Cashfree.XEnvironment = Cashfree.SANDBOX;

  static void createOrder() {
    CustomerDetails customerDetails = new CustomerDetails();
    customerDetails.setCustomerId("123");
    customerDetails.setCustomerPhone("9999999999");

    CreateOrderRequest request = new CreateOrderRequest();
    request.setOrderAmount(1.0);
    request.setOrderCurrency("INR");
    request.setCustomerDetails(customerDetails);
    try {
      Cashfree cashfree = new Cashfree();
      ApiResponse<OrderEntity> response = cashfree.PGCreateOrder("2023-08-01", request, null, null, null);
      System.out.println(response.getData().getOrderId());

    } catch (ApiException e) {
      throw new RuntimeException(e);
    }
  }
  ```

  ```go go theme={"dark"}
  import (
    cashfree "github.com/cashfree/cashfree-pg/v3"
  )

  func createOrder() {

  clientId := {Client ID}
  clientSecret := {Client Secret Key}
  cashfree.XClientId = &clientId
  cashfree.XClientSecret = &clientSecret
  cashfree.XEnvironment = cashfree.SANDBOX

  request := cashfree.CreateOrderRequest{
  		OrderAmount: 1,
  		CustomerDetails: cashfree.CustomerDetails{
  			CustomerId:    "1",
  			CustomerPhone: "9999999999",
  		},
  		OrderCurrency: "INR",
  		OrderSplits:   []cashfree.VendorSplit{},
  	}
  	version := "2023-08-01"
  	response, httpResponse, err := cashfree.PGCreateOrder(&version, &request, nil, nil, nil)
  	if err != nil {
  		fmt.Println(err.Error())
  	} else {
  		fmt.Println(httpResponse.StatusCode)
  		fmt.Println(response)
      }
  }
  ```

  ```csharp .net theme={"dark"}
  using cashfree_pg.Client;
  using cashfree_pg.Model;

  Cashfree.XClientId = {Client ID};
  Cashfree.XClientSecret = {Client Secret Key};
  Cashfree.XEnvironment = Cashfree.PRODUCTION;
  var cashfree = new Cashfree();
  var xApiVersion = "2023-08-01";

  void CreateOrder() {
      var customerDetails = new CustomerDetails("123", null, "9999999999");
      var createOrdersRequest = new CreateOrderRequest(null, 1.0, "INR", customerDetails);
      try {
          // Create Order
          var result = cashfree.PGCreateOrder(xApiVersion, createOrdersRequest, null, null, null);
          Console.WriteLine(result);
          Console.WriteLine(result.StatusCode);
          Console.WriteLine((result.Content as OrderEntity));
      } catch (ApiException e) {
          Console.WriteLine("Exception when calling PGCreateOrder: " + e.Message);
          Console.WriteLine("Status Code: " + e.ErrorCode);
          Console.WriteLine(e.StackTrace);
      }
  }
  ```

  ```php php theme={"dark"}
  \Cashfree\Cashfree::$XClientId = "<x-client-id>";
  \Cashfree\Cashfree::$XClientSecret = "<x-client-secret>";
  \Cashfree\Cashfree::$XEnvironment = Cashfree\Cashfree::$SANDBOX;

  $cashfree = new \Cashfree\Cashfree();

  $x_api_version = "2023-08-01";
  $create_orders_request = new \Cashfree\Model\CreateOrdersRequest();
  $create_orders_request->setOrderAmount(1.0);
  $create_orders_request->setOrderCurrency("INR");
  $customer_details = new \Cashfree\Model\CustomerDetails();
  $customer_details->setCustomerId("123");
  $customer_details->setCustomerPhone("9999999999");
  $create_orders_request->setCustomerDetails($customer_details);

  try {
      $result = $cashfree->PGCreateOrder($x_api_version, $create_orders_request);
      print_r($result);
  } catch (Exception $e) {
      echo 'Exception when calling PGCreateOrder: ', $e->getMessage(), PHP_EOL;
  }
  ```
</CodeGroup>

After successfully creating an order, you will receive a unique `order_id` and `payment_session_id` that you need for subsequent steps.

You can view the complete API request and response for `/orders` in the [Create Order API](/docs/api-reference/payments/latest/orders/create-order).

<Note>
  To show a short purchase description on checkout, such as a booking reference or route, add `checkout_context` to the `order_tags` object in the Create Order request above.

  ```json theme={"dark"}
  "order_tags": {
    "checkout_context": "Flight booking DEL-BOM, 12 JUN at 14:30"
  }
  ```

  For details about how checkout displays this text in a context card, see [Contextual Checkout](/docs/payments/features/contextual-checkout).
</Note>

## Step 2: Open the payment page <Badge>Client-side</Badge>

Web Checkout is a streamlined payment solution that integrates Cashfree's payment gateway into your iOS app through the SDK. This implementation uses a WebView to provide a secure, feature-rich payment experience.

Your customers are presented with a familiar web interface where they can enter their payment details and complete their transaction seamlessly. All payment logic, UI components, and security measures are managed by the SDK, eliminating the need for complex custom implementation.

### 1. Set up the SDK

##### Swift Package Manager (recommended)

The recommended way to integrate the Cashfree iOS SDK is by using Swift Package Manager. You can do this through the Xcode interface.

To add the Cashfree iOS SDK to your project, follow these steps:

1. Open your project in Xcode.
2. Go to **File > Add Package Dependencies**.
3. Enter the repository address: [https://github.com/cashfree/core-ios-sdk.git](https://github.com/cashfree/core-ios-sdk.git).
4. Select the version rule (**Recommended:** *Up to Next Major Version*).
5. Choose the products you need:

   * **CashfreePG**—Complete Payment Gateway SDK (*recommended*)
   * **CashfreePGCoreSDK**—Core payment processing
   * **CashfreePGUISDK**—UI components
   * **CashfreeAnalyticsSDK**—Analytics and tracking
   * **CFNetworkSDK**—Networking layer

##### CocoaPods

In your pod file add the following line `pod 'CashfreePG', '2.4.0'`. Install the package using `pod install`.

##### iOS configuration

To provide UPI payments on iOS you need to enable the following permissions in your app. Open the `info.plist` file and add the below content:

```xml theme={"dark"}
<key>LSApplicationQueriesSchemes</key>

</array>
		<string>amazonpay</string>
		<string>upi</string>
		<string>credpay</string>
		<string>bhim</string>
		<string>paytmmp</string>
		<string>phonepe</string>
		<string>tez</string>
		<string>navipay</string>
		<string>mobikwik</string>
		<string>myairtel</string>
		<string>popclubapp</string>
		<string>super</string>
		<string>kiwi</string>
    <string>simplypayupi</string>
    <string>whatsapp</string>
</array>
```

### 2. Complete the payment

To complete the payment, follow these steps:

1. Create a CFSession object.
2. Create a Web Checkout Payment object.
3. Set payment callback.
4. Initiate the payment using the payment object created.

#### Create a session

This object contains essential information about the order, including the payment session ID (`payment_session_id`) and order ID (`order_id`) obtained from Step 1. It also specifies the environment (sandbox or production).

<CodeGroup>
  ```swift swift theme={"dark"}
  do {
      let session = try CFSession.CFSessionBuilder()
          .setOrderID(order_id)
          .setPaymentSessionId(payment_session_id)
          .setEnvironment(Utils.environment)
          .build()
        return session;
  } catch let e {
      let error = e as! CashfreeError
      self.createAlert(title: "Warning", message: error.localizedDescription)
  }
  ```

  ```objective-c objective-c theme={"dark"}
  @try {
      CFSessionBuilder* sessionBuilder = [[CFSessionBuilder alloc] init];
      sessionBuilder = [sessionBuilder setPaymentSessionId:paymentSessionId];
      sessionBuilder = [sessionBuilder setOrderID:orderId];
      sessionBuilder = [sessionBuilder setEnvironment:CFENVIRONMENTPRODUCTION];
      CFSession* session = [sessionBuilder buildAndReturnError:nil];
          
  } @catch (NSException *exception) {
      NSLog(@"%@", exception);
  }
  ```
</CodeGroup>

#### Create a web checkout payment object

Use `CFWebCheckoutPayment` to create the payment object. This object accepts a `CFSession`, like the one created in the previous step.

<CodeGroup>
  ```swift swift theme={"dark"}
  let webCheckoutPayment = try CFWebCheckoutPayment.CFWebCheckoutPaymentBuilder()
      .setSession(session)
      .build()
  ```

  ```objective-c objective-c theme={"dark"}
  @try {
      CFWebCheckoutPaymentBuilder* web = [[CFWebCheckoutPaymentBuilder alloc] init];
      web = [web setSession:session];
      CFWebCheckoutPayment* webPayment = [web buildAndReturnError:nil];
          
  } @catch (NSException *exception) {
      NSLog(@"%@", exception);
  }
  ```
</CodeGroup>

#### Setup callback

Set up callback handlers to handle events after payment processing. The callback implements CFResponseDelegate to handle payment responses and errors. Initialise it in `viewDidLoad` by calling `CFPaymentGatewayService.getInstance().setCallback(self)`.

* onError: Handles payment failures by displaying an alert with error details
* verifyPayment: Called when payment needs merchant verification, shows status alert to user

<Tip>Make sure to set the callback at activity's onCreate as this also handles the activity restart cases.</Tip>

<CodeGroup>
  ```swift swift theme={"dark"}
  extension ViewController: CFResponseDelegate {
          
      func onError(_ error: CFErrorResponse, order_id: String) {
          self.createAlert(title: error.status ?? "ERROR", message: error.message ?? "error_message_not_present")
      }
      
      func verifyPayment(order_id: String) {
          self.createAlert(title: "VERIFY PAYMENT", message: "Payment has to be verified by merchant for \(order_id)")
      }
          
  }

  // Class Variable
  let pgService = CFPaymentGatewayService.getInstance()

  override func viewDidLoad() {
     super.viewDidLoad()
     pgService.setCallback(self) 
  }
  ```
</CodeGroup>

#### Sample code

<CodeGroup>
  ```swift swift theme={"dark"}
  import CashfreeAnalyticsSDK
  import CashfreePG
  import CashfreePGCoreSDK
  import CashfreePGUISDK

  class ViewController: UIViewController, CFResponseDelegate {

    // Class Variable
    let pgService = CFPaymentGatewayService.getInstance()

    override func viewDidLoad() {
      super.viewDidLoad()
      pgService.setCallback(self)
    }

    @IBAction func webCheckoutButtonTapped(_ sender: Any) {
      do {
        let session = try CFSession.CFSessionBuilder()
          .setPaymentSessionId(payment_session_id)
          .setOrderID(order_id)
          .setEnvironment(Utils.environment)
          .build()
        let webCheckoutPayment = try CFWebCheckoutPayment.CFWebCheckoutPaymentBuilder()
          .setSession(session)
          .build()
        try pgService.doPayment(webCheckoutPayment, viewController: self)
      } catch let e {
        let err = e as! CashfreeError
        print(err.description)
      }

    }

    // Protocol Implementation
    func onError(_ error: CFErrorResponse, order_id: String) {
      self.createAlert(
        title: error.status ?? "ERROR", message: error.message ?? "error_message_not_present")
    }

    func verifyPayment(order_id: String) {
      self.createAlert(
        title: "VERIFY PAYMENT", message: "Payment has to be verified by merchant for \(order_id)")
    }
  }
  ```

  ```objective-c objective-c theme={"dark"}
  @try {
      CFSessionBuilder* sessionBuilder = [[CFSessionBuilder alloc] init];
      sessionBuilder = [sessionBuilder setPaymentSessionId:paymentSessionId];
      sessionBuilder = [sessionBuilder setOrderID:orderId];
      sessionBuilder = [sessionBuilder setEnvironment:CFENVIRONMENTPRODUCTION];
      CFSession* session = [sessionBuilder buildAndReturnError:nil];
      
      CFWebCheckoutPaymentBuilder* web = [[CFWebCheckoutPaymentBuilder alloc] init];
      web = [web setSession:session];
      CFWebCheckoutPayment* webPayment = [web buildAndReturnError:nil];
      
      CFPaymentGatewayService* pg = [CFPaymentGatewayService alloc];
      [pg setCallback:self];
      [pg doPayment:webPayment viewController:self error:nil];
          
  } @catch (NSException *exception) {
      NSLog(@"%@", exception);
  }
  ```
</CodeGroup>

## Step 3: Confirm the payment <Badge>Server-side</Badge>

After the customer completes the payment, you must confirm the payment status. Once the payment finishes, the user redirects back to your activity.

To verify an order you can call our `/pg/orders` endpoint from your backend. You can also use our SDK to achieve the same.

<CodeGroup>
  ```bash curl theme={"dark"}
  curl --request GET \
       --url https://sandbox.cashfree.com/pg/orders/{order_id} \
       --header 'accept: application/json' \
       --header 'x-api-version: 2025-01-01' \
       --header 'x-client-id: "YOUR APP ID GOES HERE"' \
       --header 'x-client-secret: "YOUR SECRET KEY GOES HERE"'
  ```

  ```javascript nodejs theme={"dark"}
  cashfree
  .PGFetchOrder("<order_id>")
  .then((response) => {
  	console.log("Order fetched successfully:", response.data);
  })
  .catch((error) => {
  	console.error("Error:", error.response.data.message);
  });
  ```

  ```python python theme={"dark"}
  from cashfree_pg.models.create_order_request import CreateOrderRequest
  from cashfree_pg.api_client import Cashfree
  from cashfree_pg.models.customer_details import CustomerDetails
  from cashfree_pg.models.order_meta import OrderMeta

  Cashfree.XClientId = "<x-client-id>"
  Cashfree.XClientSecret = "<x-client-secret>"
  Cashfree.XEnvironment = Cashfree.SANDBOX
  x_api_version = "2023-08-01"

  try:
      api_response = Cashfree().PGFetchOrder(x_api_version, "order_3242X4jQ5f0S9KYxZO9mtDL1Kx2Y7u", None)
      print(api_response.data)
  except Exception as e:
      print(e)

  ```

  ```java java theme={"dark"}
  import com.cashfree.*;
  //other code

  try {
      Cashfree.XClientId = "<x-client-id>";
      Cashfree.XClientSecret = "<x-client-secret>";
      Cashfree.XEnvironment = Cashfree.SANDBOX;

      Cashfree cashfree = new Cashfree();
      String xApiVersion = "2023-08-01";

      ApiResponse<OrderEntity> responseFetchOrder = cashfree.PGFetchOrder(xApiVersion, "<order_id>", null, null, null);
      System.out.println(response.getData().getOrderId());
  } catch (ApiException e) {
      throw new RuntimeException(e);
  }
  ```

  ```go go theme={"dark"}
  version := "2023-08-01"
  response, httpResponse, err := cashfree.PGFetchOrder(&version, "<order_id>", nil, nil, nil)
  if err != nil {
  	fmt.Println(err.Error())
  } else {
  	fmt.Println(httpResponse.StatusCode)
  	fmt.Println(response)
  }
  ```

  ```csharp .net theme={"dark"}
  using cashfree_pg.Client;
  using cashfree_pg.Model;

  Cashfree.XClientId = "<x-client-id>";
  Cashfree.XClientSecret = "<x-client-secret>";
  Cashfree.XEnvironment = Cashfree.SANDBOX;
  var cashfree = new Cashfree();
  var xApiVersion = "2023-08-01";

  try {
      var result = cashfree.PGFetchOrder(xApiVersion, "<order_id>>", null, null);
      Console.WriteLine(result);
      Console.WriteLine(result.StatusCode);
      Console.WriteLine((result.Content as OrderEntity));
  } catch (ApiException e) {
      Console.WriteLine("Exception when calling PGFetchOrder: " + e.Message);
      Console.WriteLine("Status Code: " + e.ErrorCode);
      Console.WriteLine(e.StackTrace);
  }
  ```

  ```php php theme={"dark"}
  $x_api_version = "2023-08-01";
  try {
      $response = $cashfree->PGFetchOrder($x_api_version, "<order_id>");
      print_r($response);
  } catch (Exception $e) {
      echo 'Exception when calling PGFetchOrder: ', $e->getMessage(), PHP_EOL;
  }
  ```
</CodeGroup>

<Note>
  Always verify the order status before you deliver services to the customer. You can use the [Get Order API](/docs/api-reference/payments/latest/orders/get-order) for this. An order is successful when the `order_status` is `PAID`.
</Note>

## Testing

After you integrate the checkout functionality, verify that it opens the Cashfree-hosted payment page. Follow these steps to test:

1. Click the checkout button.
2. Verify you're redirected to the Cashfree Checkout payment page.

## Error codes

To confirm the error returned in your iOS application, you can view the error codes that are exposed by the SDK.

<Accordion title="Show error codes">
  **CashfreeError** is an Enum that inherits Foundations **Error** class. The following are some of the error codes that are exposed by the SDK:

  | Error codes | Message |
  | - | - |
  | MISSING\_CALLBACK | The callback is missing in the request. |
  | ORDER\_ID\_MISSING | The "order\_id" is missing in the request. |
  | CARD\_EMI\_TENURE\_MISSING | The "emi\_tenure" is missing or invalid (It has to be greater than 0). |
  | INVALID\_UPI\_APP\_ID\_SENT | The id sent is invalid. The value has to be one of the following: "tez://","phonepe://","paytmmp\://","bhim://. Please refer the note in CFUPI class for more details |
  | INVALID\_PAYMENT\_OBJECT\_SENT | The payment object that is set does not match any payment mode. Please set the correct payment mode and try again. |
  | WALLET\_OBJECT\_MISSING | The CFWallet object is missing in the request |
  | NETBANKING\_OBJECT\_MISSING | The CFNetbanking object is missing in the request. |
  | UPI\_OBJECT\_MISSING | The CFUPI object is missing in the request. |
  | CARD\_OBJECT\_MISSING | The CFCard object is missing in the request. |
  | INVALID\_WEB\_DATA | The url seems to be corrupt. Please reinstantiate the order. |
  | SESSION\_OBJECT\_MISSING | The "session" is missing in the request |
  | PAYMENT\_OBJECT\_MISSING | The "payment" is missing in the request |
  | ENVIRONMENT\_MISSING | The "environment" is missing in the request. |
  | ORDER\_TOKEN\_MISSING | The "order\_token" is missing in the request. |
  | CHANNEL\_MISSING | The "channel" is missing in the request. |
  | CARD\_NUMBER\_MISSING | The "card\_number" is missing in the request. |
  | CARD\_EXPIRY\_MONTH\_MISSING | The "card\_expiry\_mm" is missing in the request. |
  | CARD\_EXPIRY\_YEAR\_MISSING | The "card\_expiry\_yy" is missing in the request. |
  | CARD\_CVV\_MISSING | The "card\_cvv" is missing in the request. |
  | UPI\_ID\_MISSING | The "upi\_id" is missing in the request |
  | WALLET\_CHANNEL\_MISSING | The "channel" is missing in the wallet payment request |
  | WALLET\_PHONE\_MISSING | The "phone number" is missing in the wallet payment request |
  | NB\_BANK\_CODE\_MISSING | The "bank\_code" is missing in the request |
</Accordion>

<div>
  <p>Affiliate partner program</p>

  <p>As a developer building payment experiences for your clients, you can earn additional income while providing them with industry-leading payment solutions.</p>

  <p>Join the <a href="https://partner.cashfree.com/partner-ui/authentication/signup?source-action=Affiliate%20Program%20LP&action=Sign%20Up&button-id=StartNow_CashfreeAffiliatePartnerProgram">Cashfree affiliate partner program</a> and get rewarded every time your clients use Cashfree.</p>

  <p>**What you get:**</p>

  <ul>
    <li>Earn up to 0.25% commission on every transaction.</li>
    <li>Become a trusted fintech partner for your clients.</li>
    <li>Access to a dedicated partner manager for expert support.</li>
  </ul>

  <p>**What your clients get:**</p>

  <ul>
    <li>Instant activation and go live in minutes.</li>
    <li>Industry-best success rate across all payment modes.</li>
    <li>Effortless acceptance of international payments in 140+ currencies.</li>
  </ul>

  <p>Get started today. <a href="https://partner.cashfree.com/partner-ui/authentication/signup?source-action=Affiliate%20Program%20LP&action=Sign%20Up&button-id=StartNow_BecomeAPartner">Become a partner now</a>.</p>
</div>

<snippet>snippets/related-topics-loader.mdx</snippet>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/payments/latest/orders/create-order">Create Order API</a></li>
    <li><a href="/docs/api-reference/payments/latest/orders/get-order">Get Order API</a></li>
    <li><a href="https://github.com/cashfree/core-ios-sdk">iOS SDK on GitHub</a></li>
  </ul>
</div>


# Cashfree Integrity
Source: https://www.cashfree.com/docs/payments/online/mobile/misc/cashfree_integrity

Use Cashfree Integrity to block unauthorised tampering of merchant apps by verifying installer packages against Play Store, App Store, and approved sources.

Cashfree Integrity serves as an essential safeguard, preventing unauthorised tampering, and distribution of merchant applications, ensuring the security of your digital ecosystem.
Merchant applications undergo a comprehensive evaluation process by their respective stores such as Google Play, App Store, Samsung Store and so on. Cashfree Integrity provides a robust defence mechanism, allowing only applications to be installed from regulated stores and ensures only these applications receive payments.

### What is Cashfree Integrity

Whenever an application is installed from any regulated store such as Play Store, or App Store, Cashfree Integrity checks if the application is installed from regulated stores and ensures their compliance and makes sure the application is not tampered by any middle man.

Cashfree Integrity works by extracting the package name of the installer and compares it with authorised sources and allows the transaction to flow through. In case the installer package is not from verified stores, Cashfree Integrity blocks the transaction and your customer will not be able to perform that transaction.

### Advantages

Cashfree Integrity shields all the complexities of checking the installer package ensuring transactions are passed only from valid applications installed from verified stores.
This implementation streamlines the payment flow by enabling us to block payments directly if the aforementioned checks fail.

Cashfree also supports additional app stores, including the Samsung Galaxy Store, Indus Appstore, Vivo App Store, Xiaomi GetApps, OPPO App Market, OnePlus App Market, and Amazon Appstore.

<Note>
  If your mobile application is distributed through an app store other than the Google Play Store or the Apple App Store, you must whitelist the installer package name of that app store before you can use Checkout in the production environment.

  To whitelist the installer package name for your account, submit a request through the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1). Our support team will review your request and whitelist the installer package name.
</Note>

## FAQs

<AccordionGroup>
  <Accordion title="Can I test my app if it is not yet published on the Play Store or App Store?">
    Yes. In the sandbox environment, Cashfree Integrity does not enforce store verification, so you can test without a Play Store or App Store listing. For production testing, distribute your app through the Play Store's internal testing track instead of sideloading the APK directly. This satisfies Cashfree Integrity's store verification requirement without requiring a public release. For setup instructions, see [Integrity prod setup](/docs/payments/online/mobile/misc/cashfree_integrity_prod_testing).
  </Accordion>

  <Accordion title="What are the stores supported by Cashfree Integrity?">
    Google Play Store, Apple App Store are the stores supported by Cashfree Integrity.
  </Accordion>

  <Accordion title="When will the payment fail?">
    If any merchant distributes the APK file through any unauthorised channel, Cashfree Integrity will block any payment happening through that application. In case you are testing in production mode, the payments will fail since the application is not installed from an authorised source. You can simulate production payments by doing a beta release of your application.

    [Setup for PROD test](/docs/payments/online/mobile/misc/cashfree_integrity_prod_testing)
  </Accordion>

  <Accordion title="What are the security mechanisms available as of now in Cashfree Integrity?">
    * Transactions happen only through verified package names.
    * Package names are whitelisted and ensure that applications are installed from verified stores.
  </Accordion>
</AccordionGroup>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/payments/online/mobile/misc/cashfree_integrity_prod_testing">Setup for PROD test</a></li>
  </ul>
</div>


# Integrity Prod Setup
Source: https://www.cashfree.com/docs/payments/online/mobile/misc/cashfree_integrity_prod_testing

Set up Cashfree Integrity for production testing by distributing your Android app through the Play Store internal track instead of sideloading APKs.

When you install your app from a source other than the Play Store and test it in a production environment, the Cashfree mobile SDK `Android, React Native, Flutter, Cordova, Ionic, Capacitor` blocks the transaction and you get the following error.

```json json theme={"dark"}
{
  "message": "com.google.android.packageinstaller is not a trusted source. App should be installed from play store or another whitelisted app store.",
  "code": "installer_package_not_approved",
  "type": "feature_not_enabled"
}
```

In this case, the SDK does not load the page and you get an error in the `onPaymentFailure` callback. Check the error log for details.

Below are the sample scenarios when Cashfree Integrity will fail in the `PRODUCTION` Environment ( In Sandbox, it will always work).

<Warning>
  Trying to directly run from Android Studio/Eclipse or any IDE

  Trying to install from Gallery/File Explorer/Google Drive/Slack/Whatsapp or any other link
</Warning>

### How to properly test in production env?

To test in production, upload your app bundle/APK to the Play Store under an internal testing environment and invite your testing team to test it.

### How to do the internal testing setup?

<Tip>
  Internal testing is useful to quickly distribute builds to a small set of testers.
  This test is used to perform the initial QA checks. You can distribute your application among 100 invited testers. The feedback from your test users won’t affect your app’s public rating it is only visible to the Developer Account.

  After publishing the internal test for the first time, it may take few hours for your test link to be available to testers. After that, any new release is available in a few hours. This build is directly available for testing without review.
</Tip>

### Create a tester list and share the invitation

1. Open the [Play console](https://play.google.com/console/u/0/developers/9086506936822464322/app-list) and open the [Internal testing](https://play.google.com/console/u/0/developers/9086506936822464322/app/4972688618868666427/tracks/internal-testing) page under Testing.
2. Select the [Testers tab](https://play.google.com/console/u/0/developers/9086506936822464322/app/4972688618868666427/tracks/internal-testing?tab=testers)
3. Click on Create email list which opens a popup for adding multiple emails.
4. Add email addresses separated by commas or click Upload CSV file. If you use a .CSV file, put each email address on its line.
5. Select Save Changes.
6. As shown in the below screenshot Copy the link from the Tester tab.
7. Now share this link with all testers.
8. Testers have to open this link in Browser where it is logged in with a shared email.
   <img alt="img.png" />
9. When you open the invitation link in the browser, you can find this type of invitation information and click **Accept Invitation**.
   <img alt="img_1.png" />
10. Create a release for the internal track in the Play Console and upload an app bundle. The app is then available on the Play Store for testers to download.

### Turn on internal app sharing

If your app has any build in production then these steps are optional but if your app has not live any version yet then this step must be followed by testers.

1. Open the Google Play Store app Google Play.
2. Tap Menu Menu > Settings.
3. In the “About” section, tap the Play Store version 7 times.
4. After the Internal app sharing setting appears, tap the switch to turn on internal app sharing. Tap Turn on.
   <img alt="img_2.png" />

### Download app

1. Open the Play Store and make sure the sign-in email is your tester’s email address.
2. Now search the application on the store.
3. You can find the application shown with an internal beta label, you can download this application and start testing.
4. Make sure the Android device has Developer Mode enabled.

<img />

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/payments/online/mobile/misc/cashfree_integrity">Cashfree Integrity</a></li>
    <li><a href="https://play.google.com/console/u/0/developers/9086506936822464322/app-list">Play Console</a></li>
  </ul>
</div>


# UPI Intent Test APK
Source: https://www.cashfree.com/docs/payments/online/mobile/misc/cashfree_upi_simulator_apk

Install the Cashfree UPI Intent Simulator APK on a sandbox Android device or emulator to simulate UPI Intent payment success and failure flows while testing.

## Overview

For UPI intent flows in SANDBOX env, you can simulate payment success/failure scenarios with our simulator app.
Download and Install the app from the given link in your real device or Android emulator.

[UPI Intent Simulator App](https://github.com/cashfree/nextgen-android/blob/master/assets/SampleTestUPISimulator.apk)

When you run your app and go to the payment page, it will show our UPI intent simulator app.

<img />

Select the Cashfree test UPI app and it will open the page where you can simulate success/failure.

<img />

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="https://github.com/cashfree/nextgen-android/blob/master/assets/SampleTestUPISimulator.apk">UPI Intent Simulator App</a></li>
  </ul>
</div>


# UPI Intent in JS SDK
Source: https://www.cashfree.com/docs/payments/online/mobile/misc/upi_intent_support_js_sdk

Enable UPI Intent inside the Cashfree JS SDK web checkout embedded in Android, React Native, Flutter, and Cordova apps using feature flags and URL handlers.

Merchants integrating the Cashfree Web checkout using Cashfree JS SDK. But they are unable to see the UPI intent option on the checkout page as the Cashfree checkout page is opening on Webview.

This document provides guidance for merchants developing their applications on platforms such as `Android, React Native, Flutter, Cordova` who have integrated the Cashfree JS SDK.

<Note>
  When using Cashfree checkout inside a WebView, you must explicitly handle UPI deep links (for example, `upi://pay`, `gpay://`, `phonepe://`) to launch native UPI apps. If you don't handle them, the WebView tries to load the UPI deep link as a regular web page, which causes errors such as "Web Page not available". For implementation details, see the Android and iOS sections on this page.
</Note>

<Note>If you are using Cashfree Mobile SDK, refer to [Mobile SDK](/docs/tools-ai/sdk#mobile-sdks).</Note>

<Tip>
  Before testing UPI Intent, ensure you are testing on a device that has the relevant UPI apps installed and SIM binding is completed in the UPI PSP app (such as PhonePe, GPay, or Paytm) on that device. A UPI app that is installed but not SIM-bound does not appear as a payment option on the checkout page.
</Tip>

### Feature flag based solution <Badge>Client-side</Badge>

Our checkout page provides the capability to display default UPI apps, including `PhonePe, GPay, and Paytm`, along with an option to pay via any UPI app. This feature ensures that these UPI apps are visible on the checkout page, regardless of whether they are installed on the user's device.

When a user selects a UPI app, merchants are responsible for handling the redirection. Only a minimal code snippet is required on the merchant's side to handle the UPI app click and manage the subsequent redirection process.

<AccordionGroup>
  <Accordion title="iOS">
    <CodeGroup>
      ```swift iOS theme={"dark"}
      // Override webView(_:decidePolicyFor:decisionHandler:) method in your WKNavigationDelegate.
      func webView(_ webView: WKWebView, decidePolicyFor navigationAction: WKNavigationAction, decisionHandler: @escaping (WKNavigationActionPolicy) -> Void) {
      guard let url = navigationAction.request.url, let scheme = url.scheme else {
      decisionHandler(.allow)
      return
      }

            if (["upi",
                "tez",
                "gpay",
                "paytmmp",
                "phonepe",
                "amazonpay",
                "credpay",
                "bhim",
                "navipay",
                "mobikwik",
                "myairtel",
                "popclubapp",
                "super",
                "kiwi",
                "simplypayupi",
                "whatsapp-consumer",
                "tnupi",
                "postpe",
                "imobile",
                "payzapp",
                "fpupi",
                "snapmint"].contains(scheme)) {
                    // Open UPI app from here
                    if UIApplication.shared.canOpenURL(url) {
                        UIApplication.shared.open(url, options: [:], completionHandler: nil)
                    } else {
                        //handle no app scenario
                    }
                    decisionHandler(.cancel)
                    return
            }
            decisionHandler(.allow)
        }
      ```
    </CodeGroup>

    <Note>
      iOS requires every scheme checked with `canOpenURL` to be declared upfront in your app's `info.plist`, otherwise the check silently returns `false`. For the full iOS SDK v4 UPI Intent configuration, see the [iOS SDK v4 UPI Intent documentation](/docs/payments/online/mobile/ios).

      ```xml Info.plist theme={"dark"}
      <key>LSApplicationQueriesSchemes</key>
      <array>
        <string>upi</string>
        <string>tez</string>
        <string>gpay</string>
        <string>paytmmp</string>
        <string>phonepe</string>
        <string>amazonpay</string>
        <string>credpay</string>
        <string>bhim</string>
        <string>navipay</string>
        <string>mobikwik</string>
        <string>myairtel</string>
        <string>popclubapp</string>
        <string>super</string>
        <string>kiwi</string>
        <string>simplypayupi</string>
        <string>whatsapp-consumer</string>
        <string>tnupi</string>
        <string>postpe</string>
        <string>imobile</string>
        <string>payzapp</string>
        <string>fpupi</string>
        <string>snapmint</string>
      </array>
      ```
    </Note>
  </Accordion>

  <Accordion title="Android">
    <Note>
      On Android 11 and later (API level 30+), apps must declare which packages they intend to query before they can detect installed UPI applications. Add the following `<queries>` block to your `AndroidManifest.xml`:

      ```xml AndroidManifest.xml theme={"dark"}
      <queries>
          <intent>
              <action android:name="android.intent.action.VIEW" />
              <data android:scheme="upi" />
          </intent>
          <intent>
              <action android:name="android.intent.action.VIEW" />
              <data android:scheme="tez" />
          </intent>
          <intent>
              <action android:name="android.intent.action.VIEW" />
              <data android:scheme="gpay" />
          </intent>
          <intent>
              <action android:name="android.intent.action.VIEW" />
              <data android:scheme="phonepe" />
          </intent>
          <intent>
              <action android:name="android.intent.action.VIEW" />
              <data android:scheme="paytmmp" />
          </intent>
          <intent>
              <action android:name="android.intent.action.VIEW" />
              <data android:scheme="credpay" />
          </intent>
      </queries>
      ```

      Without this declaration, `queryIntentActivities` returns an empty list on Android 11 and later, and UPI apps do not appear.
    </Note>

    <CodeGroup>
      ```java Android theme={"dark"}
      // Override shouldOverrideUrlLoading method in your webview.
      @Override
      public boolean shouldOverrideUrlLoading(WebView view, String request) {
          if (request != null) {
              if (request.startsWith("intent://")) {
                  try {
                      final Intent intent = Intent.parseUri(request, Intent.URI_INTENT_SCHEME);
                      intent.setAction(Intent.ACTION_VIEW);
                      PackageManager pm = getPackageManager();
                      if (!pm.queryIntentActivities(intent, 0).isEmpty()) {
                          startActivity(intent);
                      } else {
                          // handle no app scenario
                      }
                  } catch (URISyntaxException e) {
                      // malformed intent uri, ignore/log
                  }
                  return true;
              }

              if (request.startsWith("upi://pay")
                      || request.startsWith("tez://")
                      || request.startsWith("paytmmp://")
                      || request.startsWith("phonepe://")
                      || request.startsWith("amazonpay://")
                      || request.startsWith("credpay://")
                      || request.startsWith("bhim://")
                      || request.startsWith("navipay://")
                      || request.startsWith("mobikwik://")
                      || request.startsWith("myairtel://")
                      || request.startsWith("popclubapp://")
                      || request.startsWith("super://")
                      || request.startsWith("kiwi://")
                      || request.startsWith("simplypayupi://")
                      || request.startsWith("whatsapp-consumer://")
                      || request.startsWith("tnupi://")
                      || request.startsWith("snapmint://")
              ) {
                  final Intent intent = new Intent();
                  intent.setAction(Intent.ACTION_VIEW);
                  intent.setData(Uri.parse(request));
                  PackageManager pm = getPackageManager();
                  final List<ResolveInfo> resInfo = pm.queryIntentActivities(intent, 0);
                  if (!resInfo.isEmpty()) {
                      startActivity(intent);
                  } else {
                      // handle no app scenario
                  }
                  return true;
              }
          }
          return false;
      }
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="React-Native">
    <CodeGroup>
      ```js JS theme={"dark"}
      // Override onShouldStartLoadWithRequest method in your webview.
      onShouldStartLoadWithRequest={event => {
        const url = event.url;
        const upiSchemePrefixes = [
          "upi://pay",              // default
          "intent://",               // Android only
          "tez://",                  // gpay
          "paytmmp://",               // paytm
          "phonepe://",               // phonepe
          "bhim://",                  // bhim
          "credpay://",               // cred
          "amazonpay://",             // amazonpay
          "navipay://",               // navi
          "mobikwik://",               // mobikwik
          "myairtel://",               // airtel
          "popclubapp://",             // pop
          "super://",                  // supermoney
          "kiwi://",                   // kiwi
          "simplypayupi://",           // simplypay
          "whatsapp-consumer://",      // whatsapp
          "tnupi://",                  // tataneu
          "postpe://",                 // bharatpe
          "imobile://",                // imobile
          "payzapp://",                // payzapp
          "fpupi://",                  // fampay
          "snapmint://",               // snapmint
        ];

        if (upiSchemePrefixes.some(prefix => url.startsWith(prefix))) {
          Linking.canOpenURL(url)
            .then(supported => {
              if (supported) {
                return Linking.openURL(url);
              }
              console.log("Not able to open");
            })
            .catch(err => {
              console.log("Failed to open UPI link", err);
            });
          return false;
        }
        return true;
      }}
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="Flutter">
    <CodeGroup>
      ```dart theme={"dark"}
      // Override shouldOverrideUrlLoading method in your webview.
      shouldOverrideUrlLoading: (controller, navigationAction) async {
        final uri = navigationAction.request.url;
        if (uri == null) return NavigationActionPolicy.ALLOW;

        const upiSchemes = {
          'upi',                // default
          'intent',             // Android only
          'tez',                 // gpay
          'paytmmp',              // paytm
          'phonepe',              // phonepe
          'bhim',                 // bhim
          'credpay',              // cred
          'amazonpay',            // amazonpay
          'navipay',              // navi
          'mobikwik',              // mobikwik
          'myairtel',              // airtel
          'popclubapp',            // pop
          'super',                 // supermoney
          'kiwi',                  // kiwi
          'simplypayupi',          // simplypay
          'whatsapp-consumer',     // whatsapp
          'tnupi',                 // tataneu
          'postpe',                // bharatpe
          'imobile',               // imobile
          'payzapp',               // payzapp
          'fpupi',                 // fampay
          'snapmint'               // snapmint
        };

        if (upiSchemes.contains(uri.scheme)) {
          print("Opening PSP app: ${uri.scheme}");
          if (await canLaunchUrl(uri)) {
            await launchUrl(uri, mode: LaunchMode.externalApplication);
          } else {
            print("No app found to handle $uri");
          }
          return NavigationActionPolicy.CANCEL;
        }
        return NavigationActionPolicy.ALLOW;
      }
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

<Note>To enable this feature flag on your account, submit a request through the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1), and our team will enable it for you. Once enabled, it may take 30–40 minutes for the supported UPI apps to reflect on the checkout. Ensure your client-side UPI deep-link handling is fully implemented and tested before requesting the flag. Enabling it before the implementation is complete breaks the checkout flow.</Note>

### Code based solution <Badge>Client-side</Badge>

The code-based solution lets you support UPI Intent without a feature flag by implementing WebView or JavaScript bridge changes directly in your Android, React Native, or Flutter application to intercept UPI Intent URLs and open the respective UPI apps. This approach gives you full control and does not require contacting support.

You have to write some custom logic in your mobile app while opening Cashfree checkout page. When you are loading Webview, Please register `JS bridge` with name `Android` and implement few of its method.

<AccordionGroup>
  <Accordion title="Android">
    [Sample code](https://github.com/kishan-cashfree/CFWebIntegrationSample/blob/245b0d655475ad5f5595437efc1e6eb503774f68/app/src/main/java/com/cashfree/webintegration/MainActivity.kt#L87)
  </Accordion>

  <Accordion title="React-Native">
    In this case, you have to write android native module
    [Native Module](https://github.com/kishan-cashfree/CFWebIntegrationRN/tree/master/android/app/src/main/java/com/cfwebintegrationrn)

    Use these native module in you JS/TS code
    [JS code](https://github.com/kishan-cashfree/CFWebIntegrationRN/tree/master/native)

    [Sample Usage](https://github.com/kishan-cashfree/CFWebIntegrationRN/blob/master/WebSitePaymentScreen.tsx)
  </Accordion>

  <Accordion title="Flutter">
    In this case, you have to write android native module
    [Native Module](https://github.com/kishan-cashfree/CFSamplewebviewFL/tree/master/android/app/src/main/kotlin/com/example/cfsamplewebviewfl)

    Use these native module in you Dart code
    [Dart Code](https://github.com/kishan-cashfree/CFSamplewebviewFL/blob/master/lib/ui/webview/customwebview.dart)

    [Sample Usage](https://github.com/kishan-cashfree/CFSamplewebviewFL/blob/master/lib/main.dart)
  </Accordion>

  <Accordion title="iOS">
    When loading WebView, register JS bridge with name `nativeProcess` and implement the required methods.

    [Sample code](https://github.com/cashfree/CFWebIntegrationSampleiOS)
  </Accordion>
</AccordionGroup>

### Frequently asked questions

<AccordionGroup>
  <Accordion title="Do I need a payment_session_id to enable UPI Intent when using a Cashfree Payment Link in a WebView?">
    No. If you are using the Cashfree Hosted Payment Link flow, you do not receive or need a `payment_session_id`. Use the `payment_link` URL returned in the API response and open it directly inside your Android WebView. UPI Intent in this flow is enabled via the feature flag on your account combined with the client-side deep-link handling described above.
  </Accordion>
</AccordionGroup>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="https://github.com/kishan-cashfree/CFWebIntegrationSample/blob/245b0d655475ad5f5595437efc1e6eb503774f68/app/src/main/java/com/cashfree/webintegration/MainActivity.kt#L87">Android Sample Code</a></li>
    <li><a href="https://github.com/kishan-cashfree/CFWebIntegrationRN/blob/master/WebSitePaymentScreen.tsx">React Native Sample</a></li>
    <li><a href="https://github.com/kishan-cashfree/CFSamplewebviewFL/blob/master/lib/main.dart">Flutter Sample</a></li>
    <li><a href="/docs/payments/online/mobile/android">Mobile SDK Docs</a></li>
  </ul>
</div>


# React Native Integration
Source: https://www.cashfree.com/docs/payments/online/mobile/react-native

Integrate the Cashfree Payment Gateway React Native SDK to add web checkout and UPI Intent payment flows to your React Native iOS and Android apps.

Cashfree's React Native SDK provides a payment solution that integrates the payment gateway into your React Native applications, supporting both Android (SDK version 19+) and iOS (deployment target 10.3+) platforms. The SDK offers multiple checkout flows including web checkout and UPI Intent checkout.

## Key benefits

The React Native SDK offers the following advantages for your payment integration:

* **Multiple checkout flows**: Provides web checkout and UPI Intent checkout options to suit different integration needs.

* **Cross-platform support**: Seamlessly supports both Android and iOS platforms from a single codebase.

* **Secure and compliant**: Securely handles payment processing with built-in security measures managed by the SDK.

## Prerequisites

Ensure you complete the following tasks before starting the integration:

* Create a [Cashfree Merchant Account](https://merchant.cashfree.com/merchants/signup).
* Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and generate an **App ID** and **Secret Key**. Learn how to [generate API keys](/docs/api-reference/authentication#generate-api-keys).
* Ensure your application complies with Cashfree's [Integrity standards](/docs/payments/online/mobile/misc/cashfree_integrity). Applications that don't meet the required integrity standards may be restricted from using production services.

The React Native integration consists of three essential steps:

<CardGroup>
  <Card title="Step 1" icon="money-bill-wave" href="/docs/payments/online/mobile/react-native#step-1-create-an-order-server-side">
    Create an order
  </Card>

  <Card title="Step 2" icon="desktop" href="/docs/payments/online/mobile/react-native#step-2-open-the-payment-page-client-side">
    Open the payment page
  </Card>

  <Card title="Step 3" icon="circle-check" href="/docs/payments/online/mobile/react-native#step-3-confirm-the-payment-server-side">
    Confirm the payment
  </Card>
</CardGroup>

The step-by-step guide for each step of the integration process is as follows:

## Step 1: Create an order <Badge>Server-side</Badge>

To integrate the Cashfree Payment Gateway, you must first create an order. Complete this step before you process any payments. Configure an endpoint on your server to handle order creation. You can't call this API from the client-side.

<Note>Create orders through your server as this API requires your secret key. Don't call it directly from your mobile application.</Note>

##### API request for creating an order

Here's a sample request for creating an order using your desired backend language. Cashfree offers backend [SDKs](/docs/api-reference/payments/sdk#server-sdk) to simplify the integration process.

<CodeGroup>
  ```bash curl theme={"dark"}
  curl --location 'https://sandbox.cashfree.com/pg/orders' \
  --header 'X-Client-Secret: {{clientKey}}' \
  --header 'X-Client-Id: {{clientId}}' \
  --header 'x-api-version: 2025-01-01' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data-raw '{
    "order_amount": 10.10,
    "order_currency": "INR",
    "customer_details": {
      "customer_id": "USER123",
      "customer_name": "joe",
      "customer_email": "joe.s@cashfree.com",
      "customer_phone": "+919876543210"
    },
    "order_meta": {
      "return_url": "https://b8af79f41056.eu.ngrok.io?order_id=order_123"
    }
  }'
  ```

  ```javascript nodejs theme={"dark"}
  import { Cashfree, CFEnvironment } from "cashfree-pg";

  const cashfree = new Cashfree(
  	CFEnvironment.PRODUCTION,
  	"{Client ID}",
  	"{Client Secret Key}"
  );

  function createOrder() {
  	var request = {
  		order_amount: "1",
  		order_currency: "INR",
  		customer_details: {
  			customer_id: "node_sdk_test",
  			customer_name: "",
  			customer_email: "example@gmail.com",
  			customer_phone: "9999999999",
  		},
  		order_meta: {
  			return_url:
  				"https://test.cashfree.com/pgappsdemos/return.php?order_id=order_123",
  		},
  		order_note: "",
  	};

  	cashfree
  		.PGCreateOrder(request)
  		.then((response) => {
  			console.log("Order created successfully:", response.data);
  		})
  		.catch((error) => {
  			console.error("Error setting up order request:", error.response.data);
  		});
  }
  ```

  ```python python theme={"dark"}
  from cashfree_pg.models.create_order_request import CreateOrderRequest
  from cashfree_pg.api_client import Cashfree
  from cashfree_pg.models.customer_details import CustomerDetails


  Cashfree.XClientId = {Client ID}
  Cashfree.XClientSecret = {Client Secret Key}
  Cashfree.XEnvironment = Cashfree.XSandbox
  x_api_version = "2023-08-01"

  def create_order():
          customerDetails = CustomerDetails(customer_id="123", customer_phone="9999999999")
          createOrderRequest = CreateOrderRequest(order_amount=1, order_currency="INR", customer_details=customerDetails)
          try:
              api_response = Cashfree().PGCreateOrder(x_api_version, createOrderRequest, None, None)
              print(api_response.data)
          except Exception as e:
              print(e)
  ```

  ```java java theme={"dark"}
  import com.cashfree.*;

  Cashfree.XClientId = {Client Key};
  Cashfree.XClientSecret = {Client Secret Key};
  Cashfree.XEnvironment = Cashfree.SANDBOX;

  static void createOrder() {
    CustomerDetails customerDetails = new CustomerDetails();
    customerDetails.setCustomerId("123");
    customerDetails.setCustomerPhone("9999999999");

    CreateOrderRequest request = new CreateOrderRequest();
    request.setOrderAmount(1.0);
    request.setOrderCurrency("INR");
    request.setCustomerDetails(customerDetails);
    try {
      Cashfree cashfree = new Cashfree();
      ApiResponse<OrderEntity> response = cashfree.PGCreateOrder("2023-08-01", request, null, null, null);
      System.out.println(response.getData().getOrderId());

    } catch (ApiException e) {
      throw new RuntimeException(e);
    }
  }
  ```

  ```go go theme={"dark"}
  import (
    cashfree "github.com/cashfree/cashfree-pg/v3"
  )

  func createOrder() {

  clientId := {Client ID}
  clientSecret := {Client Secret Key}
  cashfree.XClientId = &clientId
  cashfree.XClientSecret = &clientSecret
  cashfree.XEnvironment = cashfree.SANDBOX

  request := cashfree.CreateOrderRequest{
  		OrderAmount: 1,
  		CustomerDetails: cashfree.CustomerDetails{
  			CustomerId:    "1",
  			CustomerPhone: "9999999999",
  		},
  		OrderCurrency: "INR",
  		OrderSplits:   []cashfree.VendorSplit{},
  	}
  	version := "2023-08-01"
  	response, httpResponse, err := cashfree.PGCreateOrder(&version, &request, nil, nil, nil)
  	if err != nil {
  		fmt.Println(err.Error())
  	} else {
  		fmt.Println(httpResponse.StatusCode)
  		fmt.Println(response)
      }
  }
  ```

  ```csharp .net theme={"dark"}
  using cashfree_pg.Client;
  using cashfree_pg.Model;

  Cashfree.XClientId = {Client ID};
  Cashfree.XClientSecret = {Client Secret Key};
  Cashfree.XEnvironment = Cashfree.PRODUCTION;
  var cashfree = new Cashfree();
  var xApiVersion = "2023-08-01";

  void CreateOrder() {
      var customerDetails = new CustomerDetails("123", null, "9999999999");
      var createOrdersRequest = new CreateOrderRequest(null, 1.0, "INR", customerDetails);
      try {
          // Create Order
          var result = cashfree.PGCreateOrder(xApiVersion, createOrdersRequest, null, null, null);
          Console.WriteLine(result);
          Console.WriteLine(result.StatusCode);
          Console.WriteLine((result.Content as OrderEntity));
      } catch (ApiException e) {
          Console.WriteLine("Exception when calling PGCreateOrder: " + e.Message);
          Console.WriteLine("Status Code: " + e.ErrorCode);
          Console.WriteLine(e.StackTrace);
      }
  }
  ```

  ```php php theme={"dark"}
  \Cashfree\Cashfree::$XClientId = "<x-client-id>";
  \Cashfree\Cashfree::$XClientSecret = "<x-client-secret>";
  \Cashfree\Cashfree::$XEnvironment = Cashfree\Cashfree::$SANDBOX;

  $cashfree = new \Cashfree\Cashfree();

  $x_api_version = "2023-08-01";
  $create_orders_request = new \Cashfree\Model\CreateOrdersRequest();
  $create_orders_request->setOrderAmount(1.0);
  $create_orders_request->setOrderCurrency("INR");
  $customer_details = new \Cashfree\Model\CustomerDetails();
  $customer_details->setCustomerId("123");
  $customer_details->setCustomerPhone("9999999999");
  $create_orders_request->setCustomerDetails($customer_details);

  try {
      $result = $cashfree->PGCreateOrder($x_api_version, $create_orders_request);
      print_r($result);
  } catch (Exception $e) {
      echo 'Exception when calling PGCreateOrder: ', $e->getMessage(), PHP_EOL;
  }
  ```
</CodeGroup>

After successfully creating an order, you will receive a unique `order_id` and `payment_session_id` that you need for subsequent steps.

You can view the complete API request and response for `/orders` in the [Create Order API](/docs/api-reference/payments/latest/orders/create-order).

<Note>
  To show a short purchase description on checkout, such as a booking reference or route, add `checkout_context` to the `order_tags` object in the Create Order request above.

  ```json theme={"dark"}
  "order_tags": {
    "checkout_context": "Flight booking DEL-BOM, 12 JUN at 14:30"
  }
  ```

  For details about how checkout displays this text in a context card, see [Contextual Checkout](/docs/payments/features/contextual-checkout).
</Note>

## Step 2: Open the payment page <Badge>Client-side</Badge>

Once the order is created, the next step is to open the payment page so the customer can make the payment.

### 1. Set up the SDK

The React Native SDK is hosted on [npm](https://www.npmjs.com/). You can [download the latest SDK version 2.4.0 from npm](https://www.npmjs.com/package/react-native-cashfree-pg-sdk). The React Native SDK supports Android SDK version 19 and above and iOS minimum deployment target of 10.3 and above.

##### npm, Yarn, or Expo

Navigate to your project and run the following command:

<CodeGroup>
  ```npm npm theme={"dark"}
  npm install react-native-cashfree-pg-sdk
  ```

  ```yarn yarn theme={"dark"}
  yarn add react-native-cashfree-pg-sdk
  ```

  ```expo expo theme={"dark"}
  npx expo install react-native-cashfree-pg-sdk
  npx expo install expo-dev-client
  npx expo prebuild  //mandatory for expo
  npx expo run:android
  npx expo run:ios
  ```
</CodeGroup>

#### iOS configuration

To provide UPI payments on iOS, enable the following permissions in your app. Add this to your application's `info.plist` file:

```shell theme={"dark"}
<key>LSApplicationQueriesSchemes</key>
<array>
  <string>amazonpay</string>
	<string>upi</string>
	<string>credpay</string>
	<string>bhim</string>
	<string>paytmmp</string>
	<string>phonepe</string>
	<string>tez</string>
	<string>navipay</string>
	<string>mobikwik</string>
	<string>myairtel</string>
	<string>popclubapp</string>
	<string>super</string>
	<string>kiwi</string>
  <string>simplypayupi</string>
  <string>whatsapp</string>
</array>
```

For iOS, run the following commands:

```bash theme={"dark"}
cd ios
pod install --repo-update
```

### 2. Select a payment flow

The React Native SDK offers the following payment flows:

<AccordionGroup>
  <Accordion title="Web Checkout">
    In this flow, the SDK provides a webview-based checkout implementation to facilitate a quick integration with the payment gateway. Your customers can fill in the necessary details in the web page and complete the payment.
    This mode handles all the business logic and UI components to make the payment smooth and easy to use.

    Your customers are presented with a familiar web interface where they can enter their payment details and complete their transaction seamlessly. All payment logic, UI components, and security measures are managed by the SDK, eliminating the need for complex custom implementation.
  </Accordion>

  <Accordion title="UPI Intent Checkout">
    This flow is for merchants who want to provide UPI Intent functionality using Cashfree's mobile SDK. In this flow, the SDK provides a pre-built native Android screen to facilitate integration with the payment gateway. Your customers see a list of UPI apps installed on their phone which they can select to initiate payment.
    This mode handles all the business logic and UI components to make the payment smooth and easy to use. The SDK allows you to customise the UI in terms of colour coding and fonts.
  </Accordion>
</AccordionGroup>

### 3. Complete the payment

To complete the payment, follow these steps:

1. Create a `CFSession` object.
2. Set up payment callback.
3. Initiate the payment using the payment object.

#### Create a session

This object contains essential information about the order, including the payment session ID (`payment_session_id`) and order ID (`order_id`) obtained from Step 1. It also specifies the environment (`SANDBOX` or `PRODUCTION`).

```typescript theme={"dark"}
import {
  CFEnvironment,
  CFSession,
} from 'cashfree-pg-api-contract';

try {
      const session = new CFSession(
        'payment_session_id',
        'order_id',
        CFEnvironment.SANDBOX
      );
}
catch (e: any) {
      console.log(e.message);
}
```

#### Set up the payment callback

The SDK exposes a `CFCallback` interface to receive callbacks from the SDK once the payment flow ends. The callback supports two methods:

```typescript theme={"dark"}
onVerify(orderID: string)
onError(error: CFErrorResponse, orderID: string)
```

<Tip>Set the callback at componentDidMount and remove the callback at componentWillUnmount, as this also handles the activity restart cases and prevents memory leaks.</Tip>

<Tip>Always call `setCallback` before calling the `doPayment` method of the SDK.</Tip>

```typescript theme={"dark"}
import {
  CFErrorResponse,
  CFPaymentGatewayService,
} from 'react-native-cashfree-pg-sdk';

export default class App extends Component {
  constructor() {
    super();
  }

  componentDidMount() {
    console.log('MOUNTED');
    CFPaymentGatewayService.setCallback({
      onVerify(orderID: string): void {
        this.changeResponseText('orderId is :' + orderID);
      },
      onError(error: CFErrorResponse, orderID: string): void {
        this.changeResponseText(
          'exception is : ' + JSON.stringify(error) + '\norderId is :' + orderID
        );
      },
    });
  }

  componentWillUnmount() {
    console.log('UNMOUNTED');
    CFPaymentGatewayService.removeCallback();
  }
}

```

#### Initiate the payment

<AccordionGroup>
  <Accordion title="Web Checkout">
    Use `doWebPayment()` to open the Cashfree checkout screen. This will present the user with the payment options and handle the payment process.

    ```typescript theme={"dark"}
    async _startWebCheckout() {
        try {
            const session = new CFSession(
                'payment_session_id',
                'order_Id',
                CFEnvironment.SANDBOX
            );
            console.log('Session', JSON.stringify(session));

            CFPaymentGatewayService.doWebPayment(session);

        } catch (e: any) {
            console.log(e.message);
        }
    }
    ```
  </Accordion>

  <Accordion title="UPI Intent Checkout">
    Use `doUPIPayment()` to provide UPI functionality using Cashfree's mobile SDK without handling other modes like cards or net banking. You can optionally customise the theme by creating a CFThemeBuilder object.

    ```typescript theme={"dark"}
    try {
        // Setting theme is optional
        const theme = new CFThemeBuilder()
            .setNavigationBarBackgroundColor('#E64A19') // ios
            .setNavigationBarTextColor('#FFFFFF') // ios
            .setButtonBackgroundColor('#FFC107') // ios
            .setButtonTextColor('#FFFFFF') // ios
            .setPrimaryTextColor('#212121')
            .setSecondaryTextColor('#757575') // ios
            .build();
            
        const upiPayment = new CFUPIIntentCheckoutPayment(
            session,
            theme
        );
    	CFPaymentGatewayService.doUPIPayment(upiPayment);
    } catch (e: any) {
        console.log(e.message);
    }
    ```
  </Accordion>
</AccordionGroup>

#### Sample code

Complete code examples demonstrating the implementation of both Web Checkout and UPI Intent Checkout flows are shown below:

<AccordionGroup>
  <Accordion title="Web checkout">
    ```typescript theme={"dark"}
    import * as React from 'react';
    import { Component } from 'react';

    import {
      CFErrorResponse,
      CFPaymentGatewayService,
    } from 'react-native-cashfree-pg-api';
    import {
      CFDropCheckoutPayment,
      CFEnvironment,
      CFPaymentComponentBuilder,
      CFPaymentModes,
      CFSession,
      CFThemeBuilder,
    } from 'cashfree-pg-api-contract';

    export default class App extends Component {

      constructor() {
        super();
      }

      componentDidMount() {
        console.log('MOUNTED');
        CFPaymentGatewayService.setCallback({
          onVerify(orderID: string): void {
            this.changeResponseText('orderId is :' + orderID);
          },
          onError(error: CFErrorResponse, orderID: string): void {
            this.changeResponseText(
              'exception is : ' + JSON.stringify(error) + '\norderId is :' + orderID
            );
          },
        });
      }

      componentWillUnmount() {
        console.log('UNMOUNTED');
        CFPaymentGatewayService.removeCallback();
      }

      async _startWebCheckout() {
        try {
          const session = new CFSession(
            'payment_session_id',
            'order_Id',
            CFEnvironment.SANDBOX
          );
          console.log('Session', JSON.stringify(session));
          CFPaymentGatewayService.doWebPayment(session);
        } catch (e: any) {
          console.log(e.message);
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="UPI Intent Checkout">
    ```typescript theme={"dark"}
    import * as React from 'react';
    import { Component } from 'react';

    import {
      CFErrorResponse,
      CFPaymentGatewayService,
    } from 'react-native-cashfree-pg-api';

    import {
      CFEnvironment,
      CFPaymentComponentBuilder,
      CFSession,
      CFThemeBuilder,
    } from 'cashfree-pg-api-contract';

    export default class App extends Component {

      constructor() {
        super();
      }

      componentDidMount() {
        console.log('MOUNTED');
        CFPaymentGatewayService.setCallback({
          onVerify(orderID: string): void {
            this.changeResponseText('orderId is :' + orderID);
          },
          onError(error: CFErrorResponse, orderID: string): void {
            this.changeResponseText(
              'exception is : ' + JSON.stringify(error) + '\norderId is :' + orderID
            );
          },
        });
      }

      componentWillUnmount() {
        console.log('UNMOUNTED');
        CFPaymentGatewayService.removeCallback();
      }

      async _startCheckout() {
        try {
          const session = new CFSession(
            'payment_session_id',
            'order_id',
            CFEnvironment.SANDBOX
          );
          const theme = new CFThemeBuilder()
            .setNavigationBarBackgroundColor('#E64A19')// ios
            .setNavigationBarTextColor('#FFFFFF')// ios
            .setButtonBackgroundColor('#FFC107')// ios
            .setButtonTextColor('#FFFFFF')// ios
            .setPrimaryTextColor('#212121')
            .setSecondaryTextColor('#757575')// ios
            .build();
          const upiPayment = new CFUPIIntentCheckoutPayment(
            session,
            theme
          );
          CFPaymentGatewayService.doUPIPayment(upiPayment);
        } catch (e: any) {
          console.log(e.message);
        }
      }
    }
    ```
  </Accordion>
</AccordionGroup>

#### Sample GitHub code

You can explore a working integration example on GitHub:

[GitHub Sample](https://github.com/cashfree/react-native-cashfree-pg-sdk/blob/427286cc024c473f6c18ec4107d4071b12b3dcf5/example/src/App.tsx#L230)

[Sample UPI Test apk](/docs/payments/online/mobile/misc/cashfree_upi_simulator_apk)

<Note>This SDK is compatible with the Expo framework. For a sample implementation, see the [Expo Sample](https://github.com/kishan-cashfree/Expo-RN_Cashfree_SDK) on GitHub.</Note>

## Step 3: Confirm the payment <Badge>Server-side</Badge>

Once the payment is completed, you need to confirm whether the payment was successful by checking the order status. Once the payment finishes, the user will be redirected back to your component.

<Note>You must always verify payment status from your server. Before delivering the goods or services, ensure you check the order status from your server and verify it from your server endpoint.</Note>

```javascript theme={"dark"}
export default class App extends Component {
  ...
  componentDidMount() {

    CFPaymentGatewayService.setCallback({
      //verify order status from backend
      onVerify(orderID: string): void {
        this.changeResponseText('orderId is :' + orderID);
      },

      onError(error: CFErrorResponse, orderID: string): void {
        this.changeResponseText(
          'exception is : ' + JSON.stringify(error) + '\norderId is :' + orderID
        );
      },
    });
  }
}
```

To verify an order you can call our `/pg/orders` endpoint from your backend. You can also use our SDK to achieve the same.

<CodeGroup>
  ```bash curl theme={"dark"}
  curl --request GET \
       --url https://sandbox.cashfree.com/pg/orders/{order_id} \
       --header 'accept: application/json' \
       --header 'x-api-version: 2025-01-01' \
       --header 'x-client-id: "YOUR APP ID GOES HERE"' \
       --header 'x-client-secret: "YOUR SECRET KEY GOES HERE"'
  ```

  ```javascript nodejs theme={"dark"}
  cashfree
  .PGFetchOrder("<order_id>")
  .then((response) => {
  	console.log("Order fetched successfully:", response.data);
  })
  .catch((error) => {
  	console.error("Error:", error.response.data.message);
  });
  ```

  ```python python theme={"dark"}
  from cashfree_pg.models.create_order_request import CreateOrderRequest
  from cashfree_pg.api_client import Cashfree
  from cashfree_pg.models.customer_details import CustomerDetails
  from cashfree_pg.models.order_meta import OrderMeta

  Cashfree.XClientId = "<x-client-id>"
  Cashfree.XClientSecret = "<x-client-secret>"
  Cashfree.XEnvironment = Cashfree.SANDBOX
  x_api_version = "2023-08-01"

  try:
      api_response = Cashfree().PGFetchOrder(x_api_version, "order_3242X4jQ5f0S9KYxZO9mtDL1Kx2Y7u", None)
      print(api_response.data)
  except Exception as e:
      print(e)

  ```

  ```java java theme={"dark"}
  import com.cashfree.*;
  //other code

  try {
      Cashfree.XClientId = "<x-client-id>";
      Cashfree.XClientSecret = "<x-client-secret>";
      Cashfree.XEnvironment = Cashfree.SANDBOX;

      Cashfree cashfree = new Cashfree();
      String xApiVersion = "2023-08-01";

      ApiResponse<OrderEntity> responseFetchOrder = cashfree.PGFetchOrder(xApiVersion, "<order_id>", null, null, null);
      System.out.println(response.getData().getOrderId());
  } catch (ApiException e) {
      throw new RuntimeException(e);
  }
  ```

  ```go go theme={"dark"}
  version := "2023-08-01"
  response, httpResponse, err := cashfree.PGFetchOrder(&version, "<order_id>", nil, nil, nil)
  if err != nil {
  	fmt.Println(err.Error())
  } else {
  	fmt.Println(httpResponse.StatusCode)
  	fmt.Println(response)
  }
  ```

  ```csharp .net theme={"dark"}
  using cashfree_pg.Client;
  using cashfree_pg.Model;

  Cashfree.XClientId = "<x-client-id>";
  Cashfree.XClientSecret = "<x-client-secret>";
  Cashfree.XEnvironment = Cashfree.SANDBOX;
  var cashfree = new Cashfree();
  var xApiVersion = "2023-08-01";

  try {
      var result = cashfree.PGFetchOrder(xApiVersion, "<order_id>>", null, null);
      Console.WriteLine(result);
      Console.WriteLine(result.StatusCode);
      Console.WriteLine((result.Content as OrderEntity));
  } catch (ApiException e) {
      Console.WriteLine("Exception when calling PGFetchOrder: " + e.Message);
      Console.WriteLine("Status Code: " + e.ErrorCode);
      Console.WriteLine(e.StackTrace);
  }
  ```

  ```php php theme={"dark"}
  $x_api_version = "2023-08-01";
  try {
      $response = $cashfree->PGFetchOrder($x_api_version, "<order_id>");
      print_r($response);
  } catch (Exception $e) {
      echo 'Exception when calling PGFetchOrder: ', $e->getMessage(), PHP_EOL;
  }
  ```
</CodeGroup>

## Testing

After you integrate the checkout functionality, verify that it opens the Cashfree-hosted payment page. Follow these steps to test:

1. Click the checkout button.
2. Verify you're redirected to the Cashfree Checkout payment page.

## Error codes

To confirm the error returned in your React Native application, you can view the error codes that are exposed by the SDK.

<Accordion title="Show error codes">
  The following are some of the error codes that are exposed by the SDK:

  | Error codes | Message | |
  | :- | :- | :- |
  | MISSING\_CALLBACK | The callback is missing in the request. | |
  | ORDER\_ID\_MISSING | The "order\_id" is missing in the request. | |
  | SESSION\_OBJECT\_MISSING | The "session" is missing in the request | |
  | PAYMENT\_OBJECT\_MISSING | The "payment" is missing in the request | |
  | ENVIRONMENT\_MISSING | The "environment" is missing in the request. | |
  | ORDER\_TOKEN\_MISSING | The "order\_token" is missing in the request. | |
</Accordion>

<div>
  <p>Affiliate partner program</p>

  <p>As a developer building payment experiences for your clients, you can earn additional income while providing them with industry-leading payment solutions.</p>

  <p>Join the <a href="https://partner.cashfree.com/partner-ui/authentication/signup?source-action=Affiliate%20Program%20LP&action=Sign%20Up&button-id=StartNow_CashfreeAffiliatePartnerProgram">Cashfree affiliate partner program</a> and get rewarded every time your clients use Cashfree.</p>

  <p>**What you get:**</p>

  <ul>
    <li>Earn up to 0.25% commission on every transaction.</li>
    <li>Become a trusted fintech partner for your clients.</li>
    <li>Access to a dedicated partner manager for expert support.</li>
  </ul>

  <p>**What your clients get:**</p>

  <ul>
    <li>Instant activation and go live in minutes.</li>
    <li>Industry-best success rate across all payment modes.</li>
    <li>Effortless acceptance of international payments in 140+ currencies.</li>
  </ul>

  <p>Get started today. <a href="https://partner.cashfree.com/partner-ui/authentication/signup?source-action=Affiliate%20Program%20LP&action=Sign%20Up&button-id=StartNow_BecomeAPartner">Become a partner now</a>.</p>
</div>

<snippet>snippets/related-topics-loader.mdx</snippet>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/payments/latest/orders/create-order">Create Order API</a></li>
    <li><a href="/docs/api-reference/payments/sdk">Payment SDKs</a></li>
    <li><a href="/docs/payments/online/mobile/misc/cashfree_upi_simulator_apk">UPI Intent Simulator APK</a></li>
  </ul>
</div>


# Payment Icons
Source: https://www.cashfree.com/docs/payments/online/resources/payment-icons

Download standardised Cashfree payment icons for cards, netbanking, wallets, and UPI in multiple sizes and formats to build polished custom checkout pages.

The Payments icons library provides standardised payment method icons that you can use when building custom payment pages. This library supports various payment methods including cards, net banking, wallets, and UPI, available in multiple sizes and formats.

<Frame>
  <div>
    <img alt="American Express" />

    <img alt="Visa" />

    <img alt="Diners Club" />

    <img alt="Maestro" />

    <img alt="Mastercard" />

    <img alt="RuPay" />
  </div>
</Frame>

## Demo

You can view all available payment icons and explore the library's capabilities on the [demo page](https://cashfree.github.io/payments-icons-library/).

## Installation

Install the Payments icons library using npm:

```shell npm theme={"dark"}
npm i payments-icons-library
```

## Import the library

You can import the library using npm or include it directly in your HTML using a CDN.

<CodeGroup>
  ```javascript npm theme={"dark"}
  var Icons = require('payments-icons-library');
  ```

  ```javascript vanilla JS theme={"dark"}
  <script src="https://cdn.jsdelivr.net/gh/cashfree/payments-icons-library@latest/dist/image-library.js"></script>
  ```
</CodeGroup>

## Usage

The library provides methods to fetch individual icons, multiple icons, or all icons for a specific payment mode.

<CodeGroup>
  ```javascript ES6 theme={"dark"}
  import icons from "payments-icons-library";

  // Fetch a single icon
  let sbiIcon = icons.getIcon('sbi', 'sm');
  //{"icon_name": "sbi", "icon_url": "https://cashfreelogo.cashfree.com/assets_images/pg/nb/32/sbi.png", "icon_version": "1"}

  // Fetch multiple icons
  let [sbiIcon, auIcon] = icons.getIcons(['sbi', 'au'], 'sm');
  //[{"icon_name": "sbi", "icon_url": "https://cashfreelogo.cashfree.com/assets_images/pg/nb/32/sbi.png", "icon_version": "1"}, ...]

  // Fetch all icons for a payment mode
  let banksLogo = icons.getModesIcons('cardbanks', 'sm');
  //[{"icon_name": "sbi", "icon_url": "https://cashfreelogo.cashfree.com/assets_images/pg/nb/32/sbi.png", "icon_version": "1"}, ...]

  ```

  ```javascript Vanilla JS theme={"dark"}
  // Fetch a single icon
  let sbiIcon = paymentsIcons.getIcon('sbi', 'sm');
  //{"icon_name": "sbi", "icon_url": "https://cashfreelogo.cashfree.com/assets_images/pg/nb/32/sbi.png", "icon_version": "1"}

  // Fetch multiple icons
  let [sbiIcon, auIcon] = paymentsIcons.getIcons(['sbi', 'au'], 'sm');
  //[{"icon_name": "sbi", "icon_url": "https://cashfreelogo.cashfree.com/assets_images/pg/nb/32/sbi.png", "icon_version": "1"}, ...]

  // Fetch all icons for a payment mode
  let banksLogo = paymentsIcons.getModesIcons('cardbanks', 'sm');
  //[{"icon_name": "sbi", "icon_url": "https://cashfreelogo.cashfree.com/assets_images/pg/nb/32/sbi.png", "icon_version": "1"}, ...]

  ```
</CodeGroup>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="https://cashfree.github.io/payments-icons-library/">Payment Icons Demo</a></li>
    <li><a href="/docs/payments/online/element/introduction">Element Introduction</a></li>
    <li><a href="/docs/payments/online/web/redirect">Checkout Integration</a></li>
    <li><a href="/docs/payments/online/resources/payment-lifecycle">Payment Lifecycle</a></li>
    <li><a href="https://www.npmjs.com/package/payments-icons-library">NPM Package</a></li>
  </ul>
</div>


# Payment Lifecycle
Source: https://www.cashfree.com/docs/payments/online/resources/payment-lifecycle

Understand how Cashfree orders and payments transition through their lifecycle states so you can track transactions and handle every scenario reliably.

When processing payments through Cashfree, orders and their associated payments progress through various states. Understanding these states helps you track transactions and handle different scenarios effectively.

## Transaction lifecycle

The following diagram shows how transactions progress from order creation to final state:

<img />

## Key concepts

Two critical concepts in payment flows are order expiry time and Transaction Time Limit (TTL). Understanding these concepts helps you manage your payment flows effectively.

### Transaction time limit

Transaction Time Limit, also referred to as Transaction Completion Time (TCT), defines the maximum time allowed for a payment attempt.\
During this period, the transaction will reach one of the following final statuses: **SUCCESS**, **FAILED**, or **USER DROPPED**.\
It ensures predictable transaction behaviour and helps minimise financial risk for both merchants and customers.

### Order expiry time

Order expiry time specifies the duration for which an order remains valid and can be used to initiate a new payment attempt.

### Order expiry time vs TTL

| Concept | Starts from | Definition | Behaviour |
| :- | :- | :- | :- |
| Order expiry time | Order creation time. | Duration within which a customer must initiate a payment attempt. | Once expired, no new payment attempts can be made. |
| Transaction time limit | When the customer selects a payment method. | Maximum time allowed for the last payment attempt to reach a terminal state. | Even if the order expiry time passes, the last attempt is honoured until the TTL ends. |

### Order finalisation process

The following steps describe how a payment is finalised:

1. **Payment succeeds within TTL** → Order is **PAID**, even if order expiry time passed.
2. An order marked as **EXPIRED** can still move to **PAID** if a payment attempt was started before the expiry and completed successfully within the TTL window, even if the confirmation comes after the expiry time.
3. If payment fails or the user drops → Order remains **EXPIRED**.
4. When TTL ends, any non-terminal payments are automatically closed in a terminal state.

## How order expiry time and TTL work

* **Order creation time**: 10:00 AM
* **Order expiry time**: 15 minutes
* **TTL**: 20 minutes

**Example scenarios**:

1. **No payment attempt**: If the customer does not select any payment method → Order moves from **ACTIVE** to **EXPIRED** at **10:15 AM**
2. **Payment attempt before expiry**:
   * Customer selects a payment method at **10:02 AM**
   * TTL starts → transaction allowed until **10:22 AM**
   * Even though the order expiry time is **10:15 AM**, since a payment attempt is in progress, Cashfree waits until **10:22 AM**
   * At **10:15 AM** order moved to **EXPIRED** status.
   * If payment succeeds at **10:21 AM** → Order status will change from **EXPIRED** to **PAID**.
   * If payment fails or is dropped → Order remains **EXPIRED**.

### Order TTL flowchart

The following flowchart shows how order expiry time and TTL affect an order’s final state:

<Frame>
  <img alt="Order TTL Flowchart" />
</Frame>

## Significance of TTL

TTL helps prevent financial loss and ensures a smoother customer experience in scenarios such as:

* Customers initiate payment just before order expiry.
* Banks or Payment Service Providers (PSPs) take additional time to confirm transactions.

If payments that succeed after expiry were rejected, Cashfree would incur financial loss since the bank would still charge for the transaction, but Cashfree would neither settle the funds nor reverse them.

### Use cases

TTL is especially critical for industries where prices fluctuate rapidly, such as stock trading platforms, airline ticket sales, commodities, and flash sales.

**Example**: Flight fares may change every minute. With TTL, once a customer locks a price by initiating payment, Cashfree continues to wait for confirmation even if the order has technically expired, ensuring the transaction is honoured at the locked price.

## Configure order expiry time and TTL

Follow these steps to configure order expiry time and TTL in the Merchant Dashboard:

1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).

2. Navigate to **Settings** > **Preferences**.

3. Set **order expiry time**: Minimum 5 minutes, maximum 30 days.

4. Set **TTL**: Minimum 5 minutes, maximum 24 hours.

5. Select **Save Changes** to apply your updates.

<img alt="" />

## Order states

| Order State | Description |
| :- | :- |
| ACTIVE | Orders are marked as **ACTIVE**, when an order is created by the merchant through an API request to Cashfree. |
| PAID | Orders are marked **PAID** when the payment is verified by Cashfree and the payment is successful. |
| EXPIRED | Orders are marked as **EXPIRED** when the order has exceeded `order_expiry_time` specified by merchant to complete the order. |
| TERMINATED | This status is returned when you request order termination through the [Order Termination API](/docs/api-reference/payments/latest/orders/terminate-order). Once terminated, customers can no longer pay for this order. |
| TERMINATION\_REQUESTED | This status is returned after you call the [Order Termination API](/docs/api-reference/payments/latest/orders/terminate-order) to end an order. The termination request is acknowledged but still processing. Orders can only be terminated when all transactions have reached terminal states. If a pending transaction completes successfully while termination is processing, the status will change from **TERMINATION\_REQUESTED** to **SUCCESS**. |

## Payment states

| Payment State | Description | Remarks |
| :- | :- | :- |
| SUCCESS | Transaction is successful and the amount is captured. | Terminal state. Once successful, the order moves to **PAID**. |
| FAILED | Transaction failed due to bank, customer, or system issues. | Terminal state. Customers can initiate a new attempt. |
| NOT\_ATTEMPTED | Transaction is created but acknowledgement from the bank is awaited. | Initial state for a payment attempt. |
| PENDING | Request is sent to the bank and a response is awaited. | Non-terminal state. Do not fulfil orders in this state. |
| FLAGGED | Transaction is identified as high-risk and requires review. | Merchant must manually approve or reject the payment. |
| CANCELLED | Amount is reversed because a success response arrived after the time to live (TTL). | Automatic system reversal for late confirmations. |
| VOID | Transaction amount is not captured by explicit request. | Typically used for pre-authorised card payments or UPI mandates. |
| USER\_DROPPED | Customer abandoned the payment flow before completion. | Includes closing the app or OTP page without attempting payment. |

<div>
  <iframe title="What is order expiry time and Transaction Complete Time?" />
</div>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/payments/latest/orders/create-order">Create Order API</a></li>
    <li><a href="/docs/payments/online/web/redirect">Checkout Integration</a></li>
    <li><a href="/docs/payments/webhooks">Webhooks</a></li>
    <li><a href="/docs/payments/online/resources/payment-icons">Payment Icons</a></li>
  </ul>
</div>


# Rate Limits and Integration Usage
Source: https://www.cashfree.com/docs/payments/online/resources/rate-limits

Understand Cashfree API rate limits per endpoint, read x-ratelimit response headers, and review your current integrations and usage volumes in the dashboard.

All calls to Cashfree are subject to rate limiting. Limits are put in place to protect our system against excessive load and to make Cashfree systems available to as wide an audience as possible.

## Default limits

Per default the following limits are in place:

| API | Rate limit value per minute | Rate limit type |
| :- | :- | :- |
| Create Order | 200 | Account |
| Get Order | 400 | Account |
| Get Payments | 100 | Account |
| Get Payments by ID | 130 | Account |
| Pay Order | 100 | IP |
| Get Settlements | 30 | Account |
| Initiate Refund | 100 | Account |
| Get Refund | 30 | Account |

## Rate limit headers

You will receive rate limit information in the response headers of all calls to endpoints which are rate limited.

Currently you will receive these for every call. The following information is returned:

| Header name | Example | Description |
| :- | :- | :- |
| x-ratelimit-limit | 100 | Max number of calls that can be made in a minute |
| x-ratelimit-remaining | 30 | Remaining number of calls that can be made in a minute |
| x-ratelimit-retry | 0 | Number of seconds you will have to wait to make the next call |
| x-ratelimit-type | `app_id` or `ip` | Type of rate limiting applied |

## View your integrations

You can view all the current integrations you have configured along with their usage volumes (percentage). This provides you more visibility on different sources of your orders and helps you upgrade your integrations whenever it is marked as deprecated.

To view the integration usage, Go to **Payment Gateway Dashboard** > **Developers** > **Integration Usage**.

You can view the following details on this page:

* Integration Source: Type of integration (Flutter, React Native, Android/iOS, Shopify, Wix, etc.)
* Order Count: Number of orders paid via this integration (last 30 days)
* Percentage: Percentage of total orders
* Migration Required: Whether a migration to the new version is necessary


# Sandbox Environment
Source: https://www.cashfree.com/docs/payments/online/resources/sandbox-environment

Test Cashfree Payment Gateway integrations risk-free in the sandbox environment, which mirrors production payment modes, refunds, webhooks, and edge cases.

Before going to production, you can try the integration on Cashfree's sandbox environment. Our sandbox environment supports the following payment modes and functionalities to test.

| Payment mode/ feature supported | |
| :- | :- |
| Card | Use test card details |
| Net Banking | Use test net banking account |
| UPI | Use test UPI VPAs |
| Wallet | Only test wallet is present. No individual provider. |
| Credit / Debit Card EMI | Use test EMI card details |
| Paylater | Use test details provided |
| Cardless EMI | Use test details provided. Minimum amount – 1000. |

<Note>
  PayPal and bank transfer payment modes are not supported in the sandbox
  environment at the moment.
</Note>

## Test card details

To test card transactions in our sandbox environment, use the card numbers below based on the type of card you want to test.

| Scheme | Card type | Card sub type | Card number 1 | Card number 2 |
| :- | :- | :- | :- | :- |
| Visa | Debit | Retail | 4706131211212123 | 4062288312345026 |
| Visa | Credit | Retail | 4576238912771450 | 4444333322221111 |
| Visa | Credit | Premium | 4466050254381183 | 4136880012657791 |
| Visa | Credit | Corporate | 4074970084343075 | 4770355457382883 |
| Mastercard | Debit | Retail | 5409162669381034 | 5445856839524391 |
| Mastercard | Credit | Retail | 5105105105105100 | 5176539438527826 |
| Mastercard | Credit | Premium | 5242535837492075 | 5203860658394375 |
| Mastercard | Credit | Corporate | 5552190758372734 | 5506908329471983 |
| Rupay | Debit | Retail | 6074825972083818 | 6074828163369590 |
| Rupay | Credit | Retail | 6528591234543575 | 65292523412356 |

<Note> OTP will be 111000 for every card.</Note>

The test card expiry, CVV, and cardholder name will always remain the same and are mentioned below.

| Expiry | CVV | Name |
| :- | :- | :- |
| 03/2028 | 123 | Test |

## USD currency

| Number | Expiry | CVV | Name |
| :- | :- | :- | :- |
| 7000 0083 1380 6604 | 09/2027 | 581 | Test |
| 7000 0091 5369 7715 | 12/2021 | 591 | Test |
| 7000 0094 7240 2110 | 05/2024 | 204 | Test |
| 7000 0055 0418 0328 | 08/2026 | 324 | Test |
| 7000 0014 6659 2972 | 02/2026 | 153 | Test |

## USD currency (native OTP)

| Number | Expiry | CVV | Name |
| :- | :- | :- | :- |
| 4266 9020 7958 3702 | 09/2028 | 681 | Test |

## USD currency (subscription)

| Number | Expiry | CVV | Name |
| :- | :- | :- | :- |
| 4138 6748 6000 0008 | 01/2027 | 123 | Test |

## Test net banking

| Bank | Payment code | Bank API code |
| :- | :- | :- |
| TEST Bank | 3333 | TESTR |

## Test UPI VPA

| VPA | Remarks |
| :- | :- |
| testsuccess\@gocash | Success |
| testfailure\@gocash | Failed |
| testinvalid\@gocash | Invalid VPA |

## Test TPV net banking

| Bank | Value |
| :- | :- |
| accountNumber | 1111222233 |
| ifsc | TEST0001234 |

## Test TPV UPI

| Parameter | Values |
| :- | :- |
| userVPA (Success) | testtpvsuccess\@gocash |
| userVPA (Fail) | testtpvfail\@gocash |
| accountNumber | 1111222233 |
| ifsc | TEST0001234 |

## Token vault test cards

| Scheme | Card Bin |
| - | - |
| visa | 470613 <br /> 457623 <br /> 436534 <br /> 415527 <br /> 466535 |
| mastercard | 559423 <br /> 544405 <br /> 533983 <br /> 555219 <br /> 524877 |

Append any 10 digits to the card bin to get the test card number. Expiry can be any future date and CVV any 3-digit number. Use these card details to test the Token Vault APIs.

## Credit card EMI test cards

| Bank | card\_bank\_name | Card number |
| :- | :- | :- |
| Axis Bank | Axis | 4111 4647 7655 4152 |
| Standard Chartered Bank | Standard Chartered | 4622 7185 3202 3725 |
| ICICI Bank | ICICI | 4748 4661 2346 7526 |
| Kotak Bank | Kotak | 4363 9070 5531 5237 |
| HDFC Bank | HDFC | 5241 8100 0000 0000 |
| RBL Bank | RBL | 4112 5597 3537 3674 |
| Bank of Baroda | BOB | 4111 5638 8133 3699 |
| AU Bank | AU | 4111 5849 6705 0056 |
| Citi Bank | CITI | 4112 5229 6265 9579 |
| Yes Bank | YES | 4111 6514 1790 3257 |
| IndusInd Bank | INDUS | 4111 5351 6094 6904 |
| HSBC Bank | HSBC | 4111 6668 0832 0291 |
| Federal Bank | FED | 4111 5924 7037 2263 |

Expiry can be any future date and CVV any 3-digit number.

## Debit card EMI test cards

| Bank | card\_bank\_name | Card number |
| :- | :- | :- |
| HDFC Bank | HDFC | 4386 2412 2321 5159 |

## Paylater details

| Provider | Mobile number |
| :- | :- |
| Any | 8714268343 |

## Cardless EMI details

| Provider | Mobile number |
| :- | :- |
| Any | 8714268343 |

If 4 digits of PAN are asked, use 1234. If OTP is asked, use 777777.

## Payouts sandbox testing

For sandbox testing details, supported test scenarios, and VPAs for Payouts, see [Payouts test data](/docs/payouts/payouts/integrations/data-to-test).

## Sandbox transaction charges

In the sandbox environment, you can configure a default Transaction Discount Rate (TDR) for testing even if your live account has a promotional offer. Sandbox charges simulate the transaction flow and do not reflect the rates applied to your live production account.


# Custom Checkout Integration - Android
Source: https://www.cashfree.com/docs/payments/online/web/custom-checkout-android

Add UPI Intent support inside a WebView-based custom Cashfree checkout for Android by using the JS SDK and the steps documented in this integration guide.

Merchants integrating the Cashfree Web checkout using Cashfree JS SDK. But they are unable to see the UPI intent option on the checkout page as the Cashfree checkout page is opening on Webview.

This document provides guidance for merchants developing their applications on platforms such as `Android, React Native, Flutter, Cordova` who have integrated the Cashfree JS SDK.

<Note>If you using Cashfree Mobile SDK, then please follow cashfree official mobile sdk docs.</Note>

### Feature Flag based solution

Our checkout page provides the capability to display default UPI apps, including `PhonePe, GPay, and Paytm`, along with an option to pay via any UPI app. This feature ensures that these UPI apps are visible on the checkout page, regardless of whether they are installed on the user's device.

When a user selects a UPI app, merchants are responsible for handling the redirection. Only a minimal code snippet is required on the merchant's side to handle the UPI app click and manage the subsequent redirection process.

<AccordionGroup>
  <Accordion title="Android">
    <CodeGroup>
      ```java Android theme={"dark"}
      // Override shouldOverrideUrlLoading method in your webview.
      @Override
      public boolean shouldOverrideUrlLoading(WebView view, String request) {
         if (request != null) {
               if((request.startsWith("upi://pay") 
                   || request.startsWith("tez://") 
                   || request.startsWith("gpay://")
                   || request.startsWith("paytmmp://")
                   || request.startsWith("phonepe://")){
                      // Open UPI app from here
                      final Intent intent = new Intent();
                      intent.setAction(Intent.ACTION_VIEW);
                      intent.setData(Uri.parse(url));
                      PackageManager pm = getPackageManager();
                      final List<ResolveInfo> resInfo = pm.queryIntentActivities(intent, 0);
                      if (!resInfo.isEmpty()) {
                          startActivity(intent);
                      } else {
                         //handle no app scenario
                      }
                     return true;
                   }
         }
         return false;
      }
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="React-Native">
    <CodeGroup>
      ```js JS theme={"dark"}
      // Override onShouldStartLoadWithRequest method in your webview.
      onShouldStartLoadWithRequest={event => {
               const url  = event.url
               if((url.startsWith("upi://pay")
                  || url.startsWith("tez://")|| url.startsWith("gpay://")
                  || url.startsWith("paytmmp://")
                  || url.startsWith("phonepe://")) {
                Linking.canOpenURL(url).then(supported => {
                        if (supported) {
                              Linking.openURL(url);
                        }else{
                            console.log("Not able to open")
                        }
                      });
                      return false;
                }
              return true;
      }}
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="Flutter">
    <CodeGroup>
      ```js Dart theme={"dark"}
      // Override shouldOverrideUrlLoading method in your webview.
      shouldOverrideUrlLoading: (controller, navigationAction) async {
                var uri = navigationAction.request.url!;
                if (["upi", "tez","gpay", "paytmmp","phonepe"].contains(uri.scheme)) {
                  print("Opening PSP app");
                  await launchUrl(uri);
                  return NavigationActionPolicy.CANCEL;
                }
                return NavigationActionPolicy.ALLOW;
      }
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

<Note>To enable this flag, please fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1). they will enable this flag.</Note>

### Code based solution

You have to write some custom logic in your mobile app while opening Cashfree checkout page. When you are loading Webview, Please register `JS bridge` with name `Android` and implement few of its method.

<AccordionGroup>
  <Accordion title="Android">
    [Sample code](https://github.com/kishan-cashfree/CFWebIntegrationSample/blob/245b0d655475ad5f5595437efc1e6eb503774f68/app/src/main/java/com/cashfree/webintegration/MainActivity.kt#L87)
  </Accordion>

  <Accordion title="React-Native">
    In this case, you have to write android native module
    [Native Module](https://github.com/kishan-cashfree/CFWebIntegrationRN/tree/master/android/app/src/main/java/com/cfwebintegrationrn)

    Use these native module in you JS/TS code
    [JS code](https://github.com/kishan-cashfree/CFWebIntegrationRN/tree/master/native)

    [Sample Usage](https://github.com/kishan-cashfree/CFWebIntegrationRN/blob/master/WebSitePaymentScreen.tsx)
  </Accordion>

  <Accordion title="Flutter">
    In this case, you have to write android native module
    [Native Module](https://github.com/kishan-cashfree/CFSamplewebviewFL/tree/master/android/app/src/main/kotlin/com/example/cfsamplewebviewfl)

    Use these native module in you Dart code
    [Dart Code](https://github.com/kishan-cashfree/CFSamplewebviewFL/blob/master/lib/ui/webview/customwebview.dart)

    [Sample Usage](https://github.com/kishan-cashfree/CFSamplewebviewFL/blob/master/lib/main.dart)
  </Accordion>
</AccordionGroup>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/payments/latest/orders/create-order">Create Order API</a></li>
    <li><a href="/docs/payments/online/go-live/whitelist">Domain Whitelisting</a></li>
    <li><a href="/docs/payments/manage/payment-methods#upi">UPI Intent Methods</a></li>
    <li><a href="/docs/payments/manage/payment-methods">Payment Methods</a></li>
    <li><a href="/docs/payments/online/web/redirect">Hosted Checkout Integration</a></li>
  </ul>
</div>


# UPI Intent in iOS
Source: https://www.cashfree.com/docs/payments/online/web/custom-checkout-ios

Embed a Cashfree WKWebView-based custom checkout in your iOS app and enable UPI Intent so customers can pay using GPay, PhonePe, Paytm, and other UPI apps.

Cashfree's iOS custom checkout integration enables merchants to embed a secure payment experience directly within their iOS applications using WKWebView, supporting a wide variety of payment methods.

### Key benefits

* **Secure and PCI compliant**: Securely collects payment details and submits them directly to Cashfree servers, removing the need for Payment Card Industry Data Security Standard (PCI DSS) compliance requirements at the merchant's end.

* **Native iOS integration**: Seamlessly integrate payments into your iOS app using WKWebView without requiring third-party SDKs.

* **Support for multiple payment methods**: Accepts payments from over 120 payment methods including UPI Intent for direct app-to-app transfers.

### Prerequisites

1. Create a [Cashfree Merchant Account](https://merchant.cashfree.com/merchants/signup) and log in.
2. Navigate to **Developers > API Keys** to generate your **App ID** and **Secret Key**. Learn how to [generate API keys](/docs/api-reference/authentication#generate-api-keys).
3. Minimum iOS version is iOS 11.0 with WKWebView support.

The iOS checkout integration consists of three essential steps:

<CardGroup>
  <Card title="Step 1" icon="cube" href="/docs/payments/online/web/custom-checkout-ios#step-1:-create-order-server-side">
    Create Order
  </Card>

  <Card title="Step 2" icon="code" href="/docs/payments/online/web/custom-checkout-ios#step-2:-submit-form-client-side">
    Submit Form
  </Card>

  <Card title="Step 3" icon="check" href="/docs/payments/online/web/custom-checkout-ios#step-3:-handle-redirection-client-side">
    Handle Redirection
  </Card>
</CardGroup>

## Step 1: Create order <Badge>Server-side</Badge>

Create an order from your backend before processing the payment. This is a server-side operation and must not be called from the client side.

<Note>
  * Create orders through your backend, as this API requires your secret key.
  * Always provide a return URL when creating the order—it will be used to detect when the payment flow is complete.
</Note>

You can follow the order creation steps in the [Cashfree Hosted Checkout](/docs/payments/online/web/redirect#step-1-create-an-order-server-side) documentation. This will return a "payment\_session\_id" which will be used in the subsequent steps.

## Step 2: Submit form <Badge>Client-side</Badge>

Submit the checkout form from your app's web view using the payment session ID obtained from Step 1.

<Note>
  This step requires your application's bundle ID to be whitelisted by Cashfree. Please check [Bundle ID Whitelisting](/docs/payments/online/go-live/whitelist).
</Note>

```swift Swift theme={"dark"}
String platform = "iosx-c-x-x-x-w-x-a-" + <BuildVersion>;
String session = "PAYMENT_SESSION_ID";

func createForm(session: String, platform: String) -> String {
        var secureURL = ""
        if CFConstants.environment == .SANDBOX {
            secureURL = "https://sandbox.cashfree.com/pg/view/sessions/checkout"
        } else {
            secureURL = "https://api.cashfree.com/pg/view/sessions/checkout"
        }
        var paymentInputFormHtml =
            "<html>"
                + "<body>"
                + "<form id=\'redirectForm\' name=\'order\' action=\'\(secureURL)\' method=\'post\'>"
        paymentInputFormHtml += "<input type=\'hidden\' name=\'payment_session_id\' value=\'\(session)\'/>" +
            "<input type=\'hidden\' name=\'platform\' value=\'\(platform)\'/>" +
            "</form>" +
        "<script\n" +
                        " type=\"text/javascript\">\t window.onload = function () { const form = document.getElementById(\"redirectForm\"); const meta = { userAgent: window.navigator.userAgent, }; const sortedMeta = Object.entries(meta).sort().reduce((o, [k, v]) => { o[k] = v; return o; }, {}); const base64Meta = btoa(JSON.stringify(sortedMeta)); FN = document.createElement('input'); FN.setAttribute('type', 'hidden'); FN.setAttribute('name', 'browser_meta'); FN.setAttribute('value', base64Meta); form.appendChild(FN); form.submit(); }  </script>\n"
            + "</body>"
            + "</html>";
        return paymentInputFormHtml
    }
override func viewDidLoad(){
self.cfWebView.loadHTMLString(createForm(session: session_id, platform: "") , baseURL: nil)
}
```

## Step 3: Handle redirection <Badge>Client-side</Badge>

Once the payment flow has ended, Cashfree will redirect you to the URL specified while creating the order. Detect the URL redirection and close the web view appropriately.

```swift Swift theme={"dark"}
public func webView(_ webView: WKWebView, decidePolicyFor navigationAction: WKNavigationAction, decisionHandler: @escaping (WKNavigationActionPolicy) -> Void) {
    
    // Allowing all navigations
    decisionHandler(.allow)
    
    if navigationAction.request.url?.absoluteString ?? "" == "your return_url" {
        // close the web view
    }
}
```

## UPI intent from checkout

UPI Intent allows users to make direct payments through installed UPI applications without entering payment details manually. If you want to add UPI intent functionality to your custom iOS checkout integration, follow the steps below.

1. Add the required UPI app schemes to your **info.plist** file.\
   You need to add the following to your **info.plist** to enable your app to detect installed UPI applications:
   ```xml swift theme={"dark"}
   <key>LSApplicationCategoryType</key>
   <string></string>
   <key>LSApplicationQueriesSchemes</key>
   <array>
     <string>bhim</string>
     <string>paytmmp</string>
     <string>phonepe</string>
     <string>tez</string>
     <string>credpay</string>
   </array>
   ```

2. Add the JSBridge functions for the checkout page to get the list of installed UPI apps and handle opening the selected UPI app.

   ```swift Swift theme={"dark"}
   override func viewDidLoad() {

           super.viewDidLoad()
           self.cfWebView.configuration.userContentController.add(self, name: "nativeProcess")
           self.cfWebView.uiDelegate = self
           self.cfWebView.navigationDelegate = self
   }

   func getInstalledUPIApplications() -> [[String: String]] {
           var installedApps = [[String: String]]()
           let appName = [
               [
                   "displayName": CFConstants.googlePayName,
                   "id": "tez://",
                   "icon": (UIImage(named: "gpay", in: Bundle(for: CFUPIUtils.self), compatibleWith: nil)!).toBase64() ?? ""
               ],
               [
                   "displayName": CFConstants.paytmName,
                   "id": "paytmmp://",
                   "icon": (UIImage(named: "paytm", in: Bundle(for: CFUPIUtils.self), compatibleWith: nil)!).toBase64() ?? ""
               ],
               [
                   "displayName": CFConstants.phonePeName,
                   "id": "phonepe://",
                   "icon": (UIImage(named: "phonepe", in: Bundle(for: CFUPIUtils.self), compatibleWith: nil)!).toBase64() ?? ""
               ],
               [
                   "displayName": CFConstants.bhimName,
                   "id": "bhim://",
                   "icon": (UIImage(named: "bhim", in: Bundle(for: CFUPIUtils.self), compatibleWith: nil)!).toBase64() ?? ""
               ],
               [
                   "displayName": CFConstants.credName,
                   "id": "credpay://",
                   "icon": (UIImage(named: "credpay", in: Bundle(for: CFUPIUtils.self), compatibleWith: nil)!).toBase64() ?? ""
               ]
           ]
           for app in appName {
               let url = app["id"] ?? ""
               if UIApplication.shared.canOpenURL(URL(string: url)!) {
                   installedApps.append(app)
               }
           }
           return installedApps
       }

   public func userContentController(_ userContentController: WKUserContentController, didReceive message: WKScriptMessage) {
           var msg = message.body as? String ?? ""
           if msg == "getAppList" {
               let installedApps = getInstalledUPIApplications()
               do {
                   let jsonData = try JSONSerialization.data(withJSONObject: installedApps, options: [])
                   let jsonString = String(data: jsonData, encoding: String.Encoding.utf8)!
                   self.cfWebView.evaluateJavaScript("window.receiveAppList(\(jsonString))") { (_, _) in
                   }
               } catch {
                   print("Serialisation Failed")
               }
           } else if msg.contains("paytm") || msg.contains("phonepe") || msg.contains("tez") || msg.contains("bhim") || msg.contains("credpay") {
               if msg.contains("paytm") {
                   msg = msg.replacingOccurrences(of: "paytm:", with: "paytmmp:")
               }
               self.cfWebView.evaluateJavaScript("verifyPaymentForiOS()") { (val, error) in
                   let url = URL(string: msg)!
                   if UIApplication.shared.canOpenURL(url) {
                       UIApplication.shared.open(url, options: [:]) { (response) in
                       }
                   }
               }
           }
       }
   }
   ```

## Testing

After completing the iOS integration, verify that the payment flow works correctly:

1. Create a test order from your backend with a valid return URL.
2. Load the checkout form in your WKWebView with the payment session ID.
3. Verify that the payment page loads in the web view.
4. Test the payment flow end-to-end using test credentials.
5. Verify that the return URL is triggered correctly after payment completion.
6. If using UPI Intent, test with actual UPI applications installed on your test device.

## Sample code

```swift Swift theme={"dark"}
class CF2FAWebViewController: UIViewController, WKNavigationDelegate, WKScriptMessageHandler, WKUIDelegate {

@IBOutlet weak var cfWebView: WKWebView!

override func viewDidLoad() {

        super.viewDidLoad()
        self.cfWebView.configuration.userContentController.add(self, name: "nativeProcess")
        self.cfWebView.uiDelegate = self
        self.cfWebView.navigationDelegate = self
        self.cfWebView.loadHTMLString(createForm(session: session_id, platform: "") , baseURL: nil)
}


func getInstalledUPIApplications() -> [[String: String]] {
        var installedApps = [[String: String]]()
        let appName = [
            [
                "displayName": CFConstants.googlePayName,
                "id": CFConstants.googlePayPackage,
                "icon": (UIImage(named: "gpay", in: Bundle(for: CFUPIUtils.self), compatibleWith: nil)!).toBase64() ?? ""
            ],
            [
                "displayName": CFConstants.paytmName,
                "id": CFConstants.paytmPackage,
                "icon": (UIImage(named: "paytm", in: Bundle(for: CFUPIUtils.self), compatibleWith: nil)!).toBase64() ?? ""
            ],
            [
                "displayName": CFConstants.phonePeName,
                "id": CFConstants.phonePePackage,
                "icon": (UIImage(named: "phonepe", in: Bundle(for: CFUPIUtils.self), compatibleWith: nil)!).toBase64() ?? ""
            ],
            [
                "displayName": CFConstants.bhimName,
                "id": CFConstants.bhimPackage,
                "icon": (UIImage(named: "bhim", in: Bundle(for: CFUPIUtils.self), compatibleWith: nil)!).toBase64() ?? ""
            ],
            [
                "displayName": CFConstants.credName,
                "id": CFConstants.credPackage,
                "icon": (UIImage(named: "credpay", in: Bundle(for: CFUPIUtils.self), compatibleWith: nil)!).toBase64() ?? ""
            ]
        ]
        for app in appName {
            let url = app["id"] ?? ""
            if UIApplication.shared.canOpenURL(URL(string: url)!) {
                installedApps.append(app)
            }
        }
        return installedApps
    }

public func webView(_ webView: WKWebView, decidePolicyFor navigationAction: WKNavigationAction, decisionHandler: @escaping (WKNavigationActionPolicy) -> Void) {
    
    // Allowing all navigations
    decisionHandler(.allow)
    
    if navigationAction.request.url?.absoluteString ?? "" == "your return_url" {
        // close the web view
    }
}

func createForm(session: String, platform: String) -> String {
        var secureURL = ""
        if CFConstants.environment == .SANDBOX {
            secureURL = "https://sandbox.cashfree.com/pg/view/sessions/checkout"
//            secureURL = "https://test-k8s.cashfree.com/pgnextgenapi/api/v1/view/sessions/checkout"
        } else {
            secureURL = "https://api.cashfree.com/pg/view/sessions/checkout"
//            secureURL = "https://prod.cashfree.com/pgnextgenapi-test/api/v1/view/sessions/checkout"
        }
        var paymentInputFormHtml =
            "<html>"
                + "<body>"
                + "<form id=\'redirectForm\' name=\'order\' action=\'\(secureURL)\' method=\'post\'>"
        paymentInputFormHtml += "<input type=\'hidden\' name=\'payment_session_id\' value=\'\(session)\'/>" +
            "<input type=\'hidden\' name=\'platform\' value=\'\(platform)\'/>" +
            "</form>" +
        "<script\n" +
                        " type=\"text/javascript\">\t window.onload = function () { const form = document.getElementById(\"redirectForm\"); const meta = { userAgent: window.navigator.userAgent, }; const sortedMeta = Object.entries(meta).sort().reduce((o, [k, v]) => { o[k] = v; return o; }, {}); const base64Meta = btoa(JSON.stringify(sortedMeta)); FN = document.createElement('input'); FN.setAttribute('type', 'hidden'); FN.setAttribute('name', 'browser_meta'); FN.setAttribute('value', base64Meta); form.appendChild(FN); form.submit(); }  </script>\n"
            + "</body>"
            + "</html>";
        return paymentInputFormHtml
    }


public func userContentController(_ userContentController: WKUserContentController, didReceive message: WKScriptMessage) {
        var msg = message.body as? String ?? ""
        if msg == "getAppList" {
            let installedApps = getInstalledUPIApplications()
            do {
                let jsonData = try JSONSerialization.data(withJSONObject: installedApps, options: [])
                let jsonString = String(data: jsonData, encoding: String.Encoding.utf8)!
                self.cfWebView.evaluateJavaScript("window.receiveAppList(\(jsonString))") { (_, _) in
                }
            } catch {
                print("Serialisation Failed")
            }
        } else if msg.contains("paytm") || msg.contains("phonepe") || msg.contains("tez") || msg.contains("bhim") || msg.contains("credpay") {
            if msg.contains("paytm") {
                msg = msg.replacingOccurrences(of: "paytm:", with: "paytmmp:")
            }
            self.cfWebView.evaluateJavaScript("verifyPaymentForiOS()") { (val, error) in
                let url = URL(string: msg)!
                if UIApplication.shared.canOpenURL(url) {
                    UIApplication.shared.open(url, options: [:]) { (response) in
                    }
                }
            }
        }
    }
}
```

<snippet>snippets/related-topics-loader.mdx</snippet>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/payments/latest/orders/create-order">Create Order API</a></li>
    <li><a href="/docs/payments/online/go-live/whitelist">Domain Whitelisting</a></li>
    <li><a href="/docs/payments/manage/payment-methods#upi">UPI Intent Methods</a></li>
    <li><a href="/docs/payments/manage/payment-methods">Payment Methods</a></li>
    <li><a href="/docs/payments/online/web/redirect">Hosted Checkout Integration</a></li>
  </ul>
</div>


# Web Integration
Source: https://www.cashfree.com/docs/payments/online/web/redirect

Integrate Cashfree's prebuilt, PCI compliant hosted web checkout to accept 120+ payment methods on your site while keeping branding and UX in your control.

Cashfree’s web checkout offers merchants a secure, pre-built, and user-friendly interface that supports a wide variety of payment methods, enhancing the transaction experience for both merchants and customers.

## Key benefits

Web checkout provides the following advantages for your payment integration:

* **Simplified checkout**: Provides a pre-built, easy-to-use checkout page that delivers an optimised payment experience. It accepts payments from over 120 payment methods easily and securely.

* **Secure and PCI compliant**: Securely collects payment details and submits them directly to Cashfree servers, removing the need for Payment Card Industry Data Security Standard (PCI DSS) compliance requirements at the merchant’s end.

* **Personalised**: Customise your payment methods, branding, and various other elements to align seamlessly with your company's specific theme.

## Prerequisites

Ensure you complete the following tasks before starting the integration:

* Create a [Cashfree Merchant Account](https://merchant.cashfree.com/merchants/signup).
* Log in to the [Merchant Dashboard](https://merchant.cashfree.com/merchants/pg/developers/api-keys) and generate an **App ID** and **Secret Key**. Learn how to [generate API keys](/docs/api-reference/authentication#generate-api-keys).
* Whitelist your website domain for integration. Learn more about [domain whitelisting](/docs/payments/online/go-live/whitelist).

The web checkout integration consists of three essential steps:

<CardGroup>
  <Card title="Step 1" icon="money-bill-wave" href="/docs/payments/online/web/redirect#step-1:-create-an-order-server-side">
    Create an order
  </Card>

  <Card title="Step 2" icon="desktop" href="/docs/payments/online/web/redirect#step-2:-open-the-checkout-page-client-side">
    Open the checkout page
  </Card>

  <Card title="Step 3" icon="circle-check" href="/docs/payments/online/web/redirect#step-3:-confirm-the-payment-server-side">
    Confirm the payment
  </Card>
</CardGroup>

The step-by-step guide for each step of the integration process is as follows:

<div>
  <a href="https://www.cashfree.com/devstudio/#cf-checkout">
    <span>
      Try it in DevStudio

      <svg>
        <path />

        <path />
      </svg>
    </span>
  </a>
</div>

## Step 1: Create an order <Badge>Server-side</Badge>

To integrate the Cashfree Payment Gateway, you must first create an order. Complete this step before you process any payments. Configure an endpoint on your server to handle order creation. You cannot call this API from the client-side.

<Note>Create orders through your backend as this API requires your secret key. Do not call it directly from the client-side.</Note>

##### API request for creating an order

Here's a sample request for creating an order using your desired backend language. Cashfree offers backend [SDKs](/docs/api-reference/payments/sdk#server-sdk) to simplify the integration process.

<CodeGroup>
  ```bash curl theme={"dark"}
  curl --location 'https://sandbox.cashfree.com/pg/orders' \
  --header 'X-Client-Secret: {{clientKey}}' \
  --header 'X-Client-Id: {{clientId}}' \
  --header 'x-api-version: 2025-01-01' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data-raw '{
    "order_amount": 10.10,
    "order_currency": "INR",
    "customer_details": {
      "customer_id": "USER123",
      "customer_name": "joe",
      "customer_email": "joe.s@cashfree.com",
      "customer_phone": "+919876543210"
    },
    "order_meta": {
      "return_url": "https://b8af79f41056.eu.ngrok.io?order_id=order_123"
    }
  }'
  ```

  ```javascript nodejs theme={"dark"}
  import { Cashfree, CFEnvironment } from "cashfree-pg";

  const cashfree = new Cashfree(
  	CFEnvironment.PRODUCTION,
  	"{Client ID}",
  	"{Client Secret Key}"
  );

  function createOrder() {
  	var request = {
  		order_amount: "1",
  		order_currency: "INR",
  		customer_details: {
  			customer_id: "node_sdk_test",
  			customer_name: "",
  			customer_email: "example@gmail.com",
  			customer_phone: "9999999999",
  		},
  		order_meta: {
  			return_url:
  				"https://test.cashfree.com/pgappsdemos/return.php?order_id=order_123",
  		},
  		order_note: "",
  	};

  	cashfree
  		.PGCreateOrder(request)
  		.then((response) => {
  			console.log("Order created successfully:", response.data);
  		})
  		.catch((error) => {
  			console.error("Error setting up order request:", error.response.data);
  		});
  }
  ```

  ```python python theme={"dark"}
  from cashfree_pg.models.create_order_request import CreateOrderRequest
  from cashfree_pg.api_client import Cashfree
  from cashfree_pg.models.customer_details import CustomerDetails


  Cashfree.XClientId = {Client ID}
  Cashfree.XClientSecret = {Client Secret Key}
  Cashfree.XEnvironment = Cashfree.XSandbox
  x_api_version = "2023-08-01"

  def create_order():
          customerDetails = CustomerDetails(customer_id="123", customer_phone="9999999999")
          createOrderRequest = CreateOrderRequest(order_amount=1, order_currency="INR", customer_details=customerDetails)
          try:
              api_response = Cashfree().PGCreateOrder(x_api_version, createOrderRequest, None, None)
              print(api_response.data)
          except Exception as e:
              print(e)
  ```

  ```java java theme={"dark"}
  import com.cashfree.*;

  Cashfree.XClientId = {Client Key};
  Cashfree.XClientSecret = {Client Secret Key};
  Cashfree.XEnvironment = Cashfree.SANDBOX;

  static void createOrder() {
    CustomerDetails customerDetails = new CustomerDetails();
    customerDetails.setCustomerId("123");
    customerDetails.setCustomerPhone("9999999999");

    CreateOrderRequest request = new CreateOrderRequest();
    request.setOrderAmount(1.0);
    request.setOrderCurrency("INR");
    request.setCustomerDetails(customerDetails);
    try {
      Cashfree cashfree = new Cashfree();
      ApiResponse<OrderEntity> response = cashfree.PGCreateOrder("2023-08-01", request, null, null, null);
      System.out.println(response.getData().getOrderId());

    } catch (ApiException e) {
      throw new RuntimeException(e);
    }
  }
  ```

  ```go go theme={"dark"}
  import (
    cashfree "github.com/cashfree/cashfree-pg/v3"
  )

  func createOrder() {

  clientId := {Client ID}
  clientSecret := {Client Secret Key}
  cashfree.XClientId = &clientId
  cashfree.XClientSecret = &clientSecret
  cashfree.XEnvironment = cashfree.SANDBOX

  request := cashfree.CreateOrderRequest{
  		OrderAmount: 1,
  		CustomerDetails: cashfree.CustomerDetails{
  			CustomerId:    "1",
  			CustomerPhone: "9999999999",
  		},
  		OrderCurrency: "INR",
  		OrderSplits:   []cashfree.VendorSplit{},
  	}
  	version := "2023-08-01"
  	response, httpResponse, err := cashfree.PGCreateOrder(&version, &request, nil, nil, nil)
  	if err != nil {
  		fmt.Println(err.Error())
  	} else {
  		fmt.Println(httpResponse.StatusCode)
  		fmt.Println(response)
      }
  }
  ```

  ```csharp .net theme={"dark"}
  using cashfree_pg.Client;
  using cashfree_pg.Model;

  Cashfree.XClientId = {Client ID};
  Cashfree.XClientSecret = {Client Secret Key};
  Cashfree.XEnvironment = Cashfree.PRODUCTION;
  var cashfree = new Cashfree();
  var xApiVersion = "2023-08-01";

  void CreateOrder() {
      var customerDetails = new CustomerDetails("123", null, "9999999999");
      var createOrdersRequest = new CreateOrderRequest(null, 1.0, "INR", customerDetails);
      try {
          // Create Order
          var result = cashfree.PGCreateOrder(xApiVersion, createOrdersRequest, null, null, null);
          Console.WriteLine(result);
          Console.WriteLine(result.StatusCode);
          Console.WriteLine((result.Content as OrderEntity));
      } catch (ApiException e) {
          Console.WriteLine("Exception when calling PGCreateOrder: " + e.Message);
          Console.WriteLine("Status Code: " + e.ErrorCode);
          Console.WriteLine(e.StackTrace);
      }
  }
  ```

  ```php php theme={"dark"}
  \Cashfree\Cashfree::$XClientId = "<x-client-id>";
  \Cashfree\Cashfree::$XClientSecret = "<x-client-secret>";
  \Cashfree\Cashfree::$XEnvironment = Cashfree\Cashfree::$SANDBOX;

  $cashfree = new \Cashfree\Cashfree();

  $x_api_version = "2023-08-01";
  $create_orders_request = new \Cashfree\Model\CreateOrdersRequest();
  $create_orders_request->setOrderAmount(1.0);
  $create_orders_request->setOrderCurrency("INR");
  $customer_details = new \Cashfree\Model\CustomerDetails();
  $customer_details->setCustomerId("123");
  $customer_details->setCustomerPhone("9999999999");
  $create_orders_request->setCustomerDetails($customer_details);

  try {
      $result = $cashfree->PGCreateOrder($x_api_version, $create_orders_request);
      print_r($result);
  } catch (Exception $e) {
      echo 'Exception when calling PGCreateOrder: ', $e->getMessage(), PHP_EOL;
  }
  ```
</CodeGroup>

After successfully creating an order, you will receive a unique `order_id` and `payment_session_id` that you need for subsequent steps.

You can view the complete API request and response for `/orders` in the [Create Order API](/docs/api-reference/payments/latest/orders/create-order).

<Note>
  To show a short purchase description on checkout, such as a booking reference or route, add `checkout_context` to the `order_tags` object in the Create Order request above.

  ```json theme={"dark"}
  "order_tags": {
    "checkout_context": "Flight booking DEL-BOM, 12 JUN at 14:30"
  }
  ```

  For details about how checkout displays this text in a context card, see [Contextual Checkout](/docs/payments/features/contextual-checkout).
</Note>

## Step 2: Open the checkout page <Badge>Client-side</Badge>

<Warning>
  You must [whitelist your domain](/docs/payments/online/go-live/whitelist) with Cashfree before you start this step.
</Warning>

### 1. Include JS SDK in your client code

Include our JavaScript SDK in your client-side code to integrate the Cashfree checkout.

<CodeGroup>
  ```javascript CDN theme={"dark"}
  <script src="https://sdk.cashfree.com/js/v3/cashfree.js"></script>
  ```

  ```javascript NPM theme={"dark"}
  npm install @cashfreepayments/cashfree-js
  ```
</CodeGroup>

### 2. Initialise the SDK

Initialise the SDK using the `Cashfree()` function. You can use one of two modes:

* `sandbox`: Use this for a test environment.
* `production`: Use this for your live environment.

<CodeGroup>
  ```javascript CDN theme={"dark"}
  const cashfree = Cashfree({
      mode:"sandbox" //or production
  });
  ```

  ```javascript NPM theme={"dark"}
  const cashfree = await load({
  	mode: "sandbox" //or production
  });
  //This load function returns a Promise that resolves with a newly created Cashfree object once Cashfree.js has loaded. If you call load in a server environment it will resolve to null.
  ```
</CodeGroup>

### 3. Open Cashfree checkout

Use the `cashfree.checkout()` method to open the checkout page. Use the following parameters with this method:

* `paymentSessionId`: The ID you receive from the create order response.
* `redirectTarget` (optional): This parameter determines how the checkout page opens. Use one of the following values:

| Property value | Description |
| - | - |
| `_self` (default) | Opens the payment link in the same frame as it was clicked. |
| `_blank` | Opens the payment link in a new window or tab. |
| `_top` | Opens the linked document in the full body of the window. |
| `_modal` | Opens the payment link in a pop-up window on the current page. |
| DOM element | Opens the payment link directly within a specified DOM element. |

### Checkout variants

Cashfree supports the following checkout variants:

* **Redirect checkout**: Use for `redirectTarget` values `_self`, `_blank`, or `_top`.
* **Popup checkout**: Use for `redirectTarget` value `_modal`.
* **Inline checkout**: Use for `redirectTarget` as a DOM element.

<Note>
  The integration approach varies for pop-up and inline checkout. You must manage the promise that `cashfree.checkout()` returns to execute additional code after the payment attempt.
</Note>

<CodeGroup>
  ```javascript Redirect - javascript {14,15,16,17,18,19,20,21,22,23,24,25} theme={"dark"}
  <!DOCTYPE html>
  <html lang="en">
      <head>
          <meta charset="UTF-8">
          <meta name="viewport" content="width=device-width, initial-scale=1.0">
          <title>Cashfree Checkout Integration</title>
          <script src="https://sdk.cashfree.com/js/v3/cashfree.js"></script>
      </head>
      <body>
          <div class="row">
              <p>Click below to open the checkout page in the current tab</p>
              <button id="renderBtn">Pay Now</button>
          </div>
          <script>
              const cashfree = Cashfree({
                  mode: "production",
              });
              document.getElementById("renderBtn").addEventListener("click", () => {
                  let checkoutOptions = {
                      paymentSessionId: "your-payment-session-id",
                      redirectTarget: "_self",
                  };
                  cashfree.checkout(checkoutOptions);
              });
          </script>
      </body>
  </html>
  ```

  ```javascript Redirect - React {4,5,6,7,8,9,10,11,12,13,14,15,16,17,18} theme={"dark"}
  import { load } from "@cashfreepayments/cashfree-js";

  function Checkout() {
    let cashfree;
    var initializeSDK = async function () {
      cashfree = await load({
        mode: "production",
      });
    };
    initializeSDK();

    const doPayment = async () => {
      let checkoutOptions = {
        paymentSessionId: "your-payment-session-id",
        redirectTarget: "_self",
      };
      cashfree.checkout(checkoutOptions);
    };

    return (
      <div class="row">
        <p>Click below to open the checkout page in the current tab</p>
        <button type="submit" class="btn btn-primary" id="renderBtn" onClick={doPayment}>
          Pay Now
        </button>
      </div>
    );
  }
  export default Checkout;
  ```

  ```javascript Popup - JavaScript {15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41} theme={"dark"}
  <!DOCTYPE html>
  <html lang="en">
      <head>
          <meta charset="UTF-8">
          <meta name="viewport" content="width=device-width, initial-scale=1.0">
          <title>Cashfree Checkout Integration</title>
          <script src="https://sdk.cashfree.com/js/v3/cashfree.js"></script>
      </head>
      <body>
          <div class="row">
              <p>Click below to open the checkout page in a pop-up </p>
              <button id="renderBtn">Pay Now</button>
          </div>
          <script>
              const cashfree = Cashfree({
                  mode: "production",
              });
              document.getElementById("renderBtn").addEventListener("click", () => {
                  let checkoutOptions = {
                      paymentSessionId: "your-payment-session-id",
                      redirectTarget: "_modal",
                  };
                  cashfree.checkout(checkoutOptions).then((result) => {
                      if(result.error){
                          // This will be true whenever the user clicks on the close icon inside the modal or any error happens during the payment
                          console.log("User has closed the popup or there is some payment error, Check for Payment Status");
                          console.log(result.error);
                      }
                      if(result.redirect){
                          // This will be true when the payment redirection page can't be opened in the same window
                          // This is an exceptional case only when the page is opened inside an inAppBrowser
                          // In this case the customer will be redirected to the return URL once payment is completed
                          console.log("Payment will be redirected");
                      }
                      if(result.paymentDetails){
                          // This will be called whenever the payment is completed irrespective of transaction status
                          console.log("Payment has been completed, Check for Payment Status");
                          console.log(result.paymentDetails.paymentMessage);
                      }
                  });
              });
          </script>
      </body>
  </html>
  ```

  ```javascript Popup - React {4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35} theme={"dark"}
  import { load } from "@cashfreepayments/cashfree-js";

  function Checkout() {
    let cashfree;
    var initializeSDK = async function () {
      cashfree = await load({
        mode: "production",
      });
    };
    initializeSDK();

    const doPayment = async () => {
      let checkoutOptions = {
        paymentSessionId: "your-payment-session-id",
        redirectTarget: "_modal",
      };
      cashfree.checkout(checkoutOptions).then((result) => {
        if (result.error) {
          // This will be true whenever the user clicks on the close icon inside the modal or any error happens during the payment
          console.log("User has closed the popup or there is some payment error, Check for Payment Status");
          console.log(result.error);
        }
        if (result.redirect) {
          // This will be true when the payment redirection page can't be opened in the same window
          // This is an exceptional case only when the page is opened inside an inAppBrowser
          // In this case the customer will be redirected to the return URL once payment is completed
          console.log("Payment will be redirected");
        }
        if (result.paymentDetails) {
          // This will be called whenever the payment is completed irrespective of transaction status
          console.log("Payment has been completed, Check for Payment Status");
          console.log(result.paymentDetails.paymentMessage);
        }
      });
    };

    return (
      <div class="row">
        <p>Click below to open the checkout page in a pop-up </p>
        <button type="submit" class="btn btn-primary" id="renderBtn" onClick={doPayment}>
          Pay Now
        </button>
      </div>
    );
  }
  export default Checkout;
  ```

  ```javascript Inline - Javascript {16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46} theme={"dark"}
  <!DOCTYPE html>
  <html lang="en">
      <head>
          <meta charset="UTF-8">
          <meta name="viewport" content="width=device-width, initial-scale=1.0">
          <title>Cashfree Checkout Integration</title>
          <script src="https://sdk.cashfree.com/js/v3/cashfree.js"></script>
      </head>
      <body>
          <div class="row">
              <p>Click below to open the checkout page here</p>
              <button id="renderBtn">Pay Now</button>
              <div id="cf_checkout"></div>
          </div>
          <script>
              const cashfree = Cashfree({
                  mode: "production",
              });
              document.getElementById("renderBtn").addEventListener("click", () => {
                  let checkoutOptions = {
                      paymentSessionId: "your-payment-session-id",
                      redirectTarget: document.getElementById("cf_checkout"),
                      appearance: {
                          width: "425px",
                          height: "700px",
                      },
                  };
                  cashfree.checkout(checkoutOptions).then((result) => {
                      if(result.error){
                          // This will be true when there is any error during the payment
                          console.log("There is some payment error, Check for Payment Status");
                          console.log(result.error);
                      }
                      if(result.redirect){
                          // This will be true when the payment redirection page can't be opened in the same window
                          // This is an exceptional case only when the page is opened inside an inAppBrowser
                          // In this case the customer will be redirected to the return URL once payment is completed
                          console.log("Payment will be redirected");
                      }
                      if(result.paymentDetails){
                          // This will be called whenever the payment is completed irrespective of transaction status
                          console.log("Payment has been completed, Check for Payment Status");
                          console.log(result.paymentDetails.paymentMessage);
                      }
                  });
              });
          </script>
      </body>
  </html>
  ```

  ```javascript Inline - React {4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39} theme={"dark"}
  import { load } from "@cashfreepayments/cashfree-js";

  function Checkout() {
      let cashfree;
      var initializeSDK = async function () {          
          cashfree = await load({
              mode: "production"
          });
      }
      initializeSDK();

      const doPayment = async () => {
          let checkoutOptions = {
              paymentSessionId: "your-payment-session-id",
              redirectTarget: document.getElementById("cf_checkout"),
              appearance: {
                  width: "425px",
                  height: "700px",
              },
          };
          cashfree.checkout(checkoutOptions).then((result) => {
              if(result.error){
                  // This will be true when there is any error during the payment
                  console.log("There is some payment error, Check for Payment Status");
                  console.log(result.error);
              }
              if(result.redirect){
                  // This will be true when the payment redirection page can't be opened in the same window
                  // This is an exceptional case only when the page is opened inside an inAppBrowser
                  // In this case the customer will be redirected to the return URL once payment is completed
                  console.log("Payment will be redirected");
              }
              if(result.paymentDetails){
                  // This will be called whenever the payment is completed irrespective of transaction status
                  console.log("Payment has been completed, Check for Payment Status");
                  console.log(result.paymentDetails.paymentMessage);
              }
          });
      };

      return (
          <div class="row">
              <p>Click below to open the checkout page here</p>
              <button type="submit" class="btn btn-primary" id="renderBtn" onClick={doPayment}>
                  Pay Now
              </button>
              <div id="cf_checkout"></div>
          </div>
      );
  }
  export default Checkout;
  ```
</CodeGroup>

## Step 3: Confirm the payment <Badge>Server-side</Badge>

After the customer completes the payment, you must confirm the payment status.

### Redirect checkout

When the payment process finishes, the user redirects to the return URL you provided when you created the order (Step 1). If you do not provide a return URL, customers redirect to a default Cashfree page.

<Note>
  We recommend that you provide a return URL while creating an order. This will improve the overall user experience by ensuring your customers don’t land on
  broken or duplicated pages. Also, remember to add context of the order in your return URL so that you can identify the order once the customer has returned to
  this URL.
</Note>

### Popup and inline checkout

When the payment process finishes, the `cashfree.checkout()` function returns a promise. You must handle this promise to process the payment response.

### Order status verification

To verify an order you can call our `/pg/orders` endpoint from your backend. You can also use our SDK to achieve the same.

<CodeGroup>
  ```bash curl theme={"dark"}
  curl --request GET \
       --url https://sandbox.cashfree.com/pg/orders/{order_id} \
       --header 'accept: application/json' \
       --header 'x-api-version: 2025-01-01' \
       --header 'x-client-id: "YOUR APP ID GOES HERE"' \
       --header 'x-client-secret: "YOUR SECRET KEY GOES HERE"'
  ```

  ```javascript nodejs theme={"dark"}
  cashfree
  .PGFetchOrder("<order_id>")
  .then((response) => {
  	console.log("Order fetched successfully:", response.data);
  })
  .catch((error) => {
  	console.error("Error:", error.response.data.message);
  });
  ```

  ```python python theme={"dark"}
  from cashfree_pg.models.create_order_request import CreateOrderRequest
  from cashfree_pg.api_client import Cashfree
  from cashfree_pg.models.customer_details import CustomerDetails
  from cashfree_pg.models.order_meta import OrderMeta

  Cashfree.XClientId = "<x-client-id>"
  Cashfree.XClientSecret = "<x-client-secret>"
  Cashfree.XEnvironment = Cashfree.SANDBOX
  x_api_version = "2023-08-01"

  try:
      api_response = Cashfree().PGFetchOrder(x_api_version, "order_3242X4jQ5f0S9KYxZO9mtDL1Kx2Y7u", None)
      print(api_response.data)
  except Exception as e:
      print(e)

  ```

  ```java java theme={"dark"}
  import com.cashfree.*;
  //other code

  try {
      Cashfree.XClientId = "<x-client-id>";
      Cashfree.XClientSecret = "<x-client-secret>";
      Cashfree.XEnvironment = Cashfree.SANDBOX;

      Cashfree cashfree = new Cashfree();
      String xApiVersion = "2023-08-01";

      ApiResponse<OrderEntity> responseFetchOrder = cashfree.PGFetchOrder(xApiVersion, "<order_id>", null, null, null);
      System.out.println(response.getData().getOrderId());
  } catch (ApiException e) {
      throw new RuntimeException(e);
  }
  ```

  ```go go theme={"dark"}
  version := "2023-08-01"
  response, httpResponse, err := cashfree.PGFetchOrder(&version, "<order_id>", nil, nil, nil)
  if err != nil {
  	fmt.Println(err.Error())
  } else {
  	fmt.Println(httpResponse.StatusCode)
  	fmt.Println(response)
  }
  ```

  ```csharp .net theme={"dark"}
  using cashfree_pg.Client;
  using cashfree_pg.Model;

  Cashfree.XClientId = "<x-client-id>";
  Cashfree.XClientSecret = "<x-client-secret>";
  Cashfree.XEnvironment = Cashfree.SANDBOX;
  var cashfree = new Cashfree();
  var xApiVersion = "2023-08-01";

  try {
      var result = cashfree.PGFetchOrder(xApiVersion, "<order_id>>", null, null);
      Console.WriteLine(result);
      Console.WriteLine(result.StatusCode);
      Console.WriteLine((result.Content as OrderEntity));
  } catch (ApiException e) {
      Console.WriteLine("Exception when calling PGFetchOrder: " + e.Message);
      Console.WriteLine("Status Code: " + e.ErrorCode);
      Console.WriteLine(e.StackTrace);
  }
  ```

  ```php php theme={"dark"}
  $x_api_version = "2023-08-01";
  try {
      $response = $cashfree->PGFetchOrder($x_api_version, "<order_id>");
      print_r($response);
  } catch (Exception $e) {
      echo 'Exception when calling PGFetchOrder: ', $e->getMessage(), PHP_EOL;
  }
  ```
</CodeGroup>

<Note>
  Always verify the order status before you deliver services to the customer. You can use the [Get Order API](/docs/api-reference/payments/latest/orders/get-order) for this. An order is successful when the `order_status` is `PAID`.
</Note>

### Using return\_url and webhooks

If a `return_url` is configured while creating the order, Cashfree redirects the customer to that URL after the checkout flow is completed. Do not rely solely on browser redirects to confirm payment success, because customers may close the browser or lose connectivity before the redirect completes. Use server-side webhooks to confirm the final payment status, so your system does not depend on the customer's browser session or redirection.

The Cashfree-hosted payment success page cannot be directly customised with arbitrary text. To show a customised success page, configure a `return_url` to redirect the customer to a page hosted on your own servers after the payment flow, where you can display any required content.

## Testing

After you integrate the checkout button, verify that it opens the Cashfree-hosted payment page. If the integration does not work, follow these steps to troubleshoot:

1. Open the **Network** tab in your browser developer tools.
2. Click the pay button and check the console logs.
3. Ensure you pass the correct environment and `payment_session_id`.
4. Use `console.log()` in your button click listener to confirm that you pass data correctly.

<div>
  <p>Affiliate partner program</p>

  <p>As a developer building payment experiences for your clients, you can earn additional income while providing them with industry-leading payment solutions.</p>

  <p>Join the <a href="https://partner.cashfree.com/partner-ui/authentication/signup?source-action=Affiliate%20Program%20LP&action=Sign%20Up&button-id=StartNow_CashfreeAffiliatePartnerProgram">Cashfree affiliate partner program</a> and get rewarded every time your clients use Cashfree.</p>

  <p>**What you get:**</p>

  <ul>
    <li>Earn up to 0.25% commission on every transaction.</li>
    <li>Become a trusted fintech partner for your clients.</li>
    <li>Access to a dedicated partner manager for expert support.</li>
  </ul>

  <p>**What your clients get:**</p>

  <ul>
    <li>Instant activation and go live in minutes.</li>
    <li>Industry-best success rate across all payment modes.</li>
    <li>Effortless acceptance of international payments in 140+ currencies.</li>
  </ul>

  <p>Get started today. <a href="https://partner.cashfree.com/partner-ui/authentication/signup?source-action=Affiliate%20Program%20LP&action=Sign%20Up&button-id=StartNow_BecomeAPartner">Become a partner now</a>.</p>
</div>

<snippet>snippets/related-topics-loader.mdx</snippet>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/payments/latest/orders/create-order">Create Order API</a></li>
    <li><a href="/docs/api-reference/payments/latest/orders/get-order">Get Order API</a></li>
    <li><a href="/docs/payments/online/go-live/whitelist">Domain Whitelisting</a></li>
    <li><a href="/docs/api-reference/payments/sdk">Payment SDKs</a></li>
  </ul>
</div>


# Configuration
Source: https://www.cashfree.com/docs/payments/online/webhooks/configure

Configure Cashfree webhooks for Payment Gateway, Payment Links, Forms, and Subscriptions to receive event notifications, view logs, and set alerts.

Add and define webhooks for Payment Gateway, Payment Links, Payment Forms, and Subscriptions. Get notified for each action on the URLs you configure.

## Add a webhook endpoint

To add a new webhook:

1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
2. Go to **Payment Gateway** > **Developers** or select **Developers** from the homepage.
3. Select **Add Webhook Endpoint** to create a new webhook. Enter the endpoint URL and select the webhook version from the drop-down menu.
4. Select **Test** to verify if the webhook endpoint returns a response and select **Next**.

<Note>
  In the sandbox environment, both http\:// and https\:// endpoints are supported. In the production environment, only https\:// endpoints are supported.
</Note>

5. Select the events for which you want to configure the webhooks and select **Add Webhook**.

<Accordion title="View available webhook events">
  * Dispute Closed
  * Dispute Created
  * Dispute Updated
  * Failed Payment
  * Incident
  * Instrument Active
  * Instrument Failed
  * Refund
  * Settlement Failed
  * Settlement Initiated
  * Settlement Reversed
  * Success Payment
  * Success Payment TDR (Payment Charges webhook — `PAYMENT_CHARGES_WEBHOOK`)
  * User Dropped Payment
  * Vendor Settlement Failed
  * Vendor Settlement Initiated
  * Vendor Settlement Reversed
  * Vendor Settlement Success
</Accordion>

<Frame>
  <img />
</Frame>

You have successfully created a webhook for the required event. You can view all your webhooks from the **Webhook Endpoints** homepage. Details such as **URL**, **Webhook Version**, **Event**, and **Actions** are available.

## Test a webhook endpoint

You can test the URL at any time using the **Test** option.

1. Select **Test** on the webhook you want to verify.
2. In the **Test Webhook Endpoint** pop-up, select **Test**.
3. Select **Done** after you receive a success response.

<Frame>
  <img />
</Frame>

## Edit a webhook endpoint

To edit a webhook:

1. Select **Edit** on the webhook you want to modify.
2. Select the events you want to add or remove.
3. Select **Save**.

<Frame>
  <img />
</Frame>

## Logs

The **Logs** section displays all webhook logs (successful or failed) on your Merchant Dashboard. You can access the logs directly at [merchant.cashfree.com/merchants/pg/developers/webhooks/logs?env=prod](https://merchant.cashfree.com/merchants/pg/developers/webhooks/logs?env=prod).

<Frame>
  <img />
</Frame>

To view logs:

1. Specify the date range to view logs for a particular period.
2. Use the **Search and Filter** option to view specific logs. Enter the **URL** and select the required webhook type from the drop-down menu.
3. Select a request to view details such as **Message**, **Time**, **Version**, **Header Details**, and **Payload**.
4. To view only **Success** or **Failed** logs, navigate to the respective tabs.

Watch the video below to learn how logs work.

<iframe />

***

## Analytics

The webhook analytics feature provides contextual information on webhook metrics that help you track, monitor, and assess the success or failure of your webhooks. Metrics such as success rate and latency are available.

To view analytics:

1. Specify the date range to view metrics for a particular period.
2. Use the **Search and Filter** option to filter results. Enter the URL and select the required webhook type from the drop-down menu.

<Frame>
  <img />
</Frame>

***

### Success rate

The success rate chart displays the webhook delivery status over time. The chart shows the following metrics:

* **Total Attempts**: The total number of webhook delivery attempts.
* **Successful**: The count of webhooks delivered successfully on the first attempt.
* **Retried Successful**: The count of webhooks that succeeded after retry attempts.
* **Failed**: The count of webhooks that failed to deliver.

Hover over individual bars to view the breakdown for a specific date.

### Latency

Latency is the time taken to respond to webhooks. Hover over individual bars to view the latency for a specific date. The average latency value is also displayed.

## Webhook configuration across accounts

Webhook configurations are managed at the merchant/MID level and are not automatically replicated across different accounts. You must configure the required webhook endpoint directly from the Cashfree Merchant Dashboard for each MID and select the relevant events you wish to receive.

The webhook options in the Partner Dashboard are limited to partner-level events supported by the platform. Payment Link-specific webhook events are not available at the Partner level and can only be configured at the individual merchant account level via the Merchant Dashboard.

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/payments/online/webhooks/security-checklist">Webhook Security Checklist</a></li>
    <li><a href="/docs/payments/online/webhooks/overview">Webhooks Overview</a></li>
    <li><a href="/docs/payments/online/webhooks/signature-verification">Signature Verification</a></li>
  </ul>
</div>


# Overview
Source: https://www.cashfree.com/docs/payments/online/webhooks/overview

Listen on a webhook endpoint to receive Cashfree event notifications about orders, payments, refunds, and settlements so your backend can react automatically.

When building Cashfree integrations, you might want your applications to receive events as they occur in your Cashfree account so that your back-end systems can execute actions accordingly.

To enable real-time event notifications, register your webhook endpoints with Cashfree at **Developers > Webhooks**. These endpoints receive HTTP POST requests containing JSON payloads whenever specific events happen in your Cashfree account. This allows your application to react promptly to changes such as successful payments, failed transactions, or new chargebacks.

<Tip>Install [Cashfree Agent Skills](/docs/tools-ai/cashfree-agent-skills) to bring Cashfree product knowledge into your AI coding assistant (Claude Code, Cursor, VS Code Copilot, Gemini CLI, and more) to answer integration questions and generate accurate code without leaving your editor.</Tip>

<CardGroup>
  <Card title="Payment webhooks" icon="credit-card" href="/docs/api-reference/payments/latest/payments/webhooks">
    Headers and payload samples for payment status notifications.
  </Card>

  <Card title="Refund webhooks" icon="rotate-left" href="/docs/api-reference/payments/latest/refunds/webhooks">
    Payload samples for refund status notifications.
  </Card>

  <Card title="Settlement webhooks" icon="building" href="/docs/api-reference/payments/latest/settlements/settlement-webhooks">
    Settlement status notifications and payout objects.
  </Card>

  <Card title="Subscription webhooks" icon="repeat" href="/docs/api-reference/payments/latest/subscription/webhooks">
    Subscription lifecycle and payment status notifications for recurring billing.
  </Card>

  <Card title="Payment Link webhooks" icon="link" href="/docs/api-reference/payments/latest/payment-links/webhooks">
    Payload samples for payment link status notifications.
  </Card>

  <Card title="Payment Form webhooks" icon="file-lines" href="/docs/payments/no-code/payment-forms/webhooks">
    Payment status notifications for no-code payment forms.
  </Card>

  <Card title="Card token webhooks" icon="layer-group" href="/docs/api-reference/payments/latest/token-vault/webhooks">
    Instrument payloads for saved card token status notifications.
  </Card>

  <Card title="Dispute webhooks" icon="triangle-exclamation" href="/docs/api-reference/payments/latest/disputes/dispute-webhooks">
    Chargeback and dispute status notifications.
  </Card>

  <Card title="SoftPOS webhooks" icon="mobile" href="/docs/api-reference/payments/latest/offline-payments/softpos-webhooks">
    Terminal and SoftPOS transaction status notifications.
  </Card>

  <Card title="Easy Split webhooks" icon="users" href="/docs/api-reference/payments/latest/split/webhooks/overview">
    Vendor settlement and vendor status change notifications for Easy Split.
  </Card>

  <Card title="Global collections partner webhooks" icon="globe" href="/docs/api-reference/payments/latest/international-payments/global-collections/partner/webhooks">
    Partner-facing notifications for international collections transactions.
  </Card>
</CardGroup>

### Verify webhooks

Verify webhooks to prevent tampering and ensure you process only legitimate notifications from Cashfree. Without verification, your application is vulnerable to fraudulent payment confirmations and security threats.

Use [webhook signatures](/docs/payments/online/webhooks/signature-verification) to authenticate Cashfree webhooks, and proceed with further actions only after successful verification.

<Warning>
  Cashfree generates the webhook signature based on the raw payload, not the
  parsed payload. You can refer to how the popular JavaScript framework
  [NestJS](https://docs.nestjs.com/faq/raw-body) provides a hook for accessing
  the raw body.
</Warning>

### Test webhooks

Before going live, test your webhooks in the sandbox environment to verify payloads and integration behaviour. Configure your webhooks from the dashboard in the test environment. Events triggered by test transactions send webhooks to your configured endpoint.

<Info>
  You can create endpoint URLs and test webhooks using tools like
  [webhook.site](https://webhook.site) or create a tunnel to your localhost
  using tools like [ngrok](https://ngrok.com).
</Info>

### Duplicate webhook processing

<Note>
  Cashfree uses **at-least-once** delivery to prevent missed webhook
  notifications.
</Note>

In case of inadvertent downtimes at Cashfree or your end, Cashfree may attempt
duplicate webhook delivery to ensure fulfilment. <br />

<br />

To prevent business processing of duplicate events at your end, you are strongly
recommended to validate `x-idempotency-header` in each webhook header. This hashed
value will always be unique for each unique webhook payload.

<Note>
  This feature is available on webhook versions starting 2025-01-01. To migrate
  to this new version, refer to [Webhook Migration](#webhook-migration) section
  below.
</Note>

### Retry webhooks policy

You can define a custom retry policy for webhooks that do not receive a **200 response**. To configure the retry policy, log in to the **[Merchant Dashboard](https://merchant.cashfree.com/auth/login)** and go to **Payment Gateway > Developers > Webhooks**. Cashfree retries delivery to your URLs based on the defined policy until it receives a **200 response**.

You will see two types of URLs listed -

1. `NOTIFY_URL` - This is the default configuration added to your account and configurations here cannot be edited or deleted. This configuration will apply to only the URLs sent in the notify\_url param of [Create Order API](/docs/api-reference/payments/latest/orders/create-order) within the order\_meta object
2. Your custom configured URLs - You can click on 'Edit' and follow the steps on the screen to define a custom retry policy. A default policy is applied to all URLs

The following webhook policy types are available:

* **Default**: The system retries up to three times at 2, 10, and 30-minute intervals.
* **Fixed**: You can specify the number of retries (maximum of 10) and the interval between retries.
* **Exponential**: You can specify the number of retries (maximum of 10), the interval, and a multiplier. For example, if the number of retries is 5, the interval is 15 minutes, and the multiplier is 2, retries occur at 15, 17, 19, 23, and 31-minute intervals.
* **Custom**: You can specify the number of retries (maximum of 10) and define custom intervals.

### Resend webhooks

<Note>
  This feature is only available for [`payment`
  webhooks](/docs/api-reference/payments/latest/payments/webhooks)
</Note>

There are various reasons why you might need to resend a webhook response to your endpoint, such as service-level downtime or failure to register a webhook payload. With Cashfree, you can resend previously triggered webhooks. Log in to your dashboard and follow the steps below:

1. Go to Webhooks under the Developer section and go to **Logs**.
2. On the top right, click the **Batch Resend** button.

<img />

3. You will see three options here:
   * **Text**: Enter transaction IDs (comma separated) in the text box and click **Resend**. Transaction IDs are the same as Entity IDs listed on the logs dashboard.
   * **File**: Upload the file in the required format (downloadable from the dashboard) with the required Transaction IDs and click **Resend**.
   * **Time Duration**: Select the time period (max. allowed duration is 24 hours) and click **Resend**.

### Webhook signature verification

<Warning>
  Cashfree generates the webhook signature based on the raw payload, not the
  parsed payload. You can refer to how the popular JavaScript framework
  [NestJS](https://docs.nestjs.com/faq/raw-body) provides a hook for accessing
  the raw body.
</Warning>

Use the signature to verify that the request has not been tampered with. To verify the signature, you need your Cashfree PG secret key and the payload.

* The timestamp is present in the header `x-webhook-timestamp`.
* The actual signature is present in the header `x-webhook-signature`.

```bash signature-verification theme={"dark"}
timestamp := 1617695238078;
signedPayload := $timestamp.$payload;
expectedSignature := Base64Encode(HMACSHA256($signedPayload, $merchantSecretKey));
```

### SDK verification (built-in approach)

<CodeGroup>
  ```javascript Node (express) theme={"dark"}
  var express = require('express')
  const { Cashfree, CFEnvironment } = require("cashfree-pg");

  var app = express()

  const cashfree = new Cashfree(
  CFEnvironment.SANDBOX,
  "{Client ID}",
  "{Client Secret Key}"
  );

  app.post('/webhook', function (req, res) {
  try {
  cashfree.PGVerifyWebhookSignature(req.headers["x-webhook-signature"], req.rawBody, req.headers["x-webhook-timestamp"])
  } catch (err) {
  console.log(err.message)
  }
  })

  ```

  ```go golang theme={"dark"}
  import (
    cashfree "github.com/cashfree/cashfree-pg/v4"
  )

  // Route
  e.POST("/webhook", _this.Webhook)

  // Controller
  func (_this *WebhookRoute) Webhook(c echo.Context) error {
    	clientId := "<x-client-id>"
  		clientSecret := "<x-client-secret>"
  		cashfree.XClientId = &clientId
  		cashfree.XClientSecret = &clientSecret
  		cashfree.XEnvironment = cashfree.SANDBOX

      signature := c.Request().Header.Get("x-webhook-signature")
      timestamp := c.Request().Header.Get("x-webhook-timestamp")

      body, _ := ioutil.ReadAll(c.Request().Body)
      rawBody := string(body)
      webhookEvent, err := cashfree.PGVerifyWebhookSignature(signature, rawBody, timestamp)
      if err != nil {
  		fmt.Println(err.Error())
  	} else {
  		fmt.Println(webhookEvent.Object)
  	}
  }
  ```

  ```php PHP theme={"dark"}
  <?php

  $inputJSON = file_get_contents('php://input');

  $expectedSig = getallheaders()['x-webhook-signature'];
  $ts = getallheaders()['x-webhook-timestamp'];

  if(!isset($expectedSig) || !isset($ts)){
      echo "Bad Request";
      die();
  }

  \Cashfree\Cashfree::$XClientId = "<x-client-id>";
  \Cashfree\Cashfree::$XClientSecret = "<x-client-secret>";
  $cashfree = new \Cashfree\Cashfree();

  try {
   $response =  cashfree->PGVerifyWebhookSignature($expectedSig, $inputJSON, $ts);
  } catch(Exception $e) {
    // Error if signature verification fails
  }
  ?>
  ```

  ```python Python theme={"dark"}
  from cashfree_pg.api_client import Cashfree

  @app.route('/webhook', methods = ['POST'])
  def disp():
  		# Get the raw body from the request
      raw_body = request.data

      # Decode the raw body bytes into a string
      decoded_body = raw_body.decode('utf-8')

      #verify_signature
      timestamp = request.headers['x-webhook-timestamp']
      signature = request.headers['x-webhook-signature']

  		cashfree = Cashfree()
  		cashfree.XClientId = "<app_id>"
  		cashfree.XClientSecret = "<secret_key>"
  		try:
  			cashfreeWebhookResponse = cashfree.PGVerifyWebhookSignature(signature, decoded_body, timestamp)
  		except:
  			# If Signature mis-match
  ```

  ```java Java theme={"dark"}
  import com.cashfree.*;

  @PostMapping("/my-endpoint")
  public String handlePost(HttpServletRequest request) throws IOException {
      Cashfree.XClientId = "<x-client-id>";
  		Cashfree.XClientSecret = "<x-client-secret>";
  		Cashfree.XEnvironment = Cashfree.SANDBOX;

    	StringBuilder stringBuilder = new StringBuilder();
      BufferedReader bufferedReader = null;

      try {
        bufferedReader = request.getReader();
        String line;
        while ((line = bufferedReader.readLine()) != null) {
                stringBuilder.append(line).append('\n');
        }


        String rawBody = stringBuilder.toString();
        String signature = request.getHeader("x-webhook-signature");
        String timestamp = request.getHeader("x-webhook-timestamp");

        Cashfree cashfree = new Cashfree();
        PGWebhookEvent webhook = cashfree.PGVerifyWebhookSignature(signature, rawBody, timestamp);

      } catch (Exception e) {
              // Error if verification fails
      } finally {
           if (bufferedReader != null) {
              bufferedReader.close();
  		}
  	}

  }
  ```

  ```csharp csharp theme={"dark"}
  using cashfree_pg.Client;
  using cashfree_pg.Model;


  		[Route("api/[controller]")]
      [ApiController]
      public class YourController : ControllerBase
      {
          [HttpPost]
          public async Task<IActionResult> Post()
          {
              // Read the raw body of the POST request
              using (StreamReader reader = new StreamReader(Request.Body, Encoding.UTF8))
              {
                  string requestBody = await reader.ReadToEndAsync();
                  var headers = Request.Headers;
                  var signature = headers["x-webhook-signature"];
                  var timestamp = headers["x-webhook-timestamp"];

                  Cashfree.XClientId = "<x-client-id>";
                  Cashfree.XClientSecret = "<x-client-secret>";
                  Cashfree.XEnvironment = Cashfree.SANDBOX;
  								var cashfree = new Cashfree();

                  try {
                  var response = cashfree.PGVerifyWebhookSignature(signature, requestBody, timestamp);
                  } catch(Exception e) {
                  // Error if signature mis matches
                  }
              }
          }
      }
  ```
</CodeGroup>

### Manual verification (custom approach)

<CodeGroup>
  ```javascript Node (Express) theme={"dark"}
  function verify(ts, request){
      const body = request.headers['x-webhook-timestamp'] + request.rawBody
      const secretKey = <client secret>;
      let generatedSignature = crypto.createHmac('sha256', secretKey).update(body).digest("base64");
      const signature = request.headers['x-webhook-signature']
      if(generatedSignature === signature) {
          let jsonObject = JSON.parse(rawBody)
          return jsonObject
      }
      throw new Error("Generated signature and received signature did not match.");
  }
  ```

  ```go golang theme={"dark"}
  func VerifySignature(expectedSig string, ts string, body string) (string, error) {
          clientSecret := "<client-secret>"
  	signatureString := ts + rawBody
  	hmacInstance := hmac.New(sha256.New, []byte(*clientSecret))
  	hmacInstance.Write([]byte(signatureString))
  	bytesData := hmacInstance.Sum(nil)
  	generatedSignature := base64.StdEncoding.EncodeToString(bytesData)
  	if generatedSignature == expectedSig {
  		var object interface{}
  		err := json.Unmarshal([]byte(rawBody), &object)
  		if err != nil {
  			return nil, errors.New("something went wrong when unmarshalling raw body")
  		}
  		if objectAsMapInterface, ok := object.(map[string]interface{}); ok {
  			if webhookType, ok := objectAsMapInterface["type"].(string); ok {
  				return "signatures match", nil
  			}
  		}
  		return "", nil
  	}
  	return nil, errors.New("generated signature and received signature did not match")
  }

  timestamp := c.Request().Header.Get("x-webhook-timestamp")
  body, _ := ioutil.ReadAll(c.Request().Body)
  rawBody := string(body)
  signature := c.Request().Header.Get("x-webhook-signature")

  VerifySignature(signature, timestamp, rawBody)
  ```

  ```php PHP theme={"dark"}
  function computeSignature($ts, $rawBody){
      $rawBody = file_get_contents('php://input');
      $timestamp = getallheaders()['x-webhook-timestamp'];
      $signature = getallheaders()['x-webhook-signature'];

      $body = $timestamp . $rawBody;
      $secretKey = "<client-secret>";
      $genSignature = hash_hmac('sha256', $body, $secretKey, true);
      $genSignatureBase64 = base64_encode($genSignature);
      if($genSignatureBase64 == $signature) {
          $jsonResponse = json_decode($rawBody);
          return $jsonResponse;
      }
      throw new Exception("Generated signature and received signature did not match.");
  }
  ```

  ```java Java theme={"dark"}
  public Object generateSignature() {
    try {
        String data = headers.get("x-webhook-timestamp") + rawBody;
        String secretKey = "<client-secret>";
        Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
        SecretKeySpec secret_key_spec = new SecretKeySpec(secretKey.getBytes(), "HmacSHA256");
        sha256_HMAC.init(secret_key_spec);
        String computed_signature = Base64.getEncoder().encodeToString(sha256_HMAC.doFinal(data.getBytes()));
        String signature = headers.get("x-webhook-signature")
        if(computed_signature.equals(signature)) {
          Gson g = new Gson();
          Object response = g.fromJson(rawBody, Object.class);
          return response;
        }
        throw new Exception("Generated signature and received signature did not match.");
    } catch (Exception e) {
      throw e;
    }
  }
  ```

  ```python Python theme={"dark"}
  import base64
  import hashlib
  import hmac

  def generateSignature():
      raw_body = request.data
      timestamp = request.headers['x-webhook-timestamp']
      signature = request.headers['x-webhook-signature']
      signatureData = timestamp+rawBody
      message = bytes(signatureData, 'utf-8')
      secretkey=bytes("<client-signature>",'utf-8')
      generatedSignature = base64.b64encode(hmac.new(secretkey, message, digestmod=hashlib.sha256).digest())
      computed_signature = str(generatedSignature, encoding='utf8')
      if computed_signature == signature:
          json_response = json.loads(rawBody)
          return json_response
      raise Exception("Generated signature and received signature did not match.")
  ```
</CodeGroup>

### Webhook migration

Webhook endpoints have a specific API version set, for example, `2023-08-01`. To migrate from an older version to a newer version, follow these steps:

<Steps>
  <Step title="Add webhook for new version">
    Create a new webhook endpoint with the new URL and new version. Subscribe to
    the events you want to consume.
  </Step>

  <Step title="Update your code to return 200 for new webhooks">
    Update your event processing code and return a 200 response to prevent
    delivery retries. Next, enable the new webhook endpoint that you created in
    the previous step. At this point, every event is sent twice: once with the
    old API version and once with the new one.
  </Step>

  <Step title="Update your webhook code to process events for the new endpoint">
    Update your code to ensure you can process the version of your new webhook
    endpoint. Make sure you read the changelog and handle any breaking changes.
  </Step>

  <Step title="Disable old webhook endpoint">
    If events aren’t being correctly handled by your new code, first temporarily
    disable the new webhook endpoint. After monitoring for some time, you can
    permanently delete the old webhook endpoint.
  </Step>
</Steps>

<snippet>snippets/related-topics-loader.mdx</snippet>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/payments/online/webhooks/security-checklist">Webhook Security Checklist</a></li>
    <li><a href="/docs/api-reference/payments/latest/payments/webhooks">Payment Webhooks</a></li>
    <li><a href="/docs/api-reference/payments/latest/refunds/webhooks">Refund Webhooks</a></li>
    <li><a href="/docs/api-reference/payments/latest/token-vault/webhooks">Token Vault Webhooks</a></li>
    <li><a href="/docs/api-reference/payments/latest/payment-links/webhooks">Payment Link Webhooks</a></li>
  </ul>
</div>


# Webhook Security Checklist
Source: https://www.cashfree.com/docs/payments/online/webhooks/security-checklist

Secure your Cashfree webhook integration with HTTPS endpoints, IP whitelisting, signature verification, replay protection, and idempotent handlers.

Secure webhook integration requires multiple layers of protection to safeguard your systems from unauthorised access and data tampering. This guide outlines the recommended security measures for your webhook endpoints.

The following table summarises the security controls and their implementation priority:

| Security control | Priority | Description |
| - | - | - |
| [Public endpoint URL](#public-endpoint-url) | Mandatory | Ensure your endpoint is publicly accessible over HTTPS. |
| [IP whitelisting](#ip-whitelisting) | Highly recommended | Restrict traffic to Cashfree's IP ranges. |
| [Signature verification](#signature-verification) | Highly recommended | Verify HMAC signature for each request. |
| [Secure Sockets Layer (SSL) whitelisting](#ssl-whitelisting) | Optional | Configure mutual TLS for enhanced security. |
| [Authentication validation](#authentication-validation) | Optional | Add custom authentication for additional protection. |

## Public endpoint URL

Your webhook endpoint must be publicly accessible over the internet for Cashfree to deliver notifications. Use this as your foundation and apply the security controls described in the following sections to protect the integration.

<Note>
  Ensure your endpoint URL uses HTTPS to encrypt data during transmission.
</Note>

For instructions on adding and configuring webhook endpoints, refer to [Webhook configuration](/docs/payments/online/webhooks/configure).

## IP whitelisting

Restrict inbound traffic to accept requests only from Cashfree's known IP ranges. This control ensures your endpoint receives webhooks exclusively from legitimate Cashfree sources.

To configure IP whitelisting, complete the following steps:

1. Allow inbound traffic from the IP addresses listed below.
2. Configure your firewall rules to allow requests only from these IP ranges.
3. Block all other inbound traffic to your webhook endpoint.

Whitelist the following IP addresses on port 443:

**Production**

* 52.66.101.190
* 3.109.102.144
* 18.60.134.245
* 18.60.183.142

**Test/Sandbox (UAT)**

* 52.66.25.127
* 15.206.45.168

<Tip>
  Cashfree may update its IP ranges periodically. Monitor the documentation for changes and update your firewall rules accordingly.
</Tip>

## Signature verification

All webhook notifications include a cryptographic signature using HMAC-based validation. Verify this signature to confirm the authenticity and integrity of each request.

To implement signature verification, follow these guidelines:

* Serve your webhook endpoint over **HTTPS** to protect data during transmission.
* Extract the signature from the webhook request headers.
* Verify the signature against the raw request body using your secret key.
* Receive the payload as **raw data** to prevent modifications before verification.

<Tip>
  For partner webhooks, use the partner API key.
</Tip>

### Required headers

Validate the following mandatory headers in each webhook request:

| Header | Description |
| - | - |
| `x-webhook-signature` | The cryptographic signature for payload verification. |
| `x-webhook-timestamp` | The timestamp when the webhook was generated. |
| `x-webhook-version` | The API version of the webhook payload. |

<Info>
  For detailed implementation examples with SDK and manual verification code samples, refer to [Webhook signature verification](/docs/payments/online/webhooks/signature-verification).
</Info>

## SSL whitelisting

For enhanced transport-level security, configure mutual TLS (mTLS) authentication between your systems and Cashfree.

To enable SSL whitelisting, you can:

* Provide your SSL certificate to Cashfree for addition to their trusted certificate sources.
* Add Cashfree's certificate to your system's trusted certificates.

This configuration ensures only mutually authenticated communication occurs between your systems and Cashfree.

<Note>
  SSL whitelisting is an optional security layer. Contact [Cashfree support](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) to configure mutual TLS authentication for your account.
</Note>

## Authentication validation

If your endpoint requires custom authentication, configure Cashfree to include the necessary credentials in webhook requests.

Cashfree supports the following authentication methods:

* **Basic authentication**: Username and password credentials
* **Bearer tokens**: Token-based authentication
* **Custom headers**: Application-specific authentication parameters

To configure authentication for webhooks:

1. Share the required authentication parameters with Cashfree.
2. Implement server-side validation to verify the authentication fields in request headers.
3. Reject requests that fail authentication checks.

For more information on API authentication methods, refer to [Authentication](/docs/api-reference/authentication).

<Tip>
  Implement signature verification at minimum to prevent payload manipulation through man-in-the-middle attacks.
</Tip>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/payments/online/webhooks/overview">Webhooks overview</a></li>
    <li><a href="/docs/payments/online/webhooks/configure">Webhook configuration</a></li>
    <li><a href="/docs/payments/online/webhooks/signature-verification">Signature verification</a></li>
    <li><a href="/docs/api-reference/authentication">API authentication</a></li>
  </ul>
</div>


# Webhook Signature Verification
Source: https://www.cashfree.com/docs/payments/online/webhooks/signature-verification

Verify Cashfree webhook signatures with HMAC on the raw payload to confirm authenticity, block fraudulent notifications, and protect live payment flows.

Verify webhook signatures to ensure payloads from Cashfree haven't been tampered with. This security measure prevents fraudulent notifications and protects your application from malicious attacks.

**Essential for production environments**: all merchants processing live payments, subscriptions, or marketplace transactions must implement signature verification to maintain security and prevent financial losses.

<Warning>
  Cashfree generates the webhook signature based on the raw payload, not the parsed payload. For an example of accessing the raw body in a JavaScript framework, see the [NestJS raw-body documentation](https://docs.nestjs.com/faq/raw-body). Even minor changes to the payload structure or parameter sequence result in a signature mismatch. Use the exact raw webhook body as received at your server, without parsing, re-serialisation, formatting, or modification.
</Warning>

Use the signature to verify that the request hasn't been tampered with. You need your Cashfree PG secret key and the payload to verify the signature.

<Tip>
  For partner webhooks, use the partner API key.
</Tip>

* The timestamp is present in the header `x-webhook-timestamp`.
* The actual signature is present in the header `x-webhook-signature`.

```bash signature-verification theme={"dark"}
timestamp := 1617695238078;
signedPayload := $timestamp.$payload;
expectedSignature := Base64Encode(HMACSHA256($signedPayload, $merchantSecretKey));
```

Cashfree recommends verifying webhook signatures to protect against payload manipulation.

You can use the [Webhook Verification tool in Dev Studio](https://www.cashfree.com/devstudio/preview/pg/tools/webhookVerification) to manually verify whether a payload and signature are valid before implementing verification in your code.

## SDK verification (built-in approach)

<CodeGroup>
  ```javascript Node (express) theme={"dark"}
  var express = require('express')
  const { Cashfree, CFEnvironment } = require("cashfree-pg");

  var app = express()

  const cashfree = new Cashfree(
  CFEnvironment.SANDBOX,
  "{Client ID}",
  "{Client Secret Key}"
  );

  app.post('/webhook', function (req, res) {
  try {
  cashfree.PGVerifyWebhookSignature(req.headers["x-webhook-signature"], req.rawBody, req.headers["x-webhook-timestamp"])
  } catch (err) {
  console.log(err.message)
  }
  })

  ```

  ```go golang theme={"dark"}
  import (
    cashfree "github.com/cashfree/cashfree-pg/v4"
  )

  // Route
  e.POST("/webhook", _this.Webhook)

  // Controller
  func (_this *WebhookRoute) Webhook(c echo.Context) error {
    	clientId := "<x-client-id>"
  		clientSecret := "<x-client-secret>"
  		cashfree.XClientId = &clientId
  		cashfree.XClientSecret = &clientSecret
  		cashfree.XEnvironment = cashfree.SANDBOX

      signature := c.Request().Header.Get("x-webhook-signature")
      timestamp := c.Request().Header.Get("x-webhook-timestamp")

      body, _ := ioutil.ReadAll(c.Request().Body)
      rawBody := string(body)
      webhookEvent, err := cashfree.PGVerifyWebhookSignature(signature, rawBody, timestamp)
      if err != nil {
  		fmt.Println(err.Error())
  	} else {
  		fmt.Println(webhookEvent.Object)
  	}
  }
  ```

  ```php PHP theme={"dark"}
  <?php

  $inputJSON = file_get_contents('php://input');

  $expectedSig = getallheaders()['x-webhook-signature'];
  $ts = getallheaders()['x-webhook-timestamp'];

  if(!isset($expectedSig) || !isset($ts)){
      echo "Bad Request";
      die();
  }

  \Cashfree\Cashfree::$XClientId = "<x-client-id>";
  \Cashfree\Cashfree::$XClientSecret = "<x-client-secret>";
  $cashfree = new \Cashfree\Cashfree();

  try {
   $response =  cashfree->PGVerifyWebhookSignature($expectedSig, $inputJSON, $ts);
  } catch(Exception $e) {
    // Error if signature verification fails
  }
  ?>
  ```

  ```python Python theme={"dark"}
  from cashfree_pg.api_client import Cashfree

  @app.route('/webhook', methods = ['POST'])
  def disp():
  		# Get the raw body from the request
      raw_body = request.data

      # Decode the raw body bytes into a string
      decoded_body = raw_body.decode('utf-8')

      #verify_signature
      timestamp = request.headers['x-webhook-timestamp']
      signature = request.headers['x-webhook-signature']

  		cashfree = Cashfree()
  		cashfree.XClientId = "<app_id>"
  		cashfree.XClientSecret = "<secret_key>"
  		try:
  			cashfreeWebhookResponse = cashfree.PGVerifyWebhookSignature(signature, decoded_body, timestamp)
  		except:
  			# If Signature mis-match
  ```

  ```java Java theme={"dark"}
  import com.cashfree.*;

  @PostMapping("/my-endpoint")
  public String handlePost(HttpServletRequest request) throws IOException {
      Cashfree.XClientId = "<x-client-id>";
  		Cashfree.XClientSecret = "<x-client-secret>";
  		Cashfree.XEnvironment = Cashfree.SANDBOX;

    	StringBuilder stringBuilder = new StringBuilder();
      BufferedReader bufferedReader = null;

      try {
        bufferedReader = request.getReader();
        String line;
        while ((line = bufferedReader.readLine()) != null) {
                stringBuilder.append(line).append('\n');
        }


        String rawBody = stringBuilder.toString();
        String signature = request.getHeader("x-webhook-signature");
        String timestamp = request.getHeader("x-webhook-timestamp");

        Cashfree cashfree = new Cashfree();
        PGWebhookEvent webhook = cashfree.PGVerifyWebhookSignature(signature, rawBody, timestamp);

      } catch (Exception e) {
              // Error if verification fails
      } finally {
           if (bufferedReader != null) {
              bufferedReader.close();
  		}
  	}

  }
  ```

  ```csharp csharp theme={"dark"}
  using cashfree_pg.Client;
  using cashfree_pg.Model;


  		[Route("api/[controller]")]
      [ApiController]
      public class YourController : ControllerBase
      {
          [HttpPost]
          public async Task<IActionResult> Post()
          {
              // Read the raw body of the POST request
              using (StreamReader reader = new StreamReader(Request.Body, Encoding.UTF8))
              {
                  string requestBody = await reader.ReadToEndAsync();
                  var headers = Request.Headers;
                  var signature = headers["x-webhook-signature"];
                  var timestamp = headers["x-webhook-timestamp"];

                  Cashfree.XClientId = "<x-client-id>";
                  Cashfree.XClientSecret = "<x-client-secret>";
                  Cashfree.XEnvironment = Cashfree.SANDBOX;
  								var cashfree = new Cashfree();

                  try {
                  var response = cashfree.PGVerifyWebhookSignature(signature, requestBody, timestamp);
                  } catch(Exception e) {
                  // Error if signature mis matches
                  }
              }
          }
      }
  ```
</CodeGroup>

## Manual verification (custom approach)

<CodeGroup>
  ```javascript Node (Express) theme={"dark"}
  function verify(ts, request){
      const body = request.headers['x-webhook-timestamp'] + request.rawBody
      const secretKey = <client secret>;
      let generatedSignature = crypto.createHmac('sha256', secretKey).update(body).digest("base64");
      const signature = request.headers['x-webhook-signature']
      if(generatedSignature === signature) {
          let jsonObject = JSON.parse(rawBody)
          return jsonObject
      }
      throw new Error("Generated signature and received signature did not match.");
  }
  ```

  ```go golang theme={"dark"}
  func VerifySignature(expectedSig string, ts string, body string) (string, error) {
          clientSecret := "<client-secret>"
  	signatureString := ts + rawBody
  	hmacInstance := hmac.New(sha256.New, []byte(*clientSecret))
  	hmacInstance.Write([]byte(signatureString))
  	bytesData := hmacInstance.Sum(nil)
  	generatedSignature := base64.StdEncoding.EncodeToString(bytesData)
  	if generatedSignature == expectedSig {
  		var object interface{}
  		err := json.Unmarshal([]byte(rawBody), &object)
  		if err != nil {
  			return nil, errors.New("something went wrong when unmarshalling raw body")
  		}
  		if objectAsMapInterface, ok := object.(map[string]interface{}); ok {
  			if webhookType, ok := objectAsMapInterface["type"].(string); ok {
  				return "signatures match", nil
  			}
  		}
  		return "", nil
  	}
  	return nil, errors.New("generated signature and received signature did not match")
  }

  timestamp := c.Request().Header.Get("x-webhook-timestamp")
  body, _ := ioutil.ReadAll(c.Request().Body)
  rawBody := string(body)
  signature := c.Request().Header.Get("x-webhook-signature")

  VerifySignature(signature, timestamp, rawBody)
  ```

  ```php PHP theme={"dark"}
  function computeSignature($ts, $rawBody){
      $rawBody = file_get_contents('php://input');
      $timestamp = getallheaders()['x-webhook-timestamp'];
      $signature = getallheaders()['x-webhook-signature'];

      $body = $timestamp . $rawBody;
      $secretKey = "<client-secret>";
      $genSignature = hash_hmac('sha256', $body, $secretKey, true);
      $genSignatureBase64 = base64_encode($genSignature);
      if($genSignatureBase64 == $signature) {
          $jsonResponse = json_decode($rawBody);
          return $jsonResponse;
      }
      throw new Exception("Generated signature and received signature did not match.");
  }
  ```

  ```java Java theme={"dark"}
  public Object generateSignature() {
    try {
        String data = headers.get("x-webhook-timestamp") + rawBody;
        String secretKey = "<client-secret>";
        Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
        SecretKeySpec secret_key_spec = new SecretKeySpec(secretKey.getBytes(), "HmacSHA256");
        sha256_HMAC.init(secret_key_spec);
        String computed_signature = Base64.getEncoder().encodeToString(sha256_HMAC.doFinal(data.getBytes()));
        String signature = headers.get("x-webhook-signature")
        if(computed_signature.equals(signature)) {
          Gson g = new Gson();
          Object response = g.fromJson(rawBody, Object.class);
          return response;
        }
        throw new Exception("Generated signature and received signature did not match.");
    } catch (Exception e) {
      throw e;
    }
  }
  ```

  ```python Python theme={"dark"}
  import base64
  import hashlib
  import hmac

  def generateSignature():
      raw_body = request.data
      timestamp = request.headers['x-webhook-timestamp']
      signature = request.headers['x-webhook-signature']
      signatureData = timestamp+rawBody
      message = bytes(signatureData, 'utf-8')
      secretkey=bytes("<client-signature>",'utf-8')
      generatedSignature = base64.b64encode(hmac.new(secretkey, message, digestmod=hashlib.sha256).digest())
      computed_signature = str(generatedSignature, encoding='utf8')
      if computed_signature == signature:
          json_response = json.loads(rawBody)
          return json_response
      raise Exception("Generated signature and received signature did not match.")
  ```
</CodeGroup>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/payments/online/webhooks/security-checklist">Webhook Security Checklist</a></li>
    <li><a href="/docs/payments/online/webhooks/overview">Webhooks Overview</a></li>
    <li><a href="/docs/payments/online/webhooks/configure">Configure Webhooks</a></li>
    <li><a href="/docs/api-reference/payments/latest/payments/webhooks">Payment Webhooks API</a></li>
  </ul>
</div>


# Troubleshooting
Source: https://www.cashfree.com/docs/payments/online/webhooks/troubleshooting

Troubleshoot Cashfree webhook delivery issues like missing triggers, blocked endpoints, and configuration errors using the Merchant Dashboard logs and resends.

## Webhook did not trigger

If a webhook does not trigger for the specified endpoint:

1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).

2. Navigate to **Developer > Webhooks** under **Payment Gateway**, and select the **Logs** tab to check for failures and take necessary action.
   Common reasons for webhook failure are:
   * The endpoint returns a **500 error** or does not respond.
   * The required event is not configured in the webhook settings.

3. Select **Batch Resend** to resend missed webhook events.

4. Select the **Batch Source** and enter **Entity IDs** in the **Batch Resend** modal.

5. Select **Resend**. Refer to the screenshot below:

<img />

## Cannot add a payment gateway webhook

To add a webhook endpoint URL:

1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).

2. Navigate to **Developer > Webhooks** under **Payment Gateway**, and select **Add Webhook Endpoint** in the **Configuration** tab.

3. Add the following details in the **Add Webhook Endpoint** modal:

   * **Endpoint Details**: Enter the endpoint URL for the webhook and select the latest webhook version from the drop-down list.

   <Note>
     **Note**:
     When you add the endpoint URL, Cashfree sends a test `POST` request to check if it is valid and responsive. If the endpoint does not respond, select **Continue** and manually select the required events.
   </Note>

   * **Add Policy**: Customise the retry policy and select the webhook events you want to subscribe to.
   * **Summary**: Review and confirm your selections.

4. Select **Save** to complete the setup. Refer to the screenshot below:

<img />

## Receiving duplicate webhook events

If you receive duplicate webhook events, check for the following issues:

* **Multiple subscriptions to the same event**
  * You may have subscribed to the same event multiple times across different webhook versions or for different URLs.
  * Check each **URL Configuration** and remove duplicate subscriptions.

* **Retries due to downtime**
  * If **Cashfree** or your server experiences downtime, Cashfree retries webhook deliveries to ensure event completion.

* **Prevent duplicate processing**
  * Validate the **x-idempotency-header** in the webhook header.
    * This header contains a unique hashed value for each webhook payload.
    * Webhook versions from **2025-01-01** support this feature.
    * To upgrade, see the [Webhook Migration](/docs/payments/online/webhooks/overview#webhook-migration) section.

## Configure webhooks for non-payment gateway products

To configure webhooks for products such as **Payouts**, **Subscriptions**, **Payments**, **Payment Links**, or **Secure ID**, go to the respective product webhook section on the Merchant Dashboard and add the required webhook endpoint URL.

<img />

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/payments/online/webhooks/security-checklist">Webhook Security Checklist</a></li>
    <li><a href="/docs/payments/online/webhooks/overview">Webhooks Overview</a></li>
    <li><a href="/docs/payments/online/webhooks/configure">Webhook Configuration</a></li>
  </ul>
</div>


# Webhook Idempotency
Source: https://www.cashfree.com/docs/payments/online/webhooks/webhook-indempotency

Implement Cashfree webhook idempotency to safely handle duplicate events, multiple payment attempts per order, and terminal statuses without double processing.

When integrating with Cashfree Payment Gateway, it's crucial to implement webhook idempotency to ensure your application processes only final and unique payment events. Below are the core principles and practices to follow.

## Key concepts

The following are the key concepts:

* **Multiple payment attempts per order\_id**: For a single `order_id`, Cashfree allows multiple payment attempts until one succeeds. Each attempt generates a unique `cf_payment_id`.

* **Unique payment\_id per attempt**: Every retry—whether triggered by the user or automatically—will have a distinct `cf_payment_id` but the same `order_id`.

* **Terminal status**: Only consider webhook events where `payment_status = SUCCESS` as the final confirmation of payment for an order.

<Note> Statuses such as `FAILED`, `NOT_ATTEMPTED`, or `PENDING` are transitional and should not be treated as final.</Note>

<Frame>
  <img />
</Frame>

## Best practices

The following are the recommended best practices:

* **De-duplicate using cf\_payment\_id**: Track `cf_payment_id` in your database and process each payment only once, regardless of how many webhook retries you receive.

* **Order-level validation**: Update the order status **only when** you receive a webhook that meets **all** of the following conditions:
  * The `order_id` matches the one you created.
  * The `payment_status` is `SUCCESS`.
  * The order has **not already** been marked as paid.

* **Handle retried payments**: Users may retry failed payments. As a result, you may receive multiple webhook events in the sequence: `FAILED → PENDING → SUCCESS`.\
  Implement logic to update the order status only upon receiving the `SUCCESS` webhook.

* **Ignore duplicate FAILED webhooks**: Webhook events with a `FAILED` status may be sent multiple times. Do not trigger any final actions for these statuses unless you are tracking them for logging or metrics.

* **Store payment attempts**: Keep a log of all `cf_payment_id` for a given `order_id` to support reporting, reconciliation, or dispute management.

* **Use HTTPS endpoints**: Your webhook URL must be publicly reachable from Cashfree. Production endpoints must use HTTPS.

* **Respond immediately**: Your endpoint must return a successful HTTP 200 response immediately after receiving the webhook payload.

* **Verify signatures**: Verify the webhook signature using the `x-webhook-signature` header before processing the payload to authenticate the request. For implementation details, see [Webhook signature verification](/docs/payments/online/webhooks/signature-verification).

<Note>
  Do not mark the order as PAID on receiving `FAILED` or `PENDING` statuses.
  Always wait for a `SUCCESS` webhook before finalising the payment status.
</Note>

## Webhooks as the source of truth

Cashfree webhooks provide server-to-server communication. This means your server receives the payment status even if the customer closes the browser or application before being redirected back to your site. Webhooks are the recommended source of truth for your internal systems. You can monitor webhook delivery and retry history in the **Logs** section. See [Webhook configuration](/docs/payments/online/webhooks/configure).


# Overview
Source: https://www.cashfree.com/docs/payments/other-products

Explore Cashfree's specialised products beyond the core gateway: Easy Split, international collections, BBPS billing, and reconciliation tools.

Beyond our core Payment Gateway, Cashfree offers specialised payment products designed to address specific business needs across different industries and use cases. Whether you're running a marketplace that needs to split payments between vendors, expanding internationally, or looking to streamline payment reconciliation, we've purpose-built solutions.

These products extend the capabilities of standard payment processing by solving complex challenges such as multi-party settlements, offline card acceptance, regulated bill payments, automated reconciliation, and flexible fund blocking. Each solution integrates seamlessly with your existing systems while providing the robust infrastructure, compliance, and support that modern businesses require.

## Available products

<CardGroup>
  <Card title="Easy Split" icon="split" href="/docs/payments/split/overview">
    Automatically split payments between multiple vendors for marketplaces and platforms.
  </Card>

  <Card title="softPOS" icon="mobile" href="/docs/payments/softpos/introduction">
    Accept contactless card payments using smartphones without additional hardware.
  </Card>

  <Card title="BBPS Billers" icon="file-invoice" href="/docs/payments/bbps-billers/overview">
    Accept utility bills, subscriptions, and recurring payments through BBPS.
  </Card>

  <Card title="Virtual Bank Accounts" icon="building-columns" href="/docs/payments/vba/overview">
    Create unique virtual account numbers for automated payment reconciliation.
  </Card>

  <Card title="UPI Reserve Pay" icon="wallet" href="/docs/payments/upi-reserve-pay/reserve-pay">
    Block funds once and debit multiple times for EMIs, subscriptions, and usage-based billing.
  </Card>
</CardGroup>

## Need help choosing?

Not sure which product fits your use case? Consider these factors:

* **Marketplace or platform?** → Easy Split for vendor payouts
* **Physical store or mobile sales?** → softPOS for card acceptance
* **International customers?** → Global Collections for cross-border payments
* **Utility or bill payments?** → BBPS Billers for regulated bill collection
* **Large customer base with bank transfers?** → Virtual Bank Accounts for auto-reconciliation
* **Recurring charges with flexible amounts?** → UPI Reserve Pay for fund blocking

Contact our [sales team](https://www.cashfree.com/contact-sales/) for personalised recommendations.


# Overview
Source: https://www.cashfree.com/docs/payments/overview

Compare Cashfree Payment Gateway integration options, including hosted checkout, drop-in JS, mobile SDKs, server-side APIs, and no-code payment links and forms.

<div>
  <iframe title="YouTube video player" />
</div>

Cashfree Payment Gateway offers multiple integration options to suit different business needs and technical capabilities. Choose a hosted checkout solution, customise your checkout with web elements, or integrate payments into mobile applications.

<Tip>Install [Cashfree Agent Skills](/docs/tools-ai/cashfree-agent-skills) to bring Cashfree product knowledge into your AI coding assistant (Claude Code, Cursor, VS Code Copilot, Gemini CLI, and more) to answer integration questions and generate accurate code without leaving your editor.</Tip>

**Choose the integration method that best fits your requirements:**

<CardGroup>
  <Card>
    <h2>Web integrations</h2>

    <ul>
      <li>
        <div>
          <svg>
            <path />

            <path />
          </svg>
        </div>

        <div>
          <div>[Web checkout integration](/docs/payments/online/web/redirect)</div>
          <div>Cashfree hosted checkout</div>
        </div>
      </li>

      <li>
        <div>
          <svg>
            <path />

            <path />

            <path />

            <path />
          </svg>
        </div>

        <div>
          <div>[Web element integration](/docs/payments/online/element/overview)</div>
          <div>Merchant hosted checkout</div>
        </div>
      </li>
    </ul>
  </Card>

  <Card>
    <h2>App checkout integrations</h2>

    <ul>
      <li>
        <div>
          <svg>
            <path />
          </svg>
        </div>

        <div>
          <div>[Android integration](/docs/payments/online/mobile/android)</div>
        </div>
      </li>

      <li>
        <div>
          <svg>
            <path />
          </svg>
        </div>

        <div>
          <div>[iOS integration](/docs/payments/online/mobile/ios)</div>
        </div>
      </li>

      <li>
        <div>
          <svg>
            <path />

            <path />

            <path />

            <path />
          </svg>
        </div>

        <div>
          <div>[React Native integration](/docs/payments/online/mobile/react-native)</div>
        </div>
      </li>

      <li>
        <div>
          <svg>
            <path />
          </svg>
        </div>

        <div>
          <div>[Flutter integration](/docs/payments/online/mobile/flutter)</div>
        </div>
      </li>
    </ul>
  </Card>

  <Card>
    <h2>Plugins</h2>

    <ul>
      <li>
        <div>
          <svg>
            <path />
          </svg>
        </div>

        <div>
          <div>[Shopify](/docs/payments/shopify/overview)</div>
        </div>
      </li>

      <li>
        <div>
          <svg>
            <path />

            <path />
          </svg>
        </div>

        <div>
          <div>[Woocommerce](/docs/payments/checkout/woocommerce)</div>
        </div>
      </li>

      <li>
        <div>
          <svg>
            <path />
          </svg>
        </div>

        <div>
          <div>[Explore all plugins](/docs/payments/plugins/overview)</div>
        </div>
      </li>
    </ul>
  </Card>

  <Card>
    <h2>No-code solutions</h2>

    <ul>
      <li>
        <div>
          <svg>
            <path />
          </svg>
        </div>

        <div>
          <div>[Payment links](/docs/payments/no-code/payment-link)</div>
        </div>
      </li>

      <li>
        <div>
          <svg>
            <path />
          </svg>
        </div>

        <div>
          <div>[Payment forms](/docs/payments/no-code/payment-forms/overview)</div>
        </div>
      </li>
    </ul>
  </Card>
</CardGroup>

<div>
  <p>Affiliate partner program</p>

  <p>As a developer building payment experiences for your clients, you can earn additional income while providing them with industry-leading payment solutions.</p>

  <p>Join the <a href="https://partner.cashfree.com/partner-ui/authentication/signup?source-action=Affiliate%20Program%20LP&action=Sign%20Up&button-id=StartNow_CashfreeAffiliatePartnerProgram">Cashfree affiliate partner program</a> and get rewarded every time your clients use Cashfree.</p>

  <p>**What you get:**</p>

  <ul>
    <li>Earn up to 0.25% commission on every transaction.</li>
    <li>Become a trusted fintech partner for your clients.</li>
    <li>Access to a dedicated partner manager for expert support.</li>
  </ul>

  <p>**What your clients get:**</p>

  <ul>
    <li>Instant activation and go live in minutes.</li>
    <li>Industry-best success rate across all payment modes.</li>
    <li>Effortless acceptance of international payments in 140+ currencies.</li>
  </ul>

  <p>Get started today. <a href="https://partner.cashfree.com/partner-ui/authentication/signup?source-action=Affiliate%20Program%20LP&action=Sign%20Up&button-id=StartNow_BecomeAPartner">Become a partner now</a>.</p>
</div>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/payments/latest/overview">Payment Gateway API Overview</a></li>
    <li><a href="/docs/payments/general-faqs">General FAQs</a></li>
  </ul>
</div>


# Magento Payment Plugin
Source: https://www.cashfree.com/docs/payments/plugins/magento

Add the Cashfree plugin to your Magento store to accept cards, UPI, netbanking, and wallets through the popular open-source ecommerce platform.

Magento is an open-source e-commerce platform and is one of the most popular open e-commerce systems in the network. It empowers thousands of retailers and brands with the best eCommerce platform. It allows a flexible shopping cart system and helps you maintain a great online store experience.

### Installation

To install the Magento 2.4+ version plugin,

1. [Download the latest zip file from the cashfree-magento releases page](https://github.com/cashfree/cashfree-magento/releases).
2. Extract the zip file and upload the files to Magento\
   **root/app/**
3. Run the below Magento commands:\
   **php bin/magento module:enable Cashfree\_Cfcheckout\
   bin/magento setup:upgrade**

<div>
  <iframe title="cashfree-magento" />
</div>

<Note>Read about [whitelisting your store url](/docs/payments/online/go-live/whitelist) before you can accept payments on your store.</Note>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="https://github.com/cashfree/cashfree-magento/releases">Magento Plugin Download</a></li>
    <li><a href="/docs/payments/online/go-live/whitelist">Whitelist Store URL</a></li>
    <li><a href="/docs/payments/online/go-live/checklist">Go Live Checklist</a></li>
  </ul>
</div>


# Other E-Commerce Plugins
Source: https://www.cashfree.com/docs/payments/plugins/others

Connect Cashfree to other ecommerce platforms like OpenCart with official plugins that support multiple versions, popular payment methods, and refunds.

## Opencart

Cashfree supports 3 versions for OpenCart integration,

* **OpenCart version 3.0**
* **OpenCart version 2.3 and 2.1**

<Card href="https://github.com/cashfree/cashfree-opencart-kit">
  Download Cashfree's official Opencart plugin
</Card>

## OpenCart version 3.0

To add Cashfree Payment Gateway to your OpenCart account,

1. Download Cashfree's Plugin for Opencart Version 3.0.
2. Copy all files/folders in the Admin and Catalog folder to OpenCart installation directory.
3. Login to [OpenCart](https://www.opencart.com/).
4. In the OpenCart Dashboard, go to **Admin Panel** > **Extensions**. Select the extension type as **Payments**.
5. Click the edit button next to Cashfree in the screen.
6. Fill in the details in the configuration screen and save.
   <Info>
     End Points: **Production** - `https://api.cashfree.com` **Test** -
     `https://test.cashfree.com`
   </Info>

<Accordion title="Opencart Video">
  <iframe title="YouTube video player" />
</Accordion>

## Prestashop

Currently, we support the following PrestaShop versions:

* PrestaShop 1.7x
* PrestaShop 1.5x and 1.6x

To install the plugin

1. Log in to your PrestaShop Admin Dashboard and click **Modules** on the left side menu.
2. Click **Module Manager** > **upload a module**.
3. Select the module file to upload. Ensure the file format is as per the guidelines. On successful upload, a screen appears as shown below, and the module is successfully installed.
4. After successful installation, click **Configure** to set up the module configuration.
5. In the Configure screen:\
   a. Enter your Cashfree Payment Gateway **App Id** and **Secret Key**.\
   b. Select the **Test Mode** as **Yes** for **Test Environment** and **No** for **Production Environment**.\
   c. Select the **Success Order Status** as **Processing in progress**.
6. Click **Save** to save the module configuration. The **Configure** screen appears as shown below.

<img />

## StoreHippo

To add Cashfree Payment Gateway to your StoreHippo account,

1. Log in to your StoreHippo account and click **Settings** in the left navigation section.

2. In the **Settings** section, select **Payment methods**.

   <Accordion title="Settings - Payment Methods">
     <img />
   </Accordion>

3. In the **Payment methods** screen, click **Add New** to add a new payment gateway.

   <Accordion title="Add New Payment Method">
     <img />
   </Accordion>

4. In the **Payment methods / Add** screen, enter the following:

* In the **Name** field specify a name to represent the payment method. This will be visible to your customers.
* In the **Type** field, select **Payment Gateways**.
* In the **Settings** field, select **Cashfree**, and enter the App ID and Secret Key. To test the integration, you can use the test keys, to accept payments from customers, enter the production keys.\
  For more information on API Keys, see [Go-live checklist](/docs/payments/online/go-live/checklist).
* In the **Caption** field, you can enter details that must be displayed on the payments page for your customers.
* In the Image field, you can select a payment method logo.
* Select the **Enabled** checkbox to activate this payment method.

<Accordion title="Save Payment Method">
  <img />
</Accordion>

5. Click **Save** to add the new payment method.

The newly added Cashfree payment method will be displayed in the available Payment Methods section as shown below. Your customers can start making payments using this option.

<Accordion title="Cashfree Payment Method Added">
  <img />
</Accordion>

## WHMCS

WHMCS (Web Host Manager Complete Solution) is a web host billing and automation platform. WHMCS is the market-leading platform of choice for Web Hosting Providers and Domain Registrars to automate and manage their businesses.

Cashfree supports **WHMCS 7** and **WHMCS 8** versions for integration.

To add Cashfree Payment Gateway to your WHMCS account,

<Card href="https://github.com/cashfree/cashfree-whmcs/releases/tag/v2.2.2">
  Download Module
</Card>

1. Unzip the downloaded file and upload the contents of the repository to your WHMCS Installation directory.

2. Log into your site with the WHMCS administrator credentials. You can do this by adding /admin to the URL where you have installed WHMCS. For example, `www.example.com/whmcs/admin`.

3. In the WHMCS Admin Dashboard, go to **Setup** > **Payment Gateways** > **All Payment Gateways**, and select **Cashfree** from the list and activate it.

   <img />

4. Enter your Cashfree Payment Gateway **App Id** and **Secret Key**.

5. Click the checkbox if you want to enable test mode.

   <img />

6. Click **Save Changes**.

## ZenCommerce

To add Cashfree Payment Gateway to your Zencommerce account,

1. Log in to your Zencommerce account and click **Extras and Integrations** in the left navigation section.

2. Click **Applications** and select **Cashfree Payment Gateway**.

3. In the Cashfree Payment Gateway applications section, click **Install**.

4. In the Application Installation screen, click **Install**. After successful installation, a message **Application has been installed in your shop!** appears on the screen.

   <Accordion title="Install Application">
     <img />
   </Accordion>

5. Click **My Applications** in the **Extras and Integrations** section. A screen appears as shown below:

   <Accordion title="Installed Cashfree Payment Gateway Application">
     <img />
   </Accordion>

6. Click the application and then click **Settings** as shown below.

   <Accordion title="Settings">
     <img />
   </Accordion>

7. In the **Apply Configuration** screen, enter the **App ID** and **Client Secret** for your Cashfree account. Select Production or Test as the environment and click **Apply**.
   <Accordion title="Set Up Cashfree Payment Gateway">
     <img />
   </Accordion>

Customers can now start making payments using Cashfree Payment Gateway.

## Arastta

To add Cashfree Payment Gateway to your Zencommerce account,

<Card href="https://github.com/cashfree/arastta/releases">
  Download the **upload.zip file**
</Card>

1. Login to the Arastta admin dashboard and click **Extensions**.

2. Select **Payments** and click the upload extension icon in the **Payment** screen and upload the **upload.zip file** you downloaded in step 1.

   <Accordion title="Arastta Dashboard">
     <img />
   </Accordion>

3. Cashfree will be listed in the payment page as shown below:

   <Accordion title="Add Cashfree Extension">
     <img />
   </Accordion>

4. Click the edit icon to change the configuration.\
   a. **In General tab:**

   * Enter your Cashfree account **App ID**.
   * Enter your Cashfree account **Secret Key**.
   * In the **Sandbox Mode** option, select **Yes**, when you want to test the integration. Select\
     **No**, when you want to accept live payments.
   * Select the **Debug Mode** and **Sort Order** as per your requirements.
   * Change plugin **Status** to **Enabled**.

   <Accordion title="General Settings">
     <img />
   </Accordion>

   b. **In Order Status tab:**: Select order status for expired orders. - Select
   order status for failed orders. - Select order status for pending orders. - Select
   order status for processed orders.

   <Accordion title="Order Status Settings">
     <img />
   </Accordion>

5. Save the plugin settings. Your customers can start making payments using Cashfree Payment Gateway.

## CSCart

<Card href="https://github.com/cashfree/cashfree-cscart">
  Download Cashfree's official CS-Cart plugin
</Card>

To integrate,

1. Install the latest version of CS-Cart.\
   The file contains integration code for interaction with the Cashfree API and allows payment in CS-Cart seamlessly.
2. Execute 'install\_cashfree.sql' against CS-Cart database. The file is available in the root directory of this file. Change prefix if you have added during installation of CS-Cart. You can either use phpmyadmin to import SQL file directly or run SQL queries in your MySQL shell.
3. Upload the contents of the repo to your CS-Cart Installation directory (the content of the app folder must be uploaded to the app folder and the content of design should be uploaded to the design folder).

**Configuration**

1. Log into CS-Cart as administrator (`http://your.cscart.store.com/admin.php`).
2. Go to **Administration** > **Payment Methods**.
3. Click the **+** icon to add a new payment method.
4. Enter Name as **Cashfree**.
5. Select Cashfree from the list and template and select "cc\_outside.tpl".
6. Enter your Cashfree Payment Gateway **App Id** and **Secret Key**.
7. Select **Currency** from the dropdown.
8. Select Test or Production environment.
9. Click **Create** to save the configuration.

<Note>
  Read about [whitelisting your store url](/docs/payments/online/go-live/whitelist)
  before you can accept payments on your store.
</Note>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/payments/online/go-live/checklist">Go Live Checklist</a></li>
    <li><a href="/docs/payments/online/go-live/whitelist">Whitelist Store URL</a></li>
    <li><a href="https://github.com/cashfree/cashfree-opencart-kit">OpenCart GitHub</a></li>
    <li><a href="https://github.com/cashfree/cashfree-whmcs/releases/tag/v2.2.2">WHMCS Plugin</a></li>
    <li><a href="https://github.com/cashfree/cashfree-cscart">CS-Cart GitHub</a></li>
  </ul>
</div>


# E-Commerce Plugins
Source: https://www.cashfree.com/docs/payments/plugins/overview

Find the official Cashfree plugin for your ecommerce platform: WooCommerce, Magento, PrestaShop, OpenCart, WordPress, or Zoho, and start accepting payments.

Cashfree provides various plugins to easily integrate and get started with your website on different e-commerce platforms. All you have to do is install the plugin, enter your app Id and secret key.

Select the e-commerce platform that you're using or planning to use from the list below.

<CardGroup>
  <Card href="/docs/payments/shopify/overview">Shopify</Card>

  <Card href="/docs/payments/checkout/woocommerce">WooCommerce</Card>

  <Card href="/docs/payments/plugins/wix">WIX</Card>

  <Card href="/docs/payments/plugins/wordpress">Wordpress</Card>

  <Card href="/docs/payments/plugins/magento">Magento</Card>

  <Card href="/docs/payments/plugins/zoho">Zoho</Card>

  <Card href="/docs/payments/plugins/others#prestashop">Prestashop</Card>

  <Card href="/docs/payments/plugins/others#whmcs">WHMCS</Card>

  <Card href="/docs/payments/plugins/others#opencart">Opencart</Card>

  <Card href="/docs/payments/plugins/others#cscart">CSCart</Card>

  <Card href="/docs/payments/plugins/others#storehippo">StoreHippo</Card>

  <Card href="/docs/payments/plugins/others#zencommerce">ZenCommerce</Card>

  <Card href="/docs/payments/plugins/others#arastta">Arastta</Card>
</CardGroup>

<div>
  ### 💻 Quick dev-to-dev talk

  You clearly care about building better payment experiences for your clients, here's a quick tip: Earn additional income doing exactly what you’re doing now!

  Join the [Cashfree Affiliate Partner Program](https://partner.cashfree.com/partner-ui/authentication/signup?utm_source=dev%20docs\&utm_medium=dev%20doc\&utm_campaign=signup) and get rewarded every time your clients use Cashfree.

  What’s in it for you?

  * Earn up to 0.25% commission on every transaction
  * Be more than a dev - be the trusted fintech partner for your clients
  * Get a dedicated partner manager, your go-to expert

  What’s in it for your clients?

  * Instant activation, go live in minutes.
  * Industry-best success rate across all payment modes.
  * Effortlessly accept international payments in 140+ currencies

  Ready to push to prod? 👉 [Become a Partner now](https://partner.cashfree.com/partner-ui/authentication/signup?utm_source=dev%20docs\&utm_medium=dev%20doc\&utm_campaign=signup)
</div>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/authentication">API Keys and Authentication</a></li>
    <li><a href="/docs/payments/online/go-live/whitelist">Domain Whitelisting</a></li>
  </ul>
</div>


# Prestashop Payment Plugin
Source: https://www.cashfree.com/docs/payments/plugins/prestashop

Install the Cashfree plugin on supported PrestaShop versions to accept cards, UPI, netbanking, and wallets without custom integration work.

<Note>Read about [whitelisting your store url](/docs/payments/online/go-live/whitelist) before you can accept payments on your woocommerce store. </Note>

Currently, we support the following PrestaShop versions:

* [PrestaShop 1.7x](https://github.com/cashfree/cashfree-prestashop-kit/tree/master).
* [PrestaShop 1.5x and 1.6x](https://github.com/cashfree/cashfree-prestashop-kit/tree/master-1.5/1.6)

## To install the plugin

1. Log in to your PrestaShop Admin Dashboard and click **Modules** on the left side menu.
2. Click **Module Manager** > **upload a module**.
3. Select the module file to upload. Ensure the file format is as per the guidelines. On successful upload, a screen appears as shown below, and the module is successfully installed.
4. After successful installation, click **Configure** to set up the module configuration.
5. In the Configure screen:\
   a. Enter your Cashfree Payment Gateway **App Id** and **Secret Key**.\
   b. Select the **Test Mode** as **Yes** for\*\* Test Environment\*\* and **No** for **Production Environment**.\
   c. Select the **Success Order Status** as **Processing in progress**.
6. Click **Save** to save the module configuration. The **Configure** screen appears as shown below.

<img />

<Note>Read about [whitelisting your store url](/docs/payments/online/go-live/whitelist) before you can accept payments on your woocommerce store. </Note>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="https://github.com/cashfree/cashfree-prestashop-kit/tree/master">PrestaShop 1.7x Plugin</a></li>
    <li><a href="https://github.com/cashfree/cashfree-prestashop-kit/tree/master-1.5/1.6">PrestaShop 1.5x/1.6x Plugin</a></li>
    <li><a href="/docs/payments/online/go-live/whitelist">Whitelist Store URL</a></li>
    <li><a href="/docs/payments/online/go-live/checklist">Go Live Checklist</a></li>
  </ul>
</div>


# Wix Payment Plugin
Source: https://www.cashfree.com/docs/payments/plugins/wix

Add the Cashfree plugin to your Wix website to accept Indian payment methods like cards, UPI, netbanking, and wallets without writing any custom code.

Wix is a leading cloud-based development platform that empowers you to create, design, and run your business online. Integrate Wix with Cashfree Payment Gateway easily without any code and start accepting payments from customers.

All major payment methods such as debit card, credit card, UPI, net banking, wallets are supported to accept payments on Wix. This is one of the most important features of your Wix payment gateway in India.

<Warning>Note that WIX cannot be integrated in the test environment.</Warning>

### Steps to integrate Cashfree with Wix

To integrate Wix with Cashfree,

1. Log in to your Wix account and click **Settings**.

2. In the **Settings** page select **Accept Payments**.

3. In the Accept Payments screen, scroll down and click **See More Payment Options**.

4. Select Cashfree and click **Connect**.

5. Enter your **App ID** and **Secret Key** of your Cashfree Account. Follow the steps given in [this](/docs/api-reference/authentication#generate-api-keys) link to get API keys.

6. Click **Connect** to integrate Cashfree Payment with your Wix account.

Now, you can accept payments through your Wix payment gateway in India.

<img />

<Note>
  Read about [whitelisting your store url](/docs/payments/online/go-live/whitelist)
  before you can accept payments on your store.
</Note>

<div>
  <iframe title="cashfree-magento" />
</div>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/authentication#generate-api-keys">Generate API Keys</a></li>
    <li><a href="/docs/payments/online/go-live/whitelist">Whitelist Store URL</a></li>
    <li><a href="/docs/payments/online/go-live/checklist">Go Live Checklist</a></li>
  </ul>
</div>


# WooCommerce Payment Plugin
Source: https://www.cashfree.com/docs/payments/plugins/woocommerce

Add the Cashfree plugin to your WordPress WooCommerce store to accept debit cards, credit cards, UPI, netbanking, and wallet payments seamlessly.

<Note>Read about [whitelisting your store url](/docs/payments/online/go-live/whitelist) before you can accept payments on your woocommerce store. </Note>

WooCommerce is a customisable, open-source eCommerce platform built on WordPress. You can configure woo-commerce to best suit your store’s need. Integrate Woo-commerce with Cashfree to accept payments on the woo-commerce store via Cashfree Payment Gateway. All major payment methods such as debit card, credit card, UPI, net banking, wallets are supported to accept payments.

Click <a href="https://github.com/cashfree/cashfree-woocommerce/releases/tag/v4.7.5">here</a> to download latest Cashfree's official woocommerce plugin.

To install the plugin,

1. Log in to your Wordpress Admin Dashboard.

2. Search for the downloaded plugin, extract and copy this plugin in the plugin folder (/wp-content/plugins) of your website.

3. Activate plugin Cashfree from Wordpress Plugins Page.

4. Go to **Settings** in **WooCommerce**, click **Checkout** and select **Cashfree** in **Payment Gateways** section.

5. Select the checkbox against **Enable/Disable** field.

6. Enter your Cashfree Payment Gateway **App Id** and **Secret Key**.

7. Click on **Enable Cashfree sandbox** to enable sandbox if required.

8. Click on **Enable In Context** to use without redirection payment flow.

9. Click **Save Changes**.

<Note>If you see an "Authentication Failed" error message during integration, please clear the option "Enable Cashfree Sandbox" in the WooCommerce plugin Settings page.</Note>

<Note>The most common cause of an authentication failure on WooCommerce, even when the plugin is installed and active, is a mismatch between your API keys and the environment mode configured in the plugin. Go to **WooCommerce > Settings > Payments > Cashfree**. If **Enable Cashfree Sandbox** is checked, use your sandbox credentials from the Merchant Dashboard test environment; if it is unchecked, use your production API keys. Never mix sandbox keys with production mode, or vice versa. To locate or regenerate your API keys, see [Generate API keys](/docs/api-reference/authentication#generate-api-keys).</Note>

<div>
  <iframe title="YouTube video player" />
</div>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="https://github.com/cashfree/cashfree-woocommerce/releases/tag/v4.7.5">WooCommerce Plugin Download</a></li>
    <li><a href="/docs/payments/online/go-live/checklist">Go Live Checklist</a></li>
    <li><a href="/docs/payments/online/go-live/whitelist">Whitelist Store URL</a></li>
  </ul>
</div>


# WordPress
Source: https://www.cashfree.com/docs/payments/plugins/wordpress

Use the Cashfree WordPress plugin to embed a payment button on any WordPress page and accept cards, netbanking, UPI, and wallet payments without coding.

Cashfree's WordPress plugin allows you to easily accept payments from customers on your WordPress page by easily integrating the payment button. You can accept payments via debit card, credit card, net banking, UPI, or through any of our supported wallets.

To accept payments using Cashfree's Quick Button:

* Add a few custom variables and some markup to a page.
* Specify the amount, title, description and other custom details as page metadata.
* Write `[CFPB]` where you want the Pay With Cashfree button to be displayed. The plugin takes over and completes the payment after customers click the payment button.

## Configuration

1. Download Cashfree's [Quick Button plugin](https://github.com/cashfree/cashfree-quick-button).
2. Go to your WordPress site > Plugins > Add New.
3. Upload the plugin.

<img />

4. Select **Activate Plugin**.

<img />

5. Select **Settings**.

   <img />

6. In the **Edit Settings** screen, enter the **Title, App ID, Secret Key, Payment Mode** (Test/Prod) and the **Success Message**. Click Save Changes.
   <img />

## Add custom fields

1. In your WordPress site, open the page where you want the payment button to be displayed.

2. Click the more icon and select **Preferences**.

3. In the **Preferences** screen, enable the option **Custom fields**. You will now have the option to add custom fields to your WordPress page.

   <img />

4. Scroll down the page till you see the Custom fields section, and add the following three custom fields as metadata:

* **description**: include product description
* **orderAmount**: specify the order amount in INR
* **title**: specify the product name

<img />

5. Write `[CFPB]` in the content section where you want to display the `Pay With Cashfree` button.

<img />

6. Publish the page to see the **Pay with Cashfree** button. Customers can complete the payment by clicking the button on the page.

<img />

<Note>
  Read about [whitelisting your store url](/docs/payments/online/go-live/whitelist)
  before you can accept payments on your store.
</Note>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="https://github.com/cashfree/cashfree-quick-button">WordPress Quick Button Plugin</a></li>
    <li><a href="/docs/payments/online/go-live/whitelist">Whitelist Store URL</a></li>
    <li><a href="/docs/payments/online/go-live/checklist">Go Live Checklist</a></li>
  </ul>
</div>


# Zoho Payment Plugin
Source: https://www.cashfree.com/docs/payments/plugins/zoho

Add the Cashfree plugin to Zoho Books, Invoice, Checkout, Billing, or Inventory to collect payments seamlessly across Zoho's business apps.

We support the following Zoho apps: **Books, Invoice, Checkout, Billing and Inventory**. To add Cashfree Payment Gateway to your apps:

1. Log in to your Zoho books and click **Settings**.

2. In the Settings select **Online Payments**.

   <Accordion title="Settings">
     <img />
   </Accordion>

3. In the **Online Payments** screen, Select Cashfree and click **Set Up Now**.

4. Enter the **App ID** and **Secret Key** of your Cashfree Account.

5. Click **Save** to integrate Cashfree with your Zoho Books.
   <Accordion title="Payment Gateway Configuration">
     <img />
   </Accordion>

Your customers can start making payments using Cashfree Payment Gateway.

The following currencies are currently supported on the platform:

<Accordion title="Supported currencies">
  | ISO code | Currency name |
  | - | - |
  | INR | Indian Rupee |
  | AED | United Arab Emirates Dirham |
  | AFN | Afghan Afghani |
  | ALL | Albanian Lek |
  | ARS | Argentine Peso |
  | AUD | Australian Dollar |
  | AZN | Azerbaijani Manat |
  | BBD | Barbadian Dollar |
  | BDT | Bangladeshi Taka |
  | BGN | Bulgarian Lev |
  | BMD | Bermudian Dollar |
  | BND | Brunei Dollar |
  | BOB | Bolivian Boliviano |
  | BRL | Brazilian Real |
  | BSD | Bahamian Dollar |
  | BWP | Botswana Pula |
  | BZD | Belize Dollar |
  | CAD | Canadian Dollar |
  | CHF | Swiss Franc |
  | CLP | Chilean Peso |
  | CNY | Chinese Yuan Renminbi |
  | COP | Colombian Peso |
  | CRC | Costa Rican Colón |
  | CZK | Czech Koruna |
  | DKK | Danish Krone |
  | DOP | Dominican Peso |
  | DZD | Algerian Dinar |
  | EGP | Egyptian Pound |
  | EUR | Euro |
  | FJD | Fijian Dollar |
  | GBP | British Pound Sterling |
  | GTQ | Guatemalan Quetzal |
  | HKD | Hong Kong Dollar |
  | HNL | Honduran Lempira |
  | HUF | Hungarian Forint |
  | IDR | Indonesian Rupiah |
  | ILS | Israeli New Shekel |
  | JMD | Jamaican Dollar |
  | JPY | Japanese Yen |
  | KES | Kenyan Shilling |
  | KRW | South Korean Won |
  | KZT | Kazakhstani Tenge |
  | LAK | Lao Kip |
  | LBP | Lebanese Pound |
  | LKR | Sri Lankan Rupee |
  | LRD | Liberian Dollar |
  | MAD | Moroccan Dirham |
  | MOP | Macanese Pataca |
  | MUR | Mauritian Rupee |
  | MVR | Maldivian Rufiyaa |
  | MXN | Mexican Peso |
  | MYR | Malaysian Ringgit |
  | NIO | Nicaraguan Córdoba |
  | NOK | Norwegian Krone |
  | NPR | Nepalese Rupee |
  | NZD | New Zealand Dollar |
  | PEN | Peruvian Sol |
  | PGK | Papua New Guinean Kina |
  | PHP | Philippine Peso |
  | PLN | Polish Złoty |
  | QAR | Qatari Riyal |
  | RON | Romanian Leu |
  | RUB | Russian Ruble |
  | SAR | Saudi Riyal |
  | SBD | Solomon Islands Dollar |
  | SCR | Seychellois Rupee |
  | SEK | Swedish Krona |
  | SGD | Singapore Dollar |
  | THB | Thai Baht |
  | TOP | Tongan Paʻanga |
  | TRY | Turkish Lira |
  | TTD | Trinidad and Tobago Dollar |
  | TWD | New Taiwan Dollar |
  | UAH | Ukrainian Hryvnia |
  | USD | United States Dollar |
  | VND | Vietnamese Đồng |
  | VUV | Vanuatu Vatu |
  | WST | Samoan Tala |
  | XCD | East Caribbean Dollar |
  | XOF | West African CFA Franc |
  | YER | Yemeni Rial |
  | ZAR | South African Rand |
</Accordion>

<Note>
  Read about [whitelisting your store url](/docs/payments/online/go-live/whitelist)
  before you can accept payments on your store.
</Note>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/payments/online/go-live/whitelist">Whitelist Store URL</a></li>
    <li><a href="/docs/payments/online/go-live/checklist">Go Live Checklist</a></li>
    <li><a href="/docs/api-reference/authentication#generate-api-keys">Generate API Keys</a></li>
  </ul>
</div>


# Payment Gateway
Source: https://www.cashfree.com/docs/payments/quick-guide/payment

Use this Payment Gateway quick guide to track Cashfree transactions, monitor downtimes, review analytics, and act on the most important dashboard insights.

Cashfree’s Payment Gateway allows you to process customer transactions while ensuring industry-best success rates. Transaction outcomes may also depend on external factors such as card details, one-time passwords (OTPs), or issuer bank systems.

This guide helps you understand how to monitor and manage payments effectively through the Cashfree dashboard. This is useful to:

* Monitor transaction statuses and identify failure reasons.
* Track bank and network downtimes affecting payments.
* Review business trends and conversion rates through analytics.
* Troubleshoot common payment issues.

## Quick reference

The following questions address common tasks and concerns when managing payments through the Merchant dashboard:

<Accordion title="Payment success rate factors">
  Cashfree provides one of the highest success rates in the industry. However, transaction failures can occur due to factors outside Cashfree's control.

  * **User-related issues**: Invalid CVV, invalid OTP, failed 2-factor authentication, or card not enabled for online transactions.
  * **Bank or network issues**: Issuer bank downtime such as SBI, HDFC, Kotak or card network downtime such as NPCI, Visa, Mastercard.

  <Tip>Use Cashfree's dashboard to monitor downtimes and configure email notifications for real-time updates.</Tip>

  **Related topics:** Learn more about [error codes and troubleshooting](/docs/api-reference/payments/errors), [payment failure reasons for subscriptions](/docs/api-reference/payments/latest/subscription/error-codes), [API troubleshooting](/docs/api-reference/integration-troubleshooting/payments-ts), and [success rate monitoring](/docs/payments/manage/monitor#success-rate-alerts).
</Accordion>

<Accordion title="Transaction status checking">
  You can track whether a transaction was successful or failed directly from the dashboard. Complete these steps to check transaction status and failure reasons:

  1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com).
  2. Go to **Payment Gateway > Transactions > Payments**.
  3. Click on a **Transaction ID** to view complete details, including:
     * Error description
     * Error source
     * Failure reason

  <Frame>
    <img />
  </Frame>

  <Frame>
    <img />
  </Frame>

  **Related topics:** For detailed transaction management, see [viewing transaction details](/docs/payments/manage/transactions), [payment webhooks](/docs/api-reference/payments/latest/payments/webhooks), [using APIs to check order status](/docs/api-reference/payments/latest/orders/get-order), and [comprehensive dashboard overview](/docs/payments/dashboard).
</Accordion>

<Accordion title="Downtime information tracking">
  The dashboard provides real-time visibility into active, upcoming, and resolved downtimes. Complete these steps to track downtime information:

  1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com).
  2. Go to **Payment Gateway**.
  3. Scroll down to the **Downtime section**.
  4. Click to view complete downtime details.

  <Frame>
    <img />
  </Frame>

  The downtime section displays:

  * **Active downtimes**: Current issues affecting payments.
  * **Upcoming downtimes**: Scheduled maintenance windows.
  * **Resolved downtimes**: Recently fixed issues.

  <Note>Configure email notifications to receive real-time downtime alerts and minimise impact on your business operations.</Note>

  **Related topics:** For comprehensive downtime management, see [downtimes overview](/docs/payments/manage/downtimes), [downtime APIs](/docs/api-reference/payments/latest/downtime/fetch-all-downtimes), [downtime webhooks](/docs/api-reference/payments/latest/utilities/incidents/incident-webhook), and [payouts downtime tracking](/docs/payouts/payouts/downtimes).
</Accordion>

<Accordion title="Payment analytics access">
  The Analytics dashboard provides a consolidated view of your business performance, including conversion rates and payment failures. Complete these steps to access the analytics dashboard:

  1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com).
  2. Go to **Payment Gateway > Transactions > Analytics**.
  3. Review trends for:
     * Conversion rate
     * Business volume
     * Payment failures
     * Success rate patterns

  <Frame>
    <img />
  </Frame>

  The analytics dashboard shows:

  * **Conversion metrics**: Success rates and completion rates.
  * **Volume trends**: Transaction amounts and counts over time.
  * **Failure analysis**: Common failure reasons and patterns.
  * **Performance insights**: Peak hours and method preferences.

  **Related topics:** Explore advanced analytics with [payment analytics](/docs/payments/checkout/after/analytics), [external analytics integration](/docs/payments/checkout/after/external-analytics), [comprehensive reports](/docs/payments/manage/reports), [API monitoring](/docs/payments/manage/monitor), and [scheduled reports](/docs/payments/manage/schedule-reports).
</Accordion>

<Accordion title="Troubleshooting frequent payment failures">
  If you notice increased payment failures, follow these troubleshooting steps to identify and resolve issues:

  1. **Check downtime status**: Review the downtime section to identify any active bank or network issues affecting payments.
  2. **Analyse failure patterns**: Use the analytics dashboard to identify common failure reasons and affected payment methods.
  3. **Review transaction details**: Check individual failed transactions for specific error codes and failure sources.
  4. **Monitor success rates**: Set up success rate alerts to receive notifications when rates drop below acceptable thresholds.
     <Warning>Sudden drops in success rates often indicate external issues like bank downtimes or network problems rather than technical integration issues.</Warning>

  **Related topics:** For additional support, see [payment troubleshooting](/docs/api-reference/integration-troubleshooting/payments-ts), [error handling best practices](/docs/api-reference/payments/errors), and [success rate optimisation](/docs/payments/manage/monitor).
</Accordion>

<Accordion title="Monitoring and alerts setup">
  You can configure various monitoring and alert systems to stay informed about payment performance. Complete these steps to set up monitoring:

  1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com).
  2. Go to **Payment Gateway > Settings > Notifications**.
  3. Configure alerts for:
     * Success rate drops
     * Downtime notifications
     * Transaction volume changes
     * Failed payment thresholds

  <Tip>Set up multiple notification channels (email, SMS, webhooks) to ensure you receive critical alerts even when offline.</Tip>

  **Related topics:** For comprehensive monitoring setup, see [notification configuration](/docs/payments/manage/monitor), [webhook implementation](/docs/api-reference/payments/latest/payments/webhooks), and [automated reporting](/docs/payments/manage/schedule-reports).
</Accordion>

## Next steps

After familiarising yourself with payment monitoring basics:

* Set up [payment webhooks](/docs/api-reference/payments/latest/payments/webhooks) for real-time transaction notifications.
* Configure [automated monitoring](/docs/payments/manage/monitor) for success rate alerts.
* Explore [comprehensive reporting](/docs/payments/manage/reports) for business insights.
* Implement [error handling best practices](/docs/api-reference/payments/errors) in your integration.

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/integration-troubleshooting/payments-ts">API Troubleshooting</a></li>
    <li><a href="/docs/api-reference/payments/latest/payments/webhooks">Payments Webhooks</a></li>
    <li><a href="/docs/api-reference/payments/errors">Payments Errors</a></li>
    <li><a href="/docs/payments/manage/monitor">Monitoring and Observability</a></li>
  </ul>
</div>


# Refunds
Source: https://www.cashfree.com/docs/payments/quick-guide/refunds

Use this refunds quick guide to track, process, and manage Cashfree refunds from the Merchant Dashboard, including search filters, status updates, and exports.

Refunds return money from a successful payment to the customer. Understanding how to manage refunds efficiently helps maintain customer satisfaction and operational transparency.

This guide helps you understand how to process and track refunds effectively through the Cashfree dashboard. This is useful to:

* Process merchant-initiated and automatic refunds.
* Track refund status and processing times.
* Manage refund operations through the dashboard.
* Troubleshoot common refund issues.

<Note> You can initiate refunds only within six months of the original successful transaction's date and time.</Note>

## Quick reference

The following questions address common tasks and concerns when managing refunds through the Merchant Dashboard.

<Accordion title="Refund types and processing">
  Cashfree supports two types of refunds to ensure seamless payment reversals for different scenarios.

  * **Merchant-initiated refunds**: Manual refunds initiated by the merchant from the dashboard or via API for customer service, order cancellations, or disputes.
  * **Automatic refunds**: When a transaction fails but the customer's account is debited, Cashfree automatically initiates a refund without merchant intervention.

  <Tip>Most refunds (90%) are processed instantly regardless of payment method. Standard TAT applies only when bank delays occur.</Tip>

  **Related topics:** Learn more about [refund APIs](/docs/api-reference/payments/latest/refunds/create-refund), [refund webhooks](/docs/api-reference/payments/latest/refunds/webhooks), and [refund error handling](/docs/api-reference/payments/errors).
</Accordion>

<Accordion title="Refund processing times">
  Refund processing times vary by payment method, though most are completed instantly. Complete processing times are:

  * **UPI refunds**: Up to 5 working days. This is usually processed within hours.
  * **Card refunds**: Up to 7 working days. This depends on the issuing bank.
  * **Other payment methods**: 7-10 working days for net banking and wallet transactions.

  <Note>Processing time refers to the maximum TAT. Around 90% of refunds are processed instantly regardless of the payment method used.</Note>

  **Related topics:** For detailed refund timelines, see [refund processing](/docs/payments/manage/refunds/overview), [payment method specifics](/docs/payments/manage/payment-methods), and [bank processing times](/docs/help/payments/orders-and-payments/orders-and-payments).
</Accordion>

<Accordion title="Initiating refunds from dashboard">
  You can process refunds directly from the Merchant Dashboard. Complete these steps to initiate a refund:

  1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
  2. Go to **Payment Gateway > Transactions > Payments**.
  3. Search for the transaction to be refunded and click **Refund**.
  4. Enter refund details:
     * Enter refund amount (full or partial)
     * Add a remark if required
     * Click the info icon to view refund charges
  5. Click **Initiate refund** to process instantly.

  <Frame>
    <img />
  </Frame>

  <Warning>The refund amount can't exceed the maximum refundable amount. Refunds can also be initiated via API.</Warning>

  **Related topics:** For API-based refunds, see [create refund API](/docs/api-reference/payments/latest/refunds/create-refund), [refund status tracking](/docs/api-reference/payments/latest/refunds/get-refund), and [bulk refund operations](/docs/payments/manage/refunds/overview).
</Accordion>

<Accordion title="Checking refund status">
  You can track refund status and view detailed information directly from the dashboard. Complete these steps to check refund status:

  1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
  2. Go to **Payment Gateway**.
  3. Select **Refunds > Initiated refunds**.
  4. Apply date range, status, or amount filters as needed.
  5. Click the **Refund ID** to view complete refund information.

  <Frame>
    <img />
  </Frame>

  The dashboard shows refund status as:

  * **Pending**: Refund initiated but not yet processed.
  * **Successful**: Refund completed and funds returned.
  * **Failed**: Refund couldn't be processed.
  * **PROCESSED**: Refund has been processed by Cashfree.

  **Related topics:** For programmatic status checking, see [get refund status API](/docs/api-reference/payments/latest/refunds/get-refund), [refund webhooks](/docs/api-reference/payments/latest/refunds/webhooks), and [comprehensive refund reports](/docs/payments/manage/reports).
</Accordion>

<Accordion title="Troubleshooting refund delays">
  If the refund isn't processed within the standard TAT, follow these troubleshooting steps:

  1. **Verify refund initiation**: Check that the refund was initiated in **Payment Gateway > Transactions > Refunds > Initiated refunds**.
  2. **Check refund status**: Confirm if the status shows as pending or successful in the dashboard.
  3. **Wait for TAT completion**: If pending, wait for the respective TAT. UPI: 5 days, Cards: 7 days.
  4. **Provide ARN for bank follow-up**: If status shows **success** but the customer hasn't received funds, provide the **refund ARN** (available in the Merchant Dashboard) for bank follow-up.

  <Note>Most refund delays are due to bank processing times, not technical issues. Always check the refund status in the dashboard before escalating customer queries.</Note>

  **Related topics:** For additional support, see [refund troubleshooting](/docs/help/payments/orders-and-payments/orders-and-payments), [customer support guidelines](/docs/help/payments/orders-and-payments/orders-and-payments), and [dispute management](/docs/payments/manage/disputes/overview).
</Accordion>

<Accordion title="Cancelling refunds">
  Yes, you can cancel refunds that are still in pending status. Complete these steps to cancel a refund:

  1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
  2. Go to **Payment Gateway > Transactions > Payments**.
  3. Locate the transaction with the refund you want to cancel.
  4. In the refund section, click the cancel option on the extreme right.

  <Frame>
    <img />
  </Frame>

  <Warning>Refund cancellation is only available for pending refunds that haven't been processed yet. Successful refunds can't be cancelled.</Warning>

  **Related topics:** For API-based cancellation, see [cancel refund operations](/docs/api-reference/payments/latest/refunds/update-refund), [refund status management](/docs/payments/manage/refunds/overview), and [refund policy guidelines](/docs/help/payments/orders-and-payments/orders-and-payments).
</Accordion>

<snippet>snippets/related-topics-loader.mdx</snippet>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/payments/latest/refunds/create-refund">Create Refund API</a></li>
    <li><a href="/docs/api-reference/payments/latest/refunds/webhooks">Refunds Webhooks</a></li>
    <li><a href="/docs/payments/manage/reports">Payment Reports</a></li>
  </ul>
</div>

## Next steps

After familiarising yourself with refund management basics:

* Set up [refund webhooks](/docs/api-reference/payments/latest/refunds/webhooks) for real-time refund notifications.
* Explore [automated refund processing](/docs/api-reference/payments/latest/refunds/create-refund) via APIs.
* Review [comprehensive refund reports](/docs/payments/manage/reports) for business insights.
* Configure [customer notifications](/docs/help/payments/orders-and-payments/orders-and-payments) for refund updates.


# Settlements
Source: https://www.cashfree.com/docs/payments/quick-guide/settlement

Use this settlements quick guide to track Cashfree payouts, review settlement reports, and reconcile bank credits from the Payment Gateway Merchant Dashboard.

Settlements represent the amount collected from customers through the payment gateway that's transferred to the merchant's bank account. The cycle determines when the funds are credited, based on the type of settlement configured.

This guide helps you understand how to track and manage settlements effectively through the Cashfree dashboard. This is useful to:

* Understand different settlement types and cycles.
* Track settlement status and processing details.
* Review charges, deductions, and settlement breakdowns.
* Troubleshoot delayed settlement issues.

## Quick reference

The following questions address common tasks and concerns when managing settlements through the Merchant dashboard.

<Accordion title="Settlement types and cycles">
  Cashfree offers multiple settlement options to meet different business cash flow requirements.

  * **Standard settlements (T+2 cycle)**: Default settlement where funds are credited two business days after transaction, excluding weekends and holidays.
  * **Instant settlements**: Access funds within 15 minutes instead of waiting for the standard T+2 cycle.
  * **On-demand settlements**: Transfer funds instantly including holidays for a small fee, providing 24/7 access to your money.
    <Note>Example timing: Transaction on Friday, June 3 → T+1: Monday, June 6 → T+2: Tuesday, June 7</Note>

  **Related topics:** Learn more about [settlement cycles](/docs/payments/manage/settlements), [instant settlement configuration](/docs/help/payments/settlements/instant-settlements), and [settlement fee structures](/docs/help/payments/settlements/settlements).
</Accordion>

<Accordion title="Tracking settlement status">
  You can monitor settlement status and view detailed processing information directly from the dashboard. Complete these steps to check settlement status:

  1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com).
  2. Go to **Payment Gateway**
  3. Select **Settlements > Online**.
  4. Apply filters to view pending or processed settlements.
  5. Click the **UTR** to view details for a specific settlement.

  <Frame>
    <img />
  </Frame>

  <Frame>
    <img />
  </Frame>

  The dashboard displays settlement status as:

  * **Pending**: Settlement initiated but not yet processed.
  * **Processed**: Settlement completed and funds transferred.
  * **Failed**: Settlement couldn't be completed.

  **Related topics:** For programmatic tracking, see [settlement APIs](/docs/api-reference/payments/latest/settlement-reconciliation/settlement-reconciliation), [settlement webhooks](/docs/api-reference/payments/latest/settlements/settlement-webhooks), and [comprehensive settlement reports](/docs/payments/manage/reports).
</Accordion>

<Accordion title="Settlement charges and deductions">
  The dashboard provides detailed breakdowns of all charges and deductions applied to your settlements. Complete these steps to review settlement charges:

  1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com).
  2. Go to **Payment Gateway > Settlements > Online**.
  3. Select a settlement from the list.
  4. Review the **charges and explanation** section for detailed breakdown.

  <Frame>
    <img />
  </Frame>

  The charges section shows:

  * **Transaction fees**: Payment processing charges.
  * **Gateway fees**: Platform usage charges.
  * **Refund deductions**: Refunds processed during the settlement period.
  * **Adjustment charges**: Any account adjustments or corrections.

  **Related topics:** For detailed fee information, see [pricing structure](/docs/help/account/pricing), [refund impact on settlements](/docs/payments/manage/refunds/overview), and [settlement reconciliation reports](/docs/payments/manage/reports).
</Accordion>

<Accordion title="Instant settlement limits">
  You can monitor your daily instant settlement limits and usage directly from the dashboard. Complete these steps to view instant settlement limits:

  1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com).
  2. Go to **Payment Gateway > Settlements > Online**.
  3. Review instant settlement limits and current usage in the limits section.

  <Frame>
    <img />
  </Frame>

  The limits section displays:

  * **Daily limit**: Maximum amount available for instant settlements.
  * **Used today**: Amount already settled instantly.
  * **Available balance**: Remaining instant settlement capacity.

  <Warning>Instant settlement limits reset daily and may vary based on your account configuration and transaction history.</Warning>

  **Related topics:** For limit increases, see [account upgrades](/docs/help/account/account-management), [instant settlement pricing](/docs/help/payments/settlements/instant-settlements), and [settlement configuration](/docs/payments/manage/settlements).
</Accordion>

<Accordion title="Bank holidays and settlement timing">
  Settlement timelines exclude weekends and bank holidays, which can affect when you receive funds. Complete these steps to view the holiday calendar:

  1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com).
  2. Go to **Payment Gateway > Settlements > Online**.
  3. Click **View settlement holidays** to see the complete holiday list.

  <Frame>
    <img />
  </Frame>

  <Note>During bank holidays, T+1 and T+2 cycles are extended by the number of non-working days. Instant and on-demand settlements remain available.</Note>

  **Related topics:** For holiday impact details, see [settlement timing guidelines](/docs/help/payments/settlements/settlements), [holiday calendar updates](/docs/help/payments/settlements/settlements), and [alternative settlement options](/docs/help/payments/settlements/instant-settlements).
</Accordion>

<Accordion title="Troubleshooting settlement delays">
  If settlement funds haven't been credited to your account, follow these troubleshooting steps:

  1. **Verify transaction details**: Check the transaction date and status in the dashboard. Successful transactions settle after deductions as per the configured cycle.
  2. **Confirm settlement cycle**: Verify your settlement cycle: T+1, T+2, instant, or on-demand configuration.
  3. **Check settlement status**: Review the settlement status in the dashboard to confirm processing completion.
  4. **Contact bank if needed**: If settlement is marked as processed but funds aren't reflected, wait up to two additional business days or contact your bank using the ARN/settlement reference number.

  <Tip>For settlement issues, always verify the cycle and status before contacting support. Most delays are due to weekend/holiday timing.</Tip>

  **Related topics:** For additional support, see [settlement troubleshooting](/docs/help/payments/settlements/settlements), [bank account verification](/docs/help/account/account-management), and [settlement dispute resolution](/docs/payments/manage/disputes/overview).
</Accordion>

## Next steps

After familiarising yourself with settlement management basics:

* Configure [settlement webhooks](/docs/api-reference/payments/latest/settlements/settlement-webhooks) for real-time settlement notifications.
* Set up [automated settlement tracking](/docs/api-reference/payments/latest/settlement-reconciliation/settlement-reconciliation) via APIs.
* Review [comprehensive settlement reports](/docs/payments/manage/reports) for financial reconciliation.
* Explore [instant settlement options](/docs/help/payments/settlements/instant-settlements) for improved cash flow.

<snippet>snippets/related-topics-loader.mdx</snippet>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/payments/latest/settlement-reconciliation/settlement-reconciliation">Settlement Reconciliation API</a></li>
    <li><a href="/docs/api-reference/payments/latest/settlements/settlement-webhooks">Settlement Webhooks</a></li>
    <li><a href="/docs/payments/manage/settlements">Settlements Overview</a></li>
    <li><a href="/docs/payments/manage/reports">Payment Reports</a></li>
  </ul>
</div>


# Quickstart Guide
Source: https://www.cashfree.com/docs/payments/quickstart-guide

Walk through the Cashfree integration journey from account setup and API keys to building checkout, testing in sandbox, and going live.

This page provides the resources and configuration guides you need to set up your Cashfree account, integrate the Cashfree APIs, and deploy your integration to production.

Navigate to the relevant section based on your integration stage:

* [**Account and activation**](#account-and-activation): Signup, KYC requirements, team management, and account management.
* [**Developer integration**](#developer-integration): Server-side SDKs, test data, webhooks, and rate limits.
* [**Go-live and production**](#production-deployment): Final checklists and domain whitelisting.

## Account and activation

Access the guides below for account creation, KYC submission, team management, and account management.

<CardGroup>
  <Card title="Create an account" icon="file-shield" href="/docs/help/account/account-activation#create-an-account">
    Access the step-by-step guide for account creation, KYC submission, and bank verification.
  </Card>

  <Card title="Required documents" icon="file-lines" href="/docs/help/account/account-activation#required-documents">
    Review the list of KYC and business proofs required based on your entity type and business category.
  </Card>

  <Card title="Manage account" icon="user-gear" href="/docs/help/account/account-management">
    Update your business profile, profile information, and security settings.
  </Card>

  <Card title="Manage access" icon="users" href="/docs/help/account/access-management">
    Learn how to assign roles and manage dashboard access for your team.
  </Card>
</CardGroup>

## Developer integration

Build your integration using the official Cashfree server-side SDKs, validate with test data, configure webhooks for notifications, and understand API rate limits.

<CardGroup>
  <Card title="Server-side SDKs" icon="boxes-stacked" href="/docs/api-reference/payments/sdk">
    Accelerate your integration using the official Cashfree server-side SDKs for popular programming languages.
  </Card>

  <Card title="Test data" icon="vial" href="/docs/api-reference/payments/data-to-test-integration">
    Test data for the sandbox environment to validate your Cashfree integration.
  </Card>

  <Card title="Webhooks" icon="bell" href="/docs/payments/online/webhooks/overview">
    Register webhook endpoints to receive real-time notifications for payment and settlement events.
  </Card>

  <Card title="API rate limits" icon="gauge" href="/docs/api-reference/payments/rate-limits">
    Understand the API request limits and throughput to ensure a scalable integration.
  </Card>
</CardGroup>

## Production deployment

Complete the final checklists and security configurations before processing live transactions.

<CardGroup>
  <Card title="Go-live checklist" icon="rocket" href="/docs/payments/online/go-live/checklist">
    Complete the final 8-point checklist to ensure your integration is production-ready.
  </Card>

  <Card title="Domain whitelisting" icon="shield-check" href="/docs/payments/online/go-live/whitelist">
    Authorise production domains and application package names for secure API access.
  </Card>
</CardGroup>

<Tip>Read [Introduction](/docs/payments/introduction) for a platform overview on Cashfree products, capabilities, and the benefits they provide to merchants.</Tip>

## Environment comparison

Cashfree provides two environments for integration testing and live transaction processing.

<Info>
  You can switch between the environments directly from the [Merchant Dashboard](https://merchant.cashfree.com/auth/login). To get started, click **Switch to Test** in the top-right corner to enter the test environment (indicated by a yellow banner) and safely simulate operations without financial impact. To return to the production environment and process live transactions, click **Switch to Prod**.
</Info>

| Feature | **Sandbox (test environment)** | **Production** |
| :- | :- | :- |
| **Endpoint** | `sandbox.cashfree.com` | `api.cashfree.com` |
| **API credentials** | Sandbox **App ID** and **Secret Key** starting with `TEST_` | Production **App ID** and **Secret Key** starting with `PROD_` |
| **KYC** | Not required for simulated testing | **Mandatory** for live payment processing |
| **Transactions** | Simulated operations without financial impact | Real-time payments and settlements |
| **Activation** | Instant access for initial integration | Requires compliance verification and document submission |

## Support and resources

Use the resources below for detailed information on commonly asked questions or reach out to the Cashfree support team for personalised assistance.

<CardGroup>
  <Card title="Frequently asked questions" icon="circle-info" href="/docs/help/overview">
    Access support resources and contact channels for Cashfree.
  </Card>

  <Card title="Request support" icon="headset" href="https://merchant.cashfree.com/merchants/landing?env=prod&raise_issue=1">
    Contact the support team for personalised assistance.
  </Card>
</CardGroup>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/help/account/overview">Account Overview</a></li>
    <li><a href="/docs/help/account/access-management">Access Management</a></li>
    <li><a href="/docs/api-reference/payments/latest/overview">Payment Gateway API</a></li>
    <li><a href="/docs/api-reference/payments/data-to-test-integration">Data to Test Integration</a></li>
  </ul>
</div>


# Fraud Risk Indicator
Source: https://www.cashfree.com/docs/payments/risk-shield/fraud-risk-indicator

Review the Cashfree RiskShield Fraud Risk Indicator to score every transaction for risk, surface suspicious patterns, and act on flagged orders quickly.

The Fraud Risk Indicator (FRI) is a government-integrated mobile number risk detection feature available in Cashfree RiskShield. It helps you proactively detect and manage fraud risks linked to mobile numbers flagged by Indian regulatory and enforcement agencies.

**Data sources include:**

* Department of Telecommunications (DoT)
* Indian Cybercrime Coordination Centre (I4C)
* Law Enforcement Agencies (LEAs)
* National Cybercrime Reporting Portal (cybercrime.gov.in)
* Banks and fintech partners

Data is refreshed daily to reflect the latest list of flagged mobile numbers. For more information, refer [Official Press Release - DoT Fraud Number Registry.](https://www.pib.gov.in/PressReleasePage.aspx?PRID=2130249)

## Why this matters

Mobile numbers used in cybercrime or identity fraud often stay active for days or weeks after a fraud is committed. Fraudsters use these numbers to:

* Create new accounts on other platforms
* Abuse promotions or referral systems
* Bypass OTP checks with disposable SIMs
* Commit repeat payment fraud

FRI helps you detect these mobile numbers early — before they affect your platform — giving you a stronger defence against fraud.

## Types of blacklisted mobile numbers

| **Fraud list** | **Description** | **Risk level** | **Recommended action** |
| - | - | - | - |
| LEA Reported Cybercrime | Reported by police or I4C for scams, phishing, fraud. | Very High | Block |
| DoT Reported Fake/Forged Cases | SIMs obtained with forged or fraudulent documents. | Very High | Block |
| Subscriber Verification Non-Compliant | Non-compliant KYC cases flagged by TSPs or DoT. | Medium | Alert / Review |
| Disconnected (Zero Usage/Non-payment) | Dormant numbers flagged by telcos as suspicious. | Medium | Alert / Review |
| TSP Internal Analysis | Flagged by telecom providers using internal fraud checks. | Medium | Alert / Review |
| Others | High-risk numbers from banks, fintechs, or telcos. | Medium | Alert / Review |

## What you can do with FRI

* **Block high-risk numbers at checkout.** Stop known fraud SIMs from completing transactions.
* **Review or alert medium-risk activity.** Flag suspicious SIMs used for fake signups or mule accounts.
* **Check past exposure.** Identify how many flagged numbers transacted before you enabled FRI.
* **Customise actions by list.** Turn lists on or off and set actions like Block or Review.
* **Auto-expire stale data.** Mobile numbers expire automatically after 90 days to keep the list relevant.

## Example use cases

| **Scenario** | **How FRI helps** |
| - | - |
| Known fraudsters visit your platform for the first time | FRI detects and blocks high-risk transactions automatically. |
| A fraudster uses a forged SIM to create an account | FRI blocks the transaction using the DoT Fake/Forged list. |
| A dormant number is used for fake referrals | FRI flags it as medium risk for your review. |
| Historical audit | See how many flagged numbers transacted before FRI was active. |

<Note>
  For help with onboarding, configuration, or interpreting flagged transactions, fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1).
</Note>


# Blacklists
Source: https://www.cashfree.com/docs/payments/risk-shield/my-blacklists

Add untrusted customers to your Cashfree RiskShield blacklist using card, phone, email, IP, or device data to block risky transactions automatically.

We offer you to create your blacklist who might be regarded as unacceptable or untrustworthy. Once added in the blacklist, the transaction is blocked by RiskShield. You can block a transaction based on customer details such as:

* [Mobile Number](/docs/payments/risk-shield/my-blacklists#mobile-number)
* [Email ID](/docs/payments/risk-shield/my-blacklists#email-id)
* [UPI Handle](/docs/payments/risk-shield/my-blacklists#upi-handle)
* [Cities ](/docs/payments/risk-shield/my-blacklists#cities-indian)
* [IP Address](/docs/payments/risk-shield/my-blacklists#ip-address)
* Card BIN (Contact your account manager to block transactions from a specific card BIN)

<Note>
  **Disputes**
  You can also add a customer information from **Disputes Details** to your blacklist. This will block future transactions from the respective customer.
</Note>

## Mobile number

For your security and fraud prevention, you can block a mobile number from processing transactions. The individual cannot process a transaction from using the blocked mobile number. If you think there are indications of fraudulent activity associated with a mobile number, follow the instructions below to block that mobile number:

1. From the *My Blacklists* screen, click **Add New** > **Mobile Number**.
2. In the *Add Mobile Number to Blacklist* popup, enter the following information:
   * **Single Mobile Number**: Enter the mobile number in this field.
   * **Multiple Mobile Number**: Download the sample file, enter the mobile numbers as per the format, and upload the file.
3. Click **Show Impact Analysis**.

<Frame>
  <img />
</Frame>

## Email ID

There may be instances when fraudsters use the same email ID to process transactions. In such cases, you can block the respective email ID from making transactions in the future. Follow the instructions below to add the email ID to your blacklist:

1. From the *My Blacklists* screen, click **Add New** > **Email ID**.
2. In the *Add Email ID to Blacklist* popup, enter the following information:
   * **Single Email ID**: Enter the email ID in this field.
   * **Multiple Email ID**: Download the sample file, enter the email IDs as per the format, and upload the file.
3. Click **Show Impact Analysis**.

## Cities (Indian)

High and medium-risk cities for transactions typically refer to locations where there is a higher likelihood of fraudulent financial activities. They may have higher rates of identity theft, credit card fraud, or other financial crimes.

<Accordion title="View the high and medium risk Indian cities.">
  | City | State | Risk status |
  | :- | :- | :- |
  | Jamtara | Jharkhand | High |
  | Nuh | Haryana | High |
  | Jodhpur | Rajasthan | High |
  | Sri Ganganagar | Rajasthan | High |
  | Khokha Ki Dhani | Rajasthan | High |
  | Begusarai | Bihar | High |
  | Siwana | Rajasthan | High |
  | Samdari | Rajasthan | High |
  | Hanumangarh | Rajasthan | High |
  | Jamshedpur | Jharkhand | High |
  | Revelganj | Bihar | High |
  | Ara | Bihar | High |
  | Jasidih | Jharkhand | High |
  | Gaya | Bihar | High |
  | Buxar | Bihar | High |
  | Banswara | Rajasthan | High |
  | Raipur | Chhattisgarh | High |
  | Vapi | Gujarat | High |
  | Muzzaffarpur | Bihar | High |
  | Miran | Rajasthan | High |
  | Chunawadh | Rajasthan | High |
  | Munger | Bihar | High |
  | Sitamarhi | Bihar | High |
  | Phulan | Rajasthan | High |
  | Koelwar | Bihar | High |
  | Durg | Chhattisgarh | High |
  | Pundri | Haryana | High |
  | Chas | Jharkhand | High |
  | Dhanbad | Jharkhand | High |
  | Rusera | Bihar | High |
  | Srinagar | Jammu and Kashmir | High |
  | Pupri | Bihar | Medium |
  | Shahpur | Bihar | Medium |
  | Bakhtiyarpur | Bihar | Medium |
  | Jhanjarpur | Bihar | Medium |
  | Maner | Bihar | Medium |
  | Tekari | Bihar | Medium |
  | Madhupur | Jharkhand | Medium |
  | Baruni | Bihar | Medium |
  | Bhagalpur | Bihar | Medium |
  | Muri | Jharkhand | Medium |
  | Dalkola | Bihar | Medium |
  | Hazaribagh | Jharkhand | Medium |
  | Satbarwa | Jharkhand | Medium |
  | Jugsalai | Jharkhand | Medium |
  | Chakulia | Jharkhand | Medium |
  | Sarawan | Jharkhand | Medium |
  | Chaibasa | Jharkhand | Medium |
  | Sarath | Jharkhand | Medium |
  | Dumka | Jharkhand | Medium |
  | Ray | Jharkhand | Medium |
  | Patamda | Jharkhand | Medium |
  | Patna | Bihar | Medium |
</Accordion>

Follow the instructions below to block a transaction based on Indian cities:

1. From the *My Blacklists* screen, click **Add New** > **Cities**.
2. In the *Add Cities to Blacklist* popup, enter the following information:
   * **Select Country** - **India** is selected by default.
   * \*\*Select State \*\*: Click this dropdown menu to choose a state.
   * **Select City**: Click this dropdown menu to choose a city.
3. Click **Add Now**. Repeat the process to add more cities to the blacklist.

<Frame>
  <img />
</Frame>

## UPI handle

You can block UPI VPA information to prevent any financial harm. Follow the instructions below to add a UPI handle to the blacklist:

1. From the *My Blacklists* screen, click **Add New** > **UPI Handle**.
2. In the *Add UPI Handle to Blacklist* popup, enter the following information:
   * **Single UPI Handle**: If you want to block a single UPI handle, select this option and enter the UPI VPA in this field.
   * **Multiple UPI Handle**: If you want to block multiple UPI handles, select this option, use **Download sample file** and enter UPI VPA information as per the format in the file, and upload the file using **Upload File**.
3. Click **Show Impact Analysis**.

<Frame>
  <img />
</Frame>

## IP address

To tighten your security, you can block an IP address that is prone to suspicious or fraudulent activities. When you add an IP address to the blacklist, we will block any attempts to initiate transactions from the IP address. Follow the instructions below to add an IP address to the blacklist:

1. From the *My Blacklists* screen, click **Add New** > **IP Address**.
2. In the *Add IP Addresses to Blacklist* popup, enter the following information:
   * **IP Address**: Enter the IP address in the field.
3. Click **Show Impact Analysis**.

<Frame>
  <img />
</Frame>


# Overview
Source: https://www.cashfree.com/docs/payments/risk-shield/overview

Use the Cashfree RiskShield Analytics Dashboard to evaluate your fraud profile, track dispute trends, monitor blocked transactions, and review rule performance.

The RiskShield Analytics Dashboard offers a detailed view of your fraud and dispute trends, allowing you to understand your risk potential and assess the impact of RiskShield on your business. Track your dispute ratios, fraud sources, blocked transactions, and rule performance all in one place.

## Risk score summary

<img alt="Risk profile categories visualisation" />

At the top of the dashboard, you can view your Risk Score, a quick indicator of your business’s fraud health. Your score is placed in one of the following categories:

| Risk profile | Description |
| - | - |
| AAA | Secured |
| AA | Strong |
| A | Stable |
| B | Moderate |
| BB | Caution |
| BBB | Risky |

A higher score (AAA/AA) reflects a strong fraud posture with low dispute risk, while lower scores (BBB/BB) indicate increased exposure and the need for closer monitoring.

## Dispute ratio

**Dispute to Sales Ratio** is the total disputed amount (fraud + service) reported in a given time, divided by the total sales (GMV) processed in that time.

Dispute to Sales Ratio = Total disputed amount / Total sales (GMV).

You can toggle between **Dispute to Sales Ratio** and **Fraud to Sales Ratio** to compare against **Total Sales (GMV)** over **Daily**, **Weekly**, or **Monthly** periods.

<img alt="Dispute ratio visualisation" />

## Top metrics

This section gives you a quick snapshot of your key fraud and sales performance metrics for the selected time period.
The following metrics showcased are:

* **Total Sales (GMV)** : Total successful transaction volume.
* **Total Dispute Amount** : Value of all disputes reported in the selected duration.
* **Dispute to Sales Ratio** : Percentage of sales turning into disputes.
  <img alt="Top metrics visualisation" />

## RiskShield performance

This section gives you a detailed breakdown of how RiskShield is protecting your business.

You can monitor the following metrics:

* **Blocked Transactions**: Count of transactions blocked by RiskShield.
* **Blocked Amount**: Value of fraudulent attempts prevented.
* **Transactions in Review**: Transactions flagged for manual review.
* **Amount in Review**: Value of transactions under review.

The overall **Block Rate** is also displayed, representing the percentage of total transactions blocked.

You can toggle between **Transaction amount** and **Transaction count** to view trends over **Daily**, **Weekly**, or **Monthly** periods.

<img alt="Risk performance visualisation" />

## Fraud hotspots

Monitor where fraud originates to identify the top states and cities contributing to fraud volume. You can toggle between **States** and **Cities** to view specific fraud sources. For example, 100% of your frauds are from Karnataka. These insights help you identify geographical risk clusters and take actions such as tightening rules or reviewing suspicious locations.

<img />

## Payment mode split

Identify which payment methods contribute most to your disputes or fraudulent transactions.
The split may include:

* UPI
* Debit cards
* Credit cards
* Netbanking
* Wallets
* Other methods

For example: 45% of your frauds are from UPI.
This helps you monitor and adjust rules across different payment sources.

<img />

## Top dispute sources

This section lists the most frequent origins of disputes so you can identify repeat offenders and take preventive action.

RiskShield tracks disputes across multiple source types to help you pinpoint patterns:

* **Identity and contact sources**
  * IP address: Track disputes originating from specific IP addresses.
  * Phone number: Monitor phone numbers linked to disputed transactions.
  * Email address: Identify email addresses associated with fraudulent activity.

* **Payment sources**
  * UPI ID or VPA: Track disputes from specific UPI Virtual Payment Addresses.
  * BIN or masked card details: Monitor card ranges (Bank Identification Numbers) with high dispute rates.
  * Payment provider: Analyse dispute trends by payment gateway or provider.

* **Network sources**
  * IP type: Identify disputes from VPN, TOR, or Data Centre Hosting (DCH) networks.

For each dispute source, the dashboard displays:

* **Disputed amount**: Total value of disputes from this source.
* **Percentage contribution**: Percentage of your total disputes attributed to this source.
* **Last seen**: Most recent transaction from this source.
* **Trend of disputes**: Pattern showing whether disputes from this source are increasing or decreasing.

These insights help you decide which sources to block or monitor closely.

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

## Rule performance

Track the effectiveness of your RiskShield rules in preventing fraud. This section showcases your **Top Performing Rule**, highlighting the specific rule name along with the total **Amount Saved** and the number of **Transactions Blocked**.

For each rule, you can monitor:

* **Rule Name**: The name of the fraud prevention rule.
* **Blocked Transactions**: Number of transactions blocked by this rule.
* **Amount Saved**: Total value of fraudulent transactions prevented.
* **Date Added**: When the rule was created or activated.

This helps you understand which rules are most effective and identify where adjustments may be needed.

<img />


# Risky Transactions
Source: https://www.cashfree.com/docs/payments/risk-shield/risky-transactions

View Cashfree RiskShield flagged and blocked transactions in one place and drill into smart-rule and recommended-rule decisions for suspicious payments.

## View flagged transactions

You can view the suspicious transactions detected by Shield Pro and transactions that fall under the activated smart rules and recommended rules here. [For the transactions under the recommended rule(s), you chose to flag appear here](/docs/payments/risk-shield/smart-rules#managing-existing-smart-rules). Follow the instructions below to view the flagged transactions:

1. Log in to the **[Merchant Dashboard](https://merchant.cashfree.com/auth/login)**.
2. Go to **Payment Gateway** > **Riskshield** > **Risky Transactions** > **Flagged Transactions**.

<Frame>
  <img />
</Frame>

1. **Last 30 Days**: Use the dropdown menu to select the time period of the flagged transactions that you wish to view. You can select **Custom Data Range** to select a custom date range.
2. **Search & Filter**: Use the available filter options to retrieve the data and click **Apply**.
3. **Export**: Select this option to export the data.

<Frame>
  <img />
</Frame>

6. You can view the following data in the form of cards:
   * **Transaction Time**: It displays the number of transactions scanned.
   * **Transaction Id**: It displays the number of transactions.
   * **Amount**: It displays the amount protected because of blocking the transactions.
   * **Flagged Reason** -  It displays the reason for flagging the transaction for review.
   * **Refund / Acknowledge Txn**
     * **Refund**: Select this option to refund the flagged transaction.
     * **Acknowledge**: Select this option to acknowledge the flagged transaction.

<Frame>
  <img />
</Frame>

You can click a flagged transaction to view it in detail.

<Frame>
  <img />
</Frame>

***

### Refund flagged transaction

You can choose to refund the flagged transactions by following the instructions below:

1. From the *Flagged Transactions* screen, you can click **Refund** to proceed with the process or select the flagged transaction to view it in detail.
2. Click **Refund**.
3. In the *Initiate Refund* popup, enter the refund amount in the respective field and proceed.

<Frame>
  <img />
</Frame>

You have successfully initiated a refund for the flagged transactions.

***

### Acknowledge flagged transaction

You can choose to acknowledge the flagged transactions by following the instructions below:

1. From the *Flagged Transactions* screen, you can click **Acknowledge** to proceed with the process or select the flagged transaction to view it in detail.
2. Click **Acknowledge**.
3. In the *Confirm Acknowledgment* popup, click **Acknowledge**.

<Frame>
  <img />
</Frame>

You have successfully acknowledged a flagged transaction.

***

## View blocked transactions

You can view the transactions that we prevent or restrict from being processed. [For the transactions under the recommended rule(s), you chose to block appear here](/docs/payments/risk-shield/smart-rules#managing-existing-smart-rules). Follow the instructions below to view the blocked transactions:

1. Navigate to **Riskshield** > **Risky Transactions** > **Blocked Transactions**.

<Frame>
  <img />
</Frame>

2. **Last 7 Days**: Use the dropdown menu to select the time period of the blocked transactions that you wish to view. You can select **Custom Data Range** to select a custom date range.
3. You can view the following data in the form of cards:
   * **Transactions Scanned**: It displays the number of transactions scanned.
   * **Risky Transactions Blocked**: It displays the number of transactions.
   * **Amount Protected**: It displays the amount protected because of blocking the transactions.
4. You can view the following information of a blocked transactions:
   * **Date and Time**: It displays the date and time of the transactions.
   * **Order ID**: It displays the unique identifier of the order.
   * **Order Amount**: It displays the amount of the order.
   * **Transaction ID**: It displays the unique identifier of the transaction.
   * **Payment Mode**: It displays the mode of payment used for the transaction.
   * **Status**: It displays the status of the transaction.
   * **Block Reason**: It displays the reason for blocking the transactions.

<Frame>
  <img />
</Frame>


# Smart Rules
Source: https://www.cashfree.com/docs/payments/risk-shield/smart-rules

Use Cashfree Risk Shield Smart Rules to block or flag transactions automatically with When–Then logic, velocity checks, and AND/OR conditions.

Smart Rules allow merchants to create multi-condition fraud prevention systems across industries such as e-commerce, digital goods, travel, jewellery, utilities, and more.

The rule engine evaluates parameters, including transaction details, device signals, geographic data, payment modes, and other factors, to block fraudulent activity while allowing legitimate transactions to process seamlessly.

## Why choose smart rules

Smart Rules offer the following benefits:

* **Comprehensive coverage**: Over 30 risk parameters are evaluated in real time across devices, locations, identities, payments, and user behaviours to support advanced fraud detection strategies.

* **Flexible logic engine**: Supports advanced operators such as range-based filtering, multi-value matching, and nested AND/OR conditions, enabling precise and customisable rule creation.

* **Business-friendly interface**: Provides a visual rule builder with plain-language explanations and a pre-built rule library, enabling quick deployment without technical expertise.

* **Adaptive risk management**: Rules can be updated and refined in real time based on emerging fraud patterns, ensuring continuous protection without disrupting legitimate transactions.

* **Scalability**: Handles high transaction volumes without performance degradation, making it suitable for fast-growing or high-risk businesses.

## Use cases

You can apply Smart Rules to the following scenarios for threat protection:

| **Use case** | **Description** |
| - | - |
| New user deposit limits | Restricts high-value deposits for first-time users by enforcing a maximum limit of ₹1,00,000 when using credit cards. |
| Payment method restrictions | Limits the number of transactions by payment type. For example, restrict customers to a maximum of three Cash on Delivery (COD) orders per day. |
| Bank-specific transaction limits | Define transaction limits based on the issuing bank, particularly for non-3DS transactions. |
| Multi-condition risk assessment | Combine multiple risk factors, such as new user, VPA/TOR Transaction, high number of unique credit card usage, and unusually high transaction value, to create advanced rules for enhanced fraud protection. |
| High failure rate prevention | Blocks users with excessive failed transaction attempts. |
| IPG transaction-specific rules | Apply country-specific transaction limits, such as setting lower deposit caps for high-risk regions. |
| Velocity-based fraud prevention | Flags transactions when frequency and value thresholds are exceeded. |

## Smart rule logic and configuration parameters

Smart Rules are built using a simple **When–Then** logic structure, where conditions are defined under **When** and corresponding actions are executed under **Then**.
There are two types of Smart Rules:

## Conditional rules

These rules are executed in real time, based on specific conditions and fixed parameters.

**Example 1**: If the transaction amount is ≥ ₹50,000 AND the proxy type is VPN AND the city is Jamtara, then block further transactions.

<Frame>
  <img />
</Frame>

**Example 2**: If the transaction amount equals ₹10,000 OR the UPI VPA provider is Mobikwik, AND the city is Jamtara, then the system blocks further transactions to prevent potential fraud.

<Frame>
  <img />
</Frame>

### Conditional rule explanation

The above rule is designed to block transactions when specific high-risk conditions are met.

**WHEN**

* **Amount** = 10,000

OR

* **UPI VPA Provider** = Mobikwik

AND

* **City** = Jamtara

**THEN**

* **Block further transactions**.
* The user will be unable to complete this transaction or any other transaction that meets these conditions.
* No debit occurs from the user’s account.

The system checks if either the transaction amount is exactly ₹10,000 or the UPI VPA provider is Mobikwik. If this is true, and at the same time the transaction originates from the city of Jamtara, then the transaction is blocked, meaning the user cannot complete it.

## Aggregate rules

These are aggregated rules that consider a user's past transactions before triggering actions. They combine velocity checks with multiple conditions to create optimised, comprehensive rules.

**Example 1**: Limit the total successful transaction amount to ₹25,000 per card per hour.

<Frame>
  <img />
</Frame>

**Example 2**: If a single card number is linked to more than three mobile numbers in the past 24 hours, the system blocks further transactions to prevent potential fraud.

<Frame>
  <img />
</Frame>

### Aggregate rule explanation

The above rule is designed to prevent card sharing among users by preventing more than three mobile numbers from being linked to the same card for payment in a given day.

**WHEN**

* For each **Card Number**, the Number of linked parameters i.e **Mobile Number** is more than 3 within the last **Day**.

**THEN**

* **Block further transactions**.
* Prevents linking a fourth or additional mobile number to the same card for payments in that time period.

<Note>
  **By default, all rules follow the logic of successful transactions.**
  For example, if the rule is *Do not allow more than ₹25,000 per card per day,* it is interpreted as applying only to successful transactions. In other words, the rule prevents more than ₹25,000 in total successful GMV per card per day.
</Note>

## Rule outcomes

The two Smart Rule outcomes are:

* **Block further transactions**: Prevents any new transactions from being processed. Users will not be able to complete a transaction, and no debit will occur. In UPI Intent cases, a debit may still happen but is immediately refunded. All such attempts are marked as **FAILED** in Cashfree’s system.

* **Flag further transactions**: The transaction is processed like any regular transaction, and the merchant receives settlement as usual. However, the transaction is highlighted in the **Risky Transactions** section of RiskShield for monitoring and review.

## Smart rule parameters

Smart Rules evaluate transactions using the following parameter types to identify and prevent potential fraud attempts:

| **Parameter categories** | **Parameter name** |
| - | - |
| Transaction parameters | Amount |
| Payment status parameters | **Successful**: Transactions with status as `SUCCESS`.<br />**Attempted**: Total attempted transactions including `SUCCESS`, `FAILED`, `ABANDONED`, and all other transaction statuses.<br />**Failed**: Transactions with a terminal status of `FAILED`. |
| User parameters | Mobile number, Email address, UPI VPA, Payment mode, IP address, Card country, Card BIN, UPI VPA provider. |
| Location parameters | Country, State, City, Proxy type. |

## Conditional rule parameters

The following table lists the parameters available for creating conditional rules:

| **Parameter category** | **Parameter name** | **Type** | **Description** | **Examples** |
| - | - | - | - | - |
| Transaction parameters | Amount | Numerical | Exact transaction amount in INR. | 1,000; 25,000; 20,00,000 |
| User parameters | Mobile Number | Numerical or String | Mobile number of the customer used for the transaction. | 9876543210 |
| | Email Address | String | Email address of the customer. | [user-email@example.com](mailto:user-email@example.com) |
| | UPI VPA | String | UPI Virtual Payment Address. | user\@okhdfcbank; name\@paytm |
| | Payment Method | Categorical | Type of payment method used. | Net Banking; Credit Card; Debit Card; UPI; COD; Pay later |
| | UPI VPA Provider | Categorical | Provider associated with the UPI VPA. | Freecharge; Mobikwik |
| | IP Address | Numerical or String | Static IP address of the customer’s device or network. | 192.168.1.1; 103.45.67.89 |
| | Card Country | Categorical | Country where the card was issued. | Russia; USA; Australia |
| | Card BIN | Numerical | First 6–8 digits of the card (Bank Identification Number). | 411111; 51234567 |
| Location parameters | Country | Categorical | Country from which the transaction is initiated. | USA; UK; Singapore |
| | State | Categorical | State of the transaction origin. | Maharashtra; Karnataka; Delhi |
| | City | Categorical | City of the transaction origin. | Mumbai; Bengaluru; Delhi |
| | Proxy Type | Categorical | Type of proxy detected for the transaction. | VPN; TOR; DCH; None |

## Aggregate rule parameters

The following tables lists the parameters available for creating aggregate rules:

### Aggregation setup parameters

| **Parameter category** | **Type** | **Description** | **Possible values** |
| - | - | - | - |
| Base parameter | Categorical | Primary entity used for aggregation. | Card Number, Mobile Number, Email ID, UPI Handle, IP Address |
| Aggregation type | Categorical | Metric used to aggregate. | Count, Sum, Number of Linked Parameters |
| Linked parameter | Categorical | Used only when “Number of Linked Parameters” is selected. | Card Number, Mobile Number, Email ID, UPI Handle, IP Address |
| Duration | Categorical | Time range for aggregation. | 5 min, 1 hour, 1 day, 7 days, 15 days, 30 days |

### Filter criteria parameters

| **Parameter category** | **Parameter name** | **Type** | **Description** | **Examples** |
| - | - | - | - | - |
| Transaction parameters | Amount | Numerical | Filters transactions within or above a specified value range before aggregation. | 1,000; 25,000; 20,00,000 |
| User parameters | Card Country | Categorical | Restricts aggregation to specific card-issuing countries. | Ethiopia; Yemen; Pakistan |
| Payment status parameters | Transaction Status | Categorical | Filters transactions by outcome. | Success; Failed; Attempted |

## Create a smart rule

Follow these steps to build a Smart Rule based on transaction criteria:

1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
2. Navigate to **RiskShield** > **Smart Rules**.
3. Click **Create Smart Rule**.
4. Enter a descriptive **Rule Name**.
5. Configure the **When** conditions:
   1. Select the type of filtering from the dropdown menu, such as **Condition** or **Aggregate** based.
   2. Select the parameter used to evaluate transactions on.
   3. Select the specific operator based on the chosen parameter.
   4. Enter the comparison value(s).
   5. Click **Add Condition Set** for additional conditions with AND/OR logic.
6. Configure the **Then** outcome: **Block** or **Flag further transactions**.
7. Review the auto-generated rule **Explanation** in English for verification.
8. Click **Confirm Rule** to create the new rule.
   <img alt="" />

## Managing existing smart rules

Once created, all configured Smart Rules appear in a comprehensive dashboard table under the Smart Rules section, providing complete visibility and control over your fraud prevention system.

### Rule dashboard overview

The Smart Rules dashboard displays three main categories:

* **All Rules**: Complete list of all configured rules which includes activated and deactivated rules.

* **Active Rules**: Currently enabled and executing rules.

* **Recommended**: Pre-configured rules suggested by Cashfree for fraud prevention use.

The rule status indicators available are:

* **Active**: The rule is currently enabled and actively monitoring transactions.
* **Inactive**: The rule is disabled and not monitoring transactions.
* **Recommended**: The rule is suggested by Cashfree based on transaction patterns and risk factors.

| **Field** | **Description** |
| - | - |
| Rule Name | A descriptive name is assigned to the rule for easy identification. |
| Rule Actions | Action type configured for each rule is: Block or Flag for Review. |
| Triggers | Number of times the rule was triggered. |
| Amount Impacted | Total monetary value saved through fraud prevention which includes both blocked and flagged transaction amounts. |
| Created On | Date and time when the rule was initially created. |
| Status | Current rule statuses are: Active or Inactive. |
| Actions | Available rule management options are: Edit, Delete, Activate, Deactivate. |

## Scenario examples

The following examples show practical Smart Rule configurations with real-world scenarios. Each example illustrates the conditions, actions, and outcomes to guide effective fraud-prevention strategy setup.

### Conditional rule-based scenarios

The following scenarios illustrate common situations where conditional rule-based filtering enhances fraud detection and transaction control.

<Tabs>
  <Tab title="VPN transactions">
    **Scenario**: High-value transaction from VPN.\
    **Objective**: Detect and block transactions over 50,000 initiated from VPN connections to mitigate fraud risk.\
    **Rule configuration**: Amount >= 50,000 and Proxy Type Is = VPN.\\

    <img alt="Rule setup for VPN scenario" />
  </Tab>

  <Tab title="Credit card limits">
    **Scenario**: High-value transaction via credit card.\
    **Objective**: Identify and block transactions exceeding 100,000 made through credit card payments to prevent potential fraud.\
    **Rule configuration**: Amount > 100,000 and Payment Mode Is = Credit Card.\\

    <img alt="Rule setup for Credit Card scenario" />
  </Tab>

  <Tab title="High-risk cities">
    **Scenario**: High-value transactions from high-risk cities.\
    **Objective**: Detect and flag transactions over 50,000 originating from high-risk locations such as Patna to prevent fraudulent activity.\
    **Rule configuration**: Amount > 50,000 and City Is = Patna.

    <img alt="Rule setup for High-Risk Cities scenario" />
  </Tab>

  <Tab title="High-risk countries">
    **Scenario**: Payments from high-risk countries.\
    **Objective**: Block further transactions originating from high-risk countries such as Pakistan when any transaction exceeds 1 in value.\
    **Rule configuration**: IP Country = Pakistan and Transaction Amount > 1.

    <img alt="Rule setup for High-Risk Countries scenario" />
  </Tab>
</Tabs>

### Aggregated rule-based scenarios

The following scenarios highlight common use cases where aggregate rule-based monitoring helps detect abnormal patterns and prevent fraudulent activity.

<Tabs>
  <Tab title="Mobile frequency">
    **Scenario**: Multiple successful transactions per mobile in short interval.\
    **Objective**: Block cases where a single mobile number completes more than three successful transactions within five minutes to prevent rapid fraud attempts.\
    **Rule configuration**: Base parameter = Mobile Number, aggregation type = Count, duration = 5 minutes, condition = Count > 3.\\

    <img alt="Rule setup for Mobile Frequency scenario" />
  </Tab>

  <Tab title="Card attempts">
    **Scenario**: Maximum number of attempts per card.\
    **Objective**: Prevent excessive transaction attempts by blocking any card with more than ten attempts within one hour to reduce brute-force or testing attacks.\
    **Rule configuration**: Base parameter = Card Number, aggregation type = Count, duration = 1 hour, condition = Count > 10.

    <img alt="Rule setup for Card Attempts scenario" />
  </Tab>

  <Tab title="Card testing">
    **Scenario**: Multiple card testing per IP address.\
    **Objective**: Block IP addresses that attempt transactions with more than 5 unique cards in a 1-day period to stop card-testing attacks.\
    **Rule configuration**: Base parameter = IP Address, aggregation type = Number of Linked Parameters, linked parameter = Card Number, duration = 1 day, condition = Number of Linked Parameters > 5.\\

    <img alt="Rule setup for Card Testing scenario" />
  </Tab>

  <Tab title="Card sharing">
    **Scenario**: Multiple mobile numbers linked to the same card.\
    **Objective**: Block transactions when more than three distinct mobile numbers are linked to a single card within a 1-day period to prevent account misuse or credential sharing.\
    **Rule configuration**: Base parameter = Card Number, aggregation type = Number of Linked Parameters, linked parameter = Mobile Number, duration = 1 day, condition = Number of Linked Parameters > 3.

    <img alt="Rule setup for Card Sharing scenario" />
  </Tab>
</Tabs>


# Whitelists
Source: https://www.cashfree.com/docs/payments/risk-shield/whitelists

Add trusted customers to your Cashfree RiskShield whitelist using card, phone, email, IP, or device data so their transactions bypass risk rules.

Cashfree lets you create a whitelist for trusted customers. When you add a customer to your whitelist, RiskShield allows their transactions, even if they match other risk rules. You can whitelist using the following details:

* [Mobile Number](/docs/payments/risk-shield/whitelists#mobile-number)
* [Email ID](/docs/payments/risk-shield/whitelists#email-id)
* [UPI Handle](/docs/payments/risk-shield/whitelists#upi-handle)
* [Cities](/docs/payments/risk-shield/whitelists#cities-india)
* [IP Address](/docs/payments/risk-shield/whitelists#ip-address)
* [Card Numbers](/docs/payments/risk-shield/whitelists#card-numbers)
* [UPI Provider](/docs/payments/risk-shield/whitelists#upi-provider)

## Navigation

1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
2. Go to **Payment Gateway > RiskShield > My Lists**.
3. Select the **Whitelists** tab.
4. Click **Add Whitelist**.

## Mobile number

Whitelist a mobile number to let trusted customers process transactions without interruptions.

To add a mobile number to your whitelist:

1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
2. Go to **Payment Gateway > RiskShield > My Lists**.
3. Select the **Whitelists** tab.
4. Click **Add Whitelist** > **Mobile Number**.
5. In the *Add Mobile Number to Whitelist* window, do the following:
   * **Single Mobile Number**: Enter the mobile number.
   * **Multiple Mobile Numbers**: Download the sample file, enter the mobile numbers in the specified format, and upload the file.
6. Click **Add Now**.

<Frame>
  <img />
</Frame>

## Email ID

Whitelist an email ID to let transactions from trusted customers.

To add an email ID to your whitelist:

1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
2. Go to **Payment Gateway > RiskShield > My Lists**.
3. Select the **Whitelists** tab.
4. Click **Add Whitelist** > **Email ID**.
5. In the *Add Email ID to Whitelist* window, do the following:
   * **Single Email ID**: Enter the email ID.
   * **Multiple Email IDs**: Download the sample file, enter the email IDs in the specified format, and upload the file.
6. Click **Add Now**.

<Frame>
  <img />
</Frame>

## UPI handle

Whitelist a UPI handle to let transactions through specific trusted VPAs.

To add a UPI handle to your whitelist:

1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
2. Go to **Payment Gateway > RiskShield > My Lists**.
3. Select the **Whitelists** tab.
4. Click **Add Whitelist** > **UPI Handle**.
5. In the *Add UPI Handle to Whitelist* window, do the following:
   * **Single UPI Handle**: Enter the UPI VPA.
   * **Multiple UPI Handles**: Download the sample file, enter the UPI handles in the specified format, and upload the file.
6. Click **Add Now**.

<Frame>
  <img />
</Frame>

## Cities (India)

Whitelist cities to let transactions from trusted locations.

To add a city to your whitelist:

1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
2. Go to **Payment Gateway > RiskShield > My Lists**.
3. Select the **Whitelists** tab.
4. Click **Add Whitelist** > **Cities**.
5. In the *Add Cities to Whitelist* window, do the following:
   * **Country**: India is selected by default.
   * **State**: Select the state.
   * **City**: Select the city.
6. Click **Add Now**. Repeat this process to add more cities.

<Frame>
  <img />
</Frame>

## IP address

Whitelist an IP address to let transactions from trusted networks.

To add an IP address to your whitelist:

1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
2. Go to **Payment Gateway > RiskShield > My Lists**.
3. Select the **Whitelists** tab.
4. Click **Add Whitelist** > **IP Address**.
5. In the *Add IP Address to Whitelist* window, enter the IP address.
6. Click **Add Now**.

<Frame>
  <img />
</Frame>

## Card numbers

Whitelist specific card numbers or BINs to let transactions for trusted customers. Contact your account manager to enable card number whitelisting at the BIN level.

To add card numbers to your whitelist:

1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
2. Go to **Payment Gateway > RiskShield > My Lists**.
3. Select the **Whitelists** tab.
4. Click **Add Whitelist** > **Card Numbers**.
5. In the *Add Card Numbers to Whitelist* window, do the following:
   * **Single Card Number or BIN**: Enter the card number or BIN.
   * **Multiple Card Numbers or BINs**: Download the sample file, enter the card numbers in the specified format, and upload the file.
6. Click **Add Now**.

<Frame>
  <img />
</Frame>

## UPI provider

Whitelist a UPI provider to let transactions from specific trusted providers.

To add a UPI provider to your whitelist:

1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
2. Go to **Payment Gateway > RiskShield > My Lists**.
3. Select the **Whitelists** tab.
4. Click **Add Whitelist** > **UPI Provider**.
5. In the *Add UPI Provider to Whitelist* window, select the UPI provider from the list.
6. Click **Add Now**.

<Frame>
  <img />
</Frame>


# BNPL Plus Plugin
Source: https://www.cashfree.com/docs/payments/shopify/bnpl

Add the Cashfree BNPL Plus widget to your Shopify product pages to surface BNPL offers and EMI options that boost conversion before customers reach checkout.

BNPL Plus is a display tool you can add on your product page that will display offers and EMI options at the product page.

## Prerequisites

* Credentials to log in to your Shopify account.
* Register for an [account with Cashfree](https://merchant.cashfree.com/merchants/signup) before you start integration.

## Integration steps

1. Use the [installation link](https://apps.shopify.com/cashfree-smartsell) to install the app from the Shopify app store.
2. Click on **Apps**> **App Name**. Configure the App by providing your Cashfree App ID, and select the required options such as Offers, Pay Later, and EMI. Click **Save**. You can access the Cashfree App ID from the Developers section. Read more to know more about [API keys](/docs/api-reference/authentication#generate-api-keys).

<img alt="" />

3. Go to **Shopify store admin** > **Sales channels** > **Online Store** > **Themes** and click **Customise**.

<img alt="" />

4. Select the product from the default product drop-down menu. For example: **Products** -> **Default** **product**. Select the desired theme and customise your page. An image of the product page before the addition of BNPL Plus is shown below.

<img alt="" />

5. Click the **Add block** option and select **offer widget extension**. Drag this block and place it below the product price preferably or place it according to your convenience. Click **Save**.

<img alt="" />

BNPL Plus is now successfully integrated with Shopify. You can see the BNPL Plus enabled on the product page. The image below shows how the app looks on the Shopify product page after successful integration.

<img alt="" />

<Note>
  BNPL Plus Widget is only supported for production environment. Also online store 2.0 Shopify themes are supported.
</Note>


# One Click Checkout for Shopify
Source: https://www.cashfree.com/docs/payments/shopify/one-click-checkout

Activate and integrate Cashfree One Click Checkout on your Shopify store with this step-by-step guide for onboarding, configuration, and going live.

Follow these steps to onboard and activate One Click Checkout (OCC) on your Shopify store.

### Prerequisites

Before proceeding with the installation, complete the following steps:

1. Complete the [Cashfree support form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) or contact your account manager.
2. Create and share the collaborator request code. Use these steps:

   1. **Log in** to your Shopify store using your admin credentials.

   2. Navigate to **Settings > Users and permissions**.

   3. Scroll down to the **Collaborators** section and copy the collaborator request code.

   4. Share your Shopify store URL.

<Note>
  To approve a collaborator request in Shopify: log in to your Shopify Admin dashboard, navigate to **Settings > Users and Permissions**, scroll to the **Collaborators** section, and click **Review requests** to view pending requests. Select the specific request, check the permissions under the **Roles** section, and approve the request. If you see an error stating "The role name already exists", delete the auto-generated role and assign an existing one instead.
</Note>

3. Within 48 hours, you receive an app installation link, dashboard details, and setup instructions from Cashfree at your registered email address.

### Installation

To install the OCC app on Shopify:

1. Open the installation link, then **Log in** to Shopify to complete the installation.

2. Shopify redirects you to the **[Merchant Dashboard](https://merchant.cashfree.com/auth/login)** to finalise the installation.

3. To confirm the installation, check the installed apps in Shopify. The app should be listed as `cashfree-occ-<brand>`.

4. You can now access your One Click Checkout dashboard.

<Frame>
  <video>
    <source type="video/mp4" />

    Your browser does not support the video tag.
  </video>
</Frame>

### Configure theme

Follow these steps to configure checkout on Shopify:

1. **Log in** to Shopify using your credentials.

2. Navigate to **Sales channels > Online Store > Themes**.

3. Select the ellipsis (⋮) next to the live theme, then select **Duplicate** to create a copy.

4. Select the ellipsis (⋮) next to the duplicated theme, then select **Edit code**.

5. Search for and open the `theme.liquid` file.

6. Add the following code before the `</head>` tag:

   ```liquid theme={"dark"}
   {% render 'cashfree' %}
   ```

7. Select the ellipsis (⋮) next to the duplicated theme, then select **Preview**. Review and confirm the checkout.

8. Select **Publish** to set the updated theme as live.

<Frame>
  <video>
    <source type="video/mp4" />

    Your browser does not support the video tag.
  </video>
</Frame>

<Note>
  OCC setup is specific to your Shopify theme. If you change your store's theme, fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) to have Cashfree re-configure One Click Checkout on the new theme. International order redirection also needs separate re-configuration on the new theme.
</Note>

## Frequently asked questions

For answers to common questions about COD and shipping profile setup, Shopify conversion-data syncing, and native checkout fallback scenarios, see the [One Click Checkout FAQs](/docs/payments/checkout/one-click-checkout-faq).

## FAQs

<AccordionGroup>
  <Accordion title="Why is One Click Checkout not triggering from my website's side cart?">
    If you are using a third-party side cart plugin, One Click Checkout may not trigger automatically. This requires a configuration adjustment by the Cashfree technical team to ensure checkout is triggered correctly from both the side cart and the Buy button. Contact the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) to request this adjustment.
  </Accordion>
</AccordionGroup>


# Shopify
Source: https://www.cashfree.com/docs/payments/shopify/overview

Manage Shopify checkout with Cashfree plugins for payments, One Click Checkout, and BNPL Plus, designed to grow conversions for Indian Shopify merchants.

If you are running your store on Shopify, Cashfree offers various plugins to make selling easier for you.

These plugins offer the following benefits:

* Improve conversion on your checkout
* Manage COD effectively

<CardGroup>
  <Card title="Payments Plugin" icon="cart-shopping" href="/docs/payments/shopify/payments">
    Redirection based checkout on Shopify and card payments on Shopify Checkout.
  </Card>

  <Card title="One Click Checkout" icon="bolt" href="/docs/payments/checkout/one-click-checkout">
    Pre-fill addresses and manage COD and RTO on Cashfree Checkout.
  </Card>

  <Card title="Cash on Delivery" icon="box" href="https://apps.shopify.com/cod-order-confirmation-1">
    Manage COD on Shopify Checkout, verify COD orders, and convert COD orders to prepaid.
  </Card>

  <Card title="Conversion Tools" icon="chart-line" href="/docs/payments/checkout/cart-recovery">
    Recover abandoned orders and manage discounts and payment offers.
  </Card>
</CardGroup>


# Cashfree Plugin for Shopify
Source: https://www.cashfree.com/docs/payments/shopify/payments

Set up payments on your Shopify store with the Cashfree no-code plugin to accept Indian payment methods like cards, UPI, netbanking, and wallets.

Accept payments instantly on your Shopify store with our no-code payment gateway. We support all major payment methods including:

* UPI
* Credit Cards
* Debit Cards
* Net Banking
* Wallets
* Buy Now Pay Later (BNPL)

Cashfree provides following plugin options for Shopify integration:

* **Standard Shopify payment plugin** (listed on Shopify as **1Cashfree**): Supports all major payment methods, including UPI, credit cards, debit cards, net banking, wallets, and Buy Now Pay Later (BNPL).

* **Direct card payments plugin (manual setup)** (listed on Shopify as **Cashfree Payments - Cards**): Supports only credit and debit card payments through Shopify’s native checkout flow.

* **1Cashfree plugin**: A separate Shopify payment provider from the Direct card payments plugin. Install it from Shopify Admin by searching for **1Cashfree**. See [Install the 1Cashfree plugin on Shopify](#install-the-1cashfree-plugin-on-shopify).

<Note>
  We have introduced a new, simpler way for merchants to install Shopify using the following link:
  [Cashfree: Shopify App Store](https://apps.shopify.com/cashfree-payments).
  This method enables merchants to integrate Shopify with Cashfree seamlessly, complementing our traditional approach.
</Note>

## Prerequisites

* Credentials to log in to your Shopify account.
* Register for an [account with Cashfree](https://merchant.cashfree.com/merchants/signup) before you start integration.(Optional)

## Setup process

### 1. Complete your KYC

<Steps>
  <Step title="Login to Dashboard">
    Visit the [Cashfree dashboard](https://merchant.cashfree.com/)
    using the login credentials used at the time of installation
  </Step>

  <Step title="Submit KYC">
    Complete your KYC verification to start accepting payments
  </Step>
</Steps>

### 2. Activate the plugin

After installation, the plugin redirects you to an authentication page. Log in using your Cashfree-registered email address, then click the **Activate** button in your Shopify settings to enable Cashfree at checkout:

<Frame>
  <img alt="Activate Cashfree" />
</Frame>

### 3. Configure payment settings

#### Enable automatic payment capture

We recommend turning on automatic payment capture to avoid manual order processing:

<Steps>
  <Step title="Navigate to Settings">
    <Frame>
      <img alt="Go to Payment Settings" />
    </Frame>
  </Step>

  <Step title="Enable Auto-Capture">
    <Frame>
      <img alt="Enable Automatic Capture" />
    </Frame>
  </Step>
</Steps>

## Direct card payments

Enable direct card payments through Shopify's checkout:

<Frame>
  <img alt="Card Payments Demo" />
</Frame>

### Setup steps

<Steps>
  <Step title="Open Settings">
    <Frame>
      <img alt="Shopify Settings" />
    </Frame>
  </Step>

  <Step title="Find Payment Providers">
    <Frame>
      <img alt="Payment Providers" />
    </Frame>
  </Step>

  <Step title="Select Cashfree">
    <Frame>
      <img alt="Select Cashfree" />
    </Frame>
  </Step>

  <Step title="Connect Account">
    <Frame>
      <img alt="Connect Account" />
    </Frame>
  </Step>
</Steps>

## Test mode integration

<Tip>
  You can perform an end-to-end simulation of funds flow in the Test Mode. Once
  confident that the installation and integration is working as expected, switch
  to the Live Mode and start accepting payments from customers.
</Tip>

Follow these steps to verify your integration in test mode:

#### Enable test mode

1. Log in to your Shopify store
2. Go to Settings → Payments
3. In Supported Payment Methods, click Manage on Cashfree
4. Scroll down and enable Test mode
5. Click Save

*Switch off test mode to start accepting payments*

## Important notes

<Note>
  If you change your Shopify domain, remember to: - Whitelist the new domain in
  Cashfree dashboard from
  the **[Merchant Dashboard](https://merchant.cashfree.com/auth/login)** and go to **Payment Gateway > Developers > Whitelisting** -
  Reconnect the plugin to update settings
</Note>

<Note>
  Cashfree does not currently support customising the payment method name, description, or other text that the Cashfree plugin displays on the Shopify checkout page.
</Note>

<Tip>
  Enable mandatory phone number collection in [Shopify checkout
  settings](https://help.shopify.com/en/manual/checkout-settings/checkout-form-options)
</Tip>

## Report reconciliation

Match transactions between Shopify and Cashfree using:

* Shopify's `Payment ID` column in the shopify report.
* Cashfree's `Order Id` column in the [Transaction Report](https://merchant.cashfree.com/merchants/pg/reports)

The Shopify Payment ID is passed to Cashfree as the `order_id`. Cashfree's `order_id` in turn maps to Cashfree's `cf_payment_id`. You can use the Cashfree `order_id` to retrieve payment details via Cashfree APIs or webhooks.

## Install the 1Cashfree plugin on Shopify

The 1Cashfree plugin is a separate Shopify payment provider from the Direct card payments plugin. To install and activate it on your Shopify store:

1. Log in to your Shopify Admin.
2. Navigate to **Settings** from the bottom-left corner.
3. Select **Payments**.
4. Select **Add Payment Provider**.
5. Select **Search by Provider** and search for **1Cashfree**.
6. Install the 1Cashfree plugin.
7. After installation, scroll down to the **Payment Providers** section and activate the plugin.

<Note>
  Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) with your registered email address during this process so the correct account is mapped.
</Note>

## Frequently asked questions

The following questions cover common Shopify integration and checkout issues.

<AccordionGroup>
  <Accordion title="How do I find and install the Cashfree Payments plugin on Shopify to enable all payment modes including UPI?">
    To enable all Cashfree payment modes (including UPI) on your Shopify store, install the **1CashfreePayments** plugin:

    1. Log in to your Shopify Admin.
    2. Go to **Settings > Payments**.
    3. Under **Payment providers**, select **Choose a provider**.
    4. Search for **1CashfreePayments** under the **Third-party providers** section.
    5. Select **Install** and follow the prompts to log in with your Cashfree registered email ID to complete activation.

    For more details, see the [setup process](/docs/payments/shopify/payments#setup-process).
  </Accordion>

  <Accordion title="Why is Google Pay (GPay) or Paytm not showing under the Wallets section in checkout?">
    GPay, Paytm, and PhonePe are primarily UPI-based payment methods, not prepaid wallet products. They appear under the **UPI** section of your checkout, not the Wallets section.

    The Wallets section is reserved for prepaid wallet products such as MobiKwik, OLA Money, and Airtel Money. GPay does not have a prepaid wallet product and appears only as a UPI option.

    These apps appear in the UPI section in two ways:

    * **UPI QR Code**: Customers scan a QR code using any UPI app (GPay, PhonePe, Paytm). This is the standard option for desktop checkouts.
    * **UPI Intent (app icons)**: Individual app icons appear for customers to tap and open the app directly. This is typically available on mobile browsers. For Shopify stores using the 1CashfreePayments plugin, the plugin handles UPI Intent automatically on mobile devices.
  </Accordion>

  <Accordion title="How do I complete the setup for the Cashfree Payments - Cards plugin on Shopify?">
    To set up the Cashfree Payments - Cards app for direct card payments on Shopify:

    1. In your Shopify Admin, go to **Settings > Payments**.
    2. Under payment providers, locate and open **Cashfree Payments - Cards**.
    3. Select **Manage account** or **Connect Account**.
    4. Log in using the Cashfree account or registered email associated with your merchant account.
    5. Make sure your Cashfree account KYC activation is complete before proceeding.
    6. Return to **Settings > Payments** to verify that Cashfree appears as an active payment provider.

    If you are testing, enable **Test mode** in the payment settings. Remember to disable Test mode before going live to accept real payments.

    For detailed setup instructions, see [Direct card payments](/docs/payments/shopify/payments#direct-card-payments).
  </Accordion>

  <Accordion title="Why are my Shopify orders showing as Authorized instead of Paid after a successful transaction?">
    If orders remain in the **Authorized** state after payment, check the Payment Capture Method in Shopify. Go to **Settings > Payments > Payment Capture Method** and set it to **Automatically at checkout**. If you set it to **Manually**, you must capture the payment in Shopify before the order status updates to Paid.
  </Accordion>

  <Accordion title="Why are some orders being redirected to the native Shopify Checkout instead of Cashfree Checkout?">
    Orders may fall back to native Shopify Checkout in the following situations:

    * **Inventory issues**: The item is out of stock or has zero quantity.
    * **Network interruptions**: Technical connectivity issues can cause the checkout flow to default to Shopify's native checkout.
  </Accordion>

  <Accordion title="Why is UPI not appearing as a payment option?">
    UPI is available as a payment method only when the order currency is INR.
  </Accordion>

  <Accordion title="Why is IGST being charged or displayed separately on my Shopify orders?">
    If you enable taxes for your Shopify store, Shopify may calculate and display IGST separately on the order page. Go to **Settings > Taxes and duties** in your Shopify Admin to update your tax configuration. You can also configure your store to show prices inclusive of taxes, if required. For specific tax calculation logic, contact Shopify Support, since Shopify manages these settings.
  </Accordion>

  <Accordion title="How can I automatically add a tag to Shopify orders when a customer provides GSTIN information?">
    Cashfree cannot automatically add a GSTIN tag to Shopify orders. Shopify restricts payment apps from passing payment-related information into Order Tags.

    Cashfree passes GSTIN information in the **Additional Information** section of the order. To tag these orders automatically, build a custom Shopify Flow. Go to **Apps > Flow** in your Shopify Admin and create a flow that adds a GSTIN tag when GST information is present in the order.

    <Note>
      * Cashfree has introduced order tags in Shopify that include payment and discount details. Merchants experiencing a mismatch between the paid amount (such as with the 5% UPI discount) and the Shopify order total can resolve this by reinstalling the Cashfree plugin.
      * Match transactions using Shopify's `Payment ID` and Cashfree's `Order Id` as described in [Report reconciliation](#report-reconciliation).
    </Note>
  </Accordion>

  <Accordion title="Why is PayPal not showing, or why is the Activate button disabled in my Shopify payment settings?">
    These issues occur when you install the **Cashfree Payments - Cards** app instead of the **1Cashfree** plugin. The Cashfree Payments - Cards app does not support PayPal or the full Cashfree checkout experience.

    To resolve this, install the correct plugin from the [Shopify App Store](https://apps.shopify.com/cashfree-payments). After installation, complete the account connection in Shopify to activate the payment gateway. PayPal and all other supported payment methods then appear on the Cashfree checkout.
  </Accordion>

  <Accordion title="Does Cashfree support the CODFIRM login widget for Shopify?">
    Cashfree does not support the CODFIRM login widget. Using the CODFIRM login widget with Shopify New Customer Accounts can cause a "Missing CAPTCHA token" error. Uninstall the CODFIRM login widget and use the standard Shopify Customer Account Login flow.

    Cashfree does not currently offer an alternative Shopify-based customer login for deprecated or New Customer Accounts. A native Cashfree Customer Login flow for Shopify is under development, with no confirmed availability date. Use the standard Shopify Customer Account Login flow until then.
  </Accordion>

  <Accordion title="Why are Shopify order cancellations not triggering automatic refunds in Cashfree when using Shiprocket Checkout?">
    If you use Shiprocket Checkout, Shiprocket manages the refund flow. When you cancel an order in Shopify, Shopify notifies Shiprocket, and Shiprocket calls the Cashfree [Create Refund API](/docs/api-reference/payments/latest/refunds/create-refund). If refunds do not start, contact the Shiprocket team to confirm they received the Shopify request and initiated the refund call to Cashfree.
  </Accordion>
</AccordionGroup>

## Need help?

Submit a request through the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) for assistance with your integration.

<div>
  <iframe title="How to Setup Cashfree on Shopify" />
</div>

<div>
  <p>Affiliate partner program</p>

  <p>As a developer building payment experiences for your clients, you can earn additional income while providing them with industry-leading payment solutions.</p>

  <p>Join the <a href="https://partner.cashfree.com/partner-ui/authentication/signup?source-action=Affiliate%20Program%20LP&action=Sign%20Up&button-id=StartNow_CashfreeAffiliatePartnerProgram">Cashfree affiliate partner program</a> and get rewarded every time your clients use Cashfree.</p>

  <p>**What you get:**</p>

  <ul>
    <li>Earn up to 0.25% commission on every transaction.</li>
    <li>Become a trusted fintech partner for your clients.</li>
    <li>Access to a dedicated partner manager for expert support.</li>
  </ul>

  <p>**What your clients get:**</p>

  <ul>
    <li>Instant activation and go live in minutes.</li>
    <li>Industry-best success rate across all payment modes.</li>
    <li>Effortless acceptance of international payments in 140+ currencies.</li>
  </ul>

  <p>Get started today. <a href="https://partner.cashfree.com/partner-ui/authentication/signup?source-action=Affiliate%20Program%20LP&action=Sign%20Up&button-id=StartNow_BecomeAPartner">Become a partner now</a>.</p>
</div>


# Agent Collection Point
Source: https://www.cashfree.com/docs/payments/softpos/agent-collection-mode

Set up softPOS Agent Collection Point on the Cashfree Pulse app, log in with OTP, and accept payments through static QRs, dynamic QRs, and payment links easily.

Once an agent is verified, they can install the softPOS application and begin collecting payments from the **New Payment** screen.

## Install and log in to the softPOS application

Before collecting payments, each agent must install the softPOS application and complete OTP verification to log in.

<Steps>
  <Step title="Install the application">
    Download and install the **Cashfree softPOS application** on the agent's **Android device**.

    <AccordionGroup>
      <Accordion title="Android on Google Play" icon="android">
        Scan the QR code with your Android device camera, or use the download link below.

        <img alt="Cashfree softPOS QR Code" />

        **Download link:** [Cashfree softPOS on Google Play](https://play.google.com/store/apps/details?id=com.cashfree.softpos)
      </Accordion>
    </AccordionGroup>
  </Step>

  <Step title="Enter the registered mobile number">
    Launch the application and enter the mobile number registered with Cashfree, then tap **Send OTP**.
  </Step>

  <Step title="Complete OTP verification">
    Enter the OTP received on the registered number. After the agent completes OTP verification and logs in, their profile details appear in the **Profile** section. The agent can then start collecting payments from customers.
  </Step>
</Steps>

<Note>
  The softPOS application is available only on Google Play. It is not currently available on the iOS App Store or any other app marketplaces.
</Note>

## Payment methods

The softPOS application supports the following payment methods. Select the appropriate method on the **Payment Details** screen before tapping **Accept Payment**.

<Tabs>
  <Tab title="QR code">
    The softPOS application supports two types of QR codes:

    * **Static QR code**: Reusable for multiple payments; the customer enters the amount at payment time.
    * **Dynamic QR code**: Generated per transaction with a fixed amount the customer cannot change.

    <Frame>
      <img alt="softPOS Payment Details screen with store name, amount field, QR Code payment method selected, customer mobile number, invoice number, optional order note, and Accept Payment button" />
    </Frame>

    ### Static QR code

    A static QR code is a single, reusable QR code unique to the business. Use it to collect multiple payments without specifying an amount. The customer enters the amount during payment.

    To use a static QR code, complete the following steps:

    1. In the softPOS application, tap **QR Code** and select **Static QR**.
    2. Download or share the QR code with your customers. Customers can scan it using any UPI app such as Google Pay, PhonePe, or Paytm, then enter the amount to pay.
    3. Once the customer completes the payment, the agent receives a confirmation notification.

    ### Dynamic QR code

    A dynamic QR code is generated per transaction and includes a specified amount. The customer cannot change the amount when scanning.

    To generate a dynamic QR code, complete the following steps:

    1. In the softPOS application, tap **QR Code**.
    2. Enter the amount to collect from the customer.
    3. Optionally, enter any of the following details:
       * **Customer mobile number**: Identifies the payer.
       * **Invoice number**: A unique reference for accounting and reconciliation.
       * **Order note**: Additional details to store with the transaction.
    4. Display or share the QR code with the customer. The agent receives a notification once the payment is complete.

    <Warning>
      Dynamic QR codes time out. If the timer expires before the customer scans the QR code, regenerate the order by re-entering all details on the **New Payment** screen. If the customer already scanned the QR code before the timer expires, they can continue the transaction. Check payment status on the **Payments** tab by pulling down to refresh.
    </Warning>
  </Tab>

  <Tab title="Payment link">
    A payment link sends an SMS to the customer's phone with a link to a hosted payment page. Customers can pay using debit or credit cards, UPI, wallets, net banking, or Pay Later.

    <Frame>
      <img alt="softPOS Payment Details screen with store name, amount field, Payment Link payment method selected, customer mobile number, invoice number, optional order note, and Accept Payment button" />
    </Frame>

    To collect payments using a payment link, complete the following steps:

    1. In the softPOS application, tap **Payment Link**.
    2. Enter the amount to collect from the customer.
    3. Enter the customer's mobile number. Cashfree sends the payment link to this number via SMS.
    4. Optionally, enter any of the following details:
       * **Invoice number**: A unique reference for accounting and reconciliation.
       * **Order note**: Additional details to store with the transaction.
    5. Tap **Accept Payment** to send the payment link.
  </Tab>
</Tabs>

## Payment limits

You can set and customise daily and maximum transaction limits for each payment method in the [Merchant Dashboard](https://merchant.cashfree.com/merchants/pg/softpos/payment-methods). Limits help reduce risk at the merchant and business level.

<Note>
  There are no daily transaction count limits. Limits apply to the amount processed per transaction through different payment modes.
</Note>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/payments/latest/offline-payments/create-terminal-transaction">Create Terminal Transaction API</a></li>
    <li><a href="/docs/api-reference/payments/latest/offline-payments/softpos-webhooks">softPOS Webhooks API</a></li>
    <li><a href="/docs/payments/softpos/settlements-reports">Settlements and Reports</a></li>
  </ul>
</div>


# Collection Point Setup
Source: https://www.cashfree.com/docs/payments/softpos/collection-point-setup

Add and verify Storefront, Agent, and Customer VPA collection points in the Cashfree Merchant Dashboard before accepting Offline Payments through softPOS apps.

To ensure secure transactions, each collection point must go through a verification process before it can be used to collect payments. The specific requirements vary depending on the collection model you have chosen.

This page covers the following topics:

* [Storefront setup](#storefront-setup)
* [Agent setup](#agent-setup)
* [Customer VPA setup](#customer-vpa-setup)

## Storefront setup

To add and verify a storefront collection point, complete the following steps:

1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).

2. Navigate to **PG PRODUCTS** > **Offline Payments** > **Collection Point Management**.

3. Click **Add Collection Point**, then select the **Storefront** collection type.

   <img alt="Add Collection Point modal on the Select Collection Point Type step with Storefront selected among Storefront, Agent, and Customer VPA options" />

4. Provide the following details for the storefront:

   * **Storefront Name**: The name of the physical store location.
   * **Operator Name**: The name of the person operating the store.
   * **Operator Email**: The operator's email address.
   * **Operator Phone Number**: The operator's registered mobile number.
   * **Storefront Address**: Full address including pin code and state.

   <Frame>
     <img alt="Add Collection Point modal showing storefront name, operator name, email, phone, and storefront address fields" />
   </Frame>

5. **Add verification documents**: Upload the following mandatory documents to complete the KYC.

   | Document | Accepted formats |
   | - | - |
   | **Address proof of storefront**: Rent agreement or municipality certificate | PDF, DOC, JPEG, JPG, PNG |
   | **Storefront image**: Front facade of the store with the store name clearly visible | JPEG, JPG, PNG (max 4 MB) |

   <Frame>
     <img alt="Add Collection Point modal on the Add Verification step with upload controls for address proof and storefront image and validation messages for mandatory fields" />
   </Frame>

<Warning>
  Both documents are mandatory. The storefront status will remain **Provisionally Active** until Cashfree verifies the submitted documents. Upon successful verification, the status moves to **Active**.
</Warning>

6. **Summary**: Review the storefront and verification details you have provided. Make any necessary changes to the storefront or verification details if required by selecting the edit icon next to the details. Click the **Create Collection Point** button to submit the details.

   <Frame>
     <img alt="Add Collection Point modal on the Summary step with storefront details, verification uploads, and Create Collection Point" />
   </Frame>

## Agent setup

To add and verify an agent through KYC and onboard several agents at once using a batch file, complete the following steps:

<Tabs>
  <Tab title="Single agent">
    To perform single-agent verification, complete the following steps:

    1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).

    2. Navigate to **PG PRODUCTS** > **Offline Payments** > **Collection Point Management**.

    3. Click **Add Collection Point**, then select the **Agent** collection type.

       <img alt="Add Collection Point modal on the Select Collection Point Type step with Agent selected among Storefront, Agent, and Customer VPA options" />

    4. Provide the following mandatory agent details to initiate the verification:

       * **Agent Name**: Full name of the agent as it should appear in the Merchant Dashboard and on KYC records.
       * **Agent Email**: Valid email address that Cashfree uses for verification related communications with the agent.
       * **Agent Phone Number**: Cashfree sends the Aadhaar verification link to this number. If this number is incorrect, the agent cannot complete verification until you correct it and resend the KYC SMS.

       <Frame>
         <img alt="Add Collection Point modal on the Add Agent Details step with fields for agent name, email, and phone number plus a note about the Aadhaar verification link sent to the registered phone" />
       </Frame>

    5. **Summary**: Review the agent details you have provided. Make any necessary changes to the agent details if required by selecting the edit icon next to the details. Click the **Create Collection Point** button to submit the details.

       <Frame>
         <img alt="Add Collection Point modal on the Summary step with agent details and Create Collection Point" />
       </Frame>
  </Tab>

  <Tab title="Batch agents">
    <div>
      To perform batch agent onboarding, complete the following steps:

      1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
      2. Navigate to **PG PRODUCTS** > **Offline Payments** > **Collection Point Management**.
      3. Open the **Batch Agents** tab.
      4. **Download the sample file**: Select **Download Sample File** to get the template.
      5. **Fill in the required details**: Enter the agent details in the downloaded template as specified.
      6. **Upload the file**: Select **Upload File** to submit the batch.

      After you upload the file, the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) displays the upload status, file ID, total records, and invalid records for each submission.

      <img alt="Collection Point Management with Batch Agents tab selected, Today date filter, Download Sample File and Upload File actions, and an empty upload history table with columns for uploaded time, file name, file ID, total records, invalid records, and file status" />
    </div>
  </Tab>
</Tabs>

### Agent KYC verification

After you submit the agent's details, Cashfree runs the following verification steps:

<Steps>
  <Step title="Cashfree sends the KYC verification link">
    An SMS containing a KYC verification link is sent to the agent's registered mobile number. The link is valid for seven days from the date the agent is added. The SMS reads:

    *"\[Company name] has sent an identity verification request for KYC purposes. Click on the \[link] to complete the online KYC. The link is valid till \[date] - Powered by Cashfree."*
  </Step>

  <Step title="Agent completes Aadhaar OTP authentication">
    The link redirects the agent to an Aadhaar OTP authentication page. Once authentication is complete, the agent's status moves to **Provisionally Active**.
  </Step>

  <Step title="Cashfree completes KYC review">
    Once Cashfree reviews and approves the submission, the agent's status moves to **Active**. The agent can then download and log in to the softPOS application.
  </Step>
</Steps>

### Agent statuses

The following statuses indicate where each agent is in the verification process:

| Status | Description |
| - | - |
| **Active** | Cashfree has approved KYC; the agent can download and log in to the softPOS application. |
| **Blocked** | The agent cannot collect payments until Cashfree resolves a compliance or risk hold. |
| **Doc Awaited** | Required documents or details are still missing or incomplete. |
| **Inactive** | The agent is not enabled to collect payments (for example, deactivated or not yet usable). |
| **Provisionally Active** | Aadhaar OTP authentication is complete; Cashfree is still reviewing the submission. |
| **Rejected** | Verification did not pass; review the details in the Merchant Dashboard and correct or resubmit as prompted. |
| **Under Review** | Cashfree is reviewing the submitted information or documents. |

<Note>
  If an agent has not received or has misplaced the KYC SMS, you can resend it directly from the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
</Note>

## Customer VPA setup

<Note>
  Customer VPA is not enabled by default. Contact your Cashfree account manager to request activation before proceeding with the steps below.
</Note>

Create a Customer VPA from the Merchant Dashboard or through the API.

<Tabs>
  <Tab title="Merchant Dashboard">
    To add and verify a Customer VPA collection point, complete the following steps:

    1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).

    2. Navigate to **PG PRODUCTS** > **Offline Payments** > **Collection Point Management**.

    3. Click **Add Collection Point**, then select the **Customer VPA** collection type.

       <img alt="Add Collection Point modal showing Storefront, Agent, and Customer VPA collection type options" />

    4. On **Add Customer Details**, provide the following mandatory customer details:

       * **Customer ID**: A unique identifier for the customer (for example, `CUST001`).
       * **Customer Name**: The customer's name for this customer ID.
       * **Customer Phone Number**: The customer's mobile number with country code.

       You can also provide the following optional details:

       * **Customer VPA**: If not provided, the VPA defaults to `merchantName.customerId`.
       * **Customer Email**: The customer's email address.
       * **Customer Address**: Street, city, state, and pin code for the customer.

       <Note>
         Use **Upload File** on the **Add Customer Details** screen to upload a batch file and create customer VPAs or QR codes for multiple customers at once.
       </Note>

       <Frame>
         <img alt="Add Collection Point modal on the Add Customer Details step with Customer ID, name, phone, optional VPA and email fields, and an Upload File button for batch customer onboarding" />
       </Frame>

    5. Click **Next**. On the **Summary** step, review the customer VPA details. Make any necessary changes by selecting the edit icon next to the details, then click **Create Collection Point**.

       <Frame>
         <img alt="Add Collection Point modal on the Summary step with customer details and Create Collection Point" />
       </Frame>

    Cashfree generates the static QR code when the collection point is created. Download, print, or share it with the customer.
  </Tab>

  <Tab title="API">
    To create a Customer VPA programmatically, complete the following steps:

    1. Send a `POST` request to `/pg/terminal` using the [Create Terminal API](/docs/api-reference/payments/latest/softpos/create-terminal). Set `terminal_type` to `CUSTOMER`.

    ```json theme={"dark"}
    {
      "terminal_id": "<TERMINAL_ID>",
      "terminal_name": "<CUSTOMER_NAME>",
      "terminal_phone_no": "<CUSTOMER_PHONE>",
      "terminal_email": "<CUSTOMER_EMAIL>",
      "terminal_type": "CUSTOMER",
      "terminal_vpa_prefix": "<VPA_PREFIX>"
    }
    ```

    2. Map `cf_terminal_id` and `terminal_vpas` from the response to your internal customer ID.
    3. Call the [Fetch Terminal QR Codes API](/docs/api-reference/payments/latest/softpos/fetch-terminal-qr-codes) with `cf_terminal_id` to retrieve the static QR image and `qrCodeUrl`.

    Cashfree generates the static QR code when the terminal is created. Download, print, or share it with the customer.
  </Tab>
</Tabs>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/payments/latest/offline-payments/upload-terminal-docs">Upload Terminal Documents API</a></li>
    <li><a href="/docs/api-reference/payments/latest/offline-payments/create-terminal">Create Terminal API</a></li>
    <li><a href="/docs/payments/manage/settlements">Manage settlements</a></li>
  </ul>
</div>


# Customer VPA
Source: https://www.cashfree.com/docs/payments/softpos/customer-vpa

Set up a unique UPI VPA (Virtual Payment Address) and static QR code per customer. Match payments to payers using terminal details in the payment webhook.

Customer VPA (Virtual Payment Address) gives each customer a unique UPI VPA and static QR code on a `CUSTOMER` type terminal. Payment webhooks include `terminal_details`, so you can match each transaction to the right payer without manual bank-statement matching.

## Prerequisites

Complete the following before you create Customer VPAs:

* An active Cashfree Payment Gateway account with **Offline Payments - SoftPOS** enabled. See [Get started with Offline Payments](/docs/payments/softpos/how-softpos-works) to request activation.
* Customer VPA enabled on your account. Contact your Cashfree account manager if the **Customer VPA** collection type is not visible when you add a collection point.
* A configured webhook URL if you plan to reconcile payments programmatically. See [softPOS webhooks](/docs/api-reference/payments/latest/offline-payments/softpos-webhooks).

## Key benefits

Customer VPA provides the following capabilities:

| Benefit | Description |
| - | - |
| Automatic reconciliation | Every incoming payment maps to a specific customer ID, so you do not need to match bank credits manually. |
| Static, reusable QR | Generate the QR once and share it. The customer can pay any amount at any time. |
| Customisable VPA | Set a custom VPA prefix (for example, `yourbrand.john01@cashfree`) when you create the terminal. |
| Real-time webhooks | Receive payment notifications that include terminal and customer context. |
| Faster refunds | Initiate refunds with the `order_id` from the payment webhook. |
| Bulk creation | Create Customer VPAs in volume through the Merchant Dashboard or API. |

<Note>
  Maintain a mapping between `cf_terminal_id` and your internal customer ID. Payment webhooks include `terminal_details` with `cf_terminal_id`, `terminal_phone`, and `terminal_vpa` for reconciliation.
</Note>

## How Customer VPA works

The Customer VPA collection flow has the following stages:

1. Create a `CUSTOMER` type terminal for each payer through the [Merchant Dashboard](https://merchant.cashfree.com/merchants/pg/softpos/collection-point-management) or the [Create Terminal API](/docs/api-reference/payments/latest/offline-payments/create-terminal).
2. Cashfree generates the VPA and static QR code for the terminal.
3. Share the QR code or VPA with the customer.
4. The customer pays any amount through a UPI app.
5. Cashfree sends a `PAYMENT_SUCCESS_WEBHOOK` to your configured URL. The payload includes `terminal_details` to identify the customer terminal.

For terminal-based transactions, Cashfree generates the `order_id` only after the payment completes. Use the `order_id` from the webhook to initiate refunds.

## Use cases

Customer VPA supports collections where each payer is known in advance and requires individual tracking.

| Use case | Description |
| - | - |
| Recurring billing | One terminal per subscriber. Payments reconcile to the subscriber `terminal_id`. |
| Rent and tenancy | One terminal per tenant. Partial or full payments update the tenant ledger through webhook `payment_amount`. |
| EMI and loan repayments | One terminal per borrower. Track status per `cf_terminal_id`. |
| Fee collection | One terminal per student or member. Use separate terminals for different fee types for the same person. |
| Society maintenance | One terminal per unit owner. Review payment status per terminal. |
| B2B collections | One terminal per distributor or dealer. Share the terminal QR at delivery. |

## Create a customer VPA

<Note>
  Customer VPA is not enabled by default. Contact your Cashfree account manager to request activation before proceeding with the steps below.
</Note>

Create a Customer VPA from the Merchant Dashboard or through the API.

<Tabs>
  <Tab title="Merchant Dashboard">
    To add and verify a Customer VPA collection point, complete the following steps:

    1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).

    2. Navigate to **PG PRODUCTS** > **Offline Payments** > **Collection Point Management**.

    3. Click **Add Collection Point**, then select the **Customer VPA** collection type.

       <img alt="Add Collection Point modal showing Storefront, Agent, and Customer VPA collection type options" />

    4. On **Add Customer Details**, provide the following mandatory customer details:

       * **Customer ID**: A unique identifier for the customer (for example, `CUST001`).
       * **Customer Name**: The customer's name for this customer ID.
       * **Customer Phone Number**: The customer's mobile number with country code.

       You can also provide the following optional details:

       * **Customer VPA**: If not provided, the VPA defaults to `merchantName.customerId`.
       * **Customer Email**: The customer's email address.
       * **Customer Address**: Street, city, state, and pin code for the customer.

       <Note>
         Use **Upload File** on the **Add Customer Details** screen to upload a batch file and create customer VPAs or QR codes for multiple customers at once.
       </Note>

       <Frame>
         <img alt="Add Collection Point modal on the Add Customer Details step with Customer ID, name, phone, optional VPA and email fields, and an Upload File button for batch customer onboarding" />
       </Frame>

    5. Click **Next**. On the **Summary** step, review the customer VPA details. Make any necessary changes by selecting the edit icon next to the details, then click **Create Collection Point**.

       <Frame>
         <img alt="Add Collection Point modal on the Summary step with customer details and Create Collection Point" />
       </Frame>

    Cashfree generates the static QR code when the collection point is created. Download, print, or share it with the customer.
  </Tab>

  <Tab title="API">
    To create a Customer VPA programmatically, complete the following steps:

    1. Send a `POST` request to `/pg/terminal` using the [Create Terminal API](/docs/api-reference/payments/latest/softpos/create-terminal). Set `terminal_type` to `CUSTOMER`.

    ```json theme={"dark"}
    {
      "terminal_id": "<TERMINAL_ID>",
      "terminal_name": "<CUSTOMER_NAME>",
      "terminal_phone_no": "<CUSTOMER_PHONE>",
      "terminal_email": "<CUSTOMER_EMAIL>",
      "terminal_type": "CUSTOMER",
      "terminal_vpa_prefix": "<VPA_PREFIX>"
    }
    ```

    2. Map `cf_terminal_id` and `terminal_vpas` from the response to your internal customer ID.
    3. Call the [Fetch Terminal QR Codes API](/docs/api-reference/payments/latest/softpos/fetch-terminal-qr-codes) with `cf_terminal_id` to retrieve the static QR image and `qrCodeUrl`.

    Cashfree generates the static QR code when the terminal is created. Download, print, or share it with the customer.
  </Tab>
</Tabs>

## Reconciling payments

Every successful payment triggers a `PAYMENT_SUCCESS_WEBHOOK` to your configured URL. The webhook includes the terminal details (`cf_terminal_id`, phone, and VPA) alongside the payment amount, UPI reference number, and payer details.

You can use the webhook for the following actions:

* Mark an invoice as paid in your ERP or billing system.
* Send a payment confirmation by SMS, email, or WhatsApp to the customer.
* Trigger downstream actions such as unlocking a service, shipping an order, or extending a subscription.
* Update the customer outstanding balance in your CRM.

For batch reconciliation, download the [softPOS transactions report](/docs/payments/softpos/settlements-reports) from the Merchant Dashboard for a customer-wise view of collections over any date range.

## Refunds

Initiate refunds through the [Create Refund API](/docs/api-reference/payments/latest/refunds/create-refund). Pass the `order_id` from the `PAYMENT_SUCCESS_WEBHOOK` payload as the path parameter.

<Warning>
  Do not pre-generate `order_id` values for Customer VPA payments. Cashfree creates the order ID after the customer completes the payment and chooses the amount.
</Warning>

## FAQs

<AccordionGroup>
  <Accordion title="Is the QR code static or dynamic in Customer VPA?">
    The QR code is static. Cashfree generates the static QR code when the collection point is created. Download, print, or share it with the customer.
  </Accordion>

  <Accordion title="Can one customer have multiple VPAs?">
    Each Customer VPA requires a unique `terminal_id`. Create separate terminals if you need distinct VPAs for the same customer (for example, rent and utilities).
  </Accordion>

  <Accordion title="How is the VPA prefix determined?">
    By default, the VPA uses your merchant name as the prefix followed by the `terminal_id`. Pass `terminal_vpa_prefix` in the API request or set a custom prefix in the Merchant Dashboard to override the default.
  </Accordion>

  <Accordion title="How do partial payments work?">
    Static QR codes accept any amount the customer enters. Read `payment_amount` from the webhook and compare it against the expected balance to mark an invoice as fully paid, partially paid, or overpaid.
  </Accordion>

  <Accordion title="Is there a limit on the number of Customer VPAs?">
    Cashfree does not impose a platform cap on Customer VPA count. Contact your Cashfree account manager before creating terminals at very large scale.
  </Accordion>

  <Accordion title="When are webhooks delivered?">
    Webhooks are sent in near real time, typically within seconds of bank confirmation.
  </Accordion>
</AccordionGroup>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/payments/latest/offline-payments/create-terminal">Create Terminal API</a></li>
    <li><a href="/docs/api-reference/payments/latest/softpos/fetch-terminal-qr-codes">Fetch Terminal QR Codes API</a></li>
    <li><a href="/docs/api-reference/payments/latest/refunds/create-refund">Create Refund API</a></li>
    <li><a href="/docs/api-reference/payments/latest/offline-payments/softpos-webhooks">softPOS Webhooks API</a></li>
  </ul>
</div>


# Get Started with Offline Payments
Source: https://www.cashfree.com/docs/payments/softpos/how-softpos-works

Set up Cashfree Offline Payments in four steps: activate the product, configure collection points, complete KYC, and start accepting payments via softPOS.

Before you can accept in-person payments with Cashfree Offline Payments, you need to activate the product on your Merchant Dashboard, configure your collection points, and complete KYC verification for each point.

## Step 1: Activate Offline Payments

Ensure that you have an active Cashfree Payment Gateway account, then request Offline Payments activation from the Merchant Dashboard.

<Steps>
  <Step title="Navigate to Offline Payments">
    Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login), then go to **Offline Payments**.
  </Step>

  <Step title="Request activation">
    If the product is not yet active, click **Request Activation**. This sends an activation request to your Cashfree account manager.
  </Step>

  <Step title="Wait for email confirmation">
    You will receive an email confirmation once your account manager activates Offline Payments.
  </Step>
</Steps>

## Step 2: Select a collection point

After activation, click **Access** on **Offline Payments - SoftPOS**, open [Collection Point Management](https://merchant.cashfree.com/merchants/pg/softpos/collection-point-management), then click **Add Collection Point**.

<Frame>
  <img alt="Collection Point Management with All Collection Points and Batch Agents tabs, softPOS download link, Add Collection Point button, and a table listing Agent and Storefront collection points" />
</Frame>

Select the collection point type that matches your business needs:

<AccordionGroup>
  <Accordion title="Storefront">
    Use this model if you operate one or more physical store locations and want customers to scan a static QR code to pay at the counter, with funds credited directly to your account.
  </Accordion>

  <Accordion title="Agent (softPOS)">
    Use this model if your staff or agents collect payments on your behalf at the point of service, such as at a customer's doorstep or table, with funds credited directly to your account.
  </Accordion>

  <Accordion title="Customer VPA">
    Use this model if you need to track payments at the individual customer level, such as for loan repayments, fee collection, or recurring charges.
  </Accordion>
</AccordionGroup>

## Step 3: Set up your collection points

Cashfree must verify each collection point before you can start collecting payments. Follow the respective setup steps according to your selected collection point type:

* [Storefront setup](/docs/payments/softpos/collection-point-setup#storefront-setup)
* [Agent setup](/docs/payments/softpos/collection-point-setup#agent-setup)
* [Customer VPA setup](/docs/payments/softpos/collection-point-setup#customer-vpa-setup)

<Note>
  Each collection point must reach **Active** status before you can start collecting payments.
</Note>

## Step 4: Start collecting payments via agents

Agents can begin accepting payments through the [softPOS application](/docs/payments/softpos/agent-collection-mode#install-and-log-in-to-the-softpos-application), a mobile app for Android devices that supports QR codes, payment links, and more.

For instructions on setting up static and dynamic QR codes, payment links, and payment limits, see [agent collection point](/docs/payments/softpos/agent-collection-mode).

<Note>
  All transactions, cash and digital, are visible in a single dashboard. See [settlements and reports](/docs/payments/softpos/settlements-reports) to understand how and when funds are transferred to your bank account.
</Note>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/payments/latest/offline-payments/create-terminal">Create Terminal API</a></li>
    <li><a href="/docs/payments/manage/transactions">Manage Transactions</a></li>
    <li><a href="/docs/payments/softpos/settlements-reports">Settlements and Reports</a></li>
  </ul>
</div>


# Offline Payments
Source: https://www.cashfree.com/docs/payments/softpos/introduction

Collect, track, and reconcile payments in-store, through agents, and at the individual customer level using Cashfree Offline Payments.

Offline Payments is a product that enables businesses to collect payments in-store, through field agents, or directly from individual customers, all tracked and reconciled in the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).

## Why choose Offline Payments

Offline Payments is built for businesses that need a flexible, unified way to collect and track payments across multiple channels.

* **Accept payments anywhere**: Collect payments in-store, through agents, or at the individual customer level using Storefront, Agent (softPOS), or Customer VPA.
* **Over hundred payment modes**: Accept UPI, cards, net banking, wallets, and more from a single product.
* **Unified transaction tracking**: Cash and digital payments are recorded and visible together in one dashboard.
* **Simplified reconciliation**: All collections are automatically matched and available for download from the Merchant Dashboard.

## Collection models

A collection model defines how your business and customers interact at the point of payment. Offline Payments supports three collection models, each designed for a different operating pattern. You can enable one or more collection models simultaneously, depending on your business needs.

<Tabs>
  <Tab title="Storefront">
    Generate static QR codes for physical store locations, with all payments credited directly to your account.

    **Use cases**

    * **Retail shops**: Issue a static QR code per store so customers can pay in person at the counter.
    * **Restaurants**: Run multiple locations under one merchant account with a single settlement destination.
    * **Clinics and salons**: Accept walk-in payments at service counters without additional hardware.
    * **Multi-outlet businesses**: Manage payments across all outlets from a single dashboard.

    **Key features**

    * **Unique QR per location**: Each store gets its own QR code to keep payment tracking separate.
    * **Single settlement account**: Payments from all store locations settle into one registered bank account.
    * **No hardware required**: No dedicated POS terminal is needed to get started.

    **Example:** A grocery store owner with multiple outlets creates separate QR codes for each location while receiving all payments into a single account.
  </Tab>

  <Tab title="Agent (softPOS)">
    Enable staff or agents to collect payments on your behalf using their Android mobile devices.

    **Use cases**

    * **Delivery businesses**: Allow agents to collect payment at the customer's doorstep on cash-on-delivery orders.
    * **Restaurants**: Enable waitstaff to accept payments at the table using their mobile device.
    * **Field service teams**: Equip staff to collect payments on-site without returning to a central point.
    * **Loan recovery agents**: Record collections digitally at the customer's location.

    **Key features**

    * **Unlimited agents**: Add any number of agents under a single business account.
    * **Cash and digital payments**: Agents can accept both payment types from the same application.
    * **Centralised tracking**: All agent collections are visible in the Merchant Dashboard.

    **Example:** A restaurant owner allows waitstaff to collect payments at the customer's table, with all amounts settling into a single business account.
  </Tab>

  <Tab title="Customer VPA">
    Create a unique UPI ID or QR code per customer to track payments at the individual level.

    **Use cases**

    * **Lending businesses**: Assign each borrower a unique VPA so repayments are matched automatically.
    * **Educational institutions**: Issue per-student payment addresses for fee collection and tracking.
    * **Subscription payments**: Track recurring payments at the individual customer level for easy reconciliation.
    * **Logistics companies**: Collect payments from specific customers and match them to orders.

    **Key features**

    * **Unique VPA per customer**: Each customer receives a Virtual Payment Address tied to their account.
    * **Automatic reconciliation**: Payments are matched to the correct customer without manual effort.
    * **Real-time tracking**: Incoming payments are reflected immediately in the Merchant Dashboard.

    **Example:** A lending company assigns each borrower a unique VPA to track repayments automatically without manual matching.
  </Tab>
</Tabs>

## Explore Offline Payments

Use the following resources to get started with each area of Offline Payments:

<CardGroup>
  <Card title="Get started with Offline Payments" icon="circle-play" href="/docs/payments/softpos/how-softpos-works">
    Activate the product, verify your collection points, and begin accepting payments.
  </Card>

  <Card title="Collection Point Setup" icon="users" href="/docs/payments/softpos/collection-point-setup">
    Complete setup and verification for each collection point before you can start collecting payments.
  </Card>

  <Card title="Customer VPA" icon="qrcode" href="/docs/payments/softpos/customer-vpa">
    Create per-customer UPI VPAs and static QR codes, and reconcile payments using terminal-level webhooks.
  </Card>

  <Card title="Agent(softPOS)" icon="android" href="/docs/payments/softpos/agent-collection-mode">
    Install the softPOS application and collect payments using QR codes and payment links.
  </Card>

  <Card title="API integration" icon="code" href="/docs/api-reference/payments/latest/offline-payments/create-terminal">
    Use the Offline Payments APIs to onboard agents and manage orders programmatically.
  </Card>
</CardGroup>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/payments/latest/offline-payments/create-terminal-transaction">Create Terminal Transaction API</a></li>
    <li><a href="/docs/api-reference/payments/latest/offline-payments/softpos-webhooks">softPOS Webhooks API</a></li>
    <li><a href="/docs/payments/softpos/settlements-reports">Settlements and Reports</a></li>
  </ul>
</div>


# Settlements and Reports
Source: https://www.cashfree.com/docs/payments/softpos/settlements-reports

Understand when Offline Payments settle to your bank account and how to export softPOS transaction reports from the Merchant Dashboard for reconciliation.

All cash and digital transactions processed through Offline Payments are captured in your Cashfree account, giving you a unified view of collections, payouts, and reconciliation data from the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).

## Settlements

After a successful payment, Cashfree settles funds to the bank account registered with your merchant account. Payout timing follows the settlement schedule configured for that account.

By default, settlements follow a **T+2 bank working days** schedule. **T** is the calendar day the payment succeeds. Cashfree processes the settlement two bank working days after **T**. Weekends and bank holidays are not counted as bank working days.

For bank account details and settlement schedules, see [Manage Settlements](/docs/payments/manage/settlements).

## Transaction reports

All transactions are recorded and available for download from the **Reports** section of the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).

To generate and download a transaction report, complete the following steps:

1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
2. Navigate to **Payment Gateway** > **Reports** > **Download Reports**.
3. Select **Generate New Report**.
4. Configure your report settings:
   * **Report Type**: Select **softPOS Transactions** from the dropdown.
   * **Date Range**: Choose the time period for the report.
   * **File Format**: Select CSV or XLSX.
   * **File Name**: Modify if needed. This is optional.
5. Select **Generate Report**.

<Info>
  The report includes transaction-level details such as the agent name, terminal ID, and payment method.
</Info>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/payments/manage/settlements">Manage Settlements</a></li>
    <li><a href="/docs/api-reference/payments/latest/offline-payments/create-terminal-transaction">Create Terminal Transaction API</a></li>
    <li><a href="/docs/api-reference/payments/latest/offline-payments/softpos-webhooks">softPOS Webhooks API</a></li>
  </ul>
</div>


# Offline Payments FAQs
Source: https://www.cashfree.com/docs/payments/softpos/softpos-faq

Browse Offline Payments and softPOS FAQs covering onboarding, collection points, KYC, supported payment modes, settlements, reports, and troubleshooting.

## General

These FAQs cover what Offline Payments is, the three collection models, account prerequisites, and how to activate the product.

<AccordionGroup>
  <Accordion title="What are Cashfree Offline Payments and what are the benefits?">
    Cashfree Offline Payments is a solution that allows businesses to collect, track, and reconcile payments across in-person and remote collection journeys. With Offline Payments activated for your account, you can do the following:

    * Collect payments in-store or on the go.
    * Enable agents to collect payments on your behalf.
    * Track every transaction, including cash and digital, in one place.
    * Offer your customers more than 100 payment options.

    You also benefit from the following:

    * **Coverage across collection models**: Storefront, Agent (softPOS), and Customer VPA, depending on what you enable.
    * **Broad payment mode support**: Including UPI, cards, net banking, wallets, and more.
    * **Unified visibility**: Cash and digital payments together in one workflow.
    * **Simplified reconciliation**: Reporting aligned to how you collect.
  </Accordion>

  <Accordion title="What are the different types of Offline Payments services from Cashfree?">
    Cashfree Offline Payments offers three flexible ways to collect payments, depending on your business model:

    1. **Storefront**: Static QR codes and in-store collection for **physical stores** and fixed retail locations where customers pay at the counter.
    2. **Customer VPA**: A dedicated UPI identity or QR per customer when you run **recurring or tracked payments** and need payer-level visibility for reconciliation.
    3. **Agent (softPOS)**: Staff or agents collect on your behalf using the softPOS application on their devices for **field collections**, deliveries.
  </Accordion>

  <Accordion title="What is a storefront?">
    **Storefront** enablement helps you generate **static QR codes** for physical stores and collect payments directly into your account. It is suited to fixed retail locations where customers pay at the counter.
  </Accordion>

  <Accordion title="What is an agent (softPOS)?">
    **Agent (softPOS)** enablement lets your staff or agents collect payments on your behalf using **softPOS** on their **Android** devices. It is suited to field collections, deliveries.
  </Accordion>

  <Accordion title="What is a Customer VPA?">
    **Customer VPA** enablement lets you create a **unique UPI ID or QR code for each customer** so you can track who paid, how much, and when. It is suited to recurring collections, fees, instalments, or any flow where payer-level traceability matters.
  </Accordion>

  <Accordion title="Which collection model should I choose for my business?">
    Match your operating pattern to one of the models below.

    * **Storefront**: Physical stores and fixed checkout.
    * **Agent (softPOS)**: Field collections, deliveries.
    * **Customer VPA**: Recurring or individually tracked payments.
  </Accordion>

  <Accordion title="Can I use multiple collection methods at the same time (Storefront, Agent, and Customer VPA)?">
    Yes. You can enable and use **Storefront**, **Agent (softPOS)**, and **Customer VPA** together whenever your use case requires it.
  </Accordion>

  <Accordion title="Do I need an existing Cashfree Payment Gateway account?">
    Yes. You must have an **active Cashfree Payment Gateway relationship** before you can activate Offline Payments. If you do not have one yet, [create your account](https://merchant.cashfree.com/merchants/signup) and complete Payment Gateway onboarding first.
  </Accordion>

  <Accordion title="Can I get Offline Payments if I do not have a Payment Gateway with Cashfree?">
    No. Offline Payments is available only to merchants with an active Cashfree Payment Gateway relationship. [Create your account](https://merchant.cashfree.com/merchants/signup) if you are new to Cashfree.
  </Accordion>

  <Accordion title="How do I activate Offline Payments?">
    Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login). Open **Offline Payments** from the navigation, start **Activate Offline Payments**, and complete the steps shown on screen. You receive an **email confirmation** once Offline Payments is active for your account.
  </Accordion>

  <Accordion title="Are there any transaction limits for Storefront, Agent, or Customer VPA?">
    There are **no daily transaction count limits** across the Offline Payments product suite. **Per-transaction amount limits** still apply, and they depend on the **payment mode** in use. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login), open the **Payment Method** settings for the product you use, and customise limits there. For **softPOS**, open [softPOS payment method settings](https://merchant.cashfree.com/merchants/pg/softpos/payment-methods) or select **softPOS** > **Payment Method**.
  </Accordion>
</AccordionGroup>

## softPOS application

These FAQs cover the softPOS Android application, device requirements, pricing, receipt support, and available payment options.

<AccordionGroup>
  <Accordion title="Is the softPOS application available on iOS?">
    No. The Cashfree softPOS application is **not** available on the **iOS App Store**. It is available only on **Android** via the **Google Play Store** (Android 6.0 Marshmallow or above).
  </Accordion>

  <Accordion title="How many agents can a single merchant add?">
    There is **no limit**. You can add an **unlimited** number of agents under a single merchant account.
  </Accordion>

  <Accordion title="Are there any extra charges to use the softPOS application? Is there a monthly, yearly, or service fee?">
    No. The application is **free** to download and use. Cashfree charges **only for transactions** processed through softPOS, as per your pricing agreement. There is **no** monthly fee, yearly fee, maintenance fee, or registration fee for the application itself.
  </Accordion>

  <Accordion title="Can I print receipts using softPOS?">
    softPOS does **not** support built-in invoice or receipt printing. You can integrate **third-party software or hardware** if you need printed receipts.
  </Accordion>

  <Accordion title="Can I customise digital receipts on softPOS?">
    **Digital receipt customisation** is **not** currently available in the Cashfree softPOS application.
  </Accordion>

  <Accordion title="What payment options are available for collecting payments on the softPOS app?">
    The softPOS application supports the following collection options:

    * **Static QR**
    * **Dynamic QR**
    * **Payment links**
    * **Cash** (ledger entry only)
    * **Tap to Pay**
    * **Cardless EMI**

    Which options appear in your build can depend on account configuration and product rollout.
  </Accordion>

  <Accordion title="What payment options do my customers have?">
    Your customers can use **more than 120 payment options**, including cards, net banking, UPI, wallets, and more, depending on the collection method you choose (for example payment links expose the full hosted checkout range).
  </Accordion>
</AccordionGroup>

## QR codes, payment links, and cash

These FAQs cover the difference between static and dynamic QR codes, how payment links are shared, and how cash transactions are recorded.

<AccordionGroup>
  <Accordion title="What is the difference between a static QR code and a dynamic QR code?">
    The difference is **who enters the amount** and **how much flexibility** the payer has at scan time.

    **Dynamic QR code**

    * The **agent enters the amount** the customer must pay.
    * The agent can add **order context** such as the **customer mobile number**, **invoice number**, and **order note** before generating the code.

    **Static QR code**

    * The **customer scans** the code with a UPI application, **enters the amount**, and completes the payment.
  </Accordion>

  <Accordion title="What happens if the timer runs out before my customer can complete the transaction?">
    If the timer expires before the customer finishes:

    * If the customer has **not scanned** the QR code yet, **regenerate the order** by re-entering all details on the **New Payment** tab.
    * If the customer has **already scanned** the QR code, they can **continue** the payment flow. Check status in the **Payments** tab by **pulling down to refresh**.
  </Accordion>

  <Accordion title="How do I share a payment link?">
    Cashfree sends the payment link by **SMS** to the **customer mobile number** the agent entered when creating the payment.
  </Accordion>

  <Accordion title="Will I be able to see cash transactions in the transaction report?">
    Yes. You can see **all transactions**, including those recorded as **cash**, in the **transaction report** and in the **Payments** view for reconciliation.
  </Accordion>

  <Accordion title="What does the Cash option do?">
    The **Cash** option lets the agent record a **ledger entry** for a cash collection when a service is rendered. **No payment processing** runs through Cashfree for that leg. Entries still appear in the **Payments** tab and in **reports** for reconciliation.
  </Accordion>

  <Accordion title="Can I generate a Dynamic UPI QR code without using the S2S or Seamless flow?">
    Yes. If your account is not eligible for S2S or Seamless UPI enablement, generate a Dynamic UPI QR code with the SoftPOS (Offline Payments) flow. This also applies to in-app POS and invoice collection use cases where you need to display a dynamic UPI QR without using Cashfree Checkout. To generate a dynamic UPI QR code:

    1. [Create a Terminal](/docs/api-reference/payments/latest/offline-payments/create-terminal).
    2. [Create an Order](/docs/api-reference/payments/latest/orders/create-order) and include the terminal details in the request body.
    3. [Create a Terminal Transaction](/docs/api-reference/payments/latest/offline-payments/create-terminal-transaction) and pass `payment_method` as `QR_CODE`.

    Upon successful payment, you receive a payment success webhook containing the terminal details.

    You can also use the [Web Element SDK](/docs/payments/online/element/introduction) UPI QR component to build a custom checkout UI.
  </Accordion>

  <Accordion title="What does the error 's2s_enabled_not_approved' mean when using the /orders/pay API?">
    The error `s2s_enabled_not_approved` (HTTP 400) indicates that the S2S (Server-to-Server) or seamless payment capability for the [Order Pay API](/docs/api-reference/payments/latest/payments/order-pay) is not enabled or approved for your account. If your account is ineligible for S2S UPI enablement, you can use the [Elements SDK](/docs/payments/online/element/introduction) or the Offline Payments solution for dynamic QR use cases.
  </Accordion>
</AccordionGroup>

## Storefronts, agents, and Customer VPAs

These FAQs cover adding and managing collection points, resolving KYC issues, and how customers receive payment confirmations.

<AccordionGroup>
  <Accordion title="Can I add a single mobile number for multiple storefronts or agents?">
    Yes. **One mobile number** can be used when onboarding **multiple storefronts** or **multiple agents**, as long as each record meets Cashfree validation rules for that collection point.
  </Accordion>

  <Accordion title="What if an agent does not receive the KYC verification SMS?">
    Take the following steps:

    * **Resend** the verification SMS from the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) using the agent-management workflow for your collection points.
    * **Confirm** the mobile number on file for the agent is correct before you resend.
  </Accordion>

  <Accordion title="Can I deactivate or delete a storefront, agent, or Customer VPA?">
    Yes. You can **disable or deactivate** a storefront, agent, or Customer VPA from the [Merchant Dashboard](https://merchant.cashfree.com/auth/login). **Past transactions remain available** in reports after you change the status.
  </Accordion>

  <Accordion title="Will customers receive a payment confirmation?">
    Yes. Customers can receive confirmation through the following channels:

    * **Issuer bank**: Standard bank or card issuer notifications for the payment instrument they used.
    * **Cashfree SMS**: For payments completed through a **payment link**, Cashfree also sends an **SMS** confirmation to the customer's mobile number where applicable.
  </Accordion>

  <Accordion title="What should I do if a collection agent is unable to log in to a terminal?">
    First, ensure the agent has logged out from any previous devices before attempting to log in on a new device.

    If the agent still cannot log in (for example, due to a device reset or being unable to access the previous device), contact the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) to request a manual logout from all devices.
  </Accordion>
</AccordionGroup>

## Reports and settlements

These FAQs cover how to generate transaction reports, what fields they include, and when settlements are processed.

<AccordionGroup>
  <Accordion title="Where can I see reports for transactions?">
    Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login). Go to **Reports**, open **Download Reports**, click **Generate New Report**, choose your **file type**, select **softPOS Transactions** as the report type (the dashboard may still show **Offline Payment Transactions** for the same export in some accounts), and set the **date range**. For a guided walkthrough, see [Settlements and reports](/docs/payments/softpos/settlements-reports#transaction-reports).
  </Accordion>

  <Accordion title="What details are covered in the transaction report?">
    The transaction report includes **end-to-end transaction fields** at collection-point level. Examples include:

    * **Agent name**
    * **Terminal ID**
    * **Payment method**
    * **Amounts and status fields** (and other columns Cashfree exposes for that report type)

    The exact column set can vary slightly by export format and configuration.
  </Accordion>

  <Accordion title="When are settlements processed?">
    By default, Cashfree processes settlements on **T+2 bank working days**. **T** is the calendar day the payment succeeds. Settlement runs on **bank working days** only. For schedules, bank accounts, and reconciliation depth, see [Manage settlements](/docs/payments/manage/settlements).
  </Accordion>
</AccordionGroup>

## Support

Policy documents and contact details for Cashfree support, grievances, and dispute escalation.

<AccordionGroup>
  <Accordion title="How do I get more information on Cashfree or its policies?">
    For policy documents and Cashfree contact details, use the following:

    * [Grievance Redressal Policy](https://www.cashfree.com/grievance-redressal-policy/)
    * [Terms and Conditions](https://www.cashfree.com/tnc/)
    * [Privacy Policy](https://www.cashfree.com/privacypolicy/)

    **Grievance Officer**: Mr. Vaibhav Kaushal\
    **Email**: [grievances@cashfree.com](mailto:grievances@cashfree.com)\
    **Address**: Cashfree India Pvt Ltd, RMZ Ecoworld, Building 7, 10th Floor, Devarabeesanahalli, Marathahalli Outer Ring Road, Bengaluru – 560103

    **Nodal Officer**: Mr. Shaik Mohammed Aftab Alam\
    **Email**: [dispute@cashfree.com](mailto:dispute@cashfree.com)\
    **Address**: Cashfree India Pvt Ltd, RMZ Ecoworld, Building 7, 10th Floor, Devarabeesanahalli, Marathahalli Outer Ring Road, Bengaluru – 560103
  </Accordion>
</AccordionGroup>


# Cashfree Spark
Source: https://www.cashfree.com/docs/payments/spark-ai

Spark is an agentic layer in the Cashfree Merchant Dashboard. Ask about your business data, or have it process refunds, create offers, and more.

Spark is available from the search bar at the top of every Merchant Dashboard page. Instead of navigating to a specific page, filter, or workflow, type a question or use voice input, in English or in your own language, and Spark reads your account data, investigates, and acts on your behalf.

* "Why did my settlement come in lower than expected?" Spark investigates your account data and explains the discrepancy.
* "Why did this payment fail?" Spark finds the transaction and explains the failure reason.
* "Refund the second one." Spark resolves this against the failed payments it just listed, checks eligibility, asks you to confirm, and processes the refund.

## Try asking

Spark understands plain language questions about your business, including diagnostic questions that would otherwise take you across several dashboard pages to answer. Here are a few prompts to get started.

* "Sales today"
* "Why is today's settlement lower than yesterday's?"
* "Next settlement"
* "Refunds this week"
* "Success rate"
* "Check recent tickets"
* "Create a 10% discount offer for all customers"

## How Spark works

Spark is built as a multi-agent system. An orchestration layer routes each request to domain-specific agents and their own tools, which lets Spark investigate a request and act on it, rather than only generate an answer.

* **Grounded**: Every response is fetched live from the same services that power the dashboard, covering sales, settlements, refunds, disputes, and support tickets. If Spark cannot retrieve a figure, it says so instead of estimating one.
* **Gated**: Reading is free. Anything that changes data or moves money requires your explicit confirmation, and Spark shows the exact steps it will take before you approve them.
* **Auditable**: Spark follows the Merchant Dashboard's existing authorization model. If your role cannot perform an action in the dashboard, it cannot perform that action through Spark. An alias user is limited exactly as they would be when clicking through the dashboard, and reporting actions stay restricted to account owners.
* **In context**: Spark retains context within a conversation, so a follow-up such as "and refund the second one" resolves against what you were just looking at, without repeating earlier details.

Spark runs on Cashfree's own infrastructure, inside your existing account and permissions. There is nothing to install, and Spark doesn't create a separate copy of your data.

## Access Spark

You can open Spark from any page in the Merchant Dashboard by following these steps.

<Steps>
  <Step title="Open the search bar">
    Select the search bar at the top of the dashboard. It's labelled **Ask Spark about your business**.
  </Step>

  <Step title="Enter your question">
    Type your question, or select the microphone icon to ask using voice.
  </Step>

  <Step title="Review the response">
    Spark opens in a side drawer with a response, rendered as metrics, tables, charts, or a proposed action. If you ask for a report, Spark returns a summary in the drawer with a link to download the full file. You can ask follow-up questions, expand the drawer to full screen, or start a new conversation at any time.
  </Step>
</Steps>

<Note>
  Spark generates responses from your account data for guidance only. Review any suggested action before you confirm it.
</Note>

## What Spark can do

Spark supports answering questions about your business, investigating what happened, and taking action on your account.

### Query and diagnose

Ask Spark about your business performance, and it returns a structured answer with supporting charts or tables where relevant.

* Sales totals, trends, and comparisons across time periods.
* Settlement schedules and unsettled balances.
* Refund volumes and patterns.
* Payment success and failure rates, including why a specific payment failed.
* Transaction breakdowns by payment method.
* Support ticket status.
* Dispute status and details.
* Failed webhook deliveries and the reason each one failed.
* Whitelisted domains and configured limits.
* How a Cashfree feature works.

### Take action

Spark can also make changes to your account on your behalf. Before it does, it always presents the exact steps it will take and asks you to confirm.

* Process a refund.
* Create a new offer or coupon.
* Pause an active offer.
* Initiate an instant settlement.
* Create a payment link.
* Generate a report.
* Cancel an order.
* Replay a failed webhook.
* Whitelist a new domain or adjust a limit.

<Important>
  Spark never makes changes to your account without explicit confirmation. If you don't confirm a proposed action, Spark makes no change.
</Important>

## Use Spark

The following scenarios show how to use Spark for common tasks.

### Diagnostic scenarios

<AccordionGroup>
  <Accordion title="Check today's sales" icon="chart-line">
    Get an instant read on how your business is performing today.

    <Steps>
      <Step title="Ask">
        "Sales today"
      </Step>

      <Step title="Review">
        Spark returns your total sales for the day, compared to the previous day, along with a trend chart.
      </Step>

      <Step title="Refine">
        Ask a follow-up, such as comparing sales to the same day last week or breaking sales down by payment method.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Check your next settlement" icon="sack-dollar">
    Confirm when your funds will reach your bank account.

    <Steps>
      <Step title="Ask">
        "Next settlement"
      </Step>

      <Step title="Review">
        Spark shows your upcoming settlement amount and date, your last settlement, and your current unsettled balance.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Monitor refunds" icon="rotate-left">
    Track refund volumes against your normal range for a selected period.

    <Steps>
      <Step title="Ask">
        "Refunds this week"
      </Step>

      <Step title="Review">
        Spark returns your refund total for the period and flags whether it falls within your normal range.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Review payment success rate" icon="percent">
    Compare your current success rate against the previous period and see where transactions drop off.

    <Steps>
      <Step title="Ask">
        "Success rate"
      </Step>

      <Step title="Review">
        Spark returns your current success rate, compares it to the previous period, and breaks down the split between successful, dropped, failed, and pending transactions.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Break down sales by payment method" icon="chart-pie">
    See which payment methods drive the most sales on your account.

    <Steps>
      <Step title="Ask">
        "Show me a breakdown of sales by payment mode"
      </Step>

      <Step title="Review">
        Spark returns a split of sales across payment methods, such as UPI, cards, and net banking, with a chart and per-method totals.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Check support tickets" icon="headset">
    Get a quick summary of your open and recently resolved tickets.

    <Steps>
      <Step title="Ask">
        "Check recent tickets"
      </Step>

      <Step title="Review">
        Spark summarises your open and recently resolved tickets and offers to help move the oldest one forward.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Check a dispute" icon="gavel">
    Review a customer dispute without switching to the Disputes tab.

    <Steps>
      <Step title="Ask">
        "Show me the dispute for order ORD789"
      </Step>

      <Step title="Review">
        Spark returns the dispute details, including the reason, the amount, and the date your response is due.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Ask about a Cashfree feature" icon="circle-question">
    Get an answer from Cashfree product documentation without leaving the dashboard.

    <Steps>
      <Step title="Ask">
        "How does instant settlement pricing work?"
      </Step>

      <Step title="Review">
        Spark answers using Cashfree product documentation and links to the relevant page for more detail.
      </Step>
    </Steps>
  </Accordion>
</AccordionGroup>

### Action scenarios

<AccordionGroup>
  <Accordion title="Process a refund" icon="hand-holding-dollar">
    Resolve a customer refund request directly from your conversation with Spark.

    <Steps>
      <Step title="Ask">
        "Refund payment PAY456"
      </Step>

      <Step title="Review the plan">
        Spark checks refund eligibility, then confirms the amount it will refund.
      </Step>

      <Step title="Confirm or adjust">
        Select **Yes, process it** to proceed, or specify a different amount.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Create a new offer" icon="tag">
    Set up a discount offer without leaving your conversation with Spark.

    <Steps>
      <Step title="Ask">
        "Create a 10% discount offer for all customers"
      </Step>

      <Step title="Review the plan">
        Spark shows the exact configuration it will create, including the coupon code, discount value, eligible customers, and validity.
      </Step>

      <Step title="Confirm or adjust">
        Select **Yes, create it** to proceed, or describe a change you'd like instead.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Pause an active offer" icon="circle-pause">
    Stop a live offer from accepting further redemptions, without affecting past ones.

    <Steps>
      <Step title="Ask">
        "Pause offer OFF10"
      </Step>

      <Step title="Review the plan">
        Spark confirms which offer it will pause and clarifies that existing redemptions aren't affected.
      </Step>

      <Step title="Confirm or adjust">
        Select **Yes, pause it** to proceed, or select **Keep it live** to cancel.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Initiate an instant settlement" icon="bolt">
    Move your available balance to your bank account ahead of your regular settlement cycle.

    <Steps>
      <Step title="Ask">
        "Settle now" or "Instant settlement"
      </Step>

      <Step title="Review the plan">
        Spark shows the available balance, the instant settlement fee, the net amount, and the destination bank account.
      </Step>

      <Step title="Confirm or adjust">
        Select **Yes, settle now** to proceed.
      </Step>
    </Steps>

    <Note>
      Cashfree deducts instant settlement fees from the settled amount. Funds typically arrive in your bank account within 15 minutes of confirmation.
    </Note>
  </Accordion>

  <Accordion title="Create a payment link" icon="link">
    Generate a payment request without opening the payment links form.

    <Steps>
      <Step title="Ask">
        "Create a payment link for ₹2,000 for customer Rahul Sharma, valid for 24 hours"
      </Step>

      <Step title="Review the plan">
        Spark shows the exact link configuration it will create, including the amount, customer details, and validity period.
      </Step>

      <Step title="Confirm or adjust">
        Select **Yes, create it** to proceed, or describe a change you'd like instead.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Generate a report" icon="file-lines">
    Get a reconciliation or summary report without opening the Reports section.

    <Steps>
      <Step title="Ask">
        "Generate a settlement reconciliation report for last month"
      </Step>

      <Step title="Review">
        Spark generates the report and returns a summary with a link to download the full file.
      </Step>
    </Steps>

    <Note>
      Report generation is restricted to account owners, matching the Merchant Dashboard's existing permissions.
    </Note>
  </Accordion>

  <Accordion title="Cancel an order" icon="ban">
    Stop an order before it's paid, without opening the orders table.

    <Steps>
      <Step title="Ask">
        "Cancel order ORD12345"
      </Step>

      <Step title="Review the plan">
        Spark confirms which order it will cancel and that no further payments can be made against it.
      </Step>

      <Step title="Confirm or adjust">
        Select **Yes, cancel it** to proceed, or select **Keep it open** to cancel the request.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Find and replay a failed webhook" icon="webhook">
    Catch a silent integration failure and resend it, without checking your webhook logs manually.

    <Steps>
      <Step title="Ask">
        "Which webhook alerts to my system failed yesterday? Resend them."
      </Step>

      <Step title="Review">
        Spark lists the failed webhook deliveries and the reason each one failed.
      </Step>

      <Step title="Confirm or adjust">
        Select **Yes, resend them** to proceed, or ask Spark to resend only specific ones.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Whitelist a domain or adjust a limit" icon="shield-check">
    Update an account preference without raising a support ticket.

    <Steps>
      <Step title="Ask">
        "Whitelist checkout.mystore.com for webhooks"
      </Step>

      <Step title="Review the plan">
        Spark confirms the domain or limit it will update and the current value it will replace.
      </Step>

      <Step title="Confirm or adjust">
        Select **Yes, update it** to proceed, or describe a change you'd like instead.
      </Step>
    </Steps>
  </Accordion>
</AccordionGroup>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/tools-ai/mcp-server">Cashfree MCP Server</a></li>
    <li><a href="/docs/payments/checkout/offers">Offers Overview</a></li>
    <li><a href="/docs/payments/manage/settlements">Settlements Overview</a></li>
  </ul>
</div>


# Billing Configuration
Source: https://www.cashfree.com/docs/payments/split/billing/configuration

Configure Cashfree Easy Split billing settings to control how marketplace fees, commissions, and taxes are deducted from each order and shared with vendors.

You can now configure the payment and settlement service charges. You can either bear the service charges or bill the charges directly to the linked vendor account in the transaction split.

There are three types of services charges:

* Payment Gateway and Easy Split Charges
* Standard and Instant Settlement Charges
* On-Demand Settlement Charges

**Payment Gateway Charges**\
Charges for the collection of payment basis the mode of payment and payment gateway used.

**Easy Split Charges**\
These are to split a transaction into multiple settlement accounts. These charges will be based on the order amount and not on the number of splits that are created for the order.

**Settlement Charges**\
Settlement charges for the frequency of the schedule option configured for a vendor account. Faster or instant schedule option will be at a slightly higher cost than the standard T+2\* schedule option.

<Info>
  Settlement cycle is subject to bank approval and can vary based on transaction type, business category/model, risk parameters, and other factors.
</Info>

**On-Demand Settlement Charges**\
On-Demand settlements are routed through RTGS/IMPS, where you can expect the settlements instantly by invoking the on-demand settlement. These settlements are available 24\*7 and charged according to the settlement amount.

**Configuration Models Available**

| Bill to | Prepaid | Postpaid |
| :- | :- | :- |
| Merchant | ✅ | ✅ |
| Vendor | ✅ | Not available |

If you bear the service charges, both prepaid and postpaid models are available. You have complete control of whom to charge for each set of charges associated with Easy Split.

If the vendor bears the service charges, only the prepaid model is available. The vendor has no control over these charges as it is configured by you.

**Prepaid Model**

If you opt for the prepaid model, the service charges are deducted directly from the settlement amount. We settle the remaining amount to your account or the vendor account respectively.

For example, let us assume the following scenario mentioned in the table below:

| Description | Amount |
| :- | :- |
| Transaction Amount | Rs. 100 |
| Payment Gateway and Easy Split Charges | Rs. 2 |
| Merchant Settlement | Rs. 10 |
| Vendor Settlement | Rs. 90 |

**Case 1: You bear the settlement amount**

If you bear the settlement amount, the service charges are deducted from your settlement amount and the remaining amount of Rs. 8 is settled in your account. The vendor settlement amount is untouched, and Rs. 90 is settled in the vendor account.

**Case 2: Vendor bears the settlement amount**

If the vendor bears the settlement amount, the service charges are deducted from the vendor settlement amount and the remaining amount of Rs. 88 is settled to the vendor account. Your settlement amount is untouched, and Rs. 10 is settled in your account.

| Bill to | Merchant settlement amount | Vendor settlement amount |
| :- | :- | :- |
| Merchant | 8 | 90 |
| Vendor | 10 | 88 |

**Postpaid Model**

If you opt for the postpaid model, you receive an invoice which you have to clear at the end of the month.

For example, let us assume the following scenario mentioned in the table below:

| Description | Amount |
| :- | :- |
| Transaction Amount | Rs. 100 |
| Payment Gateway and Easy Split Charges | Rs. 2 |
| Merchant Settlement | Rs. 10 |
| Vendor Settlement | Rs. 90 |

The postpaid model credits you and the vendor account with the full settlement amount. Cashfree sends a collective invoice along with the Payment Gateway charges, you pay for the invoice.

| Bill to | Merchant settlement amount | Vendor settlement amount |
| :- | :- | :- |
| Merchant | 10 | 90 |
| Vendor | 10 | 90 |
| Invoice amount to the merchant | 2 | 0 |

You will receive details on the service charges in the following sections:

* Reports
* Settlement API
* Vendor Recon API
* Vendor Settlement Webhook

<Tip>
  - The invoiced amount to vendor capability is not available in the postpaid model currently.
  - You can request this functionality through your account manager. It is a one-time setup, and you can edit the configurations at any point in time.
</Tip>


# Data to Test Integration
Source: https://www.cashfree.com/docs/payments/split/data-to-test

Use Cashfree Easy Split test data to validate your sandbox integration with sample vendor IDs, order payloads, and split scenarios before going live.

Use this guide to access detailed sample data and inputs for testing your API integration across multiple scenarios.

## Schedule options supported

The table below lists the available settlement schedule options you can configure with Easy Split payments.
Each option specifies when funds will be settled based on the timing of transactions.

| ID | Description |
| :- | :- |
| 1 | T+1 settlement at 11:00 AM |
| 2 | T+2 settlement at 11:00 AM |
| 3 | All transactions from 4:45 PM T-1 to 10:45 AM T+0 settled at 11:15 AM T+0, and, 10:45 AM T+0 to 4:45 PM T+0 at 5:15 PM T+0. |
| 4 | All transactions from 2:00 PM T-1 to 2:00 PM T+0 settled at 3:00 PM T+0. |
| 5 | All transactions till 5.30 PM at 6:00 PM |
| 6 | Instant settlement every hour between 7:00 AM and 5:00 PM on working days. |
| 7 | Instant settlement every 3 hours between 8:00 AM and 5:00 PM on working days. |
| 8 | Instant settlement every hour 24\*7. |
| 9 | Instant settlement every 3 hours 24\*7. |
| 11 | Weekly every 1st working day. |
| 12 | Monthly every 1st working day. |
| 13 | T+1 settlement at 09:00 AM |
| 14 | Instant settlement every 15 minutes 24\*7. |
| 15 | T+3 settlement at 11:00 AM |
| 16 | T+7 settlement at 11:00 AM |

## List of business types

Refer to the table below for supported business types to simulate and test various Easy Split payment scenarios during integration.

| Business types |
| :- |
| B2B |
| Digital Goods |
| E-commerce |
| Education |
| Financial Services |
| Food and Beverages |
| Gaming |
| Government |
| Grocery |
| Health care |
| Insurance |
| Jewellery |
| NBFCs/Organisations into Lending |
| Logistics |
| Miscellaneous |
| Mutual funds/Broking |
| Non Profit/Non-Governmental Organisation(NGO) |
| Online Gaming |
| Open and Semi Open Wallet |
| Pan shop |
| Pharmacy |
| Readymade |
| Real Estate, Housing, Rentals |
| Retail and Shopping |
| SaaS |
| Social Media and Entertainment |
| Society/Trust/Club/Association |
| Telecom |
| Travel and Hospitality |
| Utilities |
| Chit Funds |
| Web host/Domain seller |
| Professional Services (Doctors, Lawyers, Architects, CAs, and other Professionals) |

## List of account types

Refer to the table below for supported account types to configure split payments.
These account types allow you to specify the beneficiary accurately in your API integration and test various scenarios.

| Account types |
| :- |
| Govt Authority/ULBs/Municipalities |
| Individual |
| Limited Liability Partnership (LLP) |
| Private Ltd or Public Ltd |
| Proprietorship |
| Society/Trust/Clubs/NGO/Association |

## Sample bank account numbers, UPI and VPA

**Bank account numbers**

Refer to the table below for sample bank account numbers and IFSC codes to simulate various vendor settlement outcomes during bank transfer integration testing.

| Name | Account number | IFSC | Remarks |
| :- | :- | :- | :- |
| John Doe | 00011020001772 | HDFC0000001 | Success |
| John Doe | 000890289871772 | SCBL0036078 | Success |
| John Doe | 000100289877623 | SBIN0008752 | Failed at the bank |
| John Doe | 2640101002729 | CNRR0002640 | Failure-invalid IFSC code |
| John Doe | 026291800001190 | YESB0000262 | Failure-invalid account number |
| John Doe | 02014457596969 | CITI0000001 | Success (later reversed) |
| Jon D | 026291800001191 | YESB0000262 | Failure-account holder name matching failed |

**UPI**

To test UPI transfers, specify the vendor's UPI Virtual Payment Address (VPA) when adding the vendor.
Refer to the table below for sample VPAs to simulate various UPI transfer outcomes during testing.

| VPA | Remarks |
| :- | :- |
| success\@upi | Successful UPI transfer |
| incorrect\@upi and invalid\@upi | Failed UPI transfer |

## Test details

**GSTIN details**

Refer to the sample GSTINs in the table below to simulate various tax validation scenarios during integration testing.

| GSTIN | Remarks |
| :- | :- |
| 29AAICP2912R1ZR | Valid |
| 27ABCFGH5678D1Z | Valid |
| 36JKLPQR9012E2Y | Valid |
| 45XYZLMN2345G3W | Valid |
| 12PQRST6789A4BC | Valid |
| 39ABCDE0987F6GH | Valid |
| 23UVWXYZ5678H5D | Valid |
| 05BBICP2912R1ZR | Valid |
| 29AAIZP2912R1ZR | Invalid |
| 05BBICA2912R1ZR | Invalid |

**PAN details**

Refer to the sample PAN details below to simulate identity verification and compliance scenarios during integration testing.

| PAN | Remarks |
| :- | :- |
| Individual PAN-ABCPV1234D | Valid |
| Individual PAN-XYZPP4321W | Valid |
| Individual PAN-AZJPG7110R | Valid |
| Business PAN-ABCCD8000T | Valid |
| Business PAN-XYZHP2000L | Valid |
| Business PAN-AAAHU4383C | Valid |
| Business PAN-AMJCL2021N | Valid |
| Individual PAN-DEFPV0126D | Invalid |
| Individual PAN-TUVPP5678W | Invalid |
| Business PAN-LMNCD8010T | Invalid |
| Business PAN-EFGHH2020L | Invalid |

**Passport details**

Refer to the sample passport details below to simulate identity verification scenarios during integration testing.

| Passport | Remarks |
| :- | :- |
| A1012345 | Valid |
| A1018005 | Valid |
| A10 12675 | Valid |
| A10 18345 | Valid |

The video below provides a step-by-step guide to adding a new vendor via API.

<iframe title="Easy Split by Cashfree | 2-step integration to split incoming payments" />


# Easy Split FAQs
Source: https://www.cashfree.com/docs/payments/split/faq

Browse Cashfree Easy Split FAQs covering vendor onboarding, KYC, split scheme configuration, refunds, settlements, and marketplace payout scenarios.

<AccordionGroup>
  <Accordion title="What features does Easy Split provide?">
    Some features our Easy Split provides:

    * Faster settlement to your vendors (T + 2 settlement cycle).
    * Unburden yourself from opening and managing a Nodal account.
    * Route payment from each order to vendors easily.
    * Individual commissions, simplify taxes and much more.
    * Make on-demand adjustments (refunds/bonus) to vendor payouts.
    * Works for non-PG or Cash on delivery orders as well.
    * Access vendor ledger wherever you need using our APIs or our dashboard.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Why should I consider Easy Split?">
    Easy Split automates payment splitting, helping you manage vendors and transactions effortlessly. With Easy Split, you can:

    * Onboard, manage, and pay vendors with ease.
    * Split payments and handle refunds at the order level.
    * Track settlements, refunds, and earnings through detailed reports.

    **Key Benefits:**

    * **Simplify Settlements:** Save your Finance team time with fewer banking tasks.
    * **Streamline Accounting:** Accept only your earnings, making tax computation easier.
    * **Clear Ledger Insights:** Access historical credits, debits, and earnings per order, vendor, or month.

    **Go Global:**

    * Onboard and support international merchants seamlessly.
    * Automate payouts to their home bank accounts with a standard T+2 payment cycle.

    Contact sales to learn [more](https://www.cashfree.com/contact-sales/)

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Handling PG Refunds in Easy Split">
    Refunds are a feature on PG that allows you to return funds back to the payment source. If the PG on your account is linked to Easy Split, then you also need to factor out how vendors will bear the liability for a refund. By default, the balance of respective vendors is debited in the proportion of their commission for the order. For example, let's say there is an order of Rs.100 where Vendor 1 gets Rs. 60 and Vendor 2 gets Rs. 40. This order has a refund of Rs. 50 against it. In such a case, Vendor 1 will receive a debit of Rs. 30 on their balance, and Vendor 2 will have a debit of Rs. 20 against it. This will be adjusted in the next payout to the respective vendors. However, this feature can be turned off in your account if you want to handle the debits against the vendors yourself.

    [Interested in Easy Split? Contact Sales for more information.](https://www.cashfree.com/contact-sales/)

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How many hours do I have to spend every day to manage settlements?">
    Zero! Everything is automated—from receiving payments through Payment Gateway to settling funds in Vendor's bank account. Focus on growing your business while we handle the rest!

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How can we add vendors at the platform for Settlement?">
    Vendors can be added manually from the dashboard. To add a new vendor,

    Go to Payment Gateway Dashboard > Easy Split - Vendor > [Add Vendor](/docs/payments/split/vendor/add).

    Enter the following details:

    Vendor ID - ID of the vendor.
    Phone Number - phone number of your vendor.
    Email ID - Email address of your vendor.
    Vendor Line of Business - Select your vendor’s line of business. Click here to know more.
    Vendor Business Type - Select the business type of your vendor. Click here to know more.
    Settlement Cycle - Select the schedule option through which you want to settle your vendors. Click here to know the available settlement cycles.
    Once done, click Next.
    Mention the Vendor Bank Account Details such as Account Holder Name, Account Number, and IFSC Code or UPI VPA to process payments to the vendor account.

    We also support automated addition through the APIs.

    The documentation for the APIs is available here. [Read more](https://www.cashfree.com/docs/api-reference/payments/latest/easy-split/create-vendor#create-vendor).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are the charges involved for Vendor payouts? Are these debited from the merchant's nodal account?">
    Charges will be communicated by your account manager. It is debited from the merchant's balance in the nodal account.

    **Example:**
    If a settlement of Rs 100 is done, Rs 100 + charges will be debited. Invoice for payout is available on the dashboard separate from payment gateway charges.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are the different possible states a transaction goes through once it’s been added against a Vendor?">
    Only successful transactions get added to a Vendor's balance. The accrued balance gets settled.
    The status can be:

    * **SUCCESS**
    * **FAILURE**
    * **IN PROGRESS**
      Read [more](/docs/payments/split/settlements/failure-reasons)

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How is the invoice presented to the merchant for the charges incurred for the payout?">
    Charges will be communicated by your account manager. It is debited from the merchant's balance in the nodal account.

    **Example:**
    If a settlement of Rs 100 is done, Rs 100 + charges will be debited.

    The invoice for the payout is available on the dashboard, separate from the payment gateway charges.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How many settlements do vendors receive per day?">
    One. Settlement of all the unsettled transactions are grouped together and sent as a single payout. We share the bank reference number for the transfers, that can be shared with the vendors for tracking purposes.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What is the Transfers option under the Vendor menu?">
    A transfer is a settlement to the vendor. The transaction is the payment that
    a customer may have made, which was added to the Settlement account manually
    or via API.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What exactly is Easy Split?">
    Easy Split automates payment splitting between you and your vendors. With Easy Split, you can:

    * Onboard, manage and disburse payments to vendors.
    * Perform splits at order level and manage refunds from vendors smoothly.
    * Track all transactions through detailed reports covering:
      * Settlements
      * Refunds
        See the [Easy Split overview](/docs/payments/split/overview) to know more.

        <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How is vendor settlement managed when there are multiple vendors linked to one transaction?">
    At the time of adding a transaction, you can assign the appropriate numeric
    commission amount against each vendor that you add with Cashfree.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How to add vendors in Easy Split?">
    Go to Payment Gateway Dashboard > Easy Split - Vendor > Add Vendor.

    Enter the following details:

    Vendor ID - ID of the vendor.
    Phone Number - phone number of your vendor.
    Email ID - Email address of your vendor.
    Vendor Line of Business - Select your vendor’s line of business. Click here to know more.
    Vendor Business Type - Select the business type of your vendor. Click here to know more.
    Settlement Cycle - Select the schedule option through which you want to settle your vendors.
    See [available schedule options](/docs/payments/split/vendor/add#available-schedule-options) to know the available settlement cycles.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are the different use cases of Easy Split?">
    Marketplace Aggregators – Split customer payments among vendors, manage commissions, and track transactions in real-time.

    * **EdTech Platforms** – Collect student payments and distribute funds to instructors after deducting charges.
    * **Franchise & Multi-Branch Outlets – Centrally manage payments and route funds to individual branches or stores.**
    * **Investment & Insurance Marketplaces – Settle 100% of the order amount to AMCs or insurers with same-day reconciliation.**
    * **Educational Institutes** – Automate payment splits for tuition, hostel, stationery, and other fees.
    * **On-Demand Services** – Seamlessly split payments for cabs, flights, food delivery, and more.

    See [Easy Split use cases](/docs/payments/split/use-cases) to know more

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are the top features of Easy Split?">
    * Add/Update Vendor: You can add or update your vendor details by providing basic information about the vendor and their account details.
    * Split after payment success: This feature allows to initiation of split after successful confirmation of payment by the customer.
    * Transfer Vendor Balance: You can initiate manual Credit/Debit of a configured vendor-configured settlement account.
    * Refund before split: If the refund is initiated before the vendor split is shared, Cashfree directly refunds the money to the customer payment instrument in the next settlement.
    * Refund after split: If the refund is initiated after the vendor split is shared - The refund will be done from your and vendor’s settlement account according to the respective transaction split created.
    * Deferred Settlement: This API allows you to assign a settlement eligibility date for an order and vendor combination.
      For more information, see [Easy Split features](/docs/payments/split/features).

      <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I edit vendor details once added in Easy Split?">
    While adding vendors, if you have specified incorrect vendor details or missed adding some information, you can modify it using the **Edit Vendor** feature on the product dashboard or use the [Update Merchant Details API](https://www.cashfree.com/docs/api-reference/payments/latest/easy-split/update-vendor-details).

    To edit the details of the vendor you have already added:

    1. Go to **Payment Gateway Dashboard > Easy Split - Vendor**.
    2. Click the ellipsis icon on the vendor you want to make changes to and select **Edit Vendor**.

    **You can update the following details:**
    **Vendor details:**

    * Vendor phone number
    * Vendor email ID
    * Settlement cycle
    * Dashboard access

    **Vendor bank account details:**

    * Account holder name
    * Account number
    * IFSC code
    * UPI VPA
    * Verify account details option

    **KYC details:**

    * Vendor type
    * Business type
    * Documents (Based on the vendor type and business type of your vendors)

    Once done updating the changes, click on the **Update Vendor Details** option to save your changes.

    **Delete Vendor**
    You can delete the added vendors from the dashboard:

    1. Click the ellipsis icon on the vendor you want to delete.
    2. Select **Delete Vendor**.
    3. Click **Delete** in the pop-up window.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I upload multiple vendors at once in Easy Split?">
    **Batch Upload**
    Use the **Batch Upload** feature to add a large number of vendors at a time. Add all the required details in a single file as per the required format and upload the file. Download the sample file to know what details are required to be filled in the batch file.

    **To upload a batch file:**

    1. Go to **Payment Gateway Dashboard > EasySplit - Vendor** and click **Upload File**.
    2. Click **Choose a file** to select the file you want to upload, and then click **Upload**.

    **Key Points:**

    * The maximum file size allowed is **8 MB**, and a maximum of **50 records** can be included in the file.
    * The file must be in the suggested format. If there are errors in the uploaded file, resolve all errors and upload the file again.

    After successful processing, all vendor details will be added, and you can start processing payments to these vendors.

    You can view the vendors that are added successfully from the uploaded files in the **Easy Split - Vendor** screen. An error log (if any) will also get downloaded to view more details.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How does split payments work?">
    To split payments to your vendors using Easy Split, you must first ensure the feature is activated for your Payment Gateway account. Fill out the Support Form or contact your Account manager to enable it for you. The feature should be activated for your Test and Production environment.

    To split payments to vendors;

    Add Vendor
    Create Order
    Accept Payment
    Split Payment
    View Split Settlement Details
    Manage Refunds using Refund Splits
    Manage Adjustments
    See the [Easy Split overview](/docs/api-reference/payments/latest/split/easy-split-overview) to view it graphically

    For more information, see the [Create Order API](/docs/api-reference/payments/latest/orders/create-order) and the [Refund API](/docs/api-reference/payments/latest/refunds/create-refund).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Why do I get 'Transaction already processed, not eligible for split' when splitting after payment?">
    The [Split After Payment](/docs/payments/split/features) feature is not enabled by default. To split a transaction after payment, fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) to enable it and configure the maximum allowable split delay, up to 48 hours after payment. You cannot retroactively split transactions created before you enable the feature.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are the different types of vendor settlements I can choose from?">
    You can define the settlement cycles right when you add the vendor. You can settle your vendors through the following settlement modes:

    * [Vendor Instant Settlement](/docs/payments/split/settlements/instant)
    * [Vendor Standard Settlement](/docs/payments/split/settlements/standard)
    * [Vendor On-Demand Settlement](/docs/payments/split/settlements/on-demand)

    To view the settlements, go to [Payment Gateway Dashboard](https://www.cashfree.com) > Settlements > Vendor. Vendor settlement details such as date and time, settlement type, vendor ID, settlement ID, and settlement status are displayed.

    Generate the settlement recon report for each vendor settlement to view all the transaction details associated with the settlement, including any adjustments/refunds. Provide the file name, choose the file format, and click Generate Report.

    Once you generate the report, you will be automatically redirected to the Reports section.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I delay my settlements to vendors?">
    You can delay vendor settlements by enabling deferred settlements in your account. To do this, ensure the Split API is called within the scheduled interval; otherwise, the full transaction amount will be credited to you.

    Delays can be added at two levels:

    Order Split Delay Post Successful Payment – Delay settlements after a payment is completed.
    Defer Settlement – Hold settlements for a specified period before processing.
    See [delayed settlements overview](/docs/payments/split/settlements/delay/overview) to know more

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are the different reports I have to track vendor payments?">
    The vendor reconciliation report lists all the transactions, adjustments, settlements and refunds that are associated with vendors. This will help you reconcile all transactions from your vendors with their respective settlement ID, time, and UTR.
    Cashfree offers a wide range of reports such as:
    Vendor Recon Report
    Transaction Summary Report
    Refunds Report
    Vendor Split Settlement Report

    To know how to view these reports, see [reconciliation reports](/docs/payments/split/reports/recon)

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How do refunds get handled?">
    Refunded amount gets adjusted during the next settlement cycle. It will be deducted from commission amount of vendors who received settlement on that transaction.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What reports are available to track vendor payments?">
    | Report type | Description |
    | - | - |
    | Vendor Recon Report | Reconcile vendor transactions and payments |
    | Transaction Summary Report | View an overview of all transactions |
    | Refunds Report | Track refund statuses and adjustments |
    | Vendor Split Settlement Report | Monitor vendor settlement details |

    View reports by day, week, or custom date range. Filter, search, and download options are available.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How can I delay settlements to vendors?">
    | Delay type | Description |
    | - | - |
    | Order-Level Delay | Set delay for individual transactions |
    | Vendor-Level Delay | Set delay for specific vendors |

    <Note>
      Enable deferred settlements in your account settings. Ensure the Split API is called within the configured settlement interval.
    </Note>

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What is the maximum period Easy Split can hold funds in deferred settlement?">
    Easy Split supports a deferred settlement period of up to 45 days. You can hold a vendor's settlement amount for up to 45 days from the transaction date. If you take no action within that window, the held amount settles to the merchant. This limit cannot currently be extended. See [Delay vendor settlements](/docs/payments/split/settlements/delay/order-level) to configure a delay within this limit.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are the different types of vendor settlements?">
    | Settlement type | Description |
    | - | - |
    | Instant Settlement | Funds transferred immediately |
    | Standard Settlement | Funds transferred on a scheduled cycle |
    | On-Demand Settlement | Funds transferred manually |

    View settlements at: Payment Gateway Dashboard > Settlements > Vendor.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How can I add multiple vendors at once?">
    Use the **Batch Upload** feature:

    1. Download the sample file
    2. Enter vendor details in the specified format
    3. Upload the completed file

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I edit vendor details after adding them?">
    | Edit method | Access path |
    | - | - |
    | Dashboard | Payment Gateway Dashboard > Easy Split - Vendor > Edit Vendor |
    | API | Use the Update Merchant Details API |

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What is the correct request body field name for updating the vendor settlement eligibility date?">
    When you update a vendor's settlement eligibility date, use `settlementEligibilityDateUpdate` in the JSON request body. Provide the date in the format `YYYY-MM-DD HH:mm:ss`. See the sample request in [Defer Settlement](/docs/payments/split/settlements/delay/vendor-level).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are the key use cases for Easy Split?">
    | Use case | Description |
    | - | - |
    | Marketplace Aggregators | Split payments with multiple product vendors |
    | EdTech Platforms | Share fees with instructors or educators |
    | Franchise & Multi-Branch | Route payments to individual stores or locations |
    | Investment/Insurance Marketplace | Same-day settlement to AMC/insurer accounts |
    | Educational Institutes | Allocate student payments across departments |
    | E-Commerce | Manage sellers within a single order |
    | Online Appointments | Share earnings with service providers |

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are the vendor limits per transaction?">
    You can split a single transaction among a maximum of **5 vendors**.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How are refunds handled?">
    Refund amounts are:

    * Deducted from the merchant’s next settlement
    * Adjusted from vendor commissions if configured
    * Applied only to vendors who received the original settlement

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How can vendors be added to Easy Split?">
    | Method | Description |
    | - | - |
    | Manual | Add vendors from the dashboard |
    | API | Use the Create Vendor API for automation |

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Why is an Easy Split vendor stuck in IN_BENE_CREATION and not becoming ACTIVE?">
    Activation runs asynchronously. When you create a vendor with a valid bank account and PAN, the expected timelines are:

    * **Sandbox**: typically within 10 minutes.
    * **Production**: may take longer depending on the processing queue.

    If the vendor remains in `IN_BENE_CREATION` after 24 hours, follow these steps:

    1. Poll the [Get Vendor API](/docs/api-reference/payments/latest/easy-split/get-vendor-all-details) to check the current status.
    2. Fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) with the vendor IDs so Cashfree can investigate.

    See [Add a vendor](/docs/payments/split/vendor/add) for the full vendor status workflow.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How many settlements do vendors receive daily?">
    Vendors receive **one settlement per day**:

    * Includes all unsettled transactions.
    * Bank reference number provided for each payout.
    * Share the reference number with vendors for tracking.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How are refunds handled when the vendor's share is still held as deferred?">
    If you initiate a refund after you create a split but before vendor settlement, use the [Create Refund API](/docs/api-reference/payments/latest/refunds/create-refund) with split details. Easy Split deducts the refund amounts from both the merchant and vendor balances, including the deferred or held share, before it refunds the customer. If the vendor has insufficient balance, adjust the balance first. See [Initiate Refunds](/docs/payments/split/refund/initiate) and [Adjust Vendor Balance](/docs/payments/split/vendor/balance/adjust).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How can I identify which vendor is linked to a specific adjustment if I don't have the vendor ID?">
    Use the Vendor Reconciliation API in time-period mode. Make a `POST` request to `/pg/recon/vendor` with a `start_date` and `end_date` in the filters, without specifying a `merchant_vendor_id`. The API returns a paginated list of reconciliation data for all vendors within that date range. Each record includes a `merchant_vendor_id` field, which you can use to identify the vendor associated with the adjustment by matching the amount, timestamp, or other known details.

    **Endpoint:** `POST https://api.cashfree.com/pg/recon/vendor`

    **Sample request body:**

    ```json theme={"dark"}
    {
      "pagination": {
        "limit": 100,
        "cursor": null
      },
      "filters": {
        "start_date": "2026-08-01T00:00:00Z",
        "end_date": "2026-08-31T23:59:59Z"
      }
    }
    ```

    <Note>
      Records older than 6 months require a date range in the request. The pagination limit must be between 10 and 100 per call.
    </Note>

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What happens to a held vendor share after the 45-day limit?">
    The 45-day period does not reverse the held vendor share to the vendor. You must initiate the split within the applicable window for that amount to settle to the vendor. If you take no action, or if you do not provide split details in the [Create Order API](/docs/api-reference/payments/latest/orders/create-order), the entire order amount settles to the merchant after the applicable period. See [Order Split Delay](/docs/payments/split/settlements/delay/order-level).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How are disputes handled for orders using Easy Split?">
    For disputed transactions, Cashfree withholds the disputed amount from the merchant balance rather than the vendor balance. Vendor settlements continue according to the configured cycle. Cashfree either reverses the withheld amount or processes it to the customer based on the final dispute status. Cashfree does not extend the 45-day window for disputes because it handles them at the merchant balance level. See [Disputes overview](/docs/payments/manage/disputes/overview).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Are there rate limits or volume caps for the Create Vendor API?">
    There is currently no specific limit on the number of vendors you can create with the [Create Vendor API](/docs/api-reference/payments/latest/easy-split/create-vendor).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are the standard PG charges for cards, UPI, and net banking?">
    For current Payment Gateway charges across cards, UPI, and net banking, see [Pricing](/docs/help/account/pricing). Standard rates apply after any promotional campaign limits are reached.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are the additional charges for using Easy Split?">
    Easy Split is an additional feature on top of the Payment Gateway. It carries a charge of 0.2% per split in addition to the standard PG charges.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Where can I find the Easy Split API documentation?">
    The following pages cover the Easy Split integration APIs:

    * [Easy Split overview](/docs/api-reference/payments/latest/split/easy-split-overview)
    * [Create vendor](/docs/api-reference/payments/latest/easy-split/create-vendor)
    * [Upload vendor documents](/docs/api-reference/payments/latest/easy-split/upload-vendor-docs)
    * [Create static split](/docs/api-reference/payments/latest/easy-split/create-static-split-configuration)
    * [Split after payment](/docs/api-reference/payments/latest/easy-split/split-after-payment)
    * [Vendor settlement webhooks](/docs/api-reference/payments/latest/split/webhooks/vendor-settlement-webhooks)
    * [Vendor status change webhooks](/docs/api-reference/payments/latest/split/webhooks/vendor-status-change-webhooks)

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Which APIs should I use to split payments between multiple vendors and process refunds?">
    You can use Easy Split to manage vendor splits. Create vendor splits while creating an order using the [Create Order API](/docs/api-reference/payments/latest/orders/create-order), and the split amount will be settled to the respective vendor based on their configured settlement cycle. Refunds can be processed using the [Refund API](/docs/api-reference/payments/latest/refunds/create-refund).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Does Easy Split support automated payouts to vendors after a successful payment?">
    Yes. Easy Split can split the payment amount among the configured vendors automatically. Pass the split details through the API, and Cashfree splits the amount according to those instructions. See [Easy Split overview](/docs/payments/split/overview).

    <iframe title="FAQs feedback component" />
  </Accordion>
</AccordionGroup>


# Features
Source: https://www.cashfree.com/docs/payments/split/features

Explore Cashfree Easy Split features for marketplaces, including vendor onboarding, split schemes, automated settlements, refund adjustments, and recon.

| Feature | Resource | Description |
| - | - | - |
| **Add/Update Vendor** | **Configuration:**<br />For NEFT/IMPS bank transfer:<br />a. Vendor unique ID<br />b. Phone and Email ID<br />c. Bank Account Holder Name<br />d. Account Number<br />e. IFSC<br />f. Schedule Option<br /><br />For UPI Transfers:<br />a. Vendor unique ID<br />b. Phone and Email ID<br />c. UPI VPA<br />d. Schedule Option | You can add or update your vendor details by providing basic information about the vendor and their account details. Details can be shared either for bank transfer or for UPI VPA transfer.<br />- Add/Update Vendor is implemented instantly.<br />- Complement add/update with bank verification, you can use Bank Account Verification APIs to avoid failures in settlement due to incorrect bank details.<br />- You can configure schedule options for each vendor during add/update. For faster schedule options, raise a request to your account manager or [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1). |
| **Split after payment success** | **Configuration:**<br />- Split by Amount<br />- Split by Percentage<br />- Order split Delay: 2 days (can be extended further if required) | - This will be active by default when Easy Split is enabled. The default configuration is as per the schedule option.<br />- This feature allows to initiation of split after successful confirmation of payment by the customer.<br />- Only successfully captured transactions can be settled to split accounts.<br />- Perform split operation for the successful order within 2 days (can be extended further if required).<br />- If the split is not provided in the configured window, the settlement will happen to your account by default. |
| **Transfer Vendor Balance** | **Configuration:**<br />1. Vendor Credit and Merchant Debit - Type: "CREDIT"<br />2. Vendor Debit and Merchant Credit - Type: "DEBIT" | You can initiate manual Credit/Debit of a configured vendor-configured settlement account. This can only be done if the debit account has sufficient balance to transfer the respective payment. |
| **Refund before split** | **Configuration:**<br />- OrderID<br />- Refund Amount | If the refund is initiated before the vendor split is shared, Cashfree directly refunds the money to the customer payment instrument in the next settlement. |
| **Refund after split** | **Configuration:**<br />- OrderID<br />- VendorID<br />- Refund Amount<br />- Refund Split by Amount or Percentage | If the refund is initiated after the vendor split is shared - The refund will be done from your and vendor's settlement account according to the respective transaction split created. |
| **Deferred Settlement** | **Configuration:**<br />- OrderID<br />- VendorID<br />- Settlement Eligibility Date: Default 2 days (can be extended further if required) | - This feature has to be pre-configured to defer settlement to specific vendors (Contact your account manager to use this defer settlement).<br />- This API allows you to assign a settlement eligibility date for an order and vendor combination.<br />- Vendors post their settlement time will be settled in the next settlement.<br />- Only successfully captured transactions can be settled to split accounts. |


# Overview
Source: https://www.cashfree.com/docs/payments/split/overview

Use Cashfree Easy Split to collect marketplace payments, deduct commissions, settle vendors automatically, and adjust vendor balances during customer refunds.

Easy Split is a split payment solution for marketplaces that helps merchants accept payments from customers, deduct commissions, and automatically settle payments to vendors. It also handles customer refund processing and adjusts vendor settlements accordingly.

Easy Split enables merchants to:

* Onboard and manage vendors, and disburse payments to them.
* Perform splits at order level and handle vendor refunds seamlessly.
* Track all transactions through detailed reports on settlements and refunds.

<Tip>Install [Cashfree Agent Skills](/docs/tools-ai/cashfree-agent-skills) to bring Cashfree product knowledge into your AI coding assistant (Claude Code, Cursor, VS Code Copilot, Gemini CLI, and more) to answer integration questions and generate accurate code without leaving your editor.</Tip>

<Note>
  Easy Split is available when a Cashfree account is set up with one of the following collections products:

  * Payment Gateway<br />
  * Payment Links/Forms<br />
  * Subscriptions

  To enable Easy Split on your account, please contact your account manager.
</Note>

<div>
  <iframe title="Easy Split- Cashfree" />
</div>

## Easy Split workflow

The following working diagram illustrates the end-to-end flow of payments and settlements when using Easy Split.

<img alt="" />

## Key benefits

Easy Split provides the following capabilities to streamline vendor payments and reconciliation:

* **Higher checkout success:** Auto-retry option, saved card support, smart routing across multiple banks and networks, and optimised integration flows for mobile and web with higher uptime.
* **Payment splitting:** Split customer payments among vendors at order level, choose between instant settlements or custom schedules, and set order-level settlement timing for each vendor.
* **Webhook-based reconciliation:** Get notified on transaction status and reconcile payments, refunds, and settlements in real-time using webhooks.
* **Comprehensive reporting:** Access detailed reports on transactions, settlements, refunds, and vendor payments with centralised reporting.
* **Flexible refund management:** Specify refund split ratios between the merchant and vendors, and automate refund adjustments even after vendor settlements.
* **Hassle-free finance closures:** Eliminate manual work of figuring out whom to pay and when, simplifying monthly and yearly finance closures.

## Explore Easy Split

Explore industry-specific use cases, review available features and configuration options, follow step-by-step implementation scenarios, and learn how to split payments to vendors after a successful collection.

<CardGroup>
  <Card title="Use cases" icon="store" href="/docs/payments/split/use-cases">
    See how Easy Split supports marketplace aggregators, EdTech and platform businesses, franchise and multi-branch outlets, and similar models.
  </Card>

  <Card title="Scenarios" icon="route" href="/docs/payments/split/recipes/scenarios">
    Follow step-by-step scenarios for creating splits during order creation and in other flows.
  </Card>
</CardGroup>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/payments/split/faq">FAQs</a></li>
    <li><a href="/docs/api-reference/payments/latest/split/easy-split-overview">Easy Split API</a></li>
  </ul>
</div>


# Scenarios
Source: https://www.cashfree.com/docs/payments/split/recipes/scenarios

Explore common Cashfree Easy Split scenarios with sample order payloads showing how to split payments across vendors, commissions, and platform fees correctly.

## Scenario 1: Create split during order creation

The flow diagram below shows how a split happens when an order is created. It is a two-step process.

<img alt="" />

<Warning>Split by amount is not supported for vendor-prepaid charges. If the vendor is billed, you can only split the order by percentage.</Warning>

**First Step: Customer completes the payment**

<Steps>
  <Step title="Step 1: The customer visits the merchant website or the application and adds goods from different vendors to the shopping cart. The customer proceeds to complete the payment.">
    <Steps>
      <Step title="Step 1.1: The merchant receives the payment request from the customer and creates an order. The order details contain information such as order ID, order amount, split details and customer name. The merchant creates an order along with splits in the Cashfree Payment Gateway system." />

      <Step title="Step 1.2: Cashfree Payment Gateway receives the order details and creates a payment link for that order. This payment link is sent to the merchant." />

      <Step title="Step 1.3: The merchant receives the payment link and sends it to the customer to complete the payment." />

      <Step title="Step 1.4: The customer clicks the link and completes the payment. The amount is received by Cashfree Payment Gateway." />

      <Step title="Step 1.5: The payment details are captured at Cashfree Payment Gateway end." />

      <Step title="Step 1.6: The payment details are stored in the Cashfree system and the payment status is sent to the merchant through payment webhooks." />

      <Step title="Step 1.7: The merchant sends the payment status to the customer." />

      <Step title="Step 1.8: The customer receives the payment status." />
    </Steps>
  </Step>
</Steps>

**Second Step: Easy Split processes the split internally**

<Steps>
  <Step title="Step 2: Once the payment is initiated, internal split calls take place. The amount is split based on the split information the merchant provides.">
    <Steps>
      <Step title="Step 2.1: Easy Split processes the vendor split amount first and settles the amount to the vendor bank account based on the vendor schedule option. The vendor settlement webhook is initiated." />

      <Step title="Step 2.2: Easy Split processes the merchant split amount and settles the amount to the merchant bank account based on the merchant schedule option. The merchant settlement webhook is initiated." />
    </Steps>
  </Step>
</Steps>

## Scenario 2: Create split after payment success

The flow diagram below shows how a split happens if the payment is successful. It is a two-step process.

<img alt="" />

**First Step: Customer completes the payment**

<Steps>
  <Step title="Step 1: The customer visits the merchant website or the application and adds goods from different vendors to the shopping cart. The customer proceeds to complete the payment.">
    <Steps>
      <Step title="Step 1.1: The merchant receives the payment request from the customer and creates an order. The order details contain information such as order ID, order amount, and customer name. The merchant creates an order in the Cashfree Payment system." />

      <Step title="Step 1.2: Cashfree Payment Gateway receives the order details and creates a payment link for that order. This payment link is sent to the merchant." />

      <Step title="Step 1.3: The merchant receives the payment link and sends it to the customer to complete the payment." />

      <Step title="Step 1.4: The customer clicks the link and completes the payment. The amount is received by Cashfree Payment Gateway." />

      <Step title="Step 1.5: The payment details are captured at Cashfree Payment Gateway end." />

      <Step title="Step 1.6: The payment details are stored in the Cashfree system and the payment status is sent to the merchant through payment webhooks." />

      <Step title="Step 1.7: The merchant sends the payment status to the customer." />

      <Step title="Step 1.8: The customer receives the payment status." />
    </Steps>
  </Step>
</Steps>

**Second Step: Easy Split processes the split after payment success**

<Steps>
  <Step title="Step 2: Once the payment is successful, the payment success webhook is triggered. The merchant shares the split details that contain the split information via the Split API to Cashfree Payment Gateway.">
    <Steps>
      <Step title="Step 2.1: The split is created in the Cashfree system, and Easy Split processes the split based on the split information received from the merchant. The split information has details such as vendor ID, split type, and the amount or percentage to be split with the merchant and vendors." />

      <Step title="Step 2.2: Easy Split processes the vendor split amount first. The amount is settled to the vendor bank account based on the vendor schedule option. The vendor settlement webhook is initiated." />

      <Step title="Step 2.3: Easy Split processes the merchant split amount and settles the amount to the merchant bank account based on the merchant schedule option. The merchant settlement webhook is initiated." />
    </Steps>
  </Step>
</Steps>


# Split After Payment
Source: https://www.cashfree.com/docs/payments/split/recipes/split-a-payment

Split a Cashfree payment after capture by attaching vendor splits to a successful order so the right amount flows to each vendor balance on settlement.

To split payments to your vendors using **Easy Split**, you must first ensure the feature is activated for your **Payment Gateway** account. Fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) or contact your account manager to enable it for you. The feature should be activated for your **Test** and **Production** environment.

To split payments to vendors,

1. [Add Vendor](/docs/api-reference/payments/latest/easy-split/create-vendor)
2. [Create Order](/docs/api-reference/payments/latest/orders/create-order)
3. [Accept Payment](/docs/api-reference/payments/latest/payments/order-pay)
4. [Split Payment](/docs/api-reference/payments/latest/easy-split/split-after-payment)
5. [View Split Settlement Details](/docs/api-reference/payments/latest/easy-split/get-split-and-settlement-details-by-orderid)
6. [Manage Refunds using Refund Splits](/docs/api-reference/payments/latest/refunds/create-refund)
7. [Manage Adjustments](/docs/api-reference/payments/latest/easy-split/create-adjustment)

Watch the video below to learn how money is collected and settlements are split for all incoming funds with multiple parties.

<iframe />

## Add vendors

To initiate payments to multiple vendors involved in a transaction, you need to first add their details, and specify the schedule option for each vendor. Each vendor can have a different schedule option based on their requirements. You must define it when you add the vendor details.

You can add vendor details using the [product dashboard](/docs/payments/split/vendor/add), or using our [Add Vendor API](/docs/api-reference/payments/latest/easy-split/create-vendor)

To process settlements to vendors, you must specify their bank account details or their UPI details.

<Tip>
  Ensure you have the right account details of the vendor to process settlements
  successfully. You can use our [Secure ID](/docs/secure-id/introduction) to verify the vendor account
  details before initiating settlements.
</Tip>

You can also edit and manage vendors using the [Update Vendor Details API](/docs/api-reference/payments/latest/easy-split/update-vendor-details).

**Sample Request to Add Vendor**

```curl theme={"dark"}
curl --location 'https://sandbox.cashfree.com/pg/easy-split/vendors'
--header 'x-client-id: {{clientId}}'
--header 'x-client-secret: {{clientSecret}}'
--header 'x-api-version: 2022-09-01'
--header 'Content-Type: application/json'
--data-raw '{
  "vendor_id": "vendortest40",
  "status": "ACTIVE",
  "name": "customer",
  "email": "[johndoe@cashfree.com]()",
  "phone": "9876543210",
  "verify_account": true,
  "dashboard_access": true,
  "schedule_option": 2,
  "bank": {
   "account_number": "026291800001191",
 	 "account_holder": "John Doe",
 	 "ifsc": "YESB0000262"
  },
  "kyc_details": {
    "account_type": "Proprietorship",
    "business_type": "Jewellery",
    "uidai": "655675523712",
    "gst": "29AAICP2912R1ZR",
    "cin": "L00000Aa0000AaA000000",
    "pan": "ABCPV1234D",
    "passport_number": "L6892603"
  }
}'
```

**Sample Response**

```json theme={"dark"}
{
	"email": "[johndoe@cashfree.com]()",
	"status": "IN_BENE_CREATION",
	"bank": {
		"account_number": "026291800001191",
		"account_holder": "John Doe",
		"ifsc": "YESB0000262"
	},
	"upi": null,
	"phone": "9876543210",
	"name": "customer",
	"vendor_id": "vendortest40",
	"schedule_option": {
		"settlement_schedule_message": "T+2 settlement at 11:00 AM",
		"schedule_id": 2,
		"merchant_default": false
	},
	"kyc_details": {
		"account_type": "Proprietorship",
		"business_type": "Jewellery",
		"documents": [
			{
				"doc_category": "PAN",
				"doc_name": "PAN",
				"doc_value": "ABCPV1234D",
				"status": "VERIFIED",
				"remarks": ""
			},
			{
				"doc_category": "GSTIN",
				"doc_name": "Merchant-Vendor Agreement",
				"doc_value": "",
				"status": "DUE_CURRENTLY",
				"remarks": ""
			}
		]
	},
	"dashboard_access": true
}
```

***

## Create order

After adding vendors you must create an order to accept payments from your customers. Use our [Create Order API](/docs/api-reference/payments/latest/orders/create-order) to do this.

**Sample Request**

```curl theme={"dark"}
curl --request POST
     --url https://sandbox.cashfree.com/pg/orders
     --header 'accept: application/json'
     --header 'content-type: application/json'
     --header 'x-api-version: 2022-09-01'
     --data '
{
  "customer_details": {
    "customer_id": "7112AAA812234",
    "customer_phone": "9898989898"
  },
  "order_currency": "INR",
  "order_amount": 10.34
}
'
```

**Sample Response**

```json theme={"dark"}
{
	"cf_order_id": 2149460581,
	"created_at": "2023-08-11T18:02:46+05:30",
	"customer_details": {
		"customer_id": "409128494",
		"customer_name": "Johmn Doe",
		"customer_email": "[pmlpayme@ntsas.com]()",
		"customer_phone": "9876543210"
	},
	"entity": "order",
	"order_amount": 22,
	"order_currency": "INR",
	"order_expiry_time": "2023-09-09T18:02:46+05:30",
	"order_id": "order_3242Tq4Edj9CC5RDcMeobmJOWOBJij",
	"order_meta": {
		"return_url": "https://example.com/return/{order_id}",
		"notify_url": "https://example.com/notify",
		"payment_methods": "cc"
	},
	"order_note": "some order note LIST",
	"order_splits": [],
	"order_status": "ACTIVE",
	"order_tags": {
		"name": "John",
		"age": "19"
	},
	"payment_session_id": "session_a1VXIPJo8kh7IBigVXX8LgTMupQW_cu25FS8KwLwQLOmiHqbBxq5UhEilrhbDSKKHA6UAuOj9506aaHNlFAHEqYrHSEl9AVtYQN9LIIc4vkH",
	"payments": {
		"url": "https://sandbox.cashfree.com/pg/orders/order_3242Tq4Edj9CC5RDcMeobmJOWOBJij/payments"
	},
	"refunds": {
		"url": "https://sandbox.cashfree.com/pg/orders/order_3242Tq4Edj9CC5RDcMeobmJOWOBJij/refunds"
	},
	"settlements": {
		"url": "https://sandbox.cashfree.com/pg/orders/order_3242Tq4Edj9CC5RDcMeobmJOWOBJij/settlements"
	},
	"terminal_data": null
}
```

***

## Accept payments

After orders are created you must use our [Order Pay](/docs/api-reference/payments/latest/payments/order-pay) API to accept payments from your customers.

**Sample Request**

```curl theme={"dark"}
curl --request POST \
     --url https://api.cashfree.com/pg/orders/pay \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'x-api-version: 2022-01-01' \
     --data '
{
     "payment_method": {
          "upi": {
               "channel": "collect",
               "upi_id": "arun@okicici"
          }
     },
     "order_token": "tScwuzJgZ0PJuVc1b"
}
```

**Sample Response**

```json theme={"dark"}
{
	"payment_method": "upi",
	"channel": "collect",
	"action": "custom",
	"data": {
		"url": null,
		"payload": null,
		"content_type": null,
		"method": null
	},
	"cf_payment_id": 971632209
}
```

***

## Split payment

Before you split the details, ensure vendors involved in the transaction are added. After adding the vendor details you can initiate payment split to your vendors. To split the payment use [Split After Payment API](/docs/api-reference/payments/latest/easy-split/split-after-payment).

You have the option to specify the split percentage-wise or amount-wise. The split amount is always calculated based on the order amount.

**Sample Request - Split details after collecting the payment**

```curl theme={"dark"}
curl --location 'https://sandbox.cashfree.com/pg/easy-split/orders/{order_id}/split'
--header 'x-client-id: {{clientId}}'
--header 'x-client-secret: {{clientSecret}}'
--header 'x-api-version: 2022-09-01'
--header 'Content-Type: application/json'
--data '{
    "split": [
          {
            "vendor_id": "test03",
            "percentage": 50,
            "tags": {
                "product": "Dri-Fit trouser",
                "size": "L",
                "AWB": "NIKE12334"
            }
          },
	  {
            "vendor_id": "test04",
            "percentage": 40,
            "tags": {
                "product": "Gym T-shirt",
                "size": "M",
                "AWB": "NIKE45673"
            }
          }
    ],
    "disable_split": true
}'
```

**Sample Response**

```json theme={"dark"}
//Case1: Split created successfully
{
	"message": "Order split created",
	"status": "OK"
}
```

### Split settlements scenarios

**Scenario 1: Split After Payment Success**

The flow diagram below shows how a split happens if the payment is successful. It is a two step process.

<img alt="" />

First Step: Customer completes the payment

* Step 1: The customer visits the merchant website or the application and adds goods from different vendors to the shopping cart. The customer proceeds to complete the payment.
* Step 1.1: The merchant receives the payment request from the customer and creates an order. The order details contain information such as order ID, order amount, and customer name. The merchant creates an order in the Cashfree Payment system.
* Step 1.2: Cashfree Payment Gateway receives the order details and creates a payment link for that order. This payment link is sent to the merchant.
* Step 1.3: The merchant receives the payment link and sends it to the customer to complete the payment.
* Step 1.4: The customer clicks the link and completes the payment. The amount is received by Cashfree Payment Gateway.
* Step 1.5: The merchant sends the payment details, and it is captured at Cashfree Payment Gateway end.
* Step 1.6: The payment details are stored in the Cashfree system and the payment status is sent to the merchant through payment webhooks.
* Step 1.7: The merchant notifies the payment status to the customer.

Second Step: Easy Split processes the split

* Step 2: Once the payment is successful, the payment success webhook is triggered. The merchant shares the split details that contain the split information via the Split API to Cashfree Payment Gateway.
* Step 2.1: The split is created in the Cashfree system, and Easy Split processes the split based on the split information received from the merchant. The split information has details such as vendor ID, split type, and the amount or percentage to be split with the merchant and vendors.
* Step 2.2: Easy Split processes the vendor split amount first. The amount is settled to the vendor bank account based on the vendor schedule option. The vendor settlement webhook is initiated.
* Step 2.3: Easy Split processes the merchant split amount and settles the amount to the merchant bank account based on the schedule option. The merchant settlement webhook is initiated.

**Scenario 2: Split During Order Creation**

The flow diagram below shows how a split happens when an order is created irrespective of the payment status. It is a two-step process.

<img alt="" />

First Step: Customer completes the payment

* Step 1: Customer visits the merchant website or the application and adds goods from different vendors to the shopping cart. The customer proceeds to complete the payment.
* Step 1.1: The merchant receives the payment request from the customer and creates an order. The order details contain split details such as order ID, order amount, and customer name. The merchant creates an order in the Cashfree Payment system.
* Step 1.2: Cashfree Payment Gateway receives the order details and creates a payment link for that order. This payment link is sent back to the merchant.
* Step 1.3: The merchant receives the payment link and sends it to the customer to complete the payment.
* Step 1.4: The customer clicks the link and completes the payment. The amount is received by Cashfree Payment Gateway.
* Step 1.5: The payment details are stored in the Cashfree system, and the payment status is sent to the merchant through payment webhooks. Easy Split initiates the split irrespective of the payment status.
* Step 1.6: Cashfree captures the payment details, and the payment status is shared to the merchant through payment webhooks.
* Step 1.7: The merchant sends the payment status to the customer.

Second Step: Easy Split processes the split irrespective of the payment status

* Step 2: Once the payment is initiated, internal split calls take place. The amount is split based on the split information the merchant provides.
* Step 2.1: Easy Split processes the vendor split amount first and settles the amount to the vendor bank account based on the vendor schedule option. The vendor settlement webhook is initiated.
* Step 2.2: Easy Split processes the merchant split amount and settles the amount to the merchant bank account based on the merchant schedule option. The merchant settlement webhook is initiated.

### Defer settlement time

You can add delay at:

* [Order Level](/docs/payments/split/settlements/delay/order-level)
* [Vendor Level](/docs/payments/split/settlements/delay/vendor-level)

***

## View split settlement details

Settlements will be processed to vendors based on the schedule option defined for each vendor during vendor creation. The applicable service charges for the order - PG **serviceCharge**, PG **serviceTax**, **splitServiceCharge**, and **splitServiceTax** will be shown in the response.

Use the [Settlement Details API](/docs/api-reference/payments/latest/easy-split/get-split-and-settlement-details-by-orderid) to view the settlements received.

**Sample Response**

```json theme={"dark"}
{
	"cursor": null,
	"data": [
		{
			"amount": 900000,
			"settlement_eligibility_time": "2024-01-08 11:30:00",
			"merchant_order_id": "order_1527072afd7Hlp4lpVLiz7dj0P0i84r1X",
			"tx_time": "2024-01-08 17:00:00",
			"settled": "NO",
			"entity_id": "14910180251",
			"merchant_settlement_utr": "N/A",
			"currency": "INR",
			"sale_type": "CREDIT",
			"customer_name": "Manideep",
			"customer_email": "customer@example.com",
			"customer_phone": "8281554863",
			"merchant_vendor_commission": "810000.00",
			"split_service_charge": "900.00",
			"split_service_tax": "162.00",
			"pg_service_tax": "4698.90",
			"pg_service_charge": "26105.00",
			"pg_charge_postpaid": "1",
			"merchant_settlement_id": "N/A",
			"added_on": "2024-01-08 17:00:00",
			"tags": "tags",
			"entity_type": "transaction",
			"settlement_initiated_on": "N/A",
			"settlement_time": "N/A",
			"order_splits": [
				{
					"split": [
						{
							"merchant_vendor_id": "vendor20Lakh",
							"percentage": 90,
							"tags": null
						}
					],
					"created_at": "2024-01-08 17:00:01"
				}
			],
			"eligible_split_balance": "0.00"
		},
		{
			"amount": 810000,
			"merchant_order_id": "order_1527072afd7Hlp4lpVLiz7dj0P0i84r1X",
			"tx_time": "2024-01-08 17:00:00",
			"settled": "YES",
			"entity_id": "305293",
			"merchant_vendor_id": "vendor20Lakh",
			"currency": "INR",
			"sale_type": "CREDIT",
			"customer_name": "Manideep",
			"customer_email": "customer@example.com",
			"customer_phone": "8281554863",
			"added_on": "2024-01-08 17:00:01",
			"entity_type": "vendor_commission",
			"past_settlements": [
				{
					"settlement_id": 54878,
					"settlement_initiated_on": "2024-01-08 17:14:38",
					"status": "SUCCESS"
				}
			],
			"vendor_split_service_charges": "0.00",
			"vendor_split_service_tax": "0.00",
			"vendor_settlement_time": "2024-01-08 17:14:39",
			"vendor_settlement_initiated_on": "2024-01-08 17:14:38",
			"vendor_settlement_eligibility_time": "2024-01-08 16:50:00",
			"vendor_settlement_id": "54878",
			"vendor_settlement_utr": "1704714278653975",
			"vendor_commission": "810000.00",
			"vendor_pg_service_charge": "0.00",
			"vendor_pg_service_tax": "0.00"
		}
	],
	"limit": 2
}
```

***

## Manage refunds

To initiate partial or full refunds to your customers you can use our [Create Refund API](/docs/api-reference/payments/latest/refunds/create-refund).

**Sample Request**

```curl theme={"dark"}
curl --request POST
     --url https://sandbox.cashfree.com/pg/orders/order_id/refunds
     --header 'accept: application/json'
     --header 'content-type: application/json'
     --header 'x-api-version: 2022-09-01'
     --data '
{
  "refund_amount": 1,
  "refund_id": "refund_00912",
  "refund_note": "refund note for reference",
  "refund_speed": "STANDARD"
}
'
```

**Sample Response**

```json theme={"dark"}
[
	{
		"cf_payment_id": 918812,
		"cf_refund_id": "refund_1553338",
		"refund_id": "REF-123",
		"order_id": "c6G-QMcbm1848",
		"entity": "refund",
		"refund_amount": 100.81,
		"refund_currency": "INR",
		"refund_note": "Refund for order #123",
		"refund_status": "SUCCESS",
		"refund_type": "MERCHANT_INITIATED",
		"refund_splits": [],
		"status_description": "In Progress",
		"refund_arn": "RF12312",
		"metadata": null,
		"created_at": "2021-07-25T08:57:52+05:30",
		"processed_at": "2021-07-25T12:57:52+05:30",
		"refund_charge": 0,
		"refund_mode": "STANDARD"
	}
]
```

## Transfer balance

To manage any adjustments with your vendors you can use our [Vendor Adjustment](/docs/api-reference/payments/latest/easy-split/create-on-demand-transfer) API.

**Sample Request**

```curl theme={"dark"}
  curl --location 'https://sandbox.cashfree.com/pg/easy-split/vendors/{vendor_id}/transfer'
--header 'x-client-id: {{clientId}}'
--header 'x-client-secret: {{clientSecret}}'
--header 'x-api-version: 2022-09-01'
--header 'Content-Type: application/json'
--data '{
    "transfer_from": "VENDOR",
    "transfer_type": "ADJUSTMENT",
    "transfer_amount": 10,
    "remark": "Testing",
    "tags": {
        "product": "Dri-Fit trouser",
        "size": "L",
        "AWB": "NIKE12334"
    }
}'
```

**Sample Response**

```json theme={"dark"}
{
	"transfer_details": {
		"vendor_id": "test03",
		"transfer_from": "VENDOR",
		"transfer_type": "ADJUSTMENT",
		"transfer_amount": 10,
		"remark": "Testing",
		"tags": {
			"product": "Dri-Fit trouser",
			"size": "L",
			"AWB": "NIKE12334"
		}
	},
	"balances": {
		"merchant_id": 152707,
		"vendor_id": "test03",
		"merchant_available_amount": 1942,
		"vendor_available_amount": 0,
		"merchant_unsettled": 2442,
		"vendor_unsettled": 4757.42
	},
	"charges": {
		"service_charges": 2,
		"service_tax": 0.36,
		"amount": 10,
		"billed_to": "MERCHANT",
		"is_postpaid": true
	}
}
```


# Initiate Refunds
Source: https://www.cashfree.com/docs/payments/split/refund/initiate

Initiate Cashfree Easy Split refunds via dashboard or API, choose how to recover funds from vendor balances, and notify customers once refunds are processed.

Easily initiate refunds from the Payment Gateway Dashboard when customers request for return of products. In some scenarios when you have a large number of refunds to be made, you can use the \[Batch Refunds] feature to process the refunds in one go.

The Refunds tab lists all the refunds that are initiated for the date range selected. You can use the Search and Filter options to search for any particular refund or filter for refunds based on the statuses.

To view more details about the refund, click on a particular transaction where a refund has been initiated. The detailed screen appears as shown below:

To initiate a refund,

1. Go to **Payment Gateway Dashboard** > **Transactions** > click **Payments**.
2. Search for the transaction you want to refund and click the **Initiate Refund** option.

<img alt="" />

3. In the **Initiate Refund** screen, specify the **Refund Amount**. Ensure the **Split Refund** option is selected if it is a split refund.\
   **Note**: The split amount cannot exceed refund amount.

4. Specify the refund amount for the respective vendors, and click **OK** to initiate a refund. If it a standard refund, refunds are processed within 2-3 working days. If it is an instant refunds, refunds are processed instantly to the customer account.

<Note>
  You cannot debit a vendor marked as DELETED.
</Note>

<img />

You will get a success message confirming the refund initiation.

<img />

## View vendor split information and refund status

To view vendor split information and the refund status,\
Go to **Payment Gateway Dashboard** > **Transactions** > select the transaction you want to see the details for. A screen appears as shown below:

<img alt="" />

Watch this video to learn how to initiate a refund through the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).

<iframe title="YouTube video player" />


# Refund Scenarios
Source: https://www.cashfree.com/docs/payments/split/refund/scenarios

Walk through common Cashfree Easy Split refund scenarios, including partial refunds, vendor-level deductions, and balance adjustments across payouts.

## Scenario 1: Refund before split

The flow diagram below shows how a refund is processed before the split is initiated. It is a two step process.

<img alt="" />

**First Step: Customer completes the payment**

* Step 1: The customer visits the merchant website or the application and adds goods from different vendors to the shopping cart. The customer proceeds to complete the payment.
* Step 1.1: The merchant receives the payment request from the customer and creates an order. The order details contain information such as order ID, order amount, and customer name. The merchant creates an order in the Cashfree Payment system.
* Step 1.2: Cashfree Payment Gateway receives the order details and creates a payment link for that order. This payment link is sent to the merchant.
* Step 1.3: The merchant receives the payment link and sends it to the customer to complete the payment.
* Step 1.4: The customer clicks the link and completes the payment. The amount is received by Cashfree Payment Gateway.
* Step 1.5: The payment details are captured at Cashfree Payment Gateway end.
* Step 1.6: The payment details are stored in the Cashfree system and the payment status is sent to the merchant through payment webhooks.
* Step 1.7: The merchant sends the payment status to the customer.
* Step 1.8: The customer receives the payment status.

**Second Step: Cashfree Payment Gateway processes the refund**

* Step 2: The customer initiates a refund request through the merchant website or the application.
* Step 2.1: The merchant receives the refund request and triggers the [Create Refund API](/docs/api-reference/payments/latest/refunds/create-refund). The merchant provides refund details such as the refund amount, refund ID, refund type, split details, and triggers the API.
* Step 2.2: The refund is created successfully in the Cashfree system. Cashfree Payment Gateway processes the refund directly, based on the refund details, to the customer account.
* Step 2.3: In the case of a standard refund, the refund amount will be processed within 5-7 working days. If it is an instant refund, the refund amount is processed instantly to the customers account.

<Info>
  This situation arises only if the split is provided after successful payment
  of the order.
</Info>

## Scenario 2: Refund after split and before vendor settlement

The flow diagram below shows how a refund is processed once a split is created but the vendor settlement is not yet processed. It is a three step process.

<img alt="" />

**First Step: Customer completes the payment**

* Step 1: The customer visits the merchant website or the application and adds goods from different vendors to the shopping cart. The customer proceeds to complete the payment.
* Step 1.1: The merchant receives the payment request from the customer and creates an order. The order details contain information such as order ID, order amount, and customer name. The merchant creates an order in the Cashfree Payment system.
* Step 1.2: Cashfree Payment Gateway receives the order details and creates a payment link for that order. This payment link is sent to the merchant.
* Step 1.3: The merchant receives the payment link and sends it to the customer to complete the payment.
* Step 1.4: The customer clicks the link and completes the payment. The amount is received by Cashfree Payment Gateway.
* Step 1.5: The payment details are captured at Cashfree Payment Gateway end.
* Step 1.6: The payment details are stored in the Cashfree system and the payment status is sent to the merchant through payment webhooks.
* Step 1.7: The merchant sends the payment status to the customer.
* Step 1.8: The customer receives the payment status.

**Second Step: Merchant initiates the split**

Step 2: Once the payment is successful, the merchant triggers the [Split After Payment API](/docs/api-reference/payments/latest/easy-split/split-after-payment). The merchant provides split information such as vendor ID, split amount/percentage between the merchant and vendor, and the split type. Based on the split information provided, East Split performs the split operations.

Third Step: Customer requests refund from merchant

* Step 3: The customer initiates a refund request through the merchant website or the application.
* Step 3.1: The merchant receives the customer refund request and calls the Create Refund API including the split. The merchant provides refund details, refund amount, refund ID, refund type and triggers the API.
* Step 3.2: The refund is created successfully in Cashfree system. Easy Split deducts the merchant and vendor balances by their respective refund amounts.
* Step 3.3: Easy Split confirms the refund initiation to Cashfree Payment Gateway and begins processing the refund.
* Step 3.4: Cashfree Payment Gateway initiates the refund directly to the customer account. In case of a standard refund, the refund amount will be processed within 5-7 working days. If it is an instant refund, the refund amount is processed instantly to the customer account.
* Step 3.5: The refund is settled to the customer bank account successfully.

<Info>
  This situation is applicable when the split is shared during the order
  creation (or) after the split has been shared for split after payment.
</Info>

## Scenario 3: Refund after split and after vendor settlement

The flow diagram below shows how a refund is processed once a split is created and the vendor settlement is processed. It is a three step process.

<img alt="" />

**First Step: Customer completes the payment**

* Step 1: The customer visits the merchant website or the application and adds goods from different vendors to the shopping cart. The customer proceeds to complete the payment.
* Step 1.1: The merchant receives the payment request from the customer and creates an order. The order details contain information such as order ID, order amount, and customer name. The merchant creates an order in the Cashfree Payment system.
* Step 1.2: Cashfree Payment Gateway receives the order details and creates a payment link for that order. This payment link is sent to the merchant.
* Step 1.3: The merchant receives the payment link and sends it to the customer to complete the payment.
* Step 1.4: The customer clicks the link and completes the payment. The amount is received by Cashfree Payment Gateway.
* Step 1.5: The payment details are captured at Cashfree Payment Gateway end.
* Step 1.6: The payment details are stored in the Cashfree system and the payment status is sent to the merchant through payment webhooks.
* Step 1.7: The merchant sends the payment status to the customer.
* Step 1.8: The customer receives the payment status.

**Second Step: Customer requests refund from merchant**

* Step 2: The customer initiates a refund request through the merchant website or the application.
* Step 2.1: The merchant receives the refund request and triggers the [Create Refund API](/docs/api-reference/payments/latest/easy-split/split-after-payment). The merchant provides refund details, refund amount, refund ID, refund type and triggers the API.
* Step 2.2: Easy Split checks the merchant and the vendor balances to process the refund.
* Step 2.3: The respective balances are sent to Easy Split. Based on this, Easy Split checks if the refund can be processed or not.

**Third Step: Easy Split processes the refund to the customer account**

* Step 3: Before initiating the refund, Easy Split checks if the refund can be processed based on the merchant and vendor balance.
* Step 3.1: Refund is initiated if both merchant and vendor balances are more than the refund request. The refund amount will be adjusted from the respective future settlements. Cashfree Payment Gateway processes the refund based on the refund details directly to the customer account. The refund is put on hold if merchant or vendor balances are less than the refund request.
* Step 3.2: Cashfree Payment Gateway initiates the refund directly to the customer account. In case of a standard refund, the refund amount will be processed within 5-7 working days. If it is an instant refund, the refund amount is processed instantly to the customer account.


# Easy-Split Reports
Source: https://www.cashfree.com/docs/payments/split/reports/es-reports

Explore the Cashfree Easy-Split reports for vendor settlements, adjustments, refunds, and reconciliation that you can view from the Merchant Dashboard.

There are various reports that Cashfree provides. These reports help you to reconcile transactions, view adjustments and settlements, analyse your business transactions, and much more. You can view these reports day-wise, week-wise or for a custom date range.

You can select the required report type from the drop-down list, configure filters, and search for a particular report using the search option. You also have the option to download or delete the reports.

Cashfree offers a wide range of reports such as:

* [Transactions](/docs/payments/split/reports/transaction)
* [Reconciliation](/docs/payments/split/reports/recon)
* [Settlements](/docs/payments/split/reports/settlement)
* [Refunds](/docs/payments/split/reports/refunds)

Watch this video to learn more on reports

<iframe title="Easy Split by Cashfree | 2-step integration to split incoming payments" />


# Reconciliation
Source: https://www.cashfree.com/docs/payments/split/reports/recon

Use Cashfree Easy Split reconciliation reports to match marketplace orders to vendor settlements, commissions, refunds, and bank credits at line-item level.

The vendor reconciliation report lists all the transactions, adjustments, settlements and refunds that are associated with vendors. This will help you reconcile all transactions from your vendors with their respective settlement ID, time, and UTR.

## Vendor Reconciliation API

To fetch vendor-wise settlement or reconciliation details programmatically, use the Vendor Reconciliation API (`POST /pg/recon/vendor`). The API provides details including Vendor ID (`merchant_vendor_id`), settlement amount, status, settlement time, and settlement UTR. You can filter by Vendor ID and time period, by time period only (across vendors), or by Settlement ID.

After receiving a `VENDOR_SETTLEMENT_SUCCESS` webhook, wait approximately 15 minutes before calling this API to ensure the data is available. See the [Vendor Reconciliation API reference](/docs/api-reference/payments/latest/reconciliation/vendor-reconciliation-api) for full details.

To view the vendor settlement recon report,

1. Go to **Payment Gateway Dashboard** > **Reports**.
2. In the **Report Type** field, select **Vendor Recon** and click **Generate Report**.
3. Select the vendor recon report type, date range, file format, and provide the file name. Click **Generate Report**.

<img alt="Vendor Recon Report" />

<Info>
  If you have already generated the report, you will get a pop-up stating to
  download the report. You can download the report by clicking the ellipsis
  button.
</Info>

<img alt="" />

Sample report is available <a href="https://gocashassets.s3.ap-south-1.amazonaws.com/subscriptions/Sample+Report.zip">here</a>.

| Column name | Description | Example |
| :- | :- | :- |
| entity\_id | Unique ID of that particular event type. | 1046658935 |
| type | The type of that event. | transaction |
| merchantVendorId | The vendor ID that is added by the merchant | john213 |
| debit | The amount that was debited. | ArunTestES2 |
| credit | The amount that was credited. | 2.0 |
| amount | The total transaction amount. | 2.0 |
| currency | The currency used for that particular transaction. | INR |
| fee | PG service charges. | 1.00 |
| tax | PG service taxes. | 0.18 |
| settled | Indication of whether the vendor amount is settled or not. | true |
| txTime | The time of that particular transaction. | 2022-06-28 14:50:58 |
| settlementTime | The time at which Cashfree received a credit confirmation from the vendor's bank. | 2022-06-28 14:50:58 |
| addedOnTime | The time at which Cashfree initiated the settlement for that particular vendor. | 2022-06-28 14:50:58 |
| settlement\_eligibility\_time | The date timestamp that denotes when the transaction will be eligible for settlement. | 2022-06-28 14:50:58 |
| settlement\_id | Unique ID generated by cashfree for that particular settlement. | 1213178 |
| merchant\_order\_id | Unique ID passed to Cashfree by merchant when the order is created. | tutnvgetyfye123 |
| cf\_order\_id | A unique ID generated for each order. | 2359676476 |
| settlement\_utr | A unique transaction reference number. A number that is generated by your bank that will help in identifying credit in the merchant bank statement. | 218038200406 |
| refund\_arn | Acquirer Reference Number - Unique ID generated by Cashfree's partner bank for a particular refund. | 322077986405 |
| order\_note | A small description for that transaction. | payment\_link\_23840285 |
| payment\_mode | The payment mode used for the transaction. | UPI |
| customer\_name | The name of the customer. | john |
| customer\_email | The email ID of the customer. | [john@cashfree.com](mailto:john@cashfree.com) |
| customer\_phone | The phone number of the customer. | 7760381080 |


# Refunds
Source: https://www.cashfree.com/docs/payments/split/reports/refunds

Download Cashfree Easy Split refund reports to review refund status, vendor balance impact, and customer payouts across every marketplace order from one place.

The refunds report gives you details of all the refunds that are initiated in the selected time period. It captures all the refunds and split information of the vendors. It also includes details such as refund ID, order ID, transaction, refund amount, date, and more.

To view the refunds report,

1. Go to **Payment Gateway Dashboard** > **Reports**.
2. In the **Report Type** field, select **Refunds**, and click **Generate Report**.
3. Select the date range, file format, and file name. and click **Generate Report**.

<img alt="Refunds Report" />

The report will be generated based on the criteria you have filtered. You can download the report after it has been generated.


# Settlements
Source: https://www.cashfree.com/docs/payments/split/reports/settlement

Download Cashfree Easy Split settlement reports to track vendor payouts, commissions, and adjustments credited from orders during each settlement cycle.

The vendor split settlement report gives you details of order ID, reference ID, settlement amount, transaction time, transaction status, and UTR for the date range selected. You can download the report for a maximum period of 31 days.

To view the vendor split settlement report,

1. Go to **Payment Gateway Dashboard** > **Reports**.
2. In the **Report Type** field, select **Vendor Split Settlements**, and click **Generate Report**.
3. Select the date range, file format, and file name. and click **Generate Report**.

<img alt="Vendor Split Settlement Report" />

The report will be generated based on the criteria you have filtered. You can download the report after it has been generated.

<img alt="" />


# Transactions
Source: https://www.cashfree.com/docs/payments/split/reports/transaction

Download Cashfree Easy Split transaction reports to review orders, vendor splits, commissions, and payment status across your marketplace at line-item level.

The transaction report gives you details of all the transactions that were made in the period selected. Customer details, transaction amount, payment method, transaction status, settlement amount (if the settlement is complete), and more are available in this report. For transactions involving the sale of goods/services from two or more vendors, the vendor-wise payment split is also available in the transactions report.

To generate the transactions report,‌

1. Go to **Payment Gateway Dashboard** > **Reports**.
2. In the **Report Type** field, select **Transactions**, and click **Generate Report**.
3. Select the date range for which you want to view the report, file format, file type, and transaction status. You can add the merchant date and offer data if any in your report. Once done choosing the options, click **Generate Report**.

<img alt="Transaction Report" />

The report will be generated based on the criteria you have filtered. You can download the report after it has been generated.

<img alt="" />

## FAQs

<AccordionGroup>
  <Accordion title="What are the different transaction status in Cashfree?">
    When customers initiate a payment, there are various states that the transaction may go through before reaching your account. After the customer initiates a payment, the transaction can go to either of the following:

    * **SUCCESS**
    * **FAILURE**
    * **VOID**
    * **INCOMPLETE**
    * **PENDING**
    * **FLAGGED**
    * **CANCELLED**
    * **USER\_DROPPED**

    See the [payment lifecycle](/docs/payments/online/resources/payment-lifecycle) to know more about each of these states.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How do I track my transactions?">
    As soon as you log in to your Cashfree account, the Summary section in the payment gateway dashboard will give you instant context as to what is the amount of transaction that has happened on that particular day, and the settlement amount that you’re yet to receive. Besides this, Cashfree also provides a wide range of reports to analyse your business finances. The different reports that Cashfree provides you are,

    * Transactions Report
    * Settlement Reconciliation Report
    * Settlement Summary
    * Refunds Report
    * Ledger Report
    * Monthly Invoices

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I track the amount of daily transactions in Cashfree?">
    Yes. With Cashfree, you can receive specific reports such as **Transaction reports**, **Settlements**, and **Adjustment reports** directly into your own SFTP servers or Cashfree's SFTP servers at a set frequency every day.
    If you'd like Cashfree to push out the reports to your own SFTP servers, please fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can Cashfree send reports to my own SFTP servers?">
    Yes. With Cashfree, you can receive specific reports such as **Transaction reports**, **Settlements**, and **Adjustment reports** directly into your own SFTP servers or Cashfree's SFTP servers at a set frequency every day.
    If you'd like Cashfree to push out the reports to your own SFTP servers, please fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I add custom fields like roll number or institute code to a payment and see them in my reconciliation report?">
    Yes. Pass the fields you need as key-value pairs in the `order_tags` object when calling the [Create Order API](/docs/api-reference/payments/latest/orders/create). Up to three tags per order appear in the Settlement Recon Report under columns `Key_1`/`Value_1`, `Key_2`/`Value_2`, and `Key_3`/`Value_3` in the Transaction details section. Although you can pass up to 10 tags per order, only three are surfaced in the report. Use keys that match your reconciliation process—for example `institute_code`, `roll_number`, and `division` for education and multi-institute fees, or identifiers such as `branch_id`, `campaign_id`, or `invoice_ref` for other businesses. Include only the fields you need and keep your `order_tags` object to three keys.

    <iframe title="FAQs feedback component" />
  </Accordion>
</AccordionGroup>


# Split Scheme Configuration
Source: https://www.cashfree.com/docs/payments/split/settlements/configuration

Configure Cashfree Easy Split scheme rules to define how marketplace order amounts split across vendors, commissions, and platform fees on every transaction.

The split scheme configuration allows you to create a split scheme wherein you can define the split type and the vendor-wise split percentage. Once you have configured the split scheme, the splits occur as per this configuration.

To create a split scheme configuration,

1. Go to **Payment Gateway Dashboard** > **Settings** > **Split Scheme Configuration**. All the splits schemes you have created will be displayed on this page along with the other details such as:

* Date and Time the scheme was created
* The product for which the scheme is applicable
* The product ID
* The split type
* The static scheme ID
* The split scheme configuration details

2. Select **Create Split Configuration**.

<img alt="" />

3. Select the product for which you are creating the scheme from the drop-down menu. The available products are:

* Payment Gateway
* Subscription

<img alt="" />

Configure the split type - Dynamic or Static. If you are configuring a dynamic split, provide the split details through the split API. If you don't provide the split details, the entire amount will get settled into your account and not to the vendor.

| Product name | Split scheme setting details |
| :- | :- |
| Payment Gateway | Mention the split type and the vendor-wise split structure - Vendor ID and commission percentage. |
| Subscription | Mention the split type, product ID, and vendor-wise split structure - Vendor ID and commission percentage. |

If you are configuring a static split, mention the commission percentage. If the product is Payment Gateway or Subscription, you must provide the vendor ID and the percentage of commission that goes to the vendor.

<img alt="" />

4. Click **Create Split Scheme** once done configuring the split. You have now created a split scheme successfully. You can view the configuration details from the split scheme configuration homepage. You can do the following actions from this page:

5. View split scheme configuration details

6. Edit a configuration

<img alt="" />

## Editing a split scheme configuration

You can edit a created split scheme configuration from the homepage. Click the **Edit** icon on the configuration you want to edit. You can edit the split type and the commission percentage. You can also add new vendors or remove existing vendors from your scheme. Once done editing the split configuration, click **Save**.

<Info>
  Any changes done to the split scheme configuration will make the existing
  split scheme configuration inactive and the latest split scheme configuration
  will be used for future splits.
</Info>

<img alt="" />

<Tip>
  You can create a new split configuration using the [Create Split
  Configuration](/docs/api-reference/payments/latest/easy-split/create-static-split-configuration) API.
</Tip>


# Order Split Delay Post Successful Payment
Source: https://www.cashfree.com/docs/payments/split/settlements/delay/order-level

Configure order-level Cashfree Easy Split delays so the marketplace settles vendor splits only after a configurable hold period following successful payment.

You can defer overall order settlements to your vendors by increasing the order split delay. By default, we support a split delay of T+1\* days (after successful payments) within which you have to specify the split details along with the vendor ID to process split settlements to your vendors.

<Note>
  T+x\*: Settlement cycle is subject to bank approval and can vary based on
  transaction type, business category/model, risk parameters, and other factors.
</Note>

If you further want to increase the order split delay for your orders, Fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) or your account manager.

To set order level delay,

1. Go to **Settings**>**Easy Split**>**Feature Configuration**
2. Enable order split delay by using the toggle button. Set the delay days and click **Save Changes**.

<Info>
  By default, order level delay will be enabled and the default delay value is
  "01".
</Info>

<img alt="" />

Let us consider the following example:

**Schedule Details:**

| Schedule options | Value |
| :- | :- |
| Merchant schedule option | T+2\* |
| Vendor schedule option | Settlement ID: 6 (Instant Hourly Settlement on working days) |

**Scenario 1: Split invoked within split delay range**

| Scenario details | Value |
| :- | :- |
| Transaction details | Transaction date and time: December 1st, 10:10 AM |
| Order Amount | Rs. 1000 |
| The time when Spit API invoked | API invoked date and time: December 2nd, 2:20 PM |
| Split percentage | Merchant : Vendor :: 30% : 70%: |
| Settlement for the vendor with split | - Vendor settlement time: December 2nd, 3:00 PM - Vendor settlement amount: Rs. 700 |
| Settlement for merchant with split | - Merchant settlement time: December 3rd, 11:00 AM - Merchant settlement amount: Rs. 300 |

The customer pays an amount of Rs. 1000, on 1st December 2022 at 10:10 AM. You invoke the Split API on 2nd December at 2.20 PM. The Split information has details such as vendor ID, split amount or percentage, and split type.

When Split API is initiated, the split happens as per the split information (Merchant : Vendor :: 30% : 70%)

* The vendor amount of Rs. 700 is settled that day as the vendor schedule option ID is: 6 (Instant Hourly Settlement on working days).
* The merchant settlement amount of Rs. 300 is settled on December 3rd at 11:00 AM as the schedule option configured is T+2\*.

**Scenario 2: Split is not invoked within split delay range**

| Scenario details | Value |
| :- | :- |
| Transaction details | Transaction date and time: December 1st, 10:10 AM |
| Order Amount | Rs. 1000 |
| Settlement for merchant without split | - Settlement date and time: December 3rd, 11:00 AM - Settlement amount: Rs. 1000 |

The customer pays an amount of Rs. 1000, on 1st December 2022 at 10:10 AM. Since split is not invoked within the split delay range, you get the entire order amount (Rs. 1000) on 3rd December at 11:00 AM as the merchant schedule option is T+2\*.


# Delay Settlements
Source: https://www.cashfree.com/docs/payments/split/settlements/delay/overview

Use Cashfree Easy Split delay settlements to hold vendor payouts at the order or vendor level so marketplaces manage risk, returns, and reconciliation flows.

You can now delay the vendor settlements by adding delays at different levels. To delay settlements to vendors, you should enable deferred settlements in your account. The Split API has to be called within the schedule option interval, else the entire transaction amount will be credited to you.

You can add a delay at two levels:

* [Order Split Delay Post Successful Payment](/docs/payments/split/settlements/delay/order-level)
* [Defer Settlement](/docs/payments/split/settlements/delay/vendor-level)

## Use cases

### Case 1: E-commerce: multiple sellers in a single order payment

<img alt="" />

### Case 2: Online appointment booking (Doctor/Consultant)

<img alt="" />

Watch this video to learn how to delay settlements to your vendors using our API

<iframe title="YouTube video player" />


# Defer Settlement
Source: https://www.cashfree.com/docs/payments/split/settlements/delay/vendor-level

Defer Cashfree Easy Split vendor settlements by configuring a per-vendor delay in days from the dashboard Settings page to better manage marketplace cash flow.

You can delay the vendor settlements by enabling the **Defer Settlement** from the **Settings** page. To enable defer settlement, click the toggle button, set the **Defer by Days** value, and click **Save**.

The Defer by Days value determines the number of the days by which the settlement will be delayed to vendors. For example, if you set the Defer by Days value to 5, the settlements to the vendors will be delayed by 5 days from the date of transaction.

<img alt="" />

**Scenario 1: You trigger the Vendor Settlement Eligibility Date for Orders API before deferred delay eligibility.**

**Configuration**:

* Defer by Days value: 15 days
* Transaction Date: 2nd December at 4:00 PM

Since the deferred delay value set by you is 15 days, the vendor settlement eligibility is: 17th December 4:00 PM.

Let us assume:

* Supplier 1 delivers goods/services to customer on 5th December.
* Supplier 2 delivers goods/services to customer on 6th December.

You can facilitate customized vendor settlements at different time for the same order ID. As supplier 1 has delivered goods on 5th December, you can trigger the **[Set\_Vendor\_Settlement\_Eligibility\_Date\_for\_Orders](/docs/api-reference/payments/latest/easy-split/get-split-and-settlement-details-by-orderid)** API.

Provide the following in the API:

* order ID
* vendor ID
* change the settlementEligibilityDate value to a newer value

<Note>
  T+x\*: Settlement cycle is subject to bank approval and can vary based on
  transaction type, business category/model, risk parameters, and other factors.
</Note>

The settlement will happen to supplier 1 based on the updated settlementEligibilityDate.

| Scenario 1 configurations (supplier 1) | Values |
| :- | :- |
| Deferred delay value | 15 days |
| Supplier 1 schedule option | Settlement ID: 1 (T+1\* settlement at 11:00 AM) |
| Supplier 1 original settlement date | 18th December at 11:00 AM (Since the deferred delay was set to 15 days and T+1\* settlement) |
| Supplier 1 service delivery time | 2022-12-06 9 PM |
| settlementEligibilityDate updated by you | 2022-12-06 09:00:00 |
| Supplier 1 new settlement date | 7th December at 11:00 AM since supplier 1 is in T+1 settlement of 11:00 AM). |

**Sample Request**

<Tabs>
  <Tab title="Production">
    <CodeBlock>
      ```bash theme={"dark"}
      curl --location --request PUT 'https://api.cashfree.com/api/v2/easy-split/orders/{{orderid}}/settlement-eligibility/vendors/{{vendorid}}
      ' \
      --header 'X-Client-Id: {{clientId}}' \
      --header 'X-Client-Secret: {{secretKey}}' \
      --header 'Content-Type: application/json' \
      {
          "settlementEligibilityDateUpdate": "2026-06-06 21:00:00"
      }
      ```
    </CodeBlock>
  </Tab>

  <Tab title="Sandbox">
    <CodeBlock>
      ```bash theme={"dark"}
      curl --location --request PUT 'https://test.cashfree.com/api/v2/easy-split/orders/{{orderid}}/settlement-eligibility/vendors/{{vendorid}}
      ' \
      --header 'X-Client-Id: {{clientId}}' \
      --header 'X-Client-Secret: {{secretKey}}' \
      --header 'Content-Type: application/json' \
      {
          "settlementEligibilityDateUpdate": "2026-06-06 21:00:00"
      }
      ```
    </CodeBlock>
  </Tab>
</Tabs>

**Sample Response**

```json theme={"dark"}
{
	"status": "OK",
	"subCode": "200",
	"message": "Updated vendor settlement eligibility date."
}
```

In the same way, you can settle supplier 2 before the deferred delay. Let us assume the similar configurations:

| Scenario 1 configurations (supplier 2) | Values |
| :- | :- |
| Deferred delay value | 15 days |
| Supplier 2 schedule option | T+1\* settlement at 11:00 AM |
| Supplier 2 original settlement date | 18th December at 11:00 AM (Since deferred delay set to 15 days and T+2\* settlement) |
| Supplier 2 service delivery time | 12th December 8PM |
| settlementEligibilityDate updated by you | 2022-12-12 09:00:00 |
| Supplier 2 new settlement date | 12th December at 11:00AM since supplier 2 is at T+1\* settlement at 11:00 AM) |

**Sample Request**

```bash theme={"dark"}
curl --location --request PUT 'https://api.cashfree.com/api/v2/easy-split/orders/{{orderid}}/settlement-eligibility/vendors/{{vendorid}}
' \
--header 'X-Client-Id: {{clientId}}' \
--header 'X-Client-Secret: {{secretKey}}' \
--header 'Content-Type: application/json' \
{
    "settlementEligibilityDateUpdate": "2022-12-07 09:00:00"
}
```

**Sample Response**

```json theme={"dark"}
{
	"status": "OK",
	"subCode": "200",
	"message": "Updated vendor settlement eligibility date."
}
```

**Scenario 2: You trigger the Set Vendor Settlement Eligibility Date for Orders API after the deferred delay eligibility**

**Configuration**:

* Defer by Days value: 15 days
* Transaction Date: 2nd December at 4:00 PM

As you have set the deferred delay value to 15 days, you can update the settlementEligibilityDate only within this time period (2nd December - 17th December 4:00PM). If you trigger the API post that, you will get an error stating: "Settlement eligibility cannot be beyond max\_eligibity\_date. Provide an earlier date". The settlements will happen as per the deferred delay only.

**Sample Request**

```bash theme={"dark"}
curl --location --request PUT 'https://api.cashfree.com/api/v2/easy-split/orders/{{orderid}}/settlement-eligibility/vendors/{{vendorid}}
' \
--header 'X-Client-Id: {{clientId}}' \
--header 'X-Client-Secret: {{secretKey}}' \
--header 'Content-Type: application/json' \
{
    "settlementEligibilityDateUpdate": "2022-21-09 09:00:00"
}
```

**Sample Response**

```json theme={"dark"}
{
    "status": "ERROR",
    "subCode": "400",
    "message": "Settlement eligibility cannot be beyond max_eligibity_date. Provide an earlier date.
}
```


# Failed Settlement Reasons
Source: https://www.cashfree.com/docs/payments/split/settlements/failure-reasons

Review common Cashfree Easy Split settlement failure reasons such as KYC issues, beneficiary mismatches, and bank rejections, plus steps to resolve each error.

| Reason | Category | Description |
| :- | :- | :- |
| BANK\_GATEWAY\_ERROR | Bank | Technical error at the bank |
| BENE\_BANK\_DECLINED | Bank | Rejected by Beneficiary bank due to business reasons |
| FAILED | Bank | No explicit failure reason from the bank |
| INVALID\_IFSC\_FAIL | Customer | Invalid ifsc code provided for bank account |
| INVALID\_ACCOUNT\_FAIL | Customer | Bank account is invalid |
| RETURNED\_FROM\_BENEFICIARY | Bank | Immediate reversal from the beneficiary bank |
| INSUFFICIENT\_BALANCE | Vendor | Merchant balance is exhausted, need to add funds |
| IMPS\_MODE\_FAIL | Bank | IMPS mode not supported for the beneficiary |
| RTGS\_MODE\_FAIL | Bank | RTGS mode not supported (only for RTGS) |
| REINITIALIZE\_TRANSFER\_LATER | Bank | Technical error at the bank, retry later |
| NRE\_ACCOUNT\_FAIL | Customer | Customer bank account is an NRE account |
| ACCOUNT\_BLOCKED | Customer | Customer bank account is blocked |
| DEST\_LIMIT\_REACHED | Bank | Transfer limit to beneficiary exceeded |
| INVALID\_MODE\_FAIL | Bank | Transfer mode not valid for beneficiary |
| NPCI\_UNAVAILABLE | Bank | NPCI is unavailable |
| BENEFICIARY\_BANK\_OFFLINE | Bank | Beneficiary bank is offline |
| INVALID\_AMOUNT\_FAIL | Vendor | Amount is invalid for the given transfer mode |
| SUSPECTED\_TRANSFER | Customer | Suspicious transfer identified |
| BENE\_NAME\_DIFFERS | Customer | Beneficiary name not matching with bank records |
| DISABLED\_MODE | Vendor | Transfer mode not enabled for the account |
| AMAZON\_AMOUNT\_EXCEED | Vendor | Amount should be less than 10000 for Amazon Pay mode |
| BENEFICIARY\_BLACKLISTED | Vendor | Beneficiary is blacklisted |
| PAYOUT\_INACTIVE | Vendor | Payout account is not active |
| INVALID\_TRANSFER\_AMOUNT | Vendor | Transfer amount is invalid |
| BENEFICIARY\_NOT\_EXIST | Vendor | Beneficiary does not exist |
| BENEFICIARY\_INVALID\_MODE | Vendor | Mode Not valid for Beneficiary |
| INVALID\_BENE\_ACCOUNT\_OR\_IFSC | Vendor | Invalid bank account number or ifsc provided |
| BENEFICIARY\_NAME\_DIFFERS | Customer | Beneficiary name not matching with bank records |
| ANY\_OTHER\_REASON | Bank | No reason provided for the failure/reversal |
| INVALID\_OR\_NO\_SUCH\_ACCOUNT\_TYPE | Customer | Invalid account |

***

# Signature Verification

Use the signature to verify that the request has not been tampered with. To verify the signature, you need your Cashfree PG secret key and the payload.

Timestamp is present in the header: x-webhook-timestamp

<pre><code>timestamp := 1617695238078;\
signedPayload := $timestamp.$payload;
expectedSignature := Base64Encode(HMACSHA256($signedPayload, $merchantSecretKey));</code></pre>


# Vendor Instant Settlements
Source: https://www.cashfree.com/docs/payments/split/settlements/instant

Enable Cashfree Easy Split vendor instant settlements so marketplace vendors receive their share in their bank accounts within minutes of order success.

You can set the vendor schedule option while [creating a vendor](/docs/api-reference/payments/latest/easy-split/create-vendor). The **settlementCycleId** value defines the vendor schedule option.

The instant schedule options are as follows:

**Instant Settlement 24 \*7**

| Settlement ID | Description |
| :- | :- |
| 8 | Instant settlement every hour 24\*7. |
| 9 | Instant settlement every 3 hours 24\*7. |
| 14 | Instant settlement every 15 minutes 24\*7. |

<Info>
  Prerequisites to enable 24\*7 cycle:

  * Merchant should be enabled on merchant IS - risk and finance check will be performed at merchant level.
  * IS limit should be configured for the merchant.
  * Markup rate for non-banking hour settlement should be set for the merchant.
  * Instant settlement limit is defined at merchant level, Instant settlement limit = Merchant IS + Vendor IS
  * When the IS daily limit is breached, the settlement for the merchants (both merchant IS and vendor IS) will be limited till new limit is refreshed the following day.
</Info>

**Vendor instant settlement within banking hours**

| Schedule  ID | Description |
| :- | :- |
| 3 | All transactions from 4:30 PM T-1 to 10:30 AM T+0 settled at 11 AM T+0, and 10:30 AM T+0 to 4:30 PM T+0 at 5:00 PM T+0. |
| 6 | Instant settlement every hour between 7:00 AM and 5:00 PM on working days. |
| 7 | Instant settlement every 3 hours between 8:00 AM and 5:00 PM on working days. |

<Tip>
  T+x\*: Settlement cycle is subject to bank approval and can vary based on transaction type, business category/model, risk parameters, and other factors.
</Tip>


# Vendor On-Demand Settlements
Source: https://www.cashfree.com/docs/payments/split/settlements/on-demand

Configure Cashfree Easy Split vendor on-demand settlements so vendors request payouts whenever they need them and instantly transfer their available balance.

You can settle the balance to a vendor on-demand from the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) or through the [On-Demand Transfer API](/docs/api-reference/payments/latest/easy-split/create-on-demand-transfer). The on-demand settlements are processed through **RTGS**/**IMPS** rails. Cashfree levies a small fee : **On Demand Service Charge** to process these settlements.

There are two types of On-demand settlements in Easy Split,

* On-demand settlement based on interval
* On-demand settlement based on the amount

## Initiate on-demand settlement based on interval

1. Go to **Payment Gateway Dashboard** > **Easy Split** > **Vendors** > **Settle Now**.

<img alt="" />

2. Mention the Start Date and Time, End Date and Time and click **Search**.

<img alt="" />

3. The related On-Demand settlement will be shown. Verify the vendor ID, the settlement amount, and the settlement time. Once done, click **Settle Now**.

<img alt="" />

4. You will now get a message that your On-demand settlement has been initiated successfully.

<img alt="" />

<Info>
  You can settle vendor balances on-demand only if: The vendor balance is
  greater than or equals Rs. 1000. - Transactions are processed at least 15
  minutes before initiating on-demand settlements through
  [API](/docs/api-reference/payments/latest/easy-split/create-on-demand-transfer). - Transactions are processed at least 1 hour
  before initiating on-demand settlements through the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
</Info>

## Initiate on-demand settlement based on amount

1. Go to **Payment Gateway Dashboard** > **Easy Split** > **Settlements** > **On-Demand** > **Settle to Vendor**.

<img alt="" />

2. In the "Create On Demand Settlement to Vendor" pop-up, enter the **vendor ID** to which you must settle. Choose the Debit Account, you can either choose to debit from your unsettled balance or debit from your vendor's unsettled balance.
3. Enter the withdrawal amount, add tags if needed and click **Transfer Balance**.

<img alt="" />

4. Once done, you will receive a message stating the On-Demand Settlement was initiated successfully.

<img alt="" />

You can view all your On-Demand Settlements from the On-Demand Settlements home page.

<img alt="" />


# Vendor Standard Settlements
Source: https://www.cashfree.com/docs/payments/split/settlements/standard

Use Cashfree Easy Split vendor standard settlements to credit marketplace vendors based on a fixed schedule, with clear reports for each settlement cycle.

The standard schedule option in Cashfree is T+2 days, where T is the date of the transaction. For instance, if the transaction takes place on a Monday, the settlement is credited to the vendor account on Wednesday. The standard settlements happen only on bank working days.

You can set the vendor schedule option while [creating a vendor](/docs/api-reference/payments/latest/easy-split/create-vendor). The **settlementCycleId** value defines the vendor schedule option.

The standard schedule options are as follows:

| Schedule ID | Description |
| :- | :- |
| 1 | T+1\* settlement at 11:00 AM. |
| 2 | T+2\* settlement at 11:00 AM. |
| 4 | All transactions from 2:00 PM T-1 to 2:00 PM T+0 settled at 3 PM T+0. |
| 5 | All transactions till 5.30 at 6. |
| 11 | Weekly Every 1st working day. If you intend to settle your vendor account on a weekly basis opt for this cycle. |
| 12 | Monthly Every 1st working day. If you intend to settle your vendor account on a monthly basis opt for this cycle. |
| 13 | T+1\* settlement at 09:00 AM. |

<Tip>
  T+x\*: Settlement cycle is subject to bank approval and can vary based on
  transaction type, business category/model, risk parameters, and other factors.
</Tip>

To view vendor standard settlement,

1. Go to **Payment Gateway Dashboard** > **Easy Split** > **Settlements** > **Scheduled**

<img alt="" />


# Use Cases
Source: https://www.cashfree.com/docs/payments/split/use-cases

See real Cashfree Easy Split use cases across marketplaces, edtech, travel, and SaaS, with patterns for commissions, vendor payouts, and refund splits.

## Marketplace aggregators

Online businesses that sell multiple products through different vendors can now use Easy Split to manage the splitting of incoming customer payments with ease. Also, easily manage schedule options, deduct commission, and view real-time reports for these vendor payments using our Easy Split product dashboard.

<img alt="" />

**Standard Marketplace Setup**

* Add and update vendor details: Add and update vendor details via product dashboard or API.
* Prepaid charge configuration: Reduces effort from the merchant finance team in reconciling the service charges to settle fee invoices.
* Split after payment: Allows order split default delay 2 days (can be extended further if required).
* Manage refunds: Allows refund both before and after the split.
* Transfer balances: Allows credit/debit vendor account.
* Deferred settlement: Allows deferred settlement time configuration basis service time for each vendor. It should be used only when there is a different settlement time for the same order.

## EdTech and other platform businesses

Online EdTech platforms that offer courses with different professors/instructors (Vendors) can use Easy Split to collect payments from students and split the amount with the instructors after deducting their charges.

<img alt="" />

**Standard Platform Business Setup**

* Add and update vendor details: Add and update vendor details via product dashboard or API.
* Split after payment: Allows order split default delay of 30 days (can be extended further if required).
* Prepaid charge configuration: Reduces effort from the merchant finance team.
* Manage refunds: Allows refund both before and after the split.
* Transfer balances: Allows credit/debit vendor account.

## Franchise and multi-branch outlets

Businesses that centrally manage payment collections for all their branches, like an online beauty product store or a pizza delivery store, can now make use of Easy Split to collect payment via website from all customers and route the incoming payments to their individual stores.

<img alt="" />

**Standard Centrally Operated Business Setup**

* Add and update vendor details: Add and update vendor details via product dashboard or API.
* Split after payment: Allows order split default delay 2 days (can be extended further if required).
* Prepaid charge configuration: Reduces effort from the merchant finance team.
* Manage refunds: Allows refund both before and after the split.
* Transfer balances: Allows credit/debit vendor account.

## Investment or insurance marketplace

Marketplaces where 100% order amount is settled to AMC or Insurer's account. The settlement will be customised and completed on the same day, with additional AMC and NBFC level reconciliation. Easy split also facilitates instant and on-demand settlements

<img alt="" />

**Standard Investment and Insurance Marketplace Setup**

* Add and update vendor details: Add and update vendor details via product dashboard or API.
* Prepaid charge configuration: Reduces effort from the merchant finance team
* Manage refunds: Allows refund both before and after split

## Educational institutes

Institutes managing multiple accounts for administration can use Easy Split to facilitate splitting student payments directly to all their business accounts by providing split. This will reduce reconciliation efforts to settle individual accounts like tutors, admin, hostel, stationery and mess accounts

<img alt="EdInstitution.gif" />

**Standard Educational Institutes Setup**

* Add and update vendor details: Add and update vendor details via product dashboard or API.
* Split after payment: Allow order split default delay 2 days (can be extended further if required)
* Prepaid charge configuration: Reduces effort from the merchant finance team
* Manage refunds: Allows refund both before and after split
* Transfer balances: Allows credit/debit vendor account

## On-demand services

Services like cab booking, flight booking, food delivery etc. can now take bookings and automate the splitting of incoming customer payments to the respective service providers with the help of Easy Split.


# Add Vendor
Source: https://www.cashfree.com/docs/payments/split/vendor/add

Add Easy Split vendors to Cashfree using the Merchant Dashboard or APIs, including single and bulk uploads, KYC document submission, and vendor approval flows.

Before you add a vendor, review the required documents that are applicable to different vendor types and business categories. They are mentioned in the tables below.

To add a new vendor, follow the Dashboard or API instructions below.

<Tabs>
  <Tab title="Dashboard">
    Use the Merchant Dashboard to add a single vendor via the Easy Split interface.

    To add a new vendor:

    1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).

    2. Go to **Payment Gateway > Easy Split - Vendor > Add Vendor**.

    3. Enter the following details and select **Next**:
       * **Vendor ID**: ID of the vendor.
       * **Phone number**
       * **Email ID**
       * **Vendor line of business**: For available options, see [Vendor LOB](#list-of-vendor-line-of-business-lob).
       * **Vendor business type**: Choose Individual or Business Entity.
       * **Settlement cycle**: Select a schedule option. For available options, see [Available schedule options](#available-schedule-options).

    4. Add vendor bank account details (account holder name, account number, and IFSC) or UPI VPA.

    <Info>
      You can provide either the vendor bank account details or a UPI VPA. Do not provide both.
    </Info>

    5. Enable Dashboard Access to allow the vendor to access the Vendor Dashboard. For more information, see [Vendor Dashboard overview](/docs/payments/split/vendor/dashboard/overview). This step is optional.

    6. Select **Verify Account Details** to validate the beneficiary bank account or UPI VPA.

    <Info>
      Verifying bank accounts and UPI VPA is chargeable. Make sure you have sufficient balance before proceeding, or continue without verification.
    </Info>

    7. Provide KYC documents according to vendor type (Individual or Business Entity). For required documents and limits, see the [KYC document requirement](#kyc-document-requirement) section.

    8. Select **Add Vendor Details** to complete onboarding. The new vendor appears in **Easy Split - Vendor**.

    ## Add multiple vendors (batch upload)

    Prepare a batch file using the sample CSV template. Ensure all required columns are present and formatted correctly.

    To add multiple vendors:

    1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
    2. Go to **Payment Gateway > Easy Split - Vendor**.
    3. Select **Upload File** and choose the prepared batch file.
    4. Select **Upload** to start processing. The system validates the file and processes valid rows.
    5. After processing completes, download the error log (if any) and fix rows that failed validation.
    6. Reupload the corrected file to add the remaining vendors.

    <Info>
      * File size limit: 8 MB. Maximum records per upload: 50.
      * The upload fails if the file does not match the required format. Always download and review the error log, fix issues, and reupload only the failed rows.
    </Info>

    Watch this video to learn how to add vendors via the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).

    <iframe title="YouTube video player" />
  </Tab>

  <Tab title="API">
    Use the Vendor APIs to create, update, and manage vendors programmatically. Before you use the Vendor APIs, ensure you have API keys generated from the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and the required permissions.

    The following table lists common vendor API endpoints and their functions.

    | API endpoint | Method | Description |
    | - | - | - |
    | `/easy-split/vendors` | POST | Create a new vendor. For more information, see [Create Vendor API](/docs/api-reference/payments/latest/easy-split/create-vendor). |
    | `/easy-split/vendors/{vendor_id}` | GET | Retrieve vendor details by vendor ID. For more information, see [Get Vendor API](/docs/api-reference/payments/latest/easy-split/get-vendor-all-details). |
    | `/easy-split/vendors/{vendor_id}` | PATCH | Update vendor fields (for example, settlement cycle or contact). For more information, see [Update Vendor API](/docs/api-reference/payments/latest/easy-split/update-vendor-details). |
    | `/easy-split/vendor-docs/{vendor_id}` | POST | Upload KYC or supporting documents for the vendor. For more information, see [Upload Vendor Docs](/docs/api-reference/payments/latest/easy-split/upload-vendor-docs). |
    | `/easy-split/vendor-docs/{vendor_id}` | GET | Check the upload and verification status of vendor documents. For more information, see [Get Vendor Docs](/docs/api-reference/payments/latest/easy-split/get-vendor-all-documents-status). |

    For full API request and response schemas, refer to the linked API reference pages.
  </Tab>
</Tabs>

## Available schedule options

Use schedule option 8, 9, 14, or 17 to schedule instant settlements to your vendor account.

<Accordion title="Schedule options">
  | ID | Description |
  | :- | :- |
  | 1 | T+1\* settlement at 11:00 AM. |
  | 2 | T+2\* settlement at 11:00 AM. |
  | 3 | All transactions from 4:45 PM T-1 to 10:45 AM T+0\* settled at 11:15 AM T+0\*, and, 10:45 AM T+0\* to 4:45 PM T+0\* at 5:15 PM T+0\*. |
  | 4 | All transactions from 2:00 PM T-1 to 2:00 PM T+0 settled at 3:00 PM T+0\*. |
  | 5 | All transactions till 5:30 PM at 6:00 PM. |
  | 6 | Instant settlement every hour between 7:00 AM and 5:00 PM on working days. |
  | 7 | Instant settlement every 3 hours between 8:00 AM and 5:00 PM on working days. |
  | 8 | Instant settlement every hour 24\*7. |
  | 9 | Instant settlement every 3 hours 24\*7. |
  | 11 | Weekly every 1st working day. |
  | 12 | Monthly every 1st working day. |
  | 13 | T+1\* settlement at 09:00 AM. |
  | 14 | Instant settlement every 15 minutes 24\*7. |
  | 15 | T+3\* settlement at 11:00 AM. |
  | 16 | T+7\* settlement at 11:00 AM. |
  | 17 | Instant settlement every minute 24\*7. |

  T+x\*: Settlement cycle is subject to bank approval and can vary based on transaction type, business category/model, risk parameters, and other factors.
</Accordion>

## Vendor status workflow

When you onboard a vendor from the dashboard or use the APIs, the vendor goes through various states. The following table describes the vendor statuses during the onboarding process.

| Vendor status | Description |
| - | - |
| IN\_BANK\_VALIDATION | The bank account validation process has been initiated. |
| BANK\_VALIDATION\_FAILED | The bank validation has failed. This typically occurs when the bank account holder's name does not match the name provided during vendor onboarding. Update the bank account details to the correct ones. |
| IN\_BENE\_CREATION | The vendor creation process has been initiated. |
| BENE\_CREATION\_FAILED | The beneficiary creation at the partner bank has failed. Update the bank account details to retry beneficiary creation. |
| IN\_KYC\_REVIEW | The vendor is created and not all mandatory KYC documents are successfully verified. Ensure all mandatory documents are submitted. |
| ACTION\_REQUIRED | One or more KYC documents have failed verification. The merchant must submit correct, updated, or relevant KYC documents to continue with vendor onboarding. |
| ACTIVE | The vendor KYC documents are verified successfully and the vendor is active. |
| ON\_HOLD | The Cashfree onboarding team has placed the account on hold because the documents are unavailable or insufficient. |
| BLOCKED | The vendor is blocked. |
| DELETED | The vendor is deleted. |

The image below shows the vendor onboarding flow.

<img alt="" />

## Document status workflow

The following table describes the states a document goes through during the verification process.

| Document status | Description |
| :- | :- |
| Due Currently | Documents in this state are pending mandatory documents that must be submitted to onboard a vendor. |
| Due Eventually | These are additional documents that must be submitted based on different limits. If a vendor is going to breach certain limits in the future, submit these documents along with the documents in the **Due Currently** category. This ensures that the vendor state is not affected by limit breaches. **Example**: GST is mandatory if the sum of vendor settlements to a single PAN or merchant across vendors exceeds 20 lakhs in the last twelve months. |
| In Review | The KYC documents are submitted and under review. Once verification is complete, the document status changes to **Verified** or **Action Required**. |
| Verified | The KYC document submitted is verified successfully. |
| Action Required | The KYC document verification has failed. Upload a correct or fresh document to continue. |

The image below shows the document status workflow.

<img alt="" />

## KYC document requirement

The following table lists the required documents based on applicable limits. Requirements vary by merchant type and vendor type.

| Document requirement | Limit | Alternatives |
| :- | :- | :- |
| PAN | Required for all limits | GSTIN |
| GSTIN | > 20 Lakhs | NA |

## List of vendor line of business (LOB)

The following list contains all supported vendor lines of business (LOB).

<Accordion title="Vendor LOB">
  | Vendor LOB |
  | :- |
  | B2B |
  | Digital Goods |
  | E-commerce |
  | Education |
  | Financial Services |
  | Food and Beverages |
  | Gaming |
  | Government |
  | Grocery |
  | Health care |
  | Insurance |
  | Jewellery |
  | NBFCs/Organisations into Lending |
  | Logistics |
  | Miscellaneous |
  | Mutual funds/Broking |
  | Non Profit/NGO |
  | Online Gaming |
  | Open and Semi Open Wallet |
  | Pan shop |
  | Pharmacy |
  | Readymade |
  | Real Estate, Housing, Rentals |
  | Retail and Shopping |
  | SaaS |
  | Social Media and Entertainment |
  | Society/Trust/Club/Association |
  | Telecom |
  | Travel and Hospitality |
  | Utilities |
  | Chit Funds |
  | Web host/Domain seller |
  | Professional Services (Doctors, Lawyers, Architects, CAs, and other Professionals) |
</Accordion>

## Vendor LOB specific documents

<Accordion title="NBFC">
  If the vendor type is NBFC, the following additional documents are required:

  * CIN
  * NBFC and LSP Agreement
  * NBFC Certificate
  * NBFC domain confirmation email on Cashfree partnership
</Accordion>


# Adjust Vendor Balance
Source: https://www.cashfree.com/docs/payments/split/vendor/balance/adjust

Adjust Cashfree Easy Split vendor balances from the dashboard or API to record corrections, manual debits, or credits without touching settled orders.

You can make credit and debit adjustments to the vendor account using the **Adjust Balance** feature in the product dashboard. You can also do the same using the [Transfer Vendor Balance](/docs/api-reference/payments/latest/easy-split/create-on-demand-transfer) API.

You can adjust balances in scenarios when,

* Refunds are not processed due to insufficient balance in the vendor's account, you can credit the vendor account to process the refund and later adjust the balance.
* The total amount is credited to your account, and you can later make credit adjustments to the vendor account.
* To manage differences in the vendor split percentages.
* If you want to discontinue business with a vendor you can make credit or debit adjustments to the vendor account before you delete the account.

To adjust vendor balance,

1. Go to **Payment Gateway Dashboard** > **Easy Split** > **Adjustments**. Click the **Adjust Balance** option.

2. From the Initiate Adjustments pop-up window, enter the **Vendor ID** you want to make adjustments to.

3. Select the **Adjustment Type** - **Debit** or **Credit**. Select **Debit** if you have to make a debit adjustment, and select credit if you have to make a credit adjustment to the vendor.

4. Enter the **Transfer Amount**, and provide **Remarks** if any. Once done, click **Ok** to initiate the adjustment.

<img alt="" />

<Tip>
  The transfer amount should be less than equal to the unsettled balance.
</Tip>


# Get On Demand Vendor Balance
Source: https://www.cashfree.com/docs/payments/split/vendor/balance/get

Get on-demand vendor balances in Cashfree Easy Split through the API to display real-time payout availability inside vendor dashboards and internal tooling.

For Auto Collect pass the Authorization token. Use the [Authorize API](/docs/api-reference/payouts/v1/authorize) to generate the token for Auto Collect APIs.

<Accordion title="Response Codes">
  | Sub code | Status | Message | Solution |
  | :- | :- | :- | :- |
  | 400 | ERROR | Vendor Not found | Provide a valid vendor ID. |
  | 400 | ERROR | Start time is beyond end time | Ensure start time is before end time. |
  | 400 | ERROR | End is a date time field and should be of format yyyy-MM-ddTHH:mm:ss | Provide a valid date time field format. |
</Accordion>


# Settle On Demand Vendor Balance
Source: https://www.cashfree.com/docs/payments/split/vendor/balance/settle

Trigger on-demand Cashfree Easy Split vendor settlements via API so marketplace vendors can pull their available balance to their bank when required.

For Auto Collect pass the Authorization token. Use the [Authorize API](/docs/api-reference/payouts/v1/authorize) to generate the token for Auto Collect APIs.

<Note>
  If you don't provide the start and end time, all the existing vendor balance till now will be settled to vendor.
</Note>

<Accordion title="Response codes">
  | Sub code | Status | Message | Solution |
  | :- | :- | :- | :- |
  | 400 | ERROR | Buffer time insufficient, please choose an earlier end time | Select an end time earlier than 5 minutes from the current time. |
  | 400 | ERROR | Vendor balance should be greater than or equal to 1000 | Make sure the vendor balance is greater than or equal to 1000. |
  | 400 | ERROR | Start time is beyond end time | Make sure start time is before the end time. |
  | 400 | ERROR | Merchant not enabled for on demand vendor settlement | Please contact your Account Manager to enable the merchant for On Demand Vendor Settlement. |
  | 400 | ERROR | Start is a date time field and should be of format yyyy-MM-ddTHH:mm:ss | Provide a valid start time. |
  | 400 | ERROR | End is a date time field and should be of format yyyy-MM-ddTHH:mm:ss | Provide a valid end time. |
</Accordion>


# Vendor Dashboard
Source: https://www.cashfree.com/docs/payments/split/vendor/dashboard/overview

Give vendors a dedicated Cashfree Vendor Dashboard to view their transactions, settlements, and reports once you grant them invitation-based portal access.

The **Vendor Dashboard** is a dedicated dashboard for vendors to view their transactions, settlements, and reports. Vendors receive an invitation and can access the dashboard only after you grant them access.

<Frame>
  <img alt="" />
</Frame>

## Accessing the vendor dashboard

Below are the steps to access the vendor dashboard for the first time:

1. Activate the vendor dashboard feature by requesting your account manager.
2. Grant access to the required vendor through the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) or APIs.
3. An automated email is sent to the vendor’s registered email ID.
4. The vendor can reset their password and log in using the new credentials.

## Summary

Once the vendor logs in to the vendor dashboard, they can view the **Summary** tab. This tab displays:

* Recent settlements
* Upcoming settlements
* Total transactions
* Total refunds

<Frame>
  <img alt="" />
</Frame>

Select a date range from the drop-down menu. If you select **Custom Date Range**, specify the date range and click **Apply**. The transactions and refunds will be displayed based on the selected period.

### Total transactions

The **Total Transactions** section displays:

* The transaction count.
* The total transaction amount for the selected period.

Hover over the dates to view individual transaction amounts. Clicking the **arrow icon** redirects vendors to the **Transactions** page.

### Total refunds

The **Total Refunds** section displays:

* The refund count.
* The total refund amount for the selected period.

Hover over the dates to view individual refund amounts. Clicking the **arrow icon** redirects vendors to the **Refunds** page.

## Profile

The **Profile** section displays vendor details. To access it, navigate to **Vendor Dashboard** > **Profile**. The **Profile** section is divided into three categories:

* [Personal Details](/docs/payments/split/vendor/dashboard/overview#personal-details)
* [Account Details](/docs/payments/split/vendor/dashboard/overview#account-details)
* [Merchant Details](/docs/payments/split/vendor/dashboard/overview#merchant-details)

<Frame>
  <img alt="" />
</Frame>

### Personal details

The **Personal Details** section includes:

* Merchant vendor ID: Unique vendor ID.
* Name: Vendor’s full name.
* Email address: Vendor’s registered email.
* Phone number: Vendor’s contact number.
* Onboarded date: Date the vendor was onboarded.
* Password: Vendor’s login password.

#### Resetting password

Vendors can reset their password by:

1. Clicking **Reset Password**.
2. Entering the old and new passwords.
3. Clicking **Reset**.

Alternatively, vendors can click **Forgot Password** and follow the instructions in the email sent to their registered email ID.

<Note>
  If the email is not received, please clear the cache and try again in incognito mode.
</Note>

<Frame>
  <img alt="" />
</Frame>

### Account details

The **Account Details** section includes:

* Account holder: Name of the account holder.
* IFSC code: Bank branch IFSC code.
* Account number: Vendor’s bank account number.
* UPI or VPA: Vendor’s UPI ID.
* Settlement cycle: Configured settlement schedule.
* Vendor type: Individual or Business.

### Merchant details

The **Merchant Details** section includes:

* Merchant ID
* Name: Merchant’s name.
* Email address: Merchant’s registered email ID.
* Phone number: Merchant’s contact number.


# Reports
Source: https://www.cashfree.com/docs/payments/split/vendor/dashboard/reports

Let vendors download Cashfree Vendor Dashboard reports for their transactions, settlements, refunds, and balances without exposing other marketplace data.

The reports section in the Vendor Dashboard allows vendors to view the vendor recon and settlement-specific report. The report section has details such as report name, report size, the report generated time, and generate a new report.

Select the date range from the drop-down menu. Use the **Search & Filter** option to view specific reports. The reports will be generated based on these selections. Vendors can configure two types of report filters:

* Vendor Reconciliation - vendors can view the reconciliation details of all vendors.
* Settlement Specific - vendors can view the reconciliation details that are specific to a settlement by specifying the settlement ID.

<img alt="" />

To generate a new report,

1. Go to **Vendor Dashboard** > **Reports**.
2. In the Reports homepage, select the **Generate New Report** option.
3. Choose the **Report Type** and the **Date Range**. Provide a **Report Name** and select the **File Format**. Supported file formats are CSV and XLS.
4. If you are generating a settlement-specific report, provide the **settlement ID**.
5. Click **Generate Report**. The report is successfully generated and can be downloaded from the Report homepage.

<img alt="" />

You can delete a report by selecting the ellipsis icon on the report that should be deleted and select the **Delete** option. Click **Delete** from the Delete Report pop-up window.

<img alt="" />

A sample report is available <a href="https://gocashassets.s3.ap-south-1.amazonaws.com/repostmancollection/Vendor%20Recon%20Report.zip">here</a>.


# Settlements
Source: https://www.cashfree.com/docs/payments/split/vendor/dashboard/settlements

Let marketplace vendors view their Cashfree settlements in the Vendor Dashboard with payout schedule, status, and per-order breakdown for full transparency.

Your vendors can now view standard and on-demand settlements from the settlement section. You can settle your vendors through the following settlement modes:

* [Vendor Instant Settlement](#instant-settlement)
* [Vendor Standard Settlement](#standard-settlement)
* [Vendor On-Demand Settlement](#on-demand-settlement)

To view the settlements, go to **vendor dashboard** > **Settlements**. Vendor settlement details such as: billed to, settlement ID, UTR number, adjustment amount, settlement charges, the settlement amount, and the settlement status are displayed.

<img alt="" />

## Standard settlement

The standard schedule option in Cashfree is T+2\* days, where T is the date of the transaction. For instance, if the transaction takes place on a Monday, the settlement is credited to your vendor's account on Wednesday. The standard settlements happen only on bank working days. By default, the standard settlement tab will be displayed.

<Info>
  T+x\*: Settlement cycle is subject to bank approval and can vary based on
  transaction type, business category/model, risk parameters, and other factors.
</Info>

To view vendor standard settlement,

Go to **vendor dashboard** > **Settlements** > **Standard**. For more information, see [Vendor standard settlement](/docs/payments/split/settlements/standard).

Select a particular settlement to view more details. On this page, vendors can view details such as: settlement ID, settlement amount, credit amount, currency, settlement fee, tax, debit amount, vendor ID, settlement status and so on.

<img alt="" />

## Instant settlement

You can settle your vendors instantly through the instant settlement feature. For more information, see [Vendor instant settlement](/docs/payments/split/settlements/instant).

<Info>Vendors can identify an instant settlement by this ⚡️ symbol.</Info>

## On demand settlement

With vendor on-demand settlements, you can settle the unsettled balances to your vendors bank account instantly 24\*7, including holidays.

To view vendor on-demand settlement,

Go to **vendor dashboard** > **Settlements** > **On Demand**. Select a particular on-demand settlement to view more details. For more information, see [On-demand settlements](/docs/payments/split/settlements/on-demand).

<img alt="" />


# Transactions
Source: https://www.cashfree.com/docs/payments/split/vendor/dashboard/transactions

Let marketplace vendors browse their Cashfree transactions in the Vendor Dashboard, filter by status and date, and reconcile orders with settlement payouts.

On the Transactions page, vendors can view details of payments, refunds, and adjustments. They can seamlessly navigate between each of these sections. Various filters are available that give vendors the flexibility to search and filter for the required transactions.

<img alt="" />

## Payments

The Payments tab displays all the payments your Vendor has made in the configured time period. In this section, vendors can see details such as: orderID, transaction ID, payment mode, commission, customer name, customer phone number, and customer email.

Click on a particular payment to view more details about the payment. The detailed screen appears as shown below:

<img alt="" />

In the transactions screen, vendors can see the order ID, and vendor settlement amount. Other details available on this page are:

* Customer details - name, phone number, email ID.
* Transaction details - transaction ID, transaction amount, service charge, split service charge, transaction time, payment mode, service tax, split service tax.
* Vendor details - payout ID, vendor settlement amount.

## Refunds

The refunds tab lists all the refunds along with the batch refunds that are initiated for that specific date range. In this section, vendors can see details such as: orderID, refund amount, refund ID, CF refund ID, customer phone number, payment mode, and the refund status.

Use the Search and Filter options to search for any particular refund or filter the refunds based on the statuses. For more information, see [Refunds](/docs/payments/split/refund/initiate).

<img alt="" />

## Adjustments

The adjustments tab lists all the adjustments that are initiated for that specific date range. In this section, vendors can see details such as: adjustment ID, credit/debit adjustment, transfer amount, adjustment status, and adjustment remark.

Use the Search and Filter option to search for any particular adjustment or filter the adjustments based on the statuses. For more information, see [Adjustments](/docs/payments/split/vendor/balance/adjust).

<img alt="" />


# Edit Vendor Details
Source: https://www.cashfree.com/docs/payments/split/vendor/edit

Edit Cashfree Easy Split vendor details from the Merchant Dashboard, including KYC, bank account, contact, and settlement preferences for active vendors.

While adding vendors, if you have specified incorrectly vendor details or missed adding some information, you can modify it using the **Edit Vendor** feature on the product dashboard or use the [Update Vendor Details](/docs/api-reference/payments/latest/easy-split/update-vendor-details) API.

## Vendor status

Once you have added a vendor, it will go through various stages. They are mentioned in the table below.

| Vendor status | Description |
| :- | :- |
| In Bank Validation | This status indicates that the bank account validation process have been initiated. |
| Bank Validation Failed | This status indicates that the bank validation has failed. Update bank account details to correct one. |
| In Bene Creation | This status indicates that the beneficiary creation is in process. During this process, we will add beneficiary accounts through our banking partner to process future transfers. |
| Bene Creation Failed | This status indicates that the beneficiary creation at the partner bank has failed. Update bank account details to retry new beneficiary creation. |
| Action Required | This status indicates that either one or multiple KYC documents has failed verification. Merchant should provide - correct/updated/relevant KYC documents to progress further with vendor onboarding. |
| Active | This status indicates that the vendor account is active. |
| On Hold | The On-hold status is updated by the Cashfree team. The onboarding team has put the account On-hold because either the document is not available or the documents shared are insufficient. |
| Blocked | This status indicates that your vendor account is blocked. You can later unblock if you intend to resume the vendor settlements. |
| Deleted | This account indicates that your vendor account is deleted. |

To edit the details of the vendor you have already added,

1. Go to **Payment Gateway Dashboard** > **Easy Split - Vendor**.

2. Click the ellipsis icon on the vendor you want to make changes to and select **Edit Vendor**.

<img alt="" />

You can update the following details:

Vendor details:

* Vendor phone number
* Vendor email ID
* Schedule Option
* Dashboard access

Vendor bank account details:

* Account holder name
* Account number
* IFSC code
* UPI VPA
* Verify account details option

KYC details:

* Vendor type
* Business type
* Documents (Based on the vendor type and business type of your vendors)

Once done updating the changes, click the **Update Vendor Details** option to save your changes.

<img alt="" />

<img alt="" />

<img alt="" />

## Delete vendor

You can delete the added vendors from the dashboard. Click the ellipsis icon on the vendor you want to delete, and select **Delete Vendor**. Click **Delete** in the pop-up window.

<img alt="" />


# Vendor KYC
Source: https://www.cashfree.com/docs/payments/split/vendor/kyc

Submit Cashfree Easy Split vendor KYC documents so marketplace vendors are verified, activated for payouts, and remain compliant with RBI and bank guidelines.

To improve the current vendor onboarding process to comply with PA-PG and the digital lending norms we have included the vendor KYC collection for both individual vendor accounts and business accounts. For business account type, type of vendor business is to be collected and additional document verification is carried out for NBFC, Financial services businesses and other critical businesses.

## Overview

Current vendor onboarding does not include KYC details collection. This makes it easier for fraudulent vendors or seller accounts to use the platform and start selling products or services which are not authorised by merchants. **There is no due diligence on the relationship between the merchant and the vendor accounts**.

By including KYC details during onboarding, there will be

1. A surety for merchants to continue business with Cashfree and post account audits
2. A clear connection between the merchant and the vendor relationship
3. Validation for the product or services offered by vendor

**Why should businesses onboard vendors with KYC?**

* To continue business as usual with Cashfree EasySplit, non-compliant vendors will be blocked for settlement until they meet the required criteria
* For businesses which fall under the purview of digital lending guidelines, onboarding the vendor accounts with the full KYC checks will ensure that loan repayments are done to the valid bank accounts of the NBFCs where the settlements are intended to be credited.
* Criminals on board the platforms use fake information and act as sellers/buyers to steal consumers' identities or process transactions for products or services which they are not intended to otherwise under specific MCC codes. This will limit such unauthorised vendors.

| Vendor type | KYC documents required for non-critical business | KYC documents required for critical business |
| :- | :- | :- |
| Individual | - PAN - Address Proof: Any one of (Aadhaar, Driving License, passport and Voter ID) | - PAN - Address Proof: Any one of (Aadhaar, Driving License, passport and Voter ID) |
| Business | - Business PAN, CIN, GSTIN when the settlement limit applies | - Business PAN, CIN, GSTIN when the settlement limit applies |

<Note>
  Individual vendors do not need a GSTIN. Business vendors need a GSTIN only when the sum of vendor settlements to a single PAN or merchant across vendors exceeds 20 lakhs in the last twelve months.
</Note>

> These are the dummy data that non-critical merchants alone can use adding vendor from the **[Merchant Dashboard](https://merchant.cashfree.com/auth/login)**:\
> Individual PAN: BNZAA2318J\
> Business PAN: BNZAA2318J\
> Voter ID: XGN3002623\
> GST : 06BZAHM6385P6Z2\
> CIN: U12345AB6784CDE123456

## Verification process

The various KYC status for vendor accounts is mentioned in the table below.

| KYC status | Description |
| :- | :- |
| Document not shared | If KYC details are submitted without documents, Cashfree marks the status as document not shared. |
| In Document Review | If KYC details are submitted with documents then Cashfree marks the status as in document review. |
| Completed | Once the documents are verified by the ops team, the status of vendor KYC will change to complete. |
| On Hold | The On-hold status is updated by the Cashfree team. The onboarding team has put the account On-hold because either the document is not available or the documents shared are insufficient. |
| Blocked | This is done by you if you intend to stop vendor settlement to the vendors. You can later unblock if you intend to resume the vendor settlements. |

Use our latest APIs to stay risk-free using KYC-based onboarding. For more information, see [Vendor APIs](/docs/api-reference/payments/previous/v2023-08-01/split/vendors/overview).


# Settlement Webhook
Source: https://www.cashfree.com/docs/payments/split/webhooks

Configure Cashfree Easy Split settlement webhooks so your backend gets real-time events for vendor settlements, balance updates, and split scheme outcomes.

Configure vendor settlement webhooks to receive automated notifications when vendor settlements are initiated, successfully processed, failed, or reversed.

The webhook notifications are sent on all the URLs added and enabled in the settlement webhook. You can add new URLs and enable or disable existing URLs for settlement webhook at any time and it will reflect instantaneously. For security best practices on webhook endpoints, refer to the [Webhook Security Checklist](/docs/payments/online/webhooks/security-checklist).

The table below lists the webhook events available for settlements.

| Webhook event | Description |
| :- | :- |
| VENDOR\_SETTLEMENT\_INITIATED | Cashfree triggers this webhook when a vendor settlement starts. |
| VENDOR\_SETTLEMENT\_SUCCESS | Cashfree triggers this webhook when a vendor settlement succeeds. |
| VENDOR\_SETTLEMENT\_FAILED | Cashfree triggers this webhook when a vendor settlement fails. |
| VENDOR\_SETTLEMENT\_REVERSED | Cashfree triggers this webhook when a vendor settlement is reversed. |

***

## Vendor settlement initiated

Cashfree triggers the SETTLEMENT\_INITIATED webhook when it initiates a settlement.

```json theme={"dark"}
{
    "data": {
        "settlement": {
            "settlement_id": 49703,
            "status": "CREATED",
            "utr": "1686217237243457",
            "payment_amount": null,
            "settlement_initiated_on": "2023-06-08T15:10:35+05:30",
            "settled_on": "null",
            "reason": null,
            "adjustment": 100.00,
            "settlement_amount": 600.00,
            "service_charge": 0.50,
            "service_tax": 0.09,
            "amount_settled": null,
            "payment_from": "2023-06-08",
            "payment_till": "2023-06-08",
            "vendor_id": "esSettlementsAutomationVendor",
            "vendor_transaction_amount": 500.00,
            "account_mode": "BANK",
            "settled_orders_count": 1
        }
    },
    "event_time": "2023-06-08T15:10:37+05:30",
    "type": "VENDOR_SETTLEMENT_CREATED"
}
```

***

## Vendor settlement success

```json theme={"dark"}
{
    "data": {
        "settlement": {
            "settlement_id": 49703,
            "status": "SUCCESS",
            "utr": "1686217237243457",
            "payment_amount": null,
            "settlement_initiated_on": "2023-06-08T15:10:35+05:30",
            "settled_on": "2023-06-08T15:10:37+05:30",
            "reason": null,
            "adjustment": 100.00,
            "settlement_amount": 600.00,
            "service_charge": 0.50,
            "service_tax": 0.09,
            "amount_settled": 600.00,
            "payment_from": "2023-06-08",
            "payment_till": "2023-06-08",
            "vendor_id": "esSettlementsAutomationVendor",
            "vendor_transaction_amount": 500.00,
            "account_mode": "BANK",
            "settled_orders_count": 1
        }
    },
    "event_time": "2023-06-08T15:10:37+05:30",
    "type": "VENDOR_SETTLEMENT_SUCCESS"
}
```

***

## Vendor settlement failed

```json theme={"dark"}
{
    "data": {
        "settlement": {
            "settlement_id": 49703,
            "status": "FAILED",
            "utr": "1686217237243457",
            "payment_amount": null,
            "settlement_initiated_on": "2023-06-08T15:10:35+05:30",
            "settled_on": "null",
            "reason": null,
            "adjustment": 100.00,
            "settlement_amount": 600.00,
            "service_charge": 0.50,
            "service_tax": 0.09,
            "amount_settled": null,
            "payment_from": "2023-06-08",
            "payment_till": "2023-06-08",
            "vendor_id": "esSettlementsAutomationVendor",
            "vendor_transaction_amount": 500.00,
            "account_mode": "BANK",
            "settled_orders_count": 1
        }
    },
    "event_time": "2023-06-08T15:10:37+05:30",
    "type": "VENDOR_SETTLEMENT_FAILED"
}
```

***

## Vendor settlement reversed

```json theme={"dark"}
{
    "data": {
        "settlement": {
            "settlement_id": 49703,
            "status": "REVERSED",
            "utr": "1686217237243457",
            "payment_amount": null,
            "settlement_initiated_on": "2023-06-08T15:10:35+05:30",
            "settled_on": "null",
            "reason": Failed from bank end,
            "adjustment": 100.00,
            "settlement_amount": 600.00,
            "service_charge": 0.50,
            "service_tax": 0.09,
            "amount_settled": null,
            "payment_from": "2023-06-08",
            "payment_till": "2023-06-08",
            "vendor_id": "esSettlementsAutomationVendor",
            "vendor_transaction_amount": 500.00,
            "account_mode": "BANK",
            "settled_orders_count": 1
        }
    },
    "event_time": "2023-06-08T15:10:37+05:30",
    "type": "VENDOR_SETTLEMENT_REVERSED"
}
```

***

## Payload field description

| Field | Description | Example |
| :- | :- | :- |
| adjustment | The sum of refunds, disputes, and chargeback part of this settlement is displayed here. | 0 |
| amount\_settled | The total amount that is settled in this schedule option. | 50 |
| payment\_amount | Total transaction amount considered for settlement. | 100 |
| payment\_from | Start date from which the payments are considered for settlement. | 2022-03-15 |
| payment\_till | End date till which the payments are considered for settlement. | 2022-03-23 |
| reason | Reason for failed and reversed settlements. For more information, see [Reasons for failed and reversed settlements](#reasons-for-failed-and-reversed-settlements). | Transfer mode is not valid for beneficiary. |
| service\_charge | Service charges are applicable for the payments that are included in this settlement. | 2 |
| service\_tax | Service tax is applicable for the payments that are included in this settlement. | 0.50 |
| settled\_on | Date and time at which the settlement was processed. | 2022-03-17T14:21:18+05:30 |
| settlement\_amount | The sum of net settlement amount for the payments part of this settlement. | 13 |
| settlement\_id | Cashfree settlement ID | 1155353 |
| settlement\_initiated\_on | The date on which settlement was initiated. | 2022-03-17T14:29:21+05:30 |
| status | Status of the settlement (either INITIATED, SUCCESS, FAILED, or REVERSED) | SUCCESS |
| utr | The unique transaction reference number is given by the bank for the settlement. | N076221079016329 |
| vendor\_id | Reference ID as shared by you when onboarding the vendor. | IS\_1hour\_Upi |
| vendor\_transaction\_amount | Transaction amount split of vendor | 50 |
| event\_time | Time at which settlement webhook was initiated. | 2022-03-17T14:29:23+05:30 |
| type | Type of webhook - VENDOR\_SETTLEMENT\_INITIATED, VENDOR\_SETTLEMENT\_SUCCESS, VENDOR\_SETTLEMENT\_FAILED, or VENDOR\_SETTLEMENT\_REVERSED. | VENDOR\_SETTLEMENT\_SUCCESS |

## Reasons for failed and reversed settlements

| Reason | Category | Description |
| :- | :- | :- |
| BANK\_GATEWAY\_ERROR | Bank | Technical error at the bank |
| BENE\_BANK\_DECLINED | Bank | Rejected by Beneficiary bank due to business reasons |
| FAILED | Bank | No explicit failure reason from the bank |
| INVALID\_IFSC\_FAIL | Customer | Invalid ifsc code provided for bank account |
| INVALID\_ACCOUNT\_FAIL | Customer | Bank account is invalid |
| RETURNED\_FROM\_BENEFICIARY | Bank | Immediate reversal from the beneficiary bank |
| INSUFFICIENT\_BALANCE | Vendor | Your balance is exhausted, need to add funds |
| IMPS\_MODE\_FAIL | Bank | IMPS mode not supported for the beneficiary |
| RTGS\_MODE\_FAIL | Bank | RTGS mode not supported (only for RTGS) |
| REINITIALIZE\_TRANSFER\_LATER | Bank | Technical error at the bank, retry later |
| NRE\_ACCOUNT\_FAIL | Customer | Customer bank account is an NRE account |
| ACCOUNT\_BLOCKED | Customer | Customer bank account is blocked |
| DEST\_LIMIT\_REACHED | Bank | Transfer limit to beneficiary exceeded |
| INVALID\_MODE\_FAIL | Bank | Transfer mode not valid for beneficiary |
| NPCI\_UNAVAILABLE | Bank | NPCI is unavailable |
| BENEFICIARY\_BANK\_OFFLINE | Bank | Beneficiary bank is offline |
| INVALID\_AMOUNT\_FAIL | Vendor | Amount is invalid for the given transfer mode |
| SUSPECTED\_TRANSFER | Customer | Suspicious transfer identified |
| BENE\_NAME\_DIFFERS | Customer | Beneficiary name not matching with bank records |
| DISABLED\_MODE | Vendor | Transfer mode not enabled for the account |
| AMAZON\_AMOUNT\_EXCEED | Vendor | Amount should be less than 10000 for Amazon Pay mode |
| BENEFICIARY\_BLACKLISTED | Vendor | Beneficiary is blacklisted |
| PAYOUT\_INACTIVE | Vendor | Payout account is not active |
| INVALID\_TRANSFER\_AMOUNT | Vendor | Transfer amount is invalid |
| BENEFICIARY\_NOT\_EXIST | Vendor | Beneficiary does not exist |
| BENEFICIARY\_INVALID\_MODE | Vendor | Mode Not valid for Beneficiary |
| INVALID\_BENE\_ACCOUNT\_OR\_IFSC | Vendor | Invalid bank account number or ifsc provided |
| BENEFICIARY\_NAME\_DIFFERS | Customer | Beneficiary name not matching with bank records |
| ANY\_OTHER\_REASON | Bank | No reason provided for the failure/reversal |
| INVALID\_OR\_NO\_SUCH\_ACCOUNT\_TYPE | Customer | Invalid account |

***

## Signature verification

Use the signature to verify that the request has not been tampered with. To verify the signature, you need your Cashfree PG secret key and the payload.

timestamp is present in the header x-webhook-timestamp\
Actual signature is present in the header x-webhook-signature

```json theme={"dark"}
"headers": {
        "host": "gamma.cashfree.com",
        "x-request-id": "ad4dc1e65f8901302455b247237a667a",
        "x-real-ip": "172.0.57.13",
        "x-forwarded-for": "172.0.57.13",
        "x-forwarded-host": "gamma.cashfree.com",
        "x-forwarded-port": "80",
        "x-forwarded-proto": "http",
        "x-forwarded-scheme": "http",
        "x-scheme": "http",
        "x-original-forwarded-for": "52.66.25.127",
        "content-length": "592",
        "accept": "_/_",
        "content-type": "application/json",
        "user-agent": "ReactorNetty/1.0.30",
        "x-datadog-parent-id": "4281924148563621550",
        "x-datadog-sampling-priority": "1",
        "x-datadog-trace-id": "228569355002181270",
        "x-webhook-signature": "Xm0YzEJCRsh0XvIEK12D4FqpmC60cReKoqPBn424kV0=",
        "x-webhook-timestamp": "1686217237543",
        "x-webhook-version": "2022-09-01"
    }
```

Watch this video to learn more on Vendor Webhooks

<iframe title="YouTube video player" />


# Charge a Subscription
Source: https://www.cashfree.com/docs/payments/subscription/charge

Charge customers on active Cashfree Subscriptions from the dashboard, in bulk, or via the Charge Subscription API for automated recurring billing.

Collect payments for your subscriptions manually through the dashboard, in bulk, or using the [Charge Subscription API](/docs/api-reference/payments/latest/subscription/raise-a-charge-or-create-an-auth). Cashfree processes each transaction and confirms payment collection from your customer.

For periodic subscriptions, Cashfree automatically initiates payments on your behalf at each billing interval. For on-demand subscriptions, you will need to manually charge your customer as needed.

<Note>
  **Cashfree Retry Policy**: UPI Autopay charges follow a 1+3 retry mechanism.
  If the initial attempt fails, the system retries up to three times at hourly
  intervals. ENACH and Card payment methods do not support automatic retries.
</Note>

<Tabs>
  <Tab title="Dashboard">
    You can either raise a single charge from a dashboard or you can raise multiple charges by uploading a file.

    <img />

    <img />
  </Tab>

  <Tab title="API">
    You can also create a new charge using the [Charge Mandate](/docs/api-reference/payments/latest/subscription/raise-a-charge-or-create-an-auth) API.

    Raising charges on multiple subscriptions at once is not supported via API currently.

    ### Controlled charging

    <Warning>
      Controlled charging is a two-step flow in which you send the pre-debit notification and trigger the debit. Cashfree does not automatically retry a failed attempt. You must trigger each attempt yourself.
    </Warning>

    By default, Cashfree handles the pre-debit notification and the debit for you in a
    single [Raise a Charge](/docs/api-reference/payments/latest/subscription/raise-a-charge-or-create-an-auth) call.

    If you would rather control both steps (sending the notification yourself, then
    triggering the debit at a time you choose, with your own retry logic), use the
    controlled payment APIs instead. You send a pre-debit notification, then execute the
    charge at least 24 hours later. Currently supported for UPI Autopay only.

    The two approaches are alternatives, not stages of the same flow. Pick one per charge cycle.

    <Card title="Controlled Subscription Payments" href="/docs/api-reference/payments/latest/subscription/payment/controlled/overview">
      How the two-step flow works, the identifiers, retry limits and timing rules.
    </Card>
  </Tab>
</Tabs>

## After creating a charge

Depending on the payment method the charge you have created might be updated asynchronously. In some cases where customer's bank account does not have sufficient funds the charge attempt will fail. Here are the states which a charge will go through:

| Transaction state | Description |
| - | - |
| **INITIALIZED** | This state indicates that the transaction is initialized. |
| **PENDING** | Transaction is pending while being processed and sent to the appropriate bank for approval. |
| **SUCCESS** | Transaction is completed successfully. A success notification is received from the bank, and a success webhook is triggered to notify this. |
| **FAILED** | Transaction has failed. A failure notification is received from the bank, and a failed webhook is triggered to notify this. |
| **CANCELLED** | This state indicates that the on-demand transaction has been cancelled. |

## Cut-off timelines for raising a charge

| Charge raised on | Charge scheduled for | NACH | UPI autopay | SI on Indian cards | SI on international cards |
| - | - | - | - | - | - |
| T: 00:00 - 06:59 | null | Raised on T | Not Allowed | Not Allowed | Raised on T |
| T: 07:00 - 11:59 | null | Raised on T+1 | Not Allowed | Not Allowed | Raised on T+1 |
| T: 00:00 - 06:59 | T | Raised on T | Not Allowed | Not Allowed | Raised on T |
| T: 07:00 - 11:59 | T | Not Allowed | Not Allowed | Not Allowed | Not Allowed |
| T: 00:00 - 20:59 | T+1 | Raised on T+1 | Raised on T+1 | Raised on T+1 | Raised on T+1 |
| T: 21:00 - 23:59 | T+1 | Raised on T+1 | Not Allowed | Not Allowed | Raised on T+1 |
| T: 00:00 - 23:59 | T+n (n between and including 2 and 14) | Raised on T+n | Raised on T+n | Raised on T+n | Raised on T+n |
| T: 00:00 - 23:59 | T+15 | Not Allowed | Not Allowed | Not Allowed | Not Allowed |


# Create a Subscription
Source: https://www.cashfree.com/docs/payments/subscription/create

Create a Cashfree subscription, collect customer authorisation through the returned auth link, and activate recurring billing once the mandate is approved.

A subscription entity signifies the customer's commitment to make regular payments, showing they actively use the service and pay on a recurring basis. To register a subscription, first obtain the customer's authorisation. When you create a subscription, the response includes an authorisation link. Redirect the customer to this link to complete the authorisation process. Once the customer authorises, the subscription becomes active.

<Tabs>
  <Tab title="Dashboard">
    To create a new subscription from the dashboard, Go to `Subscriptions Dashboard > All Subscriptions > Create Subscription`. Follow the steps as shown in the below image.

    <img />

    You can also create multiple subscriptions at once using the dashboard. Go to `Subscriptions Dashboard > Batch Subscriptions > Upload File` to upload a file that contains all the information required for multiple subscriptions.
  </Tab>

  <Tab title="API">
    To create a new subscription via API, refer [Create Mandate](/docs/api-reference/payments/latest/subscription/create-subscription).
    Currently, creation of multiple subscriptions at once using API is not supported.
  </Tab>
</Tabs>

## Authorisation lifecycle

Before a subscription becomes ACTIVE, the customer must authorise it. Authorisation indicates that the customer has completed the initial payment (if applicable) and successfully subscribed. If the customer doesn’t complete payment within a certain timeframe, the subscription link will expire.

The table below explains the various states an authorisation can go through once it's created:

| Authorisation state | Description |
| - | - |
| **INITIALIZED** | The system creates the authorisation request. |
| **PENDING** | The customer needs to act on the authorisation request, and the bank must confirm it. |
| **SUCCESS** | The customer successfully completes and approves the authorisation. |
| **FAILED** | The authorisation request fails due to customer decline, timeout, or other errors. |

### Authorisation validity period

An authorisation request remains in the **INITIALIZED** state while the customer completes the mandate authorisation. The authorisation validity period defines the maximum time available for the customer to complete this action. If the customer doesn't complete the authorisation within this period, the authorisation automatically moves to the **FAILED** state with the reason `No action performed by customer`.

Refer to the following example, where Cashfree creates an authorisation request at 10:00 AM with a validity period of 30 minutes:

| Scenario | Customer action | Outcome |
| - | - | - |
| Customer completes the authorisation | Completes the mandate authorisation at 10:20 AM, within the 30-minute window. | The authorisation reaches a terminal state, and the subscription activates successfully. |
| Customer doesn't complete the authorisation | Doesn't act before the validity period expires at 10:30 AM. | The authorisation moves from **INITIALIZED** to **FAILED** with the reason `No action performed by customer`. |

The authorisation validity period works as follows:

* The validity period starts when Cashfree creates the authorisation request.
* The customer must complete the authorisation before the validity period expires.
* After the validity period expires, the authorisation can't resume. Create a new authorisation request to retry.
* Cashfree configures the validity period for your merchant account.

<Note>
  To change your merchant account's validity period, submit a request through the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1).
</Note>

## Subscription lifecycle

The table below describes the various states a subscription enters after creation:

| Subscription state | Description |
| - | - |
| **INITIALIZED** | The system creates the subscription but waits for customer authorisation. |
| **BANK\_APPROVAL\_PENDING** | The customer authorises the subscription, but the bank confirmation is still pending. For NACH, it may take 24 to 48 hours for the bank to confirm the mandate. |
| **ACTIVE** | The bank fully authorises the subscription, making it ready for payment collection. |
| **ON\_HOLD** | The subscription goes on hold due to a failed recurring payment and resumes once reactivated. This applies to periodic mandates on NACH and Cards standing instructions payment methods. |
| **PAUSED** | The merchant pauses the subscription, applicable only for active periodic subscriptions. |
| **COMPLETED** | The subscription completes its cycle. |
| **CUSTOMER\_CANCELLED** | The customer cancels the subscription at the bank. Cancelled subscriptions can't resume. |
| **CUSTOMER\_PAUSED** | The customer pauses the subscription from their UPI app; only the customer can resume it. |
| **EXPIRED** | The subscription reaches its expiry date and stops processing payments. |
| **LINK\_EXPIRED** | The authorisation link expires without successful completion by the customer; no further action is possible. This applies to non-seamless subscriptions created after May 4, 2023. |
| **CARD\_EXPIRED** | This status occurs when the active subscription’s authorised card has expired. No further charges will be processed. To continue the subscription, create a new one and authorise it using a valid card. |
| **CANCELLED** | The merchant cancels the subscription. |

Below is a visual diagram illustrating the different states during the subscription lifecycle:

```mermaid theme={"dark"}
stateDiagram-v2
    [*] --> INITIALIZED

    INITIALIZED --> BANK_APPROVAL_PENDING: Customer completes authorisation
    INITIALIZED --> CANCELLED: Cancelled by merchant
    INITIALIZED --> LINK_EXPIRED: Checkout link expires

    BANK_APPROVAL_PENDING --> ACTIVE: Bank approval successful
    BANK_APPROVAL_PENDING --> COMPLETED: Subscription expires
    BANK_APPROVAL_PENDING --> CANCELLED: Cancelled by merchant
    BANK_APPROVAL_PENDING --> INITIALIZED: Authorisation unsuccessful



    CANCELLED --> [*]
    COMPLETED --> [*]
    LINK_EXPIRED --> [*]
```

<Note>
  When a customer cancels a UPI Autopay subscription through a third-party application provider (TPAP), such as Google Pay or PhonePe, the status updates to **CUSTOMER\_CANCELLED** within 30–45 minutes.
</Note>

## First charge date (FCD) for a subscription

Merchants pass the subscription\_first\_charge\_time (FCD) when they create a subscription.
However, the earliest possible debit date depends on the payment mode and the time when the customer completes the authorisation.

Cashfree does not modify the FCD provided by the merchant.
Instead, we set the next\_schedule\_date to the nearest possible debit date based on the rules below.
In such cases, the subscription is charged on the next\_schedule\_date instead of the merchant-provided FCD.

Nearest possible first charge date

| Payment mode | Authorisation time | Nearest possible debit date |
| - | - | - |
| UPI Autopay | Before 9:00 PM | T + 1 |
| UPI Autopay | After 9:00 PM | T + 2 |
| Cards | Before 9:00 PM | T + 1 |
| Cards | After 9:00 PM | T + 2 |
| eNACH | Anytime | T + 4 |

**T = Date on which the customer completes authorisation**

Example

A merchant passes **T + 1** as the FCD during subscription creation.\
The customer authorises using **eNACH**, and the earliest possible debit date for eNACH is **T + 4**.

* **FCD (merchant input):** remains T + 1
* **next\_schedule\_date:** automatically set to T + 4
* **First debit:** occurs on T + 4


# Android Custom Card Component (Non-PCI)
Source: https://www.cashfree.com/docs/payments/subscription/custom-checkout/custom-card/android-custom-card

Integrate the Cashfree Subscription Custom Card Component into your Android application to accept subscription payments without handling raw card data.

The Cashfree Subscription Custom Card Component lets you embed a secure, SDK-managed card input field directly into your Android application UI. Because the `CFSubsCardNumberView` component captures and processes the card number entirely within the SDK, your application never receives the raw card number. This makes the integration suitable for non-PCI merchants, that is, merchants who are not certified to store, process, or transmit raw cardholder data, and who rely on the SDK to handle card data securely on their behalf.

<Frame>
  <img alt="Sample card UI showing CFSubsCardNumberView with card number input field" />
</Frame>

<Note>
  This page covers the custom card component integration only. For the full Android Subscription Element integration, including UPI Intent and eNach (net banking), see [Android Integration](/docs/payments/subscription/custom-checkout/mobile/android-subscription-element).
</Note>

## Prerequisites

Complete the following tasks before you start the integration:

* Create a [Cashfree Merchant Account](https://merchant.cashfree.com/merchants/signup).
* Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and generate an **App ID** and **Secret Key**. Learn how to [generate API keys](/docs/api-reference/authentication#generate-api-keys).
* Set your application's `minSdkVersion` to API level 19 or higher.

The integration consists of three steps:

<CardGroup>
  <Card title="Step 1" icon="money-bill-wave" href="/docs/payments/subscription/custom-checkout/custom-card/android-custom-card#step-1-create-a-subscription-server-side">
    Create a subscription
  </Card>

  <Card title="Step 2" icon="desktop" href="/docs/payments/subscription/custom-checkout/custom-card/android-custom-card#step-2-open-the-payment-page-client-side">
    Open the payment page
  </Card>

  <Card title="Step 3" icon="circle-check" href="/docs/payments/subscription/custom-checkout/custom-card/android-custom-card#step-3-confirm-the-payment-server-side">
    Confirm the payment
  </Card>
</CardGroup>

## Step 1: Create a subscription <Badge>Server-side</Badge>

Create a subscription from your backend server before you process any payment.

<Note>This API requires your secret key. Create subscriptions through your server only — do not call this API directly from your mobile application.</Note>

After the subscription is created, your backend receives a `subscription_id` and a `subscription_session_id`. Pass both values to your Android client to proceed with the payment.

<AccordionGroup>
  <Accordion title="API request for creating a subscription">
    The following example shows how to create a subscription using the Create Subscription API:

    <CodeGroup>
      ```bash cURL theme={"dark"}
      curl --request POST \
        --url https://sandbox.cashfree.com/pg/subscriptions \
        --header 'Content-Type: application/json' \
        --header 'x-api-version: 2025-01-01' \
        --header 'x-client-id: <your-client-id>' \
        --header 'x-client-secret: <your-client-secret>' \
        --data '{
          "subscription_id": "Demo_Subscription",
          "customer_details": {
            "customer_name": "john",
            "customer_email": "john@dummy.com",
            "customer_phone": "9908730221",
            "customer_bank_account_number": "59108290701802",
            "customer_bank_ifsc": "HDFC0002614",
            "customer_bank_code": "HDFC",
            "customer_bank_account_type": "SAVINGS"
          },
          "plan_details": {
            "plan_name": "plan12345",
            "plan_type": "PERIODIC",
            "plan_amount": 10,
            "plan_max_amount": 100,
            "plan_max_cycles": 100,
            "plan_intervals": 2,
            "plan_currency": "INR",
            "plan_interval_type": "WEEK",
            "plan_note": "Bi-weekly INR 10 plan"
          },
          "authorization_details": {
            "authorization_amount": 100,
            "authorization_amount_refund": true,
            "payment_methods": [
              "card"
            ]
          },
          "subscription_meta": {
            "return_url": "https://example.com/subscription/return",
            "notification_channel": [
              "EMAIL",
              "SMS"
            ],
            "session_id_expiry": "2025-06-01T23:00:08+05:30"
          },
          "subscription_expiry_time": "2100-01-01T23:00:08+05:30",
          "subscription_first_charge_time": "2025-06-01T23:00:08+05:30",
          "subscription_tags": {
            "psp_note": "Monthly subscription payment"
          }
        }'
      ```

      ```javascript Node theme={"dark"}
      // Creating a subscription using the Cashfree Node SDK
      // https://github.com/cashfree/cashfree-pg-sdk-nodejs
      ```

      ```java Java theme={"dark"}
      // Creating a subscription using the Cashfree Java SDK
      // https://github.com/cashfree/cashfree-pg-sdk-java
      ```

      ```go Golang theme={"dark"}
      // Creating a subscription using the Cashfree Go SDK
      // https://github.com/cashfree/cashfree-pg
      ```

      ```csharp .NET theme={"dark"}
      // Creating a subscription using the Cashfree .NET SDK
      // https://github.com/cashfree/cashfree-pg-sdk-dotnet
      ```

      ```python Python theme={"dark"}
      // Creating a subscription using the Cashfree Python SDK
      // https://github.com/cashfree/cashfree-pg-sdk-python
      ```

      ```php PHP theme={"dark"}
      // Creating a subscription using the Cashfree PHP SDK
      // https://github.com/cashfree/cashfree-pg-sdk-php
      ```
    </CodeGroup>

    A successful response returns the `subscription_id` and `subscription_session_id`. Use these values to build the `CFSubscriptionSession` object in [Step 2](#step-2-open-the-payment-page-client-side). The API returns the following response on success:

    ```json theme={"dark"}
    {
      "subscription_id": "Demo_Subscription",
      "subscription_session_id": "subs_token_tc9JCN4MzUIJ",
      "subscription_status": "INITIALIZED",
      "cf_subscription_id": "4"
    }
    ```

    For the full list of request parameters and response fields, see the [Create Subscription API](/docs/api-reference/payments/latest/subscription/create-subscription).
  </Accordion>
</AccordionGroup>

## Step 2: Open the payment page <Badge>Client-side</Badge>

After you create the subscription, set up the card component and open the payment page so the customer can provide their card details.

### 1. Set up the SDK

The Cashfree Android SDK is available on Maven Central. The latest version is [2.4.0](https://github.com/cashfree/nextgen-android). The SDK requires Android API level 19 or higher.

Add the following dependency to your app-level `build.gradle` file:

```gradle theme={"dark"}
implementation 'com.cashfree.pg:api:2.4.0'
```

### 2. Complete the payment

To complete the payment, follow these steps:

1. Add the `CFSubsCardNumberView` component to your layout XML.
2. Initialise the card component in your activity or fragment.
3. Create a `CFSubscriptionSession` object.
4. Set up the subscription callback.
5. Build the payment object and initiate the payment.

#### Add the card component to your layout

The `CFSubsCardNumberView` component extends `TextInputLayout`, which means all standard `TextInputLayout` properties and methods apply to it. Add it to your layout XML file as follows:

```xml theme={"dark"}
<com.cashfree.pg.core.api.ui.CFSubsCardNumberView
    android:id="@+id/cf_subs_element_card"
    style="@style/Widget.MaterialComponents.TextInputLayout.OutlinedBox"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:layout_marginStart="16dp"
    android:layout_marginTop="16dp"
    android:layout_marginEnd="16dp"
    android:hint="@string/card_number"
    app:boxBackgroundColor="@color/white"
    app:boxStrokeColor="@color/color_cta"
    app:cf_card_error_text="Enter valid card number"
    app:cf_card_text_size="16sp"
    app:errorTextColor="@color/txt_error"
    app:helperTextTextColor="@color/color_cta"
    app:layout_constraintEnd_toEndOf="parent"
    app:layout_constraintStart_toStartOf="parent"
    app:layout_constraintTop_toTopOf="parent" />
```

The following XML attributes are available to customise the card component's appearance:

| Attribute | Description |
| - | - |
| `android:hint` | Hint text displayed on the card input field. |
| `app:boxBackgroundColor` | Background colour of the card input field. |
| `app:boxStrokeColor` | Stroke (border) colour of the card input field. |
| `app:errorTextColor` | Colour of the validation error message text. |
| `app:cf_card_error_text` | Custom error message shown when the card number is invalid. This is a Cashfree-provided attribute. |
| `app:cf_card_text_size` | Font size of the card number text. This is a Cashfree-provided attribute. |

Because `CFSubsCardNumberView` extends `TextInputLayout`, you can also call standard `TextInputLayout` methods programmatically. The following example shows commonly used methods:

```java theme={"dark"}
cfSubsCardNumberView.setError("Your error message");
cfSubsCardNumberView.setEnabled(true);
cfSubsCardNumberView.setErrorEnabled(false);
```

#### Initialise the card component

Obtain a reference to the `CFSubsCardNumberView` in your activity or fragment, then call its `initialize()` method. This method requires a `CFSubscriptionSession` object and an `ICardInfo` callback listener.

```java theme={"dark"}
// Declare the variable
private CFSubsCardNumberView cfSubsCardNumberView;

// Get the view reference from the layout
cfSubsCardNumberView = findViewById(R.id.cf_subs_element_card);
```

#### Create a session

The `CFSubscriptionSession` object holds the session context for the payment. It accepts the `subscription_session_id` and `subscription_id` obtained from [Step 1](#step-1-create-a-subscription-server-side), and the Cashfree environment (`.SANDBOX` or `.PRODUCTION`).

Set `Environment` to `.SANDBOX` for testing or `.PRODUCTION` for live payments. The following example shows how to create the session object:

```java theme={"dark"}
CFSubscriptionSession.Environment cfEnvironment = CFSubscriptionSession.Environment.SANDBOX; // or .PRODUCTION

CFSubscriptionSession cfSession = new CFSubscriptionSession.CFSubscriptionSessionBuilder()
        .setEnvironment(cfEnvironment)
        .setSubscriptionSessionID(subscription_session_id)
        .setSubscriptionId(subscription_id)
        .build();
```

#### Set up the ICardInfo callback

Call the `initialize()` method on the `CFSubsCardNumberView` object after you have created the session. The `ICardInfo` callback delivers card metadata to your application after each digit the customer enters.

```java theme={"dark"}
try {
    cfSubsCardNumberView.initialize(cfSession, jsonObject -> {
        // Card metadata is delivered here after each digit is entered.
        Log.d("CFCARDVIEW", jsonObject.toString());
    });
} catch (CFException e) {
    e.printStackTrace();
}
```

The callback delivers a `JSONObject` with the following structure:

| Field | Available from | Description |
| - | - | - |
| `cardLength` | First digit | The number of digits entered so far. |
| `luhnCheckInfo` | First digit | Whether the current card number passes the Luhn algorithm check. Values: `SUCCESS` or `FAIL`. |
| `cardBinInfo` | 8th digit | Card network metadata. Only present after the 8th digit is entered. |
| `cardBinInfo.scheme` | 8th digit | Card network scheme (for example, `visa`, `mastercard`). |
| `cardBinInfo.bankName` | 8th digit | Issuing bank name (for example, `axis bank`). |
| `cardBinInfo.type` | 8th digit | Card type classification. |
| `cardBinInfo.subType` | 8th digit | Card sub-type classification. |
| `cardBinInfo.brand` | 8th digit | Card brand classification. |

<Warning>
  The `cardBinInfo` object is only present in the callback after the customer has entered at least 8 digits. Always check that the key exists in the `JSONObject` before accessing it to avoid a `JSONException`.
</Warning>

The following log output illustrates how the callback data evolves as the customer enters their card number:

```json theme={"dark"}
// After the 1st digit
{"cardLength": 1, "luhnCheckInfo": "FAIL"}

// After the 2nd digit
{"cardLength": 2, "luhnCheckInfo": "FAIL"}

// After the 8th digit — cardBinInfo becomes available
{
  "cardLength": 8,
  "luhnCheckInfo": "FAIL",
  "cardBinInfo": {
    "scheme": "visa",
    "type": "filtered",
    "subType": "filtered",
    "brand": "filtered",
    "bankName": "axis bank"
  }
}

// After all 16 digits — luhnCheckInfo passes
{
  "cardLength": 16,
  "luhnCheckInfo": "SUCCESS",
  "cardBinInfo": {
    "scheme": "visa",
    "type": "filtered",
    "subType": "filtered",
    "brand": "filtered",
    "bankName": "axis bank"
  }
}
```

#### Set up the subscription callback

The SDK exposes the `CFSubscriptionResponseCallback` interface to receive callbacks when the subscription payment journey ends. This interface consists of two methods:

```java theme={"dark"}
public void onSubscriptionVerify(CFSubscriptionResponse response)
public void onSubscriptionFailure(CFErrorResponse cfErrorResponse)
```

<Tip>Register the callback in your activity's `onCreate` method. This configuration also handles activity restarts correctly.</Tip>

The following example shows how to implement the callback in your activity:

```java theme={"dark"}
public class YourActivity extends AppCompatActivity implements CFSubscriptionResponseCallback {

    @Override
    public void onSubscriptionVerify(CFSubscriptionResponse response) {
        // Verify subscription status from your backend before proceeding.
    }

    @Override
    public void onSubscriptionFailure(CFErrorResponse cfErrorResponse) {
        // Handle payment failure. Inspect cfErrorResponse for details.
    }

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_element_checkout);

        cfSubsCardNumberView = findViewById(R.id.cf_subs_element_card);

        try {
            CFPaymentGatewayService.getInstance().setCheckoutCallback(this);
        } catch (CFException e) {
            e.printStackTrace();
        }

        try {
            CFSubscriptionSession session = new CFSubscriptionSession.CFSubscriptionSessionBuilder()
                    .setSubscriptionId("your-subscription-id")
                    .setSubscriptionSessionID("your-subscription-session-id")
                    .setEnvironment(CFSubscriptionSession.Environment.SANDBOX) // or .PRODUCTION
                    .build();

            cfSubsCardNumberView.initialize(session, new ICardInfo() {
                @Override
                public void onInfo(JSONObject jsonObject) {
                    Log.d("CFCARDVIEW", jsonObject.toString());
                }
            });
        } catch (CFException e) {
            e.printStackTrace();
        }
    }
}
```

#### Build the payment object and initiate payment

When the customer fills in their card details and taps the pay button, build the `CFSubsCard` and `CFSubsCardPayment` objects and call `doSubscriptionPayment()` on the `CFSubsCardNumberView` instance.

<Warning>
  You must set `.setCfCard(true)` on the `CFSubsCard` builder. Because the SDK manages the card number internally via `CFSubsCardNumberView`, your application does not have access to the raw card number. Setting this flag tells the SDK to retrieve the card number from the component rather than expecting it from your code. Omitting this field causes the payment to fail.
</Warning>

```java theme={"dark"}
public void onPayNowClick(View view) {
    try {
        CFSubsCard cfSubsCard = new CFSubsCard.CFSubsCardBuilder()
                .setCardHolderName(cardHolderName)
                .setCardExpiryMonth(cardMM)
                .setCardExpiryYear(cardYY)
                .setCVV(cardCVV)
                .setCfCard(true) // Required for non-PCI card component integration
                .build();

        CFSubsCardPayment cfCardPayment = new CFSubsCardPayment.CFSubsCardPaymentBuilder()
                .setSubscriptionSession(cfSession)
                .setSubsCard(cfSubsCard)
                .build();

        // doSubscriptionPayment is called on the CFSubsCardNumberView object, not on CFPaymentGatewayService.
        cfSubsCardNumberView.doSubscriptionPayment(YourActivity.this, cfCardPayment);

    } catch (CFException exception) {
        exception.printStackTrace();
    }
}
```

<Note>
  Call `doSubscriptionPayment()` on the `cfSubsCardNumberView` object, not on `CFPaymentGatewayService`. This is different from the standard card integration.
</Note>

#### Sample code

The following example shows a complete custom card component payment flow, including session creation, card component initialisation, optional theme customisation, and payment initiation.

<AccordionGroup>
  <Accordion title="Custom card component payment sample">
    The following method demonstrates a complete non-PCI card payment integration using `CFSubsCardNumberView`:

    ```java theme={"dark"}
    // Declare the card view variable
    private CFSubsCardNumberView cfSubsCardNumberView;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_element_checkout);

        // Initialise the card view reference
        cfSubsCardNumberView = findViewById(R.id.cf_subs_element_card);

        try {
            CFPaymentGatewayService.getInstance().setCheckoutCallback(this);
        } catch (CFException e) {
            e.printStackTrace();
        }

        try {
            CFSubscriptionSession session = new CFSubscriptionSession.CFSubscriptionSessionBuilder()
                    .setSubscriptionId("your-subscription-id")
                    .setSubscriptionSessionID("your-subscription-session-id")
                    .setEnvironment(CFSubscriptionSession.Environment.SANDBOX) // or .PRODUCTION
                    .build();

            cfSubsCardNumberView.initialize(session, new ICardInfo() {
                @Override
                public void onInfo(JSONObject jsonObject) {
                    Log.d("CFCARDVIEW", jsonObject.toString());
                }
            });
        } catch (CFException e) {
            e.printStackTrace();
        }
    }

    public void onElementPayClick(View view) {
        try {
            // Mandatory: build the card object
            CFSubsCard cfSubsCard = new CFSubsCard.CFSubsCardBuilder()
                    .setCardHolderName(cardHolderName)
                    .setCardExpiryMonth(cardMM)
                    .setCardExpiryYear(cardYY)
                    .setCVV(cardCVV)
                    .setCfCard(true) // Required for non-PCI card component integration
                    .build();

            // Optional: apply a custom theme
            CFTheme theme = new CFTheme.CFThemeBuilder()
                    .setNavigationBarBackgroundColor("#6A2222")
                    .setNavigationBarTextColor("#FFFFFF")
                    .setButtonBackgroundColor("#6Aaaaa")
                    .setButtonTextColor("#FFFFFF")
                    .setPrimaryTextColor("#11385b")
                    .setSecondaryTextColor("#808080")
                    .build();

            // Mandatory: build the payment object
            CFSubsCardPayment cfCardPayment = new CFSubsCardPayment.CFSubsCardPaymentBuilder()
                    .setSubscriptionSession(cfSession)
                    .setSubsCard(cfSubsCard)
                    .build();

            // Optional: apply the theme to the payment object
            cfCardPayment.setTheme(theme);

            // Mandatory: initiate payment via the card view object
            cfSubsCardNumberView.doSubscriptionPayment(ElementCheckoutActivity.this, cfCardPayment);

        } catch (CFException exception) {
            exception.printStackTrace();
        }
    }
    ```
  </Accordion>
</AccordionGroup>

For a working end-to-end implementation, refer to the sample integration on GitHub.

<AccordionGroup>
  <Accordion title="Android subscription custom card component sample">
    [GitHub sample](https://github.com/cashfree/nextgen-android/blob/7f1c8d1b9a35b024fadf9901202bba7d06d1bff7/app/src/main/java/com/cashfree/sdk_sample/java/SubscriptionCheckoutActivity.java#L214)
  </Accordion>
</AccordionGroup>

## Step 3: Confirm the payment <Badge>Server-side</Badge>

After the SDK delivers a callback via `onSubscriptionVerify`, confirm the payment status from your backend before taking any action. The SDK callback signals only that the payment flow has ended. It does not guarantee a successful payment.

Use the [Fetch Details of All Payments of a Subscription API](/docs/api-reference/payments/latest/subscription/fetch-details-of-all-payments-of-a-subscription) to retrieve the current payment status.

<AccordionGroup>
  <Accordion title="API request for fetching subscription payments">
    The following request fetches all payments for a subscription:

    ```bash theme={"dark"}
    curl --request GET \
      --url https://api.cashfree.com/pg/subscriptions/{subscription_id}/payments \
      --header 'x-api-version: 2025-01-01' \
      --header 'x-client-id: <your-client-id>' \
      --header 'x-client-secret: <your-client-secret>'
    ```

    A successful response returns an array of payment objects. Check the `payment_status` field to determine the outcome. The API returns the following response on success:

    ```json theme={"dark"}
    [
      {
        "cf_payment_id": "123456",
        "cf_subscription_id": "7891011",
        "payment_id": "your-payment-id",
        "payment_amount": 1,
        "payment_status": "SUCCESS",
        "payment_type": "AUTH",
        "payment_initiated_date": "2025-06-01T22:14:58+0530",
        "subscription_id": "your-subscription-id",
        "retry_attempts": 0,
        "failure_details": {
          "failure_reason": ""
        }
      }
    ]
    ```
  </Accordion>
</AccordionGroup>

<Note>Always verify the subscription status from your backend before delivering goods or services to the customer. Proceed only when `payment_status` is `SUCCESS`.</Note>

## Error codes

If a required field or object is missing when you initiate payment, the SDK returns a `CFException`. The following table lists SDK-level validation errors and when they occur.

<Accordion title="Show error codes">
  The SDK validation errors are grouped by category as follows:

  ### Session errors

  These errors occur when the `CFSubscriptionSession` object or its required fields are not provided.

  | Error code | Message | Description |
  | - | - | - |
  | `SUBSCRIPTION_SESSION_OBJECT_MISSING` | The "CFSubscriptionSession" is missing in the request. | The `CFSubscriptionSession` object was not passed to the payment builder. |
  | `SUBSCRIPTION_SESSION_ID_MISSING` | The "subscription\_session\_id" is missing in the request. | The `subscription_session_id` was not set on the `CFSubscriptionSession` builder. |
  | `SUBSCRIPTION_ID_MISSING` | The "subscription\_id" is missing in the request. | The `subscription_id` was not set on the `CFSubscriptionSession` builder. |
  | `ENVIRONMENT_MISSING` | The "environment" is missing in the request. | The Cashfree environment (`.SANDBOX` or `.PRODUCTION`) was not set on the `CFSubscriptionSession` builder. |

  ### Payment method object errors

  These errors occur when a payment method object is absent or one of its required fields is not set.

  | Error code | Message | Description |
  | - | - | - |
  | `SUBSCRIPTION_CARD_OBJECT_MISSING` | The "CFSubsCard" object is missing in the request. | The `CFSubsCard` object was not passed to the `CFSubsCardPayment` builder. |

  ### Callback errors

  These errors occur when the payment callback is not registered before initiating payment.

  | Error code | Message | Description |
  | - | - | - |
  | `CALLBACK_MISSING` | The "callback" cannot be null. | `setCheckoutCallback` was not called before `doSubscriptionPayment()`. Register the callback in your activity's `onCreate` method before you initiate payment. |
</Accordion>

## Other options

The following optional configurations let you customise the payment screen appearance and enable SDK logging for troubleshooting.

<AccordionGroup>
  <Accordion title="(Optional) Customise the theme">
    Apply a custom theme to the payment screen to match your application's visual design. Use the `CFTheme` builder to set colours for the navigation bar, buttons, and text. Apply the theme to your payment object before you call `doSubscriptionPayment()`.

    The following example sets the available theme properties:

    ```java theme={"dark"}
    CFTheme theme = new CFTheme.CFThemeBuilder()
            .setNavigationBarBackgroundColor("#6A2222") // Sets the status bar and toolbar colour
            .setNavigationBarTextColor("#FFFFFF")        // Sets the toolbar text colour
            .setButtonBackgroundColor("#6Aaaaa")         // Sets the primary button background colour
            .setButtonTextColor("#FFFFFF")               // Sets the primary button text colour
            .setPrimaryTextColor("#11385b")              // Sets the primary text colour
            .setSecondaryTextColor("#808080")            // Sets the secondary text colour
            .build();

    cfCardPayment.setTheme(theme);
    ```
  </Accordion>

  <Accordion title="(Optional) Enable logging to debug issues">
    To enable SDK logging, add the following entry to your `values.xml` file:

    ```xml theme={"dark"}
    <integer name="cashfree_pg_logging_level">3</integer>
    ```

    The following logging levels are available, listed from least to most verbose:

    | Level | Value |
    | - | - |
    | VERBOSE | 2 |
    | DEBUG | 3 |
    | INFO | 4 |
    | WARN | 5 |
    | ERROR | 6 |
    | ASSERT | 7 |
  </Accordion>
</AccordionGroup>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/payments/subscription/custom-checkout/mobile/android-subscription-element">Android Integration (Full Element SDK)</a></li>
    <li><a href="/docs/payments/subscription/create">Create a Subscription</a></li>
    <li><a href="/docs/api-reference/payments/latest/subscription/fetch-details-of-all-payments-of-a-subscription">Fetch Details of All Payments of a Subscription API</a></li>
    <li><a href="/docs/payments/subscription/payment-modes">Supported Payment Methods</a></li>
    <li><a href="https://github.com/cashfree/nextgen-android">Android SDK on GitHub</a></li>
  </ul>
</div>


# iOS Custom Card Component (Non-PCI)
Source: https://www.cashfree.com/docs/payments/subscription/custom-checkout/custom-card/ios-custom-card

Integrate the Cashfree Subscription Custom Card Component into your iOS application to accept subscription payments without handling raw card data.

The Cashfree Subscription Custom Card Component lets you embed a secure, SDK-managed card input field directly into your iOS application UI. The `CFSubsCardComponent` captures and processes the card number entirely within the SDK. Your application never receives the raw card number.

This integration is suitable for non-PCI merchants. A non-PCI merchant is not certified to store, process, or transmit raw cardholder data and relies on the SDK to handle card data securely on their behalf.

The component provides auto-formatted card number input (groups of four digits), real-time card network detection with icon display, Luhn validation on every keystroke, and automatic BIN lookup after eight digits. Metadata is delivered through `CFSubsCardListener`. You receive only digit count, Luhn result, and BIN info, not the raw card number.

<Note>
  This page covers the custom card component integration only. For the full iOS Subscription Element integration, including UPI and eNach (net banking), see [iOS Integration](/docs/payments/subscription/custom-checkout/mobile/ios-subscription-element).
</Note>

<Note>
  For merchants with raw card access (PCI-DSS certified), use `.setCardNumber()` on `CFCardSubs.CFCardSubsBuilder()` directly instead of `CFSubsCardComponent`. That path follows the standard subscription card flow.
</Note>

## Prerequisites

Complete the following tasks before you start the integration:

* Create a [Cashfree Merchant Account](https://merchant.cashfree.com/merchants/signup).
* Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and generate an **App ID** and **Secret Key**. Learn how to [generate API keys](/docs/api-reference/authentication#generate-api-keys).
* Use Cashfree iOS SDK version **2.4.0** or above.
* Set your application's minimum deployment target to **iOS 13.0** or higher.

The integration consists of three steps:

<CardGroup>
  <Card title="Step 1" icon="money-bill-wave" href="/docs/payments/subscription/custom-checkout/custom-card/ios-custom-card#step-1-create-a-subscription-server-side">
    Create a subscription
  </Card>

  <Card title="Step 2" icon="desktop" href="/docs/payments/subscription/custom-checkout/custom-card/ios-custom-card#step-2-open-the-payment-page-client-side">
    Open the payment page
  </Card>

  <Card title="Step 3" icon="circle-check" href="/docs/payments/subscription/custom-checkout/custom-card/ios-custom-card#step-3-confirm-the-payment-server-side">
    Confirm the payment
  </Card>
</CardGroup>

## Step 1: Create a subscription <Badge>Server-side</Badge>

Create a subscription from your backend server before you process any payment.

<Note>This API requires your secret key. Create subscriptions through your server only. Do not call this API directly from your mobile application.</Note>

After the subscription is created, your backend receives a `subscription_id` and a `subscription_session_id`. Pass both values to your iOS client to proceed with the payment.

<AccordionGroup>
  <Accordion title="API request for creating a subscription">
    The following example shows how to create a subscription using the Create Subscription API:

    <CodeGroup>
      ```bash cURL theme={"dark"}
      curl --request POST \
        --url https://sandbox.cashfree.com/pg/subscriptions \
        --header 'Content-Type: application/json' \
        --header 'x-api-version: 2025-01-01' \
        --header 'x-client-id: <your-client-id>' \
        --header 'x-client-secret: <your-client-secret>' \
        --data '{
          "subscription_id": "Demo_Subscription",
          "customer_details": {
            "customer_name": "john",
            "customer_email": "john@dummy.com",
            "customer_phone": "9908730221",
            "customer_bank_account_number": "59108290701802",
            "customer_bank_ifsc": "HDFC0002614",
            "customer_bank_code": "HDFC",
            "customer_bank_account_type": "SAVINGS"
          },
          "plan_details": {
            "plan_name": "plan12345",
            "plan_type": "PERIODIC",
            "plan_amount": 10,
            "plan_max_amount": 100,
            "plan_max_cycles": 100,
            "plan_intervals": 2,
            "plan_currency": "INR",
            "plan_interval_type": "WEEK",
            "plan_note": "Bi-weekly INR 10 plan"
          },
          "authorization_details": {
            "authorization_amount": 100,
            "authorization_amount_refund": true,
            "payment_methods": [
              "card"
            ]
          },
          "subscription_meta": {
            "return_url": "https://example.com/subscription/return",
            "notification_channel": [
              "EMAIL",
              "SMS"
            ],
            "session_id_expiry": "2025-06-01T23:00:08+05:30"
          },
          "subscription_expiry_time": "2100-01-01T23:00:08+05:30",
          "subscription_first_charge_time": "2025-06-01T23:00:08+05:30",
          "subscription_tags": {
            "psp_note": "Monthly subscription payment"
          }
        }'
      ```

      ```javascript Node theme={"dark"}
      // Creating a subscription using the Cashfree Node SDK
      // https://github.com/cashfree/cashfree-pg-sdk-nodejs
      ```

      ```java Java theme={"dark"}
      // Creating a subscription using the Cashfree Java SDK
      // https://github.com/cashfree/cashfree-pg-sdk-java
      ```

      ```go Golang theme={"dark"}
      // Creating a subscription using the Cashfree Go SDK
      // https://github.com/cashfree/cashfree-pg
      ```

      ```csharp .NET theme={"dark"}
      // Creating a subscription using the Cashfree .NET SDK
      // https://github.com/cashfree/cashfree-pg-sdk-dotnet
      ```

      ```python Python theme={"dark"}
      // Creating a subscription using the Cashfree Python SDK
      // https://github.com/cashfree/cashfree-pg-sdk-python
      ```

      ```php PHP theme={"dark"}
      // Creating a subscription using the Cashfree PHP SDK
      // https://github.com/cashfree/cashfree-pg-sdk-php
      ```
    </CodeGroup>

    A successful response returns the `subscription_id` and `subscription_session_id`. Use these values to build the `CFSubscriptionSession` object in [Step 2](#step-2-open-the-payment-page-client-side). The API returns the following response on success:

    ```json theme={"dark"}
    {
      "subscription_id": "Demo_Subscription",
      "subscription_session_id": "subs_token_tc9JCN4MzUIJ",
      "subscription_status": "INITIALIZED",
      "cf_subscription_id": "4"
    }
    ```

    For the full list of request parameters and response fields, see the [Create Subscription API](/docs/api-reference/payments/latest/subscription/create-subscription).
  </Accordion>
</AccordionGroup>

## Step 2: Open the payment page <Badge>Client-side</Badge>

After you create the subscription, set up the card component and open the payment page so the customer can provide their card details.

### 1. Set up the SDK

The Cashfree iOS SDK is available via CocoaPods. The integration requires version **2.4.0** or above and iOS **13.0** or higher.

Add the following to your `Podfile`:

```ruby theme={"dark"}
platform :ios, '13.0'

target 'YourAppTarget' do
  use_frameworks!
  pod 'CashfreePG', '2.4.0'
end
```

Run `pod install` to install the dependency.

### 2. Complete the payment

To complete the payment, follow these steps:

1. Add the `CFSubsCardComponent` to your view.
2. Initialise the card component after the session is ready.
3. Create a `CFSubscriptionSession` object.
4. Conform to `CFSubsCardListener` to receive card metadata.
5. Set up the payment callback.
6. Build the payment object and initiate the payment.

#### Add the card component to your view

`CFSubsCardComponent` is a `UIView` that you can add in Interface Builder or programmatically. In Interface Builder, set the custom class of a `UIView` to `CFSubsCardComponent` and connect it as an outlet:

```swift theme={"dark"}
@IBOutlet weak var cfCardComponent: CFSubsCardComponent!
```

Apply standard `UIView` styling as needed:

```swift theme={"dark"}
cfCardComponent.layer.borderColor = UIColor.systemGray4.cgColor
cfCardComponent.layer.borderWidth = 1.0
cfCardComponent.layer.cornerRadius = 8.0
```

The component manages only the card number field. Collect cardholder name, expiry month, expiry year, and CVV in separate input fields in your checkout UI.

#### Initialise the card component

Call `initializeCardComponent` only after you have a valid `CFSubscriptionSession`. The component uses the session to authenticate BIN lookup requests.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `session` | `CFSubscriptionSession` | Yes | Session from your backend. |
| `card_listener` | `CFSubsCardListener` | Yes | Receives metadata on every keystroke. |
| `hint_text` | `String` | Yes | Placeholder text. Pass `""` for the default `XXXX XXXX XXXX XXXX` format. |
| `font` | `UIFont?` | No | Custom font. Pass `nil` for the system default. |
| `textColor` | `UIColor?` | No | Text colour. Pass `nil` for the system default. |
| `enable_pasting` | `Bool` | Yes | Whether the user can paste from the clipboard. |

The following example initialises the component with custom font and text colour:

```swift theme={"dark"}
cfCardComponent.initializeCardComponent(
    session: subsSession,
    card_listener: self,
    hint_text: "",
    font: UIFont.systemFont(ofSize: 16),
    textColor: UIColor.label,
    enable_pasting: false
)
```

#### Create a session

The `CFSubscriptionSession` object holds the session context for the payment. It accepts the `subscription_session_id` and `subscription_id` obtained from [Step 1](#step-1-create-a-subscription-server-side), and the Cashfree environment (`.SANDBOX` or `.PRODUCTION`).

Set the environment to `.SANDBOX` for testing or `.PRODUCTION` for live payments. The following example shows how to create the session object:

```swift theme={"dark"}
do {
    let subsSession = try CFSubscriptionSession.CFSubscriptionSessionBuilder()
        .setSubscriptionId("your_subscription_id")
        .setSubscriptionSessionId("your_subscription_session_id")
        .setEnvironment(.SANDBOX) // or .PRODUCTION
        .build()
} catch {
    print(error.localizedDescription)
}
```

#### Set up the CFSubsCardListener callback

Conform your view controller to `CFSubsCardListener` and implement `cardMetaData(card_listener_response:)`. This callback fires on every keystroke and again after the BIN lookup completes.

```swift theme={"dark"}
class CheckoutViewController: UIViewController, CFSubsCardListener {

    func cardMetaData(card_listener_response: CFSubsCardListenerResponse) {
        let charCount = card_listener_response.numberOfCharacters ?? 0
        let meta = card_listener_response.meta_data ?? [:]

        let isLuhnValid = meta["luhn_check"] as? Bool ?? false
        let binInfo = meta["card_bin_info"] as? [String: Any]

        // Enable Pay button when the card number is complete and valid
        payButton.isEnabled = (charCount == 16 && isLuhnValid)

        if let scheme = binInfo?["card_scheme"] as? String {
            print("Card scheme: \(scheme)")
        }
    }
}
```

The callback delivers a `CFSubsCardListenerResponse` with the following top-level fields:

| Field | Type | Description |
| - | - | - |
| `numberOfCharacters` | `Int?` | Number of digits entered in the card component (spaces excluded). |
| `message` | `String?` | Informational message about the response. |
| `type` | `String?` | Always `"card_info"`. |
| `meta_data` | `[String: Any]?` | Contains card validation and BIN data (see below). |

The `meta_data` dictionary contains the following keys:

| Key | Type | Description |
| - | - | - |
| `card_length` | `Int` | Same as `numberOfCharacters`; total digits entered. |
| `luhn_check` | `Bool` | `true` if the entered card number passes the Luhn algorithm; `false` otherwise. |
| `card_bin_info` | `[String: Any]` | Populated once 8 digits are entered. Contains BIN lookup data from the server. `nil` if fewer than 8 digits are entered. |

<Warning>
  The `card_bin_info` object is only present in the callback after the customer has entered at least 8 digits. Always check that the key exists in `meta_data` before accessing it.
</Warning>

After 8 digits are entered, the component calls the Cashfree BIN API automatically. The response is delivered in `meta_data["card_bin_info"]` on the next `cardMetaData` callback. No additional setup is required. Authentication uses the `x-sub-session-id` from the session provided at initialisation.

The `card_bin_info` dictionary returned from the BIN lookup API contains the following fields:

| Field | Description |
| - | - |
| `Card_bin` | Bank Identification Number. |
| `logo` | Card network logo reference. |
| `sub_type` | Card sub-type classification. |
| `type` | Card type classification. |
| `schema` | Card network schema. |
| `brand` | Card brand classification. |
| `bank name` | Issuing bank name. |

The component auto-detects the following card networks and displays the corresponding icon: Visa, Mastercard, American Express (Amex), RuPay, Diners Club, Discover, and JCB.

The following example illustrates how callback data evolves as the customer enters their card number:

```json theme={"dark"}
// After the 1st digit
{"card_length": 1, "luhn_check": false}

// After the 8th digit — card_bin_info becomes available
{
  "card_length": 8,
  "luhn_check": false,
  "card_bin_info": {
    "card_scheme": "visa",
    "type": "filtered",
    "sub_type": "filtered",
    "brand": "filtered",
    "bank name": "axis bank"
  }
}

// After all 16 digits, luhn_check passes
{
  "card_length": 16,
  "luhn_check": true,
  "card_bin_info": {
    "card_scheme": "visa",
    "type": "filtered",
    "sub_type": "filtered",
    "brand": "filtered",
    "bank name": "axis bank"
  }
}
```

#### Set up the payment callback

The SDK exposes the `CFResponseDelegate` protocol to receive callbacks when the subscription payment journey ends. This protocol consists of two methods:

```swift theme={"dark"}
func onError(_ error: CFErrorResponse, order_id: String)
func verifyPayment(order_id: String)
```

<Tip>Register the callback on `CFPaymentGatewayService` before you call `doSubsPayment`. Set `paymentService.setCallback(self)` in your view controller before initiating payment.</Tip>

The following example shows how to implement the callback:

```swift theme={"dark"}
extension CheckoutViewController: CFResponseDelegate {

    func onError(_ error: CFErrorResponse, order_id: String) {
        print("Error: \(error.message ?? "")")
        // Show error to user
    }

    func verifyPayment(order_id: String) {
        print("Flow complete. Verify order: \(order_id)")
        // Verify subscription status from your backend before proceeding.
    }
}
```

<Warning>
  Backend verification is mandatory. The SDK signals that the payment UI flow ended, not that payment succeeded. Always verify payment status from your backend before presenting success.
</Warning>

#### Build the payment object and initiate payment

When the customer fills in their card details and taps the pay button, build the `CFCardSubs` and `CFCardSubsPayment` objects and call `doSubsPayment()` on `CFPaymentGatewayService`.

<Warning>
  You must call `.setCardComponent(cfCardComponent)` on the `CFCardSubs` builder. Because the SDK manages the card number internally via `CFSubsCardComponent`, your application does not have access to the raw card number. `.setCardComponent()` and `.setCardNumber()` are mutually exclusive. Never call both. Omitting `.setCardComponent()` or calling `.setCardNumber()` alongside it causes the payment to fail.
</Warning>

The `CFCardSubs.CFCardSubsBuilder()` supports the following methods:

| Method | Required | Description |
| - | - | - |
| `.setChannel(_ channel: String)` | Yes (default: `"link"`) | Payment flow type. |
| `.setCardComponent(_ component: CFSubsCardComponent)` | Yes | Component reference; replaces `.setCardNumber()`. |
| `.setCardHolderName(_ name: String)` | No | Cardholder name. |
| `.setCardExpiryMonth(_ month: String)` | Yes | Expiry month in `"MM"` format. |
| `.setCardExpiryYear(_ year: String)` | Yes | Expiry year in `"YY"` format. |
| `.setCVV(_ cvv: String)` | Yes | Card CVV. |

```swift theme={"dark"}
@IBAction func payButtonTapped(_ sender: Any) {
    do {
        let card = try CFCardSubs.CFCardSubsBuilder()
            .setChannel("link")
            .setCardComponent(cfCardComponent)
            .setCardExpiryMonth(expiryMonthField.text ?? "")
            .setCardExpiryYear(expiryYearField.text ?? "")
            .setCardHolderName(cardHolderNameField.text ?? "")
            .setCVV(cvvField.text ?? "")
            .build()

        let payment = try CFCardSubsPayment.CFCardPaymentSubsBuilder()
            .setCard(card)
            .setSession(subsSession)
            .build()

        let paymentService = CFPaymentGatewayService.getInstance()
        paymentService.setCallback(self)
        try paymentService.doSubsPayment(payment, viewController: self)

    } catch {
        print(error.localizedDescription)
    }
}
```

<Note>
  There is no public API to read the card number out of `CFSubsCardComponent`. The SDK uses it securely when `doSubsPayment` is called.
</Note>

#### Sample code

The following example shows a complete custom card component payment flow, including session creation, card component initialisation, metadata handling, and payment initiation.

<AccordionGroup>
  <Accordion title="Custom card component payment sample">
    The following example demonstrates a complete non-PCI card payment integration using `CFSubsCardComponent`:

    ```swift theme={"dark"}
    class CheckoutViewController: UIViewController, CFSubsCardListener, CFResponseDelegate {

        @IBOutlet weak var cfCardComponent: CFSubsCardComponent!
        @IBOutlet weak var payButton: UIButton!

        private var subsSession: CFSubscriptionSession!

        override func viewDidLoad() {
            super.viewDidLoad()

            cfCardComponent.layer.borderColor = UIColor.systemGray4.cgColor
            cfCardComponent.layer.borderWidth = 1.0
            cfCardComponent.layer.cornerRadius = 8.0

            do {
                subsSession = try CFSubscriptionSession.CFSubscriptionSessionBuilder()
                    .setSubscriptionId("your_subscription_id")
                    .setSubscriptionSessionId("your_subscription_session_id")
                    .setEnvironment(.SANDBOX) // or .PRODUCTION
                    .build()

                cfCardComponent.initializeCardComponent(
                    session: subsSession,
                    card_listener: self,
                    hint_text: "",
                    font: UIFont.systemFont(ofSize: 16),
                    textColor: UIColor.label,
                    enable_pasting: false
                )

                let paymentService = CFPaymentGatewayService.getInstance()
                paymentService.setCallback(self)

            } catch {
                print(error.localizedDescription)
            }
        }

        func cardMetaData(card_listener_response: CFSubsCardListenerResponse) {
            let charCount = card_listener_response.numberOfCharacters ?? 0
            let meta = card_listener_response.meta_data ?? [:]
            let isLuhnValid = meta["luhn_check"] as? Bool ?? false
            payButton.isEnabled = (charCount == 16 && isLuhnValid)
        }

        @IBAction func payButtonTapped(_ sender: Any) {
            do {
                let card = try CFCardSubs.CFCardSubsBuilder()
                    .setChannel("link")
                    .setCardComponent(cfCardComponent)
                    .setCardExpiryMonth(expiryMonthField.text ?? "")
                    .setCardExpiryYear(expiryYearField.text ?? "")
                    .setCardHolderName(cardHolderNameField.text ?? "")
                    .setCVV(cvvField.text ?? "")
                    .build()

                let payment = try CFCardSubsPayment.CFCardPaymentSubsBuilder()
                    .setCard(card)
                    .setSession(subsSession)
                    .build()

                let paymentService = CFPaymentGatewayService.getInstance()
                try paymentService.doSubsPayment(payment, viewController: self)

            } catch {
                print(error.localizedDescription)
            }
        }

        func onError(_ error: CFErrorResponse, order_id: String) {
            print("Error: \(error.message ?? "")")
        }

        func verifyPayment(order_id: String) {
            print("Flow complete. Verify order: \(order_id)")
        }
    }
    ```
  </Accordion>
</AccordionGroup>

For a working end-to-end implementation, refer to the sample integration on GitHub.

<AccordionGroup>
  <Accordion title="iOS subscription custom card component sample">
    [iOS SDK on GitHub](https://github.com/cashfree/core-ios-sdk)
  </Accordion>
</AccordionGroup>

## Step 3: Confirm the payment <Badge>Server-side</Badge>

After the SDK delivers a callback via `verifyPayment`, confirm the payment status from your backend before taking any action. The SDK callback signals only that the payment flow has ended. It does not guarantee a successful payment.

Use the [Fetch Details of All Payments of a Subscription API](/docs/api-reference/payments/latest/subscription/fetch-details-of-all-payments-of-a-subscription) to retrieve the current payment status.

<AccordionGroup>
  <Accordion title="API request for fetching subscription payments">
    The following request fetches all payments for a subscription:

    ```bash theme={"dark"}
    curl --request GET \
      --url https://api.cashfree.com/pg/subscriptions/{subscription_id}/payments \
      --header 'x-api-version: 2025-01-01' \
      --header 'x-client-id: <your-client-id>' \
      --header 'x-client-secret: <your-client-secret>'
    ```

    A successful response returns an array of payment objects. Check the `payment_status` field to determine the outcome. The API returns the following response on success:

    ```json theme={"dark"}
    [
      {
        "cf_payment_id": "123456",
        "cf_subscription_id": "7891011",
        "payment_id": "your-payment-id",
        "payment_amount": 1,
        "payment_status": "SUCCESS",
        "payment_type": "AUTH",
        "payment_initiated_date": "2025-06-01T22:14:58+0530",
        "subscription_id": "your-subscription-id",
        "retry_attempts": 0,
        "failure_details": {
          "failure_reason": ""
        }
      }
    ]
    ```
  </Accordion>
</AccordionGroup>

<Note>Always verify the subscription status from your backend before delivering goods or services to the customer. Proceed only when `payment_status` is `SUCCESS`.</Note>

## Error codes

If a required field or object is missing when you initiate payment, the SDK returns an error through the `catch` block or `onError` callback. The following table lists common SDK-level validation errors and when they occur.

<Accordion title="Show error codes">
  The SDK validation errors are grouped by category as follows:

  ### Session errors

  These errors occur when the `CFSubscriptionSession` object or its required fields are not provided.

  | Error code | Message | Description |
  | - | - | - |
  | `SUBSCRIPTION_SESSION_OBJECT_MISSING` | The "CFSubscriptionSession" is missing in the request. | The `CFSubscriptionSession` object was not passed to the payment builder. |
  | `SUBSCRIPTION_SESSION_ID_MISSING` | The "subscription\_session\_id" is missing in the request. | The `subscription_session_id` was not set on the `CFSubscriptionSession` builder. |
  | `SUBSCRIPTION_ID_MISSING` | The "subscription\_id" is missing in the request. | The `subscription_id` was not set on the `CFSubscriptionSession` builder. |
  | `ENVIRONMENT_MISSING` | The "environment" is missing in the request. | The Cashfree environment (`.SANDBOX` or `.PRODUCTION`) was not set on the `CFSubscriptionSession` builder. |

  ### Payment method object errors

  These errors occur when a payment method object is absent or one of its required fields is not set.

  | Error code | Message | Description |
  | - | - | - |
  | `SUBSCRIPTION_CARD_OBJECT_MISSING` | The "CFCardSubs" object is missing in the request. | The `CFCardSubs` object was not passed to the `CFCardSubsPayment` builder. |

  ### Callback errors

  These errors occur when the payment callback is not registered before initiating payment.

  | Error code | Message | Description |
  | - | - | - |
  | `CALLBACK_MISSING` | The "callback" cannot be null. | `setCallback` was not called on `CFPaymentGatewayService` before `doSubsPayment()`. Register the callback before you initiate payment. |
</Accordion>

## Other options

The following optional configurations let you customise the payment screen behaviour.

<AccordionGroup>
  <Accordion title="(Optional) Enable full-screen payment">
    To present the payment flow in full screen, call `setFullScreen(true)` on the payment object before you call `doSubsPayment()`:

    ```swift theme={"dark"}
    payment.setFullScreen(true)
    ```
  </Accordion>
</AccordionGroup>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/payments/subscription/custom-checkout/mobile/ios-subscription-element">iOS Integration (Full Element SDK)</a></li>
    <li><a href="/docs/payments/subscription/create">Create a Subscription</a></li>
    <li><a href="/docs/api-reference/payments/latest/subscription/fetch-details-of-all-payments-of-a-subscription">Fetch Details of All Payments of a Subscription API</a></li>
    <li><a href="/docs/payments/subscription/payment-modes">Supported Payment Methods</a></li>
    <li><a href="https://github.com/cashfree/core-ios-sdk">iOS SDK on GitHub</a></li>
  </ul>
</div>


# Android Subscription Integration
Source: https://www.cashfree.com/docs/payments/subscription/custom-checkout/mobile/android-subscription-element

Integrate the Cashfree Subscription Element SDK into your Android application to accept subscription payments via card, UPI Intent, and eNach (net banking).

The Cashfree Subscription Element SDK lets you build a fully custom subscription payment experience within your Android application. Unlike the hosted checkout, you collect payment details directly in your own UI and pass them to the SDK, giving you complete control over the look and feel of your payment flow.

The SDK supports three payment methods for subscriptions: card, UPI Intent, and eNach (electronic National Automated Clearing House, also known as net banking).

## Prerequisites

Complete the following tasks before you start the integration:

* Create a [Cashfree Merchant Account](https://merchant.cashfree.com/merchants/signup).
* Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and generate an **App ID** and **Secret Key**. Learn how to [generate API keys](/docs/api-reference/authentication#generate-api-keys).
* Set your application's `minSdkVersion` to API level 19 or higher.

The integration consists of three steps:

<CardGroup>
  <Card title="Step 1" icon="money-bill-wave" href="/docs/payments/subscription/custom-checkout/mobile/android-subscription-element#step-1-create-a-subscription-server-side">
    Create a subscription
  </Card>

  <Card title="Step 2" icon="desktop" href="/docs/payments/subscription/custom-checkout/mobile/android-subscription-element#step-2-open-the-payment-page-client-side">
    Open the payment page
  </Card>

  <Card title="Step 3" icon="circle-check" href="/docs/payments/subscription/custom-checkout/mobile/android-subscription-element#step-3-confirm-the-payment-server-side">
    Confirm the payment
  </Card>
</CardGroup>

## Step 1: Create a subscription <Badge>Server-side</Badge>

Create a subscription from your backend server before you process any payment.

<Note>This API requires your secret key. Create subscriptions through your server only — do not call this API directly from your mobile application.</Note>

After the subscription is created, your backend receives a `subscription_id` and a `subscription_session_id`. Pass both values to your Android client to proceed with the payment.

<AccordionGroup>
  <Accordion title="API request for creating a subscription">
    The following example shows how to create a subscription using the Create Subscription API:

    <CodeGroup>
      ```bash cURL theme={"dark"}
      curl --request POST \
        --url https://sandbox.cashfree.com/pg/subscriptions \
        --header 'Content-Type: application/json' \
        --header 'x-api-version: 2025-01-01' \
        --header 'x-client-id: <your-client-id>' \
        --header 'x-client-secret: <your-client-secret>' \
        --data '{
          "subscription_id": "Demo_Subscription",
          "customer_details": {
            "customer_name": "john",
            "customer_email": "john@dummy.com",
            "customer_phone": "9908730221",
            "customer_bank_account_number": "59108290701802",
            "customer_bank_ifsc": "HDFC0002614",
            "customer_bank_code": "HDFC",
            "customer_bank_account_type": "SAVINGS"
          },
          "plan_details": {
            "plan_name": "plan12345",
            "plan_type": "PERIODIC",
            "plan_amount": 10,
            "plan_max_amount": 100,
            "plan_max_cycles": 100,
            "plan_intervals": 2,
            "plan_currency": "INR",
            "plan_interval_type": "WEEK",
            "plan_note": "Bi-weekly INR 10 plan"
          },
          "authorization_details": {
            "authorization_amount": 100,
            "authorization_amount_refund": true,
            "payment_methods": [
              "enach",
              "upi",
              "card"
            ]
          },
          "subscription_meta": {
            "return_url": "https://example.com/subscription/return",
            "notification_channel": [
              "EMAIL",
              "SMS"
            ],
            "session_id_expiry": "2025-06-01T23:00:08+05:30"
          },
          "subscription_expiry_time": "2100-01-01T23:00:08+05:30",
          "subscription_first_charge_time": "2025-06-01T23:00:08+05:30",
          "subscription_tags": {
            "psp_note": "Monthly subscription payment"
          }
        }'
      ```

      ```javascript Node theme={"dark"}
      // Creating a subscription using the Cashfree Node SDK
      // https://github.com/cashfree/cashfree-pg-sdk-nodejs
      ```

      ```java Java theme={"dark"}
      // Creating a subscription using the Cashfree Java SDK
      // https://github.com/cashfree/cashfree-pg-sdk-java
      ```

      ```go Golang theme={"dark"}
      // Creating a subscription using the Cashfree Go SDK
      // https://github.com/cashfree/cashfree-pg
      ```

      ```csharp .NET theme={"dark"}
      // Creating a subscription using the Cashfree .NET SDK
      // https://github.com/cashfree/cashfree-pg-sdk-dotnet
      ```

      ```python Python theme={"dark"}
      // Creating a subscription using the Cashfree Python SDK
      // https://github.com/cashfree/cashfree-pg-sdk-python
      ```

      ```php PHP theme={"dark"}
      // Creating a subscription using the Cashfree PHP SDK
      // https://github.com/cashfree/cashfree-pg-sdk-php
      ```
    </CodeGroup>

    A successful response returns the `subscription_id` and `subscription_session_id`. Use these values to build the `CFSubscriptionSession` object in [Step 2](#step-2-open-the-payment-page-client-side). The API returns the following response on success:

    ```json theme={"dark"}
    {
      "subscription_id": "Demo_Subscription",
      "subscription_session_id": "subs_token_tc9JCN4MzUIJ",
      "subscription_status": "INITIALIZED",
      "cf_subscription_id": "4"
    }
    ```

    For the full list of request parameters and response fields, see the [Create Subscription API](/docs/api-reference/payments/latest/subscription/create-subscription).
  </Accordion>
</AccordionGroup>

## Step 2: Open the payment page <Badge>Client-side</Badge>

After you create the subscription, open the payment page so the customer can provide payment details.

### 1. Set up the SDK

The Cashfree Android SDK is available on Maven Central. The latest version is [2.4.0](https://github.com/cashfree/nextgen-android). The SDK requires Android API level 19 or higher.

Add the following dependency to your app-level `build.gradle` file:

```gradle theme={"dark"}
implementation 'com.cashfree.pg:api:2.4.0'
```

#### Android configuration

Add the following entry inside the `<application>` tag in your Android manifest file. If you do not enable the `cashfree_subscription_flow_enable` flag, the SDK will not provide a payment callback.

<Note>Add this entry inside the `<application>` tag, not inside the `<activity>` tag.</Note>

```xml theme={"dark"}
<application
    android:icon="@mipmap/ic_launcher"
    android:label="@string/app_name">

    <meta-data
        android:name="cashfree_subscription_flow_enable"
        android:value="true"
        tools:replace="android:value"/>
</application>
```

### 2. Select a payment method

The Subscription Element SDK supports the following payment methods:

<Tabs>
  <Tab title="Card">
    In this flow, the customer enters their card details directly in your application UI. The SDK securely processes the card payment and initiates the subscription mandate.
  </Tab>

  <Tab title="UPI Intent">
    In this flow, the SDK launches the customer's selected UPI app to authorise the subscription mandate. You pass the package name of the installed UPI PSP (payment service provider) application to identify the app to launch.
  </Tab>

  <Tab title="eNach (net banking)">
    In this flow, the customer authorises the subscription mandate through one of three methods: Aadhaar OTP, debit card, or net banking. You specify the preferred authorisation mode when building the payment object.
  </Tab>
</Tabs>

### 3. Complete the payment

To complete the payment, follow these steps:

1. Create a `CFSubscriptionSession` object.
2. Create the payment object for the selected payment method.
3. Set up the subscription callback.
4. Initiate the payment using `doSubscriptionPayment()`.

#### Create a session

The `CFSubscriptionSession` object holds the session context for the payment. It accepts the `subscription_session_id` and `subscription_id` obtained from [Step 1](#step-1-create-a-subscription-server-side), and the Cashfree environment (`.SANDBOX` or `.PRODUCTION`).

Set `Environment` to `.SANDBOX` for testing or `.PRODUCTION` for live payments. The following example shows how to create the session object:

```java theme={"dark"}
CFSubscriptionSession.Environment cfEnvironment = CFSubscriptionSession.Environment.SANDBOX; // or .PRODUCTION

CFSubscriptionSession cfSession = new CFSubscriptionSession.CFSubscriptionSessionBuilder()
        .setEnvironment(cfEnvironment)
        .setSubscriptionSessionID(subscription_session_id)
        .setSubscriptionId(subscription_id)
        .build();
```

#### Create a payment object

The SDK provides a dedicated payment builder for each supported payment method. Build only the object that corresponds to the payment method your customer has selected.

<Tabs>
  <Tab title="Card">
    Use the following builders to create a card payment object:

    ```java theme={"dark"}
    CFSubsCard cfCard = new CFSubsCard.CFSubsCardBuilder()
            .setCardHolderName("Kishan")
            .setCardNumber("4011381307299555")
            .setCardExpiryMonth("08")
            .setCardExpiryYear("29")
            .setCVV("950")
            .build();

    CFSubsCardPayment cfCardPayment = new CFSubsCardPayment.CFSubsCardPaymentBuilder()
            .setSubscriptionSession(cfSession)
            .setSubsCard(cfCard)
            .build();
    ```
  </Tab>

  <Tab title="UPI Intent">
    The `setUPIID` field accepts the package name of the UPI PSP application installed on the device (for example, `com.phonepe.app`). This launches the selected UPI app directly to complete the payment.

    ```java theme={"dark"}
    CFSubsUpi cfSubsUpi = new CFSubsUpi.CFSubsUpiBuilder()
            .setMode(CFSubsUpi.Mode.INTENT)
            .setUPIID("com.phonepe.app") // package name of the selected UPI PSP app
            .build();

    CFSubsUpiPayment cfSubsUpiPayment = new CFSubsUpiPayment.CFSubsUpiPaymentBuilder()
            .setSubscriptionSession(cfSession)
            .setSubsUpi(cfSubsUpi)
            .build();
    ```
  </Tab>

  <Tab title="eNach (net banking)">
    The `setAuthMode` field specifies how the customer authorises the mandate. The following values are accepted:

    | Value | Description |
    | - | - |
    | `aadhaar` | The customer authorises the mandate using their Aadhaar number and OTP. |
    | `debit_card` | The customer authorises the mandate using their debit card details. |
    | `net_banking` | The customer authorises the mandate by logging into their net banking portal. |

    The following example shows how to build the net banking payment object:

    ```java theme={"dark"}
    CFSubsNetBanking subsNetBanking = new CFSubsNetBanking.CFSubsNetBankingBuilder()
            .setAccountHolderName("kishan")
            .setAccountBankCode("SBIN")
            .setAccountNumber("9876543210")
            .setAccountType("SAVINGS")
            .setAuthMode("aadhaar") // accepted values: aadhaar, debit_card, net_banking
            .build();

    CFSubsNetBankingPayment cfSubsNetBankingPayment = new CFSubsNetBankingPayment.CFNetBankingPaymentBuilder()
            .setSubscriptionSession(cfSession)
            .setCfSubsNetBanking(subsNetBanking)
            .build();
    ```
  </Tab>
</Tabs>

#### Set up the subscription callback

The SDK exposes the `CFSubscriptionResponseCallback` interface to receive callbacks when the subscription payment journey ends. This interface consists of two methods:

```java theme={"dark"}
public void onSubscriptionVerify(CFSubscriptionResponse response)
public void onSubscriptionFailure(CFErrorResponse cfErrorResponse)
```

<Tip>Register the callback in your activity's `onCreate` method. This configuration also handles activity restarts correctly.</Tip>

The following example shows how to implement the callback in your activity:

```java theme={"dark"}
public class YourActivity extends AppCompatActivity implements CFSubscriptionResponseCallback {

    @Override
    public void onSubscriptionVerify(CFSubscriptionResponse response) {
        // Verify subscription status from your backend before proceeding.
    }

    @Override
    public void onSubscriptionFailure(CFErrorResponse cfErrorResponse) {
        // Handle payment failure. Inspect cfErrorResponse for details.
    }

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_subscription_checkout);
        try {
            // If you are using a fragment, add this line inside onCreate() of your Fragment.
            CFPaymentGatewayService.getInstance().setSubscriptionCheckoutCallback(this);
        } catch (CFException e) {
            e.printStackTrace();
        }
    }
}
```

#### Initiate the payment

Call `doSubscriptionPayment()` to open the payment screen when the customer taps the pay button. The example below uses `cfSubsNetBankingPayment`. Replace it with `cfCardPayment` or `cfSubsUpiPayment` for your selected payment method.

```java theme={"dark"}
// Replace YourActivity with your activity class name.
CFPaymentGatewayService.getInstance().doSubscriptionPayment(YourActivity.this, cfSubsNetBankingPayment);
```

#### Sample code

The following example shows a complete card payment flow, including session creation, payment object setup, optional theme customisation, and payment initiation.

<AccordionGroup>
  <Accordion title="Card payment sample">
    The following method demonstrates a complete card payment integration:

    ```java theme={"dark"}
    private void openCardElementFlow() {
        try {
            CFSubscriptionSession cfSession = new CFSubscriptionSession.CFSubscriptionSessionBuilder()
                    .setEnvironment(cfEnvironment)
                    .setSubscriptionSessionID(subsSessionID)
                    .setSubscriptionId(subsID)
                    .build();

            CFSubsCard cfCard = new CFSubsCard.CFSubsCardBuilder()
                    .setCardHolderName("Kishan")
                    .setCardNumber("4011381307299555")
                    .setCardExpiryMonth("08")
                    .setCardExpiryYear("29")
                    .setCVV("950")
                    .build();

            CFSubsCardPayment cfCardPayment = new CFSubsCardPayment.CFSubsCardPaymentBuilder()
                    .setSubscriptionSession(cfSession)
                    .setSubsCard(cfCard)
                    .build();

            // Optional: apply a custom theme.
            CFTheme theme = new CFTheme.CFThemeBuilder()
                    .setNavigationBarBackgroundColor("#6A2222")
                    .setNavigationBarTextColor("#FFFFFF")
                    .build();
            cfCardPayment.setTheme(theme);

            CFPaymentGatewayService.getInstance().setSubscriptionCheckoutCallback(this);
            CFCorePaymentGatewayService.getInstance().doSubscriptionPayment(this, cfCardPayment);
        } catch (CFException exception) {
            exception.printStackTrace();
        }
    }
    ```
  </Accordion>
</AccordionGroup>

Refer to the sample integration on GitHub for a working end-to-end implementation.

<AccordionGroup>
  <Accordion title="Android Subscription Element integration">
    [GitHub sample](https://github.com/cashfree/nextgen-android/blob/master/app/src/main/java/com/cashfree/sdk_sample/java/SubscriptionCheckoutActivity.java)
  </Accordion>
</AccordionGroup>

## Step 3: Confirm the payment <Badge>Server-side</Badge>

After the SDK delivers a callback via `onSubscriptionVerify`, confirm the payment status from your backend before taking any action. The SDK callback signals only that the payment flow has ended. It does not guarantee a successful payment.

Use the [Fetch Details of All Payments of a Subscription API](/docs/api-reference/payments/latest/subscription/fetch-details-of-all-payments-of-a-subscription) to retrieve the current payment status.

<AccordionGroup>
  <Accordion title="API request for fetching subscription payments">
    The following request fetches all payments for a subscription:

    ```bash theme={"dark"}
    curl --request GET \
      --url https://api.cashfree.com/pg/subscriptions/{subscription_id}/payments \
      --header 'x-api-version: 2025-01-01' \
      --header 'x-client-id: <your-client-id>' \
      --header 'x-client-secret: <your-client-secret>'
    ```

    A successful response returns an array of payment objects. Check the `payment_status` field to determine the outcome. The API returns the following response on success:

    ```json theme={"dark"}
    [
      {
        "cf_payment_id": "123456",
        "cf_subscription_id": "7891011",
        "payment_id": "your-payment-id",
        "payment_amount": 1,
        "payment_status": "SUCCESS",
        "payment_type": "AUTH",
        "payment_initiated_date": "2025-06-01T22:14:58+0530",
        "subscription_id": "your-subscription-id",
        "retry_attempts": 0,
        "failure_details": {
          "failure_reason": ""
        }
      }
    ]
    ```
  </Accordion>
</AccordionGroup>

<Note>Always verify the subscription status from your backend before delivering goods or services to the customer. Proceed only when `payment_status` is `SUCCESS`.</Note>

## Error codes

If a required field or object is missing when you initiate payment, the SDK returns a `CFException`. The following table lists SDK-level validation errors and when they occur.

<Accordion title="Show error codes">
  The SDK validation errors are grouped by category as follows:

  ### Session errors

  These errors occur when the `CFSubscriptionSession` object or its required fields are not provided.

  | Error code | Message | Description |
  | - | - | - |
  | `SUBSCRIPTION_SESSION_OBJECT_MISSING` | The "CFSubscriptionSession" is missing in the request. | The `CFSubscriptionSession` object was not passed to the payment builder. |
  | `SUBSCRIPTION_SESSION_ID_MISSING` | The "subscription\_session\_id" is missing in the request. | The `subscription_session_id` was not set on the `CFSubscriptionSession` builder. |
  | `SUBSCRIPTION_ID_MISSING` | The "subscription\_id" is missing in the request. | The `subscription_id` was not set on the `CFSubscriptionSession` builder. |
  | `ENVIRONMENT_MISSING` | The "environment" is missing in the request. | The Cashfree environment (`.SANDBOX` or `.PRODUCTION`) was not set on the `CFSubscriptionSession` builder. |

  ### Payment method object errors

  These errors occur when a payment method object is absent or one of its required fields is not set.

  | Error code | Message | Description |
  | - | - | - |
  | `SUBSCRIPTION_CARD_OBJECT_MISSING` | The "CFSubsCard" object is missing in the request. | The `CFSubsCard` object was not passed to the `CFSubsCardPayment` builder. |
  | `SUBSCRIPTION_NB_OBJECT_MISSING` | The "CFSubsNetBanking" object is missing in the request. | The `CFSubsNetBanking` object was not passed to the `CFSubsNetBankingPayment` builder. |
  | `SUBSCRIPTION_UPI_OBJECT_MISSING` | The "CFSubsUpi" object is missing in the request. | The `CFSubsUpi` object was not passed to the `CFSubsUpiPayment` builder. |
  | `SUBSCRIPTION_NB_ACCOUNT_HOLDER_NAME_MISSING` | The "account holder name" is missing in the request. | The `setAccountHolderName` field was not set on the `CFSubsNetBanking` builder. |
  | `SUBSCRIPTION_NB_ACCOUNT_NUMBER_MISSING` | The "account number" is missing in the request. | The `setAccountNumber` field was not set on the `CFSubsNetBanking` builder. |
  | `SUBSCRIPTION_NB_BANK_CODE_MISSING` | The "bank code" is missing in the request. | The `setAccountBankCode` field was not set on the `CFSubsNetBanking` builder. |
  | `SUBSCRIPTION_NB_ACCOUNT_TYPE_MISSING` | The "account type" is missing in the request. | The `setAccountType` field was not set on the `CFSubsNetBanking` builder. |
  | `SUBSCRIPTION_NB_AUTH_MODE_MISSING` | The "auth mode" is missing in the request. | The `setAuthMode` field was not set on the `CFSubsNetBanking` builder. |

  ### Callback errors

  These errors occur when the payment callback is not registered before initiating payment.

  | Error code | Message | Description |
  | - | - | - |
  | `CALLBACK_MISSING` | The "callback" cannot be null. | `setSubscriptionCheckoutCallback` was not called before `doSubscriptionPayment()`. Register the callback in your activity's `onCreate` method before you initiate payment. |
</Accordion>

### Other options

The following optional configurations let you customise the payment screen appearance and enable SDK logging for troubleshooting.

<AccordionGroup>
  <Accordion title="(Optional) Customise the theme">
    Apply a custom theme to the payment screen to match your application's visual design. Use the `CFTheme` builder to set the navigation bar background colour and text colour. Apply the theme to your payment object before you call `doSubscriptionPayment()`.

    The following example sets the navigation bar colours:

    ```java theme={"dark"}
    CFTheme theme = new CFTheme.CFThemeBuilder()
            .setNavigationBarBackgroundColor("#6A2222") // sets the status bar and toolbar colour
            .setNavigationBarTextColor("#FFFFFF")        // sets the toolbar text colour
            .build();

    cfSubsNetBankingPayment.setTheme(theme);
    // or: cfCardPayment.setTheme(theme);
    ```
  </Accordion>

  <Accordion title="(Optional) Enable logging to debug issues">
    To enable SDK logging, add the following entry to your `values.xml` file:

    `<integer name="cashfree_pg_logging_level">3</integer>`

    The following logging levels are available, listed from least to most verbose:

    * VERBOSE = 2
    * DEBUG = 3
    * INFO = 4
    * WARN = 5
    * ERROR = 6
    * ASSERT = 7
  </Accordion>
</AccordionGroup>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/payments/subscription/create">Create a Subscription</a></li>
    <li><a href="/docs/api-reference/payments/latest/subscription/fetch-details-of-all-payments-of-a-subscription">Fetch Details of All Payments of a Subscription API</a></li>
    <li><a href="/docs/payments/subscription/payment-modes">Supported Payment Methods</a></li>
    <li><a href="/docs/payments/subscription/charge">Charge a Subscription</a></li>
    <li><a href="https://github.com/cashfree/nextgen-android">Android SDK on GitHub</a></li>
  </ul>
</div>


# Flutter Subscription Integration
Source: https://www.cashfree.com/docs/payments/subscription/custom-checkout/mobile/flutter-subscription-element

Integrate the Cashfree Subscription Element SDK into your Flutter application to accept subscription payments via card, UPI, and eNach on Android and iOS.

The Cashfree Subscription Element SDK lets you build a fully custom subscription payment experience within your Flutter application. Unlike the hosted checkout, you collect payment details directly in your own UI and pass them to the SDK, giving you complete control over the appearance and behaviour of your payment flow.

The SDK supports three payment methods for subscriptions: card, UPI, and eNach (electronic National Automated Clearing House, also known as net banking). It runs on both Android and iOS from a single integration.

## Prerequisites

Complete the following tasks before you start the integration:

* Create a [Cashfree Merchant Account](https://merchant.cashfree.com/merchants/signup).
* Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and generate an **App ID** and **Secret Key**. Learn how to [generate API keys](/docs/api-reference/authentication#generate-api-keys).
* Use Flutter SDK version **2.4.0+52** or above. Get it on [pub.dev](https://pub.dev/packages/flutter_cashfree_pg_sdk).
* Set your Android application's `minSdkVersion` to API level 19 or higher.
* Set your iOS minimum deployment target to 13.0 or higher.

The integration consists of three steps:

<CardGroup>
  <Card title="Step 1" icon="money-bill-wave" href="/docs/payments/subscription/custom-checkout/mobile/flutter-subscription-element#step-1-create-a-subscription-server-side">
    Create a subscription
  </Card>

  <Card title="Step 2" icon="desktop" href="/docs/payments/subscription/custom-checkout/mobile/flutter-subscription-element#step-2-open-the-payment-page-client-side">
    Open the payment page
  </Card>

  <Card title="Step 3" icon="circle-check" href="/docs/payments/subscription/custom-checkout/mobile/flutter-subscription-element#step-3-confirm-the-payment-server-side">
    Confirm the payment
  </Card>
</CardGroup>

## Step 1: Create a subscription <Badge>Server-side</Badge>

Create a subscription from your backend server before you process any payment.

<Note>This API requires your secret key. Create subscriptions through your server only — do not call this API directly from your mobile application.</Note>

After the subscription is created, your backend receives a `subscription_id` and a `subscription_session_id`. Pass both values to your Flutter client to proceed with the payment.

<AccordionGroup>
  <Accordion title="API request for creating a subscription">
    The following example shows how to create a subscription using the Create Subscription API:

    <CodeGroup>
      ```bash cURL theme={"dark"}
      curl --request POST \
        --url https://sandbox.cashfree.com/pg/subscriptions \
        --header 'Content-Type: application/json' \
        --header 'x-api-version: 2025-01-01' \
        --header 'x-client-id: <your-client-id>' \
        --header 'x-client-secret: <your-client-secret>' \
        --data '{
          "subscription_id": "Demo_Subscription",
          "customer_details": {
            "customer_name": "john",
            "customer_email": "john@dummy.com",
            "customer_phone": "9908730221",
            "customer_bank_account_number": "59108290701802",
            "customer_bank_ifsc": "HDFC0002614",
            "customer_bank_code": "HDFC",
            "customer_bank_account_type": "SAVINGS"
          },
          "plan_details": {
            "plan_name": "plan12345",
            "plan_type": "PERIODIC",
            "plan_amount": 10,
            "plan_max_amount": 100,
            "plan_max_cycles": 100,
            "plan_intervals": 2,
            "plan_currency": "INR",
            "plan_interval_type": "WEEK",
            "plan_note": "Bi-weekly INR 10 plan"
          },
          "authorization_details": {
            "authorization_amount": 100,
            "authorization_amount_refund": true,
            "payment_methods": [
              "enach",
              "upi",
              "card"
            ]
          },
          "subscription_meta": {
            "return_url": "https://example.com/subscription/return",
            "notification_channel": [
              "EMAIL",
              "SMS"
            ],
            "session_id_expiry": "2025-06-01T23:00:08+05:30"
          },
          "subscription_expiry_time": "2100-01-01T23:00:08+05:30",
          "subscription_first_charge_time": "2025-06-01T23:00:08+05:30",
          "subscription_tags": {
            "psp_note": "Monthly subscription payment"
          }
        }'
      ```

      ```javascript Node theme={"dark"}
      // Creating a subscription using the Cashfree Node SDK
      // https://github.com/cashfree/cashfree-pg-sdk-nodejs
      ```

      ```java Java theme={"dark"}
      // Creating a subscription using the Cashfree Java SDK
      // https://github.com/cashfree/cashfree-pg-sdk-java
      ```

      ```go Golang theme={"dark"}
      // Creating a subscription using the Cashfree Go SDK
      // https://github.com/cashfree/cashfree-pg
      ```

      ```csharp .NET theme={"dark"}
      // Creating a subscription using the Cashfree .NET SDK
      // https://github.com/cashfree/cashfree-pg-sdk-dotnet
      ```

      ```python Python theme={"dark"}
      // Creating a subscription using the Cashfree Python SDK
      // https://github.com/cashfree/cashfree-pg-sdk-python
      ```

      ```php PHP theme={"dark"}
      // Creating a subscription using the Cashfree PHP SDK
      // https://github.com/cashfree/cashfree-pg-sdk-php
      ```
    </CodeGroup>

    A successful response returns the `subscription_id` and `subscription_session_id`. Use these values to build the `CFSubscriptionSession` object in [Step 2](#step-2-open-the-payment-page-client-side). The API returns the following response on success:

    ```json theme={"dark"}
    {
      "subscription_id": "Demo_Subscription",
      "subscription_session_id": "subs_token_tc9JCN4MzUIJ",
      "subscription_status": "INITIALIZED",
      "cf_subscription_id": "4"
    }
    ```

    For the full list of request parameters and response fields, see the [Create Subscription API](/docs/api-reference/payments/latest/subscription/create-subscription).
  </Accordion>
</AccordionGroup>

## Step 2: Open the payment page <Badge>Client-side</Badge>

After you create the subscription, open the payment page so the customer can provide payment details.

### 1. Set up the SDK

The Flutter SDK is hosted on [pub.dev](https://pub.dev/). You can get the SDK [2.4.0+52](https://pub.dev/packages/flutter_cashfree_pg_sdk). The Flutter SDK supports Android SDK version 19 and above and iOS minimum deployment target of 13.0 and above.

Open your project's `pubspec.yaml` and add the following under dependencies:

```yaml theme={"dark"}
flutter_cashfree_pg_sdk: 2.4.0+52
```

#### Android configuration

Add the following entry inside the `<application>` tag in your Android manifest file. If you do not enable the `cashfree_subscription_flow_enable` flag, the SDK will not provide a payment callback.

<Note>Add this entry inside the `<application>` tag, not inside the `<activity>` tag.</Note>

```xml theme={"dark"}
<application
    android:icon="@mipmap/ic_launcher"
    android:label="@string/app_name">

    <meta-data
        android:name="cashfree_subscription_flow_enable"
        android:value="true"
        tools:replace="android:value"/>
</application>
```

#### iOS configuration

Add the following to your application's `info.plist` file:

```xml theme={"dark"}
<key>LSApplicationQueriesSchemes</key>
<array>
  <string>amazonpay</string>
  <string>upi</string>
  <string>credpay</string>
  <string>bhim</string>
  <string>paytmmp</string>
  <string>phonepe</string>
  <string>tez</string>
  <string>navipay</string>
  <string>mobikwik</string>
  <string>myairtel</string>
  <string>popclubapp</string>
  <string>super</string>
  <string>kiwi</string>
  <string>simplypayupi</string>
  <string>whatsapp</string>
</array>
```

### 2. Select a payment method

The Subscription Element SDK supports the following payment methods:

<Tabs>
  <Tab title="Card">
    In this flow, the customer enters their card details directly in your application UI. The SDK securely processes the card payment and initiates the subscription mandate.
  </Tab>

  <Tab title="UPI">
    In this flow, the SDK launches the customer's selected UPI app to authorise the subscription mandate. You pass the package name of the installed UPI PSP (payment service provider) application to identify the app to launch.
  </Tab>

  <Tab title="eNach (net banking)">
    In this flow, the customer authorises the subscription mandate through one of three methods: Aadhaar OTP, debit card, or net banking. You specify the preferred authorisation mode when building the payment object.
  </Tab>
</Tabs>

### 3. Complete the payment

To complete the payment, follow these steps:

1. Create a `CFSubscriptionSession` object.
2. Create the payment object for the selected payment method.
3. Set up the subscription callback.
4. Initiate the payment using `doPayment()`.

#### Create a session

The `CFSubscriptionSession` object holds the session context for the payment. It accepts the `subscription_session_id` and `subscription_id` obtained from [Step 1](#step-1-create-a-subscription-server-side), and the Cashfree environment (sandbox or production).

The following example shows how to create the session object:

```dart theme={"dark"}
Future<CFSubscriptionSession?> createSubscriptionSession() async {
  try {
    var session = CFSubscriptionSessionBuilder()
        .setEnvironment(environment)
        .setSubscriptionId(subscriptionId)
        .setSubscriptionSessionId(subscriptionSessionId)
        .build();
    return session;
  } on CFException catch (e) {
    print(e.message);
  }
  return null;
}
```

#### Create a payment object

The SDK provides a dedicated payment builder for each supported payment method. Build only the object that corresponds to the payment method your customer has selected.

<Tabs>
  <Tab title="Card">
    Use the following builders to create a card payment object:

    ```dart theme={"dark"}
    var subsCard = CFSubsCardBuilder()
        .setCardNumber(cardNumber)
        .setCardHolderName(cardHolderName)
        .setCardExpiryMM(cardExpiryMM)
        .setCardExpiryYY(cardExpiryYY)
        .setCardCVV(cardCVV)
        .build();

    var subsCardPayment = CFSubsCardPaymentBuilder()
        .setSession(session)
        .setCard(subsCard)
        .build();
    ```
  </Tab>

  <Tab title="UPI">
    The `setUPIID` field accepts the package name of the UPI PSP application installed on the device (for example, `com.phonepe.app`). This launches the selected UPI app directly to complete the payment.

    ```dart theme={"dark"}
    var subsUPI = CFSubsUPIBuilder()
        .setChannel(CFSubsUPIChannel.INTENT)
        .setUPIID(upiAppPackageName) // package name of the selected UPI PSP app
        .build();

    var subsUPIPayment = CFSubsUPIPaymentBuilder()
        .setSession(session)
        .setUPI(subsUPI)
        .build();
    ```
  </Tab>

  <Tab title="eNach (net banking)">
    The `setAuthMode` field specifies how the customer authorises the mandate. The following values are accepted:

    | Value | Description |
    | - | - |
    | `aadhaar` | The customer authorises the mandate using their Aadhaar number and OTP. |
    | `debit_card` | The customer authorises the mandate using their debit card details. |
    | `net_banking` | The customer authorises the mandate by logging into their net banking portal. |

    The following example shows how to build the net banking payment object:

    ```dart theme={"dark"}
    var subsNetbanking = CFSubsNetbankingBuilder()
        .setAuthMode(authMode) // aadhaar, debit_card, or net_banking
        .setAccountHolderName(accountHolderName)
        .setAccountNumber(accountNumber)
        .setAccountType(accountType) // SAVINGS or CURRENT
        .setAccountBankCode(bankCode)
        .build();

    var subsNetbankingPayment = CFSubsNetbankingPaymentBuilder()
        .setSession(session)
        .setNetbanking(subsNetbanking)
        .build();
    ```
  </Tab>
</Tabs>

#### Set up the subscription callback

Register callback handlers to receive the result of the payment journey. The SDK calls `onSubscriptionVerify` when the flow completes and `onSubscriptionFailure` when an error occurs.

<Tip>Register the callback before calling `doPayment()`. Setting it in `initState` ensures it is registered correctly even after widget restarts.</Tip>

```dart theme={"dark"}
void onSubscriptionVerify(String subscriptionId) {
  // Verify subscription status from your backend before proceeding.
  print("Verify Subscription: $subscriptionId");
}

void onSubscriptionFailure(CFErrorResponse errorResponse, String orderId) {
  // Handle payment failure. Inspect errorResponse for details.
  print(errorResponse.getMessage());
}

var cfPaymentGatewayService = CFPaymentGatewayService();

@override
void initState() {
  super.initState();
  cfPaymentGatewayService.setCallback(onSubscriptionVerify, onSubscriptionFailure);
}
```

#### Initiate the payment

Call `doPayment()` to open the payment screen when the customer taps the pay button. Pass the payment object for your selected payment method.

```dart theme={"dark"}
cfPaymentGatewayService.doPayment(subsCardPayment);
// or: cfPaymentGatewayService.doPayment(subsUPIPayment);
// or: cfPaymentGatewayService.doPayment(subsNetbankingPayment);
```

#### Sample code

The following example shows a complete card payment flow, including session creation, callback registration, and payment initiation.

```dart theme={"dark"}
class _MyAppState extends State<MyApp> {

  var cfPaymentGatewayService = CFPaymentGatewayService();

  @override
  void initState() {
    super.initState();
    cfPaymentGatewayService.setCallback(onSubscriptionVerify, onSubscriptionFailure);
  }

  void onSubscriptionVerify(String subscriptionId) {
    print("Verify Subscription: $subscriptionId");
  }

  void onSubscriptionFailure(CFErrorResponse errorResponse, String orderId) {
    print(errorResponse.getMessage());
    print("Error while making payment");
  }

  subsCardPay() async {
    try {
      cfPaymentGatewayService.setCallback(onSubscriptionVerify, onSubscriptionFailure);
      var session = await createSubscriptionSession();
      if (session == null) {
        return;
      }
      var subsCard = CFSubsCardBuilder()
          .setCardNumber(cardNumber)
          .setCardHolderName(cardHolderName)
          .setCardExpiryMM(cardExpiryMM)
          .setCardExpiryYY(cardExpiryYY)
          .setCardCVV(cardCVV)
          .build();
      var subsCardPayment = CFSubsCardPaymentBuilder()
          .setSession(session)
          .setCard(subsCard)
          .build();
      cfPaymentGatewayService.doPayment(subsCardPayment);
    } on CFException catch (e) {
      print(e.message);
    }
  }

  Future<CFSubscriptionSession?> createSubscriptionSession() async {
    try {
      var session = CFSubscriptionSessionBuilder()
          .setEnvironment(environment)
          .setSubscriptionId(subscriptionId)
          .setSubscriptionSessionId(subscriptionSessionId)
          .build();
      return session;
    } on CFException catch (e) {
      print(e.message);
    }
    return null;
  }
}
```

## Step 3: Confirm the payment <Badge>Server-side</Badge>

After the SDK delivers a callback via `onSubscriptionVerify`, confirm the payment status from your backend before taking any action. The SDK callback signals only that the payment flow has ended. It does not guarantee a successful payment.

Use the [Fetch Details of All Payments of a Subscription API](/docs/api-reference/payments/latest/subscription/fetch-details-of-all-payments-of-a-subscription) to retrieve the current payment status.

<AccordionGroup>
  <Accordion title="API request for fetching subscription payments">
    The following request fetches all payments for a subscription:

    ```bash theme={"dark"}
    curl --request GET \
      --url https://api.cashfree.com/pg/subscriptions/{subscription_id}/payments \
      --header 'x-api-version: 2025-01-01' \
      --header 'x-client-id: <your-client-id>' \
      --header 'x-client-secret: <your-client-secret>'
    ```

    A successful response returns an array of payment objects. Check the `payment_status` field to determine the outcome. The API returns the following response on success:

    ```json theme={"dark"}
    [
      {
        "cf_payment_id": "123456",
        "cf_subscription_id": "7891011",
        "payment_id": "your-payment-id",
        "payment_amount": 1,
        "payment_status": "SUCCESS",
        "payment_type": "AUTH",
        "payment_initiated_date": "2025-06-01T22:14:58+0530",
        "subscription_id": "your-subscription-id",
        "retry_attempts": 0,
        "failure_details": {
          "failure_reason": ""
        }
      }
    ]
    ```
  </Accordion>
</AccordionGroup>

<Note>Always verify the subscription status from your backend before delivering goods or services to the customer. Proceed only when `payment_status` is `SUCCESS`.</Note>

## Error codes

If a required field or object is missing when you initiate payment, the SDK throws a `CFException`. The following table lists SDK-level validation errors and when they occur.

<Accordion title="Show error codes">
  The SDK validation errors are grouped by category as follows:

  ### Session errors

  These errors occur when the `CFSubscriptionSession` object or its required fields are not provided.

  | Error code | Message | Description |
  | - | - | - |
  | `SUBSCRIPTION_SESSION_OBJECT_MISSING` | The "CFSubscriptionSession" is missing in the request. | The `CFSubscriptionSession` object was not passed to the payment builder. |
  | `SUBSCRIPTION_SESSION_ID_MISSING` | The "subscription\_session\_id" is missing in the request. | The `subscription_session_id` was not set on the `CFSubscriptionSessionBuilder`. |
  | `SUBSCRIPTION_ID_MISSING` | The "subscription\_id" is missing in the request. | The `subscription_id` was not set on the `CFSubscriptionSessionBuilder`. |
  | `ENVIRONMENT_MISSING` | The "environment" is missing in the request. | The Cashfree environment was not set on the `CFSubscriptionSessionBuilder`. |

  ### Payment method object errors

  These errors occur when a payment method object is absent or one of its required fields is not set.

  | Error code | Message | Description |
  | - | - | - |
  | `SUBSCRIPTION_CARD_OBJECT_MISSING` | The "CFSubsCard" object is missing in the request. | The `CFSubsCard` object was not passed to the `CFSubsCardPaymentBuilder`. |
  | `SUBSCRIPTION_NB_OBJECT_MISSING` | The "CFSubsNetbanking" object is missing in the request. | The `CFSubsNetbanking` object was not passed to the `CFSubsNetbankingPaymentBuilder`. |
  | `SUBSCRIPTION_UPI_OBJECT_MISSING` | The "CFSubsUPI" object is missing in the request. | The `CFSubsUPI` object was not passed to the `CFSubsUPIPaymentBuilder`. |
  | `SUBSCRIPTION_NB_ACCOUNT_HOLDER_NAME_MISSING` | The "account holder name" is missing in the request. | The `setAccountHolderName` field was not set on the `CFSubsNetbankingBuilder`. |
  | `SUBSCRIPTION_NB_ACCOUNT_NUMBER_MISSING` | The "account number" is missing in the request. | The `setAccountNumber` field was not set on the `CFSubsNetbankingBuilder`. |
  | `SUBSCRIPTION_NB_BANK_CODE_MISSING` | The "bank code" is missing in the request. | The `setAccountBankCode` field was not set on the `CFSubsNetbankingBuilder`. |
  | `SUBSCRIPTION_NB_ACCOUNT_TYPE_MISSING` | The "account type" is missing in the request. | The `setAccountType` field was not set on the `CFSubsNetbankingBuilder`. |
  | `SUBSCRIPTION_NB_AUTH_MODE_MISSING` | The "auth mode" is missing in the request. | The `setAuthMode` field was not set on the `CFSubsNetbankingBuilder`. |

  ### Callback errors

  These errors occur when the payment callback is not registered before initiating payment.

  | Error code | Message | Description |
  | - | - | - |
  | `CALLBACK_MISSING` | The "callback" cannot be null. | `setCallback` was not called on `CFPaymentGatewayService` before `doPayment()`. Register the callback in `initState` before you initiate payment. |
</Accordion>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/payments/subscription/create">Create a Subscription</a></li>
    <li><a href="/docs/api-reference/payments/latest/subscription/fetch-details-of-all-payments-of-a-subscription">Fetch Details of All Payments of a Subscription API</a></li>
    <li><a href="/docs/payments/subscription/payment-modes">Supported Payment Methods</a></li>
    <li><a href="/docs/payments/subscription/charge">Charge a Subscription</a></li>
    <li><a href="https://pub.dev/packages/flutter_cashfree_pg_sdk">Flutter SDK on pub.dev</a></li>
  </ul>
</div>


# iOS Subscription Integration
Source: https://www.cashfree.com/docs/payments/subscription/custom-checkout/mobile/ios-subscription-element

Integrate the Cashfree Subscription Element SDK into your iOS application to accept subscription payments using card, UPI, and eNach (net banking).

The Cashfree subscription element SDK lets you build a fully custom subscription payment experience within your iOS application. Unlike the hosted checkout, you collect payment details directly in your own UI and pass them to the SDK, giving you complete control over the appearance and behaviour of your payment flow.

The SDK supports three payment methods for subscriptions: card, UPI, and eNach (electronic National Automated Clearing House, also known as net banking).

## Prerequisites

Complete the following tasks before you start the integration:

* Create a [Cashfree Merchant Account](https://merchant.cashfree.com/merchants/signup).
* Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and generate an **App ID** and **Secret Key**. Learn how to [generate API keys](/docs/api-reference/authentication#generate-api-keys).
* Use Cashfree iOS SDK version **2.4.0** or above.
* Set your application's minimum deployment target to **iOS 13.0** or higher.

The integration consists of three steps:

<CardGroup>
  <Card title="Step 1" icon="money-bill-wave" href="/docs/payments/subscription/custom-checkout/mobile/ios-subscription-element#step-1-create-a-subscription-server-side">
    Create a subscription
  </Card>

  <Card title="Step 2" icon="desktop" href="/docs/payments/subscription/custom-checkout/mobile/ios-subscription-element#step-2-open-the-payment-page-client-side">
    Open the payment page
  </Card>

  <Card title="Step 3" icon="circle-check" href="/docs/payments/subscription/custom-checkout/mobile/ios-subscription-element#step-3-confirm-the-payment-server-side">
    Confirm the payment
  </Card>
</CardGroup>

## Step 1: Create a subscription <Badge>Server-side</Badge>

Create a subscription from your backend server before you process any payment.

<Note>This API requires your secret key. Create subscriptions through your server only. Do not call this API directly from your mobile application.</Note>

After the subscription is created, your backend receives a `subscription_id` and a `subscription_session_id`. Pass both values to your iOS client to proceed with the payment.

<AccordionGroup>
  <Accordion title="API request for creating a subscription">
    The following example shows how to create a subscription using the Create Subscription API:

    <CodeGroup>
      ```bash cURL theme={"dark"}
      curl --request POST \
        --url https://sandbox.cashfree.com/pg/subscriptions \
        --header 'Content-Type: application/json' \
        --header 'x-api-version: 2025-01-01' \
        --header 'x-client-id: <your-client-id>' \
        --header 'x-client-secret: <your-client-secret>' \
        --data '{
          "subscription_id": "Demo_Subscription",
          "customer_details": {
            "customer_name": "john",
            "customer_email": "john@dummy.com",
            "customer_phone": "9908730221",
            "customer_bank_account_number": "59108290701802",
            "customer_bank_ifsc": "HDFC0002614",
            "customer_bank_code": "HDFC",
            "customer_bank_account_type": "SAVINGS"
          },
          "plan_details": {
            "plan_name": "plan12345",
            "plan_type": "PERIODIC",
            "plan_amount": 10,
            "plan_max_amount": 100,
            "plan_max_cycles": 100,
            "plan_intervals": 2,
            "plan_currency": "INR",
            "plan_interval_type": "WEEK",
            "plan_note": "Bi-weekly INR 10 plan"
          },
          "authorization_details": {
            "authorization_amount": 100,
            "authorization_amount_refund": true,
            "payment_methods": [
              "enach",
              "upi",
              "card"
            ]
          },
          "subscription_meta": {
            "return_url": "https://example.com/subscription/return",
            "notification_channel": [
              "EMAIL",
              "SMS"
            ],
            "session_id_expiry": "2025-06-01T23:00:08+05:30"
          },
          "subscription_expiry_time": "2100-01-01T23:00:08+05:30",
          "subscription_first_charge_time": "2025-06-01T23:00:08+05:30",
          "subscription_tags": {
            "psp_note": "Monthly subscription payment"
          }
        }'
      ```

      ```javascript Node theme={"dark"}
      // Creating a subscription using the Cashfree Node SDK
      // https://github.com/cashfree/cashfree-pg-sdk-nodejs
      ```

      ```java Java theme={"dark"}
      // Creating a subscription using the Cashfree Java SDK
      // https://github.com/cashfree/cashfree-pg-sdk-java
      ```

      ```go Golang theme={"dark"}
      // Creating a subscription using the Cashfree Go SDK
      // https://github.com/cashfree/cashfree-pg
      ```

      ```csharp .NET theme={"dark"}
      // Creating a subscription using the Cashfree .NET SDK
      // https://github.com/cashfree/cashfree-pg-sdk-dotnet
      ```

      ```python Python theme={"dark"}
      // Creating a subscription using the Cashfree Python SDK
      // https://github.com/cashfree/cashfree-pg-sdk-python
      ```

      ```php PHP theme={"dark"}
      // Creating a subscription using the Cashfree PHP SDK
      // https://github.com/cashfree/cashfree-pg-sdk-php
      ```
    </CodeGroup>

    A successful response returns the `subscription_id` and `subscription_session_id`. Use these values to build the `CFSubscriptionSession` object in [Step 2](#step-2-open-the-payment-page-client-side). The API returns the following response on success:

    ```json theme={"dark"}
    {
      "subscription_id": "Demo_Subscription",
      "subscription_session_id": "subs_token_tc9JCN4MzUIJ",
      "subscription_status": "INITIALIZED",
      "cf_subscription_id": "4"
    }
    ```

    For the full list of request parameters and response fields, see the [Create Subscription API](/docs/api-reference/payments/latest/subscription/create-subscription).
  </Accordion>
</AccordionGroup>

## Step 2: Open the payment page <Badge>Client-side</Badge>

After you create the subscription, open the payment page so the customer can provide payment details.

### 1. Set up the SDK

The Cashfree iOS SDK is available on [CocoaPods](https://cocoapods.org/pods/CashfreePG). The latest integration version is **2.4.0**. The SDK requires iOS **13.0** or higher. You can also integrate via Swift Package Manager (SPM) or a manual framework. See the [iOS SDK on GitHub](https://github.com/cashfree/core-ios-sdk) for those options.

Add the following to your `Podfile`:

```ruby theme={"dark"}
platform :ios, '13.0'

target 'YourAppTarget' do
  use_frameworks!
  pod 'CashfreePG', '2.4.0'
end
```

Run `pod install` to install the dependency.

### 2. Select a payment method

The Subscription Element SDK supports the following payment methods:

<Tabs>
  <Tab title="Card">
    In this flow, the customer enters their card details directly in your application UI. The SDK securely processes the card payment and initiates the subscription mandate. Use `.setChannel("link")` on the card builder for the standard link-based card flow.
  </Tab>

  <Tab title="UPI">
    In this flow, the SDK uses the UPI ID you provide to launch the customer's UPI app and authorise the subscription mandate. Pass a UPI app URI scheme (for example, `tez://`) in `.setUPIID()`.
  </Tab>

  <Tab title="eNach (net banking)">
    In this flow, the customer authorises the subscription mandate through one of three methods: Aadhaar OTP, debit card, or net banking. You specify the preferred authorisation mode when building the payment object.
  </Tab>
</Tabs>

### 3. Complete the payment

To complete the payment, follow these steps:

1. Create a `CFSubscriptionSession` object.
2. Create the payment object for the selected payment method.
3. Set up the payment callback.
4. Initiate the payment using `doSubsPayment()`.

#### Create a session

The `CFSubscriptionSession` object holds the session context for the payment. It accepts the `subscription_session_id` and `subscription_id` obtained from [Step 1](#step-1-create-a-subscription-server-side), and the Cashfree environment (`.SANDBOX` or `.PRODUCTION`).

Set the environment to `.SANDBOX` for testing or `.PRODUCTION` for live payments. The following example shows how to create the session object:

```swift theme={"dark"}
let subsSession = try CFSubscriptionSession.CFSubscriptionSessionBuilder()
    .setSubscriptionId(subscriptionId)
    .setSubscriptionSessionId(subscriptionSessionId)
    .setEnvironment(.SANDBOX) // or .PRODUCTION
    .build()
```

#### Create a payment object

The SDK provides a dedicated payment builder for each supported payment method. Build only the object that corresponds to the payment method your customer has selected.

<Tabs>
  <Tab title="Card">
    Use the following builders to create a card payment object. Collect card details securely from user input. Do not hardcode values in production.

    ```swift theme={"dark"}
    let subsCard = try CFCardSubs.CFCardSubsBuilder()
        .setChannel("link")
        .setCardNumber(cardNumber)
        .setCardExpiryMonth(expiryMonth)
        .setCardExpiryYear(expiryYear)
        .setCardHolderName(cardHolderName)
        .setCVV(cvv)
        .build()

    let subsCardPayment = try CFCardSubsPayment.CFCardPaymentSubsBuilder()
        .setCard(subsCard)
        .setSession(subsSession)
        .build()
    ```

    <Note>
      For non-PCI merchants who must not handle raw card numbers, use `CFSubsCardComponent` instead of `.setCardNumber()`. See [iOS Custom Card Component](/docs/payments/subscription/custom-checkout/custom-card/ios-custom-card).
    </Note>
  </Tab>

  <Tab title="UPI">
    The `setUPIID` field accepts the UPI app URI scheme used to launch the customer's UPI application (for example, `tez://` for Google Pay).

    ```swift theme={"dark"}
    let subsUpi = try CFUPISubs.CFUPISubsBuilder()
        .setUPIID(upiId)
        .build()

    let subsUpiPayment = try CFUPISubsPayment.CFUPIPaymentSubsBuilder()
        .setUPI(subsUpi)
        .setSession(subsSession)
        .build()
    ```
  </Tab>

  <Tab title="eNach (net banking)">
    The `setAuthMode` field specifies how the customer authorises the mandate. The following values are accepted:

    | Value | Description |
    | - | - |
    | `aadhaar` | The customer authorises the mandate using their Aadhaar number and OTP. |
    | `debit` | The customer authorises the mandate using their debit card details. |
    | `net_banking` | The customer authorises the mandate by logging into their net banking portal. |

    The following example shows how to build the net banking payment object:

    ```swift theme={"dark"}
    let subsNetBanking = try CFNetBankingSubs.CFNetbankingSubsBuilder()
        .setBankAccountCode(bankCode)
        .setAccountHolderName(accountHolderName)
        .setAccountNumber(accountNumber)
        .setAccountType(accountType) // SAVINGS or CURRENT
        .setAuthMode("net_banking") // aadhaar, debit, net_banking
        .build()

    let subsNBPayment = try CFNetbankingSubsPayment.CFNetbankingSubsPaymentBuilder()
        .setNetbanking(subsNetBanking)
        .setSession(subsSession)
        .build()
    ```
  </Tab>
</Tabs>

#### Set up the payment callback

The SDK exposes the `CFResponseDelegate` protocol to receive callbacks when the subscription payment journey ends. This protocol consists of two methods:

```swift theme={"dark"}
func onError(_ error: CFErrorResponse, order_id: String)
func verifyPayment(order_id: String)
```

<Tip>
  Register the callback on `CFPaymentGatewayService` before you call `doSubsPayment`. Set `paymentService.setCallback(self)` in your view controller before initiating payment.
</Tip>

The following example shows how to implement the callback:

```swift theme={"dark"}
class ViewController: UIViewController, CFResponseDelegate {

    func onError(_ error: CFErrorResponse, order_id: String) {
        print(error.message ?? "")
        // Handle payment failure. Inspect error for details.
    }

    func verifyPayment(order_id: String) {
        print(order_id)
        // Verify subscription status from your backend before proceeding.
    }
}
```

<Warning>
  Backend verification is mandatory. The SDK signals that the payment UI flow ended, not that payment succeeded. Always verify payment status from your backend before presenting success.
</Warning>

#### Initiate the payment

Call `doSubsPayment()` when the customer taps the pay button. The following example uses `subsNBPayment`. Replace it with `subsCardPayment` or `subsUpiPayment` for your selected payment method.

The following code registers the callback and initiates the subscription payment:

```swift theme={"dark"}
let paymentService = CFPaymentGatewayService.getInstance()
paymentService.setCallback(self)

do {
    try paymentService.doSubsPayment(subsNBPayment, viewController: self)
} catch {
    print(error.localizedDescription)
}
```

#### Sample code

The following example shows a complete card payment flow, including session creation, payment object setup, callback registration, and payment initiation.

<AccordionGroup>
  <Accordion title="Card payment sample">
    The following method demonstrates a complete card payment integration:

    ```swift theme={"dark"}
    do {
        let subsSession = try CFSubscriptionSession.CFSubscriptionSessionBuilder()
            .setSubscriptionId(subscriptionId)
            .setSubscriptionSessionId(subscriptionSessionId)
            .setEnvironment(.SANDBOX) // or .PRODUCTION
            .build()

        let subsCard = try CFCardSubs.CFCardSubsBuilder()
            .setChannel("link")
            .setCardNumber(cardNumber)
            .setCardExpiryMonth(expiryMonth)
            .setCardExpiryYear(expiryYear)
            .setCardHolderName(cardHolderName)
            .setCVV(cvv)
            .build()

        let subsCardPayment = try CFCardSubsPayment.CFCardPaymentSubsBuilder()
            .setCard(subsCard)
            .setSession(subsSession)
            .build()

        let paymentService = CFPaymentGatewayService.getInstance()
        paymentService.setCallback(self)
        try paymentService.doSubsPayment(subsCardPayment, viewController: self)

    } catch {
        print(error.localizedDescription)
    }
    ```
  </Accordion>
</AccordionGroup>

Refer to the sample integration on GitHub for a working end-to-end implementation.

<AccordionGroup>
  <Accordion title="iOS Subscription Element integration">
    [iOS SDK on GitHub](https://github.com/cashfree/core-ios-sdk)
  </Accordion>
</AccordionGroup>

## Step 3: Confirm the payment <Badge>Server-side</Badge>

After the SDK delivers a callback via `verifyPayment`, confirm the payment status from your backend before taking any action. The SDK callback signals only that the payment flow has ended. It does not guarantee a successful payment.

Use the [Fetch Details of All Payments of a Subscription API](/docs/api-reference/payments/latest/subscription/fetch-details-of-all-payments-of-a-subscription) to retrieve the current payment status.

<AccordionGroup>
  <Accordion title="API request for fetching subscription payments">
    The following request fetches all payments for a subscription:

    ```bash theme={"dark"}
    curl --request GET \
      --url https://api.cashfree.com/pg/subscriptions/{subscription_id}/payments \
      --header 'x-api-version: 2025-01-01' \
      --header 'x-client-id: <your-client-id>' \
      --header 'x-client-secret: <your-client-secret>'
    ```

    A successful response returns an array of payment objects. Check the `payment_status` field to determine the outcome. The API returns the following response on success:

    ```json theme={"dark"}
    [
      {
        "cf_payment_id": "123456",
        "cf_subscription_id": "7891011",
        "payment_id": "your-payment-id",
        "payment_amount": 1,
        "payment_status": "SUCCESS",
        "payment_type": "AUTH",
        "payment_initiated_date": "2025-06-01T22:14:58+0530",
        "subscription_id": "your-subscription-id",
        "retry_attempts": 0,
        "failure_details": {
          "failure_reason": ""
        }
      }
    ]
    ```
  </Accordion>
</AccordionGroup>

<Note>Always verify the subscription status from your backend before delivering goods or services to the customer. Proceed only when `payment_status` is `SUCCESS`.</Note>

## Error codes

If a required field or object is missing when you initiate payment, the SDK returns an error through the `catch` block or `onError` callback. The following table lists common SDK-level validation errors and when they occur.

<Accordion title="Show error codes">
  The SDK validation errors are grouped by category as follows:

  ### Session errors

  These errors occur when the `CFSubscriptionSession` object or its required fields are not provided.

  | Error code | Message | Description |
  | - | - | - |
  | `SUBSCRIPTION_SESSION_OBJECT_MISSING` | The "CFSubscriptionSession" is missing in the request. | The `CFSubscriptionSession` object was not passed to the payment builder. |
  | `SUBSCRIPTION_SESSION_ID_MISSING` | The "subscription\_session\_id" is missing in the request. | The `subscription_session_id` was not set on the `CFSubscriptionSession` builder. |
  | `SUBSCRIPTION_ID_MISSING` | The "subscription\_id" is missing in the request. | The `subscription_id` was not set on the `CFSubscriptionSession` builder. |
  | `ENVIRONMENT_MISSING` | The "environment" is missing in the request. | The Cashfree environment (`.SANDBOX` or `.PRODUCTION`) was not set on the `CFSubscriptionSession` builder. |

  ### Payment method object errors

  These errors occur when a payment method object is absent or one of its required fields is not set.

  | Error code | Message | Description |
  | - | - | - |
  | `SUBSCRIPTION_CARD_OBJECT_MISSING` | The "CFCardSubs" object is missing in the request. | The `CFCardSubs` object was not passed to the `CFCardSubsPayment` builder. |
  | `SUBSCRIPTION_NB_OBJECT_MISSING` | The "CFNetBankingSubs" object is missing in the request. | The `CFNetBankingSubs` object was not passed to the `CFNetbankingSubsPayment` builder. |
  | `SUBSCRIPTION_UPI_OBJECT_MISSING` | The "CFUPISubs" object is missing in the request. | The `CFUPISubs` object was not passed to the `CFUPISubsPayment` builder. |
  | `SUBSCRIPTION_NB_ACCOUNT_HOLDER_NAME_MISSING` | The "account holder name" is missing in the request. | The `setAccountHolderName` field was not set on the `CFNetBankingSubs` builder. |
  | `SUBSCRIPTION_NB_ACCOUNT_NUMBER_MISSING` | The "account number" is missing in the request. | The `setAccountNumber` field was not set on the `CFNetBankingSubs` builder. |
  | `SUBSCRIPTION_NB_BANK_CODE_MISSING` | The "bank code" is missing in the request. | The `setBankAccountCode` field was not set on the `CFNetBankingSubs` builder. |
  | `SUBSCRIPTION_NB_ACCOUNT_TYPE_MISSING` | The "account type" is missing in the request. | The `setAccountType` field was not set on the `CFNetBankingSubs` builder. |
  | `SUBSCRIPTION_NB_AUTH_MODE_MISSING` | The "auth mode" is missing in the request. | The `setAuthMode` field was not set on the `CFNetBankingSubs` builder. |

  ### Callback errors

  These errors occur when the payment callback is not registered before initiating payment.

  | Error code | Message | Description |
  | - | - | - |
  | `CALLBACK_MISSING` | The "callback" cannot be null. | `setCallback` was not called on `CFPaymentGatewayService` before `doSubsPayment()`. Register the callback before you initiate payment. |
</Accordion>

### Other options

The following optional configurations let you customise the payment screen behaviour.

<AccordionGroup>
  <Accordion title="(Optional) Enable full-screen payment">
    To present the payment flow in full screen, call `setFullScreen(true)` on the payment object before you call `doSubsPayment()`:

    ```swift theme={"dark"}
    subsCardPayment.setFullScreen(true)
    // or: subsUpiPayment.setFullScreen(true)
    ```
  </Accordion>
</AccordionGroup>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/payments/subscription/create">Create a Subscription</a></li>
    <li><a href="/docs/api-reference/payments/latest/subscription/fetch-details-of-all-payments-of-a-subscription">Fetch Details of All Payments of a Subscription API</a></li>
    <li><a href="/docs/payments/subscription/payment-modes">Supported Payment Methods</a></li>
    <li><a href="/docs/payments/subscription/charge">Charge a Subscription</a></li>
    <li><a href="/docs/payments/subscription/custom-checkout/custom-card/ios-custom-card">iOS Custom Card Component (Non-PCI)</a></li>
    <li><a href="https://github.com/cashfree/core-ios-sdk">iOS SDK on GitHub</a></li>
  </ul>
</div>


# React Native Subscription Integration
Source: https://www.cashfree.com/docs/payments/subscription/custom-checkout/mobile/react-native-subscription-element

Integrate the Cashfree Subscription Element SDK into your React Native application to accept subscription payments via card, UPI, and eNach on Android and iOS.

The Cashfree Subscription Element SDK lets you build a fully custom subscription payment experience within your React Native application. Unlike the hosted checkout, you collect payment details directly in your own UI and pass them to the SDK, giving you complete control over the appearance and behaviour of your payment flow.

The SDK supports three payment methods for subscriptions: card, UPI, and eNach (electronic National Automated Clearing House, also known as net banking). It runs on both Android and iOS from a single integration.

## Prerequisites

Complete the following tasks before you start the integration:

* Create a [Cashfree Merchant Account](https://merchant.cashfree.com/merchants/signup).
* Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and generate an **App ID** and **Secret Key**. Learn how to [generate API keys](/docs/api-reference/authentication#generate-api-keys).
* Use Cashfree React Native SDK version **2.4.0** or above. Get it from [npm](https://www.npmjs.com/package/react-native-cashfree-pg-sdk).
* Set your Android application's `minSdkVersion` to API level 19 or higher.
* Set your iOS minimum deployment target to 13.0 or higher.

The integration consists of three steps:

<CardGroup>
  <Card title="Step 1" icon="money-bill-wave" href="/docs/payments/subscription/custom-checkout/mobile/react-native-subscription-element#step-1-create-a-subscription-server-side">
    Create a subscription
  </Card>

  <Card title="Step 2" icon="desktop" href="/docs/payments/subscription/custom-checkout/mobile/react-native-subscription-element#step-2-open-the-payment-page-client-side">
    Open the payment page
  </Card>

  <Card title="Step 3" icon="circle-check" href="/docs/payments/subscription/custom-checkout/mobile/react-native-subscription-element#step-3-confirm-the-payment-server-side">
    Confirm the payment
  </Card>
</CardGroup>

## Step 1: Create a subscription <Badge>Server-side</Badge>

Create a subscription from your backend server before you process any payment.

<Note>This API requires your secret key. Create subscriptions through your server only — do not call this API directly from your mobile application.</Note>

After the subscription is created, your backend receives a `subscription_id` and a `subscription_session_id`. Pass both values to your React Native client to proceed with the payment.

<AccordionGroup>
  <Accordion title="API request for creating a subscription">
    The following example shows how to create a subscription using the Create Subscription API:

    <CodeGroup>
      ```bash cURL theme={"dark"}
      curl --request POST \
        --url https://sandbox.cashfree.com/pg/subscriptions \
        --header 'Content-Type: application/json' \
        --header 'x-api-version: 2025-01-01' \
        --header 'x-client-id: <your-client-id>' \
        --header 'x-client-secret: <your-client-secret>' \
        --data '{
          "subscription_id": "Demo_Subscription",
          "customer_details": {
            "customer_name": "john",
            "customer_email": "john@dummy.com",
            "customer_phone": "9908730221",
            "customer_bank_account_number": "59108290701802",
            "customer_bank_ifsc": "HDFC0002614",
            "customer_bank_code": "HDFC",
            "customer_bank_account_type": "SAVINGS"
          },
          "plan_details": {
            "plan_name": "plan12345",
            "plan_type": "PERIODIC",
            "plan_amount": 10,
            "plan_max_amount": 100,
            "plan_max_cycles": 100,
            "plan_intervals": 2,
            "plan_currency": "INR",
            "plan_interval_type": "WEEK",
            "plan_note": "Bi-weekly INR 10 plan"
          },
          "authorization_details": {
            "authorization_amount": 100,
            "authorization_amount_refund": true,
            "payment_methods": [
              "enach",
              "upi",
              "card"
            ]
          },
          "subscription_meta": {
            "return_url": "https://example.com/subscription/return",
            "notification_channel": [
              "EMAIL",
              "SMS"
            ],
            "session_id_expiry": "2025-06-01T23:00:08+05:30"
          },
          "subscription_expiry_time": "2100-01-01T23:00:08+05:30",
          "subscription_first_charge_time": "2025-06-01T23:00:08+05:30",
          "subscription_tags": {
            "psp_note": "Monthly subscription payment"
          }
        }'
      ```

      ```javascript Node theme={"dark"}
      // Creating a subscription using the Cashfree Node SDK
      // https://github.com/cashfree/cashfree-pg-sdk-nodejs
      ```

      ```java Java theme={"dark"}
      // Creating a subscription using the Cashfree Java SDK
      // https://github.com/cashfree/cashfree-pg-sdk-java
      ```

      ```go Golang theme={"dark"}
      // Creating a subscription using the Cashfree Go SDK
      // https://github.com/cashfree/cashfree-pg
      ```

      ```csharp .NET theme={"dark"}
      // Creating a subscription using the Cashfree .NET SDK
      // https://github.com/cashfree/cashfree-pg-sdk-dotnet
      ```

      ```python Python theme={"dark"}
      // Creating a subscription using the Cashfree Python SDK
      // https://github.com/cashfree/cashfree-pg-sdk-python
      ```

      ```php PHP theme={"dark"}
      // Creating a subscription using the Cashfree PHP SDK
      // https://github.com/cashfree/cashfree-pg-sdk-php
      ```
    </CodeGroup>

    A successful response returns the `subscription_id` and `subscription_session_id`. Use these values to build the `CFSubscriptionSession` object in [Step 2](#step-2-open-the-payment-page-client-side). The API returns the following response on success:

    ```json theme={"dark"}
    {
      "subscription_id": "Demo_Subscription",
      "subscription_session_id": "subs_token_tc9JCN4MzUIJ",
      "subscription_status": "INITIALIZED",
      "cf_subscription_id": "4"
    }
    ```

    For the full list of request parameters and response fields, see the [Create Subscription API](/docs/api-reference/payments/latest/subscription/create-subscription).
  </Accordion>
</AccordionGroup>

## Step 2: Open the payment page <Badge>Client-side</Badge>

After you create the subscription, open the payment page so the customer can provide payment details.

### 1. Set up the SDK

The React Native SDK is hosted on [npm](https://www.npmjs.com/). You can get the SDK [2.4.0](https://www.npmjs.com/package/react-native-cashfree-pg-sdk). The React Native SDK supports Android SDK version 19 and above and iOS minimum deployment target of 13.0 and above.

Install the SDK in your React Native project:

<CodeGroup>
  ```npm npm theme={"dark"}
  npm install react-native-cashfree-pg-sdk
  ```

  ```yarn yarn theme={"dark"}
  yarn add react-native-cashfree-pg-sdk
  ```

  ```expo expo theme={"dark"}
  npx expo install react-native-cashfree-pg-sdk
  npx expo install expo-dev-client
  npx expo prebuild
  npx expo run:android
  npx expo run:ios
  ```
</CodeGroup>

#### Android configuration

Add the following entry inside the `<application>` tag in your Android manifest file. If you do not enable the `cashfree_subscription_flow_enable` flag, the SDK will not provide a payment callback.

<Note>Add this entry inside the `<application>` tag, not inside the `<activity>` tag.</Note>

```xml theme={"dark"}
<application
    android:icon="@mipmap/ic_launcher"
    android:label="@string/app_name">

    <meta-data
        android:name="cashfree_subscription_flow_enable"
        android:value="true"
        tools:replace="android:value"/>
</application>
```

#### iOS configuration

Update your iOS deployment target in your Podfile to 13.0 or higher:

```ruby theme={"dark"}
platform :ios, '13.0'

target 'YourAppName' do
  use_frameworks!
  pod 'CashfreePG', '2.4.0'
end
```

Run `pod install` to install the dependency:

```bash theme={"dark"}
cd ios
pod install --repo-update
```

To provide UPI payments on iOS, add the following to your application's `info.plist` file:

```xml theme={"dark"}
<key>LSApplicationQueriesSchemes</key>
<array>
  <string>amazonpay</string>
  <string>upi</string>
  <string>credpay</string>
  <string>bhim</string>
  <string>paytmmp</string>
  <string>phonepe</string>
  <string>tez</string>
  <string>navipay</string>
  <string>mobikwik</string>
  <string>myairtel</string>
  <string>popclubapp</string>
  <string>super</string>
  <string>kiwi</string>
  <string>simplypayupi</string>
  <string>whatsapp</string>
</array>
```

### 2. Select a payment method

The Subscription Element SDK supports the following payment methods:

<Tabs>
  <Tab title="Card">
    In this flow, the customer enters their card details directly in your application UI. The SDK securely processes the card payment and initiates the subscription mandate.
  </Tab>

  <Tab title="UPI">
    In this flow, the SDK launches the customer's selected UPI app to authorise the subscription mandate. On Android, pass the package name of the installed UPI PSP (payment service provider) application. On iOS, pass the UPI app URI scheme (for example, `tez://`).
  </Tab>

  <Tab title="eNach (net banking)">
    In this flow, the customer authorises the subscription mandate through one of three methods: Aadhaar OTP, debit card, or net banking. Include `enach` in `payment_methods` when you create the subscription on your server.
  </Tab>
</Tabs>

### 3. Complete the payment

To complete the payment, follow these steps:

1. Create a `CFSubscriptionSession` object.
2. Create the payment object for the selected payment method.
3. Set up the subscription callback.
4. Initiate the payment using `makeSubsPayment()`.

#### Create a session

The `CFSubscriptionSession` object holds the session context for the payment. It accepts the `subscription_session_id` and `subscription_id` obtained from [Step 1](#step-1-create-a-subscription-server-side), and the Cashfree environment (`CFEnvironment.SANDBOX` or `CFEnvironment.PRODUCTION`).

The following example shows how to create the session object:

```typescript theme={"dark"}
import {
  CFEnvironment,
  CFSubscriptionSession,
} from 'cashfree-pg-api-contract';

const getSubscriptionSession = () => {
  try {
    return new CFSubscriptionSession(
      subscriptionSessionId,
      subscriptionId,
      CFEnvironment.SANDBOX, // or CFEnvironment.PRODUCTION
    );
  } catch (e: any) {
    console.log(e.message);
    return null;
  }
};
```

#### Create a payment object

The SDK provides a dedicated payment class for each supported payment method. Build only the object that corresponds to the payment method your customer has selected.

<Tabs>
  <Tab title="Card">
    Use the following code to create a card payment object:

    ```typescript theme={"dark"}
    import {Card, CFSubsCardPayment} from 'cashfree-pg-api-contract';

    const session = getSubscriptionSession();
    if (!session) return;

    const card = new Card(
      cardNumber,
      cardHolderName,
      cardExpiryMM,
      cardExpiryYY,
      cardCVV,
    );

    const subsCardPayment = new CFSubsCardPayment(session, card);
    ```
  </Tab>

  <Tab title="UPI">
    The UPI flow launches the customer's selected UPI application. On Android, pass the app package name of the UPI PSP application installed on the device (for example, `com.phonepe.app`). On iOS, pass the UPI app URI scheme (for example, `tez://`).

    ```typescript theme={"dark"}
    import {CFSubsUPIPayment, CFUPI, UPIMode} from 'cashfree-pg-api-contract';

    const session = getSubscriptionSession();
    if (!session) return;

    const upi = new CFUPI(UPIMode.INTENT, upiId);
    const subsUpiPayment = new CFSubsUPIPayment(session, upi);
    ```
  </Tab>

  <Tab title="eNach (net banking)">
    The eNach flow allows the customer to authorise the subscription mandate using their bank account details. The following eNach authorisation modes are supported at the subscription level:

    | Value | Description |
    | - | - |
    | `aadhaar` | The customer authorises the mandate using their Aadhaar number and OTP. |
    | `debit_card` | The customer authorises the mandate using their debit card details. |
    | `net_banking` | The customer authorises the mandate by logging into their net banking portal. |

    The following example shows how to build the eNach payment object:

    ```typescript theme={"dark"}
    import {CFSubsNB, CFSubsNBPayment} from 'cashfree-pg-api-contract';

    const session = getSubscriptionSession();
    if (!session) return;

    const nb = new CFSubsNB(
      accountHolderName,
      accountNumber,
      accountBankCode,
      accountType, // SAVINGS or CURRENT
    );

    const subsNBPayment = new CFSubsNBPayment(session, nb);
    ```
  </Tab>
</Tabs>

#### Set up the subscription callback

The SDK exposes a callback interface to receive callbacks when the subscription payment journey ends. The callback supports two methods:

```typescript theme={"dark"}
onVerify(orderID: string)
onError(error: CFErrorResponse, orderID: string)
```

<Tip>Register the callback before calling `makeSubsPayment()`. Set it in `componentDidMount` and remove it in `componentWillUnmount` to handle activity restarts correctly and prevent memory leaks.</Tip>

The following example shows how to register the callback:

```typescript theme={"dark"}
import {
  CFErrorResponse,
  CFPaymentGatewayService,
} from 'react-native-cashfree-pg-sdk';

componentDidMount() {
  CFPaymentGatewayService.setCallback({
    onVerify(subscriptionId: string): void {
      // Verify subscription status from your backend before proceeding.
      console.log('Verify subscription:', subscriptionId);
    },
    onError(error: CFErrorResponse, subscriptionId: string): void {
      // Handle payment failure. Inspect error for details.
      console.log('Payment failed:', error, subscriptionId);
    },
  });
}

componentWillUnmount() {
  CFPaymentGatewayService.removeCallback();
}
```

<Warning>
  Backend verification is mandatory. The SDK signals that the payment UI flow ended, not that payment succeeded. Always verify payment status from your backend before presenting success.
</Warning>

#### Initiate the payment

Call `makeSubsPayment()` to open the payment screen when the customer taps the pay button. Pass the payment object for your selected payment method.

```typescript theme={"dark"}
import {CFPaymentGatewayService} from 'react-native-cashfree-pg-sdk';

CFPaymentGatewayService.makeSubsPayment(subsCardPayment);
// or: CFPaymentGatewayService.makeSubsPayment(subsUpiPayment);
// or: CFPaymentGatewayService.makeSubsPayment(subsNBPayment);
```

#### Sample code

The following example shows a complete card payment flow, including session creation, payment object setup, callback registration, and payment initiation.

<AccordionGroup>
  <Accordion title="Card payment sample">
    The following method demonstrates a complete card payment integration:

    ```typescript theme={"dark"}
    import {Component} from 'react';
    import {
      CFErrorResponse,
      CFPaymentGatewayService,
    } from 'react-native-cashfree-pg-sdk';
    import {
      Card,
      CFEnvironment,
      CFSubsCardPayment,
      CFSubscriptionSession,
    } from 'cashfree-pg-api-contract';

    export default class SubscriptionCheckout extends Component {

      componentDidMount() {
        CFPaymentGatewayService.setCallback({
          onVerify(subscriptionId: string): void {
            // Verify subscription status from your backend before proceeding.
            console.log('Verify subscription:', subscriptionId);
          },
          onError(error: CFErrorResponse, subscriptionId: string): void {
            console.log(error.getMessage());
            console.log('Error while making payment');
          },
        });
      }

      componentWillUnmount() {
        CFPaymentGatewayService.removeCallback();
      }

      getSubscriptionSession() {
        return new CFSubscriptionSession(
          this.state.subscriptionSessionId,
          this.state.subscriptionId,
          CFEnvironment.SANDBOX, // or CFEnvironment.PRODUCTION
        );
      }

      async subsCardPay() {
        try {
          const session = this.getSubscriptionSession();
          const card = new Card(
            this.state.cardNumber,
            this.state.cardHolderName,
            this.state.cardExpiryMM,
            this.state.cardExpiryYY,
            this.state.cardCVV,
          );
          const subsCardPayment = new CFSubsCardPayment(session, card);
          CFPaymentGatewayService.makeSubsPayment(subsCardPayment);
        } catch (e: any) {
          console.log(e.message);
        }
      }
    }
    ```
  </Accordion>
</AccordionGroup>

Refer to the sample integration on GitHub for a working end-to-end implementation.

<AccordionGroup>
  <Accordion title="React Native Subscription Element integration">
    [GitHub sample](https://github.com/cashfree/react-native-cashfree-pg-sdk/blob/master/example/src/SubscriptionScreen.tsx)
  </Accordion>
</AccordionGroup>

<Note>This SDK is compatible with the Expo framework. For a sample implementation, see the [Expo sample](https://github.com/kishan-cashfree/Expo-RN_Cashfree_SDK) on GitHub.</Note>

## Step 3: Confirm the payment <Badge>Server-side</Badge>

After the SDK delivers a callback via `onVerify`, confirm the payment status from your backend before taking any action. The SDK callback signals only that the payment flow has ended. It does not guarantee a successful payment.

Use the [Fetch Details of All Payments of a Subscription API](/docs/api-reference/payments/latest/subscription/fetch-details-of-all-payments-of-a-subscription) to retrieve the current payment status.

<AccordionGroup>
  <Accordion title="API request for fetching subscription payments">
    The following request fetches all payments for a subscription:

    ```bash theme={"dark"}
    curl --request GET \
      --url https://api.cashfree.com/pg/subscriptions/{subscription_id}/payments \
      --header 'x-api-version: 2025-01-01' \
      --header 'x-client-id: <your-client-id>' \
      --header 'x-client-secret: <your-client-secret>'
    ```

    A successful response returns an array of payment objects. Check the `payment_status` field to determine the outcome. The API returns the following response on success:

    ```json theme={"dark"}
    [
      {
        "cf_payment_id": "123456",
        "cf_subscription_id": "7891011",
        "payment_id": "your-payment-id",
        "payment_amount": 1,
        "payment_status": "SUCCESS",
        "payment_type": "AUTH",
        "payment_initiated_date": "2025-06-01T22:14:58+0530",
        "subscription_id": "your-subscription-id",
        "retry_attempts": 0,
        "failure_details": {
          "failure_reason": ""
        }
      }
    ]
    ```
  </Accordion>
</AccordionGroup>

<Note>Always verify the subscription status from your backend before delivering goods or services to the customer. Proceed only when `payment_status` is `SUCCESS`.</Note>

## Error codes

If a required field or object is missing when you initiate payment, the SDK throws an error. The following table lists SDK-level validation errors and when they occur.

<Accordion title="Show error codes">
  The SDK validation errors are grouped by category as follows:

  ### Session errors

  These errors occur when the `CFSubscriptionSession` object or its required fields are not provided.

  | Error code | Message | Description |
  | - | - | - |
  | `SUBSCRIPTION_SESSION_OBJECT_MISSING` | The "CFSubscriptionSession" is missing in the request. | The `CFSubscriptionSession` object was not passed to the payment class. |
  | `SUBSCRIPTION_SESSION_ID_MISSING` | The "subscription\_session\_id" is missing in the request. | The `subscription_session_id` was not set on the `CFSubscriptionSession` constructor. |
  | `SUBSCRIPTION_ID_MISSING` | The "subscription\_id" is missing in the request. | The `subscription_id` was not set on the `CFSubscriptionSession` constructor. |
  | `ENVIRONMENT_MISSING` | The "environment" is missing in the request. | The Cashfree environment was not set on the `CFSubscriptionSession` constructor. |

  ### Payment method object errors

  These errors occur when a payment method object is absent or one of its required fields is not set.

  | Error code | Message | Description |
  | - | - | - |
  | `SUBSCRIPTION_CARD_OBJECT_MISSING` | The "Card" object is missing in the request. | The `Card` object was not passed to the `CFSubsCardPayment` constructor. |
  | `SUBSCRIPTION_NB_OBJECT_MISSING` | The "CFSubsNB" object is missing in the request. | The `CFSubsNB` object was not passed to the `CFSubsNBPayment` constructor. |
  | `SUBSCRIPTION_UPI_OBJECT_MISSING` | The "CFUPI" object is missing in the request. | The `CFUPI` object was not passed to the `CFSubsUPIPayment` constructor. |
  | `SUBSCRIPTION_NB_ACCOUNT_HOLDER_NAME_MISSING` | The "account holder name" is missing in the request. | The account holder name was not set on the `CFSubsNB` constructor. |
  | `SUBSCRIPTION_NB_ACCOUNT_NUMBER_MISSING` | The "account number" is missing in the request. | The account number was not set on the `CFSubsNB` constructor. |
  | `SUBSCRIPTION_NB_BANK_CODE_MISSING` | The "bank code" is missing in the request. | The bank code was not set on the `CFSubsNB` constructor. |
  | `SUBSCRIPTION_NB_ACCOUNT_TYPE_MISSING` | The "account type" is missing in the request. | The account type was not set on the `CFSubsNB` constructor. |

  ### Callback errors

  These errors occur when the payment callback is not registered before initiating payment.

  | Error code | Message | Description |
  | - | - | - |
  | `CALLBACK_MISSING` | The "callback" cannot be null. | `setCallback` was not called on `CFPaymentGatewayService` before `makeSubsPayment()`. Register the callback in `componentDidMount` before you initiate payment. |
</Accordion>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/payments/latest/subscription/create-subscription">Create Subscription API</a></li>
    <li><a href="/docs/api-reference/payments/latest/subscription/fetch-details-of-all-payments-of-a-subscription">Fetch Details of All Payments of a Subscription API</a></li>
    <li><a href="/docs/payments/subscription/payment-modes">Supported Payment Methods</a></li>
    <li><a href="/docs/payments/subscription/charge">Charge a Subscription</a></li>
    <li><a href="https://www.npmjs.com/package/react-native-cashfree-pg-sdk">React Native SDK on npm</a></li>
  </ul>
</div>


# Subscription FAQs
Source: https://www.cashfree.com/docs/payments/subscription/faq

Browse Cashfree Subscriptions FAQs covering mandate authorisation, charges, supported methods like UPI mandates, retries, webhooks, and reconciliation.

<AccordionGroup>
  <Accordion title="What is Subscription?">
    Cashfree Subscriptions lets you set up and manage recurring payments for your customers.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are the payment methods supported by Cashfree Subscriptions?">
    | Payment methods supported | Banks or card networks or UPI handles | Maximum subscription amount allowed |
    | :- | :- | :- |
    | eNACH | See the [list of NPCI-supported banks](https://www.npci.org.in/product/nach/all-members) | ₹ 1,00,00,000 |
    | UPI autopay | See the [list of banks and PSPs](https://www.npci.org.in/what-we-do/autopay/list-of-banks-and-apps-live-on-autopay) | ₹ 15,000 (without AFA) or ₹ 1,00,000 (with AFA) |
    | Card (Indian) | Visa, Mastercard, RuPay | ₹ 15,000 (without AFA) or ₹ 1,00,00,000  (with AFA) |
    | Card (International) | Visa, Mastercard | ₹ 1,00,00,000 |
    | Physical mandates | See the [list of supported banks](https://gocashassets.s3.ap-south-1.amazonaws.com/subscriptions/List+of+Bank+Supported+for+Physical+NACH+-+Sheet1.pdf.zip) | ₹ 1,00,00,000 |

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What frequencies are supported for all payment methods?">
    | Payment method | Supported frequencies |
    | - | - |
    | eNACH | Daily, weekly, monthly, yearly, ad-hoc |
    | UPI AutoPay | Daily, weekly, monthly, ad-hoc |
    | Card | Weekly, monthly, yearly, ad-hoc |
    | Physical NACH | Daily, weekly, monthly, yearly, ad-hoc |

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are the different subscription states?">
    * **INITIALIZED** – Subscription created, authorisation pending.
    * **BANK APPROVAL PENDING** – Authorisation successful, pending bank approval.
    * **ACTIVE** – Subscription registered across NPCI and destination bank.
    * **ON HOLD** – A charge has failed for the subscription.
    * **PAUSED** – Subscription is paused by the merchant.
    * **COMPLETED** – Subscription completed its scheduled duration.
    * **CUSTOMER CANCELLED** – Subscription cancelled by the customer.
    * **CUSTOMER PAUSED** – Subscription paused by the customer.
    * **EXPIRED** – In seamless subscriptions, authorisation wasn't attempted before expiry.
    * **LINK EXPIRED** – In non-seamless subscriptions, authorisation wasn't attempted before expiry.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I retry a failed transaction and collect payments for that cycle?">
    Yes. You can retry the last failed charge via the Merchant Dashboard or API.\
    [Refer to the retry subscription charge API](/docs/api-reference/payments/previous/subscriptionsv1/subscription/retry-subscription-charge) for details.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I extend the expiry date of a subscription?">
    No. You can’t extend the expiry date of a subscription. You can cancel the subscription and create a new one.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I test a subscription model before going live?">
    Yes. You can test any subscription model in the test environment before going live.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How do I know if I have received payments?">
    You can use webhooks to receive notifications for all transactions.\
    [Follow these steps to configure webhooks](/docs/api-reference/payments/latest/subscription/webhooks).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Why aren't we receiving SUBSCRIPTION_PAYMENT_SUCCESS or SUBSCRIPTION_AUTHORIZED webhooks?">
    Subscription webhook events use a separate configuration from the main Payment Gateway webhooks. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login), go to **Payment Gateway > Developers > Webhooks**, and select the **Subscriptions** tab. Add your endpoint there and select the subscription events you want to receive. An endpoint configured only under the main webhooks section does not receive subscription-specific events.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I replay or resend a missed subscription webhook?">
    No. Cashfree does not currently support replaying or resending subscription webhooks, such as `SUBSCRIPTION_PAYMENT_SUCCESS`, after they trigger. To check the current status of a subscription payment instead, call the [Fetch Single Charge](/docs/api-reference/payments/latest/subscription/payment/fetch) API to poll the latest transaction state. As a fallback, configure webhook retry handling on your own server.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Why do sandbox and production send different eNACH subscription webhook payload formats?">
    This happens when each environment uses a different webhook version. Select the same webhook version, `2026-01-01` (the current version), in both your sandbox and production subscription webhook settings. Older versions (`2022-09-01`, `2023-08-01`, `2025-01-01`) return a different payload structure, so mismatched versions across environments produce mismatched payloads for the same event.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I modify an existing subscription?">
    Yes. You can update the recurring amount of an active subscription using the [Update Recurring Amount API](/docs/api-reference/payments/previous/subscriptionsv1/subscription/update-recurring-amount).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can Subscriptions charge a variable amount each billing cycle instead of a fixed amount?">
    Yes. Use [On-Demand Subscriptions](/docs/payments/subscription/introduction). The customer authorises a maximum mandate amount once, at setup. You can then charge any amount up to that maximum for each billing cycle by calling `POST /pg/subscriptions/pay` with `payment_type: CHARGE`, without requiring re-authorisation. This approach suits usage-based or milestone billing, where the charge amount varies each cycle.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What is the difference between 'Net Banking' and 'Debit Card' under the e-Mandate payment mode?">
    The customer is authenticated by their bank using either net banking or debit card credentials. Debit card credentials are used only for authentication. Therefore, the mandate remains valid even if the debit card expires.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What is the maximum amount limit for each payment method?">
    | Payment method | Supported networks or banks | Maximum subscription amount |
    | - | - | - |
    | eNACH | See the [list of NPCI-supported banks](https://www.npci.org.in/product/nach/all-members) | ₹1,00,00,000 |
    | UPI AutoPay | [Live UPI apps and banks](https://www.npci.org.in/what-we-do/autopay/list-of-banks-and-apps-live-on-autopay) | ₹15,000 (no AFA), ₹1,00,000 (with AFA) |
    | Card | Visa, Mastercard | ₹15,000 (no AFA), > ₹15,000 (with AFA) |
    | Physical Mandate | [Supported banks](https://gocashassets.s3.ap-south-1.amazonaws.com/subscriptions/List+of+Bank+Supported+for+Physical+NACH+-+Sheet1.pdf.zip) | ₹1,00,00,000 |

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Which apps are supported for UPI Subscriptions?">
    View the [list of supported UPI apps and banks](https://www.npci.org.in/what-we-do/autopay/list-of-banks-and-apps-live-on-autopay).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What is the cut-off time to raise a transaction?">
    | Charge raised on | Scheduled for | NACH | UPI AutoPay | SI on cards |
    | - | - | - | - | - |
    | 00:00–06:59 (T) | null | Raised on T | Not Allowed | Not Allowed |
    | 07:00–11:59 (T) | null | Raised on T+1 | Not Allowed | Not Allowed |
    | 00:00–06:59 (T) | T | **Raised on T** | Not Allowed | Not Allowed |
    | 07:00–11:59 (T) | T | **Not Allowed** | Not Allowed | Not Allowed |
    | 00:00–20:59 (T) | T+1 | Raised on T+1 | **Raised on T+1** | Not Allowed |
    | 21:00–23:59 (T) | T+1 | Raised on T+1 | **Not Allowed** | Not Allowed |
    | 00:00–23:59 (T) | T+n (2–14) | Raised on T+n | Raised on T+n | Raised on T+n |
    | 00:00–23:59 (T) | T+15 | Not Allowed | Not Allowed | Not Allowed |

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are the common eNACH failure reasons?">
    Mandate creation and transactions may fail due to operational or customer-related issues. View the [common failure reasons](https://cashfreelogo.cashfree.com/website/docs/nach-errors.pdf).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Which bank accounts are supported for eNACH mandates?">
    Only savings accounts and individual (proprietor) current accounts are supported. Most destination banks do not support mandates for proprietor current accounts. For unsupported cases, consider using [Physical NACH](/docs/api-reference/payments/previous/subscriptionsv1/physical-mandates).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Which intent apps are supported by Subscriptions?">
    | App | Android intent | iOS intent |
    | - | - | - |
    | Paytm | ✔️ | ✔️ |
    | GPay (@okhdfc, @okicici, @oksbi) | ✔️ | ✔️ |
    | PhonePe | ✔️ | ✔️ |
    | AmazonPay | ✔️ | ✔️ |

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can my customer pause or cancel a mandate from their end?">
    Yes. Customers can pause or cancel a mandate from their UPI app (Mandates > Active Mandates > Pause/Cancel > Submit).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I resume a mandate if my customer has paused it?">
    No. Only the customer can resume a paused mandate from their UPI app.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What is the maximum expiry period for eNACH mandates?">
    The expiry period for an eNACH mandate can be set up to a maximum of 30 years.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What happens if the card used for a subscription expires?">
    If the card expires, the subscription is marked as <code>card\_expired</code>.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can the merchant receive advance notice of a card expiry?">
    Yes. The <code>subscription\_card\_expiry\_reminder</code> webhook is triggered 6 days before the card expiry.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What happens to an active subscription after the card expires?">
    Once the card expires, the subscription moves to <code>card\_expired</code> status. Further charges cannot be processed.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What should the merchant do if a subscription is marked as card_expired?">
    The merchant must create a new mandate using the updated card details. The customer must then authorise the new mandate.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are the different ways that I can use Cashfree to collect recurring payments or payments for subscriptions from my customers?">
    Cashfree offers four different payment methods, each with specific limits on the allowed subscription amounts, as outlined below.

    * UPI AutoPay
    * Cards
    * eNach
    * Physical Mandate

    [Learn more about these payment modes](/docs/payments/subscription/payment-modes).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Is the Cashfree Subscriptions solution compliant with the new Digital Lending Guidelines by RBI?">
    Yes, it is fully compliant with the new Digital Lending Guidelines by RBI. NBFCs and Fintechs can use Cashfree to collect repayments, disburse credit, and co-lend without a hassle.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Who can benefit from using Cashfree Subscriptions?">
    Cashfree Subscriptions caters to various industries with diverse use cases. Some of the top ones include:

    * NBFCs and digital lending apps
    * OTT platforms
    * Ed-tech platforms
    * E-commerce companies
    * Investment firms
    * Insurance providers

      <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How to create a subscriptions plan on Cashfree dashboard?">
    1. Go to **Subscription Dashboard** > **All subscriptions** > **Create Subscriptions**

    2. Enter details – Add customer info, subscription ID, recurring amount, due date, and max debits.

       <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How to create a UPI AutoPay plan?">
    To create a new subscription from the Merchant Dashboard, go to **Subscriptions Dashboard > All Subscriptions > Create Subscription**.

    You can also create multiple subscriptions at once using the Merchant Dashboard. Go to **Subscriptions Dashboard > Batch Subscriptions > Upload File** to upload a file that contains all the information required for multiple subscriptions.

    [Learn more](/docs/payments/subscription/create)

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How do I activate UPI AutoPay for Subscriptions, and what does it cost?">
    Cashfree does not offer UPI AutoPay activation as a self-serve feature. Contact your Cashfree account manager, or fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1), to request activation on your production and sandbox accounts. Charges depend on your pricing plan, so confirm the applicable rate with your account manager.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What is the Bulk Payments tab on the Subscriptions dashboard?">
    For On-Demand subscriptions, when you want to initiate a large number of payments for multiple subscriptions, you can use the Bulk Payments feature.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I migrate my mandate data from another payment aggregator to Cashfree?">
    Cashfree supports importing mandate information for a subscription. You can move any historical mandate data to Cashfree and continue processing transactions in Cashfree. Cashfree ensures a smooth mandate porting experience.

    To initiate the porting process:

    1. **Contact Cashfree support**: Initiate the porting process by nominating Cashfree as your payment processing partner for your Utility Code or mandates.
    2. **Partner bank coordination**: Share the mandate list with your partner bank to update their systems. Our team will guide you through the process.
    3. **Import mandates**: Upload the updated mandate list into Cashfree’s system.
    4. **Start processing payments**: Once imported, you can begin processing payments seamlessly through Cashfree.
       [Learn more about importing mandates](/docs/payments/subscription/import).

       <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are the various eNACH transaction failure reasons?">
    Once the eMandate is successfully created, the corresponding transactions can get declined due to the reasons listed below:

    | Transaction failure reason | Detailed description | Resolution |
    | - | - | - |
    | Balance Insufficient | This error is displayed when the end-customer does not have sufficient balance in their account. In this case, due to payment failure, the end-customer will be asked to pay a fine of amount equivalent to the cheque bounce charges by the destination bank. | The merchant can present the transaction again. It is recommended to contact the end-customer before retrying the failed transaction. A total of 3 retries are allowed before the start of the next cycle. |
    | Not Arranged For or Exceeds arrangement | This error is displayed when the end-customer does not have sufficient balance in their overdraft account. | The merchant can present the transaction again. It is recommended to contact the end-customer before retrying the failed transaction. A total of 3 retries are allowed before the start of the next cycle. |
    | Customer to refer to the branch | This error is displayed when the reason for the decline is unclear and the destination bank is expecting the end-customer to contact them for further clarification. | Merchant can contact the end-customer and recommend the end-customer to contact the bank and provide further clarification. |
    | Account Closed | This error is displayed when the account has been closed and thus all the associated mandates were deactivated. | Further action cannot be taken in this scenario. The merchant can create another mandate for the end-customer to continue with the debit. |
    | Invalid UMRN or Inactive Mandate | This error is displayed when the mandate has been de-activated by the NPCI's system. Usually when the mandate has not been debited over a prolonged period of time. | Further action cannot be taken in this scenario. The merchant can create another mandate for the end-customer to continue with the debit. |
    | Mandate Cancelled | This error is displayed when the mandate has been cancelled. This can be merchant initiated or end-customer initiated. | Further action cannot be taken in this scenario. The merchant would have to create another mandate for the end-customer to continue with the debit. |
    | No Such Account | This error is displayed when the account has been closed or no longer available. Thus all the associated mandates were deactivated. | Further action cannot be taken in this scenario. The merchant would have to create another mandate for the end-customer to continue with the debit. |
    | A/c Blocked or Frozen | This error is displayed when all the withdrawals, purchases or transfers have been halted for this account. Hence, the presentation is not successful. | The merchant must contact the end-customer to resolve this issue. |
    | Payment Stopped by Drawer | This error is displayed when the presentation has been stopped at the request of the end-customer. | The merchant must contact the end-customer to resolve this issue. |
    | Payment Stopped under Court Order/Account Under Litigation | This error is displayed when the presentation has been stopped at a Court order. | The merchant must contact the end-customer to resolve this issue. |
    | Customer name mismatch | This error is displayed when the account holder's name provided during mandate creation does not match the account holder's name at the time of presentation. | Since the mandate cannot be edited, the merchant must create a new mandate with the end-customer. |
    | Network Failure (CBS) | This error is displayed when the Core Banking System(CBS) of the destination bank has a network failure. Generally, all the presentations for the affected bank would fail for the day. | The merchant can try to present the transaction again. The transaction is expected to go through once the system is up. |
    | Returned as per customer request | This error is displayed when the presentation has been stopped at the request of the customer. | The merchant must contact the end-customer to resolve this issue. |
    | KYC Documents Pending | Typically end-customer is expected to do a KYC for the bank account at least once in 3 years. On such cases, the presentation could be stopped by the bank, and this error message is displayed. | The end-customer must complete the KYC post which the merchant can try to present the transaction. |
    | Documents Pending for Account Holder turning Major | This error is displayed when the documentation is pending. | End customer must complete the documentation process at the bank. |
    | Account Inoperative | This error is displayed when there are no transactions in an account for the last 3 months. All the associated mandates are deactivated. | Further action cannot be taken in this scenario. The merchant would have to create another mandate for the end-customer to continue with the debit. |
    | Dormant Account | This error is displayed when there are no transactions in an account for the last 6 months. Account is dormant and all the associated mandates are deactivated. | Further action cannot be taken in this scenario. The merchant would have to create another mandate for the end-customer to continue with the debit. |
    | Small account, First Transaction to be from Base Branch | For a bank account type - small account, the first transaction must happen at the home branch. | |
    | Account reached maximum Debit limit set on account by Bank | This error is displayed when the end-customer has sufficient balance in their account but the account has already reached the maximum limitation set for security reasons. | The merchant must contact the end-customer to increase the limit and then they try to do another presentation. |
    | Account Holder Expired | This error message is displayed when the account holder has expired. | - |
    | Account under litigation | This error is displayed when an account is currently under legal action. | Further debits are not possible for this bank account. A new mandate must be created with a different bank account to take this forward. |
    | Aadhaar number not mapped to the account number | This error is displayed when the end customer Aadhaar number is not linked to the bank account. | The end-customer must link the Aadhaar number with the bank account post which the merchant can try to do another presentation. |
    | Customer Insolvent / Insane | - | Further action cannot be taken for this error message. The merchant would have to create another mandate with a different bank account. |
    | Item cancelled | This error is displayed when the end-customer has cancelled the presentation. | The merchant must contact the end-customer to get this resolved post which the merchant can try to do another presentation. |

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Multiple authorisations will be present if the customer has attempted the transaction multiple times?">
    Multiple auths will appear if the customer attempts the transaction more than once.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What causes a payment_mode_invalid_for_action error on the subscription pay endpoint?">
    The API returns this error when the requested payment mode is not valid for the action you are performing. Common causes include:

    * UPI AutoPay is not activated on your merchant account.
    * An `AUTH` action is being attempted on a subscription that is already authorised. Only one `AUTH` is allowed per mandate.
    * The plan or subscription type does not support the requested action. See [subscription payment modes](/docs/payments/subscription/payment-modes) for supported actions per mode.

    Use the [Fetch Subscription API](/docs/api-reference/payments/latest/subscription/fetch-subscription) to check the subscription's current status first. If UPI AutoPay activation is the cause, contact your account manager or fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1). This requires commercial approval.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="If a periodic subscription transaction is in the PENDING state and the subscription is then moved to the PAUSED state, will the transaction change to SUCCESS?">
    Yes, subscription may move to SUCCESS state or it may move to FAILED state based on bank’s confirmation. But the subscription state will move to terminal state.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="If a periodic subscription transaction is in the INITIALISED state and the subscription is then moved to the PAUSED state, will the transaction change to SUCCESS?">
    No, the subscription will move to SUCCESS.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I force a PERIODIC subscription from INITIALIZED to PENDING in the sandbox environment?">
    No. A PERIODIC subscription payment moves from `INITIALIZED` to `PENDING` only when its scheduled billing date arrives, and the sandbox environment does not support forcing this transition early. For `ON_DEMAND` subscriptions, trigger an immediate charge by calling `POST /pg/subscriptions/pay` with `subscription_id` and `payment_type: CHARGE` in the request body. Use this as the sandbox-friendly way to test a charge without waiting for a billing cycle.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Are offers supported with Subscriptions?">
    Offers are not currently supported with Subscriptions.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Are the customer's email address and mobile number both required for a UPI AutoPay mandate?">
    Yes. The Subscriptions API requires both `customer_email` and the customer's mobile number to create a UPI AutoPay mandate, and neither field is optional. The API rejects the subscription creation request if either field is missing. If collecting an email address upfront is difficult, capture a valid address during customer onboarding, before you initiate mandate creation.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Where does Cashfree use the customer’s phone number (India and International)?">
    The customer’s phone number is primarily used for sending payment links to customers and sending subscription mandate notifications for recurring payments. It may also be used for transaction-related communication where applicable. This applies to both domestic and international transactions wherever relevant.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Is it mandatory for the merchant to validate the phone number?">
    It is not mandatory for the merchant to perform OTP validation at their end. However, since the customer’s phone number is used to send payment links and important mandate notifications, we expect the number to be accurate. If an incorrect number is provided, the customer may not receive the communication.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Does Cashfree validate the phone number?">
    Yes, Cashfree performs a basic validation check to ensure the phone number is in the correct format. For Indian transactions, this includes verifying that it is a valid 10-digit mobile number. This is only a format-level validation and does not include OTP-based verification.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="When will a subscription be moved to the EXPIRED state?">
    If a subscription remains in the INITIALIZED state and the configured expiry time is reached, and there is no successful authorisation or payment against the subscription (or the authorisation attempt fails), the subscription will continue to remain in the INITIALIZED state. Once the subscription crosses its expiry time, it will be moved to the EXPIRED state.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I debit a lower amount than what was sent in the pre-debit notification (PDN)?">
    No. The debit amount cannot change after the PDN is initiated. If the executed debit amount differs from the amount notified in the PDN, the transaction is declined by the issuing bank due to the amount-match logic enforced at the issuing bank.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="When will a subscription be moved to the COMPLETED state?">
    Once the authorisation payment is successfully completed and the subscription moves to the ACTIVE state, the behaviour is different. Even if the merchant has not specified the number of cycles (max\_cycles), when the subscription reaches its configured expiry time (expires\_on), the subscription will be moved to the COMPLETED state and not the EXPIRED state.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What is the supported timeframe for the charge date in an On-Demand Subscription request?">
    For an On-Demand Subscription, the charge date must be less than 14 days from the request date. If the charge date is outside this 14-day window, the request fails with a `CHARGE_FAILED` error for an invalid schedule date. For periodic subscriptions, the first charge date must also be within this 14-day window. See [First charge date (FCD) for a subscription](/docs/payments/subscription/create#first-charge-date-fcd-for-a-subscription).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Why does a subscription transaction show as Successful in the Recon API but Failed on the Merchant Dashboard?">
    This discrepancy can occur when Cashfree first marks a transaction as Successful and the transaction then fails internal checks. In that case, the transaction can appear as Successful at the transaction level and in reconciliation reports, while Cashfree marks the payment as Failed. Cashfree then initiates a refund for the affected transactions.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What does the Maximum Amount field represent in a subscription plan?">
    The **Maximum Amount** is the upper limit you can charge under a mandate, set through the `plan_max_amount` parameter in the [Create Plan API](/docs/api-reference/payments/latest/subscription/create-a-plan) or the [Create Subscription API](/docs/api-reference/payments/latest/subscription/create-subscription). The customer sees this limit during the authorisation process. If a future charge exceeds this authorised limit, you need a new authorisation or mandate from the customer.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Why are the Card and UPI payment options not visible even though both payment modes are enabled at the account level?">
    If Cards are enabled at the account level but the Card payment option is not displayed during the subscription flow, check the following:

    1. Plan Maximum Amount:
       In both Sandbox and Production, if the `plan_max_amount` configured for the subscription is greater than ₹15,000, Card and UPI payment modes may not be displayed by default due to the applicable mandate limits. Ensure that the `plan_max_amount` is within the supported limit. If you need to support amounts above ₹15,000, the AFA (Additional Factor Authentication) configuration must be enabled. Once AFA is enabled, customers must authenticate each recurring charge using UPI PIN for UPI Autopay, or OTP/2FA for Cards.
    2. Customer Phone Number:
       If the `plan_max_amount` is less than ₹15,000 and Cards are still not visible, ensure that a valid customer phone number is passed while creating the subscription. Dummy phone numbers are blacklisted for Card payment mode and may result in Cards not being displayed.

       <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What is the Max. No. of Debits field in a subscription plan?">
    The Max. No. of Debits defines the maximum number of times you can charge a customer under a specific subscription or mandate, set via the `plan_max_cycles` parameter in the [Create Plan API](/docs/api-reference/payments/latest/subscription/create-a-plan) or the [Create Subscription API](/docs/api-reference/payments/latest/subscription/create-subscription). If you leave it blank, the subscription remains active until its configured expiry date or cancellation.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What does the On Hold status mean for a subscription and how can it be resolved?">
    The On Hold status occurs for NACH and Card standing instructions when a recurring payment fails. To reactivate it, you can retry the failed charge (up to 3 retries per billing cycle) via the Merchant Dashboard or the Manage Payment API. Once the payment succeeds, the subscription resumes.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I offer multiple subscription plans on one Payment Form?">
    Yes. A Subscription Payment Form can have a single plan or multiple plans. Add more plans to the same form when you want customers to choose an option at checkout. Customers select one plan and complete mandate registration for that plan only. See [Subscription Payment Form](/docs/payments/no-code/payment-forms/subscription-payment-form).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What is the default session ID expiry for the Create Subscription API?">
    The default expiry value for the subscription session ID is 2 hours. If the session ID expires, the subscription remains in INITIALISED status. You must generate a new session ID using the [Fetch Subscription API](/docs/api-reference/payments/latest/subscription/fetch-subscription) to open the checkout page again.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Why am I unable to find an old subscription in the Merchant Dashboard even if it was recently updated?">
    When searching for subscriptions in the Merchant Dashboard using date filters, you must use the original creation date of the subscription rather than the last updated date. If a subscription was created in the past but updated recently, set your Merchant Dashboard date range filter to include that original creation period to locate the record.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Where can I find the API documentation for UPI AutoPay integration?">
    You can refer to the following API documentation for UPI AutoPay integration:

    * [Create Subscription](/docs/api-reference/payments/latest/subscription/create-subscription)
    * [Get Subscription](/docs/api-reference/payments/latest/subscription/fetch-subscription)
    * [Manage Subscription](/docs/api-reference/payments/latest/subscription/manage-subscription)
    * [Create Plan](/docs/api-reference/payments/latest/subscription/create-a-plan)
    * [Raise a Charge](/docs/api-reference/payments/latest/subscription/raise-a-charge-or-create-an-auth)

      <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How does the charge flow work for merchant-controlled UPI subscriptions compared to Cashfree-controlled ones?">
    In the Merchant-Controlled flow, the `payment_type` field is not used. Instead, the merchant handles notification and execution separately using specific APIs (`notify-mandate` and `execute-mandate`). The `payment_type` field is only applicable to Cashfree-controlled flows, where a single API call triggers both the pre-debit notification and the charge.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What is the minimum gap required between a successful pre-debit notification and execution for UPI mandates?">
    A 25-hour window is required between a successful pre-debit notification and the execution of the charge. This logic and restriction apply to both the Sandbox and Production environments.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Is there an enablement process or lead time required to start using merchant-controlled UPI mandate APIs in production?">
    No separate enablement process or lead time is required. You can start using the merchant-controlled APIs directly in Production and migrate subscriptions gradually.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How do I cancel or revoke a mandate if I am integrated with Cashfree through Juspay?">
    If you are using Juspay as a payment orchestrator for Cashfree subscriptions, you should not call Cashfree's Cancel Subscription API directly. Instead, use [Juspay's Revoke Mandate API](https://juspay.io/in/docs/api-reference/docs/express-checkout/revoke-mandate-api). Juspay internally maps their `mandateId` to Cashfree's `subscription_id` and handles the underlying cancellation with Cashfree and the NPCI.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I pass a customer_id in the Create Subscription API?">
    The `customer_id` parameter is not supported in the Subscription APIs. It belongs to Payment Gateway order APIs, including the [Create Order API](/docs/api-reference/payments/latest/orders/create-order). If you pass `customer_id` in a [Create Subscription API](/docs/api-reference/payments/latest/subscription/create-subscription) request, Cashfree does not capture, store, or display the value in the Merchant Dashboard.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What is the maximum transaction limit for UPI AutoPay mandates in On-Demand Subscriptions?">
    UPI AutoPay mandate limits follow the payment method caps for subscriptions: ₹15,000 without Additional Factor Authentication (AFA), and ₹1,00,000 with AFA. This cap is set by the payment ecosystem, not by Cashfree, so it cannot be changed at the gateway level. If a charge exceeds the authorised mandate limit, request a new authorisation from the customer. See `plan_max_amount` on the [Create Plan API](/docs/api-reference/payments/latest/subscription/create-a-plan) and the [Create Subscription API](/docs/api-reference/payments/latest/subscription/create-subscription).

    To enable AFA for charges of ₹15,000 and above, raise a request through the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1). For the full payment-method limits, see [Supported Payment Methods](/docs/payments/subscription/payment-modes).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How can I include a Customer Reference ID in the Subscription report?">
    To include a customer reference ID or other custom identifiers in the Subscription report, pass the value in `subscription_tags` when you create the subscription. The value then appears in the Subscription report in the Merchant Dashboard. See `subscription_tags` on the [Create Subscription API](/docs/api-reference/payments/latest/subscription/create-subscription).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What is the difference between ON_DEMAND and Periodic (monthly) subscription plans?">
    A subscription plan is the template that defines how you debit a customer after they authorise a mandate. You set the plan type with `plan_type` on the [Create Plan API](/docs/api-reference/payments/latest/subscription/create-a-plan) or the [Create Subscription API](/docs/api-reference/payments/latest/subscription/create-subscription). Cashfree supports two types: `PERIODIC` for a fixed amount on a fixed schedule, and `ON_DEMAND` for a variable amount that you trigger when you need it. Monthly billing is one `PERIODIC` interval (`MONTH`), not a third plan type.

    The two types differ as follows:

    * **PERIODIC**: Cashfree automatically debits a fixed recurring amount (`plan_amount`) on the schedule you set with `plan_interval_type` (`DAY`, `WEEK`, `MONTH`, or `YEAR`) and `plan_intervals`. Use this for memberships, retainers, or any charge that repeats on a known cycle.
    * **ON\_DEMAND**: You trigger each charge yourself, for a variable amount up to `plan_max_amount`, at the time you choose. Cashfree does not run a billing schedule, and `next_schedule_date` is `null`. Use this for utility bills or usage-based billing. Raise charges from the Merchant Dashboard or the [Charge Subscription API](/docs/api-reference/payments/latest/subscription/raise-a-charge-or-create-an-auth).

    `CHANGE_PLAN` and `PAUSE` are not supported for On-Demand subscriptions. See [Subscriptions Overview](/docs/payments/subscription/introduction).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How can I initiate a refund for a subscription payment?">
    To refund a subscription payment, including the initial authorisation payment or a later charge, use the [Create Subscription Refund API](/docs/api-reference/payments/latest/subscription/create-a-refund). The request requires the following parameters:

    * `subscription_id`
    * `payment_id`
    * `refund_id`
    * `refund_amount`

    Pass a partial amount in `refund_amount` to issue a partial refund.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Why are customer bank account and IFSC details missing from the Create Subscription API response?">
    The [Create Subscription API](/docs/api-reference/payments/latest/subscription/create-subscription) returns customer bank account details such as account number and IFSC only when the subscription Third Party Validation (TPV) flag is enabled for your merchant ID. This flag is separate from Payment Gateway TPV. If subscription TPV is enabled, pass `customer_bank_account_number` and at least one of `customer_bank_ifsc` or `customer_bank_code` in the request.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How can a partner integrate with Cashfree Subscriptions on behalf of a merchant?">
    To call Subscription APIs on behalf of a merchant, use the [Subscriptions API](/docs/api-reference/payments/latest/subscription/overview) with partner authentication headers instead of `x-client-id` and `x-client-secret`. Include the following headers:

    * `x-partner-apikey`: your partner API key
    * `x-partner-merchantid`: the merchant ID
    * `x-api-version`: a current Payments API version, such as `2025-01-01` or `2026-01-01`

    See [API authentication](/docs/api-reference/authentication).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Is the Bank UTR or RRN available in the SUBSCRIPTION_PAYMENT_SUCCESS webhook?">
    The `SUBSCRIPTION_PAYMENT_SUCCESS` webhook does not include the bank UTR or RRN (`bank_reference`). Use the `cf_payment_id` from the webhook to find the transaction in the Merchant Dashboard and read the UTR from the transaction details. See [Subscription Webhooks](/docs/api-reference/payments/latest/subscription/webhooks).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Why are some of my subscription plans not visible in the Merchant Dashboard dropdown?">
    The Merchant Dashboard displays only subscription plans created within the past two years. Plans older than two years cannot be accessed in the Merchant Dashboard dropdown.

    Older plans are not deleted and remain active. You can still use them through the Cashfree APIs without needing to recreate them.

    To view older plans or subscriptions, use the **Custom Date** filter and specify a date range that includes the period when the plan or subscription was originally created. You can then use the search and filter functions to find specific plan IDs.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I set the authorisation amount to zero for UPI or Card subscriptions?">
    No. For UPI and Card payment methods, the authorisation amount cannot be set to ₹0. A ₹0 authorisation amount is supported only for eNACH (Netbanking). If you set it to ₹0 for UPI, Cashfree deducts a ₹1 authorisation amount from the customer's account.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How do I resolve the 'Split creation failed' error when using subscription_payment_splits?">
    The `Split creation failed` error typically occurs if Easy Split is not enabled for your account or if the vendors are not correctly configured. Ensure that:

    * Easy Split is enabled at the account level. Contact your account manager, or fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1), to enable this for your sandbox and production accounts.
    * The `vendor_id` used in the request already exists in your account.
    * The vendor is in an `ACTIVE` state before using it in a subscription request.

      <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How can I implement a subscription with a trial period and an initial authorisation charge?">
    To set up a subscription with a trial period (for example, 3 days) and an initial authorisation fee, follow these steps:

    1. **Create a Plan**: Use the [Create Plan API](/docs/api-reference/payments/latest/subscription/create-a-plan) with `plan_type: PERIODIC`, `plan_interval_type: MONTH`, and the recurring amount in `plan_recurring_amount`.

    2. **Create the Subscription**: Use the [Create Subscription API](/docs/api-reference/payments/latest/subscription/create-subscription) with the following parameters:

       * `authorization_details.authorization_amount`: Set to `1` to charge ₹1 instantly for mandate setup.
       * `authorization_details.authorization_amount_refund`: Set to `false` to keep the ₹1 as a trial fee, or `true` to refund it after authorisation.
       * `subscription_first_charge_time`: Set this to the date when the trial ends (for example, 3 days from the authorisation date). The first recurring charge will trigger on this date.

       <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How do I enable email and SMS notifications when creating a subscription through the Merchant Dashboard?">
    When you create a subscription in the Merchant Dashboard, select **Email** and **SMS** to enable notifications.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Why am I not receiving webhooks for refunds on subscription authorisation transactions?">
    For subscription authorisation transactions, the `authorization_amount_refund` parameter that you set during subscription creation determines the refund behaviour. If you initiate a refund through the Merchant Dashboard, Cashfree triggers the `REFUND_STATUS` webhook event. If this event is not enabled in your webhook configuration, Cashfree does not send a notification. Make sure that you enable `REFUND_STATUS` in your Payment Gateway webhook settings.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Why am I getting a 405 Method Not Allowed error on my return_url after a subscription authorisation?">
    After a subscription authorisation payment is completed, Cashfree sends a POST request to the `return_url`. If your `return_url` points to a frontend page that only handles GET requests, it returns a 405 error.

    To resolve this, use one of the following options:

    * Use a backend endpoint as the `return_url` that accepts POST requests.
    * Configure your frontend route to accept both GET and POST methods.
    * Use the `SUBSCRIPTION_PAYMENT_STATUS` webhook to handle payment status updates, and use the `return_url` only for customer redirection.

      <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Are there specific validations for percentage values in subscription payment splits?">
    Percentage values in `subscription_payment_splits` follow Easy Split rules. Keep the following in mind:

    * Each vendor `percentage` must be greater than `0`.
    * The total of all vendor percentages cannot exceed `100`.
    * Any remaining percentage stays with you as the merchant.

    You can pass decimal values, for example, `12.05`.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Are there any charges for processing normal refunds for domestic subscription payments?">
    For domestic payments (both one-time and subscription payments), no additional charges apply for processing normal refunds, whether they are partial or full refunds. Normal refunds take 5–10 working days to process.

    <Note>
      Platform fees, transaction discount rate (TDR) charges, and flat subscription fees that Cashfree collects at the time of the transaction are not reversed when you initiate a refund. Cashfree retains these fees.
    </Note>

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How do I refund a subscription payment using the API, and are partial refunds supported?">
    To refund a subscription payment, use the dedicated [Subscription Refund API](/docs/api-reference/payments/latest/subscription/create-a-refund). You don't need to create a separate payment gateway order.

    **Endpoint (Production):** `POST https://api.cashfree.com/pg/subscriptions/{subscription_id}/refunds`

    Cashfree supports partial refunds. You can specify a `refund_amount` lower than the original payment amount. The request body must include the `subscription_id`, `payment_id` (or `cf_payment_id`), a unique `refund_id`, and the `refund_amount`.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What is the maximum time period within which a refund can be initiated for a subscription payment?">
    Cashfree supports initiating a refund for a subscription payment only up to 6 months (approximately 180 days) from the transaction success time. After this period, refund initiation is not allowed.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I use the CHANGE_PLAN action to upgrade a customer to a plan whose charges exceed the original mandate limit?">
    No. The `CHANGE_PLAN` action does not support charging an amount that exceeds the `plan_max_amount` defined in the original plan. The `plan_max_amount` is the maximum mandate amount captured during the initial authorisation. If the new plan's charges exceed the original `plan_max_amount`, you can't use `CHANGE_PLAN` for the upgrade.

    To move a customer to a plan where charges exceed their current mandate limit, follow these steps:

    1. Create a new plan with the higher `plan_max_amount` or recurring amount.
    2. Create a new subscription (mandate) authorisation for the customer against this higher maximum so they re-authorise the higher cap.
    3. Start charging on the new subscription and cancel or expire the old one, depending on your business flow.

    To prevent this scenario in the future, you can set the `plan_max_amount` to the highest amount you might ever need to charge across tiers during initial setup, while keeping `plan_recurring_amount` at the current tier's price.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Why can't I activate a paused subscription?">
    You can't move a subscription from PAUSED to ACTIVE if any of the following conditions apply:

    * **Subscription expiry**: If the `subscription_expiry_time` has passed while the subscription was paused, it moves to EXPIRED status and you can't reactivate it. You must create a new subscription.
    * **Max cycles reached**: If the subscription has already completed the maximum number of cycles defined by the plan's `plan_max_cycles`, you can't reactivate it.
    * **Mandate revocation**: If the customer revoked their UPI AutoPay mandate from their bank or UPI app while the subscription was paused, the underlying mandate is no longer valid.

    To check the current status and expiry, use the [Fetch Subscription API](/docs/api-reference/payments/latest/subscription/fetch-subscription).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How do I resume or activate a paused subscription using the API?">
    To resume a paused subscription, use the [Manage Subscription API](/docs/api-reference/payments/latest/subscription/manage-subscription) with the `ACTIVATE` action. Include the `x-api-version` header in the request. The `ACTIVATE` action requires `action_details.next_scheduled_time`. Cashfree uses only the date component of this value.

    If the customer paused the mandate from their UPI app, only the customer can resume it. See [Can I resume a mandate if my customer has paused it?](#can-i-resume-a-mandate-if-my-customer-has-paused-it)

    ```http theme={"dark"}
    POST /pg/subscriptions/{subscription_id}/manage
    x-api-version: 2025-01-01
    Content-Type: application/json

    {
      "subscription_id": "<SUBSCRIPTION_ID>",
      "action": "ACTIVATE",
      "action_details": {
        "next_scheduled_time": "2026-10-01T00:00:00+05:30"
      }
    }
    ```

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are the common reasons for the Subscription Charge API to fail?">
    Common reasons the [Subscription Charge API](/docs/api-reference/payments/latest/subscription/raise-a-charge-or-create-an-auth) (`POST /pg/subscriptions/pay`) fails include the following:

    * **Subscription status**: You can raise charges only on subscriptions in ACTIVE status. If the mandate is pending or in ACTION\_REQUIRED, Cashfree rejects the charge.
    * **Payment amount**: The charge amount must not exceed the `plan_max_amount` configured for the subscription.
    * **Payment ID reuse**: Each charge attempt must use a unique `payment_id`. Reusing an ID from a prior attempt results in a duplicate rejection.
    * **Timing**: The charge can fail if you raise it before the `subscription_first_charge_time`.
    * **Mandate validity**: The charge fails if the mandate has expired or the customer has revoked it (CANCELLED).

      <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Is there an API to get a direct web journey link for eNACH mandate authentication after creating a subscription?">
    Cashfree does not provide a standalone API that returns a permanent mandate link independent of a session, and there is no generic Cashfree URL for this journey. If you build your own web journey using the `subscription_session_id` returned when you create the subscription, the redirect URL is specific to your integration.

    To get a ready-to-use link instead, use the [Create Payment Link API](/docs/api-reference/payments/latest/payment-links/create-payment-link) (`POST /pg/links`) with an inline subscription object to generate a `link_url` that customers can open directly in any browser to complete the mandate flow (such as UPI or eMandate) without requiring SDK integration. See [How do I create a subscription using a Payment Link?](#how-do-i-create-a-subscription-using-a-payment-link) for details.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How do I create a subscription using a Payment Link?">
    You can use the [Create Payment Link API](/docs/api-reference/payments/latest/payment-links/create-payment-link) (`POST /pg/links`) with an inline subscription object to generate a `link_url` for mandate authorisation. Customers can open the `link_url` in the response directly in any browser to complete the mandate flow (such as UPI or eMandate) without requiring SDK integration. Set `link_notify.send_sms` and `link_notify.send_email` to `false` if you want to handle notifications yourself. Cashfree creates the plan when it creates the link.

    **ON\_DEMAND subscription example:**

    ```json theme={"dark"}
    {
      "link_id": "<LINK_ID>",
      "link_amount": 0.00,
      "link_currency": "INR",
      "link_purpose": "On-demand subscription mandate",
      "customer_details": {
        "customer_phone": "<CUSTOMER_PHONE>"
      },
      "subscription": {
        "authorization_amount": 2.00,
        "authorization_amount_refund": true,
        "subscription_expiry_time": "2026-12-31T23:59:59+05:30",
        "plan_details": {
          "plan_id": "<PLAN_ID>",
          "plan_name": "On-demand Plan",
          "plan_type": "ON_DEMAND",
          "plan_currency": "INR",
          "plan_max_amount": 5000.00,
          "plan_max_cycles": 0
        }
      }
    }
    ```

    **PERIODIC subscription example** (shows only the `subscription` object; include the same top-level `link_*` and `customer_details` fields as the ON\_DEMAND example):

    ```json theme={"dark"}
    {
      "subscription": {
        "authorization_amount": 2.00,
        "subscription_first_charge_time": "2026-09-10T00:00:00+05:30",
        "plan_details": {
          "plan_id": "<PLAN_ID>",
          "plan_name": "Monthly Plan",
          "plan_type": "PERIODIC",
          "plan_currency": "INR",
          "plan_amount": 199.00,
          "plan_max_amount": 199.00,
          "plan_intervals": 1,
          "plan_interval_type": "MONTH"
        }
      }
    }
    ```

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I use a default mobile number in the Create Order API if the customer's number is unavailable?">
    Yes. If the customer's mobile number is unavailable, you may provide a default number in the Create Order API. You must inform your Account Manager of the specific number you are using as the default. This prevents transactions from being blocked or flagged by risk and velocity checks.
  </Accordion>

  <Accordion title="How can I restrict the checkout page to show only UPI Autopay for subscriptions?">
    To show only UPI Autopay and hide other payment methods such as Bank Account or Credit/Debit Card, pass the specific payment method in the `authorization_details` object during subscription creation. If no payment method filters are passed, all available modes are displayed by default. Refer to the [`payment_methods` parameter documentation](/docs/api-reference/payments/latest/subscription/create-subscription#body-authorization-details-payment-methods) for details.
  </Accordion>
</AccordionGroup>


# Generate Transaction Return Summary
Source: https://www.cashfree.com/docs/payments/subscription/generate-transaction-summary

Use the Generate Transaction Return Summary API to retrieve summaries for failed Cashfree Subscriptions charges caused by issues like insufficient bank balance.



# Web Integration
Source: https://www.cashfree.com/docs/payments/subscription/hosted-checkout

Integrate Cashfree's pre-built, PCI-compliant hosted web checkout to collect subscription mandates without building your own checkout page.

Cashfree's web checkout offers a secure, pre-built interface for collecting subscription mandate authorisations. It supports cards, UPI AutoPay, and eNACH, so you can start recurring payments without building or hosting your own checkout page.

## Prerequisites

Complete these steps before you integrate hosted subscription checkout:

1. Create a Cashfree merchant account.
2. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
3. Go to **Payment Gateway > Developers > API Keys** and generate your test client ID and secret key.

## Step 1: Create a plan

Create a subscription plan before you open hosted checkout. Use the [Create Plan API](/docs/api-reference/payments/latest/subscription/create-a-plan) to define the plan.

<CodeGroup>
  ```json cURL theme={"dark"}
  curl --request POST \
    --url https://sandbox.cashfree.com/pg/plans \
    --header 'accept: application/json' \
    --header 'content-type: application/json' \
    --header 'x-api-version: 2025-08-01' \
    --header 'x-client-id: xyz' \
    --header 'x-client-secret: abc' \
    --data '{
  	"plan_id": "plan_cashfree_sbox",
  	"plan_name": "Premium_10",
  	"plan_type": "ON_DEMAND",
  	"plan_currency": "INR",
  	"plan_max_amount": 100,
  	"plan_note": "Test Plan Cashfree"
  }'
  ```

  ```javascript Node.js theme={"dark"}
  const options = {
    method: 'POST',
    headers: {
      accept: 'application/json',
      'content-type': 'application/json',
      'x-api-version': '2025-08-01',
      'x-client-id': 'xyz',
      'x-client-secret': 'abc'
    },
    body: JSON.stringify({
      plan_id: 'plan_cashfree_sbox',
      plan_name: 'Premium_10',
      plan_type: 'ON_DEMAND',
      plan_currency: 'INR',
      plan_max_amount: 100,
      plan_note: 'Test Plan Cashfree'
    })
  };

  fetch('https://sandbox.cashfree.com/pg/plans', options)
    .then(response => response.json())
    .then(response => console.log(response))
    .catch(err => console.error(err));
  ```

  ```python Python theme={"dark"}
  import requests

  url = "https://sandbox.cashfree.com/pg/plans"

  payload = {
      "plan_id": "plan_cashfree_sbox",
      "plan_name": "Premium_10",
      "plan_type": "ON_DEMAND",
      "plan_currency": "INR",
      "plan_max_amount": 100,
      "plan_note": "Test Plan Cashfree"
  }
  headers = {
      "accept": "application/json",
      "content-type": "application/json",
      "x-api-version": "2025-08-01",
      "x-client-id": "xyz",
      "x-client-secret": "abc"
  }

  response = requests.post(url, json=payload, headers=headers)
  print(response.text)
  ```

  ```java Java theme={"dark"}
  OkHttpClient client = new OkHttpClient();

  MediaType mediaType = MediaType.parse("application/json");
  RequestBody body = RequestBody.create(mediaType, "{\"plan_id\":\"plan_cashfree_sbox\",\"plan_name\":\"Premium_10\",\"plan_type\":\"ON_DEMAND\",\"plan_currency\":\"INR\",\"plan_max_amount\":100,\"plan_note\":\"Test Plan Cashfree\"}");
  Request request = new Request.Builder()
    .url("https://sandbox.cashfree.com/pg/plans")
    .post(body)
    .addHeader("accept", "application/json")
    .addHeader("content-type", "application/json")
    .addHeader("x-api-version", "2025-08-01")
    .addHeader("x-client-id", "xyz")
    .addHeader("x-client-secret", "abc")
    .build();

  Response response = client.newCall(request).execute();
  ```

  ```php PHP theme={"dark"}
  <?php
  $curl = curl_init();
  curl_setopt_array($curl, [
    CURLOPT_URL => "https://sandbox.cashfree.com/pg/plans",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "{\"plan_id\":\"plan_cashfree_sbox\",\"plan_name\":\"Premium_10\",\"plan_type\":\"ON_DEMAND\",\"plan_currency\":\"INR\",\"plan_max_amount\":100,\"plan_note\":\"Test Plan Cashfree\"}",
    CURLOPT_HTTPHEADER => [
      "accept: application/json",
      "content-type: application/json",
      "x-api-version: 2025-08-01",
      "x-client-id: xyz",
      "x-client-secret: abc"
    ],
  ]);
  $response = curl_exec($curl);
  $err = curl_error($curl);
  curl_close($curl);
  echo $response;
  ```

  ```go Go theme={"dark"}
  package main

  import (
  	"fmt"
  	"strings"
  	"net/http"
  	"io/ioutil"
  )

  func main() {
  	url := "https://sandbox.cashfree.com/pg/plans"
  	payload := strings.NewReader("{\"plan_id\":\"plan_cashfree_sbox\",\"plan_name\":\"Premium_10\",\"plan_type\":\"ON_DEMAND\",\"plan_currency\":\"INR\",\"plan_max_amount\":100,\"plan_note\":\"Test Plan Cashfree\"}")
  	req, _ := http.NewRequest("POST", url, payload)
  	req.Header.Add("accept", "application/json")
  	req.Header.Add("content-type", "application/json")
  	req.Header.Add("x-api-version", "2025-08-01")
  	req.Header.Add("x-client-id", "xyz")
  	req.Header.Add("x-client-secret", "abc")
  	res, _ := http.DefaultClient.Do(req)
  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)
  	fmt.Println(string(body))
  }
  ```
</CodeGroup>

### Response

Once the request is successful, you will receive a response as shown below:

```json theme={"dark"}
{
	"plan_currency": "INR",
	"plan_id": "plan_cashfree_sbox",
	"plan_interval_type": null,
	"plan_intervals": null,
	"plan_max_amount": 100,
	"plan_max_cycles": null,
	"plan_name": "Premium_10",
	"plan_note": "Test Plan Cashfree",
	"plan_recurring_amount": 0,
	"plan_status": "ACTIVE",
	"plan_type": "ON_DEMAND"
}
```

## Step 2: Create subscription

API Documentation: [Create Subscription](/docs/api-reference/payments/latest/subscription/create-subscription)

<CodeGroup>
  ```json cURL theme={"dark"}
  curl --request POST \
    --url https://sandbox.cashfree.com/pg/subscriptions \
    --header 'accept: application/json' \
    --header 'content-type: application/json' \
    --header 'x-api-version: 2025-01-01' \
    --header 'x-client-id: xyz' \
    --header 'x-client-secret: abc' \
    --data '{
  	"customer_details": {
  		"customer_name": "Sushane Yadav",
  		"customer_email": "sushane.yadav@abc.com",
  		"customer_phone": "9999999999",
  		"customer_bank_account_holder_name": "Sushane Yadav",
  		"customer_bank_account_number": "010080198715",
  		"customer_bank_ifsc": "ICIC0001008",
  		"customer_bank_code": "ICIC",
  		"customer_bank_account_type": "SAVINGS"
  	},
  	"plan_details": {
  		"plan_id": "plan_cashfree_sbox",
  		"plan_name": "Premium_09",
  		"plan_type": "ON_DEMAND"
  	},
  	"authorization_details": {
  		"authorization_amount": 1,
  		"authorization_amount_refund": true,
  		"authorization_time": 1
  	},
  	"subscription_tags": {
  		"subscription_note": "test create subs"
  	},
  	"subscription_meta": {
  		"return_url": "https://wa.me/8473222?textPayment%20Successfull",
  		"notification_channel": [
  			"EMAIL",
  			"SMS"
  		]
  	},
  	"subscription_id": "create-ondemand-subs-12",
  	"subscription_expiry_time": "2028-12-24T14:15:22Z"
  }'
  ```

  ```javascript Node.js theme={"dark"}
  const options = {
    method: 'POST',
    headers: {
      accept: 'application/json',
      'content-type': 'application/json',
      'x-api-version': '2025-01-01',
      'x-client-id': 'xyz',
      'x-client-secret': 'abc'
    },
    body: JSON.stringify({
      customer_details: {
        customer_name: 'Sushane Yadav',
        customer_email: 'sushane.yadav@abc.com',
        customer_phone: '9999999999',
        customer_bank_account_holder_name: 'Sushane Yadav',
        customer_bank_account_number: '010080198715',
        customer_bank_ifsc: 'ICIC0001008',
        customer_bank_code: 'ICIC',
        customer_bank_account_type: 'SAVINGS'
      },
      plan_details: {
        plan_id: 'plan_cashfree_sbox',
        plan_name: 'Premium_09',
        plan_type: 'ON_DEMAND'
      },
      authorization_details: {
        authorization_amount: 1,
        authorization_amount_refund: true,
        authorization_time: 1
      },
      subscription_tags: {
        subscription_note: 'test create subs'
      },
      subscription_meta: {
        return_url: 'https://wa.me/8473222?textPayment%20Successfull',
        notification_channel: ['EMAIL', 'SMS']
      },
      subscription_id: 'create-ondemand-subs-12',
      subscription_expiry_time: '2028-12-24T14:15:22Z'
    })
  };

  fetch('https://sandbox.cashfree.com/pg/subscriptions', options)
    .then(response => response.json())
    .then(response => console.log(response))
    .catch(err => console.error(err));
  ```

  ```python Python theme={"dark"}
  import requests

  url = "https://sandbox.cashfree.com/pg/subscriptions"

  payload = {
      "customer_details": {
          "customer_name": "Sushane Yadav",
          "customer_email": "sushane.yadav@abc.com",
          "customer_phone": "9999999999",
          "customer_bank_account_holder_name": "Sushane Yadav",
          "customer_bank_account_number": "010080198715",
          "customer_bank_ifsc": "ICIC0001008",
          "customer_bank_code": "ICIC",
          "customer_bank_account_type": "SAVINGS"
      },
      "plan_details": {
          "plan_id": "plan_cashfree_sbox",
          "plan_name": "Premium_09",
          "plan_type": "ON_DEMAND"
      },
      "authorization_details": {
          "authorization_amount": 1,
          "authorization_amount_refund": True,
          "authorization_time": 1
      },
      "subscription_tags": {"subscription_note": "test create subs"},
      "subscription_meta": {
          "return_url": "https://wa.me/8473222?textPayment%20Successfull",
          "notification_channel": ["EMAIL", "SMS"]
      },
      "subscription_id": "create-ondemand-subs-12",
      "subscription_expiry_time": "2028-12-24T14:15:22Z"
  }
  headers = {
      "accept": "application/json",
      "content-type": "application/json",
      "x-api-version": "2025-01-01",
      "x-client-id": "xyz",
      "x-client-secret": "abc"
  }

  response = requests.post(url, json=payload, headers=headers)
  print(response.text)
  ```

  ```java Java theme={"dark"}
  OkHttpClient client = new OkHttpClient();

  MediaType mediaType = MediaType.parse("application/json");
  RequestBody body = RequestBody.create(mediaType, "{\"customer_details\":{\"customer_name\":\"Sushane Yadav\",\"customer_email\":\"sushane.yadav@abc.com\",\"customer_phone\":\"9999999999\",\"customer_bank_account_holder_name\":\"Sushane Yadav\",\"customer_bank_account_number\":\"010080198715\",\"customer_bank_ifsc\":\"ICIC0001008\",\"customer_bank_code\":\"ICIC\",\"customer_bank_account_type\":\"SAVINGS\"},\"plan_details\":{\"plan_id\":\"plan_cashfree_sbox\",\"plan_name\":\"Premium_09\",\"plan_type\":\"ON_DEMAND\"},\"authorization_details\":{\"authorization_amount\":1,\"authorization_amount_refund\":true,\"authorization_time\":1},\"subscription_tags\":{\"subscription_note\":\"test create subs\"},\"subscription_meta\":{\"return_url\":\"https://wa.me/8473222?textPayment%20Successfull\",\"notification_channel\":[\"EMAIL\",\"SMS\"]},\"subscription_id\":\"create-ondemand-subs-12\",\"subscription_expiry_time\":\"2028-12-24T14:15:22Z\"}");
  Request request = new Request.Builder()
    .url("https://sandbox.cashfree.com/pg/subscriptions")
    .post(body)
    .addHeader("accept", "application/json")
    .addHeader("content-type", "application/json")
    .addHeader("x-api-version", "2025-01-01")
    .addHeader("x-client-id", "xyz")
    .addHeader("x-client-secret", "abc")
    .build();

  Response response = client.newCall(request).execute();
  ```

  ```php PHP theme={"dark"}
  <?php
  $curl = curl_init();
  curl_setopt_array($curl, [
    CURLOPT_URL => "https://sandbox.cashfree.com/pg/subscriptions",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "{\"customer_details\":{\"customer_name\":\"Sushane Yadav\",\"customer_email\":\"sushane.yadav@abc.com\",\"customer_phone\":\"9999999999\",\"customer_bank_account_holder_name\":\"Sushane Yadav\",\"customer_bank_account_number\":\"010080198715\",\"customer_bank_ifsc\":\"ICIC0001008\",\"customer_bank_code\":\"ICIC\",\"customer_bank_account_type\":\"SAVINGS\"},\"plan_details\":{\"plan_id\":\"plan_cashfree_sbox\",\"plan_name\":\"Premium_09\",\"plan_type\":\"ON_DEMAND\"},\"authorization_details\":{\"authorization_amount\":1,\"authorization_amount_refund\":true,\"authorization_time\":1},\"subscription_tags\":{\"subscription_note\":\"test create subs\"},\"subscription_meta\":{\"return_url\":\"https://wa.me/8473222?textPayment%20Successfull\",\"notification_channel\":[\"EMAIL\",\"SMS\"]},\"subscription_id\":\"create-ondemand-subs-12\",\"subscription_expiry_time\":\"2028-12-24T14:15:22Z\"}",
    CURLOPT_HTTPHEADER => [
      "accept: application/json",
      "content-type: application/json",
      "x-api-version: 2025-01-01",
      "x-client-id: xyz",
      "x-client-secret: abc"
    ],
  ]);
  $response = curl_exec($curl);
  $err = curl_error($curl);
  curl_close($curl);
  echo $response;
  ```

  ```go Go theme={"dark"}
  package main

  import (
  	"fmt"
  	"strings"
  	"net/http"
  	"io/ioutil"
  )

  func main() {
  	url := "https://sandbox.cashfree.com/pg/subscriptions"
  	payload := strings.NewReader("{\"customer_details\":{\"customer_name\":\"Sushane Yadav\",\"customer_email\":\"sushane.yadav@abc.com\",\"customer_phone\":\"9999999999\",\"customer_bank_account_holder_name\":\"Sushane Yadav\",\"customer_bank_account_number\":\"010080198715\",\"customer_bank_ifsc\":\"ICIC0001008\",\"customer_bank_code\":\"ICIC\",\"customer_bank_account_type\":\"SAVINGS\"},\"plan_details\":{\"plan_id\":\"plan_cashfree_sbox\",\"plan_name\":\"Premium_09\",\"plan_type\":\"ON_DEMAND\"},\"authorization_details\":{\"authorization_amount\":1,\"authorization_amount_refund\":true,\"authorization_time\":1},\"subscription_tags\":{\"subscription_note\":\"test create subs\"},\"subscription_meta\":{\"return_url\":\"https://wa.me/8473222?textPayment%20Successfull\",\"notification_channel\":[\"EMAIL\",\"SMS\"]},\"subscription_id\":\"create-ondemand-subs-12\",\"subscription_expiry_time\":\"2028-12-24T14:15:22Z\"}")
  	req, _ := http.NewRequest("POST", url, payload)
  	req.Header.Add("accept", "application/json")
  	req.Header.Add("content-type", "application/json")
  	req.Header.Add("x-api-version", "2025-01-01")
  	req.Header.Add("x-client-id", "xyz")
  	req.Header.Add("x-client-secret", "abc")
  	res, _ := http.DefaultClient.Do(req)
  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)
  	fmt.Println(string(body))
  }
  ```
</CodeGroup>

### Response

Once the request is successful, you will receive a response as shown below:

```json theme={"dark"}
{
	"authorization_details": {
		"authorization_amount": 1,
		"authorization_amount_refund": true,
		"authorization_reference": null,
		"authorization_time": null,
		"authorization_status": null,
		"payment_id": null,
		"payment_method": null,
		"instrument_id": null
	},
	"cf_subscription_id": "604456",
	"customer_details": {
		"customer_name": "Sushane Yadav",
		"customer_email": "sushane.yadav@abc.com",
		"customer_phone": "9999999999",
		"customer_bank_account_holder_name": "Sushane Yadav",
		"customer_bank_account_number": "010080198715",
		"customer_bank_ifsc": "ICIC0001008",
		"customer_bank_code": "ICIC",
		"customer_bank_account_type": "SAVINGS"
	},
	"plan_details": {
		"plan_id": "plan_cashfree_sbox",
		"plan_name": "Premium_10",
		"plan_type": "ON_DEMAND",
		"plan_max_cycles": null,
		"plan_recurring_amount": 0,
		"plan_max_amount": 100,
		"plan_interval_type": null,
		"plan_intervals": null,
		"plan_currency": "INR",
		"plan_note": null,
		"plan_status": null
	},
	"subscription_expiry_time": "2028-12-25T01:15:22+05:30",
	"subscription_first_charge_time": null,
	"subscription_id": "create-ondemand-subs-12",
	"subscription_meta": {
		"return_url": "https://wa.me/8473222?textPayment%20Successfull"
	},
	"subscription_payment_splits": null,
	"subscription_session_id": "sub_session_0KnQeY5a63YSnrlk-unL2CuQHV1n4ghoo-laNrHiEL1qgWiytwC_ELZOxjl1AmRm53vh8XT9iTyBECN5KgjAnsu9L9cfzfbCG96rM4T_rZs02q6vsopg3RFXstNZppmlhOytuNMpayment",
	"subscription_status": "INITIALIZED",
	"subscription_tags": {
		"subscription_note": "test create subs"
	}
}
```

## Step 3: Initiate an auth

Use the **subscription\_session\_id** received in the response of create subscription to initiate the subscription auth checkout.

Refer to below code module to integrate :-

<CodeGroup>
  ```javascript javascript theme={"dark"}
  const paymentMessage = document.getElementById("paymentMessage");

  const cashfree = Cashfree({
    mode: "sandbox" // or production
  });

  document.getElementById("subsCheckout").addEventListener("click", function(){
    paymentMessage.innerText = "";
    paymentMessage.classList.remove("alert-danger");
    paymentMessage.classList.remove("alert-success");

    cashfree.subscriptionsCheckout({
      subsSessionId: document.getElementById("subsSessionId").value,
      redirectTarget: "_blank"
    }).then(function(result){
      if(result.error){
        document.getElementById("paymentMessage").innerHTML = (result.error.message)
      }
    })
  })
  ```

  ```html html theme={"dark"}
  <div class="container">
          <div class="row">
              <div class="col">
                  <div class="row">
                      <h2>Demo of Cashfree Subscriptions</h2>
                  </div>
              </div>
          </div>
          <div class="row">
              <div class="col col-lg-8 col-sm-12">
                  <div class="row">
                      <h4>Subscriptions Session ID</h4>
  					
                      <div class="col">
                          <textarea name="" id="subsSessionId" class="form-control"></textarea>
                      </div>
                  </div>
                  <div class="row mt-4">
                      <div class="col ">
                          <p class="alert" id="paymentMessage">

                          </p>
                      </div>
                  </div>
              </div>
              <div class="col col-lg-4 col-sm-10">
                  <div class=" ">
                      <div class="card w-100"  >
                          <div class="card-body w-100 pb-0">
                              <h5 class="card-title">
                                 Subscriptions Checkout
                              </h5>

                              <div class="row">
                                  <div class="col-12 submit-div col" bfor="qr">
                                      <button class="btn btn-block btn-full w-100 btn-primary" id="subsCheckout">
                                          Submit
                                      </button>
                                  </div>
                              </div>
                          </div>
                      </div>
                  </div>
              </div>
          </div>
      </div>
  ```

  ```css css theme={"dark"}
  .card {
    box-shadow: rgba(50, 50, 93, 0.25) 0px 30px 60px -12px, rgba(0, 0, 0, 0.3) 0px 18px 36px -18px;
    padding-bottom: 0px;
    border-radius: 14px;
    float: right;
  }

  .container{
    border-radius: 20px;
    position: absolute;
    top: 50%;
    left: 50%;
    transform: translate(-50%, -50%);
    padding: 20px;
    border: 1px solid #ddd;
  }

  h4{
    color: rgba(0, 0, 0, 0.5);
  }

  .submit-div {
    text-align: center;
    padding: 20px;
    border-top: 1px solid #efefef;
  }
  ```
</CodeGroup>

Try out here: [codepen](https://codepen.io/Harshith-Kanigalpula-the-styleful/pen/MWMJWeN)

1. Take the **subscription\_session\_id** and paste it in the codepen link and click on **Submit**.

<img />

2. You will be redirected to the subscription checkout page.

<img />

3. Choose the payment mode you want to setup the subscription and submit. In case of sandbox you will be asked to simulate the payment.

<img />

4. You will be redirected to the return url post the transaction is completed.

## Step 4: Get subscription details

Use this API to check the subscription status and auth details post completion of the payment.

API Documentation: [Get Subscription](/docs/api-reference/payments/latest/subscription/fetch-subscription)

<CodeGroup>
  ```json cURL theme={"dark"}
  curl --request GET \
    --url https://sandbox.cashfree.com/pg/subscriptions/{subscription_id} \
    --header 'accept: application/json' \
    --header 'x-api-version: 2025-01-01' \
    --header 'x-client-id: xyz' \
    --header 'x-client-secret: abc'
  ```

  ```javascript Node.js theme={"dark"}
  const options = {
    method: 'GET',
    headers: {
      accept: 'application/json',
      'x-api-version': '2025-01-01',
      'x-client-id': 'xyz',
      'x-client-secret': 'abc'
    }
  };

  fetch('https://sandbox.cashfree.com/pg/subscriptions/{subscription_id}', options)
    .then(response => response.json())
    .then(response => console.log(response))
    .catch(err => console.error(err));
  ```

  ```python Python theme={"dark"}
  import requests

  url = "https://sandbox.cashfree.com/pg/subscriptions/{subscription_id}"

  headers = {
      "accept": "application/json",
      "x-api-version": "2025-01-01",
      "x-client-id": "xyz",
      "x-client-secret": "abc"
  }

  response = requests.get(url, headers=headers)
  print(response.text)
  ```

  ```java Java theme={"dark"}
  OkHttpClient client = new OkHttpClient();

  Request request = new Request.Builder()
    .url("https://sandbox.cashfree.com/pg/subscriptions/{subscription_id}")
    .get()
    .addHeader("accept", "application/json")
    .addHeader("x-api-version", "2025-01-01")
    .addHeader("x-client-id", "xyz")
    .addHeader("x-client-secret", "abc")
    .build();

  Response response = client.newCall(request).execute();
  ```

  ```php PHP theme={"dark"}
  <?php
  $curl = curl_init();
  curl_setopt_array($curl, [
    CURLOPT_URL => "https://sandbox.cashfree.com/pg/subscriptions/{subscription_id}",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => [
      "accept: application/json",
      "x-api-version: 2025-01-01",
      "x-client-id: xyz",
      "x-client-secret: abc"
    ],
  ]);
  $response = curl_exec($curl);
  $err = curl_error($curl);
  curl_close($curl);
  echo $response;
  ```

  ```go Go theme={"dark"}
  package main

  import (
  	"fmt"
  	"net/http"
  	"io/ioutil"
  )

  func main() {
  	url := "https://sandbox.cashfree.com/pg/subscriptions/{subscription_id}"
  	req, _ := http.NewRequest("GET", url, nil)
  	req.Header.Add("accept", "application/json")
  	req.Header.Add("x-api-version", "2025-01-01")
  	req.Header.Add("x-client-id", "xyz")
  	req.Header.Add("x-client-secret", "abc")
  	res, _ := http.DefaultClient.Do(req)
  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)
  	fmt.Println(string(body))
  }
  ```
</CodeGroup>

### Response

Once the request is successful, you will receive a response as shown below:

```json theme={"dark"}
{
	"authorization_details": {
		"authorization_amount": 1,
		"authorization_amount_refund": true,
		"authorization_reference": "J7iuqUTKXxoNS17u5oBq4n24jYFAV5@upi",
		"authorization_time": "2024-11-25T22:05:25+05:30",
		"authorization_status": "ACTIVE",
		"payment_id": "513463",
		"payment_method": "upi",
		"instrument_id": null
	},
	"cf_subscription_id": "604456",
	"customer_details": {
		"customer_name": "Sushane Yadav",
		"customer_email": "sushane.yadav@abc.com",
		"customer_phone": "9999999999",
		"customer_bank_account_holder_name": "Sushane Yadav",
		"customer_bank_account_number": "010080198715",
		"customer_bank_ifsc": "ICIC0001008",
		"customer_bank_code": "ICIC",
		"customer_bank_account_type": "SAVINGS"
	},
	"plan_details": {
		"plan_id": "plan_cashfree_sbox",
		"plan_name": "Premium_10",
		"plan_type": "ON_DEMAND",
		"plan_max_cycles": null,
		"plan_recurring_amount": 0,
		"plan_max_amount": 100,
		"plan_interval_type": null,
		"plan_intervals": null,
		"plan_currency": "INR",
		"plan_note": null,
		"plan_status": null
	},
	"subscription_expiry_time": "2028-12-25T01:15:22+05:30",
	"subscription_first_charge_time": null,
	"subscription_id": "create-ondemand-subs-12",
	"subscription_meta": {
		"return_url": "https://wa.me/8473222?textPayment%20Successfull"
	},
	"subscription_payment_splits": null,
	"subscription_session_id": "sub_session_8NDk6JTfSb9elrakgfn8VE_1j_pJ7zEWdWJefDha68ddBjapy6AjlxLLYoObqxLvDYF1nysfWCbu11wPeJmQbub00dadRUs7rPIf1nc33-4F85BNjZV0_3uOdt7rDMkPUesto0wpayment",
	"subscription_status": "ACTIVE",
	"subscription_tags": {
		"subscription_note": "test create subs"
	}
}
```

## Step 5: Raise a charge on subscription

API Documentation: [Raise a charge](/docs/api-reference/payments/latest/subscription/raise-a-charge-or-create-an-auth)

<CodeGroup>
  ```json cURL theme={"dark"}
  curl --request POST \
    --url https://sandbox.cashfree.com/pg/subscriptions/pay \
    --header 'accept: application/json' \
    --header 'content-type: application/json' \
    --header 'x-api-version: 2025-01-01' \
    --header 'x-client-id: xyz' \
    --header 'x-client-secret: abc' \
    --data '{
  	"subscription_id": "create-ondemand-subs-12",
  	"payment_id": "test-payment-subs-07",
  	"payment_type": "CHARGE",
  	"payment_amount": 10,
  	"payment_remarks": "first payment",
  	"payment_schedule_date": "2024-11-30T14:15:22Z"
  }'
  ```

  ```javascript Node.js theme={"dark"}
  const options = {
    method: 'POST',
    headers: {
      accept: 'application/json',
      'content-type': 'application/json',
      'x-api-version': '2025-01-01',
      'x-client-id': 'xyz',
      'x-client-secret': 'abc'
    },
    body: JSON.stringify({
      subscription_id: 'create-ondemand-subs-12',
      payment_id: 'test-payment-subs-07',
      payment_type: 'CHARGE',
      payment_amount: 10,
      payment_remarks: 'first payment',
      payment_schedule_date: '2024-11-30T14:15:22Z'
    })
  };

  fetch('https://sandbox.cashfree.com/pg/subscriptions/pay', options)
    .then(response => response.json())
    .then(response => console.log(response))
    .catch(err => console.error(err));
  ```

  ```python Python theme={"dark"}
  import requests

  url = "https://sandbox.cashfree.com/pg/subscriptions/pay"

  payload = {
      "subscription_id": "create-ondemand-subs-12",
      "payment_id": "test-payment-subs-07",
      "payment_type": "CHARGE",
      "payment_amount": 10,
      "payment_remarks": "first payment",
      "payment_schedule_date": "2024-11-30T14:15:22Z"
  }
  headers = {
      "accept": "application/json",
      "content-type": "application/json",
      "x-api-version": "2025-01-01",
      "x-client-id": "xyz",
      "x-client-secret": "abc"
  }

  response = requests.post(url, json=payload, headers=headers)
  print(response.text)
  ```

  ```java Java theme={"dark"}
  OkHttpClient client = new OkHttpClient();

  MediaType mediaType = MediaType.parse("application/json");
  RequestBody body = RequestBody.create(mediaType, "{\"subscription_id\":\"create-ondemand-subs-12\",\"payment_id\":\"test-payment-subs-07\",\"payment_type\":\"CHARGE\",\"payment_amount\":10,\"payment_remarks\":\"first payment\",\"payment_schedule_date\":\"2024-11-30T14:15:22Z\"}");
  Request request = new Request.Builder()
    .url("https://sandbox.cashfree.com/pg/subscriptions/pay")
    .post(body)
    .addHeader("accept", "application/json")
    .addHeader("content-type", "application/json")
    .addHeader("x-api-version", "2025-01-01")
    .addHeader("x-client-id", "xyz")
    .addHeader("x-client-secret", "abc")
    .build();

  Response response = client.newCall(request).execute();
  ```

  ```php PHP theme={"dark"}
  <?php
  $curl = curl_init();
  curl_setopt_array($curl, [
    CURLOPT_URL => "https://sandbox.cashfree.com/pg/subscriptions/pay",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "{\"subscription_id\":\"create-ondemand-subs-12\",\"payment_id\":\"test-payment-subs-07\",\"payment_type\":\"CHARGE\",\"payment_amount\":10,\"payment_remarks\":\"first payment\",\"payment_schedule_date\":\"2024-11-30T14:15:22Z\"}",
    CURLOPT_HTTPHEADER => [
      "accept: application/json",
      "content-type: application/json",
      "x-api-version: 2025-01-01",
      "x-client-id: xyz",
      "x-client-secret: abc"
    ],
  ]);
  $response = curl_exec($curl);
  $err = curl_error($curl);
  curl_close($curl);
  echo $response;
  ```

  ```go Go theme={"dark"}
  package main

  import (
  	"fmt"
  	"strings"
  	"net/http"
  	"io/ioutil"
  )

  func main() {
  	url := "https://sandbox.cashfree.com/pg/subscriptions/pay"
  	payload := strings.NewReader("{\"subscription_id\":\"create-ondemand-subs-12\",\"payment_id\":\"test-payment-subs-07\",\"payment_type\":\"CHARGE\",\"payment_amount\":10,\"payment_remarks\":\"first payment\",\"payment_schedule_date\":\"2024-11-30T14:15:22Z\"}")
  	req, _ := http.NewRequest("POST", url, payload)
  	req.Header.Add("accept", "application/json")
  	req.Header.Add("content-type", "application/json")
  	req.Header.Add("x-api-version", "2025-01-01")
  	req.Header.Add("x-client-id", "xyz")
  	req.Header.Add("x-client-secret", "abc")
  	res, _ := http.DefaultClient.Do(req)
  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)
  	fmt.Println(string(body))
  }
  ```
</CodeGroup>

### Response

Once the request is successful, you will receive a response as shown below:

```json theme={"dark"}
{
	"action": null,
	"cf_payment_id": "513474",
	"channel": null,
	"data": null,
	"payment_amount": 10,
	"payment_id": "test-payment-subs-07",
	"payment_method": null,
	"payment_status": "INITIALIZED",
	"payment_type": "CHARGE",
	"subscription_id": "create-ondemand-subs-12"
}
```


# Import Mandates
Source: https://www.cashfree.com/docs/payments/subscription/import

Import existing NACH mandates from other gateways into Cashfree via the dashboard and manage every subscription without reauthorising customers.

The **Import Mandates** feature allows you to migrate your existing subscription data from other payment providers to Cashfree. By importing your historical mandate data, you can centrally manage all your active subscriptions directly within the Cashfree ecosystem.

<Note>**Applicable only for eNACH and Physical NACH mandates.**</Note>

Importing mandates offers the following benefits:

* You can do this without requiring additional authorisation from your customer.
* Use a single interface or payment gateway to control all mandates.
* Provide a seamless experience for customers even if you switch from one gateway to another.

## Initiate porting process

Cashfree will assist you throughout the mandate porting process.

<Steps>
  <Step title="Contact Cashfree support">
    Contact the Cashfree support team to initiate the porting process. Nominate Cashfree as your preferred payment processing partner for your Utility Code or mandates.
  </Step>

  <Step title="Partner bank coordination">
    Once you have initiated the process, the Cashfree team will guide you through sharing the list of mandates with your partner bank. This ensures the partner bank's systems are updated to reflect the change.
  </Step>

  <Step title="Import mandates into Cashfree">
    Import the updated list of mandates into Cashfree's system.
  </Step>

  <Step title="Start processing payments">
    Once the mandates are successfully imported, you can begin processing payments through Cashfree.
  </Step>
</Steps>

## Import mandates to Cashfree

To import the mandates, upload a file containing all mandate details in either the NPCI file format or the Cashfree-specified format. After uploading, download the mandate file to check the import status. The file also includes rejection reasons for mandates that could not be imported.

<Frame>
  <img alt="Overview of the mandate import flow in the Subscription Dashboard" />
</Frame>

<Warning>
  Cashfree rejects the file in the following cases:

  * The file format is incorrect (only CSV and XLSX formats are supported), the headers do not match the required format, or all records contain invalid data.
  * If some records are invalid, Cashfree displays a pop-up asking whether to proceed with the valid records or cancel the entire import.

  Cashfree processes the file for valid records only. After processing is complete, you can view the imported subscriptions in the `ACTIVE` state on the **Subscriptions** page.
</Warning>

The Cashfree Subscription object determines how the customer is charged. Mandates are the payment method used to charge customers. You can import mandates from the Subscription Dashboard using the Cashfree format, with a sample file available for download from the Subscription Dashboard.

### File format

| Required field | Description |
| - | - |
| UMRN\_NO | UMRN number of the mandate. Must be 20 characters. |
| PAYMENT\_TYPE | Import mandates is applicable only for NACH. The value must be `E_MANDATE`. |
| DEBIT\_ACCOUNT\_NUMBER | Account number of the customer. Must be a maximum of 35 characters. Ensure leading zeros are not trimmed. |
| DEBIT\_ACCOUNT\_HOLDER\_NAME | Name of the customer. Must be a maximum of 40 characters. |
| DEBIT\_BANK\_ID | Bank ID. Must be the same as the first 4 characters of the UMRN number. |
| DEBIT\_ACCOUNT\_TYPE | Account type. Possible values: `SAVINGS` or `CURRENT`. |
| MAX\_AMOUNT | Maximum amount of the mandate. |
| FREQUENCY | Debit frequency. Possible values: `ADHO` — Adhoc, `WEEK` — Weekly, `MNTH` — Monthly, `BIMN` — Every 2 months, `QURT` — Every 3 months, `MIAN` — Every 6 months, `YEAR` — Yearly. |
| START\_DATE | The date on which the mandate was authorised. This must be on or before the current date. |
| END\_DATE | Expiry date of the mandate. Must be a future date. |
| SUBSCRIPTION\_ID | A unique ID for the subscription. It can include alphanumeric characters, underscore, dot, hyphen, and space. A maximum of 200 characters are allowed. |
| CUSTOMER\_EMAIL | Email ID of the customer. Must be a valid email address. A maximum of 250 characters are allowed. |
| CUSTOMER\_PHONE | Phone number of the customer. Must be a valid phone number, with or without +91. |

**Conditional fields**

| Conditional field | Description |
| - | - |
| FIXED\_AMOUNT | This is the recurring amount for the mandate for the given `FREQUENCY`. Mandatory if `FREQUENCY` is not `ADHO`. |
| FIRST\_CHARGE\_DATE | The first charge date for the mandate after importing. Mandatory if `FREQUENCY` is not `ADHO`. |

**Optional fields**

| Optional field | Description |
| - | - |
| MAX\_CYCLES | The number of charge cycles required before moving the subscription to `COMPLETED` state. |

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/payments/latest/orders/create-order">Create Order API</a></li>
    <li><a href="/docs/api-reference/payments/latest/payments/order-pay">Create Payment Session API</a></li>
    <li><a href="/docs/payments/webhooks">Payment Webhooks</a></li>
    <li><a href="/docs/payments/features/token-vault">Token Vault Overview</a></li>
  </ul>
</div>


# Overview
Source: https://www.cashfree.com/docs/payments/subscription/introduction

Use Cashfree Subscriptions to automate recurring billing across UPI mandates, eNACH, debit cards, and netbanking with one API for the full lifecycle.

Cashfree Subscriptions enables you to automate recurring payment collection from your customers. It streamlines the payment process while providing flexibility in payment schedules and methods.

<Tip>Install [Cashfree Agent Skills](/docs/tools-ai/cashfree-agent-skills) to bring Cashfree product knowledge into your AI coding assistant (Claude Code, Cursor, VS Code Copilot, Gemini CLI, and more) to answer integration questions and generate accurate code without leaving your editor.</Tip>

## What's a mandate

A mandate is a contract between you and your customer that authorises you to debit funds from your customer's account either at a pre-decided frequency or on-demand, up to a pre-decided maximum amount.

Cashfree supports various payment methods that are compliant with RBI regulations. Your customers can pay using:

* **Cards** (both Indian and international)
* **eNACH**
* **UPI Autopay**
* **Physical NACH** (paper-based NACH)

<Tip>Mandates are valid for the maximum amount specified and can be used until the expiry date or the maximum number of debits is reached.</Tip>

## Types of subscriptions

Cashfree supports two types of subscriptions based on how you want to charge your customers:

<CardGroup>
  <Card title="Periodic subscriptions" icon="calendar-days">
    Debit a fixed amount from your customers at fixed intervals (daily, weekly, monthly, or yearly). Ideal for:

    * Monthly or annual membership fees
    * Regular service charges
    * Recurring product deliveries
  </Card>

  <Card title="On-demand subscriptions" icon="bolt">
    Debit variable amounts at any time. Ideal for:

    * Utility bills where the amount changes each cycle
    * Usage-based billing
    * Variable payment schedules

    Charge any amount up to the maximum mandate amount, at any time.
  </Card>
</CardGroup>

## Plans

A plan is a template that defines the terms of a recurring subscription service. Plans include key information that determines the billing structure for a subscription.

<Note>**Example:** Netflix Plans such as Premium, Basic, Standard, and Mobile. Each plan caters to a specific use case with different features and pricing.</Note>

Here's a breakdown of what a plan usually consists of:

| Parameter | Description |
| - | - |
| **Plan Name** | Name of the plan visible to customers during mandate authorisation. |
| **Plan Type** | `Periodic` for fixed amounts at fixed intervals (daily, weekly, monthly, yearly) or `On-Demand` for variable amounts and timing. |
| **Currency** | Currency for maximum and recurring amounts. See [supported currencies](/docs/payments/international-payments/ipg/currencies-supported). |
| **Maximum Amount** | Maximum amount you can charge for this subscription. Mandate is created for this amount. |
| **Recurring Amount** | Amount debited from customer on a recurring basis. |
| **Charge Customer Once Every** | Billing frequency: days, weeks, months, or years. |
| **Max. No. Of Debits** | Maximum number of debits allowed. If blank, subscription expiry date applies. |
| **Description** | Plan description text. |

You can create a new plan either through the dashboard or through the [Create Plan API](/docs/api-reference/payments/latest/subscription/create-a-plan). To provide flexibility for certain use cases, you can also create a subscription without a plan.

To collect recurring payments without writing code, create a [Subscription Payment Form](/docs/payments/no-code/payment-forms/subscription-payment-form). Use a single plan, or add multiple plans so customers choose one plan and complete mandate registration.

## Subscriptions

A subscription represents the relationship between a customer and a plan, indicating that the customer is actively using the service and is being billed on a recurring basis.

| Parameter | Description |
| - | - |
| **Customer Details** | Customer details such as customer name, email, and phone number. Email and phone number are required for triggering communications via email or SMS to your customers. |
| **Subscription ID** | The ID through which the subscription is identified. |
| **Select Plan** | Select an existing plan or create a subscription without a plan. In case no pre-defined plan is to be used, all necessary details will have to be given for this subscription. |
| **Subscription Type** | Select the Subscription Type - Periodic or On-Demand. |
| **Plan Name** | Provide the plan name if you aren't selecting an existing plan. This will be visible to the customer during the mandate authorisation process. |
| **Currency** | Currency in which the maximum amount and recurring amount is to be charged. For the [list of supported currencies](/docs/payments/international-payments/ipg/currencies-supported), see the international payments documentation |
| **Maximum Amount** | The maximum amount you can charge your customer for this subscription. |
| **Recurring Amount** | If the Subscription type is periodic, specify the recurring amount you want to charge your customer as per the agreed payment schedule. |
| **Charge Customer Once Every** | The time interval in which you want to charge your customer. |
| **Max. No. of Debits** | The maximum number of times you want to charge your customer for this subscription. |
| **First Charge Date** | The date on which your customer will be charged for the first time for this subscription. Applicable only for periodic subscriptions. |
| **Subscription Ends** | The date on which this subscription ends. It can end on a particular date or will remain active until you or your customer cancels it. |
| **Expiry Date** | The last date the customer will be charged for this subscription. |
| **Return Address** | The web address to which your customers will be redirected once the subscription is authorised. |

<snippet>snippets/related-topics-loader.mdx</snippet>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/payments/latest/subscription/create-a-plan">Create Plan API</a></li>
    <li><a href="/docs/payments/subscription/faq">FAQs</a></li>
  </ul>
</div>


# Manage Subscriptions
Source: https://www.cashfree.com/docs/payments/subscription/manage

Manage Cashfree subscriptions: cancel active mandates to stop future charges, reactivate cancelled subscriptions, or stop pending charges before debit.

Manage your active subscriptions by updating their status, retrying failed charges, or modifying existing plans and amounts. You can perform these actions manually through the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) or programmatically using the [Subscriptions APIs](/docs/api-reference/payments/latest/subscription/overview).

<Tabs>
  <Tab title="Dashboard">
    Manage your subscriptions manually through the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).

    ### Cancel, pause, or reactivate subscriptions

    Update the status of your subscriptions to handle customer requests or manage temporary service suspensions.

    1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login) and go to **Subscriptions** > **All Subscriptions**.
    2. Select the specific subscription you want to manage.
    3. Select **Manage Subscriptions**.
    4. Choose the required action:
       * **Cancel**: Stops all future charges.
       * **Pause**: Temporarily stops billing until you resume it.
       * **Reactivate**: Resumes billing for a cancelled or paused subscription.

    ### Manage charges

    Manage individual payment cycles by cancelling pending charges or retrying failed transactions.

    The following options are available for managing a scheduled or failed charge:

    * **Cancel**: Stop a pending charge before it is debited.
    * **Retry**: Attempt to collect payment again for a failed charge cycle. If a charge fails due to insufficient funds, the subscription may move to `ON_HOLD`.
    * **Refund**: Issue [refunds](/docs/payments/manage/refunds/overview) for successful subscription payments directly from the transaction details page.

    <Note>
      A maximum of 3 retries are allowed per billing cycle. The system stops further attempts once this limit is reached.
    </Note>

    <Tip>
      Customers can also pause or cancel a mandate directly from their UPI app or net banking portal.
    </Tip>
  </Tab>

  <Tab title="API">
    Automate your subscription lifecycle management using the following APIs:

    * **[Manage Subscription API](/docs/api-reference/payments/latest/subscription/manage-subscription)**: Programmatically cancel, pause, activate, or change the plan associated with a subscription.
      * **To update the recurring amount**: Create a new [plan](/docs/payments/subscription/introduction#plans) with the revised amount and use this API with the `CHANGE_PLAN` action.
      * **Constraints**: The `CHANGE_PLAN` and `PAUSE` actions are not supported for On-Demand Subscriptions.

    * **[Manage Payment API](/docs/api-reference/payments/latest/subscription/manage-a-single-payment)**: Cancel or retry a specific charge before or after processing. A maximum of 3 retries are allowed per billing cycle.

    * **[Refund APIs](/docs/api-reference/payments/latest/subscription/create-a-refund)**: Programmatically initiate and track refunds for subscription payments.

    * [Manage Subscription API](/docs/api-reference/payments/latest/subscription/manage-subscription): Use this to cancel or update a subscription mandate.

    * [Manage Payment API](/docs/api-reference/payments/latest/subscription/manage-a-single-payment): Use this to cancel or update a pending charge.
  </Tab>
</Tabs>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/payments/latest/subscription/manage-subscription">Manage Subscription API</a></li>
    <li><a href="/docs/payments/subscription/create#subscription-lifecycle">Subscription Lifecycle</a></li>
    <li><a href="/docs/payments/subscription/import">Import Mandates</a></li>
    <li><a href="/docs/payments/subscription/webhooks">Subscription Webhooks</a></li>
    <li><a href="/docs/payments/subscription/faq">Subscription FAQs</a></li>
  </ul>
</div>


# Supported Payment Methods
Source: https://www.cashfree.com/docs/payments/subscription/payment-modes

Compare payment methods supported by Cashfree Subscriptions: UPI mandates, debit cards, netbanking, and physical NACH mandates for recurring billing.

Cashfree Subscriptions supports the following payment methods to collect recurring payments from your customers:

* Bank account (e-Mandate + Physical mandate)
* UPI autopay
* Standing Instructions (SI) on cards (credit or debit) (Indian and International)

The following table shows the maximum subscription amounts allowed for each payment method:

| Payment methods supported | Banks or card networks or UPI handles | Maximum subscription amount allowed |
| :- | :- | :- |
| eNACH | Navigate to E-mandate > Live Bank in API E-mandate > Destination bank on the [NPCI site](https://www.npci.org.in/product/nach/all-members) to view or download the list of supported banks | ₹ 1,00,00,000 |
| UPI autopay | Check the [list of banks and PSPs on the NPCI Autopay page](https://www.npci.org.in/what-we-do/autopay/list-of-banks-and-apps-live-on-autopay) | ₹ 15,000 (without AFA) or ₹ 1,00,000 (with AFA) |
| Card (Indian) | Visa, Mastercard, RuPay | ₹ 15,000 (without AFA) or ₹ 1,00,00,000  (with AFA) |
| Card (International) | Visa, Mastercard | ₹ 1,00,00,000 |
| Physical mandates | Supported banks (see Note below) | ₹ 1,00,00,000 |

**Additional Factor Authentication (AFA)**: Customers must authorise the debit by providing additional authentication. For UPI autopay, customers enter their UPI PIN within 30 minutes of receiving the link or PSP app notification. For Standing Instructions (SI) on cards, customers enter a One-Time Password (OTP) or other 2FA as required by the issuing bank, which can be completed any time before 7:00 AM on the scheduled charge date.

<Note>
  UPI autopay and Cards are disabled by default for subscription amounts of ₹15,000 and above. To enable these modes at or above this threshold, up to the higher limits shown in the table, the AFA (Additional Factor Authentication) configuration must be enabled for your account; customers then authenticate each charge as described above. If you need a payment mode that does not require AFA, use eNACH, which supports up to ₹1,00,00,000 without additional authentication. For more information, contact the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1).
</Note>

<Note>
  **Supported banks and PSPs**:

  * **eNACH**: Navigate to E-mandate > Live Bank in API E-mandate > Destination bank on the [NPCI site](https://www.npci.org.in/product/nach/all-members) to view or download the list of supported banks
  * **UPI autopay**: [Banks and PSPs](https://www.npci.org.in/what-we-do/autopay/list-of-banks-and-apps-live-on-autopay)
  * **Physical mandates**: [Supported banks](https://gocashassets.s3.ap-south-1.amazonaws.com/subscriptions/List+of+Bank+Supported+for+Physical+NACH+-+Sheet1.pdf.zip)
</Note>

## Supported payment frequencies

All payment methods support the following frequencies: Day, Week, Month, Year, and ad-hoc.

## Bank account (e-Mandate)

Customers can authorise subscriptions using their bank account via net banking, debit card, or Aadhaar. They must enter their bank account details and authorise the subscription. The payment is debited automatically based on the selected plan.

<Note>
  **Account eligibility**: According to NACH guidelines, e-NACH is permitted only for individual accounts, including both savings and current accounts with a single registered signatory. Corporate current accounts with multiple registered signatories must use physical NACH.

  **Authorisation amount**: There is no authorisation amount charged for e-NACH. The charge is zero (0).
</Note>

### Authorise using a bank account

Complete the following steps on the checkout page to authorise a subscription using a bank account:

1. Select **Bank Account (e-Mandate)** as the payment method.
2. Select their bank and the preferred authorisation mode: Net Banking, debit card, or Aadhaar (depending on availability for the bank).
3. Enter the required details, and approve the subscription.

Check the [list of NPCI-supported banks on the NACH members page](https://www.npci.org.in/product/nach/all-members).

## Bank account (Physical mandate)

Customers can authorise subscriptions using only their signature and bank account details. There is no requirement to have a debit card or net banking enabled to set up the mandate.

The physical NACH form includes several fields that can be pre-filled to simplify the process. Leave the **UMRN** (Unique Mandate Reference Number) field blank when creating a mandate. Cashfree provides values for the **Sponsor Bank Code**, **Utility Code**, and **Authoriser Information**.

Refer to the sample physical mandate below.

<img />

### Pre-fill physical mandate fields

You can pre-fill the following fields to simplify the form completion process:

* **Date**: The date when the form is filled.
* **Frequency**: Select an appropriate option based on your use case: *Monthly*, *Quarterly*, *Half-yearly*, *Yearly*, or *As and when presented*.
* **Amount**: The mandate amount to be debited.
* **Debit type**: Select **Fixed Amount** for recurring payments or **Maximum Amount** for on-demand debits.
* **Reference 1** and **Reference 2** *(optional)*: Use these fields to add internal remarks, subscription IDs, or other identifiers relevant to your system.
* **Period of mandate**: Enter the mandate duration, from the first debit date to the subscription end date. To keep the mandate active until cancelled, select **Until Cancelled**.

After you pre-fill these fields, share the form with the customer. Ask the customer to complete their **bank account details** and **signature**. This reduces manual errors and improves the overall experience.

### Submit completed physical mandate forms

When you receive the completed form, choose one of the following options:

* Use the **Bulk Physical Mandate** feature on the Cashfree dashboard to upload the details, or
* Integrate using the following Cashfree APIs:
  1. **Create subscription**: Use this [API](/docs/api-reference/payments/latest/subscription/create-subscription) to create a subscription for your customer. This includes providing customer and mandate details. If the mandate details such as amount and frequency are the same for all your customers, you can create a plan before creating a subscription. The response provides the list of supported banks applicable for physical mandate.
  2. **Step 2: Upload file**: Use the [Upload File API](/docs/api-reference/payments/latest/subscription/upload-file-for-physical-nach-authorisation) to upload the physical Nach registration forms that contain your customer’s bank account details, mandate details and signature. You will receive a file ID in the response, this needs to be used in the next step.
  3. **Step 3: Create auth seamless physical mandate**: Use the [Create Auth Seamless Physical Mandate API](/docs/api-reference/payments/latest/subscription/raise-a-charge-or-create-an-auth) to create an authorisation request for your customer. For physical mandates, this API informs Cashfree that the NACH form should be submitted to the bank for mandate registration in production. The final authorization status for a Physical NACH (Paper) mandate typically takes between 5 to 10 working days to appear, depending on the bank's processing speed and verification.

## Debit or credit card (issued in India)

Customers can authorise subscriptions using their debit or credit card. They must enter their card details to authorise the subscription, similar to a regular one-time online payment. The payment is automatically debited based on the selected plan. All issuing banks support credit and debit card payments. Standing Instructions (SI) on cards are supported on Visa, Mastercard, and RuPay cards.

## Debit or credit card (issued outside India)

Customers can authorise subscriptions using their debit or credit card. They must enter their card details to authorise the subscription, similar to a regular one-time online payment. The payment is automatically debited based on the selected plan. All issuing banks support credit and debit card payments, and 140+ currencies are supported. Standing Instructions (SI) on international cards are supported on Visa and Mastercard cards.

## UPI Autopay

Payments for subscriptions via UPI provide customers the flexibility to pay using any UPI application. Customers must first enter their UPI VPA and authorise the subscription. UPI Autopay is supported for all methods via **Intent Flow**, **Collect Flow**, and **QR Flow**.

For mandates where the debit amount exceeds ₹15,000, customers must enter their UPI PIN on the collect request triggered to their VPA. No customer input is required for debit amounts less than ₹15,000.

<Note>
  **NPCI guidelines**: Starting August 1, 2025, UPI Autopay transactions are processed only during non-peak hours: before 10:00 AM, between 1:00 PM and 5:00 PM, or after 9:30 PM. For more information, refer to the [NPCI guidelines](https://www.npci.org.in/PDF/npci/upi/circular/2025/UPI-OC-No-215-A-FY-2025-26-Guidelines-on-usage-of-UPI-APIs.pdf).

  **RBI guidelines for specific payment types**: For mutual fund payments, credit card payments, and insurance premium payments, no customer input is required for debit amounts up to ₹1,00,000.
</Note>

### Intent applications supported

The following table lists the intent applications supported by subscriptions:

| Apps | Android intent | iOS intent |
| - | - | - |
| Paytm | ✔️ | ✔️ |
| GPay | ✔️ | ✔️ |
| PhonePe | ✔️ | ✔️ |
| AmazonPay | ✔️ | ✔️ |


# Android Integration
Source: https://www.cashfree.com/docs/payments/subscription/subscription_checkout_android_sdk

Integrate the Cashfree Subscription Android SDK to add hosted checkout, mandate authorisation, and recurring payment flows to your native Android app.

### Setting up mobile SDK <Badge>Client-side</Badge>

```
implementation 'com.cashfree.pg:api:2.4.0'
```

### Step 1: Creating a subscription <Badge>Server-side</Badge>

The first step in the Subscription Checkout integration is to create a subscription. You need to do this before any payment can be processed. You can add an endpoint to your server which creates this subscription and is used for communication with your frontend.

<Tip>Subscription creation must happen from your backend (as this API uses your secret key). Please do not call this directly from your mobile application. You can use below-mentioned backend SDKs</Tip>

<AccordionGroup>
  <Accordion title="Node">
    [Creating Subscription from Node SDK](https://github.com/cashfree/cashfree-pg-sdk-nodejs/blob/main/api.ts#L31393)
  </Accordion>

  <Accordion title="Java">
    [Creating Subscription from Java SDK](https://github.com/cashfree/cashfree-pg-sdk-java/blob/main/src/main/java/com/cashfree/pg/Cashfree.java)
  </Accordion>

  <Accordion title="Golang">
    [Creating Subscription from Golang SDK](https://github.com/cashfree/cashfree-pg/blob/main/api_subscription.go#L1288)
  </Accordion>

  <Accordion title="Dotnet">
    [Creating Subscription from Dotnet SDK](https://github.com/cashfree/cashfree-pg-sdk-dotnet/blob/master/src/cashfree_pg/Client/ApiClient.cs#L9375)
  </Accordion>

  <Accordion title="Python">
    [Creating Subscription from Python SDK](https://github.com/cashfree/cashfree-pg-sdk-python/blob/master/cashfree_pg/api_client.py#L8502)
  </Accordion>

  <Accordion title="PHP">
    [Creating Subscription from PHP SDK](https://github.com/cashfree/cashfree-pg-sdk-php)
  </Accordion>
</AccordionGroup>

Once you create subscription, you will get the `subscription_id` and `subscription_session_id`

### Step 2: Opening the subscription checkout payment page <Badge>Client-side</Badge>

Once the subscription is created, the next step is to open the payment page so the customer can make the payment. Cashfree Android SDK offer below payment flow.

To complete the payment, we can follow the following steps:

1. Enable Subscription flow flag in Android Manifest
2. Create a `CFSubscriptionSession` object.
3. Create a `CFWebCheckoutTheme` object (Optional).
4. Create a `CFSubscriptionPayment` object.
5. Set payment callback.
6. Initiate the payment using the payment object created from \[step 3]

We go through these step by step below.

#### Enable subscription flow flag

Add the Below entry to your Android manifest file. If you don't enable `cashfree_subscription_flow_enable` flag, SDK won't provide a payment callback.
<Note>It should be added inside application tag, not inside activity tag.</Note>

<CodeGroup>
  ```java java theme={"dark"}
    <application
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name">

        <meta-data
            android:name="cashfree_subscription_flow_enable"
            android:value="true"
            tools:replace="android:value"/>
    </application>
  ```
</CodeGroup>

#### Create a subscription session

This object contains essential information about the subscription, including the subscription session ID (`subscription_session_id`) and subscription ID (`subscription_id`) obtained from creation step. It also specifies the environment (sandbox or production).

<CodeGroup>
  ```java java theme={"dark"}
  CFSubscriptionSession cfSubsSession = new CFSubscriptionSession.CFSubscriptionSessionBuilder()
                      .setEnvironment(CFSubscriptionSession.Environment.SANDBOX)
                      .setSubscriptionSessionID(subscription_session_id)
                      .setSubscriptionId(subscription_id)
                      .build();
  ```

  ```kotlin kotlin theme={"dark"}
  val cfSubsSession = CFSubscriptionSessionBuilder()
      .setEnvironment(CFSubscriptionSession.Environment.SANDBOX)
      .setSubscriptionSessionID(subscription_session_id)
      .setSubscriptionId(subscription_id)
      .build()
  ```
</CodeGroup>

#### Customise theme (optional)

You can customise the appearance of the checkout screen using `CFWebCheckoutTheme`. This step is optional but can help maintain consistency with your app's design.
You can set the `NavigationBarBackgroundColor` which will set the colour for status bar and cashfree loader

<CodeGroup>
  ```java java theme={"dark"}
  CFWebCheckoutTheme cfTheme = new CFWebCheckoutTheme.CFWebCheckoutThemeBuilder()
      .setNavigationBarBackgroundColor("#6A3FD3")
      .build();
  ```

  ```kotlin kotlin theme={"dark"}
  val cfTheme = CFWebCheckoutThemeBuilder()
      .setNavigationBarBackgroundColor("#6A3FD3")
      .build()
  ```
</CodeGroup>

#### Create subscription payment object

<CodeGroup>
  ```java java theme={"dark"}
  CFSubscriptionPayment cfSubscriptionPayment = new CFSubscriptionPayment.CFSubscriptionCheckoutBuilder()
      .setSubscriptionSession(cfSubsSession)
      .setSubscriptionUITheme(cfTheme)
      .build();
  ```

  ```kotlin kotlin theme={"dark"}
  val cfSubscriptionPayment = CFSubscriptionCheckoutBuilder()
    .setSubscriptionSession(cfSubsSession)
    .setSubscriptionUITheme(cfTheme)
    .build()
  ```
</CodeGroup>

#### Setup payment callback

The SDK exposes an interface `CFSubscriptionResponseCallback` to receive callbacks from the SDK once the payment journey ends.

This interface consists of 2 methods:

<CodeGroup>
  ```java java theme={"dark"}
  void onSubscriptionVerify(CFSubscriptionResponse cfSubscriptionResponse);
  void onSubscriptionFailure(CFErrorResponse cfErrorResponse);
  ```

  ```kotlin kotlin theme={"dark"}
  fun onSubscriptionVerify(cfSubscriptionResponse: CFSubscriptionResponse)
  fun onSubscriptionFailure(cfErrorResponse: CFErrorResponse) 
  ```
</CodeGroup>

<Tip>Make sure to set the callback at activity's onCreate as this also handles the activity restart cases.</Tip>

<CodeGroup>
  ```java java theme={"dark"}
  public class YourActivity extends AppCompatActivity implements CFSubscriptionResponseCallback {
      ...
      @Override
      public void onSubscriptionVerify(CFSubscriptionResponse cfSubscriptionResponse) {
      }

      @Override
      public void onSubscriptionFailure(CFErrorResponse cfErrorResponse) {
      }

      @Override
      protected void onCreate(Bundle savedInstanceState) {
          super.onCreate(savedInstanceState);
          setContentView(R.layout.activity_upi_intent_checkout);
          try {
            // If you are using a fragment then you need to add this line inside onCreate() of your Fragment
              CFPaymentGatewayService.getInstance().setSubscriptionCheckoutCallback(this);
          } catch (CFException e) {
              e.printStackTrace();
          }
      }
      ...

  }

  ```

  ```kotlin kotlin theme={"dark"}
  class YourActivity : AppCompatActivity(), CFSubscriptionResponseCallback {

      override fun onCreate(savedInstanceState: Bundle?) {
          super.onCreate(savedInstanceState)
          setContentView(R.layout.activity_drop_checkout)
          try {
              CFPaymentGatewayService.getInstance().setSubscriptionCheckoutCallback(this)
          } catch (e: CFException) {
              e.printStackTrace()
          }
      }

      override fun onSubscriptionVerify(cfSubscriptionResponse: CFSubscriptionResponse) {
          Log.d("onSubscriptionVerify", "verifyPayment triggered")
      }

      override fun onSubscriptionFailure(cfErrorResponse: CFErrorResponse) {
          Log.e("onSubscriptionFailure", cfErrorResponse.message)
      }
  ...
  }
  ```
</CodeGroup>

#### Open checkout screen

Finally, call `doSubscriptionPayment()` to open the Cashfree Subscription checkout screen. This will present the user with the payment options and handle the payment process.

<CodeGroup>
  ```java java theme={"dark"}
  // replace the SubscriptionCheckoutActivity class with your class name
  CFPaymentGatewayService.getInstance().doSubscriptionPayment(SubscriptionCheckoutActivity.this, cfSubscriptionPayment);
  ```

  ```kotlin kotlin theme={"dark"}
  // replace the SubscriptionCheckoutActivity class with your class name
  CFPaymentGatewayService.getInstance().doSubscriptionPayment(this@SubscriptionCheckoutActivity, cfSubscriptionPayment)
  ```
</CodeGroup>

#### Sample code

<CodeGroup>
  ```java java theme={"dark"}
  package com.cashfree.sdk_sample.java;

  import android.os.Bundle;
  import android.text.TextUtils;
  import android.util.Log;
  import android.widget.Toast;

  import androidx.appcompat.app.AppCompatActivity;

  import com.cashfree.pg.api.CFPaymentGatewayService;
  import com.cashfree.pg.core.api.CFSubscriptionSession;
  import com.cashfree.pg.core.api.callback.CFSubscriptionResponseCallback;
  import com.cashfree.pg.core.api.exception.CFException;
  import com.cashfree.pg.core.api.subscription.CFSubscriptionPayment;
  import com.cashfree.pg.core.api.utils.CFErrorResponse;
  import com.cashfree.pg.core.api.utils.CFSubscriptionResponse;
  import com.cashfree.pg.core.api.webcheckout.CFWebCheckoutTheme;
  import com.cashfree.sdk_sample.R;

  public class SubscriptionCheckoutActivity extends AppCompatActivity implements CFSubscriptionResponseCallback {
      String subsID = "sub_1936672690";
      String subsSessionID = "sub_session_Axr2QtKpKwh4_dQypuNwtkpy0uZ8wWbwejEv7gYqrsej2jfXDpQPfDfJr999H-ay9ipYx4-2ZIV6MXX-d7vodyuEHVpDDH43yavnmPiK9kTtNosm";
      CFSubscriptionSession.Environment cfEnvironment = CFSubscriptionSession.Environment.SANDBOX;

      @Override
      protected void onCreate(Bundle savedInstanceState) {
          super.onCreate(savedInstanceState);
          setContentView(R.layout.activity_drop_checkout);
          try {
              CFPaymentGatewayService.getInstance().setSubscriptionCheckoutCallback(this);
              doSubscriptionCheckoutPayment();
          } catch (CFException e) {
              e.printStackTrace();
          }
      }

      @Override
      public void onSubscriptionVerify(CFSubscriptionResponse cfSubscriptionResponse) {
          Log.d("onSubscriptionVerify", "verifyPayment triggered");
          finish();
      }

      @Override
      public void onSubscriptionFailure(CFErrorResponse cfErrorResponse) {
          Log.d("onPaymentFailure " + subsID, cfErrorResponse.getMessage());
          finish();
      }

      public void doSubscriptionCheckoutPayment() {
          if (subsID.equals("ORDER_ID") || TextUtils.isEmpty(subsID)) {
              Toast.makeText(this, "Please set the subsId", Toast.LENGTH_SHORT).show();
              finish();
              return;
          }
          if (subsSessionID.equals("SUBS_SESSION_ID") || TextUtils.isEmpty(subsSessionID)) {
              Toast.makeText(this, "Please set the subs_session_id", Toast.LENGTH_SHORT).show();
              finish();
              return;
          }
          try {
              CFSubscriptionSession cfSession = new CFSubscriptionSession.CFSubscriptionSessionBuilder()
                      .setEnvironment(cfEnvironment)
                      .setSubscriptionSessionID(subsSessionID)
                      .setSubscriptionId(subsID)
                      .build();

              CFSubscriptionPayment cfSubscriptionPayment = new CFSubscriptionPayment.CFSubscriptionCheckoutBuilder()
                      .setSubscriptionSession(cfSession)
                      .setSubscriptionUITheme(new CFWebCheckoutTheme.CFWebCheckoutThemeBuilder()
                              .setNavigationBarBackgroundColor("#d11b1b")
                              .build())
                      .build();
              CFPaymentGatewayService gatewayService = CFPaymentGatewayService.getInstance();
              gatewayService.doSubscriptionPayment(SubscriptionCheckoutActivity.this, cfSubscriptionPayment);
          } catch (CFException exception) {
              exception.printStackTrace();
          }
      }
  }
  ```
</CodeGroup>

[Github Sample](https://github.com/cashfree/nextgen-android/blob/master/app/src/main/java/com/cashfree/sdk_sample/java/SubscriptionCheckoutActivity.java)

### Step 3: Confirming the payment <Badge>Server-side</Badge>

After the payment is completed, you need to confirm whether the payment was successful by checking the subscription status. Once the payment finishes, the user will be redirected back to your activity to your implementation of the `CFSubscriptionResponseCallback` interface.

<Note>You must always verify payment status from your backend. Before delivering the goods or services, please ensure you check the subscription status from your backend. Ensure you check the subscription status from your server endpoint.</Note>

### Testing

You should now have a working checkout button that redirects your customer to Cashfree Subscription Checkout. If your integration isn’t working:

1. Open the Network tab in your browser’s developer tools.
2. Click the button and check the console logs.
3. Use console.log(session) inside your button click listener to confirm the correct error returned.

### Other options

<AccordionGroup>
  <Accordion title="(Optional) Enable logging to debugging issues">
    To enable SDK logging add the following to your `values.xml` file.

    `<integer name="cashfree_pg_logging_level">3</integer>`

    Following are the Logging levels.

    * VERBOSE = 2
    * DEBUG = 3
    * INFO = 4
    * WARN = 5
    * ERROR = 6
    * ASSERT = 7
  </Accordion>
</AccordionGroup>


# Cordova Integration
Source: https://www.cashfree.com/docs/payments/subscription/subscription_checkout_cordova_sdk

Integrate the Cashfree Subscription Cordova SDK to add hosted checkout and mandate authorisation flows to your hybrid Cordova or Capacitor app.

### Setting up SDK  <Badge>Client-side</Badge>

The Cordova SDK is available on [npm](https://www.npmjs.com/). You can download the latest version [1.0.12](https://www.npmjs.com/package/cordova-plugin-cashfree-pg?activeTab=readme).

The SDK supports Android SDK version 19 and later, and iOS 10.3 and later.

To install the SDK, run the following command in your project directory:

<CodeGroup>
  ```shell cordova theme={"dark"}
  npm install cordova-plugin-cashfree-pg
  # Or Install with latest tag
  npm install cordova-plugin-cashfree-pg@latest

  # Add Plugin
  cordova plugin add cordova-plugin-cashfree-pg

  # With Ionic Cordova platform
  ionic cordova plugin add cordova-plugin-cashfree-pg 
  ```

  ```shell capacitor theme={"dark"}
  # Install with capacitor tag
  npm install cordova-plugin-cashfree-pg@capacitor

  # Ionic Capacitor setup

  # Install Core library (once per project)
  npm install @awesome-cordova-plugins/core
  # Install Awesome Cordova Plugins TypeScript wrapper for CashFree PG
  npm install @awesome-cordova-plugins/cashfree-pg
  # Update native platform project(s) to include newly added plugin
  ionic cap sync
  ```
</CodeGroup>

#### iOS

Add this to your application's `info.plist` file.

```shell theme={"dark"}
<key>LSApplicationQueriesSchemes</key>
<array>
  <string>phonepe</string>
  <string>tez</string>
  <string>paytmmp</string>
  <string>bhim</string>
  <string>amazonpay</string>
  <string>credpay</string>
</array>
```

```shell theme={"dark"}
cd ios
pod install --repo-update
```

### Step 1: Creating a subscription <Badge>Server-side</Badge>

Before you can process payments, you must create a subscription. Create an API endpoint on your server that generates the subscription and communicates with your frontend.

<Tip>Always create subscriptions from your backend. This API requires your secret key. Never call it directly from your mobile app. </Tip>
Use any of the following backend SDKs:

<AccordionGroup>
  <Accordion title="Node">
    [Creating Subscription from Node SDK](https://github.com/cashfree/cashfree-pg-sdk-nodejs/blob/main/api.ts#L31393)
  </Accordion>

  <Accordion title="Java">
    [Creating Subscription from Java SDK](https://github.com/cashfree/cashfree-pg-sdk-java/blob/main/src/main/java/com/cashfree/pg/Cashfree.java)
  </Accordion>

  <Accordion title="Golang">
    [Creating Subscription from Golang SDK](https://github.com/cashfree/cashfree-pg/blob/main/api_subscription.go#L1288)
  </Accordion>

  <Accordion title="Dotnet">
    [Creating Subscription from Dotnet SDK](https://github.com/cashfree/cashfree-pg-sdk-dotnet/blob/master/src/cashfree_pg/Client/ApiClient.cs#L9375)
  </Accordion>

  <Accordion title="Python">
    [Creating Subscription from Python SDK](https://github.com/cashfree/cashfree-pg-sdk-python/blob/master/cashfree_pg/api_client.py#L8502)
  </Accordion>

  <Accordion title="PHP">
    [Creating Subscription from PHP SDK](https://github.com/cashfree/cashfree-pg-sdk-php)
  </Accordion>
</AccordionGroup>

After you create the subscription, you receive a `subscription_id` and a `subscription_session_id`.

### Step 2: Opening the subscription checkout payment page <Badge>Client-side</Badge>

After creating the subscription, open the payment page so the customer can complete the payment.

To complete the payment:

1. Enable Subscription flow flag in Android Manifest
2. Create a `CFSubscriptionSession` object.
3. Set payment callback.
4. Initiate the payment

#### Enable subscription flow flag

Add the following entry inside the `<application>` tag in your Android manifest file. If you do not enable the `cashfree_subscription_flow_enable` flag, the SDK will not provide a payment callback.
<Note>Add this entry inside the `<application>` tag, Not inside the `<activity>` tag.</Note>

<CodeGroup>
  ```java java theme={"dark"}
    <application
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name">

        <meta-data
            android:name="cashfree_subscription_flow_enable"
            android:value="true"
            tools:replace="android:value"/>
    </application>
  ```
</CodeGroup>

#### Create a subscription session

This object contains essential information about the subscription, including the subscription session ID (`subscription_session_id`) and subscription ID (`subscription_id`) obtained from creation step. It also specifies the environment `(SANDBOX or PRODUCTION)`.

```javascript theme={"dark"}
try {
      let session = {
            subscription_session_id: SESSION_ID,
            subscription_id: ORDER_ID,
            environment: ENV
        }
}
catch (e: any) {
      console.log(e.message);
}
```

#### Setup payment callback

You need to set up callback handlers to handle events after payment processing. This must be set before calling `doSubscriptionPayment`.

```javascript theme={"dark"}
onVerify(orderID: string)
onError(error: CFErrorResponse, orderID: string)
```

<Tip>Always call setCallback before calling `doSubscriptionPayment` method of SDK</Tip>

```javascript theme={"dark"}
function onDeviceReady() {
    const callbacks = {
        onVerify: function (result) {
            console.log("Payment Verify: " + JSON.parse(JSON.stringify(result)));
        },
        onError: function (error){
            console.log("Payment Error: " + JSON.parse(JSON.stringify(error)));
        }
    }
    CFPaymentGateway.setCallback(callbacks)
}
```

#### Initiate the payment

Call `doSubscriptionPayment()` to open the Cashfree subscription checkout screen. This will present the user with the payment options and handle the payment process.

```javascript theme={"dark"}
function initiateSubscriptionPayment() {
    var cfSubscriptionPayment = {
        "session": {
            "subscription_session_id": SESSION_ID,
            "subscription_id": ORDER_ID,
            "environment": ENV
        }
    }
    CFPaymentGateway.doSubscriptionPayment(cfSubscriptionPayment)
}
```

### Sample code

```Javascript theme={"dark"}
// Wait for the deviceready event before using any of Cordova's device APIs.
// See https://cordova.apache.org/docs/en/latest/cordova/events/events.html#deviceready

document.addEventListener('deviceready', onDeviceReady, false);
const SESSION_ID = 'sub_session_f-e0jnzQa_qQtkFtPZmWmxj1We1Tu5f76DImA4ySE5CklsjjJVTiGbyTGxGM-ZKLUJV8-ft2SBYRmws180vI-nivXWq56qJhfY75AIjY823dgn1bLGUADSgZ1yqN_6spayment' // payment_session_id
const ORDER_ID = 'devstudio_subs_7358099936054719343' // order_id
const ENV = "SANDBOX" // "SANDBOX" or "PRODUCTION"

function onDeviceReady() {
    console.log('Running cordova-' + cordova.platformId + '@' + cordova.version);
    let subscriptionElement = document.getElementById("onSubscription");
    subscriptionElement.addEventListener("click", (e) => initiateSubscriptionPayment());

    const callbacks = {
        onVerify: function (result) {
            console.log("Payment Verify: " + JSON.parse(JSON.stringify(result)));
        },
        onError: function (error){
            console.log("Payment Error: " + JSON.parse(JSON.stringify(error)));
        }
    }
    CFPaymentGateway.setCallback(callbacks)
}

function initiateSubscriptionPayment() {
    var cfSubscriptionPayment = {
        "session": {
            "subscription_session_id": SESSION_ID,
            "subscription_id": ORDER_ID,
            "environment": ENV
        }
    }
    CFPaymentGateway.doSubscriptionPayment(cfSubscriptionPayment)
}
```

### Sample GitHub code

<AccordionGroup>
  <Accordion title="Cordova Integration">
    [Github Sample](https://github.com/cashfree/cordova-plugin-cashfree/tree/master/example-cordova)
  </Accordion>

  <Accordion title="Ionic Capacitor Integration">
    [Github Sample](https://github.com/kishan-cashfree/CFSampleCapacitor)
  </Accordion>

  <Accordion title="Ionic Angular Capacitor Integration">
    [Github Sample](https://github.com/kishan-cashfree/SampleIonicAngularCapacitor)
  </Accordion>

  <Accordion title="NextJs Capacitor Integration">
    [Github Sample](https://github.com/kishan-cashfree/NextjsCapacitorCashFreeSample)
  </Accordion>
</AccordionGroup>

[Sample UPI Test apk](https://docs.cashfree.com/docs/cashfree-upi-intent-simulator-apk)

<Note>
  We currently do not provide a dedicated SDK for the Capacitor framework. However, we've developed a Capacitor plugin that acts as a wrapper over our Cordova SDK. See the [sample Capacitor app](https://github.com/droiddevgeeks/CFSampleCapacitor/tree/main).
</Note>

### Step 3: Confirming the payment <Badge>Server-side</Badge>

After the payment is completed, confirm the subscription status to verify whether the payment was successful. The user will return to your activity after checkout.

<Note>You must always verify payment status from your backend. Before delivering the goods or services, please ensure you check the subscription status from your backend. Ensure you check the subscription status from your server endpoint.</Note>


# Flutter Integration
Source: https://www.cashfree.com/docs/payments/subscription/subscription_checkout_flutter_sdk

Integrate the Cashfree Subscription Flutter SDK to add hosted checkout and mandate authorisation flows to your Flutter Android and iOS apps.

### Setting up SDK <Badge>Client-side</Badge>

The Flutter SDK is hosted on [https://pub.dev/](https://pub.dev/) you can get the SDK [2.4.0+52](https://pub.dev/packages/flutter_cashfree_pg_sdk). View the [example app on GitHub](https://github.com/cashfree/flutter-cashfree-pg-sdk/blob/00cd08f3d9657702bbad2c4fa12044e2a3117678/example/lib/main.dart#L296).

Our Flutter SDK supports Android SDK version 19 and above and iOS minimum deployment target of 11 and above. Open your project's `pubspec.yaml` and add the following under dependencies:

```
dependencies:
  flutter_cashfree_pg_sdk: 2.4.0+52
```

#### iOS

Add this to your application's `info.plist` file.

```shell theme={"dark"}
<key>LSApplicationQueriesSchemes</key>
<array>
  <string>phonepe</string>
  <string>tez</string>
  <string>paytmmp</string>
  <string>bhim</string>
  <string>amazonpay</string>
  <string>credpay</string>
</array>
```

```shell theme={"dark"}
cd ios
pod install --repo-update
```

### Step 1: Creating a subscription <Badge>Server-side</Badge>

The first step in the Subscription Checkout integration is to create a subscription. You need to do this before any payment can be processed. You can add an endpoint to your server which creates this subscription and is used for communication with your frontend.

<Tip>Subscription creation must happen from your backend (as this API uses your secret key). Please do not call this directly from your mobile application. You can use below-mentioned backend SDKs</Tip>

<AccordionGroup>
  <Accordion title="Node">
    [Creating Subscription from Node SDK](https://github.com/cashfree/cashfree-pg-sdk-nodejs/blob/main/api.ts#L31393)
  </Accordion>

  <Accordion title="Java">
    [Creating Subscription from Java SDK](https://github.com/cashfree/cashfree-pg-sdk-java/blob/main/src/main/java/com/cashfree/pg/Cashfree.java)
  </Accordion>

  <Accordion title="Golang">
    [Creating Subscription from Golang SDK](https://github.com/cashfree/cashfree-pg/blob/main/api_subscription.go#L1288)
  </Accordion>

  <Accordion title="Dotnet">
    [Creating Subscription from Dotnet SDK](https://github.com/cashfree/cashfree-pg-sdk-dotnet/blob/master/src/cashfree_pg/Client/ApiClient.cs#L9375)
  </Accordion>

  <Accordion title="Python">
    [Creating Subscription from Python SDK](https://github.com/cashfree/cashfree-pg-sdk-python/blob/master/cashfree_pg/api_client.py#L8502)
  </Accordion>

  <Accordion title="PHP">
    [Creating Subscription from PHP SDK](https://github.com/cashfree/cashfree-pg-sdk-php)
  </Accordion>
</AccordionGroup>

Once you create subscription, you will get the `subscription_id` and `subscription_session_id`

### Step 2: Opening the subscription checkout payment page <Badge>Client-side</Badge>

Once the subscription is created, the next step is to open the payment page so the customer can make the payment.

To complete the payment, we can follow the following steps:

1. Enable Subscription flow flag in Android Manifest
2. Create a `CFSubscriptionSession` object.
3. Create a `CFTheme` object (Optional).
4. Create a `CFSubscriptionPayment` object.
5. Set payment callback.
6. Initiate the payment using the payment object created from \[step 3]

We go through these step by step below.

#### Enable subscription flow flag

Add the Below entry to your Android manifest file. If you don't enable `cashfree_subscription_flow_enable` flag, SDK won't provide a payment callback.
<Note>It should be added inside application tag, not inside activity tag.</Note>

<CodeGroup>
  ```java java theme={"dark"}
    <application
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name">

        <meta-data
            android:name="cashfree_subscription_flow_enable"
            android:value="true"
            tools:replace="android:value"/>
    </application>
  ```
</CodeGroup>

#### Create a subscription session

This object contains essential information about the subscription, including the subscription session ID (`subscription_session_id`) and subscription ID (`subscription_id`) obtained from creation step. It also specifies the environment (sandbox or production).

```dart theme={"dark"}
try {
    var subscriptionSession = CFSubscriptionSessionBuilder().setEnvironment(environment).setSubscriptionId(subscriptionId).setSubscriptionSessionId(subscriptionSessionId).build();
    return subsriptionSession;
} on CFException catch (e) {
    print(e.message);
}
```

#### Customise theme (optional)

You can customise the appearance of the checkout screen using `CFTheme`. This step is optional but can help maintain consistency with your app's design.
You can set the `NavigationBarBackgroundColor` which will set the colour for status bar and cashfree loader

```dart theme={"dark"}
var theme = CFThemeBuilder()
          .setNavigationBarBackgroundColorColor("#ffffff")
          .setNavigationBarTextColor("#ffffff")
          .build();
```

#### Create subscription payment object

Use `CFSubscriptionPaymentBuilder` to create the payment object. This object accepts a `CFSubscriptionSession`, like the one created in the previous step.

```dart theme={"dark"}
var cfSubscriptionCheckout = CFSubscriptionPaymentBuilder()
  .setSession(subscriptionSession!)
  .setTheme(theme)
  .build();
```

#### Setup payment callback

You need to set up callback handlers to handle events after payment processing. This must be set before calling `doPayment`.

```dart theme={"dark"}
void onSubscriptionVerify(String subscriptionId) {
    print("Verify Subscription ===> $subscriptionId");
 }

void onSubscriptionFailure(CFErrorResponse errorResponse, String data) {
    print("Failure in subscription flow");
}

var cfPaymentGatewayService = CFPaymentGatewayService();
@override
void initState() {
  super.initState();
  cfPaymentGatewayService.setCallback(onSubscriptionVerify, onSubscriptionFailure);
}
```

#### Sample code

```dart theme={"dark"}
import 'package:flutter/material.dart';
import 'package:flutter_cashfree_pg_sdk/api/cferrorresponse/cferrorresponse.dart';
import 'package:flutter_cashfree_pg_sdk/api/cfpayment/cfsubscriptioncheckoutpayment.dart';
import 'package:flutter_cashfree_pg_sdk/api/cfpaymentgateway/cfpaymentgatewayservice.dart';
import 'package:flutter_cashfree_pg_sdk/api/cfsession/cfsubssession.dart';
import 'package:flutter_cashfree_pg_sdk/api/cftheme/cftheme.dart';
import 'package:flutter_cashfree_pg_sdk/utils/cfenums.dart';
import 'package:flutter_cashfree_pg_sdk/utils/cfexceptions.dart';

class MyApp extends StatefulWidget {
  const MyApp({Key? key}) : super(key: key);

  @override
  State<MyApp> createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {

  var cfPaymentGatewayService = CFPaymentGatewayService();
  CFEnvironment environment = CFEnvironment.SANDBOX;
  
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(
          title: const Text('Plugin example app'),
        ),
        body: Center(
          child: Column(
            children: [
              TextButton(
                  onPressed: () => susbcriptionCheckout(),
                  child: const Text("Subscription Web Checkout Flow")),
            ],
          ),
        ),
      ),
    );
  }

  susbcriptionCheckout() async {
    try {
      cfPaymentGatewayService.setCallback(onSubscriptionVerify, onSubscriptionFailure);
      var subsriptionSession = CFSubscriptionSessionBuilder()
            .setEnvironment(environment)
            .setSubscriptionId(subscriptionId)
            .setSubscriptionSessionId(subscriptionSessionId)
            .build();
      
      var theme = CFThemeBuilder()
          .setNavigationBarBackgroundColorColor("#ffffff")
          .setNavigationBarTextColor("#ffffff")
          .build();
      var cfsubscriptionCheckout = CFSubscriptionPaymentBuilder()
          .setSession(subsriptionSession)
          .setTheme(theme)
          .build();
      cfPaymentGatewayService.doPayment(cfsubscriptionCheckout);
    } on CFException catch (e) {
      print(e.message);
    }
  }

  void onSubscriptionVerify(String subscriptionId) {
    print("Verify Subscription ===> $subscriptionId");
  }

  void onSubscriptionFailure(CFErrorResponse errorResponse, String data) {
    print(errorResponse.getMessage());
  }
}

```

### Step 3: Confirming the payment <Badge>Server-side</Badge>

After the payment is completed, you need to confirm whether the payment was successful by checking the subscription status. Once the payment finishes, the user will be redirected back to your activity.

<Note>You must always verify payment status from your backend. Before delivering the goods or services, please ensure you check the subscription status from your backend. Ensure you check the subscription status from your server endpoint.</Note>

### Testing

You should now have a working checkout button that redirects your customer to Cashfree Subscription Checkout. If your integration isn’t working:

1. Open the Network tab in your browser’s developer tools.
2. Click the button and check the console logs.
3. Use console.log(session) inside your button click listener to confirm the correct error returned.


# iOS Integration
Source: https://www.cashfree.com/docs/payments/subscription/subscription_checkout_ios_sdk

Integrate the Cashfree Subscription iOS SDK to embed a WebView-based hosted checkout in your iOS app for mandate authorisation and recurring payments.

### Setting up SDK  <Badge>Client-side</Badge>

##### CocoaPods

In your pod file add the following line `pod 'CashfreePG', '2.4.0'`. Ensure you are using the latest version of the SDK. Install the package using `pod install`.

To provide UPI payments on iOS you will also need to enable the following permissions in your app. Open the `info.plist` file and add the below content.

```shell theme={"dark"}
<key>LSApplicationQueriesSchemes</key>
<array>
  <string>phonepe</string>
  <string>tez</string>
  <string>paytmmp</string>
  <string>bhim</string>
  <string>amazonpay</string>
  <string>credpay</string>
</array>
```

### Step 1: Creating a subscription <Badge>Server-side</Badge>

The first step in the Subscription Checkout integration is to create a subscription. You need to do this before any payment can be processed. You can add an endpoint to your server which creates this subscription and is used for communication with your frontend.

<Tip>Subscription creation must happen from your backend (as this API uses your secret key). Please don't call this directly from your mobile application. You can use below-mentioned backend SDKs</Tip>

<AccordionGroup>
  <Accordion title="Node">
    [Creating Subscription from Node SDK](https://github.com/cashfree/cashfree-pg-sdk-nodejs/blob/main/api.ts#L31393)
  </Accordion>

  <Accordion title="Java">
    [Creating Subscription from Java SDK](https://github.com/cashfree/cashfree-pg-sdk-java/blob/main/src/main/java/com/cashfree/pg/Cashfree.java)
  </Accordion>

  <Accordion title="Golang">
    [Creating Subscription from Golang SDK](https://github.com/cashfree/cashfree-pg/blob/main/api_subscription.go#L1288)
  </Accordion>

  <Accordion title="Dotnet">
    [Creating Subscription from Dotnet SDK](https://github.com/cashfree/cashfree-pg-sdk-dotnet/blob/master/src/cashfree_pg/Client/ApiClient.cs#L9375)
  </Accordion>

  <Accordion title="Python">
    [Creating Subscription from Python SDK](https://github.com/cashfree/cashfree-pg-sdk-python/blob/master/cashfree_pg/api_client.py#L8502)
  </Accordion>

  <Accordion title="PHP">
    [Creating Subscription from PHP SDK](https://github.com/cashfree/cashfree-pg-sdk-php)
  </Accordion>
</AccordionGroup>

Once you create subscription, you will get the `subscription_id` and `subscription_session_id`

### Step 2: Opening the subscription checkout payment page <Badge>Client-side</Badge>

Once the subscription is created, the next step is to open the payment page so the customer can make the payment.

To complete the payment, we can follow the following steps:

1. Create a `CFSubscriptionSession` object.
2. Create a `CFSubscriptionPayment` object.
3. Set payment callback.
4. Initiate the payment using the payment object created from \[step 2]

We go through these step by step below.

#### Create a session

This object contains essential information about the subscription, including the subscription session ID (`subscription_session_id`) and subscription ID (`subscription_id`) obtained from creation step. It also specifies the environment (sandbox or production).

<CodeGroup>
  ```swift swift theme={"dark"}
  do {
      let session = try CFSubscriptionSession.CFSubscriptionSessionBuilder()
                      .setEnvironment(CFENVIRONMENT.PRODUCTION) // or CFENVIRONMENT.SANDBOX
                      .setSubscriptionId(subscription_id)
                      .setSubscriptionSessionId(subscription_session_id)
                      .build()
  } catch let e {
      let error = e as! CashfreeError
      self.createAlert(title: "Warning", message: error.localizedDescription)
  }
  ```
</CodeGroup>

#### Create subscription payment object

Use `CFSubscriptionPaymentBuilder` to create the payment object. This object accepts a `CFSubscriptionSession`, like the one created in the previous step.

<CodeGroup>
  ```swift swift theme={"dark"}
  let subscriptionWebCheckoutPayment = try CFSubscriptionPayment.CFSubscriptionPaymentBuilder()
                      .setSession(session)
                      .build()
  ```
</CodeGroup>

#### Setup callback

You need to set up callback handlers to handle events after payment processing. The callback implements `CFResponseDelegate` to handle payment responses and errors.
It can be initialized in `viewDidLoad` by calling `CFPaymentGatewayService.getInstance().setCallback(self)` or call it before calling `startSubscription`.

* onError: Handles payment failures by displaying an alert with error details
* verifyPayment: Called when payment needs merchant verification, shows status alert to user

<CodeGroup>
  ```swift swift theme={"dark"}
  extension ViewController: CFResponseDelegate {

      func onError(_ error: CFErrorResponse, order_id: String) {
           print("Subscription Error", order_id)
      }
      
      func verifyPayment(order_id: String) {
          print("Subscription verifyPayment", order_id)
      }
  }

  // Class Variable
  let pgService = CFPaymentGatewayService.getInstance()

  override func viewDidLoad() {
  super.viewDidLoad()
  pgService.setCallback(self)
  }
  ```
</CodeGroup>

#### Sample code

<CodeGroup>
  ```swift swift theme={"dark"}
  import UIKit
  import CashfreePGUISDK
  import CashfreePGCoreSDK
  import CashfreePG

  class SubscriptionViewController: UIViewController, CFResponseDelegate {
      
      func onError(_ error: CashfreePGCoreSDK.CFErrorResponse, order_id: String) {
          print("Subscription Error", order_id)
      }
      
      @objc func verifyPayment(order_id: String){
          print("Subscription verifyPayment", order_id)
      }
      
      
      override func viewDidLoad() {
          super.viewDidLoad()
      }
      
      @IBAction func openSubscriptionCheckoutPage(_ sender: Any) {
          do {
                  let session = try CFSubscriptionSession.CFSubscriptionSessionBuilder()
                      .setEnvironment(CFENVIRONMENT.PRODUCTION) // or CFENVIRONMENT.SANDBOX
                      .setSubscriptionId(subscription_id)
                      .setSubscriptionSessionId(subscription_session_id)
                      .build()
                  let subscriptionWebCheckoutPayment = try CFSubscriptionPayment.CFSubscriptionPaymentBuilder()
                      .setSession(session)
                      .build()
                  let cfPaymentgatewat = CFPaymentGatewayService.getInstance()
                  cfPaymentgatewat.setCallback(self)
                  try cfPaymentgatewat.startSubscription(subscriptionWebCheckoutPayment, viewController: self)
              } catch let e {
                  let err = e as! CashfreeError
                  print(err.description)
              }
      }
  }

  ```
</CodeGroup>

### Step 3: Confirming the payment <Badge>Server-side</Badge>

After the payment is completed, you need to confirm whether the payment was successful by checking the subscription status. Once the payment finishes, the user will be redirected back to your activity.

<Note>You must always verify payment status from your backend. Before delivering the goods or services, please ensure you check the subscription status from your backend. Ensure you check the subscription status from your server endpoint.</Note>


# React Native Integration
Source: https://www.cashfree.com/docs/payments/subscription/subscription_checkout_react_native_sdk

Integrate the Cashfree Subscription React Native SDK to add hosted checkout and mandate authorisation flows to your React Native iOS and Android apps.

### Setting up SDK <Badge>Client-side</Badge>

The React Native SDK is available on [npm.org](https://www.npmjs.com/package/react-native-cashfree-pg-sdk). You can [get the latest SDK 2.4.0 from npm](https://www.npmjs.com/package/react-native-cashfree-pg-sdk).<br />
The SDK supports Android SDK version 19 and later, and iOS 10.3 and later.

To install the SDK, run the following command in your project directory:

<CodeGroup>
  ```npm npm theme={"dark"}
  npm install react-native-cashfree-pg-sdk
  ```

  ```yarn yarn theme={"dark"}
  yarn add react-native-cashfree-pg-sdk
  ```

  ```expo expo theme={"dark"}
  npx expo install react-native-cashfree-pg-sdk
  npx expo install expo-dev-client
  npx expo prebuild  //mandatory for expo
  npx expo run:android
  npx expo run:ios
  ```
</CodeGroup>

#### iOS

Add this to your application's `info.plist` file.

```shell theme={"dark"}
<key>LSApplicationQueriesSchemes</key>
<array>
  <string>phonepe</string>
  <string>tez</string>
  <string>paytmmp</string>
  <string>bhim</string>
  <string>amazonpay</string>
  <string>credpay</string>
</array>
```

```shell theme={"dark"}
cd ios
pod install --repo-update
```

### Step 1: Creating a subscription <Badge>Server-side</Badge>

Before you can process payments, you must create a subscription. Create an API endpoint on your server that generates the subscription and communicates with your frontend.

<Tip>Always create subscriptions from your backend. This API requires your secret key. Never call it directly from your mobile app. </Tip>
Use any of the following backend SDKs:

<AccordionGroup>
  <Accordion title="Node">
    [Creating Subscription from Node SDK](https://github.com/cashfree/cashfree-pg-sdk-nodejs/blob/main/api.ts#L31393)
  </Accordion>

  <Accordion title="Java">
    [Creating Subscription from Java SDK](https://github.com/cashfree/cashfree-pg-sdk-java/blob/main/src/main/java/com/cashfree/pg/Cashfree.java)
  </Accordion>

  <Accordion title="Golang">
    [Creating Subscription from Golang SDK](https://github.com/cashfree/cashfree-pg/blob/main/api_subscription.go#L1288)
  </Accordion>

  <Accordion title="Dotnet">
    [Creating Subscription from Dotnet SDK](https://github.com/cashfree/cashfree-pg-sdk-dotnet/blob/master/src/cashfree_pg/Client/ApiClient.cs#L9375)
  </Accordion>

  <Accordion title="Python">
    [Creating Subscription from Python SDK](https://github.com/cashfree/cashfree-pg-sdk-python/blob/master/cashfree_pg/api_client.py#L8502)
  </Accordion>

  <Accordion title="PHP">
    [Creating Subscription from PHP SDK](https://github.com/cashfree/cashfree-pg-sdk-php)
  </Accordion>
</AccordionGroup>

After you create the subscription, you receive a `subscription_id` and a `subscription_session_id`.

### Step 2: Opening the subscription checkout payment page <Badge>Client-side</Badge>

After creating the subscription, open the payment page so the customer can complete the payment.

To complete the payment:

1. Enable Subscription flow flag in Android Manifest
2. Create a `CFSubscriptionSession` object.
3. Set payment callback.
4. Initiate the payment

#### Enable subscription flow flag

Add the following entry inside the `<application>` tag in your Android manifest file. If you do not enable the `cashfree_subscription_flow_enable` flag, the SDK will not provide a payment callback.
<Note>Add this entry inside the `<application>` tag, not inside the `<activity>` tag.</Note>

<CodeGroup>
  ```java java theme={"dark"}
    <application
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name">

        <meta-data
            android:name="cashfree_subscription_flow_enable"
            android:value="true"
            tools:replace="android:value"/>
    </application>
  ```
</CodeGroup>

#### Create a subscription session

This object contains essential information about the subscription, including the subscription session ID (`subscription_session_id`) and subscription ID (`subscription_id`) obtained from creation step. It also specifies the environment (sandbox or production).

```typescript theme={"dark"}
import {
  CFEnvironment,
  CFSubscriptionSession,
} from 'cashfree-pg-api-contract';

try {
      const session = new CFSubscriptionSession(
        'subscription_session_id',
        'subscription_id',
        CFEnvironment.SANDBOX
      );
}
catch (e: any) {
      console.log(e.message);
}
```

#### Setup payment callback

You need to set up callback handlers to handle events after payment processing. This must be set before calling `doSubscriptionPayment`.

```typescript theme={"dark"}
onVerify(orderID: string)
onError(error: CFErrorResponse, orderID: string)
```

<Note>Make sure to set the callback at componentDidMount and remove the callback at componentWillUnmount as this also handles the activity restart cases and prevents memory leaks.</Note>

<Tip>Always call setCallback before calling `doSubscriptionPayment` method of SDK</Tip>

```typescript theme={"dark"}
import {
  CFErrorResponse,
  CFPaymentGatewayService,
} from 'react-native-cashfree-pg-sdk';

export default class App extends Component {
  constructor() {
    super();
  }

  componentDidMount() {
    console.log('MOUNTED');
    CFPaymentGatewayService.setCallback({
      onVerify(orderID: string): void {
        this.changeResponseText('orderId is :' + orderID);
      },
      onError(error: CFErrorResponse, orderID: string): void {
        this.changeResponseText(
          'exception is : ' + JSON.stringify(error) + '\norderId is :' + orderID
        );
      },
    });
  }

  componentWillUnmount() {
    console.log('UNMOUNTED');
    CFPaymentGatewayService.removeCallback();
  }
}
```

#### Initiate the payment

Call `doSubscriptionPayment()` to open the Cashfree subscription checkout screen. This will present the user with the payment options and handle the payment process.

```typescript theme={"dark"}
async _startSubscriptionCheckout() {
    try {
        const session = CFSubscriptionSession(
            'subscription_session_id',
            'subscription_id',
            CFEnvironment.PRODUCTION/SANDBOX,
        );
        CFPaymentGatewayService.doSubscriptionPayment(session);

    } catch (e: any) {
        console.log(e.message);
    }
}
```

### Sample code

```typescript theme={"dark"}
import * as React from 'react';
import {Component} from 'react';

} from 'react-native';
import {
  CFErrorResponse,
  CFPaymentGatewayService,
  CFCard,
} from 'react-native-cashfree-pg-sdk';
import {
  CFEnvironment,
  CFSubscriptionSession,
} from 'cashfree-pg-api-contract';


export default class App extends Component {
  componentWillUnmount() {
    console.log('UNMOUNTED');
    CFPaymentGatewayService.removeCallback();
  }

  componentDidMount() {
    console.log('MOUNTED');
    CFPaymentGatewayService.setCallback({
      onVerify(orderID: string): void {
        console.log('orderId is :' + orderID);
      },
      onError(error: CFErrorResponse, orderID: string): void {
        console.log(
          'exception is : ' +
            JSON.stringify(error) +
            '\norderId is :' +
            orderID,
        );
      },
    });
  }

  async _startSubscriptionCheckout() {
    try {
      const session = CFSubscriptionSession(
            'subscription_session_id',
            'subscription_id',
            CFEnvironment.PRODUCTION/SANDBOX,
        );
      CFPaymentGatewayService.doSubscriptionPayment(session);
    } catch (e: any) {
      console.log(e.message);
    }
  }

  render() {
    return (
      <ScrollView>
          <View style={styles.button}>
            <Button
              onPress={() => this._startSubscriptionCheckout()}
              title="Start Subscription Checkout"
            />
      </ScrollView>
    );
  }
}
```

<Note>This SDK is compatible with expo framework.
[Sample Expo framework](https://github.com/kishan-cashfree/Expo-RN_Cashfree_SDK)</Note>

### Step 3: Confirming the payment <Badge>Server-side</Badge>

After the payment is completed, confirm the subscription status to verify whether the payment was successful. The user will return to your activity after checkout.

<Note>You must always verify payment status from your backend. Before delivering the goods or services, please ensure you check the subscription status from your backend. Ensure you check the subscription status from your server endpoint.</Note>

### Testing

To test your integration:

1. Open the Network tab in your browser’s developer tools.
2. Click the button and check the console logs.
3. Use console.log(session) inside your button click listener to confirm the correct error returned.


# UPI One-Time Mandate
Source: https://www.cashfree.com/docs/payments/subscription/upi-otm

Learn how to use UPI one-time mandates with Cashfree to block funds upfront from a customer account and capture payment later upon fulfilment.

UPI One-Time Mandate (OTM) is a secure, RBI-compliant payment workflow that allows you to block a specific amount from a customer's UPI-linked bank account upfront and debit it only after the order or service has been fulfilled.

This two-step block-then-capture model gives you confidence in fund availability before debiting, and gives customers a transparent authorisation trail in their UPI app.

## Key benefits

UPI OTM offers the following benefits:

* **Guaranteed fund availability**: You block funds at order time and capture only after fulfilment.
* **Customer trust and transparency**: Your customers approve the mandate in their UPI app and see the block in real time.
* **Flexible capture**: You can capture any amount up to the authorised order value.
* **Auto-release on void**: If the order is cancelled, funds are unblocked through a simple void request to the [Preauthorisation API](/docs/api-reference/payments/latest/payments/preauthorisation).
* **UPI channel support**: You can use UPI Collect, UPI Intent, or UPI QR based on your checkout experience.

## Use cases

Use UPI OTM when you need to confirm payment availability before finalising an order.

Common scenarios include:

* **IPO applications**: Reserve funds for ASBA requests and debit only if the allotment succeeds.
* **Insurance approvals**: Block the premium amount until underwriting is completed.
* **Variable utility or charging services**: Hold funds when the final amount is not known at the time of booking.
* **Healthcare and hospital services**: Reserve a provisional amount while insurance coverage or treatment costs are confirmed.
* **Rental deposits**: Hold a refundable deposit and charge only for actual damages.
* **Travel and hospitality reservations**: Reserve funds for bookings while preserving flexibility for cancellations.
* **Limited-stock product launches**: Reserve funds for high-demand orders and collect payment only once the order is confirmed.

<Tip>Set `approve_by` to a short window to reduce abandoned mandates, and choose `start_time` and `end_time` based on your fulfilment SLA.</Tip>

## UPI OTM lifecycle

The UPI OTM lifecycle consists of four stages. Each stage maps to a Cashfree API call.

1. **[Create an order and payment session](#create-an-order)**: Create an order with the [Create Order API](/docs/api-reference/payments/latest/orders/create-order), then initiate a UPI mandate payment session with the [Order Pay API](/docs/api-reference/payments/latest/payments/order-pay) using `authorize_only: true` to block funds without immediately debiting the customer's account.
2. **[Get customer approval to block funds](#create-the-upi-mandate-session)**: Your customer approves the mandate in their UPI app. You receive a `SUCCESS` webhook, and the funds are blocked without immediate debit.
3. **[Capture the mandate on fulfilment](#capture-the-mandate)**: After you fulfil the order, call the [Preauthorisation API](/docs/api-reference/payments/latest/payments/preauthorisation) with `action: CAPTURE` to debit the blocked amount.
4. **[Void the mandate or process a refund](#void-the-mandate)**: If the order is cancelled before capture, call the [Preauthorisation API](/docs/api-reference/payments/latest/payments/preauthorisation) with `action: VOID` to release the block. If the order is already captured, create a refund with the [Create Refund API](/docs/api-reference/payments/latest/refunds/create-refund) instead.

## Supported UPI channels

UPI OTM works across the following channels:

| `channel` value | Channel name | When to use |
| - | - | - |
| `collect` | UPI Collect | Cashfree sends a collect request to the customer's UPI app. |
| `link` | UPI Intent | A deep link opens the customer's UPI app directly on mobile. |
| `qrcode` | UPI QR | A QR code is generated for the customer to scan and approve the mandate. |

## Integrate the UPI OTM flow

Use the following steps to create orders, start a UPI mandate session so customers can approve a block, capture or void the authorisation, and issue refunds after capture.

<Steps>
  <Step title="Create an order and payment session">
    Create an order with Cashfree using the [Create Order API](/docs/api-reference/payments/latest/orders/create-order) and your order and customer details.

    Use the following cURL example as a template when you call the API from your application.

    <Accordion title="Sample create order request">
      ```bash title="Request sample" theme={"dark"}
      curl --request POST \
          --url https://api.cashfree.com/pg/orders \
          --header 'x-client-id: <CLIENT_ID>' \
          --header 'x-client-secret: <CLIENT_SECRET>' \
          --header 'Accept: application/json' \
          --header 'Content-Type: application/json' \
          --header 'x-api-version: 2023-08-01' \
          --data '{
          "order_amount": 100.00,
          "order_currency": "INR",
          "order_id": "devstudio_4809486",
          "customer_details": {
              "customer_id": "devstudio_user",
              "customer_phone": "8474090589"
          },
          "order_meta": {
              "return_url": "https://www.cashfree.com/devstudio/preview/pg/web/checkout?order_id={order_id}"
          }
      }'
      ```
    </Accordion>
  </Step>

  <Step title="Create UPI mandate session to block funds">
    Create the OTM transaction with Cashfree using the [Order Pay API](/docs/api-reference/payments/latest/payments/order-pay).

    The sample below uses UPI Collect; you can adapt the payload for your channel.

    <Accordion title="Sample UPI Collect mandate request">
      ```bash title="UPI Collect" theme={"dark"}
      curl --request POST \
          --url https://api.cashfree.com/pg/orders/sessions \
          --header 'x-client-id: <CLIENT_ID>' \
          --header 'x-client-secret: <CLIENT_SECRET>' \
          --header 'Accept: application/json' \
          --header 'Content-Type: application/json' \
          --header 'x-api-version: 2023-08-01' \
          --data '{
          "payment_method": {
              "upi": {
                  "channel": "collect",
                  "upi_id": "testsuccess@gocash",
                  "authorize_only": true,
                  "authorization": {
                      "approve_by": "2024-07-02T10:20:12+05:30",
                      "start_time": "2024-09-21T12:34:34Z",
                      "end_time": "2024-10-22T12:34:34Z"
                  }
              }
          },
          "payment_session_id": "sessionid"
      }'
      ```
    </Accordion>

    For UPI Intent or UPI QR, use the following `channel` values:

    * `link` for UPI Intent
    * `qrcode` for UPI QR

    Cashfree calls the acquiring bank to create an OTM transaction. If the customer approves the mandate, you receive a `SUCCESS` response and a webhook notification. The amount is blocked in the customer's account, but no amount is debited at this stage.

    <Note>The mandate blocks funds but does not debit them immediately. Capture the amount only when you are ready to complete the transaction.</Note>
  </Step>

  <Step title="Capture the mandate">
    To capture the mandate, call the [Preauthorisation API](/docs/api-reference/payments/latest/payments/preauthorisation) with the `CAPTURE` action.

    <Note>The captured amount must be less than or equal to the order amount.</Note>

    Use the following cURL example when you send a capture action for the order.

    <Accordion title="Sample capture request">
      ```bash title="Capture mandate" theme={"dark"}
      curl --request POST \
           --url https://api.cashfree.com/pg/orders/<ORDER_ID>/authorization \
           --header 'Accept: application/json' \
           --header 'x-client-id: <CLIENT_ID>' \
           --header 'x-client-secret: <CLIENT_SECRET>' \
           --header 'Content-Type: application/json' \
           --header 'x-api-version: 2023-08-01' \
           --data '{
        "action": "CAPTURE",
        "amount": 100
      }'
      ```
    </Accordion>

    Cashfree calls the acquiring bank to capture the mandate. If the capture succeeds, the payment amount is settled to you according to the settlement cycle.

    In most cases, capture succeeds immediately. For a small percentage of requests, you receive a failure response and the final outcome is confirmed later. For details on handling these cases, see [Capture error codes and handling](#capture-error-codes-and-handling).
  </Step>

  <Step title="Void the mandate or process a refund">
    Choose one path: void releases a block only before capture; refund applies only after capture. You do not run both for the same order.

    To void the mandate before capture, call the [Preauthorisation API](/docs/api-reference/payments/latest/payments/preauthorisation) with the `VOID` action.

    Use the following cURL example when you void an authorisation.

    <Accordion title="Sample void request">
      ```bash title="Void mandate" theme={"dark"}
      curl --request POST \
           --url https://api.cashfree.com/pg/orders/<ORDER_ID>/authorization \
           --header 'Accept: application/json' \
           --header 'x-client-id: <CLIENT_ID>' \
           --header 'x-client-secret: <CLIENT_SECRET>' \
           --header 'Content-Type: application/json' \
           --header 'x-api-version: 2023-08-01' \
           --data '{
        "action": "VOID"
      }'
      ```
    </Accordion>

    Cashfree calls the acquiring bank to void the mandate. If the void succeeds, the blocked amount is released from the customer's account.

    <Note>If the bank returns a failure response, Cashfree automatically retries the void up to three times. If the void does not succeed, the blocked funds are released automatically at mandate expiry (`end_time`).</Note>

    To refund after capture, use the [Create Refund API](/docs/api-reference/payments/latest/refunds/create-refund) instead of void. A refund can be initiated only after the transaction is captured. Use the following steps to process a refund:

    1. Call the [Create Refund API](/docs/api-reference/payments/latest/refunds/create-refund) to initiate the refund.
    2. Cashfree submits the refund to the acquiring bank for processing.
    3. If processing succeeds, the amount is refunded to the customer.
    4. If the refund fails, Cashfree retries every six hours for up to five attempts.

    Use the following cURL example when you complete step 1 with the [Create Refund API](/docs/api-reference/payments/latest/refunds/create-refund).

    <Accordion title="Sample create refund request">
      ```bash title="Create refund" theme={"dark"}
      curl --request POST \
          --url https://api.cashfree.com/pg/orders/<ORDER_ID>/refunds \
          --header 'x-client-id: <CLIENT_ID>' \
          --header 'x-client-secret: <CLIENT_SECRET>' \
          --header 'Accept: application/json' \
          --header 'Content-Type: application/json' \
          --header 'x-api-version: 2023-08-01' \
          --data '{
        "refund_amount": 100,
        "refund_id": "refund_001"
      }'
      ```
    </Accordion>

    <Note>If the refund remains unsuccessful after all retry attempts, Cashfree coordinates directly with the bank to process the refund offline.</Note>
  </Step>
</Steps>

## Capture error codes and handling

For a small percentage of captures from the [Preauthorisation API](/docs/api-reference/payments/latest/payments/preauthorisation) that do not return an immediate success, Cashfree returns one of the following error codes. Each code has a defined resolution path.

| Error code | Meaning | What to expect |
| - | - | - |
| `59` | Processing delay at bank | Cashfree escalates to NPCI. Delayed success can be delivered on T+5 business days. |
| `K1` | Bank timeout or hold | Cashfree escalates to NPCI. Delayed success can be delivered on T+5 business days. |
| `VH` | Bank hold or verification hold | Cashfree escalates to NPCI. Delayed success can be delivered on T+5 business days. |
| `VO` | Void override (not settable) | The transaction is not settled. No further action is available through Cashfree for this capture attempt. |

<Note>Error codes `59`, `K1`, and `VH` are recoverable. Cashfree escalates these to NPCI and the settlement may arrive within T+5 business days. Error code `VO` is non-recoverable and has a very low occurrence rate.</Note>

## Integration checklist

Use the following checklist to validate a complete UPI OTM integration:

* Obtain `x-client-id` and `x-client-secret` from the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
* Create an order using the [Create Order API](/docs/api-reference/payments/latest/orders/create-order) and store the `payment_session_id`.
* Initiate the UPI OTM session with the [Order Pay API](/docs/api-reference/payments/latest/payments/order-pay) using `authorize_only: true` and the required `channel`.
* Call the [Preauthorisation API](/docs/api-reference/payments/latest/payments/preauthorisation) with `action: CAPTURE` after fulfilment.
* Call the [Preauthorisation API](/docs/api-reference/payments/latest/payments/preauthorisation) with `action: VOID` for cancellations before capture.
* Create a refund using the [Create Refund API](/docs/api-reference/payments/latest/refunds/create-refund) only for orders already captured.
* Handle error codes `59`, `K1`, and `VH` by waiting up to T+5 business days for delayed settlement confirmation from NPCI.

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/payments/latest/orders/create-order">Create Order API</a></li>
    <li><a href="/docs/api-reference/payments/latest/payments/order-pay">Order Pay API</a></li>
    <li><a href="/docs/api-reference/payments/latest/payments/preauthorisation">Preauthorisation API</a></li>
    <li><a href="/docs/api-reference/payments/latest/refunds/create-refund">Create Refund API</a></li>
    <li><a href="/docs/payments/webhooks">Payment Webhooks</a></li>
    <li><a href="/docs/payments/features/token-vault">Token Vault Overview</a></li>
  </ul>
</div>


# Signature Verification
Source: https://www.cashfree.com/docs/payments/subscription/webhook-signature

Validate Cashfree Subscriptions webhook signatures using HMAC verification to confirm authenticity and reject spoofed events before processing them.

Webhook signature verification validates that webhook notifications are sent by Cashfree and haven't been tampered with during transmission. This cryptographic verification protects your server from accepting malicious or forged webhook requests.

Each webhook request sent by Cashfree includes the following:

| Parameter | Description |
| - | - |
| `x-webhook-signature` | HMAC SHA256 signature generated by Cashfree. |
| `x-webhook-timestamp` | Timestamp of when the webhook was generated. |
| Request body | The actual webhook payload. |

To validate the webhook, verify the signature using your webhook secret key.

## Verification flow

To validate the webhook:

<Steps>
  <Step title="Capture headers and raw payload">
    * Read `x-webhook-signature` from request headers.
    * Read `x-webhook-timestamp` from request headers.
    * Capture the raw request body.

    <Warning>
      Don't modify, parse, or reformat the request body before verification.
    </Warning>
  </Step>

  <Step title="Create signature data">
    Concatenate the timestamp and raw request body:

    ```text theme={"dark"}
    signatureData = timestamp + rawBody
    ```
  </Step>

  <Step title="Generate HMAC SHA256 signature">
    * Use your secret key.
    * Apply HMAC SHA256 hashing on `signatureData`.

    <Warning>
      Please note that the Partner API key should be used for partner level webhooks.
    </Warning>
  </Step>

  <Step title="Encode signature">
    Encode the hash as a Base64 string.
  </Step>

  <Step title="Compare signatures">
    Compare the computed signature with the received signature:

    ```text theme={"dark"}
    computed_signature == x-webhook-signature
    ```

    * If matched: Webhook is valid.
    * If not matched: Reject the request.
  </Step>
</Steps>

## Sample implementations

Select your language or framework to view a sample implementation.

<Accordion title="Node.js (Express)">
  ```javascript Node.js theme={"dark"}
  const express = require("express");
  const crypto = require("crypto");

  const app = express();

  // Capture raw body
  app.use(express.json({
    verify: (req, res, buf) => {
      req.rawBody = buf.toString();
    }
  }));

  function verifyWebhook(req) {
    const signature = req.headers["x-webhook-signature"];
    const timestamp = req.headers["x-webhook-timestamp"];
    const rawBody = req.rawBody;

    const secretKey = process.env.CASHFREE_WEBHOOK_SECRET;

    const computedSignature = crypto
      .createHmac("sha256", secretKey)
      .update(timestamp + rawBody)
      .digest("base64");

    return computedSignature === signature;
  }

  app.post("/webhook", (req, res) => {
    if (!verifyWebhook(req)) {
      return res.status(400).send("Invalid signature");
    }

    res.send("Webhook received");
  });
  ```
</Accordion>

<Accordion title="Python (Flask)">
  ```python Python theme={"dark"}
  import hmac
  import hashlib
  import base64
  from flask import request

  def verify_webhook(secret_key):
      webhook_signature = request.headers.get("x-webhook-signature")
      timestamp = request.headers.get("x-webhook-timestamp")

      raw_body = request.get_data(as_text=True)

      signature_data = timestamp + raw_body

      dig = hmac.new(
          secret_key.encode('utf-8'),
          msg=signature_data.encode('utf-8'),
          digestmod=hashlib.sha256
      ).digest()

      computed_signature = base64.b64encode(dig).decode()

      return computed_signature == webhook_signature
  ```
</Accordion>

<Accordion title="Go">
  ```go Go theme={"dark"}
  import (
  	"crypto/hmac"
  	"crypto/sha256"
  	"encoding/base64"
  	"io/ioutil"
  	"net/http"
  )

  func verifyWebhook(r *http.Request, secretKey string) bool {
  	signature := r.Header.Get("x-webhook-signature")
  	timestamp := r.Header.Get("x-webhook-timestamp")

  	bodyBytes, _ := ioutil.ReadAll(r.Body)
  	rawBody := string(bodyBytes)

  	h := hmac.New(sha256.New, []byte(secretKey))
  	h.Write([]byte(timestamp + rawBody))
  	computed := base64.StdEncoding.EncodeToString(h.Sum(nil))

  	return computed == signature
  }
  ```
</Accordion>

<Accordion title="PHP">
  ```php PHP theme={"dark"}
  <?php

  function verifyWebhook($secretKey) {
      $rawBody = file_get_contents("php://input");
      $timestamp = $_SERVER['HTTP_X_WEBHOOK_TIMESTAMP'];
      $signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'];

      $computed = base64_encode(
          hash_hmac('sha256', $timestamp . $rawBody, $secretKey, true)
      );

      return $computed === $signature;
  }
  ?>
  ```
</Accordion>

<Accordion title="Java">
  ```java Java theme={"dark"}
  import javax.crypto.Mac;
  import javax.crypto.spec.SecretKeySpec;
  import java.util.Base64;

  public class WebhookValidator {

      public static boolean verify(String rawBody, String timestamp, String signature, String secretKey) {
          try {
              String data = timestamp + rawBody;

              Mac mac = Mac.getInstance("HmacSHA256");
              mac.init(new SecretKeySpec(secretKey.getBytes(), "HmacSHA256"));

              byte[] hash = mac.doFinal(data.getBytes());
              String computed = Base64.getEncoder().encodeToString(hash);

              return computed.equals(signature);

          } catch (Exception e) {
              return false;
          }
      }
  }
  ```
</Accordion>

<Accordion title="C# (.NET)">
  ```csharp C# theme={"dark"}
  using System;
  using System.Security.Cryptography;
  using System.Text;

  public class WebhookValidator
  {
      public static bool Verify(string rawBody, string timestamp, string signature, string secretKey)
      {
          var data = timestamp + rawBody;

          using (var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secretKey)))
          {
              var hash = hmac.ComputeHash(Encoding.UTF8.GetBytes(data));
              var computed = Convert.ToBase64String(hash);

              return computed == signature;
          }
      }
  }
  ```
</Accordion>

## Security requirements

Keep the following requirements in mind when implementing webhook signature verification.

* Always use the raw request body for signature computation.
* Don't modify, parse, or reformat the payload before verification.
* Store your webhook secret key securely. Use environment variables.
* Reject webhook requests if signature mismatch occurs or required headers are missing.

## Best practices

Use these practices to improve the security and reliability of your webhook implementation.

* Validate timestamp to prevent replay attacks (recommended window: 5 minutes).
* Log invalid webhook attempts for debugging and monitoring.
* Process webhook events only after successful signature verification.

## Summary

The verification process covers the following steps:

1. Capture the `x-webhook-signature` and `x-webhook-timestamp` headers along with the raw request body.
2. Concatenate the timestamp and raw body to form the signature data.
3. Generate an HMAC SHA256 hash using your webhook secret key.
4. Encode the hash as a Base64 string.
5. Compare the computed signature with `x-webhook-signature`. If they match, the webhook is valid. If they don't match, reject the request.


# Events
Source: https://www.cashfree.com/docs/payments/subscription/webhooks

Receive Cashfree Subscriptions webhook events for mandate authorisation, charges, payment status changes, and subscription lifecycle updates on your endpoint.

Cashfree sends webhook notifications to your server whenever significant events occur during the lifecycle of a subscription, enabling you to track subscription status changes, payment outcomes, authorisation updates, and refund status in real-time without polling the API. By listening to these webhooks, you can automate your business workflows, update your database, and keep your customers informed about their subscription status.

Below are the various events that can be sent to your webhook endpoint. These webhooks will be triggered if you have integrated the Subscription API.

<Note>
  * If the merchant added the webhook under the 2025-01-01 version, they will receive the same version of the webhook for older subscriptions as well.
  * While filling the UPI payment methods, `upi_instrument` and `upi_instrument_number` will remain empty for webhook versions before 2025. This will be implemented in later versions.
  * While filling the UPI payment methods, `upi_payer_account_number` and `upi_payer_ifsc` will be applicable only for TPV customers who have passed TPV details while creating the subscription.
</Note>

* [`SUBSCRIPTION_STATUS_CHANGED`](/docs/api-reference/payments/latest/subscription/webhooks#subscription_status_changed)
* [`SUBSCRIPTION_AUTH_STATUS`](/docs/api-reference/payments/latest/subscription/webhooks#subscription_auth_status)
* [`SUBSCRIPTION_PAYMENT_NOTIFICATION_INITIATED`](/docs/api-reference/payments/latest/subscription/webhooks#subscription_payment_notification_initiated)
* [`SUBSCRIPTION_PAYMENT_SUCCESS`](/docs/api-reference/payments/latest/subscription/webhooks#subscription_payment_success)
* [`SUBSCRIPTION_PAYMENT_FAILED`](/docs/api-reference/payments/latest/subscription/webhooks#subscription_payment_failed)
* [`SUBSCRIPTION_PAYMENT_CANCELLED`](/docs/api-reference/payments/latest/subscription/webhooks#subscription_payment_cancelled)
* [`SUBSCRIPTION_REFUND_STATUS`](/docs/api-reference/payments/latest/subscription/webhooks#subscription_refund_status)
* [`SUBSCRIPTION_CARD_EXPIRY_REMINDER`](/docs/api-reference/payments/latest/subscription/webhooks#subscription_card_expiry_reminder)
* [`SUBSCRIPTION_CONTROLLED_NOTIFICATION_STATUS`](/docs/api-reference/payments/latest/subscription/webhooks#subscription_controlled_notification_status)
* [`SUBSCRIPTION_CONTROLLED_EXECUTION_STATUS`](/docs/api-reference/payments/latest/subscription/webhooks#subscription_controlled_execution_status)

Payment method object attributes:

<CodeGroup>
  ```javascript UPI theme={"dark"}
  "payment_method": {
        "upi": {
          "channel": "collect",
          "upi_id": "8709228804@ybl",
          "upi_instrument": "",
          "upi_instrument_number": "",
          "upi_payer_account_number": "",
          "upi_payer_ifsc": ""
        }
  },
  "payment_group": "upi"
  ```

  ```javascript ENACH theme={"dark"}
  "payment_method": {
      "enach": {
        "channel": "link",
        "auth_mode": "aadhar",
        "account_type": "",
        "account_number": "",
        "account_ifsc": "",
        "account_holder_name": "",
        "account_bank_code": ""
      }
  },
  "payment_group": "enach"
  ```

  ```javascript PNACH theme={"dark"}
  "payment_method": {
      "pnach": {
        "channel": "link",
        "mandate_creation_date": "",
        "mandate_start_date": "",
        "account_type": "",
        "account_number": "",
        "account_ifsc": "",
        "account_holder_name": "",
        "account_bank_code": ""
      }
  },
  "payment_group": "pnach"
  ```

  ```javascript Debit/Credit card theme={"dark"}
  {
    "payment_method": {
      "card": {
        "channel": null,
        "card_number": "XXXXXXXXXXXX2123",
        "card_network": "visa",
        "card_type": "debit_card",
        "card_sub_type": "R",
        "card_country": "IN",
        "card_bank_name": "KOTAK MAHINDRA BANK",
        "card_network_reference_id": null,
        "instrument_id": "8e9cc167-4fe2-4ece-be8d-c1b224e50a23"
      }
    },
    "payment_group": "debit_card"
  }
  ```
</CodeGroup>

## SUBSCRIPTION\_STATUS\_CHANGED

Whenever a subscription is created it goes to initialised state and customer is expected to authorise it. The list of statuses where this webhook will get triggered are:

* ACTIVE
* ON\_HOLD
* COMPLETED
* CUSTOMER\_CANCELLED
* CUSTOMER\_PAUSED
* EXPIRED
* LINK\_EXPIRED
* BANK\_APPROVAL\_PENDING
* CANCELLED
* CARD\_EXPIRED

<Tabs>
  <Tab title="Version (2025-01-01)">
    ```javascript theme={"dark"}
    {
    "data": {
    "subscription_details": {
      "cf_subscription_id": "23639356",
      "subscription_id": "mozuyYwUCbWEfJVVRLi",
      "subscription_status": "BANK_APPROVAL_PENDING",
      "subscription_expiry_time": "2055-08-07T10:30:46",
      "subscription_first_charge_time": null,
      "subscription_tags": null,
      "next_schedule_date": null
    },
    "customer_details": {
      "customer_name": null,
      "customer_email": "john@dummy.com",
      "customer_phone": "9900000000"
    },
    "plan_details": {
      "plan_id": "mozuyYwUCbWEfJVVRLi",
      "plan_name": "6Msuj2mttuf2F5P1FYVSet",
      "plan_type": "ON_DEMAND",
      "plan_max_cycles": 0,
      "plan_recurring_amount": null,
      "plan_max_amount": 399.00,
      "plan_interval_type": null,
      "plan_intervals": null,
      "plan_currency": "INR",
      "plan_note": null,
      "plan_status": null
    },
    "authorization_details": {
      "authorization_amount": 2.00,
      "authorization_amount_refund": false,
      "approve_by_time": "2025-09-06T10:30:47",
      "authorization_reference": "6ba74ac2b047424da95591xxxxx[at]xxxx",
      "authorization_time": "2025-08-07T10:31:36",
      "authorization_status": "PENDING",
      "payment_id": "49988270",
      "payment_method": {
        "upi": {
          "channel": "link",
          "upi_id": "9910000000@ybl",
          "upi_instrument": "",
          "upi_instrument_number": "",
          "upi_payer_account_number": "",
          "upi_payer_ifsc": ""
        }
      },
      "payment_group": "upi"
    },
    "payment_gateway_details": {
      "gateway_name": "CASHFREE",
      "gateway_subscription_id": "23639356",
      "gateway_plan_id": "mozuyYwUCbWEfJVVRLi",
      "gateway_auth_id": "6ba74ac2b047424da95591xxxxx[at]xxxx"
    }
    },
    "event_time": "2025-08-07T10:31:35+05:30",
    "type": "SUBSCRIPTION_STATUS_CHANGED"
    }
    ```
  </Tab>

  <Tab title="Version (2023-08-01)">
    ```javascript theme={"dark"}
    {
    "data": {
        "subscription_details": {
            "cf_subscription_id": "123456",
            "subscription_id": "Demo_Subscription",
            "subscription_status": "ACTIVE",
            "subscription_expiry_time": "2024-01-14T23:00:08+05:30",
            "subscription_first_charge_time": "2024-01-10T23:00:08+05:30"
        },
        "customer_details": {
            "customer_name": "john",
            "customer_email": "john@dummy.com",
            "customer_phone": "9900000000"
        },
        "plan_details": {
            "plan_id": "plan12345",
            "plan_name": "Plan Name",
            "plan_type": "ON_DEMAND",
            "plan_max_cycles": 10,
            "plan_recurring_amount": 100.00,
            "plan_max_amount": 1000.00,
            "plan_currency": "INR",
            "plan_note": "Note",
            "plan_status": "ACTIVE"
        },
        "authorization_details": {
            "authorizationAmount": 1.00,
            "authorizationAmountRefund": true,
            "approveByTime": "2025-09-06T16:44:48",
            "authorizationReference": "544edde057f34ce588627axxxxx[at]xxxx",
            "authorizationTime": "2025-08-07T16:46:06",
            "authorizationStatus": "PENDING",
            "paymentId": "50088288",
            "paymentMethod": "upi",
            "instrumentId": "xxxxx@xxxx"
        },
        "payment_gateway_details": {
            "gateway_name": "CASHFREE",
            "gateway_subscription_id": "Demo_Subscription",
            "gateway_plan_id": "plan12345",
            "gateway_auth_id": "6595231908096894505959"
        }
    },
    "event_time": "2023-01-03T11:16:10+05:30",
    "type": "SUBSCRIPTION_STATUS_CHANGED"
    }
    ```
  </Tab>
</Tabs>

## SUBSCRIPTION\_AUTH\_STATUS

The event is triggered when the checkout is completed by the customer for success and failed cases.

<Tabs>
  <Tab title="Version (2026-01-01)">
    ```javascript theme={"dark"}
    {
     "data": {
       "payment_id": "ab-SUBV2ODRFhdJuHlcQYyFw-1",
       "cf_payment_id": "49988825",
       "cf_txn_id": "4213159266",
       "cf_order_id": "4519691525",
       "subscription_id": "mozth7smWGCCqPRaSv7",
       "cf_subscription_id": "23639858",
       "payment_type": "AUTH",
       "subscription_details": {
         "cf_subscription_id": "23639858",
         "subscription_id": "mozth7smWGCCqPRaSv7",
         "subscription_status": "ACTIVE",
         "subscription_expiry_time": "2047-07-30T13:24:54",
         "subscription_first_charge_time": null,
         "subscription_tags": {
           "company": "Cashfree",
           "name": "Payment link"
         },
         "next_schedule_date": null
       },
       "authorization_details": {
         "authorization_amount": 2.00,
         "authorization_amount_refund": false,
         "approve_by_time": "",
         "authorization_reference": "cce92d335be0467693c020xxxxx[at]xxxx",
         "authorization_time": "2025-08-07T10:34:23+05:30",
         "authorization_status": "FAILED",
         "payment_id": "ab-SUBV2ODRFhdJuHlcQYyFw-1",
         "payment_method": {
           "upi": {
             "channel": "link",
             "upi_id": "9910000000@ybl",
             "upi_instrument": "",
             "upi_instrument_number": "",
             "upi_payer_account_number": "",
             "upi_payer_ifsc": ""
           }
         },
         "payment_group": "upi"
       },
       "payment_amount": 2.00,
       "payment_currency": "INR",
       "payment_schedule_date": "",
       "payment_initiated_date": "2025-08-07T10:33:56+05:30",
       "payment_remarks": "auth payment",
       "retry_attempts": 0,
       "failure_details": {
         "failure_reason": "DEBIT HAS BEEN FAILED"
       },
       "payment_status": "FAILED",
       "payment_gateway_details": {
         "gateway_name": "CASHFREE",
         "gateway_subscription_id": "23639858",
         "gateway_payment_id": "49988825"
       }
     },
     "event_time": "2025-08-07T10:34:23+05:30",
     "type": "SUBSCRIPTION_AUTH_STATUS"
    }
    ```
  </Tab>

  <Tab title="Version (2025-01-01)">
    ```javascript theme={"dark"}
    {
     "data": {
       "payment_id": "ab-SUBV2ODRFhdJuHlcQYyFw-1",
       "cf_payment_id": "49988825",
       "cf_txn_id": "4213159266",
       "cf_order_id": "4519691525",
       "subscription_id": "mozth7smWGCCqPRaSv7",
       "cf_subscription_id": "23639858",
       "payment_type": "AUTH",
       "authorization_details": {
         "authorization_amount": 2.00,
         "authorization_amount_refund": false,
         "approve_by_time": "",
         "authorization_reference": "cce92d335be0467693c020xxxxx[at]xxxx",
         "authorization_time": "2025-08-07T10:34:23+05:30",
         "authorization_status": "FAILED",
         "payment_id": "ab-SUBV2ODRFhdJuHlcQYyFw-1",
         "payment_method": {
           "upi": {
             "channel": "link",
             "upi_id": "9910000000@ybl",
             "upi_instrument": "",
             "upi_instrument_number": "",
             "upi_payer_account_number": "",
             "upi_payer_ifsc": ""
           }
         },
         "payment_group": "upi"
       },
       "payment_amount": 2.00,
       "payment_currency": "INR",
       "payment_schedule_date": "",
       "payment_initiated_date": "2025-08-07T10:33:56+05:30",
       "payment_remarks": "auth payment",
       "retry_attempts": 0,
       "failure_details": {
         "failure_reason": "DEBIT HAS BEEN FAILED"
       },
       "payment_status": "FAILED",
       "payment_gateway_details": {
         "gateway_name": "CASHFREE",
         "gateway_subscription_id": "23639858",
         "gateway_payment_id": "49988825"
       }
     },
     "event_time": "2025-08-07T10:34:23+05:30",
     "type": "SUBSCRIPTION_AUTH_STATUS"
    }
    ```
  </Tab>

  <Tab title="Version (2023-08-01)">
    ```javascript theme={"dark"}
    {
    "data": {
        "payment_id": "12345",
        "cf_payment_id": "67890",
        "cf_txn_id": "789012",
        "cf_order_id": "98765",
        "subscription_id": "sub12345",
        "cf_subscription_id": "sub67890",
        "payment_type": "DEBIT_CARD",
        "authorization_details": {
            "authorization_amount": 100,
            "authorization_amount_refund": true,
            "approve_by_time": "2024-07-20T16:09:50+05:30",
            "authorization_reference": "6595231908096894505959",
            "authorization_time": "2024-07-20T16:09:51",
            "authorization_status": "ACTIVE",
            "payment_id": "123",
            "payment_method": "DEBIT_CARD",
            "instrument_id": "hsdg9"
        },
        "payment_amount": 200.75,
        "payment_schedule_date": "2024-07-20",
        "payment_initiated_date": "2024-07-20",
        "payment_remarks": "auth payment",
        "retry_attempts": 0,
        "failureDetails": null,
        "payment_status": "SUCCESS",
        "payment_gateway_details": {
            "gateway_name": "CASHFREE",
            "gateway_subscription_id": "Demo_Subscription",
            "gateway_payment_id": "payment12345"
        }
    },
    "event_time": "2024-07-20T11:16:10+05:30",
    "type": "SUBSCRIPTION_AUTH_STATUS"
    }
    ```
  </Tab>
</Tabs>

## SUBSCRIPTION\_PAYMENT\_NOTIFICATION\_INITIATED

This webhook is used to inform the merchant that we have sent a notification of payment to the customer.

<Tabs>
  <Tab title="Version (2026-01-01)">
    ```javascript Version (2026-01-01) theme={"dark"}
    {
    "data": {
    "payment_id": "ab-SUBV2ODR683gV1CXF85ev-1",
    "cf_payment_id": "49970855",
    "cf_txn_id": null,
    "cf_order_id": "",
    "subscription_id": "moziva9hyjiLtCuGN74",
    "cf_subscription_id": "22390006",
    "payment_type": "CHARGE",
    "subscription_details": {
      "cf_subscription_id": "22390006",
      "subscription_id": "moziva9hyjiLtCuGN74",
      "subscription_status": "ACTIVE",
      "subscription_expiry_time": "2047-07-30T13:24:54",
      "subscription_first_charge_time": null,
      "subscription_tags": {
        "company": "Cashfree",
        "name": "Payment link"
      },
      "next_schedule_date": null
    },
    "authorization_details": {
      "authorization_amount": 399.00,
      "authorization_amount_refund": false,
      "approve_by_time": "",
      "authorization_reference": null,
      "authorization_time": "",
      "authorization_status": null,
      "payment_id": "ab-SUBV2ODR683gV1CXF85ev-1",
      "payment_method": null,
      "payment_group": null
    },
    "payment_amount": 399.00,
    "payment_currency": "INR",
    "payment_schedule_date": "2025-08-08T12:00:00+05:30",
    "payment_initiated_date": "2025-08-07T09:08:09+05:30",
    "payment_remarks": null,
    "retry_attempts": 0,
    "failure_details": {
      "failure_reason": null
    },
    "payment_status": "INITIALIZED",
    "payment_gateway_details": {
      "gateway_name": "CASHFREE",
      "gateway_subscription_id": "22390006",
      "gateway_payment_id": "49970855"
    }
    },
    "event_time": "2025-08-07T09:51:07+05:30",
    "type": "SUBSCRIPTION_PAYMENT_NOTIFICATION_INITIATED"
    }
    ```
  </Tab>

  <Tab title="Version (2025-01-01)">
    ```javascript Version (2025-01-01) theme={"dark"}
    {
    "data": {
    "payment_id": "ab-SUBV2ODR683gV1CXF85ev-1",
    "cf_payment_id": "49970855",
    "cf_txn_id": null,
    "cf_order_id": "",
    "subscription_id": "moziva9hyjiLtCuGN74",
    "cf_subscription_id": "22390006",
    "payment_type": "CHARGE",
    "authorization_details": {
      "authorization_amount": 399.00,
      "authorization_amount_refund": false,
      "approve_by_time": "",
      "authorization_reference": null,
      "authorization_time": "",
      "authorization_status": null,
      "payment_id": "ab-SUBV2ODR683gV1CXF85ev-1",
      "payment_method": null,
      "payment_group": null
    },
    "payment_amount": 399.00,
    "payment_currency": "INR",
    "payment_schedule_date": "2025-08-08T12:00:00+05:30",
    "payment_initiated_date": "2025-08-07T09:08:09+05:30",
    "payment_remarks": null,
    "retry_attempts": 0,
    "failure_details": {
      "failure_reason": null
    },
    "payment_status": "INITIALIZED",
    "payment_gateway_details": {
      "gateway_name": "CASHFREE",
      "gateway_subscription_id": "22390006",
      "gateway_payment_id": "49970855"
    }
    },
    "event_time": "2025-08-07T09:51:07+05:30",
    "type": "SUBSCRIPTION_PAYMENT_NOTIFICATION_INITIATED"
    }
    ```
  </Tab>

  <Tab title="Version (2023-08-01)">
    ```javascript theme={"dark"}
    {
    "data": {
        "payment_id": "12345",
        "cf_payment_id": "67890",
        "cf_txn_id": "789012",
        "cf_order_id": "98765",
        "subscription_id": "sub12345",
        "cf_subscription_id": "sub67890",
        "payment_type": "DEBIT_CARD",
        "authorization_details": {
            "authorization_amount": 100,
            "authorization_amount_refund": true,
            "approve_by_time": "2024-07-20T16:09:50+05:30",
            "authorization_reference": "6595231908096894505959",
            "authorization_time": "2024-07-20T16:09:51",
            "authorization_status": "PENDING",
            "payment_id": "123",
            "payment_method": "DEBIT_CARD",
            "instrument_id": "hsdg9"
        },
        "payment_amount": 200,
        "payment_schedule_date": "2024-07-20",
        "payment_initiated_date": "2024-07-20",
        "payment_remarks": "payment",
        "retry_attempts": 0,
        "failureDetails": null,
        "payment_status": "INITIALIZED",
        "payment_gateway_details": {
            "gateway_name": "CASHFREE",
            "gateway_subscription_id": "Demo_Subscription",
            "gateway_payment_id": "payment12345"
        }
    },
    "event_time": "2024-07-20T11:16:10+05:30",
    "type": "SUBSCRIPTION_PAYMENT_NOTIFICATION_INITIATED"
    }
    ```
  </Tab>
</Tabs>

## SUBSCRIPTION\_PAYMENT\_SUCCESS

This notification is sent whenever a successful payment is processed for an active subscription.

<Tabs>
  <Tab title="Version (2026-01-01)">
    ```javascript Version (2026-01-01) theme={"dark"}
    {
    "data": {
    "payment_id": "ab-SUBV2ODRc5Dl2meCr7Iui-1",
    "cf_payment_id": "49914526",
    "cf_txn_id": "4212435861",
    "cf_order_id": "4518936510",
    "subscription_id": "moznV33AssPd6vXsSm2",
    "cf_subscription_id": "23601811",
    "payment_type": "AUTH",
    "subscription_details": {
      "cf_subscription_id": "23601811",
      "subscription_id": "moznV33AssPd6vXsSm2",
      "subscription_status": "ACTIVE",
      "subscription_expiry_time": "2047-07-30T13:24:54",
      "subscription_first_charge_time": null,
      "subscription_tags": {
        "company": "Cashfree",
        "name": "Payment link"
      },
      "next_schedule_date": null
    },
    "authorization_details": {
      "authorization_amount": 2.00,
      "authorization_amount_refund": false,
      "approve_by_time": "",
      "authorization_reference": "427b608f83ad4cbdb6d472xxxxx[at]xxxx",
      "authorization_time": "2025-08-07T05:53:22+05:30",
      "authorization_status": "ACTIVE",
      "payment_id": "ab-SUBV2ODRc5Dl2meCr7Iui-1",
      "payment_method": {
        "upi": {
          "channel": "link",
          "upi_id": "8100000000@ybl",
          "upi_instrument": "",
          "upi_instrument_number": "",
          "upi_payer_account_number": "",
          "upi_payer_ifsc": ""
        }
      },
      "payment_group": "upi"
    },
    "payment_amount": 2.00,
    "payment_currency": "INR",
    "payment_schedule_date": "",
    "payment_initiated_date": "2025-08-07T05:52:21+05:30",
    "payment_remarks": "auth payment",
    "retry_attempts": 0,
    "failure_details": {
      "failure_reason": null
    },
    "payment_status": "SUCCESS",
    "payment_gateway_details": {
      "gateway_name": "CASHFREE",
      "gateway_subscription_id": "23601811",
      "gateway_payment_id": "49914526"
    }
    },
    "event_time": "2025-08-07T05:53:21+05:30",
    "type": "SUBSCRIPTION_PAYMENT_SUCCESS"
    }

    ```
  </Tab>

  <Tab title="Version (2025-01-01)">
    ```javascript Version (2025-01-01) theme={"dark"}
    {
    "data": {
    "payment_id": "ab-SUBV2ODRc5Dl2meCr7Iui-1",
    "cf_payment_id": "49914526",
    "cf_txn_id": "4212435861",
    "cf_order_id": "4518936510",
    "subscription_id": "moznV33AssPd6vXsSm2",
    "cf_subscription_id": "23601811",
    "payment_type": "AUTH",
    "authorization_details": {
      "authorization_amount": 2.00,
      "authorization_amount_refund": false,
      "approve_by_time": "",
      "authorization_reference": "427b608f83ad4cbdb6d472xxxxx[at]xxxx",
      "authorization_time": "2025-08-07T05:53:22+05:30",
      "authorization_status": "ACTIVE",
      "payment_id": "ab-SUBV2ODRc5Dl2meCr7Iui-1",
      "payment_method": {
        "upi": {
          "channel": "link",
          "upi_id": "8100000000@ybl",
          "upi_instrument": "",
          "upi_instrument_number": "",
          "upi_payer_account_number": "",
          "upi_payer_ifsc": ""
        }
      },
      "payment_group": "upi"
    },
    "payment_amount": 2.00,
    "payment_currency": "INR",
    "payment_schedule_date": "",
    "payment_initiated_date": "2025-08-07T05:52:21+05:30",
    "payment_remarks": "auth payment",
    "retry_attempts": 0,
    "failure_details": {
      "failure_reason": null
    },
    "payment_status": "SUCCESS",
    "payment_gateway_details": {
      "gateway_name": "CASHFREE",
      "gateway_subscription_id": "23601811",
      "gateway_payment_id": "49914526"
    }
    },
    "event_time": "2025-08-07T05:53:21+05:30",
    "type": "SUBSCRIPTION_PAYMENT_SUCCESS"
    }

    ```
  </Tab>

  <Tab title="Version (2023-08-01)">
    ```javascript theme={"dark"}
    {
    "data": {
        "payment_id": "12345",
        "cf_payment_id": "67890",
        "cf_txn_id": "789012",
        "cf_order_id": "98765",
        "subscription_id": "sub12345",
        "cf_subscription_id": "sub67890",
        "payment_type": "DEBIT_CARD",
        "authorization_details": {
            "authorization_amount": 100,
            "authorization_amount_refund": true,
            "approve_by_time": "2024-07-20T16:09:50+05:30",
            "authorization_reference": "6595231908096894505959",
            "authorization_time": "2024-07-20T16:09:51",
            "authorization_status": "ACTIVE",
            "payment_id": "123",
            "payment_method": "DEBIT_CARD",
            "instrument_id": "hsdg9"
        },
        "payment_amount": 200,
        "payment_schedule_date": "2024-07-20",
        "payment_initiated_date": "2024-07-20",
        "payment_remarks": "payment",
        "retry_attempts": 0,
        "failureDetails": null,
        "payment_status": "SUCCESS",
        "payment_gateway_details": {
            "gateway_name": "CASHFREE",
            "gateway_subscription_id": "Demo_Subscription",
            "gateway_payment_id": "payment12345"
        }
    },
    "event_time": "2024-07-20T11:16:10+05:30",
    "type": "SUBSCRIPTION_PAYMENT_SUCCESS"
    }
    ```
  </Tab>
</Tabs>

## SUBSCRIPTION\_PAYMENT\_FAILED

This notification is sent whenever payment processing fails for an active subscription.

<Tabs>
  <Tab title="Version (2026-01-01)">
    ```javascript theme={"dark"}
    {
    "data": {
    "payment_id": "ab-SUBV2ODRIeYlFEhMHfS0M-1",
    "cf_payment_id": "49585655",
    "cf_txn_id": "4212555720",
    "cf_order_id": "4519061918",
    "subscription_id": "mozh4iRHSsjre7GkDNz",
    "cf_subscription_id": "22393526",
    "payment_type": "CHARGE",
    "subscription_details": {
      "cf_subscription_id": "22393526",
      "subscription_id": "mozh4iRHSsjre7GkDNz",
      "subscription_status": "ACTIVE",
      "subscription_expiry_time": "2047-07-30T13:24:54",
      "subscription_first_charge_time": null,
      "subscription_tags": {
        "company": "Cashfree",
        "name": "Payment link"
      },
      "next_schedule_date": null
    },
    "authorization_details": {
      "authorization_amount": 399.00,
      "authorization_amount_refund": false,
      "approve_by_time": "",
      "authorization_reference": "a7d6101a7d9340269f070dxxxxx[at]xxxx",
      "authorization_time": "2025-07-25T22:37:53+05:30",
      "authorization_status": "ACTIVE",
      "payment_id": "ab-SUBV2ODRIeYlFEhMHfS0M-1",
      "payment_method": {
        "upi": {
          "channel": "link",
          "upi_id": "9910000000@ybl",
          "upi_instrument": "",
          "upi_instrument_number": "",
          "upi_payer_account_number": "",
          "upi_payer_ifsc": ""
        }
      },
      "payment_group": "upi"
    },
    "payment_amount": 399.00,
    "payment_currency": "INR",
    "payment_schedule_date": "2025-08-07T12:00:00+05:30",
    "payment_initiated_date": "2025-08-06T05:02:41+05:30",
    "payment_remarks": null,
    "retry_attempts": 0,
    "failure_details": {
      "failure_reason": "DEBIT FAILED | Insufficient Funds In Customer (Remitter) Account"
    },
    "payment_status": "FAILED",
    "payment_gateway_details": {
      "gateway_name": "CASHFREE",
      "gateway_subscription_id": "22393526",
      "gateway_payment_id": "49585655"
    }
    },
    "event_time": "2025-08-07T10:24:45+05:30",
    "type": "SUBSCRIPTION_PAYMENT_FAILED"
    }


    ```
  </Tab>

  <Tab title="Version (2025-01-01)">
    ```javascript theme={"dark"}
    {
    "data": {
    "payment_id": "ab-SUBV2ODRIeYlFEhMHfS0M-1",
    "cf_payment_id": "49585655",
    "cf_txn_id": "4212555720",
    "cf_order_id": "4519061918",
    "subscription_id": "mozh4iRHSsjre7GkDNz",
    "cf_subscription_id": "22393526",
    "payment_type": "CHARGE",
    "authorization_details": {
      "authorization_amount": 399.00,
      "authorization_amount_refund": false,
      "approve_by_time": "",
      "authorization_reference": "a7d6101a7d9340269f070dxxxxx[at]xxxx",
      "authorization_time": "2025-07-25T22:37:53+05:30",
      "authorization_status": "ACTIVE",
      "payment_id": "ab-SUBV2ODRIeYlFEhMHfS0M-1",
      "payment_method": {
        "upi": {
          "channel": "link",
          "upi_id": "9910000000@ybl",
          "upi_instrument": "",
          "upi_instrument_number": "",
          "upi_payer_account_number": "",
          "upi_payer_ifsc": ""
        }
      },
      "payment_group": "upi"
    },
    "payment_amount": 399.00,
    "payment_currency": "INR",
    "payment_schedule_date": "2025-08-07T12:00:00+05:30",
    "payment_initiated_date": "2025-08-06T05:02:41+05:30",
    "payment_remarks": null,
    "retry_attempts": 0,
    "failure_details": {
      "failure_reason": "DEBIT FAILED | Insufficient Funds In Customer (Remitter) Account"
    },
    "payment_status": "FAILED",
    "payment_gateway_details": {
      "gateway_name": "CASHFREE",
      "gateway_subscription_id": "22393526",
      "gateway_payment_id": "49585655"
    }
    },
    "event_time": "2025-08-07T10:24:45+05:30",
    "type": "SUBSCRIPTION_PAYMENT_FAILED"
    }


    ```
  </Tab>

  <Tab title="Version (2023-08-01)">
    ```javascript theme={"dark"}
    {
    "data": {
        "payment_id": "12345",
        "cf_payment_id": "67890",
        "cf_txn_id": "789012",
        "cf_order_id": "98765",
        "subscription_id": "sub12345",
        "cf_subscription_id": "sub67890",
        "payment_type": "DEBIT_CARD",
        "authorization_details": {
            "authorization_amount": 100,
            "authorization_amount_refund": true,
            "approve_by_time": "2024-07-18T16:09:50+05:30",
            "authorization_reference": "6595231908096894505959",
            "authorization_time": "2024-07-18T16:09:51",
            "authorization_status": "ACTIVE",
            "payment_id": "123",
            "payment_method": "DEBIT_CARD",
            "instrument_id": "hsdg9"
        },
        "payment_amount": 200,
        "payment_schedule_date": "2024-07-20",
        "payment_initiated_date": "2024-07-20",
        "payment_remarks": "payment",
        "retry_attempts": 0,
        "failureDetails": {
            "failureReason": "Insufficient balance"
        },
        "payment_status": "FAILED",
        "payment_gateway_details": {
            "gateway_name": "CASHFREE",
            "gateway_subscription_id": "Demo_Subscription",
            "gateway_payment_id": "payment12345"
        }
    },
    "event_time": "2024-07-20T11:16:10+05:30",
    "type": "SUBSCRIPTION_PAYMENT_FAILED"
    }
    ```
  </Tab>
</Tabs>

## SUBSCRIPTION\_PAYMENT\_CANCELLED

This notification is sent whenever payment processing is cancelled by user for an active subscription.

<Tabs>
  <Tab title="Version (2026-01-01)">
    ```javascript Version (2026-01-01) theme={"dark"}
    {
    "data": {
    "payment_id": "433563_33_1754492527395",
    "cf_payment_id": "2011332",
    "cf_txn_id": null,
    "cf_order_id": "",
    "subscription_id": "subTestIdOndemand_2025080615020470",
    "cf_subscription_id": "1220385",
    "payment_type": "CHARGE",
    "subscription_details": {
      "cf_subscription_id": "1220385",
      "subscription_id": "subTestIdOndemand_2025080615020470",
      "subscription_status": "ACTIVE",
      "subscription_expiry_time": "2047-07-30T13:24:54",
      "subscription_first_charge_time": null,
      "subscription_tags": {
        "company": "Cashfree",
        "name": "Payment link"
      },
      "next_schedule_date": null
    },
    "authorization_details": {
      "authorization_amount": 1.00,
      "authorization_amount_refund": false,
      "approve_by_time": "",
      "authorization_reference": null,
      "authorization_time": "",
      "authorization_status": null,
      "payment_id": "433563_33_1754492527395",
      "payment_method": null,
      "payment_group": null
    },
    "payment_amount": 1.00,
    "payment_currency": "INR",
    "payment_schedule_date": "2025-08-08T12:00:00+05:30",
    "payment_initiated_date": "2025-08-06T20:32:07+05:30",
    "payment_remarks": null,
    "retry_attempts": 0,
    "failure_details": {
      "failure_reason": null
    },
    "payment_status": "CANCELLED",
    "payment_gateway_details": {
      "gateway_name": "CASHFREE",
      "gateway_subscription_id": "1220385",
      "gateway_payment_id": "2011332"
    }
    },
    "event_time": "2025-08-06T20:32:07+05:30",
    "type": "SUBSCRIPTION_PAYMENT_CANCELLED"
    }
    ```
  </Tab>

  <Tab title="Version (2025-01-01)">
    ```javascript Version (2025-01-01) theme={"dark"}
    {
    "data": {
    "payment_id": "433563_33_1754492527395",
    "cf_payment_id": "2011332",
    "cf_txn_id": null,
    "cf_order_id": "",
    "subscription_id": "subTestIdOndemand_2025080615020470",
    "cf_subscription_id": "1220385",
    "payment_type": "CHARGE",
    "authorization_details": {
      "authorization_amount": 1.00,
      "authorization_amount_refund": false,
      "approve_by_time": "",
      "authorization_reference": null,
      "authorization_time": "",
      "authorization_status": null,
      "payment_id": "433563_33_1754492527395",
      "payment_method": null,
      "payment_group": null
    },
    "payment_amount": 1.00,
    "payment_currency": "INR",
    "payment_schedule_date": "2025-08-08T12:00:00+05:30",
    "payment_initiated_date": "2025-08-06T20:32:07+05:30",
    "payment_remarks": null,
    "retry_attempts": 0,
    "failure_details": {
      "failure_reason": null
    },
    "payment_status": "CANCELLED",
    "payment_gateway_details": {
      "gateway_name": "CASHFREE",
      "gateway_subscription_id": "1220385",
      "gateway_payment_id": "2011332"
    }
    },
    "event_time": "2025-08-06T20:32:07+05:30",
    "type": "SUBSCRIPTION_PAYMENT_CANCELLED"
    }
    ```
  </Tab>

  <Tab title="Version (2023-08-01)">
    ```javascript theme={"dark"}
    {
    "data": {
        "payment_id": "12345",
        "cf_payment_id": "67890",
        "cf_txn_id": "789012",
        "cf_order_id": "98765",
        "subscription_id": "sub12345",
        "cf_subscription_id": "sub67890",
        "payment_type": "DEBIT_CARD",
        "authorization_details": {
            "authorization_amount": 100,
            "authorization_amount_refund": true,
            "approve_by_time": "2024-07-18T16:09:50+05:30",
            "authorization_reference": "6595231908096894505959",
            "authorization_time": "2024-07-18T16:09:51",
            "authorization_status": "ACTIVE",
            "payment_id": "123",
            "payment_method": "DEBIT_CARD",
            "instrument_id": "hsdg9"
        },
        "payment_amount": 200,
        "payment_schedule_date": "2024-07-20",
        "payment_initiated_date": "2024-07-20",
        "payment_remarks": "payment",
        "retry_attempts": 0,
        "failureDetails": {
            "failureReason": "Subscription is not active"
        },
        "payment_status": "CANCELLED",
        "payment_gateway_details": {
            "gateway_name": "CASHFREE",
            "gateway_subscription_id": "Demo_Subscription",
            "gateway_payment_id": "payment12345"
        }
    },
    "event_time": "2024-07-20T11:16:10+05:30",
    "type": "SUBSCRIPTION_PAYMENT_CANCELLED"
    }
    ```
  </Tab>
</Tabs>

## SUBSCRIPTION\_REFUND\_STATUS

This event is triggered whenever a refund status of a transaction will be success, failed, or cancelled.

<Tabs>
  <Tab title="Version (2025-01-01)">
    ```javascript theme={"dark"}
    {
    "data": {
    "payment_id": "yCzJxeT2aXDqI",
    "cf_payment_id": "49778199",
    "refund_id": "WHOqiwy05P1l0",
    "cf_refund_id": "SUB_21ebb4bf-e84f-4afa-bb09-07aac433abe4",
    "refund_amount": 1000.00,
    "refund_speed": "STANDARD",
    "refund_note": "Tesg Refund",
    "refund_status": "SUCCESS",
    "failure_details": "",
    "refund_gateway_details": {
      "gateway_name": "CASHFREE",
      "gateway_payment_id": "49778199",
      "gateway_refund_id": "SUB_21ebb4bf-e84f-4afa-bb09-07aac433abe4"
    }
    },
    "event_time": "2025-08-06T17:20:02+05:30",
    "type": "SUBSCRIPTION_REFUND_STATUS"
    }
    ```
  </Tab>

  <Tab title="Version (2023-08-01)">
    ```javascript theme={"dark"}
    {
    "data": {
        "payment_id": "pay8643",
        "cf_payment_id": "863782648",
        "refund_id": "refund2",
        "cf_refund_id": "ref_212",
        "refund_amount": 100,
        "refund_note": "test",
        "refund_speed": "INSTANT",
        "refund_status": "SUCCESS",
        "failure_details": null,
        "payment_gateway_details": {
            "gateway_name": "CASHFREE",
            "gateway_payment_id": "pay8643",
            "gateway_refund_id": "refund2"
        }
    },
    "event_time": "2023-01-03T11:16:10+05:30",
    "type": "SUBSCRIPTION_REFUND_STATUS"
    }
    ```
  </Tab>
</Tabs>

## SUBSCRIPTION\_CARD\_EXPIRY\_REMINDER

This event is triggered 7 days prior to the card’s expiry date for active card subscriptions.

<Tabs>
  <Tab title="Version (2025-01-01)">
    ```javascript theme={"dark"}
    {
    "data": {
        "subscription_status_webhook": {
            "subscription_details": {
                "cf_subscription_id": "23661347",
                "subscription_id": "SUB_TEST_1754550382119",
                "subscription_status": "ACTIVE",
                "subscription_expiry_time": "2050-12-31T00:00:00",
                "subscription_first_charge_time": "2025-09-30T00:00:00",
                "subscription_tags": {
                    "next_schedule_date": "2025-09-30T00:10:00"
                }
            },
            "customer_details": {
                "customer_name": "John Doe",
                "customer_email": "john@cashfree.com",
                "customer_phone": "9090909090"
            },
            "plan_details": {
                "plan_id": "PLAN_1754550139964",
                "plan_name": "MY_PLAN",
                "plan_type": "PERIODIC",
                "plan_max_cycles": 2,
                "plan_recurring_amount": 5,
                "plan_max_amount": 1000,
                "plan_interval_type": "MONTH",
                "plan_intervals": 1,
                "plan_currency": null,
                "plan_note": null,
                "plan_status": null
            },
            "authorization_details": {
                "authorizationAmount": 1,
                "authorizationAmountRefund": false,
                "approveByTime": "2025-09-06T12:36:22",
                "authorizationReference": null,
                "authorizationTime": "2025-08-07T13:14:18",
                "authorizationStatus": "ACTIVE",
                "paymentId": "160594_178_1754552533131",
                "paymentMethod": "card",
                "instrumentId": null
            },
            "payment_gateway_details": {
                "gateway_name": "CASHFREE",
                "gateway_subscription_id": "23661347",
                "gateway_plan_id": "PLAN_1754550139964",
                "gateway_auth_id": null
            }
        },
        "card_expiry_date": "2025-09-30"
    },
    "event_time": "2025-09-24T02:00:09+05:30",
    "type": "SUBSCRIPTION_CARD_EXPIRY_REMINDER"
    }
    ```
  </Tab>
</Tabs>

<Note>
  The following webhooks are only relevant if you are using Controlled API endpoints for notification and charge.
</Note>

## SUBSCRIPTION\_CONTROLLED\_NOTIFICATION\_STATUS

Cashfree sends this webhook when the status of a merchant-controlled payment notification attempt changes (for example, SUCCESS or FAILED).

<Tabs>
  <Tab title="Version (2025-01-01)">
    ```javascript theme={"dark"}
    {
    "data": {
    "cf_notification_id": "3333",
    "cf_order_id": "123456",
    "cf_payment_id": "123456",
    "cf_subscription_id": "7891011",
    "cf_txn_id": "123456",
    "notification_attempted_time": "2025-06-01T22:14:59+05:30",
    "notification_completed_time": "2025-06-01T22:15:59+05:30",
    "notification_failure_details": {
      "failure_reason": "",
      "failure_error_code": "",
      "failure_sub_error_code": ""
    },
    "notification_id": "notification-001",
    "notification_initiated_time": "2025-06-01T22:14:58+05:30",
    "notification_status": "SUCCESS",
    "payment_amount": 1,
    "payment_id": "test-payment-id",
    "payment_remarks": "monthly charge",
    "payment_status": "INITIALIZED",
    "subscription_id": "test-subscription-id"
    },
    "event_time": "2025-06-01T22:15:59+05:30",
    "type": "SUBSCRIPTION_CONTROLLED_NOTIFICATION_STATUS"
    }
    ```
  </Tab>
</Tabs>

## SUBSCRIPTION\_CONTROLLED\_EXECUTION\_STATUS

Cashfree sends this webhook when the status of a merchant-controlled charge execution attempt changes (for example, SUCCESS or FAILED).

<Tabs>
  <Tab title="Version (2025-01-01)">
    ```javascript theme={"dark"}
    {
    "data": {
    "cf_execution_id": "3333",
    "cf_order_id": "123456",
    "cf_payment_id": "123456",
    "cf_subscription_id": "7891011",
    "cf_txn_id": "123456",
    "execution_attempted_time": "2025-06-01T22:14:59+05:30",
    "execution_completed_time": "2025-06-01T22:15:59+05:30",
    "execution_id": "execution-001",
    "execution_initiated_time": "2025-06-01T22:14:58+05:30",
    "execution_status": "SUCCESS",
    "failure_details": {
      "failure_reason": "",
      "failure_error_code": "",
      "failure_sub_error_code": ""
    },
    "payment_amount": 1,
    "payment_id": "test-payment-id",
    "payment_remarks": "",
    "payment_status": "SUCCESS",
    "subscription_id": "test-subscription-id"
    },
    "event_time": "2025-06-01T22:15:59+05:30",
    "type": "SUBSCRIPTION_CONTROLLED_EXECUTION_STATUS"
    }
    ```
  </Tab>
</Tabs>


# Overview
Source: https://www.cashfree.com/docs/payments/upi-reserve-pay/reserve-pay

Use Cashfree UPI Reserve Pay to block funds on a customer's UPI account once and debit automatically as products or services are delivered over time, securely.

UPI Reserve Pay is a payment framework that enables you to block customer funds upfront and debit automatically as products or services are delivered. It combines the security of One-Time Mandates (OTM) with the flexibility of multiple debits, ensuring high payment success rates and enhanced customer experience.

Reserve Pay supports the following payment modes:

* Savings Account (UPI-linked)
* Credit Line on UPI
* RuPay Credit Card on UPI

## Key features

UPI Reserve Pay provides the following capabilities:

* **Single block, multiple debits**: Block a maximum amount once and debit multiple times against the blocked amount.
* **Guaranteed funds**: Pre-blocked funds ensure payment collection without dependency on the customer's future account balance.
* **Flexible payment collection**: Debit exact amounts as services or products are delivered.
* **Automatic release**: Any unused funds are automatically released after mandate expiry or when you manually release them.
* **Webhook notifications**: Receive real-time updates for authorisations, payments, and refunds.

## Benefits

The following table describes the benefits of UPI Reserve Pay for merchants and customers:

| Merchant benefits | Customer benefits |
| - | - |
| Reduce cart abandonment by minimising friction at checkout—customers don't need to authenticate with a PIN for repeat payments. | Customers can keep money in their bank account earning interest instead of preloading wallets, or block funds via UPI credit card to avoid actual fund blocking. |
| Achieve high payment success rates and minimise failed payments (typically 10% of transactions). | Customers can authorise once and pay flexibly without multiple authentication steps for recurring payments. |
| Guarantee payment collection irrespective of the customer's future account balance. | Customers can manage funds better by blocking specific limits with each merchant (for example, ₹10,000 on a food delivery app). |
| Enable flexible business models such as **try and buy**, flexible reservations, subscriptions, and usage-based billing. | Customers can enjoy flexible payment options across multiple use cases without the need to preload funds. |

## Use cases

The following table describes common scenarios where UPI Reserve Pay adds value:

| Use case | Description |
| - | - |
| E-commerce "try and buy" or pay-on-delivery | Customers place an order and block funds (for example, ₹5,000) at checkout. When the product is delivered and confirmed, you debit only for the items the customer keeps. If the product is returned, the blocked funds are automatically released. This makes "try and buy" or "pay-on-delivery" safe for both you and your customers. |
| In-app wallets (without preloading) | Create instant wallets by asking customers to block a certain amount (for example, ₹2,000) in their bank account. Each time the customer purchases within the app, the amount is debited from the block. Unlike traditional wallets, customers don't need to preload funds, and unused blocked funds are released automatically. |
| Smart margin trading and securities | Investors block a lump-sum amount (for example, ₹5,00,000) once in their account. Brokers can then debit smaller amounts as trades are executed or as shares are allotted. Investors don't need to make multiple payments, and any unused funds remain in their account until the mandate expires. |
| Hotel and travel bookings | At the time of booking, customers block the estimated booking amount (for example, ₹10,000). The hotel or travel provider debits only the final bill at checkout or usage. If the customer cancels within the cancellation policy, the funds are automatically released. |

## How it works

UPI Reserve Pay follows a workflow where customers reserve funds once, and you can debit multiple times against the reserved amount.

### Customer and merchant workflow

The following describes the end-to-end flow:

1. **Customer reserves funds**: The customer authorises a total estimated amount via UPI PIN or pre-authorisation. For example, a customer reserves ₹10,000 for multiple purchases.

2. **You initiate multiple debits**: You debit portions of the reserved amount for each product or service delivered:
   * ₹3,000 for Product 1
   * ₹3,500 for Product 2
   * ₹3,500 for Product or Service 3

3. **No additional customer action**: The customer doesn't need to enter a UPI PIN again for each debit. Reserved funds automatically cover each transaction up to the pre-approved limit.

4. **Guaranteed settlement**: You receive funds instantly or at a guaranteed settlement schedule. The remaining reserved balance reduces automatically after each debit.

### Common scenarios

UPI Reserve Pay is particularly useful for the following business models:

* **Subscription services**: Weekly or monthly deliveries
* **Instalment payments**: Partial payments for multiple products
* **Pay-as-you-go models**: Pre-reserved credit for multiple services like rides, utilities, or rentals

### Integration workflow

The following table outlines the steps you need to follow to integrate UPI Reserve Pay:

<Steps>
  <Step title="Create Subscription (Mandate Setup)">
    Initialise the subscription by passing the required customer and plan details through the Create Subscription API.

    Once successfully created, the subscription enters the `INITIALIZED` state, indicating that mandate setup has begun but customer approval is pending.
  </Step>

  <Step title="Raise Authorisation (Customer Approval)">
    Trigger the authorisation request to block the mandate amount. The customer approves the blocked amount via UPI.

    * On successful authorisation, the subscription transitions to the `ACTIVE` state.
    * The `SUBSCRIPTION_AUTH_STATUS` webhook is triggered to notify you of the authorisation outcome.
  </Step>

  <Step title="Raise Charge (Debit Funds)">
    Initiate a charge against the blocked funds (either full or partial amount).

    * On success, the `SUBSCRIPTION_PAYMENT_SUCCESS` webhook is triggered.
    * On failure, the `SUBSCRIPTION_PAYMENT_FAILED` webhook is triggered.
  </Step>

  <Step title="Get Mandate Details">
    Use the Get Mandate Details API to retrieve:

    * All charges raised against the mandate
    * Remaining blocked amount
    * Current mandate limits and status
  </Step>

  <Step title="Refund Individual Charge">
    Refund a specific charge using the Subscription Refund API.

    * Refund updates are communicated via the `SUBSCRIPTION_REFUND_STATUS` webhook.
  </Step>

  <Step title="Manage Mandate">
    Use the Manage Mandate API to:

    * Release unused blocked funds
    * Cancel the mandate if no longer required
  </Step>
</Steps>

## Supported apps and issuers

The following UPI apps and issuers support UPI Reserve Pay.

<Tabs>
  <Tab title="UPI apps">
    The following third-party application providers (TPAPs) support UPI Reserve Pay:

    * Paytm
    * Navi
    * BHIM
  </Tab>

  <Tab title="Credit card issuers">
    The following credit card issuers support UPI Reserve Pay:

    * ICICI Bank
    * Axis Bank
    * Punjab National Bank
    * Canara Bank
    * Union Bank of India
    * Indian Bank
    * Bank of India
    * City Union Bank
    * Indian Overseas Bank
  </Tab>

  <Tab title="Credit line issuers">
    The following credit line issuers support UPI Reserve Pay:

    * City Union Bank
    * Bank of Baroda
    * South Indian Bank
    * Punjab National Bank
    * Indian Bank
    * Tamilnad Mercantile Bank
  </Tab>

  <Tab title="Savings account issuers">
    The following CASA (Current Account and Savings Account) issuers support UPI Reserve Pay:

    * SBI
    * Axis Bank
    * ICICI Bank
    * IDFC Bank
    * Kotak Mahindra Bank
    * Karur Vysya Bank
    * Kerala Gramin Bank
    * Karnataka Grameena Bank
  </Tab>
</Tabs>

## Frequently asked questions

<Accordion title="How do I enable UPI Reserve Pay for my account?">
  Contact your account manager or use the [support form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) to enable UPI Reserve Pay for your account.
</Accordion>

<Accordion title="Can I debit multiple times from a single authorisation?">
  Yes, UPI Reserve Pay allows multiple debits against a single blocked amount until the limit is reached or the mandate expires.
</Accordion>

<Accordion title="What is the maximum amount limit and expiry time?">
  The maximum blockable amount is ₹10,000, and the mandate is valid for up to 90 days.
</Accordion>

<Accordion title="What happens if the customer cancels the transaction?">
  Any unused funds are automatically released back to the customer. You will be informed about the updated status of the mandate.
</Accordion>

<Accordion title="Can I refund a partial debit?">
  Yes, individual debits can be refunded using the Subscription Refund APIs. Refund status is communicated via webhooks. Note that the refunded amount does not increase the original limit; the refund is processed like a standard UPI refund.
</Accordion>

<Accordion title="How can I check the status of a subscription or payment?">
  Use the Get Mandate Details API to view all debits, remaining limits, and subscription status.
</Accordion>

<Accordion title="Which UPI apps are supported?">
  Currently supported apps include Paytm, Navi, and BHIM. More apps will be added soon. Check with your account manager for the latest details.
</Accordion>

<Accordion title="Is there a limit on how much can be blocked?">
  The block amount is set during subscription creation and may vary by plan and merchant policy. For secondary markets, the limit can be higher. For most merchants, the current limit is ₹10,000 per month.
</Accordion>

<Accordion title="Can the mandate be irrevocable?">
  This depends on your merchant category. Please consult your account manager for details.
</Accordion>

<Accordion title="Can customers use RuPay Credit Cards via UPI Reserve Pay?">
  Yes, UPI Reserve Pay supports Savings Accounts, Credit Line on UPI, and RuPay Credit Cards.
</Accordion>

<Accordion title="What if authorisation fails due to insufficient funds?">
  You will receive a `SUBSCRIPTION_PAYMENT_FAILED` webhook. You can retry the debit if required.
</Accordion>

<Accordion title="How can the customer cancel the mandate?">
  Customers can cancel the mandate directly from their UPI app using the cancellation option.
</Accordion>

<Accordion title="What is the pricing for UPI Reserve Pay?">
  Please contact your account manager for pricing details.
</Accordion>


# Implementation Guide
Source: https://www.cashfree.com/docs/payments/upi-reserve-pay/upi-reserve-pay

Use Cashfree UPI Reserve Pay to block funds once on a customer's UPI account and debit multiple times, ideal for EMIs, usage-based billing, and subscriptions.

UPI Reserve Pay uses Single Block Multi Debit (SBMD) to allow you to block a maximum amount once from your customer's account and then debit multiple times against that blocked amount. This feature is ideal for EMIs, usage-based billing, and subscription services.

## Key benefits

* **One-time authorisation**: Customer provides approval once for multiple future debits
* **Flexible charging**: Debit multiple amounts until the blocked limit is reached or the mandate expires
* **Fund management**: Release unused blocked funds back to customers when needed

## Workflow overview

The UPI Reserve Pay SBMD workflow involves the following steps:

1. **Create subscription for mandate setup**
   * You initialise the subscription with customer and plan details
   * Subscription is created in `INITIALISED` state

2. **Raise authorisation to get customer approval**
   * You raise the authorisation request for blocking the amount
   * Customer approves the blocked amount via UPI
   * On success, subscription moves to `ACTIVE` state
   * Cashfree sends `SUBSCRIPTION_AUTH_STATUS` webhook

3. **Raise charge to debit funds**
   * You raise charges against the blocked amount (partial or multiple)
   * Payment is processed and status is sent via webhook:
     * `SUBSCRIPTION_PAYMENT_SUCCESS`
     * `SUBSCRIPTION_PAYMENT_FAILED`

4. **Get mandate details**
   * You fetch all charges and remaining limit using subscription ID

5. **Refund individual charge**
   * You can refund an individual charge
   * Notification of refund status is sent via `SUBSCRIPTION_REFUND_STATUS` webhook

6. **Manage mandate**
   * You can unblock unused debits and release funds back to the customer

## Implementation steps

UPI Reserve Pay extends the [Subscription APIs](/docs/payments/subscription/introduction) with SBMD-specific parameters for fund blocking. Follow these steps to implement the feature:

<Note>All API examples belong to version 2025-01-01.</Note>

### Quick reference

| Step | SBMD requirement | API reference |
| :- | :- | :- |
| 1. Create subscription | Add `"category": "SBMD"` in `subscription_meta` | [Create Subscription API](/docs/api-reference/payments/latest/subscription/create-subscription) |
| 2. Raise authorisation | Set `"payment_type": "AUTH"` | [Raise Payment API](/docs/api-reference/payments/latest/subscription/raise-a-charge-or-create-an-auth) |
| 3. Raise charges | Set `"payment_type": "CHARGE"` | [Raise Payment API](/docs/api-reference/payments/latest/subscription/raise-a-charge-or-create-an-auth) |
| 4. Get mandate details | No SBMD-specific changes | [Fetch Payments API](/docs/api-reference/payments/latest/subscription/fetch-details-of-all-payments-of-a-subscription) |
| 5. Refund charges | No SBMD-specific changes | [Create Refund API](/docs/api-reference/payments/latest/subscription/create-a-refund) |
| 6. Manage mandate | Only `CANCEL` action supported | [Manage Subscription API](/docs/api-reference/payments/latest/subscription/manage-subscription) |

### Step 1: Create subscription

Create a subscription to set up the mandate for blocking funds. UPI Reserve Pay requires setting the subscription category to `SBMD`.

**API Endpoint:** `POST https://api.cashfree.com/pg/subscriptions`

**Sandbox URL:** `https://sandbox.cashfree.com/pg/subscriptions`

<Tip>
  **SBMD-specific requirement**

  Add `"category": "SBMD"` in the `subscription_meta` object to enable fund blocking:

  ```json theme={"dark"}
  {
    "subscription_meta": {
      "return_url": "https://example.com/return",
      "notification_channel": ["EMAIL", "SMS"],
      "category": "SBMD"  // Required for UPI Reserve Pay
    }
  }
  ```

  For complete request parameters and response structure, see [Create Subscription API](/docs/api-reference/payments/latest/subscription/create-subscription).
</Tip>

<Accordion title="View complete SBMD request example">
  ```json Request theme={"dark"}
  {
    "subscription_id": "subscription_001",
    "customer_details": {
      "customer_name": "John Doe",
      "customer_email": "john@example.com",
      "customer_phone": "9799002505",
      "customer_bank_code": "HDFC",
      "customer_bank_account_type": "SAVINGS"
    },
    "plan_details": {
      "plan_name": "plan12345",
      "plan_type": "ON_DEMAND",
      "plan_currency": "INR",
      "plan_max_amount": 1000.00
    },
    "authorization_details": {
      "authorization_amount": 0,
      "authorization_amount_refund": true,
      "payment_methods": ["upi"]
    },
    "subscription_meta": {
      "return_url": "https://bit.ly/4glEd0W",
      "notification_channel": ["EMAIL", "SMS"],
      "category": "SBMD"
    },
    "subscription_expiry_time": "2026-01-01T23:00:08+05:30",
    "subscription_note": "UPI Reserve Pay subscription",
    "subscription_tags": {
      "psp_note": "Fund blocking for recurring payments"
    }
  }
  ```
</Accordion>

After you create the subscription, it will be in the `INITIALISED` state, ready for customer authorisation.

### Step 2: Raise authorisation

Raise an authorisation request for customers to approve the fund blocking. The key requirement for SBMD is setting `payment_type` to `AUTH`.

**API Endpoint:** `POST https://api.cashfree.com/pg/subscriptions/pay`

**Sandbox URL:** `https://sandbox.cashfree.com/pg/subscriptions/pay`

<Tip>
  **SBMD-specific requirement**

  Set `"payment_type": "AUTH"` in your request to initiate the authorisation flow:

  ```json theme={"dark"}
  {
    "subscription_id": "subscription_001",
    "payment_id": "auth_payment_001",
    "payment_remarks": "Fund blocking authorisation",
    "payment_type": "AUTH",  // Required for authorisation
    "payment_method": {
      "upi": {
        "channel": "link"  // Use "link", "qrcode", or "collect"
      }
    }
  }
  ```

  For complete request parameters and response structure, see [Raise Payment API](/docs/api-reference/payments/latest/subscription/raise-a-charge-or-create-an-auth).
</Tip>

<Accordion title="View UPI channel options">
  **Available UPI channels:**

  * `link`: Payment link that redirects to UPI apps
  * `qrcode`: QR code for scanning with UPI apps
  * `collect`: Direct UPI collect request (requires `upi_id`)

  **Example for UPI collect:**

  ```json theme={"dark"}
  {
    "payment_method": {
      "upi": {
        "channel": "collect",
        "upi_id": "john.doe@bank"
      }
    }
  }
  ```
</Accordion>

After the customer completes the authorisation, you'll receive a `SUBSCRIPTION_AUTH_STATUS` webhook notification.

#### SUBSCRIPTION\_AUTH\_STATUS webhook

<Accordion title="Authorisation success notification">
  ```json Webhook Example theme={"dark"}
  {
    "data": {
      "payment_id": "auth_payment_001",
      "cf_payment_id": "49988825",
      "cf_txn_id": "4213159266",
      "cf_order_id": "4519691525",
      "subscription_id": "subscription_001",
      "cf_subscription_id": "23639858",
      "payment_type": "AUTH",
      "authorization_details": {
        "authorization_amount": 1000.00,
        "authorization_amount_refund": false,
        "approve_by_time": "",
        "authorization_reference": "cce92d335be0467693c020xxxxx[at]xxxx",
        "authorization_time": "2025-08-07T10:34:23+05:30",
        "authorization_status": "SUCCESS",
        "payment_id": "auth_payment_001",
        "payment_method": {
          "upi": {
            "channel": "link",
            "upi_id": "9910000000@ybl",
            "upi_instrument": "",
            "upi_instrument_number": "",
            "upi_payer_account_number": "",
            "upi_payer_ifsc": ""
          }
        },
        "payment_group": "upi"
      },
      "payment_amount": 1000.00,
      "payment_currency": "INR",
      "payment_schedule_date": "",
      "payment_initiated_date": "2025-08-07T10:33:56+05:30",
      "payment_remarks": "Authorisation request",
      "retry_attempts": 0,
      "payment_status": "SUCCESS",
      "payment_gateway_details": {
        "gateway_name": "CASHFREE",
        "gateway_subscription_id": "23639858",
        "gateway_payment_id": "49988825"
      }
    },
    "event_time": "2025-08-07T10:34:23+05:30",
    "type": "SUBSCRIPTION_AUTH_STATUS"
  }
  ```
</Accordion>

### Step 3: Raise charges

After successful authorisation, you can debit amounts from the blocked funds. Set `payment_type` to `CHARGE` for debit requests.

**API Endpoint:** `POST https://api.cashfree.com/pg/subscriptions/pay`

**Sandbox URL:** `https://sandbox.cashfree.com/pg/subscriptions/pay`

<Tip>
  **SBMD-specific requirement**

  Set `"payment_type": "CHARGE"` to debit from blocked funds:

  ```json theme={"dark"}
  {
    "subscription_id": "subscription_001",
    "payment_id": "charge_payment_001",
    "payment_amount": 100,
    "payment_schedule_date": "2025-09-26T12:40:12+05:30",
    "payment_remarks": "Monthly charge",
    "payment_type": "CHARGE"  // Required for debiting
  }
  ```

  For complete request parameters and response structure, see [Raise Payment API](/docs/api-reference/payments/latest/subscription/raise-a-charge-or-create-an-auth).
</Tip>

You'll receive webhook notifications for each charge attempt:

#### SUBSCRIPTION\_PAYMENT\_SUCCESS webhook

<Accordion title="Charge success notification">
  ```json Webhook Example theme={"dark"}
  {
    "data": {
      "payment_id": "charge_payment_001",
      "cf_payment_id": "49914526",
      "cf_txn_id": "4212435861",
      "cf_order_id": "4518936510",
      "subscription_id": "subscription_001",
      "cf_subscription_id": "23601811",
      "payment_type": "CHARGE",
      "authorization_details": {
        "authorization_amount": 1000.00,
        "authorization_amount_refund": false,
        "approve_by_time": "",
        "authorization_reference": "427b608f83ad4cbdb6d472xxxxx[at]xxxx",
        "authorization_time": "2025-08-07T05:53:22+05:30",
        "authorization_status": "ACTIVE",
        "payment_id": "charge_payment_001",
        "payment_method": {
          "upi": {
            "channel": "link",
            "upi_id": "8100000000@ybl",
            "upi_instrument": "",
            "upi_instrument_number": "",
            "upi_payer_account_number": "",
            "upi_payer_ifsc": ""
          }
        },
        "payment_group": "upi"
      },
      "payment_amount": 100.00,
      "payment_currency": "INR",
      "payment_schedule_date": "",
      "payment_initiated_date": "2025-08-07T05:52:21+05:30",
      "payment_remarks": "Monthly subscription charge",
      "retry_attempts": 0,
      "failure_details": {
        "failure_reason": null
      },
      "payment_status": "SUCCESS",
      "payment_gateway_details": {
        "gateway_name": "CASHFREE",
        "gateway_subscription_id": "23601811",
        "gateway_payment_id": "49914526"
      }
    },
    "event_time": "2025-08-07T05:53:21+05:30",
    "type": "SUBSCRIPTION_PAYMENT_SUCCESS"
  }
  ```
</Accordion>

#### SUBSCRIPTION\_PAYMENT\_FAILED webhook

<Accordion title="Charge failure notification">
  ```json Webhook Example theme={"dark"}
  {
    "data": {
      "payment_id": "charge_payment_002",
      "cf_payment_id": "49585655",
      "cf_txn_id": "4212555720",
      "cf_order_id": "4519061918",
      "subscription_id": "subscription_001",
      "cf_subscription_id": "22393526",
      "payment_type": "CHARGE",
      "authorization_details": {
        "authorization_amount": 1000.00,
        "authorization_amount_refund": false,
        "approve_by_time": "",
        "authorization_reference": "a7d6101a7d9340269f070dxxxxx[at]xxxx",
        "authorization_time": "2025-07-25T22:37:53+05:30",
        "authorization_status": "ACTIVE",
        "payment_id": "charge_payment_002",
        "payment_method": {
          "upi": {
            "channel": "link",
            "upi_id": "9910000000@ybl",
            "upi_instrument": "",
            "upi_instrument_number": "",
            "upi_payer_account_number": "",
            "upi_payer_ifsc": ""
          }
        },
        "payment_group": "upi"
      },
      "payment_amount": 500.00,
      "payment_currency": "INR",
      "payment_schedule_date": "2025-08-07T12:00:00+05:30",
      "payment_initiated_date": "2025-08-06T05:02:41+05:30",
      "payment_remarks": null,
      "retry_attempts": 0,
      "failure_details": {
        "failure_reason": "DEBIT FAILED | Insufficient Funds In Customer (Remitter) Account"
      },
      "payment_status": "FAILED",
      "payment_gateway_details": {
        "gateway_name": "CASHFREE",
        "gateway_subscription_id": "22393526",
        "gateway_payment_id": "49585655"
      }
    },
    "event_time": "2025-08-07T10:24:45+05:30",
    "type": "SUBSCRIPTION_PAYMENT_FAILED"
  }
  ```
</Accordion>

### Step 4: Get mandate details

Retrieve information about all payments made against a subscription and the remaining blocked amount.

**API Endpoint:** `GET https://api.cashfree.com/pg/subscriptions/{subscription_id}/payments`

**Sandbox URL:** `https://sandbox.cashfree.com/pg/subscriptions/{subscription_id}/payments`

<Note>
  SBMD subscriptions use the same API as regular subscriptions. For complete response structure and parameters, see [Fetch Payments API](/docs/api-reference/payments/latest/subscription/fetch-details-of-all-payments-of-a-subscription).

  To get individual payment details, use [Fetch Payment API](/docs/api-reference/payments/latest/subscription/fetch-details-of-a-single-payment).
</Note>

### Step 5: Refund individual charges

Refund specific charges using the subscription refund APIs. SBMD refunds work the same as regular subscription refunds.

**Create Refund:** `POST https://api.cashfree.com/pg/subscriptions/{subscription_id}/refunds`

**Sandbox URL:** `https://sandbox.cashfree.com/pg/subscriptions/{subscription_id}/refunds`

**Get Refund Status:** `GET https://api.cashfree.com/pg/subscriptions/{subscription_id}/refunds/{refund_id}`

**Sandbox URL:** `https://sandbox.cashfree.com/pg/subscriptions/{subscription_id}/refunds/{refund_id}`

<Note>
  For complete API documentation and examples, see:

  * [Create Refund API](/docs/api-reference/payments/latest/subscription/create-a-refund)
  * [Get Refund API](/docs/api-reference/payments/latest/subscription/fetch-details-of-a-refund)
</Note>

### Step 6: Manage mandate

Release unused blocked funds back to the customer using the manage subscription API.

**API Endpoint:** `POST https://api.cashfree.com/pg/subscriptions/{subscription_id}/manage`

**Sandbox URL:** `https://sandbox.cashfree.com/pg/subscriptions/{subscription_id}/manage`

<Warning>
  **SBMD limitation**

  Only the `CANCEL` action is supported for SBMD subscriptions. Other management actions like `PAUSE` are not available.

  ```json theme={"dark"}
  {
    "subscription_id": "subscription_001",
    "action": "CANCEL"
  }
  ```

  For complete API documentation, see [Manage Subscription API](/docs/api-reference/payments/latest/subscription/manage-subscription).
</Warning>

## Subscription webhooks

Cashfree sends webhook notifications for various subscription events during the SBMD lifecycle.

### SUBSCRIPTION\_STATUS\_CHANGED

This webhook is sent when a subscription's status changes during the lifecycle.

<Accordion title="Subscription status change notification">
  ```json Webhook Example theme={"dark"}
  {
    "data": {
      "subscription_details": {
        "cf_subscription_id": "23639356",
        "subscription_id": "subscription_001",
        "subscription_status": "BANK_APPROVAL_PENDING",
        "subscription_expiry_time": "2055-08-07T10:30:46",
        "subscription_first_charge_time": null,
        "subscription_tags": null,
        "next_schedule_date": null
      },
      "customer_details": {
        "customer_name": null,
        "customer_email": "john@example.com",
        "customer_phone": "9900000000"
      },
      "plan_details": {
        "plan_id": "subscription_001",
        "plan_name": "6Msuj2mttuf2F5P1FYVSet",
        "plan_type": "ON_DEMAND",
        "plan_max_cycles": 0,
        "plan_recurring_amount": null,
        "plan_max_amount": 1000.00,
        "plan_interval_type": null,
        "plan_intervals": null,
        "plan_currency": "INR",
        "plan_note": null,
        "plan_status": null
      },
      "authorization_details": {
        "authorization_amount": 1000.00,
        "authorization_amount_refund": false,
        "approve_by_time": "2025-09-06T10:30:47",
        "authorization_reference": "6ba74ac2b047424da95591xxxxx[at]xxxx",
        "authorization_time": "2025-08-07T10:31:36",
        "authorization_status": "PENDING",
        "payment_id": "49988270",
        "payment_method": {
          "upi": {
            "channel": "link",
            "upi_id": "9910000000@ybl",
            "upi_instrument": "",
            "upi_instrument_number": "",
            "upi_payer_account_number": "",
            "upi_payer_ifsc": ""
          }
        },
        "payment_group": "upi"
      },
      "payment_gateway_details": {
        "gateway_name": "CASHFREE",
        "gateway_subscription_id": "23639356",
        "gateway_plan_id": "subscription_001",
        "gateway_auth_id": "6ba74ac2b047424da95591xxxxx[at]xxxx"
      }
    },
    "event_time": "2025-08-07T10:31:35+05:30",
    "type": "SUBSCRIPTION_STATUS_CHANGED"
  }
  ```
</Accordion>

<snippet>snippets/related-topics-loader.mdx</snippet>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/payments/latest/subscription/create-subscription">Create Subscription API</a></li>
    <li><a href="/docs/api-reference/payments/latest/subscription/raise-a-charge-or-create-an-auth">Raise Payment API</a></li>
    <li><a href="/docs/api-reference/payments/latest/subscription/create-a-refund">Create Refund API</a></li>
    <li><a href="/docs/payments/subscription/introduction">Subscriptions Overview</a></li>
  </ul>
</div>


# Managing Virtual Bank Accounts
Source: https://www.cashfree.com/docs/payments/vba/managing-vba

Learn how to create Virtual Bank Accounts, set up notification groups, and view VBA payment details from the Cashfree Merchant Dashboard.

Virtual Bank Accounts (VBAs) let you collect payments through NEFT, RTGS, and IMPS transfers. Each VBA is a unique account number assigned to a customer or transaction, enabling automated reconciliation of incoming payments.

## Prerequisites

Ensure you complete the following before getting started:

* Have an active [Cashfree account](https://merchant.cashfree.com/merchants/signup). See how to [create an account](/docs/help/account/account-activation#create-an-account) for setup instructions if you have not created one yet.
* Ensure the **VBA** payment method is enabled on your account. Contact [Cashfree Support](https://www.cashfree.com/contact-us) to enable it.

## Creating a VBA

Use the following steps to create a VBA:

1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
2. Navigate to **Payment Gateway** > **VBA Configuration** > **VBA Accounts**.
3. Click **Create VBA Account**.
   <img alt="VBA Accounts page on the Merchant Dashboard" />
4. In the **Create Virtual Bank Account** side panel, enter the following details:
   * **Account Holder Name**: Enter the name of the account holder.
   * **Virtual Account ID**: Enter a unique identifier for the payer. This is appended to the generated virtual account number. A maximum of 20 characters are allowed.
   * **Mobile Number**: Enter the account holder's mobile number.
   * **Email ID**: Enter the account holder's email address.
   <Frame>
     <img />
   </Frame>
5. Enable any of the following optional settings using the toggles:
   * **Receive Notifications**: Notify the account holder when a payment is received. When enabled, select a notification group from the **Select Groups** dropdown, or click **+ Create a group** to set up a new one.
   * **Add KYC Details**: Attach KYC information to this VBA. This is optional unless mandated by Cashfree for your account. When enabled, enter the following details:
     * **Aadhaar Number**: Enter the account holder's 12-digit Aadhaar number.
     * **GSTIN**: Enter the GST Identification Number.
     * **PAN**: Enter the account holder's PAN.
   * **Get payments from a specific account**: Optionally restrict this VBA to accept payments only from specified source accounts. Payments from any other account are rejected. When enabled, enter the following details:
     * **Account Number**: Enter the source account number.
     * **IFSC**: Enter the IFSC code for the source account.
     * Click **+ Add another account** to add multiple source accounts.
   * **Get payments of a set amount or range**: Optionally set a limit on accepted payment amounts. When enabled, enter the following details:
     * **Min. Amount**: Enter the minimum accepted payment amount.
     * **Max. Amount**: Enter the maximum accepted payment amount.
6. Click **Create Virtual Account**.

<Frame>
  <img />
</Frame>

<Tip>
  Create numeric-only virtual bank account numbers where possible. Some banking apps do not support alphabetic characters in account number fields, which can cause payment failures. Numeric account numbers reduce input errors and improve payment success rates.
</Tip>

After you save, the VBA appears on the **VBA Accounts** page. Use the **All**, **Active**, and **Inactive** filters at the top of the page to filter virtual bank accounts by status. For each VBA card, you can copy account details, or update the existing account details by clicking the **Edit Details** button.

## Bulk creating or deactivating VBAs

Use the following steps to create or deactivate multiple VBAs:

1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
2. Navigate to **Payment Gateway** > **VBA Configuration** > **VBA Accounts**.
3. Click **Bulk Create & Update**.
4. Download the relevant CSV template:
   * **Create multiple VBAs**: Downloads a template to fill in details for new VBAs.
   * **Deactivate multiple VBAs**: Downloads a template to specify VBAs to deactivate.
5. Fill in the required details in the downloaded CSV file.
6. Click **Upload File** and select your completed CSV file. Files must be in CSV format and up to 5 MB each.
7. Click **Submit**. Valid entries are processed immediately. Invalid entries can be corrected and re-uploaded.

<Frame>
  <img />
</Frame>

## Viewing VBA payments

Use the following steps to view payments received through VBAs:

1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
2. Navigate to **Payment Gateway** > **Transactions** > **Payments**.
3. Click the **Search & Filter** dropdown.
4. Under **Payment Methods**, select **VBA Transfer**.

The payments list updates to show only transactions processed through VBAs.

<img alt="Payment filter showing VBA Transfer selected under Payment Methods" />

## Creating a notification group

Notification groups receive WhatsApp and email alerts whenever a payment is made to a VBA. You can add multiple email addresses and mobile numbers to a single group.

Use the following steps to create a notification group for VBAs:

1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
2. Navigate to **Payment Gateway** > **VBA Configuration** > **Notification Groups**.
3. Click **Create Notification Group**.
   <img alt="Notif-groups-VBA" />
4. In the **Create a notification group** panel, enter the following details:
   * **Name your group**: Enter a name to identify this notification group.
   * **Add email or mobile numbers**: Enter the email addresses or mobile numbers to include in the group.
5. Click **Save group**.

<Frame>
  <img />
</Frame>

## FAQs

The following questions cover common scenarios and limitations for Virtual Bank Accounts.

<Accordion title="What is a Virtual Bank Account (VBA)?">
  A Virtual Bank Account (VBA) is a unique bank account number assigned to a customer or transaction. It lets businesses collect payments through NEFT, RTGS, and IMPS and automatically reconcile incoming transfers.
</Accordion>

<Accordion title="Can I collect payments from UPI apps such as Google Pay, PhonePe, or Paytm?">
  No. NPCI regulations do not permit UPI payments to Virtual Bank Accounts. These transactions are classified as P2P (person-to-person) transfers, which are not supported by VBAs.
</Accordion>

<Accordion title="Is there a transaction limit for payments to a VBA?">
  Yes. Transaction limits depend on the payment mode: IMPS, NEFT, or RTGS each have their own limits set by the banking network. You can also define a minimum and maximum limit when creating a VBA to control the accepted payment range.
</Accordion>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/payments/latest/pgvba/create-vba">Create VBA API</a></li>
    <li><a href="/docs/api-reference/payments/latest/pgvba/edit-vba">Edit VBA API</a></li>
    <li><a href="/docs/api-reference/payments/latest/pgvba/get-vba-payments">Get VBA Payments API</a></li>
    <li><a href="/docs/api-reference/payments/latest/pgvba/create-vba-notification-group">Create VBA Notification Group API</a></li>
  </ul>
</div>


# Overview
Source: https://www.cashfree.com/docs/payments/vba/overview

Use Cashfree Virtual Bank Accounts to assign unique IFSC and account numbers to customers and automatically reconcile incoming IMPS, NEFT, and RTGS transfers.

Virtual Bank Accounts (VBAs) simplify payment collection via bank transfers (NEFT, RTGS, and IMPS). Each customer gets a unique virtual account for payments, allowing businesses to track transactions seamlessly and reconcile them automatically. Cashfree instantly notifies businesses of payments, transfers the funds, and settles them into their business accounts.

Additionally, you can enable Third-Party Validation (TPV) on VBAs, ensuring that the customer adds funds only from the bank account you specify. The system automatically rejects payments from other accounts and refunds any debited amounts. This enhances security, ensures compliance, and benefits industries like stock brokerage, where strict fund source verification is required.

<img alt="" />

AXIS, ICICI, and YES Bank support VBAs.

<Tip>Install [Cashfree Agent Skills](/docs/tools-ai/cashfree-agent-skills) to bring Cashfree product knowledge into your AI coding assistant (Claude Code, Cursor, VS Code Copilot, Gemini CLI, and more) to answer integration questions and generate accurate code without leaving your editor.</Tip>

## Benefits

The following are the key benefits of VBA:

* **Seamless payments**: Unique VBAs remove the need for manual tracking

* **Real-time tracking**: Instant payment notifications provide full visibility

* **Automated reconciliation**: The system minimises errors and reduces operational overhead

* **Supports high-value transactions**: The system efficiently handles large payments

## Use cases

The following are the use cases of virtual bank accounts (VBAs):

* NBFCs: Collect EMIs, loan repayments, and deposits from customers. Each borrower gets a unique virtual account

* Stock brokerage and trading: Facilitate seamless fund transfers for customers. Each investor gets a unique virtual account to add funds

* Real estate: Collect payments for property bookings, rentals, and maintenance charges

* Educational institutes: Collect tuition fees, exam charges, and other student payments. Each student gets a unique virtual account for seamless fee collection

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/payments/latest/pgvba/create-vba">Create VBA API</a></li>
    <li><a href="/docs/api-reference/payments/latest/pgvba/manage-vba">Manage VBA API</a></li>
    <li><a href="/docs/api-reference/payments/latest/pgvba/get-vba-payments">Get VBA payments API</a></li>
    <li><a href="/docs/api-reference/payments/latest/pgvba/create-vba-notification-group">Create VBA notification group API</a></li>
  </ul>
</div>


# Webhooks Configuration and Usage
Source: https://www.cashfree.com/docs/payments/vba/webhooks

Configure Cashfree Virtual Bank Account webhooks to receive real-time events when customers send funds via IMPS, NEFT, or RTGS to virtual accounts.

Configure webhooks to receive real-time updates on transaction and settlement events for your Virtual Bank Account (VBA) integration.

<Warning>
  **For existing merchant integrations:** The `VBA_TRANSFER_SUCCESS_PAYMENT` webhook remains the supported webhook for VBA transactions. If you configure the `PAYMENT_SUCCESS_WEBHOOK`, it does not include VBA-related transfer details. To receive VBA transfer updates, continue using the `VBA_TRANSFER_SUCCESS_PAYMENT` webhook.

  **For new merchant integrations:** The `VBA_TRANSFER_SUCCESS_PAYMENT` webhook is not supported. Configure the `PAYMENT_SUCCESS_WEBHOOK` instead, which includes the VBA payment and transfer-related details your integration requires.
</Warning>

## Payment success webhook

For newer integrations, use the `PAYMENT_SUCCESS_WEBHOOK` to receive VBA payment and transfer-related updates. The following sample shows the payload structure:

```json JSON theme={"dark"}
{
  "data": {
    "order": {
      "order_id": "n585ctivoh6g",
      "order_amount": 1500,
      "order_currency": "INR",
      "order_tags": null
    },
    "payment": {
      "cf_payment_id": "5114925103565",
      "payment_status": "SUCCESS",
      "payment_amount": 1500,
      "payment_currency": "INR",
      "payment_message": "NA",
      "payment_time": "2026-02-05T15:19:36+05:30",
      "bank_reference": "MerchantID_TESTUTR12362",
      "auth_id": null,
      "payment_method": {
        "vba_transfer": {
          "utr": "MerchantID_TESTUTR12362",
          "credit_ref_no": "NA",
          "remitter_account": "123456789012",
          "remitter_name": "John Doe",
          "remitter_ifsc": "NOOB0CMSNOC",
          "email": "user@cashfree.com",
          "phone": "9999999999",
          "vaccount_id": "USER09",
          "vaccount_number": "98912574JSER10"
        }
      },
      "payment_group": "vba_transfer",
      "international_payment": null,
      "payment_surcharge": {
        "payment_surcharge_service_charge": 0,
        "payment_surcharge_service_tax": 0
      }
    },
    "customer_details": {
      "customer_name": "John Doe",
      "customer_id": null,
      "customer_email": "user@cashfree.com",
      "customer_phone": "9999999999"
    },
    "payment_gateway_details": {
      "gateway_name": "CASHFREE",
      "gateway_order_id": null,
      "gateway_payment_id": null,
      "gateway_status_code": null,
      "gateway_order_reference_id": null,
      "gateway_settlement": "CASHFREE",
      "gateway_reference_name": null
    },
    "payment_offers": null,
    "terminal_details": null
  },
  "event_time": "2026-02-05T15:19:35+05:30",
  "type": "PAYMENT_SUCCESS_WEBHOOK"
}
```

## Legacy VBA amount collected webhook

For existing integrations, Cashfree sends the following payload when a customer completes a payment to a Virtual Bank Account:

```json JSON theme={"dark"}
{
    "event":"AMOUNT_COLLECTED",
    "amount":"400",
    "vAccountId":"87654321",
    "virtualVpaId":"8080808087654321",
    "isVpa":"0",
    "email":"xyz@example.com",
    "phone":"9876543210",
    "referenceId":87654,
    "utr":"N123456789",
    "creditRefNo":"0976541123",
    "remitterAccount":"123455666778",
    "remitterName":"CASHFREE PAYMENTS",
    "paymentTime":"2019-07-20 15:27:37",
    "signature":"8uV792gBZaasJHBFSsfaMHLuqnZKkossjw9gEJ8Sx85V+jgbpg4ME="
}
```

## Settlement webhook

<Warning>
  From day 0 of migration, Cashfree sends the PG settlement payload to your configured endpoints instead of the AC payload format. This change might break your integration if it relies on the AC settlement webhook format.
</Warning>

The following sample shows the PG payload for the settlement webhook:

```json JSON theme={"dark"}
{
    "data": {
        "settlement": {
            "adjustment": 0,
            "amount_settled": 97.94,
            "payment_amount": 100,
            "payment_from": "2022-02-14 12:00:00",
            "payment_till": "2022-02-14 12:15:00",
            "reason": null,
            "service_charge": 1.75,
            "service_tax": 0.31,
            "settled_on": "2022-02-14T12:35:19+05:30",
            "settlement_type": "STANDARD",   //settlement type//
            "settlement_amount": 97.94,
            "settlement_id": 738,
            "settlement_initiated_on": "2022-02-14T12:35:17+05:30",
            "status": "SUCCESS",
            "utr": 1644822317781212,
            "settlement_charge": 0,    // applicable for instant settlement //
            "settlement_tax": 0,       // applicable for instant settlement //
            "remarks": null    // applicable for instant settlement //
        }
    },
    "event_time": "2022-02-08T13:37:34+05:30",
    "type": "SETTLEMENT_SUCCESS"
}
```

For detailed information on PG settlement webhooks, see [PG Settlement Webhooks](/docs/api-reference/payments/latest/settlements/settlement-webhooks).


# Webhooks
Source: https://www.cashfree.com/docs/payments/webhooks

Set up Cashfree webhooks so your backend automatically receives real-time events for orders, payments, refunds, settlements, and disputes.

When building Cashfree integrations, you might want your applications to receive events as they occur in your Cashfree account so that your back-end systems can execute actions accordingly.

To enable real-time event notifications, register your webhook endpoints with Cashfree at **Developers > Webhooks**. These endpoints receive HTTP POST requests containing JSON payloads whenever specific events happen in your Cashfree account. This allows your application to react promptly to changes such as successful payments, failed transactions, or new chargebacks.

<Tip>Install [Cashfree Agent Skills](/docs/tools-ai/cashfree-agent-skills) to bring Cashfree product knowledge into your AI coding assistant (Claude Code, Cursor, VS Code Copilot, Gemini CLI, and more) to answer integration questions and generate accurate code without leaving your editor.</Tip>

<CardGroup>
  <Card title="Payment webhooks" icon="credit-card" href="/docs/api-reference/payments/latest/payments/webhooks">
    Headers and payload samples for payment status notifications.
  </Card>

  <Card title="Refund webhooks" icon="rotate-left" href="/docs/api-reference/payments/latest/refunds/webhooks">
    Payload samples for refund status notifications.
  </Card>

  <Card title="Settlement webhooks" icon="building" href="/docs/api-reference/payments/latest/settlements/settlement-webhooks">
    Settlement status notifications and payout objects.
  </Card>

  <Card title="Subscription webhooks" icon="repeat" href="/docs/api-reference/payments/latest/subscription/webhooks">
    Subscription lifecycle and payment status notifications for recurring billing.
  </Card>

  <Card title="Payment Link webhooks" icon="link" href="/docs/api-reference/payments/latest/payment-links/webhooks">
    Payload samples for payment link status notifications.
  </Card>

  <Card title="Payment Form webhooks" icon="file-lines" href="/docs/payments/no-code/payment-forms/webhooks">
    Payment status notifications for no-code payment forms.
  </Card>

  <Card title="Card token webhooks" icon="layer-group" href="/docs/api-reference/payments/latest/token-vault/webhooks">
    Instrument payloads for saved card token status notifications.
  </Card>

  <Card title="Dispute webhooks" icon="triangle-exclamation" href="/docs/api-reference/payments/latest/disputes/dispute-webhooks">
    Chargeback and dispute status notifications.
  </Card>

  <Card title="SoftPOS webhooks" icon="mobile" href="/docs/api-reference/payments/latest/offline-payments/softpos-webhooks">
    Terminal and SoftPOS transaction status notifications.
  </Card>

  <Card title="Easy Split webhooks" icon="users" href="/docs/api-reference/payments/latest/split/webhooks/overview">
    Vendor settlement and vendor status change notifications for Easy Split.
  </Card>

  <Card title="Global collections partner webhooks" icon="globe" href="/docs/api-reference/payments/latest/international-payments/global-collections/partner/webhooks">
    Partner-facing notifications for international collections transactions.
  </Card>
</CardGroup>

### Verify webhooks

Verify webhooks to prevent tampering and ensure you process only legitimate notifications from Cashfree. Without verification, your application is vulnerable to fraudulent payment confirmations and security threats.

Use [webhook signatures](/docs/payments/online/webhooks/signature-verification) to authenticate Cashfree webhooks, and proceed with further actions only after successful verification.

<Warning>
  Cashfree generates the webhook signature based on the raw payload, not the
  parsed payload. You can refer to how the popular JavaScript framework
  [NestJS](https://docs.nestjs.com/faq/raw-body) provides a hook for accessing
  the raw body.
</Warning>

### Test webhooks

Before going live, test your webhooks in the sandbox environment to verify payloads and integration behaviour. Configure your webhooks from the dashboard in the test environment. Events triggered by test transactions send webhooks to your configured endpoint.

<Info>
  You can create endpoint URLs and test webhooks using tools like
  [webhook.site](https://webhook.site) or create a tunnel to your localhost
  using tools like [ngrok](https://ngrok.com).
</Info>

### Duplicate webhook processing

<Note>
  Cashfree uses **at-least-once** delivery to prevent missed webhook
  notifications.
</Note>

In case of inadvertent downtimes at Cashfree or your end, Cashfree may attempt
duplicate webhook delivery to ensure fulfilment. <br />

<br />

To prevent business processing of duplicate events at your end, you are strongly
recommended to validate `x-idempotency-header` in each webhook header. This hashed
value will always be unique for each unique webhook payload.

<Note>
  This feature is available on webhook versions starting 2025-01-01. To migrate
  to this new version, refer to [Webhook Migration](#webhook-migration) section
  below.
</Note>

### Retry webhooks policy

You can define a custom retry policy for webhooks that do not receive a **200 response**. To configure the retry policy, log in to the **[Merchant Dashboard](https://merchant.cashfree.com/auth/login)** and go to **Payment Gateway > Developers > Webhooks**. Cashfree retries delivery to your URLs based on the defined policy until it receives a **200 response**.

You will see two types of URLs listed -

1. `NOTIFY_URL` - This is the default configuration added to your account and configurations here cannot be edited or deleted. This configuration will apply to only the URLs sent in the notify\_url param of [Create Order API](/docs/api-reference/payments/latest/orders/create-order) within the order\_meta object
2. Your custom configured URLs - You can click on 'Edit' and follow the steps on the screen to define a custom retry policy. A default policy is applied to all URLs

The following webhook policy types are available:

* **Default**: The system retries up to three times at 2, 10, and 30-minute intervals.
* **Fixed**: You can specify the number of retries (maximum of 10) and the interval between retries.
* **Exponential**: You can specify the number of retries (maximum of 10), the interval, and a multiplier. For example, if the number of retries is 5, the interval is 15 minutes, and the multiplier is 2, retries occur at 15, 17, 19, 23, and 31-minute intervals.
* **Custom**: You can specify the number of retries (maximum of 10) and define custom intervals.

### Resend webhooks

<Note>
  This feature is only available for [`payment`
  webhooks](/docs/api-reference/payments/latest/payments/webhooks)
</Note>

There are various reasons why you might need to resend a webhook response to your endpoint, such as service-level downtime or failure to register a webhook payload. With Cashfree, you can resend previously triggered webhooks. Log in to your dashboard and follow the steps below:

1. Go to Webhooks under the Developer section and go to **Logs**.
2. On the top right, click the **Batch Resend** button.

<img />

3. You will see three options here:
   * **Text**: Enter transaction IDs (comma separated) in the text box and click **Resend**. Transaction IDs are the same as Entity IDs listed on the logs dashboard.
   * **File**: Upload the file in the required format (downloadable from the dashboard) with the required Transaction IDs and click **Resend**.
   * **Time Duration**: Select the time period (max. allowed duration is 24 hours) and click **Resend**.

### Webhook signature verification

<Warning>
  Cashfree generates the webhook signature based on the raw payload, not the
  parsed payload. You can refer to how the popular JavaScript framework
  [NestJS](https://docs.nestjs.com/faq/raw-body) provides a hook for accessing
  the raw body.
</Warning>

Use the signature to verify that the request has not been tampered with. To verify the signature, you need your Cashfree PG secret key and the payload.

* The timestamp is present in the header `x-webhook-timestamp`.
* The actual signature is present in the header `x-webhook-signature`.

```bash signature-verification theme={"dark"}
timestamp := 1617695238078;
signedPayload := $timestamp.$payload;
expectedSignature := Base64Encode(HMACSHA256($signedPayload, $merchantSecretKey));
```

### SDK verification (built-in approach)

<CodeGroup>
  ```javascript Node (express) theme={"dark"}
  var express = require('express')
  const { Cashfree, CFEnvironment } = require("cashfree-pg");

  var app = express()

  const cashfree = new Cashfree(
  CFEnvironment.SANDBOX,
  "{Client ID}",
  "{Client Secret Key}"
  );

  app.post('/webhook', function (req, res) {
  try {
  cashfree.PGVerifyWebhookSignature(req.headers["x-webhook-signature"], req.rawBody, req.headers["x-webhook-timestamp"])
  } catch (err) {
  console.log(err.message)
  }
  })

  ```

  ```go golang theme={"dark"}
  import (
    cashfree "github.com/cashfree/cashfree-pg/v4"
  )

  // Route
  e.POST("/webhook", _this.Webhook)

  // Controller
  func (_this *WebhookRoute) Webhook(c echo.Context) error {
    	clientId := "<x-client-id>"
  		clientSecret := "<x-client-secret>"
  		cashfree.XClientId = &clientId
  		cashfree.XClientSecret = &clientSecret
  		cashfree.XEnvironment = cashfree.SANDBOX

      signature := c.Request().Header.Get("x-webhook-signature")
      timestamp := c.Request().Header.Get("x-webhook-timestamp")

      body, _ := ioutil.ReadAll(c.Request().Body)
      rawBody := string(body)
      webhookEvent, err := cashfree.PGVerifyWebhookSignature(signature, rawBody, timestamp)
      if err != nil {
  		fmt.Println(err.Error())
  	} else {
  		fmt.Println(webhookEvent.Object)
  	}
  }
  ```

  ```php PHP theme={"dark"}
  <?php

  $inputJSON = file_get_contents('php://input');

  $expectedSig = getallheaders()['x-webhook-signature'];
  $ts = getallheaders()['x-webhook-timestamp'];

  if(!isset($expectedSig) || !isset($ts)){
      echo "Bad Request";
      die();
  }

  \Cashfree\Cashfree::$XClientId = "<x-client-id>";
  \Cashfree\Cashfree::$XClientSecret = "<x-client-secret>";
  $cashfree = new \Cashfree\Cashfree();

  try {
   $response =  cashfree->PGVerifyWebhookSignature($expectedSig, $inputJSON, $ts);
  } catch(Exception $e) {
    // Error if signature verification fails
  }
  ?>
  ```

  ```python Python theme={"dark"}
  from cashfree_pg.api_client import Cashfree

  @app.route('/webhook', methods = ['POST'])
  def disp():
  		# Get the raw body from the request
      raw_body = request.data

      # Decode the raw body bytes into a string
      decoded_body = raw_body.decode('utf-8')

      #verify_signature
      timestamp = request.headers['x-webhook-timestamp']
      signature = request.headers['x-webhook-signature']

  		cashfree = Cashfree()
  		cashfree.XClientId = "<app_id>"
  		cashfree.XClientSecret = "<secret_key>"
  		try:
  			cashfreeWebhookResponse = cashfree.PGVerifyWebhookSignature(signature, decoded_body, timestamp)
  		except:
  			# If Signature mis-match
  ```

  ```java Java theme={"dark"}
  import com.cashfree.*;

  @PostMapping("/my-endpoint")
  public String handlePost(HttpServletRequest request) throws IOException {
      Cashfree.XClientId = "<x-client-id>";
  		Cashfree.XClientSecret = "<x-client-secret>";
  		Cashfree.XEnvironment = Cashfree.SANDBOX;

    	StringBuilder stringBuilder = new StringBuilder();
      BufferedReader bufferedReader = null;

      try {
        bufferedReader = request.getReader();
        String line;
        while ((line = bufferedReader.readLine()) != null) {
                stringBuilder.append(line).append('\n');
        }


        String rawBody = stringBuilder.toString();
        String signature = request.getHeader("x-webhook-signature");
        String timestamp = request.getHeader("x-webhook-timestamp");

        Cashfree cashfree = new Cashfree();
        PGWebhookEvent webhook = cashfree.PGVerifyWebhookSignature(signature, rawBody, timestamp);

      } catch (Exception e) {
              // Error if verification fails
      } finally {
           if (bufferedReader != null) {
              bufferedReader.close();
  		}
  	}

  }
  ```

  ```csharp csharp theme={"dark"}
  using cashfree_pg.Client;
  using cashfree_pg.Model;


  		[Route("api/[controller]")]
      [ApiController]
      public class YourController : ControllerBase
      {
          [HttpPost]
          public async Task<IActionResult> Post()
          {
              // Read the raw body of the POST request
              using (StreamReader reader = new StreamReader(Request.Body, Encoding.UTF8))
              {
                  string requestBody = await reader.ReadToEndAsync();
                  var headers = Request.Headers;
                  var signature = headers["x-webhook-signature"];
                  var timestamp = headers["x-webhook-timestamp"];

                  Cashfree.XClientId = "<x-client-id>";
                  Cashfree.XClientSecret = "<x-client-secret>";
                  Cashfree.XEnvironment = Cashfree.SANDBOX;
  								var cashfree = new Cashfree();

                  try {
                  var response = cashfree.PGVerifyWebhookSignature(signature, requestBody, timestamp);
                  } catch(Exception e) {
                  // Error if signature mis matches
                  }
              }
          }
      }
  ```
</CodeGroup>

### Manual verification (custom approach)

<CodeGroup>
  ```javascript Node (Express) theme={"dark"}
  function verify(ts, request){
      const body = request.headers['x-webhook-timestamp'] + request.rawBody
      const secretKey = <client secret>;
      let generatedSignature = crypto.createHmac('sha256', secretKey).update(body).digest("base64");
      const signature = request.headers['x-webhook-signature']
      if(generatedSignature === signature) {
          let jsonObject = JSON.parse(rawBody)
          return jsonObject
      }
      throw new Error("Generated signature and received signature did not match.");
  }
  ```

  ```go golang theme={"dark"}
  func VerifySignature(expectedSig string, ts string, body string) (string, error) {
          clientSecret := "<client-secret>"
  	signatureString := ts + rawBody
  	hmacInstance := hmac.New(sha256.New, []byte(*clientSecret))
  	hmacInstance.Write([]byte(signatureString))
  	bytesData := hmacInstance.Sum(nil)
  	generatedSignature := base64.StdEncoding.EncodeToString(bytesData)
  	if generatedSignature == expectedSig {
  		var object interface{}
  		err := json.Unmarshal([]byte(rawBody), &object)
  		if err != nil {
  			return nil, errors.New("something went wrong when unmarshalling raw body")
  		}
  		if objectAsMapInterface, ok := object.(map[string]interface{}); ok {
  			if webhookType, ok := objectAsMapInterface["type"].(string); ok {
  				return "signatures match", nil
  			}
  		}
  		return "", nil
  	}
  	return nil, errors.New("generated signature and received signature did not match")
  }

  timestamp := c.Request().Header.Get("x-webhook-timestamp")
  body, _ := ioutil.ReadAll(c.Request().Body)
  rawBody := string(body)
  signature := c.Request().Header.Get("x-webhook-signature")

  VerifySignature(signature, timestamp, rawBody)
  ```

  ```php PHP theme={"dark"}
  function computeSignature($ts, $rawBody){
      $rawBody = file_get_contents('php://input');
      $timestamp = getallheaders()['x-webhook-timestamp'];
      $signature = getallheaders()['x-webhook-signature'];

      $body = $timestamp . $rawBody;
      $secretKey = "<client-secret>";
      $genSignature = hash_hmac('sha256', $body, $secretKey, true);
      $genSignatureBase64 = base64_encode($genSignature);
      if($genSignatureBase64 == $signature) {
          $jsonResponse = json_decode($rawBody);
          return $jsonResponse;
      }
      throw new Exception("Generated signature and received signature did not match.");
  }
  ```

  ```java Java theme={"dark"}
  public Object generateSignature() {
    try {
        String data = headers.get("x-webhook-timestamp") + rawBody;
        String secretKey = "<client-secret>";
        Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
        SecretKeySpec secret_key_spec = new SecretKeySpec(secretKey.getBytes(), "HmacSHA256");
        sha256_HMAC.init(secret_key_spec);
        String computed_signature = Base64.getEncoder().encodeToString(sha256_HMAC.doFinal(data.getBytes()));
        String signature = headers.get("x-webhook-signature")
        if(computed_signature.equals(signature)) {
          Gson g = new Gson();
          Object response = g.fromJson(rawBody, Object.class);
          return response;
        }
        throw new Exception("Generated signature and received signature did not match.");
    } catch (Exception e) {
      throw e;
    }
  }
  ```

  ```python Python theme={"dark"}
  import base64
  import hashlib
  import hmac

  def generateSignature():
      raw_body = request.data
      timestamp = request.headers['x-webhook-timestamp']
      signature = request.headers['x-webhook-signature']
      signatureData = timestamp+rawBody
      message = bytes(signatureData, 'utf-8')
      secretkey=bytes("<client-signature>",'utf-8')
      generatedSignature = base64.b64encode(hmac.new(secretkey, message, digestmod=hashlib.sha256).digest())
      computed_signature = str(generatedSignature, encoding='utf8')
      if computed_signature == signature:
          json_response = json.loads(rawBody)
          return json_response
      raise Exception("Generated signature and received signature did not match.")
  ```
</CodeGroup>

### Webhook migration

Webhook endpoints have a specific API version set, for example, `2023-08-01`. To migrate from an older version to a newer version, follow these steps:

<Steps>
  <Step title="Add webhook for new version">
    Create a new webhook endpoint with the new URL and new version. Subscribe to
    the events you want to consume.
  </Step>

  <Step title="Update your code to return 200 for new webhooks">
    Update your event processing code and return a 200 response to prevent
    delivery retries. Next, enable the new webhook endpoint that you created in
    the previous step. At this point, every event is sent twice: once with the
    old API version and once with the new one.
  </Step>

  <Step title="Update your webhook code to process events for the new endpoint">
    Update your code to ensure you can process the version of your new webhook
    endpoint. Make sure you read the changelog and handle any breaking changes.
  </Step>

  <Step title="Disable old webhook endpoint">
    If events aren’t being correctly handled by your new code, first temporarily
    disable the new webhook endpoint. After monitoring for some time, you can
    permanently delete the old webhook endpoint.
  </Step>
</Steps>

<snippet>snippets/related-topics-loader.mdx</snippet>

<div>
  <p>
    <svg>
      <path />

      <path />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/payments/online/webhooks/security-checklist">Webhook Security Checklist</a></li>
    <li><a href="/docs/api-reference/payments/latest/payments/webhooks">Payment Webhooks</a></li>
    <li><a href="/docs/api-reference/payments/latest/refunds/webhooks">Refund Webhooks</a></li>
    <li><a href="/docs/api-reference/payments/latest/token-vault/webhooks">Token Vault Webhooks</a></li>
    <li><a href="/docs/api-reference/payments/latest/payment-links/webhooks">Payment Link Webhooks</a></li>
  </ul>
</div>


# Approve Batch Cashgrams
Source: https://www.cashfree.com/docs/payouts/cashgram/approve-cashgrams

Set up an approver profile in your Cashfree account so batch-uploaded Cashgrams require sign-off before disbursing funds to beneficiaries.

To manage a large number of Cashgrams at once Batch Upload of Cashgrams is supported. Since it involves processing all the Cashgrams at once, you may want to check and approve it before it is sent to the respective beneficiaries. To do this, you have to create an approver profile within Cashfree Account and after it gets approved by the approver, Cashgrams will be sent to beneficiaries.

All the Cashgrams that are pending approval will be shown in the **Approve Batch** section as shown below:

<img alt="" />

One of the users in your company can add the required details in a file and upload it. The approver can approve or reject the file. After approval, the Cashgrams are sent to beneficiaries, and you can view the status of the Cashgram in the Dashboard.

To view and approve the Cashgrams,

1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
2. Go to **Payouts Dashboard** > **Cashgram** > **Approve Batch**.
3. Select the file you want to approve, and click **Approve**. All file details and the details of the individual who uploaded the file will be displayed here as shown below:

<img alt="" />

The option to create multiple users and assign permissions can be done from the Profile section.


# Overview
Source: https://www.cashfree.com/docs/payouts/cashgram/cashgram

Use Cashfree Cashgram to send instant payout links via WhatsApp, email, or SMS so beneficiaries can collect funds without sharing bank or UPI details upfront.

With Cashgram you can send instant refunds for COD payments, cash prizes to the customers, security deposits that need to be returned, and so on, even if you do not know their bank account details. Users have to simply click the link received on WhatsApp, email or SMS and provide their details to collect the payment using one of the payment methods provided.

Cashgram reduces the processing time for refunds/payments by eliminating the manual work that you would have to do to collect users' payment details like, bank account details, UPI, or phone numbers registered with wallets.

You can create a single Cashgram or create a larger number of Cashgrams at a time using the dashboard, check the links below to know more.

* [Create Cashgram](/docs/payouts/cashgram/create-new-cashgram)
* [Create Cashgrams in Batches](/docs/payouts/cashgram/create-new-cashgram#batch-upload-cashgrams)


# Approve Bulk Cashgram
Source: https://www.cashfree.com/docs/payouts/cashgram/cashgram-classic-dashboard/approve-bulk-cashgram

Use the Cashfree classic Payouts Dashboard to review and approve bulk-uploaded Cashgrams before they are released to customers for collection.

When you create a large number of cashgrams using the bulk cashgram feature, you may want approval from the approver in your company before sending it to the customers. An approver can verify and approve the cashgrams, and then send them to the customers.

One of the users in your company can add all the customer details in the file and upload the file and later another user can approve the cashgrams. The approver has the option to accept or reject the Cashgrams. After approval, the Cashgrams are sent to customers, and you can view the status of the Cashgram in the Payout Dashboard.

The option to create multiple users and assign permissions can be done from the Payout Dashboard. Write to Cashfree by filling the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1), if you want to use the Approve Bulk Cashgrams feature.


# Create Bulk Cashgram
Source: https://www.cashfree.com/docs/payouts/cashgram/cashgram-classic-dashboard/create-bulk-cashgram

Send Cashgrams to many customers at once by uploading a beneficiary file through the Cashfree classic Payouts Dashboard for fast bulk disbursements.

When you have to create and send cashgrams to a large number of customers you can use the Bulk Cashgram feature. You can upload the file with the details using the Upload File option in the Payouts Dashboard.

You can view the status of the uploaded files and also download them to view further details.

To create cashgram in bulk,

1. Go to **Payouts Dashboard** > **Cashgram** > **Bulk Cashgrams** > click **UPLOAD FILE**.
2. Download a sample format in which you wish to provide the customer details for creating the Cashgrams.
3. Fill in the details and save the file.
4. Click **CHOOSE FILE** to select the file and then select **UPLOAD**. You get a message that the file has been uploaded.

The file can include a maximum of 100 rows and the file size should be within 2 MB.


# Create Cashgram
Source: https://www.cashfree.com/docs/payouts/cashgram/cashgram-classic-dashboard/create-cashgram

Create a single Cashgram from the Cashfree classic Payouts Dashboard or APIs and send the link to a customer to collect funds from your Payouts Account.

You can create Cashgrams through your Payouts Dashboard or from the APIs. Ensure you have sufficient balance in your Payouts Account before you create a Cashgram. The amount will be deducted from your Payouts Account to send money to your customers.

To create a Cashgram,

1. Go to **Payouts Dashboard** > **Cashgram** > **Cashgrams** > click **NEW CASHGRAM**.
2. Enter the **Cashgram Id**, **Customer Name**, **Amount** to be transferred, **Customer Phone**, and **Customer Email**. The Cashgram Id helps you to track the Cashgram status.
3. Select an **Expiry** date. The Cashgram link will not be valid beyond this date.
4. Enter the Remarks.
5. Select the checkbox **Send Cashgram Link via WhatsApp, Email, and SMS** **to user** to notify the customer.
6. Click **CREATE**. The Cashgram link is created and sent to the customer. The customer can access the link and provide the required details to receive the payment.

<Tip>
  You can also use our API to create Cashgrams. Check the API documentation for more details.
</Tip>


# Verify Beneficiary Name
Source: https://www.cashfree.com/docs/payouts/cashgram/cashgram-classic-dashboard/verify-beneficiary-name

Use the Cashfree Beneficiary Name Verification feature to confirm that an account is valid and held by the intended recipient before transferring funds.

Beneficiary Name Verification is a new feature that allows businesses to ensure that the refunds, reimbursements, claims, etc., are sent to the intended beneficiary account only. It verifies that the bank account is valid before making the transfer and also ensures that the bank account is registered under the name of the intended beneficiary.

<img alt="" />

1. [Create Cashgram](/docs/payouts/cashgram/cashgram-classic-dashboard/create-cashgram) with the option Enable Bank Account Verification enabled. Share the link with the intended beneficiary over WhatsApp/SMS/email.
2. Beneficiary inputs their bank account number and IFSC.
3. Cashfree does a penny transfer to the bank account. On getting a response from the bank, Cashfree ensures that the account is valid and validates if the name entered by you matches with the beneficiary name as registered with the bank.\
   i) If the name matches accurately, the amount gets credited to the beneficiary account instantly.\
   ii) If there is a mismatch, the transaction will have to be manually approved from the **Verify Cashgrams** section.

<img alt="" />

<Info>
  Contact your Cashfree Account Manager to enable this functionality. This feature is
  only available on Cashgram payouts to bank accounts currently.
</Info>


# Payouts: Cashgram FAQs
Source: https://www.cashfree.com/docs/payouts/cashgram/cashgram-faq

Find answers to common questions about Cashfree Cashgram, including link generation, beneficiary redemption, expiry rules, refunds, and bulk disbursements.

<AccordionGroup>
  <Accordion title="How to assign approver to verify bulk Cashgrams?">
    When you create a large number of Cashgrams using the `Bulk Cashgram` feature, you may want approval from the approver in your company before sending it to the customers. An approver can verify and approve the Cashgrams, and then send them to the customers.

    One of the users in your company can add all the customer details in the file and upload the file and later another user can approve the Cashgrams. The approver has the option to accept or reject the Cashgrams. After approval, the Cashgrams are sent to customers, and you can view the status of the Cashgram in the Payout Dashboard.

    The option to create multiple users and assign permissions can be done from the Payout Dashboard. See the [Approve Cashgrams documentation](https://docs.cashfree.com/docs/approve-cashgrams) for more information. Fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1), if you want to use the Approve Bulk Cashgrams feature.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What happens if the customer enters an incorrect bank account while redeeming a Cashgram?">
    If the customer enters an invalid bank account number or IFSC code we will notify him on the web page. But if the customer enters a valid but incorrect account number the money will be transferred to that bank account.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What is a Cashgram?">
    Cashgram is an instant payout link used by businesses to send money to their customers, vendors, or partners, even if you do not know their bank account details. Users can access the payment link sent via WhatsApp, email, or SMS, provide their details, and choose a payment method to receive the amount.
    Merchants can create a single Cashgram or create a larger number of Cashgrams at a time using the dashboard.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Detailed Walkthrough of the new Cashgram changes">
    Cashgram helps businesses to instantly send money to users when bank account details are not known. With Cashgram, you can pay your vendors, partners, customers, or others instantly when you only know their mobile number or email address.

    What changes in the new Cashgram?
    Creating a Cashgram
    With this new upgrade, you can now specify the type of disbursal you are doing with the Payout Type field (Example - refunds, reimbursements, rewards) and a brief note on why the disbursal is being made in the Payout Reason field.

    Customising your Cashgram checkout page:
    You can now customise your checkout page with logos and colours that reflect your brand. Here’s how you do it,

    Login to the Cashgram dashboard
    Click on Settings > General > Branding
    Once in, you can upload your logo, add your brand colour to customise your Cashgrams, and enhance the experience for the end-user

    Here\`s how the checkout experience will look like for your end-users:

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How to generate a Cashgram?">
    You can create Cashgrams via the Payouts Dashboard or APIs. Ensure your Payouts account has sufficient balance, as funds are deducted from it to send money to beneficiaries.

    Steps to create a Cashgram:

    Navigate to:
    Payouts Dashboard > Cashgram > Create Cashgram.

    Fill in the details:

    Cashgram ID: A unique identifier to track the Cashgram.
    Payout Type: Select from Refunds, Reimbursements, Rewards, or add custom types.
    Beneficiary Details: Name, Phone Number, Email, and Transfer Amount.
    Validity: Set the expiry date for the Cashgram link.
    Reason & Remarks: Remarks will appear in the beneficiary’s bank statement if supported.
    Notification Mode: Choose Email, SMS, or WhatsApp to notify the beneficiary.
    Click "Create":
    The Cashgram link is sent to the beneficiary. They can click the link, provide details, and receive the funds.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How to generate bulk Cashgrams?">
    When you have to create and send Cashgrams to a large number of customers you can use the ‘Bulk Cashgram’ feature. You can upload the file with the details using the ‘Upload File’ button in the Payouts Dashboard.
    You can view the status of the uploaded files and also download them to view further details.

    To upload a batch file:

    1. Go to Payouts Dashboard > Cashgram > Batch > click Upload File.
    2. Click Choose a File to select the file you want to upload and then click Upload. The uploaded file will be visible in the Batch section.
    3. Click on the file to view the individual Cashgram details uploaded in the file.
       **Note**- Maximum file size allowed is 5 MB, and a maximum of 10000 records can be included in the file.

       <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How secure is Cashgram?">
    Cashgram is a secure way to transfer money to your customers. Once you create a Cashgram for a user only that user with the provided phone number can use that Cashgram. Cashgram is also active only for a limited amount of time, you can control the expiry time of each Cashgram. Post expiry, no one will be able to view/redeem the Cashgram.

    Once a Cashgram has been redeemed or expired, the customer will not be able to view it again.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How do I let a user know that I have generated a Cashgram for them?">
    You can use the dashboard to notify the user about their Cashgram. We will notify the customer over email or SMS.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Is it possible to edit or deactivate an active Cashgram?">
    You can't edit an active Cashgram. However, you can deactivate it at any time.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="I deactivated a Cashgram link, but a new one was triggered for the same customer. How do I stop this?">
    Deactivating a Cashgram link stops only that specific link. It does not prevent new Cashgram links from being created. Cashfree does not automatically re-trigger or regenerate Cashgram links; your refund automation workflow initiates new ones. To stop new Cashgram links for a customer, review and update your refund automation so it does not create a new Cashgram after deactivation.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Why is a customer’s Cashgram status showing as pending?">
    Once the customer submits their bank details to redeem a Cashgram we will initiate a bank transfer from Merchant’s account to the customer’s bank account. When the transfer status is yet to be confirmed, the Cashgram is in the Pending state. At this point, the partner bank could be processing the payout, and no further action is required from your end.
    The Pending state can transition into:

    * Redeemed state, if the Cashgram is successfully redeemed.
    * Failed state, if the Cashgram could not be redeemed.

      <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What happens if the user fails to get money using Cashgram?">
    If a beneficiary fails to redeem a Cashgram, it will appear as Failed on your dashboard. The Failed state is final and cannot transition to any other state.

    Common reasons for failure include:

    1. Incorrect beneficiary account details.

    2. Insufficient balance in your Payouts account. Enable Low Balance Alerts to get notified when your balance falls below a set threshold.

    3. Downtime or issues with partner or beneficiary bank servers.

    4. Most failures occur due to exceeding OTP limits. Ensure accurate details and sufficient balance to minimise such occurrences.

       <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are Payout links?">
    A Payout Links is a way to instantly send money to your beneficiaries without knowing their bank account details. You can simply create a payout link from the Cashfree dashboard, and send it to your vendors/ customers on their email id or mobile number.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Will I be notified if the Cashgram I generated is used?">
    Once the customer redeems a Cashgram its status changes from ACTIVE to REDEEMED instantly. You will be able to view this on the dashboard. You will also be notified over email once a Cashgram has been successfully redeemed, if merchant has opted for the email notification.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How do I use a Cashgram?">
    To use a Cashgram you need to have a Cashfree account. From your Cashfree dashboard, you can create a new Cashgram for a customer. The typical process is listed below-

    The merchant creates a Cashgram filling in the customer’s phone number.
    The customer receives SMS and email notification about this Cashgram generated by the Merchant.
    The customer visits the Cashgram link, authenticates, and enters their bank details.
    The money is instantly transferred from Merchant’s account to the customer’s bank account.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How can I start using Cashgram?">
    To start using Cashgram you will need to sign-up with Cashfree. If you already have a Payout account you can instantly start using Cashgram using the dashboard. Click on the “Cashgram” tab in the Payout dashboard.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="My Cashgram link is not working. What do I do?">
    A Cashgram link may not work if it is in an Expired, Failed, or Reversed state. Cashgrams remain Active for up to 30 days or the specified duration and can transition to states like Redeemed, Expired, Failed, or Reversed.
    Check the Cashgram status on the Payouts Dashboard. If the Cashgram link sent to you has expired. Please get in touch with the merchant to get a new Cashgram.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can the customer view and redeem a Cashgram any time?">
    Yes, the Cashgram recipient will be able to view and redeem their Cashgram at any time.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What happens if the Cashgram is never used?">
    Every Cashgram has an expiry date. If the Cashgram is not redeemed before this expiry date, the Cashgram will become inactive. No one will be able to view/redeem such an inactive Cashgram.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How will you verify user identity for Cashgram?">
    We authenticate users using OTP so that only authorised users can view/redeem a Cashgram. Without a valid OTP, nobody can view/redeem a particular Cashgram.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can customers also redeem money to their UPI account?">
    If you have UPI enabled in your Smart Payout account your customers will be able to redeem a Cashgram to their UPI account.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can customers also redeem money to their PayTM account?">
    If you have PayTM enabled in your Smart Payout account your customers will be able to redeem a Cashgram to their PayTM account.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are the advantages of using a Cashgram?">
    Cashgram simplifies money transfers by removing the need for bank details or manual processing. Users are notified via WhatsApp, email, or SMS and can redeem payments anytime using a secure link.\
    **Key Benefits:**

    * Instant refunds for COD payments, cash prizes, and security deposits.
    * No need to collect bank details; users choose from multiple payment methods.
    * Saves time with automated payment processing.
    * Supports single or bulk Cashgram creation via the dashboard.

      <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Is Cashgram different from Payout links?">
    Cashgram is a payout link with many additional features. You can customise your Cashgram links with your company logo and colour to reflect your brand. You can also set up a link expiry time and verify the beneficiary's name before sending out the money.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="I am not able to receive the OTP.">
    Please verify your mobile number with the merchant. You can receive the OTP via SMS or WhatsApp. If one method does not work, we recommend trying the alternative. In case you are still not receiving the OTP, please [report the issue to us](https://www.cashfree.com/en/report-issue/).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What is a Payout link?">
    A Payout Link is a way to instantly send money to your beneficiaries without knowing their bank account details. You can simply create a payout link from the Cashfree dashboard, and send it to your vendors/ customers on their email id or mobile number.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="I received a Cashgram on email but the mobile number mentioned on the Cashgram is incorrect. How do I proceed?">
    It seems that the Merchant entered a different mobile number while generating the Cashgram. Please reach out to the merchant to get this changed.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="My Cashgram transfer is showing successful but I have not received the money in my account?">
    The money should be transferred into your account in some time. If you do not receive the amount within one hour please fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1). Do mention your email id, phone number, Cashgram Id, and merchant name in your email.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="My Cashgram transfer failed, what do I do now?">
    A Cashgram can fail due to:

    1. Incorrect beneficiary account details.
    2. Insufficient balance in your Payouts account. To avoid this, set a Low Balance Alert to receive notifications when the balance falls below a specified amount.
    3. Downtime in partner or beneficiary bank servers.\
       Please reach out to the merchant so that they can generate a new Cashgram for you.

       <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What all details do I need to redeem a Cashgram?">
    Cashgram can be redeemed to your bank account, UPI VPA, or PayTM. If any of the above modes is not enabled for you, please get in touch with the merchant.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="What are the charges for using Cashgram?">
    Cashfree doesn't publish a standard rate card for Cashgram. Pricing is customised based on your transaction volume and business category.

    To get pricing for your business, submit this [Contact Sales form](https://www.cashfree.com/contact-sales/).

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="My Cashgram transfer is pending, when will the money be credited into my account?">
    When the transfer status is yet to be confirmed, the Cashgram is in the Pending state. At this point, the partner bank could be processing the payout, and no further action is required from your end.

    The Pending state can transition into:

    1. Redeemed state, if the Cashgram is successfully redeemed.
    2. Failed state, if the Cashgram could not be redeemed.

    Please wait for 24 hours, if you still have not received the money in your account, reach us by filling out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1). Do mention your email id, phone number, Cashgram Id, and merchant name in the support form.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="My Cashgram is not showing PayTM or UPI?">
    If any of the above modes is not enabled for you, please get in touch with the merchant.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="How can I provide a new user with access to Cashgram Payouts in the Merchant Dashboard?">
    To provide a user with access to Cashgram Payouts, the Primary Admin must create an Alias Account and assign the appropriate role:

    1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
    2. Go to **Settings** in the top navigation panel.
    3. Under the **General** tab, click **Access Management**.
    4. Click **+ Invite New User** and enter the user's email address to create the Alias Account.
    5. Once the account is added, navigate to **Role Management** and assign the required permissions for Cashgram Payouts.

    <iframe title="FAQs feedback component" />
  </Accordion>

  <Accordion title="Can I re-trigger or re-hit a Cashgram status webhook?">
    Cashfree does not provide a separate URL to re-hit or re-trigger Cashgram webhooks. Cashgram uses event-based webhooks — `CASHGRAM_TRANSFER_SUCCESS`, `CASHGRAM_TRANSFER_FAILED`, and `CASHGRAM_EXPIRED` — that are sent to the URL configured in your Payouts Dashboard. If you need to verify the current status of a Cashgram, use the Get Cashgram Status API.

    <iframe title="FAQs feedback component" />
  </Accordion>
</AccordionGroup>


# Lifecycle
Source: https://www.cashfree.com/docs/payouts/cashgram/cashgram-lifecycle

Understand the Cashfree Cashgram lifecycle, including every status from creation and beneficiary notification to redemption, expiry, and refunded states.

When you create a Cashgram there are various states that the Cashgram goes through before the user redeems the Cashgram to his account. The various states help you understand the status of Cashgram.

<img alt="" />

A state is final if it does not allow transitioning to any other state within the lifecycle.

The various states in the Cashgram lifecycle are as below:

* **Active**
* **Expired**
* **Pending**
* **Failed**
* **Redeemed**
* **Reversed**

## Active

When a new Cashgram has been created it is in the Active state. A Cashgram is active for a maximum of 30 days from the date of creation or the date specified by you during the creation.

The Active state can transition into:

* Redeemed state, if the customer successfully redeems the Cashgram.
* Expired state, if the Cashgram is no longer active.

## Expired

When the Cashgram is no longer active, the Cashgram is in the Expired state. Expired is a final state and does not allow transitioning to any other state.

A Cashgram can indicate the Expired state due to various reasons, such as:

* The Cashgram link has not been accessed within the specified time.
* The OTP verification is successful and the Cashgram is not redeemed.

## Pending

When the transfer status is yet to be confirmed, the Cashgram is in the Pending state. At this point, the partner bank could be processing the payout, and no further action is required from your end.

The Pending state can transition into:

* Redeemed state, if the Cashgram is successfully redeemed.
* Failed state, if the Cashgram could not be redeemed.

## Failed

When the transfer fails, the Cashgram is in the Failed state. Failed is a final state and does not allow transitioning to any other state.

A Cashgram can indicate the Failed state due to various reasons, such as:

* The beneficiary account details are incorrect.
* Insufficient balance in your Payouts recharge account. To avoid this, you can specify the balance in the Low Balance Alert section, if the balance goes below the amount specified, Cashfree will send you a notification.
* Partner or beneficiary bank servers are down.

## Redeemed

When the transfer is successfully processed, the Cashgram is in the Redeemed state.

In certain cases, the Redeemed state may transition into the Reversed state if the transfer is reversed by the beneficiary bank.

## Reversed

A Cashgram can be in the Reversed state if the transfer is reversed by the clearing house or beneficiary bank.

Reversed is a final state and does not allow transitioning to any other state. Cashfree credits the original amount to your Payouts account.

You can see the status of the Cashgrams on the Payouts Dashboard, or you can use the API [Get Cashgram Status](/docs/api-reference/payouts/v1/get-cashgram-status) to know the status.


# Create Cashgram
Source: https://www.cashfree.com/docs/payouts/cashgram/create-new-cashgram

Create and send Cashfree Cashgrams to beneficiaries from the Payouts Dashboard or APIs, with single and batch upload options for faster bulk disbursements.

You can create Cashgrams from your Payouts Dashboard or through the APIs. Before creating a Cashgram, ensure you have sufficient balance in your Payouts Account. The specified amount will be deducted from your account and sent to your beneficiaries.

<Note>
  You can't edit active Cashgrams, but you can deactivate them.
</Note>

## Create a Cashgram

You can create individual Cashgrams through the Payouts Dashboard for targeted payouts to specific beneficiaries.

To create a Cashgram:

1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
2. Go to **Payouts Dashboard** > **Cashgram** > click **Create Cashgram**.
3. Enter the **Cashgram ID** and specify the **Payout Type**. Refunds, Reimbursements, and Rewards payout types are available by default. You can specify any other payout type according to your requirement.
4. Enter the **Beneficiary Name**, **Beneficiary Phone Number**, **Beneficiary Email ID**, and the **Amount** to be transferred. The Cashgram ID helps you track the Cashgram status.
5. In the **Cashgram Valid Till** field, specify the date until which the Cashgram link should remain valid. The link won't be valid beyond this date.
6. Enter the **Reason** and **Remarks**. The remarks will be visible in the beneficiary account statement if their bank supports it.
7. In the **Send Cashgram via** field, select how you want to notify the beneficiary. Email, SMS, and WhatsApp notifications are supported.
8. Click **CREATE**. The Cashgram link is created and sent to the beneficiary. The beneficiary can access the link and provide the required details to receive the amount.

<img alt="Create Cashgram" />

<Tip>You can also use the API to [create Cashgrams](/docs/api-reference/payouts/v1/create-cashgram).</Tip>

## Batch upload cashgrams

Use the Batch Upload feature to create and send Cashgrams to multiple beneficiaries simultaneously. You must add all required details in a single file according to the required format and upload it in the Batch Upload section. Download the sample file to understand what information is required in the batch upload.

To upload a batch file:

1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).
2. Go to **Payouts Dashboard** > **Cashgram** > **Batch** > click **Upload File**.
3. Click **Choose a File** to select the file you want to upload and then select **Upload**. The uploaded file will be visible in the **Batch** section.
4. Click on the file to view the individual Cashgram details uploaded in the file.

<Info>
  * Maximum file size allowed is 5 MB, and a maximum of 10,000 records can be
    included in the file. - The file can't be uploaded if it's not according to the
    suggested format. Also, if there are any errors in the uploaded file, you must
    resolve all the errors and upload the file again.
</Info>

You can view the status of the uploaded files and also download them to view more details.


# Cashgram Integration
Source: https://www.cashfree.com/docs/payouts/cashgram/integration/cashgram-integration

Integrate Cashfree Cashgram to send instant payouts to beneficiaries via shareable links, including creating Cashgrams and fetching their status via API.

Cashgram is a sub-service of payouts offered by Cashfree that enables you to send money to your clients instantly. This topic will help you to integrate with Cashgram. It includes creating a Cashgram and fetching the Cashgram status.

<img alt="" />

**Steps**

1. Setup
2. Initialisation and Authorisation
3. Create Cashgram
4. Get Cashgram Status

## Step 1: Setup

Get your corresponding clientId and clientSecret from your payout dashboard and ensure that your IP is whitelisted. Check our development quickstart here.

**Host URL**: Use the following URL for PROD and TEST, respectively:

* For the **production** environment: [https://payout-api.cashfree.com](https://payout-api.cashfree.com)
* For the **test** environment: [https://payout-gamma.cashfree.com](https://payout-gamma.cashfree.com)

## Step 2: Initialisation and authorisation

Call the authenticate API to Cashfree's system/server to obtain an Authorization Bearer token. All other API calls must have this token as Authorization header in the format 'Bearer \<token>' (without quotes) to get processed.

<CodeGroup>
  ```bash cURL theme={"dark"}
  curl -X POST \
    'http://{{Host%20Url}}/payout/v1/authorize' \

    -H 'X-Client-Id: {{client id}}' \
    -H 'X-Client-Secret: {{client secret}}' \
    -H 'cache-control: no-cache'
  ```

  ```javascript Node theme={"dark"}
  //require CashfreeSDK
  const cfSdk = require("cashfree-sdk");

  //access the PayoutsSdk from CashfreeSDK
  const { Payouts } = cfSdk;

  // Instantiate Cashfree Payouts
  const payoutsInstance = new Payouts({
  	env: "TEST",
  	clientId: "<CLIENT_ID>",
  	clientSecret: "<CLIENT_SECRET>",
  });
  ```

  ```python Python theme={"dark"}
  from cashfree_sdk.payouts import Payouts
  from cashfree_sdk.payouts.cashgram import Cashgram

  clientId = "your_client_id"
  clientSecret = "your_client_secret"
  env = "TEST"

  Payouts.init(clientId, clientSecret, env)
  ```

  ```java Java theme={"dark"}
  import com.cashfree.lib.clients.Payouts;
  import com.cashfree.lib.constants.Constants.Environment;

  public static void main() {
  Payouts payouts = Payouts.getInstance(
      Environment.PRODUCTION, "<client_id>", "<client_secret>");
  payouts.init();
  }
  ```
</CodeGroup>

**Sample Response**

```json theme={"dark"}
{
	"status": "SUCCESS",
	"message": "Token generated",
	"subCode": "200",
	"data": { "token": "eyJ0eXA...fWStg", "expiry": 1564130052 }
}
```

## Step 3: Create cashgram

Create a Cashgram that can be sent directly to your end customer by passing their relevant information.

<CodeGroup>
  ```bash cURL theme={"dark"}
  curl -X POST \
    'https://{{Host%20Url}}/payout/v1/payout/v1/createCashgram' \
    -H 'Accept: */*' \
    -H 'Authorization: Bearer {{token}}' \
    -H 'Content-Type: application/json' \
    -d '{
         "cashgramId": "cf6",
          "amount": "1.00",
          "name": "sameera",
          "email": "beneficiary@example.com",
          "phone": "9000000001",
          "linkExpiry": "2019/11/9",
          "remarks": "sample cashgram",
          "notifyCustomer": 1
  }'
  ```

  ```javascript Node theme={"dark"}
  //create cashgram
  const response = await payoutsInstance.cashgram.create({
  	cashgramId: "cf11",
  	amount: "1.00",
  	name: "sameera",
  	email: "beneficiary@example.com",
  	phone: "9000000001",
  	linkExpiry: "2020/01/12",
  	remarks: "sample cashgram",
  	notifyCustomer: 1,
  });
  ```

  ```python Python theme={"dark"}
  #create cashgram
  create_cashgram_response = Cashgram.create_cashgram(
      cashgramId = "cf11",
      amount = "1.00",
      name = "sameera",
      email = "beneficiary@example.com",
      phone = "9000000001",
      linkExpiry = "2020/01/19",
      remarks = "sample cashgram",
      notifyCustomer = 1
      )
  ```

  ```java Java theme={"dark"}
  import com.cashfree.lib.clients.Payouts;
  import com.cashfree.lib.clients.Cashgram;
  import com.cashfree.lib.domains.CashgramDetails

  Payouts payouts = Payouts.getInstance(
      Environment.PRODUCTION, "<client_id>", "<client_secret>");
  payouts.init();
  Cashgram cashgram = new Cashgram(payouts);

  CashgramDetails cashgramDetails = new CashgramDetails()
          .setCashgramId("javasdk-test2")
          .setAmount(new BigDecimal("1.00"))
          .setName("John Doe")
          .setEmail("johndoe@cashfree.com")
          .setPhone("9876543210")
          .setLinkExpiry(LocalDateTime.now().plusMinutes(0))
          .setRemarks("api")
          .setNotifyCustomer(1);
  cashgram.createCashgram(cashgramDetails);

  }
  ```
</CodeGroup>

notifyCustomer field is an optional field when set to 1 it sends the Cashgram to your end customer phone and email.

**Sample Response**

```json theme={"dark"}
{
	"status": "SUCCESS",
	"subCode": "200",
	"message": "Cashgram Created",
	"data": { "referenceId": 3645, "cashgramLink": "http://bit.ly/2xxnGm8" }
}
```

The `cashgramLink` is returned directly in the `data` object of the response. You can use this link to deliver the Cashgram through your own application or interface rather than relying on Cashfree's automated delivery.

## Step 4: Get cashgram status

Get the status of the created Cashgram by passing the cashgramId.

<CodeGroup>
  ```bash theme={"dark"}
  curl -X GET \
    'https://{{Host%20Url}}/payout/v1/getCashgramStatus?cashgramId=JOHaN10' \
    -H 'Accept: */*' \
    -H 'Authorization: Bearer {{token}}' \
    -H 'Content-Type: application/json' \
  ```

  ```javascript Node theme={"dark"}
  //get cashgram status
  payoutsInstance.cashgram.getStatus({
  	cashgramId: cashgram.cashgramId,
  });
  ```

  ```python Python theme={"dark"}
  get_cashgram_status_response = Cashgram.get_cashgram_status("cf11")
  ```

  ```java Java theme={"dark"}
  import com.cashfree.lib.clients.Payouts;
  import com.ca