AgnosMW provides a set of primitives to manage the transient data model. It also defines the C structures used to manage transaction flows:
tPaymentContext
tOutComeParameter
C Structures
tPaymentContext (paymentMW.h)
Information provided by Level3: these data members must be filled up by the payment application integrating Agnos API. These data members are provided by a TRD trigggered by a sales system or a test environment (ACE)
Information set by Payment System:
mEMVContact/mEMVContactless/mMagstripe: these data members are initialized from TERMINAL file by AgnosEP at enpInitialize calling time. They are mandatory only when integrating a CL acceptance system supporting contact and/or magstripe
Tags 9F3A/9F3C/9F3D (meant for contact only): not used yet
Tag 5F57, account type (meant for contact and contacless): this data is used to set AgnosDB with from a TRD trigggered by a sales system or a test environment (ACE). If missing or lenth invalid 5F57 is systematically set to empty
Tag 9F39, POS entry mode (meant for contact and contactless):
Magstripe: set by payment application to MAG_MODE = 0x90
Contact: set by payment application to MAG_MODE = 0x05
Fallback from Contact to Magstripe: set by payment application to FALLBACK_MODE=0x80
Contactless: set by contactless card processing to EMV_CL_MODE=0x07 or MAG_CL_MODE=0x91
Tag 9F41, Transaction Counter (meant for contact only): this data member is used by emvco.c to demonstrate that each subsequent transsction can be indexed by a counter (for the purpose of L2 TA)
mARC (meant for contact and contactless): this data member is set by payment application just before completion from issuer response. It is used to set mCID to TC or AAC
mUnableToGoOnline (meant for contact only): this data member is set by payment application just before completion to indicate how to manage risk at GenAC2 time
Information set by Payment Application (from Agnos primitives):
Information set by EMV Library:
Information calculated by Level3: these data members are set automatically on at pmwSetEMVResult calling time. It shall be called at the end of any EMV contact transactions by payment application. It is systematically called by AgnosEP at the end of any contactless transaction
Level3<->Level2 communication: this data member is only meant for contactless transaction when supporting data exchange. Even if it is mandatory for few payment schemes during L2 TA, it is not mandatory to support it in production
...
breakoutMode | wide |
---|
language | c |
---|
...
API _Version _Revision | Description |
---|
_AgnosMW _version 3.5.20 _revision 23791 | Image Added |
Payment Middleware |
---|
See paymentmw.h |
#include
| Code Block |
---|
| #include "datamngr.h"
#include "dataxchng.h"
//---- Agnos Framework Headers ----
#include "agnos.h"
//---- Global Headers ----
#include "gpi_agnos_framework_globals.h" |
| -- |
#define
| Code Block |
---|
| #define CHIP_MODE 0x05
#define MAG_MODE 0x90
#define FALLBACK_MODE 0x80
#define MANUAL_MODE 0x01
#define EMV_CL_MODE 0x07
#define MAG_CL_MODE 0x91
#define PSE_DDF_NAME "1PAY.SYS.DDF01"
#define PSE_DDF_LENGTH 14
#define PPSE_DDF_NAME "2PAY.SYS.DDF01"
#define PPSE_DDF_LENGTH 14
#define ACCOUNT_TYPE_RANGE 10 |
| -- |
tTransactionType
| Code Block |
---|
| typedef enum {
ttPURCHASE,
ttCASH,
ttWITH_CASHBACK,
ttREFUND,
ttMANUAL_CASH,
ttQUASI_CASH,
ttDEPOSIT,
ttINQUIRY,
ttPAYMENT,
ttTRANSFER,
ttADMINISTRATIVE,
ttHOUSE_KEEPING,
ttRETRIEVAL,
ttUPDATE,
ttAUTHENTICATION,
ttCASH_DISBURSEMENT,
ttPRE_AUTHORIZATION,
ttMONEY_ADD,
ttVOID,
ttCLEAN_ALL,
ttRESET,
ttUNDEFINED
} tTransactionType; |
| -- |
tAccountType
| Code Block |
---|
| typedef enum {
atDEFAULT,
atSAVINGS,
atCHECKING,
atCREDIT
} tAccountType; |
| -- |
tStartingPoint
| Code Block |
---|
| typedef enum {
spNO_START,
spSTART_A, // as per EMVCo contactless specifications
spSTART_B, // as per EMVCo contactless specifications
spSTART_C, // as per EMVCo contactless specifications - No used by external calling applications (internal start)
spSTART_D, // as per EMVCo contactless specifications
// Amadis to generalize EMVCo's entrypoint architecture pattern
spSTART_K, // Agnos call for EMV contact transactions -> DEPRECATED
spSTART_M, // Agnos call for MAG stripe transactions -> DEPRECATED
spSTART_L // Agnos call for ManualKey entry transactions -> DEPRECATED
} tStartingPoint; |
| -- |
tOutCome
| Code Block |
---|
| typedef enum {
ocNONE,
ocTRY_ANOTHER_INTERFACE,
ocOFFLINE_APPROVED,
ocOFFLINE_DECLINED,
ocOFFLINE_FAILED,
ocOFFLINE_NOT_ACCEPTED,
ocAPPROVED,
ocDECLINED,
ocFAILED,
ocNOT_ACCEPTED,
ocTRANSACTION_CANCELLED,
ocSELECT_NEXT_NOT_ACCEPTED,
ocSELECT_NEXT_RETRY,
ocTRY_AGAIN,
ocONLINE_REQUEST,
ocEND_APPLICATION,
ocNOT_EMV_CARD_POOLED
} tOutCome; |
| -- |
tInterface
| Code Block |
---|
| typedef enum {
stCONTACT,
stCONTACTLESS,
stMAGSTRIPE,
stMANUAL,
stNUMBER_OF_INTERFACE,
} tInterface |
| -- |
tAlternateInterfacePreference
| Code Block |
---|
| typedef enum {
ipNONE, // i.e. not applicable
ipCONTACTCHIP,
ipMAGSTRIPE
} tAlternateInterfacePreference; |
| -- |
tOnlineResponseData
| Code Block |
---|
| typedef enum {
rdNONE, // i.e. not applicable
rdEMV,
rdANY
} tOnlineResponseData; |
| -- |
tCVM
| Code Block |
---|
| typedef enum {
cvNONE, // i.e. not applicable
cvNO_CVM,
cvOBTAIN_SIGNATURE,
cvONLINE_PIN,
cvCONFIRMATION_CODE_VERIFIED
} tCVM; |
| -- |
tOutComeParameter
| Code Block |
---|
| typedef struct {
tOutCome mOutCome;
tStartingPoint mStartingPoint;
tOnlineResponseData mOnlineResponseData;
tCVM mCVM;
tBoolean mUIReqOnOutcomePresent; // If bTRUE, found in DataExchange
tBoolean mUIReqOnRestartPresent; // If bTRUE, found in DataExchange
tBoolean mReceipt;
tBoolean mDRPresent; // Data record. If present, found in DataExchange
tBoolean mDDPresent; // Discretionary Data. If present, found in DataExchange
tAlternateInterfacePreference mAlternateInterfacePreference;
tWord mFieldOffReq;
tWord mRemovalTimeout;
} tOutComeParameter; |
| -- |
tPaymentContext
| Code Block |
---|
| typedef struct {
////////////////////////////////////////////////////////////////////
// Information |
|
...
...
Level3
tAmount *mAmount; // |
|
...
...
...
...
...
"Amount, Authorized" + "Amount, Other"
tAmount *mCashBack; // EMV Tag 9F03 = "Amount, Other"
tTransactionType mTransactionType; // EMV Tag 9C
tNumericDate mTransactionDate[3]; // EMV Tag 9A
tNumericDate mTransactionTime[3]; // EMV Tag 9F21
tByte mMerchantCustomData[20]; // EMV Tag 9F7C
tByte mTransactionCurrencyCode[2]; // EMV Tag 5F2A
tByte mTransactionCurrencyExponent; // EMV Tag 5F36
tByte mTransactionCategoryCode; // EMV Tag 9F53
tByte mMerchantCategoryCode[2]; // EMV Tag 9F15
tByte mMerchantID[15]; // EMV Tag 9F16
tBoolean mForcedOnline; // As per merchant decision
char mWorkingPath[2*MAX_NAME_LENGTH];
//////////////////////////////////////////////////////////////////// |
|
...
...
...
...
...
...
...
...
...
tOutComeParameter (paymentMW.h)
...
breakoutMode | wide |
---|
language | c |
---|
...
...
...
...
...
...
mEMVContact; // by configuration (terminal)
tBoolean |
|
...
...
...
...
...
...
by configuration (terminal)
tBoolean |
|
...
...
...
...
...
...
...
mMagstripe; // by configuration (terminal)
tAmount mAmountReferenceCurrency; // EMV Tag 9F3A - not used yet
tByte mTransactionReferenceCurrencyCode[2]; // |
|
...
...
...
...
...
...
...
Primitives
Names | Comments |
---|
Initialization |
pmwGetPaymentMiddlewareVersionNumber | Get AgnosMW version |
pmwGetKernelVersion | Get EMV core engine version |
pmwInitializePaymentContext | Shall be called before any new transaction |
pmwIntializeOutComeParameter | Shall be called before any new transaction |
dtmInitializeFromFile | Agnos uses three files to persist the data model: Use this primitive ahead any transaction flow in order to initialize the transient data model. |
Data Model |
dtmSetTransactionalContext | Set this context to open an Agnos session (contact only. See emvco.c) |
dtmSetData | |
dtmGetData | |
EMV Selection |
pmwProceedToUniversalFinalSelection | Proceed to standard final selection following EMVCo specs. This mechanism can be overloaded: In contact, don’t call the primitive and implement a specific selection processing (see selectionlogic.c) In contactless, use tApplicationSelectionMethod callback
|
Others | pmwSetEMVResult | Set EMV parameters after a transaction within tPaymentContext based on Agnos status. In contact, this shall be systematically called by payment application. In contactless, AgnosEP encapsulated that call. |
pmwCloseSession | Close Agnos sessionyet
tByte mTransactionReferenceCurrencyExponent; // EMV Tag 9F3D - not used yet
tByte mTerminalRiskManagementData[8]; // EMV Tag 9F1D - not used yet
tAccountType mAccountType; // EMV Tag 5F57 - payment application specific
tByte mPOSEntryMode; // EMV Tag 9F39 - payment application specific
tCounter mTransactionSequenceCounter;
tARC mARC; //Authorization Response Code, eg mapping from Issuer's Response Code (ISO8583:DE39)
tBoolean mUnableToGoOnline;
////////////////////////////////////////////////////////////////////
// Information set by Payment Application (from Agnos primitives)
tByte mRID[RID_LENGTH];
tADF mADF;
tByte mADFOrderNumber; // For a given configuration, AID's order number
tBoolean mAdvice;
tBoolean mBatchData;
tBoolean mReversal;
////////////////////////////////////////////////////////////////////
// Information set by EMV Library
tSessionId mSession;
tByte mCID; // Information used by Level3 to detect transaction's outcome requested by ICC
// CID Bit map (see also EMV4.2 book III section 6.5.5.4)
// b8 b7 b6 b5 b4 b3 b2 b1
// AAC 0 0
// TC 0 1
// ARQC 1 0
// RFU 1 1
// Payment System-specific cryptogram x x
// No advice required 0
// Advice required 1
// Reason/advice code x x x
// No information given 0 0 0
// Service not allowed 0 0 1
// PIN try limit exceeded 0 1 0
// Issuer authentication failed 0 1 1
// Other values RFU 1 x x
//
// Important: terminal shall inspect CID to detect whether transaction requires an advice (when supported by terminal)
// Pls, refer to payment system rules
//
////////////////////////////////////////////////////////////////////
// Information calculated by Level3 once transaction is completed (from paymentMW primitives)
tByte mFinal9F02[6];
tByte mCVMResult[3];
tByte mTVR[5];
tByte mTSI[2];
tByte mAC[8];
tByte mUN[4];
tByte mAID[MAX_AID_LENGTH];
tByte mAIDLen;
tByte mPANSHA[20];
tByte mCardholderNameLen;
tByte mCardholderName[26];
tByte mAgnosTVR[AGNOS_TVR_SIZE];
#ifdef _AGNOSISR_
tBoolean mIsScriptExecuted;
tByte mIssuerScriptResultLen;
tByte mIssuerScriptResult[2*MAX_SCRIPT*sizeof(tScriptResult)];
#endif
////////////////////////////////////////////////////////////////////
// Level3 <-> Level2 communication
tDataExchange mDataExchange;
tExitCondition mExitCondition;
} tPaymentContext; |
| |
pmwGetPaymentMiddlewareVersionNumber
| Code Block |
---|
| DLLEXPORT char* pmwGetPaymentMiddlewareVersionNumber(void); |
| Get AgnosMW version. |
pmwGetKernelVersion
| Code Block |
---|
| DLLEXPORT tString pmwGetKernelVersion(void); |
| Get EMV core engine version. |
pmwInitializePaymentContext
| Code Block |
---|
| DLLEXPORT void pmwInitializePaymentContext(tPaymentContext *ctx); |
| Reset the payment context. Shall be called before any new transaction. |
pmwInitializeOutComeParameter
| Code Block |
---|
| DLLEXPORT void pmwInitializeOutComeParameter(tOutComeParameter *outcome); |
| Reset the outcome context. Shall be called before any new transaction. |
pmwProceedToUniversalFinalSelection
| Code Block |
---|
| DLLEXPORT tPaymentError pmwProceedToUniversalFinalSelection(
tADFList *mutualList,
tByte *AIDIndex, // Index in the AID list supported by the terminal (see processing context)
tByte *MLIndex, // Index in the mutual list
const tTerminalContext *terminal,
tBoolean CLMode); |
| Proceed to standard final selection following EMVCo specs. This mechanism can be overloaded: In contact, don’t call the primitive and implement a specific selection processing (see selectionlogic.c) In contactless, use tApplicationSelectionMethod callback
|
pmwSetEMVResult | | Set EMV parameters after a transaction within tPaymentContext based on Agnos status. In contact, this shall be systematically called by payment application. In contactless, AgnosEP encapsulated that call. |
pmwCloseSession | | Close Agnos session |
Data Manager |
---|
See datamngr.h |
dtmInitializeFromFile | | Agnos uses three files to persist its data model: Use this primitive ahead of any transaction flow in order to initialize the transient data model. |
dtmSetTransactionalContext | | Set this context to open an Agnos session (contact only. See emvco.c) |
dtmSetData | | |
dtmGetData | | |
Data Exchange |
---|
See agnosmw.h. dataxchng.h |
tLevel3DataExchange
| Code Block |
---|
| typedef struct {
tDataExchangeType mDEType; // In
tByte mAPDUStatus; // In
tPaymentContext *mPayment; // In
tDecision mDecision; // Out
void* mProprietary; // In/Out
} tLevel3DataExchange; |
| -- |
| | |
| | |
| | |
Exit Condition |
---|
See agnosmw.h. exitcondition.h |
tExitCondition
| Code Block |
---|
| typedef struct
{
uint8_t cnt[4];
uint8_t ctlss[4];
uint8_t techno;
uint8_t code;
uint8_t start;
uint8_t action;
} tExitCondition; |
| -- |
#define
| Code Block |
---|
| // ### CONTACT EVENTS ###
// --- Detection Events ---
#define EC_CNT_EVENT_CARD_DETECTED 0x11
// --- Selection Events ---
#define EC_CNT_EVENT_GET_PSE_FCI 0x12
#define EC_CNT_EVENT_GET_CANDIDATE_LIST 0x13
#define EC_CNT_EVENT_PROCESSING 0x14
#define EC_CNT_EVENT_GET_FINAL_SELECT_FCI 0x15
// --- Processing Event ---
#define EC_CNT_EVENT_GET_GPO 0x21
#define EC_CNT_EVENT_APP_DATA_AVAILABLE 0x23
#define EC_CNT_EVENT_RESTRICTION_PERFORMED 0x25
#define EC_CNT_EVENT_ODA_PERFORMED 0x26
#define EC_CNT_EVENT_CVM_PERFORMED 0x28
#define EC_CNT_EVENT_TRM_PERFORMED 0x31
#define EC_CNT_EVENT_TAA_PERFORMED 0x33
#define EC_CNT_EVENT_CAA_PERFORMED 0x35
#define EC_CNT_EVENT_GET_FIRST_GEN_AC 0x36
#define EC_CNT_EVENT_GET_PIN 0x38
// --- Completion Events ---
#define EC_CNT_EVENT_ISSUER_SCRIPT_1_RESULTS 0x42
#define EC_CNT_EVENT_GET_SECOND_GEN_AC 0x43
#define EC_CNT_EVENT_ISSUER_SCRIPT_2_RESULTS 0x44 |
Code Block |
---|
| // ### CONTACTLESS EVENTS ###
// --- START-A EVENTS ---
#define EC_CTLSS_EVENT_GET_PRE_PROCESSING_RESULT 0x16
// --- START-B EVENTS ---
// Ready for Card Detection (PRESENT CARD) (Byte 2 bit 2)
#define EC_CTLSS_EVENT_STATUS_READY_TO_READ 0x22
// Contactless Collision Detected (Byte 2 bit 4)
#define EC_CTLSS_EVENT_COLLISION_DETECTED 0x24
// Contactless Card Detected (Byte 2 bit 7)
#define EC_CTLSS_EVENT_CARD_DETECTED 0x27
// --- START-C EVENTS ---
// Get PPSE FCI (Byte 3 bit 2)
#define EC_CTLSS_EVENT_GET_PPSE_FCI 0x32
// Get Candidate List (Byte 3 bit 4)
#define EC_CTLSS_EVENT_GET_CANDIDATE_LIST 0x34
// Get Final Select FCI (Byte 3 bit 7)
#define EC_CTLSS_EVENT_GET_FINAL_SELECT_FCI 0x37
// --- START-D EVENTS ---
// Kernel Activation (PROCESSING) (Byte 4 bit 1) (i.e. Exit after GPO)
#define EC_CTLSS_EVENT_STATUS_PROCESSING 0x41
// Kernel finished reading ICC's Application Data (Byte 4 bit 4) (i.e. Exit before GenAC)
#define EC_CTLSS_EVENT_APP_DATA_AVAILABLE 0x44
// Kernel finished normal ICC's Exchanges (Byte 4 bit 5) (i.e. Exit after GenAC)
#define EC_CTLSS_EVENT_STATUS_CARD_READ_SUCCESSFULLY 0x45
// See Phone required (Byte 4 bit 6)
#define EC_CTLSS_EVENT_SEE_PHONE 0x46
// Kernel completed APDU Exchanges with ICC including DATA STORAGE (CLEAR DISPLAY) (Byte 4 bit 7)
#define EC_CTLSS_EVENT_REMOVE_CARD 0x47 |
| |