Search

Skip to end of metadata
Go to start of metadata


About Gothia PayByBill

General information about PayByBill

With PayByBill from the Gothia Financial Group you can offer your customers popular methods of payment such as direct debit, purchase on invoice or flexible hire purchase. PayByBill enables merchants to send their own invoice. At the same time merchants will receive payments. PayByBill takes care of the debt collection.


Logo

Info

PayByBill enables merchants to offer payment methods such as invoice purchasing, financing and direct debit. The solution offers merchants a payment guarantee and is available for Denmark, Germany, Finland, the Netherlands, Norway and Sweden.

TypePayments by Cash-In / Bill


Further information can be found on the webpage of PayByBill (www.paybybill.com/de).

 

Process flow charts


Process flow PayByBill



Process flow PayByBill instalment payment


Paygate interface

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.


PayByBill purchase on invoice and hire purchase

This chapter describes how to reserve a PayByBill payment. Following successful reservation you can capture PayByBill payments or if necessary credit them. Merchants can also cancel PayByBill reservations.

In order to execute a PayByBill payment via server-to-server communication, please go to 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 payment 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.

TransID

ans..64

M

TransactionID which should be unique for each payment

RefNr

ans..30

O

Unique reference number

Amount

n..10

M

Amount in the smallest currency unit (e.g. EUR Cent)

Please contact the helpdesk, if you want to capture amounts < 100 (smallest currency unit).

Currency

a3

M

Currency, three digits DIN / ISO 4217

MAC

an64

M

Hash Message Authentication Code (HMAC) with SHA-256 algorithm

UserData

ans..1024

O

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

PayType

ans..16

M

Payment type: “Invoice” or “DirectDebet”. “DirectDebet” is permitted in Germany only. In case of hire purchase via Germany only ‘DirectDebet’ is allowed.

FirstName

ans..30

M

First name of the custumer

LastName

ans..30

M

Last name of the customer or company name

AddrStreet

ans..128

M

Customer’s street

AddrHouseNr

ans..5

O

Customer’s street number

AddrZipCode

ans..15

M

Postcode of the customer

AddrCity

ans..30

M

Customer’s place of residence

AddrCountryCode

a2

M

Country code of the customer's residence, 2 characters according to ISO 3166.

BirthDate

ans..10

OC

Obligatory if AddrCountryCode=DE: Date of birth in the format YYYY-MM-DD

SocialSecurityNumber

ans..20

OC

Obligatory if AddrCountryCode=DE: Social security number if CompanyOrPerson=P. Register of Companies number if CompanyOrPerson=C.


Country-specific formats

SE: DDMMYYNNNN

NO: DDMMYYNNNNN

DK: DDMMYY-NNNN

FI: DDMMYY-NNNN

NL: DDMMYYYY

Email

ans..100

M

Email address of the customer

Phone

ans..20

O

Customer’s phone number

MobileNo

ans..16

O

Customer’s mobile telephone number

AccIBAN

n8

OC

Obligatory if PayType=DirectDebet: Identification of the financial institution of the account holder

AccNr

n..11

OC

Obligatory if PayType=DirectDebet: account holder’s account number

CustomerID

ans..50

M

Customer number at the merchant

CompanyOrPerson

a1

O

P=Person (standard), C=Company

Salutation

ans..10

O

Salutation – ‘Mr’, ‘Mrs’, ‘Miss’

Title

ans..20

O

Title, e.g. Dr. or Prof.

DistributionType

ans..8

O

Method of dispatch of the invoice: ‘paper’ or by ‘email’

DistributionBy

ans..8

O

Sender of the printed invoice. ‘Company’ for Gothia; ‘Client’ if the merchant is the sender.

In case of hire purchase

EventToken

a2

M

1. call: “IP” for Instalment Purchase (to request the terms & conditions and AcceptID)

2. call: “AT” for AcceptAccountTermsAndConditions (to confirm the terms & conditions)

Month

n..2

M

Number of instalments

ProductNr

ans..4

O

Account profile number, as configured with Gothia, e.g. ‘1’

PayID

an32

OC

Obligatory on second call: Paygate ID for the identification of a payment

Parameters for payments with PayByBill


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

Parameter

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.

XID

an32

M

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

TransID

ans..64

M

Merchant’s transaction number

Status

a..50

M

OK or FAILED. AUTHORIZE_REQUEST on first call with EventToken=IP

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!

Code

n8

M

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

RefNr

ns..30

O

Merchant’s unique reference number

UserData

ans..1024

O

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

CodeExt

n..10

O

Error code from PayByBill, if agreed with Computop Support

ErrorText

ans..1024

O

Error text from PayByBill, if agreed with Computop Support

InstallmentData

ans..1024

O

Installment plan

InstallmentData=<Month>;<PaymentAmount>;

<CapitalBalance>;<Fees>;<Interest>+ <Month>;<PaymentAmount>; …

TermsAndConditions

ans..1024

O

Terms & conditions for payment by instalment

FirstName

ans..128

O

First name

LastName

ans..128

O

Last name

AddrStreet

ans..255

O

Street and street number in the delivery address

AddrZip

ans..20

O

Postcode in the delivery address

AddrCity

ans..50

O

Town/city in the delivery address

InvoiceText

ans..1024

O

Access data for the instalment payment portal and the minimum instalment amount for the product plus invoice information.

Example:

InvoiceText=<minimum rate amount>;<Text>;<account number>;<password>;<LogonText>;<OCR number>

Result parameters for PayByBill payments



Capture

Captures are possible via a Server-to-Server connection. To settle an invoice / carry out dispatch by PayByBill 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 payment 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.

PayID

an32

M

ID assigned by Paygate for the payment to be captured

TransID

ans..64

M

ID assigned by Merchant for the payment process to be captured

Amount

n..10

M

Amount in the smallest currency unit (e.g. EUR Cent)

Please contact the helpdesk, if you want to capture amounts < 100 (smallest currency unit).

Currency

a..3

M

Currency, three digits DIN / ISO 4217

RefNr

ns..30

O

Reference number of merchant (e.g. invoice number)

MAC

an64

M

Hash Message Authentication Code (HMAC) with SHA-256 algorithm

ReqIDans..32OTo avoid double payments, enter an alphanumeric value which identifies your transaction and may be assigned only once. If the transaction is submitted again with the same ReqID, Paygate will not carry out the payment, but will just return the status of the original transaction. Please note that the Paygate must have a finalized transaction status for the first initial action. Submissions with identical ReqID for an open status will be processed regularly.

InvoiceNr

ans..16

M

unique reference number

ProductNr

ans..4

O

Account profile number, as configured with Gothia, e.g. ‘1’

ArticleList

ans..1024

M

Article list with description of items and prices:

<Article number> ;<quantity> ;<article description> ;<net price> ;<gross price> ;<VAT> ;<tax rate>; <unit>

<;> separates the fields of an article data set
<+> separates the article data sets

Data type (size):

Article number (ans..100)

Quantity (n..3)

Article description (ans..100)

Net amount (n..10) in the smallest currency unit (e.g. EUR Cent)

Gross amount (n..10) in the smallest currency unit (e.g. EUR Cent)

VAT amount (n..10) in the smallest currency unit (e.g. EUR Cent)

VAT rate (n..2), e.g. 19 for 19%

unit (ans..50), e.g. kg for kilogram, or l for litre

BDStreet

ans..100

M

Street name in the invoicing address

BDHouseNr

ans..5

O

Street number in the invoicing address

BDCity

ans..100

M

Town/city in the invoicing address

BDCountryCode

a2

M

Country code for the invoicing address, 2 characters according to ISO 3166

BDZipCode

ans..8

M

Postcode in the invoicing address

DueDate

n8

O

Due date in the format DDMMYYYY

InvoiceDate

n8

O

Invoice date in the format DDMMYYYY:

TxAmount

n..10

O

Tax amount of the entire order in the smallest currency unit (e.g. EUR Cent).

Please contact the helpdesk, if you want to capture amounts < 100 (smallest currency unit).

NetAmount

n..10

O

Net amount in the smallest currency unit (e.g. EUR Cent)

Please contact the helpdesk, if you want to capture amounts < 100 (smallest currency unit).

Parameters for PayByBill captures


The following table describes the Paygate response parameters:

Parameter

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

XID

an32

M

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

TransID

ans..64

M

Merchant transaction number, which must be unique

Status

a..50

M

OK or 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!

Code

n8

M

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

RefNr

ns..30

O

Merchant’s unique reference number

Reference

ans..16

O

Reference number for PayByBill (OCR number)

DocumentLink

ans..1024

O

Link to PDF document of the invoice

InvoiceText

ans..1024

O

Access data for the instalment payment portal and the minimum instalment amount for the product plus invoice information.


Example:

InvoiceText=<minimum rate amount>;<Text>;<account number>;<password>;<LogonText>;<OCR number>

File

ans..1024

O

Instalment payment contract as PDF document: Base64 encrypted data string

CodeExt

n..10

O

Error code from PayByBill, if agreed with Computop Support

ErrorText

ans..256

O

Error text from PayByBill, if agreed with Computop Support

Result parameters for PayByBill captures



Credit with reference and partial credit

Credits (refunds) are possible via a Server-to-Server connection. For a Credit with reference to a capture the amount of the Credit is limited to the amount of the previous capture. To carry out a credit with a reference transaction (returns via PayByBill), 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 payment 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.

PayID

an32

M

ID assigned by Paygate for the payment to be credited

TransID

ans..64

M

ID assigned by Merchant for the payment process to be credited

Amount

n..10

M

Amount in the smallest currency unit (e.g. EUR Cent)

Please contact the helpdesk, if you want to capture amounts < 100 (smallest currency unit).

Currency

a..3

M

Currency, three digits DIN / ISO 4217

RefNr

ns..30

O

Reference number of merchant (e.g. invoice number)

MAC

an64

M

Hash Message Authentication Code (HMAC) with SHA-256 algorithm

ReqIDans..32OTo avoid double payments, enter an alphanumeric value which identifies your transaction and may be assigned only once. If the transaction is submitted again with the same ReqID, Paygate will not carry out the payment, but will just return the status of the original transaction. Please note that the Paygate must have a finalized transaction status for the first initial action. Submissions with identical ReqID for an open status will be processed regularly.

InvoiceNr

ans..16

M

Number of invoice as reference for the refund

ArticleList

ans..1024

M

Article list with description of items and prices:

<Article number> ;<quantity> ;<article description> ;<net price> ;<gross price> ;<VAT> ;<tax rate>; <unit>

<;> separates the fields of an article data set
<+> separates the article data sets

Data type (size):

Article number (ans..100)

Quantity (n..3)

Article description (ans..100)

Net amount (n..10) in the smallest currency unit (e.g. EUR Cent)

Gross amount (n..10) in the smallest currency unit (e.g. EUR Cent)

VAT amount (n..10) in the smallest currency unit (e.g. EUR Cent)

VAT rate (n..2), e.g. 19 for 19%

unit (ans..50), e.g. kg for kilogram, or l for litre

TxAmount

n..10

O

Tax amount of the entire order in the smallest currency unit (e.g. EUR Cent).

Please contact the helpdesk, if you want to capture amounts < 100 (smallest currency unit).

NetAmount

n..10

O

Net amount in the smallest currency unit (e.g. EUR Cent)

Please contact the helpdesk, if you want to capture amounts < 100 (smallest currency unit).

Parameters for PayByBill credits


The following table describes the Paygate response parameters:

Parameter

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

XID

an32

M

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

TransID

ans..64

M

Merchant transaction number, which must be unique

Status

a..50

M

OK or 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!

Code

n8

M

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

RefNr

ns..30

O

Reference number of merchant (e.g. invoice number)

Reference

ans..16

O

Reference number for PayByBill

CodeExt

n..10

O

Error code from PayByBill, if agreed with Computop Support

ErrorText

ans..256

O

Error text from PayByBill, if agreed with Computop Support

Result parameters for PayByBill credits



Reversal and Updating

To reverse a payment with PayByBill, go to 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 payment 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.

PayID

an32

M

ID assigned by Paygate for the payment to be reverted

TransID

ans..64

M

Merchant ID for the identification of the payment process to be reversed

RefNr

ns..30

O

Reference number of merchant (e.g. invoice number)

Amount

n..10

M

Amount in the smallest currency unit (e.g. EUR Cent)

Please contact the helpdesk, if you want to capture amounts < 100 (smallest currency unit).

Currency

a..3

M

Currency, three digits DIN / ISO 4217

MAC

an64

M

Hash Message Authentication Code (HMAC) with SHA-256 algorithm

ReqIDans..32OTo avoid double payments, enter an alphanumeric value which identifies your transaction and may be assigned only once. If the transaction is submitted again with the same ReqID, Paygate will not carry out the payment, but will just return the status of the original transaction. Please note that the Paygate must have a finalized transaction status for the first initial action. Submissions with identical ReqID for an open status will be processed regularly.

Parameters for reversals of PayByBill payments


The following table describes the Paygate response parameters:

Parameter

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

XID

an32

M

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

TransID

ans..64

M

Merchant transaction number, which must be unique

Status

a..50

M

OK or 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!

Code

n8

M

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

RefNr

ns..30

O

Reference number of merchant (e.g. invoice number)

CodeExt

n..10

O

Error code from PayByBill, if agreed with Computop Support

ErrorText

ans..256

O

Error text from PayByBill, if agreed with Computop Support

Result parameters for PayByBill reversals



Batch processing via the interface

Basic information about using Batch files and about their structure can be found in the Batch Manager manual. Within batch processing not alle functions are available which are usually available for the online interface.

This section describes the parameters which must be transferred within the data set (Record) for executing a PayByBill payment and which information can be found within the response file about the payment status. You can only cancel in full.

Following table gives an overview of all batch versions that are possible for a specific action and their specialities:

Action

Version

Description

Reverse

1.0 / 2.0

Standard version without return of parameter Code

 

1.x / 2.x

with RefNr (valid for all versions other than 1.0)

Description of the possible batch versions


The structure for a PayByBill payment within a Batch file to be submitted is the following:

HEAD,<MerchantID>,<Date>,<Version>

PayByBill,Reverse,<Amount>,<Currency>,<TransID>,(<RefNr>,)<PayID>

FOOT,<CountRecords>,<SumAmount>


Example for Master MID Funktion:

HEAD,[Master]MerchantID,Date,2.x
Type,Action,[Slave]MID,Amount,Currency,TransID,Data (depends on Action)
FOOT,CountRecords,SumAmount


The following table describes the individual fields and values used within the data set (record) in the batch file:

Parameter

Format

CND

Description

Type

a..11

M

HEAD for Header, FOOT for Footer, PayByBill for PayByBill

Action

a..20

M

The parameter Action defines the type of transaction:

Reverse (cancellation)

Amount

n..10

M

Amount in the smallest currency unit (e.g. EUR Cent)

Please contact the helpdesk, if you want to capture amounts < 100 (smallest currency unit).

Currency

a3

M

Currency code, three digits DIN / ISO 4217

TransID

ans..64

M

TransactionID which should be unique for each payment

RefNr

ns..30

O

Unique reference number

PayID

an32

M

ID for this transaction given by Paygate

Description of fields within the record for Batch files

 

The record area within the response file for Batch transactions looks the following way:

HEAD,<MerchantID>,<Date>,<Version>

PayByBill,Reverse,<Amount>,<Currency>,<TransID>,(<RefNr>,)<PayID>,<Status>,<Code>

FOOT,<CountRecords>,<SumAmount>

 

The following table describes the response parameters which the Batch Manager saves in the Record area for each transaction (standard parameters not explained here, such as <TransID> or <RefNR> and request parameters are returned unchanged and correspond to the call as specified before):

Parameter

Format

CND

Description

Action

a..20

M

The parameter Action defines the type of transaction:

Reverse (cancellation)

PayID

an32

M

ID for this transaction given by Paygate

Status

a..50

M

OK or FAILED

Code

n8

M

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

Description of result parameters within the record for Batch files