> ## 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 Beneficiary > 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. ## OpenAPI ````yaml /openapi/ppi/ppi.yaml post /ppi/user/bene 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/user/bene: post: tags: - Beneficiary Management summary: Create Beneficiary description: > 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. operationId: createPPIBeneficiary parameters: - $ref: '#/components/parameters/global_x_api_version' requestBody: description: Request parameters to create a beneficiary for a user. required: true content: application/json: schema: $ref: '#/components/schemas/CreateBeneRequest' examples: SUCCESS: summary: Request with multiple instrument types value: bene_id: BENE28448 user_id: USER827364 bene_first_name: John bene_last_name: Doe bene_instruments: - bene_instrument_id: INST194947 type: BANK_ACCOUNT bank_account_number: '1234567890' ifsc: HDFC0001234 - bene_instrument_id: INST194948 type: VPA vpa: example@upi bene_contact_details: email: john.doe@example.com phone: '9876543210' dob: '1990-05-12' gender: MALE address: No. 123, 5th Main, Indiranagar city: Bangalore state: Karnataka pincode: '560038' country: India purpose: Family notes: example_key_1: example_value_1 example_key_2: example_value_2 responses: '200': description: Success response for creating a beneficiary. content: application/json: schema: $ref: '#/components/schemas/CreateBeneResponse' examples: SUCCESS: summary: Beneficiary created successfully value: bene_id: BENE28448 cf_bene_id: '473974924929' user_id: USER827364 bene_first_name: John bene_last_name: Doe status: ACTIVE bene_instruments: - bene_instrument_id: INST194947 type: BANK_ACCOUNT bank_bank_account_number: '3749378903' ifsc: HDFC0001234 status: ACTIVE verification_status: PENDING cf_bene_instrument_id: '8324782642946' - bene_instrument_id: INST194948 type: VPA vpa: example@upi status: ACTIVE verification_status: PENDING cf_bene_instrument_id: '8324782642947' bene_contact_details: email: john.doe@example.com phone: '9876543210' dob: '1990-05-12' gender: MALE address: No. 123, 5th Main, Indiranagar city: Bangalore state: Karnataka pincode: '560038' country: India purpose: Family notes: example_key_1: example_value_1 example_key_2: example_value_2 '400': description: Bad request - Invalid input parameters. content: application/json: schema: $ref: '#/components/schemas/StructuredErrorResponse' examples: userIdMissing: summary: user ID missing value: message: user id is missing code: user_id_missing type: validation_error beneIdMissing: summary: Beneficiary ID missing value: message: bene id is missing code: bene_id_missing type: validation_error beneFirstNameMissing: summary: Beneficiary first name missing value: message: bene first name is missing code: bene_first_name_missing type: validation_error instrumentsEmpty: summary: '`bene_instruments` array is empty' value: message: at least one instrument is required code: instruments_empty type: validation_error vpaMissing: summary: VPA details missing value: message: vpa is required for VPA instrument type code: vpa_missing type: validation_error bankAccountMissing: summary: Bank account details missing value: message: >- bank_account_number is required for BANK_ACCOUNT instrument type code: bank_account_details_missing type: validation_error ifscCodeMissing: summary: IFSC code missing value: message: ifsc is required for BANK_ACCOUNT instrument type code: ifsc_missing type: validation_error invalidPhone: summary: invalid phone format value: message: phone format is invalid code: phone_invalid type: validation_error invalidEmail: summary: invalid email format value: message: email format is invalid code: email_invalid type: validation_error invalidIfsc: summary: invalid IFSC code value: message: ifsc is invalid code: ifsc_invalid type: validation_error invalidBankAccountNumber: summary: invalid bank account number value: message: bank_bank_account_number is invalid code: bank_bank_account_number_invalid type: validation_error invalidVpa: summary: invalid VPA format value: message: vpa format is invalid code: vpa_invalid type: validation_error subWalletNotFound: summary: Sub wallet not found value: message: specified cf_sub_wallet_id does not exist code: sub_wallet_not_found type: validation_error 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': $ref: '#/components/responses/Response403' '404': description: Bad request - Invalid User ID. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid_user_id: summary: user_id not found value: code: user_id_not_found type: invalid_request_error message: The user_id with given id not found '409': description: Conflict - Beneficiary or instrument already exists. content: application/json: schema: $ref: '#/components/schemas/StructuredErrorResponse' examples: duplicateBene: summary: Beneficiary Id already exists value: code: bene_id_already_exists type: validation_error message: Beneficiary with the same bene_id already exists duplicateInstrument: summary: Instrument Id already exists value: code: instrument_id_already_exists type: validation_error message: Instrument with the same bene_instrument_id already exists duplicateInstrumentDetails: summary: Instrument details already exist value: code: instrument_already_exists type: validation_error message: >- Instrument with the same details already exists for this beneficiary '429': $ref: '#/components/responses/Response429' '500': $ref: '#/components/responses/Response500' security: - XClientID: [] XClientSecret: [] 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' schemas: CreateBeneRequest: type: object required: - bene_id - user_id - bene_instruments - bene_first_name properties: bene_id: type: string minLength: 1 maxLength: 50 description: >- Unique identifier that you create to identify the beneficiary in your system. Maximum 50 characters. Only alphanumeric characters, periods (.), hyphens (-), and underscores (_) are allowed. example: BENE28448 user_id: type: string description: >- Unique identifier for the user, as provided by you during PPI user creation. example: USER827364 minLength: 1 maxLength: 50 bene_first_name: type: string minLength: 1 maxLength: 100 description: First name of the beneficiary. example: John bene_last_name: type: string minLength: 1 maxLength: 100 description: Last name of the beneficiary. example: Doe bene_instruments: type: array description: List of payment `bene_instruments` for the beneficiary. items: oneOf: - title: Bank Account type: object required: - bene_instrument_id - type - bank_account_number - ifsc properties: bene_instrument_id: type: string minLength: 1 maxLength: 50 description: >- Unique identifier that you create to identify the instrument in your system. Maximum 50 characters. Only alphanumeric characters, periods (.), hyphens (-), and underscores (_) are allowed. example: INST194947 type: type: string description: Type of instrument. example: BANK_ACCOUNT bank_account_number: type: string description: >- It is the beneficiary bank account number. The value should be between 9 and 18 characters. Alphanumeric characters are allowed. example: '1234567890' ifsc: type: string description: >- It is the IFSC information of the beneficiary's bank account in the standard IFSC format. The value should be 11 characters. (The first 4 characters should be alphabets, the 5th character should be a 0, and the remaining 6 characters should be numerals.) example: HDFC0001234 - title: VPA type: object required: - bene_instrument_id - type - vpa properties: bene_instrument_id: type: string minLength: 1 maxLength: 50 description: >- Unique identifier that you create to identify the instrument in your system. Maximum 50 characters. Only alphanumeric characters, periods (.), hyphens (-), and underscores (_) are allowed. example: INST194947 type: type: string description: Type of instrument. example: VPA vpa: type: string description: Virtual Payment Address (UPI ID). example: example@upi bene_contact_details: type: object description: Contact details of the beneficiary. properties: phone: type: string description: Phone number of the beneficiary. example: '9876543210' email: type: string description: Email address of the beneficiary. example: john.doe@example.com dob: type: string format: date description: Date of birth in YYYY-MM-DD format. example: '1990-05-12' gender: type: string enum: - MALE - FEMALE - OTHERS description: Gender of the beneficiary. example: MALE address: type: string description: Street address of the beneficiary. example: No. 123, 5th Main, Indiranagar city: type: string description: City of the beneficiary. example: Bangalore state: type: string description: State of the beneficiary. example: Karnataka pincode: type: string description: Pincode or ZIP code. example: '560038' country: type: string description: Country. example: India purpose: type: string description: Purpose of creating the beneficiary. example: Family notes: $ref: '#/components/schemas/Notes' CreateBeneResponse: type: object properties: bene_id: type: string description: >- Unique identifier for the beneficiary, as provided by you during beneficiary creation. example: BENE28448 cf_bene_id: type: string description: Cashfree-generated unique ID for the beneficiary. example: '473974924929' user_id: type: string description: >- Unique identifier for the user, as provided by you during PPI user creation. example: USER827364 bene_first_name: type: string description: First name of the beneficiary. example: John bene_last_name: type: string description: Last name of the beneficiary. example: Doe status: type: string description: Status of the beneficiary. example: ACTIVE bene_instruments: type: array description: List of payment `bene_instruments` for the beneficiary. items: oneOf: - title: Bank Account type: object properties: bene_instrument_id: type: string description: >- Unique identifier for the instrument, as provided by you during beneficiary creation. example: INST194947 type: type: string description: Type of instrument. example: BANK_ACCOUNT bank_bank_account_number: type: string description: Masked bank account number. example: '3749378903' ifsc: type: string description: IFSC code of the bank branch. example: HDFC0001234 status: type: string description: > Status of the instrument. Supported values: - ACTIVE : The instrument is authorised to perform transactions. - INACTIVE : The instrument is not authorised to perform transactions. - INVALID : Beneficiary Instrument is invalid. - BLOCKED : The instrument is restricted from performing any transactions. verification_status: type: string description: > Verification status of the instrument. Supported values: - PENDING : The verification is currently is pending. - VERIFIED : The instrument has been successfully verified. - FAILED : The verification has failed. cf_bene_instrument_id: type: string description: Cashfree-generated unique ID for the instrument. example: '8324782642946' - title: VPA type: object properties: bene_instrument_id: type: string description: >- Unique identifier for the instrument, as provided by you during beneficiary creation. example: INST194947 type: type: string description: Type of instrument. example: VPA vpa: type: string description: Virtual Payment Address (UPI ID). example: example@upi status: type: string description: > Status of the instrument. Supported values: - ACTIVE : The instrument is authorised to perform transactions. - INACTIVE : The instrument is not authorised to perform transactions. - INVALID : The instrument is invalid. - BLOCKED : The instrument is restricted from performing any transactions. verification_status: type: string description: > Verification status of the instrument. Supported values: - INITIATED : The verification is currently is initiated.. - VERIFIED : The instrument has been successfully verified. - FAILED : The verification has failed. cf_bene_instrument_id: type: string description: Cashfree-generated unique ID for the instrument. example: '8324782642946' bene_contact_details: type: object description: >- Contact details of the beneficiary. Only not null fields will be returned. properties: email: type: string description: Email address of the beneficiary. example: john.doe@example.com phone: type: string description: Phone number of the beneficiary. example: '9876543210' dob: type: string format: date description: Date of birth in YYYY-MM-DD format. example: '1990-05-12' gender: type: string enum: - MALE - FEMALE - OTHERS description: Gender of the beneficiary. example: MALE address: type: string description: Street address of the beneficiary. example: No. 123, 5th Main, Indiranagar city: type: string description: City of the beneficiary. example: Bangalore state: type: string description: State of the beneficiary. example: Karnataka pincode: type: string description: Pincode or ZIP code. example: '560038' country: type: string description: Country. example: India purpose: type: string example: Family notes: $ref: '#/components/schemas/Notes' 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 ErrorResponse: type: object properties: code: type: string description: Specific error code identifier. example: invalid_parameter_value type: type: string description: Error type or category. example: validation_error message: type: string description: Human-readable error message. example: Invalid request parameter value provided occurred_at: type: string format: date-time description: Timestamp when the error occurred. example: '2025-05-01T12:00:00Z' details: type: object nullable: true description: Additional error details. additionalProperties: type: string Notes: type: object description: >- Optional key-value pairs for any extra information. Keys and values must be strings. properties: example_key: type: string description: value of the note example: example_value 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 Response403: 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) Response429: description: Too Many Requests - Rate limit exceeded. content: application/json: schema: $ref: '#/components/schemas/StructuredErrorResponse' examples: internalError: summary: Internal server error value: code: too_many_requests_per_operation type: rate_limit_error message: Rate limit exceeded. Please try again after some time 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). ````