> ## Documentation Index > Fetch the complete documentation index at: https://www.cashfree.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Debit Wallet > 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: 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`. 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](/api-reference/prepaid-payment-instruments/wallet-management/verify-debit-wallet). This two-step flow does not apply to `GIFT_PPI` or `CLOSED_LOOP_PPI` sub-wallets. ## OpenAPI ````yaml /openapi/ppi/ppi.yaml post /ppi/wallet/debit openapi: 3.0.3 info: title: PPI Wallet API description: >- API for managing PPI (Prepaid Payment Instrument) wallets and sub-wallets, including credit and debit operations. version: 1.0.0 contact: name: PPI Service Team email: support@cashfree.com license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0 servers: - url: https://api.cashfree.com description: Production server. - url: https://sandbox.cashfree.com description: Sandbox server. security: - XClientID: [] XClientSecret: [] tags: - name: Wallet Management description: Operations related to PPI wallet management. - name: User Management description: Operations related to user management within the PPI system. - name: Beneficiary Management description: Operations related to beneficiary management for users. - name: KYC Management description: Operations related to KYC (Know Your Customer) management. - name: Transfers description: Operations related to transfer. paths: /ppi/wallet/debit: post: tags: - Wallet Management summary: Debit Wallet description: > 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: 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`. operationId: debitWallet parameters: - $ref: '#/components/parameters/global_x_api_version' requestBody: $ref: '#/components/requestBodies/CreateWalletDebitRequest' responses: '200': description: > Success response for debiting a wallet. - For `GIFT_PPI` and `CLOSED_LOOP_PPI`, the debit completes in one step. - For other sub-wallet types with OTP verification, the response body includes `auth` (echoed from the request) and status `OTP_GENERATED` until you call the Verify Debit Wallet API. content: application/json: schema: $ref: '#/components/schemas/WalletDebitResponse' examples: SUCCESS_GIFT_WALLET: summary: Successful debit from GIFT_WALLET value: 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 applied_gift_codes: - code: GHO-8900-HKDH-8899 amount_debited: 100 value: 100 expiry: '2026-07-28T10:30:00Z' - code: NMK-8454-JKJD-4224 amount_debited: 500 value: 600 expiry: '2026-07-28T10:30:00Z' status: SUCCESS amount: 600 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 SUCCESS_CLOSED_WALLET: summary: Successful debit from CLOSED_WALLET value: debit_id: DEBIT420984 user_id: USER827364 cf_debit_id: '8901234567890123456' wallet_id: WALLET936721 sub_wallet: cf_sub_wallet_id: '35246543210987654321' name: Closed Wallet type: CLOSED_LOOP_PPI status: ACTIVE balance: 1500.75 available_balance: 1500.75 funds_on_hold: 0 status: SUCCESS amount: 600 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 OTP_GENERATED_SMALL_PPI_WALLET: $ref: '#/components/examples/OTP_GENERATED_SMALL_PPI_WALLET' OTP_GENERATED_FULL_KYC_PPI_WALLET: $ref: '#/components/examples/OTP_GENERATED_FULL_KYC_PPI_WALLET' '400': description: Bad request - Invalid input parameters. content: application/json: schema: $ref: '#/components/schemas/StructuredErrorResponse' examples: debit_id_missing: $ref: '#/components/examples/debit_id_missing' sub_wallet_id_missing: summary: Sub-wallet ID missing value: code: sub_wallet_id_missing type: validation_error message: cf_sub_wallet_id is missing in the request user_id_missing: summary: User ID missing value: code: user_id_missing type: validation_error message: user_id is missing in the request userWalletMismatch: summary: User-Wallet mismatch value: message: wallet does not belong to provided user code: wallet_id_value_invalid type: validation_error userSubWalletMismatch: summary: User-SubWallet mismatch value: message: sub-wallet does not belong to provided user code: sub_wallet_id_value_invalid type: validation_error sub_wallet_id_invalid: summary: Sub-wallet ID is Invalid value: code: sub_wallet_id_invalid type: validation_error message: cf_sub_wallet_id is invalid in the request amountMissing: summary: Amount missing value: code: amount_missing type: validation_error message: amount is missing in the request invalidAmount: summary: Invalid amount format value: code: amount_value_invalid type: validation_error message: amount should be of valid format missingClientId: summary: Missing client ID value: message: x-client-id is missing in the request code: x-client-id_missing type: validation_error missingClientSecret: summary: Missing client secret value: message: x-client-secret is missing in the request code: x-client-secret_missing type: validation_error maximumNotesExceeded: summary: Maximum notes limit exceeded value: message: Maximum 10 notes entries allowed code: notes_value_invalid type: validation_error notesValueInvalidLength: summary: Note value length exceeds limit value: message: Note value must be 200 characters or less code: notes_value_invalid type: validation_error notesKeyInvalidLength: summary: Note key length exceeds limit value: message: Note Key must be 50 characters or less code: notes_value_invalid type: validation_error auth_mode_missing: $ref: '#/components/examples/auth_mode_missing' auth_mode_invalid: $ref: '#/components/examples/auth_mode_invalid' auth_data_missing: $ref: '#/components/examples/auth_data_missing' auth_notification_modes_missing: $ref: '#/components/examples/auth_notification_modes_missing' auth_notification_modes_too_many: $ref: '#/components/examples/auth_notification_modes_too_many' auth_notification_modes_null: $ref: '#/components/examples/auth_notification_modes_null' auth_notification_modes_duplicate: $ref: '#/components/examples/auth_notification_modes_duplicate' '401': $ref: '#/components/responses/Response401' '403': description: Forbidden - Access denied. content: application/json: schema: $ref: '#/components/schemas/StructuredErrorResponse' examples: ipNotWhitelisted: summary: IP not whitelisted value: code: ip_not_whitelisted type: authentication_error message: Authentication error (IP not whitelisted) '404': description: Not found - Wallet or sub-wallet not found. content: application/json: schema: $ref: '#/components/schemas/StructuredErrorResponse' examples: walletNotFound: summary: Wallet not found value: code: wallet_id_not_found type: invalid_request_error message: The specified wallet_id does not exist subWalletNotFound: summary: Sub-wallet not found value: code: sub_wallet_id_not_found type: invalid_request_error message: The specified cf_sub_wallet_id does not exist '409': description: Conflict - Transaction already processed. content: application/json: schema: $ref: '#/components/schemas/StructuredErrorResponse' examples: duplicateTransaction: summary: Duplicate transaction value: code: debit_id_already_exists type: invalid_request_error message: >- Transaction with the same debit_id has already been processed '422': description: Unprocessable Entity - Business rule validation failed. content: application/json: schema: $ref: '#/components/schemas/StructuredErrorResponse' examples: dailyMaxDebitCountLimitExceeded: summary: Daily debit count limit exceeded value: code: daily_max_debit_count_limit_exceeded type: validation_error message: daily debit count cannot exceed 3 for Gift ppi monthlyMaxDebitCountLimitExceeded: summary: Monthly debit count limit exceeded value: code: monthly_max_debit_count_limit_exceeded type: validation_error message: monthly debit count cannot exceed 20 for Gift ppi yearlyMaxDebitCountLimitExceeded: summary: Yearly debit count limit exceeded value: code: yearly_max_debit_count_limit_exceeded type: validation_error message: yearly debit count cannot exceed 100 for Gift ppi dailyMaxDebitAmountLimitExceeded: summary: Daily total debit amount limit exceeded value: code: daily_max_debit_amount_limit_exceeded type: validation_error message: >- daily total debit amount cannot exceed ₹10,000.00 for Small ppi monthlyMaxDebitAmountLimitExceeded: summary: Monthly total debit amount limit exceeded value: code: monthly_max_debit_amount_limit_exceeded type: validation_error message: >- monthly total debit amount cannot exceed ₹10,000.00 for Small ppi yearlyMaxDebitAmountLimitExceeded: summary: Yearly total debit amount limit exceeded value: code: yearly_max_debit_amount_limit_exceeded type: validation_error message: >- yearly total debit amount cannot exceed ₹1,20,000.00 for Small ppi maxPerDebitLimitExceeded: summary: Per debit amount limit exceeded value: code: max_per_debit_limit_exceeded type: validation_error message: per debit amount cannot exceed ₹10,000.00 for Gift ppi '429': description: Too Many Requests - Rate limit exceeded. content: application/json: schema: $ref: '#/components/schemas/StructuredErrorResponse' examples: rateLimitExceeded: summary: Rate limit exceeded value: code: rate_limit_exceeded type: rate_limit_error message: Rate limit exceeded. Please try again after some time '500': $ref: '#/components/responses/Response500' components: parameters: global_x_api_version: description: API version to be used. Format is in YYYY-MM-DD. name: x-api-version in: header required: true schema: type: string default: '2025-11-01' example: '2025-11-01' example: '2025-11-01' requestBodies: CreateWalletDebitRequest: description: Request parameters to debit funds from a user's wallet. required: true content: application/json: schema: $ref: '#/components/schemas/WalletDebitRequest' examples: giftWalletDebit: summary: Gift wallet debit description: Debiting from a gift wallet with gift card processing. value: debit_id: DEBIT420984 user_id: USER827364 wallet_id: WALLET936721 cf_sub_wallet_id: '35246543210987654321' amount: 600 remarks: Purchase of electronics item notes: example_key: example_value smallPpiDebitWithOtp: summary: SMALL_PPI debit (auth required) description: The auth object is mandatory for SMALL_PPI sub-wallets. value: debit_id: DEBIT420984 user_id: USER827364 wallet_id: WALLET936721 cf_sub_wallet_id: '54252453468535350359' amount: 600 remarks: Purchase of electronics item notes: example_key: example_value auth: mode: OTP_VERIFICATION data: notification_modes: - SMS - WHATSAPP fullKycPpiDebitWithOtp: summary: FULL_KYC_PPI debit (auth required) description: The auth object is mandatory for FULL_KYC_PPI sub-wallets. value: debit_id: DEBIT420985 user_id: USER827364 wallet_id: WALLET936721 cf_sub_wallet_id: '35246543210987654321' amount: 500.75 remarks: Purchase of electronics item notes: example_key: example_value auth: mode: OTP_VERIFICATION data: notification_modes: - SMS - WHATSAPP schemas: WalletDebitResponse: type: object properties: debit_id: type: string description: >- Unique identifier for the debit transaction, as provided by you during the debit request. example: DEBIT420984 user_id: type: string description: >- Unique identifier for the user, as provided by you during PPI user creation. example: USER827364 cf_debit_id: type: string description: Unique identifier for the debit transaction, generated by Cashfree. example: '8901234567890123456' wallet_id: type: string description: Primary wallet ID from which the amount was debited. example: WALLET936721 sub_wallet: $ref: '#/components/schemas/SubWallet' applied_gift_codes: type: array description: >- List of gift codes used in the transaction are applicable for GIFT type wallets. items: $ref: '#/components/schemas/AppliedGiftCode' status: type: string description: > The status of the debit transaction. - For `GIFT_PPI` and `CLOSED_LOOP_PPI` sub-wallets, the status is `SUCCESS` when the debit completes in a single call. - For `SMALL_PPI` and `FULL_KYC_PPI` sub-wallets, the Debit Wallet API returns `OTP_GENERATED` until you verify the OTP using the [Verify Debit Wallet](/api-reference/prepaid-payment-instruments/wallet-management/verify-debit-wallet) API, after which the status moves to `SUCCESS`. example: SUCCESS amount: type: number format: double description: Amount that was debited. example: 600 remarks: type: string description: Remarks for the debit transaction. example: Purchase of electronics item initiated_at: type: string format: date-time description: Timestamp when the debit transaction was initiated. example: '2025-07-28T10:30:00Z' processed_at: type: string format: date-time nullable: true description: > Timestamp when the debit transaction was processed. Returns null while the debit is awaiting OTP verification or is still in progress. example: '2025-07-28T10:30:00Z' notes: type: object description: | Optional key-value metadata for the debit transaction. properties: example_key: type: string example: example_value auth: description: > Present only when you sent `auth` in the Debit Wallet request body for an OTP flow (`SMALL_PPI` or `FULL_KYC_PPI`). Echoes the same `mode` and `data` you supplied. Omitted for single-step debits (such as `GIFT_PPI` or `CLOSED_LOOP_PPI`). allOf: - $ref: '#/components/schemas/WalletOtpVerificationAuth' StructuredErrorResponse: type: object properties: type: type: string description: A broad category of the error. example: internal_error code: type: string description: A machine-readable error code specific to the issue. example: internal_server_error message: type: string description: >- A message providing more details about the error, dynamic based on the specific issue. example: Internal server error WalletDebitRequest: type: object required: - debit_id - user_id - wallet_id - cf_sub_wallet_id - amount properties: debit_id: type: string description: >- Unique identifier that you create to identify the debit transaction in your system. Maximum 100 characters. Only alphanumeric characters, periods (.), hyphens (-), and underscores (_) are allowed. example: DEBIT420984 minLength: 1 maxLength: 50 user_id: type: string description: >- Unique identifier for the user, as provided by you during PPI user creation. example: USER827364 minLength: 1 maxLength: 50 wallet_id: type: string description: >- Unique identifier for the wallet, as provided by you during wallet creation. example: WALLET936721 cf_sub_wallet_id: type: string description: >- Unique identifier of the sub-wallet from which the amount will be debited. example: '35246543210987654321' minLength: 1 maxLength: 100 amount: type: number format: double description: >- Amount to be debited. Decimal values are allowed. The minimum value should be equal to or greater than 1.00 (>= 1.00). example: 100.5 minimum: 1 remarks: type: string description: >- Alphanumeric and whitespaces are allowed. The maximum character limit is 60. example: Payment for subscription service maxLength: 500 notes: type: object description: | Optional key-value metadata for the debit transaction. properties: example_key: type: string example: example_value auth: description: > Required for `SMALL_PPI` and `FULL_KYC_PPI` sub-wallets. Set `mode` to `OTP_VERIFICATION` and specify at least one channel in `data.notification_modes` (for example, `SMS` or `WHATSAPP`). Not applicable for `GIFT_PPI` or `CLOSED_LOOP_PPI` sub-wallets. allOf: - $ref: '#/components/schemas/WalletOtpVerificationAuth' SubWallet: type: object properties: cf_sub_wallet_id: type: string description: >- Unique identifier for the sub-wallet provided in response while creating the wallet. example: '5432109876543210987' name: type: string description: Name for the sub-wallet. example: Gift Wallet type: type: string description: Type of the sub-wallet. example: GIFT_PPI status: type: string description: Status of the sub-wallet. example: ACTIVE balance: type: number format: double description: Current balance of the sub-wallet. example: 1500.75 available_balance: type: number format: double description: Available balance in the sub-wallet. example: 1500.75 funds_on_hold: type: number format: double description: Funds on hold in the sub-wallet. example: 0 AppliedGiftCode: type: object properties: code: type: string description: Unique identifier for the gift code. example: GIFT-2025-XYZ133 amount_debited: type: number format: double description: Amount debited from the gift code. example: 100 value: type: number format: double description: Total Value of the gift code. example: 100 expiry: type: string format: date-time description: Expiry date of the gift code. example: '2026-07-28T10:30:00Z' WalletOtpVerificationAuth: type: object description: > OTP verification payload. When `mode` is `OTP_VERIFICATION`, Cashfree sends an OTP using `data.notification_modes`. required: - mode - data properties: mode: type: string description: >- Authentication mode applied to this request. Only `OTP_VERIFICATION` is supported. enum: - OTP_VERIFICATION example: OTP_VERIFICATION data: type: object description: >- Configuration for the selected `mode`. Required when `mode` is `OTP_VERIFICATION`. required: - notification_modes properties: notification_modes: type: array description: > Channels used to deliver the OTP to the end user. Specify at least one value. For example, use `SMS` and `WHATSAPP` to send the OTP over both channels. minItems: 1 items: type: string description: Delivery channel for the OTP. enum: - SMS - WHATSAPP example: - SMS - WHATSAPP examples: OTP_GENERATED_SMALL_PPI_WALLET: summary: OTP_GENERATED_SMALL_PPI_WALLET value: debit_id: DEBIT420984 user_id: USER827364 cf_debit_id: '8901234567890123456' wallet_id: WALLET936721 sub_wallet: cf_sub_wallet_id: '54252453468535350359' name: Small PPI Wallet type: SMALL_PPI status: ACTIVE balance: 1500.75 available_balance: 1500.75 funds_on_hold: 0 status: OTP_GENERATED amount: 600 remarks: Purchase of electronics item initiated_at: '2025-07-28T10:30:00Z' processed_at: null notes: example_key: example_value auth: mode: OTP_VERIFICATION data: notification_modes: - SMS - WHATSAPP OTP_GENERATED_FULL_KYC_PPI_WALLET: summary: OTP_GENERATED_FULL_KYC_PPI_WALLET value: debit_id: DEBIT420985 user_id: USER827364 cf_debit_id: '8901234567890123457' wallet_id: WALLET936721 sub_wallet: cf_sub_wallet_id: '35246543210987654321' name: Cashfree payout Wallet type: FULL_KYC_PPI status: ACTIVE balance: 9500.86 available_balance: 1500.75 funds_on_hold: 0 status: OTP_GENERATED amount: 500.75 remarks: Purchase of electronics item initiated_at: '2025-07-28T10:30:00Z' processed_at: null notes: example_key: example_value auth: mode: OTP_VERIFICATION data: notification_modes: - SMS - WHATSAPP debit_id_missing: summary: Debit ID missing value: code: debit_id_missing type: validation_error message: debit_id is missing in the request auth_mode_missing: summary: auth.mode missing value: code: auth_mode_missing type: validation_error message: auth.mode is required auth_mode_invalid: summary: auth.mode invalid value: code: auth_mode_invalid type: validation_error message: only OTP_VERIFICATION mode is supported auth_data_missing: summary: auth.data missing for OTP_VERIFICATION value: code: auth_data_missing type: validation_error message: auth.data is required for OTP_VERIFICATION auth_notification_modes_missing: summary: auth.data.notification_modes missing or empty value: code: auth_notification_modes_missing type: validation_error message: >- auth.data.notification_modes must contain at least one channel for OTP_VERIFICATION auth_notification_modes_too_many: summary: auth.data.notification_modes too many entries value: code: auth_notification_modes_too_many type: validation_error message: auth.data.notification_modes must contain at most 5 entries auth_notification_modes_null: summary: auth.data.notification_modes contains null value: code: auth_notification_modes_null type: validation_error message: auth.data.notification_modes cannot contain null entries auth_notification_modes_duplicate: summary: auth.data.notification_modes contains duplicates value: code: auth_notification_modes_duplicate type: validation_error message: auth.data.notification_modes must not contain duplicates responses: Response401: description: Unauthorised - Invalid or missing authentication. content: application/json: schema: $ref: '#/components/schemas/StructuredErrorResponse' examples: invalidCredentials: summary: Invalid client credentials value: code: authentication_failed type: authentication_error message: Invalid client ID and client secret combination Response500: description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/StructuredErrorResponse' examples: internalError: summary: Internal server error value: code: internal_server_error type: internal_error message: An internal error occurred while processing the request securitySchemes: XClientID: type: apiKey in: header name: x-client-id description: >- Your unique client identifier issued by Cashfree. You can find this in your [Merchant Dashboard](https://merchant.cashfree.com/merchants/landing?env=prod). XClientSecret: type: apiKey in: header name: x-client-secret description: >- The secret key associated with your client ID. Use this to authenticate your API requests. You can find this in your [Merchant Dashboard](https://merchant.cashfree.com/merchants/landing?env=prod). ````