Agnos API - version 3.5.20.23770

[ 1 _Agnos _version 3.5.20 _revision 23770 ] [ 2 EMV Engine ] [ 2.1 #include ] [ 2.2 tTransactionalContext ] [ 2.3 agnGetVersionNumber ] [ 2.4 agnOpenSession ] [ 2.5 agnInitiateEMVTransaction ] [ 2.6 agnCompleteEMVTransaction ] [ 2.7 agnCloseSession ] [ 3 Application Selection Routines ] [ 3.1 tADFList ] [ 4 EMV Tags Database ] [ 5 Code Example ]

API _Version _Revision	Description

API _Version _Revision

Description

_Agnos _version 3.5.20 _revision 23770

Agnos Interface is an abstraction of EMVCo Book I, II, and III. It relies on 3 components:

An EMV tags database to store all tags involved in a card processing
A set of EMV application selection routines
An EMV engine implementing EMV steps and EMV primitives to access internal states and structures

Pre-contions setup

Use tTransactionContext C structure to initialize Agnos → see emvco.c, an example used to implement EMVCo test app required for EMVCo CT L2 TA
Use agnSetEMVTag() calls to initialize Agnos

		gpiMemSet(gEMVCoCtx.mTransactionalContext,0x00,sizeof(tTransactionalContext));

		// Set now default parameters for transactional context and using proprietary tags
		gEMVCoCtx.mTransactionalContext->mForceTRM = bTRUE; // Always bTRUE for L2 TA. If AIP is missing then do TRM depending on DF12, DF13, DF14
		gEMVCoCtx.mTransactionalContext->mSkipTACIACDefault = bTRUE;  // DF11. If online only terminal and unable to go online then ARC = Z3 + AAC at 2nd GenAC
		gEMVCoCtx.mTransactionalContext->mVelocityChecking = bTRUE; // DF12
		gEMVCoCtx.mTransactionalContext->mRandomTransactionSelection = bTRUE;  // DF13
		gEMVCoCtx.mTransactionalContext->mFloorLimitChecking = bTRUE;  // DF14
		gEMVCoCtx.mTransactionalContext->mTAC = bTRUE;  // DF15
		gEMVCoCtx.mTransactionalContext->mPinTimeOut = 10;  // DF27

		gpiMemCpy(gEMVCoCtx.mTransactionalContext->mTransactionDate,payCtx->mTransactionDate,sizeof(gEMVCoCtx.mTransactionalContext->mTransactionDate));
		gpiMemCpy(gEMVCoCtx.mTransactionalContext->mTransactionTime,payCtx->mTransactionTime,sizeof(gEMVCoCtx.mTransactionalContext->mTransactionTime));

		agnosError = agnOpenSession("","",(const tString)"EMVCO CT Example",(const tTransactionalContext*)gEMVCoCtx.mTransactionalContext,
									bTRUE /*DirectExecution -> reach GenAC - no granular calls*/,
									bFALSE /*setEMVTag calls are performed by L3*/,
									&payCtx->mSession,
									bFALSE /*clipping*/,
									bFALSE /*sred*/);
									
		agnSetEMVTag(payCtx->mSession,0x9C,1,(uint8_t*)"\x00"); // Transaction type: depends on Transaction Related Data (TRD)
		agnSetEMVTag(payCtx->mSession,0x9F1A,2,(uint8_t*)"\x00\x00"); // Terminal Country Code: depends on merchant context
		agnSetEMVTag(payCtx->mSession,0x9F33,3,(uint8_t*)"\x00\x00\x00"); // Terminal Capabilities: depends on ICS
		agnSetEMVTag(payCtx->mSession,0x9F35,1,(uint8_t*)"\x00"); // Terminal Type: depends on TRD
		agnSetEMVTag(payCtx->mSession,0x9F40,5,uint8_t*)"\x00\x00\x00\x00\x00"); // Additional Terminal Capabilities: depends on TRD
		
		agnSetEMVTag(payCtx->mSession,0x9F39,1,"\x05"); // POS Entry Mode

Important:

L3 must initialize CAKeys to enable ODA
Application Selection shall be performed ahead to map AID selection with corresponding EMV tags. This depends on merchant context and acquirer configuration (PROCESSING)

Execution

There are 3 ways to execute an EMVCo CT transaction. However, they follow the same pattern initiate/complete

Direct Execution → see emvco.c, an example used to implement EMVCo test app required for EMVCo CT L2 TA

		agnosError = agnInitiateEMVTransaction(	payCtx->mSession,payCtx->mAmount,payCtx->mCashBack,
												gEMVCoCtx.mMutualList.mList[gEMVCoCtx.mCandidate].mADFName,gEMVCoCtx.mMutualList.mList[gEMVCoCtx.mCandidate].mADFLen,
												&payCtx->mCID);
		if (agnTXN_ONLINE == agnosError)
		{
			return OLA_GO_ONLINE;
		}
		else if (agnTXN_ACCEPTED == agnosError)
		{
			return OLA_OFFLINE_ACCEPTED;
		}
		else if (agnTXN_REJECTED == agnosError)
		{
			return OLA_OFFLINE_DECLINED;
		}
		else if (agnSERVICE_NOT_ALLOWED == agnosError)
		{
			return OLA_NOT_ACCEPTED;
		}
		else if (agnPROCEED_TO_NEW_SELECTION == agnosError)
		{
			return OLA_CONTACT_NEW_SELECTION;
		}
		else if (agnSELECTION_ERROR == agnosError)
		{
			return OLA_CONTACT_SELECTION_ERROR;
		}
		else if (agnINTERRUPTED == agnosError)
		{
			return OLA_CANCEL;
		}
		else // Including agnSYSTEM_ERROR
		{
			return OLA_ERROR;
		}
		
		// ...
		
		agnosError = agnCompleteEMVTransaction(	payCtx->mSession,payCtx->mARC,&payCtx->mCID,
												payCtx->mDataExchange.mIssuerResponse.mStream,payCtx->mDataExchange.mIssuerResponse.mLength,
												payCtx->mUnableToGoOnline);

Granular calls

Documentation under development…

Granular calls through state machine

Documentation under development…

Post-conditions setup

Use different primitives such as agnGetEMVTag() to fetch any EMV information

EMV Engine

EMV Engine
See agnos..h
`#include`	`#include "agnoserrors.h" //---- Agnos Framework Headers ---- #include "agnosdatabase.h" //---- Global Headers ---- #include "gpi_agnos_framework_globals.h"`	--
`tTransactionalContext`
`agnGetVersionNumber`		Get EMV core engine version.
`agnOpenSession`		Open a CT session to initiate an EMV transaction flow.
`agnInitiateEMVTransaction`		Initiate/Resume an EMV transaction
`agnCompleteEMVTransaction`		Complete a transaction as per EMVCo definition
`agnGetDatabase`
`agnIsEMVTagKnown`		Return bTRUE is tag statically known.
`agnIsEMVTagPresent`		Return bTRUE if tag is present whatever its length.
`agnIsEMVTagEmpty`		Return bTRUE if tag’s length is 0.
`agnIsEMVTagNotEmpty`		Return bTRUE if tag’s length is not 0.
`agnGetEMVTag`		Get a specific tag from Agnos database.
`agnSetEMVTag`		Add a tag into Agnos database without checking tag’s update condition.
`agnOverwriteEMVTag`		Overwrite an existing tag. If it doesn’t exist, create it (no garbage collection if sizes don’t match).
`agnRemoveEMVTag`		Remove a tag from Agnos database (no garbage collection).
`agnORTVR`		OR a specific TVR’s bit to 1.
`agnORAgnosTVR`		OR a specific Agnos TVR’s bit to 1.
`agnSetAgnosTVR`		Set a specific Agnos TVR byte value.
`agnOpenSessionCL`		Open a CL session to initiate an EMV transaction flow
`agnCloseSession`		Close a transaction flow.
agnSetAgnosDatabase		Add a series of tags. Each tag is statically indexed and ruled by an update condition. Use an appropriate update condition to store tags directly into Agnos database
agnSetKernelStatus		Set core engine to a specific state. Use this primitive to skip a state in State Machine mode
agnGetAllTags		Get all tags from Agnos database

Application Selection Routines

Application Selection Routines
See selection..h
`#include`		--
`tADFList`
`tADF`
`tPSE`

EMV Tags Database

EMV Tags Database
See emvtag.h, agnosdatabase.h
		--
adbGetVersionNumber		Provide Agnos database version. Get all pointers on shared RAM spaces provided by SAL/HAL and set adbAddTag strategy to STANDARD (i.e. EMVCo rule where update conditions are not checked)
adbResetDataBase		Reserved to Agnos core engine. Reset database structure
adbSetStrategy		Reserved to Agnos core engine and contactless card processing. By default, Agnos databse uses EMVco tags storage strategy where no check is performed on tags' update conditions. If a storage strategy is defined (by a contactless card processing) then: If an AddTag_Contacltess callback is defined (by a contactless card processing), Agnos database calls the callback to check wheter a tag can be added Else, Agnos database uses its default contactless storage strategy
adbAddTag		Reserved to Agnos core engine. Check whether a tag may be added into EMV tags database. In order to store EMV tags directly into Agnos database, use agnSetAgnosDataBase primitive instead
adbAddUnknownTag		Add any tags into EMV tags database in “UnknowTag” bucket
adbGetUnknowTags		Get all tags stored into unknown tags bucket
adbGetUnknownTagsLength		Get the bucket’s length
adbGetUnknownTagsCount		Get tags count from the bucket
adbGetAllTLV		Get all TLV stored in AgnosDB.

Code Example

Code Example
See emvco.c. and selectionlogic.h. They provide good examples on agnos.h and selection.h integration in the scope of contact card processing.

Amadis Developer's Guide

Amadis

Agnos API - version 3.5.20.23770

_Agnos _version 3.5.20 _revision 23770

EMV Engine

EMV Engine

`#include`

`tTransactionalContext`

`agnGetVersionNumber`

`agnOpenSession`

`agnInitiateEMVTransaction`

`agnCompleteEMVTransaction`

`agnCloseSession`

Application Selection Routines

Application Selection Routines

`tADFList`

EMV Tags Database

EMV Tags Database

Code Example

Code Example