saferpay json api specification - six · the saferpay json api (javascript object notation...

© SIX 2017

Saferpay JSON API

Specification

Version: 2.3

© SIX 2017

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

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

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.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

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.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

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.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.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

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).

https://saferpay.github.io/jsonapi/index.html

https://saferpay.github.io/sndbx/index.html

https://www.pcisecuritystandards.org/

© SIX 2017

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

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

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

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

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

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

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

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

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


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": {


"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

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": {





"ClientInfo": {




}

},


"Payment": {

"Amount": {

"Value": "100",


},




},

"PaymentMethods": ["VISA", "MASTERCARD", "MASTERPASS"],

"Payer": {

"IpAddress": "111.111.111.111"

},

"ReturnUrls": {




},

"Notification": {


"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

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


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": {




"RetryIndicator": 0

},

"Token": "234uhfh78234hlasdfh8234e1234"

}

3.5.3 Payment Page Assert Response


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

3.5.4 Examples Assert Response

{

"ResponseHeader": {



},

"Transaction": {

"Type": "PAYMENT",

"Status": "AUTHORIZED",

"Transaction": {

"Id": "K5OYS9Ad6Ex4rASU1IM1b3CEU8bb",

"Date": "2011-09-23T14:57:23.023+01:00",

"Amount": {

"Value": "100",


},


"AcquirerName": "AcquirerName",

"AcquirerReference": "AcquirerReference"

}

},

"PaymentMeans": {

"Brand": {

"Id": 35,

"Name": "PayPal"

},

"DisplayText": "PayPal transaction"

},

"Payer": {

"IpAddress": "111.111.111.111",

"IpLocation": "NZ"

}

}

© SIX 2017

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





Payment Payment m Container Contains information on the payment.

PaymentMeans PaymentMeans o Container Contains information on the payment means used.


ReturnUrls ReturnUrls m Container Contains the return addresses for the merchant system in the case of forwar-ding by 3DS or DCC.


© SIX 2017

4.2.2 Examples Initialize Request

Without PaymentMeans: {

"RequestHeader": {





"ClientInfo": {



}

},


"Payment": {

"Amount": {

"Value": "100",


},



"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": {





"ClientInfo": {



}

},


"Payment": {

"Amount": {

"Value": "100",


},




"MandateId": "O6E1ItArnhWpvAMGMEh2Ar9zbjtA"

},

"PaymentMeans": {

"Card": {

"Number": "1234123412341234",

"ExpYear": 2015,

"ExpMonth": 9,

"HolderName": "John Doe"

}

},

"Payer": {

"IpAddress": "111.111.111.111",


},

"ReturnUrls": {




}

}

© SIX 2017

4.2.3 Initialize Response

The response to the initial call may contain the following parameters:



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": {



},


"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

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

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:



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

4.5.2 Example Authorize Request

{

"RequestHeader": {


"CustomerId": 123123,



"ClientInfo": {



}

},


"VerificationCode": "123",

"RegisterAlias": {

"IdGenerator": "MANUAL",

"Id": "Id",

"Lifetime": 1000

}

}

4.5.3 Authorize Response

The Authorize Response can contain the following parameters:



Transaction Transaction m Container Contains information on the authorizati-on.


RegistrationResult RegistrationResult o Container Contains information on the registration in SCD.


ThreeDs ThreeDsInfo o Container Contains information on 3-D Secure.

Dcc DccInfo o Container Contains information on Dynamic Cur-rency Conversion.

© SIX 2017

4.5.4 Example of Authorize Response

{

"ResponseHeader": {



},

"Transaction": {

"Type": "PAYMENT",



"Date": "2011-09-23T14:57:23.02+01:00",

"Amount": {

"Value": "100",


},




},

"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

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

4.6.2 AuthorizeDirect Request

For authorization without prior initialization, the following parameters are available:



TerminalId String m An[8] Identification of the used terminal


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": {



"RequestId": "7b09c4af-e28a-4f32-9386-1b06490238ec",


"ClientInfo": {



}

},


"Payment": {

"Amount": {

"Value": "100",


},



"PayerNote": "PayerNote"

},

"PaymentMeans": {

"Card": {

"Number": "1234123412341234",

"ExpYear": 2015,

"ExpMonth": 7,


"VerificationCode": "123"

}

},

"RegisterAlias": {


"AliasId": "AliasId",

"LifeTime": 1000

},

"Payer": {

"IpAddress": "10.1.1.1"

}

}

© SIX 2017

4.6.4 AuthorizeDirect Response




Transaction Transaction m Container Contains information on the authori-zation.


RegistrationResult RegistrationResult o Container Contains information on the registra-tion in SCD.


4.6.5 Example AuthorizeDirect Response

{

"ResponseHeader": {



},

"Transaction": {

"Type": "PURCHASE", "Status": "AUTHORIZED",


"Date": "2011-09-23T14:57:23.023Z",

"Amount": {

"Value": "100",


},




},

"PaymentMeans": {

"Brand": {

"PaymentMethod": 6,


},


"Card": {


"ExpYear": 2015,

"ExpMonth": 9,


"CountryCode": "CH"

}

},

"RegistrationResult": {

"Success": true,

"AliasId": "AliasId"

},

"Payer": {

"IpAddress": "111.111.111.111",

"IpLocation": "NZ"

}

}

© SIX 2017

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": {





"ClientInfo": {



}

},


"Payment": {

"Amount": {

"Value": "100",

"CurrencyCode": "EUR"

},



"PayerNote": "PayerNote",

"MandateId": "O6E1ItArnhWpvAMGMEh2Ar9zbjtA"

},

"PaymentMeans": {

"BankAccount": {

"CountryCode": "DE",

"IBAN": "DE12500105170648489890",

"BIC": "INGDDEFFXXX",


}

},

"Payer": {

"IpAddress": "10.1.1.1"

}

}

© SIX 2017

4.6.8 Example ELV AuthorizeDirect Response:

{

"ResponseHeader": {



},

"Transaction": {

"Type": "PAYMENT", "Status": "AUTHORIZED",


"Date": "2011-09-23T14:57:23.023Z",

"Amount": {

"Value": "100",


},


"AcquirerName": "Lastschrift InterCard SEPA",

"AcquirerReference": "0e3f8ec3-1a4e-4916-8c31-609552278a0a"

},

"PaymentMeans": {

"Brand": {

"PaymentMethod": 13,

"Name": "Lastschrift"

},

"DisplayText": "DE12 5001 05xx xxxx xx98 90",

"BankAccount": {


"IBAN": "DE12500105170648489890",

"BIC": "INGDDEFFXXX",


}

},

"Payer": {

"IpAddress": "111.111.111.111",

"IpLocation": "NZ"

}

}

© SIX 2017

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




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.


ReturnUrls ReturnUrls m Container Contains the return addresses for the merchant system in the case of forwar-ding by 3DS or DCC.


4.7.2 Examples Initialize Request

{

"RequestHeader": {





"ClientInfo": {



}

},


"Payment": {

"Amount": {

"Value": "100",


},

"RecurringOptions": {

"Initial": true },



"PayerNote": "Payernote"

},

"Payer": {

"IpAddress": "111.111.111.111",


},

"ReturnUrls": {




},

"Styling": {

"CssUrl": "HTTPS://my-shop.com/styling.css"

},

}

© SIX 2017

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.


RequestHeader RequestHea-der

m Container Contains basic information on the requ-est.


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": {





"ClientInfo": {



}

},


"Payment": {

"Amount": {

"Value": "100",


},



"PayerNote": "PayerNote"

},

"TransactionReference": {

"TransactionId": "K5OYS9Ad6Ex4rASU1IM1b3CEU8bb"

}

}

© SIX 2017

4.7.6 AuthorizeReferenced Response







4.7.7 Example AuthorizeReferenced Response

{

"ResponseHeader": {



},

"Transaction": {

"Type": "PURCHASE", "Status": "AUTHORIZED",


"Date": "2011-09-23T14:57:23.023Z",

"Amount": {

"Value": "100",


},




},

"PaymentMeans": {

"Brand": {

"PaymentMethod": 6,


},


"Card": {


"ExpYear": 2015,

"ExpMonth": 9,


"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

4.8.1 Overview

4.8.2 RedirectPayment Request

The following parameters are available for the RedirectPayment call.





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


ReturnUrls ReturnUrls m Container Contains the return addresses for the client to the web shop.


© SIX 2017

4.8.3 Example RedirectPayment Request

{

"RequestHeader": {





"ClientInfo": {



}

},


"Payment": {

"Amount": {

"Value": "100",


},


"Description": "Description"

},

"ServiceProvider": "PAYPAL",

"Payer": {

"IpAddress": "111.111.111.111",


},

"ReturnUrls": {




}

}

© SIX 2017

4.8.4 RedirectPayment Response

The response to the Redirect payment request may contain the following parameters:


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": {



},


"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.


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:



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

4.8.9 Example Assert Redirect Payment Request

{

"RequestHeader": {





"ClientInfo": {



}

},

"Token": "234uhfh78234hlasdfh8234e"

}

4.8.10 Assert Redirect Payment Response

The AssertInsert Response delivers the following parameters:




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": {





"ClientInfo": {



}

},

"Transaction": {

"Type": "PAYMENT",


"Id": "nlj7UUbljO2ttA3n494rAE3b2brb",

"Date": "21015-05-12T12:02:24+2:00",

"Amount": {

"Value": "100",


},

"AcquirerName": "PostFinance Card",

"AcquirerReference": "PostFinance Card",

},

"PaymentMeans": {

"Amount": {


"Name": "Postcard"

},

"DisplayText": "Postcard",

},

"Payer": {

"IpAddress": "111.111.111.111"

},

}

© SIX 2017

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:



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": {





"ClientInfo": {



}

},

"Refund": {


"Amount": {

"Value": "100",


},

"OrderId": "OrderId"

},


"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

4.9.3 Refund Response





Dcc DccInfo o Container Contains information on Dynamic Currency Conversion.

4.9.4 Example Refund Request

{

"ResponseHeader": {



},

"Transaction": {

"Type": "REFUND", "Status": "AUTHORIZED",


"Date": "2011-09-23T14:57:23.023Z",

"Amount": {

"Value": "100",


},




},

"PaymentMeans": {

"Brand": {



},

"DisplayText": "912345xxxxxx1234",

"Card": {


"ExpYear": 2015,

"ExpMonth": 9,


"CountryCode": "CH"

}

},

"Dcc": {

"PaymentAmount": {

"Value": "134",

"CurrencyCode": "NZD"

}

}

}

© SIX 2017

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:



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": {





"ClientInfo": {



}

},


"Refund": {


"Amount": {

"Value": "100",


},

"OrderId": "OrderId"

},

"PaymentMeans": {

"Card": {

"Number": "1234123412341234",

"ExpYear": 2015,

"ExpMonth": 7,



}

}

}

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

4.9.7 RefundDirect Response





4.9.8 Example RefundDirect Response

{

"ResponseHeader": {



},

"Transaction": {

"Type": "REFUND", "Status": "AUTHORIZED",


"Date": "2011-09-23T14:57:23.023Z",

"Amount": {

"Value": "100",


},




},

"PaymentMeans": {

"Brand": {

"Id": 42,


},

"DisplayText": "912345xxxxxx1234",

"Card": {


"ExpYear": 2015,

"ExpMonth": 9,


"CountryCode": "CH"

}

}

}

© SIX 2017

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



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": {



"RequestId": "5e9adf9e-7468-4dff-9dfb-6c99d8e43acb",


"ClientInfo": {



}

},


"TransactionId": "qiuwerhfi23h4189asdhflk23489"

},

"Amount": {

"Value": "50",


}

}

5.3 Capture Response

The following parameters can be included in the Capture 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

5.4 Example Capture Response

{

"ResponseHeader": {


"RequestId": "d4dcf2f6-ddc1-4e2c-8b13-290a3eb09dbf"

},

"TransactionId": "qiuwerhfi23h4189asdhflk23489",


"Date": "2014-04-25T08:33:44.159Z"

}

© SIX 2017

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



TransactionReference TransactionReference m Container Contains a reference to the transaction

6.2 Example Cancel Request

{

"RequestHeader": {





"ClientInfo": {



}

},


"TransactionId": "qiuwerhfi23h4189asdhflk23489"

}

}

6.3 Cancel Response

The following parameters can be included in the Cancel Response message:



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": {


"RequestId": "d4dcf2f6-ddc1-4e2c-8b13-290a3eb09dbf"

},

"TransactionId": "qiuwerhfi23h4189asdhflk23489",


"Date": "2014-04-25T08:33:44.159Z"

}

© SIX 2017

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:




7.2 Example Close Request

{

"RequestHeader": {





"ClientInfo": {



}

},

"TerminalId": "12341234"

}

7.3 Close Response

The response to the daily closing instruction contains the following container:



7.4 Example Close Response

{

"ResponseHeader": {


"RequestId": "d4dcf2f6-ddc1-4e2c-8b13-290a3eb09db"

}

}

© SIX 2017

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:



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.


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

8.2.2 Example Insert Request

{

"RequestHeader": {





"ClientInfo": {



}

},

"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:



Token String m Id [1..50] ID for registration. Can only be used once for a successful registration.


RedirectUrl String m ans[1..128] URL for redirection / the Iframe

8.2.4 Example Insert Response

{

"ResponseHeader": {



},

"Token": "K5OYS9Ad6Ex4rASU1IM1b3CEU8bb",

"Date": "2014-11-22T11:15:26.674+01:00",

"RedirectUrl":

"HTTPS://www.saferpay.com/VT2/InsertAlias/1234/12341234/234uhfh78234hlasdfh8234e" }

© SIX 2017

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.


<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.


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

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.


The parameters are required:



Token String m Id [1..50] ID for the registration delivered with the Inse-rtResponse.

8.2.11 Example AssertInsert Request

{

"RequestHeader": {





"ClientInfo": {



}

},

"Token": "cspfxpj6mrqbeu0veobxsh8bo" }

© SIX 2017

8.2.12 AssertInsert Response

The AssertInsert Response delivers the following parameters:



Alias AliasInfo m Container Contains information on the saved alias.


8.2.13 Example AssertInsert Response

{

"ResponseHeader": {



},

"Alias": {

"Id": "ALIAS",

"Lifetime": "1000"

},

"PaymentMeans": {

"Brand": { "PaymentMethod": 6,

"Name": "Saferpay Test Card" } "DisplayText": "912345xxxxxx1234", "Card": {


"ExpYear": 2015,

"ExpMonth": 9,


"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.


8.3.1 InsertDirect Request

The following parameters are required for this method:



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

8.3.2 Example InsertDirect Request

{

"RequestHeader": {





"ClientInfo": {



}

},

"RegisterAlias": {


"AliasId": "AliasId",

"LifeTime": 1000

},

"PaymentMeans": {

"Card": {

"Number": "1234123412341234",

"ExpYear": 2015,

"ExpMonth": 7,



}

}

}

8.3.3 InsertDirect Response

The response to the request for direct registration delivers the following parameters:



Alias AliasInfo m Container Contains information on the saved alias.


8.3.4 Example InsertDirect Response

{

"ResponseHeader": {



},

"Alias": {

"Id": "ALIAS",

"Lifetime": "1000"

},

"PaymentMeans": {

"Brand": {

"PaymentMethod": 6,


},

"DisplayText": "Display Text",

"Card": {


"ExpYear": 2015,

"ExpMonth": 9,


"CountryCode": "CH"

}

}

}

© SIX 2017

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:



AliasId String m Id[1..40] Alias of the card data in Secure Card Data.

8.4.2 Example Delete Request

{

"RequestHeader": {





"ClientInfo": {



}

},

"AliasId": "ALIAS" }

8.4.3 Delete Response

The response to the delete request contains the following container:



8.4.4 Example Delete Response

{

"ResponseHeader": {



}

}

© SIX 2017

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

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

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

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

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

https://www.six-payment-services.com/dam/saferpay/testaccount/css/mobile1.css

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

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:


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


<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:


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:


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

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

}); });


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

11 Container This section describes the structure of the containers named in the parameter tables.

11.1 Address


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


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


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


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

11.5 Amount


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


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


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


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


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


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

11.11 CardInfo


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


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


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


PayAmount Amount m Container Information on the shop system.

11.15 DirectDebit


MandateId String o an[1..35] Contains the SEPA mandate ID.

CreditorId String o an[1..35] The creditor's ID.

11.16 Invoice


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


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

11.18 NotifyHeader


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


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


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

11.21 Payment


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


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


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

11.24 PaymentOptions


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


Initial boolean m true^false Defines whether this payment is an initial pay-ment for recurring payments or not.

11.26 Redirect


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


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

11.28 RegisterAlias


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


ErrorName String m an[1..50] Name or ID of the error

ErrorMessage String m an[1..250] Description of error.

11.30 RegistrationResult


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


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

11.32 ResponseHeader


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.


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


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


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

11.36 Transaction


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.


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


Type String m Predefined values

Type of wallet used. Value: MASTERPASS

© SIX 2017

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.


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

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

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

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

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

A selection list of Available permissions is displayed:

Activate the following check boxes and then click on Add:

© SIX 2017

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.



RequestHeader RequestHea-der

m Container Contains basic information on the requ-est.



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

13.2.2 Example Payment Page Initialize Request Transfer of Address

{

"RequestHeader": {





"ClientInfo": {




}

},


"Payment": {

"Amount": {

"Value": "100",


},




},

"PaymentMethods": ["PAYPAL"],

"Payer": {

"IpAddress": "111.111.111.111",

"DeliveryAddress": {

"FirstName": "Hans",

"LastName": "Muster",

"DateOfBirth": "1969-07-21",

"Street": "Strasse 1",

"Zip": "12345",

"City": "Musterstadt",


"Phone": "+49 40 1234 5678",

"Email": "[email protected]",

"Gender": "MALE",

}

},

"ReturnUrls": {




},

"Notification": {



}

}

© SIX 2017

13.2.3 Example Payment Page Initialize Request Use of Address Form

{

"RequestHeader": {





"ClientInfo": {




}

},


"Payment": {

"Amount": {

"Value": "100",


},




},


"Payer": {

"IpAddress": "111.111.111.111"

},

"DeliveryAddressForm": ["CI-

TY","COUNTRY","EMAIL","FIRSTNAME","LASTNAME","PHONE","SALUTATION","STATE","STREET","ZIP"],

"ReturnUrls": {




},

"Notification": {



}

}

© SIX 2017

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.


The following parameters are available for the initial call for BillPay. Please note that certain parameters that are otherwise optional are mandatory for Billpay:


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

13.3.2 Example Payment Page Initialize Request Transfer of Address

{

"RequestHeader": {





"ClientInfo": {




}

},


"Payment": {

"Amount": {

"Value": "100",


},

"OrderId": "Order_ID_is_mandatory",



},


"Payer": {

"IpAddress": "111.111.111.111",

"DeliveryAddress": {

"FirstName": "Hans",

"LastName": "Muster",

"DateOfBirth": "1969-07-21",

"Street": "Strasse 1",

"Zip": "12345",

"City": "Musterstadt",


"Phone": "+49 40 1234 5678",

"Email": "[email protected]",

"Gender": "MALE",

}

},

"ReturnUrls": {




},

"Notification": {



}

}

© SIX 2017

13.3.3 Example Payment Page Initialize Request Use of Address Form

{

"RequestHeader": {





"ClientInfo": {




}

},


"Payment": {

"Amount": {

"Value": "100",


},




},


"Payer": {

"IpAddress": "111.111.111.111"

},



"ReturnUrls": {




},

"Notification": {



}

}

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.


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

13.3.5 Example Payment Page Assert Response

{

"ResponseHeader": {



},

"Transaction": {

"Id": " E6tnhrAbrYGfvAYvff47b7fG6Kfb", "Date": "2015-10-15T10:01:42.527+02:00",

"Amount": {

"Value": "100",


},


"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"

}

},


"Payer": {

"IpAddress": "111.111.111.111"

},



"ReturnUrls": {




},

"Notification": {



}

}

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.


BillpayCapture BillpayCapture o Container Contains capture options specifically for Billpay payments

© SIX 2017

13.3.7 Example Capture Request

{

"RequestHeader": {





},


"TransactionId": "E6tnhrAbrYGfvAYvff47b7fG6Kfb"

},

"Amount": {

"Value": "100",


},

"Payer": {

"DelayInDays": 10

}

}

13.3.8 Capture Response

With the Capture Response you receive the account data again, as well as the due date.


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": {



},

"TransactionId": "E6tnhrAbrYGfvAYvff47b7fG6Kfb",


"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

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:



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": {





"ClientInfo": {



}

},

"RegisterAlias": {

"IdGenerator": "manual",

"Id": "ALIAS",

"Lifetime": "1000"

}, "Type": "POSTFINANCE",

"ReturnUrls": {

"Success": "https://successurl", "Fail": "https://failedurl", "Abort": "https://aborturl" } }

© SIX 2017

13.4.4 Insert Response

The Insert Response can contain the following parameters:



Token String m Id [1..50] ID for registration. Can only be used once for a successful registration.


RedirectUrl String m ans[1..128] URL for redirection / the Iframe

13.4.5 Example Insert Response

{

"ResponseHeader": {



},

"Token": "K5OYS9Ad6Ex4rASU1IM1b3CEU8bb",

"Date": "2014-11-22T11:15:26.674+01:00",

"RedirectUrl":

"HTTPS://www.saferpay.com/VT2/InsertAlias/1234/12341234/234uhfh78234hlasdfh8234e" }

© SIX 2017

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

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

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


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

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

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

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

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

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

[email protected]

Saferpay Europe

SIX Payment Services (Germany) GmbH

Langenhorner Chaussee 92-94

22415 Hamburg

+49 40 325 967- 280


[email protected]

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


[email protected]

Saferpay Europe

SIX Payment Services (Germany) GmbH

Langenhorner Chaussee 92-94

22415 Hamburg

+49 40 325 967- 250


[email protected]

The Saferpay Team wishes much success in using your Saferpay e-payment solution!

http://www.saferpay.com/

mailto:[email protected]

http://www.saferpay.com/

mailto:[email protected]

saferpay json api specification - six · the saferpay json api (javascript object notation...

Documents