> ## 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. # Create 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. 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. | 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. ## OpenAPI ````yaml /openapi/ppi/ppi.yaml post /ppi/wallet 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: post: tags: - Wallet Management summary: Create Wallet description: > 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. operationId: createOrManageWallet parameters: - $ref: '#/components/parameters/global_x_api_version' requestBody: $ref: '#/components/requestBodies/WalletRequest' responses: '200': $ref: '#/components/responses/WalletResponse' '400': description: Bad request - Invalid input parameters. content: application/json: schema: $ref: '#/components/schemas/StructuredErrorResponse' examples: program_id_missing: summary: Program ID missing value: code: program_id_missing type: validation_error message: cf_program_id parameter is missing user_id_missing: summary: User ID missing value: code: user_id_missing type: validation_error message: user_id parameter is missing wallet_id_missing: summary: Wallet ID missing value: code: wallet_id_missing type: validation_error message: wallet_id parameter is missing 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 '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 - Program not found for subsequent operations. content: application/json: schema: $ref: '#/components/schemas/StructuredErrorResponse' examples: programNotFound: summary: Program not found value: code: program_not_found type: validation_error message: The specified cf_program_id does not exist '409': description: Conflict - Duplicate request. content: application/json: schema: $ref: '#/components/schemas/StructuredErrorResponse' examples: duplicateWallet: summary: Wallet already exists value: code: wallet_already_exists type: validation_error message: >- Wallet with the same cf_program_id already exists for the user duplicateWalletID: summary: Wallet Id already exists value: code: wallet_id_already_exists type: validation_error message: Wallet with the same wallet_id already exists for the user '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: WalletRequest: description: >- Request parameters to create a primary wallet and associated sub-wallets for a user. required: true content: application/json: schema: $ref: '#/components/schemas/WalletRequest' examples: createWallet: summary: Create wallet request value: user_id: USER827364 cf_program_id: '9876543210987654321' wallet_id: WALLET936721 createWalletWithCard: summary: Create wallet with card request value: user_id: USER827364 card_id: CARDR827364 wallet_id: WALLET936721 cf_program_id: '9876543210987654322' responses: WalletResponse: description: Success response for creating a wallet. content: application/json: schema: $ref: '#/components/schemas/WalletResponse' examples: SUCCESS_WALLET: summary: Successful GIFT_WALLET creation value: user_id: USER827364 cf_program_id: '9876543210987654321' wallet_id: WALLET936721 cf_wallet_id: '1234567890123456783' wallet_name: Gift Wallet sub_wallets: - cf_sub_wallet_id: '35246543210987654321' name: Gift Wallet type: GIFT_PPI status: ACTIVE balance: 0 available_balance: 0 funds_on_hold: 0 - cf_sub_wallet_id: '54252453468535350356' name: Closed Wallet type: CLOSED_LOOP_PPI status: ACTIVE balance: 0 available_balance: 0 funds_on_hold: 0 SUCCESS_WALLET_HAVING_CARD: summary: Successful wallet creation with card details value: user_id: USER827364 cf_program_id: '9876543210987654322' wallet_id: WALLET936721 cf_wallet_id: '1410908340658724864' wallet_name: Cashfree Pay sub_wallets: - cf_sub_wallet_id: '1410908340658724865' name: Cashfree Pay type: STANDARD_PPI status: ACTIVE balance: 0 available_balance: 0 funds_on_hold: 0 - cf_sub_wallet_id: '1410908340662919168' name: Fuel Wallet type: STANDARD_PPI status: ACTIVE balance: 0 available_balance: 0 funds_on_hold: 0 card: card_name: Corporate Card card_id: CARDR827364 cf_card_id: '1410908340461592576' masked_card_number: XXXXXXXXXXXX0185 name_on_card: John Doe card_holder_name: John Doe card_network: RUPAY status: ACTIVE 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 schemas: 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 WalletRequest: type: object required: - user_id - cf_program_id - wallet_id properties: user_id: type: string description: >- Unique identifier for the user, as provided by you during PPI user creation. example: USER827364 minLength: 1 maxLength: 50 cf_program_id: type: string description: >- Unique identifier of the PPI program, provided by Cashfree. Use this to specify the program configuration when creating a wallet. If the provided `cf_program_id` is associated with a card program, then `card_id` is also required in the request. In such cases, the card is linked to the wallet during creation. example: '9876543210987654321' minLength: 1 maxLength: 50 wallet_id: type: string description: >- Unique identifier that you create to identify the wallet in your system. Maximum 50 characters. Only alphanumeric characters, periods (.), hyphens (-), and underscores (_) are allowed. example: WALLET936721 minLength: 1 maxLength: 50 card_id: type: string description: >- Unique identifier for the card in your system. Maximum 50 characters. Only alphanumeric characters, periods (.), hyphens (-), and underscores (_) are allowed. Required if the cf_program_id is linked to a card program. The card is associated with the wallet when the wallet is created. example: CARDR827364 minLength: 1 maxLength: 50 example: user_id: USER827364 cf_program_id: '9876543210987654321' wallet_id: WALLET936721 WalletResponse: type: object properties: user_id: type: string description: >- Unique identifier for the user, as provided by you during PPI user creation. example: USER827364 cf_program_id: type: string description: >- Unique identifier of the PPI program associated with the wallet, as provided by Cashfree. example: '9876543210987654321' wallet_id: type: string description: >- Unique identifier for the wallet, as provided by you during wallet creation. example: WALLET936721 cf_wallet_id: type: string description: >- Unique identifier for the wallet, automatically generated by Cashfree after successful wallet creation. example: '1234567890123456783' wallet_name: type: string description: Name of the wallet. example: Gift Wallet sub_wallets: type: array description: List of sub-wallets created for this wallet. items: 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: 0 available_balance: type: number format: double description: Available balance in the sub-wallet. example: 0 funds_on_hold: type: number format: double description: Funds on hold in the sub-wallet. example: 0 card: $ref: '#/components/schemas/WalletCardDetails' WalletCardDetails: type: object description: Card details associated with the wallet, if a card exists. properties: card_name: type: string description: Name of the card. example: Cashfree Pay card_id: type: string description: >- Unique identifier for the card, as provided by you during card creation. example: CARDR827364 cf_card_id: type: string description: Unique identifier for the card, generated by Cashfree. example: '1410908340461592576' masked_card_number: type: string description: Masked card number. example: XXXXXXXXXXXX0185 name_on_card: type: string description: Name printed on the card. example: John Doe card_holder_name: type: string description: Name of the cardholder. example: John Doe card_network: type: string description: Card network. example: RUPAY status: type: string description: | Status of the card: - `ACTIVE`: Card is active and can be used for transactions. - `LOCKED`: Card is locked and cannot be used for transactions. enum: - ACTIVE - LOCKED example: ACTIVE 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). ````