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

NFC Transaction Start/Continue

Developing
POST
https://api.bavindo.com/v1/nfc
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 NFC Transaction, the API key needs to have the same store ID as the linked Adyen POS terminal, otherwise it will fail to create a NFC transaction. Use Connected Terminals to get the linked terminals to a store.

Start/Continue NFC Transaction#

Near Field Communication (NFC) tags can be cards, phones, bracelets, or similar. They can store data and are commonly used for contactless payments, loyalty programs, festival entrance, and more.
By sending a Terminal API card acquisition request to your Adyen payment terminal, you can identify the type of NFC tag, or read and write data to it.
For more complex use cases, you can create a session to present multiple requests as a single user interaction. For example, in a single session, you could identify the NFC tag, read its balance, and write the new balance on the tag.
To understand how you can use this, here are some examples:
Enrol shoppers in a loyalty program.
Identify a customer when entering an area such as festival grounds or a parking garage.
Check the balance and top up NFC tags such as loyalty and transport cards, or festival tags used to pay for drinks.
Define multiple behaviours of the NFC tag. For example, use the tag to enter one event and reuse it to pay for drinks at a different event.

Supported products (Still needs to be enabled by Adyen)#

The following NFC tags can be used on Adyen payment terminals:
MIFARE Classic (DISABLED)
MIFARE DESFire (DISABLED)
MIFARE Ultralight, Ultralight C, and Ultralight AES (DISABLED)
NFC tags are not supported on UX300 and UX410 payment terminals.
For NFC cards that require keys to read and write from are currently not supported. Hopefully in the furture we do.

How it works#

1.
Use this request to identify, read, or write to an NFC tag, specify the action using the nfc_instruction.
For more complex use cases that require multiple requests, see Create a session (Adyen docs).
2.
The terminal prompts the user to present their NFC tag or NFC-enabled card.
3.
The user presents their NFC tag by tapping, inserting, or swiping.
4.
The terminal makes one or multiple read/write requests to the NFC tag. While this is going on, the terminal shows the loading screen: One moment or Keep card inserted if the customer inserted their NFC-enabled card into the terminal.
5.
To stop a NFC request use the NFC Transaction Stop request.

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

Webhooks#

For an asynchronous NFC Transaction 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.

nfc_instruction? => Adyen Docs#

Refer to the Adyen Docs to what to do with nfc_instruction as this is effectively SaleToPOIData in the Adyen request. In our API Request you do not need to base64 and json encode the field. There are also detailed responses of what you would get in the adyen_response.
So what you would need to learn from the Adyen Docs are the following:
How to use the SaleToPOIData and place the content in the nfc_instruction field without a base64 and json encode.
Identify the type of NFC Tag
Read data
Write data
Create a session
When to stop the loading screen (Stop NFC Transaction) after applying your business logic, and display your business logic relevant information.

Response#

Response event statuses#

Asynchronous#

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

Synchronous#

success (200) A NFC Transaction has been successful
failure (400) Failed to create a NFC Transaction OR the NFC Transaction has failed

Request

Authorization
Provide your bearer token in the
Authorization
header when making requests to protected resources.
Example:
Authorization: Bearer ********************
Body Params application/json

Example
{"pos_id":"willekeurig","terminal_id":"P400Plus-00000000","synchronous_method":"async","webhook":{"event":{"url":"https://webhook.yourplatform.com/bavindo/event","authentication_type":"bearer","token":"39905c29c0e698e273c88f9f7292aa55a603a5de","username":"username","password":"6d56f6f3fa98f4689cacf868a99a7634a448d609"}},"nfc_instruction":{"Operation":[{"Type":"NFCReadUID"}]}}

Responses

🟢200Asynchronous
application/json
Body

Examples
{
    "event_type": "service.cardacquisition.request",
    "event": "inprogress",
    "event_condition": null,
    "store_id": "3294V22322755KZ6TWHGPRJ",
    "terminal_id": "P400Plus-00000000",
    "pos_id": "willekeurig",
    "metadata": null,
    "adyen_response": null,
    "adyen_error_log": [],
    "environment": "test"
}
🟢200Synchronous
Modified at 2024-11-11 19:09:15
Previous
POS Payment Refund Referenced
Next
NFC Transaction Stop
Built with