---
created: 2023-09-01T00:00
updated: 2024-04-25T14:23
author: ibelsa API team
title: ibelsaPay
---
# ibelsaPay
## Hosts
- __beta__: https://beta-rooms.ibelsa.com
- __production__: https://rooms.ibelsa.com
# 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}`
## 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`.
## Payload
| 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` |
### 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.
# 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}`
## 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`.
## Payload
| 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` |