Are you looking for test card numbers?

Would you like to contact support?

Point-of-sale icon

NFC tags read and write

Read and write data on NFC tags using Adyen payment terminals.

NFC (near field communication) 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:

  • Enroll 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

The following NFC tags can be used on Adyen payment terminals:

  • MIFARE Classic
  • MIFARE DESFire
  • MIFARE Ultralight and Ultralight C

How it works

To use NFC tags on Adyen payment terminals, first you need to contact our POS Support Team to create a configuration for your use case. Usually, this includes:

  • The type of NFC tag you want to use, for example MIFARE Classic.
  • For NFC tags that have keys, you need to supply the keys you want to use to access data.

After the configuration is created:

  1. Make a card acquisition request to identify, read, or write to an NFC tag.

    For more complex use cases that require multiple requests, see Create a session.

  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.

Identify the type of NFC tag

You can use the card acquisition request to get the unique identifier and the type of the NFC tag. You can use this identifier, for example, to check if the NFC tag exists in your system or if it is still valid.

  1. Create an Operation JSON object with Operation.Type: NFCReadUID:

    Operation JSON object
    {
       "Operation":[
          {
             "Type":"NFCReadUID"
          }
       ]
    }
  2. Encode the Operation JSON object to Base64. You will pass the resulting string in SaleData.SaleToPOIData.

    Converted to a Base64-encoded string
    ewogICAgIk9wZXJhdGlvbiI6WwogICAgICAgIHsKICAgICAgICAgICAgIlR5cGUiOiJORkNSZWFkVUlEIgogICAgICAgIH0KICAgIF0KfQ==
  3. Make a POST request to a Terminal API endpoint, specifying:

    • CardAcquisitionRequest.SaleData:

      Parameter Required Description
      SaleTransactionID -white_check_mark- An object with:
      • TransactionID: your reference to identify the transaction. We recommend using a unique value.
      • TimeStamp: date and time of the request in UTC format.
      SaleToPOIData The Base64-encoded Operation JSON object.
    • CardAcquisitionRequest.CardAcquisitionTransaction:

      Parameter Required Description
      TotalAmount The transaction amount. You can omit the TotalAmount field when getting the UID of the NFC tag.
      If you omit TotalAmount, you still have to include an empty CardAcquisitionTransaction field in the request.

    The example below shows a card acquisition request to identify the NFC tag:

    Identify NFC tag request
    {
        "SaleToPOIRequest":{
            "MessageHeader":{
                "ProtocolVersion":"3.0",
                "MessageClass":"Service",
                "MessageCategory":"CardAcquisition",
                "MessageType":"Request",
                "ServiceID":"1020711110",
                "SaleID":"POSSystemID12345",
                "POIID":"V400m-346403161"
            },
            "CardAcquisitionRequest":{
                "SaleData":{
                    "SaleTransactionID":{
                        "TransactionID":"02072",
                        "TimeStamp":"2020-01-07T14:14:04+00:00"
                    },
                    "SaleToPOIData":"ewogICAgIk9wZXJhdGlvbiI6WwogICAgICAgIHsKICAgICAgICAgICAgIlR5cGUiOiJORkNSZWFkVUlEIgogICAgICAgIH0KICAgIF0KfQ=="
                },
                "CardAcquisitionTransaction":{
                }
            }
        }
    }
  4. In the AdditionalResponse of the CardAcquisitionResponse note:

    • NFC.uid: the unique identifier of the NFC tag.
    • NFC.variant: the type of the NFC tag, for example mf_classic for MIFARE Classic.
    Identify NFC tag response
    {
        "SaleToPOIResponse":{
            "CardAcquisitionResponse":{
                "POIData":{
                    "POIReconciliationID": "1000",
                    "POITransactionID":{
                        "TimeStamp": "2022-10-10T12:50:31.000Z",
                        "TransactionID": "CglQ001665406231000"
                    }
                },
                "PaymentInstrumentData":{
                    "CardData": {},
                    "PaymentInstrumentType": "Card"
                },
                "Response":{
                    "AdditionalResponse": "...NFC.uid=96924E37...NFC.variant=mf_classic...",
                    "Result": "Success"
                },
                "SaleData":{
                    "SaleTransactionID":{
                        "TimeStamp": "2022-10-03T10:56:42.198Z",
                        "TransactionID": "729"
                    }
                }
            },
            "MessageHeader": {...}
        }
    }

    After you have identified the NFC tag, the loading screen continues to show until you send an EnableServiceRequest (see the next step).

  5. To stop the loading screen, make a POST request to a Terminal API endpoint, specifying:

    • EnableServiceRequest with:

      Parameter Required Description
      TransactionAction -white_check_mark- AbortTransaction.
      DisplayOutput Optional object to show your own message and an 'Approved' icon (green check mark) or a 'Declined' icon (red cross).
      If you omit DisplayOutput, the terminal shows Canceled, a red cross , and Transaction canceled.

    The following example is the basic request, without the DisplayOutput object, to stop the card acquisition flow.

    Basic request to cancel the card acquisition data
    {
       "SaleToPOIRequest":{
          "MessageHeader":{
             "ProtocolVersion":"3.0",
             "MessageClass":"Service",
             "MessageCategory":"EnableService",
             "MessageType":"Request",
             "ServiceID":"3020711110",
             "SaleID":"POSSystemID12345",
             "POIID":"V400m-346403161"
          },
          "EnableServiceRequest":{
             "TransactionAction":"AbortTransaction"
          }
       }
    }

Read data

NFC tags have multiple parts that can store data. Because the data structure is different for every NFC tag type, the request needs to specify where to read the data from. For some tags, you need to include the key to read data from a sector, aid, orpage.
Select a tab to see the parameters that you need to specify to read data from MIFARE Classic, MIFARE DESFire, or MIFARE Ultralight.

  1. Create an Operation JSON object and specify:

    Parameter Required Description
    Type -white_check_mark- NFCRead: reads data from the specified sector.
    Variant -white_check_mark- MifareClassic: the type of NFC tag.
    NFCData -white_check_mark-
    If you leave the NFCData array empty, the terminal will try to read all sectors.
    An array with:
    • sector: specifies what sector on MifareClassic to read from.
    • keyType: specifies what key is used to access a sector, a (default) or b.
      You cannot use keyType: b on Android terminals due to a limitation from Castles.
    Structure of Operation object for read data request - MIFARE Classic
    {
        "Operation":[
            {
                "Type":"NFCRead",
                "Variant":"MifareClassic",
                "NFCData":[
                    {
                        "sector":1,
                        "keyType":"a"
                    },
                    {
                        "sector":2,
                        "keyType":"b"
                    }
                ]
            }
        ]
    }
  2. Encode the Operation JSON object to Base64. You will pass the resulting string in SaleData.SaleToPOIData.

    Converted to a Base64-encoded string
    ewogICAgIk9wZXJhdGlvbiI6WwogICAgICAgIHsKICAgICAgICAgICAgIlR5cGUiOiJORkNSZWFkIiwKICAgICAgICAgICAgIlZhcmlhbnQiOiJNaWZhcmVDbGFzc2ljIiwKICAgICAgICAgICAgIk5GQ0RhdGEiOlsKICAgICAgICAgICAgICAgIHsKICAgICAgICAgICAgICAgICAgICAic2VjdG9yIjoxLAogICAgICAgICAgICAgICAgICAgICJrZXlUeXBlIjoiYSIKICAgICAgICAgICAgICAgIH0sCiAgICAgICAgICAgICAgICB7CiAgICAgICAgICAgICAgICAgICAgInNlY3RvciI6MiwKICAgICAgICAgICAgICAgICAgICAia2V5VHlwZSI6ImIiCiAgICAgICAgICAgICAgICB9CiAgICAgICAgICAgIF0KICAgICAgICB9CiAgICBdCn0=
  3. Make a POST request to a Terminal API endpoint, specifying:

    • CardAcquisitionRequest.SaleData:

      Parameter Required Description
      SaleTransactionID -white_check_mark- An object with:
      • TransactionID: your reference to identify the transaction. We recommend using a unique value.
      • TimeStamp: date and time of the request in UTC format.
      SaleToPOIData The Base64-encoded Operation JSON object.
    • CardAcquisitionRequest.CardAcquisitionTransaction:

      Parameter Required Description
      TotalAmount The transaction amount. You can omit the TotalAmount field when reading the NFC tag.
      If you omit TotalAmount, you still have to include an empty CardAcquisitionTransaction field in the request.

    The example below shows a card acquisition request to read data from sectors 1 and 2 on a MifareClassic NFC tag:

    Read data request - MIFARE Classic
    {
        "SaleToPOIRequest":{
            "MessageHeader":{
                "ProtocolVersion":"3.0",
                "MessageClass":"Service",
                "MessageCategory":"CardAcquisition",
                "MessageType":"Request",
                "ServiceID":"282",
                "SaleID":"POSSystemID12345",
                "POIID":"V400m-346403161"
            },
            "CardAcquisitionRequest":{
                "SaleData":{
                    "SaleTransactionID":{
                        "TransactionID":"369",
                        "TimeStamp":"2021-03-05T12:22:57.449Z"
                    },
                    "SaleToPOIData":"ewogICAgIk9wZXJhdGlvbiI6WwogICAgICAgIHsKICAgICAgICAgICAgIlR5cGUiOiJORkNSZWFkIiwKICAgICAgICAgICAgIlZhcmlhbnQiOiJNaWZhcmVDbGFzc2ljIiwKICAgICAgICAgICAgIk5GQ0RhdGEiOlsKICAgICAgICAgICAgICAgIHsKICAgICAgICAgICAgICAgICAgICAic2VjdG9yIjoxLAogICAgICAgICAgICAgICAgICAgICJrZXlUeXBlIjoiYSIKICAgICAgICAgICAgICAgIH0sCiAgICAgICAgICAgICAgICB7CiAgICAgICAgICAgICAgICAgICAgInNlY3RvciI6MiwKICAgICAgICAgICAgICAgICAgICAia2V5VHlwZSI6ImIiCiAgICAgICAgICAgICAgICB9CiAgICAgICAgICAgIF0KICAgICAgICB9CiAgICBdCn0="
                },
                "CardAcquisitionTransaction":{
                }
            }
        }
    }
  4. When the card acquisition succeeds, in the AdditionalResponse of the CardAcquisitionResponse note:

    • NFC.data: the data from the specified sectors.
      • For a single sector, the data shows as NFC.data=afafafafafafafafafa....
      • For multiple sectors, the data from each sector shows as value of the NFC.data for that sector, for example: NFC.data.S01=afafafafafafafafafa, NFC.data.S02=2222222222222222.
    • NFC.status: the status of the read action for every sector, for example NFC.status=s01.OKs02.OKS03.AUTH_ERROR.
    • NFC.uid: the unique identifier of the NFC tag.
    • NFC.variant: the type of the NFC tag, in this case MIFARE Classic.
    Read data response - MIFARE Classic
    {
        "SaleToPOIResponse":{
            "CardAcquisitionResponse":{
                "POIData":{
                    "POIReconciliationID":"1000",
                    "POITransactionID":{
                        "TimeStamp":"2022-10-17T11:35:04.000Z",
                        "TransactionID":"CglQ001666006504012"
                    }
                },
                "PaymentInstrumentData":{
                    "CardData":{
                    },
                    "PaymentInstrumentType":"Card"
                },
                "Response":{
                    "AdditionalResponse":"tid=47353332&transactionType=GOODS_SERVICES&giftcardIndicator=false&posAmountGratuityValue=0&store=YourStore&iso8601TxDate=2022-10-17T11%3a35%3a04.733Z&posOriginalAmountValue=0&txtime=13%3a35%3a04&NFC.data.S01=AFAFAFAFAFAFAFAF&NFC.uid=96924E37&txdate=17-10-2022&NFC.data.S02=2222222222222222&merchantReference=868&posadditionalamounts.originalAmountCurrency=EUR&NFC.ref=mifareClassicCard&posAuthAmountCurrency=EUR&message=CARD_ACQ_COMPLETED&posAmountCashbackValue=0&NFC.variant=mf_classic&posEntryMode=CLESS_SWIPE&NFC.status=S01.OKS02.OK&posAuthAmountValue=0",
                    "Result":"Success"
                },
                "SaleData":{
                    "SaleTransactionID":{
                        "TimeStamp":"2022-10-03T10:56:42.966Z",
                        "TransactionID":"868"
                    }
                }
            },
            "MessageHeader":{
                "MessageCategory":"CardAcquisition",
                "MessageClass":"Service",
                "MessageType":"Response",
                "POIID":"V400m-346403161",
                "ProtocolVersion":"3.0",
                "SaleID":"POSSystemID12345",
                "ServiceID":"40"
            }
        }
    }

    After you have read the specified sectors on the NFC tag, the loading screen continues to show until you send an EnableServiceRequest (see the next step).

  5. To stop the loading screen, make a POST request to a Terminal API endpoint, specifying:

    • EnableServiceRequest with:

      Parameter Required Description
      TransactionAction -white_check_mark- AbortTransaction.
      DisplayOutput Optional object to show your own message and an 'Approved' icon (green check mark) or a 'Declined' icon (red cross).
      If you omit DisplayOutput, the terminal shows Canceled, a red cross , and Transaction canceled.

    The following example is the basic request, without the DisplayOutput object, to stop the card acquisition flow.

    Basic request to cancel the card acquisition data
    {
       "SaleToPOIRequest":{
          "MessageHeader":{
             "ProtocolVersion":"3.0",
             "MessageClass":"Service",
             "MessageCategory":"EnableService",
             "MessageType":"Request",
             "ServiceID":"3020711110",
             "SaleID":"POSSystemID12345",
             "POIID":"V400m-346403161"
          },
          "EnableServiceRequest":{
             "TransactionAction":"AbortTransaction"
          }
       }
    }

Write data

NFC tags have multiple parts that can store data. Because the data structure is different for every NFC tag type, the request needs to specify the sector, aid, or page where to write the data to.
Select a tab to see the parameters that you need to specify to write data to MIFARE Classic, MIFARE DESFire, or MIFARE Ultralight.

  1. Create an Operation JSON object and specify:

    Parameter Required Description
    Type -white_check_mark- NFCWrite: writes data to the specified sector.
    Variant -white_check_mark- MifareClassic: specifies the type of NFC tag used.
    NFCData -white_check_mark-
    If you leave the NFCData array empty when trying to write, the response will return the UID and the variant but will not write to the card.
    An array specifying:
    • sector: specifies the sector to write to.
    • keyType: specifies what key is used to write to a sector, a (default) or b.
      You cannot use keyType: b on Android terminals due to a limitation from Castles.
    • data: data to write in the specified sector.
    Structure of Operation object for write data request - Mifare Classic
    {
       "Operation":[
           {
               "Type":"NFCWrite",
               "Variant":"MifareClassic",
               "NFCData":[
                   {
                       "sector":1,
                       "data":"afafafafafafafafafafafafafafafafafafafafafafafafafafafafafafafafafafafafafafafafafafafafafafafaf"
                   },
                   {
                       "sector":2,
                       "data":"afafafafafafafafafafafafafafafafafafafafafafafafafafafafafafafafafafafafafafafafafafafafafafafaf",
                       "keyType":"b"
                   }
               ]
           }
       ]
    }
  2. Encode the Operation JSON object to Base64. You will pass the resulting string in SaleData.SaleToPOIData.

    Converted to a Base64-encoded string
    ewogICAgIk9wZXJhdGlvbiI6WwogICAgICAgIHsKICAgICAgICAgICAgIlR5cGUiOiJORkNXcml0ZSIsCiAgICAgICAgICAgICJWYXJpYW50IjoiTWlmYXJlQ2xhc3NpYyIsCiAgICAgICAgICAgICJORkNEYXRhIjpbCiAgICAgICAgICAgICAgICB7CiAgICAgICAgICAgICAgICAgICAgInNlY3RvciI6MSwKICAgICAgICAgICAgICAgICAgICAiZGF0YSI6ImFmYWZhZmFmYWZhZmFmYWZhZmFmYWZhZmFmYWZhZmFmYWZhZmFmYWZhZmFmYWZhZmFmYWZhZmFmYWZhZmFmYWZhZmFmYWZhZmFmYWZhZmFmYWZhZmFmYWZhZmFmYWZhZiIKICAgICAgICAgICAgICAgIH0sCiAgICAgICAgICAgICAgICB7CiAgICAgICAgICAgICAgICAgICAgInNlY3RvciI6MiwKICAgICAgICAgICAgICAgICAgICAiZGF0YSI6ImFmYWZhZmFmYWZhZmFmYWZhZmFmYWZhZmFmYWZhZmFmYWZhZmFmYWZhZmFmYWZhZmFmYWZhZmFmYWZhZmFmYWZhZmFmYWZhZmFmYWZhZmFmYWZhZmFmYWZhZmFmYWZhZiIsCiAgICAgICAgICAgICAgICAgICAgImtleVR5cGUiOiJiIgogICAgICAgICAgICAgICAgfQogICAgICAgICAgICBdCiAgICAgICAgfQogICAgXQp9
  3. Make a POST request to a Terminal API endpoint, specifying:

    • CardAcquisitionRequest.SaleData:

      Parameter Required Description
      SaleTransactionID -white_check_mark- An object with:
      • TransactionID: your reference to identify the transaction. We recommend using a unique value.
      • TimeStamp: date and time of the request in UTC format.
      SaleToPOIData The Base64-encoded Operation JSON object.
    • CardAcquisitionRequest.CardAcquisitionTransaction:

      Parameter Required Description
      TotalAmount The transaction amount. You can omit the TotalAmount field when writing to the NFC tag.
      If you omit TotalAmount, you still have to include an empty CardAcquisitionTransaction field in the request.

    The example below shows a card acquisition request to write data to sectors 1 and 2 on a MifareClassic NFC tag:

    Write data request - MIFARE Classic
    {
        "SaleToPOIRequest":{
            "MessageHeader":{
                "ProtocolVersion":"3.0",
                "MessageClass":"Service",
                "MessageCategory":"CardAcquisition",
                "MessageType":"Request",
                "ServiceID":"283",
                "SaleID":"POSSystemID12345",
                "POIID":"V400m-346403161"
            },
            "CardAcquisitionRequest":{
                "SaleData":{
                    "SaleTransactionID":{
                        "TransactionID":"369",
                        "TimeStamp":"2021-03-05T12:22:57.449Z"
                    },
                    "TokenRequestedType":"Customer",
                    "SaleToPOIData":"ewogICAgIk9wZXJhdGlvbiI6WwogICAgICAgIHsKICAgICAgICAgICAgIlR5cGUiOiJORkNXcml0ZSIsCiAgICAgICAgICAgICJWYXJpYW50IjoiTWlmYXJlQ2xhc3NpYyIsCiAgICAgICAgICAgICJORkNEYXRhIjpbCiAgICAgICAgICAgICAgICB7CiAgICAgICAgICAgICAgICAgICAgInNlY3RvciI6MSwKICAgICAgICAgICAgICAgICAgICAiZGF0YSI6ImFmYWZhZmFmYWZhZmFmYWZhZmFmYWZhZmFmYWZhZmFmYWZhZmFmYWZhZmFmYWZhZmFmYWZhZmFmYWZhZmFmYWZhZmFmYWZhZmFmYWZhZmFmYWZhZmFmYWZhZmFmYWZhZiIKICAgICAgICAgICAgICAgIH0sCiAgICAgICAgICAgICAgICB7CiAgICAgICAgICAgICAgICAgICAgInNlY3RvciI6MiwKICAgICAgICAgICAgICAgICAgICAiZGF0YSI6ImFmYWZhZmFmYWZhZmFmYWZhZmFmYWZhZmFmYWZhZmFmYWZhZmFmYWZhZmFmYWZhZmFmYWZhZmFmYWZhZmFmYWZhZmFmYWZhZmFmYWZhZmFmYWZhZmFmYWZhZmFmYWZhZiIsCiAgICAgICAgICAgICAgICAgICAgImtleVR5cGUiOiJiIgogICAgICAgICAgICAgICAgfQogICAgICAgICAgICBdCiAgICAgICAgfQogICAgXQp9"
                },
                "CardAcquisitionTransaction":{
                }
            }
        }
    }
  4. When the card acquisition succeeds, in the AdditionalResponse of the CardAcquisitionResponse note:

    • NFC.data: the data written to the specified sectors.
      • For a single sector, the data shows as NFC.data=afafafafafafafafafa....
      • For multiple sectors, the data from each sector shows as value of the NFC.data for that sector, for example: NFC.data.S01=afafafafafafafafafa, NFC.data.S02=2222222222222222.
    • NFC.status: the status of the write action for every sector, for example NFC.status=s01.OKs02.OKS03.AUTH_ERROR.
    • NFC.uid: the unique identifier of the NFC tag.
    • NFC.variant: the type of the NFC tag, in this case MIFARE Classic.
    Write data response - MIFARE Classic
    {
        "SaleToPOIResponse":{
            "CardAcquisitionResponse":{
                "POIData":{
                    "POIReconciliationID":"1000",
                    "POITransactionID":{
                        "TimeStamp":"2022-10-18T08:17:51.000Z",
                        "TransactionID":"CglQ001666081071002"
                    }
                },
                "PaymentInstrumentData":{
                    "CardData":{
                    },
                    "PaymentInstrumentType":"Card"
                },
                "Response":{
                    "AdditionalResponse":"tid=47353332&transactionType=GOODS_SERVICES&giftcardIndicator=false&posAmountGratuityValue=0&store=YourStore&iso8601TxDate=2022-10-18T08%3a17%3a51.591Z&posOriginalAmountValue=0&txtime=10%3a17%3a51&NFC.uid=96924E37&txdate=18-10-2022&merchantReference=889&posadditionalamounts.originalAmountCurrency=EUR&NFC.ref=mifareClassicCard&posAuthAmountCurrency=EUR&message=CARD_ACQ_COMPLETED&NFC.data.1=AFAFAFAFAFAFAFAF&posAmountCashbackValue=0&NFC.data.2=AFAFAFAFAFAFAFAF&NFC.variant=mf_classic&posEntryMode=CLESS_SWIPE&NFC.status=S01.OKS02.OK&posAuthAmountValue=0",
                    "Result":"Success"
                },
                "SaleData":{
                    "SaleTransactionID":{
                        "TimeStamp":"2022-10-03T10:56:42.966Z",
                        "TransactionID":"889"
                    }
                }
            },
            "MessageHeader":{
                "MessageCategory":"CardAcquisition",
                "MessageClass":"Service",
                "MessageType":"Response",
                "POIID":"V400m-346403161",
                "ProtocolVersion":"3.0",
                "SaleID":"POSSystemID12345",
                "ServiceID":"833"
            }
        }
    }

    After you write to the specified sectors on the NFC tag, the loading screen continues to show until you send an EnableServiceRequest (see the next step).

  5. To stop the loading screen, make a POST request to a Terminal API endpoint, specifying:

    • EnableServiceRequest with:

      Parameter Required Description
      TransactionAction -white_check_mark- AbortTransaction.
      DisplayOutput Optional object to show your own message and an 'Approved' icon (green check mark) or a 'Declined' icon (red cross).
      If you omit DisplayOutput, the terminal shows Canceled, a red cross , and Transaction canceled.

    The following example is the basic request, without the DisplayOutput object, to stop the card acquisition flow.

    Basic request to cancel the card acquisition data
    {
       "SaleToPOIRequest":{
          "MessageHeader":{
             "ProtocolVersion":"3.0",
             "MessageClass":"Service",
             "MessageCategory":"EnableService",
             "MessageType":"Request",
             "ServiceID":"3020711110",
             "SaleID":"POSSystemID12345",
             "POIID":"V400m-346403161"
          },
          "EnableServiceRequest":{
             "TransactionAction":"AbortTransaction"
          }
       }
    }

Create a session

If your use case requires multiple read/write actions on an NFC tag, you can create a session to make multiple requests part of the same user interaction. While the session is in progress, the terminal shows the One moment screen.

To start the session you need to add Session.Type: Begin in the SaleToPOIData of your first identify, read, or write request. You then send multiple requests and, to finish the session, you add Session.Type: End in the SaleToPOIData of the last request. All requests that belong to the session must contain the same Session.Id in the SaleToPOIData.
When the session ends, the terminal continues to show the loading screen until you send an EnableServiceRequest.

Here's an example of a session that consists of 3 card acquisition requests:

Step 1: Start a session and identify the NFC tag type

When starting the session, you need specify the Id to connect the requests into a single session. Here's example of how identify the tag and start the session:

  1. Create a JSON object with:

    Parameter Required Description
    Session.Type -white_check_mark- Begin: starts the session.
    Session.Id -white_check_mark- Your unique reference of the session.
    Session.Timeout -white_check_mark-
    • How long the One moment screen is shown on the terminal display, in milliseconds.
    • If there is no end session request, how long before the session data is deleted and new requests can be sent.
    Operation.Type -white_check_mark- NFCReadUID: returns the NFC tag identifier and type.
    JSON object
    {
        "Session": {
            "Type": "Begin",
            "Id": "50",
            "TimeoutMs": "60000"
        },
        "Operation":[
            {
                "Type":"NFCReadUID"
            }
        ]
    }
  2. Encode the JSON object to Base64. You will pass the resulting string in SaleData.SaleToPOIData.

    Converted to a Base64-encoded string
    ewogICAgIlNlc3Npb24iOnsKICAgICAgICAiVHlwZSI6IkJlZ2luIiwKICAgICAgICAiSWQiOiI1MCIsCiAgICAgICAgIlRpbWVvdXRNcyI6IjYwMDAwIgogICAgfSwKICAgICJPcGVyYXRpb24iOlsKICAgICAgICB7CiAgICAgICAgICAgICJUeXBlIjoiTkZDUmVhZFVJRCIKICAgICAgICB9CiAgICBdCn0=
  3. Make a card acquisition request with the Base64-encoded string in the SaleToPOIData.

    Start a session and identify the NFC tag type
    {
        "SaleToPOIRequest":{
            "MessageHeader":{
                "ProtocolVersion":"3.0",
                "MessageClass":"Service",
                "MessageCategory":"CardAcquisition",
                "MessageType":"Request",
                "ServiceID":"1020711110",
                "SaleID":"POSSystemID12345",
                "POIID":"V400m-346403161"
            },
            "CardAcquisitionRequest":{
                "SaleData":{
                    "SaleTransactionID":{
                        "TransactionID":"02072",
                        "TimeStamp":"2020-01-07T14:14:04+00:00"
                    },
                    "SaleToPOIData":"ewogICAgIlNlc3Npb24iOnsKICAgICAgICAiVHlwZSI6IkJlZ2luIiwKICAgICAgICAiSWQiOiI1MCIsCiAgICAgICAgIlRpbWVvdXRNcyI6IjYwMDAwIgogICAgfSwKICAgICJPcGVyYXRpb24iOlsKICAgICAgICB7CiAgICAgICAgICAgICJUeXBlIjoiTkZDUmVhZFVJRCIKICAgICAgICB9CiAgICBdCn0="
                },
                "CardAcquisitionTransaction":{
    
                }
            }
        }
    }

Step 2: Send read data request with Session.Id

Make sure to include the Session.Id specified in the SaleToPOIData of the first request. Here's example of how to read data from MIFARE Classic as part of the session:

  1. Create a JSON object with:

    Parameter Required Description
    Session.Id -white_check_mark- Your unique reference of the session, specified in the first request.
    Operation.Type -white_check_mark- NFCRead: reads data from the specified sector.
    Operation.Variant -white_check_mark- MifareClassic: the type of NFC tag.
    Operation.NFCData -white_check_mark-
    If you leave the NFCData array empty, the terminal will try to read all sectors.
    An array with:
    • sector: specifies what sector on MifareClassic to read from.
    • keyType: specifies what key is used to access a sector, a (default) or b.
      You cannot use keyType: b on Android terminals due to a limitation from Castles.
    JSON object
    {
        "Session":{
            "Id":"50"
        },
        "Operation":[
            {
                "Type":"NFCRead",
                "Variant":"MifareClassic",
                "NFCData":[
                    {
                        "sector":1,
                        "keyType":"a"
                    }
                ]
            }
        ]
    }
  2. Encode the JSON object to Base64. You will pass the resulting string in SaleData.SaleToPOIData.

    Converted to a Base64-encoded string
    ewogICAgIlNlc3Npb24iOnsKICAgICAgICAiSWQiOiI1MCIKICAgIH0sCiAgICAiT3BlcmF0aW9uIjpbCiAgICAgICAgewogICAgICAgICAgICAiVHlwZSI6Ik5GQ1JlYWQiLAogICAgICAgICAgICAiVmFyaWFudCI6Ik1pZmFyZUNsYXNzaWMiLAogICAgICAgICAgICAiTkZDRGF0YSI6WwogICAgICAgICAgICAgICAgewogICAgICAgICAgICAgICAgICAgICJzZWN0b3IiOjEsCiAgICAgICAgICAgICAgICAgICAgImtleVR5cGUiOiJhIgogICAgICAgICAgICAgICAgfQogICAgICAgICAgICBdCiAgICAgICAgfQogICAgXQp9
  3. Make a card acquisition request with the Base64-encoded string in the SaleToPOIData.
    The example below shows how to read data from MifareClassic NFC tag as part of the session:

    Read data request with Sessions.Id
    {
        "SaleToPOIRequest":{
            "MessageHeader":{
                "ProtocolVersion":"3.0",
                "MessageClass":"Service",
                "MessageCategory":"CardAcquisition",
                "MessageType":"Request",
                "ServiceID":"282",
                "SaleID":"POSSystemID12345",
                "POIID":"V400m-346403161"
            },
            "CardAcquisitionRequest":{
                "SaleData":{
                    "SaleTransactionID":{
                        "TransactionID":"369",
                        "TimeStamp":"2021-03-05T12:22:57.449Z"
                    },
                    "TokenRequestedType":"Customer"
                },
                "SaleToPOIData":"ewogICAgIlNlc3Npb24iOnsKICAgICAgICAiSWQiOiI1MCIKICAgIH0sCiAgICAiT3BlcmF0aW9uIjpbCiAgICAgICAgewogICAgICAgICAgICAiVHlwZSI6Ik5GQ1JlYWQiLAogICAgICAgICAgICAiVmFyaWFudCI6Ik1pZmFyZUNsYXNzaWMiLAogICAgICAgICAgICAiTkZDRGF0YSI6WwogICAgICAgICAgICAgICAgewogICAgICAgICAgICAgICAgICAgICJzZWN0b3IiOjEsCiAgICAgICAgICAgICAgICAgICAgImtleVR5cGUiOiJhIgogICAgICAgICAgICAgICAgfQogICAgICAgICAgICBdCiAgICAgICAgfQogICAgXQp9",
                "CardAcquisitionTransaction":{
                }
            }
        }
    }

Step 3: Write data to the NFC tag and end the session

In the final request of the interaction, make sure to include the same Session.Id and Session.Type: End. Here's example of how to write data to MIFARE Classic and end the session:

  1. Create a JSON object with:

    Parameter Required Description
    Session.Type -white_check_mark- End: ends the session.
    Session.Id -white_check_mark- Your unique reference of the session.
    Operation.Type -white_check_mark- NFCWrite: reads data from the specified sector.
    Operation.Variant -white_check_mark- MifareClassic: the type of NFC tag.
    Operation.NFCData -white_check_mark-
    If you leave the NFCData array empty when trying to write, the response will return the UID and the variant but will not write to the card.
    An array with:
    • sector: specifies what sector on MifareClassic to read from.
    • keyType: specifies what key is used to access a sector, a (default) or b.
      You cannot use keyType: b on Android terminals due to a limitation from Castles.
    JSON object
    {
        "Session":{
            "Type": "End",
            "Id":"50"
        },
        "Operation":[
            {
                "Type": "NFCWrite",
                "Variant": "MifareClassic",
                "NFCData":[
                    {
                        "sector": 1,
                        "data":"..."
                    }
                ]
            }
        ]
    }
  2. Encode the JSON object to Base64. You will pass the resulting string in SaleData.SaleToPOIData.

    Converted to a Base64-encoded string
    ewogICAgIlNlc3Npb24iOnsKICAgICAgICAiVHlwZSI6IkVuZCIsCiAgICAgICAgIklkIjoiNTAiCiAgICB9LAogICAgIk9wZXJhdGlvbiI6WwogICAgICAgIHsKICAgICAgICAgICAgIlR5cGUiOiJORkNXcml0ZSIsCiAgICAgICAgICAgICJWYXJpYW50IjoiTWlmYXJlQ2xhc3NpYyIsCiAgICAgICAgICAgICJORkNEYXRhIjpbCiAgICAgICAgICAgICAgICB7CiAgICAgICAgICAgICAgICAgICAgInNlY3RvciI6MSwKICAgICAgICAgICAgICAgICAgICAiZGF0YSI6Ii4uLiIKICAgICAgICAgICAgICAgIH0KICAgICAgICAgICAgXQogICAgICAgIH0KICAgIF0KfQ==
  3. Make a card acquisition request with the Base64-encoded string in the SaleToPOIData.
    The example below shows how to write data MifareClassic NFC tag and end the session:

    Write data to the NFC tag and end the session
    {
        "SaleToPOIRequest":{
            "MessageHeader":{
                "ProtocolVersion":"3.0",
                "MessageClass":"Service",
                "MessageCategory":"CardAcquisition",
                "MessageType":"Request",
                "ServiceID":"283",
                "SaleID":"POSSystemID12345",
                "POIID":"V400m-346403161"
            },
            "CardAcquisitionRequest":{
                "SaleData":{
                    "SaleTransactionID":{
                        "TransactionID":"369",
                        "TimeStamp":"2021-03-05T12:22:57.449Z"
                    },
                    "TokenRequestedType":"Customer"
                },
                "SaleToPOIData":"ewogICAgIlNlc3Npb24iOnsKICAgICAgICAiVHlwZSI6IkVuZCIsCiAgICAgICAgIklkIjoiNTAiCiAgICB9LAogICAgIk9wZXJhdGlvbiI6WwogICAgICAgIHsKICAgICAgICAgICAgIlR5cGUiOiJORkNXcml0ZSIsCiAgICAgICAgICAgICJWYXJpYW50IjoiTWlmYXJlQ2xhc3NpYyIsCiAgICAgICAgICAgICJORkNEYXRhIjpbCiAgICAgICAgICAgICAgICB7CiAgICAgICAgICAgICAgICAgICAgInNlY3RvciI6MSwKICAgICAgICAgICAgICAgICAgICAiZGF0YSI6Ii4uLiIKICAgICAgICAgICAgICAgIH0KICAgICAgICAgICAgXQogICAgICAgIH0KICAgIF0KfQ==",
                "CardAcquisitionTransaction":{
                }
            }
        }
    }

    After you end the session, the loading screen continues to show until you send an EnableServiceRequest (see the next step).

  4. To stop the loading screen, make a POST request to a Terminal API endpoint, specifying:

    • EnableServiceRequest with:

      Parameter Required Description
      TransactionAction -white_check_mark- AbortTransaction.
      DisplayOutput Optional object to show your own message and an 'Approved' icon (green check mark) or a 'Declined' icon (red cross).
      If you omit DisplayOutput, the terminal shows Canceled, a red cross , and Transaction canceled.

    The following example is the basic request, without the DisplayOutput object, to stop the card acquisition flow.

    Basic request to cancel the card acquisition data
    {
       "SaleToPOIRequest":{
          "MessageHeader":{
             "ProtocolVersion":"3.0",
             "MessageClass":"Service",
             "MessageCategory":"EnableService",
             "MessageType":"Request",
             "ServiceID":"3020711110",
             "SaleID":"POSSystemID12345",
             "POIID":"V400m-346403161"
          },
          "EnableServiceRequest":{
             "TransactionAction":"AbortTransaction"
          }
       }
    }

See also