--- created: 2023-09-01T00:00 updated: 2026-06-05T09:59 author: ibelsa API team title: ibelsaPay --- # ibelsaPay ## Hosts - __beta__: https://beta-rooms.ibelsa.com - __production__: https://rooms.ibelsa.com ## Authentication - **x-ibelsa-system-key**\ A partner-specific system key, required for authentication. It must be transmitted in the request header as `x-ibelsa-system-key`.
# Get activation status of the ibelsaPay module The endpoint provides the current activation status of the ibelsaPay module.\ Payments can only be made if `provider_status` is `ACTIVE` and `provider_settings_valid` is `true`.\ To avoid checking these two values separately, you can also simply check the aggregated field `payment_allowed` for `true`. ## Endpoint ### Method `GET` ### Route `/api/pay/status` ## Response parameters | Parameter | Type | Description | |-------------------------------|--------------------|------------------------------------------------------------------------------------------------------------------| | _**provider_status**_ | `string` | The current status of the active payment provider, possible values: `ACTIVE`, `INACTIVE`, `ORDERED`, `CANCELLED` | | _**provider_identifier**_ | `string` \| `null` | A unique identifier of the active payment provider | | _**provider_settings_valid**_ | `bool` | Indicates whether the payment provider's individual settings are valid and ready for processing payments | | _**payment_allowed**_ | `bool` | Aggregated field from `provider_status` and `provider_settings_valid` to easily check wheter processing payments is allowed | ## Example response ```json { "provider_status": "ACTIVE", "provider_identifier": "PAYMENT_FANZ", "provider_settings_valid": true, "payment_allowed": true } ```

# Paylink for third parties Through the **ibelsaAPI**, it is possible to direct the guest to a payment route to make a payment. This endpoint can only be used in conjunction with a system key assigned to the partner. This key is transmitted in the header as **x-ibelsa-system-key.** ## Endpoint ### Method `POST` ### Route `/api/pay/link/generate/{payment_provider}` ## Request parameters | Parameter | Type | Required | Default | Description | |----------------------------|----------|:--------:|:-------:|----------------------------------------------------------------------------------------------------------------------------| | _**folio_uuid**_ | `string` | yes | - | The unique UUID of the folio (not invoice) | | _**amount**_ | `string` | yes | - | The amount of the payment, ex. `'246.48'`
Must be >= `'0.50'` and must not exceed the outstanding amount of the folio | | _**pp_success_url**_ | `string` | yes | - | The full URL that the guest will be redirected to after a successful payment.
**This should not be used as webhook for payment feedback. Use `ibelsa_success_url` instead!** | | _**pp_fail_url**_ | `string` | yes | - | The full URL that the guest will be redirected to after a failed payment.
**This should not be used as webhook for payment feedback. Use `ibelsa_fail_url` instead!** | | _**pp_back_url**_ | `string` | yes | - | The full URL that the guest will be redirected to when he cancels the payment. | | _**ibelsa_success_url**_ | `string` | yes | - | The full URL that is called after a successful payment to inform about payment result. The URL should lead to the partner. | | _**ibelsa_fail_url**_ | `string` | no | - | The full URL that is called after a failed payment to inform about payment result. The URL should lead to the partner.
If not provided, the feedback for failed payments will also be sent to the `ibelsa_success_url` | ## Response parameters | Parameter | Type | Description | |----------------------|----------|-----------------------------------------| | _**url**_ | `string` | The payment link | | _**uuid**_ | `string` | A unique identifier of the payment link | | _**qrcode_b64_png**_ | `string` | A qrcode as a base64-encoded PNG image | ## Example response ```json { "success": true, "totalCount": 3, "data": { "data": { "url": "https://rooms.ibelsa.com/ibelsapay/fanz/pay_link/AbCdEfGhIjKlMnOpQrStUvWxYz/123", "uuid": "3758a06d-2c22-4ec9-bac3-c337e0c438df", "qrcode_b64_png": "qrcode_base64_abcdef12345" }, "success": true, "msg": "success" } } ``` ### The call is followed by the following actions. - A payment link from **the payment provider** is requested and registered in ibelsa. - The payment request returns a URL as a response. Calling up this URL leads to a redirect to the payment route of **the payment provider.** - In addition, the response also contains the payment URL as a QR code in the form of a base64-encoded PNG image. This way, the link can also be scanned on a mobile device and the payment path can be gone through there. - On the confirmation page of **the payment provider** there is a link that is linked to your pp_back_url. - At the end of the payment process, **the payment provider** will call up your pp_success_url if the payment was successful. - If the payment fails, the pp_failure_url is retrieved. - In addition, **the payment provider** informs **ibelsa** about the status of the payment. If the payment was successful the *ibelsa_success_url* is called and, the payment is created in the Folio. If the payments failed, the *ibelsa_fail_url* is called.

# Get payment terminals The endpoint provides all available payment terminals of the hotel, that are usable in kiosk systems. ## Endpoint ### Method `GET` ### Route `/api/pay/terminal/list/{payment_provider}` ## Request parameters | Parameter | Type | Required | Default | Description | |----------------------------|----------|:--------:|:-------:|:----------------------------------------------------------------| | _**payment_provider**_ | `string` | yes | - | Is part of the URL of this endpoint. Will be provided by ibelsa | ## Response parameters | Parameter | Type | Description | |---------------|-------------------------|:---------------------------------------------------------------------------------------| | _**online**_ | `array[TerminalObject]` | payment terminals that are currently online and available for processing payments | | _**offline**_ | `array[TerminalObject]` | payment terminals that are currently offline and not available for processing payments | \ **TerminalObject** | Parameter | Type | Description | |--------------------|----------|:--------------------------| | _**locationName**_ | `string` | location of the terminal | | _**readerId**_ | `string` | unique id of the terminal | | _**readerName**_ | `string` | name of the terminal | ## Example response ```json { "success": true, "totalCount": 2, "data": { "online": [ { "locationName": "Kiosk-Outside", "readerId": "S1EL-000150223502953", "readerName": "KO", }, { "locationName": "Kiosk-Inside", "readerId": "AMS1-000162340843992", "readerName": "KI", } ], "offline": [] } } ```

# Terminal payment for third parties Through the **ibelsaAPI**, it is possible to initiate a terminal payment. This endpoint can only be used in conjunction with a system key assigned to the partner. This key is transmitted in the header as **x-ibelsa-system-key.** ## Endpoint ### Method `POST` ### Route `/api/pay/terminal/payment/{payment_provider}` ## Request parameters | Parameter | Type | Required | Default | Description | |----------------------------|---------|:--------:|:-------:|:---------------------------------------------------------------------------------------------------------------------------| | _**payment_provider**_ | `string` | yes | - | Is part of the URL of this endpoint. Will be provided by ibelsa | | _**terminal**_ | `array` | yes | - | Data array describing the terminal as it is returned by [/api/doc#get--api-pay-terminal-list-{payment_provider}](/api/doc#get--api-pay-terminal-list-{payment_provider}).
Depending on the payment provider | | _**folio_uuid**_ | `string` | yes | - | The unique UUID of the folio (not invoice) | | _**amount**_ | `string` | yes | - | The amount of the payment, ex. `'246.48'`
Must be >= `'0.50'` and must not exceed the outstanding amount of the folio | | _**ibelsa_success_url**_ | `string` | yes | - | The full URL that is called after a successful payment to inform about payment result. The URL should lead to the partner. | | _**ibelsa_fail_url**_ | `string` | no | - | The full URL that is called after a failed payment to inform about payment result. The URL should lead to the partner.
If not provided, the feedback for failed payments will also be sent to the `ibelsa_success_url` |


# ibelsa_success_url & ibelsa_fail_url data The following data will be appended as GET parameter when ibelsa calls the provided `ibelsa_success_url` and `ibelsa_fail_url`: | Parameter | Type | Description | |---------------------------------|:------------:|------------------------------------------------------------------------------------------| | _**transactionId**_ | string | Provider transaction id | | _**pid**_ | string | Provider payment identifier | | _**paymentPid**_ | string | Payment identifier | | _**status**_ | string | The status of the payment: | | _**message**_ | string | Additional info from the payment provider | | _**paidAt**_ | number | The actual payment date in millis | | _**createdAt**_ | number | The initial creation date of the payment in millis | | _**terminalId**_ | string | If it was a terminal payment it will contain the id of the terminal used for the payment | | _**currency**_ | string | The currency of the payment, ex. `'EUR'`, `'USD'`, ... | | _**amount**_ | number | The amount of the payment as decimal, ex. `15.00` | | _**discount**_ | number | The discount amount as decimal, if applicable, ex. `1.0` | | _**tipAmount**_ | number | The tip amount as decimal, ex. `1.50` | | _**chargeAmount**_ | number | The amount including tip and discount as decimal, ex. `15.50` | | _**paymentMethodBrand**_ | string | Payment method identifier, ex. `'amex'`, `'mc_applepay'`, `'visa_applepay'`, `'cup'`, `'diners'`, `'discover'`, `'girocard'`, `'jcb'`, `'maestro'`, `'mc'`, `'paypal'`, `'visa'`, `'visadankort'`, `'vpay'`
If payment method cannot be determined `'card'` is provided as a fallback
Possible supported values may change | | _**paymentMethodAlignedBrand**_ | string | Payment method, ex. `'amex'`, `'applepay'`, `'cup'`, `'diners'`, `'discover'`, `'girocard'`, `'jcb'`, `'maestro'`, `'mastercard'`, `'paypal'`, `'visa'`, `'visadankort'`, `'vpay'`
If payment method cannot be determined `'card'` is provided as a fallback
Possible supported values may change | | _**paymentMethodSource**_ | string\|null | Payment method type, ex. `'CREDIT'`, `'DEBIT'`, `null` |