Saferpay JSON API Specification - SIX · The Saferpay JSON API (JavaScript Object Notation...
Transcript of Saferpay JSON API Specification - SIX · The Saferpay JSON API (JavaScript Object Notation...
© SIX 2017 Page 1
Saferpay JSON API
Specification
Version: 2.3
© SIX 2017 Page 2
Content
1.1 Requirements ................................................................................................................................... 7
1.2 Data Security and PCI DSS ............................................................................................................. 7
1.3 3-D Secure ....................................................................................................................................... 8
1.4 Dynamic Currency Conversion ........................................................................................................ 8
1.5 Supported Payment Means ............................................................................................................. 9
1.6 Format Details ................................................................................................................................ 10
2.1 Web Addresses .............................................................................................................................. 11
2.2 Support only for HTTP POST ........................................................................................................ 11
2.3 Encoding and Headers................................................................................................................... 11
2.4 Authentication ................................................................................................................................ 12
2.4.1 HTTPS Basic Authentication ......................................................................................................................... 12
2.4.2 HTTPS Client Certificate Authentication ........................................................................................................ 13
3.1 Initialization .................................................................................................................................... 15
3.1.1 Payment Page Initialize Request ................................................................................................................... 15
3.1.2 Example of Payment Page Initialize Request ................................................................................................ 16
3.1.3 Payment Page Initialize Response ................................................................................................................ 16
3.1.4 Examples Initialize Response ........................................................................................................................ 16
3.2 Browser Redirect ............................................................................................................................ 17
3.3 Return to Shop ............................................................................................................................... 17
3.4 Notification ..................................................................................................................................... 17
3.4.1 Beispiel Payment Page Initialize Request with Notify .................................................................................... 17
3.5 Payment Page Assert .................................................................................................................... 18
3.5.1 Payment Page Assert Request ...................................................................................................................... 18
3.5.2 Examples Assert Request ............................................................................................................................. 18
3.5.3 Payment Page Assert Response ................................................................................................................... 18
3.5.4 Examples Assert Response ........................................................................................................................... 19
4.1 Overview ........................................................................................................................................ 20
4.2 Initialization .................................................................................................................................... 20
4.2.1 Initialize Request ........................................................................................................................................... 20
4.2.2 Examples Initialize Request ........................................................................................................................... 21
4.2.3 Initialize Response ........................................................................................................................................ 22
4.3 Browser Redirect (PaymentMeansRequired: false) ....................................................................... 22
4.4 Hosted Form (PaymentMeansRequired: true) ............................................................................... 22
4.4.1 Integration of the Credit Card Form in the Iframe .......................................................................................... 23
4.4.2 Example HTML Form..................................................................................................................................... 23
4.4.3 Features of the Form ..................................................................................................................................... 23
4.4.4 Return to Shop .............................................................................................................................................. 23
4.4.5 Example Exit from the Iframe ........................................................................................................................ 24
4.5 Authorization .................................................................................................................................. 24
4.5.1 Authorize Request ......................................................................................................................................... 24
4.5.2 Example Authorize Request .......................................................................................................................... 25
4.5.3 Authorize Response ...................................................................................................................................... 25
4.5.4 Example of Authorize Response ................................................................................................................... 26
© SIX 2017 Page 3
4.6 Authorization without initialization .................................................................................................. 27
4.6.1 Difference between Initialize and AuthorizeDirect ......................................................................................... 27
4.6.2 AuthorizeDirect Request ................................................................................................................................ 28
4.6.3 Example AuthorizeDirect Request ................................................................................................................. 28
4.6.4 AuthorizeDirect Response ............................................................................................................................. 29
4.6.5 Example AuthorizeDirect Response .............................................................................................................. 29
4.6.6 ELV via AuthorizeDirect ................................................................................................................................. 30
4.6.7 Example ELV AuthorizeDirect Request: ........................................................................................................ 30
4.6.8 Example ELV AuthorizeDirect Response: ..................................................................................................... 31
4.7 Recurring Payments ....................................................................................................................... 32
4.7.1 Request Initial Payment ................................................................................................................................. 32
4.7.2 Examples Initialize Request ........................................................................................................................... 32
4.7.3 Subsequent Payments................................................................................................................................... 33
4.7.4 AuthorizeReferenced Request ....................................................................................................................... 33
4.7.5 Example AuthorizeReferenced Request ........................................................................................................ 33
4.7.6 AuthorizeReferenced Response .................................................................................................................... 34
4.7.7 Example AuthorizeReferenced Response ..................................................................................................... 34
4.8 Redirect Payment Means ............................................................................................................... 34
4.8.1 Overview ........................................................................................................................................................ 35
4.8.2 RedirectPayment Request ............................................................................................................................. 35
4.8.3 Example RedirectPayment Request .............................................................................................................. 36
4.8.4 RedirectPayment Response .......................................................................................................................... 37
4.8.5 Example RedirectPayment Response ........................................................................................................... 37
4.8.6 Browser Redirect ........................................................................................................................................... 37
4.8.7 Return to Shop .............................................................................................................................................. 37
4.8.8 Assert Redirect Payment Request ................................................................................................................. 37
4.8.9 Example Assert Redirect Payment Request .................................................................................................. 38
4.8.10 Assert Redirect Payment Response .............................................................................................................. 38
4.8.11 Example Assert Redirect Payment Response ............................................................................................... 38
4.9 Credits ............................................................................................................................................ 39
4.9.1 Refund Request ............................................................................................................................................. 39
4.9.2 Example Refund Request .............................................................................................................................. 39
4.9.3 Refund Response .......................................................................................................................................... 40
4.9.4 Example Refund Request .............................................................................................................................. 40
4.9.5 RefundDirect Request ................................................................................................................................... 41
4.9.6 Example RefundDirect Request .................................................................................................................... 41
4.9.7 RefundDirect Response ................................................................................................................................. 42
4.9.8 Example RefundDirect Response .................................................................................................................. 42
5.1 Capture Request ............................................................................................................................ 43
5.2 Example Capture Request ............................................................................................................. 43
5.3 Capture Response ......................................................................................................................... 43
5.4 Example Capture Response .......................................................................................................... 44
6.1 Cancel Request .............................................................................................................................. 45
6.2 Example Cancel Request............................................................................................................... 45
6.3 Cancel Response ........................................................................................................................... 45
© SIX 2017 Page 4
6.4 Example Cancel Response ............................................................................................................ 45
7.1 Close Request ................................................................................................................................ 46
7.2 Example Close Request................................................................................................................. 46
7.3 Close Response ............................................................................................................................. 46
7.4 Example Close Response .............................................................................................................. 46
8.1 Supported Payment Means ........................................................................................................... 47
8.2 Registration of Alias via a Form ..................................................................................................... 47
8.2.1 Insert Request ............................................................................................................................................... 47
8.2.2 Example Insert Request ................................................................................................................................ 48
8.2.3 Insert Response ............................................................................................................................................ 48
8.2.4 Example Insert Response .............................................................................................................................. 48
8.2.5 Integration of the Credit Card Form in an Inline Frame.................................................................................. 49
8.2.6 Example HTML Form..................................................................................................................................... 49
8.2.7 Properties of the Form ................................................................................................................................... 49
8.2.8 Return to Shop .............................................................................................................................................. 49
8.2.9 Example Exit from the Iframe ........................................................................................................................ 50
8.2.10 AssertInsert Request ..................................................................................................................................... 50
8.2.11 Example AssertInsert Request ...................................................................................................................... 50
8.2.12 AssertInsert Response .................................................................................................................................. 51
8.2.13 Example AssertInsert Response ................................................................................................................... 51
8.3 Registration with InsertDirect ......................................................................................................... 51
8.3.1 InsertDirect Request ...................................................................................................................................... 51
8.3.2 Example InsertDirect Request ....................................................................................................................... 52
8.3.3 InsertDirect Response ................................................................................................................................... 52
8.3.4 Example InsertDirect Response .................................................................................................................... 52
8.4 Deleting an Alias ............................................................................................................................ 53
8.4.1 Delete Request .............................................................................................................................................. 53
8.4.2 Example Delete Request ............................................................................................................................... 53
8.4.3 Delete Response ........................................................................................................................................... 53
8.4.4 Example Delete Response ............................................................................................................................ 53
9.1 Size of the Inline frame .................................................................................................................. 54
9.2 Using CSS ...................................................................................................................................... 54
9.2.1 Element name ............................................................................................................................................... 54
9.2.2 Class name .................................................................................................................................................... 54
9.2.3 Element ID ..................................................................................................................................................... 54
9.2.4 Element attributes .......................................................................................................................................... 55
9.2.5 CSS selectors ................................................................................................................................................ 55
9.2.6 Concluding notes ........................................................................................................................................... 55
9.3 Important Information for Using CSS ............................................................................................. 55
9.4 CSS Class names .......................................................................................................................... 56
9.4.1 General Classes ............................................................................................................................................ 56
9.4.2 Specifically for Payment Page ....................................................................................................................... 57
9.4.3 Specifically for Card Form ............................................................................................................................. 57
9.4.4 Specifically for Direct Debit Form .................................................................................................................. 57
9.4.5 Specifically for Online Banking ...................................................................................................................... 58
© SIX 2017 Page 5
9.4.6 Specifically for Billing Form ............................................................................................................................ 58
9.4.7 Specifically for Address Form (incl. Billpay Address Form) ........................................................................... 58
9.4.8 Specifically for GTC ....................................................................................................................................... 58
9.4.9 Specifically for Redirect Pages (incl. 3D-Secure) .......................................................................................... 58
9.4.10 Specifically for Error Pages ........................................................................................................................... 58
9.4.11 Specifically for Confirmation Page ................................................................................................................. 58
9.5 CSS Examples ............................................................................................................................... 58
10.1.1 Redirection via POST .................................................................................................................................... 59
10.1.2 Example HTML Form..................................................................................................................................... 60
10.1.3 Data Transfer with AJAX ............................................................................................................................... 60
10.1.4 Example of AJAX Transfer ............................................................................................................................ 61
10.1.5 Return to Shop .............................................................................................................................................. 61
11.1 Address .......................................................................................................................................... 62
11.2 AddressForm .................................................................................................................................. 62
11.3 Alias................................................................................................................................................ 62
11.4 AliasInfo ......................................................................................................................................... 62
11.5 Amount ........................................................................................................................................... 63
11.6 BankAccount .................................................................................................................................. 63
11.7 BankAccountInfo ............................................................................................................................ 63
11.8 BillpayCapture ................................................................................................................................ 63
11.9 Brand .............................................................................................................................................. 63
11.10 Card................................................................................................................................................ 63
11.11 CardInfo ......................................................................................................................................... 64
11.12 CardForm ....................................................................................................................................... 64
11.13 ClientInfo ........................................................................................................................................ 64
11.14 DccInfo ........................................................................................................................................... 64
11.15 DirectDebit ..................................................................................................................................... 64
11.16 Invoice ............................................................................................................................................ 64
11.17 Notification ..................................................................................................................................... 64
11.18 NotifyHeader .................................................................................................................................. 65
11.19 Payer .............................................................................................................................................. 65
11.20 PayerInfo ........................................................................................................................................ 65
11.21 Payment ......................................................................................................................................... 66
11.22 PaymentMeans .............................................................................................................................. 66
11.23 PaymentMeansInfo ........................................................................................................................ 66
11.24 PaymentOptions ............................................................................................................................. 67
11.25 RecurringOptions ........................................................................................................................... 67
11.26 Redirect .......................................................................................................................................... 67
11.27 Refund ............................................................................................................................................ 67
11.28 RegisterAlias .................................................................................................................................. 68
11.29 RegistrationError ............................................................................................................................ 68
11.30 RegistrationResult .......................................................................................................................... 68
11.31 RequestHeader .............................................................................................................................. 68
11.32 ResponseHeader ........................................................................................................................... 69
11.33 ReturnUrls ...................................................................................................................................... 69
11.34 Styling............................................................................................................................................. 69
© SIX 2017 Page 6
11.35 ThreeDsInfo ................................................................................................................................... 69
11.36 Transaction .................................................................................................................................... 70
11.37 TransactionReference .................................................................................................................... 70
11.38 Wallet ............................................................................................................................................. 70
12.1 HTTP Status Codes ....................................................................................................................... 71
12.2 Error Message ................................................................................................................................ 71
12.2.1 HTTP Error Messages ................................................................................................................................... 72
13.1 Introduction .................................................................................................................................... 74
13.2 Pay Pal ........................................................................................................................................... 74
1.1 Prerequisites .................................................................................................................................. 74
1.2 Grant API permission for Saferpay ................................................................................................ 74
1.3 PayPal Seller Protection ................................................................................................................ 77
13.2.1 Payment Page Initialize Request ................................................................................................................... 77
13.2.2 Example Payment Page Initialize Request Transfer of Address .................................................................... 78
13.2.3 Example Payment Page Initialize Request Use of Address Form ................................................................. 79
13.3 Billpay ............................................................................................................................................. 80
1.4 Requirements ................................................................................................................................. 80
13.3.1 Payment Page Initialize Request ................................................................................................................... 80
13.3.2 Example Payment Page Initialize Request Transfer of Address .................................................................... 81
13.3.3 Example Payment Page Initialize Request Use of Address Form ................................................................. 82
13.3.4 Payment Page Assert Response ................................................................................................................... 82
13.3.5 Example Payment Page Assert Response .................................................................................................... 83
13.3.6 Capture Request ........................................................................................................................................... 83
13.3.7 Example Capture Request ............................................................................................................................. 84
13.3.8 Capture Response ......................................................................................................................................... 84
13.3.9 Example Capture Response .......................................................................................................................... 84
13.4 Alias Registration for Postfinance Card ......................................................................................... 85
13.4.1 Requirements ................................................................................................................................................ 85
13.4.2 Insert Request ............................................................................................................................................... 85
13.4.3 Example Insert Request ................................................................................................................................ 85
13.4.4 Insert Response ............................................................................................................................................ 86
13.4.5 Example Insert Response .............................................................................................................................. 86
13.4.6 Redirection to PostFinance ............................................................................................................................ 87
14.1.1 Return to Shop .............................................................................................................................................. 90
15.1 Language Codes for LanguageCode ............................................................................................. 91
15.2 Supported Payment Means Values for PaymentMethod(s)........................................................... 92
15.3 License Matrix ................................................................................................................................ 93
17.1 Saferpay Integration Team ............................................................................................................ 95
17.2 Saferpay Support Team ................................................................................................................. 95
© SIX 2017 Page 7
1 Introduction
The Saferpay JSON API (JavaScript Object Notation Application Programming Interface), hereinafter also referred to as the "JA", is a modern and lean interface which works independently of programming langu-ages.
The JA supports all Saferpay methods and is suitable for all shop systems and call center solutions as well as merchandise management, ERP and CRM systems. It can also be used for all other areas of applicati-on in which online payments have to be processed.
This document describes the process for integrating various Saferpay modules into existing systems via the Saferpay JSON API.
Find more information for JSON API on GitHub:
https://saferpay.github.io/jsonapi/index.html (Technical Specifikation JSON API)
https://saferpay.github.io/sndbx/index.html (Further documentation JSON API)
1.1 Requirements
The following is required to use the JA:
A corresponding license for the Saferpay module.
A valid account with username and password for Saferpay Backoffice.
At least one active Saferpay terminal via which payments can be made and the associated Safer-pay terminal number and Saferpay client number.
A valid acceptance contract for credit cards or other payment channels.
1.2 Data Security and PCI DSS
The credit card organizations have launched the PCI DSS (Payment Card Industry Data Security Stan-dard) security program in order to prevent the fraudulent and unauthorized use of credit cards.
Please take note of the PCI DSS guidelines when designing the payment process and using Saferpay.
By using the Saferpay Hosted Form, along with the optional Saferpay Secure Card Data (SCD) service, you can structure the payment processes in such a secure manner than no credit card numbers are pro-cessed, forwarded or saved on your (web) servers.
When using the Saferpay payment page, cardholders do not enter their credit card number and expiry date within the merchant's e-commerce application, but rather within the Saferpay payment page. As the e-commerce application and Saferpay are operated on physically separate platforms, there is no risk that the credit card data may be saved in the database on the merchant system.
Using Saferpay Secure Card Data or the Saferpay payment page significantly reduces the risk of credit card data being misused and also means there is considerably less work for the merchant as regards the PCI DDS certification process.
Your processor or a company specialized in this area will be able to answer any questions you may have on PCI DDS (see https://www.pcisecuritystandards.org).
© SIX 2017 Page 8
1.3 3-D Secure
3-D Secure, or 3DS for short, is supported by Visa (Verified by Visa), MasterCard (MasterCard SecureCo-de), American Express (SafeKey) and Diners Club (ProtectBuy). Merchants who offer the 3-D Secure pro-cedure benefit from increased security as regards credit card acceptance and also suffer fewer payment defaults thanks to the liability shift. Here, it is not relevant whether the cardholder (CH) participates in the procedure or not. The 3-D Secure procedure can only be used for online payments. Cardholders who participate in the pro-cedure must identify themselves to the card-issuing bank (issuer) during the payment process. Payments processed by the merchant using 3-D Secure must be specially marked. The liability shift only applies upon the relevant security features being sent to the credit card company with the authorization. The Saferpay Merchant Plug-In, or MPI for short, supports the necessary interactions and the data exchange between the involved systems. The JSON API handles this step in automated fashion via the transaction interface (Initialize) and the payment page, so no additional integration work is required. The CH is authenticated using a web form, which is hosted by the issuer or a service provider acting on its be-half. The CH thus must have an Internet connection in order to complete the 3-D Secure authentication process. 1. The merchant sends the credit card data to Saferpay together with the relevant payment data.
2. Saferpay checks whether the CH participates in the 3-D Secure procedure or not. If the CH does, the CH is required to identify himself to his bank. Should the CH choose not to participate, the payment is made without the authentication process.
3. The 3-D Secure query is forwarded to the card-issuing bank via the Internet browser of the CH. The CH must identify himself using a password, certificate or another method.
4. The result of this check (authentication) is sent back to Saferpay via the client's Internet browser.
5. Saferpay checks the result and ensures that there has been no manipulation. The payment can be continued upon the authentication process being successfully completed.
6. Saferpay links the MPI data to the token used by the JSON API and automatically requests the data to enable the card to be authorized.
1.4 Dynamic Currency Conversion
Dynamic Currency Conversion, or DCC for short, is only available for SIX acceptance contracts for which DCC has been added. Here, the terminal used for payment queries is given a base currency in which all transactions are settled. With DCC, international clients are displayed the purchase amount in the base currency and at the best exchange rate in their home currency. Clients can decide in which currency they would like to pay.
A separate implementation process by the merchant is not required for DCC. Saferpay handles this step automatically during the redirect process.
© SIX 2017 Page 9
1.5 Supported Payment Means
The JSON API currently supports the following payment means:
Payment means Transaction interface Payment page Visa
V PAY
MasterCard
Maestro International
American Express
Diners Club
JCB
Bonus Card
PostFinance e-finance
PostFinance card
MyOne
SEPA direct debit
PayPal
ePrzelewy
Homebanking AT (eps)
giropay
iDeal
Billpay Pay by Invoice
Billpay Direct Debit
© SIX 2017 Page 10
1.6 Format Details
The following abbreviations are used in this document for the format details:
a Letters (a - z, A - Z)
n Numeric characters (0 - 9)
an Alphanumeric characters (a - z, A - Z, 0 - 9)
s Special characters (:?,-(+‘.)/ and spaces)
ans Alphanumeric and special characters
true^false Boolsche variable ("true" or "false")
date Date format according to ISO 8601 YYYY-MM-DD
datetime Time format according to ISO 8601 YYYY-MM-DDThh:mm:ss.fff+hh:mm
id Alphanumeric characters as well as period, colon, hyphen and underscore (.:-_)
o/m Indicates whether a parameter is optional (o) or mandatory (m)
© SIX 2017 Page 11
2 JSON API
2.1 Web Addresses
The JA can be accessed externally via the following web addresses:
Base URL: HTTPS://www.saferpay.com/api
Each request sent to the JA is made via an individual URL based on the base URL:
Payment page initialization: /Payment/v1/PaymentPage/Initialize
Payment Page assert: /Payment/v1/PaymentPage/Assert
Initialization: /Payment/v1/Transaction/Initialize
Authorization: /Payment/v1/Transaction/Authorize
Direct authorization: /Payment/v1/Transaction/AuthorizeDirect
Referenced authorization: /Payment/v1/Transaction/AuthorizeReferenced
Redirect payment: /Payment/v1/Transaction/RedirectPayment
Redirect payment check: /Payment/v1/Transaction/AssertRedirectPayment
Booking: /Payment/v1/Transaction/Capture
Cancellation: /Payment/v1/Transaction/Cancel
Daily closing: /Payment/v1/Batch/Close
Referenced credit: /Payment/v1/Transaction/Refund
Direct credit: /Payment/v1/Transaction/RefundDirect
Alias registration via form: /Payment/v1/Alias/Insert
Direct registration: /Payment/v1/Alias/InsertDirect
Registration check: /Payment/v1/Alias/AssertInsert
Alias deletion: /Payment/v1/Alias/Delete
2.2 Support only for HTTP POST
Please note that all requests to Saferpay must be made via the HTTP method POST. The GET method is not supported because of limited data length.
2.3 Encoding and Headers
Saferpay uses UTF-8 for the encoding of text messages. Please ensure that your application is configured accordingly.
The following header must be set for server-to-server calls:
Header Value
Accept application/json
Content type application/json
© SIX 2017 Page 12
2.4 Authentication
Authentication via the JA is usually processed by HTTPS Basic Authentication. For Saferpay Business li-cence holders there is also the option of HTTPS Client Certificate Authentication.
Attention! HTTPS Client Certificate Authenticationprovides additional security, but we only recommend u-sing it when it is absolutely necessary. Every client certificate is valid for two years once it has been crea-ted and must be renewed at that point at the latest. Saferpaywill not inform you if a client certificate ex-pires. If the renewal date is missed, it will not be possible to make any more payments!
2.4.1 HTTPS Basic Authentication
The user ID for JA is generated in Saferpay BackOffice. To reach the “JSON API Basic Authentication” section in Backoffice, click:
My Saferpay Administration JSON API
The form with the user ID filled in by Saferpay will be displayed:
Enter a password that meets the following requirements:
At least 16 characters long
At least one capital and one lowercase letter
At least one number or a special character
Permitted characters:
Capital letters: ABCDEFGHIJKLMNOPQRSTUVWXYZ
Lowercase letters: abcdefghijklmnopqrstuvwxyz
Numbers: 0123456789
Special characters: :+-,_*/$%&()[]=!
© SIX 2017 Page 13
Thereafter, enter a description and click on “Save”.
An overview for the user IDs available for the account appears:
2.4.2 HTTPS Client Certificate Authentication
A client certificate for the JA can be ordered in the Saferpay Backoffice. In order to get to the “JSON API Client Certificate Authentication” heading in the back office click on:
My Saferpay Administration JSON API
If you have a Saferpay Business licence, you will find the HTTPS Client Certificate Authentication section under the form for HTTPS Basic Authentication.
Please note that Saferpay only saves the password in an encrypted form. It is not possible to request the password later. .Furthermore, please take care that the password for requests is securely saved on your server.
© SIX 2017 Page 14
Generate the CSR as described on the page and import it using the upload button.
The signed client certificate is then available to download via the browser:
© SIX 2017 Page 15
3 Payment Page Interface
3.1 Initialization
Transactions are initiated via the URL described in section 2.1.
3.1.1 Payment Page Initialize Request
The following parameters are available for the initial call.
Parameter Type Use Format Description
RequestHeader RequestHeader m Container Contains basic information on the request.
TerminalId String m an[8] Identification of the used terminal
Payment Payment m Container Contains information on the pay-ment.
PaymentMethods String array o Array of predefined values
Contains information on the pay-ment means used. See section 14.2
Wallet Wallet o Container Contains information on the use of wallets (e.g. MasterPass). If no payment methods and only one wallet are given, the payment page automatically forwards the client.
Payer Payer o Container Contains information on the client.
RegisterAlias RegisterAlias o Container For saving the card data in Secure Card Data. PLEASE NOTE: Please pay attention to section 8!
ReturnUrls ReturnUrls m Container Contains the return addresses for the merchant system in the case of forwarding by 3DS or DCC.
Notification Notification o Container Contains information on the URL and e-mail notification.
Styling Styling o Container Contains all the information for the CSS styling feature
BillingAddressForm AddressForm o Container Options for the address form for the billing address
DeliveryAddressForm AddressForm o Container Options for the address form for the delivery address
CardForm CardForm o Container Options for the card form
© SIX 2017 Page 16
3.1.2 Example of Payment Page Initialize Request
{
"RequestHeader": {
"SpecVersion": "1.3",
"CustomerId": "123123",
"RequestId": "33e8af17-35c1-4165-a343-c1c86a320f3b",
"RetryIndicator": 0,
"ClientInfo": {
"ShopInfo": "My Shop",
"ApplicationInfo": "ApplicationInfo",
"OsInfo": "Windows Server 2013"
}
},
"TerminalId": "12345678",
"Payment": {
"Amount": {
"Value": "100",
"CurrencyCode": "CHF"
},
"OrderId": "OrderId",
"Description": "Description",
"PayerNote": "Payernote",
},
"PaymentMethods": ["VISA", "MASTERCARD", "MASTERPASS"],
"Payer": {
"IpAddress": "111.111.111.111"
},
"ReturnUrls": {
"Success": "https://merchanthost/success",
"Fail": "https://merchanthost/fail",
"Abort": "https://merchanthost/abort"
},
"Notification": {
"MerchantEmail": "[email protected]",
"NotifyUrl": "https://merchanthost/notify"
}
}
3.1.3 Payment Page Initialize Response
Parameter Type Use Format Description
ResponseHeader ResponseHeader m Container Contains basic information on the requ-est.
Token String m Id[1..50] Initialization ID for later referencing.
Expiration DateTime m ans[1..30] Expiry date of the token according to ISO 8601. The token can no longer be used after it expires.
RedirectUrl String m ans[1..128] Contains the URL for redirecting the cli-ent.
3.1.4 Examples Initialize Response
{
"ResponseHeader": {
"SpecVersion": "1.3",
"RequestId": "33e8af17-35c1-4165-a343-c1c86a320f3b"
},
"Token": "234uhfh78234hlasdfh8234e",
"Expiration": "2014-11-20T08:58:42.304+1:00",
"RedirectUrl":"https://www.saferpay.com/VT2/Authorize/1234/12341234/234uhfh78234hlasdfh8234e"
}
© SIX 2017 Page 17
3.2 Browser Redirect
After calling up the RedirectUrl the client is redirected to the transmitted link.
3.3 Return to Shop
After the client has made the required entries on the payment page, he is returned to the relevant URL de-pending on the outcome of the transaction.
3.4 Notification
When the NotifyUrl is used, Saferpay can call up the merchant server via http/https-GET. This gets round problems with redirecting to the SuccessUrl.
Please note, that Saferpay does not submit any data through the NotifyUrl. To identify the call, you have to generate your own transactionID, you add to the URL, during Initialize.
You then connect this ID with the Token inside your database. Saferpay then will submit this ID through the notification-call, so you can look up the token for the Assert.
3.4.1 Beispiel Payment Page Initialize Request with Notify
{
"RequestHeader": {
"SpecVersion": "1.3",
"CustomerId": "123123",
"RequestId": "33e8af17-35c1-4165-a343-c1c86a320f3b",
"RetryIndicator": 0,
"ClientInfo": {
"ShopInfo": "My Shop",
"ApplicationInfo": "ApplicationInfo",
"OsInfo": "Windows Server 2013"
}
},
"TerminalId": "12345678",
"Payment": {
"Amount": {
"Value": "100",
"CurrencyCode": "CHF"
},
"OrderId": "OrderId",
"Description": "Description",
"PayerNote": "Payernote",
},
"PaymentMethods": ["VISA", "MASTERCARD", "MASTERPASS"],
"Payer": {
"IpAddress": "111.111.111.111"
},
"ReturnUrls": {
"Success": "https://merchanthost/success",
"Fail": "https://merchanthost/fail",
"Abort": "https://merchanthost/abort"
},
"Notification": {
"MerchantEmail": "[email protected]",
"NotifyUrl": "https://merchanthost/notify.aspx?ID=ABC123"
}
}
Please note! To ensure that the return addresses have not been changed over with fraudulent inten-tions (e.g. swapping the FailUrl for the SuccessUrl), Assert Request should always be used after the buyer is returned to the shop's success page. This elicits a meaningful response, either a confir-mation or a rejection.
© SIX 2017 Page 18
3.5 Payment Page Assert
Using this function, the outcome of a payment page payment can be checked and the result can be deter-mined. Depending on the provider, the transaction is either an authorization (reservation), or has already been automatically booked (capture).
If the transaction has failed, an error message with an http status code 4xx and a JSON error message comes back.
Transactions can be checked via the URL described in section 2.1.
3.5.1 Payment Page Assert Request
Parameter Type Use Format Description
RequestHeader RequestHeader m Container Contains basic information on the requ-est.
Token String m Id[1..50] Initialization ID for later referencing.
3.5.2 Examples Assert Request
{
"RequestHeader": {
"SpecVersion": "1.3",
"CustomerId": "123123",
"RequestId": "33e8af17-35c1-4165-a343-c1c86a320f3b",
"RetryIndicator": 0
},
"Token": "234uhfh78234hlasdfh8234e1234"
}
3.5.3 Payment Page Assert Response
Parameter Type Use Format Description
ResponseHeader ResponseHeader m Container Contains basic information on the response.
Transaction Transaction m Container Contains information on the authorizati-on.
PaymentMeans PaymentMeansInfo m Container Contains information on the payment means.
RegistrationResult RegistrationResult o Container Contains information on the registration in SCD.
Payer PayerInfo o Container Contains information on the payer.
ThreeDs ThreeDsInfo o Container Contains information on 3-D Secure.
Dcc DccInfo o Container Contains information on Dynamic Cur-rency Conversion.
© SIX 2017 Page 19
3.5.4 Examples Assert Response
{
"ResponseHeader": {
"SpecVersion": "1.3",
"RequestId": "33e8af17-35c1-4165-a343-c1c86a320f3b"
},
"Transaction": {
"Type": "PAYMENT",
"Status": "AUTHORIZED",
"Transaction": {
"Id": "K5OYS9Ad6Ex4rASU1IM1b3CEU8bb",
"Date": "2011-09-23T14:57:23.023+01:00",
"Amount": {
"Value": "100",
"CurrencyCode": "CHF"
},
"OrderId": "OrderId",
"AcquirerName": "AcquirerName",
"AcquirerReference": "AcquirerReference"
}
},
"PaymentMeans": {
"Brand": {
"Id": 35,
"Name": "PayPal"
},
"DisplayText": "PayPal transaction"
},
"Payer": {
"IpAddress": "111.111.111.111",
"IpLocation": "NZ"
}
}
© SIX 2017 Page 20
4 Transaction Interface
4.1 Overview
4.2 Initialization
Transactions are initiated via the URL described in section 2.1.
4.2.1 Initialize Request
The following parameters are available for the initial call.
Parameter Type Use Format Description
RequestHeader RequestHeader m Container Contains basic information on the requ-est.
TerminalId String m an[8] Identification of the used terminal
Payment Payment m Container Contains information on the payment.
PaymentMeans PaymentMeans o Container Contains information on the payment means used.
Payer Payer o Container Contains information on the client.
ReturnUrls ReturnUrls m Container Contains the return addresses for the merchant system in the case of forwar-ding by 3DS or DCC.
Styling Styling o Container Contains all the information for the CSS styling feature
© SIX 2017 Page 21
4.2.2 Examples Initialize Request
Without PaymentMeans: {
"RequestHeader": {
"SpecVersion": "1.3",
"CustomerId": "123123",
"RequestId": "33e8af17-35c1-4165-a343-c1c86a320f3b",
"RetryIndicator": 0,
"ClientInfo": {
"ShopInfo": "My Shop",
"OsInfo": "Windows Server 2013"
}
},
"TerminalId": "12341234",
"Payment": {
"Amount": {
"Value": "100",
"CurrencyCode": "CHF"
},
"OrderId": "OrderId",
"Description": "Description",
"PayerNote": "Payernote"
},
"Payer": {
"IpAddress": "111.111.111.111",
"LanguageCode": "de"
},
"ReturnUrls": {
"Success": "HTTPS://merchanthost/success",
"Fail": "HTTPS://merchanthost/fail",
"Abort": "HTTPS://merchanthost/abort"
},
"Styling": {
"CssUrl": "HTTPS://my-shop.com/styling.css"
},
}
With PaymentMeans: {
"RequestHeader": {
"SpecVersion": "1.3",
"CustomerId": "123123",
"RequestId": "33e8af17-35c1-4165-a343-c1c86a320f3b",
"RetryIndicator": 0,
"ClientInfo": {
"ShopInfo": "My Shop",
"OsInfo": "Windows Server 2013"
}
},
"TerminalId": "12341234",
"Payment": {
"Amount": {
"Value": "100",
"CurrencyCode": "CHF"
},
"OrderId": "OrderId",
"Description": "Description",
"PayerNote": "Payernote",
"MandateId": "O6E1ItArnhWpvAMGMEh2Ar9zbjtA"
},
"PaymentMeans": {
"Card": {
"Number": "1234123412341234",
"ExpYear": 2015,
"ExpMonth": 9,
"HolderName": "John Doe"
}
},
"Payer": {
"IpAddress": "111.111.111.111",
"LanguageCode": "de"
},
"ReturnUrls": {
"Success": "HTTPS://merchanthost/success",
"Fail": "HTTPS://merchanthost/fail",
"Abort": "HTTPS://merchanthost/abort"
}
}
© SIX 2017 Page 22
4.2.3 Initialize Response
The response to the initial call may contain the following parameters:
Parameter Type Use Format Description
ResponseHeader ResponseHeader m Container Contains basic information on the response.
Token String m Id[1..50] Initialization ID for the later payment.
RedirectRequired Boolean m true^false Indicates whether the client needs to be redirected for 3DS and/or DCC.
Expiration Datetime m ans[1..30] Expiry date of the token according to ISO 8601. The token can no longer be used after it expires.
LiabilityShift Boolean o true^false Indicates whether there is a formal liability shift for the payment.
Redirect Redirect o / m, wenn RedirectRequired=true
Container Contains the URL for the redirecting of the client for the 3DS and/or DCC ser-vices.
Example Initialize Response {
"ResponseHeader": {
"SpecVersion": "1.3",
"RequestId": "33e8af17-35c1-4165-a343-c1c86a320f3b"
},
"Token": "234uhfh78234hlasdfh8234e",
"Expiration": "2014-11-20T08:58:42.304+1:00",
"RedirectRequired": true,
"LiabilityShift": false,
"Redirect": { "Redirec-
tUrl":https://www.saferpay.com/VT2/Api/ThreeDs/123456/12341234/234uhfh78234hlasdfh8234e",
"PaymentMeansRequired": true
}
}
4.3 Browser Redirect (PaymentMeansRequired: false)
If the Initialize Response delivers the value "true" for parameter RedirectRequiredand delivers the value "false" for parameter PaymentMeansRequired, the client simply needs to be redirected to the link in-cluded with RedirectUrl in order to process the 3DS and DCC services. The client is then directed back to the return address for the shop set in the ReturnUrls container.
4.4 Hosted Form (PaymentMeansRequired: true)
In the event that both parameters RedirectRequired and PaymentMeansRequired are "true" in the Initia-lize Response, the card data must to be transmitted to the link included with RedirectUrl to process the 3DS and DCC services.
The client will then be directed back to the shop via the return address set in the ReturnUrls container.
© SIX 2017 Page 23
4.4.1 Integration of the Credit Card Form in the Iframe
The PCI rules according to PCI DSS version 3 SAQ-A stipulate that the credit card data must no longer be captured by the merchant system.
For this reason, the Saferpay JSON API uses Hosted Register Form which can integrate into your applica-tion via HTML Iframe.
To do this, only the RedirectUrl included in section 3.2.3 needs to be entered as an address in the Iframe.
4.4.2 Example HTML Form
<HTML>
<head>
<title>Payment Form</title>
</head>
<body>
<h1>Payment Form</h1>
<iframe src= "<%= RedirectUrl %>">
</iframe>
</body>
</HTML>
4.4.3 Features of the Form
The new form provides you with two important features of use for integration and subsequent authorizati-on:
- CVC Caching:
Because the credit card data is now entered directly through the Saferpay system, we can save
the card verification code (CVC) for you so that it can be used for subsequent authorization.
PLEASE NOTE: Permanent storage of the CVC is not permitted even for units with full PCI certifi-
cation. For this reason, Saferpay caches the CVC only for up to 20 minutes.
After this time has elapsed or once authorization has been carried out, the CVC is deleted.
- CSS Styling:
The design of the Iframe form can be adjusted to your requirements through a CSS.
You will find more information in section 5.
4.4.4 Return to Shop
After the cardholder has entered all the required information for 3DS and/or DCC, the cardholder will be ta-ken back to the shop via the browser depending on the outcome (success, rejection or cancellation).
Please note that the buyer is also returned within the HTML Iframe. If this is not desired, then exit from the Iframe is to be envisaged.
Please note! To ensure that the return addresses have not been changed over with fraudulent inten-tions (e.g. swapping the FailUrl for the SuccessUrl), the payment should always be authorized after the buyer is returned to the shop's success page. This elicits a meaningful response, either a confir-mation or a rejection.
© SIX 2017 Page 24
4.4.5 Example Exit from the Iframe
<HTML>
<head>
<title>Success Page</title>
<script language="JavaScript" type="text/javascript">
function iframe_breakout()
{
if (top.location != location){
top.location.href = document.location.href;
}
}
</script>
</head>
<body onload="iframe_breakout()">
SOME CODE…
</body>
</HTML>
4.5 Authorization
Payments are authorized via the URL described in section 2.1.
4.5.1 Authorize Request
After the cardholder has been directed back to the shop, the actual card authorization takes place. The following parameters are available to this end:
Parameter Type Use Format Description
RequestHeader RequestHeader m Container Contains basic information on the request.
Token String m Id[1..50] ID of the Initialize Response
Condition String o Predefined Values Ensures that an Authorize Request is only made if there is a formal lia-bility shift. Is ignored if no 3DS contract is in place for the used payment means. Value: "WITH_LIABILITY_SHIFT"
VerificationCode String o n[3..4] Contains the card verification code. As a rule, the CVC is no longer re-quired at this point as it was sub-mitted with Initialize.
RegisterAlias RegisterAlias o Container For saving the card data in Secure Card Data. PLEASE NOTE: Please pay attention to section 8.20!
© SIX 2017 Page 25
4.5.2 Example Authorize Request
{
"RequestHeader": {
"SpecVersion": "1.3",
"CustomerId": 123123,
"RequestId": "33e8af17-35c1-4165-a343-c1c86a320f3b",
"RetryIndicator": 0,
"ClientInfo": {
"ShopInfo": "My Shop",
"OsInfo": "Windows Server 2013"
}
},
"Token": "234uhfh78234hlasdfh8234e",
"VerificationCode": "123",
"RegisterAlias": {
"IdGenerator": "MANUAL",
"Id": "Id",
"Lifetime": 1000
}
}
4.5.3 Authorize Response
The Authorize Response can contain the following parameters:
Parameter Type Use Format Description
ResponseHeader ResponseHeader m Container Contains basic information on the response.
Transaction Transaction m Container Contains information on the authorizati-on.
PaymentMeans PaymentMeansInfo m Container Contains information on the payment means.
RegistrationResult RegistrationResult o Container Contains information on the registration in SCD.
Payer PayerInfo o Container Contains information on the payer.
ThreeDs ThreeDsInfo o Container Contains information on 3-D Secure.
Dcc DccInfo o Container Contains information on Dynamic Cur-rency Conversion.
© SIX 2017 Page 26
4.5.4 Example of Authorize Response
{
"ResponseHeader": {
"SpecVersion": "1.3",
"RequestId": "33e8af17-35c1-4165-a343-c1c86a320f3b"
},
"Transaction": {
"Type": "PAYMENT",
"Status": "AUTHORIZED",
"Id": "K5OYS9Ad6Ex4rASU1IM1b3CEU8bb",
"Date": "2011-09-23T14:57:23.02+01:00",
"Amount": {
"Value": "100",
"CurrencyCode": "CHF"
},
"OrderId": "OrderId",
"AcquirerName": "AcquirerName",
"AcquirerReference": "AcquirerReference"
},
"PaymentMeans": {
"Brand": {
"PaymentMethod": 6,
"Name": "SaferpayTestCard"
},
"DisplayText": "9123 45xx xxxx 1234",
"Card": {
"MaskedNumber": "912345xxxxxx1234",
"ExpYear": 2016,
"ExpMonth": 9,
"HolderName": "John Doe",
"CountryCode": "CH"
}
},
"RegistrationResult": {
"Success": true,
"Alias": {
"Id": "AliasId",
"Lifetime": "1000"
}
},
"Payer": {
"IpAddress": "111.111.111.111",
"IpLocation": "NZ"
},
"ThreeDs": {
"Authenticated": true,
"LiabilityShift": true,
"Xid": "ARkvCgk5Y1t/BDFFXkUPGX9DUgs=",
"VerificationValue": "AAABBIIFmAAAAAAAAAAAAAAAAAA="
}
}
© SIX 2017 Page 27
4.6 Authorization without initialization
Transactions can be executed directly and without initialization or redirection using this function.
Payments can be authorized directly via the URL described in section 2.1.
4.6.1 Difference between Initialize and AuthorizeDirect
Initialize is the standard method for initializing payments. The method should be given preference in the following cases:
1.) For 3-D Secure transactions. This are available only if Initialize is used.
Use of 3-D Secure is recommended in all circumstances!
2.) For Dynamic Currency Conversion transactions. This function is also available only with Initialize.
3.) For PCI-compliant entry of card details. for PCI-compliant entry of card details, the Hosted Form
described in section 3.4 must be used. The URL required for this can only be obtained through Ini-
tialize.
Cases where Authorize Direct can be used:
1.) One Click/Direct-Payments. In some cases, the main priority is user convenience, so the interme-
diate steps 3DS and DCC are dispensed with. Payments of this kind are particularly attractive for
Android or iOS apps that enable the client to pay in one step.
Please note that we at SIX generally recommend carrying out at least the first transaction with a
new card using 3-D Secure, in order to minimize the risk of fraud.
The following must also be noted in the case of AuthorizeDirect transactions:
a) The transactions described are generally effected without the use of 3DS and without the CVC. To
ensure they are not rejected by the processor, they should be executed via a terminal with a Mail
Phone Order contract.
The IT connection is made via a separate terminal ID. To conclude such a contract, please contact Saferpay Sales, or your contact for contractual matters.
b) PCI-compliant entry of card details can be ensured through Secure Card Data.
For this purpose, Saferpay provides the option of registering a card alias through the Authorize
Request described in section 3.5 and keeping the alias safe for a subsequent payment. Alterna-
tively, the alias can be registered directly and without payment in Secure Card Data, as described
in section 4.
© SIX 2017 Page 28
4.6.2 AuthorizeDirect Request
For authorization without prior initialization, the following parameters are available:
Parameter Type Use Format Description
RequestHeader RequestHeader m Container Contains basic information on the request.
TerminalId String m An[8] Identification of the used terminal
Payment Payment m Container Contains information on the payment.
PaymentMeans PaymentMeans m Container Contains information on the payment means.
RegisterAlias RegisterAlias o Container For saving the card data in Secure Card Data.
Payer Payer o Container Contains information on the payer.
4.6.3 Example AuthorizeDirect Request
{
"RequestHeader": {
"SpecVersion": "1.3",
"CustomerId": 123123,
"RequestId": "7b09c4af-e28a-4f32-9386-1b06490238ec",
"RetryIndicator": 0,
"ClientInfo": {
"ShopInfo": "My Shop",
"OsInfo": "Windows Server 2013"
}
},
"TerminalId": "12341234",
"Payment": {
"Amount": {
"Value": "100",
"CurrencyCode": "CHF"
},
"OrderId": "OrderId",
"Description": "Description",
"PayerNote": "PayerNote"
},
"PaymentMeans": {
"Card": {
"Number": "1234123412341234",
"ExpYear": 2015,
"ExpMonth": 7,
"HolderName": "John Doe",
"VerificationCode": "123"
}
},
"RegisterAlias": {
"IdGenerator": "MANUAL",
"AliasId": "AliasId",
"LifeTime": 1000
},
"Payer": {
"IpAddress": "10.1.1.1"
}
}
© SIX 2017 Page 29
4.6.4 AuthorizeDirect Response
The Authorize Response can contain the following parameters:
Parameter Type Use Format Description
ResponseHeader ResponseHeader m Container Contains basic information on the response.
Transaction Transaction m Container Contains information on the authori-zation.
PaymentMeans PaymentMeansInfo m Container Contains information on the payment means.
RegistrationResult RegistrationResult o Container Contains information on the registra-tion in SCD.
Payer PayerInfo o Container Contains information on the payer.
4.6.5 Example AuthorizeDirect Response
{
"ResponseHeader": {
"SpecVersion": "1.3",
"RequestId": "33e8af17-35c1-4165-a343-c1c86a320f3b"
},
"Transaction": {
"Type": "PURCHASE", "Status": "AUTHORIZED",
"Id": "K5OYS9Ad6Ex4rASU1IM1b3CEU8bb",
"Date": "2011-09-23T14:57:23.023Z",
"Amount": {
"Value": "100",
"CurrencyCode": "CHF"
},
"OrderId": "OrderId",
"AcquirerName": "AcquirerName",
"AcquirerReference": "AcquirerReference"
},
"PaymentMeans": {
"Brand": {
"PaymentMethod": 6,
"Name": "SaferpayTestCard"
},
"DisplayText": "9123 45xx xxxx 1234",
"Card": {
"MaskedNumber": "912345xxxxxx1234",
"ExpYear": 2015,
"ExpMonth": 9,
"HolderName": "John Doe",
"CountryCode": "CH"
}
},
"RegistrationResult": {
"Success": true,
"AliasId": "AliasId"
},
"Payer": {
"IpAddress": "111.111.111.111",
"IpLocation": "NZ"
}
}
© SIX 2017 Page 30
4.6.6 ELV via AuthorizeDirect
Because no PCI rules apply to the electronic direct debit procedure (ELV), a bank account can be entered directly. Use of one's own HTML form and the subsequent payment request are permitted. For this, the bank account, with the BankAccount parameter in the PaymentMeans container, must be passed to Autho-rizeDirect.
4.6.7 Example ELV AuthorizeDirect Request:
{
"RequestHeader": {
"SpecVersion": "1.3",
"CustomerId": 123123,
"RequestId": "7b09c4af-e28a-4f32-9386-1b06490238ec",
"RetryIndicator": 0,
"ClientInfo": {
"ShopInfo": "My Shop",
"OsInfo": "Windows Server 2013"
}
},
"TerminalId": "12341234",
"Payment": {
"Amount": {
"Value": "100",
"CurrencyCode": "EUR"
},
"OrderId": "OrderId",
"Description": "Description",
"PayerNote": "PayerNote",
"MandateId": "O6E1ItArnhWpvAMGMEh2Ar9zbjtA"
},
"PaymentMeans": {
"BankAccount": {
"CountryCode": "DE",
"IBAN": "DE12500105170648489890",
"BIC": "INGDDEFFXXX",
"HolderName": "John Doe"
}
},
"Payer": {
"IpAddress": "10.1.1.1"
}
}
© SIX 2017 Page 31
4.6.8 Example ELV AuthorizeDirect Response:
{
"ResponseHeader": {
"SpecVersion": "1.3",
"RequestId": "33e8af17-35c1-4165-a343-c1c86a320f3b"
},
"Transaction": {
"Type": "PAYMENT", "Status": "AUTHORIZED",
"Id": "K5OYS9Ad6Ex4rASU1IM1b3CEU8bb",
"Date": "2011-09-23T14:57:23.023Z",
"Amount": {
"Value": "100",
"CurrencyCode": "EUR"
},
"OrderId": "OrderId",
"AcquirerName": "Lastschrift InterCard SEPA",
"AcquirerReference": "0e3f8ec3-1a4e-4916-8c31-609552278a0a"
},
"PaymentMeans": {
"Brand": {
"PaymentMethod": 13,
"Name": "Lastschrift"
},
"DisplayText": "DE12 5001 05xx xxxx xx98 90",
"BankAccount": {
"CountryCode": "DE",
"IBAN": "DE12500105170648489890",
"BIC": "INGDDEFFXXX",
"HolderName": "John Doe"
}
},
"Payer": {
"IpAddress": "111.111.111.111",
"IpLocation": "NZ"
}
}
© SIX 2017 Page 32
4.7 Recurring Payments
The recurring payments facility is of particular interest for ABO systems. The process is instigated through an initial payment. The payment may be made through Initialize or the payment page. The main thing to remember is that this first transaction needs to be flagged as an initial payment, as it is referenced and used for subsequent transactions. This creates a kind of trail.
4.7.1 Request Initial Payment
The following parameters are available for the initial call.
Parameter Type Use Format Description
RequestHeader RequestHeader m Container Contains basic information on the requ-est.
TerminalId String m an[8] Identification of the used terminal.
Payment Payment m Container Contains information on the payment. The container contains the relevant RECURRING flag among other things.
PaymentMeans PaymentMeans o Container Contains information on the payment means used.
Payer Payer o Container Contains information on the client.
ReturnUrls ReturnUrls m Container Contains the return addresses for the merchant system in the case of forwar-ding by 3DS or DCC.
Styling Styling o Container Contains all the information for the CSS styling feature
4.7.2 Examples Initialize Request
{
"RequestHeader": {
"SpecVersion": "1.3",
"CustomerId": "123123",
"RequestId": "33e8af17-35c1-4165-a343-c1c86a320f3b",
"RetryIndicator": 0,
"ClientInfo": {
"ShopInfo": "My Shop",
"OsInfo": "Windows Server 2013"
}
},
"TerminalId": "12341234",
"Payment": {
"Amount": {
"Value": "100",
"CurrencyCode": "CHF"
},
"RecurringOptions": {
"Initial": true },
"OrderId": "OrderId",
"Description": "Description",
"PayerNote": "Payernote"
},
"Payer": {
"IpAddress": "111.111.111.111",
"LanguageCode": "de"
},
"ReturnUrls": {
"Success": "HTTPS://merchanthost/success",
"Fail": "HTTPS://merchanthost/fail",
"Abort": "HTTPS://merchanthost/abort"
},
"Styling": {
"CssUrl": "HTTPS://my-shop.com/styling.css"
},
}
© SIX 2017 Page 33
4.7.3 Subsequent Payments
It is important that you save the transaction ID of the initial payment. This is used to reference back to the initial payment for subsequent payments.
The subsequent payments are processed by means of their own request.
4.7.4 AuthorizeReferenced Request
This request carried out referenced authorization if a prior initial payment was effected.
Payments can be authorized directly via the URL described in section 2.1.
The following parameters are available for the call.
Parameter Type Use Format Description
RequestHeader RequestHea-der
m Container Contains basic information on the requ-est.
TerminalId String m an[8] Identification of the used terminal.
Payment Payment m Container Contains information on the payment. The container contains the relevant RECURRING flag among other things.
TransactionReference Transaction-Reference
o Container Contains all information on the refe-renced initial payment
4.7.5 Example AuthorizeReferenced Request
{
"RequestHeader": {
"SpecVersion": "1.3",
"CustomerId": 123123,
"RequestId": "7b09c4af-e28a-4f32-9386-1b06490238ec",
"RetryIndicator": 0,
"ClientInfo": {
"ShopInfo": "My Shop",
"OsInfo": "Windows Server 2013"
}
},
"TerminalId": "12341234",
"Payment": {
"Amount": {
"Value": "100",
"CurrencyCode": "CHF"
},
"OrderId": "OrderId",
"Description": "Description",
"PayerNote": "PayerNote"
},
"TransactionReference": {
"TransactionId": "K5OYS9Ad6Ex4rASU1IM1b3CEU8bb"
}
}
© SIX 2017 Page 34
4.7.6 AuthorizeReferenced Response
The Authorize Response can contain the following parameters:
Parameter Type Use Format Description
ResponseHeader ResponseHeader m Container Contains basic information on the response.
Transaction Transaction m Container Contains information on the authori-zation.
PaymentMeans PaymentMeansInfo m Container Contains information on the payment means.
Payer PayerInfo o Container Contains information on the payer.
4.7.7 Example AuthorizeReferenced Response
{
"ResponseHeader": {
"SpecVersion": "1.3",
"RequestId": "33e8af17-35c1-4165-a343-c1c86a320f3b"
},
"Transaction": {
"Type": "PURCHASE", "Status": "AUTHORIZED",
"Id": "K5OYS9Ad6Ex4rASU1IM1b3CEU8bb",
"Date": "2011-09-23T14:57:23.023Z",
"Amount": {
"Value": "100",
"CurrencyCode": "CHF"
},
"OrderId": "OrderId",
"AcquirerName": "AcquirerName",
"AcquirerReference": "AcquirerReference"
},
"PaymentMeans": {
"Brand": {
"PaymentMethod": 6,
"Name": "SaferpayTestCard"
},
"DisplayText": "9123 45xx xxxx 1234",
"Card": {
"MaskedNumber": "912345xxxxxx1234",
"ExpYear": 2015,
"ExpMonth": 9,
"HolderName": "John Doe",
"CountryCode": "CH"
}
},
"Payer": {
"IpAddress": "111.111.111.111",
"IpLocation": "NZ"
}
}
4.8 Redirect Payment Means
This function enables the processing of payment means such as PayPal, Postcard and others. When paying with a Redirect payment means, the buyer is directed via their browser to an external site operated by the payment means provider or their bank. The main difference in processing Redirect payment means compared to payment means which execute via Initialize and Authorize or AuthorizeDirect methods is that they end directly in a successful payment. Depending on the payment means, the payment is authori-zed directly or booked so that the client's account is debited immediately.
Redirect payments can be authorized directly via the URL described in section 2.1.
© SIX 2017 Page 35
4.8.1 Overview
4.8.2 RedirectPayment Request
The following parameters are available for the RedirectPayment call.
Parameter Type Use Format Description
RequestHeader RequestHeader m Container Contains basic information on the requ-est.
TerminalId String m an[8] Identification of the used terminal
Payment Payment m Container Contains information on the payment.
ServiceProvider String o Predifined Values
Contains information as to which Redi-rect payment means is being used (pro-vided the merchant has an active pay-ment means contract with Saferpay). Possible values: PAYPAL, POST-FINANCE, POSTCARD
Payer Payer o Container Contains information on the client.
ReturnUrls ReturnUrls m Container Contains the return addresses for the client to the web shop.
Styling Styling o Container Contains all the information for the CSS styling feature
© SIX 2017 Page 36
4.8.3 Example RedirectPayment Request
{
"RequestHeader": {
"SpecVersion": "1.3",
"CustomerId": "123123",
"RequestId": "33e8af17-35c1-4165-a343-c1c86a320f3b",
"RetryIndicator": 0,
"ClientInfo": {
"ShopInfo": "My Shop",
"OsInfo": "Windows Server 2013"
}
},
"TerminalId": "12341234",
"Payment": {
"Amount": {
"Value": "100",
"CurrencyCode": "CHF"
},
"OrderId": "OrderId",
"Description": "Description"
},
"ServiceProvider": "PAYPAL",
"Payer": {
"IpAddress": "111.111.111.111",
"LanguageCode": "de"
},
"ReturnUrls": {
"Success": "HTTPS://merchanthost/success",
"Fail": "HTTPS://merchanthost/fail",
"Abort": "HTTPS://merchanthost/abort"
}
}
© SIX 2017 Page 37
4.8.4 RedirectPayment Response
The response to the Redirect payment request may contain the following parameters:
Parameter Type Use Format Description
ResponseHeader Respon-seHeader
m Container Contains basic information on the response.
Token String m Id[1..50] Initialization ID for the later pay-ment.
Expiration Datetime m ans[1..30] Token's expiry date The token can no longer be used after it expires.
RedirectUrl String m ans[1..128] Contains the URL for redirecting the client.
4.8.5 Example RedirectPayment Response
{
"ResponseHeader": {
"SpecVersion": "1.3",
"RequestId": "33e8af17-35c1-4165-a343-c1c86a320f3b"
},
"Token": "234uhfh78234hlasdfh8234e",
"Expiration": "2011-07-14T19:43:37Z",
"RedirectUrl":
"https://www.saferpay.com/VT2/RedirectPayment/1234/12341234/234uhfh78234hlasdfh8234e"
}
4.8.6 Browser Redirect
The client is simply redirected to the link transmitted with RedirectUrl.
Note: Not all payment means processors permit their pages to be loaded in a frame.
4.8.7 Return to Shop
Depending on the payment outcome, the buyer is returned to the shop via a return address transmitted to Saferpay in the ReturnUrls container.
4.8.8 Assert Redirect Payment Request
Using this function, the outcome of a Redirect payment can be checked and the result can be determined.
Registrations can be checked via the URL described in section 2.1.
The following parameters are required:
Parameter Type Use Format Description
RequestHeader RequestHeader m Container Contains basic information on the request.
Token String m Id [1..50] ID for the registration delivered with the Redi-rectPayment response.
Please note! To ensure that the return addresses have not been changed over with fraudulent inten-tions (e.g. swapping the FailUrl for the SuccessUrl), Assert Redirect Payment Request should always be used after the buyer is returned to the shop's success page. This elicits a meaningful response, either a confirmation or a rejection.
© SIX 2017 Page 38
4.8.9 Example Assert Redirect Payment Request
{
"RequestHeader": {
"SpecVersion": "1.3",
"CustomerId": "123123",
"RequestId": "33e8af17-35c1-4165-a343-c1c86a320f3b",
"RetryIndicator": 0,
"ClientInfo": {
"ShopInfo": "My Shop",
"OsInfo": "Windows Server 2013"
}
},
"Token": "234uhfh78234hlasdfh8234e"
}
4.8.10 Assert Redirect Payment Response
The AssertInsert Response delivers the following parameters:
Parameter Type Use Format Description
ResponseHeader ResponseHeader m Container Contains basic information on the response.
Transaction Transaction m Container Contains information on the authori-zation.
PaymentMeans PaymentMeansInfo m Container Contains information on the saved payment means.
Payer PayerInfo o Container Contains information on the client.
4.8.11 Example Assert Redirect Payment Response
{
"RequestHeader": {
"SpecVersion": "1.3",
"CustomerId": "123123",
"RequestId": "33e8af17-35c1-4165-a343-c1c86a320f3b",
"RetryIndicator": 0,
"ClientInfo": {
"ShopInfo": "My Shop",
"OsInfo": "Windows Server 2013"
}
},
"Transaction": {
"Type": "PAYMENT",
"Status": "AUTHORIZED",
"Id": "nlj7UUbljO2ttA3n494rAE3b2brb",
"Date": "21015-05-12T12:02:24+2:00",
"Amount": {
"Value": "100",
"CurrencyCode": "CHF"
},
"AcquirerName": "PostFinance Card",
"AcquirerReference": "PostFinance Card",
},
"PaymentMeans": {
"Amount": {
"PaymentMethod": 10,
"Name": "Postcard"
},
"DisplayText": "Postcard",
},
"Payer": {
"IpAddress": "111.111.111.111"
},
}
© SIX 2017 Page 39
4.9 Credits
Credits can be made via the URL described in section 2.1.
4.9.1 Refund Request
Using this function, credits can be triggered with reference to existing payments. The following parameters are available for this purpose:
Parameter Type Use Format Description
RequestHeader RequestHeader m Container Contains basic information on the request.
Refund Refund m Container Contains the payment details for the credit.
TransactionReference TransactionReference m Container Contains a reference to the un-derlying payment.
4.9.2 Example Refund Request
{
"RequestHeader": {
"SpecVersion": "1.3",
"CustomerId": 123123,
"RequestId": "7b09c4af-e28a-4f32-9386-1b06490238ec",
"RetryIndicator": 0,
"ClientInfo": {
"ShopInfo": "My Shop",
"OsInfo": "Windows Server 2013"
}
},
"Refund": {
"Description": "Description",
"Amount": {
"Value": "100",
"CurrencyCode": "CHF"
},
"OrderId": "OrderId"
},
"TransactionReference": {
"TransactionId": "Id"
}
}
PLEASE NOTE! With some processors, referenced refunds may be declined if the batch close was not processed previously. Therefore, please ensure that the batch close was processed for referenced transactions. Otherwise, please cancel the transaction using Cancel Request (section 6.1). If you use the automatic batch close, this is processed daily at approx. 10 pm. We recommend mat-ching of the referenced transactions with a time stamp. Alternatively, the JSON API provides the option of activating the batch close yourself using Close Request (section 7.1). for this, please ensure here that the automatic batch close is deactivated in Saferpay Backoffice and the transactions flagged accordingly in your system.
© SIX 2017 Page 40
4.9.3 Refund Response
Parameter Type Use Format Description
ResponseHeader ResponseHeader m Container Contains basic information on the response.
Transaction Transaction m Container Contains information on the authori-zation.
PaymentMeans PaymentMeansInfo m Container Contains information on the payment means.
Dcc DccInfo o Container Contains information on Dynamic Currency Conversion.
4.9.4 Example Refund Request
{
"ResponseHeader": {
"SpecVersion": "1.3",
"RequestId": "33e8af17-35c1-4165-a343-c1c86a320f3b"
},
"Transaction": {
"Type": "REFUND", "Status": "AUTHORIZED",
"Id": "K5OYS9Ad6Ex4rASU1IM1b3CEU8bb",
"Date": "2011-09-23T14:57:23.023Z",
"Amount": {
"Value": "100",
"CurrencyCode": "CHF"
},
"OrderId": "OrderId",
"AcquirerName": "AcquirerName",
"AcquirerReference": "AcquirerReference"
},
"PaymentMeans": {
"Brand": {
"PaymentMethod": 10,
"Name": "SaferpayTestCard"
},
"DisplayText": "912345xxxxxx1234",
"Card": {
"MaskedNumber": "912345xxxxxx1234",
"ExpYear": 2015,
"ExpMonth": 9,
"HolderName": "John Doe",
"CountryCode": "CH"
}
},
"Dcc": {
"PaymentAmount": {
"Value": "134",
"CurrencyCode": "NZD"
}
}
}
© SIX 2017 Page 41
4.9.5 RefundDirect Request
Using this function, credits can be triggered without a preceding payment having been made with the pay-ment means to be used. The following parameters are available:
Parameter Type Use Format Description
RequestHeader RequestHeader m Container Contains basic information on the request.
TerminalId String m An[8] Identification of the used ter-minal.
Refund Refund m Container Contains the payment details for the credit.
Alias Alias m Container Contains Secure Card Data in-formation on the card data to be saved.
PaymentMeans PaymentMeans m Container Contains information on the payment means.
4.9.6 Example RefundDirect Request
{
"RequestHeader": {
"SpecVersion": "1.3",
"CustomerId": 123123,
"RequestId": "7b09c4af-e28a-4f32-9386-1b06490238ec",
"RetryIndicator": 0,
"ClientInfo": {
"ShopInfo": "My Shop",
"OsInfo": "Windows Server 2013"
}
},
"TerminalId": "12341234",
"Refund": {
"Description": "Description",
"Amount": {
"Value": "100",
"CurrencyCode": "CHF"
},
"OrderId": "OrderId"
},
"PaymentMeans": {
"Card": {
"Number": "1234123412341234",
"ExpYear": 2015,
"ExpMonth": 7,
"HolderName": "John Doe",
"VerificationCode": "123"
}
}
}
PLEASE NOTE! Use of payment means is per-mitted only with full PCI certification. In there is any doubt, the alias should always be used.
© SIX 2017 Page 42
4.9.7 RefundDirect Response
Parameter Type Use Format Description
ResponseHeader ResponseHeader m Container Contains basic information on the response.
Transaction Transaction m Container Contains information on the authori-zation.
PaymentMeans PaymentMeansInfo m Container Contains information on the payment means.
4.9.8 Example RefundDirect Response
{
"ResponseHeader": {
"SpecVersion": "1.3",
"RequestId": "33e8af17-35c1-4165-a343-c1c86a320f3b"
},
"Transaction": {
"Type": "REFUND", "Status": "AUTHORIZED",
"Id": "K5OYS9Ad6Ex4rASU1IM1b3CEU8bb",
"Date": "2011-09-23T14:57:23.023Z",
"Amount": {
"Value": "100",
"CurrencyCode": "CHF"
},
"OrderId": "OrderId",
"AcquirerName": "AcquirerName",
"AcquirerReference": "AcquirerReference"
},
"PaymentMeans": {
"Brand": {
"Id": 42,
"Name": "SaferpayTestCard"
},
"DisplayText": "912345xxxxxx1234",
"Card": {
"MaskedNumber": "912345xxxxxx1234",
"ExpYear": 2015,
"ExpMonth": 9,
"HolderName": "John Doe",
"CountryCode": "CH"
}
}
}
© SIX 2017 Page 43
5 Booking of a Payment Each authorized transaction is initially given the status "Reservation" by Saferpay. With this status, the card has been authorized for the stated amount, but the money cannot yet be transferred via the daily clo-sing process.
Reservations can be booked via the URL described in section 2.1.
5.1 Capture Request
Parameter Type Use Format Description
RequestHeader RequestHeader m Container Contains basic information on the request.
TransactionReference TransactionReference m Container Contains a reference to the re-servation.
Amount Amount m Container Contains the amount to be booked, whereby the currency must correspond to the authoriza-tion. As a rule, the amount may be reduced but not increased!
5.2 Example Capture Request
{
"RequestHeader": {
"SpecVersion": "1.3",
"CustomerId": 123123,
"RequestId": "5e9adf9e-7468-4dff-9dfb-6c99d8e43acb",
"RetryIndicator": 0,
"ClientInfo": {
"ShopInfo": "My Shop",
"OsInfo": "Windows Server 2013"
}
},
"TransactionReference": {
"TransactionId": "qiuwerhfi23h4189asdhflk23489"
},
"Amount": {
"Value": "50",
"CurrencyCode": "CHF"
}
}
5.3 Capture Response
The following parameters can be included in the Capture Response:
Parameter Type Use Format Description
ResponseHeader ResponseHeader m Container Contains basic information on the response.
TransactionId String m an[1..64] Contains the Saferpay transaction ID.
OrderId String o Id[1..80] Contains the order number.
Date DateTime m ans[1..30] Contains the date and time of the booking.
© SIX 2017 Page 44
5.4 Example Capture Response
{
"ResponseHeader": {
"SpecVersion": "1.3",
"RequestId": "d4dcf2f6-ddc1-4e2c-8b13-290a3eb09dbf"
},
"TransactionId": "qiuwerhfi23h4189asdhflk23489",
"OrderId": "OrderId",
"Date": "2014-04-25T08:33:44.159Z"
}
© SIX 2017 Page 45
6 Cancellation of a Payment A reservation can be rejected or a booking can be cancelled provided that it was not processed during daily closing. The process here is the same. If this involves a reservation, the transaction is only displayed in Saferpay Backoffice for a further six days under "rejected reservations" after being rejected. It is then deleted from the database. Cancelled boo-kings, however, remain visible and marked in Backoffice as cancelled.
Transactions can be cancelled via the URL described in section 2.1.
6.1 Cancel Request
Parameter Type Use Format Description
RequestHeader RequestHeader m Container Contains basic information on the request.
TransactionReference TransactionReference m Container Contains a reference to the transaction
6.2 Example Cancel Request
{
"RequestHeader": {
"SpecVersion": "1.3",
"CustomerId": 123123,
"RequestId": "5e9adf9e-7468-4dff-9dfb-6c99d8e43acb",
"RetryIndicator": 0,
"ClientInfo": {
"ShopInfo": "My Shop",
"OsInfo": "Windows Server 2013"
}
},
"TransactionReference": {
"TransactionId": "qiuwerhfi23h4189asdhflk23489"
}
}
6.3 Cancel Response
The following parameters can be included in the Cancel Response message:
Parameter Type Use Format Description
ResponseHeader ResponseHeader m Container Contains basic information on the response.
TransactionId String m an[1..64] Contains the Saferpay transaction ID.
OrderId String o Id[1..80] Contains the order number.
Date DateTime m ans[1..30] Contains the date and time of the cancellation.
6.4 Example Cancel Response
{
"ResponseHeader": {
"SpecVersion": "1.3",
"RequestId": "d4dcf2f6-ddc1-4e2c-8b13-290a3eb09dbf"
},
"TransactionId": "qiuwerhfi23h4189asdhflk23489",
"OrderId": "OrderId",
"Date": "2014-04-25T08:33:44.159Z"
}
© SIX 2017 Page 46
7 Daily Closing Using this method, Saferpay can be instructed to complete the daily closing for a terminal.
Daily closing can be initiated via the URL described in section 2.1.
The use of this function is only recommended if the automatic daily closing process activated via Saferpay Backoffice is not feasible at 10 p.m. Daily closing needs to be performed only once within a 24 hour period.
7.1 Close Request
The following parameters are required to call up the daily closing process:
Parameter Type Use Format Description
RequestHeader RequestHeader m Container Contains basic information on the request.
TerminalId String m an[8] Identification of the used terminal.
7.2 Example Close Request
{
"RequestHeader": {
"SpecVersion": "1.3",
"CustomerId": 123123,
"RequestId": "7b09c4af-e28a-4f32-9386-1b06490238ec",
"RetryIndicator": 0,
"ClientInfo": {
"ShopInfo": "My Shop",
"OsInfo": "Windows Server 2013"
}
},
"TerminalId": "12341234"
}
7.3 Close Response
The response to the daily closing instruction contains the following container:
Parameter Type Use Format Description
ResponseHeader ResponseHeader m Container Contains basic information on the response.
7.4 Example Close Response
{
"ResponseHeader": {
"SpecVersion": "1.3",
"RequestId": "d4dcf2f6-ddc1-4e2c-8b13-290a3eb09db"
}
}
© SIX 2017 Page 47
8 Secure Card Data Saferpay Secure Card Data, or SCD for short, is a service for saving sensitive payment means information in the certified Saferpay data center. By using SCD, the payment means data is separated from the mer-chant application and no longer comes into contact with it. Secure Card Data is suitable for shop systems, call center solutions, inventory management, ERP and CRM systems.
8.1 Supported Payment Means
The following payment means can currently be processed using Saferpay Secure Card Data:
Visa
MasterCard
Maestro international
V PAY
American Express
Diners Club
JCB
PostFinance e-finance
PostFinance card
8.2 Registration of Alias via a Form
The registration process takes place via a HTML form which transfers the payment means information to Saferpay. Here, the received payment means data is verified and only saved in SCD in successful cases. Integration of the form in an Iframe is supported.
Payment means data can be registered via the URL described in section 2.1.
8.2.1 Insert Request
Using this method, aliases can be saved in SCD without the merchant system coming into contact with the payment means data. The table lists the parameters available for this purpose:
Parameter Type Use Format Description
RequestHeader RequestHeader m Container Contains basic information on the request.
RegisterAlias RegisterAlias m Container Information on the saving of the card data in Secure Card Data. PLEASE NOTE: Please pay attention to section 11.28!
Type String, RegisterType
m Predefined Values
Indicates which payment means type is sa-ved in SCD. Value: "POSTFINANCE"
ReturnUrls ReturnUrls m Container Contains the return addresses to the mer-chant system.
Styling Styling o Container Contains all the information for the CSS styling feature
LanguageCode String o ans[2,5] Determines the language in which Safer-pay may need to display something to the payer. Value: two-digit code according to ISO 639-1 or five-digit code formed from a combina-tion of ISO 639-1 and ISO 3166, e.g. "de-ch"
© SIX 2017 Page 48
8.2.2 Example Insert Request
{
"RequestHeader": {
"SpecVersion": "1.3",
"CustomerId": 123123,
"RequestId": "5e9adf9e-7468-4dff-9dfb-6c99d8e43acb",
"RetryIndicator": 0,
"ClientInfo": {
"ShopInfo": "My Shop",
"OsInfo": "Windows Server 2013"
}
},
"RegisterAlias": {
"IdGenerator": "manual",
"Id": "ALIAS",
"Lifetime": "1000"
}, "Type": "CARD",
"ReturnUrls": {
"Success": "https://successurl", "Fail": "https://failedurl", "Abort": "https://aborturl" }, "Styling": {
"CssUrl": "https://my-shop.com/styling.css" }
}
8.2.3 Insert Response
The Insert Response can contain the following parameters:
Parameter Type Use Format Description
ResponseHeader ResponseHeader m Container Contains basic information on the response.
Token String m Id [1..50] ID for registration. Can only be used once for a successful registration.
Expiration Datetime m ans[1..30] Token's expiry date The token can no longer be used after it expires.
RedirectUrl String m ans[1..128] URL for redirection / the Iframe
8.2.4 Example Insert Response
{
"ResponseHeader": {
"SpecVersion": "1.3",
"RequestId": "5e9adf9e-7468-4dff-9dfb-6c99d8e43acb",
},
"Token": "K5OYS9Ad6Ex4rASU1IM1b3CEU8bb",
"Date": "2014-11-22T11:15:26.674+01:00",
"RedirectUrl":
"HTTPS://www.saferpay.com/VT2/InsertAlias/1234/12341234/234uhfh78234hlasdfh8234e" }
© SIX 2017 Page 49
8.2.5 Integration of the Credit Card Form in an Inline Frame
The PCI rules according to PCI DSS version 3 SAQ-A stipulate that the credit card date must no longer be captured by the merchant system.
For this reason, the Saferpay JSON API uses a Hosted Register Form which you can integrate into your application through an HTML Iframe.
To do this, you simply need to enter the RedirectURL contained in section 4.2.3 as the address in the Ifra-me.
8.2.6 Example HTML Form
<HTML>
<head>
<title>Register Form</title>
</head>
<body>
<h1>Register Form</h1>
<iframe src= "<%= RedirectUrl %>">
</iframe>
</body>
</HTML>
8.2.7 Properties of the Form
The design of the registration form can be adapted using CSS styling. Display of the registration form in an Iframe is supported. Details on CSS styling can be found in section 5. Unlike the Initialize method, caching of the CVC simply on registration is not supported because the CVC has to be deleted after 20 minutes and the authorization request may occur later than this.
8.2.8 Return to Shop
After the cardholder has entered all the required information, he will be taken back to the shop via the browser depending on the outcome (success, rejection, cancellation). Please note! To ensure that the return addresses have not been changed over by a skilled user with frau-dulent intentions (e.g. swapping the FailUrl for the SuccessUrl), an AssertInsert Request should always be used after the buyer is returned to the shop's success page. This always provides a reliable answer. Either successful registration will be confirmed or a meaningful error message will be transmitted.
Please note that the return also takes place within the HTML Iframe. If a problem should arise for any reason, then exit from the Iframe may need to be effected.
© SIX 2017 Page 50
8.2.9 Example Exit from the Iframe
<HTML>
<head>
<title>SUCCESS</title>
<script language="JavaScript" type="text/javascript">
function iframe_breakout()
{
if (top.location != location){
top.location.href = document.location.href;
}
}
</script>
</head>
<body onload="iframe_breakout()">
SOME CODE…
</body>
</HTML>
8.2.10 AssertInsert Request
Using this function, the outcome of a registration can be checked and the result can be determined.
Registrations can be checked via the URL described in section 2.1.
The parameters are required:
Parameter Type Use Format Description
RequestHeader RequestHeader m Container Contains basic information on the request.
Token String m Id [1..50] ID for the registration delivered with the Inse-rtResponse.
8.2.11 Example AssertInsert Request
{
"RequestHeader": {
"SpecVersion": "1.3",
"CustomerId": 123123,
"RequestId": "5e9adf9e-7468-4dff-9dfb-6c99d8e43acb",
"RetryIndicator": 0,
"ClientInfo": {
"ShopInfo": "My Shop",
"OsInfo": "Windows Server 2013"
}
},
"Token": "cspfxpj6mrqbeu0veobxsh8bo" }
© SIX 2017 Page 51
8.2.12 AssertInsert Response
The AssertInsert Response delivers the following parameters:
Parameter Type Use Format Description
ResponseHeader ResponseHeader m Container Contains basic information on the response.
Alias AliasInfo m Container Contains information on the saved alias.
PaymentMeans PaymentMeansInfo m Container Contains information on the saved payment means.
8.2.13 Example AssertInsert Response
{
"ResponseHeader": {
"SpecVersion": "1.3",
"RequestId": "5e9adf9e-7468-4dff-9dfb-6c99d8e43acb",
},
"Alias": {
"Id": "ALIAS",
"Lifetime": "1000"
},
"PaymentMeans": {
"Brand": { "PaymentMethod": 6,
"Name": "Saferpay Test Card" } "DisplayText": "912345xxxxxx1234", "Card": {
"MaskedNumber": "912345xxxxxx1234",
"ExpYear": 2015,
"ExpMonth": 9,
"HolderName": "John Doe",
"CountryCode": "CH"
} }
8.3 Registration with InsertDirect
Using this method, aliases can be saved directly in SCD. Here, the payment means data comes into direct contact with the merchant system.
This method should only be used if the merchant system has its own PCI certificate.
Registrations can be checked via the URL described in section 2.1.
8.3.1 InsertDirect Request
The following parameters are required for this method:
Parameter Type Use Format Description
RequestHeader RequestHeader m Container Contains basic information on the request.
RegisterAlias RegisterAlias m Container Contains information on the registra-tion of the alias.
PaymentMeans PaymentMeans m Container Contains information on the registra-tion of the payment means.
© SIX 2017 Page 52
8.3.2 Example InsertDirect Request
{
"RequestHeader": {
"SpecVersion": "1.3",
"CustomerId": 123123,
"RequestId": "7b09c4af-e28a-4f32-9386-1b06490238ec",
"RetryIndicator": 0,
"ClientInfo": {
"ShopInfo": "My Shop",
"OsInfo": "Windows Server 2013"
}
},
"RegisterAlias": {
"IdGenerator": "MANUAL",
"AliasId": "AliasId",
"LifeTime": 1000
},
"PaymentMeans": {
"Card": {
"Number": "1234123412341234",
"ExpYear": 2015,
"ExpMonth": 7,
"HolderName": "John Doe",
"VerificationCode": "123"
}
}
}
8.3.3 InsertDirect Response
The response to the request for direct registration delivers the following parameters:
Parameter Type Use Format Description
ResponseHeader ResponseHeader m Container Contains basic information on the response.
Alias AliasInfo m Container Contains information on the saved alias.
PaymentMeans PaymentMeansInfo m Container Contains information on the saved payment means.
8.3.4 Example InsertDirect Response
{
"ResponseHeader": {
"SpecVersion": "1.3",
"RequestId": "33e8af17-35c1-4165-a343-c1c86a320f3b"
},
"Alias": {
"Id": "ALIAS",
"Lifetime": "1000"
},
"PaymentMeans": {
"Brand": {
"PaymentMethod": 6,
"Name": "SaferpayTestCard"
},
"DisplayText": "Display Text",
"Card": {
"MaskedNumber": "912345xxxxxx1234",
"ExpYear": 2015,
"ExpMonth": 9,
"HolderName": "John Doe",
"CountryCode": "CH"
}
}
}
© SIX 2017 Page 53
8.4 Deleting an Alias
Using this method, an alias can be deleted from SCD prior to the expiry of the storage period.
Payment means data can be deleted via the URL described in section 2.1.
8.4.1 Delete Request
The following parameters are required for the deletion:
Parameter Type Use Format Description
RequestHeader RequestHeader m Container Contains basic information on the request.
AliasId String m Id[1..40] Alias of the card data in Secure Card Data.
8.4.2 Example Delete Request
{
"RequestHeader": {
"SpecVersion": "1.3",
"CustomerId": 123123,
"RequestId": "5e9adf9e-7468-4dff-9dfb-6c99d8e43acb",
"RetryIndicator": 0,
"ClientInfo": {
"ShopInfo": "My Shop",
"OsInfo": "Windows Server 2013"
}
},
"AliasId": "ALIAS" }
8.4.3 Delete Response
The response to the delete request contains the following container:
Parameter Type Use Format Description
ResponseHeader ResponseHeader m Container Contains basic information on the response.
8.4.4 Example Delete Response
{
"ResponseHeader": {
"SpecVersion": "1.3",
"RequestId": "33e8af17-35c1-4165-a343-c1c86a320f3b"
}
}
© SIX 2017 Page 54
9 CSS Styling
9.1 Size of the Inline frame
The width and height of the Iframe are passed on to the shop website via the HTML5 postMessage func-tion. The details are in pixels. JSON Example: {
"message":"css",
"height":450,
"width":650
}
Example of the message received (jQuery): $(window).bind("message", function (e) {
$("#iframe").css("height", e.originalEvent.data.height + "px");
});
As not every website transfers information with regard to its size, we would recommend defining a mini-mum height and width on the shop page.
9.2 Using CSS
The following information should be observed when adjusting the payment page or the Hosted Form with the help of CSS.
9.2.1 Element name
The element name may be used in accordance with CSS specifications. Example: h1{
text-decoration: underline;
}
9.2.2 Class name
The CSS class names defined by Saferpay in Section 5.4 should be used.
Example: .form-group
{
font-family: "Times New Roman", serif;
font-style: italic;
}
9.2.3 Element ID
The Element ID should not be used as the IDs can change without prior notice.
© SIX 2017 Page 55
9.2.4 Element attributes
Element attributes should not be used as the attributes (name, value, data*, etc.) can change without prior notice.
9.2.5 CSS selectors
All CSS selectors are generally supported for CSS1, CSS2 and CSS3.
9.2.6 Concluding notes
Please note that, if your own CSS file is used, this completely replaces the Saferpay standard CSS. If you do not have a CSS definition for certain elements in your file, then the element in question will be displayed without a style.
9.3 Important Information for Using CSS
The style sheet referred to with the CSSURL parameter must be stored on a web server that sup-ports HTTPS.
Graphics must be loaded within the style sheet via "HTTPS://", otherwise a warning appears in the browser. For example: "[…] this page includes other resources which are not secure. […].
We would recommend displaying a progress bar while loading the Iframe
and exiting the Iframe to go to the success, abort or fail page when returning to the shop (see sec-tions 3.4.5 and 4.2.9).
© SIX 2017 Page 56
9.4 CSS Class names
9.4.1 General Classes
HTML saferpay-paymentpage
Header img-logo
Footer btn-back
btn-abort
btn-next
navitem
navitem-back
navitem-abort
navitem-next
Display Boxes box-content
box-shop
box-information
box-success
box-error
box-information-required-fields
img-shop
text-information
text-success
text-error
icon-information
icon-success
icon-error Form
form-group
form-label
form-input
form-col-small
form-col-large
input-required
input-large
input-medium
input-small
icon-required
Form Validation validation-summary-errors
label-validation-error
input-validation-error
Basic Classes box
btn
img
icon
text
© SIX 2017 Page 57
9.4.2 Specifically for Payment Page
page-paymentselection
paymentgroup o paymentgroup-creditcard o paymentgroup-onlinebanking o paymentgroup-card o paymentgroup-onlinepaymentservice o paymentgroup-directdebit o paymentgroup-invoice o paymentgroup-wallet
btn-select
btn-creditcard-visa
btn-creditcard-mastercard
btn-creditcard-maestro
btn-creditcard-amex
btn-creditcard-jcb
btn-creditcard-dinersclub
btn-creditcard-saferpay
btn-onlinebanking-sofort
btn-onlinebanking-giropay
btn-onlinebanking-ideal
btn-onlinebanking-eps
btn-onlinebanking-post
btn-onlinebanking- eprzelewy
btn-card-myone
btn-card-bonuscard
btn-card-postcard
btn-card-lasercard
btn-directdebit-zvt
btn-directdebit-intercardelv
btn-directdebit-billpay
btn-invoice-billpay
btn-wallet-masterpass
9.4.3 Specifically for Card Form
page-card o page-creditcard-visa o page-creditcard-mastercard o page-creditcard-maestro o page-creditcard-amex o page-creditcard-jcb o page-creditcard-dinersclub o page-creditcard-saferpay o page-card-myone o page-card-bonuscard o page-card-postcard o page-card-lasercard
text-hint
icon-hint
9.4.4 Specifically for Direct Debit Form
page-directdebit o page-directdebit-billpay o page-directdebit-intercardelv o page-directdebit-zvt
© SIX 2017 Page 58
9.4.5 Specifically for Online Banking
page-onlinebanking o page-onlinebanking-ideal o page-onlinebanking-giropay
9.4.6 Specifically for Billing Form
page-invoice o page-invoice-billpay
9.4.7 Specifically for Address Form (incl. Billpay Address Form)
page-address
form-col-small
form-col-large
9.4.8 Specifically for GTC
page-termsandconditions
9.4.9 Specifically for Redirect Pages (incl. 3D-Secure)
page-redirect
9.4.10 Specifically for Error Pages
page-error
9.4.11 Specifically for Confirmation Page
page-confirmation
9.5 CSS Examples
Below are CSS example files for the payment page which you may use. However, please note these are only examples that have been drawn up for the Saferpay test account. SIX Payment Services makes no guarantees for live operation. However, you can use the examples as a basis for your own drafts.
Mobile:
https://www.six-payment-services.com/dam/saferpay/testaccount/css/mobile1.css -
Embedded:
https://www.six-payment-services.com/dam/saferpay/testaccount/css/embedded1.css https://www.six-payment-services.com/dam/saferpay/testaccount/css/embedded2.css
© SIX 2017 Page 59
10 Use of own HTML Form
As well as the Hosted Form, Saferpay provides the option of using your own HTML form for entry of pay-ment data. However, the following rules apply:
1. For the acceptance of credit cards, such as VISA and MasterCard, using your own HTML form is permitted only if the merchant system is at least certified according to PCI DSS3 SAQ-A EP. If this is not the case, the Hosted Form must be used.
2. In general, you can use your own HTML form only for the following payment means:
Visa
MasterCard
Maestro international
V PAY
American Express
Diners Club
J.C.B.
10.1.1 Redirection via POST
A HTML form with the following parameters is required for handling the transactions:
Parameter Type Use Format Description
RedirectURL URL m ans[1..128] Redirect URL from the Initiali-zeResponse for POST action.
HolderName String o ans[1..50] Input field for the cardholder name
CardNumber String m n[1..50] Input field for the card number
ExpMonth String m n[1..2] Input field for the month of ex-piry
ExpYear String m n[4] Input field for the year of expiry
VerificationCode String m n[3..4] Input field for the card verifica-tion code. Saferpay then stores the CVC for approximately 20 minutes in order to complete the pay-ment.
FromAjax Boolean o true^false Activates browser-server communication via AJAX so that Saferpay can send a di-rect response.
© SIX 2017 Page 60
10.1.2 Example HTML Form
<html>
<head>
<title>Credentials-Form</title>
</head>
<body>
<h1>Credentials Form</h1>
<form method="POST" action= "<%= RedirectUrl %>">
Karteninhabername
<input type="text" name="HolderName" size="20"><br />
Kartennummer
<input type="text" name="CardNumber" size="16"><br />
Gültig bis
<input type="text" name="ExpMonth" size="2">
<input type="text" name="ExpYear" size="2"><br />
Kartenprüfnummer
<input type="text" name="VerificationCode" size="4"><br />
<input type="submit" name="submit" value="purchase">
</form>
</body>
</html>
10.1.3 Data Transfer with AJAX
If browser-server communication via AJAX has been activated, the card data can be transmitted with an AJAX request. For this, the data to be transferred by POST must be encoded as www-form-url. The call is then responded to with the http status code 200 and the URL for the redirecting of the client in the browser or with an error response with the http status code 400 or higher (see section xxx "Error handling"). The latter can be displayed to the client with the request to check the card data. For this purpose, the browser must support JavaScript. This enables the card data to be checked before redirection. Success response with the http status code 200:
Parameter Type Use Format Description
RedirectURL URL m ans [1..128] URL for the redirecting of the client in the browser
The client must then be redirected in the browser to the RedirectURL to process the payment. Error response with the http status code 400 or higher:
Parameter Type Use Format Description
ErrorName String m an[1..50] Name or ID of the error
Behavior String m as[1..50] Information on how to proceed (RETRY_LATER , RETRY, ABORT…)
ErrorDetail o as[1..50] Further details (if available). (If, for example, the ErrorNa-me=VALIDATION_FAILED, Er-rorDetail includes a list with the invalid fields such as “Card-Number”, “ExpYear”, “Ex-pMonth”, etc.)
© SIX 2017 Page 61
10.1.4 Example of AJAX Transfer
HTML form:
<html>
<head>
<title>Credentials-Form</title>
</head>
<body>
<h1>Credentials Form</h1>
<form method="POST" action= "<%= RedirectUrl %>">
Karteninhabername
<input type="text" name="HolderName" size="20"><br />
Kartennummer
<input type="text" name="CardNumber" size="16"><br />
Gültig bis
<input type="text" name="ExpMonth" size="2">
<input type="text" name="ExpYear" size="2"><br />
Kartenprüfnummer
<input type="text" name="VerificationCode" size="4"><br />
<button>Submit</button>
</form>
</body>
</html>
JavaScript for jQuery (version 1.9 or above): $("#myForm").submit(function (e) {
// prevent normal (non-ajax) formular submission
e.preventDefault();
var formData = $(this).serializeArray();
// add flag to ensure AJAX handling on server
formData.push({ name: "FromAjax", value: true });
$.post($(this).attr("action"), $.param(formData))
// data has been posted successfully and user can be redirected
.done(function(data, textStatus, jqXHR) {
// NOTE: data is a json response
window.location.href = data.RedirectUrl;
})
// validation failed or server error occured
.fail(function(jqXHR, textStatus, errorThrown) {
// NOTE: use $.parseJSON(jqXHR.responseText) in order to try to get a json response
}); });
10.1.5 Return to Shop
After the cardholder has entered all the required information for 3DS and/or DCC, the cardholder will be ta-ken back to the shop via the browser depending on the outcome (success, rejection, cancellation). Please Note! To ensure that the return addresses have not been changed over by a skilled user with frau-dulent intentions (e.g. swapping the FailUrl for the SuccessUrl), the payment should always be authorized after the buyer is returned to the shop's success page. This always provides a reliable answer. Either a successful payment will be confirmed or a meaningful error message is transmitted. The merchant application only automatically receives information on possible errors during the entry of card data if AJAX is used. Without AJAX, an authorization query should always be made in order to allow for a reason for the rejection to be provided upon the buyer being returned to the shop's error page.
© SIX 2017 Page 62
11 Container This section describes the structure of the containers named in the parameter tables.
11.1 Address
Parameter Type Use Format Description
FirstName String o ans[1..254] First name
LastName String o ans[1..254] Last name
DateOfBirth String o Date[1..10] Date of birth
Company String o ans[1..254] Company
Gender String o n[1] Sex Values: ‘f’ (female), ‘m’ (male) or ‘c’ (company)
LegalForm String o ans[1..254] Legal form
Street String o ans[1..254] Street
Street2 String o ans[1..254] Additional line for street. Please use only if ne-cessary. Not all processors support this parame-ter.
Zip String o ans[1..254] Postcode
City String o ans[1..254] Town
CountrySubdivisionCode String o Code for sub-national units according to ISO 3166-2
CountryCode String o a[2] Country code in accordance with ISO 3166.
Phone String o as[1..3] Telephone number
Email String o ans[1..254] E-mail address
11.2 AddressForm
Parameter Type Use Format Description
MandatoryFields String array o Array of predefined values
The array contains a list of mandatory fields that the client must complete. Possible values: CITY, COMPANY, COUNTRY, EMAIL, FIRSTNAME, LASTNAME, PHONE, SALUTA-TION, STATE, STREET, ZIP
11.3 Alias
Parameter Type Use Format Description
Id String m Id[1..40] Replacement value for credit card number and ex-piry date or bank account (ELV). Usage requires the "Saferpay Secure Card Data" service.
VerificationCode String o n[3..4] Card verification code (CVC2, CVV2, CAV, CID/4DBC)
11.4 AliasInfo
Parameter Type Use Format Description
Id String m Id[1..40] Replacement value for credit card number and ex-piry date or bank account (ELV).
Lifetime Int o n[1..4] Number of days that the alias is stored in the data-base.
© SIX 2017 Page 63
11.5 Amount
Parameter Type Use Format Description
Value String m n[..9] Payment amount in the smallest currency unit. Example: "1020" equates to 10.20 in euro.
CurrencyCode String m a[3] Currency code in accordance with ISO 4217 Example: "CHF" or "EUR"
11.6 BankAccount
Parameter Type Use Format Description
IBAN String m an[1..50] International Bank Account Number, SEPA bank account Only German IBANs are supported.
BIC String o an[11] Bank Identifier Code, international sort code
HolderName String o ans[1..50] Name of account holder.
BankName String o ans[1..50] Name of bank (if available)
11.7 BankAccountInfo
Parameter Type Use Format Description
IBAN String m an[1..50] International Bank Account Number, SEPA bank account Only German IBANs are supported.
BIC String o an[11] Bank Identifier Code, international sort code
HolderName String o ans[1..50] Name of account holder.
BankName String o ans[1..50] Name of bank (if available)
11.8 BillpayCapture
Parameter Type Use Format Description
DelayInDays Int o n [1..2] Number of days by which the due date is to be deferred. PLEASE NOTE: Please contact Billpay to cla-rify this aspect.
11.9 Brand
Parameter Type Use Format Description
PaymentMethod String, BrandId
m id[1..40] Payment means ID. . A list of possible payment means IDs can be found in section 14.2.
Name String, Brandname
o ans[..50] Name of payment means. This should only be used for display purposes and not be parsed as changes are possible at any time.
11.10 Card
Parameter Type Use Format Description
Number String m n[1..50] Card number
ExpYear Int m n[2..4] Year of expiry
ExpMonth Int m n[.2] Month of expiry
HolderName String o ans[..50] Name of the cardholder.
VerificationCode String o n[1..4] Card verification number (CVV, CVC) if available.
* The use of a credit card number in clear text format is only permitted for PCI-certified units. In the absen-ce of certification, it is strongly advised to use an alias.
© SIX 2017 Page 64
11.11 CardInfo
Parameter Type Use Format Description
MaskedNumber String m ns[1..50] Card number
ExpYear Int m n[2..4] Year of expiry
ExpMonth Int m n[.2] Month of expiry
HolderName String o ans[..50] Name of the cardholder.
CountryCode String o a[2] ISO country code for the card
11.12 CardForm
Parameter Type Use Format Description
HolderName String o optio-nal/mandatory
Determines whether the cardholder's name needs to be requested or not. Default is optio-nal.
11.13 ClientInfo
Parameter Type Use Format Description
ShopInfo String o ans[1..100] Information on the shop system.
OsInfo String o ans[1..100] Information on the operating system.
11.14 DccInfo
Parameter Type Use Format Description
PayAmount Amount m Container Information on the shop system.
11.15 DirectDebit
Parameter Type Use Format Description
MandateId String o an[1..35] Contains the SEPA mandate ID.
CreditorId String o an[1..35] The creditor's ID.
11.16 Invoice
Parameter Type Use Format Description
Payee BankAccount m Container Contains the payment data for Bill Pay pay-ments.
ReasonForTransfer String o ans[1..254] Payment purpose.
DueDate DateTime o ans[10..19] The due date by which the payment must be effected.
11.17 Notification
Parameter Type Use Format Description
MerchantEmail String o ans[1..254] Merchant's e-mail. Upon conclusion of the payment, Saferpay sends an e-mail to this address. This pa-rameter describes values set in the Backoffice (if available).
PayerEmail String o ans[1..254] Client's e-mail. Upon conclusion of the payment, Sa-ferpay sends an e-mail to this address.
NotifyUrl String o url[1..2000] Url for a server-to-server callback via https/https-POST. After successful payments, Saferpay sends the token to this address so that it can be used for an Assert.
© SIX 2017 Page 65
11.18 NotifyHeader
Parameter Type Use Format Description
SpecVersion String m ns[3] Version of the interface Value: "1.3"
RequestId String o id[1..50] ID of the original request if available.
11.19 Payer
Parameter Type Use Format Description
IpAddress String o ns[7..15] Client IP address. Example: "92.168.12.23"
LanguageCode String o ns[..5] Indicates the language in which Saferpay displays messages to the payer. A selection of possible lan-guage codes can be found in section 14.1.
DeliveryAddress Address o Container Client's name and delivery address.
BillingAddress Address o Container Client's name and billing address.
11.20 PayerInfo
Parameter Type Use Format Description
IpAddress String o ns[7..15] Client IP address. Example: "92.168.12.23"
IpLocation String o ns[..15] Country of origin of the IP address of the payer in accordance with ISO 3166. Country code (e.g. CH, DE, AT). If it is not possible to assign a code, the va-lue "IX" is used. Example: "DE"
DeliveryAddress Address o Container Client's name and delivery address.
BillingAddress Address o Container Client's name and billing address.
© SIX 2017 Page 66
11.21 Payment
Parameter Type Use Format Description
Amount Amount m Container Contains information on the payment amount.
OrderId String o id[1..80] Payment identification number assigned by the merchant system. Must be clear. Saferpay can display 80 characters for the or-der ID. In general, this is not possible on the side of the processor. Overly long character chains are cut. In practice, a length of 12 cha-racters has proven successful. In cases of doubt, please inquire to your processor how many characters can be displayed.
Description String o ans[1…255] Merchant payment description.
PayerNote String o ans[1...30] Brief message to the client which will later appear on his account statement. NOTE: Most processors do not support 30 characters. We recommend 12 at most.
MandateId String o ans[1..35] Alphanumeric mandate reference for SEPA di-rect debit transactions. Permitted characters: ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789 ':?,-(+.)/
InitialType String o Predefined values
Flags the transaction as recurring. Value: "RECURRING"
RecurringOp- tions
RecurringOptions o Container Contains options for flagging a transaction for recurring payments.
Options PaymentOptions o Container Additional processing options
11.22 PaymentMeans
Parameter Type Use Format Description
Card Card o Container Contains information on the card used.
BankAccount BankAccount o Container Contains information on the bank account used.
Alias Alias o Container Contains information on the Secure Card Data ali-as.
Wallet Wallet o Container Options for the wallet to be used
Invoice Invoice o Container Options for Pay by Invoice
11.23 PaymentMeansInfo
Parameter Type Use Format Description
Brand Brand m Container Contains the card type.
DisplayText String m ans[1...40] Contains the masked payment means data for the display
Card CardInfo o Container Contains the card data
BankAccount BankAccountInfo o Container Contains the account data.
© SIX 2017 Page 67
11.24 PaymentOptions
Parameter Type Use Format Description
PreAuth boolean o true^false Flags a pre-authorized transaction. Pre-authorized transactions can be settled up to 30 days after authorization. If no parameter is specified, a “final authorization” (default) is processed.
11.25 RecurringOptions
Parameter Type Use Format Description
Initial boolean m true^false Defines whether this payment is an initial pay-ment for recurring payments or not.
11.26 Redirect
Parameter Type Use Format Description
RedirectUrl String m ans[..1024] Contains the link for the redirecting of the brow-ser.
PaymentMeansRequired Boolean m true^false If "true", the provision of the payment means data is required. If "false", the browser can be redirec-ted to the RedirectURL directly.
11.27 Refund
Parameter Type Use Format Description
Amount Amount m Container Contains information on the credit amount.
OrderId String o id[1..80] Credit identification number assigned by the merchant system. Must be clear. Saferpay can display 80 characters for the order ID. In general, this is not possible on the side of the processor. Overly long chara-cter chains are cut. In practice, a length of 12 characters has proven successful. In cases of doubt, please inquire to your processor how many characters can be displayed.
Description String o ans[1…255] Merchant description of credit.
Please note: Pre-authorizations are not supported by all processors. Pre-authorizations are currently possible via Sa-ferpay in the case of the processors SIX, B+S CardService, ConCardis, Airplus, and, after consultation, with American Express.
© SIX 2017 Page 68
11.28 RegisterAlias
Parameter Type Use Format Description
IdGenerator String m a[6] Type of alias allocation. Values: "MANUAL" (merchant system assigns the alias) or "RANDOM" (as-signment by Saferpay) PLEASE NOTE: If assignment is ma-nual, then attention should be paid to ensuring that the ID generated cannot be guessed for attack purposes.
Id String, AliasId o / m, wenn IdGenerator=MANUAL
ans[1..40] Contains the alias for the saving of the card data in SCD.
Lifetime Int o n[1..4] Number of days that a registered card should be stored in the database. The date of the card's most recent use is used as a reference point for the ex-piry. Unless specified, the data will be held for 1,000 days. After this period expires, the data is deleted automati-cally. The longest lifetime is 1,600 days.
11.29 RegistrationError
Parameter Type Use Format Description
ErrorName String m an[1..50] Name or ID of the error
ErrorMessage String m an[1..250] Description of error.
11.30 RegistrationResult
Parameter Type Use Format Description
Success Boolean m true^false Indicates whether the registration in SCD was successful.
Alias AliasInfo o / m, wenn Success=true Container Contains the alias for the card da-ta in SCD.
Error RegistrationError o / m, wenn Success= false
as[1..64] Contains information on the failed registration in SCD.
11.31 RequestHeader
Parameter Type Use Format Description
SpecVersion String m ns[3] Version of the interface. Value: "1.3"
CustomerId Int m n[5..6] Saferpay client number.
RequestId String m id[1..50] Request identification number. Assigned by the merchant system and should be clear.
RetryIndicator Int m n[1] Counter which monitors the request at-tempts. The counter is managed by the mer-chant system. As a rule, the value should be "0" and be incremented by 1 in the case of a repeat.
ClientInfo Clientinfo o Container Contains information on the merchant sys-tem.
© SIX 2017 Page 69
11.32 ResponseHeader
Parameter Type Use Format Description
SpecVersion String m ns[..3] Version of the interface on which implemen-tation is based.
RequestId String o id[1..50] Request identification number.
11.33 ReturnUrls
GET parameters can be added to the return addresses. However, attention should be paid to keeping the URLs as short as possible.
Parameter Type Use Format Description
Success String m ans[1..2000] Return address in the case of success.
Fail String m ans[1..2000] Return address in the case of failure.
Abort String o ans[1..2000] Return address in the case of a cancellation.
11.34 Styling
Parameter Type Use Format Description
CssUrl String m ans[1..2000] Address of the CSS style sheet for use of the CSS styling feature. The CSS must be delivered via HTTPS.
Theme String o Predefined values
Theme of the payment page. Possible values: "DEFAULT" (standard), "NONE"
11.35 ThreeDsInfo
Parameter Type Use Format Description
Authenticated Boolean m true^false Indicates whether the cardholder has au-thenticated himself.
LiabilityShift Boolean m true^false Indicates whether there is a formal liability shift for the transaction.
Xid String m an[28] Contains a Base64 character string assigned by the MPI. Xid makes reference to the pro-cedure in the 3-D Secure protocol.
VerificationValue String o / m, wenn Authenticated =true
an[28] Depending on the card type, contains the UCAF value (MasterCard), the AEVV value (American Express) or the CAVV value (Vi-sa). Saferpay uses VerificationValue regar-dless of the credit card type.
© SIX 2017 Page 70
11.36 Transaction
Parameter Type Use Format Description
Type String m a[6..7] Indicates the payment type. Values: "PAYMENT" or "REFUND"
Status String m a[8..10] Contains the transaction status. Values: "AUTHORIZED" or "CAPTURED"
Id String m an[28] The Saferpay transaction ID.
Date Datetime m ans[10..19] Date and time of authorization.
Amount Amount m Container Contains the authorized amount.
OrderId Id o ans[1..80] Contains the reference number for the pay-ment.
AcquirerName String o ans[1..64] Contains the names of the payment means processor.
AcquirerReference String o ans[1..64] Contains the authorization code of the payment means processor.
DirectDebit DirectDebit o Container Contains information on direct debit payments
Invoice Invoice o Container Contains information on payments by invoice, e.g. Bill Pay Pay by Invoice
11.37 TransactionReference
One of the two parameters must be used. If both parameters are assigned, this will generate a validation error.
Parameter Type Use Format Description
TransactionId String o an[1..64] The Saferpay transaction ID of the reservation.
OrderId String o ans[1..80] The order number of the reservation.
11.38 Wallet
Parameter Type Use Format Description
Type String m Predefined values
Type of wallet used. Value: MASTERPASS
© SIX 2017 Page 71
12 Error Handling Saferpay responds to successful requests with an HTTP status code 200. If it is not possible to successful-ly process a request sent to Saferpay, the system will receive an HTTP status code 400 or higher.
12.1 HTTP Status Codes
The table lists possible HTTP status codes from Saferpay:
Code Error type
200 No error (OK)
400 Validation error
401 Authentication failed
402 Action failed
403 Access denied
406 Not accepted (accept header does not contain "application/json")
415 Non-supported media type (content type is not "application/json")
500 Internal error
12.2 Error Message
Where possible, Saferpay displays a message with additional information on the error that has occurred in the body of the response page in addition to the HTTP status code.
Parameter Type Use Format Description
Header ResponseHeader m Container Contains basic in-formation.
ErrorName String m ans[1..50] Name or ID of the er-ror.
ErrorMessage String m ans[1..250] Description of error. The content can changes and should therefore not be par-sed.
Behavior String m Predefined Values
Suggested solution Values: "RET-RY_LATER", "Other means", "ABORT"
ErrorDetail String array o ans[undefined] Further details (if available). The con-tent can change and should therefore not be parsed.
ProcessorName String o ans[1..100] Name of processor.
ProcessorResult String o ans(1..20) Response code of processor.
PRocessorMessage String o ans[1..255] Message from pro-cessor.
© SIX 2017 Page 72
12.2.1 HTTP Error Messages
The following errors can also be returned with a response:
Error name Possible cause Solution
AUTHENTICATION_FAILED Incorrect password, invalid to-ken.
Use the correct access data or a valid token.
ALIAS_INVALID The alias used is unknown or already exists.
Use a different alias.
BLOCKED_BY_RISK_MANAGEMENT Action was blocked by Safer-pay Risk Management.
Reactivate the setting, where necessary, in Saferpay Back-office under "Risk Management"
CARD_CVC_INVALID Incorrect CVC entered. Try again with the correct card verification code.
CARD_CVC_REQUIRED CVC is required but was not entered.
Try again with the card verifica-tion code.
CARD_EXPIRED Card has expired. Try with a different card or a dif-ferent expiry date.
PAYMENTMEANS_INVALID Incorrect payment information (e.g. incorrect card number).
Try again with the correct pay-ment information.
INTERNAL_ERROR Internal error with Saferpay. Try again after a short time. If the error persists, please contact Saferpay Support.
3DS_AUTHENTICATION_FAILED The 3-D Secure authenticati-on has failed.
Use different payment informa-tion or try again.
NO_CONTRACT No contract exists for this card type or this card-currency combination.
Use a different card or currency in order to meet the contractual conditions or have a new cur-rency activated for your contract.
NO_CREDITS_AVAILABLE No transaction points availab-le.
Please acquire new transaction points.
PERMISSION_DENIED Access denied (e.g. incorrect terminal provided)
Check your parameters.
TRANSACTION_DECLINED Processor has declined the transaction.
Use a different card.
VALIDATION_FAILED Validation rejected.
AMOUNT_INVALID The amount exceeds the rest-rictions (e.g. the maximum amount that can be authori-zed)
CURRENCY_INVALID Currency does not correspond to the referenced transaction.
COMMUNICATION_FAILED Communication with the pro-cessor failed.
Try again later or use different payment information.
COMMUNICATION_TIMEOUT The processor did not send a response within the defined interval.
You are advised to contact the processor and ask whether the-re is an authorization.
TOKEN_EXPIRED Token expired. Create a new token.
© SIX 2017 Page 73
Error name Possible cause Solution
TOKEN_INVALID Token does not exist or has already been used.
TRANSACTION_IN_WRONG_STATE Transaction is erroneous. Oc-curs, for example, if an autho-rization is performed although the 3D-Secure authentication is still outstanding.
Perform the incorrect steps again and then repeat.
ACTION_NOT_SUPPORTED Process is not supported.
TRANSACTION_NOT_FOUND The transaction was not found. An incorrect transac-tion number may have been used.
Use the correct transaction number.
CONDITION_NOT_SATISFIED The condition defined in the required was not satisfied.
© SIX 2017 Page 74
13 Information on Third-Party Payment Means
13.1 Introduction
The link-up to certain payment means requires particular consideration to assure a smooth working in the production environment.
13.2 Pay Pal
1.1 Prerequisites
The following is required for the processing of PayPal payments with Saferpay:
An appropriate Saferpay eCommerce license and thus valid identification with user name and password for the Saferpay System.
At least one active Saferpay Terminal over which payments can be transacted including the respective Saferpay TERMINALID or the Saferpay ACCOUNTID.
A valid PayPal dealer account.
For PayPal activation on the Saferpay Terminal please communicate your PayPal dealer ac-count ID to [email protected].
1.2 Grant API permission for Saferpay
In the dealer account, go to My Account and click on My Profile. Then, on the left side, sel-ect Seller/Dealer in order to display the setting options for Online Sales on the right. Here, sel-ect Update in the API access line:
© SIX 2017 Page 75
A dialogue will be displayed Set API permissions and authorisations. Click on Grant API permission:
The dialogue add New permission for third-parties is displayed:
Enter be-sfp_api1.six-group.com into the field User name for permission for third-parties. Then click on Look-up.
© SIX 2017 Page 76
A selection list of Available permissions is displayed:
Activate the following check boxes and then click on Add:
© SIX 2017 Page 77
1.3 PayPal Seller Protection
The PayPal Seller Protection is intended to protect you against non-payment if your customer uses PayPal to pay for goods or services he or she purchases from you. Occasionally, it can happen that an expected payment is not received because the customer does not have sufficient funds in their account or they are not happy with the delivery. Your customers can revoke all payments – for instance if there is a case of credit card fraud. Seller Protection is activated in the following cases:
Your customer revokes a direct debit or credit card payment
There are insufficient funds in your customer’s account
Your customer has complained without justification and requested customer protection
Credit card fraud
If a credit card payment or direct debit is revoked (reversal), the amount is automatically returned to the bank or the credit card company. PayPal will then debit the amount to your PayPal account. If the Seller Protection is then activated, PayPal will refund you the amount once the case is closed. For you to benefit from the PayPal Seller Protection, the following conditions need to be fulfilled:
The goods are insured and sent with accompanying paperwork
The item is sent within seven days if at all possible
The goods are sent to the buyer’s address maintained in the transaction details and in the PayPal account
In order for the PayPal Seller Protection to take effect if your customers pay via PayPal using Saferpay, the address data must be transferred to Saferpay.
If you are already operating with the Saferpay Payment process and transmit parameter DELIVERY=yes,
you don’t need to make any changes. In that case the customer enters his or her address details directly on the payment page and Saferpay transmits the data to PayPal.
But if you operate with DELIVERY=no because the address details are already recorded in your shop, it
will be necessary for the customer’s address data to be transmitted as well when the PayInit URL is gene-rated.
13.2.1 Payment Page Initialize Request
Parameter Type Use Format Description
RequestHeader RequestHea-der
m Container Contains basic information on the requ-est.
TerminalId String m an[8] Identification of the used terminal
Payment Payment m Container Contains information on the payment.
PaymentMethods String Array o Array of predefined values
Contains information on the payment means used.
Payer Payer o/m (AddressForm nicht ge-nutzt wird)
Container Contains information on the client. PLEASE NOTE: Important for PayPal vendor protection.
DeliveryAddressForm AddressForm o/m (Wenn die Adress-daten nicht überge-ben wer-den.)
Container Contains information on the client. PLEASE NOTE: Important for PayPal vendor protection.
© SIX 2017 Page 78
13.2.2 Example Payment Page Initialize Request Transfer of Address
{
"RequestHeader": {
"SpecVersion": "1.3",
"CustomerId": "123123",
"RequestId": "33e8af17-35c1-4165-a343-c1c86a320f3b",
"RetryIndicator": 0,
"ClientInfo": {
"ShopInfo": "My Shop",
"ApplicationInfo": "ApplicationInfo",
"OsInfo": "Windows Server 2013"
}
},
"TerminalId": "12345678",
"Payment": {
"Amount": {
"Value": "100",
"CurrencyCode": "EUR"
},
"OrderId": "OrderId",
"Description": "Description",
"PayerNote": "Payernote",
},
"PaymentMethods": ["PAYPAL"],
"Payer": {
"IpAddress": "111.111.111.111",
"DeliveryAddress": {
"FirstName": "Hans",
"LastName": "Muster",
"DateOfBirth": "1969-07-21",
"Street": "Strasse 1",
"Zip": "12345",
"City": "Musterstadt",
"CountryCode": "DE",
"Phone": "+49 40 1234 5678",
"Email": "[email protected]",
"Gender": "MALE",
}
},
"ReturnUrls": {
"Success": "https://merchanthost/success",
"Fail": "https://merchanthost/fail",
"Abort": "https://merchanthost/abort"
},
"Notification": {
"MerchantEmail": "[email protected]",
"NotifyUrl": "https://merchanthost/notify"
}
}
© SIX 2017 Page 79
13.2.3 Example Payment Page Initialize Request Use of Address Form
{
"RequestHeader": {
"SpecVersion": "1.3",
"CustomerId": "123123",
"RequestId": "33e8af17-35c1-4165-a343-c1c86a320f3b",
"RetryIndicator": 0,
"ClientInfo": {
"ShopInfo": "My Shop",
"ApplicationInfo": "ApplicationInfo",
"OsInfo": "Windows Server 2013"
}
},
"TerminalId": "12345678",
"Payment": {
"Amount": {
"Value": "100",
"CurrencyCode": "EUR"
},
"OrderId": "OrderId",
"Description": "Description",
"PayerNote": "Payernote",
},
"PaymentMethods": ["PAYPAL"],
"Payer": {
"IpAddress": "111.111.111.111"
},
"DeliveryAddressForm": ["CI-
TY","COUNTRY","EMAIL","FIRSTNAME","LASTNAME","PHONE","SALUTATION","STATE","STREET","ZIP"],
"ReturnUrls": {
"Success": "https://merchanthost/success",
"Fail": "https://merchanthost/fail",
"Abort": "https://merchanthost/abort"
},
"Notification": {
"MerchantEmail": "[email protected]",
"NotifyUrl": "https://merchanthost/notify"
}
}
© SIX 2017 Page 80
13.3 Billpay
1.4 Requirements
The transaction of Billpay payments via the Saferpay Payment Page requires the following:
A suitable license and thus valid identification information for the Saferpay system including a userna-me and password.
At least one active Saferpay terminal with which the payments can be processed must be available with the corresponding Saferpay TERMINALID and/or Saferpay ACCOUNTID.
A valid acceptance contract for Billpay.
13.3.1 Payment Page Initialize Request
The following parameters are available for the initial call for BillPay. Please note that certain parameters that are otherwise optional are mandatory for Billpay:
Parameter Type Use Format Description
Payment Payment m Container Contains information on the payment. PLEASE NOTE: For BillPay payments, transfer of an order ID is mandatory.
PaymentMethods String Array o/m (For certifica-tion)
Array of predefined values
Contains information on the payment means used.
Payer Payer o/m (Ad-dress-Form not support-ed)
Container Contains information on the client. PLEASE NOTE: The client's address data is important for Bill Pay.
DeliveryAddressForm AddressForm o/m (when address data is not set)
Container Contains information on the client. PLEASE NOTE: The client's address data is important for Bill Pay.
© SIX 2017 Page 81
13.3.2 Example Payment Page Initialize Request Transfer of Address
{
"RequestHeader": {
"SpecVersion": "1.3",
"CustomerId": "123123",
"RequestId": "33e8af17-35c1-4165-a343-c1c86a320f3b",
"RetryIndicator": 0,
"ClientInfo": {
"ShopInfo": "My Shop",
"ApplicationInfo": "ApplicationInfo",
"OsInfo": "Windows Server 2013"
}
},
"TerminalId": "12345678",
"Payment": {
"Amount": {
"Value": "100",
"CurrencyCode": "EUR"
},
"OrderId": "Order_ID_is_mandatory",
"Description": "Description",
"PayerNote": "Payernote",
},
"PaymentMethods": ["PAYPAL"],
"Payer": {
"IpAddress": "111.111.111.111",
"DeliveryAddress": {
"FirstName": "Hans",
"LastName": "Muster",
"DateOfBirth": "1969-07-21",
"Street": "Strasse 1",
"Zip": "12345",
"City": "Musterstadt",
"CountryCode": "DE",
"Phone": "+49 40 1234 5678",
"Email": "[email protected]",
"Gender": "MALE",
}
},
"ReturnUrls": {
"Success": "https://merchanthost/success",
"Fail": "https://merchanthost/fail",
"Abort": "https://merchanthost/abort"
},
"Notification": {
"MerchantEmail": "[email protected]",
"NotifyUrl": "https://merchanthost/notify"
}
}
© SIX 2017 Page 82
13.3.3 Example Payment Page Initialize Request Use of Address Form
{
"RequestHeader": {
"SpecVersion": "1.3",
"CustomerId": "123123",
"RequestId": "33e8af17-35c1-4165-a343-c1c86a320f3b",
"RetryIndicator": 0,
"ClientInfo": {
"ShopInfo": "My Shop",
"ApplicationInfo": "ApplicationInfo",
"OsInfo": "Windows Server 2013"
}
},
"TerminalId": "12345678",
"Payment": {
"Amount": {
"Value": "100",
"CurrencyCode": "EUR"
},
"OrderId": "Order_ID_is_mandatory",
"Description": "Description",
"PayerNote": "Payernote",
},
"PaymentMethods": ["PAYPAL"],
"Payer": {
"IpAddress": "111.111.111.111"
},
"DeliveryAddressForm": ["CI-
TY","COUNTRY","EMAIL","FIRSTNAME","LASTNAME","PHONE","SALUTATION","STATE","STREET","ZIP"],
"ReturnUrls": {
"Success": "https://merchanthost/success",
"Fail": "https://merchanthost/fail",
"Abort": "https://merchanthost/abort"
},
"Notification": {
"MerchantEmail": "[email protected]",
"NotifyUrl": "https://merchanthost/notify"
}
}
13.3.4 Payment Page Assert Response
With the Assert, Saferpay sends back specific data on the BillPay payment, such as the client's address.
Parameter Type Use Format Description
Transaction Transaction m Container Contains information on the authorizati-on. PLEASE NOTE: In the case of Bill Pay Pay by Invoice, Saferpay sends back the required account data for the bill.
Payer Payer m Container Contains information on the client. PLEASE NOTE: Saferpay sends back the client's address data.
© SIX 2017 Page 83
13.3.5 Example Payment Page Assert Response
{
"ResponseHeader": {
"SpecVersion": "1.3",
"RequestId": "33e8af17-35c1-4165-a343-c1c86a320f3b",
},
"Transaction": {
"Id": " E6tnhrAbrYGfvAYvff47b7fG6Kfb", "Date": "2015-10-15T10:01:42.527+02:00",
"Amount": {
"Value": "100",
"CurrencyCode": "EUR"
},
"OrderId": "Order_ID_is_mandatory",
"AcquirerName": "Billpay Kauf auf Rechnung Abnahme",
"AcquirerReference": "a83e4312-e85c-4b30-9e7c-50b511155a55",
"Invoice": {
"Payee": {
"IBAN": "DE2501200000TEST000000000003",
"HolderName": "Billpay GmbH",
"BIC": "TESTBIC0003",
"BankName": "BillPay Test Bank"
},
"ReasonForTransfer": "BPOrder_ID_is_mandatory/544"
}
},
"PaymentMethods": ["PAYPAL"],
"Payer": {
"IpAddress": "111.111.111.111"
},
"DeliveryAddressForm": ["CI-
TY","COUNTRY","EMAIL","FIRSTNAME","LASTNAME","PHONE","SALUTATION","STATE","STREET","ZIP"],
"ReturnUrls": {
"Success": "https://merchanthost/success",
"Fail": "https://merchanthost/fail",
"Abort": "https://merchanthost/abort"
},
"Notification": {
"MerchantEmail": "[email protected]",
"NotifyUrl": "https://merchanthost/notify"
}
}
13.3.6 Capture Request
The Capture Request can be used to defer the due date. Saferpay itself does not set a limit, but BillPay does. Please clarify with BillPay beforehand as to how long you can defer the payment for.
Parameter Type Use Format Description
BillpayCapture BillpayCapture o Container Contains capture options specifically for Billpay payments
© SIX 2017 Page 84
13.3.7 Example Capture Request
{
"RequestHeader": {
"SpecVersion": "1.3",
"CustomerId": "123123",
"RequestId": "33e8af17-35c1-4165-a343-c1c86a320f3b",
"RetryIndicator": 0,
},
"TransactionReference": {
"TransactionId": "E6tnhrAbrYGfvAYvff47b7fG6Kfb"
},
"Amount": {
"Value": "100",
"CurrencyCode": "EUR"
},
"Payer": {
"DelayInDays": 10
}
}
13.3.8 Capture Response
With the Capture Response you receive the account data again, as well as the due date.
Parameter Type Use Format Description
Invoice Invoice m Container Contains the account data as well as the due date for the Bill Pay payment.
13.3.9 Example Capture Response
{
"ResponseHeader": {
"SpecVersion": "1.3",
"RequestId": "33e8af17-35c1-4165-a343-c1c86a320f3b"
},
"TransactionId": "E6tnhrAbrYGfvAYvff47b7fG6Kfb",
"OrderId": "Order_ID_is_mandatory",
"Date": "2015-10-15T10:08:49.607+02:00",
"Invoice": {
"Payee": {
"IBAN": "DE2501200000TEST000000000003",
"HolderName": "Billpay GmbH",
"BIC": "TESTBIC0003",
"BankName": "BillPay Test Bank"
},
"ReasonForTransfer": "BPOrder_ID_is_mandatory/544",
"DueDate": "2015-11-04T00:00:00+01:00"
}
}
© SIX 2017 Page 85
13.4 Alias Registration for Postfinance Card
13.4.1 Requirements
The requirements for registration of Postfinance cards are as follows:
A corresponding license and thus a valid account with username and password for the Saferpay sys-tem.
Activation of the Saferpay Secure Card Data store
A valid contract with the post office
Activation for the Postfinance alias system with the post office and Saferpay.
Please note that Postfinance cards can only be registered through Insert.
13.4.2 Insert Request
Using this method, aliases can be saved in SCD without the merchant system coming into contact with the payment means data. The table lists the parameters available for this purpose:
Parameter Type Use Format Description
RequestHeader RequestHeader m Container Contains basic information on the request.
RegisterAlias RegisterAlias m Container Information on the saving of the card data in Secure Card Data. PLEASE NOTE: Please pay attention to section 11.28.
Type String, RegisterType
m Predefined Values
Indicates which payment means type is sa-ved in SCD. Value: "POSTFINANCE"
ReturnUrls ReturnUrls m Container Contains the return addresses to the mer-chant system.
13.4.3 Example Insert Request
{
"RequestHeader": {
"SpecVersion": "1.3",
"CustomerId": 123123,
"RequestId": "5e9adf9e-7468-4dff-9dfb-6c99d8e43acb",
"RetryIndicator": 0,
"ClientInfo": {
"ShopInfo": "My Shop",
"OsInfo": "Windows Server 2013"
}
},
"RegisterAlias": {
"IdGenerator": "manual",
"Id": "ALIAS",
"Lifetime": "1000"
}, "Type": "POSTFINANCE",
"ReturnUrls": {
"Success": "https://successurl", "Fail": "https://failedurl", "Abort": "https://aborturl" } }
© SIX 2017 Page 86
13.4.4 Insert Response
The Insert Response can contain the following parameters:
Parameter Type Use Format Description
ResponseHeader ResponseHeader m Container Contains basic information on the response.
Token String m Id [1..50] ID for registration. Can only be used once for a successful registration.
Expiration Datetime m ans[1..30] Token's expiry date The token can no longer be used after it expires.
RedirectUrl String m ans[1..128] URL for redirection / the Iframe
13.4.5 Example Insert Response
{
"ResponseHeader": {
"SpecVersion": "1.3",
"RequestId": "5e9adf9e-7468-4dff-9dfb-6c99d8e43acb",
},
"Token": "K5OYS9Ad6Ex4rASU1IM1b3CEU8bb",
"Date": "2014-11-22T11:15:26.674+01:00",
"RedirectUrl":
"HTTPS://www.saferpay.com/VT2/InsertAlias/1234/12341234/234uhfh78234hlasdfh8234e" }
© SIX 2017 Page 87
13.4.6 Redirection to PostFinance
After being redirected to PostFinance, in the first step the cardholder has to accept the terms of condition for postcard registration.
© SIX 2017 Page 88
14 Post Registration Dialogue After being redirected to PostFinance, in the first step the cardholder has to accept the terms of condition for postcard registration:
After clicking „continue“ a new page occurs.
© SIX 2017 Page 89
The cardholder is now asked for the ID number of the postcard:
Confirm the ID with „Continue“.. To finish registration process a code hast o be entered which is generated by the cardholder’s card reader.
© SIX 2017 Page 90
14.1.1 Return to Shop
After the cardholder has entered all the required information, he will be taken back to the shop via the browser depending on the outcome (success, rejection, cancellation). Please note! To ensure that the return addresses have not been changed over by a skilled user with frau-dulent intentions (e.g. swapping the FailUrl for the SuccessUrl), an AssertInsert Request should always be used after the buyer is returned to the shop's success page. This always provides a reliable answer. Either successful registration will be confirmed or a meaningful error message will be transmitted.
From here on in the PostCard registration behaves like any other.
© SIX 2017 Page 91
15 Appendix
15.1 Language Codes for LanguageCode
The following table shows a selection of language codes:
Code Name Language
de Deutsch German
en English English
fr Français French
da Dansk Danish
cs Čeština Czech
es Español Spanish
hr Hrvatski Croatian
it Italiano Italian
hu Magyar Hungarian
nl Nederlands Dutch
no Norsk Norwegian
pl Polski Polish
pt Português Portuguese
ru Pусский Russian
ro Română Romanian
sk Slovenský Slovakian
sl slovenščina Slovenian
fi Suomi Finnish
sv Svenska Swedish
tr Türkçe Turkish
el Eλληνικές Greek
ja 日本語 Japanese
zh 中国語 Chinese
Extension of the language code to include the culture codes is possible. Saferpay supports all codes in the Microsoft .NET CultureInfo Class.
© SIX 2017 Page 92
15.2 Supported Payment Means Values for PaymentMethod(s)
PaymentMethod Payment means
MASTERCARD MasterCard
VISA Visa
VPAY vPay
AMEX American Express
DINERS Diners Club
JCB JCB
SAFERPAYTEST Saferpay Test Card
BONUS Bonus Card
POSTFINANCE PostFinance e-finance
POSTCARD PostFinance card
MAESTRO Maestro International
MYONE MyOne
DIRECTDEBIT Direct debit (SEPA, Bill Pay PLEASE NOTE: Only one contract can be activated per Terminal ID. If both are to be used, then an additional terminal needs to be reques-ted!)
PAYPAL PayPal
EPRZELEWY ePrzelewy EPS Homebanking AT (eps)
GIROPAY giropay
IDEAL iDeal
INVOICE Invoice
© SIX 2017 Page 93
15.3 License Matrix
The following matrix indicates which Saferpay license is needed to carry out a JSON API function.
*Only in connection with the Secure Card Data service
eCommerce Business
Initialize Payment Page
Initialize Transaction
Verify
Authorize
AuthorizeDirect
RedirectPayment
AssertRedirectPayment
Refund
RefundDirect
Capture
Cancel
Close Batch
Insert*
AssertInsert*
InsertDirect*
© SIX 2017 Page 94
16 Saferpay Test Environment
For the integration phase and in order to be able to test Saferpay, we can offer you our External Test En-vironment (ETU). In this environment, which is isolated from the operational environment, you can test Saferpay with simula-tions for all current payment means in your own test account. All the details on our test environment can be found at the following address:
https://www.six-payment-services.com/en/site/saferpay-support/testaccount.html
© SIX 2017 Page 95
17 Contact
17.1 Saferpay Integration Team
Do you have any questions on this document? Are you experiencing problems with the Saferpay integrati-
on? Or do you require support? If so, the Integration Team would be happy to help you:
Saferpay Switzerland
SIX Payment Services Ltd
Hardturmstrasse 201
8021 Zurich
+41 848 66 44 44
www.six-payment-services.com/saferpay
Saferpay Europe
SIX Payment Services (Germany) GmbH
Langenhorner Chaussee 92-94
22415 Hamburg
+49 40 325 967- 280
www.six-payment-services.com/saferpay
17.2 Saferpay Support Team
Do you have any questions on error messages or are you having any problems during day-to-day operati-
ons. If so, our Support Team will be happy to help:
Saferpay Switzerland
SIX Payment Services Ltd
Hardturmstrasse 201
8021 Zurich
+41 848 66 44 44
www.six-payment-services.com/saferpay
Saferpay Europe
SIX Payment Services (Germany) GmbH
Langenhorner Chaussee 92-94
22415 Hamburg
+49 40 325 967- 250
www.six-payment-services.com/saferpay
The Saferpay Team wishes much success in using your Saferpay e-payment solution!