List Diagnoses
GET /diagnoses
Responses
200OK
400The server could not understand the request due to invalid syntax.
500An unexpected error occurred on the server.
Manage payments: Add, list, update and delete payments.
Integrate credit card terminals: Directly communicate with hardware based credit card terminals with one common API.
Integrate with payment gateways: Handle payments through e-commerce payment gateways and route them through one common interface.
Servers: https://hotelplatform.io/api/v2
Diagnose payment gateways
GET /diagnoses
200OK
400The server could not understand the request due to invalid syntax.
500An unexpected error occurred on the server.
POST /diagnoses
Diagnose the payment gateway
application/vnd.api+json · object
gatewayId (id) – Resource iddiagnoseType (DiagnoseType) – The type of diagnose that can be performed on a gateway.
For ZVT terminals these map to the specification's one-based `1B` values: `standard` and
`network` both to `01`, the line diagnosis. ZVT has no separate network test; the line
diagnosis is the connection test. `extended` maps to `02`, `configuration` to `03`, `emv`
to `04` and `ep2` to `05`.
`ep2` is the Swiss payment standard EP2 and is unrelated to `emv`, despite sitting next to
it in the list.
202Diagnose in progress
400The server could not understand the request due to invalid syntax.
422The request body failed validation.
500An unexpected error occurred on the server.
GET /diagnoses/{diagnoseId}
diagnoseId (path, string (uuid), required) 200OK
404The requested resource could not be found.
500An unexpected error occurred on the server.
Manage payment gateways
OPTIONS /gateways/{gatewayId}/featuresDeprecated
Get Information about which features are supported by a specific payment gateway
gatewayId (path, string (uuid), required) 200OK
404The requested resource could not be found.
500An unexpected error occurred on the server.
GET /gateways/{gatewayId}/status
Gets information about the readiness of the payment gateway.
gatewayId (path, string (uuid), required) 200OK
404The requested resource could not be found.
500An unexpected error occurred on the server.
Amounts hold as guarantees
This is work in progress - Preview only
Add guarantees as a method to collect order amounts at a later point in time. Can be used to connect tokenized credit card data with a reservation or similar order.
GET /guarantees
List payment guarantees
200Lists payment guarantees
400The server could not understand the request due to invalid syntax.
500An unexpected error occurred on the server.
POST /guarantees
This endpoint is work in progress and for preview only. Add a payment guaranty. This endpoint is usually used from pci compliant systems to add tokenized guarantees.
application/vnd.api+json · Guaranty
id (string (uuid), required) – The generated UUIDcreatedAt (string (date-time), required) – Time of creationupdatedAt (string (date-time), required) – Time of last updatelimit (integer, required) – the max amount the payment guaranty is forcurrency (Iso4217CurrencyCode, required) – Three alphabetic caracters representing the currency according to the [Iso4217 standards](https://www.iso.org/standard/64758.html).gatewayId (string (uuid), required)token (string, required) – token reference required to exchange the guaranty to a deposit.valid_from (string (date), required) – The earliest point in time the guaranty can be usedvalid_to (string (date), required) – The latest point in time the guaranty can be usedreference (object)type (string enum)201Guaranty created
400The server could not understand the request due to invalid syntax.
422The request body failed validation.
500An unexpected error occurred on the server.
GET /guarantees/{guarantyId}
Get a single guaranty
guarantyId (path, string, required) 200Ok
404The requested resource could not be found.
500An unexpected error occurred on the server.
PUT /guarantees/{guarantyId}
Updates the guaranty
guarantyId (path, string, required) application/vnd.api+json · Guaranty
id (string (uuid), required) – The generated UUIDcreatedAt (string (date-time), required) – Time of creationupdatedAt (string (date-time), required) – Time of last updatelimit (integer, required) – the max amount the payment guaranty is forcurrency (Iso4217CurrencyCode, required) – Three alphabetic caracters representing the currency according to the [Iso4217 standards](https://www.iso.org/standard/64758.html).gatewayId (string (uuid), required)token (string, required) – token reference required to exchange the guaranty to a deposit.valid_from (string (date), required) – The earliest point in time the guaranty can be usedvalid_to (string (date), required) – The latest point in time the guaranty can be usedreference (object)type (string enum)204Updated
DELETE /guarantees/{guarantyId}
Deletes a payment guaranty
guarantyId (path, string, required) 204Deleted
To start a payment process, you need to create a payment intent. A payment intent is a request to start a payment process. A payment intent may or may not follow through. If the payment intent is not followed through, it will be aborted. There can be various reasons for this, such as the customer not having enough funds on their account or the payment gateway not being available.
Before one can create a payment intent, a payment gateway configuration must be created. This is done through the configuration API.
GET /intents
List all payment intents
200A list of payment intents
400The server could not understand the request due to invalid syntax.
500An unexpected error occurred on the server.
POST /intents
Start an intent to make a payment or refund.
Payment intents are expressed in positive amounts in the lowest currency unit.
Refunds are expressed in negative amount in the lowest currency unit.
A rollback will be performed if the refund is the total amount of the payment, the last payment on the gateway and no register cut has been performed.
All intents are auto commit by default. If the acquirer requests confirmation to finalize the intent to a deposit, it will be auto confirmed / auto committed.
One intent at a time per gateway. A gateway drives a terminal, and a terminal serves one transaction at a time, so an intent for a gateway that is already processing one is refused with 409 rather than queued behind it. Queuing would leave the intent looking as though it were under way while the terminal is showing a different amount. Wait for the running intent to reach a final status, then start this one again.
An intent that is accepted returns immediately with status processing; the terminal interaction continues afterwards. Its outcome arrives as an intent.updated event, or on a later read of the intent.
A refund that cannot run is refused with 422 and not stored. The errorCode member of the problem details says why:
originalIntentIdMissing: originalIntentId is not set.originalIntentNotFound: no payment intent has that id.originalIntentNotRefundable: the intent is not a payment, has no settled deposit, was reversed, or the refund amount is more than is left to refund on it.An intent in a currency its gateway does not take is refused with 422 and not stored, errorCode currencyNotSupported, the error at /currency. A terminal works in the one currency its gateway configuration names (hobex, Adyen, ZVT and TIM): it would refuse another currency only once the guest is at the terminal, or charge the amount in its own currency. The comparison ignores case. A gateway whose configuration names no currency takes any.
application/vnd.api+json · PaymentOrRefund
The gatewayId property is required to indicate which payment gateway should be used. It corresponds to the id of a payment gateway configuration created through the configuration API.
You may set the externalId property to your internal reference.
If the gateway has its own menu and supports multiple languages, you can set the languageproperty to indicate the correct menu language.
201Get a payment intent
400The server could not understand the request due to invalid syntax.
409The resource cannot be deleted because it is still referenced by other resources.
422The request body failed validation.
500An unexpected error occurred on the server.
GET /intents/{intentId}
Get payment intent details
intentId (path, string (uuid), required) 200Get a payment intent
404The requested resource could not be found.
500An unexpected error occurred on the server.
PUT /intents/{intentId}
Abort pending intent
intentId (path, string (uuid), required) application/vnd.api+json · object
status (string enum)204Payment deposit aborted
GET /logs
Lists intent log messages relative to the intent.
This endpoint is temporary and may be removed.
200Lists intent log messages
400The server could not understand the request due to invalid syntax.
500An unexpected error occurred on the server.
A deposit is a payment that has been completed.
A positive deposit is referred to as payment, while a negative deposit is referred to as a refund.
GET /deposits
List all deposits
200A list of deposits
400The server could not understand the request due to invalid syntax.
500An unexpected error occurred on the server.
POST /deposits
Payments are expressed in positive amounts in the lowest currency unit.
Refunds are expressed in negative amount in the lowest currency unit.
Authorized payment intents are converted into new deposits. Most deposits are final but the acquirer can still revert it.
application/vnd.api+json · DepositOrRefund
201Get a deposit
400The server could not understand the request due to invalid syntax.
422The request body failed validation.
500An unexpected error occurred on the server.
GET /deposits/{depositId}
Get deposit details
depositId (path, string (uuid), required) 200Get a deposit
404The requested resource could not be found.
500An unexpected error occurred on the server.
Manage register cuts
Register cuts can usually only be created for hardware based credit card terminals. After a register cut is created, all deposits are submitted to the acquirer for settlement. After this point its not possible to rollback or refund payments. If you don't make a register cut, you won't be credited for the deposits until the next register cut. The terminal or payment service provider may trigger a register cut automatically, in which case you will not have access to the register cut report through this interface.
Usually a register cut is done once a day at the end of the business day.
A register cut is usually scheduled to be done at a specific time, but can also be triggered manually.
GET /register-cuts
List all register cut reports.
Register cuts are created by a createGatewayRegisterCut request.
200OK
400The server could not understand the request due to invalid syntax.
500An unexpected error occurred on the server.
POST /register-cuts
Create a register cut
application/vnd.api+json · object
gatewayId (id) – Resource id202OK
400The server could not understand the request due to invalid syntax.
422The request body failed validation.
500An unexpected error occurred on the server.
GET /register-cuts/{registerCutId}
Get a register cut
registerCutId (path, string, required) 200OK
404The requested resource could not be found.
500An unexpected error occurred on the server.