DocumentationAPI ReferenceRecipes
API Reference

Create a EMV payment

post
https://api.hips.com/v2/payments/emv

This resource is used to send EMV payment pre-authorizations or purchase from an EMV payment terminal. The EMV payment terminal must be registered in Hips TMS (see separate TMS API) and you must have the TerminalApiKeyAuth to authenticate to this resouce. Idempotency-Key header is required for the resource. Authentication Key Type: TerminalApiKeyAuth

Body Params
string

TLV-BER EMV ICC Data (DE-55). Field 55 is used to transport ICC data. This data element utilises the Tag, Length, Value (TLV) structure to delineate different sub-elements in the following manner:[TAG][LENGTH][VALUE][TAG][LENGTH][VALUE].

string
enum
required

Specify transaction type. pre_authorization places a hold on your customer’s card for a specified amount and needs to be captured later. purchase is pre_authorization and capture in one transaction, hence no capture is required. authorization_check are transactions to check the validity of the card.

Allowed:
int32

This is the total amount of the transaction (including tip, vat/tax and cashback). This should be same amount as in EMV TAGS 9F02+9F03. We express amounts in minor units according to the ISO 4217 standard. That means they are expressed in the smallest unit of currency. Examples are USD with 1000 representing $10, GBP with 500 representing £5, EUR with 50 representing €0.50 and SEK with 100 representing 1kr.

int32

This is the amount with vat/tax, but without tip and cashback. We express amounts in minor units according to the ISO 4217 standard. That means they are expressed in the smallest unit of currency. Examples are USD with 1000 representing $10, GBP with 500 representing £5, EUR with 50 representing €0.50 and SEK with 100 representing 1kr.

int32

This is the vat/tax amount. This amount is part of net_amount. We express amounts in minor units according to the ISO 4217 standard. That means they are expressed in the smallest unit of currency. Examples are USD with 1000 representing $10, GBP with 500 representing £5, EUR with 50 representing €0.50 and SEK with 100 representing 1kr.

string
enum
required

We use the ISO 4217 standard for defining currencies.

int32

This is the tip amount. This amount is part of gross_amount. We express amounts in minor units according to the ISO 4217 standard. That means they are expressed in the smallest unit of currency. Examples are USD with 1000 representing $10, GBP with 500 representing £5, EUR with 50 representing €0.50 and SEK with 100 representing 1kr.

int32

This is the cashback amount. This should be same amount as in EMV TAG 9F03. We express amounts in minor units according to the ISO 4217 standard. That means they are expressed in the smallest unit of currency. Examples are USD with 1000 representing $10, GBP with 500 representing £5, EUR with 50 representing €0.50 and SEK with 100 representing 1kr.

string

Any integer. This is a reference so you know which employee the tips belongs to or who initiated the transaction.

string

Reserved field for Hips

string

Your reference for this transaction. This reference will pass through in the transaction chain all the way to the card issuer.

string

Your metadata 1 for order (max 255 characters)

string

Your metadata 2 for order (max 255 characters)

string

URL - Webhook URL where HIPS will post all events related to this payment

boolean

Indicates if this is a test transaction. Test transactions will have simulated responses and will not be sent to card schemes.

string

This data must be provided if the magnetic stripe is read and in all transactions where ICC is present. As this data may not be stored in the terminal due to PCI regulations it will appear only for transaction types where the card is present. The Track2 data is provided excluding start and end sentinels and excluding LRC characters. Example: `5413330056003529D141220599999994699600

string

10 byte. For DUKPT this subfield contains the KSN. For other algorithms the binary data can contain all zeros. It is mandatory in case track2 is provided and pos_entry_mode is magstripe.

string

A 2-digit number needed to distinguish separate cards with the same primary account number. In case of EMV transactions this field must be created from tag ‘5F34’.

string

This is an 16 byte field containing the encrypted Online-PIN. The PIN block is formatted in ISO-0, ISO-1 or ISO-3 format.

string

20 byte. For DUKPT this subfield contains the KSN. For other algorithms the binary data can contain all zeros. It is mandatory in case pin_block is provided.

string
enum
required

POS Entry Mode

string
enum

Card PIN BLOCK ISO format iso_0, iso_1 or iso_3

Allowed:
string
enum

Card PIN BLOCK encryption algorithm

Allowed:
string

Cardholder reference number, e.g. a dynamic descriptor shown on the cardholder’s bank account statement. The descriptor can be dynamically to include e.g. an order number for improved customer service and payment identification. Not all issuing banks are capable to show the full descriptor due to the technical limitations.

boolean

In order to allow acquirers and issuers to comply with the PSD2 regulation, card schemes introduced new response codes and new fields, which has to be supported by issuers/acquirers to support the contactless single tap processing in case the card scheme receive a transaction acquired from a contactless terminal using a card on which the PIN was not entered. Set to true if this transaction is a single tap re-submission.

string

The unique identifier (id) of the payment for which you are providing SCA (Strong Customer Authentication).

boolean

Set to true if this is a deferred authorization that was approved by the terminal.

Responses

Updated 10 months ago

Language
Credentials
Basic
base64
:
Response 
Click Try It! to start a request and see the response here! Or choose an example:
application/json
Updated 10 months ago