openapi: 3.0.0
info:
  description: |
    ## Description
    The HiPay POS API allows you to trigger in-store payments by:
    - waking a point-of-sale (POS) payment terminal with the payment information (amount, currency, etc.)
    - creating the related transaction in HiPay Console, your dedicated management interface.
    
    *Please note: this documentation describes the POS API parameters and response fields and allows you to test the platform in real time.  
    If you are looking for information about its integration, please check the [dedicated documentation](/point-of-sale/smart-terminal/pos-api).*
    ## Prerequisites
    - Internet connection:
      - a working and stable Wi-Fi connection is needed to join the payment terminal
      - a fixed public IP address for the network router is needed to join the payment terminal. In case your public IP address changes over time, it is usually possible to fix it by contacting your Internet access provider (please notice additional costs may be applied).
    ## Base URLs
    | Environment | Base URL |
    | --- | --- |
    | Stage | [https://cloudrun-api-yugcnet4yq-ew.a.run.app/](https://cloudrun-api-yugcnet4yq-ew.a.run.app/) |
    | Production | [https://cloudrun-api-n3l7nqotca-ew.a.run.app/](https://cloudrun-api-n3l7nqotca-ew.a.run.app/) |
    ## Authentication
    The HiPay POS API relies on *HTTP Basic Authentication*: for every request, API credentials must be provided in the request headers.
    
    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>')`
    
    *Note #1: API credentials can be found in the Integration section of your HiPay Enterprise back office.*  
    *Note #2: Only **private credentials** can be used to authenticate ("Accessibility" value = "Private").*
    ## Security
    For security reasons, it is highly recommended to filter access to your electronic POS payment terminals, based on the request origins.
    To make sure only requests coming from HiPay will be able to join your terminals, you can set up an IP packet filtering rule on your firewall based on the following IPs:
    | Environment | IP |
    | --- | --- |
    | Stage | 35.241.177.31 |
    | Production | 35.205.91.234 |
  title: POS API
  version: 1.2.0
servers:
- url: https://cloudrun-api-yugcnet4yq-ew.a.run.app/
  description: Stage
paths:
  /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
  /v1/connector/healthcheck:
    get:
      description: 'Health check'
      responses:
        '200':
          description: 'Health check OK'
      operationId : healthcheck
components:
  schemas:
    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.  
            The sum of every “total_amount” must be equal to the “amount” sent in the call.
          example: 8.99
        product_category:
          type: number
          description: |-
            Product Category:
              - `1`: Food & drinks
              - `2`: Auto & Motorcycle
              - `3`: Culture & Entretainment
              - `4`: Home & Garden
              - `5`: Home appliances
              - `6`: Bidding & Multi purchasing
              - `7`: Flowers & Gifts
              - `8`: Computers & Software
              - `9`: Health & Beauty
              - `10`: Personal services
              - `11`: Professional services
              - `12`: Sport
              - `13`: Clothing & Accessories
              - `14`: Travel & Tourism
              - `15`: Hifi, Photo & Video
              - `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.  
            This image will be displayed in the transaction notice page on HiPay Console.
          example: https://image.example.com/image_180x180.jpg
    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
    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'
        customer:
          $ref: '#/components/schemas/Customer'
        shipping:
          $ref: '#/components/schemas/Shipping'
        pos_technical_info:
          $ref: '#/components/schemas/TechnicalInformation'
    Address:
      type: object
      description: Address format
      properties:
        country:
          description: |
            Country code.  
            This two-letter country code complies with ISO 3166-1 (alpha 2).
          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'
    RootOrder:
      type: object
      description: Definition of the order's api call body
      required:
        - order
        - pos_technical_info
      properties:
        order:
          $ref: '#/components/schemas/Order'
        customer:
          $ref: '#/components/schemas/Customer'
        shipping:
          $ref: '#/components/schemas/Shipping'
        pos_technical_info:
          $ref: '#/components/schemas/TechnicalInformation'
    Order:
      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).  
                The amount is expressed in the smallest unit of the currency (100 for 1).
              type: number
              minimum: 0
              example: 100
            currency:
              description: |
                Base currency for this order.  
                This three-character currency code complies with ISO 4217.
              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"}'
    Customer:
      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'
    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.  
            It can be the customer itself, or someone else.
          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'
    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).  
            It overrides the default notification URL set in the configuration section of the HiPay back office.
          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).  
                      This contract number may have a different value depending on payment application used and payment mode (with contact or contactless).  
                      The contract number must be provided, or the other information required to retrieve it (shop or device and payment application).
                    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:
                       * `001` - CB, VISA, MASTERCARD with contact mode
                       * `002` - American Express with contact mode
                       * `003` - CB ENSEIGNE (CETELEM instalment payment)
                       * `004` - CETELEM
                       * `005` - COFINOGA
                       * `006` - DINNER'S CLUB
                       * `007` - PASS
                       * `008` - FRANFINANCE
                       * `009` - JCB
                       * `101` - CB VAD (Payment by entering the CB card numbers)
                       * `201` - quasi-Cash
                       * `301` - PLBS (Product Location Goods and Services)
                       * `401` - OPTALION (Crédit Lyonnais instalment payment)
                       * `501` - Cash-Agence
                       * `601` - PNF (Crédit Mutuel instalment payment)
                       * `602` - P3F
                       * `603` - OPTALION
                       * `604` - Préauto-CM
                       * `605` - PRCME
                       * `607` - Paiement-QR (Payment by QR-Code)
                       * `608` - TOP3-3XCB
                       * `609` - PNF-HPS
                       * `701` - PPFCA (Crédit Agricole)
                       * `00A` - Banque Accord EMV
                       * `00B` - CB, VISA, Mastercard contactless
                       * `00C` - CHEQUE
                       * `00D` - AMEX contactless
                       * `00E` - CONECS contact
                       * `00F` - DCC (Dynamic Currency Conversion)
                       * `00G` - QuickPass
                       * `00I` - CPEI-EMV
                       * `00S` - SOFINCO (private card)
                       * `00U` - UPI (China Union Pay)
                       * `10E` - CONECS contactless
                       * `30F` - PLBS-DCC-GB
                    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.  
                Overwrites the authorizationThreshold parameter to enable authorization.
              type: boolean
              default: FALSE
              example: TRUE
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic