EMV

End-Point

Methods

Description

End-Point

Methods

Description

/api/v1/transactions/emv

POST

Initiate EMV transaction

/api/v1/transactions/emv/{id}/cancel

POST

Cancel EMV transaction

All API end-points require an authentication header to included with the request. See API Authentication

Initiate EMV transaction

Allows for the initiation of an EMV transaction in conjunction with a supported EMV device. Calls made will activate the EMV terminal to prompt the customer for action, either swipe/insert card. Once completed the results of the transaction will be returned.

Request Fields

Field

Required

Description

Field

Required

Description

amount

Yes

Amount of the transaction

id

No

Unique identifier for the transaction. This ID can also be used in the event that the current transaction request needs to be canceled.

orderNumber

No

Merchant generated order number for the transaction. This can be PO Number or any other unique value to allow duplicate transactions if desired.

Example Request

1 2 3 4 5 6 POST /api/v1/transactions/emv { "id": "025a16e997a4", "amount": "5.26", "orderNumber": "584568", }

Response Fields

Field

Description

Field

Description

account

Masked account number

auth

Authorization code

authamount

If the amount authorized is different than the requested amount this is the amount that must show on the receipt. It is possible that the integration could pool multiple transactions on one receipt and in that case the authamount needs to be present for each card along with other card specific receipt data. Note that some processors do not allow pooling card data onto one receipt and require separate receipts per card.

cardholdername

Customers name as encoded on the card.

cardlevel

Internal interpretation of the visa 62.23 card level result returned by most processing institutions

cardtype

This is the value that would have been configured in supported card types for the account. Use this to take card specific action in receipt generation.

code

Used to determine if the transaction was approved or declined.

merch_proc

Merchant Processing Institution (internal name) used. This may be used to trigger different receipt formats based on processor-specific requirements.

pclevel

whether or not it was a Purchase card transaction- 0=no, 1=business card, 2=purchase card

phard_code

detailed result code for success/fail from processor

ttid

transaction id guaranteed to be unique across all transactions for a particular merchant

u_need_signature

The u_need_signature means that a signature is required and it should be printed/obtained from the paper receipt. If an EMV requires a signature and one was not captured electronically, this flag indicates it should be obtained via a paper receipt.

verbiage

textual, human-interpretable response code (meant for system display to clerk)

Cancel EMV transaction

Cancel an already initiated EMV transaction, based on the ID provided in the original request.

Request Fields

Field

Required

Description

Field

Required

Description

id

No

Unique identifier for the transaction. This ID will be the one provided in the initial EMV initiate request.

Example Request

Using our previous initiate EMV request as an example, we use the “id” value to identify the transaction to cancel.

1 POST /api/v1/transactions/emv/025a16e997a4/cancel