...
ola_ contactless.h
| Code Block | ||
|---|---|---|
| ||
// NAME....... ola_contactless.h
// PURPOSE.... Level 2 Abstraction Layer for contactless
// to be used by the external world (Level 3 application)
// PROJECT.... Arkos Payment Solution
// REFERENCES. --
//
//
// Copyright 2005-2019 - 9164-4187 QUEBEC INC (AMADIS), All Rights Reserved
//
#ifndef OLA_CONTACTLESS_H
#define OLA_CONTACTLESS_H
//---------------------------------------------------------
// Includes
//---------------------------------------------------------
#include "ola_emv.h"
#include <stdint.h>
//---------------------------------------------------------
// Definitions
//---------------------------------------------------------
#define OLA_KERNEL_ID_MASTERCARD 2
#define OLA_KERNEL_ID_VISA 3
#define OLA_KERNEL_ID_AMEX 4
#define OLA_KERNEL_ID_JCB 5
#define OLA_KERNEL_ID_DISCOVER 6
#define OLA_KERNEL_ID_CUP 7
#define OLA_MSD_ID_APPROVED 0x03
#define OLA_MSD_ID_NOT_AUTHORISED 0x07
#define OLA_MSD_ID_PLEASE_INSERT_OR_SWIPE_CARD 0x18
#define OLA_MSD_ID_AUTHORISING_PLEASE_WAIT 0x1B
#define OLA_MSD_ID_INSERT_SWIPE_OR_TRY_ANOTHER_CARD 0x1C
#define OLA_MSD_ID_SEE_PHONE_FOR_INSTRUCTIONS 0x20
typedef enum
{
ctsNone,
ctsPreprocess,
ctsBuildCandidate,
ctsFinalSelect,
ctsActivate
} tOlaContactlessTransactionStep;
// Outcome definition based on EMV Co Books A and B
typedef enum
{
outcNone,
outcSelectNext,
outcTryAgain,
outcApproved,
outcDeclined,
outcOnlineRequest,
outcTryAnotherInterface,
outcEndApplication
} tOlaOutcome;
typedef enum
{
spNoStart,
spStartA,
spStartB,
spStartC,
spStartD,
} tOlaStartPoint;
typedef enum
{
ordNone,
ordEmv,
ordAny
} tOlaOnlineResponseData;
typedef enum
{
aipNone,
aipContactChip,
aipMagneticStripe
} tOlaAlternateInterfacePreference;
typedef enum
{
cvmcNone,
cvmcNoCvm,
cvmcSignature,
cvmcOnlinePin,
cvmcConfirmationCodeVerified
} tOlaCVMethodContactless;
typedef enum
{
staNone,
staNotReady,
staIdle,
staReadyToRead,
staProcessing,
staCardReadSuccessfully,
staProcessingError
} tOlaStatus;
typedef enum
{
vqNone,
vqAmount,
vqBalance
} tOlaValueQualifier;
typedef struct
{
tOlaOutcome outCome;
tOlaStartPoint startingPoint;
tOlaOnlineResponseData onlineResponseData;
tOlaCVMethodContactless cvm;
int UIReqOnOutcomePresent;
int UIReqOnRestartPresent;
int receipt;
int dataRecordPresent;
int discretionaryDataPresent;
tOlaAlternateInterfacePreference alternateInterfacePreference;
uint32_t fieldOffReq;
uint32_t removalTimeout;
} tOlaOutcomeParameter;
// User Interface Request definition based on EMV Co Books A and B
typedef struct
{
uint8_t messageIdentifier;
tOlaStatus status;
uint32_t holdTime;
uint8_t languagePreference[8]; // List of languages, ISO 639-1 representation
tOlaValueQualifier valueQualifier;
uint8_t value[6]; // BCD
uint8_t currencyCode[2]; // Numeric ISO 4217
} tOlaUIRequest;
//---------------------------------------------------------
// Primitives
//---------------------------------------------------------
// Erase all AID and DRL supported from configuration
void ola_contactless_flush_aid_supported(void);
// Add one AID supported to configuration.
// Must be called before ola_contactless_preprocess()
// Input parameters:
// aid : AID, max 16 bytes
// aidLength : length of the AID
// kernelId : on one byte, identifies the kernel to be used when selected later (useful for Carte Bancaire)
// tlv :
// tlvLength :
// Return
// OLA_CONTACTLESS_OK
// OLA_CONTACTLESS_MAX_REACHED
// OLA_CONTACTLESS_PARAMETER_ERROR
tOLAError ola_contactless_add_aid_supported(
const uint8_t *aid,
uint8_t aidLength,
int partial,
uint8_t kernelId,
const uint8_t *tlv,
uint16_t tlvLength
);
// Add one DRL (Dynamic Reader Limit) supported to configuration.
// Input parameters:
// programId : Program ID, max 16 bytes (one byte for XPressPay)
// programIdLength : length of the Program ID
// transactionLimit : contactless transaction limit, 6 bytes BCD
// (NULL pointer if there is no value)
// floorLimit : contactless floor limit, 6 bytes BCD
// (NULL pointer if there is no value)
// CVMLimit : contactless CVM limit, 6 bytes BCD
// (NULL pointer if there is no value)
// statusCheck: for PayWave only: allow status check; 0 is false, else is true
// isZeroAllowed : for PayWave only: allow zero amount; 0 is false, else is true
// kernelId : on one byte, identifies the kernel using the DRL; it can be 3 (PayWave) or 4 (XPressPay)
// Return
// OLA_CONTACTLESS_OK
// OLA_CONTACTLESS_MAX_REACHED
// OLA_CONTACTLESS_PARAMETER_ERROR
uint16_t ola_contactless_add_drl_supported(
const uint8_t *programId,
uint8_t programIdLength,
const uint8_t *transactionLimit,
const uint8_t *floorLimit,
const uint8_t *CVMLimit,
int statusCheck,
int isZeroAllowed,
uint8_t kernelId
);
// Commit added AID and DRL supported in configuration
void ola_contactless_commit_supported_aids(void);
// Build the candidate list of common AID between the card and the configuration,
// in order of priority.
// Output parameter:
// nb_candidates : tell how many candidates are in the list
// Return
// OLA_CONTACTLESS_OK
// OLA_CONTACTLESS_NO_CANDIDATE
// OLA_CONTACTLESS_CARD_ERROR
uint16_t ola_contactless_build_candidate_list(
uint8_t *nb_candidates
);
// Get a tag from a candidate in the candidate list
// Must be called after ola_contactless_build_candidate_list()
// Input parameter:
// candidate : an occurrence in candidate list, value must be from 1 to nb_candidates
// tag
// Output parameter:
// value : buffer to copy the value of the tag
// length : the length of the value
// Return
// OLA_CONTACTLESS_OK
// OLA_CONTACTLESS_MISSING_DATA: the tag is not present
// OLA_CONTACTLESS_PARAMETER_ERROR
uint16_t ola_contactless_get_tag_from_candidate(
uint8_t candidate,
uint32_t tag,
uint8_t *value,
uint16_t *length
);
// Send the final select to the card for a candidate in the candidate list
// Input parameter:
// candidate : an occurrence in candidate list, value must be from 1 to nb_candidates
// Output parameter:
// kernelId : the kernel Id that will be activated for this candidate
// Return
// OLA_CONTACTLESS_OK
// OLA_CONTACTLESS_PARAMETER_ERROR
// OLA_CONTACTLESS_BLOCKED
// OLA_CONTACTLESS_CARD_ERROR
tOLAError ola_contactless_final_select_candidate(
uint8_t candidate,
uint8_t *kernelId
);
// Get the preference language for the card holder. It's the first match between the
// card preferred languages list and terminal languages supported, or, when this match
// does not occur, the first occurrence of terminal languages supported
// Output parameter:
// language : preference language in ISO 639-1 format (two ASCII character)
// Return
// OLA_CONTACTLESS_OK
tOLAError ola_contactless_get_card_preferred_language(
char *language
);
// Perform preprocessing
// Return
// OLA_EMV_OK : at least on scheme can be used with contactless technology
// OLA_CONTACTLESS_USE_CONTACT
// OLA_EMV_PARAMETER_ERROR
tOLAError ola_contactless_preprocess(void);
// Perform the Contactless transaction after the AID is selected and configured
// (First step is building the PDOL and sending the GPO command)
// Output parameter:
// contactlessEntryMode : EMV_CL_MODE or MAG_CL_MODE
// Return
// OLA_CONTACTLESS_GO_ONLINE
// OLA_CONTACTLESS_OFFLINE_APPROVAL
// OLA_CONTACTLESS_OFFLINE_DENIAL
// OLA_CONTACTLESS_SEE_PHONE
// OLA_CONTACTLESS_USE_CONTACT
// OLA_CONTACTLESS_USE_OTHER_CARD
// OLA_CONTACTLESS_CONDITIONS_NOT_SATISFIED
// OLA_CONTACTLESS_NO_RESPONSE
// OLA_CONTACTLESS_CARD_ERROR
tOLAError ola_contactless_do_transaction(
uint8_t *contactlessEntryMode
);
// Release all internal states
void ola_contactless_clean(void);
// Get the outcome from the Contactless transaction context
// Values based on EMV Co Book A Annex B (standards outcomes)
// or as specified elsewhere in Book B (for entry point outcome)
// or in Books C (specifics for different schemes)
// Output parameter:
// outcome : outcome parameter structure
// Return
// OLA_CONTACTLESS_OK
// OLA_CONTACTLESS_ERROR
tOLAError ola_contactless_get_outcome(
tOlaOutcomeParameter *outcome
);
// Get the UI request on outcome from the Contactless transaction context
// Output parameter:
// uiRequest : UI request parameter structure
// Return
// OLA_CONTACTLESS_OK
// OLA_CONTACTLESS_ERROR
tOLAError ola_contactless_get_UI_request_upon_outcome(
tOlaUIRequest *uiRequest
);
// Get the UI request on restart from the contactless transaction context
// Output parameter:
// uiRequest : UI request parameter structure
// Return
// OLA_CONTACTLESS_OK
// OLA_CONTACTLESS_ERROR
tOLAError ola_contactless_get_UI_request_restart(
tOlaUIRequest *uiRequest
);
#endif /* OLA_CONTACTLESS_H */
|
...