HiPay maintenance API
Perform operations (capture, refund) on transactions
OpenAPI Specification
openapi: 3.0.0
info:
title: Hipay Payment Gateway balance maintenance 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: maintenance
description: Perform operations (capture, refund) on transactions
paths:
/v1/maintenance/transaction/{transaction_reference}:
post:
tags:
- maintenance
summary: Performs a maintenance operation on a given transaction
description: Performs a maintenance operation on a given transaction.
operationId: performMaintenanceOperation
parameters:
- name: transaction_reference
in: path
description: The unique identifier of the transaction.
required: true
schema:
type: string
example: '800000420435'
x-sort: 1
requestBody:
description: Maintenance information
required: true
content:
multipart/form-data:
schema:
$ref: '#/components/schemas/Maintenance'
responses:
'200':
description: The maintenance operation was executed successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Operation'
'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'
'404':
description: Transaction was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
security:
- basicAuth: []
components:
schemas:
Operation:
title: Operation
description: Operation model
properties:
operation:
description: The operation to perform on the transaction.
type: string
enum:
- capture
- refund
- cancel
- acceptChallenge
- denyChallenge
example: capture
x-sort: 1
mid:
description: ''
type: string
example: 00001326589
x-sort: 5
authorizationCode:
description: ''
type: string
example: author
x-sort: 10
transactionReference:
description: ''
type: string
example: '800000968431'
x-sort: 15
status:
description: ''
type: string
example: '118'
x-sort: 35
message:
description: ''
type: string
example: Captured
x-sort: 40
dateCreated:
description: ''
type: string
example: 2019-02-07T10:07:09+0000
x-sort: 20
dateUpdated:
description: ''
type: string
example: 2019-02-07T10:07:09+0000
x-sort: 25
dateAuthorized:
description: ''
type: string
example: 2019-02-07T10:07:09+0000
x-sort: 30
authorizedAmount:
description: ''
type: string
example: '125.85'
x-sort: 45
capturedAmount:
description: ''
type: string
example: '125.85'
x-sort: 50
refundedAmount:
description: ''
type: string
example: '0.00'
x-sort: 55
decimals:
description: ''
type: string
example: '2'
x-sort: 60
currency:
description: ''
type: string
example: EUR
x-sort: 65
type: object
Maintenance:
title: Maintenance
description: Maintenance model
required:
- operation
properties:
operation:
description: "The operation to perform on the transaction.\n\n The payment gateway supports the following types of maintenance transactions.\n\n | Operation Type | Description |\n | -------------- | ----------- |\n | `capture` | A request instructing the payment gateway to capture a previously-authorized transaction, i.e. transfer the funds from the customer’s bank account to the merchant’s bank account. This transaction is always preceded by an authorization. |\n | `refund` | A request instructing the payment gateway to refund a previously captured transaction. A captured transaction can be partly or fully refunded. |\n | `cancel` | A request instructing the payment gateway to cancel a previously authorized transaction. Only authorized transactions can be cancelled, captured transactions must be refunded. |\n | `acceptChallenge` | A request instructing the payment gateway to accept a previously challenged transaction. |\n | `denyChallenge` | A request instructing the payment gateway to deny a previously challenged transaction. |\n | `finalize` | A request instructing the payment gateway to finalize an asynchronous operation. |"
type: string
enum:
- capture
- refund
- cancel
- acceptChallenge
- denyChallenge
- finalize
example: capture
x-sort: 1
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
example: EUR
additionalProperties:
default: EUR
x-sort: 5
amount:
description: Amount is required for partial maintenances. Do not specify amount for full captures or refunds.
type: string
example: '3.5'
x-sort: 10
operation_id:
description: Operation merchant ID. This value will be returned to merchant with the notifications related to this operation.
type: string
example: 204OJ23LKJ234
x-sort: 15
basket:
description: "Shopping cart details. **You must send only items that must be captured or refunded.**\n\n 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."
type: string
x-sort: 20
sub_transaction_reference:
description: Number of the subtransaction to be refunded.
type: string
example: '134470136955'
x-sort: 25
source:
description: "To identify the origin of the transaction. Here are the authorized values for source property:\n\n `AUTO`, `SAPI`, `CONS`, `PAGE`, `TPE`, `RTRY`, `MANU`, `PREF`, `REVI`, `CMS`, `SSDK`, `CSDK`"
type: string
example: '{"integration_version":"1.9.0","brand":"DEVPORTAL","source":"CSDK","brand_version":"12.2.0"}'
x-sort: 30
type: object
Error:
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
securitySchemes:
BasicAuth:
type: http
scheme: basic
ApiKeyAuth:
type: apiKey
name: X-API-KEY
in: header
externalDocs:
description: Find out more about HiPay
url: https://developer.hipay.com/