Maintenance Work Notice!

We will carry out maintenance work on this documentation on Tuesday, 15.06.2021 between 3 pm and 4 pm CEST. Thank you for your understanding.

Page tree

Search

Skip to end of metadata
Go to start of metadata


Terms and Definitions

Terms

Term

Definition

Transaction

A transaction consists of a number of linked messages. At its simplest a transaction will consist of a minimum of a request message and a response message.

Payment

A payment is the equivalent to a transaction in Paygate. During a payment lifecycle, the state of a transaction will change, depending on the performed action. These actions may include authorization, capture, sale, cancel and refund. A payment is thereby defined as a sequence of actions.

Action

An action is an operation that changes the status of a payment when performed successfully.


Definitions

Data formats

Format

Description

a

alphabetical

as

alphabetical with special characters

n

numeric

an

alphanumeric

ans

alphanumeric with special characters

ns

numeric with special characters

bool

boolean expression (true or false)

3

fixed length with 3 digits/characters

..3

variable length with maximum 3 digits/characters

enum

enumeration of allowed values

dttm

ISODateTime (YYYY-MM-DDThh:mm:ss)


Abbreviations

Abbreviation

Description

Comment

CND

condition


M

mandatory

If a parameter is mandatory, then it must be present

O

optional

If a parameter is optional, then it can be present, but it is not required

C

conditional

If a parameter is conditional, then there is a conditional rule which specifies whether it is mandatory or optional


Notice: Please note that the names of parameters can be returned in upper or lower case.


Schematic overview

The following block diagram provides a high level process overview.


Process narrative

(1) ECR submits estimated amount and a Reference Number via OPI message protocol to the POI device

(2) POI device performs cardholder authentication, encrypts the PIN block and the PAN with the Computop encryption key and forwards the authorization request via SSL through a central proxy server to CCV acCEPT

(3) CCV acCEPT routes the transaction to Computop Paygate via VPN connection

(4) Paygate submits authorization request to the acquirer

(5) Authorization result are transferred via notification request

Please note that authorization and notification are two distinct asynchronous processes.


Notification request

Computop Paygate will submit a notification request via HTTP POST in order to transfer the authorization status and transaction details to the server URL as stored in the merchant configuration.

The request will be sent in real-time. If no response Paygate will retry the notification once after 2 seconds of the first submission. In case that the retry fails Merchant System may actively request the status of the transaction once the system is available again.

Parameter

FormatConditionConfig

Description

MID

ans..30M

MerchantID, assigned by Computop

PayID

an32M

ID assigned by Paygate for the payment, e.g. for referencing in batch files

XID

an32M

ID for all single transactions (authorisation, capture, credit note) for one payment assigned by Paygate

TransIDans..64M
Unique transaction identifier supplied by CCV acCEPT
RefNrans..30M
Unique reference number
Statusa..50M

Payment status which can be either of the following:

•       AUTHORIZED

•       FAILED

•       OK (= Captured)

Descriptionans..1024M
Further details in the event that payment is rejected. Please do not use the Description but the Code parameter for the transaction status analysis! For automated payment processing please always use the code parameter.
Coden8M
Error code according to Paygate Response Codes (A4 Error codes)
MACan64M
Hash Message Authentication Code (HMAC) with SHA-256 algorithm
POSTerminalIDan..20M
Terminal Identification Number assigned and linked to a specific point-of-sale (POS) terminal
MessageTypen2M
Message Type describing the performed action: 01=Sale, 02=Reversal, 03=Credit
DMACKSNan..20M
Serial Number of the key (DUKPT) that was used to generate the DMAC
DMACan16M
Message Authentication Code
CodeExtan..10OXOriginal code from external payment system
AQa..5OXAcquirer
EMVDataan..2028OXEMV Data
CCNrn12..19OXCredit card number at least 12-digit, numerical without spaces
PCNrn16OXPaygate card token
CCBranda..22OXCredit card brand (e.g. Visa, MasterCard, Maestro etc.)
CCExpiryn6OXCard expiry date
MaskedPanan12..19M
Masked card number (6X4)
baseAmountn..10M
Amount in its smallest currency unit of merchant’s local currency at the Point of Sale (POS)
baseCurrencya3M
Merchant’s local currency at the Point of Sale (POS)
Amountn..10C
Amount in its smallest currency unit of card currency
Currencya3C
Cardholder’s currency
dccRateValueans13C
Applicable FX rate with 4 decimal places (e.g. ‘3.0245’)
schemeReferenceIDans..64C
Card scheme specific transaction ID required for subsequent credential-on-file payments, delayed authorizations and resubmssions.

Notice: The parameters baseAmount, baseCurrency, and dccRateValue will be only present when DCC was used. In this case the Amount and the Currency parameter correspond to the foreign values. For transaction that have been carried out without DCC the parameter Amount will refer to the amount in the merchant's local currency as given in the parameter Currency.


References

Paygate supports two external references, TransID and RefNr. For POS environments the parameter TransID holds a unique identifier from CCV acCEPT. Thus, the merchant may submit a unique reference via RefNr to Computop Paygate.

For reconciliation purposes, Computop maps the parameter RefNr against suitable elements in the corresponding acquirer protocol in order to make sure that values are shown in the electronic merchant statements (e.g. EPA file). As RefNr is an optional element, Computop automatically reverts to the TransID if RefNr is not given in the request message.

Merchant may transfer his Reference Number in the OPI protocol to the acCEPT server. CCV will map this element against the Paygate parameter RefNr.

Please note that acquirers do have different size limits for references that can be submitted depending on the message protocol and host capabilities.

Acquirer

Protocol

Size limit

ConCardis

GICC

30

JPMorgan Chase

ISO8583

22

American Express

GICC

30

AirPlusGICC30
WorldpayAPACS20


Status inquiry

In order to inquire about the status of a payment via a Server-to-Server connection, please use the following URL:


Notice: For security reasons, Paygate rejects all payment requests with formatting errors. Therefore, please use the correct data type for each parameter.

The following table describes the encrypted request parameters:

Parameter

Format

CND

Description

MerchantID

ans..30

M

MerchantID, assigned by Computop. Additionally this parameter has to be passed in plain language too.

RefNrans..30MMerchant’s unique reference number. Reference used at the Point of Sale (POS) 
MACan64MHash Message Authentication Code (HMAC) with SHA-256 algorithm

Parameters for status inquiries via socket connections


The following table describes the Paygate response parameters:

Parameter

FormatConditionConfig

Description

MID

ans..30M

MerchantID, assigned by Computop

PayID

an32M

ID assigned by Paygate for the payment, e.g. for referencing in batch files

Statusa..50M
OK or FAILED
Descriptionans..1024M
Further details in the event that payment is rejected. Please do not use the Description but the Code parameter for the transaction status analysis!
Coden8M
Error code according to Paygate Response Codes (A4 Error codes)
LastStatusan32M
Payment status which can be either of the following: AUTHORIZED, FAILED, CAPTURE_REQUEST, CREDIT_REQUEST, OK (=captured)
LastXCoden8OXResponse code of the most recent payment action
LastXAmountn..10OXAmount of the most recent payment action
XIDan32OXIdentifier of the most recent payment action assigned by Paygate
AmountAuthn..10M
Sum of authorized amounts
AmountCapn..10M
Sum of captured amounts
AmountCredn..10M
Sum of refunded amounts
CCNrn12..19OXCredit card number at least 12-digit, numerical without spaces
CCBranda..22OX

Credit card brand (e.g. Visa, MasterCard, Maestro etc.)

Returned only after configuration by Merchant Services (helpdesk@computop.com).

CCExpiryn6OXCard expiry date
MaskedPanan12..19M
Masked card number (6X4)
baseAmountn..10C
Amount in its smallest currency unit of merchant’s local currency at the Point of Sale (POS)
baseCurrencya3C
Merchant’s local currency at the Point of Sale (POS)
dccRateValueans13C
Applicable FX rate with 4 decimal places (e.g. ‘3.0245’)
schemeReferenceIDans..64C
Card scheme specific transaction ID required for subsequent credential-on-file payments, delayed authorizations and resubmssions.

Notice: The parameter baseAmount, baseCurrency and dccRateValue will be only present when DCC was used. In this case AmountAuth, AmountCap and AmountCred are given in the cardholder's currency. For transaction that have been carried out without DCC all Amounts refer the merchant's local currency.


Code Listings

Brands

Code

Brand

VISA

Visa

MasterCard

MasterCard

Maestro

Maestro

AMEXAmerican Express
DinersDiners Club
DiscoverDiscover
AirPlusAirPlus Corporate Accounts (UATP)

Acquirer

Code

Acquirer

CON

Concardis

CHASE

Chase Paymentech

AME

American Express

AIRAirPlus
WLPWorldpay