Table of Contents |
---|
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.
Page properties | ||||||||
---|---|---|---|---|---|---|---|---|
|
Further information can be found on the webpage of PayByBill (www.paybybill.com/de).
Process flow charts
Process flow PayByBill
Multiexcerpt | ||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||
|
Process flow PayByBill instalment payment
Paygate interface
Multiexcerpt |
---|
|
|
|
|
|
|
Process flow PayByBill installment payment
Multiexcerpt include | ||||||
---|---|---|---|---|---|---|
|
Multiexcerpt include | ||||||
---|---|---|---|---|---|---|
|
PayByBill purchase on invoice and hire purchase
This chapter describes how
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 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.
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
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
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
|
Multiexcerpt include SpaceWithExcerpt EN MultiExcerptName Request_Intro PageWithExcerpt Reuse API
Table Filter | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Parameters for payments with PayByBill
Multiexcerpt include SpaceWithExcerpt EN MultiExcerptName Response_Intro PageWithExcerpt Reuse API
Table Filter | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
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:
|
Multiexcerpt include SpaceWithExcerpt EN MultiExcerptName Request_Intro PageWithExcerpt Reuse API
Table Filter | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Parameters for PayByBill captures
Multiexcerpt include SpaceWithExcerpt EN MultiExcerptName Response_Intro PageWithExcerpt Reuse API
Table Filter | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
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:
|
Multiexcerpt include SpaceWithExcerpt EN MultiExcerptName Request_Intro PageWithExcerpt Reuse API
Table Filter | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Parameters for PayByBill credits
Multiexcerpt include SpaceWithExcerpt EN MultiExcerptName Response_Intro PageWithExcerpt Reuse API
Table Filter | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Result parameters for PayByBill credits
Reversal and Updating
To reverse a payment with PayByBill, please use the following URL:
|
Multiexcerpt include SpaceWithExcerpt EN MultiExcerptName Request_Intro PageWithExcerpt Reuse API
Table Filter | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Parameters for reversals of PayByBill payments
Multiexcerpt include SpaceWithExcerpt EN MultiExcerptName Response_Intro PageWithExcerpt Reuse API
Table Filter | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
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:
Table Filter | ||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||||||||||||||||||
|
Description of the possible batch versions
The structure for a PayByBill payment within a Batch file to be submitted is the following:
Multiexcerpt | |||||
---|---|---|---|---|---|
| |||||
|
Example for Master MID function:
Multiexcerpt | |||||
---|---|---|---|---|---|
| |||||
|
The following table describes the individual fields and values used within the data set (record) in the batch file:
Table Filter | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Description of fields within the record for Batch files
The record area within the response file for Batch transactions looks the following way:
Multiexcerpt | |||||
---|---|---|---|---|---|
| |||||
|
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):
Table Filter | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
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
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
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:
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
Description of result parameters within the record for Batch files