Introduction and Prerequisites

Use your web-based ERP or shop system to accept card payments in stationery businesses. The communication of your terminals at the point of sale occurs via the Internet directly through and makes traditional interfaces such as OPI or ZVT superfluous.

Process diagram




interface


Calling the interface for POS – Cloud POS Interface

In order to use the Cloud POS Interface, please use the following URL:

catpos.aspx


Key

Format

CND

Description

MessageType

an2

M

Defines the type of payment:

Supported values are:

  • 01 - Sale
  • 02 - Reverse
  • 03 - Credit
  • 05 - Authorization/Reservation
  • 0B - Capture
  • 0C - Card Read
  • 0D - Diagnose
  • A1 - Terminal Startup

CardReadMode

ans..10

C

Defines the technology to be used to read the card. Valid values are

  • msr
    Required for MessageType=0C (CardRead)

Key

Format

CND

Description

RefNr

ans..21

O

Merchant reference number

POSTerminalID

an..20

M

TerminalID of pin entry device

Printer

an1

M

Possible values that the merchant POS application can send are:

1 - Printer is ready

0 - Printer is not ready

Should be populated with 1 (further clarifications are in progress for usage of value 0)

Key

Format

CND

Description

localDate

n8

M

Transaction date: YYYYMMDD

localTime

n6

M

Transaction time: hhmmss

TraceNr

ans8

C

Mandatory for subsequent functions Reversal or Capture (MessageType=02/08).

It must be equal to the value TraceNr received from the original authorization response.

Merchant POS system must provide this in the request.

AppCode

ans6

C

Mandatory for subsequent function Capture (MessageType=08).

It must be equal to the value Approvalcode received from the original authorization response.

Merchant POS system must provide this in the request.

RTF

a1

O

Host protocol specific – COF: RTF parameter.
Possible values: I or E

ContractID

n..12

O

Special merchant ID at the acquirer to overrule the default merchant ID

Parameters for payments with POS – Cloud POS Interface


(Note: List of parameters in response may differ based on the Cloud POS Interface function called and the final POS transaction result.)

Key

Format

CND

Description

RefNr

ans..21

O
Merchant reference number
Description

ans..1024

M
Further details in the event that payment is rejected. Please do not use the Description but the CATCode parameter for the transaction status analysis!
CATCodeans3MCode from the POS Server or POS device
MaskedPANan12..19C

Masked card number (6X4).

Only in case of successful credit card transactions.

BankAccountan64CMasked Bank account number for EC transactions
additionalresponsedataan..128OAdditional text which the operator’s processing system can send optionally in replies to payment/cutover requests.
Approvalcodeans6C

Approval code from authorization host in the response message to the client.

Only in case of successful credit card transactions.

Merchant must save this value form the response and use it when referencing Capture subsequent action.

CCSeqNrn3OCard sequence number
Brandan..22OBrand: VISA, MasterCard, Maestro, AMEX, DINERS, JCB, CUP
CodeExtn3CFinancial transaction Authorization Host response code (Payment).
TraceNrans8CMerchant must save this value form the response and use it when referencing subsequent actions i.e Reverse, Capture
VUNrn8OAcquirer Contract ID number on which the transaction was processed
ReceiptobjectCReceipt content for the Merchant and the cardholder. The information should be than used from Merchant Printer system to print out the respective receipts.
ReceiptNran..10OReceipt Number
schemeReferenceID / TransactionIDan..22OUnique transaction identifier provided by Schemes/Issuer to reference the transaction in MIT or COF scenarios
dccForeignAmountn..10OOnly when DCC was performed
dccCommissionans..7OOnly when DCC was performed
dccForeignCurrencyCoden..4OOnly when DCC was performed
dccDisclaimer (new Param)ans..1024OOnly when DCC was performed
dccMarginans..5OOnly when DCC was performed
dccRateValuen..13OOnly when DCC was performed
dccSourceans..32OOnly when DCC was performed
dccTimestampans..20OOnly when DCC was performed
ExpiryDaten..6OYYYYMM. Only when DCC was performed

Key

Format

CND

Description

VerificationCode

an..40

O
Used authentication mode. Possible values:
  • Signature
  • PIN
  • On consumer device
  • NoAuth
PayID

an..32

O

PayID of the respective payment completed and linked with this CPI command

aidParameters

ans..1024

O
Authorisation parameters: if these are present, the authorisation parameters must be printed out on the terminal receipt in unpacked form as 10 hexadecimal numbers. Aid-parameters can contain up to 130 characters for electronic cash payments.
localDate

n..8

O
Transaction date: YYYYMMDD
localTime

n..6

O
Transaction time: hhmmss
RTF

a1

O
Echoed from the request parameter
ContractID

n..12

O
Echoed from the request parameter
POSTerminalId

an..20

O
Echoed from the request parameter
TerminalID

an..12

O
Terminal ID which is forwarded towards acquirer authorization host

Result parameters for payments with POS – Cloud POS Interface


JSON Object (Receipt)

Please note that the data within this JSON object is encoded using ISO-8859-1 in contrast to the standard encoding of JSON objects with UTF-8 and then must be also Base64 encoded. This applies in particular to special characters such as "Umlaute" and diactrics.

"receipt"

Key

Format

CND

Description

receiptCopies

integer

O

Number of receipt copies to be printed 

receiptCustomer

string

O

Customer receipt data

receiptMerchant

string

O

Merchant receipt data

receiptNumber

integer

O

Receipt number


JSON Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "http://json-schema.org/draft-07/schema#",
  "title": "receipt",
  "description": "Data containing the receipt information which can be printed out by the merchant system",
  "type": "object",
  "properties": {
    "receiptMerchant": {
      "type": "string",
      "description": "Merchant Receipt data"
    },
    "receiptCustomer": {
      "type": "string",
      "description": "Customer Receipt data"
    },
    "receiptCopies": {
      "type": "integer",
      "description": "Number of receipt copies to be printed"
    },
    "receiptNumber": {
      "type": "integer",
      "description": "Receipt Number "
    },
      
  },
  "additionalProperties": false
}