HiPay Transaction API
The Transaction API from HiPay — 6 operation(s) for transaction.
OpenAPI Specification
openapi: 3.0.0
info:
title: Hipay Payment Gateway balance Transaction 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: Transaction
paths:
/v3/transaction/{transaction_reference}:
get:
tags:
- Transaction
operationId: get_api_transaction_consultation_public
parameters:
- name: transaction_reference
in: path
description: The unique identifier of the transaction.
required: true
schema:
type: string
pattern: \d+
example: '800000420435'
responses:
'200':
description: Transaction retrieved successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Transaction'
'401':
description: An authentication error occurred/invalid credentials.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: This transaction is not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
security:
- ApiKeyAuth: []
- BasicAuth: []
/v3/transactions/{type}/{value}:
get:
tags:
- Transaction
operationId: get_api_transaction_consultations_by_type_public
parameters:
- name: type
in: path
required: true
schema:
type: string
pattern: arn|opid|acquirerid
enum:
- arn
- opid
- acquirerid
- name: value
in: path
required: true
schema:
type: string
responses:
'200':
description: Transactions retrieved successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/TransactionCollection'
'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'
'404':
description: No transaction found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
security:
- ApiKeyAuth: []
- BasicAuth: []
/v1/transaction/{transaction_reference}:
get:
tags:
- Transaction
summary: Gets details of existing transactions based on a transaction ID
description: Gets details of existing transactions based on a transaction ID.
operationId: getTransactionByReference
parameters:
- name: transaction_reference
in: path
description: The unique identifier of the transaction.
required: true
schema:
type: string
example: '800000420435'
x-sort: 1
responses:
'200':
description: Transaction retrieved successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/TransactionDetail'
'400':
description: The request was rejected due to a validation error.
content:
application/json:
schema:
$ref: '#/components/schemas/Error_2'
'401':
description: An authentication error occurred/invalid credentials.
content:
application/json:
schema:
$ref: '#/components/schemas/Error_2'
'403':
description: Access to this resource is fordidden.
content:
application/json:
schema:
$ref: '#/components/schemas/Error_2'
deprecated: true
security:
- basicAuth: []
/v1/transaction:
get:
tags:
- Transaction
summary: Gets details of existing transactions related to a given order
description: Gets details of existing transactions related to a given order. Deprecated, you can refer to [this page](https://developer.hipay.com/api-explorer/api-gateway#/transaction/get_api_consultation_transaction) for new endpoint
operationId: getTransactionsByReference
parameters:
- name: orderid
in: query
description: Merchant unique order id. Return all the transactions related to an order id.
required: true
schema:
type: string
example: ORDER_1487239265080
x-sort: 1
responses:
'200':
description: Transactions retrieved successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/TransactionDetail'
'400':
description: The request was rejected due to a validation error.
content:
application/json:
schema:
$ref: '#/components/schemas/Error_2'
'401':
description: An authentication error occurred/invalid credentials.
content:
application/json:
schema:
$ref: '#/components/schemas/Error_2'
'403':
description: Access to this resource is fordidden.
content:
application/json:
schema:
$ref: '#/components/schemas/Error_2'
deprecated: true
security:
- basicAuth: []
/transaction.{_format}:
get:
produces: []
consumes:
- multipart/form-data
summary: Get transactions list
description: '
### Information
Get transactions list.'
parameters:
- in: path
name: _format
required: true
type: string
enum:
- json
- xml
default: json
- in: query
description: 'Start of transaction date range. Accepted formats : yyyy-MM-dd HH:MM:ss and yyyy-MM-dd. Default date : 7 days ago. Default time : 00:00:00.'
name: start-date
type: string
default: '2018-01-31'
- in: query
description: 'End of transaction date range. Accepted formats : yyyy-MM-dd HH:MM:ss and yyyy-MM-dd. Default date : today. Default time : 23:59:59.
Interval between start-date and end-date cannot be greater than 3 months (92 days).
'
name: end-date
type: string
default: '2018-04-07'
- in: query
description: 'Number of results to display on each page. Cannot exceed 1000. Default : 20'
name: nb-result-per-page
type: integer
format: int32
default: 20
- in: query
description: 'Page number. First page has number 1. Default : 1'
name: page
type: integer
format: int32
default: 1
- in: query
description: 'Properties sorting configuration. Ex: sort-props[email]=asc&sort-props[status]=desc. Default : sort-props[captured]=desc'
name: sort-props
type: string
- description: Account ID if operations must be made on an account other than yours (you must have specific rights on this account).
in: header
name: php-auth-subaccount-id
type: integer
- description: Account login (email address) if operations must be made on an account other than yours (you must have specific rights on this account).
in: header
name: php-auth-subaccount-login
type: string
responses:
'200':
description: Success response.
schema:
properties:
code:
type: integer
format: int32
description: Status code of the answer.
message:
type: string
description: Description of the answer.
nb_result:
type: integer
format: int32
description: Total number of results matching search criterias
transactions_list:
type: array
items:
type: string
description: List of transactions
'400':
description: Validation failed.
'401':
description: Authentication failed.
tags:
- Transaction
security:
- basicAuth: []
/transaction/{id}.{_format}:
get:
produces: []
consumes:
- multipart/form-data
summary: Get transaction details
description: '
### Information
This request will send you the details of a requested transaction.'
parameters:
- in: path
name: id
description: HiPay transaction ID or Merchant reference of transaction ID to verify.
required: true
type: string
default: 5a71d61c6778932713
- in: path
name: _format
required: true
type: string
enum:
- json
- xml
default: json
- description: Account ID if operations must be made on an account other than yours (you must have specific rights on this account).
in: header
name: php-auth-subaccount-id
type: integer
- description: Account login (email address) if operations must be made on an account other than yours (you must have specific rights on this account).
in: header
name: php-auth-subaccount-login
type: string
responses:
'200':
description: Success response.
schema:
properties:
code:
type: integer
format: int32
description: Status code of the answer.
message:
type: string
description: Description of the answer.
transaction_id:
type: string
description: HiPay transaction ID.
amount:
type: number
format: float
description: Transaction amount.
currency:
type: string
description: Transaction currency.
creation_date:
type: string
description: Transaction creation date.
collect_date:
type: string
description: Transaction collect date.
transaction_status:
type: string
description: "### Actual status of the transaction\nTransaction type\n\n - `1`: feeding\n - `2`: external transfer\n - `3`: simple payment\n - `4`: direct payment\n - `5`: european withdrawal\n - `6`: other\n - `7`: international transfer\n - `8`: international withdrawal\n - `10`: affiliation transfer\n - `11`: tax transfer\n - `12`: identification transfer\n - `13`: direct donation\n - `14`: simple donation\n - `15`: payable reference payment\n - `16`: business contributor transfer\n - `17`: injection payment"
transaction_label:
type: string
description: Transaction label.
type:
type: string
description: Transaction type.
capture_date:
type: string
description: Transaction capture date.
issuer_email:
type: string
description: Issuer email.
recipient_email:
type: string
description: Recipient email.
subscription_id:
type: string
description: If a subscription is linked to the transaction, subscription ID.
merchant_reference:
type: string
description: Merchant reference sent to the transaction.
site_url:
type: string
description: Site URL linked to the transaction.
merchant_email:
type: string
description: Merchant Email.
site_name:
type: string
description: Website name.
fees:
type: string
description: Transaction fees.
currency_fees:
type: string
description: Currency linked to fees.
refusal_reason:
type: string
description: Refusal reason.
'400':
description: Validation failed.
'401':
description: Authentication failed.
tags:
- Transaction
security:
- basicAuth: []
components:
schemas:
Result3:
type: string
enum:
- NOT_LAUNCHED
- PENDING
- ACCEPTED
- REQUEST EXEMPTION
- BLOCKED
- CHALLENGED
- AUTHENTICATE
- FORCE_AUTHENTICATE
- OVERRIDE
- ACCEPT WITH NO PREFERENCE
- DENIED
- ALLOWED
reason:
title: Reason
description: Reason model
properties:
code:
description: ''
type: string
x-sort: 1
message:
description: ''
type: string
x-sort: 5
type: object
Preference:
type: integer
enum:
- 1
- 2
- 3
- 4
- 5
- 7
Issuer3:
properties:
fullname:
type: string
nullable: true
institution:
type: string
nullable: true
country:
type: string
nullable: true
type: object
Review3:
type: string
enum:
- ALLOWED
- PENDING
- DENIED
Address2:
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
Authentication4:
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/Authentication6'
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/Preference3'
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/ThreeDSAuthenticationMethod3'
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/ThreeDSAuthenticationLiability3'
type: object
ReasonCode:
properties:
code:
type: integer
nullable: true
reason:
type: string
nullable: true
type: object
paymentMethod:
title: Payment
description: Payment model
properties:
token:
description: ''
type: string
x-sort: 1
brand:
description: ''
type: string
x-sort: 5
pan:
description: ''
type: string
x-sort: 10
cardExpiryMonth:
description: ''
type: string
example: '03'
x-sort: 20
cardExpiryYear:
description: ''
type: string
example: '2020'
x-sort: 25
issuer:
description: 'Name of the financial institution that
issued the payment method.'
type: string
x-sort: 30
country:
description: The country code where payment method was issued.
type: string
example: US
x-sort: 35
cardHolder:
description: ''
type: string
example: JOHN DOE
x-sort: 15
type: object
ComputedAuthenticationStatus3:
type: string
enum:
- No authentication
- Abandoned strong authentication
- Unsuccessful authentication attempted
- Challenge authentication
- Frictionless authentication
- Successful authentication
- Failed authentication
- Unknown authentication
ThreeDSAuthenticationMethod3:
type: string
enum:
- challenge
- frictionless
- ''
Status6:
type: string
enum:
- available
- created
- error
- incomplete
- pending
- suspended
- terminated
CardEntryMode2:
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
Transaction_2:
title: Transaction
description: Transaction model
properties:
order:
type: object
allOf:
- $ref: '#/components/schemas/OrderResponse'
x-sort: 140
authorizationCode:
description: ''
type: string
example: author
x-sort: 25
dateCreated:
description: ''
type: string
example: 2019-02-07T10:07:09+0000
x-sort: 35
dateAuthorized:
description: ''
type: string
example: 2019-02-07T10:07:09+0000
x-sort: 45
authorizedAmount:
description: ''
type: string
example: '125.85'
x-sort: 60
decimals:
description: ''
type: string
example: '2'
x-sort: 80
currency:
description: ''
type: string
example: EUR
x-sort: 85
ipAddress:
description: ''
type: string
example: 0.0.0.0
x-sort: 90
ipCountry:
description: ''
type: string
example: 0.0.0.0
x-sort: 95
avsResult:
description: ''
type: string
x-sort: 105
cvcResult:
description: ''
type: string
x-sort: 110
threeDSecure:
type: object
allOf:
- $ref: '#/components/schemas/ThreeDSecure'
x-sort: 130
transactionReference:
description: Unique Transaction Identifier.
type: string
example: '800000790677'
x-sort: 30
attemptId:
description: Attempt identifier.
type: integer
example: '1'
x-sort: 20
dateUpdated:
description: 'Date of last status change.
This date must comply with ISO 8601.'
type: string
x-sort: 40
state:
description: Transaction state.
type: string
example: completed
x-sort: 1
mid:
description: 'Merchant id (MID).
Unique identifier assigned to the merchant.'
type: integer
x-sort: 15
capturedAmount:
description: Captured amount.
type: string
example: '125.75'
x-sort: 65
refundedAmount:
description: Refunded amount.
type: string
example: '00.00'
x-sort: 70
creditedAmount:
description: Total credited.
type: string
x-sort: 75
chargebackedAmount:
description: Chargebacked amount.
type: string
example: '125.75'
x-sort: 65
paymentProduct:
description: The payment product used for processing current transaction.
type: string
example: visa
x-sort: 120
paymentMethod:
description: The payment method used for processing current transaction.
type: object
allOf:
- $ref: '#/components/schemas/paymentMethod'
x-sort: 125
status:
description: Transaction status.
type: integer
example: '116'
x-sort: 50
reason:
description: The numeric value of the error.
type: object
allOf:
- $ref: '#/components/schemas/reason'
x-sort: 5
forwardUrl:
description: URL of the page on which to redirect the customer.
type: string
x-sort: 10
deviceId:
description: ''
type: string
x-sort: 100
fraudScreening:
description: Fraud screening result.
type: object
allOf:
- $ref: '#/components/schemas/fraud'
x-sort: 135
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'
x-sort: 115
debitAgreement:
type: object
allOf:
- $ref: '#/components/schemas/debitAgreement'
x-sort: 145
message:
type: string
x-sort: 55
type: object
OperationType3:
type: string
enum:
- CAPTURE
- CREDIT
- REFUND
- CHGBCK
- CHGBCK_REFUND
- RDR
Error_2:
title: Error
description: Error model
properties:
code:
description: Code
type: integer
x-sort: 1
message:
description: Message
type: string
x-sort: 5
description:
description: Description
type: string
x-sort: 10
type: object
TerminalInformation2:
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/CardEntryMode2'
file_number:
description: File number
type: string
nullable: true
type: object
fraud:
title: Fraud screening
description: Fraud screening model
properties:
scoring:
description: ''
type: string
example: '0'
x-sort: 1
result:
description: ''
type: string
example: ACCEPTED
x-sort: 5
review:
description: ''
type: string
example: ''
x-sort: 15
type: object
Authentication6:
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
Status:
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
Cvc3:
type: string
enum:
- Match
- No Match
- Not Processed
- Missing
- Not Supported
PaymentMethod3:
required:
- name
- description
properties:
name:
type: string
description:
type: string
type: object
ThreeDSAuthenticationLiability:
type: string
enum:
- issuer
- merchant
- not applicable
Transaction:
required:
- id
- attemptid
- merchant_order_id
- 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'
order:
nullable: true
oneOf:
- $ref: '#/components/schemas/Order2'
attemptid:
type: integer
merchant_order_id:
type: string
state:
$ref: '#/components/schemas/TransactionState'
status:
$ref: '#/components/schemas/Status'
computed_authentication_status:
description: Transaction computed authentication status.
example: Successful authentication
nullable: true
oneOf:
- $ref: '#/components/schemas/ComputedAuthentica
# --- truncated at 32 KB (74 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/hipay/refs/heads/main/openapi/hipay-transaction-api-openapi.yml