> ## Documentation Index
> Fetch the complete documentation index at: https://developer.tazapay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Update Beneficiary

> This lets you update an existing beneficiary

## **For beneficiaries having successful payouts, the following information cannot be updated**

* Type (business or individual)
* Beneficiary Name
* Account Number / IBAN
* Country
* Existing Bank Codes (SWIFT, IFSC, BSB\_CODE, ABA\_CODE, etc.). Additional bank codes can be added.

  **In these scenarios, you can create a new beneficiary with the updated details.**


## OpenAPI

````yaml put /v3/beneficiary/{id}
openapi: 3.1.0
info:
  title: sandbox
  version: '3'
servers:
  - url: https://service-sandbox.tazapay.com
security:
  - sec0: []
paths:
  /v3/beneficiary/{id}:
    put:
      summary: Update Beneficiary
      description: This lets you update an existing beneficiary
      operationId: update-beneficiary
      parameters:
        - name: id
          in: path
          description: ID of the exisitng beneficiary
          schema:
            type: string
          required: true
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Beneficiary Name
                  maxLength: 140
                type:
                  type: string
                  description: business or individual
                address:
                  $ref: '#/components/schemas/Address'
                phone:
                  $ref: '#/components/schemas/Phone'
                destination_details:
                  $ref: '#/components/schemas/DestinationDetails'
                metadata:
                  type: string
                  description: Set of key-value pairs to attach to the beneficiary
                  format: json
                tax_id:
                  type: string
                  description: >-
                    Tax ID of the beneficiary. (CPF or CPNJ is mandatory for
                    payouts to Brazil)
                documents:
                  type: object
                  description: Documents for the beneficiary
                  properties:
                    type:
                      type: string
                      description: >-
                        A string mentioning the type of document (example -
                        shareholding_pattern)
                    url:
                      type: string
                      description: Dynamically Downloadable URL
                national_identification_number:
                  type: string
                  description: National ID of the individual
            examples:
              Request Example:
                value:
                  metadata:
                    key1: value1
                    key2: value2
      responses:
        '200':
          description: '200'
          content:
            application/json:
              examples:
                Result:
                  value: '{}'
              schema:
                type: object
                description: >-
                  Represents a payout beneficiary with personal, contact, and
                  destination details.
                properties:
                  address:
                    $ref: '#/components/schemas/Address'
                  date_of_birth:
                    type: string
                    description: Date of birth of the beneficiary in YYYY-MM-DD format.
                  nationality:
                    type: string
                    description: >-
                      ISO 3166-1 alpha-2 country code representing the
                      beneficiary's nationality. Optional field used for
                      enhanced compliance screening. Sending this field will
                      reduce compliance hold.
                  destination:
                    type: string
                    description: >-
                      Identifier or reference to the beneficiary's payment
                      destination (bank account, wallet, etc.).
                  destination_details:
                    $ref: '#/components/schemas/DestinationDetails'
                  documents:
                    type: array
                    description: >-
                      List of documents associated with the beneficiary (e.g.,
                      ID proof, address proof).
                    items:
                      type: object
                  email:
                    type: string
                    description: Email address of the beneficiary.
                  name:
                    type: string
                    description: Full name of the beneficiary.
                  name_local:
                    type: string
                    description: >-
                      Local language representation of the beneficiary's name,
                      if applicable.
                  national_identification_number:
                    type: string
                    description: National identification number or equivalent ID.
                  party_classification:
                    type: string
                    description: >-
                      Classification of the beneficiary. Possible Values -
                      'self', 'third_party'.
                  phone:
                    $ref: '#/components/schemas/Phone'
                  registration_number:
                    type: string
                    description: >-
                      Registration or incorporation number for business
                      beneficiaries.
                  tax_id:
                    type: string
                    description: Tax identification number for the beneficiary.
                  type:
                    type: string
                    description: >-
                      Specifies whether the beneficiary is an 'individual' or a
                      'business'.
        '400':
          description: Bad Request
          content:
            application/json:
              examples:
                Result:
                  value: '{}'
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      deprecated: false
components:
  schemas:
    Address:
      type: object
      description: Address details
      properties:
        line1:
          type: string
          description: Address Line 1
        line2:
          type: string
          description: Address Line 2
        city:
          type: string
          description: Address city
        state:
          type: string
          description: Address state
        country:
          type: string
          description: Address country (ISO 3166-1 alpha-2 country code)
        postal_code:
          type: string
          description: Postal Code
    Phone:
      type: object
      description: Phone contact details
      properties:
        calling_code:
          type: string
          description: >-
            Calling country code (for example, '1' for United States, '91' for
            India)
        number:
          type: string
          description: Phone Number
    DestinationDetails:
      type: object
      description: >-
        Destination details for beneficiary payouts (discriminated union based
        on type)
      required:
        - type
      properties:
        type:
          type: string
          description: Type of destination
          enum:
            - bank
            - wallet
            - local_payment_network
            - tazapay_account
        bank:
          $ref: '#/components/schemas/Bank'
        wallet:
          $ref: '#/components/schemas/Wallet'
        local_payment_network:
          $ref: '#/components/schemas/LocalPaymentNetwork'
        tazapay_account:
          $ref: '#/components/schemas/TazapayAccount'
    ErrorResponse:
      type: object
      description: Standard error response structure
      properties:
        status:
          type: string
          enum:
            - error
          description: Always 'error' for error responses
        message:
          type: string
          description: High-level error message
        errors:
          type: array
          description: Array of detailed error objects
          items:
            type: object
            properties:
              code:
                type: integer
                description: Specific error code
              message:
                type: string
                description: Detailed error message
              remarks:
                type: string
                description: Additional context or suggestions for resolution
    Bank:
      type: object
      description: Bank account details
      properties:
        account_number:
          type: string
          description: Bank Account Number. Either account_number or IBAN is mandatory
        iban:
          type: string
          description: IBAN. Either account_number or iban is mandatory
        bank_name:
          type: string
          description: Name of the bank
        branch_name:
          type: string
          description: Name of the branch
        country:
          type: string
          description: Two-letter country code (ISO 3166-1 alpha-2)
        currency:
          type: string
          description: Three-letter ISO currency code, in uppercase
        purpose_code:
          type: string
          description: Purpose Code for INR bank accounts
        bank_codes:
          $ref: '#/components/schemas/BankCodes'
        firc_required:
          type: boolean
          description: Pass true if you want FIRC for a payout to India
        account_type:
          type: string
          description: Type of bank account
          enum:
            - savings
            - checking
            - payment
        account_holder_name:
          type: string
          description: Name of the account holder
        transfer_type:
          type: string
          description: Type of transfer (e.g., local, SWIFT)
    Wallet:
      type: object
      description: Crypto wallet destination details
      required:
        - deposit_address
        - type
        - currency
      properties:
        deposit_address:
          type: string
          description: Blockchain wallet address
        type:
          type: string
          description: >-
            Type of blockchain wallet (e.g., ethereum,
            bitcoin_lightning_network). Use `bitcoin_lightning_network` for BTC
            currency only.
          enum:
            - ethereum
            - tron
            - polygon
            - solana
            - bitcoin_lightning_network
        currency:
          type: string
          description: Cryptocurrency code (e.g., USDC, BTC, ETH)
        hosted:
          type: string
          description: Whether wallet is hosted/custodial
          enum:
            - 'yes'
            - 'no'
        vasp_name:
          type: string
          description: Virtual Asset Service Provider name (required for hosted wallets)
        vasp_website:
          type: string
          description: VASP website URL (required for hosted wallets)
    LocalPaymentNetwork:
      type: object
      description: Local payment network destination details (e.g., PIX, UPI, PromptPay)
      required:
        - type
        - deposit_key
      properties:
        type:
          type: string
          description: >-
            Type of local payment network (e.g., pix_brl, upi_inr,
            promptpay_thb)
        deposit_key_type:
          type: string
          description: >-
            Type of the deposit key (conditionally mandatory depending on
            network type)
        deposit_key:
          type: string
          description: >-
            Deposit key for the local payment network (e.g., PIX key, UPI
            handle)
        currency:
          type: string
          description: Currency code for the local payment network
    TazapayAccount:
      type: object
      description: Tazapay account destination details
      required:
        - deposit_address
      properties:
        deposit_address:
          type: string
          description: Tazapay account deposit address (format - xxxxx@tzp)
    BankCodes:
      type: object
      description: Bank specific identification codes
      properties:
        swift_code:
          type: string
          description: SWIFT Code
        bic_code:
          type: string
          description: Bank Identifier Code (BIC)
        ifsc_code:
          type: string
          description: IFS Code
        aba_code:
          type: string
          description: ABA / Routing Number
        sort_code:
          type: string
          description: SORT Code
        branch_code:
          type: string
          description: Branch Code
        bsb_code:
          type: string
          description: BSB Code
        bank_code:
          type: string
          description: Bank Code
        cnaps:
          type: string
          description: CNAPS
  securitySchemes:
    sec0:
      type: http
      scheme: basic

````