Bavindo
  1. Payment
Bavindo
API
  • API
  • Webhook
  • v1
    • Terminal
      • POS Connected Terminals
    • Payment
      • POS Payment Create
        POST
      • POS Payment Cancel
        POST
      • Get Payment Details
        GET
      • POS Payment Refund Referenced
        POST
    • NFC
      • NFC Transaction Start/Continue
      • NFC Transaction Stop
  1. Payment

POS Payment Create

Developing
POST
https://api.bavindo.com/v1/payment/pos/create
INFO
This endpoint can be accessed with the following API type: pos-payment.
TIP
Don't have an API key? Create one in your Customer Area with the type pos-payment, go to Developers -> Api Credentials.
INFO
When creating a payment, the API key needs to have the same store ID as the linked Adyen POS terminal, otherwise it will fail to create a payment. Use Connected Terminals to get the linked terminals to a store.

Creating a POS Payment#

Please refer to the Body Params for every value you need to pass along.
A minimum payment amount of 35 cents needs to be met. This amount just deems as reserve for the payment fee. The payment fee is calculated afterwards by Adyen (after the payment is fulfilled).

Currency#

The amount of the payment is given in cents.
The only currency we support right now is EUR.

Synchronous method#

There are two options: asynchronous & synchronous. We strongly advise implementing the asynchronous method.

Receiving a synchronous result#

Your POS app needs to make HTTPS requests to the endpoint with the synchronous_method value sync. This request must use an extended timeout of more than 150 seconds. During this time the connection is kept alive, and a synchronous response will follow.
Optionally, show display notifications in your POS app. During a tender, the payment terminal generates display notifications. You can show these in your POS app to keep your staff up-to-date on the progress of the tender. For example, whether the customer has selected Dynamic Currency Conversion, or finished entering their PIN.

Receiving an asynchronous result#

Your POS app needs to make HTTPS requests to the endpoint with the synchronous_method value async. The time between making the request and receiving the event depends on the quality of the terminal's internet connection.
To asynchronously receive the actual Payment response, you need to set up event notifications. The terminal will send the Payment response over the webhook to your event webhook endpoint.
Optionally, show display notifications in your POS app. During a tender, the payment terminal generates display notifications. You can show these in your POS app to keep your staff up-to-date on the progress of the tender. For example, whether the customer has selected Dynamic Currency Conversion, or finished entering their PIN.

Check the payment status#

We recommend that your integration should automatically check the status of a payment any time it fails to receive a payment response.
Payment requests time out after a while. If you do not receive a payment response (or you receive a response indicating a time-out) after 150 seconds and the internet connection hasn't dropped, your integration should automatically check the payment status.
This can be done using the Get Payment Details endpoint.

Webhooks#

Event webhooks are only used for asynchronous payments, for synchronous and asynchronous payments the display webhook will still function if provided.
For an asynchronous payment an event webhook is required, a display webhook is optional.
To use a webhook you need to specify the type object in the webhook object.
event
display
In the type object, provide the url, authentication_type and the authentication type specific values.

Authentication types#

1.
bearer
token
2.
basic
username
password
3.
no_auth (We do not endorse this authentication type)
INFO
A detailed explanation of the webhooks can be found under the dropdown in the top left corner with the corresponding webhook.

Splits#

When a payment amount needs to be split between balance accounts or between different parties, you can easily provide a split on a per payment basis.
For a split to a specific balance account, you need a SpliToken that has the correct balance account configured. The SpliToken can be safely shared.

Configure a split#

Under the splits array, you can provide splits that are desired. These values are required in a split object:
splitoken Used to direct the funds to the correct balance account.
amount The amount in cents.
description This will be shown in your Customer Area under the payment.
The remaining of the split will be booked to the balance account specified in the API key.
The remaining amount always needs to be higher than the minimum payment amount.

Tipping#

Tipping is easily done by adding the object tip: {amount: *}.
When the amount is 0, it will ask on the terminal to enter their desired amount, that way the customer has full control.
When 0 is provided, and you have configured predefined tips in the terminal settings of the store or terminal, those options will be shown and can be picked right from the terminal display.
You can also provide the amount in cents, it will autofill the amount, and it will ask for confirmation on the terminal display.

Split#

Split the tip amount into a different balance account using the splitoken field.
tip: {amount: *, splitoken: "splitoken"}

Metadata#

Under the metadata value, you can store miscellaneous values. These values will be returned with the following:
Payment POS Create
Get Payment Details
Webhook event notifications
Webhook display notifications

Responses#

The Adyen response is wrapped in our response, for extra information on the Adyen response, please refer to these Adyen docs.

Response event statuses#

Asynchronous#

inprogress (200) A payment is started and ongoing
failure (400) Failed to create a payment

Synchronous#

success (200) A payment has been successfully paid
failure (400) Failed to create a payment OR A terminal has failed to complete the payment

Other scenarios#

When using the asynchronous method and a payment is still open on the terminal, and you start another payment, it will fail. But Adyen still returns a null (200) (while using the asynchronous method) so we are none the wiser, and thus we still send a inprogress (200), the failure will be immediately send via the event webhook afterwards.

Request

Authorization
Provide your bearer token in the
Authorization
header when making requests to protected resources.
Example:
Authorization: Bearer ********************
Body Params application/json
terminal_id
string <uuid>
required
The ID of the pysical Adyen terminal
Examples:
P400Plus-00000000SATURN-00000000
pos_id
string <uuid>
required
The ID of your POS unit
payment
object 
required
amount
integer 
required
The amount of what the payment should be in cents
>= 0
Examples:
10005000
currency
string <char>
required
The currency in which the payment should be (We only support what is provided in the examples)
Default:
EUR
Example:
EUR
webhook
object  | null 
optional
Webhooks are only required for async payments (For sync payments the event webhook will be disgarded)
event
object 
required
display
object 
optional
splits
array [object {3}] 
optional
When not using splits do not send this value preferably, this can also accept a empty array [] or null.
splitoken
string 
required
The splitoken associated to a balance account
Example:
3619c492f266264dc42651ed9b64cc5f5dbeb1e65b18ae08a5a7063f03a6aeff
amount
integer 
required
The amount in cents to split
Example:
100
description
string 
required
A description of the split
Example:
Fee conform contract
tip
object 
optional
amount
integer 
required
The amount in cents to tip or 0 to fill it in on the terminal display
Examples:
0250
splitoken
string 
optional
The splitoken associated to a balance account
metadata
object  | null 
optional
In the metadata you can provide an object that will be returned with every request
your_info
string 
optional
Example:
123456789
synchronous_method
string <char>
required
What type of synchronous method should we used (If possible only use async)
Examples:
asyncsync
Example
{
    "terminal_id": "P400Plus-00000000",
    "pos_id": "2697c7ff-139f-4d66-bdb1-14d458bc3aa2",
    "payment": {
        "amount": 1000,
        "currency": "EUR"
    },
    "webhook": {
        "event": {
            "url": "https://webhook.yourplatform.com/bavindo/event",
            "authentication_type": "bearer",
            "token": "39905c29c0e698e273c88f9f7292aa55a603a5de",
            "username": "username",
            "password": "6d56f6f3fa98f4689cacf868a99a7634a448d609"
        },
        "display": {
            "url": "https://webhook.yourplatform.com/bavindo/display",
            "authentication_type": "bearer",
            "token": "29dcbefce76fbc1a19785fa84c888fd4d29323a8",
            "username": "username",
            "password": "e9cb442897c7bb992b2b65e8424be009b04088e7"
        }
    },
    "splits": [
        {
            "splitoken": "3619c492f266264dc42651ed9b64cc5f5dbeb1e65b18ae08a5a7063f03a6aeff",
            "amount": 100,
            "description": "Fee conform contract"
        }
    ],
    "tip": {
        "amount": 0,
        "splitoken": "string"
    },
    "metadata": {
        "your_info": "123456789"
    },
    "synchronous_method": "async"
}

Responses

🟢200Asynchronous
application/json
Body
event_type
string 
required
The sent Adyen event message type
Examples:
service.payment.responseservice.payment.request
event
string 
required
Status of the payment request
Examples:
successfailure
event_condition
string  | null 
required
If event == failed a reason will be provided
payment_id
string 
required
The ID of your Payment, store this well to process the recieving webhooks and to use the Get Payment Details
store_id
string 
required
The Store ID associated with the API Key
terminal_id
string 
required
The ID of the pysical Adyen terminal
pos_id
string 
required
The ID of your POS unit
payment_amount
object 
required
currency
string 
required
The currency if the payment (ISO 4217)
Example:
EUR
amount
integer 
required
The amount of the goods (cents)
Example:
1000
amount_tip
integer 
required
The tip amount when given (cents)
Example:
50
amount_total
integer 
required
Amount + Tip = Total (cents)
Example:
1050
amount_refunded
integer 
required
Amount refunded (cents)
Example:
0
metadata
object  | null 
required
The metadata you provided
your_info
string 
required
adyen_response
object  | null 
required
The raw adyen response. When Asynchronous Adyen will return null on a successfull payment request.
SaleToPOIRequest
object 
required
adyen_error_log
array[string]
required
When an Adyen Exception happens on Bavindo's side the readable errors will be passed through
environment
string 
required
The environment the API key is working on
Examples:
testlive
Examples
{
    "event_type": "service.payment.request",
    "event": "inprogress",
    "event_condition": null,
    "payment_id": "766d4925-4e65-4c52-bbc7-90d63216",
    "store_id": "3294V22322755KZ6TWHGPRJ",
    "terminal_id": "P400Plus-000000000",
    "pos_id": "willekeurig",
    "payment_amount": {
        "currency": "EUR",
        "amount": 1000,
        "amount_tip": 50,
        "amount_total": 1050,
        "amount_refunded": 0
    },
    "metadata": {
        "your_info": "123456789"
    },
    "adyen_response": null,
    "environment": "test"
}
🟢200Synchronous
Modified at 2024-11-26 09:56:54
Previous
POS Connected Terminals
Next
POS Payment Cancel
Built with