Skip to content

Payments API 0.0.15-alpha.1

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

Diagnoses

Diagnose payment gateways

List Diagnoses

GET /diagnoses

Responses

  • 200

    OK

  • 400

    The server could not understand the request due to invalid syntax.

  • 500

    An unexpected error occurred on the server.

Diagnose Payment Gateway

POST /diagnoses

Diagnose the payment gateway

Request body

application/vnd.api+json · object

  • gatewayId (id) – Resource id
  • diagnoseType (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.

Responses

  • 202

    Diagnose in progress

  • 400

    The server could not understand the request due to invalid syntax.

  • 422

    The request body failed validation.

  • 500

    An unexpected error occurred on the server.

Get Diagnose

GET /diagnoses/{diagnoseId}

Parameters

  • diagnoseId (path, string (uuid), required)

Responses

  • 200

    OK

  • 404

    The requested resource could not be found.

  • 500

    An unexpected error occurred on the server.

Gateways

Manage payment gateways

Get Gateway Features

OPTIONS /gateways/{gatewayId}/featuresDeprecated

Get Information about which features are supported by a specific payment gateway

Parameters

  • gatewayId (path, string (uuid), required)

Responses

  • 200

    OK

  • 404

    The requested resource could not be found.

  • 500

    An unexpected error occurred on the server.

Gateway Status

GET /gateways/{gatewayId}/status

Gets information about the readiness of the payment gateway.

Parameters

  • gatewayId (path, string (uuid), required)

Responses

  • 200

    OK

  • 404

    The requested resource could not be found.

  • 500

    An unexpected error occurred on the server.

PaymentGuarantees

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.

List Payment Guarantees

GET /guarantees

List payment guarantees

Responses

  • 200

    Lists payment guarantees

  • 400

    The server could not understand the request due to invalid syntax.

  • 500

    An unexpected error occurred on the server.

Create Payment Guaranty

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.

Request body

application/vnd.api+json · Guaranty

  • id (string (uuid), required) – The generated UUID
  • createdAt (string (date-time), required) – Time of creation
  • updatedAt (string (date-time), required) – Time of last update
  • limit (integer, required) – the max amount the payment guaranty is for
  • currency (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 used
  • valid_to (string (date), required) – The latest point in time the guaranty can be used
  • reference (object)
  • type (string enum)

Responses

  • 201

    Guaranty created

  • 400

    The server could not understand the request due to invalid syntax.

  • 422

    The request body failed validation.

  • 500

    An unexpected error occurred on the server.

Show Guaranty

GET /guarantees/{guarantyId}

Get a single guaranty

Parameters

  • guarantyId (path, string, required)

Responses

  • 200

    Ok

  • 404

    The requested resource could not be found.

  • 500

    An unexpected error occurred on the server.

Overwrite Guaranty

PUT /guarantees/{guarantyId}

Updates the guaranty

Parameters

  • guarantyId (path, string, required)

Request body

application/vnd.api+json · Guaranty

  • id (string (uuid), required) – The generated UUID
  • createdAt (string (date-time), required) – Time of creation
  • updatedAt (string (date-time), required) – Time of last update
  • limit (integer, required) – the max amount the payment guaranty is for
  • currency (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 used
  • valid_to (string (date), required) – The latest point in time the guaranty can be used
  • reference (object)
  • type (string enum)

Responses

  • 204

    Updated

Delete Guaranty

DELETE /guarantees/{guarantyId}

Deletes a payment guaranty

Parameters

  • guarantyId (path, string, required)

Responses

  • 204

    Deleted

Intent

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.

List Intents

GET /intents

List all payment intents

Responses

  • 200

    A list of payment intents

  • 400

    The server could not understand the request due to invalid syntax.

  • 500

    An unexpected error occurred on the server.

Create Intent

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.

Request body

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.

Responses

  • 201

    Get a payment intent

  • 400

    The server could not understand the request due to invalid syntax.

  • 409

    The resource cannot be deleted because it is still referenced by other resources.

  • 422

    The request body failed validation.

  • 500

    An unexpected error occurred on the server.

Show Intent

GET /intents/{intentId}

Get payment intent details

Parameters

  • intentId (path, string (uuid), required)

Responses

  • 200

    Get a payment intent

  • 404

    The requested resource could not be found.

  • 500

    An unexpected error occurred on the server.

Abort Payment Intent

PUT /intents/{intentId}

Abort pending intent

Parameters

  • intentId (path, string (uuid), required)

Request body

application/vnd.api+json · object

  • status (string enum)

Responses

  • 204

    Payment deposit aborted

List intent logs

GET /logs

Lists intent log messages relative to the intent.
This endpoint is temporary and may be removed.

Responses

  • 200

    Lists intent log messages

  • 400

    The server could not understand the request due to invalid syntax.

  • 500

    An unexpected error occurred on the server.

Deposits

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.

List Deposits

GET /deposits

List all deposits

Responses

  • 200

    A list of deposits

  • 400

    The server could not understand the request due to invalid syntax.

  • 500

    An unexpected error occurred on the server.

Create Deposit

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.

Request body

application/vnd.api+json · DepositOrRefund

Responses

  • 201

    Get a deposit

  • 400

    The server could not understand the request due to invalid syntax.

  • 422

    The request body failed validation.

  • 500

    An unexpected error occurred on the server.

Show Deposit

GET /deposits/{depositId}

Get deposit details

Parameters

  • depositId (path, string (uuid), required)

Responses

  • 200

    Get a deposit

  • 404

    The requested resource could not be found.

  • 500

    An unexpected error occurred on the server.

RegisterCuts

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.

List register cuts

GET /register-cuts

List all register cut reports.

Register cuts are created by a createGatewayRegisterCut request.

Responses

  • 200

    OK

  • 400

    The server could not understand the request due to invalid syntax.

  • 500

    An unexpected error occurred on the server.

Register cut

POST /register-cuts

Create a register cut

Request body

application/vnd.api+json · object

  • gatewayId (id) – Resource id

Responses

  • 202

    OK

  • 400

    The server could not understand the request due to invalid syntax.

  • 422

    The request body failed validation.

  • 500

    An unexpected error occurred on the server.

Get register cut

GET /register-cuts/{registerCutId}

Get a register cut

Parameters

  • registerCutId (path, string, required)

Responses

  • 200

    OK

  • 404

    The requested resource could not be found.

  • 500

    An unexpected error occurred on the server.