Introduction

This page describes the Saferpay JSON application programming interface.

Our API is designed to have predictable, resource-oriented URLs and to use HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which can be understood by off-the-shelf HTTP clients. JSON will be returned in all responses from the API, including errors.

Content Encoding

UTF-8 must be used for text encoding (there are restrictions on allowed characters for specific fields though).

Content-Type and Accept headers should be set to application/json for server-to-server calls. Redirects use the standard browser types.

HTTP Headers:

Content-Type: application/json; charset=utf-8

Accept: application/json

Formats

The Saferpay JSON Api uses unified and standardized formats. The following abbreviations for format information are used in this page:

Name Definition Description
Id A-Za-z0-9.:-_ Alphanumeric with dot, colon, hyphen and underscore.
Numeric 0-9 Numbers.
Boolean true or false Boolean values.
Date ISO 8601 Date and Time ISO 8601 format, e.g. 2007-12-24T18:21:25.123Z (UTC) or 2007-12-24T19:21:25.123+01:00 (CET). Max 3 digits in the fractional seconds part.

Authentication

Saferpay supports the mechanism of basic authentication or a client certificate for authentication of a server (host) system.

Important: You must use either the Basic Authentication, OR the Client Certificate, but not both! Also make sure, that you do not send any faulty or old certificates, or authentication/accept headers. Otherwise our corporate Firewall will reject the call with a 403-Forbidden status! Furthermore, please note, that some environments do this by default. So even if you didn't implement it, the environment may do it as a default! It may be necessary to check your configuration.

HTTP basic authentication

This is the default authentication method. Technical users for the JSON API can be created by the merchant in the Saferpay Backoffice under Settings > JSON API basic authentication. The password will not be stored at SIX (only a securely salted hash thereof). There will be no password recovery besides creating a new user / password pair from your Backoffice account.

The password must meet some complexity requirements. We suggest using / generating dedicated passwords with a length of 16 alphanumeric characters (up to 32 characters).

Basic Authentication

HTTP Header:

Authorization: Basic [your base64 encoded "user_name:password"]

HTTPS Client Certificate Authentication

Alternatively, Saferpay also supports authentication via a client certificate.

Important: This feature is only available for Saferpay Business merchants!

A client certificate for the JSON-API can be ordered in the Saferpay Backoffice under Settings > JSON API client certificate.

If you have a Saferpay Business licence, you will find the HTTPS Client Certificate Authentication section under the form for HTTPS Basic Authentication.

Basic Aiuthentication

Generate the CSR as described on the page and import it using the upload button. The signed client certificate will then be downloaded through your browser.

Integration

Integration Guide

While these Documents are meant as a quick reference and technical specification of the Saferpay JSON-API, the Saferpay Integration Guide contains an in depth explanation about payment-flows, tips and tricks, as well as best practices for those, who want to integrate the JSON-API and its features for the first time. It will also help to understand certain characteristics about the different payment methods we offer, as well as the rules you must follow, when processing vital credit card data and more.

The sequential steps of the general integration process are described in our Step-by-step Integration-Manual.

Server-to-Server code Samples

The JSON API is a modern and lightweight interface, that can be used with all shop systems and all programming languages. Only a few steps are necessary to integrate your online shop with Saferpay. The proceeding is mostly as follows:

  1. Initialize via secure server-to-server call
  2. Integrate iframe to redirect your customer
  3. Authorize/ assert customer interaction via secure server-to-server call

In secure server-to-server calls you have to submit a JSON request containing you processing instructions to the defined URLs. The URL and the JSON structure varies depending on the action/resource you want to call. For further details check the description of resources below.

Server-to-server calls are a secure way to submit and gather data. Hence, a server-to-server call should always follow after the customer returns back to the shop, to gather information about the outcome of e.g. 3D Secure.

Important: Saferpay only supports TLS 1.2 and up, for secure connections. Please make sure, that your system is configured accordingly! More information in our TLS-FAQ.

Important: The redirect towards the redirectUrl via http-POST IS NOT supported. You should always use http-GET, unless specifically stated otherwise!

Caution: Please DO NOT use client side scripting languages like JavaScript to execute the server-to-server (JSON) calls directly. Clients could manipulate the code, or even try to extract the credentials, to execute refunds or other requests with malicious intentions. Always execute the requests and keep your credentials on your server, maybe by using AJAX.

Caution: DO NOT implement a polling-process, to poll for the transaction-data. Respond with the necessary request, at the correct time (e.g. doing the assert only, if the SuccessUrl, or NotifyUrl are called). Saferpay reserves the right to otherwise deactivate, or block your account!

Server-to-server communication:

private object SubmitRequest(string sfpUrl, object request, string sfpLogin, string sfpPassword)
{
    // don't keep your connection alive, it's a simple request/response server call
    // for details on NoKeepAliveWebClient, see https://github.com/saferpay/jsonapi/blob/master/snippets/NoKeepAliveWebClient.cs
    using (var client = new NoKeepAliveWebClient())
    {
        string authInfo = $"{sfpLogin}:{sfpPassword}";
        client.Headers[HttpRequestHeader.Authorization] = "Basic " + Convert.ToBase64String(Encoding.UTF8.GetBytes(authInfo));
        client.Headers[HttpRequestHeader.Accept] = "application/json";
        client.Headers[HttpRequestHeader.ContentType] = "application/json; charset=utf-8";
        client.Encoding = Encoding.UTF8;
        try
        {
            var responseData = client.UploadString(sfpUrl, JsonConvert.SerializeObject(request));
            return JsonConvert.DeserializeObject(responseData);
        }
        catch (WebException we)
        {
            if (we.Response is HttpWebResponse response)
            {
                Trace.WriteLine($"Web exception occured: {response.StatusCode} {response.StatusDescription}");
                if (response.ContentLength > 0)
                {
                    using (var rs = we.Response.GetResponseStream())
                    using (var sr = new StreamReader(rs))
                    {
                        Trace.WriteLine($"{sr.ReadToEnd()}");
                    }
                }
            }
            else
            {
                Trace.WriteLine($"Web exception occured: {we.Message} ({we.Status}");
            }
            throw;
        }
    }
}
      
public static JsonObject sendRequest(URL sfpUrl, JsonObject request, String sfpLogin, String sfpPassword) throws IOException {
    //encode credentials
    String credential = sfpLogin + ":" + sfpPassword;
    String encodedCredentials = DatatypeConverter.printBase64Binary(credential.getBytes());
//create connection
HttpURLConnection connection = (HttpURLConnection) sfpUrl.openConnection();
connection.setRequestProperty("connection", "close");
connection.setRequestProperty("Content-Type", "application/json; charset=utf-8");
connection.setRequestProperty("Accept", "application/json");
connection.setRequestProperty("Authorization", "Basic " + encodedCredentials);
connection.setRequestMethod("POST");
connection.setDoOutput(true);
connection.setUseCaches(false);

//write JSON to output stream
JsonWriter writer = Json.createWriter(connection.getOutputStream());
writer.writeObject(request);
writer.close();

//send request
int responseCode = connection.getResponseCode();

//get correct input stream
InputStream readerStream = responseCode == 200 ? connection.getInputStream() : connection.getErrorStream();
JsonObject response = Json.createReader(readerStream).readObject();

return response;

}

//This is an EXAMPLE of the payload-Array.
$payload = array(
'RequestHeader' => array(
'SpecVersion' => "1.7",
'CustomerId' => "[YOUR CUSTOMERID]",
'RequestId' => "aScdFewDSRFrfas2wsad3",
'RetryIndicator' => 0,
'ClientInfo' => array(
'ShopInfo' => "My Shop",
'OsInfo' => "Windows Server 2013"
)
),
'TerminalId' => "[YOUR TERMINALID]",
'PaymentMethods' => array("DIRECTDEBIT","VISA"),
'Payment' => array(
'Amount' => array(
'Value' => "21065",
'CurrencyCode' => "EUR"
),
'OrderId' => "123test",
'PayerNote' => "A Note",
'Description' => "Test_Order_123test"
),
'Payer' => array(
'IpAddress' => "192.168.178.1",
'LanguageCode' => "en"
),
'ReturnUrls' => array(
'Success' => "https://myshop.com/success",
'Fail' => "https://myshop.com/fail"
),
'Notification' => array(
'PayerEmail' => "payee@mailcom",
'MerchantEmail' => "merchant@mail.com",
'NotifyUrl' => "https://myshop/callback"
),
'DeliveryAddressForm' => array(
'Display' => true,
'MandatoryFields' => array("CITY","COMPANY","COUNTRY","EMAIL","FIRSTNAME","LASTNAME","PHONE","SALUTATION","STATE","STREET","ZIP")
)
);
//$username and $password for the http-Basic Authentication
//$url is the SaferpayURL eg. https://www.saferpay.com/api/Payment/v1/PaymentPage/Initialize
//$payload is a multidimensional array, that assembles the JSON structure. Example see above
function do_curl($username,$password,$url, $payload){
//Set Options for CURL
$curl = curl_init($url);
curl_setopt($curl, CURLOPT_HEADER, false);
//Return Response to Application
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
//Set Content-Headers to JSON
curl_setopt($curl, CURLOPT_HTTPHEADER,array("Content-type: application/json","Accept: application/json; charset=utf-8"));
//Execute call via http-POST
curl_setopt($curl, CURLOPT_POST, true);
//Set POST-Body
//convert DATA-Array into a JSON-Object
curl_setopt($curl, CURLOPT_POSTFIELDS, json_encode($payload));
//WARNING!!!!!
//This option should NOT be "false", otherwise the connection is not secured
//You can turn it of if you're working on the test-system with no vital data
//PLEASE NOTE:
//Under Windows (using WAMP or XAMP) it is necessary to manually download and save the necessary SSL-Root certificates!
//To do so, please visit: http://curl.haxx.se/docs/caextract.html and Download the .pem-file
//Then save it to a folder where PHP has write privileges (e.g. the WAMP/XAMP-Folder itself)
//and then put the following line into your php.ini:
//curl.cainfo=c:\path\to\file\cacert.pem
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, true);
curl_setopt($curl, CURLOPT_SSL_VERIFYHOST, 2);
//HTTP-Basic Authentication for the Saferpay JSON-API.
//This will set the authentication header and encode the password & username in Base64 for you
curl_setopt($curl, CURLOPT_USERPWD, $username . ":" . $password);
//CURL-Execute & catch response
$jsonResponse = curl_exec($curl);
//Get HTTP-Status
//Abort if Status != 200
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
if ($status != 200) {
//IF ERROR
//Get http-Body (if aplicable) from CURL-response
$body = json_decode(curl_multi_getcontent($curl), true);
//Build array, containing the body (Response data, like Error-messages etc.) and the http-status-code
$response = array(
"status" => $status . " <|> " . curl_error($curl),
"body" => $body
);
} else {
//IF OK
//Convert response into an Array
$body = json_decode($jsonResponse, true);
//Build array, containing the body (Response-data) and the http-status-code
$response = array(
"status" => $status,
"body" => $body
);
}
//IMPORTANT!!!
//Close connection!
curl_close($curl);
//$response, again, is a multi-dimensional Array, containing the status-code ($response["status"]) and the API-response (if available) itself ($response["body"])
return $response;
}

If you include the redirect pages into your web-page using an iframe, you can react on size changes of the iframe content by listening to a message event containing the new sizing information.

Please note: Depending on the bank, issuer, or payment provider, the page can try to break out of the iframe or lack telling you the actual size of the content.

Handle JavaScript events from Saferpay (for JQuery 1.9 and higher):

$(window).bind('message', function (e) {
  switch (e.originalEvent.data.message) {
    case 'css':
      $('#iframe').css('height', e.originalEvent.data.height + "px");
      break;
  }
});

Granting IP-permission

As an additional security feature, you can also grant permissions to specific IPs. This way you can control the API access even further in connection with the authentication credentials. To do so, you need to log into the Saferpay Backoffice, for either production or test, then go under Settings > IP permissions and enter the IP, or IP range of your network/server!

Note: This feature is entirely optional and only supports IPv4 addresses only!

Building the correct API URL

Every request is differentiated by its own unique request URL. This way Saferpay knows which API-function you want to access. Combined with the base URL for either the production- or test-environment, you will get the complete API-URL. Here is an example of how to build this URL correctly:

Base URL production system:

https://www.saferpay.com/api

Base URL test system:

https://test.saferpay.com/api

Take the correct request URL and add it to the base URL. You can find it on the right side of the request-specification.

For instance, if you want to call PaymentPage Initialize, the request URL is:

/Payment/v1/PaymentPage/Initialize

Add this to the base URL and you will get the full API URL:

Full API URL production system:

https://www.saferpay.com/api/Payment/v1/PaymentPage/Initialize

Full API URL test system:

https://test.saferpay.com/api/Payment/v1/PaymentPage/Initialize

Error Handling

Successfully completed requests are confirmed with an http status code of 200 and contain the appropriate response message in the body.

If the request could not be completed successfully, this is indicated by a status code of 400 or higher and – if possible (some errors are generated by the web server itself, or the web application firewall and are thus outside of our control) – an error message stating the reason of the failure is included in the body of the response. The presence of an error message as specified in this document can be derived from the content type: if it’s application/json, then there is an error message present.

HTTP status codes:

200 OK (No error)
400 Validation error
401 Authentication of the request failed
402 Requested action failed
403 Access denied
406 Not acceptable (wrong accept header)
415 Unsupported media type (wrong content-type header)
500 Internal error

Info: The API timeout for requests should be 100 seconds! After that, a connection should be closed. Also, no further actions should be taken, until the request is answered or runs into a timeout, to prevent unwanted behavior.

Error Message

Arguments
ResponseHeader
mandatory, container
Contains general informations about the response.
Behavior
mandatory, string
What can be done to resolve the error?
Possible values: ABORT, OTHER_MEANS, RETRY, RETRY_LATER.
ErrorName
mandatory, string
Name / id of the error. These names will not change, so you may parse these and attach your logic to the ErrorName.
ErrorMessage
mandatory, string
Description of the error. The contents of this element might change without notice, so do not parse it.
TransactionId
string
Id of the failed transaction, if available
ErrorDetail
string[]
More details, if available. Contents may change at any time, so don’t parse it.
ProcessorName
string
Name of acquirer (if declined by acquirer) or processor
ProcessorResult
string
Result code returned by acquirer or processor
ProcessorMessage
string
Message returned by acquirer or processor

Example:

{
  "ResponseHeader": {
    "SpecVersion": "1.10",
    "RequestId": "[your request id]"
  },
  "Behavior": "ABORT",
  "ErrorName": "VALIDATION_FAILED",
  "ErrorMessage": "Request validation failed",
  "ErrorDetail": [
    "PaymentMeans.BankAccount.IBAN: The field IBAN is invalid."
  ]
}

List of behaviors:

ABORT Do not retry this request. It will never succeed.
RETRY Request is valid and understood, but can't be processed at this time. This request can be retried.
RETRY_LATER This request can be retried later after certain state/ error condition has been changed.
OTHER_MEANS Special case of retry. Please provide another means of payment.

List of error names (these names will not change, so you may parse these and attach your logic to the ErrorName):

ACTION_NOT_SUPPORTED The requested action is not supported in the given context or the action can't be executed with the request data.
ALIAS_INVALID The alias is not known or already used (in case of registration).
Solution: Use another alias for registration
AMOUNT_INVALID The amount does not adhere to the restrictions for this action. E.g. it might be exceeding the allowed capture amount.
AUTHENTICATION_FAILED Wrong password, wrong client certificate, invalid token, wrong HMAC.
Solution: Use proper credentials, fix HMAC calculation, use valid token
BLOCKED_BY_RISK_MANAGEMENT Action blocked by risk management
Solution: Unblock in Saferpay Risk Management (Backoffice)
CARD_CHECK_FAILED Invalid card number or cvc (this is only returned for the SIX-internal chard check feature for Alias/InsertDirect).
Solution: Let the card holder correct the entered data
CARD_CVC_INVALID Wrong cvc entered
Solution: Retry with correct cvc
CARD_CVC_REQUIRED Cvc not entered but required
Solution: Retry with cvc entered
CARD_EXPIRED Card expired
Solution: Use another card or correct expiry date
COMMUNICATION_FAILED The communication to the processor failed.
Solution: Try again or use another means of payment
COMMUNICATION_TIMEOUT Saferpay did not receive a response from the external system in time. It’s possible that an authorization was created, but Saferpay is not able to know this.
Solution: Check with the acquirer if there is an authorization which needs to be canceled.
CONDITION_NOT_SATISFIED The condition which was defined in the request could not be satisfied.
CURRENCY_INVALID Currency does not match referenced transaction currency.
GENERAL_DECLINED Transaction declined by unknown reason
INTERNAL_ERROR Internal error in Saferpay
Solution: Try again
NO_CONTRACT No contract available for the brand / currency combination.
Solution: Use another card or change the currency to match an existing contract or have the currency activated for the contract.
NO_CREDITS_AVAILABLE No more credits available for this account.
Solution: Buy more transaction credits
PAYMENTMEANS_INVALID Invalid means of payment (e.g. invalid card)
PERMISSION_DENIED No permission (e.g. terminal does not belong to the customer)
3DS_AUTHENTICATION_FAILED 3D-secure authentication failed – the transaction must be aborted.
Solution: Use another card or means of payment
TOKEN_EXPIRED The token is expired.
Solution: Create a new token.
TOKEN_INVALID The token either does not exist for this customer or was already used
TRANSACTION_ABORTED The transaction was aborted by the payer.
TRANSACTION_ALREADY_CAPTURED Transaction already captured.
TRANSACTION_DECLINED Declined by the processor.
Solution: Use another card or check details.
TRANSACTION_IN_WRONG_STATE
TRANSACTION_NOT_FOUND
TRANSACTION_NOT_STARTED The transaction was not started by the payer. Therefore, no final result for the transaction is available.
Solution: Try again later.
VALIDATION_FAILED Validation failed.
Solution: Fix request

Payment Page

The Payment Page Interface provides a simple and easy integration of Saferpay into your web shop, mobile app or other applications without the need to implement a user interface for card data entry. The Saferpay Payment Page can be used with a Saferpay eCommerce license as well as with a Saferpay Business license. It allows the processing of all payment methods that are available with Saferpay. Once integrated, more payment methods can be activated at any time and without major adjustments.

Payment Process with the Payment Page

This chapter will give you a simple overview about the transaction flow, when using the Payment Page

Important Note: If you have trouble understanding the transaction flow with the Payment Page in its detail, you may want to read our Saferpay Integration guide, which offers an in depth explanation on how to integrate the Payment Page, optional features, best practices and more.

Transaction-flow

  1. Payment Page Initialize
    • Initializes the Payment and generates the RedirectUrl for the Payment Page.
  2. Redirect to the RedirectUrl
  3. Return to ReturnUrl depending on the outcome of the transaction. The ReturnUrls are defined in step 1!
  4. Payment Page Assert
    • Gathers all the information about the payment, like LiabilityShift through 3D Secure and more, using the Token, gathered in step 1!
  5. Depending on the outcome of step 4 you may
  6. Transaction is finished!

PaymentPage Initialize

This method can be used to start a transaction with the Payment Page which may involve either DCC and / or 3d-secure

Request URL:

POST: /Payment/v1/PaymentPage/Initialize

Request

Arguments
RequestHeader
mandatory, container
General information about the request.
ConfigSet
string
This parameter let you define your payment page config (PPConfig) by name. If this parameters is not set, your default PPConfig will be applied if available.
When the PPConfig can't be found (e.g. wrong name), the Saferpay basic style will be applied to the payment page.
Id[1..20]
Example: name of your payment page config (case-insensitive)
TerminalId
mandatory, string
Saferpay terminal id
Numeric[8..8]
Example: 12345678
Payment
mandatory, container
Information about the payment (amount, currency, ...)
PaymentMethods
string[]
Used to restrict the means of payment which are available to the payer for this transaction. If only one payment method id is set, the payment selection step will be skipped.
Possible values: AMEX, BANCONTACT, BONUS, DINERS, DIRECTDEBIT, EPRZELEWY, EPS, GIROPAY, IDEAL, INVOICE, JCB, MAESTRO, MASTERCARD, MYONE, PAYPAL, PAYDIREKT, POSTCARD, POSTFINANCE, SAFERPAYTEST, SOFORT, TWINT, UNIONPAY, VISA, VPAY.
Example: ["VISA", "MASTERCARD"]
Wallets
string[]
Used to control if wallets should be enabled on the payment selection page and to go directly to the given wallet (if exactly one wallet is filled and PaymentMethods is not set).
Possible values: MASTERPASS.
Example: ["MASTERPASS"]
Payer
container
Information about the payer
RegisterAlias
container
If the given means of payment should be stored in Saferpay Secure Card Data storage (if applicable)
ReturnUrls
mandatory, container
Urls which are to be used to redirect the payer back to the shop if the transaction requires some kind of browser redirection (3d-secure, dcc)

These Urls are used by Saferpay to redirect the shopper back to the merchant shop. You may add query string parameters to identify your session, but please be aware that the shopper could modify these parameters inside the browser!
The whole url including query string parameters should be as short as possible to prevent issues with specific browsers and must not exceed 2000 characters.
Note: you should not add sensitive data to the query string, as its contents is plainly visible inside the browser and will be logged by our web servers.
Notification
container
Notification options
Styling
container
Styling options
BillingAddressForm
container
Used to have the payer enter his billing address in the payment process.
DeliveryAddressForm
container
Used to have the payer enter his delivery address in the payment process.
CardForm
container
Options for card data entry form (if applicable)

Example:

{
  "RequestHeader": {
    "SpecVersion": "1.10",
    "CustomerId": "[your customer id]",
    "RequestId": "[unique request identifier]",
    "RetryIndicator": 0
  },
  "TerminalId": "[your terminal id]",
  "Payment": {
    "Amount": {
      "Value": "100",
      "CurrencyCode": "CHF"
    },
    "OrderId": "Id of the order",
    "Description": "Description of payment"
  },
  "ReturnUrls": {
    "Success": "[your shop payment success url]",
    "Fail": "[your shop payment fail url]"
  }
}

Response

Arguments
ResponseHeader
mandatory, container
Contains general informations about the response.
Token
mandatory, string
Token for later referencing
Example: 234uhfh78234hlasdfh8234e1234
Expiration
mandatory, date
Expiration date / time of the generated token in ISO 8601 format in UTC. After this time, the token won’t be accepted for any further action.
Example: 2011-07-14T19:43:37+01:00
RedirectUrl
mandatory, string
Redirecturl for the payment page transaction. Simply add this to a "Pay Now"-button or do an automatic redirect.
Example: https://www.saferpay.com/vt2/api/PaymentPage/1234/12341234/z2p7a0plpgsd41m97wjvm5jza

Example:

{
  "ResponseHeader": {
    "SpecVersion": "1.10",
    "RequestId": "Id of the request"
  },
  "Token": "234uhfh78234hlasdfh8234e1234",
  "Expiration": "2015-01-30T12:45:22.258+01:00",
  "RedirectUrl": "https://www.saferpay.com/vt2/api/..."
}

PaymentPage Assert

Call this function to safely check the status of the transaction from your server. Depending on the payment provider, the resulting transaction may either be an authorization or may already be captured (meaning the financial flow was already triggered). This will be visible in the status of the transaction container returned in the response.

If the transaction failed (the payer was redirected to the Fail url or he manipulated the return url), an error response with an http status code 400 or higher containing an error message will be returned providing some information on the transaction failure.

Request URL:

POST: /Payment/v1/PaymentPage/Assert

Request

Arguments
RequestHeader
mandatory, container
General information about the request.
Token
mandatory, string
Token returned by initial call.
Id[1..50]
Example: 234uhfh78234hlasdfh8234e

Example:

{
  "RequestHeader": {
    "SpecVersion": "1.10",
    "CustomerId": "[your customer id]",
    "RequestId": "[unique request identifier]",
    "RetryIndicator": 0
  },
  "Token": "234uhfh78234hlasdfh8234e"
}

Response

Arguments
ResponseHeader
mandatory, container
Contains general informations about the response.
Transaction
mandatory, container
Information about the transaction
PaymentMeans
mandatory, container
Information about the means of payment
Payer
container
Information about the payer / card holder
RegistrationResult
container
Information about the SCD registration outcome
Liability
container
LiabilityShift information, replaces ThreeDs Info from api version 1.8
Dcc
container
Dcc information, if applicable

Example:

{
  "ResponseHeader": {
    "SpecVersion": "1.10",
    "RequestId": "[your request id]"
  },
  "Transaction": {
    "Type": "PAYMENT",
    "Status": "AUTHORIZED",
    "Id": "723n4MAjMdhjSAhAKEUdA8jtl9jb",
    "Date": "2015-01-30T12:45:22.258+01:00",
    "Amount": {
      "Value": "100",
      "CurrencyCode": "CHF"
    },
    "AcquirerName": "Saferpay Test Card",
    "AcquirerReference": "000000",
    "SixTransactionReference": "0:0:3:723n4MAjMdhjSAhAKEUdA8jtl9jb",
    "ApprovalCode": "012345"
  },
  "PaymentMeans": {
    "Brand": {
      "PaymentMethod": "VISA",
      "Name": "VISA Saferpay Test"
    },
    "DisplayText": "9123 45xx xxxx 1234",
    "Card": {
      "MaskedNumber": "912345xxxxxx1234",
      "ExpYear": 2015,
      "ExpMonth": 9,
      "HolderName": "Max Mustermann",
      "CountryCode": "CH"
    }
  },
  "Liability": {
    "LiabilityShift": true,
    "LiableEntity": "ThreeDs",
    "ThreeDs": {
      "Authenticated": true,
      "LiabilityShift": true,
      "Xid": "ARkvCgk5Y1t/BDFFXkUPGX9DUgs=",
      "VerificationValue": "AAABBIIFmAAAAAAAAAAAAAAAAAA="
    },
    "FraudFree": {
      "Id": "deab90a0458bdc9d9946f5ed1b36f6e8",
      "LiabilityShift": false,
      "Score": 0.6,
      "InvestigationPoints": [
        "susp_bill_ad",
        "susp_machine"
      ]
    }
  }
}

Transaction

Payment Process with the Transaction Interface

This chapter will give you a simple overview about the general transaction flow, when using the Transaction Interface.

Important Note: The Transaction Interface offers all sorts of options to perform transactions. This flow only describes the general flow. Furthermore, you may want to read our Saferpay Integration guide, which offers an in debth explanation on how to integrate the Transaction Interface, optional features, best practices and more.

Transaction-flow

  1. Transaction Initialize
  2. Open the RedirectUrl inside an HTML-iFrame, to show the hosted card entry form!
  3. Return to Return Url depending on the outcome of the 3D Secure procedure. The ReturnUrls are defined in step 1!
  4. Transaction Authorize
    • Authorizes the card, which has been gathered in step 2. Up until now, no transaction has been made!
  5. Depending on the outcome of step 4 you may
  6. Transaction is finished!

Transaction Initialize Business license

This method may be used to start a transaction which may involve either DCC and / or 3d-secure.

Warning: Only PCI certified merchants may submit the card-data directly, or use their own HTML form! Click here for more information!

Request URL:

POST: /Payment/v1/Transaction/Initialize

Request

Arguments
RequestHeader
mandatory, container
General information about the request.
ConfigSet
string
This parameter let you define your payment page config (PPConfig) by name. If this parameters is not set, your default PPConfig will be applied if available.
When the PPConfig can't be found (e.g. wrong name), the Saferpay basic style will be applied to the payment page.
Id[1..20]
Example: name of your payment page config (case-insensitive)
TerminalId
mandatory, string
Saferpay terminal to use for this authorization
Numeric[8..8]
Example: 12341234
Payment
mandatory, container
Information about the payment (amount, currency, ...)
PaymentMeans
container
Means of payment (either card data or a reference to a previously stored card).
Important: Only fully PCI certified merchants may directly use the card data. If your system is not explicitly certified to handle card data directly, then use the Saferpay Secure Card Data-Storage instead. If the customer enters a new card, you may want to use the Saferpay Hosted Register Form to capture the card data through Saferpay.
Payer
container
Information on the payer (IP-address)
ReturnUrls
mandatory, container
Urls which are to be used to redirect the payer back to the shop if the transaction requires some kind of browser redirection (3d-secure, dcc)

These Urls are used by Saferpay to redirect the shopper back to the merchant shop. You may add query string parameters to identify your session, but please be aware that the shopper could modify these parameters inside the browser!
The whole url including query string parameters should be as short as possible to prevent issues with specific browsers and must not exceed 2000 characters.
Note: you should not add sensitive data to the query string, as its contents is plainly visible inside the browser and will be logged by our web servers.
Styling
container
Styling options
Wallet
container
Wallet system to be used for the transaction (this cannot be combined with PaymentMeans above).
PaymentMethods
string[]
Used to restrict the means of payment which are available to the payer
Possible values: AMEX, BANCONTACT, BONUS, DINERS, DIRECTDEBIT, JCB, MAESTRO, MASTERCARD, MYONE, SAFERPAYTEST, UNIONPAY, VISA, VPAY. Additional values may be accepted but are ignored.
Example: ["VISA", "MASTERCARD"]
CardForm
container
Options for card data entry form (if applicable)

Example:

{
  "RequestHeader": {
    "SpecVersion": "1.10",
    "CustomerId": "[your customer id]",
    "RequestId": "[unique request id]",
    "RetryIndicator": 0
  },
  "TerminalId": "[your terminal id]",
  "Payment": {
    "Amount": {
      "Value": "100",
      "CurrencyCode": "CHF"
    }
  },
  "Payer": {
    "LanguageCode": "en"
  },
  "ReturnUrls": {
    "Success": "[your shop payment success url]",
    "Fail": "[your shop payment fail url]"
  },
  "Styling": {
    "CssUrl": "[your shop css url]"
  }
}

Response

Arguments
ResponseHeader
mandatory, container
Contains general informations about the response.
Token
mandatory, string
Id for referencing later
Example: 234uhfh78234hlasdfh8234e
Expiration
mandatory, date
Expiration date / time of the generated token in ISO 8601 format in UTC. After this time, the token won’t be accepted for any further action.
Example: 2015-01-30T13:45:22.258+02:00
LiabilityShift
boolean
Indicates if liability shift to issuer is possible or not. Not present if PaymentMeans container was not present in InitializeTransaction request. True, if liability shift to issuer is possible, false if not.
RedirectRequired
mandatory, boolean
True if a redirect must be performed to continue, false otherwise
Redirect
container
Mandatory if RedirectRequired is true. Contains the URL for the redirect to use for example the Saferpay hosted register form.

Example:

{
  "ResponseHeader": {
    "SpecVersion": "1.10",
    "RequestId": "[your request id]"
  },
  "Token": "234uhfh78234hlasdfh8234e",
  "Expiration": "2015-01-30T12:45:22.258+01:00",
  "LiabilityShift": false,
  "RedirectRequired": true,
  "Redirect": {
    "RedirectUrl": "https://www.saferpay.com/vt2/Api/...",
    "PaymentMeansRequired": true
  }
}

Transaction Authorize Business license

This function may be called to authorize a transaction which was started by a call to Transaction/Initialize.

Request URL:

POST: /Payment/v1/Transaction/Authorize

Request

Arguments
RequestHeader
mandatory, container
General information about the request.
Token
mandatory, string
Token returned by Initialize
Id[1..50]
Example: 234uhfh78234hlasdfh8234e
Condition
string
WITH_LIABILITY_SHIFT: the authorization will be executed if the previous 3d-secure process indicates that the liability shift to the issuer is possible (liability shift may still be declined with the authorization though). This condition will be ignored for brands which Saferpay does not offer 3d-secure for.

If left out, the authorization will be done if allowed, but possibly without liability shift to the issuer. See the specific result codes in the response message.
Possible values: WITH_LIABILITY_SHIFT.
Example: WITH_LIABILITY_SHIFT
VerificationCode
string
Card verification code if available
Numeric[3..4]
Example: 123
RegisterAlias
container
Controls whether the given means of payment should be stored inside the saferpay Secure Card Data storage.

Example:

{
  "RequestHeader": {
    "SpecVersion": "1.10",
    "CustomerId": "[your customer id]",
    "RequestId": "[unique request id]",
    "RetryIndicator": 0
  },
  "Token": "sdu5ymxx210y2dz1ggig2ey0o",
  "VerificationCode": "123"
}

Response

Arguments
ResponseHeader
mandatory, container
Contains general informations about the response.
Transaction
mandatory, container
Information about the transaction
PaymentMeans
mandatory, container
Information about the means of payment
Payer
container
Information about the payer / card holder
RegistrationResult
container
Information about the Secure Card Data registration outcome.
Liability
container
LiabilityShift information, replaces ThreeDs Info from api version 1.8
Dcc
container
Dcc information, if applicable

Example:

{
               "ResponseHeader": {
                 "SpecVersion": "1.10",
                 "RequestId": "[your request id]",
               },
               "Transaction": {
                 "Type": "PAYMENT",
                 "Status": "AUTHORIZED",
                 "Id": "MUOGAWA9pKr6rAv5dUKIbAjrCGYA",
                 "Date": "2015-09-18T09:19:27.078Z",
                 "Amount": {
                   "Value": "100",
                   "CurrencyCode": "CHF"
                 },
                 "AcquirerName": "AcquirerName",
                 "AcquirerReference": "Reference",
                 "SixTransactionReference":"0:0:3:MUOGAWA9pKr6rAv5dUKIbAjrCGYA",
                 "ApprovalCode":"012345"
               },
               "PaymentMeans": {
                 "Brand": {
                   "PaymentMethod": "VISA",
                   "Name": "VISA Saferpay Test"
               },
               "DisplayText": "9123 45xx xxxx 1234",
               "Card": {
                 "MaskedNumber": "912345xxxxxx1234",
                 "ExpYear": 2015,
                 "ExpMonth": 9,
                 "HolderName": "Max Mustermann",
                 "CountryCode": "CH"
               },
               "Payer": {
                 "IpAddress": "1.2.3.4",
                 "IpLocation": "DE"
               },
               "Liability": {
                 "LiabilityShift": true,
                 "LiableEntity": "ThreeDs",
                 "ThreeDs": {
                   "Authenticated": true,
                   "LiabilityShift": true,
                   "Xid": "ARkvCgk5Y1t/BDFFXkUPGX9DUgs=",
                   "VerificationValue": "AAABBIIFmAAAAAAAAAAAAAAAAAA="
                 },
                 "FraudFree": {
                   "Id": "deab90a0458bdc9d9946f5ed1b36f6e8",
                   "LiabilityShift": false,
                   "Score": 0.6,
                   "InvestigationPoints": ["susp_bill_ad", "susp_machine"]
                 }
               }
             }

Transaction QueryPaymentMeans Business license

This method may be used to query the payment means and payer data (address) after initialize and wallet redirect.

Request URL:

POST: /Payment/v1/Transaction/QueryPaymentMeans

Request

This function may be called to retrieve information on the means of payment which was entered / chosen by the payer after the browser is redirected to the successUrl.
For MasterPass, the address the payer has selected in his wallet is returned as well as the RedirectUrl for DCC if DCC was skipped by the EnableAmountAdjustment attribute in Initialize.

Arguments
RequestHeader
mandatory, container
General information about the request.
Token
mandatory, string
Token returned by Initialize
Id[1..50]
Example: 234uhfh78234hlasdfh8234e
ReturnUrls
container
Urls which are to be used to redirect the payer back to the shop if the transaction requires some kind of browser redirection (3d-secure, dcc)

These Urls are used by Saferpay to redirect the shopper back to the merchant shop. You may add query string parameters to identify your session, but please be aware that the shopper could modify these parameters inside the browser!
The whole url including query string parameters should be as short as possible to prevent issues with specific browsers and must not exceed 2000 characters.
Note: you should not add sensitive data to the query string, as its contents is plainly visible inside the browser and will be logged by our web servers.

Example:

{
  "RequestHeader": {
    "SpecVersion": "1.10",
    "CustomerId": "[your customer id]",
    "RequestId": "[unique request id]",
    "RetryIndicator": 0
  },
  "Token": "sdu5ymxx210y2dz1ggig2ey0o"
}

Response

Arguments
ResponseHeader
mandatory, container
Contains general informations about the response.
PaymentMeans
mandatory, container
Information about the means of payment
Payer
container
Information about the payer / card holder
RedirectRequired
mandatory, boolean
RedirectUrl
string
Available if DCC may be performed.

Example:

{
              "ResponseHeader": {
                "SpecVersion": "1.10",
                "RequestId": "[your request id]",
              },
              "PaymentMeans": {
                "Brand": {
                  "PaymentMethod": "VISA",
                  "Name": "VISA Saferpay Test"
                },
                DisplayText": "9123 45xx xxxx 1234",
                "Card":{
                  "MaskedNumber": "912345xxxxxx1234",
                  "ExpYear": 2015,
                  "ExpMonth": 9,
                  "HolderName": "Max Mustermann",
                  "CountryCode": "CH"
                }
              },
              "Payer": {
                "IpAddress": "1.2.3.4",
                "IpLocation": "DE"
              }
            }

Transaction AdjustAmount Business license

This method may be used to adjust the amount after query payment means.

Request URL:

POST: /Payment/v1/Transaction/AdjustAmount

Request

This function allows a change of the authorization amount which was originally set by Initialize.
For the time being, this is only allowed for MasterPass business integration scenario and requires a flag having been set in the Initialize call.

Arguments
RequestHeader
mandatory, container
General information about the request.
Token
mandatory, string
Token returned by Initialize
Id[1..50]
Example: 234uhfh78234hlasdfh8234e
Amount
mandatory, container
The new amount

Example:

{
  "RequestHeader": {
    "SpecVersion": "1.10",
    "CustomerId": "[your customer id]",
    "RequestId": "[unique request id]",
    "RetryIndicator": 0
  },
  "Token": "sdu5ymxx210y2dz1ggig2ey0o",
  "Amount": {
    "Value": "110",
    "CurrencyCode": "CHF"
  }
}

Response

Arguments
ResponseHeader
mandatory, container
Contains general informations about the response.

Example:

{
  "ResponseHeader": {
    "SpecVersion": "1.10",
    "RequestId": "[your request id]"
  }
}

Transaction AuthorizeDirect Business license

This function may be used to directly authorize transactions which do not require a redirect of the customer (e.g. direct debit or recurring transactions based on a previously registered alias).

Warning: Only PCI certified merchants may submit the card-data directly, or use their own HTML form! Click here for more information!

Request URL:

POST: /Payment/v1/Transaction/AuthorizeDirect

Request

Arguments
RequestHeader
mandatory, container
General information about the request.
TerminalId
mandatory, string
Saferpay Terminal-Id
Numeric[8..8]
Example: 12341234
Payment
mandatory, container
Information about the payment (amount, currency, ...)
PaymentMeans
mandatory, container
Information on the means of payment. Important: Only fully PCI certified merchants may directly use the card data. If your system is not explicitly certified to handle card data directly, then use the Saferpay Secure Card Data-Storage instead. If the customer enters a new card, you may want to use the Saferpay Hosted Register Form to capture the card data through Saferpay.
RegisterAlias
container
Controls whether the given means of payment should be stored inside the saferpay Secure Card Data storage.
Payer
container
Information on the payer (IP-address)

Example:

{
  "RequestHeader": {
    "SpecVersion": "1.10",
    "CustomerId": "[your customer id]",
    "RequestId": "[unique request id]",
    "RetryIndicator": 0
  },
  "TerminalId": "[your terminal id]",
  "Payment": {
    "Amount": {
      "Value": "100",
      "CurrencyCode": "CHF"
    },
    "Description": "Test123",
    "PayerNote": "Order123_Testshop"
  },
  "PaymentMeans": {
    "Card": {
      "Number": "912345678901234",
      "ExpYear": 2015,
      "ExpMonth": 9,
      "HolderName": "Max Mustermann",
      "VerificationCode": "123"
    }
  }
}

Response

Arguments
ResponseHeader
mandatory, container
Contains general informations about the response.
Transaction
mandatory, container
Information about the transaction
PaymentMeans
mandatory, container
Information about the means of payment
Payer
container
Information about the payer / card holder
RegistrationResult
container
Information about the Secure Card Data registration outcome.

Example:

{
               "ResponseHeader": {
                 "SpecVersion": "1.10",
                 "RequestId": "[your request id]",
               },
               "Transaction": {
                 "Type": "PAYMENT",
                 "Status": "AUTHORIZED",
                 "Id": "723n4MAjMdhjSAhAKEUdA8jtl9jb",
                 "Date": "2015-01-30T13:45:22.258+02:00",
                 "Amount": {
                   "Value": "100",
                   "CurrencyCode": "CHF"
                 },
                 "AcquirerName": "AcquirerName",
                 "AcquirerReference": "Reference",
                 "SixTransactionReference":"0:0:3:723n4MAjMdhjSAhAKEUdA8jtl9jb",
                 "ApprovalCode":"012345"
               },
               "PaymentMeans": {
                 "Brand": {
                   "PaymentMethod": "VISA",
                   "Name": "VISA Saferpay Test"
                 },
                 DisplayText": "9123 45xx xxxx 1234",
                 "Card":{
                   "MaskedNumber": "912345xxxxxx1234",
                   "ExpYear": 2015,
                   "ExpMonth": 7,
                   "HolderName": "Max Mustermann",
                   "CountryCode": "CH"
                 }
               },
               "Payer": {
                 "IpAddress": "1.2.3.4",
                 "IpLocation": "DE"
               }
             }

Transaction AuthorizeReferenced Business license

This method may be used to perform follow-up authorizations to an earlier transaction. At this time, the referenced (initial) transaction must have been performed setting either the recurring or installment option.

Request URL:

POST: /Payment/v1/Transaction/AuthorizeReferenced

Request

Arguments
RequestHeader
mandatory, container
General information about the request.
TerminalId
mandatory, string
Saferpay Terminal-Id
Numeric[8..8]
Example: 12341234
Payment
mandatory, container
Information about the payment (amount, currency, ...)
TransactionReference
mandatory, container
Reference to previous transaction.

Exactly one element must be set.
SuppressDcc
boolean
Used to suppress direct currency conversion

Example:

{
  "RequestHeader": {
    "SpecVersion": "1.10",
    "CustomerId": "[your customer id]",
    "RequestId": "[unique request id]",
    "RetryIndicator": 0
  },
  "TerminalId": "[your terminal id]",
  "Payment": {
    "Amount": {
      "Value": "100",
      "CurrencyCode": "CHF"
    },
    "Description": "Test123",
    "PayerNote": "Order123_Testshop"
  },
  "TransactionReference": {
    "TransactionId": "723n4MAjMdhjSAhAKEUdA8jtl9jb"
  }
}

Response

Arguments
ResponseHeader
mandatory, container
Contains general informations about the response.
Transaction
mandatory, container
Information about the transaction
PaymentMeans
mandatory, container
Information about the means of payment
Payer
container
Information about the payer / card holder
Dcc
container
Dcc information, if applicable

Example:

{
               "ResponseHeader": {
                 "SpecVersion": "1.10",
                 "RequestId": "[your request id]",
               },
               "Transaction": {
                 "Type": "PAYMENT",
                 "Status": "AUTHORIZED",
                 "Id": "723n4MAjMdhjSAhAKEUdA8jtl9jb",
                 "Date": "2015-01-30T13:45:22.258+02:00",
                 "Amount": {
                   "Value": "100",
                   "CurrencyCode": "CHF"
                 },
                 "AcquirerName": "AcquirerName",
                 "AcquirerReference": "Reference",
                 "SixTransactionReference":"0:0:3:723n4MAjMdhjSAhAKEUdA8jtl9jb",
                 "ApprovalCode":"012345"
               },
               "PaymentMeans": {
                 "Brand": {
                   "PaymentMethod": "VISA",
                   "Name": "VISA Saferpay Test"
                 },
                 DisplayText": "9123 45xx xxxx 1234",
                 "Card":{
                   "MaskedNumber": "912345xxxxxx1234",
                   "ExpYear": 2015,
                   "ExpMonth": 7,
                   "HolderName": "Max Mustermann",
                   "CountryCode": "CH"
                 }
               },
               "Payer": {
                 "IpAddress": "1.2.3.4",
                 "IpLocation": "DE"
               },
               "Dcc":{
                 "PayerAmount":{
                 "Value":"109",
                 "CurrencyCode":"USD"
               }
             }

Transaction Capture

This method may be used to finalize previously authorized transactions and refunds.

Request URL:

POST: /Payment/v1/Transaction/Capture

Request

Arguments
RequestHeader
mandatory, container
General information about the request.
TransactionReference
mandatory, container
Reference to authorization.

Exactly one element must be set.
Amount
container
Currency must match the original transaction currency (request will be declined if currency does not match)
Billpay
container
Optional Billpay specific options.
PendingNotification
container
Optional pending notification capture options for Paydirekt transactions.
Marketplace
container
Optional Marketplace capture parameters.

Example:

{
  "RequestHeader": {
    "SpecVersion": "1.10",
    "CustomerId": "[your customer id]",
    "RequestId": "[unique request id]",
    "RetryIndicator": 0
  },
  "TransactionReference": {
    "TransactionId": "723n4MAjMdhjSAhAKEUdA8jtl9jb"
  }
}

Response

Arguments
ResponseHeader
mandatory, container
Contains general informations about the response.
CaptureId
string
CaptureId of the created capture. Must be stored for later reference (eg refund).
Id[1..64]
Example: ECthWpbv1SI6SAIdU2p6AIC1bppA_c
Status
mandatory, string
Current status of the capture. (PENDING is only used for paydirekt at the moment)
Possible values: PENDING, CAPTURED.
Date
mandatory, date
Date and time of capture. Not set if the capture state is pending.
Example: 2014-04-25T08:33:44.159+01:00
Invoice
container
Optional infos for invoice based payments.

Example:

{
  "ResponseHeader": {
    "SpecVersion": "1.10",
    "RequestId": "[your request id]"
  },
  "CaptureId": "723n4MAjMdhjSAhAKEUdA8jtl9jb",
  "Status": "CAPTURED",
  "Date": "2015-01-30T12:45:22.258+01:00"
}

Transaction MultipartCapture

This method may be used to capture multiple parts of an authorized transaction.

Important:

  • MultipartCapture is available for SIX Acquiring contracts only!
  • Your live merchant-account needs to be configured, in order to support Multipart Captures, or the request will fail!
  • No MultipartCapture request should be sent before receiving the response of a preceeding request (i.e. no parallel calls are allowed).
  • The sum of multipart captures must not exceed the authorized amount.
  • A unique OrderPartId must be used for each request.

Request URL:

POST: /Payment/v1/Transaction/MultipartCapture

Request

Arguments
RequestHeader
mandatory, container
General information about the request.
TransactionReference
mandatory, container
Reference to authorization.

Exactly one element must be set.
Amount
mandatory, container
Currency must match the original transaction currency (request will be declined if currency does not match)
Type
mandatory, string
'PARTIAL' if more captures should be possible later on, 'FINAL' if no more captures will be done on this authorization.
Possible values: PARTIAL, FINAL.
OrderPartId
mandatory, string
Must be unique. It identifies each individual step and is especially important for follow-up actions such as refund.
Id[1..80]
Example: kh9ngajrfe6wfu3d0c
Marketplace
container
Optional Marketplace capture parameters.

Example:

{
    "RequestHeader": {
      "SpecVersion": "1.10",
      "CustomerId": "[your customer id]",
      "RequestId": "[unique request identifier]",
      "RetryIndicator": 0
    },
    "TransactionReference": {
        "TransactionId": "723n4MAjMdhjSAhAKEUdA8jtl9jb"
    },
    "Amount": {
        "Value": "1000",
        "CurrencyCode": "CHF"
    },
    "Type": "PARTIAL",
    "OderPartId": "123456789",
    "Marketplace": {
        "SubmerchantId": "17312345",
        "Fee": {
            "Value": "500",
            "CurrencyCode": "CHF"
        }
    }
}

Response

Arguments
ResponseHeader
mandatory, container
Contains general informations about the response.
CaptureId
string
CaptureId of the created capture. Must be stored for later reference (eg refund).
Id[1..64]
Example: ECthWpbv1SI6SAIdU2p6AIC1bppA_c
Status
mandatory, string
Current status of the capture. (PENDING is only used for paydirekt at the moment)
Possible values: PENDING, CAPTURED.
Date
mandatory, date
Date and time of capture. Not set if the capture state is pending.
Example: 2018-08-08T12:45:22.258+01:00

Example:

{
  "ResponseHeader": {
    "SpecVersion": "1.10",
    "RequestId": "[unique request identifier]"
  },
  "CaptureId": "723n4MAjMdhjSAhAKEUdA8jtl9jb_c",
  "Status": "CAPTURED",
  "Date": "2018-08-08T12:45:22.258+01:00"
}

Transaction AssertCapture

This method is only supported for pending capture transactions (only used for paydirekt at the moment)

Request URL:

POST: /Payment/v1/Transaction/AssertCapture

Request

Arguments
RequestHeader
mandatory, container
General information about the request.
CaptureReference
mandatory, container
Reference to the capture.

Example:

{
  "RequestHeader": {
    "SpecVersion": "1.10",
    "CustomerId": "[your customer id]",
    "RequestId": "[unique request id]",
    "RetryIndicator": 0
  },
  "CaptureReference": {
    "CaptureId": "24218eabae254caea6f898e413fe_c"
  }
}

Response

Arguments
ResponseHeader
mandatory, container
Contains general informations about the response.
TransactionId
mandatory, string
Id of the referenced transaction.
AlphaNumeric[1..64]
Example: 723n4MAjMdhjSAhAKEUdA8jtl9jb
OrderId
string
OrderId of the referenced transaction. If present.
Id[1..80]
Example: c52ad18472354511ab2c33b59e796901
Status
mandatory, string
Current status of the capture. (PENDING is only used for paydirekt at the moment)
Possible values: PENDING, CAPTURED.
Date
mandatory, date
Date and time of capture. Not set if the capture state is pending.
Example: 2014-04-25T08:33:44.159+01:00

Example:

{
  "ResponseHeader": {
    "SpecVersion": "1.10",
    "RequestId": "[your request id]"
  },
  "TransactionId": "723n4MAjMdhjSAhAKEUdA8jtl9jb",
  "Status": "CAPTURED",
  "Date": "2015-01-30T12:45:22.258+01:00"
}

Transaction MultipartFinalize

This method may be used to finalize a transaction having one or more partial captures (i.e. marks the end of partial captures).

Request URL:

POST: /Payment/v1/Transaction/MultipartFinalize

Request

Arguments
RequestHeader
mandatory, container
General information about the request.
TransactionReference
mandatory, container
Reference to authorization.

Exactly one element must be set.

Example:

{
  "RequestHeader": {
    "SpecVersion": "1.10",
    "CustomerId": "[your customer id]",
    "RequestId": "[unique request identifier]",
    "RetryIndicator": 0
  },
  "TransactionReference": {
    "TransactionId": "723n4MAjMdhjSAhAKEUdA8jtl9jb"
  }
}

Response

Arguments
ResponseHeader
mandatory, container
Contains general informations about the response.

Example:

{
  "ResponseHeader": {
    "SpecVersion": "1.10",
    "RequestId": "[unique request identifier]"
  }
}

Transaction Refund Business license

This method may be called to refund a previous transaction.

Request URL:

POST: /Payment/v1/Transaction/Refund

Request

Arguments
RequestHeader
mandatory, container
General information about the request.
Refund
mandatory, container
Information about the refund (amount, currency, ...)
CaptureReference
mandatory, container
Reference to the capture you want to refund.
PendingNotification
container
Optional pending notification capture options for Paydirekt transactions.

Example:

{
  "RequestHeader": {
    "SpecVersion": "1.10",
    "CustomerId": "[your customer id]",
    "RequestId": "[your request id]",
    "RetryIndicator": 0
  },
  "Refund": {
    "Amount": {
      "Value": "100",
      "CurrencyCode": "CHF"
    }
  },
  "CaptureReference": {
    "CaptureId": "723n4MAjMdhjSAhAKEUdA8jtl9jb_c"
  }
}

Response

Arguments
ResponseHeader
mandatory, container
Contains general informations about the response.
Transaction
mandatory, container
Information about the transaction
PaymentMeans
mandatory, container
Information about the means of payment
Dcc
container
Dcc information, if applicable

Example:

{
  "ResponseHeader": {
    "SpecVersion": "1.10",
    "RequestId": "[your request id]"
  },
  "Transaction": {
    "Type": "REFUND",
    "Status": "AUTHORIZED",
    "Id": "723n4MAjMdhjSAhAKEUdA8jtl9jb",
    "Date": "2015-01-30T12:45:22.258+01:00",
    "Amount": {
      "Value": "100",
      "CurrencyCode": "CHF"
    },
    "AcquirerName": "Saferpay Test",
    "AcquirerReference": "000000",
    "SixTransactionReference": "0:0:3:723n4MAjMdhjSAhAKEUdA8jtl9jb",
    "ApprovalCode": "012345"
  },
  "PaymentMeans": {
    "Brand": {
      "PaymentMethod": "VISA",
      "Name": "VISA Saferpay Test"
    },
    "DisplayText": "9123 45xx xxxx 1234",
    "Card": {
      "MaskedNumber": "912345xxxxxx1234",
      "ExpYear": 2015,
      "ExpMonth": 9,
      "HolderName": "Max Mustermann",
      "CountryCode": "CH"
    }
  }
}

Transaction AssertRefund Business license

This method may be used to inquire the status and further information of pending refunds.

Attention: This method is only supported for pending refunds. A pending refund is only applicable for paydirekt transactions at the moment.

Request URL:

POST: /Payment/v1/Transaction/AssertRefund

Request

Arguments
RequestHeader
mandatory, container
General information about the request.
TransactionReference
mandatory, container
Reference to authorization.

Exactly one element must be set.

Example:

{
  "RequestHeader": {
    "SpecVersion": "1.10",
    "CustomerId": "[your customer id]",
    "RequestId": "[unique request id]",
    "RetryIndicator": 0
  },
  "TransactionReference": {
    "TransactionId": "723n4MAjMdhjSAhAKEUdA8jtl9jb"
  }
}

Response

Arguments
ResponseHeader
mandatory, container
Contains general informations about the response.
TransactionId
mandatory, string
Id of the referenced transaction.
AlphaNumeric[1..64]
Example: 723n4MAjMdhjSAhAKEUdA8jtl9jb
OrderId
string
OrderId of the referenced transaction. If present.
Id[1..80]
Example: c52ad18472354511ab2c33b59e796901
Status
mandatory, string
Current status of the capture. (PENDING is only used for paydirekt at the moment)
Possible values: PENDING, CAPTURED.
Date
mandatory, date
Date and time of capture. Not set if the capture state is pending.
Example: 2014-04-25T08:33:44.159+01:00

Example:

{
  "ResponseHeader": {
    "SpecVersion": "1.10",
    "RequestId": "[your request id]"
  },
  "TransactionId": "723n4MAjMdhjSAhAKEUdA8jtl9jb",
  "Status": "CAPTURED",
  "Date": "2015-01-30T12:45:22.258+01:00"
}

Transaction RefundDirect Business license

This method may be called to refund an amount to the given means of payment (not supported for all means of payment) without referencing a previous transaction. This might be the case if the original transaction was done with a card which is not valid any more.

Warning: Only PCI certified merchants may submit the card-data directly, or use their own HTML form! Click here for more information!

Request URL:

POST: /Payment/v1/Transaction/RefundDirect

Request

Arguments
RequestHeader
mandatory, container
General information about the request.
TerminalId
mandatory, string
Saferpay Terminal-Id
Numeric[8..8]
Example: 12341234
Refund
mandatory, container
Information about the refund (amount, currency, ...)
PaymentMeans
mandatory, container
Information on the means of payment. Important: Only fully PCI certified merchants may directly use the card data.
If your system is not explicitly certified to handle card data directly, then use the Saferpay Secure Card Data-Storage instead.
If the customer enters a new card, you may want to use the Saferpay Hosted Register Form to capture the card data through Saferpay.

Example:

{
  "RequestHeader": {
    "SpecVersion": "1.10",
    "CustomerId": "[your customer id]",
    "RequestId": "[your request id]",
    "RetryIndicator": 0
  },
  "TerminalId": "[your terminal id]",
  "Refund": {
    "Amount": {
      "Value": "100",
      "CurrencyCode": "CHF"
    }
  },
  "PaymentMeans": {
    "Alias": {
      "Id": "alias35nfd9mkzfw0x57iwx"
    }
  }
}

Response

Arguments
ResponseHeader
mandatory, container
Contains general informations about the response.
Transaction
mandatory, container
Information about the transaction
PaymentMeans
mandatory, container
Information about the means of payment
Dcc
container
Dcc information, if applicable

Example:

{
  "ResponseHeader": {
    "SpecVersion": "1.10",
    "RequestId": "[your request id]"
  },
  "Transaction": {
    "Type": "REFUND",
    "Status": "AUTHORIZED",
    "Id": "723n4MAjMdhjSAhAKEUdA8jtl9jb",
    "Date": "2015-01-30T12:45:22.258+01:00",
    "Amount": {
      "Value": "100",
      "CurrencyCode": "CHF"
    },
    "AcquirerName": "Saferpay Test",
    "AcquirerReference": "000000",
    "SixTransactionReference": "0:0:3:723n4MAjMdhjSAhAKEUdA8jtl9jb",
    "ApprovalCode": "012345"
  },
  "PaymentMeans": {
    "Brand": {
      "PaymentMethod": "VISA",
      "Name": "VISA Saferpay Test"
    },
    "DisplayText": "9123 45xx xxxx 1234",
    "Card": {
      "MaskedNumber": "912345xxxxxx1234",
      "ExpYear": 2015,
      "ExpMonth": 9,
      "HolderName": "Max Mustermann",
      "CountryCode": "CH"
    }
  }
}

Transaction Cancel

This method may be used to cancel previously authorized transactions and refunds.

Request URL:

POST: /Payment/v1/Transaction/Cancel

Request

Arguments
RequestHeader
mandatory, container
General information about the request.
TransactionReference
mandatory, container
Reference to transaction to be canceled.

Exactly one element must be set.

Example:

{
  "RequestHeader": {
    "SpecVersion": "1.10",
    "CustomerId": "[your customer id]",
    "RequestId": "[unique request id]",
    "RetryIndicator": 0
  },
  "TransactionReference": {
    "TransactionId": "723n4MAjMdhjSAhAKEUdA8jtl9jb"
  }
}

Response

Arguments
ResponseHeader
mandatory, container
Contains general informations about the response.
TransactionId
mandatory, string
Id of the referenced transaction.
Example: qiuwerhfi23h4189asdhflk23489
OrderId
string
OrderId of the referenced transaction. If present.
Example: c52ad18472354511ab2c33b59e796901
Date
mandatory, date
Date and time of cancel.
Example: 2014-04-25T08:33:44.159+01:00

Example:

{
  "ResponseHeader": {
    "SpecVersion": "1.10",
    "RequestId": "[your request id]"
  },
  "TransactionId": "723n4MAjMdhjSAhAKEUdA8jtl9jb",
  "OrderId": "c52ad18472354511ab2c33b59e796901",
  "Date": "2015-01-30T12:45:22.258+01:00"
}

Transaction RedirectPayment Business license

WARNING: This feature is deprecated and replaced by the Payment Page. Please use the parameter PaymentMethods to directly select the desired 3rd party provider!

Request URL:

POST: /Payment/v1/Transaction/RedirectPayment

Request

Arguments
RequestHeader
mandatory, container
General information about the request.
TerminalId
mandatory, string
Saferpay terminal to use for this authorization
Numeric[8..8]
Example: 12341234
Payment
mandatory, container
Information about the payment (amount, currency, ...)
ServiceProvider
mandatory, string
Service provider to be used for this payment
Possible values: PAYPAL, POSTCARD, POSTFINANCE.
Example: PAYPAL
Payer
container
Information on the payer (IP-address)
ReturnUrls
mandatory, container
Urls which are to be used to redirect the payer back to the shop if the transaction requires some kind of browser redirection (3d-secure, dcc)

These Urls are used by Saferpay to redirect the shopper back to the merchant shop. You may add query string parameters to identify your session, but please be aware that the shopper could modify these parameters inside the browser!
The whole url including query string parameters should be as short as possible to prevent issues with specific browsers and must not exceed 2000 characters.
Note: you should not add sensitive data to the query string, as its contents is plainly visible inside the browser and will be logged by our web servers.
Styling
container
Custom styling resource
Notification
container
Notification options

Example:

{
  "RequestHeader": {
    "SpecVersion": "1.10",
    "CustomerId": "[your customer id]",
    "RequestId": "[your request id]",
    "RetryIndicator": 0
  },
  "TerminalId": "[your terminal id]",
  "Payment": {
    "Amount": {
      "Value": "100",
      "CurrencyCode": "CHF"
    }
  },
  "ServiceProvider": "PAYPAL",
  "ReturnUrls": {
    "Success": "[your shop payment success url]",
    "Fail": "[your shop payment fail url]"
  }
}

Response

Arguments
ResponseHeader
mandatory, container
Contains general informations about the response.
Token
mandatory, string
Id for referencing later
Example: 234uhfh78234hlasdfh8234e
Expiration
mandatory, date
Expiration date / time of the generated token in ISO 8601 format in UTC. After this time, the token won’t be accepted for any further action.
Example: 2015-01-30T13:45:22.258+02:00
RedirectUrl
string
Url to redirect the browser to for payment processing
Example: https://www.saferpay.com/VT2/api/...

Example:

{
  "ResponseHeader": {
    "SpecVersion": "1.10",
    "RequestId": "[your request id]"
  },
  "Token": "234uhfh78234hlasdfh8234e",
  "Expiration": "2015-01-30T12:45:22.258+01:00",
  "RedirectUrl": "https://www.saferpay.com/vt2/Api/..."
}

Transaction AssertRedirectPayment Business license

WARNING: This feature is deprecated and replaced by the Payment Page. Please use the parameter PaymentMethods to directly select the desired 3rd party provider!

Request URL:

POST: /Payment/v1/Transaction/AssertRedirectPayment

Request

Arguments
RequestHeader
mandatory, container
General information about the request.
Token
mandatory, string
Token returned by initial call.
Id[1..50]
Example: 234uhfh78234hlasdfh8234e

Example:

{
  "RequestHeader": {
    "SpecVersion": "1.10",
    "CustomerId": "[your customer id]",
    "RequestId": "[unique request identifier]",
    "RetryIndicator": 0
  },
  "Token": "234uhfh78234hlasdfh8234e"
}

Response

Arguments
ResponseHeader
mandatory, container
Contains general informations about the response.
Transaction
mandatory, container
Information about the transaction
PaymentMeans
mandatory, container
Information about the means of payment
Payer
container
Information about the payer / card holder

Example:

{
  "ResponseHeader": {
    "SpecVersion": "1.10",
    "RequestId": "[your request id]"
  },
  "Transaction": {
    "Type": "PAYMENT",
    "Status": "AUTHORIZED",
    "Id": "723n4MAjMdhjSAhAKEUdA8jtl9jb",
    "Date": "2015-01-30T12:45:22.258+01:00",
    "Amount": {
      "Value": "100",
      "CurrencyCode": "CHF"
    },
    "AcquirerName": "Saferpay Test",
    "AcquirerReference": "8EZRQVT0ODW4ME525",
    "SixTransactionReference": "0:0:3:723n4MAjMdhjSAhAKEUdA8jtl9jb",
    "ApprovalCode": "012345"
  },
  "PaymentMeans": {
    "Brand": {
      "PaymentMethod": "VISA",
      "Name": "VISA Saferpay Test"
    },
    "DisplayText": "9123 45xx xxxx 1234",
    "Card": {
      "Number": "912345678901234",
      "MaskedNumber": "912345xxxxxx1234",
      "ExpYear": 2015,
      "ExpMonth": 9,
      "HolderName": "Max Mustermann",
      "CountryCode": "CH"
    }
  }
}

Secure Card Data

Alias Insert

This function may be used to insert an alias without knowledge about the card details. Therefore a redirect of the customer is required.

Request URL:

POST: /Payment/v1/Alias/Insert

Request

Arguments
RequestHeader
mandatory, container
General information about the request.
RegisterAlias
mandatory, container
Registration parameters
Type
mandatory, string
Type of payment means to register
Possible values: CARD, BANK_ACCOUNT, POSTFINANCE, TWINT.
Example: CARD
ReturnUrls
mandatory, container
Urls which are to be used to redirect the payer back to the shop.

These Urls are used by Saferpay to redirect the shopper back to the merchant shop. You may add query string parameters to identify your session, but please be aware that the shopper could modify these parameters inside the browser!
The whole url including query string parameters should be as short as possible to prevent issues with specific browsers and must not exceed 2000 characters.
Note: you should not add sensitive data to the query string, as its contents is plainly visible inside the browser and will be logged by our web servers.
Styling
container
Custom styling resource for the Hosted Register form.
LanguageCode
string
Language used for displaying forms.

Code-List:
de - German
en - English
fr - French
da - Danish
cs - Czech
es - Spanish
hr - Croatian
it - Italian
hu - Hungarian
nl - Dutch
nn - Norwegian
pl - Polish
pt - Portuguese
ru - Russian
ro - Romanian
sk - Slovak
sl - Slovenian
fi - Finnish
sv - Swedish
tr - Turkish
el - Greek
ja - Japanese
zh - Chinese
Example: de
Check
container
Parameters for checking the means of payment before registering. IMPORTANT NOTE: The Check function is only available for SIX Payment Services VISA and Mastercard acquiring contracts!
PaymentMethods
string[]
Used to restrict the means of payment which are available to the payer
Possible values: AMEX, BANCONTACT, BONUS, DINERS, DIRECTDEBIT, JCB, MAESTRO, MASTERCARD, MYONE, SAFERPAYTEST, UNIONPAY, VISA, VPAY. Additional values may be accepted but are ignored.
Example: ["VISA", "MASTERCARD"]
CardForm
container
Options for card data entry form (if applicable)

Example:

{
  "RequestHeader": {
    "SpecVersion": "1.10",
    "CustomerId": "[your customer id]",
    "RequestId": "[your request id]",
    "RetryIndicator": 0
  },
  "RegisterAlias": {
    "IdGenerator": "RANDOM"
  },
  "Type": "CARD",
  "ReturnUrls": {
    "Success": "[your shop alias registration success url]",
    "Fail": "[your shop alias registration fail url]"
  }
}

Response

Arguments
ResponseHeader
mandatory, container
Contains general informations about the response.
Token
mandatory, string
Id for referencing later
Example: 234uhfh78234hlasdfh8234e
Expiration
mandatory, date
Expiration date / time of the generated token in ISO 8601 format in UTC. After this time, the token won’t be accepted for any further action.
Example: 2015-01-30T13:45:22.258+02:00
RedirectUrl
mandatory, string
Saferpay-Url to post the form data to.
Example: https://www.saferpay.com/VT2/api/...

Example:

{
  "ResponseHeader": {
    "SpecVersion": "1.10",
    "RequestId": "[your request id]"
  },
  "Token": "234uhfh78234hlasdfh8234e",
  "Expiration": "2015-01-30T12:45:22.258+01:00",
  "RedirectUrl": "https://www.saferpay.com/vt2/api/..."
}

Alias AssertInsert

This method may be used to inquire the Alias Id and further information after a successful Alias Insert call.

Caution: Please DO NOT use the AssertInsert request for polling. You should always await the reception of the SuccessUrl.

Request URL:

POST: /Payment/v1/Alias/AssertInsert

Request

Arguments
RequestHeader
mandatory, container
General information about the request.
Token
mandatory, string
Token returned by initial call.
Id[1..50]
Example: 234uhfh78234hlasdfh8234e

Example:

{
  "RequestHeader": {
    "SpecVersion": "1.10",
    "CustomerId": "[your customer id]",
    "RequestId": "[unique request identifier]",
    "RetryIndicator": 0
  },
  "Token": "234uhfh78234hlasdfh8234e"
}

Response

Arguments
ResponseHeader
mandatory, container
Contains general informations about the response.
Alias
mandatory, container
Information about the registered alias.
PaymentMeans
mandatory, container
Information about the registered means of payment
CheckResult
container
Result of the Check

Example:

{
  "ResponseHeader": {
    "SpecVersion": "1.10",
    "RequestId": "[your request id]"
  },
  "Alias": {
    "Id": "alias35nfd9mkzfw0x57iwx",
    "Lifetime": 1000
  },
  "PaymentMeans": {
    "Brand": {
      "PaymentMethod": "VISA",
      "Name": "VISA Saferpay Test"
    },
    "DisplayText": "9123 45xx xxxx 1234",
    "Card": {
      "MaskedNumber": "912345xxxxxx1234",
      "ExpYear": 2015,
      "ExpMonth": 9,
      "HolderName": "Max Mustermann",
      "CountryCode": "CH"
    }
  }
}

Alias InsertDirect

This method may be used to insert an alias directly with card-data collected by using your own HTML form.

Warning: Only respectively PCI certified merchants may submit the card-data directly, or use their own HTML form! Click here for more information!

Request URL:

POST: /Payment/v1/Alias/InsertDirect

Request

Arguments
RequestHeader
mandatory, container
General information about the request.
RegisterAlias
mandatory, container
Registration parameters
PaymentMeans
mandatory, container
Means of payment to register
Check
container
Parameters for checking the means of payment before registering. IMPORTANT NOTE: The Check function is only available for SIX Payment Services VISA and Mastercard acquiring contracts!

Example:

{
  "RequestHeader": {
    "SpecVersion": "1.10",
    "CustomerId": "[your customer id]",
    "RequestId": "[your request id]",
    "RetryIndicator": 0
  },
  "PaymentMeans": {
    "Card": {
      "Number": "912345678901234",
      "ExpYear": 2015,
      "ExpMonth": 9,
      "HolderName": "Max Mustermann",
      "VerificationCode": "123"
    }
  },
  "RegisterAlias": {
    "IdGenerator": "RANDOM"
  }
}

Response

Arguments
ResponseHeader
mandatory, container
Contains general informations about the response.
Alias
mandatory, container
Information about the registered alias.
PaymentMeans
mandatory, container
Information about the registered means of payment
CheckResult
container
Result of the Check

Example:

{
  "ResponseHeader": {
    "SpecVersion": "1.10",
    "RequestId": "[your request id]"
  },
  "Alias": {
    "Id": "alias35nfd9mkzfw0x57iwx",
    "Lifetime": 1000
  },
  "PaymentMeans": {
    "Brand": {
      "PaymentMethod": "VISA",
      "Name": "VISA Saferpay Test"
    },
    "DisplayText": "9123 45xx xxxx 1234",
    "Card": {
      "MaskedNumber": "912345xxxxxx1234",
      "ExpYear": 2015,
      "ExpMonth": 9,
      "HolderName": "Max Mustermann",
      "CountryCode": "CH"
    }
  }
}

Alias Delete

This method may be used to delete previously inserted aliases.

Request URL:

POST: /Payment/v1/Alias/Delete

Request

Arguments
RequestHeader
mandatory, container
General information about the request.
AliasId
mandatory, string
The Alias you want to delete. This value is case-insensitive.
Id[1..40]
Example: alias35nfd9mkzfw0x57iwx

Example:

{
  "RequestHeader": {
    "SpecVersion": "1.10",
    "CustomerId": "[your customer id]",
    "RequestId": "[unique request id]",
    "RetryIndicator": 0
  },
  "AliasId": "alias35nfd9mkzfw0x57iwx"
}

Response

Arguments
ResponseHeader
mandatory, container
Contains general informations about the response.

Example:

{
  "ResponseHeader": {
    "SpecVersion": "1.10",
    "RequestId": "[your request id]"
  }
}

Batch

Batch Close

This chapter covers the Batch Close via API

Note: If you want to trigger the batch-close via API, make sure, to turn the automatic batch off. Please log into the Saferpay Backoffice. Go to Settings => Terminals and select the desired terminal out of the list. Turn off the Automatic closure!

Request URL:

POST: /Payment/v1/Batch/Close

Request

Arguments
RequestHeader
mandatory, container
General information about the request.
TerminalId
mandatory, string
Saferpay Terminal-Id
Numeric[8..8]
Example: 12341234

Example:

{
  "RequestHeader": {
    "SpecVersion": "1.10",
    "CustomerId": "[your customer id]",
    "RequestId": "[unique request id]",
    "RetryIndicator": 0
  },
  "TerminalId": "[your terminal id]"
}

Response

Arguments
ResponseHeader
mandatory, container
Contains general informations about the response.

Example:

{
  "ResponseHeader": {
    "SpecVersion": "1.10",
    "RequestId": "[your request id]"
  }
}

OmniChannel

OmniChannel InsertAlias

This function may be used to create an alias by providing a SixTransactionReference.

Request URL:

POST: /Payment/v1/OmniChannel/InsertAlias

Request

Arguments
RequestHeader
mandatory, container
General information about the request.
RegisterAlias
mandatory, container
Registration parameters
SixTransactionReference
mandatory, string
SIX Transaction Reference
Example: 1:100002:199970683910

Example:

{
  "RequestHeader": {
    "SpecVersion": "1.10",
    "CustomerId": "[your customer id]",
    "RequestId": "[your request id]",
    "RetryIndicator": 0
  },
  "SixTransactionReference": "1:100002:1:87768996410",
  "RegisterAlias": {
    "IdGenerator": "RANDOM"
  }
}

Response

Arguments
ResponseHeader
mandatory, container
Contains general informations about the response.
Alias
mandatory, container
Information about the registered alias.
PaymentMeans
mandatory, container
Information about the registered means of payment
CheckResult
container
Result of the Check

Example:

{
  "ResponseHeader": {
    "SpecVersion": "1.10",
    "RequestId": "[your request id]"
  },
  "Alias": {
    "Id": "alias35nfd9mkzfw0x57iwx",
    "Lifetime": 1000
  },
  "PaymentMeans": {
    "Brand": {
      "PaymentMethod": "VISA",
      "Name": "VISA Saferpay Test"
    },
    "DisplayText": "9123 45xx xxxx 1234",
    "Card": {
      "MaskedNumber": "912345xxxxxx1234",
      "ExpYear": 2015,
      "ExpMonth": 9,
      "HolderName": "Max Mustermann",
      "CountryCode": "CH"
    }
  }
}

OmniChannel AcquireTransaction

This function may be used to acquire an authorized transaction by providing a SixTransactionReference. This transaction can then be captured or canceled.

Request URL:

POST: /Payment/v1/OmniChannel/AcquireTransaction

Request

This request allows to acquire an OmniChannel transaction.

Arguments
RequestHeader
mandatory, container
General information about the request.
TerminalId
mandatory, string
Saferpay terminal id
Numeric[8..8]
Example: 12345678
OrderId
string
Unambiguous order identifier defined by the merchant/ shop. This identifier might be used as reference later on.
Id[1..80]
Example: c52ad18472354511ab2c33b59e796901
SixTransactionReference
mandatory, string
SIX Transaction Reference
Example: 1:100002:199970683910

Example:

{
  "RequestHeader": {
    "SpecVersion": "1.10",
    "CustomerId": "[your customer id]",
    "RequestId": "[your request id]",
    "RetryIndicator": 0
  },
  "TerminalId": "17791723",
  "SixTransactionReference": "1:100002:1:87768996410",
  "OrderId": "Id of the order"
}

Response

This response returns an acquired OmniChannel transaction.

Arguments
ResponseHeader
mandatory, container
Contains general informations about the response.
Transaction
mandatory, container
Information about the transaction
PaymentMeans
mandatory, container
Information about the means of payment

Example:

{
  "ResponseHeader": {
    "SpecVersion": "1.10",
    "RequestId": "[your request id]"
  },
  "Transaction": {
    "Type": "PAYMENT",
    "Status": "AUTHORIZED",
    "Id": "723n4MAjMdhjSAhAKEUdA8jtl9jb",
    "Date": "2015-01-30T12:45:22.258+01:00",
    "Amount": {
      "Value": "100",
      "CurrencyCode": "CHF"
    },
    "AcquirerName": "Saferpay Test",
    "AcquirerReference": "8EZRQVT0ODW4ME525",
    "SixTransactionReference": "0:0:3:723n4MAjMdhjSAhAKEUdA8jtl9jb",
    "ApprovalCode": "012345"
  },
  "PaymentMeans": {
    "Brand": {
      "PaymentMethod": "VISA",
      "Name": "VISA Saferpay Test"
    },
    "DisplayText": "9123 45xx xxxx 1234",
    "Card": {
      "Number": "912345678901234",
      "MaskedNumber": "912345xxxxxx1234",
      "ExpYear": 2015,
      "ExpMonth": 9,
      "HolderName": "Max Mustermann",
      "CountryCode": "CH"
    }
  }
}

Container Dictionary

Container "Common_RequestHeader"

SpecVersion
mandatory, string
Version number of the interface specification. For new implementations, the newest Version should be used.
Possible values: 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8, 1.9, 1.10
Example: 1.10
CustomerId
mandatory, string
Saferpay customer id. Part of the Saferpay AccountID, which has the following format: 123123-12345678. The first Value is your CustomerID.
Numeric[1..8]
Example: 123123
RequestId
mandatory, string
Unique id generated by merchant. Must not change for subsequently resent requests.
Id[1..50]
Example: 33e8af17-35c1-4165-a343-c1c86a320f3b
RetryIndicator
mandatory, integer
0 if the request is sent for the first time, >=1 if it is a repetition.
Range: inclusive between 0 and 9
Example: 0
ClientInfo
container
Information about the caller (merchant host)

Container "Common_ResponseHeader"

RequestId
mandatory, string
RequestId of the original request header
Id[1..50]
Example: 33e8af17-35c1-4165-a343-c1c86a320f3b
SpecVersion
mandatory, string
Version number of the interface specification.
Possible values: 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8, 1.9, 1.10
Example: 1.10

Container "Payment_Models_BankAccountInfo"

IBAN
mandatory, string
International Bank Account Number in electronical format (without spaces).
AlphaNumeric[1..50]
Example: DE12500105170648489890
HolderName
string
Name of the account holder.
Iso885915[1..50]
Example: John Doe
BIC
string
Bank Identifier Code without spaces.
AlphaNumeric[8..11]
Example: INGDDEFFXXX
BankName
string
Name of the Bank.
CountryCode
string
ISO 2-letter country code of the IBAN origin (if available)
Example: CH

Container "Payment_Models_CaptureReference"

CaptureId
string
Id of the referenced capture.
Id[1..64]
Example: jCUC8IAQ1OCptA5I8jpzAMxC5nWA_c
TransactionId
string
Id of the referenced transaction. This should only be used if you don't have the CaptureId of the referenced Capture (probably, because it was performed with an older SpecVersion)
AlphaNumeric[1..64]
Example: 723n4MAjMdhjSAhAKEUdA8jtl9jb
OrderId
string
Unambiguous OrderId of the referenced transaction.
Id[1..80]
Example: c52ad18472354511ab2c33b59e796901
OrderPartId
string
OrderPartId of the referenced capture if a partial capture should be referenced and the CaptureId/TransactionId of the partial capture is not available.
Id[1..80]
Example: kh9ngajrfe6wfu3d0c

Container "Payment_Models_Data_Address"

FirstName
string
The payer's first name
Utf8[1..100]
Example: John
LastName
string
The payer's last name
Utf8[1..100]
Example: Doe
DateOfBirth
string
The payer's date of birth in ISO 8601 extended date notation
YYYY-MM-DD
AlphaNumeric[11..11]
Example: 1990-05-31
Company
string
The payer's company
Utf8[1..100]
Example: ACME Corp.
Gender
string
The payer's gender
Possible values: MALE, FEMALE, COMPANY.
Example: COMPANY
LegalForm
string
The payer's legal form
Possible values: AG, GmbH, Misc.
Example: AG
Street
string
The payer's street
Utf8[1..100]
Example: Bakerstreet 32
Street2
string
The payer's street, second line. Only use this, if you need two lines. It may not be supported by all acquirers.
Utf8[1..100]
Example: Stewart House
Zip
string
The payer's zip code
Utf8[1..100]
Example: 8000
City
string
The payer's city
Utf8[1..100]
Example: Zurich
CountrySubdivisionCode
string
The payer's country subdivision code
ISO 3166-2 country subdivision code
AlphaNumeric[1..3]
Example: ZH
CountryCode
string
The payer's country subdivision code
ISO 3166-1 alpha-2 country code
Alphabetic[2..2]
Example: CH
Phone
string
The payer's phone number
Utf8[1..100]
Example: +41 12 345 6789
Email
string
The payer's email address
Example: payer@provider.com

Container "Payment_Models_Data_AddressForm"

Display
mandatory, boolean
Specifies whether to show the address form or not.
MandatoryFields
string[]
List of fields which the payer must enter to proceed with the payment.
Possible values: CITY, COMPANY, COUNTRY, EMAIL, FIRSTNAME, LASTNAME, PHONE, SALUTATION, STATE, STREET, ZIP.
Example: ["FIRSTNAME", "LASTNAME", "PHONE"]

Container "Payment_Models_Data_Alias"

Id
mandatory, string
Id / name of the alias. This value is case-insensitive.
Id[1..40]
Example: alias35nfd9mkzfw0x57iwx
VerificationCode
string
Verification code (CVV, CVC) if applicable (if the alias referenced is a card).
Numeric[3..4]
Example: 123

Container "Payment_Models_Data_AliasInfo"

Id
mandatory, string
Id / name of the alias
Example: alias35nfd9mkzfw0x57iwx
Lifetime
mandatory, integer
Number of days this card is stored within Saferpay. Minimum 1 day, maximum 1600 days.
Example: 1000

Container "Payment_Models_Data_AliasInsertCheck"

Type
mandatory, string
Type of check to perform.
Possible values: ONLINE.
Example: ONLINE
TerminalId
mandatory, string
Saferpay Terminal-Id to be used for checking.
Numeric[8..8]
Example: 12341234

Container "Payment_Models_Data_AliasInsertCheckResult"

Result
mandatory, string
The result of the online check.
Possible values: OK, NOT_PERFORMED.
Message
mandatory, string
More details, if available. Contents may change at any time, so don’t parse it.
Example: Online card check was successful.

Container "Payment_Models_Data_Amount"

Value
mandatory, string
Amount in minor unit (CHF 1.00 ⇒ Value=100). Only Integer values will be accepted!
Example: 100
CurrencyCode
mandatory, string
ISO 4217 3-letter currency code (CHF, USD, EUR, ...)
Example: CHF

Container "Payment_Models_Data_BankAccount"

IBAN
mandatory, string
International Bank Account Number in electronical format (without spaces).
AlphaNumeric[1..50]
Example: DE12500105170648489890
HolderName
string
Name of the account holder.
Iso885915[1..50]
Example: John Doe
BIC
string
Bank Identifier Code without spaces.
AlphaNumeric[8..11]
Example: INGDDEFFXXX
BankName
string
Name of the Bank.

Container "Payment_Models_Data_BasicPayment"

Amount
mandatory, container
Amount data (currency, value, etc.)
OrderId
string
Unambiguous order identifier defined by the merchant / shop. This identifier might be used as reference later on.
Id[1..80]
Example: c52ad18472354511ab2c33b59e796901
Description
string
A human readable description provided by the merchant that can be displayed in web sites.
Utf8[1..1000]
Example: Description
PayerNote
string
Text which will be printed on payer's debit note. Supported by SIX Acquiring. No guarantee that it will show up on the payer's debit note, because his bank has to support it too.
Please note that maximum allowed characters are rarely supported. It's usually around 10-12.
Utf8[1..50]
Example: Payernote

Container "Payment_Models_Data_BillpayCapture"

DelayInDays
integer
Number of days to delay the due date of the invoice / direct debit (see billpay for specifics)
Example: 10

Container "Payment_Models_Data_Brand"

PaymentMethod
string
alphanumeric id of the payment method / brand
Possible values: AMEX, BANCONTACT, BONUS, DINERS, DIRECTDEBIT, EPRZELEWY, EPS, GIROPAY, IDEAL, INVOICE, JCB, MAESTRO, MASTERCARD, MYONE, PAYPAL, PAYDIREKT, POSTCARD, POSTFINANCE, SAFERPAYTEST, SOFORT, TWINT, UNIONPAY, VISA, VPAY.
Name
mandatory, string
Name of the Brand (Visa, Mastercard, an so on – might change over time, only use for display, never for parsing). Only use it for display, never for parsing and/or mapping! Use PaymentMethod instead.
Example: SaferpayTestCard

Container "Payment_Models_Data_Card"

Number
mandatory, string
Card number without separators
Example: 1234123412341234
ExpYear
mandatory, integer
Year of expiration
Range: inclusive between 2000 and 9999
Example: 2015
ExpMonth
mandatory, integer
Month of expiration (eg 9 for September)
Range: inclusive between 1 and 12
Example: 9
HolderName
string
Name of the card holder
Utf8[1..50]
Example: John Doe
VerificationCode
string
Verification code (CVV, CVC) if applicable
Numeric[3..4]
Example: 123

Container "Payment_Models_Data_CardForm"

HolderName
string
This parameter let you customize the holder name field on the card entry form. Per default, a mandatory holder name field is shown.
Possible values: NONE, MANDATORY.
Example: MANDATORY

Container "Payment_Models_Data_CardInfo"

MaskedNumber
mandatory, string
Masked card number
Example: 912345xxxxxx1234
ExpYear
mandatory, integer
Year of expiration
Example: 2015
ExpMonth
mandatory, integer
Month of expiration (eg 9 for September)
Example: 9
HolderName
string
Name of the card holder (if known)
Example: John Doe
CountryCode
string
ISO 2-letter country code of the card origin (if available)
Example: CH
HashValue
string
The HashValue, if the hash generation is configured for the customer.

Container "Payment_Models_Data_ClientInfo"

ShopInfo
string
Name and version of the shop software
Iso885915[1..100]
Example: My Shop
OsInfo
string
Information on the operating system
Iso885915[1..100]
Example: Windows Server 2013

Container "Payment_Models_Data_DccInfo"

PayerAmount
mandatory, container
Amount in payer’s currency

Container "Payment_Models_Data_DirectDebitInfo"

MandateId
mandatory, string
The unique Mandate reference, required for german direct debit payments.
CreditorId
mandatory, string
Creditor id, required for german direct debit payments.

Container "Payment_Models_Data_FraudFreeInfo"

Id
mandatory, string
Id to identify the fraud free request.
LiabilityShift
mandatory, boolean
Indicates whether liability shift to Fraugster is possible or not. True, if liability shift to issuer is possible, false if not (only SSL transaction).
Score
mandatory, decimal number
Fraud score, indicates the risk of a transaction being fraudulent.
Investigationpoints
string[]
Indicate the issues with the transaction.
ErrorMessage
string
Error message which indicates why FraudFree could not process the request.

Container "Payment_Models_Data_InstallmentOptions"

Initial
mandatory, boolean
If set to true, the authorization may later be referenced for installment followup transactions.

Container "Payment_Models_Data_InvoiceInfo"

Payee
container
Information about the payee, eg billpay, who is responsible for collecting the bill
ReasonForTransfer
string
The reason for transfer to be stated when paying the invoice (transfer of funds)
DueDate
date
The date by which the invoice needs to be settled

Container "Payment_Models_Data_LiabilityInfo"

LiabilityShift
mandatory, boolean
Is liability shifted for this transaction
LiableEntity
mandatory, string
Indicates who takes the liability for the transaction
ThreeDs
container
Details about ThreeDs if applicable
FraudFree
container
Details about FraudFree if applicable

Container "Payment_Models_Data_MarketplaceCapture"

SubmerchantId
mandatory, string
The id of the marketplace submerchant on whose behalf the capture or refund capture is being made.
Id[1..15]
Fee
container
The marketplace fee that will be charged from the marketplace to the submerchant.
The properties Fee and FeeRefund cannot be used simultaneously.
FeeRefund
container
The fee amount that will be refunded from the marketplace to the submerchant.
The properties Fee and FeeRefund cannot be used simultaneously.

Container "Payment_Models_Data_Notification"

MerchantEmail
string
Email address to which a confirmation email will be sent to the merchant after successful authorizations.
Example: merchant@saferpay.com
PayerEmail
string
Email address to which a confirmation email will be sent to the payer after successful authorizations.
Example: payer@saferpay.com
NotifyUrl
recommended, string
Url to which Saferpay will send the asynchronous confirmation for the transaction. Supported schemes are http and https. You also have to make sure to support the GET-method.
Example: https://merchanthost/notify

Container "Payment_Models_Data_Payer"

IpAddress
string
IPv4 address of the card holder / payer if available. Dotted quad notation.
Example: 111.111.111.111
LanguageCode
string
Language to be used if Saferpay displays something to the payer.

Code-List:
de - German
en - English
fr - French
da - Danish
cs - Czech
es - Spanish
et - Estonian
hr - Croatian
it - Italian
hu - Hungarian
lv - Latvian
lt - Lithuanian
nl - Dutch
nn - Norwegian
pl - Polish
pt - Portuguese
ru - Russian
ro - Romanian
sk - Slovak
sl - Slovenian
fi - Finnish
sv - Swedish
tr - Turkish
el - Greek
ja - Japanese
zh - Chinese
Example: de
DeliveryAddress
container
Information on the payers delivery address
BillingAddress
container
Information on the payers billing address

Container "Payment_Models_Data_PayerInfo"

IpAddress
string
IPv4 address of the card holder / payer if available. Dotted quad notation.
Example: 111.111.111.111
IpLocation
string
The location the IpAddress, if available. This might be a valid country code or a special value for 'non-country' locations (anonymous proxy, satellite phone, ...).
Example: NZ
DeliveryAddress
container
BillingAddress
container

Container "Payment_Models_Data_Payment"

Amount
mandatory, container
Amount data (currency, value, etc.)
OrderId
recommended, string
Unambiguous order identifier defined by the merchant / shop. This identifier might be used as reference later on.
Id[1..80]
Example: c52ad18472354511ab2c33b59e796901
Description
string
A human readable description provided by the merchant that can be displayed in web sites.
Utf8[1..1000]
Example: Description
PayerNote
string
Text which will be printed on payer's debit note. Supported by SIX Acquiring. No guarantee that it will show up on the payer's debit note, because his bank has to support it too.
Please note that maximum allowed characters are rarely supported. It's usually around 10-12.
Utf8[1..50]
Example: Payernote
MandateId
string
Mandate reference of the payment. Needed for German direct debits (ELV) only. The value has to be unique.
Id[1..35]
Example: MandateId
Options
container
Specific payment options
Recurring
container
Recurring options – cannot be combined with Installment.
Installment
container
Installment options – cannot be combined with Recurring.

Container "Payment_Models_Data_PaymentMeans"

Card
container
Card data
BankAccount
container
Bank account data for direct debit transaction
Alias
container
Alias data if payment means was registered with Secure Card Data before.

Container "Payment_Models_Data_PaymentMeansInfo"

Brand
mandatory, container
Brand information
DisplayText
mandatory, string
Means of payment formatted / masked for display purposes
Example: DisplayText
Wallet
string
Name of Wallet, if the transaction was done by a wallet
Example: MasterPass
Card
container
Card data
BankAccount
container
Bank account data for direct debit transactions.
Twint
container
Twint data

Container "Payment_Models_Data_PaymentOptions"

PreAuth
boolean
Used to flag the transaction as a Pre-Athorization. This type of transaction is only supported with the following Acquiring: SIX Payment Services, B+S Card Service, ConCardis, Airplus and -after an agreement- with American Express.

Container "Payment_Models_Data_PaymentPagePayment"

Amount
mandatory, container
Amount data (currency, value, etc.)
OrderId
recommended, string
Unambiguous order identifier defined by the merchant / shop. This identifier might be used as reference later on.
Id[1..80]
Example: c52ad18472354511ab2c33b59e796901
Description
mandatory, string
A human readable description provided by the merchant that will be displayed in Payment Page.
Utf8[1..1000]
Example: Description of payment
PayerNote
string
Text which will be printed on payer's debit note. Supported by SIX Acquiring. No guarantee that it will show up on the payer's debit note, because his bank has to support it too.
Please note that maximum allowed characters are rarely supported. It's usually around 10-12.
Utf8[1..50]
Example: Payernote
MandateId
string
Mandate reference of the payment. Needed for German direct debits (ELV) only. The value has to be unique.
Id[1..35]
Example: MandateId
Options
container
Specific payment options
Recurring
container
Recurring options – cannot be combined with Installment.
Installment
container
Installment options – cannot be combined with Recurring.

Container "Payment_Models_Data_PaymentTransaction"

Type
mandatory, string
Type of transaction. One of 'PAYMENT'
Possible values: PAYMENT.
Example: PAYMENT
Status
mandatory, string
Current status of the transaction. One of 'AUTHORIZED', 'CAPTURED' or 'PENDING' (PENDING is only used for paydirekt at the moment)
Possible values: AUTHORIZED, CAPTURED, PENDING.
Example: AUTHORIZED
Id
mandatory, string
Unique Saferpay transaction id. Used to reference the transaction in any further step.
Example: K5OYS9Ad6Ex4rASU1IM1b3CEU8bb
Date
mandatory, date
Date / time of the authorization
Example: 2011-09-23T14:57:23.023+02.00
Amount
mandatory, container
Amount (currency, value, etc.) that has been authorized.
OrderId
string
OrderId given with request
Id[1..80]
Example: c52ad18472354511ab2c33b59e796901
AcquirerName
string
Name of the acquirer
Example: AcquirerName
AcquirerReference
string
Reference id of the acquirer (if available)
Example: AcquirerReference
SixTransactionReference
mandatory, string
Unique SIX transaction reference.
Example: 0:0:3:K5OYS9Ad6Ex4rASU1IM1b3CEU8bb
ApprovalCode
string
Approval id of the acquirer (if available)
Example: AcquirerReference
DirectDebit
container
Direct Debit information, if applicable
Example: AcquirerReference
Invoice
container
Invoice information, if applicable

Container "Payment_Models_Data_PendingNotification"

MerchantEmail
string
Email which will be notified by Saferpay if an action could not be completed synchronously and was reported with a ‘pending’ state (eg CAPTURE_PENDING). Up until now, this is only applicable for Paydirekt transactions.
Example: merchant@saferpay.com
NotifyUrl
recommended, string
Url which is called by Saferpay if an action could not be completed synchronously and was reported with a ‘pending’ state (eg CAPTURE_PENDING). Up until now, this is only applicable for Paydirekt transactions.
Example: https://merchanthost/pendingnotify

Container "Payment_Models_Data_RecurringOptions"

Initial
mandatory, boolean
If set to true, the authorization may later be referenced for recurring followup transactions.

Container "Payment_Models_Data_Redirect"

RedirectUrl
mandatory, string
Redirect-URL. Used to either redirect the payer or let him enter his means of payment.
Example: https://www.saferpay.com/VT2/api/...
PaymentMeansRequired
mandatory, boolean
True, if the given URL must be used as the target of a form containing card data entered by the card holder. If ‘false’, either a GET or POST redirect without additional data may be performed.

Container "Payment_Models_Data_Refund"

Amount
mandatory, container
Amount data
OrderId
recommended, string
Reference defined by the merchant.
Id[1..80]
Example: c52ad18472354511ab2c33b59e796901
Description
string
Description provided by merchant
Utf8[1..1000]
Example: Description

Container "Payment_Models_Data_RefundTransaction"

Type
mandatory, string
Type of transaction. One of 'REFUND'
Possible values: REFUND.
Example: REFUND
Status
mandatory, string
Current status of the transaction. One of 'AUTHORIZED', 'CAPTURED' or 'PENDING' (PENDING is only used for paydirekt at the moment)
Possible values: AUTHORIZED, CAPTURED, PENDING.
Example: AUTHORIZED
Id
mandatory, string
Unique Saferpay transaction id. Used to reference the transaction in any further step.
Example: K5OYS9Ad6Ex4rASU1IM1b3CEU8bb
Date
mandatory, date
Date / time of the authorization
Example: 2011-09-23T14:57:23.023+02.00
Amount
mandatory, container
Amount (currency, value, etc.) that has been authorized.
OrderId
string
OrderId given with request
Id[1..80]
Example: c52ad18472354511ab2c33b59e796901
AcquirerName
string
Name of the acquirer
Example: AcquirerName
AcquirerReference
string
Reference id of the acquirer (if available)
Example: AcquirerReference
SixTransactionReference
mandatory, string
Unique SIX transaction reference.
Example: 0:0:3:K5OYS9Ad6Ex4rASU1IM1b3CEU8bb
ApprovalCode
string
Approval id of the acquirer (if available)
Example: AcquirerReference
DirectDebit
container
Direct Debit information, if applicable
Example: AcquirerReference
Invoice
container
Invoice information, if applicable

Container "Payment_Models_Data_RegisterAlias"

IdGenerator
mandatory, string
Id generator to be used by Saferpay.
Possible values: MANUAL, RANDOM, RANDOM_UNIQUE.
Example: MANUAL
Id
string
Alias id to be used for registration if not generated by Saferpay. Mandatory if IdGenerator is 'MANUAL'. This value is case-insensitive.
Id[1..40]
Example: alias35nfd9mkzfw0x57iwx
Lifetime
integer
Number of days this card is to be stored within Saferpay. If not filled, the standard lifetime will be used.
Range: inclusive between 1 and 1600
Example: 1000

Container "Payment_Models_Data_RegistrationErrorInfo"

ErrorName
string
Name / id of the error.
Example: ErrorName
ErrorMessage
string
Description of the error.
Example: ErrorMessage

Container "Payment_Models_Data_RegistrationResult"

Success
mandatory, boolean
Result of registration
Alias
container
If Success is 'true', information about the alias
Error
container
If Success is 'false', information on why the registration failed

Container "Payment_Models_Data_ReturnUrls"

Success
mandatory, string
Return url for successful transaction
Example: https://merchanthost/success
Fail
mandatory, string
Return url for failed transaction
Example: https://merchanthost/fail
Abort
string
Return url for transaction aborted by the payer.
Example: https://merchanthost/abort

Container "Payment_Models_Data_Styling"

CssUrl
string
Custom styling resource (url) which will be referenced in web pages displayed by Saferpay to apply your custom styling.
This file must be hosted on a SSL/TLS secured web server (the url must start with https://).
Example: https://merchanthost/merchant.css
ContentSecurityEnabled
boolean
When enabled, then ContentSecurity/SAQ-A is requested, which leads to the CSS being loaded from the saferpay server.
Theme
string
This parameter let you customize the appearance of the displayed payment pages. Per default a lightweight responsive styling will be applied.
If you don't want any styling use 'NONE'.
Possible values: DEFAULT, SIX, NONE.
Example: DEFAULT

Container "Payment_Models_Data_ThreeDsInfo"

Authenticated
mandatory, boolean
Indicates, whether the payer has successfuly authenticated him/herself or not.
LiabilityShift
mandatory, boolean
Indicates whether liability shift to issuer is possible or not. Not present if PaymentMeans container was not present in Initialize request. True, if liability shift to issuer is possible, false if not (only SSL transaction).
Please note, that the authentification can be true, but the liabilityshift is false. The issuer has the right to deny the liabiliy shift during the authorization. You can continue to capture the payment here, but we recommend to cancel unsecure payments.
Xid
mandatory, string
BASE64 encoded value, given by the MPI. References the 3D Secure process.
Example: ARkvCgk5Y1t/BDFFXkUPGX9DUgs=
VerificationValue
string
Mandatory if Authenticated is true
Example: AAABBIIFmAAAAAAAAAAAAAAAAAA=

Container "Payment_Models_Data_TransactionReference"

TransactionId
string
Id of the referenced transaction.
AlphaNumeric[1..64]
Example: 723n4MAjMdhjSAhAKEUdA8jtl9jb
OrderId
string
Unambiguous OrderId of the referenced transaction.
Id[1..80]
Example: c52ad18472354511ab2c33b59e796901

Container "Payment_Models_Data_TwintInfo"

CertificateExpirationDate
mandatory, date
Twint token expiry date
Example: 2019-11-08T12:29:37.000+01:00

Container "Payment_Models_Data_Wallet"

Type
mandatory, string
The type of the wallet.
Possible values: MASTERPASS.
PaymentMethods
string[]
May be used to restrict the brands which should be allowed. If not sent, we use all brands configured on this terminal.
Possible values: AMEX, BANCONTACT, BONUS, DINERS, DIRECTDEBIT, EPRZELEWY, EPS, GIROPAY, IDEAL, INVOICE, JCB, MAESTRO, MASTERCARD, MYONE, PAYPAL, PAYDIREKT, POSTCARD, POSTFINANCE, SAFERPAYTEST, SOFORT, TWINT, UNIONPAY, VISA, VPAY.
Example: ["VISA", "MASTERCARD"]
RequestDeliveryAddress
boolean
Have the payer select a delivery address in his wallet. If not sent, no address is obtained from wallet.
EnableAmountAdjustment
boolean
This option is very specific for the MasterPass business scenario where the amount may be adjusted after the redirect to MasterPass and QueryPaymentMeans to allow for changes in shipping costs.
If this is set to true, DCC will not be done right away (but may be done later with an additional redirect).
DON’T USE THIS IF YOU’RE NOT SURE – IT’S PROBABLY NOT WHAT YOU WANT!

Changelog

Table of Contents

Version 1.10 (released 2018-11-13)

  • available on Sandbox: 2018-08-14
  • introduced version 1.10
  • added value 1.10 for SpecVersion
  • added method Transaction/MultipartCapture for capturing multiple parts of a transaction also supporting enhanced clearing for marketplaces
  • added method Transaction/MultipartFinalize to finalize a transaction that is still open for capturing additional parts
  • added container MarketPlace to Transaction/Capture request to support enhanced clearing for marketplaces
  • removed container Partial from Transaction/Capture request - see method Transaction/MultipartCapture for details
  • replaced TransactionId and OrderId with CaptureId in Transaction/Capture response to uniquely identify captures
  • replaced container TransactionReference with CaptureReference in Transaction/Refund and Transaction/AssertCapture request to uniquely identify captures
  • added value TWINT for field Type in Alias/Insert requests (only available in the Sandbox environment until further notice)
  • added subcontainer Twint to container PaymentMeans

Version 1.9 (released 2018-05-15)

  • available on Sandbox: 2018-04-26
  • introduced version 1.9
  • added value 1.9 for SpecVersion
  • replaced container ThreeDs from previous versions with Liability in PaymentPage/Assert and Transaction/Initialize responses

Version 1.8 (released 2017-11-14)

Version 1.7 (released 2017-08-22)

Version 1.6 (released 2017-04-04)

Version 1.5 (released 2017-02-07)

  • introduced version 1.5
  • added value 1.5 for SpecVersion
  • added method Transaction/AssertCapture for checking the status of a pending capture (currently needed for paydirekt)
  • added method Transaction/AssertRefund for checking the status of a pending refund (currently needed for paydirekt)
  • added container PendingNotification for Transaction/Capture requests for notification settings on pending captures (currently needed for paydirekt)
  • added container PendingNotification for Transaction/Refund requests for notification settings on pending captures (currently needed for paydirekt)
  • added Status in Transaction/Capture responses to indicate the status of a capture
  • changed Date in Transaction/Capture responses to optional, e.g. for pending captures
  • changed PaymentPage/Initialize request to allow BillingAddressForm.Display and DeliveryAddressForm.Display both set to true at the same time
  • added ContentSecurityEnabled to Styling container to control Content Security Policy
  • corrected type documentation for CountrySubdivisionCode to "AlphaNumeric" in the address containers

Version 1.4 (released 2016-10-15)

Back to Top