> ## 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.

# Revenue Recovery - Create

> Record a transaction made outside of Hyperswitch against an invoice.

```bash cURL theme={null}
curl --request POST \
  --url https://sandbox.hyperswitch.io/v2/recovery \
  --header 'Authorization: api-key=<API_KEY>' \
  --header 'Content-Type: application/json' \
  --header 'X-Profile-Id: pro_abcdefghijklmnop' \
  --data '{
  "amount_details": {
    "currency": "USD",
    "order_amount": 6540
  },
  "billing": {
    "address": {
      "city": "San Francisco",
      "country": "US",
      "first_name": "John",
      "last_name": "Doe",
      "line1": "1467 Harrison Street",
      "state": "California",
      "zip": "94122"
    },
    "email": "john@example.com"
  },
  "billing_merchant_connector_id": "mca_billing_1234567890",
  "billing_started_at": "2022-09-10T10:11:12Z",
  "connector_customer_id": "cust_12345",
  "connector_transaction_id": "993672945374576J",
  "error": {
    "code": "card_declined",
    "message": "The card was declined.",
    "network_advice_code": "01",
    "network_decline_code": "51",
    "network_error_message": "Retry after some time",
    "reason": "Insufficient funds"
  },
  "merchant_reference_id": "invoice_mbabizu24mvu3mela5njyh",
  "payment_merchant_connector_id": "mca_payment_1234567890",
  "payment_method_data": {
    "payment_method_metadata": {
      "card_exp_month": "01",
      "card_exp_year": "2026",
      "card_extended_bin": "42424242",
      "card_isin": "424242",
      "card_network": "Visa",
      "card_type": "credit",
      "last4": "4242"
    },
    "primary_processor_payment_method_token": "token_1234"
  },
  "payment_method_sub_type": "credit",
  "payment_method_type": "card",
  "transaction_created_at": "2022-09-10T10:11:12Z",
  "transaction_status": "failure"
}'
```


## OpenAPI

````yaml post /v2/recovery
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
paths:
  /v2/recovery:
    post:
      tags:
        - Revenue Recovery
      summary: Revenue Recovery - Create
      description: Record a transaction made outside of Hyperswitch against an invoice.
      operationId: Create a Revenue Recovery Payment
      parameters:
        - name: X-Profile-Id
          in: header
          description: >-
            Unique identifier of the business profile under which the invoice is
            processed. Any billing and payment merchant connector accounts in
            the request must belong to this profile.
          required: true
          schema:
            type: string
          example: pro_abcdefghijklmnop
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RecoveryPaymentsCreate'
            examples:
              Record a failed transaction and schedule a retry:
                value:
                  amount_details:
                    currency: USD
                    order_amount: 6540
                  billing:
                    address:
                      city: San Francisco
                      country: US
                      first_name: John
                      last_name: Doe
                      line1: 1467 Harrison Street
                      state: California
                      zip: '94122'
                    email: john@example.com
                  billing_merchant_connector_id: mca_billing_1234567890
                  billing_started_at: '2022-09-10T10:11:12Z'
                  connector_customer_id: cust_12345
                  connector_transaction_id: 993672945374576J
                  error:
                    code: card_declined
                    message: The card was declined.
                    network_advice_code: '01'
                    network_decline_code: '51'
                    network_error_message: Retry after some time
                    reason: Insufficient funds
                  merchant_reference_id: invoice_mbabizu24mvu3mela5njyh
                  payment_merchant_connector_id: mca_payment_1234567890
                  payment_method_data:
                    payment_method_metadata:
                      card_exp_month: '01'
                      card_exp_year: '2026'
                      card_extended_bin: '42424242'
                      card_isin: '424242'
                      card_network: Visa
                      card_type: credit
                      last4: '4242'
                    primary_processor_payment_method_token: token_1234
                  payment_method_sub_type: credit
                  payment_method_type: card
                  transaction_created_at: '2022-09-10T10:11:12Z'
                  transaction_status: failure
              Record a failed transaction on a profile with external triggers:
                value:
                  amount_details:
                    currency: USD
                    order_amount: 6540
                  billing:
                    address:
                      city: San Francisco
                      country: US
                      first_name: John
                      last_name: Doe
                      line1: 1467 Harrison Street
                      state: California
                      zip: '94122'
                    email: john@example.com
                    phone:
                      country_code: '+1'
                      number: '9123456789'
                  billing_started_at: '2022-09-10T10:11:12Z'
                  connector: stripe
                  connector_customer_id: cust_12345
                  connector_transaction_id: 993672945374576J
                  error:
                    code: card_declined
                    message: The card was declined.
                    network_advice_code: '01'
                    network_decline_code: '51'
                    network_error_message: Retry after some time
                    reason: Insufficient funds
                  merchant_reference_id: invoice_mbabizu24mvu3mela5njyh
                  payment_method_data:
                    payment_method_metadata:
                      card_exp_month: '01'
                      card_exp_year: '2026'
                      card_extended_bin: '42424242'
                      card_isin: '424242'
                      card_network: Visa
                      card_type: credit
                      last4: '4242'
                    primary_processor_payment_method_token: token_1234
                  payment_method_sub_type: credit
                  payment_method_type: card
                  transaction_created_at: '2022-09-10T10:11:12Z'
                  transaction_status: failure
        required: true
      responses:
        '200':
          description: Revenue Recovery Transaction Recorded Successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecoveryPaymentsResponse'
              example:
                id: 12_pay_01a3868d94a471219b5c4bc71638e2zc
                intent_status: failed
                merchant_reference_id: invoice_mbabizu24mvu3mela5njyh
        '400':
          description: >-
            Missing or invalid mandatory fields, or the invoice takes no more
            transactions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericErrorResponseOpenApi'
        '404':
          description: Resource missing
        '500':
          description: Internal server error
      security:
        - api_key: []
components:
  schemas:
    RecoveryPaymentsCreate:
      type: object
      required:
        - amount_details
        - merchant_reference_id
        - transaction_status
        - payment_method_type
        - payment_method_sub_type
        - transaction_created_at
        - connector_customer_id
        - billing_started_at
        - connector_transaction_id
        - payment_method_data
      properties:
        amount_details:
          $ref: '#/components/schemas/AmountDetails'
        merchant_reference_id:
          type: string
          description: >-
            Unique identifier of the invoice in the merchant's billing system
            against which the transaction is being recorded.
          example: invoice_mbabizu24mvu3mela5njyh
          maxLength: 30
          minLength: 30
        error:
          allOf:
            - $ref: '#/components/schemas/ErrorDetails'
          nullable: true
        billing_merchant_connector_id:
          type: string
          description: >-
            Unique identifier assigned by Hyperswitch for the custom billing
            connector account. The account must belong to the profile passed in
            the `X-Profile-Id` header. Required when the
            `revenue_recovery_trigger_model` of the profile is
            `internal_triggers`, and ignored when it is `external_triggers`.
          example: mca_1234567890
          nullable: true
        payment_merchant_connector_id:
          type: string
          description: >-
            Unique identifier assigned by Hyperswitch for the payment connector
            account, such as Stripe, on which the transaction was processed. The
            account must belong to the profile passed in the `X-Profile-Id`
            header. Required when the `revenue_recovery_trigger_model` of the
            profile is `internal_triggers`, and ignored when it is
            `external_triggers`.
          example: mca_1234567890
          nullable: true
        connector:
          allOf:
            - $ref: '#/components/schemas/RecoveryConnector'
          nullable: true
        transaction_status:
          $ref: '#/components/schemas/RecoveryTransactionStatus'
        amount_captured:
          type: integer
          format: int64
          description: >-
            Amount captured by the transaction, in the lowest denomination of
            the currency. It is required when `transaction_status` is
            `partial_charged`, where it must be greater than zero and less than
            the order amount. For `charged` it may be omitted, and if sent it
            must equal the order amount. It must not be sent for a `failure`.
          example: 6540
          nullable: true
        mit_category:
          allOf:
            - $ref: '#/components/schemas/MitCategory'
          nullable: true
        customer_present:
          allOf:
            - $ref: '#/components/schemas/PresenceOfCustomerDuringPayment'
          default: absent
          nullable: true
        setup_future_usage:
          allOf:
            - $ref: '#/components/schemas/FutureUsage'
          default: off_session
          nullable: true
        billing:
          allOf:
            - $ref: '#/components/schemas/Address'
          nullable: true
        customer_details:
          allOf:
            - $ref: '#/components/schemas/CustomerDetails'
          nullable: true
        payment_method_type:
          $ref: '#/components/schemas/PaymentMethod'
        payment_method_sub_type:
          $ref: '#/components/schemas/PaymentMethodType'
        transaction_created_at:
          type: string
          format: date-time
          description: >-
            The time at which the transaction was created at the payment
            connector.
          example: '2022-09-10T10:11:12Z'
        connector_customer_id:
          type: string
          description: >-
            Unique identifier of the customer at the payment connector
            (connector customer id), with which the payment method token used
            for the transaction is associated.
          example: cust_12345
        billing_started_at:
          type: string
          format: date-time
          description: Invoice billing started at billing connector's end.
          example: '2022-09-10T10:11:12Z'
        connector_transaction_id:
          type: string
          description: >-
            Unique identifier of the transaction at the payment connector
            (connector transaction id). It is used to identify the transaction
            among the attempts recorded for the invoice, and together with
            `merchant_reference_id` it has to be unique.
          example: 993672945374576J
        payment_method_data:
          $ref: '#/components/schemas/CustomRecoveryPaymentMethodData'
        enable_partial_authorization:
          type: boolean
          description: Allow partial authorization for this payment
          default: false
          nullable: true
        metadata:
          type: object
          description: >-
            You can specify up to 50 keys, with key names up to 40 characters
            long and values up to 500 characters long. Metadata is useful for
            storing additional, structured information on an object.
          nullable: true
      additionalProperties: false
    RecoveryPaymentsResponse:
      type: object
      required:
        - id
        - intent_status
      properties:
        id:
          type: string
          description: >-
            Unique identifier of the invoice in Hyperswitch against which the
            transaction has been recorded.
          example: pay_mbabizu24mvu3mela5njyhpit4
          maxLength: 30
          minLength: 30
        intent_status:
          allOf:
            - $ref: '#/components/schemas/IntentStatus'
          default: requires_confirmation
        merchant_reference_id:
          type: string
          description: >-
            Unique identifier of the invoice in the merchant's billing system
            against which the

            transaction is being recorded.
          example: invoice_mbabizu24mvu3mela5njyh
          nullable: true
          maxLength: 30
          minLength: 30
    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
    AmountDetails:
      type: object
      required:
        - currency
      properties:
        order_amount:
          type: integer
          format: int64
          description: >-
            The payment amount. Amount for the payment in the lowest
            denomination of the currency, (i.e) in cents for USD denomination,
            in yen for JPY denomination etc. E.g., Pass 100 to charge $1.00 and
            1 for 1¥ since ¥ is a zero-decimal currency. Read more about [the
            Decimal and Non-Decimal
            Currencies](https://github.com/juspay/hyperswitch/wiki/Decimal-and-Non%E2%80%90Decimal-Currencies)
          example: 6540
          minimum: 0
        currency:
          $ref: '#/components/schemas/Currency'
        shipping_cost:
          allOf:
            - $ref: '#/components/schemas/MinorUnit'
          nullable: true
        order_tax_amount:
          allOf:
            - $ref: '#/components/schemas/MinorUnit'
          nullable: true
        skip_external_tax_calculation:
          $ref: '#/components/schemas/TaxCalculationOverride'
        skip_surcharge_calculation:
          $ref: '#/components/schemas/SurchargeCalculationOverride'
        surcharge_amount:
          allOf:
            - $ref: '#/components/schemas/MinorUnit'
          nullable: true
        tax_on_surcharge:
          allOf:
            - $ref: '#/components/schemas/MinorUnit'
          nullable: true
    ErrorDetails:
      type: object
      description: Error details for the payment
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: The error code
          example: card_declined
        message:
          type: string
          description: The error message
          example: The card was declined.
        reason:
          type: string
          description: The detailed error reason that was returned by the connector.
          example: The card was declined.
          nullable: true
        unified_code:
          type: string
          description: |-
            The unified error code across all connectors.
            This can be relied upon for taking decisions based on the error.
          example: card_declined
          nullable: true
        unified_message:
          type: string
          description: >-
            The unified error message across all connectors.

            If there is a translation available, this will have the translated
            message
          example: The card was declined.
          nullable: true
        network_advice_code:
          type: string
          description: >-
            This field can be returned for both approved and refused Mastercard
            payments.

            This code provides additional information about the type of
            transaction or the reason why the payment failed.

            If the payment failed, the network advice code gives guidance on if
            and when you can retry the payment.
          example: '01'
          nullable: true
        network_decline_code:
          type: string
          description: >-
            For card errors resulting from a card issuer decline, a brand
            specific 2, 3, or 4 digit code which indicates the reason the
            authorization failed.
          example: '05'
          nullable: true
        network_error_message:
          type: string
          description: >-
            A string indicating how to proceed with an network error if payment
            gateway provide one. This is used to understand the network error
            code better.
          example: Do not retry
          nullable: true
    RecoveryConnector:
      type: string
      description: >-
        Payment processor on which the reported transaction was made. Any other
        value is refused, as

        the standardised error code of a transaction is looked up by its
        processor.
      enum:
        - adyen
        - stripe
        - paypal
    RecoveryTransactionStatus:
      type: string
      description: Status of the transaction reported.
      enum:
        - charged
        - failure
        - partial_charged
    MitCategory:
      type: string
      description: >-
        Specifies the category of a Merchant Initiated Transaction (MIT). In the
        case of MIT, `mit_category` tells what kind of MIT is being processed.
        In the case of CIT, it tells the future intended MIT type.
      enum:
        - installment
        - unscheduled
        - recurring
        - subscription
        - resubmission
    PresenceOfCustomerDuringPayment:
      type: string
      description: >-
        Set to `present` to indicate that the customer is in your checkout flow
        during this payment, and therefore is able to authenticate. This
        parameter should be `absent` when merchant's doing merchant initiated
        payments and customer is not present while doing the payment.
      enum:
        - present
        - absent
    FutureUsage:
      type: string
      description: >-
        Specifies how the payment method can be used for future payments.

        - `off_session`: The payment method can be used for future payments when
        the customer is not present.

        - `on_session`: The payment method is intended for use only when the
        customer is present during checkout.


        If omitted, defaults to `on_session`.
      enum:
        - off_session
        - on_session
    Address:
      type: object
      properties:
        address:
          allOf:
            - $ref: '#/components/schemas/AddressDetails'
          nullable: true
        phone:
          allOf:
            - $ref: '#/components/schemas/PhoneDetails'
          nullable: true
        email:
          type: string
          nullable: true
    CustomerDetails:
      type: object
      description: >-
        Passing this object creates a new customer or attaches an existing
        customer to the payment
      properties:
        id:
          type: string
          description: The identifier for the customer.
          example: cus_y3oqhf46pyzuxjbcn2giaqnb44
          nullable: true
          maxLength: 64
          minLength: 1
        name:
          type: string
          description: The customer's name
          example: John Doe
          nullable: true
          maxLength: 255
        email:
          type: string
          description: The customer's email address
          example: johntest@test.com
          nullable: true
          maxLength: 255
        phone:
          type: string
          description: The customer's phone number
          example: '9123456789'
          nullable: true
          maxLength: 10
        phone_country_code:
          type: string
          description: The country code for the customer's phone number
          example: '+1'
          nullable: true
          maxLength: 2
        tax_registration_id:
          type: string
          description: The tax registration identifier of the customer.
          nullable: true
          maxLength: 255
        document_details:
          allOf:
            - $ref: '#/components/schemas/CustomerDocumentDetails'
          nullable: true
        date_of_birth:
          type: string
          format: date
          description: The customer's date of birth
          example: '1990-01-31'
          nullable: true
    PaymentMethod:
      type: string
      description: 'Indicates the type of payment method. Eg: ''card'', ''wallet'', etc.'
      enum:
        - card
        - card_redirect
        - pay_later
        - wallet
        - bank_redirect
        - bank_transfer
        - crypto
        - bank_debit
        - reward
        - real_time_payment
        - upi
        - voucher
        - gift_card
        - open_banking
        - mobile_payment
        - network_token
    PaymentMethodType:
      type: string
      description: >-
        Indicates the sub type of payment method. Eg: 'google_pay' & 'apple_pay'
        for wallets.
      enum:
        - ach
        - affirm
        - afterpay_clearpay
        - alfamart
        - ali_pay
        - ali_pay_hk
        - alma
        - amazon_pay
        - paysera
        - apple_pay
        - atome
        - bacs
        - bancontact_card
        - becs
        - benefit
        - bizum
        - blik
        - bluecode
        - boleto
        - bca_bank_transfer
        - bni_va
        - breadpay
        - bri_va
        - bhn_card_network
        - card_redirect
        - cimb_va
        - classic
        - credit
        - crypto_currency
        - cashapp
        - dana
        - danamon_va
        - debit
        - duit_now
        - efecty
        - eft
        - eft_debit_order
        - eps
        - flexiti
        - fps
        - evoucher
        - giropay
        - givex
        - google_pay
        - go_pay
        - gcash
        - ideal
        - interac
        - indomaret
        - klarna
        - kakao_pay
        - local_bank_redirect
        - mandiri_va
        - knet
        - mb_way
        - mobile_pay
        - momo
        - momo_atm
        - multibanco
        - neteller
        - online_banking_thailand
        - online_banking_czech_republic
        - online_banking_finland
        - online_banking_fpx
        - online_banking_poland
        - online_banking_slovakia
        - oxxo
        - pago_efectivo
        - permata_bank_transfer
        - open_banking_uk
        - pay_bright
        - payjustnow
        - paypal
        - paze
        - pix
        - pix_key
        - pix_emv
        - pix_qr
        - pix_automatico_qr
        - pix_automatico_push
        - pay_safe_card
        - przelewy24
        - prompt_pay
        - pse
        - qris
        - red_compra
        - red_pagos
        - samsung_pay
        - sepa
        - sepa_bank_transfer
        - sepa_guarenteed_debit
        - skrill
        - sofort
        - swish
        - touch_n_go
        - trustly
        - twint
        - upi_collect
        - upi_intent
        - upi_qr
        - vipps
        - viet_qr
        - venmo
        - walley
        - wero
        - we_chat_pay
        - seven_eleven
        - lawson
        - mini_stop
        - family_mart
        - seicomart
        - pay_easy
        - local_bank_transfer
        - mifinity
        - open_banking_pis
        - direct_carrier_billing
        - instant_bank_transfer
        - instant_bank_transfer_finland
        - instant_bank_transfer_poland
        - revolut_pay
        - indonesian_bank_transfer
        - open_banking
        - network_token
        - payshap
        - payshap_proxy
        - ted
    CustomRecoveryPaymentMethodData:
      type: object
      required:
        - primary_processor_payment_method_token
        - payment_method_metadata
      properties:
        primary_processor_payment_method_token:
          type: string
          description: >-
            Primary payment method token at payment processor end, i.e. the
            connector token or connector mandate id.
          example: token_1234
        payment_method_metadata:
          $ref: '#/components/schemas/AdditionalCardInfo'
    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
    Currency:
      type: string
      description: >-
        The three-letter ISO 4217 currency code (e.g., "USD", "EUR") for the
        payment amount. This field is mandatory for creating a payment.
      enum:
        - AED
        - AFN
        - ALL
        - AMD
        - ANG
        - AOA
        - ARS
        - AUD
        - AWG
        - AZN
        - BAM
        - BBD
        - BDT
        - BGN
        - BHD
        - BIF
        - BMD
        - BND
        - BOB
        - BRL
        - BSD
        - BTN
        - BWP
        - BYN
        - BZD
        - CAD
        - CDF
        - CHF
        - CLF
        - CLP
        - CNY
        - COP
        - CRC
        - CUC
        - CUP
        - CVE
        - CZK
        - DJF
        - DKK
        - DOP
        - DZD
        - EGP
        - ERN
        - ETB
        - EUR
        - FJD
        - FKP
        - GBP
        - GEL
        - GHS
        - GIP
        - GMD
        - GNF
        - GTQ
        - GYD
        - HKD
        - HNL
        - HRK
        - HTG
        - HUF
        - IDR
        - ILS
        - INR
        - IQD
        - IRR
        - ISK
        - JMD
        - JOD
        - JPY
        - KES
        - KGS
        - KHR
        - KMF
        - KPW
        - KRW
        - KWD
        - KYD
        - KZT
        - LAK
        - LBP
        - LKR
        - LRD
        - LSL
        - LYD
        - MAD
        - MDL
        - MGA
        - MKD
        - MMK
        - MNT
        - MOP
        - MRU
        - MUR
        - MVR
        - MWK
        - MXN
        - MYR
        - MZN
        - NAD
        - NGN
        - NIO
        - NOK
        - NPR
        - NZD
        - OMR
        - PAB
        - PEN
        - PGK
        - PHP
        - PKR
        - PLN
        - PYG
        - QAR
        - RON
        - RSD
        - RUB
        - RWF
        - SAR
        - SBD
        - SCR
        - SDG
        - SEK
        - SGD
        - SHP
        - SLE
        - SLL
        - SOS
        - SRD
        - SSP
        - STD
        - STN
        - SVC
        - SYP
        - SZL
        - THB
        - TJS
        - TMT
        - TND
        - TOP
        - TRY
        - TTD
        - TWD
        - TZS
        - UAH
        - UGX
        - USD
        - UYU
        - UZS
        - VES
        - VND
        - VUV
        - WST
        - XAF
        - XCD
        - XOF
        - XPF
        - YER
        - ZAR
        - ZMW
        - ZWL
    MinorUnit:
      type: integer
      format: int64
      description: This Unit struct represents MinorUnit in which core amount works
    TaxCalculationOverride:
      type: string
      enum:
        - skip
        - calculate
    SurchargeCalculationOverride:
      type: string
      enum:
        - skip
        - calculate
    AddressDetails:
      type: object
      description: Address details
      properties:
        city:
          type: string
          description: The city, district, suburb, town, or village of the address.
          example: New York
          nullable: true
          maxLength: 50
        country:
          allOf:
            - $ref: '#/components/schemas/CountryAlpha2'
          nullable: true
        line1:
          type: string
          description: The first line of the street address or P.O. Box.
          example: 123, King Street
          nullable: true
          maxLength: 200
        line2:
          type: string
          description: >-
            The second line of the street address or P.O. Box (e.g., apartment,
            suite, unit, or building).
          example: Powelson Avenue
          nullable: true
          maxLength: 50
        line3:
          type: string
          description: The third line of the street address, if applicable.
          example: Bridgewater
          nullable: true
          maxLength: 50
        zip:
          type: string
          description: The zip/postal code for the address
          example: '08807'
          nullable: true
          maxLength: 50
        state:
          type: string
          description: The address state
          example: New York
          nullable: true
        first_name:
          type: string
          description: The first name for the address
          example: John
          nullable: true
          maxLength: 255
        last_name:
          type: string
          description: The last name for the address
          example: Doe
          nullable: true
          maxLength: 255
        origin_zip:
          type: string
          description: The zip/postal code of the origin
          example: '08807'
          nullable: true
          maxLength: 50
    PhoneDetails:
      type: object
      description: Phone contact details shared by payment and payout API models.
      properties:
        number:
          type: string
          description: The contact number
          example: '9123456789'
          nullable: true
        country_code:
          type: string
          description: The country code attached to the number
          example: '+1'
          nullable: true
    CustomerDocumentDetails:
      type: object
      required:
        - document_type
        - document_number
      properties:
        document_type:
          $ref: '#/components/schemas/DocumentKind'
        document_number:
          type: string
          description: |-
            The customer's document number
            Length of the document number depends upon the document_type.
            For CPF/CNPJ it is typically 11/14 digits long
          example: '12345678911'
          maxLength: 255
    AdditionalCardInfo:
      type: object
      properties:
        card_issuer:
          type: string
          description: The name of issuer of the card
          nullable: true
        card_network:
          allOf:
            - $ref: '#/components/schemas/CardNetwork'
          nullable: true
        card_type:
          type: string
          description: Card type, can be either `credit` or `debit`
          nullable: true
        card_subtype:
          type: string
          description: |-
            The product the card is issued under, e.g. `CLASSIC` or `ELECTRON`.
            Free form, as the value comes straight from the BIN record.
          nullable: true
        card_segment_type:
          allOf:
            - $ref: '#/components/schemas/CardSegmentType'
          nullable: true
        funding_source:
          allOf:
            - $ref: '#/components/schemas/FundingSource'
          nullable: true
        card_issuing_country:
          type: string
          nullable: true
        card_issuing_country_code:
          type: string
          nullable: true
        bank_code:
          type: string
          nullable: true
        last4:
          type: string
          description: Last 4 digits of the card number
          nullable: true
        card_isin:
          type: string
          description: The ISIN of the card
          nullable: true
        card_extended_bin:
          type: string
          description: Extended bin of card, contains the first 8 digits of card number
          nullable: true
        card_exp_month:
          type: string
          example: '01'
          nullable: true
        card_exp_year:
          type: string
          example: '2026'
          nullable: true
        card_holder_name:
          type: string
          example: John Doe
          nullable: true
        payment_checks:
          description: >-
            Additional payment checks done on the cvv and billing address by the
            processors.

            This is a free form field and the structure varies from processor to
            processor
          nullable: true
        authentication_data:
          description: >-
            Details about the threeds environment.

            This is a free form field and the structure varies from processor to
            processor
          nullable: true
        is_regulated:
          type: boolean
          description: >-
            Indicates if the card issuer is regulated under government-imposed
            interchange fee caps.

            In the United States, this includes debit cards that fall under the
            Durbin Amendment,

            which imposes capped interchange fees.
          nullable: true
        signature_network:
          allOf:
            - $ref: '#/components/schemas/CardNetwork'
          nullable: true
        auth_code:
          type: string
          description: Unique authorisation code generated for the payment.
          nullable: true
    CountryAlpha2:
      type: string
      enum:
        - AF
        - AX
        - AL
        - DZ
        - AS
        - AD
        - AO
        - AI
        - AQ
        - AG
        - AR
        - AM
        - AW
        - AU
        - AT
        - AZ
        - BS
        - BH
        - BD
        - BB
        - BY
        - BE
        - BZ
        - BJ
        - BM
        - BT
        - BO
        - BQ
        - BA
        - BW
        - BV
        - BR
        - IO
        - BN
        - BG
        - BF
        - BI
        - KH
        - CM
        - CA
        - CV
        - KY
        - CF
        - TD
        - CL
        - CN
        - CX
        - CC
        - CO
        - KM
        - CG
        - CD
        - CK
        - CR
        - CI
        - HR
        - CU
        - CW
        - CY
        - CZ
        - DK
        - DJ
        - DM
        - DO
        - EC
        - EG
        - SV
        - GQ
        - ER
        - EE
        - ET
        - FK
        - FO
        - FJ
        - FI
        - FR
        - GF
        - PF
        - TF
        - GA
        - GM
        - GE
        - DE
        - GH
        - GI
        - GR
        - GL
        - GD
        - GP
        - GU
        - GT
        - GG
        - GN
        - GW
        - GY
        - HT
        - HM
        - VA
        - HN
        - HK
        - HU
        - IS
        - IN
        - ID
        - IR
        - IQ
        - IE
        - IM
        - IL
        - IT
        - JM
        - JP
        - JE
        - JO
        - KZ
        - KE
        - KI
        - KP
        - KR
        - KW
        - KG
        - LA
        - LV
        - LB
        - LS
        - LR
        - LY
        - LI
        - LT
        - LU
        - MO
        - MK
        - MG
        - MW
        - MY
        - MV
        - ML
        - MT
        - MH
        - MQ
        - MR
        - MU
        - YT
        - MX
        - FM
        - MD
        - MC
        - MN
        - ME
        - MS
        - MA
        - MZ
        - MM
        - NA
        - NR
        - NP
        - NL
        - NC
        - NZ
        - NI
        - NE
        - NG
        - NU
        - NF
        - MP
        - 'NO'
        - OM
        - PK
        - PW
        - PS
        - PA
        - PG
        - PY
        - PE
        - PH
        - PN
        - PL
        - PT
        - PR
        - QA
        - RE
        - RO
        - RU
        - RW
        - BL
        - SH
        - KN
        - LC
        - MF
        - PM
        - VC
        - WS
        - SM
        - ST
        - SA
        - SN
        - RS
        - SC
        - SL
        - SG
        - SX
        - SK
        - SI
        - SB
        - SO
        - ZA
        - GS
        - SS
        - ES
        - LK
        - SD
        - SR
        - SJ
        - SZ
        - SE
        - CH
        - SY
        - TW
        - TJ
        - TZ
        - TH
        - TL
        - TG
        - TK
        - TO
        - TT
        - TN
        - TR
        - TM
        - TC
        - TV
        - UG
        - UA
        - AE
        - GB
        - UM
        - UY
        - UZ
        - VU
        - VE
        - VN
        - VG
        - VI
        - WF
        - EH
        - YE
        - ZM
        - ZW
        - US
    DocumentKind:
      type: string
      description: Represents the type of identification document used for validation.
      enum:
        - cpf
        - cnpj
        - psn
        - other
    CardNetwork:
      type: string
      description: Indicates the card network.
      enum:
        - Visa
        - Mastercard
        - AmericanExpress
        - JCB
        - DinersClub
        - Discover
        - CartesBancaires
        - UnionPay
        - Interac
        - RuPay
        - Maestro
        - Star
        - Pulse
        - Accel
        - Nyce
        - Prop
        - PrivateLabel
        - Dinacard
        - AirPlus
        - Aurore
        - EftposAustralia
        - GeCapital
        - Uatp
    CardSegmentType:
      type: string
      enum:
        - business
        - commercial
        - consumer
        - government
    FundingSource:
      type: string
      enum:
        - CREDIT
        - DEBIT
        - DEFERRED DEBIT
        - PREPAID
        - CHARGE CARD
  securitySchemes:
    api_key:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        Format: `api-key=<api_key>`


        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.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.