POS developer manuals

Here we describe the technical aspects of a POS integration like initial setup and configuration, and integration in different environments like Windows, Android and iOS.

COM extension for Windows

This document applies for library version 1.5. For the version 1.4.3 document, click here.

Use the COM extension for Windows to integrate your POS solution with the Adyen platform. This extension uses the COM to enable communication between your POS solution, written in a language that supports COM, and the PED firmware.

Architecture

The COM extension for Windows implements a process of callback registration that defines coupling with the POS application. This allows for platform-independent, loosely coupled, implementation. Use the documentation to enforce proper code conventions, implement required elements, and ensure technical accuracy. This helps to avoid exceptions and simplifies error detection. 

The COM extension for Windows is a server object, not a DLL. For VB you can use tlbimp to generate a DLL that can be linked to your cash register application.

The callback handlers are functions that require their own identifier. This should include a substring indicating the type of callback along with the naming convention.

Adyen provides the COM extension for Windows as a single service executable, containing payment and registration functionality through the underlying C-library. Register the COM extension for Windows as a service in the registry of the cash register. Registration and de-registration example batch files are provided.  

The Adyen POS solution

The Adyen POS solution consists of a Pin Entry Device (PED) (running Adyen's payment software), a library (integrated in the Cash Register environment) and Adyen's payment system. Your POS connects to the PED via a serial, Ethernet or Wi-Fi connection.

To perform online transactions, you must connect both the POS system and the PED to the Internet. The PED can connect to the Adyen platform directly or by using the POS system as a proxy, which requires a physical connection between the PED and POS. 

You must authorise your POS system to connect to the Adyen systems, at least during the deployment and boarding of new PEDs. The POS system uses our C library functions to register associated PEDs. This allows you to exchange PEDs quickly and easily, and does not require you to store credentials on the device. This also means you don't need to contact Adyen to swap terminals, for example, in case of a replacement.

Multiple PEDs may be connected to a single POS system. The cash register application provides the staff with an interface to switch dynamically between these connected PEDs when required.

Legacy instructions for library version 1.4.3

1.5 is the latest version of our library. To download legacy instructions for library version 1.4.3, click here.

Com extension for Windows last update

Version Date Changes
1.5 2017 - 2 - 23 Editorial updates
Version Date Changes
1.5 2017 - 2 - 23 Editorial updates
1.4 2017 - 1 - 11 Updates for library v. 1.4 and 1.5
1.3 2016 - 12 - 13 Added Gift Card section
1.2 2016 - 11 - 23 Added parameter details
1.1 2016 - 09 - 06 Updated Calls and callbacks structure
1.0 2016 - 05 - 04 Initial version

Getting Started - COM extension for Windows

Downloading and installing the COM extension

  1. Log in to the  Customer Area (CA):

  2. Go to Point of Sale > Release notes and libraries 

    You need to request access to these sections by emailing Adyen support.

  3. Select Libraries.

  4. Scroll to the bottom of the page. Links to the library packages are listed underneath the relase notes. 

  5. Download the library files including the COM .bat and .exe files.
  6. Copy the files to the directory where you want to store and run them.

    Run all included files as an administrator.

After registering the COM extension for Windows, the executable creates Adyen POS objects in the application directory.

Moving the COM extension for Windows after registration can cause a failure and requires a re-registration.

The Adyen.POS service

The specific calls you use will vary depending on your implementation language,

The single service executable registers under the name "Adyen.POS". The cash register creates an instance of the Adyen.POS service according to coding preference. For example: objADYPOS. We use this example name throughout this guide.

Communicating boolean variables using the COM

Communicating boolean variables across COM varies for different application languages and implementations. To prevent variations in implementations, in the C library COM extension for Windows booleans are handled via a simple {0,1} Integer mapping. False equates to 0 and True is passed as 1.

To implement this, we assume the cash register has a method, for example COMBoolean, which takes a single argument of type boolean and returns a 0/1. We use the COMBoolean method in examples in this guide. 

Communicating ENUMs using the COM

The ENUMs as defined in the C library are not portable through the COM extension for Windows. Adyen provides helper methods to allow the cash register to retrieve the string representing the ENUM.

Example methods are: GetInitFlags, GetPEDresultStr, GetLIBresultStr, and GetPSPresultStr.

Callback results are passed in the form of integers. The values can then be checked by the application for process control. The objADYPOS instance offers methods to interpret the provided values.

Code Example: Result checking

private void AdyenPOSClass_RegisterAppCB(AppInfo appObj, int pedResult, int pspResult, int libResult,

            string errorMessage)

        {

            // Check if pspresult and library result is 0. If result is 0 then the register application is successful

            if (pspResult == 0 && libResult==0)

            {

                Log.Debug("App registered");

            }

            else

            {

                // Translate the error messages

                string pspResultCode = objPOS.GetPSPresultStr(pspResult);

                string libResultCode = objPOS.GetLIBresultStr(libResult);

               

                Log.Debug(String.Format(

                        "RegisterApp callback ped_result: {0} lib_result: {1} PSP_result: {2} error_message: {3}",

                        pedResult, libResultCode, pspResultCode, errorMessage));

            }

            WaitForRegisterApp.Set();

        }

The values returned by the ENUM in the C Library are string literals. The value 0 is used for successful results. All other values indicate an action has been duplicated unnecessarily, a longer wait is required, or a problem was encountered. When the application encounters a non-zero value, it is recommended to log the issue and have the application message the cash register staff so that they can take action if necessary. 

Obtain the available values (strings) by either looking at the C library header files or by running a simple loop on the helper methods. If you find an occurrence of an empty string, or a string with the value UNKNOWN, this indicates the end of the available entries in the underlying ENUM.

Reference the Adyen COM Object to a .net project

1. Copy the COM_intel_WINDOWS folder to a convenient location, for example your documents folder.
2. Run the i nstall_adyen_COM_service.bat file as administrator.
3. Start Visual studio with the POS project.
4. On the Visual studio project right click choose Add Reference...
5. In the Reference manager screen choose COM on the left side.
6. From the list, choose Adyen POS c library COM interface, and click OK.

Calls and Callbacks

Adyen POS Object Creation is a void method.


Calls and callbacks follow this flow:

  1. Invoke a method to perform a specific action.
  2. Set a timer to wait for an application-internal flag.
  3. In the callback pass the objects and results to internal objects, set the application-internal wait-flag and proceed to the end of the callback handler.
  4. Proceed with the main flow - handle and process the information obtained in the callback.

For methods from the COM extension for Windows that take arguments, carefully verify these arguments to avoid runtime errors. There is no option to validate the passed arguments. The same applies to the callback arguments - they are specified in the POS application and the COM extension for Windows can not validate these for you.

Callback Parameter Order

The order is defined in the C library but can not be enforced by it. As an example the create tender callback:

CreateTenderCB(objTender, intPedResult, intPspResult, intLibResult, strErrorMessage)

The tender object is returned in the CreateTender callback and should be used to execute subsequent tender-actions. The other arguments can be evaluated through the helper methods. A difference applies to the strErrorMessage as it can directly be used in logging or feedback.
The objects are provided in a specific order, defined in the C library COM extension for Windows and accessible via the normal interface in any standard coding tool. If desired the IDL in the executable can be observed via an OLE viewer.

Actionable vs. Informational Callbacks

When using the COM extension for Windows, during the processing of a tender, several callbacks happen. There are two  types: Actionable and Informational. Actionable callbacks require action to complete the transaction. Informational callbacks can be logged but are not required to complete a transaction.

Actionable type:

Informational type:

Mandatory

Mandatory calls and callbacks must be used by the cash register application to connect with the Adyen platform and process payments. If these calls and callbacks are not used, it is not possible to process payments.

Initializing the library

Before the library can be used, you must initialize it using the InitLibrary method.

POS Object

Name

Description

POS

POS object representing the Cash Register Application.

Method

Name Description
InitLibrary

Initializes the library and sets the environment, merchant name, cash register name, integrator name and library flags.

Parameters

Name Type Required Description

environment

long (tick)

Environment flag. Set as 1 for the Test environment and 2 for the Live environment.

merchantName

String (tick)

The merchant account used for the cash register application registration.

appName

String (tick)

The cash register name.

flags

long (error)

A set of library flags.

integratorName

String (error) Defines the name of the integrator company for logging.

You can check the intCallResult value immediately to indicate if the C library received the request without error.

Library flags

 Library Flags offer a level of control to the cash register and are useful for application development and debugging.

POS Object

Name Description
POS POS object representing the Cash Register Application.

Method

Name Description

GetInitFlags

Flags offer a level of control to the cash register for application development and debugging. Because you cannot ENUMs are not portable through the COM, we have provided a method to set the correct flags.

Parameters

Name

Type Required Description

logLevel

String (tick) Defines the level of logging provided.

logArea

long (tick) Defines the parts of the logs you can see. As default set this to 0xffff.

comLogConsole

int (tick)

Set to 1 to show the COM log console, set to 0 to hide it.

The possible values of LogLevel are:

Value
Description
E ERROR: Logs errors.
W WARNING: Logs warnings.
I INFO: Logs information about program state, representing program events or behavior tracking.
D

DEBUG: Logs detailed information about program state for debugging.

Registering the application with Adyen

POS Object

Name Description
POS POS object representing the Cash Register Application.

Method

Name Description

RegisterApp

After you initialize the library, you must register the cash register application with Adyen.

Registration requires a valid merchant account and web service credentials to access the Adyen platform. A unique cash register identifier is required.

Parameters

Name Type Required Description

merchantAccount

String (tick)

The merchant account used for registration.

wsUser

String (tick)

Web service user account. In the Adyen customer area, go to Settings > Users to create a new web service user.

password

String (tick) Password for the web service user account. In the Adyen customer area, go to Settings > Users to add a new password.

appID

String (tick) Unique ID of the cash register application.

Register the application once, after the cash register starts.

Callback

Name Description

RegisterAppCB

The Register App Callback returns the result of registration, as well as any errors.

Parameters

Name Type Description

appObj

AppInfo

Object used to hold POS information, which can be used for App registration.

pedResult

int

Result denoting whether an error occurred on the PED. A value of 0 means no error occurred.

pspResult

int

Result denoting whether an error occurred on the PSP. A value of 0 means no error occurred.
libResult int Result denoting whether an error occurred in the Library. A value of 0 means no error occurred.
errorMessage String Error message describing what went wrong.
Setting Cash Register Application Details

POS Object

Name

Description

POS

POS object representing the Cash Register Application.

Method

Name Description

SetApplicationDetails

Provides the C library with information about the cash register. This allows merchants to quickly find data in the Adyen portal and aids troubleshooting. 

Parameters

Name Type Required Description

applicationName

String (tick) Identifying name for the Cash Register application.

integratorName

String (tick)

Identifying name for the integrator.

Set the application details once, after the cash register starts.

Registering the PED with the Adyen platform

POS Object

Name Description
POS POS object representing the Cash Register Application.

Method

Name Description
RegisterPED When registerPED is invoked, the COM extension for Windows handles multiple steps for the cash register:
  1. Registering the PED device on the merchant account in the Adyen platform.
  2. Providing the initial configuration from the Adyen back-end to the PED.
  3. Exposing the PED for use by the C library.
  4. Returning the PED object to the cash register (in the callback) to pass control over the PED to the cash register.

Parameters

Name

Type

Required

Description

address

String

(tick)

Address of the PED, can be IP, COM port or URL etc.

name

String

(tick)

Logical name assigned to the PED.

This should be done when you connect the PED for the first time (and it is not yet registered), or when the PED is in a device state where tenders can not be processed. Retrieve the device state by looking at the Device State of the PED object under control of the cash register.

Invoking a RefreshPED on the PED object causes a PEDStateChange callback. Use this to update and validate the device state prior to starting a tender on the PED.

The cash register should not invoke a RegisterPED for every tender to be processed. 

The cash register performs tenders on the PED of choice. All callbacks relating to tender progress include a PED object to allow the cash register to decide if any action is required.

Creating the tender

PedDevice Object

Name

Description

PedDevice

PED object that represents the terminal.

Method

Name Description
CreateTender

The create tender method is used to start the transaction.

Parameters

Name

Type

Required

Description

merchantAccount

String

(tick)

The merchantAccount account that will receive the payment.

amountValue Long (tick)

The transaction amount in minor units (100 is 1.00 with EUR).

amountCurrency String (tick)

The transaction currency.

transactionType String (tick)  The type of transaction, for example: GOODS_SERVICES, REFUND.
tenderOptions TenderOption (tick)

The transaction options. Can be an empty TenderOption.

merchantRef String (tick)

The transaction reference provided by the Merchant (reported in Adyen back end).

orderRef String (tick)

The order reference for split payments (reported in Adyen back end).

gratuityAmountValue int (tick)

The tender gratuity amount in minor units (100 is 1.00 with EUR).

gratuityAmountCurrency String (tick)

The tender gratuity currency.

shopperEmail String (error)

Shopper identification (used for omni-channel digital customer recognition).

shopperRef String (error)

Shopper identification (used for omni-channel digital customer recognition).

recurringContract String (error)

Recurring contract if registering for RECURRING or ONE_CLICK payments.

recurringContractDetailName String (error)

Recurring contract detail key (points at payment details of this Tender).

additionalData AdditionalData (error) Additional data the method passes with the tender. The additionalData object is a generic container that can hold extra fields. The system uses the card number as a key to collect relevant additional data, for example loyalty data or recurring contract information.

Not all languages using COM handle empty parameters equally. This has the potential to cause unexpected behavior. To prevent this, provide empty strings or pass Null objects for C++/C#, and the default value Nothing for vb.net.

Callbacks

Name

Description
CreateTenderCB Immediate callback to tender creation.

Progress Event Callback

Reports the progress of a running tender.

Additional Data Callback

Invoked after a card has been inserted or swiped. Retrieves additional data about the tender.

DCC Callback

Returns dynamic currency conversion information to allow shoppers to choose their own currency at checkout.

PrintReceipt Callback

Checks if a receipt should be printed.

Signature Callback

Allows the store assistant to accept or decline a shopper's signature on the PED.
Final Callback When the system finishes processing the tender, it triggers the final state callback.
Passing tender options

PedDevice Object

Name

Description

PedDevice

PED object that represents the terminal.

Method

Name

Description

CreateTenderOptionObj

Used to create a TenderOption object, created on a PED device is available to facilitate passing of tender processing options.

Parameters

Name

Type

Required

Description

myTenderOptions

TenderOption

(tick)

The object allows for adding and removing of specific TenderOption(s). The ENUM in the C-Lib defines TenderOptions. Pass tender options as strings equal to the string representation of the ENUM.

For more info on tender options and the general POS considerations regarding various transaction options see Implementations, tender options and considerations.

Handling progress events

Callback

Name Description

TenderProgress

Reports progress events. The PED returns event information to the cash register. Progress events do not require any action by the cash register. They inform the staff of what is happening on the PED.

Parameters

Name

Type

Description

pedObj

PedDevice

PED object that represents the terminal.

tenderObj

Tender

The tender in progress.

headerObj

ResponseHdr

Header object that includes generic statuses, information about a merchant, and additional data from the PED.


Typical progress events sequence for a transaction with PIN as cardholder verification method:

  1. CARD_INSERTED
  2. WAIT_FOR_APP_SELECTION
  3. APPLICATION_SELECTED
  4. WAIT_FOR_PIN
  5. PIN_DIGIT_ENTERED
  6. PIN_DIGIT_ENTERED
  7. PIN_DIGIT_ENTERED
  8. PIN_DIGIT_ENTERED
  9. PIN_ENTERED


Handling the Signature callback

Callback

Name Description

TenderCheckSignature

The system invokes this callback if the terminal or card settings require signature as CVM.

Parameters

Name

Type

Description

pedObj

PedDevice

PED Object that represents the terminal.

tenderObj

Tender

The tender associated with the additional data.

headerObj

ResponseHdr

Header object that includes generic statuses, information about merchant, additional data from the PED.

Confirmation Method

Name Description

ConfirmSignature

This method runs against the tender object. Staff must verify the signature, and confirm or reject it.

Parameters

Name

Type

Required

Description

confirmation

int

(tick)

The result of signature verification. The staff member either confirms or rejects the signature.

signatureData

String

(error)

Base-64 encoded string of the bitmap. The PED passes the digital signature to the Adyen platform. Image size: 240 X 170px. 

Confirmation values

Value

Meaning
0 Declined
1 Approved
2 Retry

You can use value 2, retry, to allow shoppers to re-enter their signature.

Handling the Print Receipt callback

Callback

Name Description

TenderPrintReceipt

Printing receipts is the penultimate step for a transaction.

Parameters

Name

Type

Description

pedObj

PedDevice

Ped Object representing the terminal.

tenderObj

Tender

The tender associated with the additional data.

receiptsObj

Receipts

Passes receipts to the cash register. It's structure is formatted for printing.


Confirmation Method

Name Description

ConfirmPrintReceipt

Confirm that the receipt is printed.

Parameters

Name

Type

Required

Description

printed int (tick) Returns the result of printing, as the cash register must confirm printing of receipts.

Confirming whether the receipt has been printed is a mandatory step. The cash register must confirm his to the C Library and PED to complete the tender Do this outside the tender process between the POS, Adyen library, and PED.

Extracting data from a callback

Variable

Name Description
Any, for example: intCallResult

Declare and initialize the variables in your cash register application, and pass them as arguments with the COM extension methods.

The COM extension assigns values to these variables. The cash register can use these variables to access, store, and process the data returned from the library through the COM.

The additional data construct provides this data in the ResponseHeader. We provide a count helper method to aid the cash register.

Method

Name Description
GetTenderState Use this method to access the relevant tender state in the same header.
Querying the PED object for device information

PEDDevice object

Name

Description

PedDevice

PED object that represents the terminal.

Getter

Name

Description

GetTerminalInfo

Retrieves information from the PED.  

Returned Parameters

Name

Type

Description

id

Variant

Unique ID of the terminal.

brand

Variant

Brand of the terminal, i.e. Verifone.

type

Variant

Type of the terminal.

snr

Variant

Serial number of the terminal.

hw

Variant

Terminal hardware version.

os

Variant

Terminal Operating System.

api

Variant

Terminal firmware version

Method

Name

Description

RefreshPed

Updates the terminal information. Triggers a PED state callback from which you can query the state using GetDeviceState.

Parameters

Name

Type

Required

Description

retries

Int

(tick)

Number of times to retry refreshing the PED state. If you have multiple POS systems connected to a single PED, there may be an active transaction on the device which would block the request. Set this to a high number to avoid blocking.

Callback

Name

Description

PedStateChange

Callback that returns the current PED state.

Getter

Name

Description

GetDeviceState

Used on PedStateChange to return the current PED state.



Handling the final state callback

Final State Callback

Name

Description

TenderFinal

When the transaction completes, it triggers the final state callback.

Parameters

Name

Type

Description

pedObj

PedDevice

PED object that represents the terminal.

tenderObj

Tender

The tender that represents the transaction.

finalObj

FinalResponse

The library returns a final header object, including final status and additional information.


Method

Name

Description

GetResponseHeader

Access the header object and additional data with this method. The cash register can use the provided objects to obtain the relevant information regarding the outcome of the transaction by invoking a method on the finalObj with private parameters to store the information in.

strTenderState holds the final state of the tender and determines whether to provide goods or services to the cardholder.

Determining the current and final tender state

Use the following methods to retrieve the current or final state of a tender.

The pos_result_code visible in your logs refers to the result of communication between the library and the PED and does not represent the final state of a transaction.

Method

Name

Description

GetTenderState

Returns the current state result code. The first status to be checked during the transaction. If the tender state is not OK, something went wrong.


TenderState states

State

Description

UNDEFINED

The tender is in an undefined state.

ADDITIONAL_DATA_AVAILABLE

Additional data (like card alias (token), card type and issuer country code) are available

PRINT_RECEIPT

The terminal is printing the receipt

CHECK_SIGNATURE

The terminal is waiting for the cashier to check the signature.

ASK_DCC

The terminal is checking if the customer requires dynamic currency conversion

INITIAL

A transaction was initiated.

TENDER_CREATED

The tender was successfully created

CARD_INSERTED

A card was inserted

CARD_SWIPED

A card was swiped

WAIT_FOR_APP_SELECTION

The terminal is waiting to select...

APPLICATION_SELECTED

The customer has selected their preferred payment application.

WAIT_FOR_AMOUNT_ADJUSTMENT

Waiting for an amount to be adjusted based on the gratuity

ASK_GRATUITY

The terminal is waiting for a possible gratuity

GRATUITY_ENTERED

The gratuity amount was entered

DCC_ACCEPTED

The customer requested Dynamic Currency Conversion

DCC_REJECTED

The customer rejected Dynamic Currency Conversion

PROCESSING_TENDER

The payment is being processed. The terminal displays a progress bar.

WAIT_FOR_PIN

A PIN is requested at the terminal.

PIN_DIGIT_ENTERED A digit of the PIN was entered
PIN_ENTERED The whole PIN was entered
PROVIDE_CARD_DETAILS The terminal is waiting for (manually entered?) card details
CARD_DETAILS_PROVIDED The card details have been entered (either on the terminal or the cash register?)
RECEIPT_PRINTED A receipt was printed
REFERRAL_CHECKED The referral code was checked
SIGNATURE_CHECKED The cashier has checked and confirmed the signature
ACKNOWLEDGED
The transaction is acknowledged, but not approved, declined, cancelled or failed in error.
REFERRAL The acquirer sends a referral status
ASK_SIGNATURE The PED has requested a signature from the shopper.
APPROVED The transaction has been approved
DECLINED This response maps all those response codes that cannot be reliably mapped.
This makes it easier to tell generic declines (for example, MasterCard "05: Do not honor" response) from more specific ones.
CANCELLED The transaction was cancelled.
ERROR The transaction did not go through as an error occurred.
BALANCE_QUERY_STARTED The terminal is requesting the balance on a card
BALANCE_QUERY_COMPLETED The request for card balance has completed.
LOAD_STARTED A load of a value on the card has started.
BALANCE_QUERY_ACQUIRED Confirms the acquired balance and allows the user to take next steps,
LOAD_COMPLETED A load of a value on the card has completed.
UNKNOWN The tender state is unknown, and it is not possible to determine it.  
Contact the  Adyen Support Team to request assistance.



Object

Name Description
finalObj Run GetFinalStateCode against this object to get the final state of the transaction. Do this after the final transaction callback.


Method

Name Description
GetResponseHeader Return the response header of the final object.


GetResponseHeader returns:

Object

Name Description
ResponseHdr Run GetFinalStateCode against this object to get the final state of the transaction. Do this after the final transaction callback


Method

Name Description
GetTenderState Apply this to the response header of the final callback to return the final state of the transaction.


Final States

State Description

DECLINED

The transaction was declined.
APPROVED The transaction was approved
CANCELLED The transaction was cancelled.
UNKNOWN The tender state is unknown, and it is not possible to determine it.  
Contact the  Adyen Support Team to request assistance.


Conditional/Optional

Use conditional calls and callbacks for implementation-specific functions. For example, to provide additional data from the cash register during a transaction, like loyalty data, you use the Additional Data Callback. If the cash register does not handle these calls and callbacks, they will block further processing of the transaction.

Optional calls and callbacks do not need confirmation from the POS system. For example, the progress callback does not require any action. 

Handling the Additional Data callback

Callback

Name Description

TenderAdditionalData

The callback is tender-based and includes both a PED object and tender object as parameters.

Parameters

Name

Type

Description

pedObj

PedDevice

Ped Object representing the terminal.

tenderObj

Tender

The tender associated with the additional data.

headerObj

ResponseHdr

Header object that includes generic statuses, information about merchant, and additional data from the PED.

Confirmation Method

Name Description

ConfirmAdditionalData

Provides additional data to the terminal. After the POS receives the additional data callback from the PED, the POS must confirm this in order to continue the transaction. At this point, based upon the information received during the callback, the amount can be adjusted. The currency must be the same as the original currency.

Parameters

Name

Type

Required

Description

adjustedAmountValue

long

(tick)

Final (potentially adjusted) value of the transaction.

amountCurrency

String

(tick)

Currency of the amount.

shopperReference

String

(error)

Use this field to record the shopper reference with the transaction and for recurring or one-click functionality shopper data.

shopperEmail String (error) Supply a shopper reference and/or shopper email to allow for digital shopper recognition.
recurring_contract String (error) Recurring contract reference. Use this field to set up recurring or one-click functionality.
recurring_contract_detail_name String (error) Recurring contract details. Use this field to set up recurring or one-click functionality.
additionalData AdditionalData (error) Additional data returned by Adyen. The additionalData object is a generic container that can hold extra response fields.
transactionType String (error)

Type of transaction, for example: GOODSSERVICES, REFUND. 


A new, possibly altered, amount must be provided, typically used to offer a loyalty discount.

Additional data elements

When the additional data callback is triggered the cash register is provided with a large number of data elements which can be used in business processes to make decisions on the progress of the transaction. This is typically used for loyalty as the most distinguishing information concerns the cardholder-specific information. An example list contains the following:

additionalDataKey additionalDataValue
alias M469509594859802
cardIssueNumber 53
tid 83814241
posOriginalAmountValue 14823
cardHolderName TC02_MC_Approved
merchantReference Mref-12345
transactionType GOODS_SERVICES
cardIssuerCountryId 056
cardSummary 9999
cardBin 541333
paymentMethod mc
paymentMethodVariant mccredit
applicationLabel MCNL
posAuthAmountValue 14823
posAuthAmountCurrency EUR
txdate 1-4-2018
txtime 09:34:34
iso8601TxDate 2018-04-01T09:34:34.0000000+0000
applicationPreferredName mc nl
AID A000000004101001
posEntryMode ICC
expiryMonth 02
expiryYear 2028
Optionally additional elements can be provided:
shopperReference shopref123456789
shopperEmail my.name@email.com

All these elements are present for chip-based transactions while several are non-existent for MSR or NFC transactions. Non-existence should not block the cash register from standard operating. Additional elements may be present depending on the transaction options like Gratuity.

Handling the Dynamic Currency Conversion (DCC) callback

Callback

Name Description
TenderAdditionalData The callback is tender-based and thus has both a PED object as well as a Tender object as parameters. The header contains the DCC related information accessible via the standard mechanism. This is a progress style event as it requires no cash register action. In this case, the cardholder is uncertain what to do the staff is aware of the options/choice the cardholder is facing.

Parameters

Name

Type

Description

pedObj

PedDevice

Ped Object representing the terminal.

tenderObj

Tender

The tender associated with the additional data.

headerObj

ResponseHdr

Header object that includes generic statuses, information about merchant, additional data from the PED.

DCC Returned Details

The DCC details extracted using the standard mechanism contain the following keys (values mere examples):

additionalDataKey

additionalDataValue

dcc.markup

300

dcc.commissionfee

0

dcc.exchangerate

11180

dcc.converted.amount.value

1677

dcc.converted.amount.currency

USD

dcc.org.amount.value

1500

dcc.org.amount.currency

EUR

dcc.source

oanda


DCC Progress events

  • ASK_DCC
  • DCC_ACCEPTED / DCC_REJECTED
Displaying a screen on a large screen terminal

Method

Name Description
ShowScreen For terminals with large screens (MX925, MX915) this method allows the cash register to display specific screens prior to the processing the tender. Use this method to display order items on a virtual receipt.

Parameters

 

Name

Type

Required

Description

merchantAccount

String

(tick)

The merchant account associated with the transaction

screenName

String

(tick)

Logical name for the screen. Indicates the template and the XML contains all relevant data in simple nodes.

formatB64XML

String

(tick)

Base64 encoded XML data sent to the screen. Includes data elements as well as styling options. The relevant options depend on the template to show the screen and expose content control options.


Callback

Name

Description

ShowScreenCB

Callback used to return whether the screen displayed correctly, including error messages if applicable.

Returned Details

Name

Type

Description

screenId

int

The ID of the screen reporting in the callback. A terminal will only accept one message at a time. If several showScreen requests are sent before getting the showScreen callback, the last message will override previous messages.

pedResult

int

Result denoting whether an error occurred on the PED. A value of 0 means no error occurred.

pspResult

int

Result denoting whether an error occurred on the PSP. A value of 0 means no error occurred.
libResult int Result denoting whether an error occurred in the Library. A value of 0 means no error occurred.
errorMessage String Error message describing what went wrong.
Cancelling or refunding a transaction

POS Object

Name Description
POS POS object that represents the Cash Register Application.

Method

Name Description
CancelOrRefundPspReference Initiates the cancel or refund process. Use the PSP reference to identify the transaction to be cancelled.

Parameters

Name

Type

Required

Description

merchantAccount

String

(tick)

The merchant account account that is cancelling the transaction and refunding the money (if applicable).

pspreference String (tick)

PSP reference of the original transaction.

reference String (tick) Reference for the merchant, used in reporting.

Method

Name

Description

CancelOrRefundTenderReference

Initiates the cancel or refund process where the PSP reference is unknown. Use the tender reference instead of the PSP reference.

Occurs when the original sale transaction was performed offline, where the PspReference was not generated as it requires online access. In this case, provide the TerminalId and TenderReference. The property PspReference is not required.


Parameters

Name

Type

Required

Description

merchantAccount

String

(tick)

The merchant account that is cancelling the transaction and refunding the money (if applicable).

uniqueTerminalId Long (tick)

Unique terminal ID to reference the PED that is processing the request.

tenderReference String (tick) Reference for the transaction, used as the PSP reference is not available.
reference String (tick) Reference for the merchant, used in reporting.

Getters

Name

Description

GetPSPReference Returns the PSP reference.
GetResponse Returns the result of the cancel/refund request.

GetUniqueTerminalId

Returns the Terminal ID which is processing the transaction

GetTenderReference

Returns the Tender reference of the original transaction

GetOriginalPspReference

Returns the PSP reference of the original transaction.
Handling the LibraryLog callback

The COM extension for Windows provides feedback from the C library via a standard callback mechanism in the form of logs listing encountered problems. After the log level has been set in the library initialization call, the information becomes available via this callback.

Callback

Name Description

LibraryLog

Callback that provides the log, including header and data.

Parameters

Name

Type

Required

Description

header

String (tick) Header of the log file.

data

String (tick) Body of the log file.

Advanced features

Gift Card integrations

To allow your business to provide and process gift cards for customers, Adyen has created Gift Card Integration. This integration lets you perform balance inquiry, load a balance onto the card (including refunds), and perform payments. You can easily process single payments, or split payments into multiple chunks where necessary.

Manual Keyed Entry and passing of card details

Manual Keyed Entry involves manually typing the card details from a customer's gift card into either the Cash Register or the Pin Entry Device (PED).

When the terminal uses a card-swipe action to read details from a magnetic stripe, manual keyed entry is not necessary. In this case, it is not necessary to pass card details (such as cardNumber, expiry date) with commands.

If the terminal reads card information using the barcode reader on the POS, this will trigger an MKE type transaction.

If card details must be entered manually, then the KeyedEntry option is set to true and the merchant or cardholder will enter their details manually. For example, where the magnetic stripe and chip are not functional, or on a phone order, card details must be entered manually.

If the cashier knows the card details, they can enter them on the Cash Register. Otherwise, the shopper will enter the details on the PED.

Manual Keyed details can be passed with BalanceInquiryLoadCard, or with a  CardOperation.

If these methods do not pass card information, the system will ask for the information from the Shopper through the PED.

You can send card mask data without card information, which the PED will display. If you send no cardMask information, the PED uses a default mask. 

Gift Card Matrix

  Redemption Load Balance Inquiry
Swipe

1. CreateTender

  • Set additional data callback if the transaction requires CardAlias, masked PAN etc.

2. Swipe

  • No CardOperation.
  • No cardType set. 

1. LoadCard

  • Set additional data callback if the transaction requires CardAlias, masked PAN, current balance etc.
  • Set loadType: load

2. Swipe

  • No CardOperation.
  • Set cardType

1. BalanceInquiry

2. Swipe

  • No CardOperation.
  • Set cardType.
MKE POS

1. CreateTender

  • Set additional data callback if the transaction requires CardAlias, masked PAN etc.

2. CardOperation

  • Include cardNumber in CardOperation

  • Set cardType in command.
  • If the cardType is not included consumer will be prompted. 

1. LoadCard

  • Set additional data callback if the transaction requires CardAlias, masked PAN etc.
  • Set loadType: load.
  • Set KeyedEntry tenderOption.
  • Include cardNumber in command.
  • Set cardType in command.

1. BalanceInquiry

  •  Include cardNumber in command.
  • Set KeyedEntry tenderOption.
  • Set cardType in command.
MKE PED

1. CreateTender

  • Set additional data callback if the transaction requires CardAlias, masked PAN etc.

2. CardOperation

  • Do not include cardNumber in command.
  • Set cardType in command.
  • If cardType is not included, the shopper will be prompted.
  • Provide cardMask & cardMaskMin and cardMaskMax.
  • If a cardMask is not included, the default will be used. 
  1. LoadCard
  • Set additional data callback if the transaction requires CardAlias, masked PAN etc.
  • Set loadType: load.
  • Set KeyedEntry tenderOption.
  • Do not include cardNumber in CardOperation(will be ignored).
  • Set cardType in CardOperation.
  • Provide cardMask & cardMaskMin and cardMaskMax.
  • If a cardMask is not included, the default will be used. 
  1. BalanceInquiry
  • Do not include cardNumber in command.
  • Set KeyedEntry tenderOption.
  • Set cardType in command.
  • Provide cardMask & cardMaskMin and cardMaskMax.
  • If a cardMask is not included, the default will be used. 

Swipe: The system processes a swiped gift card transaction like a regular POS payment.

MKE: Always requires cardType. PED vs POS is implicit. If the cashier provides the cardNumber, the system uses POS as the entry mode. Otherwise, the system uses the PED as the entry mode. In this case, the PED requires a cardMask. If the system does not provide a cardMask, a default is used. 

Overriding the card mask

A card mask is a template for the format of a cardNumber.

If the gift card number is longer than the default cardMask, you will need to override this with your own mask.

For example, the default card mask is 9 digits and is formatted like "xxx-xxx-xxx".

To override the default card mask, specify the format in the cardMask parameter. For example, format a 16-digit cardNumber like so: "xxxx-xxxx-xxxx-xxxx"

Overriding the card mask

A card mask is a template for the format of a card number.

If the gift card number is longer than the default card mask, you will need to override this with your own mask.

For example, the default card mask is 9 digits and is formatted like "xxx-xxx-xxx".

To override the default card mask, specify the format in the card_mask parameter. For example, a 16 digit card number would be formatted like so: "xxxx-xxxx-xxxx-xxxx"

Check the balance of a gift card

BalanceInquiry is allows your customers to check their balance.  It can use three entry modes:

  • Manual keyed entry (MKE) on the POS system
  • MKE on the Pin Entry Device (PED)
  • Swipe

Balance inquiry follows this flow: 

  1. Use the BalanceInquiry method of the PedDevice object to retrieve the balance of a card and additional relevant data.

  2. A shopper enters their details by swiping their gift card, or manually entering the card number on the PED or cash register.

  3. The PED validates the call and retrieves data from the Adyen platform.

  4. The Adyen platform sends the status of the inquiry, including balance information, to the cash register. 

     

The KeyedEntry tender option defines whether manual keyed entry will be selected. If selected, the POS must pass the card number with the BalanceInquiry method.

PedDevice Object

Name

Description

PedDevice

PED object representing the terminal.

Method

Name Description

BalanceInquiry 

Allows the shopper to check their balance. If the entry mode is MKE, the merchant enters the card details manually using cardNumber.

Parameters

Name Type Required Definition

merchant_account

String (tick)

The merchant account processing this transaction. Use a merchant account that you provided during app registration.

card_type 

String (error)

The type of gift card. 

reference String (tick)

A reference for the balance inquiry. 

card_number String (error)

The gift card number.

Use of this parameter depends on selection of the Manual Keyed Entry option.

expiry_month Long (error)

Month of expiration.

Use of this parameter depends on selection of the Manual Keyed Entry option.

expiry_year Long (error)

Year of expiration.

Use of this parameter depends on selection of the Manual Keyed Entry option.

card_mask String (error)

A mask to validate the correct number of digits to enter.

Use of this parameter depends on selection of the Manual Keyed Entry option.

card_mask_min String (error)

Minimum number of characters in the card mask.

Use of this parameter depends on selection of the Manual Keyed Entry option.

card_mask_max String (error)

Maximum number of characters in the card mask.

Use of this parameter depends on selection of the Manual Keyed Entry option.

tenderOptions TenderOption (error)

Tender options define the behavior of the PED.

An object of type TENDER_OPTIONS that can have the following values:

  1. ReceiptHandler
  2. GetAdditionalData
  3. Recurring
  4. OneClick
  5. BypassPin
  6. AskGratuity
  7. NoProcess
  8. KeyedEntry
  9. DontPrintReceipt
  10. Error
  11. ForcedOnline
  12. ForcedDecline
  13. EnableMagstripeFallback
  14. NoCTLS
  15. AllowPartialAuthorisation 

number_of_additional_data_entries: defines the number of entries in the additional_data array.

additionalData AdditionalData (error)

Additional data that the POS sends with the transaction. 

Code example

Balance Inquiry Call 

'Initiate Balance Inquiry Command
 Console.WriteLine(String.Format("Current PED State = {0}", Current_PED_state))
 WaitforStateChange.Reset()
     If Current_PED_state = "ped_state_ready_for_transaction" Then
         Console.WriteLine("Just Continue")
     Else
         Console.WriteLine("Waiting for State change 'ready for transaction' ")
         WaitforStateChange.WaitOne()
     End If
 Dim tenderoptions As Adyen.TenderOption = PedDevice.CreateTenderOptionObj()
 'If KeyedEntry option is selected, then Merchathas to explicitly send enter the card details via this command.
 ' If the option is not selected (default case), then the card details are not 'mandatory' becasue a card-swipe operation will be triggered
 'tenderoptions.AddOption("KeyedEntry")
Dim balanceinquiry_result As Integer = PedDevice.BalanceInquiry("TestMerchantPOS", "testcard", "balance check", "", 12, 2049, Nothing, 12, 16, tenderoptions, Nothing)
 	If balanceinquiry_result <> 0 Then
 		Throw New Exception(String.Format("Balance Inquiry Request Failed. Result: {0}", balanceinquiry_result))
 	End If
 'Waiting for Balance Inquiry CB
 WaitForBalanceInquiryCB.WaitOne()
 'Waiting for Balance Acquired
 WaitForBalanceAcquired.WaitOne()

 

Callback

Name Description
POS.BalanceInquiryCB Confirms the system has successfully created a balance inquiry. 

Code example

Balance Inquiry Callback

Private Sub POS_BalanceInquiryCB(tenderObj As Adyen.Tender, pedResult As Integer, pspResult As Integer, libResult As Integer, errorMessage As String) Handles POS.BalanceInquiryCB
 If pedResult = 0 AndAlso libResult = 0 Then
 Console.WriteLine("Balance Inquiry Created")
' Tell main thread to continue
 Tender = tenderObj
 Else
 Console.WriteLine(String.Format("Balance Inquiry Request Rejected. Callback: ped_result: {0} lib_result: {1} PSP_result: {2} error_message: {3}", pedResult, libResult, pspResult, errorMessage))
 End If
 WaitForBalanceInquiryCB.Set()
 End Sub

Final Callback

Name Description
POS.BalanceAcquired Confirms the acquired balance and allows the user to take next steps,

Code example

Balance Acquired Final Callback

Private Sub POS_BalanceAcquired(pedObj As Adyen.PedDevice, tenderObj As Adyen.Tender, headerObj As Adyen.ResponseHdr) Handles POS.BalanceAcquired
 Console.WriteLine("Balance Acquired")
 Dim objAdditionalDataKey As Object = Nothing
 Dim objAdditionalDataValue As Object = Nothing
 Dim intCount As Integer
For intCount = 1 To headerObj.GetAdditionalData.Count
 headerObj.GetAdditionalData.GetData(intCount, objAdditionalDataKey, objAdditionalDataValue)
 Console.WriteLine(String.Format("Balance Acquired : {0},{1}", objAdditionalDataKey, objAdditionalDataValue))
 Next
'Peform one of the three operations: Just Process, CancelCardOperation, ProcessAdditionalData
If LoadCardUnderProgress Then
 Console.WriteLine("Just Process Card Operation")
 tenderObj.ConfirmAdditionalDataCardOperation(0, "")
 'Console.WriteLine("Cancel Card Operation")
 'tenderObj.CancelCardOperation()
End If
 WaitForBalanceAcquired.Set()
End Sub
Loading a balance to a card

The LoadCard function allows your customer to add a cash balance to their gift card and is also used to refund a balance to their card.

Loading a Card has 3 entry modes:

  • Manual keyed entry (MKE) on the POS system
  • MKE on the Pin Entry Device (PED)
  • Swipe

Loading a balance follows this flow: 

  1. The cash register initiates a load by including the Type (gift card provider), LoadType (different per provider), and from where the system reads the card information (e.g. PED, mag stripe or in the load request). This can include Manual Keyed entry, where the number is input through the terminal or cash register.

    You can support multiple types of loads, depending on the gift card provider. 

  2. The additional data callback will return the balance of the card. The system prompts the customer to review their balance before they complete the load. This allows them to change their load amount if necessary.

  3. The cash register updates the status of the tender, with additional information to allow for a decision based on card details. The cashier can then update or cancel the transaction.

PedDevice Object

Name Description
PedDevice PED object representing the terminal.

Method

Name Description

LoadCard 

Allows your customer to add a cash balance to their gift card and is used by the merchant to refund a balance to their card.

Parameters

Name Type Required Definition
merchant_account String (tick)

The merchant account processing this transaction. Use a merchant account that you provided during app registration

card_type 

String (error) The type of gift card.

load_type 

String (tick)

Gift Card Providers allow for many types of loads to cards. For example, merchandising return loads are used to credit returns to a card. Pass the default value: "load". 

reference String (tick) A reference for the load.
card_number String (error)

The gift card number.

Use of this parameter depends on selection of the Manual Keyed Entry option.

expiry_month Long (error)

Month of expiration.

Use of this parameter depends on selection of the Manual Keyed Entry option.

expiry_year Long (error)

Year of expiration.

Use of this parameter depends on selection of the Manual Keyed Entry option.

card_mask String (error)

A mask to validate the correct number of digits to enter.

Use of this parameter depends on selection of the Manual Keyed Entry option.

card_mask_min String (error)

Minimum number of characters in the card mask.

Use of this parameter depends on selection of the Manual Keyed Entry option.

card_mask_max String (error)

Maximum number of characters in the card mask.

Use of this parameter depends on selection of the Manual Keyed Entry option.

currency String (tick)

The currency of the balance. 

value Long (tick)

The value of the balance. 

tender_options TenderOption (error)

Tender options define the behavior of the PED.  

An object of type TENDER_OPTIONS that can have the following values:

  1. ReceiptHandler
  2. GetAdditionalData
  3. Recurring
  4. OneClick
  5. BypassPin
  6. AskGratuity
  7. NoProcess
  8. KeyedEntry - Defines whether the cashier enters the card information manually.
  9. DontPrintReceipt
  10. Error
  11. ForcedOnline
  12. ForcedDecline
  13. EnableMagstripeFallback
  14. NoCTLS
  15. AllowPartialAuthorisation 

number_of_additional_data_entries: defines the number of entries in the additional_data array.


AD_data AdditionalData (error)

Register additional data with the transaction if necessary. 

 

 Code example 

Load Card Method 

'Initiate the Load Card Command
 Console.WriteLine("Initiate the Load Card Command...")
 Dim Current_PED_state As String = PedDevice.GetDeviceState()
 LoadCardUnderProgress = True
 Console.WriteLine(String.Format("Current PED State = {0}", Current_PED_state))
 WaitforStateChange.Reset()
 Current_PED_state = PedDevice.GetDeviceState()
 If Current_PED_state = "ped_state_ready_for_transaction" Then
 Console.WriteLine("Just Continue")
 Else
 Console.WriteLine("Waiting for State change 'ready for transaction' ")
 WaitforStateChange.WaitOne()
 End If
 Dim loadtenderoptions As Adyen.TenderOption = PedDevice.CreateTenderOptionObj()
 loadtenderoptions.AddOption("KeyedEntry")
 'If KeyedEntry option is selected, then Merchant has to explicitly send enter the card details via this command.
 ' If the option is not selected (default case), then the card details are not 'mandatory' because a card-swipe operation will be triggered
 'If GetAdditionalData option is set, then an internal balanceinquiry call will be triggered, which will return the current balance on the card.
 ' Once the balance is available, an update tender option can be sent to just process the load, cancel the load, or select a new amount for the load. 
 loadtenderoptions.AddOption("GetAdditionalData")
 Console.WriteLine("Iniaitaing Load Card")
 Dim loadresult As Integer = PedDevice.LoadCard(Merchant, "testcard", "load", " load card", "1234123412341234", 12, 2049, "GBP", 1100, Nothing, 12, 16, loadtenderoptions, Nothing)
 If loadresult <> 0 Then
 Throw New Exception(String.Format("Load Card Request Failed. Result: {0}", loadresult))
 End If
Console.WriteLine("Waiting for Load CB")
 WaitForLoadCardCB.WaitOne()
 Console.WriteLine("Waiting for Balance Acquired ")
 WaitForBalanceAcquired.Reset()
WaitForBalanceAcquired.WaitOne()
LoadCardUnderProgress = False  

Callback

 

Name Description
POS.LoadCardCB Callback to confirm creation of the LoadCard request.

 

Load Card Callback

Private Sub POS_LoadCardCB(tenderObj As Adyen.Tender, pedResult As Integer, pspResult As Integer, libResult As Integer, errorMessage As String) Handles POS.LoadCardCB
 If pedResult = 0 AndAlso libResult = 0 Then
 Console.WriteLine("Load Card Request Created")
' Tell main thread to continue
 Tender = tenderObj
 Else
 Console.WriteLine(String.Format("Load Card Request Rejected. Callback: ped_result: {0} lib_result: {1} PSP_result: {2} error_message: {3}", pedResult, libResult, pspResult, errorMessage))
 End If
 WaitForLoadCardCB.Set()
 End Sub

Final Callback

Name Description
TenderFinal The final callback for LoadCard. Returns a value of either LOAD_COMPLETED or DECLINED

Code example

Final Callback

Private Sub POS_TenderFinal(pedObj As Adyen.PedDevice, tenderObj As Adyen.Tender, finalObj As Adyen.FinalResponse) Handles POS.TenderFinal
 Dim authCode As String = New String(String.Empty)
 Dim refusalReason As String = New String(String.Empty)
Dim state As String = New String(String.Empty)
 Dim pedResult As String = New String(String.Empty)
 Dim libResult As String = New String(String.Empty)
 Dim errorMessage As String = New String(String.Empty)
finalObj.GetFinalResult(authCode, refusalReason)
 finalObj.GetResponseHeader().GetTenderState(state, pedResult, libResult, errorMessage)
Console.WriteLine("Tender Final. State: " & state & " AuthCode: " & authCode & " RefusalReason:" & refusalReason)
 WaitForTenderFinal.Set()
 End Sub
Refunding a balance to a card

 Use the LoadCard command to load the value of the refund to the card. See Loading a balance to a card for more information. 

Redeeming gift cards

To redeem a gift card you can use the magnetic stripe, or redeem using the PED or your Cash Register. Your integration manager provides you with all card types available on your account. 

Redeem a gift card using a magnetic stripe

 

Your integration manager provides you with all card types available on your account. 

Magstripe gift cards are processed by Adyen like payment cards. Redeeming a card follows this flow:  

  1. The POS initiates CreateTender on the PedDevice.

  2. The customer or attendant swipes the gift card.
  3. The PED retrieves additional data and optionally a balance which is returned as additional data
  4. The cash register updates the status of the tender with additional information to allow for a decision based on the card details.

  5. The cash register either updates or cancels the transaction.

  6. A normal authorization request is made using the card number and any additional data. When this authorization is confirmed, the balance is removed from the card. 

PedDevice Object 

Name Description
PedDevice PED object representing the terminal.

Method

Name Description
CreateTender Initiates the transaction and makes a call to the Adyen platform for card information.

Parameters

Name Type Required Definition
merchant_account String (tick)

The merchant account processing this transaction. Use a merchant account that you provided during app registration.

terminal_id String (tick)

A reference for the terminal. 

card_type 

String  (error)

The type of gift card.

Use of this parameter depends on selection of the Manual Keyed Entry option.

card_number String (error)

The gift card number.

Use of this parameter depends on selection of the Manual Keyed Entry option.

expiry_month Long (error)

Month of expiration.

Use of this parameter depends on selection of the Manual Keyed Entry option.

expiry_year Long (error)

Year of expiration.

Use of this parameter depends on selection of the Manual Keyed Entry option.

card_mask String (error)

A mask to validate the correct number of digits to enter.

Use of this parameter depends on selection of the Manual Keyed Entry option.

card_mask_min String (error)

Minimum number of characters in the card mask.

Use of this parameter depends on selection of the Manual Keyed Entry option.

card_mask_max String (error)

Maximum number of characters in the card mask.

Use of this parameter depends on selection of the Manual Keyed Entry option.

tender_options TenderOption (error)

Tender options define the behavior of the PED. 

 

An object of type TENDER_OPTIONS that can have the following values:

  1. ReceiptHandler
  2. GetAdditionalData
  3. Recurring
  4. OneClick
  5. BypassPin
  6. AskGratuity
  7. NoProcess
  8. KeyedEntry
  9. DontPrintReceipt
  10. Error
  11. ForcedOnline
  12. ForcedDecline
  13. EnableMagstripeFallback
  14. NoCTLS
  15. AllowPartialAuthorisation 

number_of_additional_data_entries: defines the number of entries in the additional_data array.


AD_data AdditionalData (error)

Additional data that the POS sends with the transaction.

Code example 

CreateTender

'magstripe transaction, pass details with the tender.
Dim resultCreateTender = PedDevice.CreateTender(Merchant, 10100, "EUR", "GOODS_SERVICES", options, "12345", "45567", 0, "EUR", Nothing, Nothing , Nothing, Nothing)
    If resultCreateTender <> 0 Then
        Throw New Exception(String.Format("CreateTender failed.
        Result: {0}", resultCreateTender)) 
    End If 

Callbacks

The callbacks that apply to the CreateTender method are the same as those used in credit card transactions. Review these callbacks here.

Code example

CreateTender Callback

Private Sub POS_CreateTenderCB(tenderObj As Adyen.Tender, pedResult As Integer, pspResult As Integer, libResult As Integer, errorMessage As String) Handles POS.CreateTenderCB
    If pedResult = 0 AndAlso libResult = 0 Then
        Console.WriteLine("Tender Created")
        ' Tell main thread to continue
        TenderCreated = True
        Tender = tenderObj
    Else
        Console.WriteLine(String.Format("CreateTender callback ped_result: {0} lib_result: {1} PSP_result: {2} error_message: {3}", pedResult, libResult, pspResult, errorMessage))
    End If
    WaitForCreateTender.Set()
 End Sub

 

Final Callback

Name

Description
POS.TenderFinal Final callback that reports the state and result of the tender and any appropriate errors.

Code example

Final Callback

Private Sub POS_TenderFinal(pedObj As Adyen.PedDevice, tenderObj As Adyen.Tender, finalObj As Adyen.FinalResponse) Handles POS.TenderFinal
    Dim authCode As String = New String(String.Empty)
    Dim refusalReason As String = New String(String.Empty)
    Dim state As String = New String(String.Empty)
    Dim pedResult As String = New String(String.Empty)
    Dim libResult As String = New String(String.Empty)
    Dim errorMessage As String = New String(String.Empty)
       finalObj.GetFinalResult(authCode, refusalReason)
       finalObj.GetResponseHeader().GetTenderState(state, pedResult, libResult, errorMessage)
       Console.WriteLine("Tender Final. State: " & state & " AuthCode: " & authCode & " RefusalReason:" & refusalReason)
       WaitForTenderFinal.Set()
 End Sub


Redeem a gift card using a cash register application

Your integration manager provides you with all card types available on your account. 

Gift cards can be processed by manually entering the card details on a the Cash Register application. Redeeming a card follows this flow:   
  1. CreateTender: Begin the transaction on the payment application.

    Wait for the CreateTenderCB before running a CardOperation.

  2. CreateTenderCB: The system returns a callback confirming creation of a tender. 

    The POS can now run a CardOperation.

  3. CardOperation: The Pin Entry Device (PED) requests a Manual Keyed Entry (MKE).

  4. The Adyen platform returns AdditionalData. Confirm this to proceed.
  5. The cash register either updates or cancels the transaction.

  6. The PED requests authorisation using the card number and any additional data. If the Adyen platform confirms the authorisation, it removes the balance from the card.

 

POS Object

Name
Description
 POS POS object representing the Cash Register application.

Method

Name Description
 CardOperation Method to redeem card being processed on the cash register.

Parameters

Name Type Required Definition
merchant_account String (tick)

The merchant account processing this transaction. Use a merchant account that you provided during app registration.

terminal_id String (tick)

A reference for the terminal. 

card_type 

String  (error)

The type of gift card.

Use of this parameter depends on selection of the Manual Keyed Entry option.

card_number String (error)

The gift card number.

Use of this parameter depends on selection of the Manual Keyed Entry option.

expiry_month Long (error)

Month of expiration.

Use of this parameter depends on selection of the Manual Keyed Entry option.

expiry_year Long (error)

Year of expiration.

Use of this parameter depends on selection of the Manual Keyed Entry option.

card_mask String (error)

A mask to validate the correct number of digits to enter.

Use of this parameter depends on selection of the Manual Keyed Entry option.

card_mask_min String (error)

Minimum number of characters in the card mask.

Use of this parameter depends on selection of the Manual Keyed Entry option.

card_mask_max String (error)

Maximum number of characters in the card mask.

Use of this parameter depends on selection of the Manual Keyed Entry option.

Code examples

Card Operation


'Card Operation, first start a tender
Dim resultCreateTender = PedDevice.CreateTender(Merchant, 10100, "EUR", "GOODS_SERVICES", options, "12345", "45567", 0, "EUR", Nothing, Nothing, Nothing, Nothing)
    If resultCreateTender <> 0 Then
        Throw New Exception(String.Format("CreateTender failed. Result: {0}", resultCreateTender))
    End If
'Wait for tender to be created, And terminal to be in ready to accept card
Dim cardoperationresult = POS.CardOperation("TestMerchantPOS", "VX820- 900863881", "testcard", "1234123412341234", 12, 2049, Nothing, 12, 16)
    If cardoperationresult <> 0 Then
        Throw New Exception(String.Format("CardOperation failed. Result: {0}", cardoperationresult))
    End If 

 

Callbacks

The callbacks that apply to the CreateTender method are the same as those used in credit card transactions. Review these callbacks here.

Final Callback 

Name Description
POS.TenderFinal Final callback that reports the state and result of the tender and any appropriate errors.

Code example 

Final Callback

Private Sub POS_TenderFinal(pedObj As Adyen.PedDevice, tenderObj As Adyen.Tender, finalObj As Adyen.FinalResponse) Handles POS.TenderFinal
	Dim authCode As String = New String(String.Empty)
	Dim refusalReason As String = New String(String.Empty)
	Dim state As String = New String(String.Empty)
	Dim pedResult As String = New String(String.Empty)
	Dim libResult As String = New String(String.Empty)
	Dim errorMessage As String = New String(String.Empty)
		finalObj.GetFinalResult(authCode, refusalReason)
 		finalObj.GetResponseHeader().GetTenderState(state, pedResult, libResult, errorMessage)
			Console.WriteLine("Tender Final. State: " & state & " AuthCode: " & authCode & " RefusalReason:" & refusalReason)
 		WaitForTenderFinal.Set()
 End Sub

Redeem a gift card using manual keyed entry on the PED

 

Your integration manager provides you with all card types available on your account. 

Gift cards can be processed by manually entering the card details on a Pin Entry Device. Redeeming a card follows this flow:  

  1. CreateTender: Begin the transaction on the payment application.

    Wait for the CreateTenderCB before running a CardOperation.

  2. CreateTenderCB: The system returns a callback confirming creation of a tender. 

    The POS can now run a CardOperation.

  3. CardOperation: The Pin Entry Device (PED) requests a Manual Keyed Entry (MKE).

  4. The Adyen platform returns AdditionalData. Confirm this to proceed.
  5. The PED requests authorisation using the card number and any additional data. If the Adyen platform confirms the authorisation, it removes the balance from the card.

POS Object

Name
Description
 POS POS object representing the Cash Register application.

Method

Name Description
CardOperation Method used to redeem card being processed by the PED. The CardOperation can only be performed after a create tender has already been performed.

 

Parameters

 

Name Type Required Definition
merchant_account String (tick)

The merchant account processing this transaction. Use a merchant account that you provided during app registration

terminal_id String (tick)

A reference for the terminal. 

card_type 

String  (error)

The type of gift card.

Use of this parameter depends on selection of the Manual Keyed Entry option.

card_number String (error)

The gift card number.

Use of this parameter depends on selection of the Manual Keyed Entry option.

expiry_month Long (error)

Month of expiration.

Use of this parameter depends on selection of the Manual Keyed Entry option.

expiry_year Long (error)

Year of expiration.

Use of this parameter depends on selection of the Manual Keyed Entry option.

card_mask String (error)

A mask to validate the correct number of digits to enter.

Use of this parameter depends on selection of the Manual Keyed Entry option.

card_mask_min String (error)

Minimum number of characters in the card mask.

Use of this parameter depends on selection of the Manual Keyed Entry option.

card_mask_max String (error)

Maximum number of characters in the card mask.

Use of this parameter depends on selection of the Manual Keyed Entry option.

 

Code example

Card operation  

'Card Operation, first start a tenderDim resultCreateTender = PedDevice.CreateTender(Merchant, 10100, "EUR", "GOODS_SERVICES", options, "12345", "45567", 0, "EUR", Nothing, Nothing, Nothing, Nothing)
If resultCreateTender <> 0 Then
 Throw New Exception(String.Format("CreateTender failed. Result: {0}", resultCreateTender))
End If
'Wait for tender to be created, And terminal to be in ready to accept card
 Dim cardoperationresult = POS.CardOperation("TestMerchantPOS", "VX820- 900863881", "testcard", "1234123412341234", 12, 2049, Nothing, 12, 16)
If cardoperationresult <> 0 Then
 Throw New Exception(String.Format("CardOperation failed. Result: {0}", cardoperationresult))
End If 

Callbacks

The callbacks that apply to the CreateTender method are the same as those used in credit card transactions. Review these callbacks here.

Final Callback

Name Description
POS.TenderFinal Final callback that reports the state and result of the tender and any appropriate errors.

Code example

Final Callback 

Private Sub POS_TenderFinal(pedObj As Adyen.PedDevice, tenderObj As Adyen.Tender, finalObj As Adyen.FinalResponse) Handles POS.TenderFinal
 Dim authCode As String = New String(String.Empty)
 Dim refusalReason As String = New String(String.Empty)
 Dim state As String = New String(String.Empty)
 Dim pedResult As String = New String(String.Empty)
 Dim libResult As String = New String(String.Empty)
 Dim errorMessage As String = New String(String.Empty)
	finalObj.GetFinalResult(authCode, refusalReason)
	finalObj.GetResponseHeader().GetTenderState(state, pedResult, libResult, errorMessage)
	Console.WriteLine("Tender Final. State: " & state & " AuthCode: " & authCode & " RefusalReason:" & refusalReason)
	 WaitForTenderFinal.Set()
 End Sub

Com extension for Windows Code Examples

C# .NET Implementation

 The initial declaration:

using POS;
public class CashRegisterCLibExtension : C_AdyenPOSClass

Initialisation of the class:

C_AdyenPOSClass c_AdyenPOSClass = new C_AdyenPOSClass(); 

Declaration of the callback handler:

c_AdyenPOSClass.InitLibraryCB += new comFeedback_InitLibraryCBEventHandler(this.AdyenPOSClass_InitLibraryCB); 

Initialisation of the library:

c_AdyenPOSClass.InitLibrary

Implement the callback handler:

public void c_AdyenPOSClass_InitLibraryCB()
{
	Console.WriteLine("Init lib callback was called");
} 

VB Implementation

The initial declaration:

 

Private WithEvents POS As Adyen.POS
Private WaitForInitLibrary As AutoResetEvent = New AutoResetEvent(False) 

Initialisation of the object:

objADYPOS = New Adyen.POS

Initialisation of the library:

objADYPOS.InitLibrary

Implementation of a callback:

Private Sub POS_InitLibraryCB() Handles POS.InitLibraryCB
	Console.WriteLine("Init lib callback was called")
	WaitForInitLibrary.Set()
End Sub

COM Extension for Windows - Objects

AdditionalData

Name Description
AdditionalData Additional data you pass with the tender. The additionalData object is a generic container that can hold extra response fields. The system uses the card number as a key to collect relevant additional data, for example loyalty data or recurring contract information.


Use this object in the following calls and callbacks to represent the Tender:

Creating the tender

Loading a balance to a card

Check the balance of a gift card

Redeem a gift card using a magnetic stripe

Handling the Additional Data callback

Additional data elements

When the additional data callback is triggered the cash register is provided with a large number of data elements which can be used in business processes to make decisions on the progress of the transaction. This is typically used for loyalty as the most distinguishing information concerns the cardholder-specific information. An example list contains the following: 

additionalDataKey additionalDataValue
alias M469509594859802
cardIssueNumber 53
tid 83814241
posOriginalAmountValue 14823
cardHolderName TC02_MC_Approved
merchantReference Mref-12345
transactionType GOODS_SERVICES
cardIssuerCountryId 056
cardSummary 9999
cardBin 541333
paymentMethod mc
paymentMethodVariant mccredit
applicationLabel MCNL
posAuthAmountValue 14823
posAuthAmountCurrency EUR
txdate 1-4-2018
txtime 09:34:34
iso8601TxDate 2018-04-01T09:34:34.0000000+0000
applicationPreferredName mc nl
AID A000000004101001
posEntryMode ICC
expiryMonth 02
expiryYear 2028
Optionally additional elements can be provided:
shopperReference shopref123456789
shopperEmail my.name@email.com

All these elements are present for chip-based transactions while several are non-existent for MSR or NFC transactions. If these elements do not exist, it should not block the cash register. Additional elements may be present, depending on the transaction options like Gratuity.

AppInfo

Name Description
AppInfo

Object that holds POS information, which you use to register the app.

Getters

Name

Description

GetCurrencyCount

Returns the number of currencies available.

GetCurrency

Returns the currencies used for transactions on the POS.

GetPaymentMethodCount

Returns the number of payment methods available.

GetPaymentMethod

Returns the payment methods available to the POS.

GetMerchantCount

Returns the number of merchant accounts available.

GetMerchantName

Returns the name of the merchant accounts used for the cash register application registration.

GetRegisteredForOfflineUsage

Returns a boolean that determines whether the POS app has been registered for offline transactions. he first time you register the application, the POS will attempt to communicate with the Adyen Platform and download and store credentials locally on the POS.

This object is used in the following calls and callbacks to represent the PED:

Registering the Application 

PedDevice

Name Description
PedDevice

PED object that represents the terminal.

Getters

Name

Description

GetTerminalInfo

Retrieves terminal information such as ID, brand, OS, etc.

GetTenderState

Retrieves the current processing state of the tender.

GetDeviceState

Returns the state of the PED.

GetCurrentTender

Returns the tender that is currently being processed.

GetUniquePEDreference

Returns a unique identifier for the PED object.

GetBatteryPercentage

Returns the battery charge in percent. Write alerts and optimizations based on this.

GetTerminalAdditionalData

Returns the additional data object of the terminal.

GetDeviceAddress

Returns the unique address of the terminal.

GetDeviceName

Returns the configured name of the terminal that the PedDevice object applies to.

Use this object in the following calls and callbacks to represent the PED:

Handling progress events

Handling the Signature callback

Handling the Print Receipt callback

Querying the PED object for device information

Handling the Dynamic Currency Conversion (DCC) callback

Handling the Additional Data callback

Handling the final state callback

POS

Name Description
POS

POS object representing the Cash Register Application.

Getters

Name

Description

GetPEDcount

Retrieves the amount of registered PED devices.

GetPEDobj

Retrieves the PED object by ID.

GetPEDresultStr

Returns the PED result with a description.

GetPSPresultStr

Returns the PSP result with a description.

GetLIBresultStr

Returns the library/POS result with a description.

GetInitFlags

Returns init flags for the library.

Flags offer a level of control to the cash register which is especially useful during application development and debugging. Because of the lack of ENUM portability a method has been provided to set the correct flags.
The method accepts three arguments:

  • The log level.
  • Several options for Adyen debugging usage.
  • Whether the console should be displayed.


For more information see Library Flags.

Use this object in the following calls and callbacks to represent the POS:

Initializing the library

Registering the application with Adyen

Registering the PED with the Adyen platform

Cancelling or refunding a transaction

Receipt

Name Description
Receipt

Object representing the receipt. Content of the individual receipts which are used in the Receipts object for printing.

Getters

Each receipt consists of three sections: a header, a content and a footer section. These getters retrieve each section separately.

Name

Description

GetReceiptHeader

This returns the header.

GetReceiptContent

This returns the receipt content.

GetReceiptFooter

This returns the footer.


This object is used in the following calls and callbacks to represent the PED:

Handling the Print Receipt callback

Receipts

Name Description
Receipts

Object representing the receipts. The print receipt callback contains the full receipt objects. The cash register should accept and store receipts for handling outside of the transaction flow. You receive a merchant, and a cardholder receipt.

Getters

Name

Description
GetResponseHeader

Returns the tender state, PED result, LIB result, error messages if necessary, tender reference and additional data. Certain callbacks, such as the print receipt callback and final callback get more information using GetResponseHeader.

GetMerchantReceipt

Retrieves merchant version of the receipt.

GetCardHolderReceipt

Retrieves cardholder version of the receipt.

get_receipt_type

Returns type of receipt, whether merchant or cardholder.

Use this object in the following calls and callbacks to represent the PED:

Handling the Print Receipt callback

Tender

Name Description
Tender

Object representing the transaction being processed.

Getters

Name

Description

GetTenderReference

Retrieves terminal information such as ID, brand, OS, etc.

GetTenderPED

Retrieves the current processing state of the tender.

Use this object in the following calls and callbacks to represent the PED:

Creating the tender

Handling progress events

Handling the Signature callback

Handling the Print Receipt callback

Handling the Additional Data callback

Handling the Dynamic Currency Conversion (DCC) callback

Handling the final state callback

TenderOption

Name Description
TenderOption

Represents tender options that are passed with the tender. Object representing options to be processed with the tender. Create the object using CreateTenderOptionObj method from the PedDevice object. Generally, transaction options can be configured via the Adyen Customer Area (CA) or as a TenderOption on a per-transaction basis.

Tender options define the behavior of the PED.

An object of type TENDER_OPTIONS can have the following values:

Name Description
ReceiptHandler Specifies that the POS handles and prints receipts. If omitted, the PED prints the receipt (if it contains a printer unit).
GetAdditionalData Gathers and makes available additional data, after a card is read. The amount of the transaction can be changed, based on additional input from the POS. When DCC is used, the GetAdditionalData tender option must be specified.
Recurring Set up recurring payments based on the payment details collected with this transaction.
OneClick Registers the shopper reference and shopper email data for digital customer recognition. This option allows payment details to be used for one-click payment later in a separate ecommerce transaction,
BypassPin

Used to bypass PIN entry by the shopper if the shopper does not know the PIN for the card and the Merchant trusts the shopper.

AskGratuity Initiates a question on the PED whether or not the shopper wants to offer a tip, which for instance can be useful in restaurant environments.
NoProcess  
KeyedEntry Required for MKE processing. If set to true, this allows the merchant or cardholder to enter the card number manually if necessary.
DontPrintReceipt Prevents the terminal from printing the receipt.
Error  
ForcedOnline Forces online authorisation of the transaction.
ForcedDecline Forces a decline of the transaction.
EnableMagstripeFallback IF EMV is not supported or cannot be processed, magstripe will be used as an authentication method.
NoCTLS Disables contactless payments on the terminal.
AllowPartialAuthorisations Allows partial authorisation, where the shopper pays for their goods with another card, if the balance of their primary card is less than the value of the goods.

Use this object in the following calls and callbacks to represent the Tender:

Passing tender options 


Java Native Interface integration

This document applies for library version 1.5.

Java Native Interface last update

Version Date Changes
1.0 2016 - 12 - 13 Initial version

Getting Started - Java Native Interface integration

The Java Native Interface integration allows you to integrate your Java-based POS system with our terminals. It enables transactions, for example sales, refunds and so on. The supported  Point-Of-Sale (POS) entry modes are: ICC, MSR and MKE. 

Software distribution

The software is distributed from the Adyen merchant Customer Area (CA) system:

  1. Go to Point of Sale > Release notes and libraries 

    You need to request access to these sections by emailing Adyen support.

  2. At the top of the page select Libraries

  3. Scroll to the bottom of the page, you will see links to download the C library and JNI files. 

Architecture

The Adyen POS solution

The Adyen POS solution consists of a Pin Entry Device (PED) (running Adyen's payment software), a library (integrated in the Cash Register environment) and Adyen's payment system. Your POS connects to the PED via a serial, ethernet or Wi-Fi connection.

To perform online transactions, you must connect both the POS system and the PED to the Internet. The PED can connect to the Adyen platform directly or by using the POS system as a proxy, which requires a physical connection between the PED and POS. 

You must authorise your POS system to connect to the Adyen systems, at least during the deployment and boarding of new PEDs. The POS system uses our C library functions to register associated PEDs. This allows you to exchange PEDs quickly and easily, and does not require you to store credentials on the device. This also means you don't need to contact Adyen to swap terminals. for example, in case of a replacement.

Multiple PEDs may be connected to a single POS system. The cash register application provides the staff with an interface to switch dynamically between these connected PEDs when required.

Calls and Callbacks - Java Native Interface

Calls and callbacks follow this flow:

  1. Invoke a method to perform a specific action.
  2. The invoked method invokes the synchronization helper method, specifying a parameter to determine which callback should be returned.

  3. The synchronization helper method waits until one of the following occurs:
    1. The system returns a callback
    2. A timeout of 20 seconds
    3. An exception. 
  4. if the system returns a callback, the main flow resumes, and the the application handles and processes the information returned in the callback.

Callback Parameter Order

The order of parameters is defined in the C library defines the order of parameters but can not enforce it. 

The createTender callback returns a tender object. Use this to execute subsequent actions on a tender. Evaluate other arguments using the provided helper methods.

Error Messages can be used directly in logging or feedback without helper methods.

Actionable vs. Informational Callbacks

Several callbacks occur during the processing of a tender. There are two types of callback: Actionable and Informational.

  • Actionable callbacks require action to complete the transaction.
  • Informational callbacks can be logged but are not required to complete a transaction.

Actionable callbacks:

Informational callbacks:

Mandatory - JNI

Initializing the library - JNI

Class

Name

Description

MerchantPos

Extends AdyenPos. Class used to implement all payment platform functionality. Implements all functions that do not involve the PED.

Method

Name

Description

initLibrary

Method used to begin library Initialization.

This method returns an immediate response of type LibraryResult. Check if this result is OK, before continuing the operation. If the LibraryResult value is not OK, the system will not return the related callback with the asynchronous result. See here for more on extracting data from an event or callback.

initLibraryRequest Parameter

Name Description
initLibraryRequest Object to hold parameters needed for library initialization

initLibraryRequest Attributes

Name

Type Required

Description

libraryEnvironment

Environment (tick) The execution environment.

posId

String (tick) The unique POS ID.
integratorName String (tick) The name of the integrator company, defined for logging reasons.
logConfig LogConfig (tick) Object containing logLevel

posName

String (error) The symbolic POS name.

appName

String (error) The Integrator/Merchant App ID.

logLevel

String (error) Defines the level of logging provided.


Callback

Name

Description
initLibraryCallback Returns the result of the library initialization.

Callback Response Attribute

Name

Description
libraryResult The result of the initialization of the C Library.
Debugging and logging - JNI

Method

Name

Description

setLogLevel

Used on a LogConfig object to set the log level.


The possible values of LogLevel are:

Name Description
OFF Logging is turned off.
ERROR Errors are logged.
WARNING Warnings are logged.
INFO Logs information about program state, representing program events or behavior tracking.
DEBUG

Logs detailed information about program state that developers will need to debug a problem.


 

Registering the application with Adyen - JNI

Class

Name Description
MerchantPos Extends AdyenPos. Class used to implement all payment platform functionality. Implements all functions that do not involve the PED.

Method

Name Description
registerPos

Method used to authenticate and authorize a POS application with the Adyen PSP system. Do this once before using a POS to perform transactions.

This method returns an immediate response of type LibraryResult. Check if this result is OK, before continuing the operation. If the LibraryResult value is not OK, the system will not return the related callback with the asynchronous result. See here for more on extracting data from an event or callback.

registerPosRequest Parameter

Name Description
registerPosRequest Signature of the registerPos method. One parameter object used to hold all the attributes.

registerPosRequest Attributes

Name

Type Required

Description

merchantAccountCode

String (tick) The merchant account name.
user String (tick) Web service user account. In the Adyen customer area, go to Settings > Users to create a new web service user.
password String (tick) Password for the web service user account. In the Adyen customer area, go to Settings > Users to add a new password.
posId String (tick) The unique POS ID.

Callback

Name

Description
 registerPosCallback Returns the result of registering the POS.

Callback Response Attribute

Name

Description
PosInfo

Contains the PosInfo object, which includes the PSP configuration as maintained in the POSTFM.

Registering the PED with the Adyen platform - JNI

Class

Name Description
MerchantPed Extends AdyenPed. Class used to implement all pin entry device (PED) functionality.

Method

Name Description
registerPed

Method used to authenticate and authorize the Pin Entry device with the Adyen PSP system. Do this before processing transactions using a POS.

This method returns an immediate response of type LibraryResult. Check if this result is OK, before continuing the operation. If the LibraryResult value is not OK, the system will not return the related callback with the asynchronous result. See here for more on extracting data from an event or callback.

Parameter

Name

Type Required

Description

ped

Ped (tick) Instance of MerchantPed. Represents the PED that is processing the tender.

Callback

Name

Description
 registerPedCallback Returns the result of registering the PED.

Callback Response Attribute

Name

Description
pedInfo

Contains the PED info, the result of registering the PED.

Creating the tender - JNI

Class

Name Description
MerchantPed Extends AdyenPedClass used to implement all pin entry device (PED) functionality.

Method

Name Description
createTender

Creates a tender using a number of attributes.

This method returns an immediate response of type LibraryResult. Check if this result is OK, before continuing the operation. If the LibraryResult value is not OK, the system will not return the related callback with the asynchronous result. See here for more on extracting data from an event or callback.

Tender Parameter 

Name

Type

Description

tender

Tender

Holds the tender attributes.


Attributes

Name Type Required Definition

merchantAccount

String

(tick)

The merchantAccount account to receive the money.

merchantReference

String

(tick)

The transaction reference provided by the Merchant (reported in Adyen back end).

currency

String

(tick)

The transaction currency.

amount

long

(tick)

The transaction amount in minor units (100 is 1.00 with EUR).

tenderOptions

Tender.TenderOption

(tick)

The transaction options. Can be an empty TenderOption.

tenderType

TenderType

(tick)

The tender type (GOODS_SERVICES or REFUND).

requestReference

String

(error)

The request reference provided by the PED.

pspReference

String

(error)

The tender reference provided by the Adyen PSP (reported in Adyen platform).

orderReference

String

(error)

The order reference for split payments (reported in Adyen platform).

originalReference

String

(error)

The original reference for refunds (reported in Adyen platform).

gratuityAmount

long

(error)

The tender gratuity amount in minor units (100 is 1.00 with EUR).

shopperReference

String

(error)

Shopper identification (used for omni-channel digital customer recognition).

shopperEmail

String

(error)

Shopper identification (used for omni-channel digital customer recognition).

recurringContract

RecurringContract

(error)

Recurring contract if registering for RECURRING or ONE_CLICK payments.

recurringContractDetail

String (error)

Recurring contract detail key (points at payment details of this Tender).

dccData

DccData 

(error)

Container for the DCC data.

receipts

List<Receipts.ReceiptSet> (error)

Holds a list of receipt information.

authCode

String

(error) Authorisation code for the transaction.

refusalReason

String

(error) Reason for refused transaction, if applicable.

tenderPed

AdyenPed

(error)

The PED to run this transaction on, do not serialize it

terminalId

String

(error)

The PED to process the transaction on.

adjustCurrency

String

(error)

The transaction adjusted currency.

adjustAmount

long (error)

The transaction adjusted amount in minor units (100 is 1.00 with EUR).

Passing tender options

Tender options, such as creating a recurring contract, are passed with the TenderOption list as described below:

Tender.TenderOption[] tenderOptions = {
        Tender.TenderOption.GetAdditionalData,
        Tender.TenderOption.ReceiptHandler,
};

For more information on tender options, see the Implementations, tender options and considerations page.

Callbacks

Name

Description
createTenderCallback Immediate callback to creation of the tender.
progressCallback Reports the progress on a running tender
additionalDataCallback Retrieves additional data about the tender after a card has been inserted or swiped.
tenderDccCallback

Checks if the customer requires Dynamic Currency Conversion

tenderPrintReceiptCallback Checks if a receipt should be printed
tenderCheckSignatureCallback Allows the store assistant to accept or decline the signature.
finalCallback The system triggers the final callback after the tender completes.
Handling the Progress callback - JNI

Callback 

Name

Description

progressCallback

Provides progress status updates of the transaction.

Parameter

Name Description
Tender Object used to hold the tender attributes.

Tender Response Attributes

Name

Description

additionalData

Adyen returns the additionalData object, a generic container that can hold extra response fields.

tenderReference

Reference the PED provides for the transaction, used in reporting on the Adyen platform.

tenderState

Transaction state

adyenResult

Transaction result details

Handling the Signature callback - JNI

Callback

Name

Description

tenderCheckSignatureCallback

Whenever a signature is required, the relevant data is shown on the display of the PED and the shopper can sign on the touch screen display of the PED. The tenderCheckSignatureCallback is then invoked to allow the store assistant to accept or decline the signature.

This callback will only be triggered if the tender is created with the tender option receiptHandler

Callback Response Attributes

Name

Description

additionalData

Adyen returns the additionalData object, a generic container that can hold extra response fields

tenderReference

Reference the PED provides for the transaction, used in reporting on the Adyen platform.

tenderState

Transaction state

adyenResult

Transaction result details

Handling the Print Receipt callback - JNI

Callback

Name

Description

tenderPrintReceiptCallback

The print receipt callback is invoked at various points during a transaction where there may be a requirement to print a receipt. For example, an authorization receipt which must be signed by the shopper. 

Trigger this callback by creating a tender with the tenderOption receiptHandler.

Confirm the print receipt callback before the POS begins printing the receipt. This will prevent an approved transaction from being canceled because of printer failure.

Parameter

Name Description
Tender Object used to hold the tender attributes.

Callback Response Attributes

Name

Description

additionalData

Adyen returns the additionalData object, a generic container that can hold extra response fields

tenderReference

Reference the PED provides for the transaction, used in reporting on the Adyen platform.

tenderState

Transaction state

adyenResult

Transaction result details

Cancelling or refunding a tender on the PSP - JNI

Class

Name Description
MerchantPos Extends AdyenPos. Class used to implement all payment platform functionality. Implements all functions that do not involve the PED.

Method

Name Description
cancelOrRefundAtPsp
Start a cancel or refund of type REFUND_PSP. Execute this cancel or refund on the PSP instead of the PED.

This method returns an immediate response of type LibraryResult. Check if this result is OK, before continuing the operation. If the LibraryResult value is not OK, the system will not return the related callback with the asynchronous result. See here for more on extracting data from an event or callback.

Tender Parameter

Name

Type Required

Description

tender Tender (tick) Represents the tender.

Attributes

Name Type Required Definition

merchantAccount

String

(tick)

The merchantAccount account to receive the money

merchantReference

String

(tick)

The transaction reference provided by the Merchant (reported in Adyen platform)

currency

String

(tick)

The transaction currency

amount

long

(tick)

The transaction amount in minor units (100 is 1.00 with EUR)

tenderType

TenderType

(tick)

The tender type (GOODS_SERVICES or REFUND).

originalReference

String

(tick)

The original reference for refunds (reported in Adyen platform).

tenderOptions

Tender.TenderOption

(error)

The transaction options. Can be an empty TenderOption.

requestReference

String

(error)

The request reference provided by the PED.

pspReference

String

(error)

The tender reference provided by the Adyen PSP (reported in Adyen platform).

orderReference

String

(error)

The order reference for split payments (reported in Adyen platform).

gratuityAmount

long

(error)

The tender gratuity amount in minor units (100 is 1.00 with EUR).

shopperReference

String

(error)

Shopper identification (used for omni-channel digital customer recognition).

shopperEmail

String

(error)

Shopper identification (used for omni-channel digital customer recognition).

recurringContract

RecurringContract

(error)

Recurring contract if registering for RECURRING or ONE_CLICK payments.

recurringContractDetail

String (error)

Recurring contract detail key (points at payment details of this Tender).

dccData

DccData 

(error)

Container for the DCC data.

receipts

List<Receipts.ReceiptSet> (error)

Holds a list of receipt information.

authCode

String

(error) Authorisation code for the transaction.

refusalReason

String

(error) Reason for refused transaction, if applicable.

tenderPed

AdyenPed

(error)

The PED to run this transaction on, do not serialize it

terminalId

String

(error)

The PED to process the transaction on

adjustCurrency

String

(error)

The transaction adjusted currency

adjustAmount

long (error)

The transaction adjusted amount in minor units (100 is 1.00 with EUR)

Callback

Name

Description

 cancelOrRefundAtPspCallback

Callback used to return the result of creating the tender

Callback Response Attributes

Name

Description

additionalData

Adyen returns the additionalData object, a generic container that can hold extra response fields

tenderReference

Reference the PED provides for the transaction, used in reporting on the Adyen platform.

tenderState

Transaction state

adyenResult

Transaction result details

Cancelling a tender on the PED - JNI

Class

Name Description
MerchantPed Extends AdyenPedClass used to implement all pin entry device (PED) functionality.

Method

Name

Description

cancelTender Issues a cancel tender request from the PED.

Parameters

Name Type Required Description
ped String (tick) Instance of MerchantPed. Represents the PED on which the tender will be executed.
terminalIdOfTender
String (tick) Identifier for the terminal that is processing the tender.
tenderReference
String (tick) Reference for the tender.
Extracting data from a callback - JNI

Variable

Name

Description

LibraryResult

Use in-app declared variables to extract and store data. Initialize variables on the cash register side and pass them as arguments to the methods provided by the Java Native Interface (JNI). The JNI then assigns the appropriate value to the variables. The cash register can then access, store and process the information.

The following pages describe extracting data from callbacks:

Handling the Progress callback - JNI

Handling the Dynamic Currency Conversion (DCC) callback - JNI

Handling the Show Screen callback - JNI

Handling the Signature callback - JNI

Handling the Print Receipt callback - JNI

Handling the PED Exception Callback - JNI

Handling the Additional Data callback - JNI

Querying the PED object for device information - JNI

Method

Name Description
RefreshPed Retrieves the state of the PED if connectivity with the PED was lost.

Parameters

Name Description
retries Specify the number of retries when attempting to refresh the PED state. 

Callback

Name Description
pedStateChangeCallback
RefreshPed  triggers this callback. It returns if the PED state has changed, for example, if the PED has come online.
Handling the final state callback - JNI

Callback

Name

Description

finalCallback

When the tender completes, it triggers the final state callback.

Parameter

Name Description
Tender Object used to hold the tender attributes.

Callback Response Attributes

Name Description
additionalData

The additional data returned by Adyen 

tenderReference

The transaction reference provided by the PED (reported in the Adyen platform)

tenderState

The transaction state

adyenResult

The transaction result details


Conditional/Optional - JNI

Handling the Additional Data callback - JNI

 Callback

Name Description
tenderAdditionalDataCallback

Invoked after the shopper inserts or swipes a card. Uses the card number as a key to retrieve additional data about the tender, like loyalty and customer recognition data. 

AdditionalData defined by a tender will contain only the data coming from the terminal. To provide additional data to the terminal, use the operations createTender and confirmAdditionalData passing an extra parameter.

Create the tender with the tender option  getAdditionalData to trigger the tenderAdditionalDataCallback.

Parameter

Name

Description

Tender

Object that holds the tender attributes.

Callback Response Attributes

Name Description
additionalData

Additional data returned by Adyen.  The  additionalData  object is a generic container that can hold extra response fields.

tenderReference

Transaction reference provided by the PED (reported in Adyen back end).

tenderState

Transaction state.

adyenResult

Transaction result details.

Providing Additional Data for Credit Cards

Method

Name Description

confirmAddionalData

Provides additional data to the terminal.

Parameters

Name Type Required Description
tender Tender (tick)

Use this as a key to confirm additional data.

modification

boolean (tick)

Input parameter of confirmAddionalData. When sending this call it's possible to modify some of the fields of the tender, i.e amount. The parameter modification lets the caller specify if the library should expect updates on the tender object or not.

Providing Additional Data for Gift Cards

Method

Name Description

confirmAdditionalDataCardOperation

Provides additional data to the terminal.

Parameters

Name Type Required Description
giftCard GiftCard (tick)

Use this as a key to confirm additional data.

modification

boolean (tick)

Input parameter of the confirmAdditionalDataCardOperation. When sending this call it's possible to modify some of the fields of the tender, i.e amount. The parameter modification lets the caller specify if the library should expect updates on the tender object or not.

Handling the PED Exception Callback - JNI

Callback

Name Description
pedExceptionCallback

Returned when an exception occurs during a Tender or GiftCard operation. The parameter Transaction is a parent class of both Tender and GiftCard classes, defining the common attributes. The callback returns the following parameters:


Callback Response Attributes

Name

Description

additionalData

Adyen returns the additionalData object, a generic container that can hold extra response fields

tenderReference

Reference the PED provides for the transaction, used in reporting on the Adyen platform.

tenderState

Transaction state

adyenResult

Transaction result details

Handling the Dynamic Currency Conversion (DCC) callback - JNI

Callback

Name

Description

tenderDccCallback

Informs the POS about the status of a DCC transaction, offered currencies, rates and so on. Allows the cashier to give informed assistance to the shopper.

Parameter

Name

Description

Tender

Object that holds the tender attributes.

Callback Response Attributes

Name

Description

additionalData

Adyen returns the additionalData object, a generic container that can hold extra response fields

tenderReference

Reference the PED provides for the transaction, used in reporting on the Adyen platform.

tenderState

Transaction state

adyenResult

Transaction result details

Handling the Show Screen callback - JNI

Method

Name

Description

showScreenCallback
Queries whether Show Screen should be implemented for larger screens.

Callback Response Attributes

Name

Description

AdditionalData

The additional data returned by Adyen. The additionalData object is a generic container that can hold extra response fields.

TenderReference

The transaction reference provided by the PED (reported in Adyen back end).

TenderState

The transaction state.

AdyenResult

The transaction result details.

ScreenId

Identifier of the message shown on the screen, which can be queried later. A terminal will only accept one message at a time, if several showScreen requests are sent before getting the showScreen callback, the last message will override previous ones.

ScreenResult

Enum result of the show screen action. It can contain values: Unknown, Accepted, and Failed.

Advanced features JNI

Handling Gift Cards - JNI

To allow your business to provide and process gift cards for customers, Adyen provides gift card functionality in the Java Native Interface. This integration lets you perform balance inquiry, load a balance onto the card, perform payments and process refunds. You can easily process single payments, or split payments into multiple chunks where necessary.

Manual Keyed Entry and passing of card details - JNI

Manual Keyed Entry involves manually typing the card details from a customers gift card into either the Cash Register or the Pin Entry Device (PED).

When details are read from a magnetic stripe (magstripe), a card-swipe action is triggered and manual keyed entry is not necessary. In this case, it is not necessary to pass card details (such as card number, expiry date) with commands. For barcodes, if the information is read using the barcode reader on the POS, this will trigger an MKE type transaction.

If card details must be entered manually, for example where the magnetic stripe and chip are not functional, or on a phone order, the keyedEntry option is set to true and the merchant or cardholder will enter their details manually.

If the cashier knows the customer's card details, they can enter them on the Cash Register. Otherwise, the shopper will enter the details on the PED.

Manual Keyed details can be passed with balanceInquiry, loadCard or with CardOperation.

If the MKE TenderOption is set, then the cashier can enter the details on the POS or the shopper can enter them on the PED.

Card Mask data can be sent without card information, which will then be displayed on the PED. If no card mask information is sent, the PED uses a default mask. 

Overriding the card mask - JNI

A card mask is a template for the format of a card number.

If the gift card number is longer than the default card mask, you will need to override this with your own mask.

For example, the default card mask is 9 digits and is formatted like "xxx-xxx-xxx".

To override the default card mask, specify the format in the cardMask parameter. For example, a 16 digit card number would be formatted like so: "xxxx-xxxx-xxxx-xxxx"

Check the balance of a gift card - JNI

BalanceInquiry is allows your customers to check their balance.  It can use three entry modes:

  • Manual keyed entry (MKE) on the POS system
  • MKE on the Pin Entry Device (PED)
  • Swipe



Balance inquiry follows this flow: 

  1. Use the balanceInquiry method of the MerchantPed class to retrieve the balance of a card and additional relevant data.

  2. A shopper enters their details by swiping their gift card, or manually entering the card number on the PED or cash register.

  3. The PED validates the call and retrieves data from the Adyen platform.

  4. The status of the inquiry, including balance information, is sent from the Adyen platform to the cash register. 

     

Class

Name

Description

MerchantPed

Class used for operations that are performed using the PED.

Method

Name

Description

balanceInquiry 

Allows the customer to check their balance.

The keyedEntry tender option defines whether manual keyed entry will be selected. If selected, the POS must pass the card number with the balanceInquiry method.

This method returns an immediate response of type LibraryResult. Check if this result is OK, before continuing the operation. If the LibraryResult value is not OK, the system will not return the related callback with the asynchronous result. See here for more on extracting data from an event or callback.

The tender needs to be in the "ready for tender" state before you trigger a balanceInquiry.

Object

Name

Type

Description

giftcard

GiftCard

Contains all parameters to be passed with the balanceInquiry.

Attributes

Name Type Required Definition

merchantAccount

String

(tick)

The merchantAccount account to receive the money.

merchantReference

String

(tick)

The transaction reference provided by the Merchant (reported in Adyen paltform).

loadType String (tick)

Should contain the value: GiftCard.LoadType.load.getName()

currency

String

(error)

The transaction currency.

amount

long

(error)

The transaction amount in minor units (100 is 1.00 with EUR).

tenderOptions

Tender.TenderOption

(error)

The transaction options. Can be an empty TenderOption.

cardType 

String (error)

The type of gift card. 

cardNumber String (error)

The gift card number.

Use of this parameter depends on selection of the Manual Keyed Entry option.

expiryMonth Long (error)

Month of expiration.

Use of this parameter depends on selection of the Manual Keyed Entry option.

expiryYear Long (error)

Year of expiration.

Use of this parameter depends on selection of the Manual Keyed Entry option.

cardMask String (error)

A mask to validate the correct number of digits to enter.

Use of this parameter depends on selection of the Manual Keyed Entry option.

cardMaskMin String (error)

Minimum number of characters in the card mask.

Use of this parameter depends on selection of the Manual Keyed Entry option.

cardMaskMax String (error)

Maximum number of characters in the card mask.

Use of this parameter depends on selection of the Manual Keyed Entry option.

tenderPed

AdyenPed

(error)

The PED to run this transaction on, do not serialize it.

terminalId

String

(error)

The PED to process the transaction on.

adjustCurrency

String

(error)

The transaction adjusted currency.

adjustAmount

long (error)

The transaction adjusted amount in minor units (100 is 1.00 with EUR).

Callback

Name

Description

balanceInquiryCallback

Confirms the balanceInquiry has been created. 

Callback Response Attributes

Name

Description

additionalData

The additional data returned by Adyen. The additionalData object is a generic container that can hold extra response fields.

GiftCard

The transaction reference provided by the PED (reported in Adyen back end).

tenderState

The transaction state.

adyenResult

The transaction result details.


Final Callback

Name Description

finalCallback

Confirms the acquired balance and allows the user to take next steps,
Loading a balance to a card - JNI

The LoadCard function allows your customer to add a cash balance to their gift card and is also used to refund a balance to their card.

Loading a Card has 3 entry modes:

  • Manual keyed entry (MKE) on the POS system
  • MKE on the Pin Entry Device (PED)
  • Swipe

Loading a balance follows this flow: 

  1. The cash register initiates a load by including the merchantAccount, loadType (different per provider), currency and amount. 

    You can support multiple types of loads, depending on the gift card provider. 

    The keyedEntry tender option defines whether or not manual keyed entry will be selected.

  2. The additional data callback will return the balance of the card. The system prompts the shopper to review their balance before they complete the load. This allows them to change their load amount if necessary.

  3. The system updates the cash register with the status of the tender and additional data. Additional data, like the card balance, can be used to determine whether or not to continue with the transaction. For example, if the card already holds sufficient balance, the customer may decide not to load a balance.

  4. The cash register can then update or cancel the transaction.

Class

Name Description
MerchantPed Class used to perform operations using the PED.

Method

Name Description

loadCard 

Allows the shopper to add a cash balance to their gift card and allows the merchant to refund a balance to the shopper's card.

This method returns an immediate response of type LibraryResult. Check if this result is OK, before continuing the operation. If the LibraryResult value is not OK, the system will not return the related callback with the asynchronous result. See here for more on extracting data from an event or callback.

 

The tender needs to be in the "ready for tender" state before you trigger a load.


Attributes

Name

Type

Required

Definition

merchantAccount

String

(tick)

The merchantAccount account to receive the money.

loadType

String

(tick)

Should contain the value: GiftCard.LoadType.load.getName()

currency

String

(tick)

The transaction currency.

amount

long

(tick)

The transaction amount in minor units (100 is 1.00 with EUR).

merchantReference

String

(error)

The transaction reference provided by the Merchant (reported in Adyen platform).

tenderOptions

Tender.TenderOption

(error)

The transaction options. Can be an empty TenderOption.

cardType 

String

(error)

The type of gift card. 

cardNumber

String

(error)

The gift card number.

Use of this parameter depends on selection of the Manual Keyed Entry option.

expiryMonth

Long

(error)

Month of expiration.

Use of this parameter depends on selection of the Manual Keyed Entry option.

expiryYear

Long

(error)

Year of expiration.

Use of this parameter depends on selection of the Manual Keyed Entry option.

cardMask

String

(error)

A mask to validate the correct number of digits to enter.

Use of this parameter depends on selection of the Manual Keyed Entry option.

cardMaskMin

String

(error)

Minimum number of characters in the card mask.

Use of this parameter depends on selection of the Manual Keyed Entry option.

cardMaskMax

String

(error)

Maximum number of characters in the card mask.

Use of this parameter depends on selection of the Manual Keyed Entry option.

tenderPed

AdyenPed

(error)

The PED to run this transaction on, do not serialize it.

terminalId

String

(error)

The PED to process the transaction on.

adjustCurrency

String

(error)

The transaction adjusted currency.

adjustAmount

long

(error)

The transaction adjusted amount in minor units (100 is 1.00 with EUR).


Callback 

Name Description
loadCardCallback Callback to confirm creation of the loadCard request. Contains an AdyenResult object.

 

Callback Response Attributes

Name

Description

additionalData

The additional data returned by Adyen. The additionalData object is a generic container that can hold extra response fields.

GiftCard

The transaction reference provided by the PED (reported in Adyen back end).

tenderState

The transaction state.

adyenResult

The transaction result details.


Final Callback

Name Description
finalCallback The final callback for loadCard. Contains a GiftCard object. Can return a value of either LOAD_COMPLETED or DECLINED
Refunding a balance to a card - JNI

Use the loadCard command to load the value of the refund to the card. See Loading a balance to a card for more information. 

Redeeming gift cards - JNI

To redeem a gift card you can use the magnetic stripe, or redeem using the PED or your Cash Register. Your integration manager provides you with all card types available on your account. 

Redeeming a gift card using a magnetic stripe - JNI

Your integration manager provides you with all card types available on your account. 

Adyen processes magstripe gift cards like payment cards. Redeeming a card follows this flow:   

  1. The POS initiates CreateTender on the MerchantPed.

  2. The customer or attendant swipes the gift card.
  3. The Adyen PED retrieves additional data and optionally a balance which is returned as additional data
  4. The system updates the cash register with the status of the tender and additional data. Additional data, like the card balance, can be used to determine whether or not to continue with the transaction. For example, if the card already holds insufficient balance, the customer may decide not to redeem. Additional information to allow for a decision based on the card details.

  5. The Cash register either updates or cancels the transaction.

  6. The PED requests authorisation using the card number and any additional data. If the Adyen platform confirms the authorisation, it removes the balance from the card. 

Class  

Name

Description

MerchantPed

Class used to perform operations using the PED.

Method

Name Description
createTender

Initiates the transaction and makes a call to the Adyen platform for card information.

This method returns an immediate response of type LibraryResult. Check if this result is OK, before continuing the operation. If the LibraryResult value is not OK, the system will not return the related callback with the asynchronous result. See here for more on extracting data from an event or callback.

 

The tender needs to be in the "ready for tender" state before you trigger an MSR.

Object

Name Description
GiftCard Contains parameters related to gift cards.

Attributes

Name

Type

Required

Definition

merchantAccount

String

(tick)

The merchantAccount account to receive the money.

loadType

String

(tick)

Should contain the value: GiftCard.LoadType.load.getName()

currency

String

(tick)

The transaction currency.

amount

long

(tick)

The transaction amount in minor units (100 is 1.00 with EUR).

merchantReference

String

(error)

The transaction reference provided by the Merchant (reported in Adyen platform).

tenderOptions

Tender.TenderOption

(error)

The transaction options. Can be an empty TenderOption.

cardType 

String

(error)

The type of gift card. 

cardNumber

String

(error)

The gift card number.

Use of this parameter depends on selection of the Manual Keyed Entry option.

expiryMonth

Long

(error)

Month of expiration.

Use of this parameter depends on selection of the Manual Keyed Entry option.

expiryYear

Long

(error)

Year of expiration.

Use of this parameter depends on selection of the Manual Keyed Entry option.

cardMask

String

(error)

A mask to validate the correct number of digits to enter.

Use of this parameter depends on selection of the Manual Keyed Entry option.

cardMaskMin

String

(error)

Minimum number of characters in the card mask.

Use of this parameter depends on selection of the Manual Keyed Entry option.

cardMaskMax

String

(error)

Maximum number of characters in the card mask.

Use of this parameter depends on selection of the Manual Keyed Entry option.

tenderPed

AdyenPed

(error)

The PED to run this transaction on, do not serialize it.

terminalId

String

(error)

The PED to process the transaction on.

adjustCurrency

String

(error)

The transaction adjusted currency.

adjustAmount

long

(error)

The transaction adjusted amount in minor units (100 is 1.00 with EUR).

Callbacks 

The callbacks that apply to the createTender method are the same as those used in credit card transactions. Review these callbacks  here .

Callback Response Attributes

Name

Description

additionalData

The additional data returned by Adyen. The additionalData object is a generic container that can hold extra response fields.

GiftCard

The transaction reference provided by the PED (reported in Adyen back end).

tenderState

The transaction state.

adyenResult

The transaction result details.


Final Callback

Name

Description
finalCallback Final callback that reports the state and result of the tender and any appropriate errors.

Redeem a gift card using a cash register application - JNI

Your integration manager provides you with all card types available on your account. 

  1. The PED executes a createTender.

    Wait for the createTenderCallback before running a cardOperation.

  2. createTenderCallback: The system returns a callback confirming creation of a tender. 

    The POS can now run a cardOperation.

  3. cardOperation: The  POS updates the transaction with the gift card provider type and account number.

  4. The system updates the cash register with the status of the tender and additional data. Additional data, like the card balance, can be used to determine whether or not to continue with the transaction. For example, if the card already holds insufficient balance, the customer may decide not to redeem. 
  5. The cash register must update or cancel the transaction.

  6. The system makes an authorisation request for the value of the goods using the card number, and any included additional data. 

Class

Name Description
MerchantPos Class used for operations that are not performed on the PED, i.e. Card operations on cash register

 

Method

Name Description
 cardOperation

Redeems a value from a card by using the cash register application.

This method returns an immediate response of type LibraryResult. Check if this result is OK, before continuing the operation. If the LibraryResult value is not OK, the system will not return the related callback with the asynchronous result. See here for more on extracting data from an event or callback.

 

The tender needs to be in the "Tender Created" state before you trigger redemption by manual key entry.

 

Attributes

Name

Type

Required

Definition

merchantAccount

String

(tick)

The merchantAccount account to receive the money.

loadType

String

(tick)

Should contain the value: GiftCard.LoadType.load.getName()

currency

String

(tick)

The transaction currency.

amount

long

(tick)

The transaction amount in minor units (100 is 1.00 with EUR).

merchantReference

String

(error)

The transaction reference provided by the Merchant (reported in Adyen platform).

tenderOptions

Tender.TenderOption

(error)

The transaction options. Can be an empty TenderOption.

cardType 

String

(error)

The type of gift card. 

cardNumber

String

(error)

The gift card number.

Use of this parameter depends on selection of the Manual Keyed Entry option.

expiryMonth

Long

(error)

Month of expiration.

Use of this parameter depends on selection of the Manual Keyed Entry option.

expiryYear

Long

(error)

Year of expiration.

Use of this parameter depends on selection of the Manual Keyed Entry option.

cardMask

String

(error)

A mask to validate the correct number of digits to enter.

Use of this parameter depends on selection of the Manual Keyed Entry option.

cardMaskMin

String

(error)

Minimum number of characters in the card mask.

Use of this parameter depends on selection of the Manual Keyed Entry option.

cardMaskMax

String

(error)

Maximum number of characters in the card mask.

Use of this parameter depends on selection of the Manual Keyed Entry option.

tenderPed

AdyenPed

(error)

The PED to run this transaction on, do not serialize it.

terminalId

String

(error)

The PED to process the transaction on.

adjustCurrency

String

(error)

The transaction adjusted currency.

adjustAmount

long

(error)

The transaction adjusted amount in minor units (100 is 1.00 with EUR).

Callbacks 

The callbacks that apply to the createTender method are the same as those used in credit card transactions. Review these callbacks  here .

Callback Response Attributes

Name

Description

additionalData

The additional data returned by Adyen. The additionalData object is a generic container that can hold extra response fields.

GiftCard

The transaction reference provided by the PED (reported in Adyen back end).

tenderState

The transaction state.

adyenResult

The transaction result details.


Final Callback

Name

Description

finalCallback

Final callback that reports the state and result of the tender and any appropriate errors.

Redeem a gift card using manual keyed entry on the PED - JNI

 

Process gift cards by manually entering the card details on a Pin Entry Device. Redeeming a card follows this flow:  

  1. createTender: Begin the transaction on the payment application.

    Wait for the createTenderCallback before running a cardOperation.

  2. cardOperation: The Pin Entry Device (PED) requests a Manual Keyed Entry (MKE).

    The POS can now run a cardOperation.

  3. The system returns additional data is returned which must be confirmed. Additional data, like the card balance, can be used to determine whether or not to continue with the transaction. For example, if the card already holds insufficient balance, the customer may decide not to redeem. 
  4. An authorization request for the value of the goods is made using the card number, and any included additional data. 

Class

Name Description
MerchantPos Class used for operations that are not performed on the PED, i.e. Card operations on cash register

Method

Name Description
createTender

Method used to redeem card being processed by the PED. The CardOperation can only be performed after a create tender has already been performed.

This method returns an immediate response of type LibraryResult. Check if this result is OK, before continuing the operation. If the LibraryResult value is not OK, the system will not return the related callback with the asynchronous result. See here for more on extracting data from an event or callback.

Attributes

Name

Type

Required

Definition

merchantAccount

String

(tick)

The merchantAccount account to receive the money.

loadType

String

(tick)

Should contain the value: GiftCard.LoadType.load.getName()

currency

String

(tick)

The transaction currency.

amount

long

(tick)

The transaction amount in minor units (100 is 1.00 with EUR).

merchantReference

String

(error)

The transaction reference provided by the Merchant (reported in Adyen platform).

tenderOptions

Tender.TenderOption

(error)

The transaction options. Can be an empty TenderOption.

cardType 

String

(error)

The type of gift card. 

cardNumber

String

(error)

The gift card number.

Use of this parameter depends on selection of the Manual Keyed Entry option.

expiryMonth

Long

(error)

Month of expiration.

Use of this parameter depends on selection of the Manual Keyed Entry option.

expiryYear

Long

(error)

Year of expiration.

Use of this parameter depends on selection of the Manual Keyed Entry option.

cardMask

String

(error)

A mask to validate the correct number of digits to enter.

Use of this parameter depends on selection of the Manual Keyed Entry option.

cardMaskMin

String

(error)

Minimum number of characters in the card mask.

Use of this parameter depends on selection of the Manual Keyed Entry option.

cardMaskMax

String

(error)

Maximum number of characters in the card mask.

Use of this parameter depends on selection of the Manual Keyed Entry option.

tenderPed

AdyenPed

(error)

The PED to run this transaction on, do not serialize it.

terminalId

String

(error)

The PED to process the transaction on.

adjustCurrency

String

(error)

The transaction adjusted currency.

adjustAmount

long

(error)

The transaction adjusted amount in minor units (100 is 1.00 with EUR).

The tender needs to be in the "Tender Created" state before you trigger redemption by manual key entry.

Callbacks 

The callbacks that apply to the createTender method are the same as those used in credit card transactions. Review these callbacks here.

Callback Response Attributes

Name

Description

additionalData

The additional data returned by Adyen. The additionalData object is a generic container that can hold extra response fields.

GiftCard

The transaction reference provided by the PED (reported in Adyen back end).

tenderState

The transaction state.

adyenResult

The transaction result details.


Final Callback

Name

Description
finalCallback Final callback that reports the state and result of the tender and any appropriate errors

Canceling redemption of a gift card - JNI

Class 

Name Description
MerchantPed Class used for operations that merchant's perform using the PED.

Method

Name Description

cancelCardOperation

Cancels the previously initiated card operation.

This method returns an immediate response of type LibraryResult. Check if this result is OK, before continuing the operation. If the LibraryResult value is not OK, the system will not return the related callback with the asynchronous result. See here for more on extracting data from an event or callback.

You can only use this method when confirming balanceAcquiredCallback.

Parameters

Name

Type

Required

Definition

terminalIdOfTender

String

(tick)

Identifier for the terminal that processed the tender.

tenderReference

String

(tick)

Reference for the tender that will be cancelled.

C library integration

Applicable for library version 1.4.3 

Use the C Library Integration to integrate your POS solution with the Adyen Platform.

C library integration last update

Version
Date
Changes
4.0.1 2016-9-1
  • Fixed codeblock issue
  • Improved layout
Version
Date
Changes
4.0.1 2016-9-1
  • Fixed codeblock issue
  • Improved layout
4.0 2015-12-04
  • Documentation migration from PDF to web-based online deliverable as a main distributable asset.
  • Versioning: version reset and adoption of semantic versioning as per v. 4.0.0.
  • Manual redesign to improve readability, navigation, content search.

Getting Started - C Library Integration

Get started with using the C Library integration. Review details regarding registration of the POS app and terminal, make calls and receive callbacks as well as Enums and their respective results and states.

C library transaction flow

The sequence of events required to perform a transaction are summarized in the steps:

  1. Initialize the library (init_task)
  2. Register the POS (register_app)
  3. Register the PED (register_device)
  4. Start a transaction (create_tender)  this step can be repeated as many times as required
  5. Exit the library (exit_task)

Architecture

Calls and callbacks

Calls to the library are handled asynchronously. All calls to the library return directly and results are reported back by callbacks that are registered with the PED initialization. All calls to the library are therefore non-blocking.

Since processing is done asynchronously and callbacks are required to get additional info from the attendant, a number of callback routines need to be specified. These respond to the above calls whenever additional input is required.

These callbacks are:

  • library initialization callback
  • register the POS callback
  • register the PED callback
  • create_tender callback
  • additional data callback
  • confirm receipt callbacks
  • confirm signature callback
  • progress event callback
  • final transaction result callback
  • library exit callback

ENUMS

Results, states and other fixed values are represented by enums in the library, and these enums are contained in the adyen_enum.h file. Helper functions are available to convert strings to enums and enums to strings.

The POS App should use the enumerated values and not the underlying integer values. For example, if a value of an enum should be stored on disk, the string should be stored, and not the integer value.

Initializing and exiting the library

On start and shut down of the POS device, the library needs to be initialised and exit respectively.

Initialize the library

Initialize the library by making a call to the library with input parameters and process the callback that is invoked by the library after initialization.

The call and the callback are on purpose made asynchronous, to prevent the call from blocking the calling thread.

Method

Name Description
init_task Call this method with the provided parameters to initialize the library.

Parameters

Name Description
ADYEN_RESULT An enum that indicates if the request was successfully received. Note that this is not the final result of the call. The final result is reached when the callback is received from the library in response to the library initialization call.
init_result
Should be ADYEN_OK, if this is not the case, something has gone wrong. In this case, check the input to the call and if it cannot be resolved, log the result and contact  Adyen POS Support Team
init_task Method used to initialize and exit the library depending on the parameters it passes.
initReq A pointer to the init_library_request struct, this struct contains all the input parameters for this call.
initialization_CB A pointer to the callback function in the POS that is called with the results of the initialization call.
echo_struct A pointer to a POS defined struct that can be set by the POS that is echoed back in the callback, it can be used to share a POS data struct between the call to the library and the callback from the library in response to the call.

Code example

ADYEN_RESULT init_result = init_task(initReq*, initialization_CB, echo_struct*);

initialization_CB

Method

Name Description

initialization_CB

The POS needs to wait for the initialization callback before continuing with other functions, like boarding the POS systems and PED devices, and performing transactions.

Parameter

Name Description
 result The result parameter in the callback has no meaning. After the callback is invoked, the POS can continue.

Code example

The callback function declaration is:

void initialization_CB(void * result, echo_struct*);
init_library_request

Contains the following data elements:

Name Description
environment Defines the environment, ENVIRONMENT_TYPE values: ENVIRONMENT_LIVE or ENVIRONMENT_TEST
library_log Pointer to a function that is called for every log line produced by the library, where the POS can decide for instance to print it, write it to a file, discard it etc.

Depending on the environment parameter, transactions are executed in either Adyen LIVE or TEST environment.

Code example

The log function declaration is:

void function(char* header, char *data);

The header contains a timestamp and tender reference amongst others, the data contains the actual log data.

init_library_request formatting function

Method

Name Description
init_library_request_to_string Function available to format the init_library_request for printing and logging. The buffer should be allocated by the POS using the INIT_LIBRARY_REQUEST_LOG_SIZE value to indicate the maximum number of bytes to be used and should be freed by the POS afterwards.

Code example

The function declaration is:

init_library_request_to_string(char *buffer, init_library_request *);
Log file

The SDK package contains a folder documentation/log_files/documentation. This folder contains log files of actual test runs that relate to the items discussed in this manual.

The init_task.log file that shows a live example of the library initialization call and the related callback.

Exiting the library

The call and the callback are asynchronous to prevent the call from blocking the calling thread.

Method

Name Description
init_task  Method used with provided parameters to exit the library.

Code example

ADYEN_RESULT init_result = init_task(exit_CB, echo_struct*);

Parameters

Name Description
ADYEN_RESULT An enum that indicates if the Adyen platform has successfully received the request . Note that this is not the final result of the call. The final result of the call is in a callback returned by the system to the library initialization call.
init_result Should be ADYEN_OK, if this is not the case, something has gone wrong. In this case, check the input to the call and if it cannot be resolved, log the result and contact Adyen POS Support Team
init_task Method used to initialize and exit the library depending on the parameters it passes.
exit_CB Pointer to the callback function in the POS that is called with the results of the exit call.
echo_struct Pointer to a POS defined struct that can be set by the POS that is echoed back in the callback, it can be used to share a POS data struct between the call to the library and the callback from the library in response to the call.

Callback

The callback function declaration is:

void exit_CB(void * result, void * echo_struct);

The POS must wait until the callback is returned, the library has been successfully discarded and all related resources are destroyed before continuing with other functions

Log file

The SDK package contains a folder documentation/log_files/documentation. This folder contains log files of actual test runs that relate to the items discussed in this manual.

The exit_task.log file that shows an example of the library exit call and the related callback.

Registration

Before using the POS systems and connected PED devices to process transactions on the Adyen platform, the POS system and the PED both need to be authenticated and authorised (at least once) with the Adyen platform.

Authenticate and authorise the POS by supplying the Adyen provided credentials.

The POS can then authenticate and authorise any PED that is connected to it. After POS and PEDs are authenticated and authorised, they are registered in the POSTFM system. This system can be accessed in the Adyen Customer Area (CA) area.

POS registration - C library

The POS is authenticated and authorized by making a call to the library with input parameters and processing the callback that are invoked by the library after the POS registration has been processed.

The call and the callback are made asynchronously to prevent the call from blocking the calling thread.

The merchant account, user id and password that are required to authenticate and authorize the POS are provided by Adyen when the required accounts are being set up.

Code example

The declaration of the call to register the POS is:

ADYEN_RESULT register_app(register_app_req, register_app_CB, echo_struct);
Value Description
register_app_req Pointer to the register_app_request struct, this struct contains all the input parameters for this call.
register_app_CB Pointer to the callback function in the POS that is called with the results of the register_app call.
echo_struct Pointer to a POS defined struct that can be set by the POS that is echoed back in the callback, it can be used to share a POS data struct between the call to the library and the callback from the library in response to the call.

register_app_request

The register_app_request struct contains the following data elements:

Value Description
merchant_account Pointer to the merchant account.
user_id Pointer to the user id.
password Pointer to the password.
app_id Pointer to a unique POS identifier.

The app_id needs to be an identifier that uniquely identifies the POS system within the merchant realm and needs to be provided by the POS to the library.

The first three parameters are used to authenticate and authorise the POS, the last parameter is used as a key to register the POS.

The ADYEN_RESULT is an enum that indicates if the request was successfully received. This is not the final result of the call, the final result is reached when the callback is received from the library in response to the library initialization call.

The init_result should be ADYEN_OK, if this is not the case, something has gone wrong. In this case, check the input to the call and if it cannot be resolved, log the result and contact Adyen POS Support Team.

register_app_CB

Code example

The callback function declaration is:

void register_app_CB(register_app-response* , echo_struct*);

The POS needs to wait for the register app callback to happen, before it can continue with other functions, like boarding the PED device and performing transactions.

The register_app_response contains the following data elements:

Value Description
register_app_status The response on the register app request; an enum of type REGISTER_APP_STATUS that indicated the result of the register app call. The result should either be AppRegistered (the first time) or AppAlreadyRegistered (subsequent time). Any other response indicates failure, in which case the ped_result_code and error_message might be populated as well to provide more detail.
supported_currencies_size Number of supported currencies; defines the number of currencies recorded in the supported_currencies array.
supported_currencies List of the supported currencies (ISO 4217); an array of strings containing ISO 4217 currency codes that are supported, these are configured on a per merchant basis in the Adyen system.
supported_payment_methods_size The number of supported payment method;  defines the number of payment methods recorded in the supported_payment_methods array.
supported_payment_methods The supported payment methods; an array of payment_method structs, containing an AID (optional) and a description. The AID can be present multiple times, in the case of co-branding of cards for instance. It contains all the payment methods that can be used by the merchant, including eCom payment methods. These are configured on a per merchant basis in the Adyen platform.
For a full list of AID's, see the following: https://www.eftlab.com.au/index.php/site-map/knowledge-base/211-emv-aid-rid-pix
associated_merchants_size The number of associated merchants; the number of merchant accounts in the supported_payment_methods array.
associated_merchants The associated merchant accounts; an array of merchant accounts that can be used. These are configured on a per merchant basis in the Adyen platform.
ped_result_code The result of the PED; an enum of type PED_RESULT_CODE and is populated in case of failure. The values of this field are self explanatory.
error_message Error message in case the request failed;  a textual message that might give additional information in case of failure.

Helper functions

There is a function available to format the register_app_request for printing and logging.

The buffer should be allocated by the POS using the REGISTER_APP_REQUEST_LOG_SIZE value to indicate the maximum number of bytes to be used and should be freed by the POS afterwards.

Request 

The function declaration is:

register_app_request_to_string(char *buffer, register_app_request *);

Response

The function declaration is:

register_app_response_to_string(char *buffer, register_app_response *);

Log files

The SDK package contains a folder documentation/log_files/documentation. This folder contains log files of actual test runs that relate to the items discussed in this manual.

Please see the register_app.log file that shows a live example of the register app call and the related callback.

PED registration - C Library

A PED is authenticated and authorised by making a call to the library with input parameters and processing the callback that will be invoked by the library, once the PED registration has been processed.

The call and the callback are made asynchronously to prevent the call from blocking the calling thread.

The PED can only be registered after the POS has been authenticated and authorised. If this is not the case, the call fails.

Code example

The declaration of the call to register the PED is as follows:

ADYEN_RESULT register_device(register_dev_req*);

register_dev_req: A pointer to the register_device_request struct, this struct contains all the input parameters for this call

register_device_request

The register_device_request contains the following data elements:

Value Description
address The address of the PED to be registered. For PEDs connected directly to the Internet, it is the URL of the PED (for example https://localhost:8443/) For PEDs connected to a serial port, it is the COM port (like: /dev/ttyS0 or /dev/ttyUSB0, etc.).
callbacks An array with callback function pointers; struct of type device_callbacks defines the callbacks that are used by the PED to communicate with the POS. The relevant one at this stage is the device_state_update_CB, that will be triggered to report the device status. The other callbacks are related to performing transactions. The callbacks struct also defines an echo_struct pointer, which allows the POS to pass a pointer to a POS specific struct, that is echoed back during any of the callbacks.
posregister_configured_name A unique name of the POS to be set by the POS. This is recorded in the Adyen platform with transactions.
posregister_mac_address The POS MAC address; the MAC address of the POS to be set by the POS. This is recorded in the Adyen platform with transactions.
number_of_payment_device_options The number of payment device options; the number of payment device options in the PAYMENT_DEVICE_OPTION array.
device_options An array with payment device options; enum of type PAYMENT_DEVICE_OPTION and defines some options that can be passed on to the PED.

register_device_CB

Code example

The callback function declaration is: 

void register_device_CB(void* , ped_device_info*, echo_struct*);

The POS needs to wait for the register device callback to happen, before it can continue with other functions, in particular, performing transactions.

This callback not only arrives in response to a register_device call, it is also be called every time a change in device status occurs, It is possible to happen during a transaction.

The callback gets the following parameters passed:

Value Description
ped_device_info A pointer to a ped_device_info struct that defines the status and details of the PED.
echo_struct A pointer to a POS defined struct that can be set by the POS on the device_callbacks struct and which is being echoed back here.

The ped_device_info struct contains the following data elements:

Value Description
device_state

An enum of type ped_state and indicates the state the device is in. It should reach the status ped_state_operational before transactions can be done. Before arriving at that state, there might be multiple callbacks, that show a change in PED state. The meaning of the device states is terminal_id: unique reference to the PED and is recorded in the Adyen platform CA, both in the transaction view and in the:

  1. ped_state_offline
  2. ped_state_online
  3. ped_state_unregistered
  4. ped_state_identified
  5. ped_state_registered
  6. ped_config_synced
  7. ped_state_operational
  8. ped_state_tender
    This is the logical sequence the device state goes through. It is not mandatory that these states are cycled through always and in this order. The POS should react only to the ped_state_operational before performing a transaction, the other states are information only.
ped_state_offline The PED is offline.
ped_state_online The PED is online, but not yet operational.
ped_state_unregistered The PED is not yet registered.
ped_state_identified The PED is identified.
ped_state_registered The PED is registered.
ped_config_synced The PED configuration is synced from the Adyen platform.
ped_state_operational The PED is operational and can start a transaction.
ped_state_tender The PED is operational and has started a transaction.
POSTFM view  For each transaction, this PED iD is listed to trace back the origin of a transaction to the PED on which it had been executed. The POSTFM shows for each PED, all its configuration details and offers functions to change those.
 terminal_serial_number  The PED serial number.
 terminal_type  The PED terminal type.
 terminal_brand  The PED device brand.
 terminal_api_version  The PED API version.
terminal_os_version The PED OS version.
terminal_hardware_version The PED hardware version and only relevant during a transaction.
tender_reference The reference to a running transaction that is unique to the PED. It has no relevance during this callback function. This callback is triggered only when a transaction is started when no reference is available.

The terminal_serial_number, terminal_type, terminal_brand, terminal_api_version, terminal_os_version, and terminal_hardware_version data elements are used to define the exact state of the PED and to be used for investigation purposes whenever an issue might arise.

These data elements are recorded in the Adyen Customer Area (CA).

Helper Functions

A function available to pretty format the register_device_request for printing and logging.

The buffer should be allocated by the POS using the REGISTER_DEVICE_REQUEST_LOG_SIZE value to indicate the maximum number of bytes to be used and should be freed by the POS afterwards.

Code example

The function declaration is:

register_device_request_to_string(char *buffer, register_device_request *);

A function available to pretty format the ped_device_info for printing and logging.

The buffer should be allocated by the POS using the PED_DEVICE_INFO_LOG_SIZE value to indicate the maximum number of bytes to be used and should be freed by the POS afterwards.

Code example

The function declaration is:

ped_device_info_to_string(char *buffer, ped_device_info *);

Log files

The SDK package contains a folder documentation/log_files/documentation. This folder contains the log files of actual test runs that relate to the items discussed in this manual.

The register_device.log file that shows a live example of the register device call and the related callback.

Sale transaction processing

You can invoke two transaction related functions by the library:

  • Performing a transaction.
  • Canceling a transaction.

The general process flow

A transaction can be started by calling the appropriate function in the library, after which the library takes care of the processing of the transaction and returns the result to the POS application by calling the appropriate callbacks.

The result provided in the TENDER_STATE in the response_header, which is a parameter to the final state callback, can only be one of FINAL_STATE_APPROVED, FINAL_STATE_DECLINED,  FINAL_STATE_CANCELLED, or FINAL_STATE_ERROR.

In FINAL_STATE_DECLINED,  FINAL_STATE_CANCELLED, or FINAL_STATE_ERROR the additional information is available regarding the cause of the particular outcome.

During the execution of the transaction, additional communication may be required by the library from the POS application in order to complete the transaction. In those cases, the library invokes a callback routine as specified by the POS application.

The transaction may be cancelled, but in that case, the POS application may not assume the transaction is actually cancelled, and should continue to wait until the library announces the final state of the transaction by invoking the final transaction complete callback.

The following gives a simplified example of an approved (ICC) transaction with adjusted amount and (accepted) DCC quote:

  1. POS app starts sale transaction by making a call to the library.
    Library instructs the terminal to start the payment process. The terminal shows the amount and asks for a card and the customer inserts card.
  2. The Library informs the POS app that the card is inserted.
  3. The Library supplies the POS app with Loyalty data, Global Blue data, and Digital Customer Recognition data.
  4. The POS app responds to the Library with a final (adjusted) amount.
    The terminal shows the final amount. The terminal shows a DCC quote and asks the customer to confirm.
  5. The Library informs the POS app that DCC is confirmed.
    The customer enters PIN.
  6. The Library informs the POS app that the customer has entered PIN.
    Terminal goes online and validates payment.
  7. The Library supplies the POS app with the receipt.
    The POS app prints the receipt.
  8. The POS app responds to the Library that the receipt was printed.
  9. The Library informs the POS app that the payment is approved.

Perform sale transaction

Method

Name Description
create_tender Initiates the sale transaction, which triggers any relevant callbacks. The POS waits for the final state and the status_tender_final callback to report the final result of the transaction, even if a cancel request has been issued. The reason for this is that the transaction might already be in a state in which a cancel is not possible. The sale transaction includes the merchant account information, as this is used to register PEDs for multiple merchant accounts, and transactions can be performed on more than one of these merchant accounts.

Parameters

Value Description
create_tender_request Pointer to the create_tender_request struct, this struct contains all the input parameters for this call.
create_tender_CB Pointer to the callback function in the POS that will be called with the results of the create tender call
echo_struct Pointer to a POS defined struct that can be set by the POS that is echoed back in the callback, it can be used to share a POS data struct between the call to the library and the callback from the library in response to the call.

Code example

The declaration of the call to start a transaction is as follows:

ADYEN_RESULT create_tender(create_tender_request*, create_tender_CB*, echo_struct*);

Request

create_tender_request

The create_tender_request contains the following data elements:

Field Required Description
merchant_account (tick) The merchant account for this tender; under which merchant account the transaction should be executed. Transactions can be performed with any of the merchant accounts that were returned when registering the POS.
transaction_type (tick) An enum of type TRANSACTION_TYPES and for a sale transaction it must have the value GOODS_SERVICES.
reference (tick) A merchant reference that allows the merchant to identify the transaction.
order_reference (tick) Adyen order reference, which is used in special cases when reference needs to be made to an earlier transaction. If populated it must refer to the pspReference of an earlier existing transaction unless the transaction fails.
terminal_id (tick) The PED device ID; the unique PED device ID which is returned in the callback that is triggered after a PED device status change. This callback is defined in the callbacks struct in the register_device_request.
amount_currency (tick) The transaction currency; the currency of the transaction (ISO 4217).
amount_value (tick) The transaction amount; the amount of the transaction in minor currency units.
gratuity_amount_currency (error) The currency of any gratuity amount, if specified, which should match the transaction currency.
gratuity_amount_value (error) The amount of the gratuity in minor currency units. For an example, if the transaction amount, say for a few beers in a bar is EUR 9.00. and the shopper wishes to add EUR 1.00 as gratuity and when this is known by the person operating the POS, these two values can be specified separately and the total amount will be EUR 10.00.
shopper_email (error) To allow for digital shopper recognition, optionally a shopper reference and/or a shopper email address may be supplied. See also the description under additional data callback, since the shopper email and shopper reference can also be supplied when confirming the additional data callback. For instance, when the additional data callback indicates that there is currently no shopper email registered for this customer, the shopper can be asked for his email address as part of the payment process.
shopper_reference (error) This field can be used to record the shopper reference with the transaction and can also be used to setup recurring or one-click functionality.
recurring_contract_name (error) An enum of type CONTRACT_NAMES.
recurring_contract_detail (error) The recurring contract detail or a recurring contract reference. Both these fields are optional and are only used when the merchant wants to set up recurring or one-click functionality. See the recurring manual for more information.
number_of_tender_options (tick) The number of tender options specified.
tender_options (tick) An enum of type TENDER_OPTIONS that can have the following values:
  1. ReceiptHandler
  2. GetAdditionalData
  3. Recurring
  4. OneClick
  5. BypassPin
  6. AskGratuity
  7. NoProcess
  8. KeyedEntry
ReceiptHandler (tick) Defines that the POS wishes to receive the receipts and takes care of printing the receipts. If the ReceiptHandler tender option is omitted, the PED prints the receipt (if it contains a printer unit).
GetAdditionalData (tick) Defines that after a card is read, additional data is gathered and made available to the POS during the transaction. The amount of the transaction can be changed, based on additional input from the POS. When DCC is used, the GetAdditionalData tender option must be specified.
Recurring (tick) Invokes the functionality to perform recurring payments based upon the payment details collected with this transaction.
OneClick (tick) Invokes the functionality to register shopper reference and shopper email data (digital customer recognition). When this option is used, the payment details can later be used in an Ecom transaction, to allow the shopper to perform a one-click payment.
BypassPin (tick) Can be used to bypass the PIN entry by the shopper, which can be used in situations where a rather low amount is to be paid, in order to speed up the transaction process.
AskGratuity (tick) Can be used to initiate a question on the PED whether or not the shopper wants to offer a tip, which for instance can be useful in restaurant environments.
KeyedEntry (tick) Required for MKE processing. If set to true, this allows the merchant or cardholder to enter the card number manually in case the magnetic stripe and chip do not work, or if a phone order is taken.
number_of_additional_data_entries (tick) Defines the number of entries in the additional_data array.
additional_data (error) Contains key/value pairs that can be used by the merchant to specify selected key/value pairs, which will be echoed back during the  transaction, in particular in the final transaction result.

In order to allow the library to issue a callback in each of the callback situation, callback functions in the POS application need to be provided to the library. The callback functions are registered during the register device stage, where the callbacks handlers are specified in the callbacks structure of the register_device_request. The following callback functions need to be specified:

The MKE and confirm referral callbacks are not yet active and are planned to be added in a future release.

Payment process exclusively controlled by PED

It is extremely important to note that the payment process is exclusively run by the PED.  The PED is the only point at which the status of the transaction is known. This implies that the POS application may never assume any finalising state of the transaction. The POS always needs to wait for the final state of the transaction as indicated by the library. Even in the case that the POS decides to cancel the transaction, the POS application should continue to wait until the Library has provided the final state of the transaction.

Callback function

Callback

Name

Description

create_tender_CB

Callback to the create_tender call. The POS needs to wait for the register device callback to happen, after which a number of other callbacks can take place, until the callback with the final transaction result. Another transaction can only be started when the final transaction result is received.

The create_tender call only starts a transaction, so the callback is only related to the start of the transaction it self. It does not tell anything about the status and/or result of the whole transaction. The transaction result is provided by the library by calling the final transaction result callback in the POS application.

Parameters

The create_tender_response contains the following data elements:

Data element Description
tender_reference A reference of the transaction that is unique for the PED device, it is generated by the PED device. For subsequent actions on the transaction, this reference is used.
create_tender_status

The result of the call.

An enum of type CREATE_TENDER_STATUS and it should have the value created to indicate that the transaction is successfully started.

If the result is an error, either the library_result_code (library related errors) or the ped_result_code (PED originated errors) provides more detail.

library_result_code

The result of the library; an enum of type ADYEN_LIBRARY_RESULT and is populated in case of a failure by the library. In case the create_tender_status is an error, the library_result_code must be checked first since it indicates if the library process itself has performed correctly.

This field should be ADYEN_REMOTE_OK, if not there is an internal error that should be reported to Adyen.

ped_result_code

Result of the PED; an enum of type PED_RESULT_CODE and must subsequently be checked. This field indicates the error that has occurred on the PED. It can have a number of values that are documented in the adyen_enum.h file, see under the Create Tender heading.

  • The “UNFINISHED_TENDER” error specifies that a tender is still running on the PED. The tender_reference here indicates the tender reference of this unfinished tender. This reference can then be used to either continue the unfinished tender or to cancel the unfinished tender. Subsequent callbacks refer to the unfinished tender. 
    In both cases, continue or cancel, you should wait for the final callback on the unfinished tender before a new tender can be created. The result is also required when the tender is cancelled, since there is no guarantee that the unfinished tender can be cancelled, the tender for instance could already have reached the APPROVED status.
 error_message Message in case of an error. 

Code example

The final transaction result callback function declaration is:

void create_tender_CB(create_tender_response*, void * echo_str)

Cancel a transaction

Method

Name Description

cancel_transaction

A transaction can be cancelled by calling this function in the library, after this library processes this request.

The POS application may not assume the transaction is actually cancelled, and should wait until the library announces the final state of the transaction.

Parameters

Name

Description

terminal_id

The terminal ID of the PED.

tender_reference

A reference for the transaction to cancel.

Code example

The declaration of the call to cancel a transaction is:

ADYEN_RESULT cancel_transaction(char * terminal_id, char *tender_reference)

Helper functions

Request printing and logging

Method

Name Description
create_tender_request_to_string

Used to format the register_app_request for printing and logging. The buffer should be allocated by the POS using the CREATE_TENDER_REQUEST_LOG_SIZE value to indicate the maximum number of bytes to be used and should be freed by the POS afterwards.

Code example

create_tender_request_to_string(char *buffer, create_tender_request *);

Response printing and logging

Method

Name Description

create_tender_response_to_string

Used to format the register_app_library_response for printing and logging. The buffer should be allocated by the POS using the CREATE_TENDER_RESPONSE_LOG_SIZE value to indicate the maximum number of bytes to be used and should be freed by the POS afterwards.

Code example

create_tender_response_to_string(char *buffer, rcreate_tender_response *);

The SDK package contains a folder documentation/log_files/documentation. This folder contains the log files of actual test runs that relate to the items discussed in this manual.

The create_tender.log file shows a live example of the register app call and the related callback.

The Progress callback

Method

Name

Description

progress_callback The progress callback provides additional information during the transaction regarding the progress of the transaction. There are various situations where progress information is supplied.

It is not mandatory to process these progress events and they should only be used to inform applications and people of the progress, they are for information only, they might occur or they might not occur, and the order in which they occur might be different. They should never be used to act upon, for instance as part of a state machine flow or any other kind of functional processing. Instead, the callbacks should be used for that.

Parameters

Name Description
ped_device_info For a description of the ped_device_info, see register device callback.
response_header

For a description of the response_header, see additional data callback.

The response_header indicates the progress state of the transaction in the state data element, which is an enum of type TENDER_STATE. Additional information might be provided in the additional_data struct.

additional_data

The additional_data_count defines the number of key/value pairs in the additional_data.

The additional_data struct contains the following key/value pairs (if available): status_info gives additional information

 For example if TENDER_STATE is:

  • APPLICATION_SELECTED - The status_info contains the application preferred name.
  • CARD_SWIPED - The status_info may contain the text “fallback” when it is a fallback transaction.
  • PIN_ENTERED - The status_info contains the number of pin digits entered so far.

Code example

The declaration of the progress callback is:

void progress_callback(response_header*, ped_device_info*, void * echo_struct)

Enable third party sharing using the additional data object

You may need to share information with third party service providers. For example, if a tourist purchases an item from your store, and wants to reclaim VAT, you will need to share this information with a tax free provider. You can do this by enabling third party sharing using the additional data object.

Code example

Use the following helper function to set the flag to true:

additional_data_struct *AD_obj = allocate_additional_data();
add_additional_data_kvp_by_id(AD_obj, "taxfree.indicator", "true");

Once this flag has been set, you will pass the additional_data_obj object as part of the confirm_additional_data call. 

Additional data callback - C Library

The additional data callback is invoked after a card is inserted or swiped if the create_tender_request has defined the option GetAdditionalData. The card number is used as a key to collect relevant additional data. This facility can be used to make additional data available to the POS during the transaction, right after a card has been read by chip or stripe. Apart from the general card information,there are two optional additional relevant sets of data.

The loyalty data for merchant branded cards and/or recurring references in case of a non-merchant card (1) and Global Blue data (2). This includes Digital Customer Recognition data. This option is also required when the merchant wants to implement DCC.

The relevant loyalty data is passed through as is retrieved from the merchant loyalty database. When a merchant managed loyalty system needs to be consulted. A communication link needs to be setup between Adyen and the merchant system. The merchant guarantees that no sensitive data elements, like the card number etc. that would bring the merchant into the scope of PCI DSS, are present in the loyalty data that is passed through.

Furthermore, on starting the transaction the shopper reference and/or shopper email address may be provided, both for merchant cards and other cards. If the card has been used before, then the existing alias, last used shopper reference and last used shopper email address is returned. If no alias is present yet, then one is generated. If a shopper reference is provided at the start of the transaction, it is recorded as the last used shopper reference, the same applies for the shopper email address. In these cases, the shopper reference and shopper email address are echoed back.

The merchant can use the standard Adyen facilities for recurring payments, by either using the alias or the shopper reference to retrieve the recurring details against a specific customer. These recurring details can then be used to submit subsequent recurring transactions. The shopper recognition details can also be used to support one-click payments in the web shop.

If recurring details have not previously been recorded, but the merchant intends to record recurring details as part of the current transaction, then the recurring details are recorded only when the payment is authorised. Recurring payments can not be processed against cards that are not authorised.

Some schemes do not allow recurring payments, contact Adyen Support Team for more information.

The shopper reference and/or the shopper email address can be provided in the TransactionRequest is passed to the library when starting such a transaction.

Code example

The additional data callback function declaration is:

void additional_data_CB(response_header*, ped_device_info*, void * echo_struct)
Response

The response_header contains the following data elements:

Field Description
tender_reference Reference of the transaction that is unique for the PED device, it is generated by the PED device.
request_reference Internal PED reference that is only relevant for debugging, it has no further relevance here.
state Enum of type TENDER_STATE and contains the transaction state, which is ADDITIONAL_DATA_AVAILABLE.
library_result_code Enum of type LIBRARY_RESULT_CODE and contains the result of the library processing and should be ADYEN_LIBRARY_OK, if this is not the case, the error should be reported to Adyen.
ped_result_code Enum of type PED_RESULT_CODE, which can indicate ERROR, in which case the error_message provides more detail. Other values have no further relevance and can be ignored.
error_message

Error message in case of error.

For instance, if there is a network failure when the payment device wants to retrieve the additional data, it continues with a subset. In this case there is no alias.

If the shopperReference was not set, it cannot be created by using the alias. In this case the transaction ends with result ERROR with the message: “Cannot create dummy shopper reference because alias is not set”. You an decide if you want to continue with the transaction.

additional_data_count Number of additional data entries, defines the number of key/value pairs in the additional_data.
additional_data Additional data (key/value pairs) struct contains the following key/value pairs (if available).

Transaction data:

Field Description
PosEntryMode POS entry mode (ICC/MSR/MKE/CLESS_CHIP/CLESS_SWIPE).
merchantReference Merchant reference of this transaction.
txdate Transaction date, like (14-8-2018).
txtime Transaction time, like (09:37:21).
iso8601TxDate ISO timestamp, like (2018-08-14T09:37:27.0000000+0000).
transactionType Transaction type.
posOriginalAmountValue Original transaction amount.
posAuthAmountCurrency Transaction currency (like: EUR).
posAuthAmountValue Transaction amount (like: 100, which is € 1.00).

Customer Data:

Field Description
alias Unique PCI safe card alias.
loyaltyData Loyalty data as retrieved from merchant loyalty system.

Digital Customer Recognition data:

Field Description
shopperReference Shopper reference.
shopperEmail Shopper email.

Card Data (including date check for tax free eligibility):

Field Description
AID Full AID, like (A000000004101002).
posEntryMode POS entry mode (like ICC).
applicationLabel Application label.
applicationPreferredName Application preferred name.
cardEffectiveYear Effective year (format: YYYY).
cardEffectiveMonth Effective month (format: MM).
cardBin First six digits of card number.
cardSummary Last 4 digits of card number.
cardIssueNumber Card issue number.
tid Terminal id at the acquirer.
cardHolderName Cardholder name.
cardIssuerCountryId Card issuer ISO 3166 country code (like 840).
paymentMethod

The  scheme of the payment method used, e.g. Visa, MasterCard etc.

paymentMethodVariant

The  type or sub-brand of payment method used, e.g. Visa Debit, Visa Corporate, etc.

expiryMonth Expiry month, like (02).
expiryYear Expiry year, like (2028).
error_message Textual message that might give additional information in case of failure.
Confirm additional data call

Method

Name Description
confirm_additional_data After the additional data callback from the PED has been received by the POS, the POS must confirm this in order to continue the transaction. At this point, based upon the information received during the callback, the amount can be adjusted. The currency must be the same as the original currency.

Example

1) Assume a transaction was started for EUR 10,00.

2) Assume the loyalty data received in the call indicates this is a shopper that is eligible for a discount of 10%. In this case the amount can be changed to EUR 9,00.

It is also possible to record at this point shopper reference and shopper email, say in case the shopper has been identified at that stage.

Parameters

Field Description
terminal_id Terminal id of the PED.
tender_reference The tender_reference of the transaction.
adjust_currency The currency of the transaction (must match original currency).
adjust_amount The adjusted amount.
shopper_reference The shopper reference.
shopper_email The shopper email.
additional_data_obj Object used to hold additional data

Code example

The declaration of the call to confirm the additional data callback is as follows:

void confirm_additional_data(char *terminal_id, char * tender_reference, char * adjust_currency, char * adjust_amount, char * shopper_reference, char * shopper_email, additional_data_struct * additional_data_obj);

If you wish to finish the originally started transaction without making any changes, or adding new information, enter the terminal_id and tender_reference and set all other fields to NULL.

Dynamic Currency Conversion callback

Method

Name

Description

progress_callback The DCC callback is invoked through the Progress callback when a currency conversion option is presented to the shopper. This allows the POS to indicate this on the POS screen and to provide the details of the currency conversion option also to the shop agent.

Parameters

Name Description
ped_device_info For a description of the ped_device_info, see register device callback.
response_header

For a description of the response_header, see additional data callback.

indicates the progress state of the transaction in the state data element, which is an enum of type TENDER_STATE. In this case it will be ASK_DCC. Additional information might be provided in the additional_data struct.

additional_data

The additional_data_count defines the number of key/value pairs in the additional_data.

The additional_data struct contains the following key/value pairs (if available):

Code example

void progress_callback(response_header*, ped_device_info*, void * echo_struct)

DCC Returned Details

The DCC details extracted via the standard mechanism contain the following keys (values mere examples):

Fields Description
dcc.markup The markup percentage (300 = 3%).
dcc.commissionfee The commission fee in minor units (not used at the moment, e.g. 0).
dcc.exchangerate The exchange rate (16178 = 1.6178).
dcc.converted.amount.value The amount after conversion (minor units).
dcc.converted.amount.currency The currency after conversion (like USD).
dcc.org.amount.value The original amount (minor units).
dcc.org.amount.currency The original currency (like EUR).
dcc.source The exchange rate source (like oanda).

Helper functions

Functions are available to format the response_header and ped_device_info for printing and logging.

A function is available to extract additional data values from the additional_data struct, see get_additional_data_value function in additional_data.h.

The SDK package contains a folder documentation/log_files/documentation. This folder contains log files of actual test runs that relate to the items discussed in this manual.

The dcc_callback.log file that shows a live example of the register device call and the related callback.

The Print receipt callback

Callback

Name Description
print_receipt_CB Invoked whenever there is a receipt available on the PED that needs to be printed. Receipt printing is part of scheme certification. Print receipt functionality in the POS is the only way to print receipts when the PED does not include a printer, or in cases where the merchant wishes to archive or email the receipt instead of printing. The POS must then confirm that the receipt was received and printed.

Tender options

Name Description
ReceiptHandler  If specified, the print receipt callback is invoked, if not specified it is not invoked. If the ReceiptHandler tender option is not specified and the PED does not have a printer, the transaction fails in violation with the certification requirements.

Receipts might need to be printed multiple times. For example, when an approved receipt is printed to allow the shopper to set his signature. If the merchant then disapproves that signature after checking it with the signature on the back of the card, a cancel receipt needs to be printed. So, each invocation of the print receipt callback implies a new receipt.

Receipts provided by Adyen are certified. If the merchant builds its own receipts, care must be taken to include all the data elements that are required by certification. Any issues that may arise from an incorrect composition of receipts is the at the liability of the merchant.

Code example

The print receipt callback declaration is:

print_receipt_CB(receipts_strct *, ped_device_info *, void * echo_struct))

receipts_strct

The receipts_strct contains the actual receipts and contains:

Field Description
info response_header struct
merchant_receipt Receipt struct
card_holder_receipt Receipt struct

response_header

The response_header contains the following data elements:

Field Description

tender_reference

Reference of the transaction that is unique for the PED device, it is generated by the PED device.
request_reference Internal PED reference, only relevant for debugging.
state Enum of type TENDER_STATE and contains the transaction state, which is PRINT_RECEIPT
library_result_code Enum of type LIBRARY_RESULT_CODE and contains the result of the library processing and should be ADYEN_LIBRARY_OK, if this is not the case, the error should be reported to Adyen.
ped_result_code Enum of type PED_RESULT_CODE, which can indicate ERROR, in which case the error_message provides more detail. Other values have no further relevance and can be ignored.
error_message Error message in case of error.
additional_data_count Defines the number of key/value pairs in the additional_data.
additional_data Additional data (key/value pairs); struct contains the following key/value pairs (if available): please see the description under the additional data callback. Together with the formatted merchant and cardholder receipt, all data elements that are on the receipt are provided in the additional data that is contained in the response header. This allows the merchant to query specific property values of receipt data elements and ultimately it allows the merchant to compose its own receipt.

The receipt struct contains the following data elements:

Field Description
number_of_header_lines Number of header lines.
header Array of receipt_line struct.
number_of_content_lines Number of header lines.
abbreviation Deprecated.
content Array of receipt_line struct.
number_of_footer_lines Number of header lines.
footer Array of receipt_line struct.

The receipt_line struct contains the following data elements:

Field Description
line_key Deprecated.
position Deprecated.
name Label (left justified on the line).
abbreviation Deprecated.
value Value (right justified on the line).
format Format.

The format is an enum of type RECEIPT_LINE_FORMAT. For example,  RECEIPT_LINE_FORMAT_SignatureArea means that an area should be left open on the receipt to allow the cardholder to set their signature.

The MerchantReceipt also contains a separate key/value pair in the additional_data with the key signatureOnReceipt, and value true, in case the receipt needs to be printed to allow the shopper to sign the receipt.

Response header printing and logging function

Name Description
status_tender_response_to_string

Formats the response_header for printing and logging with a help of a function. The buffer should be allocated by the POS using the STATUS_TENDER_RESPONSE_HEADER_LOG_SIZE value to indicate the maximum number of bytes to be used and should be freed by the POS afterwards.

Code example

The function declaration is:

status_tender_response_to_string(char *buffer, response_header *);

Receipt printing and logging function

Name Description
receipt_to_string Formats the receipt into a string. The buffer should be allocated by the POS using the RECEIPT_LOG_SIZE value to indicate the maximum number of bytes to be used and should be freed by the POS afterwards.
print_receipt Function used to print the data in the receipt, with a width value to specify paper width.

Code examples

The function declarations are:

receipt_to_string(buffer, receipt *);
print_receipt(receipt *, int width);

The SDK package contains a documentation/log_files/documentation folder. This folder contains log files of actual test runs that relate to the items discussed in this manual.

The print_receipt.log file that shows a live example of the register device call and the related callback.

Confirm Print Receipt Call

In response to the print receipt callback, a call must be made to inform the Library that the App has completed printing the receipt. The transaction continues after this confirmation has been received.

Code example

The declaration of the call to confirm the print receipt callback is as follows:

confirm_print_receipt(char * terminal_id, char * tender_reference, boolean confirmation);

Parameters

Field Description
terminal_id Terminal id of the PED.
tender_reference Tender reference of the transaction.
confirmation Confirmation (true/false).

The check signature callback

Method

Name Description
check_signature_CB

Whenever a shopper signature is required, on the touchscreen of the PED or on a printed paper receipt, this callback is invoked. For the transaction to proceed, this must be confirmed by the PED to indicate the signature is accepted or declined by the merchant.

  • If the signature is set on the touchscreen of the PED, the relevant data is displayed on the display of the PED, and the shopper can sign on the touch screen display of the PED. The check signature callback then invokes the merchant to accept or decline the signature. In that case, the response header contains a graphic representation of the signature, so it can be shown on the POS.
  • If the signature is set on a printed paper copy of the receipt, the signature also needs to be confirmed. In this scenario, there would not be no graphical representation of the signature.

In both cases, it is assumed that the merchant is checking the signature against the signature on the back of the card, before confirming and accepting the signature.

Parameters

Field Description
response_header Pointer to the response_header struct, this struct contains all the input parameters for this call.
ped_device_info Pointer to the ped_device_info struct in the POS that is called with the results of the create tender call.
echo_struct Pointer to a POS defined struct that can be set by the POS that is echoed back in the callback, it can be used to share a POS data struct between the call to the library and the callback from the library in response to the call.

The state is an enum of type TENDER_STATE and contains the transaction state, which is CHECK_SIGNATURE.

The additional_data_count defines the number of key/value pairs in the additional_data. The additional_data struct contains the following key/value pairs (if available):

Field Description
signature.retries.available Number of signature retries available.
signature.mimetype Mime type of the image (like “image/bmp”).
signature.data Base64 encoded image.

For a description of the ped_device_info struct, please see the register_device_CB see the print_receipt.log file to see a live example of the register device call and the related callback.

Code example

void check_signature_CB(response_header *, ped_device_info *, void * echo_struct);
Confirming the check signature callback

Method

Name Description
 confirm_signature

In response to the check signature callback, a call must be made to inform the Library that the merchant has approved or declined the signature of the shopper. The transaction continues after this confirmation is received.

Code example

The declaration of the call to confirm the signature callback is as follows:

 confirm_signature (char *terminal_id, char *tender_reference, ATTENDANT_ACTION_CODE confirmation)

Parameters

Field Description
terminal_id Terminal id of the PED.
tender_reference Tender reference of the transaction.
confirmation

Enum of type a ATTENDANT_ACTION_CODE, indicating either ATTENDANT_ACTION_CODE_APPROVED, ATTENDANT_ACTION_CODE_DECLINED, ATTENDANT_ACTION_CODE_RETRY.

Final transaction result callback

The  tender_finished_cb contains the following data elements:

Field Description
final_strct Pointer to a final_strct struct that defines the final outcome of the transaction.
ped_device_info Pointer to a ped_device_info struct that defines the status and details of the PED, see earlier description of this struct.
echo_struct Pointer to a POS defined struct that can be set by the POS on the device_callbacks struct and which is being echoed back here.

The final_strct contains the following data elements:

Field Description
info Final result.
auth_code The authorisation code in case of APPROVED.
refusal_reason The refusal reason in case of DECLINED.
pos_result_code

The POS result code. Represents the response of the issuer.

As card approval is still required, the POS result code is not the final result of the transaction.

The info data is a response_header struct and contains the following data elements:

Field Description
tender_reference Tender reference.
request_reference Request reference.
state Final state of the transaction.
additional_data_count Number of additional data structs.
additional_data_ptr Array of additional_data structs, containing key/value pairs.

The state is an enum of type TENDER_STATE and defines the final outcome of the transaction, it can be one of the following:

  • FINAL_STATE_APPROVED
  • FINAL_STATE_DECLINED
  • FINAL_STATE_CANCELLED
  • FINAL_STATE_ERROR

This is different from ped_result_code APPROVED.

If the pos_result_code is FINAL_STATE_DECLINED, FINAL_STATE_CANCELLED or FINAL_STATE_ERROR, additional information is available in the pos_result_code, which is an enum of type POS_RESULT_CODE. Additional textual information might be available in refusal_reason and/or error_message. 

Referral callback C library

Method

Name

Description

referral_CB

The Issuer may reply to the authorisation request with a referral when the Issuer wants to get a call back by phone form the merchant to get additional information. The Issuer then can either approve or decline the transaction. If approved, an authorisation code is provided during the call which needs to be entered on the POS and submitted to the library.  A callback is made to the POS which needs to be confirmed with either an authorisation code or a decline.

The user that was used to register the POS must have the special permission API Authorise Referred Payments enabled else the referral fails. Contact Adyen POS Support Team  to resolve this.

Parameters

Field Description

response_header 

A pointer to the response_header struct, this struct contains all the input parameters for this call

ped_device_info

A pointer to the ped_device_info struct in the POS that will be called with the results of the create tender call

echo_struct

A pointer to a POS defined struct that can be set by the POS that will be echoed back in the callback, it can be used to share a POS data struct between the call to the library and the callback from the library in response to the call. 

For a description of the response_header, see the print receipt callback, with the following differences.

The state is an enum of type TENDER_STATE and contains the transaction state, which is REFERRAL.

For a description of the ped_device_info struct, see register_device_CB.

Additional Data Parameters

The additional_data contains entries for the following data elements:

Field Description

referralType

 The type of referral:

  • IssuerReferral
  • VoiceAuth
IssuerReferral

Used in case the PED is online.

VoiceAuth

Used in case the PED is offline.

referralReference

Referral reference.

originalReference

Reference of the original transaction.

cardBin

First six digits of the card number.

cardSummary

Last four digits of the card number.

paymentMethod

The  scheme of the payment method used, e.g. Visa, MasterCard etc.

paymentMethodVariant

The  type or sub-brand of payment method used, e.g. Visa Debit, Visa Corporate, etc.

posAuthAmountValue

Transaction amount (minor units)

posAuthAmountCurrency

Transaction currency, like “EUR”

Code example

The referral callback declaration is:

void referral_CB(response_header *, ped_device_info *, void * echo_struct); 
Referral Callback confirmation

Method

Name Description
confirm_signature In response to the referral callback, a call must be made to inform the library of the fact whether or not a referral code was received form the Issuer and if yes, what the authorisation code is.

A referral callback must be confirmed, either approved or declined. If this is not done, the library stays in that state forever. The library cannot perform time-out processing, since getting an authorisation code by phone might take 10 minutes, and such a timeout does not work. After confirmation, the POS needs to wait for the final callback of the library that delivers the final result of the transaction.

Parameters

Field Description

terminal_id

The terminal_id of the PED

tender_reference

The tender_reference of the transaction

confirmation

Enum of type a ATTENDANT_ACTION_CODE, indicating either:

  • ATTENDANT_ACTION_CODE_APPROVED
  • ATTENDANT_ACTION_CODE_DECLINED

auth_code

The auth code received from the Issuer.

Code example

The declaration of the call to confirm the referral callback is:

confirm_signature (char *terminal_id, char *tender_reference, char * auth_code ATTENDANT_ACTION_CODE confirmation)

Refund transaction processing

A refund transaction can be initiated in much the same way as a sale transaction, with the only difference that the transaction_type should be specified as Refund instead of GOODS_SERVICES.

For all refund types, an additional check is performed to make sure that there are enough funds available in the merchant account. Care should be taken in interpreting the FINAL_RESULT_APPROVED tender state. It only means that the refund transaction has been received  and has been accepted for processing.

Refunds are not processed online real-time, since many acquirer/issuers process those by offline batch processes, by which the final result is only  known after a some time. So, only basic checks can be performed when the refund is submitted and no guarantee can be given that the refund indeed is accepted by the Issuer. Failure is exceptional but there can be rare cases,

When notifications are configured, the result of the transaction is transmitted via a notification, as soon as the result has been retrieved from the issuer. By processing these notifications, merchants can reconcile their refunds and if one has failed at processing by the Issuer, actions can be taken to repeat the refund or take other means of reimbursing the shopper.

If at the time of any refund transaction the Internet connection is not available, the transaction is queued and submitted when the Internet connection is restored.

A DCC transaction should be refunded in the currency paid by the shopper, irrespective of any exchange rate changes that might have happened during the time since the original transaction. This is required by scheme regulations.

As an example. An Amsterdam Merchant (currency EUR) sells an item of € 10.00 to a US citizen, who selected DCC and paid $12.00, exchange rate being 1.2000; After some time, the refund is granted, but the exchange rate is now 1.3000. The refund needs to be done for $12.00, which amounts to € 9.23.

In this case, there is a loss to the merchant of € 0.77.

It could also work the other way around, resulting in a profit for the merchant. Since this refund capability is basically a means to hand out money, it is restricted by permissions that can be set for the merchant in the Adyen system and on the PED.

It is disabled by default.

When using this types of refunds, merchants need to build specific security measures around this functionality to make sure that no fraudulent actions can be initiated by using these facilities.

The SDK package contains a documentation/log_files/documentation folder. This folder contains log files of actual test runs that relate to the items discussed in this manual.

The refund.log file that shows a live example of the register device call and the related callback.

Android integration

This guide will help you integrate your existing POS system, which runs on Android, with the Adyen platform. If you have any question after completing this tutorial, contact the Adyen Support Team.

To proceed with this tutorial you should sign up for a test account. If you haven't done so yet, submit your details on this page.

Install the library

  1. Download the Adyen library sources from Adyen Customer Area (CA) → Reports → POS Libraries. On this page, download the latest version of Android library and a sample Android app, which demonstrates how you can integrate the library with your existing Android application.

  2. Unzip the downloaded sources and add the library to your Android application.

  3. Run this code to register this instance of the library with Adyen:

     LibraryReal.registerLib(mApplicationContext, "YOUR_APP_NAME");
  4. Initiate the library in your app:

    try {
        lib = LibraryReal.getLib();
    } catch (NotYetRegisteredException exception) {
        Log.d(LOG_TAG, exception.getMessage());
    }

Register the app and the terminal

  1. Register your application with the Adyen library:

    lib.registerApp(MERCHANT_CODE, USER_NAME, PASSWORD, new RegistrationCompleteListener()) 
  2. Board a terminal:

    if (deviceInfo.isPaired() && !deviceInfo.isRegistered()) {
        // board the terminal
        boardTerminal(subscriber, deviceInfo);
    } 
    else {
        // does sync with the back office to get all settings (like dynamic currency converter and others)
        boolean synchronizeNow = false;
        // when updates are available for the terminal, they will be automatically pushed to it
        boolean installUpdateWhenAvailable = false;
    
        // on getTerminalIdentity we have the following:
        // the device is paired and registered already and
        // we get device information and settings from Adyen's back office
        // and the settings are pushed on the device
        lib.getTerminalIdentity(new AddDeviceListener())
    }
  3. In the boardTerminal method, add the addDevice call:

    lib.addDevice(new AddDeviceListener()

Accept payments

Once the device is added, you can start making payment requests:

  1. First implement the setPrintReceiptListener method to initialize an object to print receipts:

    private void setPrintReceiptListener() {
        // mandatory if a receipt handler tender option was added.
        lib.setPrintReceiptListener(new PrintReceiptListener() {
            @Override
            public PrintReceiptResponse onPrintReceiptRequested(PrintReceiptRequest printReceiptRequest) {
                PrintReceiptResponse response = new PrintReceiptResponse();
    
                response.setStatus(com.adyen.services.posregister.PrintReceiptResponse.Status.Printed);
    
                return response;
            }
        });
    } 
  2. Then implement the enableEagerConnection method, which checks if the terminal connection is active and reconnects to it, if necessary:

     public void enableEagerConnection(){
        // starts the terminal connect intent service
        // eager connection starts a DeviceInfoTask that checks for available updates
        // checkUpdatesAvailable (called also from DeviceRegistrationTask and PSPSyncTask) calls TerminalConfigUpdateIntentService.
        lib.enableEagerConnection();
    }

    Make sure you disable the eager connection when your app becomes inactive. For this, use the lib.disableEagerConnection method.

  3. Implement a transaction listener as follows:

     private TransactionListener mTransactionListener = new TransactionListener() {
    
        // integer - code of the error
        @Override
        public void onTransactionComplete(final CompletedStatus completedStatus, final String message, final Integer integer, Map<String, String> stringStringMap) {
    
            Toast.makeText(PaymentActivity.this, "tx listener: completed status:" + completedStatus.name() + " " + message, Toast.LENGTH_LONG).show();
    
            runOnUiThread(new Runnable() {
                @Override
                public void run() {
                    mAdyenPaymentWorker.disableEagerConnection();
    
                    mPayButton.setEnabled(true);
    
                    int color = getResources().getColor(android.R.color.black);;
                    switch (completedStatus) {
                        case APPROVED:
                            color = getResources().getColor(android.R.color.holo_green_dark);
                            break;
                        // happens for: amount too low, card reasons
                        // when canceling the tx via lib.cancelTransaction while the signature screen is displayed
                        // the tx is declined
                        case DECLINED:
                            // from a merchant or shopper
                        case CANCELLED:
                        case UNKNOWN:
                            // may occur when communication is lost; check outcome on a terminal or send cancelOrRefund.
                        case ERROR:
                            color = getResources().getColor(android.R.color.holo_red_dark);
                            break;
                    }
    
                    final String newStatus = completedStatus.name() + " " + message;
                    updateCompletionStatus(newStatus, color);
                }
            });
        }
    
        // state of the communication between the app and the terminal
        @Override
        public void onProgress(final ProcessStatus processStatus, final String message) {
    
            switch (processStatus) {
                // app is connecting to the terminal - just starts a connection
                case CONNECTING:
                    // identifying the terminal - the connection was established and now the terminal is identified
                case IDENTIFYING:
                    // the terminal is processing the payment
                case PROCESSING:
                    // the phone doesn't have internet connection
                case NONETWORK:
                    // the phone cannot connect to the Adyen backend (even if there is internet connection)
                case NOROUTE:
                    // the merchant or the shopper cancelled the tx
                case CANCELLING:
                    break;
    
            }
    
            runOnUiThread(new Runnable() {
                @Override
                public void run() {
                    Toast.makeText(PaymentActivity.this, "tx listener: process status:" + processStatus.name() + " " + message, Toast.LENGTH_SHORT).show();
                }
            });
        }
    
        // called when the tendered state changed (state of a payment)
        @Override
        public void onStateChanged(final TenderStates tenderStates, final String s, Map<String, String> stringStringMap) {
    
            runOnUiThread(new Runnable() {
                @Override
                public void run() {
                    String newStatus = tenderStates.name() + " " + s;
                    updateStatus(newStatus);
                }
            });
    
            switch (tenderStates) {
                //
                case PIN_DIGIT_ENTERED:
                    Log.d(LOG_TAG, "!! PIN_DIGIT_ENTERED !!");
                    break;
                // tx was initiated
                case INITIAL:
                    // a new tender was created
                case TENDER_CREATED:
                    // the card was inserted
                case CARD_INSERTED:
                    // the card was swiped
                case CARD_SWIPED:
                    // waiting for some input from the customer on the terminal
                case WAIT_FOR_APP_SELECTION:
                    // the customer selected something from the previous step
                case APPLICATION_SELECTED:
                    // waiting for an amount to be adjusted based on the gratuity
                case WAIT_FOR_AMOUNT_ADJUSTMENT:
                    // gratuity option was selected in tender options and the shuttle requests for it
                case ASK_GRATUITY:
                    // gratuity amount was entered
                case GRATUITY_ENTERED:
                    // dynamic currency conversion was selected in tender options
                case ASK_DCC:
                    // the conversion amount was accepted
                case DCC_ACCEPTED:
                    // the conversion amount was rejected
                case DCC_REJECTED:
                    // the payment is being processed (on the terminal you can see the progress bar)
                case PROCESSING_TENDER:
                    // pin is being requested on the terminal
                case WAIT_FOR_PIN:
                    // the user accepted the pin
                case PIN_ENTERED:
                    // for MKE the card details are requested
                case PROVIDE_CARD_DETAILS:
                    // for MKE the card details were provided
                case CARD_DETAILS_PROVIDED:
                    // starting printing the receipt (receipt generation)
                case PRINT_RECEIPT:
                    // the receipt printing was finished
                case RECEIPT_PRINTED:
                    // the acquirer sends a referral status
                case REFERRAL:
                    // the referral code was checked
                case REFERRAL_CHECKED:
                    // after the user has entered the signature, there's a check between the signature on the card and the one on the screen/receipt
                case CHECK_SIGNATURE:
                    // the signature matched the one on the card
                case SIGNATURE_CHECKED:
                    // additional data (like currency conversion rate, adjusted amount for gratuity and others) are available
                case ADDITIONAL_DATA_AVAILABLE:
                    // final states of a tx.
                case ERROR:
                case APPROVED:
                case DECLINED:
                case CANCELLED:
                    // transaction cancelled
                case UNKNOWN:  
                case ACKNOWLEDGED:
                    break;
            }
    
        }
    };
  4. Initiate the transaction:

    public void initiateTransaction(TransactionRequest transactionRequest, TransactionListener transactionListener) {
        enableEagerConnection();
        setPrintReceiptListener();
        // starts communication with the terminal and the payment process
        lib.initiateTransaction(transactionRequest, transactionListener);
    }

POS test system

Adyen provides a basic TEST system to simulate transaction scenarios and test functionalities before implementing them in the live system. Test cards are dummy payment cards which work in the Adyen test environment only. Transactions carried out with these test cards do not result in actual credits/debits to live (bank) accounts. In order to board a Test terminal and perform tests, you need test credentials which differ from live credentials. You also need a test terminal, configured with test keys instead of live keys.

When using the test system, set the environment to TEST upon initialization (using the appropriate flag for your library).

When switching the library between the live environment and test environment the app must re-register to make sure the correct credentials are selected and used for communication.

You can log in to the test Adyen Customer Area, using your personal user credentials for test, to look at completed transactions. These are not the same credentials as used for the application.

You can perform tests by using the provided Adyen test card. It contains five different applications:

Application Payment Method Issuing Country Currency Expiration Date Locale
MC NL Mastercard Belgium EUR 28-02-29 Dutch
MS EN Maestro Belgium EUR 28-02-29 English
MC F Mastercard US USD 28-02-29 French
MC ES Maestro US USD 28-02-29 Spanish
Magstripe (MSR) Mastercard US USD 01-12-25 English

The test card is programmed to select a different Cardholder Verification Method (CVM) based upon the transaction amount and currency:

Application Condition CVM
MC NL >200.00 EUR CVM 1: Enciphered PIN verified online
  >100 EUR CVM 2: Enciphered PIN verification performed by ICC
  0-100 EUR CVM 3: Signature
MS EN >200.00 EUR CVM 1: Enciphered PIN verified online
  >100 EUR CVM 2: Enciphered PIN verification performed by ICC
  0-100 EUR CVM 3: Signature
MC F All CVM 1: Enciphered PIN verification performed by ICC
MC ES All CVM 1: Enciphered PIN verification peformed by ICC
MSR (Magnetic Stripe Reader) All CVM1: Service code 201 - Signature

For a general explanation of CVM lists, click here.

For sale transactions, there are four possible results:

  • Approved
  • Refused
  • Cancelled
  • Error

These results are described below. 

Change the last digits of the transaction amount to simulate different scenarios.

Shoppers and merchants can cancel the transaction using the PED. Merchants can also cancel the transaction using the library. A cancellation will generate the result "CANCELLED".

Refunds will generate an approved response. 

Amount (last three digits) Acquirer Response Transaction Result
Any (except the special cases below) Approved Approved
121 Acquirer Cancelled Refused
122 Fraud Refused
123 Declined Refused
124 Not enough balance Refused
125 Blocked card Refused
126 Expired card Refused
127 Invalid amount Refused
128 Invalid card number Refused
129 Not supported Refused
130 Acquirer error Error
131 Acquirer declined Refused
132 Acquirer declined Refused
133 Referral Refused
134 (use correct PIN only!) Incorrect online PIN Error
135 PIN tries exceeded Refused
136 Issuer unavailable Refused
137

Withdrawal Amount Exceeded

Refused
138

Withdrawal Count Exceeded

Refused
139

Amount partially approved

Approved
140 Invalid issuer authentication data Refused
Any Card removed during app selection Error
Any Cancelled via terminal Cancelled
Any Cancelled through the library by merchant Cancelled

Use cases and process flows

Use cases and process flows for the POS test system are provided below to aid understanding.

Use case: Registration

Registering (boarding) an App

Step# Description/Requirement
1 Enter credentials (merchant account, user name, password).
  The result message about the boarding is sent.

Registering (boarding) a payment device

Step# Description/Requirement
1 Set up communication channel for device (wifi, serial).
2

Set the payment device to be boarded:

  • For wifi connection, enter IP address.
  • For serial, set COM port that is used.
3

When a completely new PED is boarded, the DLL goes through these steps:

3.1. The library queries the PED to identify it and to check its status.

3.2. The library registers the device at the Adyen system.

3.3. The library loads the device configuration from the PSP.

3.4. The library stores the device configuration at the PED.

3.5. The library queries the PED finally to check that it has been registered.

If the first step concludes that the PED is already authorized and authenticated, the remaining steps are not required.

4 The result message about the boarding is sent.

Use case: Sale transaction

Step# Description/Requirement
1 Associate enters amount, currency and merchant reference and starts a transaction.
  The terminal shows amount and currency and asks shopper to insert card.
2

Shopper inserts or swipes the credit/debit card:

  • If the EMV chip cannot be read, the terminal displays a “chip failed” message. After 3 failed attempts the magnetic stripe is offered as a fallback method.

Always swipe a non chip card.

4

After swipe or insert of the card the Customer Verification Method (CVM) method is determined. Common CVM methods are Signature Capture or PIN entry.

4.1

CVM is PIN Entry: 

For EMV transactions if the PIN is valid the flow continues. If the entered PIN is not valid, the terminal prompts the shopper to retry up to three times. The message about the transaction process should be displayed to the merchant as it is displayed to the customer on the terminal. If the PIN entry is unsuccessful the terminal displays a message to the shopper, timeout flow begins if there is no next action.

4.2

CVM is Signature:

The signature can be captured on screen or paper. For capture on screen each terminal has to be set up in Adyen's backoffice and merchant config to be downloaded on the terminal.

  • Capture on screen: The shopper signs on the PED, the signature is displayed at the register for the associate to accept.
  • Capture on paper: The merchant copy of the receipt is printed. So the shopper can sign on the field Signature. The associate can see the signature on paper, and should confirm the signature before the transaction flow continues.

If the signature is unsuccessful, the tender cannot be authorized.

5

Authorization request is sent after cardholder verification is secured. For PIN entry, Authorization request is sent with the PIN, for signature Capture the request is sent before the signature is captured.

  • If Adyen returns an Authorization Approved response, the flow continues.
  • If Adyen does not return Authorization response due to technical issue or decline, the terminal displays the response to the shopper.
6

The receipt is handled when the transaction is completed:

  • Receipt is printed on the integrated printer of the terminal.
  • Receipt handler tender option is set up, and other printer is set up to print the receipt.
    The receipt is sent by email.

Three options are possible: print only, email only or print and email.

7

The result from the transaction is provided. The result can be either Approved, Declined, Cancelled and Error.

Use case: Refund

Step #

Description/Requirement

Prerequisites

There are two types of refund:

  • Restricted: if the PspReference (or TerminalReference, TerminalId) to the transaction is known. The funds are transferred to the same card as the original transaction. Go to step R1.

  • Unrestricted: Funds are transferred to a Card, two options are available: Card present (reads the card on the PED) and card not present (the card details are entered manually). We describe the card present scenario in step U1).

R1

Associate enters Merchant reference for refund.

R2

Query the Merchant database for the original transaction payment information using the Merchant reference to find the Adyen's PspReference

  • Shopper recognition: find the payment with the information of the originally used credit card number.

R3

The original payment information is presented to the Associate. The Associate choose existent transaction to be refunded, confirms the amount: full, partial, or bigger then the original amount within the limit defined by the merchant.

R4

The POS sends RefundRequest to Adyen. The result from the transaction is Refund Requested. The merchant database should be updated with this result. The final result from the refund is known when Adyen receives capture for the refund.

 U1

Unrestricted refund to a specific card can be performed, if the shopper choose to receive the refund to a different card, or if the transaction reference is not known.

 U2

Requires the shopper to insert or swipe the card on the terminal. Cardholder verification is secured as in sale transaction. For details, go to steps 4,5,6 and 7 in Sale transaction.

 N1

The requested refund is performed on the Adyen platform, the result may be REFUND or REFUND_FAILED. Notifications should be used to keep your back-office systems up to date with the status of each payment and modification.

 N2

The merchant's server receives the notifications and sends back message [accepted]. The merchant database should be updated after the transaction is successful.

Use case: Sale transaction - functions

Step #

Description/Requirement

1

Associate enters amount, currency and merchant reference and starts a transaction.

2

The tender option AskGratuity can be used to initiate a question on the PED whether or not the shopper wants to offer a tip, which can be useful in restaurant environments.

If AskGratuity option is enabled, go to Steps G1, G2, G3. If it is not enabled go to Step 3.

G1

The terminal shows amount, currency and asks shopper to enter gratuity amount.

G2

The shopper enters gratuity amount and presses Enter.

G3

Associate can see the updated amount in POS. The updated amount is presented on the PED.

3

The terminal shows amount and currency and asks shopper to insert/swipe card.

4

Shopper inserts or swipes the card.

D1

POS retrieves discount from Merchant database, sends adjusted amount to PED.

D2

PED shows discounted amount.

5

The merchant account may be configured to accept DCC. If AskDCC is set up on the merchant account, go to Steps DCC1, DCC2, DCC 3. It is not enabled go to Step 6.

DCC1

After the card is swiped or inserted, the country of origin is known, and the currency of the shopper is offered. DCC quote is shown on the PED.

DCC2

If the shopper accepts the DCC quote, the transaction continues in the chosen (shoppers) currency.

DCC3

If the shopper declines the DCC quote, the transaction continues in the merchants currency.

6

After swipe or insert of the card the CVM method is determined. For details  check the use case diagram Sale transaction.

Implementations, tender options and considerations

Review the generic options and considerations that apply across the different libraries and stand-alone terminals. 

Generally, transaction options can be configured via the Adyen Customer Area (CA) or as a TenderOption on a per-transaction basis.

For example, AskGratuity, where the shopper is asked to enter a tip, can be set in createTender or as a configuration option for stand-alone terminals.

Handling signatures

Signature handling is required for all POS deployments. The cash register therefore needs to provide support for the process.

Flow options:

There are three options to control this flow:

  1. The signature is placed on the terminal via the touchscreen. 
    • Customer signs on the terminal touchscreen (for terminal models with an available touchscreen, for example VX680, VX820, etc.) The image is then provided to the Cash Register by the Adyen library and sent to the Adyen CA. The Cash Register App in turn should provide this image to in-store staff for verification.
  2. The signature is placed on the Cash Register.
    • Used typically for tablets in combination with a small terminal without a printer and touchscreen. The signature is captured by the Cash Register App and the image should be provided to the Adyen library where it is sent to the Adyen CA.
  3.  The signature is placed on a physical receipt.
    • This is a legacy flow, used if neither the Cash Register nor terminal has a touchscreen. The shopper signs a physical receipt (Merchant copy), printed by either the terminal or the Cash Register. The Cash Register then confirms to the Adyen library that the signature is accepted and the transaction can proceed.  Signatures performed on the PED are available in the Adyen CA and do not need to be stored separately.

Creating a recurring contract

  1. Similar to e-commerce, to create a recurring contract additional parameters need to be send as tender options on the initial transaction. These additional parameters are: 

    Element

    Details

    recurringContract* 

    The type of usage desired in the future for the Card Details to be stored in the recurring contract. Only in combination with shopperEmail and shopperReference.

    Contact Adyen for configuration of your account for recurring usage. 

    shopperEmail 

    The email of the shopper.
    Only in combination with shopperReference, and recurringContract

    shopperReference 

    A unique reference to the shopper as generated by the merchant. Only in combination with shopperEmail and recurringContract

  2. A recurring contract is created after a successful transaction which can also be a zero value transaction. 

    For recurring details to be returned a special configuration is needed on the Adyen platform, contact support for details.

Zero value auth has limited BIN support. If the issuer does not support a zero value auth, the shopper's card can be charged with the lowest amount possible and refunded later.

Shopper Recognition

  1. Initiate a transaction with the GetAdditionalData parameter and without recurring parameters.
  2. If a recurring contract has been created before, the Adyen CA retrieves the shopperReference and shopperEmail from the recurring contracts based on the card number. The card alias is always returned.

  3. The Merchant POS system is provided with these shopper details and can check within the merchant database for previous shopper purchases and decide on a discount for the ongoing transaction. The adjusted amount is then provided and the transaction can be completed.  Merchant database can be checked on both shopper reference and card alias.

Partial Authorization

Partial authorization allows the shopper to pay for their goods with another card, if the balance of their primary card is less than the value of the goods. The tender option  AllowPartialAuthorisation is used to enable partial authorizations on a tender.

  1. Initiate a transaction with CreateTender including AllowPartialAuthorisation as a tender option.
  2. A request for payment is returned from the Adyen platform which includes the allowPartialAuthorisation parameter as part of the AdditionalData object.
  3. Confirm the authorisation with the ConfirmAdditionalData response, including the following parameters:

Element
Details
authorisedAmountValue The value available to partially authorise from the card.
authorisedAmountCurrency The currency of the balance being authorised from the card.
requestedAmount The total value of the tendered goods.

Tender State Reference Sheet

TenderState states

State

Description

UNDEFINED

The tender is in an undefined state.

ADDITIONAL_DATA_AVAILABLE

Additional data (like card alias (token), card type and issuer country code) are available

PRINT_RECEIPT

The terminal is printing the receipt

CHECK_SIGNATURE

The terminal is waiting for the cashier to check the signature.

ASK_DCC

The terminal is checking if the customer requires dynamic currency conversion

INITIAL

A transaction was initiated.

TENDER_CREATED

The tender was successfully created

CARD_INSERTED

A card was inserted

CARD_SWIPED

A card was swiped

WAIT_FOR_APP_SELECTION

The terminal is waiting to select...

APPLICATION_SELECTED

The customer has selected their preferred payment application.

WAIT_FOR_AMOUNT_ADJUSTMENT

Waiting for an amount to be adjusted based on the gratuity

ASK_GRATUITY

The terminal is waiting for a possible gratuity

GRATUITY_ENTERED

The gratuity amount was entered

DCC_ACCEPTED

The customer requested Dynamic Currency Conversion

DCC_REJECTED

The customer rejected Dynamic Currency Conversion

PROCESSING_TENDER

The payment is being processed. The terminal displays a progress bar.

WAIT_FOR_PIN

A PIN is requested at the terminal.

PIN_DIGIT_ENTERED A digit of the PIN was entered
PIN_ENTERED The whole PIN was entered
PROVIDE_CARD_DETAILS The terminal is waiting for (manually entered?) card details
CARD_DETAILS_PROVIDED The card details have been entered (either on the terminal or the cash register?)
RECEIPT_PRINTED A receipt was printed
REFERRAL_CHECKED The referral code was checked
SIGNATURE_CHECKED The cashier has checked and confirmed the signature
ACKNOWLEDGED
The transaction is acknowledged, but not approved, declined, cancelled or failed in error.
REFERRAL The acquirer sends a referral status
ASK_SIGNATURE The PED has requested a signature from the shopper.
APPROVED The transaction has been approved
DECLINED This response maps all those response codes that cannot be reliably mapped.
This makes it easier to tell generic declines (for example, MasterCard "05: Do not honor" response) from more specific ones.
CANCELLED The transaction was cancelled.
ERROR The transaction did not go through as an error occurred.
BALANCE_QUERY_STARTED The terminal is requesting the balance on a card
BALANCE_QUERY_COMPLETED The request for card balance has completed.
LOAD_STARTED A load of a value on the card has started.
BALANCE_QUERY_ACQUIRED Confirms the acquired balance and allows the user to take next steps,
LOAD_COMPLETED A load of a value on the card has completed.
UNKNOWN The tender state is unknown, and it is not possible to determine it.  
Contact the  Adyen Support Team to request assistance.

Final States

State

Description

DECLINED

The transaction was declined.
APPROVED The transaction was approved
CANCELLED The transaction was cancelled.
ERROR The transaction did not go through as an error occurred.
UNKNOWN The tender state is unknown, and it is not possible to determine it.  
Contact the  Adyen Support Team to request assistance.