Amadis

Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 57 Next »

API _Version _Revision

Description

_AgnosMW _version 3.5.20 _revision 23791

Payment Middleware

See paymentmw.h

#include

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

#define

#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

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

typedef enum {
	atDEFAULT,
	atSAVINGS,
	atCHECKING,
	atCREDIT
} tAccountType;

tStartingPoint

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

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

typedef enum {
	stCONTACT,
	stCONTACTLESS,
	stMAGSTRIPE,
	stMANUAL,
	stNUMBER_OF_INTERFACE,
} tInterface

tAlternateInterfacePreference

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

tOnlineResponseData

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

tCVM

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

tOutComeParameter

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

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

tPaymentContext

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;
  • 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):

    • 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

typedef struct {
	tDataExchangeType 	mDEType;		// In
	tByte 				mAPDUStatus;	// In
	tPaymentContext		*mPayment;		// In
	tDecision			mDecision;		// Out
	void*				mProprietary;	// In/Out
} tLevel3DataExchange;

pmwGetPaymentMiddlewareVersionNumber

DLLEXPORT char* pmwGetPaymentMiddlewareVersionNumber(void);

Get AgnosMW version.

pmwGetKernelVersion

DLLEXPORT tString pmwGetKernelVersion(void);

Get EMV core engine version.

pmwInitializePaymentContext

DLLEXPORT void pmwInitializePaymentContext(tPaymentContext *ctx);

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

pmwInitializeOutComeParameter

DLLEXPORT void pmwInitializeOutComeParameter(tOutComeParameter *outcome);

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

pmwProceedToUniversalFinalSelection

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

  • No labels