Payment Service provider API ISO8583_2 ( IFSF) H2H description

Version 5.2 by Kristian Lingsom on 2017/10/13 15:11

 

OVERVIEW

The purpose of the H2H PayEx link is to enable authorization and settlement of card transactions, where PayEx is end host for that card, or just an PSP. The third party host acts as a gateway in between payment terminals and PayEx.

pos server.png

  • The third party host can be a single or dual host system.
  • PayEx has a fully redundant system, with an active/active configuration.
  • The third party host(s) connect to PayEx loadbalanser

MESSAGE LAYOUT

This section covers message types and fields supported by PayEx

​​​​​​GENERAL

Presence

Title

Description

C

Conditional

The data element’s presence depends on specific

circumstances. The circumstance is defined either directly or by reference to another section of the document

CE

Conditional echo

The response message must have the same data element

if the data element is present in the original message

M

Mandatory

Data element must be present in the specified message

ME

Mandatory echo

The response message must have the same data element and value as sent in the original message request or advice message.

O

Optional

The data element may or may not be present in the

message.

Requests received missing a mandatory field will be 904 - Format Error.

Optional fields may always be present in requests, even when not needed. In such case, they will be ignored.

The third party host must ignore unknown fields included in the response messages.

When no usage notes are given in the field description, the field should be used as described in IFSF [1].

The “Format”-column can contain following info:

  • LL: Variable length field, max 99 bytes as data. The field contains 2 bytes holding the length of the data. Example: 303101 a one byte field with LL = 3031 and the data is 01.
    • Date/time field formats, YYMMDDhhmmss (or variations), where:
      • YY : Last 2 digits of the year, 00 through 99
      • MM: Month, 01 through 12.
      • DD: Day, 01 through 31
      • hh: Hour, 00 through 23
      • mm: Minutes, 00 through 59
      • ss: Seconds, 00 through 59
    • LLL: Variable length field, max 999 bytes as data. The field contains 3 bytes holding the length of the data. Example: 30303101 a one byte field with LLL = 303031 and the data is 01.

The “Type”-column can contain:

  • a : Alphabetic character [a..z,A..Z]
  • n : Numeric BCD-digit. [0..9]
  • ans: alphabetic, numeric and special characters
  • an : alphabetic and numeric.
  • s : Special characters.
  • b : Binary
  • p: pad character, space
  • x: “C” for credit, “D” for debit and shall always be associated with a numerical amount data element.

The “Size”-column can contain:

  • Variable length fields have a size that looks like “..nn”, where nn is the maximum number of characters or bytes.
  • A fixed length field has “n” as size content, with n the number of characters or bytes.

All fixed length “n” data elements are assumed to be right justified with leading zeroes. All other fixed length data elements are left justified with trailing spaces. In all “b” data elements, blocks of 8 bits are assumed to be left justified with trailing zeroes.

For technical reasons an advice can be declined if PayEx is unable to store the transaction. In this case the third party host need to retry the advice until manual intervention or the advice has been accepted. It’s expected that the third party implement a retry delay (to-be-defined). After 6 retry attemps have failed manual intervention by thirsd party and PayEx support must be initiated.

 

NETWORK MANAGEMENT

Message authentication is performed on network management requests to validate the MAC key issued by PayEx, and by the third patry to validate that the PayEx system is running as expected. Implementation of this message type is not mandatory.

NETWORK MANAGEMENT ADVICE 1820

Element number

Data element name

Presence

Format

Type

Size

Usage notes

7

Date and time, transmission

M

MMDDh

hmmss

n

10

 

11

Systems trace audit number

M

 

n

6

 

12

Date and time, local transaction

M

YYMMD

Dhhmm ss

n

12

 

24

Function code

M

 

n

3

831: System audit control / echo test. Other function codes are not supported.

32

Acquiring institution identification

code

M

LL

n

..11

ISO country code (where the

host is located)

53

Security Related Control Information

M

LL

b

..48

 

64

MAC

M

 

b

8

 

NETWORK MANAGEMENT ADVICE RESPONSE 1830

Element number

Data element name

Presence

Format

Type

Size

Usage notes

7

Date and time, transmission

M

MMDDh

hmmss

n

10

 

11

Systems trace audit number

ME

 

n

6

 

12

Date and time, local transaction

ME

YYMMD

Dhhmm ss

n

12

 

32

Acquiring institution identification code

ME

LL

n

..11

 

39

Action code

M

 

n

3

Fixed 800

53

Security Related Control Information

M

LL

b

..48

 

64

MAC

M

 

b

8

 

Data element name

INDOOR TRANSACTIONS

FINANCIAL TRANSACTION REQUEST 1200

Fields not described on the below table are not supported by PayEx

Element number

Data element name

Presence

Format

Type

Size

Usage notes

2

PAN

C

LL

ans

..19

Present if manual PAN key entry.

3

Processing Code

M

 

n

6

 

4

Amount, transaction

M

 

n

12

 

7

Date and time, transmission

M

MMDDh

hmmss

n

10

 

11

Systems trace audit number

M

 

n

6

Assigned by third party host

12

Date and time, local transaction

M

YYMMD

Dhhmms s

n

12

 

14

Date expiry

C

YYMM

n

4

Only present for manual PAN keyentry.

22

Point of service data code

M

 

an

12

 

24

Function code

M

 

n

3

 

25

Message reason code

M

 

n

4

 

26

Card acceptor business code

M

 

n

4

5541 for indoor and 5542 for outdoor.

32

Acquiring institution identification

code

M

LL

n

..11

Contains ISO country code.

33

Forwarding Institution identification code

O

LL

n

..11

Required in concentrator model

35

Track 2 data

C

LL

ns

..37

Mandatory unless it’s a pan key entry transaction

41

Card acceptor terminal identification

M

 

ans

8

 

42

Card acceptor identification code

M

 

ans

15

8 digit number assigned by PayEx

43

Card acceptor name / location

M

 

ans

..999

 

48

Message control data elements

M

LLL

ans

..999

 

48-0

Bit map

M

 

b

8

 

48-4

Batch/sequence number

M

 

n

10

Assigned by 3rd party

48-8

Customer data

C

LLL

ans

..250

Only present if customer data entered.  As specified in [1]

48-9

Track II of vehicle card

O

LL

ns

..37

 

48-14

PIN Encryption Methodology

C

 

ans

2

Mandatory if online PIN, and must have value 33.

48-32

VAT Percentages

M

LL

ans

..91

 

48-37

Vehicle identification entry mode

O

 

ans

1

 

48-38

Pump linked indicator

O

 

n

1

 

48-39

Delivery note number

O

 

n

10

POS ticket number

49

Currency code, transaction

M

 

an

3

 

52

PIN Data

C

 

b

8

Only for Online PIN

53

Security Related Control Information

M

LL

b

..48

 

59

Transport Data

M

LLL

ans

..999

63

Product data

M

LLL

ans

..999

 

64

MAC

M

 

b

8

 

FINANCIAL TRANSACTION RESPONSE 1210

The following fieds listed below are supported in the response message. Fields not listed are not supported.

Element number

Data element name

Presence

Format

Type

Size

Usage notes

3

Processing Code

ME

 

n

6

 

4

Amount, transaction

M

 

n

12

 

7

Date and time, transmission

M

MMDDh

hmmss

n

10

 

11

Systems trace audit number

ME

 

n

6

 

12

Date and time, local transaction

ME

YYMMD

Dhhmm ss

n

12

 

32

Acquiring institution identification code

ME

LL

n

..11

 

38

Approval code

C

 

anp

6

Present if transaction approved

39

Action code

M

 

n

3

 

41

Card acceptor terminal identification

ME

 

ans

8

 

42

Card acceptor identification code

ME

 

ans

15

 

48

Message control data elements

M

LLL

ans

..999

 

48-0

Bit map

M

 

b

8

 

48-4

Batch/sequence number

ME

 

n

10

 

49

Currency code, transaction

ME

 

an

3

 

53

Security Releated Control Info

M

LL

b

..48

 

59

Transport Data

ME

LLL

ans

..999

Ref xxx

62

Product sets

C

LLL

ans

..999

 

62-1

Allowed product sets

C

LL

ans

..99

 

62-2

Device type

O

 

n

1

 

62-3

Message text

O

LLL

ans

..894

 

64

MAC

M

 

b

8

 

 

​​​​​​​FINANCIAL TRANSACTION ADVICE 1220/1221

Fields not described on the below table are not supported.

Element number

Data element name

Presence

Format

Type

Size

Usage notes

2

PAN

C

LL

ans

..19

Present if manual PAN key entry

3

Processing Code

M

 

n

6

 

4

Amount, transaction

M

 

n

12

 

7

Date and time, transmission

M

MMDDh

hmmss

n

10

 

11

Systems trace audit number

M

 

n

6

Assigned by third party host

12

Date and time, local transaction

M

YYMMD

Dhhmms s

n

12

 

14

Date expiry

C

YYMM

n

4

Present if manual PAN key entry

22

Point of service data code

M

 

an

12

 

24

Function code

M

 

n

3

Fixed 200: Original Financial Transaction Advice

25

Message reason code

M

 

n

4

1003: Card Issuer

Unavailable

6

Card acceptor business code

M

 

n

4

5541 for indoor and 5542 for outdoor.

32

Acquiring institution identification code

M

LL

n

..11

Contains ISO country code

33

Forwarding Institution identification code

O

LL

n

..11

Required in concentrator model

35

Track 2 data

C

LL

ns

..37

 

38

Approval Code

M

 

anp

6

Fixed 000000

39

Action Code

M

 

n

3

Fixed 000

41

Card acceptor terminal identification

M

 

ans

8

 

42

Card acceptor identification code

M

 

ans

15

 

43

Card acceptor name / location

M

 

ans

..999

 

48

Message control data elements

M

LLL

ans

..999

 

48-0

Bit map

M

 

b

8

 

48-4

Batch/sequence number

M

 

n

10

Assigned by third party host

48-8

Customer data

C

LLL

ans

..250

 

48-9

Track II of vehicle card

O

 

ns

..37

 

48-32

VAT Percentages

M

LL

ans

..91

 

48-37

Vehicle identification entry mode

O

 

ans

1

 

48-38

Pump linked indicator

O

 

n

1

 

48-39

Delivery note number

O

 

n

10

POS ticket number

49

Currency code, transaction

M

 

an

3

 

53

Security Related Control Information

M

LL

b

..48

 

59

Transport data

M

LLL

ans

..999

63

Product data

M

LLL

ans

..999

 

64

MAC

M

 

b

8

 

​​​​​FINANCIAL TRANSACTION ADVICE RESPONSE 1230

The following fields listed below are supported in the response message. Fields not listed are not included in the response message.

Element number

Data element name

Presence

Format

Type

Size

Usage notes

3

Processing Code

ME

 

n

6

 

4

Amount, transaction

ME

 

n

12

 

7

Date and time, transmission

M

MMDDh

hmmss

n

10

 

11

Systems trace audit number

ME

 

n

6

 

12

Date and time, local transaction

ME

YYMMD

Dhhmm ss

n

12

 

32

Acquiring institution identification code

ME

LL

n

..11

 

38

Approval code

ME

 

anp

6

 

39

Action code

M

 

n

3

Fixed 000: Approved

41

Card acceptor terminal identification

ME

 

ans

8

 

42

Card acceptor identification code

ME

 

ans

15

 

48

Message control data elements

M

LLL

ans

..999

 

48-0

Bit map

M

 

b

8

 

48-4

Batch/sequence number

ME

 

n

10

 

49

Currency code, transaction

ME

 

an

3

 

53

Security Related Control Information

M

LL

b

..48

 

59

Transport Data

ME

LLL

ans

..999

64

MAC

M

 

b

8

 

​​​​​​​REVERSAL ADVICE 1420/1421

Only fields listed below are supported

Element number

Data element name

Presence

Format

Type

Size

Usage notes

2

Primary account number

M

LL

ans

..19

 

3

Processing Code

M

 

n

6

 

4

Amount, transaction

M

 

n

12

 

7

Date and time, transmission

M

MMDDh

hmmss

n

10

 

11

Systems trace audit number

M

 

n

6

 

12

Date and time, local transaction

M

YYMMD

Dhhmm ss

n

12

 

14

Date, expiration

M

YYMM

n

4

 

24

Function code

M

 

n

3

Fixed 400: Full reversal

25

Message reason code

M

 

n

4

4000: Customer Cancellation.

4020: Invalid response, no action taken.

4021: Timeout waiting for response.

4351: Cancellation – unmatched signature

32

Acquiring institution identification

code

M

LL

n

..11

Country ISO code

33

Forwarding Institution identification code

O

LL

n

..11

Required in concentrator model

38

Approval code

C

 

anp

6

Present if original

transaction was approved

41

Card acceptor terminal identification

M

 

ans

8

 

42

Card acceptor identification code

M

 

ans

15

 

43

Card acceptor name / location

M

LL

ans

..99

 

48

Message control data elements

M

LLL

ans

..999

 

48-0

Bit map for data elements in bit 48

M

 

b

8

 

48-4

Batch/sequence number

M

 

n

10

 

49

Currency code, transaction

M

 

an

3

 

53

Security Related Control Information

M

LL

b

..48

 

56

Original data elements

M

LL

n

..35

 

59

Transport data

M

LLL

ans

..999

Ref.13.25.  Same as P-59

from 1200 (If host originated)

64

MAC

M

 

b

8

 

​​​​​​​REVERSAL ADVICE RESPONSE 1430

Element number

Data element name

Presence

Format

Type

Size

Usage notes

2

Primary account number

ME

LL

ans

..19

 

3

Processing Code

ME

 

n

6

 

4

Amount, transaction

ME

 

n

12

 

7

Date and time, transmission

M

MMDDh

hmmss

n

10

 

11

Systems trace audit number

ME

 

n

6

 

12

Date and time, local transaction

ME

YYMMD

Dhhmm ss

n

12

 

32

Acquiring institution identification code

ME

LL

n

..11

 

38

Approval code

CE

 

anp

6

Present if original transaction was approved

39

Action code

M

 

n

3

400 or 480

41

Card acceptor terminal identification

ME

 

ans

8

 

42

Card acceptor identification code

ME

 

ans

15

 

48

Message control data elements

M

LLL

ans

..999

 

48-0

Bit map for data elements in bit 48

M

 

b

8

 

48-4

Batch/sequence number

ME

 

n

10

 

49

Currency code, transaction

ME

 

an

3

 

53

Security Related Control Information

M

LL

b

..48

 

59

Transport data

ME

LLL

ans

..999

64

MAC

M

 

b

8

 

​​​​​​​OUTDOOR TRANSACTIONS

​​​​​​​AUTHORISATION REQUEST 1100

Element number

Data element name

Presence

Format

Type

Size

Usage notes

3

Processing Code

M

 

n

6

Fixed 000000. Other processing code values are not supported.

4

Amount, transaction

M

 

n

12

 

7

Date and time, transmission

M

MMDDh

hmmss

n

10

 

11

Systems trace audit number

M

 

n

6

Assigned by third party host

12

Date and time, local transaction

M

YYMMD

Dhhmms s

n

12

 

22

Point of service data code

M

 

an

12

 

24

Function code

M

 

n

3

Fixed 101: Original Authorisation. Other values are

not supported.

25

Message reason code

M

 

n

4

Fixed 1508

26

Card acceptor business code

M

 

n

4

5541 for indoor and 5542 for outdoor

32

Acquiring institution identification

code

M

LL

n

..11

Country ISO code

33

Forwarding Institution identification code

O

LL

n

..11

Required in concentrator model

35

Track 2 data

M

LL

ns

..37

 

41

Card acceptor terminal identification

M

 

ans

8

 

42

Card acceptor identification code

M

 

ans

15

 

43

Card acceptor name / location

M

LL

ans

..99

 

48

Message control data elements

M

LLL

ans

..999

 

48-0

Bit map

M

 

b

8

 

48-4

Batch/sequence number

M

 

n

10

Assigned by third party host

48-8

Customer data

C

LLL

ans

..250

 

48-9

Track II of vehicle card

O

LL

ns

..37

 

48-14

PIN Encryption Methodology

C

 

ans

2

Present if online PIN

48-37

Vehicle identification entry mode

O

 

ans

1

 

48-38

Pump linked indicator

O

 

n

1

 

49

Currency code, transaction

M

 

an

3

 

52

PIN Data

C

 

b

8

Present if online PIN

53

Security Related Control Information

M

LL

b

..48

 

59

Transport data

M

LLL

ans

..999

64

MAC

M

 

b

8

 

​​​​​​​AUTHORISATION RESPONSE 1110

Element number

Data element name

Presence

Format

Type

Size

Usage notes

3

Processing Code

ME

 

n

6

 

4

Amount, transaction

M

 

n

12

 

7

Date and time, transmission

M

MMDDh

hmmss

n

10

 

11

Systems trace audit number

ME

 

n

6

 

12

Date and time, local transaction

ME

YYMMD

Dhhmm ss

n

12

 

30

Original amount

C

 

n

24

Original amount if partial approval or decline.

32

Acquiring institution identification

code

ME

LL

n

..11

 

38

Approval code

C

 

anp

6

If transaction has been approved.

39

Action code

M

 

n

3

 

41

Card acceptor terminal identification

ME

 

ans

8

 

42

Card acceptor identification code

ME

 

ans

15

 

48

Message control data elements

M

LLL

ans

..999

 

48-0

Bit map

M

 

b

8

 

48-4

Batch/sequence number

ME

 

n

10

 

49

Currency code, transaction

ME

 

an

3

 

53

Security Related Control Information

M

LL

b

..48

 

59

Transport data

ME

LLL

ans

..999

 

62

Product sets

C

LLL

ans

..999

 

62-1

Allowed product sets

C

LL

ans

..99

 

62-2

Device type

O

 

n

1

 

62-3

Message text

O

LLL

ans

..894

 

64

MAC

M

 

b

8

 

​​​​​​​FINANCIAL TRANSACTION ADVICE 1220/1221

Element number

Data element name

Presence

Format

Type

Size

Usage notes

3

Processing Code

M

 

n

6

Fixed 000000

4

Amount, transaction

M

 

n

12

 

7

Date and time, transmission

M

MMDDh

hmmss

n

10

 

11

Systems trace audit number

M

 

n

6

Assigned by third party host

12

Date and time, local transaction

M

YYMMD

Dhhmm ss

n

12

 

22

Point of service data code

M

 

an

12

 

24

Function code

M

 

n

3

200: Standing in for Card Issuer

201: Previously approved authorisation

202: Previously approved

authorisation (amount differs)

25

Message reason code

M

 

n

4

1003: Card Issuer unavailable

1004:Terminal processed

26

Card acceptor business code

M

 

n

4

5541 for indoor and 5542 for outdoor

32

Acquiring institution identification

code

M

LL

n

..11

ISO country code

33

Forwarding Institution identification code

O

LL

n

..11

Required in concentrator model

35

Track 2 data

M

LL

ns

..37

 

38

Approval code

M

 

anp

6

Copied from original approved authorisation response if available. Otherwise 000000

39

Action code

M

 

n

3

Copied from approved authorisation, or 000 when

approved offline.

41

Card acceptor terminal identification

M

 

ans

8

 

42

Card acceptor identification code

M

 

ans

15

 

43

Card acceptor name/location

M

LL

ans

..99

 

48

Message control data elements

M

LLL

ans

..999

 

48-0

Bit map

M

 

b

8

 

48-4

Batch/sequence number

M

 

n

10

Assigned by Third party host

48-8

Customer data

C

LLL

ans

..250

 

48-32

VAT Percentages

M

LL

ans

..91

 

48-37

Vehicle identification entry mode

O

 

ans

1

 

48-38

Pump linked indicator

O

 

n

1

 

48-39

Delivery note number

O

 

n

10

POS ticket number

49

Currency code, transaction

M

 

an

3

 

53

Security Related Control Information

M

LL

b

..48

 

56

Original Data Elements

C

LL

n

..35

Not present if stand-in authorised (P-24 with value

200)

59

Transport data

M

LLL

ans

..999

63

Product data

M

LLL

ans

..999

 

64

MAC

M

 

b

8

 

​​​​​​​FINANCIAL TRANSACTION ADVICE RESPONSE 1230

Element number

Data element name

Presence

Format

Type

Size

Usage notes

3

Processing Code

ME

 

n

6

 

4

Amount, transaction

ME

 

n

12

 

7

Date and time, transmission

M

MMDDh

hmmss

n

10

 

11

Systems trace audit number

ME

 

n

6

 

12

Date and time, local transaction

ME

YYMMD

Dhhmm ss

n

12

 

32

Acquiring institution identification code

ME

LL

n

..11

 

38

Approval code

CE

 

anp

6

 

39

Action code

M

 

n

3

Fixed 000: Approved

41

Card acceptor terminal identification

ME

 

ans

8

 

42

Card acceptor identification code

ME

 

ans

15

 

48

Message control data elements

M

LLL

ans

..999

 

48-0

Bit map

M

 

b

8

 

48-4

Batch/sequence number

ME

 

n

10

 

49

Currency code, transaction

ME

 

an

3

 

53

Security Related Control Information

M

LL

b

..48

 

59

Transport Data

ME

LLL

ans

..999

64

MAC

M

 

b

8

 

​​​​​​​REVERSAL ADVICE 1420/1421

A reversal on an authorization request is possible.

Element Number

Data element name

Presence

Format

Type

Size

Usage notes

2

Primary account number

M

LL

ans

..19

 

3

Processing Code

M

 

n

6

Fixed 000000

4

Amount, transaction

M

 

n

12

 

7

Date and time, transmission

M

MMDDh

hmmss

n

10

 

11

Systems trace audit number

M

 

n

6

 

12

Date and time, local transaction

M

YYMMD

Dhhmm ss

n

12

 

14

Date, expiration

M

YYMM

n

4

 

24

Function code

M

 

n

3

Fixed 400: Full reversal

25

Message reason code

M

 

n

4

4000: Customer Cancellation 4020: Invalid response, no action taken

4021: Timeout waiting for response

32

Acquiring institution identification

code

M

LL

n

..11

ISO country code

33

Forwarding Institution

identification code

O

LL

n

..11

Required in concentrator

model

38

Approval code

C

 

anp

6

Present if original transaction was approved

41

Card acceptor terminal identification

M

 

ans

8

 

42

Card acceptor identification code

M

 

ans

15

 

43

Card acceptor name/location

M

LL

ans

..99

 

48

Message control data elements

M

LLL

ans

..999

 

48-0

Bit map

M

 

b

8

 

48-4

Batch/sequence number

M

 

n

10

 

49

Currency code, transaction

M

 

an

3

 

53

Security Related Control Information

M

LL

b

..48

 

56

Original data elements

M

LL

n

..35

 

59

Transport data

M

LLL

ans

..999

64

MAC

M

 

b

8

 

​​​​​​​REVERSAL ADVICE RESPONSE 1430

Element number

Data element name

Presence

Format

Type

Size

Usage notes

2

Primary account number

ME

LL

ans

..19

 

3

Processing Code

ME

 

n

6

 

4

Amount, transaction

ME

 

n

12

 

7

Date and time, transmission

M

MMDDh

hmmss

n

10

 

11

Systems trace audit number

ME

 

n

6

 

12

Date and time, local transaction

ME

YYMMD

Dhhmm ss

n

12

 

32

Acquiring institution identification

code

ME

LL

n

..11

 

38

Approval code

CE

 

anp

6

 

39

Action code

M

 

n

3

400

41

Card acceptor terminal identification

ME

 

ans

8

 

42

Card acceptor identification code

ME

 

ans

15

 

48

Message control data elements

M

LLL

ans

..999

 

48-0

Bit map

M

 

b

8

 

48-4

Batch/sequence number

ME

 

n

10

 

49

Currency code, transaction

ME

 

an

3

 

53

Security Related Control Information

M

LL

b

..48

 

59

Transport data

ME

LLL

ans

..999

 

64

MAC

M

 

b

8

 

 

Tags:
Created by Kristian Lingsom on 2017/10/13 14:13