C Structures
tPaymentContext (paymentMW.h)
...
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
|
|
...
...
...
...
...
...
"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 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];
//////////////////////////////////////////////////////////////////// |
|
...
...
...
...
...
...
...
...
...
...
...
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; |
| |
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 {
|
|
...
tDataExchange (dataechng.h)
tLevel3DataExchange
Callbacks
typedef void (*emvcallback)(void* data)
Primitives
Names | Comments |
---|
pmwGetPaymentMiddlewareVersionNumber | pmwGetKernelVersion | pmwInitializePaymentContext | Shall be called before any new transaction |
pmwIntializeOutComeParameter | Shall be called before any new transaction |
pmwProceedToUniversalFinalSelection | dtmInitializeFromFile | dtmSelectCTKernel | dtmSetData | dtmGetData | dtmSetTransactionalContext | pmwCloseSession 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 |
| |