HiPay payments API

openapi: 3.2.0
info:
  title: Hipay Payments API
  version: '1.0'
  description: 'Operations tagged payments across 3 of this provider''s published API definitions: gateway.yaml, hpayment.yaml, omnichannel.yaml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://stage-secure-gateway.hipay-tpp.com/rest
  description: Stage
- url: https://secure-gateway.hipay-tpp.com/rest
  description: Production
- url: https://stage-api.hipay.com
- url: https://stage-secure-gateway.hipay-tpp.com/rest/
tags:
- name: payments
  description: Everything you need to create orders and transactions
paths:
  /v1/order:
    post:
      tags:
      - payments
      summary: Creates an order and a transaction based on payment details
      description: 'This service allows you to execute transactions through API with no need

        to redirect your customer to the payment page hosted by HiPay. This

        service supports payments with credit or debit cards as well as

        alternative payment methods.


        In **order** to make a payment with a credit or debit card, a token must

        have been generated beforehand. In fact, this service cannot receive

        credit or debit card numbers in clear. Instead, you must provide this

        service with a token associated to a card number. Use the HiPay

        Enterprise SDK for JavaScript in order to generate tokens.


        If you need to make payments with alternative payment methods, you can

        use this service directly. Note that the use of some alternative payment

        products implies that you redirect your user to an external URL. In such

        a case, the `forwardUrl` parameter will be set with the appropriate URL.

        Moreover, the activation of *3-D Secure* also implies a redirection of

        your customer.'
      operationId: requestNewOrder
      requestBody:
        description: Order information
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/InputOrder'
      responses:
        '200':
          description: Order successfully created and transaction executed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Transaction'
        '400':
          description: The request was rejected due to a validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: An authentication error occurred/invalid credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Access to this resource is fordidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - basicAuth: []
    servers:
    - url: https://stage-secure-gateway.hipay-tpp.com/rest
      description: Stage
    - url: https://secure-gateway.hipay-tpp.com/rest
      description: Production
  /v1/hpayment:
    post:
      responses:
        '200':
          description: Order successfully created and transaction executed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HostedPage_Forward'
        '400':
          description: The request was rejected due to a validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HostedPage_Error'
        '401':
          description: An authentication error occurred/invalid credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HostedPage_Error'
        '403':
          description: Access to this resource is fordidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HostedPage_Error'
      security:
      - basicAuth: []
      tags:
      - payments
      description: 'This service allows you to **redirect your customer to a payment page (hosted by HiPay)** in order to proceed checkout.


        This service creates an order and returns a forward URL. This forward URL is dedicated to display a payment page with your a customizable theme and validated payment products.


        After payment form validation, the checkout is processed and the customer is being returned to your website.


        According to transaction state and `authentication_indicator` parameter (see below), the customer will be redirected either to the accept or the decline page.


        There are two strategies for implementing this service:


        ### Hosted: Full redirection mode


        Once the payment page is created, you redirect your customer to it. Your customer is redirected back to your website once the transaction si executed.


        ### iFrame mode


        You may also display the payment page in an iFrame, in order to have a unified checkout workflow. To do so, you have to provide the `template` parameter with the value `iframe-js` (see below).'
      operationId: generatePage
      summary: Creates a secure payment page which you can redirect your customer to, in order to proceed checkout
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                payment_product_list:
                  type: string
                  description: "\n The list of payment products to display on the payment page.\n\n- `american-express`, `bancomatpay`, `bizum`, `bcmc`,  `cb`, `maestro`, `mastercard`, `visa`, `3xcb`, `3xcb-no-fees`, `4xcb`, `4xcb-no-fees`, `alma-3x`, `alma-4x`, `bancontact`, `bcmc-mobile`, `bnpp-3xcb`, `bnpp-4xcb`, `carte-cadeau`, `credit-long`, `giropay`, `ideal`, `illicado`, `klarna`, `mbway`, `mybank`, `multibanco`, `paypal`, `paysafecard`, `payshop`, `postfinance-card`, `postfinance-efinance`, `przelewy24`, `sdd`, `sisal`, `sofort-uberweisung`"
                payment_product_category_list:
                  type: string
                  default: credit-card
                  description: "\n The categories of payment products to be displayed on the payment page.\n\n- `credit-card`, `debit-card`, `realtime-banking`, `ewallet`, `prepaid-card`, `open-invoice`, `credit-consumption`"
                template:
                  type: string
                  default: basic-js
                  description: 'The template name. Possible values:

                    - `basic-js` : Template with customizable theme

                    - `basic` [Deprecated] : Template with customizable theme

                    - `iframe-js` : Template with hosted iFrame integration

                    - `iframe` [Deprecated] : Template with hosted iFrame integration

                    - `autodetection` : Automatic detection of the brand of the card, if the merchant has the option'
                merchant_display_name:
                  type: string
                  maxLength: 32
                  description: The merchant name displayed on payment page, otherwise the name is retrieved from order.
                display_selector:
                  type: integer
                  enum:
                  - 0
                  - 1
                  description: "Enable/disable the payment products selector. Possible values:\n  - `0`: the selector is not displayed\n  - `1`: the selector is displayed"
                time_limit_to_pay:
                  type: string
                  pattern: ^[0-9]+( [a-zA-Z]+)?$
                  description: 'The time limit to pay allows you to specify the validity period of a payment page in seconds starting from the moment the payment link (forwardUrl) is generated. If empty, default value is fixed to 7 days. Max value: 24 days (2140000 seconds).'
                orderid:
                  type: string
                  maxLength: 32
                  description: Unique order ID.
                operation:
                  type: string
                  format: alpha
                  default: Authorization
                  description: 'Transaction type:

                    - `Sale` indicates that the transaction is automatically submitted for capture.

                    - `Authorization` indicates that this transaction is sent for authorization only.'
                basket:
                  type: string
                  format: json
                  description: 'Shopping cart details.


                    Please refer to [HiPay Enterprise - Payment Gateway - Shopping cart managment](https://support.hipay.com/hc/fr/articles/115001660469-Payment-Gateway-Shopping-cart-management) technical documentation.'
                description:
                  type: string
                  maxLength: 255
                  description: The order short description.
                long_description:
                  type: string
                  description: Additional order description. You can show this description in HiPay payment page if desired.
                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
                  description: Base currency for this order. This three-character currency code complies with ISO 4217.
                amount:
                  type: string
                  minimum: 1
                  pattern: ^-?[0-9]+(\.[0-9]+)?$
                  description: Total order amount, calculated as the sum of purchased items, plus shipping fees (if present), plus tax fees (if present).
                shipping:
                  type: string
                  pattern: ^[0-9]+(\.[0-9]+)?$
                  description: The order shipping fee. It can be omitted if the shipping fee value is zero.
                tax:
                  type: string
                  pattern: ^[0-9]+(\.[0-9]+)?$
                  description: The order tax fee. It can be omitted if the order tax value is zero.
                tax_rate:
                  type: string
                  pattern: ^[0-9]+(\.[0-9]+)?$
                  description: The order tax rate.
                cid:
                  type: string
                  description: Merchant's customer id. For fraud detection reasons.
                ipaddr:
                  type: string
                  pattern: ^((25[0-5]|2[0-4][0-9]|[01]?[0-9]?[0-9])(\.(25[0-5]|2[0-4][0-9]|[01]?[0-9]?[0-9])){3})$|^((([0-9A-Fa-f]{1,4}:){7}[0-9A-Fa-f]{1,4})|(([0-9A-Fa-f]{1,4}:){6}:[0-9A-Fa-f]{1,4})|(([0-9A-Fa-f]{1,4}:){5}:([0-9A-Fa-f]{1,4}:)?[0-9A-Fa-f]{1,4})|(([0-9A-Fa-f]{1,4}:){4}:([0-9A-Fa-f]{1,4}:){0,2}[0-9A-Fa-f]{1,4})|(([0-9A-Fa-f]{1,4}:){3}:([0-9A-Fa-f]{1,4}:){0,3}[0-9A-Fa-f]{1,4})|(([0-9A-Fa-f]{1,4}:){2}:([0-9A-Fa-f]{1,4}:){0,4}[0-9A-Fa-f]{1,4})|(([0-9A-Fa-f]{1,4}:){6}((b((25[0-5])|(1d{2})|(2[0-4]d)|(d{1,2}))b).){3}(b((25[0-5])|(1d{2})|(2[0-4]d)|(d{1,2}))b))|(([0-9A-Fa-f]{1,4}:){0,5}:((b((25[0-5])|(1d{2})|(2[0-4]d)|(d{1,2}))b).){3}(b((25[0-5])|(1d{2})|(2[0-4]d)|(d{1,2}))b))|(::([0-9A-Fa-f]{1,4}:){0,5}((b((25[0-5])|(1d{2})|(2[0-4]d)|(d{1,2}))b).){3}(b((25[0-5])|(1d{2})|(2[0-4]d)|(d{1,2}))b))|([0-9A-Fa-f]{1,4}::([0-9A-Fa-f]{1,4}:){0,5}[0-9A-Fa-f]{1,4})|(::([0-9A-Fa-f]{1,4}:){0,6}[0-9A-Fa-f]{1,4})|(([0-9A-Fa-f]{1,4}:){1,7}:))$
                  description: The IP address of your customer making a purchase.
                accept_url:
                  type: string
                  format: uri
                  description: '

                    The URL to return your customer to once the payment process is

                    completed successfully.


                    For more information about the user

                    redirection workflow, check the [HiPay Enterprise

                    Overview](/payment-fundamentals/requirements/redirect-pages).'
                decline_url:
                  type: string
                  format: uri
                  description: '

                    The URL to return your customer to after the acquirer declines the

                    payment.


                    For more information about the user redirection

                    workflow, check the [HiPay Enterprise

                    Overview](/payment-fundamentals/requirements/redirect-pages).'
                pending_url:
                  type: string
                  format: uri
                  description: '

                    The URL to return your customer to when the payment request was

                    submitted to the acquirer but response is not yet available.


                    For more information about the user redirection workflow, check the

                    [HiPay Enterprise

                    Overview](/payment-fundamentals/requirements/redirect-pages).'
                exception_url:
                  type: string
                  format: uri
                  description: '

                    The URL to return your customer to after a system failure.


                    For more information about the user redirection workflow, check the

                    [HiPay Enterprise

                    Overview](/payment-fundamentals/requirements/redirect-pages).'
                cancel_url:
                  type: string
                  format: uri
                  description: '

                    The URL to return your customer to after a system failure.


                    For more information about the user redirection workflow, check the

                    [HiPay Enterprise

                    Overview](/payment-fundamentals/requirements/redirect-pages).'
                notify_url:
                  type: string
                  format: uri
                  description: This field allows you to override the notification URL, available in the configuration in the HiPay back office, with the URL of your choice that will process the notification sent by the HiPay platform.
                http_accept:
                  type: string
                  format: accept_header
                  description: This element should contain the exact content of the HTTP Accept header as sent to the merchant from the customer's browser.
                http_user_agent:
                  type: string
                  description: This element should contain the exact content of the HTTP User-Agent header as sent to the merchant from the customer's browser.
                language:
                  type: string
                  format: lang
                  maxLength: 5
                  description: Locale code of your customer. This will be used to display payment page in correct language.
                custom_data:
                  type: string
                  format: json
                  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.
                eci:
                  type: integer
                  default: 7
                  maximum: 99
                  description: "\n **This parameter is specific to SEPA Direct Debit as well as credit\nor debit card payment products.**\n\nElectronic Commerce Indicator (ECI).\n\nThe ECI indicates the security level at which the payment information is processed between the cardholder and merchant.\n\n### Credit or debit card\n\nIf the payment product is a credit or debit card:\n\n- `1`: MO/TO (Mail Order/Telephone Order)\n- `2`: MO/TO – Recurring\n- `7`: E-commerce with SSL/TLS Encryption\n- `9`: Recurring E-commerce\n- `10`: TPE payment\n\nA default ECI value can be set in the preferences page. An ECI value sent along in the transaction will overwrite the default ECI value.\n\n### SEPA Direct Debit\n\nIf the payment product is SEPA Direct Debit:\n- `7`: First transaction/one-shot transaction\n- `9`: Recurring transaction"
                authentication_indicator:
                  type: integer
                  default: 0
                  description: '

                    **This parameter is specific to SEPA Direct Debit as well as credit or debit card payment products.**


                    ### Credit or debit card


                    If the payment product is a credit or debit card, this parameter indicates if the 3-D Secure authentication should be performed for this transaction.


                    - `0`: Bypass 3-D Secure authentication.


                    - `1`: 3-D Secure authentication if available.


                    - `2`: 3-D Secure authentication mandatory.


                    For more information about the 3-D Secure workflow, check the [HiPay Enterprise Overview](/online-payments/features/3ds).


                    ### SEPA Direct Debit


                    If the payment product is SEPA Direct Debit, this parameter indicates if the debit agreement (mandate) must be electronically signed or not.


                    - `0`: Bypass electronic signature.


                    - `1`: Ask for electronic signature.


                    For more information about the SEPA Direct Debit integration (including examples), check the [HiPay Enterprise Overview](/online-payments/payment-means/sepa-direct-debit).'
                expiration_limit:
                  type: string
                  default: '3'
                  description: '**This parameter is specific to provider COMPRAFACIL.**


                    Validity period of the payment code in days.'
                prepaid_card_number:
                  type: string
                  description: '**This parameter is specific to provider ONEY (Gift Card).**


                    Gift Card number.'
                prepaid_card_security_code:
                  type: string
                  description: '**This parameter is specific to provider ONEY (Gift Card).**


                    Gift Card CVC.'
                email:
                  type: string
                  description: The customer's e-mail address.
                phone:
                  type: string
                  description: The customer's phone number.
                msisdn:
                  type: string
                  format: phone
                  description: '

                    **This parameter is specific to the 3x and 4x Carte Bancaire payment products.**


                    The customer''s ship-to mobile phone number.'
                birthdate:
                  type: string
                  description: Birth date of the customer (YYYYMMDD). For fraud detection reasons.
                gender:
                  type: string
                  enum:
                  - U
                  - F
                  - M
                  default: U
                  description: 'Gender of the customer:


                    - `M`: male

                    - `F`: female

                    - `U`: unknown'
                firstname:
                  type: string
                  description: The customer's first name. This value will be use to pre-fill cardholder name on credit card payment form.
                lastname:
                  type: string
                  description: The customer's last name. This value will be use to pre-fill cardholder name on credit card payment form.
                card_holder:
                  type: string
                  description: '**This parameter is specific to provider PAYON.**


                    The customer''s card holder.'
                recipientinfo:
                  type: string
                  description: Additional information about the customer (e.g., quality or function, company name, department, etc.).
                house_extension:
                  type: string
                  description: House extension of the customer.
                house_number:
                  type: string
                  description: House number of the customer.
                streetaddress:
                  type: string
                  description: Street address of the customer.
                streetaddress2:
                  type: string
                  description: Additional address information of the customer (e.g., building, floor, flat, etc.).
                city:
                  type: string
                  description: The customer's city.
                state:
                  type: string
                  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).
                zipcode:
                  type: string
                  description: The zip or postal code of the customer.
                country:
                  type: string
                  maxLength: 2
                  pattern: ^[a-zA-Z]+$
                  description: The country code of the customer.
                shipto_firstname:
                  type: string
                  description: The first name of the order recipient.
                shipto_lastname:
                  type: string
                  description: The last name of the order recipient.
                shipto_recipientinfo:
                  type: string
                  description: Additional information about the order recipient (e.g., quality or function, company name, department, etc.).
                shipto_house_number:
                  type: string
                  description: House number of the recipient.
                shipto_streetaddress:
                  type: string
                  description: Street address to which the order is to be shipped.
                shipto_streetaddress2:
                  type: string
                  description: The additional information about address to which the order is to be shipped (e.g., building, floor, flat, etc.).
                shipto_city:
                  type: string
                  description: The city to which the order is to be shipped.
                shipto_state:
                  type: string
                  description: The USA state or Canada state to which the order is being shipped. Send this information only if the shipping country is US (USA) or CA (Canada).
                shipto_zipcode:
                  type: string
                  description: The zip or postal code to which the order is being shipped.
                shipto_country:
                  type: string
                  maxLength: 2
                  pattern: ^[a-zA-Z]+$
                  description: Country code to which the order is being shipped. This two-letter country code complies with ISO 3166-1 (alpha 2).
                device_fingerprint:
                  type: string
                  format: fingerprint
                  description: 'This element should contain the value of the ''ioBB'' hidden field.


                    For more information about the device fingerprint integration, check the [HiPay Enterprise Overview](/payment-fundamentals/requirements/device-fingerprint-integration).'
                source:
                  type: string
                  format: json
                  description: 'To identify the origin of the transaction. Here are the authorized values for source property:


                    - `AUTO`, `SAPI`, `CONS`, `PAGE`, `TPE`, `RTRY`, `MANU`, `PREF`, `REVI`, `CMS`, `SSDK`, `CSDK`'
                issuer_bank_id:
                  type: string
                  description: '**This parameter is specific to the iDEAL and the SEPA Direct Debit payment products.**


                    This is the Business Identifier Code (BIC) of the customer''s issuer bank.'
                shipto_gender:
                  type: string
                  enum:
                  - M
                  - F
                  - U
                  default: U
                  description: '

                    **This parameter is specific to the 3x and 4x Carte Bancaire payment products.**


                    Gender of the recipient:


                    - `M`: male

                    - `F`: female

                    - `U`: unknown'
                shipto_phone:
                  type: string
                  format: phone
                  description: '

                    **This parameter is specific to the 3x and 4x Carte Bancaire payment products.**


                    The recipient''s ship-to phone number.'
                shipto_msisdn:
                  type: string
                  format: phone
                  description: '

                    **This parameter is specific to the 3x and 4x Carte Bancaire payment products.**


                    The recipient''s ship-to mobile phone number.'
                order_category_code:
                  type: integer
                  description: '

                    **This parameter is specific to the 3x and 4x Carte Bancaire payment products.**


                    The order category code.


                    Please refer to the following list:


                    | Code | Description |

                    | --- | --- |

                    | 5499 | Alimentation & gastronomie

                    | 5571 | Auto & moto

                    | 7929 | Culture & divertissements

                    | 5261 | Maison & jardin

                    | 5200 | Electroménager

                    | 7278 | Enchères et achats groupés

                    | 5193 | Fleurs & cadeaux

                    | 5734 | Informatique & logiciels

                    | 7298 | Santé & beauté

                    | 0 | Services aux particuliers

                    | 7361 | Services aux professionnels

                    | 5941 | Sport

                    | 5651 | Vêtements & accessoires

                    | 4722 | Voyage & tourisme

                    | 5946 | Hifi, photo & vidéos

                    | 4812 | Téléphonie & communication'
                delivery_date:
                  type: string
                  format: date
                  description: '

                    **This parameter is specific to the 3x and 4x Carte Bancaire payment products.**


                    Estimated delivery date. Format is YYYY-MM-DD.'
                delivery_method:
                  type: string
                  description: '

                    **This parameter is specific to the 3x and 4x Carte Bancaire payment products.**`


                    The delivery method.'
                carrier_description:
                  type: string
                  format: json
                  description: '

                    **This parameter is specific to the 3x and 4x Carte Bancaire payment products.**


                    Carrier description.'
                recurring_payment:
                  type: integer
                  default: 0
                  maximum: 9
                  description: '

                    **This parameter is specific to the SEPA Direct Debit payment product.**


                    Indicates if the debit agreement will be created for a single-use or a multi-use.


                    Possible values:


                    - `0`: Generate a single-use agreement id.

                    - `1`: Generate a multi-use agreement id.'
                iban:
                  type: string
                  pattern: ^[a-zA-Z]{2}[0-9]{2}[ \.\-0-9a-zA-Z]{10,38}$
                  description: '

                    **This parameter is specific to the SEPA Direct Debit payment product.**


                    International Bank Account Number (IBAN).'
                bank_name:
                  type: string
                  description: '

                    **This parameter is specific to the SEPA Direct Debit payment product.**


                    Issuer Bank Name.'
                sales_channel:
                  type: string
                  format: numeric
                  description: 'Sales channel :


                    - `0`: Default.

                    - `1`: Ecommerce API.

                    - `2`: Hosted Payment Page.

                    - `3`: POS.'
                soft_descriptor:
                  type: string
                  description: Billing descriptor for machine learning.
                cardtoken:
                  type: string
                  format: words
                  description: '

                    **This parameter is specific to credit or debit card payment products.**


                    This is the token obtained from the HiPay Enterprise Secure Vault API when tokenizing a cre

# --- truncated at 32 KB (100 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/hipay/refs/heads/main/openapi/hipay-payments-api-openapi.yml