Payment processing via Server-to-Server
If you wish to design your own forms for entering the payment data you can process your transactions in the background via a Server-to-Server connection. In this case your system saves payment details such as credit card numbers or bank account details and then creates a TLS socket-connection to the
Multiexcerpt include | ||||||
---|---|---|---|---|---|---|
|
Multiexcerpt include | ||||||
---|---|---|---|---|---|---|
|
Multiexcerpt include | ||||||
---|---|---|---|---|---|---|
|
Process of a Server-to-Server payment
Notice: Please note that captures, credits and status inquiries are possible only via the Server-to-Server connection or via Batch.
Payment processing via Batch
Batch Manager lets you transmit payment transactions in the form of files. In this process you assemble transaction data such as the transaction ID, amount and currency in a batch file which you will later transmit to
Multiexcerpt include | ||||||
---|---|---|---|---|---|---|
|
Multiexcerpt include | ||||||
---|---|---|---|---|---|---|
|
Security: Payment Card Industry Data Security Standard (PCI DSS)
Where the credit card data is entered and stored is vital for the security of the credit card payments on the Internet. The card organisations have established a security program with the PCI security authorisation (Payment Card Industry) in order to guarantee the secure storage of credit card data. Please note that participation in PCI is compulsory and subject to a charge if you store credit card data. The key factor in this is the Merchant Interface variant:
1) Multiexcerpt includeSpaceWithExcerpt EN MultiExcerptName Platform-Kurz PageWithExcerpt Wording
HTML form
SpaceWithExcerpt | EN |
---|---|
MultiExcerptName | Platform-Kurz |
PageWithExcerpt | Wording |
In this case the credit card data is only saved on the secure
Multiexcerpt include | ||||||
---|---|---|---|---|---|---|
|
Multiexcerpt include | ||||||
---|---|---|---|---|---|---|
|
2) Server-to-Server payment
Credit card data is saved on your systems. Therefore you are obliged under certain circumstances to undergo the MasterCard and VISA PCI Data Security program which is associated with annual authorisation costs and time. You can obtain further details from your credit card acquirer.
Notice: Please note that Visa and MasterCard have established strict security regulations for the protection of credit card data. Anyone who saves credit card numbers on their system or even only transmits such data must undergo –at their own expense - regular security authorisation. You should therefore use the
Multiexcerpt include | ||||||
---|---|---|---|---|---|---|
|
Multiexcerpt include | ||||||
---|---|---|---|---|---|---|
|
3) Batch
Payment data can be submitted as Batch file to
Multiexcerpt include | ||||||
---|---|---|---|---|---|---|
|
Multiexcerpt include | ||||||
---|---|---|---|---|---|---|
|
4) PayNow – the Silent Mode
With the PayNow solution the customer enters the data analogue as for the Server-to-Server solution but with the essential difference, that credit card data are transferred directly from the browser (client) to
Multiexcerpt include | ||||||
---|---|---|---|---|---|---|
|
Principles of Multiexcerpt includeSpaceWithExcerpt EN MultiExcerptName Platform-Kurz PageWithExcerpt Wording
programming
SpaceWithExcerpt | EN |
---|---|
MultiExcerptName | Platform-Kurz |
PageWithExcerpt | Wording |
The Merchant Interface is designed to accept transactions across the Internet. This interface can be used not only by shops but also by enterprise resource planning systems, for example to initiate payment capture via the
Multiexcerpt include | ||||||
---|---|---|---|---|---|---|
|
To ensure compatibility with programming languages and operating systems,
Multiexcerpt include | ||||||
---|---|---|---|---|---|---|
|
Multiexcerpt include | ||||||
---|---|---|---|---|---|---|
|
Communication with
Multiexcerpt include | ||||||
---|---|---|---|---|---|---|
|
Please note, that the
Multiexcerpt include | ||||||
---|---|---|---|---|---|---|
|
Accepted cipher:
TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
In this homogenous interface, irrespective of the payment method, the same parameters are transmitted in general to these Internet pages so that all payment methods operate in the same way and require no additional effort.
The most important parameters to be submitted to the
Multiexcerpt include | ||||||
---|---|---|---|---|---|---|
|
- MerchantID
- Amount and Currency
- URLs for status-messages
The MerchantID is an alphanumerical value which uniquely identifies the merchant within the
Multiexcerpt include | ||||||
---|---|---|---|---|---|---|
|
Multiexcerpt include | ||||||
---|---|---|---|---|---|---|
|
Multiexcerpt include | ||||||
---|---|---|---|---|---|---|
|
The following list shows a typical example with the parameters for processing a payment:
MerchantID=YourMerchantID&TransID=ab123456&Amount=9000&Currency=EUR&URLSuccess=https://www.shop.de/ok.cgi&URLFailure=https://www.shop.de/failed.cgi&URLNotify=https://www.shop.de/notify.cgi |
Notice: Depending on the implementation, URLSuccess and URLFailure are called up via a Redirect (HTTP Status 302 Object Moved) which is then dependent on the customer's browser. In order to ensure that the shop has been informed correctly about the status of the payment
Multiexcerpt include | ||||||
---|---|---|---|---|---|---|
|
Operating principle of the Merchant Interface
In order to send payment orders to the
Multiexcerpt include | ||||||
---|---|---|---|---|---|---|
|
Multiexcerpt include | ||||||
---|---|---|---|---|---|---|
|
Multiexcerpt include | ||||||
---|---|---|---|---|---|---|
|
Multiexcerpt include | ||||||
---|---|---|---|---|---|---|
|
A payment process looks something like the following:
1 The customer selects the payment method in the shop and clicks on the Pay button. 2 The shop generates a character string with merchant number, amount and shopping cart: "MERCHANT=YourMerchantID&AMOUNT=49&SHOPPING CART=Flowers" 3 Depending on the payment method the character string is transmitted to the corresponding Internet page:
|
The simple transmission of a character string has the advantage that you need install no software on the shop server. The interface functions with all current payment methods so that a connection to
Multiexcerpt include | ||||||
---|---|---|---|---|---|---|
|
Payments via
Multiexcerpt include | ||||||
---|---|---|---|---|---|---|
|
In the case of payments via
Multiexcerpt include | ||||||
---|---|---|---|---|---|---|
|
Multiexcerpt include | ||||||
---|---|---|---|---|---|---|
|
Multiexcerpt include | ||||||
---|---|---|---|---|---|---|
|
Process of a payment with
Multiexcerpt include | ||||||
---|---|---|---|---|---|---|
|
Process of payment
To make payments via
Multiexcerpt include | ||||||
---|---|---|---|---|---|---|
|
Multiexcerpt include | ||||||
---|---|---|---|---|---|---|
|
All details required for payment processing are forwarded as parameters. The parameters are encrypted with Blowfish and protected with HMAC-Authentication (see below) to ensure that neither the customer nor a third party can manipulate the data.
When calling the form
Multiexcerpt include | ||||||
---|---|---|---|---|---|---|
|
After the payment has been made
Multiexcerpt include | ||||||
---|---|---|---|---|---|---|
|
Multiexcerpt include | ||||||
---|---|---|---|---|---|---|
|
Notice: Please note that the merchant must be able to process HTTPS GET as well as HTTPS POST. Whether GET or POST is used, depends on the payment method and implementation.
Request for a Multiexcerpt includeSpaceWithExcerpt EN MultiExcerptName Platform-Kurz PageWithExcerpt Wording
form
SpaceWithExcerpt | EN |
---|---|
MultiExcerptName | Platform-Kurz |
PageWithExcerpt | Wording |
The request for a
Multiexcerpt include | ||||||
---|---|---|---|---|---|---|
|
MerchantID=YourMerchantID |
All parameters are assembled in a character string and separated by the character &:
Amount=100&Currency=EUR&TransID=12345 |
Notice: Since the characters "=" and "&" are used as separating characters, these characters cannot be transmitted as values. All values which you transmit without BlowFish-encryption must be URL-Encoded.
A correct parameter character string for
Multiexcerpt include | ||||||
---|---|---|---|---|---|---|
|
MerchantID=YourMerchantID&Len=67&Data=0A67FE96a65d384350F50FF1 |
The Data parameter contains the sensitive payment details such as amount and currency. The encrypted bytes are Hex-encoded and completed to two characters from the left with a zero. Encryption is via Blowfish ECB and is available to you as source-code and components.
The Len parameter is very important for encryption because it contains the length of the unencrypted(!) character string in the Data parameter. Since the data quantity to be encrypted is increased by a multiple of 8 in the case of the Blowfish encryption, the correct length of the character string must be known for decryption. Otherwise accidental characters emerge at the end of the character string.
The parameters are transmitted via HTTPS POST or HTTPS GET. The recommended transmit method is HTTPS POST because the parameter character string in the case of GET is attached to the URL, which is limited to 2048 bytes depending on the browser.
Notice: Please note that the maximum length of a payment request is limited to 5120 characters. If you require longer strings please contact
Multiexcerpt include | ||||||
---|---|---|---|---|---|---|
|
The following listings show the development of a payment request. The first listing is the unencrypted parameter character string:
MerchantID=YourMerchantID&TransID=100000001&Amount=11&Currency=EUR&URLSuccess=https://www.shop.de/ok.html&URLFailure=https://www.shop.de/failed.html&URLNotify=https://www.shop.com/notify.cgi&OrderDesc=My purchase |
Notice: Please note that a value is to be assigned to each parameter. Do not transmit empty parameters, as this can cause the payment to fail.
This character string is encrypted and transmitted as the Data parameter. The HTTPS GET request for a
Multiexcerpt include | ||||||
---|---|---|---|---|---|---|
|
Code Block |
---|
<A href="https://vr-epayment-gateway.de/payssl.aspx?MerchantID=YourMerchantID&Len=162&Data=E98D40FFFD622C5FE7414F73539A1852C2CE7C8B09D34DF217E27FA2E194B9968DE9ABAE3B1F44B5485EFE3EF2597C7395BADBAD4340CDFD000DD57129EEFAA0BE904A7E2339DCF9363DA6ACDBE5EF98E169FC3092B160252A037135421FD0CE092C174A7D1D63517BD45099AC2B682F5E3CD2C942A6F0E741A833C0&Background=https://www.meinshop.de/grafik/hintergrundbild.jpg">Pay</A> |
Notice: Please note that the parameters are transmitted unencrypted for the purpose of layout of the form.
An HTML form is produced for HTTPS POST and all parameters are transmitted as Hidden Fields. Only the Pay button is visible to the customer:
Code Block |
---|
<FORM method="POST" action="https://vr-epayment-gateway.de/payssl.aspx"> <INPUT type="hidden" name="MerchantID" value="YourMerchantID"> <INPUT type="hidden" name="Len" value="162"> <INPUT type="hidden" name="Data" value="E98D40FFFD622C5FE7414F73539A1852C2CE7C8B09D34DF217E27FA2E194B9968DE9ABAE3B1F44B5485EFE3EF2597C7395BADBAD4340CDFD000DD57129EEFAA0BE904A7E2339DCF9363DA6ACDBE5EF98E169FC3092B160252A037135421FD0CE092C174A7D1D63517BD45099AC2B682F5E3CD2C942A6F0E741A833C0"> <INPUT type="hidden" name="Background" value="https://www.meinshop.de/grafik/hintergrundbild.jpg"> <INPUT type="submit" name="Pay" value="Pay"> </FORM> |
Include Page | ||||
---|---|---|---|---|
|
Include Page | ||||
---|---|---|---|---|
|
Notification of the shop
After processing the payment
Multiexcerpt include | ||||||
---|---|---|---|---|---|---|
|
Multiexcerpt include | ||||||
---|---|---|---|---|---|---|
|
Multiexcerpt include | ||||||
---|---|---|---|---|---|---|
|
Notice: Please note that the Notify-call is permitted only via Port 443 (TLS) for security reasons.
If the shop’s URLNotify is not accessible (e.g. HTTP-status 500/404), notification is repeated 8 times. In this case the customer transmit to the shop is prior to the URLNotify request. Therefore the shop should analyse and compare both status messages from URLNotify and transmission (URLSuccess, URLFailure).
Repeat | Waiting time | Time after 1. Notify |
---|---|---|
0 | instantly | 0 |
1 | 00:01 h | 00:01 h |
2 | 00:08 h | 00:09 h |
3 | 00:27 h | 00:36 h |
4 | 01:04 h | 01:40 h |
5 | 02:05 h | 03:45 h |
6 | 03:36 h | 07:21 h |
7 | 05:43 h | 13:04 h |
8 | 08:32 h | 21:36 h |
Time of repeat of Notify respectively calculated after first failed attempt
Notice: The URL encoded parameters are transmitted in key-value pairs (Key1=Value1&Key2=Value2). Please note that new parameters can be added unannounced at any time. Therefore, we recommend the use of the parameter name for the analysis, not the order since this can change at any time. Please do not use case sensitive mechanisms for the spelling of the parameters as this can change at any time. For example, it is recommended switching all parameters “to lower” and continuing in lower case.
For more details please go to:
www.w3.org/MarkUp/html-spec/html-spec_8.html#SEC8.2.1
Transfer of the customer to the shop
Once payment is complete, the customer is redirected via HTTP GET back to the shop.
Multiexcerpt include | ||||||
---|---|---|---|---|---|---|
|
Correct testing
Until you have completed the programming your
Multiexcerpt include | ||||||
---|---|---|---|---|---|---|
|
Multiexcerpt include | ||||||
---|---|---|---|---|---|---|
|
Notice: Please use only small amounts between 0.11 and 2 euros in test mode because the credit card authorisations are genuine even in the test and reduce the limit of your credit card. If you use large amounts and reach the card limit, your credit card will no longer function temporarily.
In the case of successful payments the
Multiexcerpt include | ||||||
---|---|---|---|---|---|---|
|
If you wish to test the different error cases,
Multiexcerpt include | ||||||
---|---|---|---|---|---|---|
|
Multiexcerpt include | ||||||
---|---|---|---|---|---|---|
|
Test case with timeout
A credit card payment is normally completed within one to two seconds. In a few cases however, payments may be terminated due to long processing times in the banking network.
Multiexcerpt include | ||||||
---|---|---|---|---|---|---|
|
Multiexcerpt include | ||||||
---|---|---|---|---|---|---|
|
Payments via Server-to-Server connection
In the case of payments via the Server-to-Server connection, the merchant already holds payment details such as credit card numbers and bank account details. Shop or enterprise resource planning systems create a TLS socket-connection to the
Multiexcerpt include | ||||||
---|---|---|---|---|---|---|
|
Process of a Server-to-Server payment
Notice: When processing payments via a Server-to-Server connection your system must control the communication with the
Multiexcerpt include | ||||||
---|---|---|---|---|---|---|
|
Notice: Please ensure that for one payment (PayID) no multiple requests are submitted simultaneously, because this can lead to errors within transaction processing. Please ensure to have a few seconds between two requests for the same payment/PayID.
Process of a Server-to-Server payment
The request for a payment starts with the correct composition of the parameters which consist of a key and a value and which are separated by an equals sign (=). These are so called Name-Value-Pairs (NVP):
Code Block |
---|
MerchantID=YourMerchantID |
All parameters are assembled in a character string and separated by the character &:
Code Block |
---|
Amount=100&Currency=EUR&TransID=12345 |
Notice: Since the characters "=" and "&" are used as separating characters, these characters cannot be transmitted as values. All values which you transmit without BlowFish-encryption must be URL-Encoded. There is only one exemption from this rule: For credit cards which are registered for Verified/SecureCode/SafeKey/JSecure/ProtectBuy for example the ACSURL is transmitted unencoded.
A correct parameter character string for
Multiexcerpt include | ||||||
---|---|---|---|---|---|---|
|
Code Block |
---|
MerchantID=YourMerchantID&Len=67&Data=0A67FE96a65d384350F50FF1 |
The Data parameter contains the sensitive payment details such as amount and currency. The encrypted bytes are Hex-encoded and completed to two characters from the left with a zero. Encryption is via Blowfish ECB and is available to you as source-code and components.
The Len parameter is very important for encryption because it contains the length of the unencrypted(!) character string in the Data parameter. Since the data quantity to be encrypted is increased by a multiple of 8 in the case of the Blowfish encryption, the correct length of the character string must be known for decryption. Otherwise accidental characters emerge at the end of the character string.
The following listings show the development of a payment request. The first listing is the unencrypted parameter character string:
Code Block |
---|
MerchantID=YourMerchantID&TransID=100000001&Amount=11&Currency=EUR&OrderDesc=My purchase&CCNr=1111333355557777&CCCVC=123&CCExpiry=202012&CCBrand=VISA |
Notice: Please note that a value is to be assigned to each parameter. Do not transmit empty parameters, as this can cause the payment to fail.
This character string is encrypted with Blowfish:
Code Block |
---|
MerchantID=YourMerchantID&Len=140&Data=D622C5FE7414F73539A1852C2CE7AA0BE904A7E2339DCF9363DA6ACDBE5EF98E169FC3092B1602564DBF2C3C75173A62C484962A247B8A91EA7A544ADCF2A037135421FD0CE092C174A7D1D63517BD45099AC2B682F5E3CD2C942A6F0E741A833C |
In order to make payments via a Server-to-Server connection, open a TLS-Socket connection to
Multiexcerpt include | ||||||
---|---|---|---|---|---|---|
|
|
As soon as the TLS socket connection is made, a normal HTTP POST, version 1.1 is carried out. In this case the following fields are specified in the HTTP header:
Field | Value |
---|---|
Host | |
Connection | Close |
Content-type | Application/x-www-form-urlencoded |
Content-length | Length of character string transferred to the HTTP-Body |
Charset | UTF-8 |
The HTTP Body contains the parameter character string. Note that the values must be submitted as URL-encoded parameters. The following listing is an example of a credit card payment:
Code Block |
---|
POST /direct.aspx HTTP/1.1 Host: vr-epayment-gateway.de/ Connection: Close Content-type: application/x-www-form-urlencoded Content-Length: 287 MerchantID=YourMerchantID&Len=162&Data=E98D40FFFD622C5FE7414F73539A1852C2CE7C8B09D3E876F52CBECF59EC63E9B8AA0130FA92F65964E3EEE74DF217E27FA2E194B9968DE9ABAE3B1F44B5485EFE3EF2597C7395BADBAD4340CDFD000DD57129EEFAA0BE904A7E2339DCF9363DA6ACDBE5EF98E169FC3092B1602564DBF2C3C75173A62C484962A247B8A91EA7A5 |
Notice: Please note that the maximum length of a payment request is limited to 5120 characters. If you require longer strings please contact
Multiexcerpt include | ||||||
---|---|---|---|---|---|---|
|
The following listing shows a typical
Multiexcerpt include | ||||||
---|---|---|---|---|---|---|
|
Multiexcerpt include | ||||||
---|---|---|---|---|---|---|
|
Code Block |
---|
HTTP/1.0 200 OK Connection: Close Content-type: text/plain Content-Length: 228 Len=125&Data=ECF59EC63E9BEE74DF217E27FA2E194B92597C7395BADBAD4340CDFD000DD57129EEFAA0BE904A7E233ACDBE5EF98E1692B1602564DBF2C3C75173A62C484962A247B8A91EA7A544 |
The decrypted
Multiexcerpt include | ||||||
---|---|---|---|---|---|---|
|
Code Block |
---|
PayID=a234b678e01f34567090e23d567890ce&XID=50f35e768edf34c4e090e23d567890ce&TransID=100000001&Status=AUTHORIZED&Description=AUTHORIZED&Code=00000000 |
It is a synchronous communication such that the Socket-connection remains open until
Multiexcerpt include | ||||||
---|---|---|---|---|---|---|
|
Multiexcerpt include | ||||||
---|---|---|---|---|---|---|
|
Notice: The URL encoded parameters are transmitted in key-value pairs (Key1=Value1&Key2=Value2). Please note that new parameters can be added unannounced at any time. Therefore, we recommend the use of the parameter name for the analysis, not the order since this can change at any time. Please do not use case sensitive mechanisms for the spelling of the parameters as this can change at any time. For more details please go to: