API _Version _Revision | Description |
---|---|
_AgnosMW _version 3.5.20 _revision 23791 |
Payment Middleware | ||
---|---|---|
See paymentmw.h | ||
| #include "datamngr.h" #include "dataxchng.h" //---- Agnos Framework Headers ---- #include "agnos.h" //---- Global Headers ---- #include "gpi_agnos_framework_globals.h" | -- |
| #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 | -- |
| 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; | -- |
| typedef enum { atDEFAULT, atSAVINGS, atCHECKING, atCREDIT } tAccountType; | -- |
| 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; | -- |
| 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; | -- |
| typedef enum { stCONTACT, stCONTACTLESS, stMAGSTRIPE, stMANUAL, stNUMBER_OF_INTERFACE, } tInterface | -- |
| typedef enum { ipNONE, // i.e. not applicable ipCONTACTCHIP, ipMAGSTRIPE } tAlternateInterfacePreference; | -- |
| typedef enum { rdNONE, // i.e. not applicable rdEMV, rdANY } tOnlineResponseData; | -- |
| typedef enum { cvNONE, // i.e. not applicable cvNO_CVM, cvOBTAIN_SIGNATURE, cvONLINE_PIN, cvCONFIRMATION_CODE_VERIFIED } tCVM; | -- |
| 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; | -- |
| typedef struct { //////////////////////////////////////////////////////////////////// // Information provided by Level3 tAmount *mAmount; // EMV Tag 9F02 = "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]; //////////////////////////////////////////////////////////////////// // Information set by Payment System tBoolean mEMVContact; // by configuration (terminal) tBoolean mEMVContactless; // by configuration (terminal) tBoolean mMagstripe; // by configuration (terminal) tAmount mAmountReferenceCurrency; // EMV Tag 9F3A - not used yet tByte mTransactionReferenceCurrencyCode[2]; // EMV Tag 9F3C - not used yet 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; |
|
| DLLEXPORT char* pmwGetPaymentMiddlewareVersionNumber(void); | Get AgnosMW version. |
| DLLEXPORT tString pmwGetKernelVersion(void); | Get EMV core engine version. |
| DLLEXPORT void pmwInitializePaymentContext(tPaymentContext *ctx); | Reset the payment context. Shall be called before any new transaction. |
| DLLEXPORT void pmwInitializeOutComeParameter(tOutComeParameter *outcome); | Reset the outcome context. Shall be called before any new transaction. |
| 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:
|
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 | ||
| 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 | ||
| typedef struct { uint8_t cnt[4]; uint8_t ctlss[4]; uint8_t techno; uint8_t code; uint8_t start; uint8_t action; } tExitCondition; | -- |
| // ### 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 // ### 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 |