Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Table of Contents
typeflat

...

API _Version _Revision

Description

_AgnosMW _version 3.5.20 _revision 23791

Image RemovedImage Added

Payment Middleware

See paymentmw.h

#include

Code Block
languagec
#include "datamngr.h"
#include "dataxchng.h"
//---- Agnos Framework Headers ----
#include "agnos.h"
//---- Global Headers ----
#include "gpi_agnos_framework_globals.h"

--

#define

Code Block
languagec
#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
languagec
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
languagec
typedef enum {
	atDEFAULT,
	atSAVINGS,
	atCHECKING,
	atCREDIT
} tAccountType;

--

tStartingPoint

Code Block
languagec
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
languagec
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
languagec
typedef enum {
	stCONTACT,
	stCONTACTLESS,
	stMAGSTRIPE,
	stMANUAL,
	stNUMBER_OF_INTERFACE,
} tInterface

--

tAlternateInterfacePreference

Code Block
languagec
typedef enum {
	ipNONE,			// i.e. not applicable
	ipCONTACTCHIP,
	ipMAGSTRIPE
} tAlternateInterfacePreference;

--

tOnlineResponseData

Code Block
languagec
typedef enum {
	rdNONE,			// i.e. not applicable
	rdEMV,
	rdANY
} tOnlineResponseData;

--

tCVM

Code Block
languagec
typedef enum {
	cvNONE,	// i.e. not applicable
	cvNO_CVM,
	cvOBTAIN_SIGNATURE,
	cvONLINE_PIN,
	cvCONFIRMATION_CODE_VERIFIED
} tCVM;

--

tOutComeParameter

Code Block
languagec
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;
tExitCondition

--

tPaymentContext

Code Block
languagec
typedef struct {
	uint8_t cnt[4];
	uint8_t ctlss[4];
	uint8_t techno;
	uint8_t code;
	uint8_t start;
	uint8_t action;
} tExitCondition;

tPaymentContext

Code Block
languagec
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    tByte               mRIDmRID[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    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;
  • 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 length invalid 5F57 is then 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):

    • mRID:

    • mADF:

    • mADFOrder:

  • Information set by EMV Library:

    • mSession

    • mCID

  • 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

pmwGetPaymentMiddlewareVersionNumber

Code Block
languagec
typedefDLLEXPORT struct {
	tDataExchangeType 	mDEType;		// In
	tByte 				mAPDUStatus;	// In
	tPaymentContext		*mPayment;		// In
	tDecision			mDecision;		// Out
	void*				mProprietary;	// In/Out
} tLevel3DataExchange;

pmwGetPaymentMiddlewareVersionNumber

Code Block
languagec
DLLEXPORT char* pmwGetPaymentMiddlewareVersionNumber(void);

Get AgnosMW version.

pmwGetKernelVersion

Code Block
languagec
DLLEXPORT tString pmwGetKernelVersion(void);

Get EMV core engine version.

pmwInitializePaymentContext

Code Block
languagec
DLLEXPORT void pmwInitializePaymentContext(tPaymentContext *ctx);

Reset the payment context. Shall be called before any new transaction.

pmwInitializeOutComeParameter

Code Block
languagec
DLLEXPORT void pmwInitializeOutComeParameter(tOutComeParameter *outcome);

Reset the outcome context. Shall be called before any new transaction.

pmwProceedToUniversalFinalSelection

Code Block
languagec
DLLEXPORT tPaymentError pmwProceedToUniversalFinalSelection(
	tADFList 			*mutualList,
	tByte				*AIDIndex,	// Index in the AID list supported by the terminal (see processing context)
    tByte				*MLIndex,	char* pmwGetPaymentMiddlewareVersionNumber(void);

Get AgnosMW version.

pmwGetKernelVersion

Code Block
languagec
DLLEXPORT tString pmwGetKernelVersion(void);

Get EMV core engine version.

pmwInitializePaymentContext

Code Block
languagec
DLLEXPORT void pmwInitializePaymentContext(tPaymentContext *ctx);

Reset the payment context. Shall be called before any new transaction.

pmwInitializeOutComeParameter

Code Block
languagec
DLLEXPORT void pmwInitializeOutComeParameter(tOutComeParameter *outcome);

Reset the outcome context. Shall be called before any new transaction.

pmwProceedToUniversalFinalSelection

Code Block
languagec
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:

  • TERMINAL

  • PROCESSING

  • ENTRY_POINT (contactless only)

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

  • TERMINAL_CTX

  • CONTACT_PROCESSING_CTX

  • CONTACTLESS_PROCESSING_CTX

  • ENTRY_POINT

dtmGetData

  • TERMINAL_CTX

  • CONTACT_PROCESSING_CTX

  • CONTACTLESS_PROCESSING_CTX

  • ENTRY_POINT

Data Exchange

See agnosmw.h. dataxchng.h

tLevel3DataExchange

Code Block
languagec
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
languagec
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
languagec
// ### 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
languagec
// ### 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