openapi: 3.0.0
info:
  title: Hipay Payment Gateway balance Order API
  description: '## Version 1.6.1 - June 11, 2025


    The Gateway API allows you to get paid and manage orders and transactions.


    Please note: this documentation describes the Gateway API parameters and response fields and allows you to test the platform in real time.


    This page is to be used alongside the **[HiPay Enterprise Platform Overview documentation](https://developer.hipay.com/api-explorer/api-online-payments)**, which gives you more information and details on the HiPay Enterprise workflow. You may use both documents in parallel when integrating HiPay Enterprise.

    # Web service information

    ## Gateway API base URLs

    | Environment | Base URL |

    | --- | --- |

    | Stage | [https://stage-api-gateway.hipay.com](https://stage-api-gateway.hipay.com) |

    | Production |  [https://api-gateway.hipay.com](https://api-gateway.hipay.com) |

    ## Authentication

    All requests to the HiPay Enterprise API require identification through *HTTP Basic Authentication*. Your API credentials can be found in the Integration section of your HiPay Enterprise back office. Most HTTP clients (including web browsers) have built-in support for HTTP basic authentication. If not, the following header must be included in all HTTP requests.

    `Authorization: Basic base64(''API login>:<API password>'')`

    '
  version: 1.6.1
servers:
- url: https://stage-api-gateway.hipay.com
  description: Stage
- url: https://api-gateway.hipay.com
  description: Production
tags:
- name: Order
paths:
  /v3/order/{orderid}:
    get:
      tags:
      - Order
      operationId: get_api_order_consultation_public
      parameters:
      - name: orderid
        in: path
        description: Unique merchant orderid.
        required: true
        schema:
          type: string
        example: ORD_202501_0001
      responses:
        '200':
          description: Order retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '401':
          description: An authentication error occurred/invalid credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: This order is not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - ApiKeyAuth: []
      - BasicAuth: []
  /v1/connector/order:
    post:
      security:
      - BasicAuth: []
      requestBody:
        required: true
        content:
          application/*:
            schema:
              $ref: '#/components/schemas/RootOrder'
      responses:
        200:
          description: OK - The request has succeeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponse'
        400:
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        401:
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        403:
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        500:
          description: KO - The request has failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      operationId: postOrder
      summary: Wake a POS payment terminal to process an order payment.
      tags:
      - Order
components:
  schemas:
    Address:
      properties:
        house_number:
          description: House number.
          type: string
          example: '101'
          nullable: true
        house_extension:
          description: House extension.
          type: string
          example: B
          nullable: true
        street:
          description: Street address.
          type: string
          example: Rue de Rivoli
          nullable: true
        street_additional:
          description: Additional address information of the customer (e.g., building, floor, flat, etc.).
          type: string
          example: Immeuble B
          nullable: true
        locality:
          description: City.
          type: string
          example: Paris
          nullable: true
        locality_additional:
          description: The USA state or the Canada state of the customer making the purchase. Send this information only if the address country of the customer is US (USA) or CA (Canada)
          type: string
          example: ''
          nullable: true
        postal_code:
          description: The zip or postal code of the customer.
          type: string
          example: '75001'
          nullable: true
        country:
          description: Country code to which the order is being shipped. This two-letter country code complies with ISO 3166-1 (alpha 2).
          type: string
          example: FR
          nullable: true
      type: object
    Status2:
      type: integer
      enum:
      - 1
      - 2
      - 3
      - 4
      - 52
      - 5
      - 6
      - 7
      - 8
      - 9
      - 10
      - 11
      - 12
      - 13
      - 14
      - 15
      - 42
      - 43
      - 75
      - 16
      - 55
      - 17
      - 18
      - 54
      - 19
      - 20
      - 21
      - 22
      - 23
      - 24
      - 65
      - 25
      - 26
      - 27
      - 28
      - 29
      - 34
      - 30
      - 31
      - 32
      - 40
      - 41
      - 80
      - 81
      - 82
      - 83
      - 50
      - 51
      - 53
      - 57
      - 69
      - 66
      - 72
      - 74
      - 77
      - 78
    BasketItem:
      type: object
      description: Representation of one product line in a customer basket
      required:
      - product_reference
      - type
      - quantity
      - name
      - unit_price
      - tax_rate
      - total_amount
      properties:
        european_article_numbering:
          type: string
          description: European article numbering.
          example: 4711892728946
        product_reference:
          type: string
          description: Unique product reference.
          example: NF-a1690
        type:
          type: string
          description: Type of product.
          enum:
          - good
          - discount
          - fee
          example: good
        quantity:
          type: integer
          description: Product quantity.
          example: 1
        name:
          type: string
          description: Product description.
          example: My first product
        unit_price:
          type: number
          description: Unit price including taxes in order currency.
          example: 8.99
        tax_rate:
          type: number
          description: Tax rate in percentage.
          example: 0
        discount:
          type: number
          description: Discount amount, always 0 or negative.
          example: 0
        total_amount:
          type: number
          description: "Unit price X quantity – discount.  \nThe sum of every “total_amount” must be equal to the “amount” sent in the call.\n"
          example: 8.99
        product_category:
          type: number
          description: "Product Category:\n  - `1`: Food & drinks\n  - `2`: Auto & Motorcycle\n  - `3`: Culture & Entretainment\n  - `4`: Home & Garden\n  - `5`: Home appliances\n  - `6`: Bidding & Multi purchasing\n  - `7`: Flowers & Gifts\n  - `8`: Computers & Software\n  - `9`: Health & Beauty\n  - `10`: Personal services\n  - `11`: Professional services\n  - `12`: Sport\n  - `13`: Clothing & Accessories\n  - `14`: Travel & Tourism\n  - `15`: Hifi, Photo & Video\n  - `16`: Telephone & Communication"
          enum:
          - 1
          - 2
          - 3
          - 4
          - 5
          - 6
          - 7
          - 8
          - 9
          - 10
          - 11
          - 12
          - 13
          - 14
          - 15
          - 16
          example: 2
        url:
          type: string
          description: "Product Image.  \nThis image will be displayed in the transaction notice page on HiPay Console.\n"
          example: https://image.example.com/image_180x180.jpg
    Operation2:
      required:
      - type
      - status
      - amount
      - arn
      - date_created
      - id
      - currency
      - decimals
      properties:
        type:
          $ref: '#/components/schemas/OperationType2'
        status:
          $ref: '#/components/schemas/OperationStatus2'
        amount:
          description: Operation Amount.
          type: string
          example: '10.00'
        arn:
          description: Acquirer Reference Number.
          type: string
          example: '75064953264000221624949'
        merchant_reference:
          type: string
          nullable: true
        date_created:
          type: string
          format: date-time
        date_updated:
          type: string
          format: date-time
          nullable: true
        date_remitted:
          type: string
          format: date-time
          nullable: true
        date_processed:
          type: string
          format: date-time
          nullable: true
        date_reconciled:
          type: string
          format: date-time
          nullable: true
        id:
          type: integer
        currency:
          $ref: '#/components/schemas/Currency'
        decimals:
          type: integer
          example: '2'
        caseid:
          type: string
          nullable: true
      type: object
    Currency:
      type: string
      enum:
      - AED
      - AFN
      - ALL
      - AMD
      - ANG
      - AOA
      - ARS
      - AUD
      - AWG
      - AZN
      - BAM
      - BBD
      - BDT
      - BGN
      - BHD
      - BIF
      - BMD
      - BND
      - BOB
      - BRL
      - BSD
      - BTN
      - BWP
      - BYR
      - BZD
      - CAD
      - CDF
      - CHF
      - CLP
      - CNY
      - COP
      - CRC
      - CUC
      - CUP
      - CVE
      - CZK
      - DJF
      - DKK
      - DOP
      - DZD
      - EEK
      - EGP
      - ERN
      - ETB
      - EUR
      - FJD
      - FKP
      - FRF
      - 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
      - LTL
      - LVL
      - LYD
      - MAD
      - MDL
      - MGA
      - MKD
      - MMK
      - MNT
      - MOP
      - MRO
      - 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
      - SKK
      - SLL
      - SOS
      - SRD
      - STD
      - SVC
      - SYP
      - SZL
      - THB
      - TJS
      - TMM
      - TMT
      - TND
      - TOP
      - TRY
      - TTD
      - TWD
      - TZS
      - UAH
      - UGX
      - USD
      - UYU
      - UZS
      - VEF
      - VND
      - VUV
      - WST
      - XAF
      - XCD
      - XOF
      - XPF
      - YER
      - ZAR
      - ZMK
      - ZWL
    Customer:
      required:
      - email
      - phone
      properties:
        id:
          type: string
          example: '283749291'
          nullable: true
        firstname:
          description: The customer’s first name. This value will be use to pre-fill cardholder name on credit card payment form.
          type: string
          example: Rose
          nullable: true
        lastname:
          description: The customer’s last name. This value will be use to pre-fill cardholder name on credit card payment form.
          type: string
          example: Dévent
          nullable: true
        email:
          description: The customer’s e-mail address.
          type: string
          example: otto.graph@foobar.email
        phone:
          description: The customer’s phone.
          type: string
          example: 01234567890
        language:
          type: string
          example: en_GB
          nullable: true
      type: object
    Acquirer2:
      properties:
        transaction_reference:
          description: Unique Transaction Identifier.
          type: string
          example: '800000790677'
          nullable: true
      type: object
    TerminalInformation:
      properties:
        payment_context:
          description: Payment context
          type: string
          example: online
          nullable: true
        input_mode:
          description: Input mode
          type: string
          example: contact
          nullable: true
        aid:
          description: Aid
          type: string
          example: A0000000422010
          nullable: true
        payment_gateway:
          description: Payment gateway
          type: string
          example: nepting
          nullable: true
        authorization_code:
          description: Authorization code
          type: string
          example: '00'
          nullable: true
        authorization_number:
          description: Authorization number
          type: string
          example: '963379'
          nullable: true
        customer_receipt:
          description: Customer receipt
          type: string
          nullable: true
        payment_source:
          description: Payment source
          type: string
          example: IPN Nepting
          nullable: true
        payment_terminal_serial_number:
          description: Payment terminal serial number
          type: string
          nullable: true
        idsa:
          description: Acceptance system identifier assigned by an acquirer
          type: string
          nullable: true
        rts:
          description: Transaction ID generated by the issuer auth system
          type: string
          nullable: true
        card_entry_mode:
          description: Card entry mode
          example: magstripe
          nullable: true
          oneOf:
          - $ref: '#/components/schemas/CardEntryMode'
        file_number:
          description: File number
          type: string
          nullable: true
      type: object
    Order_2:
      description: Object containing all the basic information of a given transaction.
      type: object
      required:
      - order_id
      - price
      properties:
        order_id:
          description: Unique order ID.
          type: string
          example: ORDER_1537532589263
        transaction_type:
          description: 'Type of transaction to be performed:

            - `Debit`: debit

            - `Credit`: credit

            - `Cancel`: cancel

            '
          type: string
          enum:
          - Debit
          - Credit
          - Cancel
          default: Debit
          example: Debit
        initialize_payment_terminal:
          description: Whether HiPay needs to display the transaction on a POS payment terminal.
          type: boolean
          default: true
          example: true
        price:
          description: Information about the order pricing.
          type: object
          required:
          - amount
          properties:
            amount:
              description: "Total order amount, calculated as the sum of purchased items, plus shipping fees (if present), plus tax fees (if present).  \nThe amount is expressed in the smallest unit of the currency (100 for 1).\n"
              type: number
              minimum: 0
              example: 100
            currency:
              description: "Base currency for this order.  \nThis three-character currency code complies with ISO 4217.\n"
              type: string
              enum:
              - FRF
              - SKK
              - EEK
              - TMT
              - AED
              - AFN
              - ALL
              - AMD
              - ANG
              - AOA
              - ARS
              - AUD
              - AWG
              - AZN
              - BAM
              - BBD
              - BDT
              - BGN
              - BHD
              - BIF
              - BMD
              - BND
              - BOB
              - BRL
              - BSD
              - BTN
              - BWP
              - BYR
              - BZD
              - CAD
              - CDF
              - CHF
              - 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
              - LTL
              - LVL
              - LYD
              - MAD
              - MDL
              - MGA
              - MKD
              - MMK
              - MNT
              - MOP
              - MRO
              - 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
              - SLL
              - SOS
              - SRD
              - STD
              - SVC
              - SYP
              - SZL
              - THB
              - TJS
              - TND
              - TOP
              - TRY
              - TTD
              - TWD
              - TZS
              - UAH
              - UGX
              - USD
              - UYU
              - UZS
              - VEF
              - VND
              - VUV
              - TMM
              - WST
              - XAF
              - XCD
              - XOF
              - XPF
              - YER
              - ZAR
              - ZMK
              - ZWL
              default: EUR
              example: EUR
            tax_fees:
              description: 'The order tax fee.

                It can be omitted if the order tax value is zero.

                '
              type: number
              minimum: 0
              example: 1.1
            shipping_fees:
              description: 'The order shipping fee.

                It can be omitted if the shipping fee value is zero.

                '
              type: number
              minimum: 0
              example: 1.3
        basket:
          description: To get the best insights from HiPay's platform, it is recommended to send all the information you have about the products that are part of the customer basket.
          type: array
          items:
            $ref: '#/components/schemas/BasketItem'
        description:
          description: Short description of the order.
          type: string
          default: POS payment
          example: A super short description here...
        long_description:
          description: Additional order description.
          type: string
          example: A super long description here...
        soft_descriptor:
          description: Billing descriptor for machine learning.
          type: string
          example: Dell Inspiron 15 3583 (i3583-3112BLK-PFR)
        custom_data:
          description: 'Custom data.

            You can use these parameters to submit custom values you wish to show in HiPay back office transaction details, receive back in the API response messages, in the notifications or to activate specific FPS rules.

            '
          type: object
          example: '{"internal_reference":"ORD_987465","customer_first_order":true,"other_sample_parameter":"Other sample value"}'
    OrderResponse:
      type: object
      properties:
        paymentStatus:
          type: string
          description: Status received from the TPE regarding the payment.
          enum:
          - Success
          - Failure
          example: success
        receipt:
          type: string
          description: Receipt encoded in Base64
          example: UkVDRUlQVCA5OSBFVVI==
        error:
          type: object
          required:
          - errorCode
          properties:
            errorCode:
              type: string
              description: Error code
              example: 1003
            errorDescription:
              type: string
              description: Error description
              example: The network is unavailable
        order:
          $ref: '#/components/schemas/Order_2'
        customer:
          $ref: '#/components/schemas/Customer_2'
        shipping:
          $ref: '#/components/schemas/Shipping'
        pos_technical_info:
          $ref: '#/components/schemas/TechnicalInformation'
    ReasonCode2:
      properties:
        code:
          type: integer
          nullable: true
        reason:
          type: string
          nullable: true
      type: object
    PaymentProduct2:
      required:
      - name
      - description
      properties:
        payment_method:
          nullable: true
          oneOf:
          - $ref: '#/components/schemas/PaymentMethod2'
        name:
          type: string
        description:
          type: string
      type: object
    ThreeDSAuthenticationLiability2:
      type: string
      enum:
      - issuer
      - merchant
      - not applicable
    Shipping:
      description: To get additional insights and to be more efficient in fighting against fraud, it is recommended to send any relevant shipping information.
      type: object
      properties:
        delivery_date:
          description: Estimated delivery date (YYYY-MM-DD).
          type: string
          example: '2022-12-20'
          minLength: 10
          maxLength: 10
        delivery_method:
          description: 'The delivery method:

            - `EXPRESS24H`: express shipping in a maximum of 24 hours

            - `EXPRESS48H`: express shipping in a maximum of 48 hours

            - `STORE`: in-store shipping

            - `STORE24H`: in-store shipping in a maximum of 24 hours

            - `CARRIER`: shipped by a carrier

            - `CARRIER24H`: shipped by a carrier in a maximum of 24 hours

            - `RELAYPOINT`: shipped in a relay point

            - `RELAYPOINT24H`: shipped in a relay point in a maximum of 24 hours

            '
          type: string
          enum:
          - EXPRESS24H
          - EXPRESS48H
          - STORE
          - STORE24H
          - CARRIER
          - CARRIER24H
          - RELAYPOINT
          - RELAYPOINT24H
          example: CARRIER
        carrier_description:
          description: Carrier description.
          type: string
          example: La Poste, 27 Rue des Francs Bourgeois
        recipient_information:
          description: "Information about the person who will receive the delivery.  \nIt can be the customer itself, or someone else.\n"
          type: object
          properties:
            first_name:
              description: Recipient's first name.
              type: string
              example: Cathy
            last_name:
              description: Recipient's last name.
              type: string
              example: Doe
            additional_info:
              description: Additional information about the recipient (e.g., quality or function, company name, department, etc.).
              type: string
              example: Dr.
            gender:
              description: 'Gender of the recipient:

                - `M`: male

                - `F`: female

                - `U`: unknown

                '
              type: string
              enum:
              - M
              - F
              - U
              example: U
            phone:
              description: Recipient's phone number.
              type: string
              example: '33112345678'
        delivery_address:
          $ref: '#/components/schemas/Address_2'
    Cvc2:
      type: string
      enum:
      - Match
      - No Match
      - Not Processed
      - Missing
      - Not Supported
    TechnicalInformation:
      title: Technical Information
      description: Object that contains technical parameters that are required to process the order.
      type: object
      required:
      - terminal_transaction_display
      properties:
        notify_url:
          description: "This parameter allows you to define the URL address of your notification handler (the endpoint you want to use to process these order-related notifications that will be sent by the HiPay platform).  \nIt overrides the default notification URL set in the configuration section of the HiPay back office.\n"
          type: string
          example: https://hipay.com/notify
        device_information:
          description: 'Information about the targeted POS payment terminal.

            Its attributes (`serial_number` and `manufacturer`) are **mandatory** if the protocol used is **`AppNepting`**, because they are used to join the POS payment terminal.

            '
          type: object
          properties:
            serial_number:
              description: 'Unique serial number of the POS terminal device.

                It is **mandatory** if the protocol used is **`AppNepting`**, because it is used to join the POS payment terminal.

                '
              type: string
              example: '1850320198'
            manufacturer:
              description: 'Manufacturer name of the POS payment terminal.

                It is **mandatory** if the protocol used is **`AppNepting`**, because it is used to join the POS payment terminal.

                '
              type: string
              example: PAX
        host_information:
          description: 'Network address of the POS payment terminal.

            Its attributes (`host` and `port`) are **mandatory** if the protocol used is **`ConcertV3.1` or `ConcertV3.2`**, because they are used to join the POS payment terminal.

            '
          type: object
          properties:
            host:
              type: string
              description: 'Host name or public IP address of the POS payment terminal (IP address that can be accessed directly over the internet and is assigned to your network router by your Internet Service Provider).

                It is **mandatory** if the protocol used is **`ConcertV3.1` or `ConcertV3.2`**, because they are used to join the POS payment terminal.

                '
              example: 193.251.48.153
            port:
              type: integer
              description: 'Port configured in your **network router** to forward the API call to your terminal, using its internal address (internal IP address + port)

                It is **mandatory** if the protocol used is **`ConcertV3.1` or `ConcertV3.2`**, because they are used to join the POS payment terminal.

                '
              default: 8888
              example: 8888
        terminal_transaction_display:
          description: 'Information used in case of "passive mode" (when the order must be sent to a POS payment terminal to handle the payment operation).

            The `contract_array` information is **mandatory** if the protocol used is **`ConcertV3.1` or `ConcertV3.2`**.

            '
          properties:
            contract_array:
              type: array
              description: 'Information related to the configuration of the POS payment terminal.

                The following information are **mandatory** if the protocol used is **`ConcertV3.1` or `ConcertV3.2`**.

                '
              items:
                type: object
                properties:
                  merchant_contract:
                    type: string
                    description: "Merchant contract number (or MID).  \nThis contract number may have a different value depending on payment application used and payment mode (with contact or contactless).  \nThe contract number must be provided, or the other information required to retrieve it (shop or device and payment application).\n"
                    minimum: 7
                    maximum: 7
                    example: 1234567
                  rank:
                    type: string
                    description: Terminal rank used by paymentApplication to reconcile the transaction.
                    minLength: 3
                    maxLength: 3
                    example: '001'
                  payment_application:
                    type: string
                    description: "Payment application used to made the payment on the device:\n * `001` - CB, VISA, MASTERCARD with contact mode\n * `002` - American Express with contact mode\n * `003` - CB ENSEIGNE (CETELEM instalment payment)\n * `004` - CETELEM\n * `005` - COFINOGA\n * `006` - DINNER'S CLUB\n * `007` - PASS\n * `008` - FRANFINANCE\n * `009` - JCB\n * `101` - CB VAD (Payment by entering the CB card numbers)\n * `201` - quasi-Cash\n * `301` - PLBS (Product Location Goods and Services)\n * `401` - OPTALION (Crédit Lyonnais instalment payment)\n * `501` - Cash-Agence\n * `601` - PNF (Crédit Mutuel instalment payment)\n * `602` - P3F\n * `603` - OPTALION\n * `604` - Préauto-CM\n * `605` - PRCME\n * `607` - Paiement-QR (Payment by QR-Code)\n * `608` - TOP3-3XCB\n * `609` - PNF-HPS\n * `701` - PPFCA (Crédit Agricole)\n * `00A` - Banque Accord EMV\n * `00B` - CB, VISA, Mastercard contactless\n * `00C` - CHEQUE\n * `00D` - AMEX contactless\n * `00E` - CONECS contact\n * `00F` - DCC (Dynamic Currency Conversion)\n * `00G` - QuickPass\n * `00I` - CPEI-EMV\n * `00S` - SOFINCO (private card)\n * `00U` - UPI (China Union Pay)\n * `10E` - CONECS contactless\n * `30F` - PLBS-DCC-GB\n"
                    minLength: 3
                    maxLength: 3
                    example: '001'
            push_to:
              description: 'Whether HiPay needs to interact directly with the POS payment terminal or with another product like the Omnichannel SDK or the ECR Connector:

                - `POS`: interact with the POS payment terminal

                - `SDK`: interact with the [Omnichannel SDK](/point-of-sale/smart-terminal/omnichannel-sdk)

                - `ECR`: interact with the [ECR Connector](/point-of-sale/smart-terminal/desktop)

                '
              type: string
              enum:
              - POS
              - SDK
              - ECR
              default: POS
              example: POS
            protocol:
              description: 'Protocol used to send the payment to the POS payment terminal:

                - `AppNepting`: Used to connect with the Nepting App via the HiPay App (via App2App mechanism)

                - `ConcertV3.1`: Concert V3.1

                - `ConcertV3.2`: Concert V3.2

                '
              type: string
              enum:
              - AppNepting
              - ConcertV3.1
              - ConcertV3.2
              default: ConcertV3.1
              example: AppNepting
            force_authorization:
              description: "Whether the authorization should be forced or not.  \nOverwrites the authorizationThreshold parameter to enable authorization.\n"
              type: boolean
              default: false
              example: true
    ThreeDSAuthenticationMethod2:
      type: string
      enum:
      - challenge
      - frictionless
      - ''
    Status5:
      type: string
      enum:
      - available
      - created
      - error
      - incomplete
      - pending
      - suspended
      - terminated
    Error:
      required:
      - message
      - code
      properties:
        message:
          type: string
        code:
          type: integer
        details:
          type: array
          items: {}
          default: null
          nullable: true
        description:
          type: string
          nullable: true
      type: object
    ComputedAuthenticationStatus2:
      type: string
      enum:
      - No authentication
      - Abandoned strong authentication
      - Unsuccessful authentication attempted
      - Challenge authentication
      - Frictionless authentication
      - Successful authentication
      - Failed authentication
      - Unknown authentication
    ShippingAddress:
      properties:
        house_number:
          description: House number.
          type: string
          example: '101'
          nullable: true
        house_extension:
          description: House extension.
          type: string
          example: B
          nullable: true
        street:
          description: Street address.
          type: string
          example: Rue de Rivoli
          nullable: true
        street_additional:
          description: Additional address information of the customer (e.g., building, floor, flat, etc.).
          type: string
          example: Immeuble B
          nullable: true
        locality:
          description: City.
          type: string
          example: Paris
          nullable: true
        locality_additional:
          description: The USA state or the Canada state of the customer making the purchase. Send this information only if the address country of the customer is US (USA) or CA (Canada)
          type: string
          example: ''
          nullable: true
        postal_code:
          description: The zip or postal code of the customer.
          type: string
          example: '75001'
          nullable: true
        country:
          description: Country code to which the order is being shipped. This two-letter country code complies with ISO 3166-1 (alpha 2).
          type: string
          example: FR
          nullable: true
      type: object
    Card2:
      properties:
        pan:
          type: string
          nullable: true
        last_digits:
          type: string
          nullable: true
        scheme:
          type: string
          nullable: true
        category:
          type: string
          nullable: true
        type:
          type: string
          nullable: true
        bin:
          type: integer
          nullable: true
        token:
          type: string
          nullable: true
      type: object
    PaymentMethod2:
      required:
      - name
      - description
      properties:
        name:
          type: string
        description:
          type: string
      type: object
    Device2:
      required:
      - ip_address
      properties:
        id:
          type: string
          nullable: true
        ip_address:
          description: The IP address of the Device
          type: string
          example: 127.0.0.1
      type: object
    OperationStatus2:
      type: string
      enum:
      - CANCELLED
      - COMPLETED
      - CREATED
      - FAILURE
      - NOT_PROCESSED
      - PENDING
      - RECONCILED
      - REMITTED
      - REQUESTED
      - RETRIED
      - SPLIT
      - CHGBCK
      - CHGBCK_REFUND
    RootOrder:
      type: object
      description: Definition of the order's api call body
      required:
      - order
      - pos_technical_info
      properties:
        order:
          $ref: '#/components/schemas/Order_2'
        customer:
          $ref: '#/components/schemas/Customer_2'
        shipping:
          $ref: '#/components/schemas/Shipping'
        pos_technical_info:
          $ref: '#/components/schemas/TechnicalInformation'
    Authentication5:
      type: string
      enum:
      - Authentication Successful
      - Authentication Attempt Performed
      - Authentication Failed
      - Authentication Could Not Be Performed
      - Error
      - Not applicable
      - Cardholder challenge required
      - Not authenticated because the issuer is rejecting authentication
      - Challenge required; decoupled authentication confirmed
      - Informational only; 3DS Requestor challenge preference acknowledged
      - Mastercard Delegated Authentication
    Address_2:
      type: object
      description: Address format
      properties:
        country:
          description: "Country code.  \nThis two-letter country code complies with ISO 3166-1 (alpha 2).\n"
          type: string
          example: FR
        state:
          description: State.
          type: string
        city:
          description: The city.
          type: string
          example: Paris
        zip_code:
          description: The zip or postal code.
          type: string
          example: '75001'
        street_address:
          description: Street address.
          type: string
          example: 101 Rue de Rivoli
        street_additional_details:
          description: Any additional information about the address where te order will be shipped (e.g., building, floor, flat, etc.).
          type: string
          example: Immeuble B
        house_number:
          description: House number.
          type: string
          example: '101'
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          required:
          - code
          properties:
            status:
              type: integer
            code:
              type: string
            message:
              type: string
            description:
              type: string
            details:
              type: object
              properties:
                path:
                  type: string
    Customer_2:
      description: To get additional insights and to be more efficient in fighting against fraud, it is recommended to send any relevant information about the customer.
      type: object
      properties:
        customer_id:
          description: Merchant's customer id.
          type: string
          example: '283749291'
        email:
          description: Customer's email address.
          type: string
          example: john.doe@foobar99.com
        phone:
          description: Customer's phone number.
          type: string
          example: '33012345678'
        first_name:
          description: Customer's first name.
          type: string
          example: Cathy
        last_name:
          description: Customer's last name.
          type: string
          example: Doe
        birthdate:
          description: Customer's birth date (YYYY-MM-DD).
          type: string
          example: '1988-06-12'
          minLength: 10
          maxLength: 10
        gender:
          description: 'Gender of the customer:

            - `M`: male

            - `F`: female

            - `U`: unknown'
          type: string
          enum:
          - U
          - F
          - M
          example: U
        additional_customer_information:
          description: Additional information about the customer (e.g., quality or function, company name, department, etc.).
          type: string
          example: Dr.
        customer_location:
          $ref: '#/components/schemas/Address_2'
    CardEntryMode:
      type: string
      enum:
      - Not specified
      - Magstripe
      - Contactless chip transaction using EMV chip data
      - Contactless chip transaction using magstripe data
      - ICC
      - Manual entry
      - Magstripe, after attempt to read chip
      - Provided by a server
      - Card-on-File
    DebitAgreement2:
      required:
      - id
      - status
      properties:
        id:
          type: integer
        scheme_reference_data:
          type: string
          nullable: true
        status:
          $ref: '#/components/schemas/Status5'
        recurring_payment_end_date:
          type: string
          nullable: true
      type: object
    AcquirerTraContext2:
      type: object
    Result2:
      type: string
      enum:
      - NOT_LAUNCHED
      - PENDING
      - ACCEPTED
      - REQUEST EXEMPTION
      - BLOCKED
      - CHALLENGED
      - AUTHENTICATE
      - FORCE_AUTHENTICATE
      - OVERRIDE
      - ACCEPT WITH NO PREFERENCE
      - DENIED
      - ALLOWED
    TransactionState2:
      type: string
      enum:
      - completed
      - waiting
      - pending
      - declined
      - forwarding
      - error
    FraudResult2:
      required:
      - result
      - review
      - score
      properties:
        result:
          $ref: '#/components/schemas/Result2'
        review:
          $ref: '#/components/schemas/Review2'
        score:
          type: integer
          example: 200
      type: object
    Order:
      required:
      - id
      - merchant_order_id
      - attempts
      - amount
      - shipping
      - tax
      - customer
      - shipping_to
      - date_created
      - transactions
      - currency
      - decimals
      properties:
        id:
          description: Unique order ID.
          type: integer
          example: '1537532589263'
        merchant_order_id:
          type: string
        attempts:
          description: Attempt identifier
          type: integer
          example: 1
        amount:
          description: Total order amount, calculated as the sum of purchased items, plus shipping fees (if present), plus tax fees (if present).
          type: string
          example: '8.99'
        shipping:
          description: The order shipping fee. It can be omitted if the shipping fee value is zero.
          type: string
          example: '1.30'
        tax:
          description: The order tax fee. It can be omitted if the order tax value is zero...
          type: string
          example: '1.10'
        customer:
          $ref: '#/components/schemas/Customer'
        shipping_to:
          $ref: '#/components/schemas/ShippingAddress'
        terminal_information:
          description: The customer terminal informations used for the order.
          nullable: true
          oneOf:
          - $ref: '#/components/schemas/TerminalInformation'
        date_created:
          type: string
          format: date-time
        transactions:
          type: array
          items:
            $ref: '#/components/schemas/Transaction2'
        currency:
          $ref: '#/components/schemas/Currency'
        decimals:
          type: integer
          example: '2'
        billing_to:
          nullable: true
          oneOf:
          - $ref: '#/components/schemas/Address'
        custom_data:
          type: string
          nullable: true
      type: object
    Preference2:
      type: integer
      enum:
      - 1
      - 2
      - 3
      - 4
      - 5
      - 7
    Review2:
      type: string
      enum:
      - ALLOWED
      - PENDING
      - DENIED
    OperationType2:
      type: string
      enum:
      - CAPTURE
      - CREDIT
      - REFUND
      - CHGBCK
      - CHGBCK_REFUND
      - RDR
    Issuer2:
      properties:
        fullname:
          type: string
          nullable: true
        institution:
          type: string
          nullable: true
        country:
          type: string
          nullable: true
      type: object
    Transaction2:
      required:
      - id
      - attemptid
      - state
      - status
      - eci
      - amount
      - captured_amount
      - refunded_amount
      - credited_amount
      - chargebacked_amount
      - acquirer
      - issuer
      - device
      - forward_url
      - customer_country
      - date_created
      - date_updated
      - mid
      - operations
      - authorized_amount
      - currency
      - decimals
      properties:
        id:
          description: Unique transaction ID.
          type: integer
          example: '2456731565945'
        attemptid:
          type: integer
        state:
          $ref: '#/components/schemas/TransactionState2'
        status:
          $ref: '#/components/schemas/Status2'
        computed_authentication_status:
          description: Transaction computed authentication status.
          example: Successful authentication
          nullable: true
          oneOf:
          - $ref: '#/components/schemas/ComputedAuthenticationStatus2'
        reason:
          nullable: true
          oneOf:
          - $ref: '#/components/schemas/ReasonCode2'
        eci:
          description: 'Electronic Commerce Indicator (ECI).


            The Electronic Commerce Indicator (ECI) is used by acquirers/issuers


            to determine the type of transaction being processed. The ECI value


            should represent the source of the transaction request. That is, the


            environment that the cardholder used to provide the payment card details


            to the merchant. It is important that merchants set the correct ECI


            value during transaction processing to ensure that appropriate merchant


            service rates are received.'
          type: integer
          example: 7
        amount:
          description: Transaction amount.
          type: string
          example: '125.75'
        captured_amount:
          description: Captured amount.
          type: string
          example: '125.75'
        refunded_amount:
          description: Refunded amount.
          type: string
          example: '0.00'
        credited_amount:
          description: Total credited.
          type: string
          example: '125.75'
        chargebacked_amount:
          description: Chargebacked amount.
          type: string
          example: '125.75'
        payment_product:
          description: The payment product used for processing current transaction.
          example: visa
          nullable: true
          oneOf:
          - $ref: '#/components/schemas/PaymentProduct2'
        acquirer:
          $ref: '#/components/schemas/Acquirer2'
        acquirer_tra:
          nullable: true
          oneOf:
          - $ref: '#/components/schemas/AcquirerTraContext2'
        issuer:
          $ref: '#/components/schemas/Issuer2'
        card:
          nullable: true
          oneOf:
          - $ref: '#/components/schemas/Card2'
        debit_agreement:
          nullable: true
          oneOf:
          - $ref: '#/components/schemas/DebitAgreement2'
        device:
          $ref: '#/components/schemas/Device2'
        authentication:
          nullable: true
          oneOf:
          - $ref: '#/components/schemas/Authentication2'
        authorization_code:
          type: string
          nullable: true
        forward_url:
          description: URL of the page on which to redirect the customer.
          type: string
          example: ''
        fraud_screening:
          nullable: true
          oneOf:
          - $ref: '#/components/schemas/FraudResult2'
        cvc_result:
          nullable: true
          oneOf:
          - $ref: '#/components/schemas/Cvc2'
        customer_country:
          type: string
          example: FR
        date_created:
          type: string
          format: date-time
        date_updated:
          description: 'Date of last status change.


            This date must comply with ISO 8601.'
          type: string
          format: date-time
        date_authorized:
          type: string
          format: date-time
          nullable: true
        mid:
          description: 'Merchant id (MID).


            Unique identifier assigned to the merchant.'
          type: integer
        operations:
          type: array
          items:
            $ref: '#/components/schemas/Operation2'
        authorized_amount:
          description: Authorized amount.
          type: string
          example: '125.75'
        currency:
          $ref: '#/components/schemas/Currency'
        decimals:
          type: integer
          example: '2'
      type: object
    Authentication2:
      required:
      - eci
      properties:
        enrollment_status:
          description: ''
          type: string
          example: N
          nullable: true
        enrollment_message:
          description: ''
          type: string
          example: Cardholder Not Enrolled
          nullable: true
        authentication_status:
          nullable: true
          oneOf:
          - $ref: '#/components/schemas/Authentication5'
        authentication_message:
          type: string
          nullable: true
        eci:
          description: 'Electronic Commerce Indicator (ECI).


            The Electronic Commerce Indicator (ECI) is used by acquirers/issuers


            to determine the type of transaction being processed. The ECI value


            should represent the source of the transaction request. That is, the


            environment that the cardholder used to provide the payment card details


            to the merchant. It is important that merchants set the correct ECI


            value during transaction processing to ensure that appropriate merchant


            service rates are received.'
          type: integer
          example: 5
        sca_preference:
          description: "To indicate the preference for a frictionless flow during the authentication request, the merchant may send the sca_preference parameter.\n\nDepending on the merchant's assessment of the risk of fraud, specific values may be sent.\n\nThis parameter can only be used by merchants who have a fraud risk assessment mechanism of their own and who have subscribed to the SCA Preference merchant option.\n\nPlease contact your account manager to request it.\n\n`1` : No Preference.\n\n    If you are not sure about the transaction's risk of fraud, use this value. Using this value for all your transactions may result in a high strong customer authentication rate.\n\n`2` : No Challenge\n\n    If you think this transaction is safe. This will tell the acquirer a frictionless flow is preferred.\n\n`3` : Challenge Requested\n\n    If you think this transaction may be at risk, use this value. This will tell the acquirer that a strong customer authentication may be required, depending on the PSD2 specific information you sent along with the transaction."
          example: 1
          nullable: true
          oneOf:
          - $ref: '#/components/schemas/Preference2'
        method:
          description: "To indicate the authentication method used :\n\n - 3DSecure\n\n - ApplePay"
          type: string
          example: 3DSecure
          nullable: true
        three_ds_version:
          description: 3D Secure Version
          type: string
          example: '2'
          nullable: true
        three_ds_authentication_method:
          description: "3D Secure Authentication Method:\n\n - challenge\n\n - frictionless\n\n - <i>empty</i>"
          example: frictionless
          nullable: true
          oneOf:
          - $ref: '#/components/schemas/ThreeDSAuthenticationMethod2'
        three_ds_liability:
          description: "3D Secure payment liability shift:\n\n - issuer\n\n - merchant\n\n - not applicable"
          example: issuer
          nullable: true
          oneOf:
          - $ref: '#/components/schemas/ThreeDSAuthenticationLiability2'
      type: object
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
    ApiKeyAuth:
      type: apiKey
      name: X-API-KEY
      in: header
externalDocs:
  description: Find out more about HiPay
  url: https://developer.hipay.com/