...
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 */ |
...