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 Refund Referenced

Developing
POST
https://api.bavindo.com/v1/payment/pos/refund/referenced
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 cancelling a payment, the API key needs to have the same store ID a the payment itself.

Refunding a referenced POS payment#

To return funds to a shopper after a payment is Approved, you need to refund the payment. Referenced refunds are connected to the original payment, using the unique identifier of that payment (payment_id).
You can make a:
Full refund to return the total value of the purchase to the shopper.
(In talks with Adyen to provide this option) Partial refund to return part of the purchase to the shopper. For example, when a shopper returns one of the items they purchased. You can also make multiple partial refunds. For example, when a shopper returns several items at different times.
It can take up to 40 business days for the funds to be returned to the shopper's account, depending on the payment method.

Refund authorization#

Refund authorization means that before processing a refund, Adyen checks with the issuer if the shopper's card or account is valid. This happens automatically; you do not have to ask for this in your refund request.
Adyen supports this for:
American Express
Discover
Mastercard
Visa
As soon as the issuer authorizes the refund, the refund is visible on the shopper's account. This improves customer satisfaction and reduces the number of questions from shoppers about their refund. Also, there are less refund-related chargebacks because issuers usually return the funds to the shopper sooner.
Issuers can decline a refund authorization for reasons like:
Lost or expired card
Invalid card number
Closed account
Suspected fraud
When a refund authorization is declined, Adyen still tries to process the refund.

Terminal & Point of sale#

By default a refund will make use of the same terminal_id and pos_id as the original payment. How ever you can provide new values.
A refund can be processed on a different terminal_id but the terminal needs to be online, as Adyen processes the refund on a terminal device.

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.

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 response, you need to set up event notifications. The terminal will send the response over the webhook to your event webhook endpoint.

Check the payment status#

We recommend that your integration should automatically check the status of a payment any time it fails to receive a response.
Refund requests time out after a while. If you do not receive a 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 refund requests.
For an asynchronous refund request an event webhook is required.
To use a webhook you need to specify the type object in the webhook object.
event
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.

Request

Authorization
Provide your bearer token in the
Authorization
header when making requests to protected resources.
Example:
Authorization: Bearer ********************
Body Params application/json
payment_id
string <uuid>
required
The ID of your Payment to refund
Example:
de0be7da-bf1d-4b0a-863f-b212cc92
pos_id
string <uuid> | null 
optional
The ID of your POS unit
terminal_id
string <uuid> | null 
optional
The ID of the pysical Adyen terminal
Example:
P400Plus-000000000
webhook
object  | null 
required
Webhooks are only required for async refunds (For sync refunds the event webhook will be disgarded)
event
object 
required
synchronous_method
string <char>
required
What type of synchronous method should we used (If possible only use async)
Examples:
asyncsync
Example
{
    "payment_id": "de0be7da-bf1d-4b0a-863f-b212cc92",
    "pos_id": "2697c7ff-139f-4d66-bdb1-14d458bc3aa2",
    "terminal_id": "P400Plus-000000000",
    "webhook": {
        "event": {
            "url": "https://webhook.yourplatform.com/bavindo/event",
            "authentication_type": "bearer",
            "token": "39905c29c0e698e273c88f9f7292aa55a603a5de",
            "username": "username",
            "password": "6d56f6f3fa98f4689cacf868a99a7634a448d609"
        }
    },
    "synchronous_method": "async"
}

Responses

🟢200Asynchronous
application/json
Body
event_type
string 
required
The sent Adyen event message type
Example:
service.reversal.request
event
string 
required
Status of the refund request
Examples:
inprogressfailure
event_condition
null 
required
If event == failed a reason will be provided
payment_id
string 
required
The ID of your Payment
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:
1050
metadata
object  | null 
required
The metadata you provided
your_info
string 
required
adyen_response
object  | null 
required
The raw adyen response
SaleToPOIResponse
object 
required
environment
string 
required
The environment the API key is working on
Examples
{
    "event_type": "service.reversal.request",
    "event": "inprogress",
    "event_condition": null,
    "payment_id": "796b7a75-bc19-4220-971e-1719bd03",
    "store_id": "3294V22322755KZ6TWHGPRJ",
    "terminal_id": "P400Plus-000000000",
    "pos_id": "willekeurig",
    "payment_amount": {
        "currency": "EUR",
        "amount": 1000,
        "amount_tip": 50,
        "amount_total": 1050,
        "amount_refunded": 1050
    },
    "metadata": {
        "your_info": "123456789"
    },
    "adyen_response": null,
    "environment": "test"
}
🟢200Synchronous
Modified at 2024-11-28 09:25:28
Previous
Get Payment Details
Next
NFC Transaction Start/Continue
Built with