HiPay Order API
The Order API from HiPay — 2 operation(s) for order.
OpenAPI Specification
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
- Con
# --- truncated at 32 KB (51 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/hipay/refs/heads/main/openapi/hipay-order-api-openapi.yml