girocard e-commerce | Computop Documents

About girocard e-commerce

E-commerce payments with girocard are currently only possible via Apple Pay.

This page is describing solution for merchant's own decryption of Apple Pay payload (token) for recurring payments.

For standard Apple Pay integration (including Girocard), please refer to Apple Pay documentation.

Paygate interface: via Server-to-Server

Definitions

Data formats

Format

Description

alphabetical

alphabetical with special characters

numeric

alphanumeric

ans

alphanumeric with special characters

numeric with special characters

bool

boolean expression (true or false)

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

mandatory

If a parameter is mandatory, then it must be present

optional

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

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.

Request elements

In order to start a server-to-server girocard e-commerce payment, please use the following URL:

https://www.computop-paygate.com/girocard.aspx

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

The following table describes the encrypted payment request parameters:

Key

Format

CND

Description

MerchantID

ans..30

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

msgver

ans..5

Computop Paygate Message version. Valid values:

Value

Description

2.0

With 3-D Secure 2.x a lot of additional data were required (e.g. browser-information, billing/shipping-address, account-info, ...) to improve authentication processing. To handle these information the JSON-objects have been put in place to handle such data. To indicate that these data are used the MsgVer has been implemented.

TransID

ans..64

TransactionID provided by you which should be unique for each payment

RefNr

ans..30

Merchant’s unique reference number, which serves as payout reference in the acquirer EPA file. Please note, without the own shop reference delivery you cannot read out the EPA transaction and regarding the additional Computop settlement file (CTSF) we cannot add the additional payment data.

Amount

n..10

Amount in the smallest currency unit (e.g. EUR Cent). Please contact the Computop Helpdesk, if you want to capture amounts <100 (smallest currency unit).

Currency

Currency, three digits DIN / ISO 4217, e.g. EUR, USD, GBP. Please find an overview here: A1 Currency table

MAC

an64

Hash Message Authentication Code (HMAC) with SHA-256 algorithm. Details can be found here:

UserData

ans..1024

If specified at request, Paygate forwards the parameter with the payment result to the shop.

OrderDesc

ans..768

Description of goods and prices. Intended purpose on the statement of account.

card

JSON

Card data, brand=girocard

Capture

an..6

Determines the type and time of capture.

Capture Mode

Description

AUTO

Capturing immediately after authorisation (default value).

MANUAL

Capturing made by the merchant. Capture is normally initiated at time of delivery.

Delay in hours until the capture (whole number; 1 to 696).

channel

a..20

Indicates the type of channel interface being used to initiate the transaction. Values accepted:

WEBSITE
MOBILE_APP

credentialOnFile

JSON

Object specifying type and series of transactions using payment account credentials (e.g. account number or payment token) that is stored by a merchant to process future purchases for a customer. Required if applicable.

tokenData

JSON

Token Data, structure: see below

MerchantIDExt

ans..128

Apple Merchant Identifier

Parameters for girocard e-commerce payment

Response elements

The following table describes the result parameters with which the Computop Paygate responds to your system

pls. be prepared to receive additional parameters at any time and do not check the order of parameters

the key (e.g. MerchantId, RefNr) should not be checked case-sentive

Key	Format	CND	Description
mid	ans..30	M	MerchantID, assigned by Computop
PayID	an32	M	ID assigned by Paygate for the payment, e.g. for referencing in batch files as well as for capture or credit request.
XID	an32	M	ID for all single transactions (authorisation, capture, credit note) for one payment assigned by Paygate
TransID	ans..64	M	TransactionID provided by you which should be unique for each payment
Code	an8	M	Error code according to Paygate Response Codes (A4 Error codes)
Status	a..20	M	Status of the transaction. Values accepted: AUTHORIZED FAILED
Description	ans..1024	M	Further details in the event that payment is rejected. Please do not use the Description but the Code parameter for the transaction status analysis!
UserData	ans..1024	O	If specified at request, Paygate forwards the parameter with the payment result to the shop.
MAC	an64	M	Hash Message Authentication Code (HMAC) with SHA-256 algorithm. Details can be found here: HMAC Authentication (Request) HMAC Authentication (Notify)

Key

Format

CND

Description

mid

ans..30

MerchantID, assigned by Computop

PayID

an32

ID assigned by Paygate for the payment, e.g. for referencing in batch files as well as for capture or credit request.

XID

an32

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

TransID

ans..64

TransactionID provided by you which should be unique for each payment

Code

an8

Error code according to Paygate Response Codes (A4 Error codes)

Status

a..20

Status of the transaction.

Values accepted:

AUTHORIZED
FAILED

Description

ans..1024

Further details in the event that payment is rejected. Please do not use the Description but the Code parameter for the transaction status analysis!

UserData

ans..1024

If specified at request, Paygate forwards the parameter with the payment result to the shop.

MAC

an64

Hash Message Authentication Code (HMAC) with SHA-256 algorithm. Details can be found here:

Response parameters for girocard e-commerce payments

JSON object tokenData

Key

Format

CND

Description

tokenCryptogram

string

Cryptogram as received from Tokenization Service.

eci

string

Payment system specific Electronic Commerce Indicator.

For MasterCard, if not received in payload, use value "2".

tokenRequestor

string

Token Requestor. Possible values:

applePay
googlePay
merchantTokenization

tokenRequestorID

string

Token Requestor ID assigned by the card scheme.

Required for MasterCard merchant tokenization.

Schema

BASEURL= https://www.computop-paygate.com/schemas

1
{
2
    "$schema": "http://json-schema.org/draft-07/schema#",
3
    "$id": "BASEURL/tokenData.json",
4
    "title": "tokenData",
5
    "description": "Token Data",
6
    "type": "object",
7
    "properties": {
8
        "tokenCryptogram": {
9
            "type": "string",
10
            "description": "Token cryptogram."
11
        },
12
        "eci": {
13
            "type": "string",
14
            "description": "Electronic Commerce Indicator."
15
        },
16
        "tokenRequestor": {
17
            "type": "string",
18
            "description": "Token requestor."
19
        },
20
        "tokenRequestorID": {
21
            "type": "string",
22
            "description": "Token requestor ID."
23
        }
24
    },
25
    "required": ["tokenCryptogram", "tokenRequestor, "eci"],
26
    "additionalProperties": false
27
}

Sample

1
{
2
    "tokenCryptogram": "YwAAErsAAcll8GEDuiS4gFlgAgA=",
3
    "eci": "7",
4
    "tokenRequestor": "merchantTokenization",
5
    "tokenRequestorID": "50129390584"
6
}

Recurring payments

Girocard e-commerce offers the possibility of recurring payments, which must always reference initial payment done via Apple Pay.

These recurring payments are not online authorized with the issuing bank, but only included in the clearing file.

Please note, that since there is no online authorization (validation) at the time of recurring payment, the account might not have enough funds or might not exist.

Request elements

In order to start a server-to-server girocard e-commerce payment, please use the following URL:

https://www.computop-paygate.com/girocard.aspx

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

The following table describes the encrypted payment request parameters:

Key

Format

CND

Description

MerchantID

ans..30

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

msgver

ans..5

Computop Paygate Message version. Valid values:

Value

Description

2.0

TransID

ans..64

TransactionID provided by you which should be unique for each payment

RefNr

ans..30

Amount

n..10

Amount in the smallest currency unit (e.g. EUR Cent). Please contact the Computop Helpdesk, if you want to capture amounts <100 (smallest currency unit).

Currency

Currency, three digits DIN / ISO 4217, e.g. EUR, USD, GBP. Please find an overview here: A1 Currency table

MAC

an64

Hash Message Authentication Code (HMAC) with SHA-256 algorithm. Details can be found here:

UserData

ans..1024

If specified at request, Paygate forwards the parameter with the payment result to the shop.

OrderDesc

ans..768

Description of goods and prices. Intended purpose on the statement of account.

Capture

an..6

Determines the type and time of capture.

Capture Mode

Description

AUTO

Capturing immediately after authorisation (default value).

MANUAL

Capturing made by the merchant. Capture is normally initiated at time of delivery.

Delay in hours until the capture (whole number; 1 to 696).

credentialOnFile

JSON

Object specifying type and series of transactions using payment account credentials (e.g. account number or payment token) that is stored by a merchant to process future purchases for a customer.

Please note that only type : recurring, initial payment : false is allowed to be sent.

InitialPayID

an32

PayID received in Paygate response from initial Girocard Apple Pay payment.

Parameters for recurring payments

Response elements

The following table describes the result parameters with which the Computop Paygate responds to your system

pls. be prepared to receive additional parameters at any time and do not check the order of parameters

the key (e.g. MerchantId, RefNr) should not be checked case-sentive

Key	Format	CND	Description
mid	ans..30	M	MerchantID, assigned by Computop
PayID	an32	M	ID assigned by Paygate for the payment, e.g. for referencing in batch files as well as for capture or credit request.
XID	an32	M	ID for all single transactions (authorisation, capture, credit note) for one payment assigned by Paygate
TransID	ans..64	M	TransactionID provided by you which should be unique for each payment
Code	an8	M	Error code according to Paygate Response Codes (A4 Error codes)
Status	a..20	M	Status of the transaction. Values accepted: AUTHORIZED FAILED
Description	ans..1024	M	Further details in the event that payment is rejected. Please do not use the Description but the Code parameter for the transaction status analysis!
UserData	ans..1024	O	If specified at request, Paygate forwards the parameter with the payment result to the shop.
MAC	an64	M	Hash Message Authentication Code (HMAC) with SHA-256 algorithm. Details can be found here: HMAC Authentication (Request) HMAC Authentication (Notify)

Key

Format

CND

Description

mid

ans..30

MerchantID, assigned by Computop

PayID

an32

ID assigned by Paygate for the payment, e.g. for referencing in batch files as well as for capture or credit request.

XID

an32

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

TransID

ans..64

TransactionID provided by you which should be unique for each payment

Code

an8

Error code according to Paygate Response Codes (A4 Error codes)

Status

a..20

Status of the transaction.

Values accepted:

AUTHORIZED
FAILED

Description

ans..1024

Further details in the event that payment is rejected. Please do not use the Description but the Code parameter for the transaction status analysis!

UserData

ans..1024

If specified at request, Paygate forwards the parameter with the payment result to the shop.

MAC

an64

Hash Message Authentication Code (HMAC) with SHA-256 algorithm. Details can be found here:

Response parameters for recurring payments