> ## Documentation Index
> Fetch the complete documentation index at: https://api-reference.hyperswitch.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Payments - Update Metadata



## OpenAPI

````yaml post /payments/{payment_id}/update_metadata
openapi: 3.0.3
info:
  title: Hyperswitch - API Documentation
  description: >

    ## Get started


    Hyperswitch provides a collection of APIs that enable you to process and
    manage payments.

    Our APIs accept and return JSON in the HTTP body, and return standard HTTP
    response codes.


    You can consume the APIs directly using your favorite HTTP/REST library.


    We have a testing environment referred to "sandbox", which you can setup to
    test API calls without

    affecting production data.

    Currently, our sandbox environment is live while our production environment
    is under development

    and will be available soon.

    You can sign up on our Dashboard to get API keys to access Hyperswitch API.


    ### Environment


    Use the following base URLs when making requests to the APIs:


    | Environment   |  Base URL                          |

    |---------------|------------------------------------|

    | Sandbox       | <https://sandbox.hyperswitch.io>   |

    | Production    | <https://api.hyperswitch.io>       |


    ## Authentication


    When you sign up on our [dashboard](https://app.hyperswitch.io) and create a
    merchant

    account, you are given a secret key (also referred as api-key) and a
    publishable key.

    You may authenticate all API requests with Hyperswitch server by providing
    the appropriate key in

    the request Authorization header.


    | Key             | 
    Description                                                                                 
    |

    |-----------------|-----------------------------------------------------------------------------------------------|

    | api-key         | Private key. Used to authenticate all API requests from
    your merchant server                  |

    | publishable key | Unique identifier for your account. Used to authenticate
    API requests from your app's client  |


    Never share your secret api keys. Keep them guarded and secure.
  contact:
    name: Hyperswitch Support
    url: https://hyperswitch.io
    email: support.global@juspay.io
  license:
    name: Apache-2.0
  version: 0.1.0
servers:
  - url: https://sandbox.hyperswitch.io
    description: Sandbox Environment
security: []
tags:
  - name: Merchant Account
    description: Create and manage merchant accounts
  - name: Profile
    description: Create and manage profiles
  - name: Merchant Connector Account
    description: Create and manage merchant connector accounts
  - name: Payments
    description: Create and manage one-time payments, recurring payments and mandates
  - name: Refunds
    description: Create and manage refunds for successful payments
  - name: Mandates
    description: Manage mandates
  - name: Customers
    description: Create and manage customers
  - name: Payment Methods
    description: Create and manage payment methods of customers
  - name: Disputes
    description: Manage disputes
  - name: API Key
    description: Create and manage API Keys
  - name: Payouts
    description: Create and manage payouts
  - name: payment link
    description: Create payment link
  - name: Routing
    description: Create and manage routing configurations
  - name: Event
    description: Manage events
  - name: Authentication
    description: Create and manage authentication
  - name: Subscriptions
    description: Subscription management and billing endpoints
  - name: Card Issuer
    description: Create and manage card issuers
paths:
  /payments/{payment_id}/update_metadata:
    post:
      tags:
        - Payments
      summary: Payments - Update Metadata
      operationId: Update Metadata for a Payment
      parameters:
        - name: payment_id
          in: path
          description: The identifier for payment
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentsUpdateMetadataRequest'
        required: true
      responses:
        '200':
          description: Metadata updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentsUpdateMetadataResponse'
        '400':
          description: Missing mandatory fields
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericErrorResponseOpenApi'
      security:
        - api_key: []
components:
  schemas:
    PaymentsUpdateMetadataRequest:
      type: object
      required:
        - metadata
      properties:
        metadata:
          type: object
          description: >-
            Metadata is useful for storing additional, unstructured information
            on an object.
        feature_metadata:
          allOf:
            - $ref: '#/components/schemas/FeatureMetadata'
          nullable: true
      additionalProperties: false
    PaymentsUpdateMetadataResponse:
      type: object
      required:
        - payment_id
      properties:
        payment_id:
          type: string
          description: The identifier for the payment
        metadata:
          type: object
          description: >-
            Metadata is useful for storing additional, unstructured information
            on an object.
          nullable: true
        status:
          allOf:
            - $ref: '#/components/schemas/IntentStatus'
          default: requires_confirmation
          nullable: true
        feature_metadata:
          allOf:
            - $ref: '#/components/schemas/FeatureMetadata'
          nullable: true
    GenericErrorResponseOpenApi:
      type: object
      required:
        - error_type
        - message
        - code
      properties:
        error_type:
          type: string
          example: invalid_request
        message:
          type: string
          example: 'Missing required param: {param}'
        code:
          type: string
          example: IR_04
    FeatureMetadata:
      type: object
      description: additional data that might be required by hyperswitch
      properties:
        redirect_response:
          allOf:
            - $ref: '#/components/schemas/RedirectResponse'
          nullable: true
        search_tags:
          type: array
          items:
            type: string
          description: Additional tags to be used for global search
          nullable: true
        apple_pay_recurring_details:
          allOf:
            - $ref: '#/components/schemas/ApplePayRecurringDetails'
          nullable: true
        pix_additional_details:
          allOf:
            - $ref: '#/components/schemas/PixAdditionalDetails'
          nullable: true
        boleto_additional_details:
          allOf:
            - $ref: '#/components/schemas/BoletoAdditionalDetails'
          nullable: true
        pix_automatico_additional_details:
          allOf:
            - $ref: '#/components/schemas/PixAutomaticoAdditionalDetails'
          nullable: true
        finix_additional_details:
          allOf:
            - $ref: '#/components/schemas/FinixAdditionalDetails'
          nullable: true
    IntentStatus:
      type: string
      description: >-
        Represents the overall status of a payment intent.

        The status transitions through various states depending on the payment
        method, confirmation, capture method, and any subsequent actions (like
        customer authentication or manual capture).
      enum:
        - succeeded
        - failed
        - cancelled
        - cancelled_post_capture
        - processing
        - requires_customer_action
        - requires_merchant_action
        - requires_payment_method
        - requires_confirmation
        - requires_capture
        - partially_captured
        - partially_captured_and_capturable
        - partially_authorized_and_requires_capture
        - partially_captured_and_processing
        - conflicted
        - expired
        - review
    RedirectResponse:
      type: object
      properties:
        param:
          type: string
          nullable: true
        json_payload:
          type: object
          nullable: true
    ApplePayRecurringDetails:
      type: object
      required:
        - payment_description
        - regular_billing
        - management_url
      properties:
        payment_description:
          type: string
          description: >-
            A description of the recurring payment that Apple Pay displays to
            the user in the payment sheet
        regular_billing:
          $ref: '#/components/schemas/ApplePayRegularBillingDetails'
        billing_agreement:
          type: string
          description: >-
            A localized billing agreement that the payment sheet displays to the
            user before the user authorizes the payment
          nullable: true
        management_url:
          type: string
          description: >-
            A URL to a web page where the user can update or delete the payment
            method for the recurring payment
          example: https://hyperswitch.io
    PixAdditionalDetails:
      oneOf:
        - type: object
          required:
            - immediate
          properties:
            immediate:
              $ref: '#/components/schemas/ImmediateExpirationTime'
        - type: object
          required:
            - scheduled
          properties:
            scheduled:
              $ref: '#/components/schemas/ScheduledExpirationTime'
    BoletoAdditionalDetails:
      type: object
      properties:
        due_date:
          type: string
          description: Due Date for the Boleto
          example: '2026-12-31'
          nullable: true
        document_kind:
          allOf:
            - $ref: '#/components/schemas/BoletoDocumentKind'
          nullable: true
        payment_type:
          allOf:
            - $ref: '#/components/schemas/BoletoPaymentType'
          nullable: true
        covenant_code:
          type: string
          example: '3568253'
          nullable: true
        pix_key:
          allOf:
            - $ref: '#/components/schemas/PixKey'
          nullable: true
        discount_rules:
          allOf:
            - $ref: '#/components/schemas/SantanderPaymentDiscountRules'
          nullable: true
        penalties:
          allOf:
            - $ref: '#/components/schemas/PenaltyRules'
          nullable: true
        collection_actions:
          allOf:
            - $ref: '#/components/schemas/CollectionActions'
          nullable: true
        payment_constraints:
          allOf:
            - $ref: '#/components/schemas/BoletoPaymentTypeConstraints'
          nullable: true
        beneficiary:
          allOf:
            - $ref: '#/components/schemas/BeneficiaryDetails'
          nullable: true
    PixAutomaticoAdditionalDetails:
      oneOf:
        - allOf:
            - $ref: '#/components/schemas/PixAutomaticoPushData'
            - type: object
              required:
                - type
              properties:
                type:
                  type: string
                  enum:
                    - pix_automatico_push
        - allOf:
            - $ref: '#/components/schemas/PixAutomaticoQrData'
            - type: object
              required:
                - type
              properties:
                type:
                  type: string
                  enum:
                    - pix_automatico_qr
        - allOf:
            - $ref: '#/components/schemas/PixAutomaticoMitData'
            - type: object
              required:
                - type
              properties:
                type:
                  type: string
                  enum:
                    - pix_automatico_mit
      description: >-
        Represents the specific data for Santander Pix Automatico (recurring PIX
        payments)

        Split into CIT (Customer Initiated Transaction) and MIT (Merchant
        Initiated Transaction) variants
      discriminator:
        propertyName: type
    FinixAdditionalDetails:
      type: object
      properties:
        fraud_session_id:
          type: string
          description: The fraud session ID used for Finix fraud detection
          example: 1234567890abcdef
          nullable: true
    ApplePayRegularBillingDetails:
      type: object
      required:
        - label
      properties:
        label:
          type: string
          description: >-
            The label that Apple Pay displays to the user in the payment sheet
            with the recurring details
        recurring_payment_start_date:
          type: string
          format: date-time
          description: The date of the first payment
          example: '2023-09-10T23:59:59Z'
          nullable: true
        recurring_payment_end_date:
          type: string
          format: date-time
          description: The date of the final payment
          example: '2023-09-10T23:59:59Z'
          nullable: true
        recurring_payment_interval_unit:
          allOf:
            - $ref: '#/components/schemas/RecurringPaymentIntervalUnit'
          nullable: true
        recurring_payment_interval_count:
          type: integer
          format: int32
          description: The number of interval units that make up the total payment interval
          nullable: true
    ImmediateExpirationTime:
      type: object
      required:
        - time
      properties:
        time:
          type: integer
          format: int32
          description: Expiration time in seconds
          minimum: 0
        pix_key:
          allOf:
            - $ref: '#/components/schemas/PixKey'
          nullable: true
    ScheduledExpirationTime:
      type: object
      required:
        - date
      properties:
        date:
          type: string
          description: 'Expiration time in terms of date, format: YYYY-MM-DD'
          example: '2026-07-08'
        validity_after_expiration:
          type: integer
          format: int32
          description: Days after expiration date for which the QR code remains valid
          example: 10
          nullable: true
          minimum: 0
        pix_key:
          allOf:
            - $ref: '#/components/schemas/PixKey'
          nullable: true
    BoletoDocumentKind:
      type: string
      enum:
        - commercial_invoice
        - service_invoice
        - promissory_note
        - rural_promissory_note
        - receipt
        - insurance_policy
        - credit_card_invoice
        - proposal
        - deposit_or_funding
        - cheque
        - direct_promissory_note
        - other
    BoletoPaymentType:
      type: string
      enum:
        - fixed_amount
        - flexible_amount
        - installment
    PixKey:
      oneOf:
        - type: object
          required:
            - type
            - value
          properties:
            type:
              type: string
              enum:
                - cpf
            value:
              type: string
        - type: object
          required:
            - type
            - value
          properties:
            type:
              type: string
              enum:
                - cnpj
            value:
              type: string
        - type: object
          required:
            - type
            - value
          properties:
            type:
              type: string
              enum:
                - email
            value:
              type: string
        - type: object
          required:
            - type
            - value
          properties:
            type:
              type: string
              enum:
                - phone
            value:
              type: string
        - type: object
          required:
            - type
            - value
          properties:
            type:
              type: string
              enum:
                - evp_token
            value:
              type: string
      discriminator:
        propertyName: type
    SantanderPaymentDiscountRules:
      type: object
      description: >-
        Defines the type of discount applied to a payment, such as whether it's
        a fixed date discount, a daily calendar discount, or a daily business
        discount.
      required:
        - tiers
      properties:
        discount_type:
          allOf:
            - $ref: '#/components/schemas/DiscountType'
          nullable: true
        tiers:
          type: array
          items:
            $ref: '#/components/schemas/DiscountTier'
          description: A generic vector of discount tiers
    PenaltyRules:
      type: object
      description: >-
        Represents the rules for applying discounts to a payment, such as a
        percentage discount or a fixed amount discount, along with any
        applicable grace periods.
      properties:
        fixed_penalty:
          allOf:
            - $ref: '#/components/schemas/PenaltyDetail'
          nullable: true
        interest:
          allOf:
            - $ref: '#/components/schemas/InterestDetail'
          nullable: true
    CollectionActions:
      type: object
      description: >-
        Represents the legal or administrative actions that may be taken for
        non-payment, such as protest rules and automatic write-off timelines.
      properties:
        legal_protest:
          allOf:
            - $ref: '#/components/schemas/ProtestRules'
          nullable: true
        auto_write_off_days:
          type: integer
          format: int32
          description: Days after which the bill is automatically cancelled/written off
          example: 60
          nullable: true
          minimum: 0
    BoletoPaymentTypeConstraints:
      oneOf:
        - type: object
          required:
            - type
          properties:
            type:
              type: string
              enum:
                - fixed_amount
        - type: object
          required:
            - type
            - details
          properties:
            type:
              type: string
              enum:
                - flexible_amount
            details:
              $ref: '#/components/schemas/FlexibleAmountDetails'
        - type: object
          required:
            - type
            - details
          properties:
            type:
              type: string
              enum:
                - installment
            details:
              $ref: '#/components/schemas/InstallmentDetails'
      description: >-
        Represents the rules for legal protest (official debt registration) for
        non-payment, including the type of protest and the number of days after
        which the protest is initiated.
      discriminator:
        propertyName: type
    BeneficiaryDetails:
      type: object
      description: Represents the end-recipient of a payout or fund transfer.
      properties:
        name:
          type: string
          description: The full legal name of the individual or entity receiving the funds.
          example: João da Silva
          nullable: true
        document_number:
          type: string
          description: >-
            The customer's unique identification number (e.g., Tax ID, SSN,
            Passport Number).

            Used by processors to verify the identity of the recipient and
            prevent fraud.

            Length of the document number depends upon the document_type.

            For CPF/CNPJ it is typically 11/14 digits long.
          example: '9615865832'
          nullable: true
        document_type:
          allOf:
            - $ref: '#/components/schemas/DocumentKind'
          nullable: true
    PixAutomaticoPushData:
      type: object
      description: >-
        Data for PixAutomaticoPush Payment Method Type CIT (Customer Initiated
        Transaction) - used during mandate setup
      required:
        - time
      properties:
        time:
          type: integer
          format: int32
          description: Time in seconds until which the push notification is valid
          example: 3600
          minimum: 0
        retry_policy:
          type: boolean
          description: >-
            Enable retry policy for failed payments (maps to PERMITE_3R_7D if
            true)
          example: true
          nullable: true
        mandate_details:
          allOf:
            - $ref: '#/components/schemas/SantanderMandateDetails'
          nullable: true
    PixAutomaticoQrData:
      type: object
      description: >-
        Data for PixAutomaticoQr Payment Method Type CIT (Customer Initiated
        Transaction) - used during mandate setup + non 0$ mandate setup
      properties:
        retry_policy:
          type: boolean
          description: >-
            Enable retry policy for failed payments (maps to PERMITE_3R_7D if
            true)
          example: true
          nullable: true
        mandate_details:
          allOf:
            - $ref: '#/components/schemas/SantanderMandateDetails'
          nullable: true
    PixAutomaticoMitData:
      type: object
      description: >-
        Data for Santander Pix Automatico MIT (Merchant Initiated Transaction) -
        used during recurring charge creation
      properties:
        receiver_details:
          allOf:
            - $ref: '#/components/schemas/SantanderPixAutomaticoReceiverDetails'
          nullable: true
        mandate_execution_date:
          type: string
          description: >-
            Execution date for the mandate charge (maps to data_de_vencimento).
            Format: YYYY-MM-DD.

            If not provided, defaults to current date + 1 day.
          example: '2026-12-31'
          nullable: true
        auto_adjust_date:
          type: boolean
          description: >-
            Whether to automatically adjust the due date to the next business
            day if it falls on a non-business day.

            Maps to ajuste_dia_util in Santander API. Defaults to true if not
            provided.
          example: true
          nullable: true
    RecurringPaymentIntervalUnit:
      type: string
      enum:
        - year
        - month
        - day
        - hour
        - minute
    DiscountType:
      type: string
      description: >-
        Defines the type of discount applied to a payment, such as whether it's
        a fixed date discount, a daily calendar discount, or a daily business
        discount.
      enum:
        - standard
        - fixed_date
        - daily_calendar
        - daily_business
    DiscountTier:
      type: object
      properties:
        amount:
          type: string
          description: The discount value (e.g., "5.50").
          example: '5.50'
          nullable: true
        end_date:
          type: string
          description: The ISO-8601 date until which this discount is valid
          example: '2027-12-31'
          nullable: true
    PenaltyDetail:
      type: object
      description: >-
        Represents the rules for applying discounts to a payment, such as a
        percentage discount or a fixed amount discount, along with any
        applicable grace periods.
      properties:
        value:
          type: string
          description: The numeric value (as a string to preserve decimal precision)
          example: '2.00'
          nullable: true
        grace_period_days:
          type: integer
          format: int32
          description: 'Grace period: Days after due date before this applies'
          example: 1
          nullable: true
          minimum: 0
    InterestDetail:
      type: object
      description: >-
        Represents the rules for applying discounts to a payment, such as a
        percentage discount or a fixed amount discount, along with any
        applicable grace periods.
      properties:
        interest_percentage:
          type: string
          description: 'Percentage of Juros (Interest). Pattern: ^[0-9]{1,3}\.[0-9]{2}$'
          example: '5.00'
          nullable: true
        iof_percentage:
          type: string
          description: |-
            Percentage of IOF (Financial Operations Tax). Pattern: \d{3}$\.\d{5}
            Only provided if the agreement is "Cobra IOF na Barra ou Cadastro"
          example: '32.45325'
          nullable: true
    ProtestRules:
      type: object
      required:
        - protest_type
        - days_after_due_date
      properties:
        protest_type:
          $ref: '#/components/schemas/ProtestType'
        days_after_due_date:
          type: integer
          format: int32
          description: Number of days after the due date to initiate the protest
          example: 30
          minimum: 0
    FlexibleAmountDetails:
      type: object
      description: >-
        Represents the rules for legal protest (official debt registration) for
        non-payment, including the type of protest and the number of days after
        which the protest is initiated.
      properties:
        min_value:
          type: string
          description: Minimum value allowed (e.g., "10.00")
          example: '38.02'
          nullable: true
        max_value:
          type: string
          description: Maximum value allowed (e.g., "5000.00")
          example: '38.02'
          nullable: true
        value_type:
          allOf:
            - $ref: '#/components/schemas/CalculationType'
          nullable: true
    InstallmentDetails:
      type: object
      description: >-
        Represents the rules for legal protest (official debt registration) for
        non-payment, including the type of protest and the number of days after
        which the protest is initiated.
      properties:
        max_partial_payments:
          type: integer
          format: int32
          description: Maximum number of partial payments allowed (Up to 99 for Santander).
          example: 99
          nullable: true
          minimum: 0
        value_type:
          allOf:
            - $ref: '#/components/schemas/CalculationType'
          nullable: true
    DocumentKind:
      type: string
      description: Represents the type of identification document used for validation.
      enum:
        - cpf
        - cnpj
        - psn
        - other
    SantanderMandateDetails:
      type: object
      properties:
        fixed_recurring_amount:
          type: integer
          format: int64
          description: >-
            Fixed amount for each recurring charge in minor units (e.g., cents).
            If not provided, the mandate will allow variable amounts.
          example: 6540
          nullable: true
          minimum: 0
        min_recurring_amount:
          type: integer
          format: int64
          description: >-
            Minimum amount for each recurring charge in minor units (e.g.,
            cents). If not provided, there will be no minimum limit on the
            amount.
          example: 6540
          nullable: true
          minimum: 0
        start_date:
          type: string
          description: >-
            Start date for the recurring charges. Format: YYYY-MM-DD. If not
            provided, the mandate will be valid immediately.
          example: '2026-12-31'
          nullable: true
        end_date:
          type: string
          description: >-
            End date for the recurring charges. Format: YYYY-MM-DD. If not
            provided, the mandate will be valid indefinitely.
          example: '2026-12-31'
          nullable: true
        periodicity:
          allOf:
            - $ref: '#/components/schemas/SantanderMandatePeriodicity'
          nullable: true
    SantanderPixAutomaticoReceiverDetails:
      type: object
      description: >-
        Represents the receiver details for Santander Pix Automatico recurring
        charges
      properties:
        branch_code:
          type: string
          description: Branch code (agencia) of the receiver's bank account
          example: '0001'
          nullable: true
        account_number:
          type: string
          description: Account number (conta) of the receiver
          example: '130333323'
          nullable: true
        account_type:
          allOf:
            - $ref: '#/components/schemas/AccountType'
          nullable: true
    ProtestType:
      type: string
      description: >-
        Defines the type of protest for non-payment, such as whether the count
        is based on calendar days, business days, or if the protest logic is
        determined by a pre-signed contract with the bank.
      enum:
        - disabled
        - calendar_days
        - business_days
        - contract_default
    CalculationType:
      type: string
      description: >-
        Defines how the payment amount is calculated for penalties or discounts,
        either as a percentage or as a flat amount.
      enum:
        - percentage
        - flat_amount
    SantanderMandatePeriodicity:
      type: string
      enum:
        - weekly
        - monthly
        - quarterly
        - semiannually
        - annually
    AccountType:
      type: string
      description: Account type for Santander Pix Automatico recurring charges
      enum:
        - current
        - savings
        - payment
  securitySchemes:
    api_key:
      type: apiKey
      in: header
      name: api-key
      description: >-
        Use the API key created under your merchant account from the HyperSwitch
        dashboard. API key is used to authenticate API requests from your
        merchant server only. Don't expose this key on a website or embed it in
        a mobile application.

````