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

Test Environment

For the integration phase, you should visit our test environment! There you can register your personal test account, which you then can use for testing, to try out different functions and for general evaluation.

You can find a list of test-cards and other payment means for testing over here!

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, object
Contains general information about the response.
Risk
object
Contains additional risk related information for the transaction that is blocked by risk.
Behavior
mandatory, string
What can be done to resolve the error?
Possible values: DO_NOT_RETRY, 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
array of strings
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
PayerMessage
string
A text message provided by the card issuer detailing the reason for a declined authorization. It is safe to display it to the payer.
OrderId
string
OrderId of the failed transaction. This is only returned in the PaymentPage Assert Response and the Transaction Authorize Response.

Example:

{
  "ResponseHeader": {
    "SpecVersion": "[current Spec-Version]",
    "RequestId": "[your request id]"
  },
  "Behavior": "DO_NOT_RETRY",
  "ErrorName": "VALIDATION_FAILED",
  "ErrorMessage": "Request validation failed",
  "ErrorDetail": [
    "PaymentMeans.BankAccount.IBAN: The field IBAN is invalid."
  ],
  "TransactionId": "723n4MAjMdhjSAhAKEUdA8jtl9jb",
  "OrderId": "c52ad18472354511ab2c33b59e796901"
}

List of behaviors:

DO_NOT_RETRY Do not try again to avoid potential fees related to authorization reattempts that do not respect card schemes instructions. The card issuer will never approve this authorization request.
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 a certain state/error condition has been changed. For example, insufficient funds (up to 10 attempts in 30 days)
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
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
PAYER_AUTHENTICATION_REQUIRED Payer authentication required to proceed (soft decline).
PAYMENTMEANS_INVALID Invalid means of payment (e.g. invalid card)
PAYMENTMEANS_NOT_SUPPORTED Unsupported means of payment (e.g. non SEPA IBAN)
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.
UNEXPECTED_ERROR_BY_ACQUIRER The acquirer returned an unexpected error code.
Solution: Try again
UPDATE_CARD_INFORMATION Card details need to be updated in order to have the possibility of a successful payment
Solution: Update card data
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. The ReturnUrl is 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

POST
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, object
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, object
Information about the payment (amount, currency, ...)
PaymentMethods
array of strings
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: ACCOUNTTOACCOUNT, ALIPAY, AMEX, BANCONTACT, BONUS, DINERS, CARD, DIRECTDEBIT, EPRZELEWY, EPS, GIROPAY, IDEAL, INVOICE, JCB, KLARNA, MAESTRO, MASTERCARD, MYONE, PAYCONIQ, PAYDIREKT, PAYPAL, POSTCARD, POSTFINANCE, POSTFINANCEPAY, SOFORT, TWINT, UNIONPAY, VISA, WLCRYPTOPAYMENTS.
Example: ["VISA", "MASTERCARD"]
PaymentMethodsOptions
object
Optional. May be used to set specific options for some payment methods.
Authentication
object
Strong Customer Authentication (exemptions, ...)
Wallets
array of strings
Used to control if wallets should be enabled on the payment selection page.
Possible values: APPLEPAY, GOOGLEPAY.
Possible values: APPLEPAY, GOOGLEPAY.
Example: ["APPLEPAY"]
Payer
object
Information about the payer
RegisterAlias
object
If the given means of payment should be stored in Saferpay Secure Card Data storage (if applicable)
ReturnUrl
mandatory, object
URL which is used to redirect the payer back to the shop

This Url is 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
object
Notification options
BillingAddressForm
object
Use this container if you need to get a billing address from the payer during the payment process.
Saferpay can show an address form and depending on the means of payment, it is also possible to get the address from the means of payment (e.g. PayPal or any kind of wallet) if available.
Check the options in the container for different behaviors.
In case you also provide payer addresses, these are used as default values to prefill the address form (if displayed) and are overwritten by the final address entered by the payer or provided by the payment method.
DeliveryAddressForm
object
Use this container if you need to get a delivery address from the payer during the payment process.
Saferpay can show an address form and depending on the means of payment, it is also possible to get the address from the means of payment (e.g. PayPal or any kind of wallet) if available.
Check the options in the container for different behaviors.
In case you also provide payer addresses, these are used as default values to prefill the address form (if displayed) and are overwritten by the final address entered by the payer or provided by the payment method.
CardForm
object
Options for card data entry form (if applicable)
Condition
string
Optional Condition for Authorization (only 3DSv2), to control, whether or not, transactions without LiabilityShift should be accepted. Important Note: This only filters out transactions, where the condition is conclusive before the authorization itself. It is possible, that LiabilityShift is rejected after the authorization. Please always check the Liability container, within the authorization-response, to be 100% sure, if LiabilityShift applies, or not!
Default: NONE (empty)
Possible values: NONE, THREE_DS_AUTHENTICATION_SUCCESSFUL_OR_ATTEMPTED.
Order
object
Optional order information. Only used for payment method Klarna (mandatory) and for Fraud Intelligence (optional).
RiskFactors
object
Optional risk factors

Example:

{
  "RequestHeader": {
    "SpecVersion": "[current Spec-Version]",
    "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"
  },
  "ReturnUrl": {
    "Url": "[your shop payment url]"
  }
}

Response

Arguments
ResponseHeader
mandatory, object
Contains general information about the response.
Token
mandatory, string
Token for later referencing
Example: 234uhfh78234hlasdfh8234e1234
Expiration
mandatory, date
Expiration date / time of the RedirectUrl in ISO 8601 format in UTC. After this time, the RedirectUrl can't be called anymore.
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/234uhfh78234hlasdfh8234e1234

Example:

{
  "ResponseHeader": {
    "SpecVersion": "[current Spec-Version]",
    "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

POST
Call this function to safely check the status of the transaction from your server.

Important:

  • 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.
  • This function can be called up to 24 hours after the transaction was initialized. For pending transaction the token expiration is increased to 120 hours.
  • 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, object
General information about the request.
Token
mandatory, string
Token returned by initial call.
Id[1..50]
Example: 234uhfh78234hlasdfh8234e

Example:

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

Response

Arguments
ResponseHeader
mandatory, object
Contains general information about the response.
Transaction
mandatory, object
Information about the transaction
PaymentMeans
mandatory, object
Information about the means of payment
Payer
object
Information about the payer / card holder
RegistrationResult
object
Information about the SCD registration outcome
Liability
object
LiabilityShift information, replaces ThreeDs Info from api version 1.8
Dcc
object
Dcc information, if applicable
MastercardIssuerInstallments
object
Mastercard card issuer installment payment options, if applicable
FraudPrevention
object
Contains details of a performed fraud prevention check

Example:

{
  "ResponseHeader": {
    "SpecVersion": "[current Spec-Version]",
    "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,
      "Xid": "ARkvCgk5Y1t/BDFFXkUPGX9DUgs="
    }
  }
}

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 depth 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 ReturnUrl. The ReturnUrl is 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 Available depending on license

POST
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, object
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, object
Information about the payment (amount, currency, ...)
PaymentMeans
object
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.
Authentication
object
Strong Customer Authentication (exemptions, ...)
Payer
object
Information on the payer (IP-address)
ReturnUrl
mandatory, object
URL which is used to redirect the payer back to the shop if the transaction requires some kind of browser redirection (3d-secure, dcc)

This Url is 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
object
Styling options
PaymentMethods
array of strings
Used to restrict the means of payment which are available to the payer
Possible values: AMEX, BANCONTACT, BONUS, DINERS, DIRECTDEBIT, JCB, MAESTRO, MASTERCARD, MYONE, VISA. Additional values may be accepted but are ignored.
Example: ["VISA", "MASTERCARD"]
Order
object
Optional order information. Only used for payment method Klarna (mandatory) and for Fraud Intelligence (optional).
RiskFactors
object
Optional risk factors
CardForm
object
Options for card data entry form (if applicable)
RedirectNotifyUrls
object
If a redirect of the payer is required, these URLs will be used by Saferpay to notify you when the payer has completed the required steps and the transaction is ready to be authorized or when the operation has failed or has been aborted by the payer.
If no redirect of the payer is required, then these URLs will not be called (see RedirectRequired attribute of the Transaction Initialize response).

Supported schemes are http and https. You also have to make sure to support the GET-method.
The whole url including query string parameters must not exceed 2000 characters.
Note: you should not add sensitive data to the query string, as its contents are logged by our web servers.
Notification
object
Notification options

Example:

{
  "RequestHeader": {
    "SpecVersion": "[current Spec-Version]",
    "CustomerId": "[your customer id]",
    "RequestId": "[unique request id]",
    "RetryIndicator": 0
  },
  "TerminalId": "[your terminal id]",
  "Payment": {
    "Amount": {
      "Value": "100",
      "CurrencyCode": "CHF"
    }
  },
  "Payer": {
    "LanguageCode": "en"
  },
  "ReturnUrl": {
    "Url": "[your shop payment url]"
  },
  "Styling": {
    "CssUrl": "[your shop css url]"
  }
}

Response

Arguments
ResponseHeader
mandatory, object
Contains general information 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 is exceeded, the token will not be accepted for any further actions except Asserts.
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
object
Mandatory if RedirectRequired is true. Contains the URL for the redirect to use for example the Saferpay hosted register form.

Example:

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

Transaction Authorize Available depending on license

POST
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, object
General information about the request.
Token
mandatory, string
Token returned by Initialize
Id[1..50]
Example: 234uhfh78234hlasdfh8234e
Condition
string
THREE_DS_AUTHENTICATION_SUCCESSFUL_OR_ATTEMPTED: 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: NONE, THREE_DS_AUTHENTICATION_SUCCESSFUL_OR_ATTEMPTED.
Example: NONE
VerificationCode
string
Card verification code if available
Numeric[3..4]
Example: 123
RegisterAlias
object
Controls whether the given means of payment should be stored inside the Saferpay Secure Card Data storage.

Example:

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

Response

Arguments
ResponseHeader
mandatory, object
Contains general information about the response.
Transaction
mandatory, object
Information about the transaction
PaymentMeans
mandatory, object
Information about the means of payment
Payer
object
Information about the payer / card holder
RegistrationResult
object
Information about the Secure Card Data registration outcome.
MastercardIssuerInstallments
object
Mastercard card issuer installment payment options, if applicable
FraudPrevention
object
Contains details of a performed fraud prevention check
Liability
object
LiabilityShift information, replaces ThreeDs Info from api version 1.8
Dcc
object
Dcc information, if applicable

Example:

{
  "ResponseHeader": {
    "SpecVersion": "[current Spec-Version]",
    "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,
      "Xid": "ARkvCgk5Y1t/BDFFXkUPGX9DUgs="
    }
  }
}

Transaction AuthorizeDirect Available depending on license

POST
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!

Important: This function does not perform 3D Secure! Only the PaymentPage or Transaction Initialize do support 3D Secure!

Request URL:

POST: /Payment/v1/Transaction/AuthorizeDirect

Request

Arguments
RequestHeader
mandatory, object
General information about the request.
TerminalId
mandatory, string
Saferpay Terminal-Id
Numeric[8..8]
Example: 12341234
Payment
mandatory, object
Information about the payment (amount, currency, ...)
PaymentMeans
mandatory, object
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.
Authentication
object
Strong Customer Authentication exemption for this transaction.
Some exemptions are only applicable to payer-initiated transactions and will be ignored otherwise. If you are performing a payer-initiated transaction, make sure you set the 'Initiator' attribute properly (see below).
RegisterAlias
object
Controls whether the given means of payment should be stored inside the Saferpay Secure Card Data storage.
Payer
object
Information on the payer (IP-address)
Order
object
Optional order information. Only used for payment method Klarna (mandatory) and for Fraud Intelligence (optional).
RiskFactors
object
Optional risk factors
Initiator
string
Specify if the transaction was initiated by the merchant (default behavior if not specified) or by the payer.
This is relevant for most credit and debit cards managed by Mastercard, Visa and American Express card schemes (in card scheme jargon: MERCHANT means MIT, PAYER means CIT).
For these schemes, transactions initiated by the payer usually require authentication of the card holder, which is not possible if you use Transaction/AuthorizeDirect (use Transaction/Initialize or PaymentPage/Initialize if you're not sure).
Saferpay will flag the transaction accordingly (also taking the optional Exemption in the Authentication container into account) on the protocols which support this and card issuers might approve or decline transactions depending on this flagging.
Possible values: MERCHANT, PAYER.
Example: MERCHANT

Example:

{
  "RequestHeader": {
    "SpecVersion": "[current Spec-Version]",
    "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"
    }
  },
  "Authentication": {
    "Exemption": "RECURRING"
  }
}

Response

Arguments
ResponseHeader
mandatory, object
Contains general information about the response.
Transaction
mandatory, object
Information about the transaction
PaymentMeans
mandatory, object
Information about the means of payment
Payer
object
Information about the payer / card holder
RegistrationResult
object
Information about the Secure Card Data registration outcome.
MastercardIssuerInstallments
object
Mastercard card issuer installment payment options, if applicable
FraudPrevention
object
Contains details of a performed fraud prevention check
Liability
object
LiabilityShift information, replaces ThreeDs Info from api version 1.26

Example:

{
  "ResponseHeader": {
    "SpecVersion": "[current Spec-Version]",
    "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": "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 Available depending on license

POST
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, object
General information about the request.
TerminalId
mandatory, string
Saferpay Terminal-Id
Numeric[8..8]
Example: 12341234
Payment
mandatory, object
Information about the payment (amount, currency, ...)
TransactionReference
mandatory, object
Reference to previous transaction.

Exactly one element must be set.
Authentication
object
Strong Customer Authentication (exemptions, ...)
SuppressDcc
boolean
Used to suppress direct currency conversion
Notification
object
Notification options

Example:

{
  "RequestHeader": {
    "SpecVersion": "[current Spec-Version]",
    "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"
  },
  "Authentication": {
    "Exemption": "RECURRING"
  },
  "TransactionReference": {
    "TransactionId": "723n4MAjMdhjSAhAKEUdA8jtl9jb"
  }
}

Response

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

Example:

{
  "ResponseHeader": {
    "SpecVersion": "[current Spec-Version]",
    "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": "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 Available depending on license

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

Request URL:

POST: /Payment/v1/Transaction/Capture

Request

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

Exactly one element must be set.
Amount
object
Currency must match the original transaction currency (request will be declined if currency does not match)
Billpay
object
Optional Billpay specific options.
PendingNotification
object
Optional pending notification capture options for Paydirekt transactions.
Marketplace
object
Optional Marketplace capture parameters.
MastercardIssuerInstallments
object
Selected Mastercard card issuer installment payment option, if applicable

Example:

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

Response

Arguments
ResponseHeader
mandatory, object
Contains general information 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
object
Optional infos for invoice based payments.

Example:

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

Transaction MultipartCapture Available depending on license

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

Important:

  • MultipartCapture is available for PayPal, Klarna and card payments Visa, Mastercard, Maestro, Diners/Discover, JCB and American Express which are acquired by Worldline.
  • No MultipartCapture request should be sent before receiving the response of a preceding 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, object
General information about the request.
TransactionReference
mandatory, object
Reference to authorization.

Exactly one element must be set.
Amount
mandatory, object
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
object
Optional Marketplace capture parameters.

Example:

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

Response

Arguments
ResponseHeader
mandatory, object
Contains general information 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": "[current Spec-Version]",
    "RequestId": "[unique request identifier]"
  },
  "CaptureId": "723n4MAjMdhjSAhAKEUdA8jtl9jb_c",
  "Status": "CAPTURED",
  "Date": "2018-08-08T13:45:22.258+02:00"
}

Transaction AssertCapture Available depending on license

POST

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

Request URL:

POST: /Payment/v1/Transaction/AssertCapture

Request

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

Example:

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

Response

Arguments
ResponseHeader
mandatory, object
Contains general information 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": "[current Spec-Version]",
    "RequestId": "[your request id]"
  },
  "TransactionId": "723n4MAjMdhjSAhAKEUdA8jtl9jb",
  "Status": "CAPTURED",
  "Date": "2015-01-30T12:45:22.258+01:00"
}

Transaction MultipartFinalize Available depending on license

POST
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, object
General information about the request.
TransactionReference
mandatory, object
Reference to authorization.

Exactly one element must be set.

Example:

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

Response

Arguments
ResponseHeader
mandatory, object
Contains general information about the response.

Example:

{
  "ResponseHeader": {
    "SpecVersion": "[current Spec-Version]",
    "RequestId": "[unique request identifier]"
  }
}

Transaction Refund Available depending on license

POST
This method may be called to refund a previous transaction.

Request URL:

POST: /Payment/v1/Transaction/Refund

Request

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

Example:

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

Response

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

Example:

{
  "ResponseHeader": {
    "SpecVersion": "[current Spec-Version]",
    "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 Available depending on license

POST
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 or WL Crypto Payments transactions at the moment.

Request URL:

POST: /Payment/v1/Transaction/AssertRefund

Request

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

Exactly one element must be set.

Example:

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

Response

Arguments
ResponseHeader
mandatory, object
Contains general information 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": "[current Spec-Version]",
    "RequestId": "[your request id]"
  },
  "TransactionId": "723n4MAjMdhjSAhAKEUdA8jtl9jb",
  "Status": "CAPTURED",
  "Date": "2015-01-30T12:45:22.258+01:00"
}

Transaction RefundDirect Available depending on license

POST
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, object
General information about the request.
TerminalId
mandatory, string
Saferpay Terminal-Id
Numeric[8..8]
Example: 12341234
Refund
mandatory, object
Information about the refund (amount, currency, ...)
PaymentMeans
mandatory, object
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.
OriginalCreditTransfer
object
Information about the Original Credit Transfer like the Address of the Recipient.

Example:

{
  "RequestHeader": {
    "SpecVersion": "[current Spec-Version]",
    "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, object
Contains general information about the response.
Transaction
mandatory, object
Information about the transaction
PaymentMeans
mandatory, object
Information about the means of payment

Example:

{
  "ResponseHeader": {
    "SpecVersion": "[current Spec-Version]",
    "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 Available depending on license

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

Request URL:

POST: /Payment/v1/Transaction/Cancel

Request

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

Exactly one element must be set.

Example:

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

Response

Arguments
ResponseHeader
mandatory, object
Contains general information 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": "[current Spec-Version]",
    "RequestId": "[your request id]"
  },
  "TransactionId": "723n4MAjMdhjSAhAKEUdA8jtl9jb",
  "OrderId": "c52ad18472354511ab2c33b59e796901",
  "Date": "2015-01-30T12:45:22.258+01:00"
}

Transaction RedirectPayment Available depending on license

POST

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, object
General information about the request.
TerminalId
mandatory, string
Saferpay terminal to use for this authorization
Numeric[8..8]
Example: 12341234
Payment
mandatory, object
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
object
Information on the payer (IP-address)
ReturnUrl
mandatory, object
URL which is used to redirect the payer back to the shop if the transaction requires some kind of browser redirection (3d-secure, dcc)

This Url is 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
object
Custom styling resource
Notification
object
Notification options

Example:

{
  "RequestHeader": {
    "SpecVersion": "[current Spec-Version]",
    "CustomerId": "[your customer id]",
    "RequestId": "[your request id]",
    "RetryIndicator": 0
  },
  "TerminalId": "[your terminal id]",
  "Payment": {
    "Amount": {
      "Value": "100",
      "CurrencyCode": "CHF"
    }
  },
  "ServiceProvider": "PAYPAL",
  "ReturnUrl": {
    "Url": "[your shop payment url]"
  }
}

Response

Arguments
ResponseHeader
mandatory, object
Contains general information 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": "[current Spec-Version]",
    "RequestId": "[your request id]"
  },
  "Token": "234uhfh78234hlasdfh8234e",
  "Expiration": "2015-01-30T12:45:22.258+01:00",
  "RedirectUrl": "https://www.saferpay.com/vt2/Api/..."
}

Transaction AssertRedirectPayment Available depending on license

POST

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, object
General information about the request.
Token
mandatory, string
Token returned by initial call.
Id[1..50]
Example: 234uhfh78234hlasdfh8234e

Example:

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

Response

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

Example:

{
  "ResponseHeader": {
    "SpecVersion": "[current Spec-Version]",
    "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": 2022,
      "ExpMonth": 9,
      "HolderName": "Max Mustermann",
      "CountryCode": "CH"
    }
  }
}

Transaction Inquire Available depending on license

POST
This method can be used to get the details of a transaction that has been authorized successfully.

Fair use:This method is not intended for polling. You have to restrict the usage of this method in order to provide a fair data access to all our customers. We may contact you if we notice the excessive usage of this function and in some exceptional cases we preserve the right to limit the access to it.

Request URL:

POST: /Payment/v1/Transaction/Inquire

Request

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

Exactly one element must be set.

Example:

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

Response

Arguments
ResponseHeader
mandatory, object
Contains general information about the response.
Transaction
mandatory, object
Information about the transaction
PaymentMeans
mandatory, object
Information about the means of payment
Payer
object
Information about the payer / card holder
Liability
object
LiabilityShift information, replaces ThreeDs Info from api version 1.8
Dcc
object
Dcc information, if applicable
FraudPrevention
object
Contains details of a performed fraud prevention check

Example:

{
  "ResponseHeader": {
    "SpecVersion": "1.11",
    "RequestId": "[your request id]"
  },
  "Transaction": {
    "Type": "PAYMENT",
    "Status": "CAPTURED",
    "Id": "UlKpE6A2UxlttAOQtnYIbCj1CpIA",
    "Date": "2019-04-05T10:49:55.76+02:00",
    "Amount": {
      "Value": "1200",
      "CurrencyCode": "CHF"
    },
    "AcquirerName": "Saferpay Test Card",
    "AcquirerReference": "32436794662",
    "SixTransactionReference": "0:0:3:723n4MAjMdhjSAhAKEUdA8jtl9jb",
    "ApprovalCode": "012345"
  },
  "PaymentMeans": {
    "Brand": {
      "PaymentMethod": "VISA",
      "Name": "VISA"
    },
    "DisplayText": "xxxx xxxx xxxx 0004",
    "Card": {
      "MaskedNumber": "901050xxxxxx0004",
      "ExpYear": 2022,
      "ExpMonth": 6,
      "HolderName": "Max Mustermann",
      "CountryCode": "CH"
    }
  },
  "Liability": {
    "LiabilityShift": true,
    "LiableEntity": "THREEDS",
    "ThreeDs": {
      "Authenticated": true,
      "Xid": "ARkvCgk5Y1t/BDFFXkUPGX9DUgs="
    }
  }
}

Transaction AlternativePayment Available depending on license

POST
This method can be used to authorize the payments that do not have a payment-page or for the payments that before authorization some additional steps such as authentication should be done.

Request URL:

POST: /Payment/v1/Transaction/AlternativePayment

Request

Arguments
RequestHeader
mandatory, object
General information about the request.
TerminalId
mandatory, string
Saferpay terminal to use for this authorization
Numeric[8..8]
Example: 12341234
Payment
mandatory, object
Information about the payment (amount, currency, ...)
PaymentMethod
mandatory, string
Service provider to be used for this payment
Possible values: BANCONTACT.
Example: BANCONTACT
PaymentMethodOptions
object
Optional. May be used to set specific options for the payment method.
Payer
object
Information on the payer (IP-address)
Notification
mandatory, object
Notification options
Order
object
Optional order information. Only used for payment method Klarna (mandatory) and for Fraud Intelligence (optional).
RiskFactors
object
Optional risk factors

Example:

{
  "RequestHeader": {
    "SpecVersion": "1.12",
    "CustomerId": "[your customer id]",
    "RequestId": "[your request id]",
    "RetryIndicator": 0
  },
  "TerminalId": "[your terminal id]",
  "Payment": {
    "Amount": {
      "Value": "100",
      "CurrencyCode": "CHF"
    }
  },
  "PaymentMethod": "BANCONTACT"
}

Response

Arguments
ResponseHeader
mandatory, object
Contains general information 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
ProcessingData
object
data required by the merchant system to process the payment (e.g. QR-code data, intent URL, ...)

Payment method specific data required to process an alternative payment.
Only one container (matching the PaymentMethod of the AlternativePaymentRequest message) will be present

Example:

{
  "ResponseHeader": {
    "SpecVersion": "[current Spec-Version]",
    "RequestId": "[your request id]"
  },
  "Token": "234uhfh78234hlasdfh8234e",
  "Expiration": "2015-01-30T12:45:22.258+01:00",
  "ProcessingData": {
    "Bancontact": {
      "QrCodeData": "someQRcodeData",
      "IntentUrl": "https://www.saferpay.com/vt2/Api/..."
    }
  }
}

Transaction QueryAlternativePayment Available depending on license

POST
Call this method to get information about a previously initialized alternative payment transaction

Request URL:

POST: /Payment/v1/Transaction/QueryAlternativePayment

Request

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

Example:

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

Response

Arguments
ResponseHeader
mandatory, object
Contains general information about the response.
Transaction
mandatory, object
Information about the transaction
PaymentMeans
mandatory, object
Information about the means of payment
Payer
object
Information about the payer / card holder
Liability
object
LiabilityShift information, replaces ThreeDs Info from api version 1.8
FraudPrevention
object
Contains details of a performed fraud prevention check

Example:

{
  "ResponseHeader": {
    "SpecVersion": "1.12",
    "RequestId": "[your request id]"
  },
  "Transaction": {
    "Type": "PAYMENT",
    "Status": "CAPTURED",
    "Id": "ChAChMA5hx89vAAzEh52AUYvxWCb",
    "CaptureId": "ChAChMA5hx89vAAzEh52AUYvxWCb",
    "Date": "2019-06-19T15:04:48.733+02:00",
    "Amount": {
      "Value": "100",
      "CurrencyCode": "EUR"
    },
    "AcquirerName": "Bancontact Saferpay Test",
    "AcquirerReference": "32332251189",
    "SixTransactionReference": "0:0:3:723n4MAjMdhjSAhAKEUdA8jtl9jb",
    "ApprovalCode": "945011"
  },
  "PaymentMeans": {
    "Brand": {
      "PaymentMethod": "BANCONTACT",
      "Name": "Bancontact"
    },
    "DisplayText": "xxxx xxxx xxxx x000 5",
    "Card": {
      "MaskedNumber": "xxxxxxxxxxxxx0005",
      "ExpYear": 2020,
      "ExpMonth": 6,
      "CountryCode": "BE"
    }
  },
  "Liability": {
    "LiabilityShift": true,
    "LiableEntity": "THREEDS",
    "ThreeDs": {
      "Authenticated": true,
      "Xid": "ARkvCgk5Y1t/BDFFXkUPGX9DUgs="
    }
  }
}

Secure Card Data

Alias Insert

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

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/Alias/Insert

Request

Arguments
RequestHeader
mandatory, object
General information about the request.
RegisterAlias
mandatory, object
Registration parameters
Type
mandatory, string
Type of payment means to register
Possible values: CARD, BANK_ACCOUNT, POSTFINANCE, TWINT.
Example: CARD
ReturnUrl
mandatory, object
URL which is used to redirect the payer back to the shop.

This Url is 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
object
Custom styling resource for the Hosted Register form.
LanguageCode
string
Language used for displaying forms.
The supported language codes are listed below. This list may be extended in the future as more languages become available. If the submitted language code has a valid format, but is not supported, then the default language is used.

Code-List:
bg - Bulgarian
cs - Czech
da - Danish
de - German
de-ch - Swiss German
el - Greek
en - English
es - Spanish
et - Estonian
fi - Finnish
fr - French
hr - Croatian
hu - Hungarian
is - Icelandic
it - Italian
ja - Japanese
lt - Lithuanian
lv - Latvian
nl - Dutch
nn - Norwegian
pl - Polish
pt - Portuguese
ro - Romanian
ru - Russian
sk - Slovak
sl - Slovenian
sv - Swedish
tr - Turkish
uk - Ukrainian
zh - Chinese
Example: de
Check
object
Parameters for checking the means of payment before registering.
IMPORTANT NOTE: The Check function is only available for certain brands / acquirers! For more information, see Saferpay Integration Guide for Secure Card Data

PaymentMethods
array of strings
Used to restrict the means of payment which are available to the payer
Possible values: AMEX, BANCONTACT, BONUS, DINERS, DIRECTDEBIT, JCB, MAESTRO, MASTERCARD, MYONE, VISA. Additional values may be accepted but are ignored.
Example: ["VISA", "MASTERCARD"]
CardForm
object
Options for card data entry form (if applicable)
PaymentMeans
object
Means of payment to register
Notification
object
Url to which Saferpay will send the asynchronous confirmation for the process completion. Supported schemes are http and https. You also have to make sure to support the GET-method.
Example: https://merchanthost/notify/123

Example:

{
  "RequestHeader": {
    "SpecVersion": "[current Spec-Version]",
    "CustomerId": "[your customer id]",
    "RequestId": "[your request id]",
    "RetryIndicator": 0
  },
  "RegisterAlias": {
    "IdGenerator": "RANDOM"
  },
  "Type": "CARD",
  "ReturnUrl": {
    "Url": "[your shop alias registration url]"
  }
}

Response

Arguments
ResponseHeader
mandatory, object
Contains general information 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 is exceeded, the token will not be accepted for any further actions except Asserts.
Example: 2015-01-30T13:45:22.258+02:00
RedirectRequired
boolean
True if a redirect must be performed to continue, false otherwise
Redirect
object
Mandatory if RedirectRequired is true. Contains the URL for the redirect to use for example the Saferpay hosted register form.

Example:

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

Alias AssertInsert

POST
This method may be used to inquire the Alias Id and further information after a successful Alias Insert call. This function can be called up to 24 hours after the transaction was initialized.

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, object
General information about the request.
Token
mandatory, string
Token returned by initial call.
Id[1..50]
Example: 234uhfh78234hlasdfh8234e

Example:

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

Response

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

Example:

{
  "ResponseHeader": {
    "SpecVersion": "[current Spec-Version]",
    "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

POST
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, object
General information about the request.
RegisterAlias
mandatory, object
Registration parameters
PaymentMeans
mandatory, object
Means of payment to register
Check
object
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!
IssuerReference
object
Contains that is received from the issuer in the response of a successful payment by other payment providers. This data will be used for authorizations based on this alias.

Example:

{
  "RequestHeader": {
    "SpecVersion": "[current Spec-Version]",
    "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, object
Contains general information about the response.
Alias
mandatory, object
Information about the registered alias.
PaymentMeans
mandatory, object
Information about the registered means of payment
CheckResult
object
Result of the Check

Example:

{
  "ResponseHeader": {
    "SpecVersion": "[current Spec-Version]",
    "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 Update

POST
This method may be used to update an alias' lifetime and / or its credit card expiry date

Request URL:

POST: /Payment/v1/Alias/Update

Request

Arguments
RequestHeader
mandatory, object
General information about the request.
UpdateAlias
mandatory, object
Update parameters
UpdatePaymentMeans
mandatory, object
Means of payment to update

Example:

{
  "RequestHeader": {
    "SpecVersion": "[current Spec-Version]",
    "CustomerId": "[your customer id]",
    "RequestId": "[your request id]",
    "RetryIndicator": 0
  },
  "AliasUpdate": {
    "Id": "[your alias id]",
    "Lifetime": "[your lifetime]"
  },
  "UpdatePaymentMeans": {
    "Card": {
      "ExpMonth": "[your expiry month]",
      "ExpYear": "[your expiry year]"
    }
  }
}

Response

Arguments
ResponseHeader
mandatory, object
Contains general information about the response.
Alias
mandatory, object
Information about the registered alias.
PaymentMeans
mandatory, object
Information about the registered means of payment

Example:

{
  "ResponseHeader": {
    "SpecVersion": "[current Spec-Version]",
    "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

POST
This method may be used to delete previously inserted aliases.

Request URL:

POST: /Payment/v1/Alias/Delete

Request

Arguments
RequestHeader
mandatory, object
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": "[current Spec-Version]",
    "CustomerId": "[your customer id]",
    "RequestId": "[unique request id]",
    "RetryIndicator": 0
  },
  "AliasId": "alias35nfd9mkzfw0x57iwx"
}

Response

Arguments
ResponseHeader
mandatory, object
Contains general information about the response.

Example:

{
  "ResponseHeader": {
    "SpecVersion": "[current Spec-Version]",
    "RequestId": "[your request id]"
  }
}

Batch

Batch Close

POST
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, object
General information about the request.
TerminalId
mandatory, string
Saferpay Terminal-Id
Numeric[8..8]
Example: 12341234

Example:

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

Response

Arguments
ResponseHeader
mandatory, object
Contains general information about the response.

Example:

{
  "ResponseHeader": {
    "SpecVersion": "[current Spec-Version]",
    "RequestId": "[your request id]"
  }
}

OmniChannel

OmniChannel InsertAlias

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

Request URL:

POST: /Payment/v1/OmniChannel/InsertAlias

Request

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

Example:

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

Response

Arguments
ResponseHeader
mandatory, object
Contains general information about the response.
Alias
mandatory, object
Information about the registered alias.
PaymentMeans
mandatory, object
Information about the registered means of payment

Example:

{
  "ResponseHeader": {
    "SpecVersion": "[current Spec-Version]",
    "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

POST
This function may be used to acquire a POS authorized or captured transaction by providing a SixTransactionReference. This transaction can then be authorized, canceled, captured or refunded.

Request URL:

POST: /Payment/v1/OmniChannel/AcquireTransaction

Request

This request allows to acquire an OmniChannel transaction.

Arguments
RequestHeader
mandatory, object
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": "[current Spec-Version]",
    "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, object
Contains general information about the response.
Transaction
mandatory, object
Information about the transaction
PaymentMeans
mandatory, object
Information about the means of payment

Example:

{
  "ResponseHeader": {
    "SpecVersion": "[current Spec-Version]",
    "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"
    }
  }
}

Management API

This interface offers REST based access to various management features. This enables customers to integrate those features into their systems on a technical level.

Important Note: The Saferpay Management API does not use the JSON API header. Instead, some additional HTTP header fields are required.

Additional HTTP Headers

Instead of the RequestHeader container used in the JSON API, the Management API uses additional HTTP Headers to store and transfer general information about the request. All other requirements regarding the HTTP Headers (e.g. for content encoding and authentication) still apply.

Header field Possible values Description
Saferpay-ApiVersion 1.14 Version number of the interface specification.
Saferpay-RequestId Id[1..50] Id generated by merchant system, for debugging purposes. Should be unique for each new request. If a request is retried due to an error, use the same request id.

HTTP Headers example:

Saferpay-ApiVersion: 1.14

Saferpay-RequestId: 33e8af17-35c1-4165-a343-c1c86a320f3b

Licensing CustomerLicense

GET
This method is used to retrieve the current license configuration for a customer

Request URL:

GET: /rest/customers/[customerId]/license

Request

No body needed

Example:

No example available

Response

Arguments
Package
mandatory, object
Information about the configured package
Features
mandatory, array of objects
All features contained in the configured package or assigned additionally

Example:

{
  "Package": {
    "Id": "SAFERPAY_FLEX",
    "DisplayName": "Saferpay Flex"
  },
  "Features": [
    {
      "Id": "MANAGEMENT_API",
      "DisplayName": "Management API"
    },
    {
      "Id": "PAYMENT_API",
      "DisplayName": "Payment API"
    }
  ]
}

Licensing CustomerLicenseConfiguration

GET
DEPRECATED: since Version 1.35. Please use instead: /rest/customers/{customerId}/license

This method is used to retrieve the current license configuration for a customer

Request URL:

GET: /rest/customers/[customerId]/license-configuration

Request

No body needed

Example:

No example available

Response

Arguments
Package
mandatory, object
Information about the configured package
Features
mandatory, array of objects
All features contained in the configured package or assigned additionally

Example:

{
  "Package": {
    "Id": "SAFERPAY_FLEX",
    "DisplayName": "Saferpay Flex"
  },
  "Features": [
    {
      "Id": "MANAGEMENT_API",
      "DisplayName": "Management API"
    },
    {
      "Id": "PAYMENT_API",
      "DisplayName": "Payment API"
    }
  ]
}

SaferpayFieldsAccessToken CreateAccessToken

POST
Create a Saferpay Fields Access Token that can be used to integrate Saferpay Fields into web pages and is restricted to the given customerId, terminalId and URL(s).

Request URL:

POST: /rest/customers/[customerId]/terminals/[terminalId]/fields-access-tokens

Request

Arguments
SourceUrls
mandatory, string[]
The fully qualified URL of the shop (the page that integrates Saferpay Fields). We recommend that URLs end with a trailing slash. Only HTTPS is allowed.
Example: https://yourshop.com/
Description
mandatory, string
A human readable description that will be shown in the Saferpay Backoffice to easily identify the Access Token.
Utf8[1..128]

Example:

{
  "SourceUrls": [
    "https://a.yourshop.com/",
    "https://b.yourshop.com/"
  ],
  "Description": "Saferpay Fields Access Token for YourShop"
}

Response

Arguments
AccessToken
mandatory, string
The AccessToken for the Saferpay Fields JavaScript library
Example: 67f47961-2912-4338-8039-22ac2b8486f3

Example:

{
  "AccessToken": "67f47961-2912-4338-8039-22ac2b8486f3"
}

SecurePayGate Create SingleUsePaymentLink

POST
This function may be used to create a single use payment link

Request URL:

POST: /rest/customers/[customerId]/terminals/[terminalId]/spg-offers

Request

Arguments
Payment
mandatory, object
Information about the payment (amount, currency, ...)
ExpirationDate
mandatory, string
The date after which the offer expires in ISO 8601 format.
yyyy-MM-ddTHH:mm:ssK
Must be at least 1h in the future and within the next 180 days.
AlphaNumeric[10..25]
Example: 2019-10-20T00:00:00+02:00
ConfigSet
string
This parameter lets you define your payment page config (PPConfig) by name. If this parameter 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)
Payer
mandatory, object
Information about the payer
BillingAddressForm
object
Used to have the payer enter or change his billing address in the payment process.
RegisterAlias
object
Controls whether the means of payment used for paying the offer should be stored inside the Saferpay Secure Card Data storage.
If the offer is paid using a payment means that does not support being stored in the Secure Card Data storage, this parameter has no effect.
Order
object
Optional order information. Only used for payment method Klarna (mandatory) and for Fraud Intelligence (optional).
Condition
string
THREE_DS_AUTHENTICATION_SUCCESSFUL_OR_ATTEMPTED: 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.
WITH_SUCCESSFUL_THREE_DS_CHALLENGE: Will force the 3D-Secure challenge.
---
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: NONE, THREE_DS_AUTHENTICATION_SUCCESSFUL_OR_ATTEMPTED, WITH_SUCCESSFUL_THREE_DS_CHALLENGE.
Example: NONE

Example:

{
  "Payment": {
    "Amount": {
      "Value": "404",
      "CurrencyCode": "CHF"
    },
    "OrderId": "094c2a7ce1374f7ca184591f123b154d",
    "Options": {
      "PreAuth": true
    }
  },
  "ExpirationDate": "2020-04-23T00:00:00+02:00",
  "Payer": {
    "LanguageCode": "de",
    "BillingAddress": {
      "FirstName": "John",
      "LastName": "Doe",
      "Company": "Worldline",
      "Gender": "MALE",
      "Street": "Mustergasse 123",
      "Zip": "8008",
      "City": "Zurich",
      "CountryCode": "CH",
      "Email": "payer@provider.com"
    }
  }
}

Response

Arguments
OfferId
mandatory, globally unique identifier
The Id of the SecurePayGate offer
Example: 503a3d7b-072b-400f-9e7e-8ec15191c737
PaymentLink
mandatory, string
The SecurePayGate link for the payment
Example: https://www.saferpay.com/SecurePayGate/Payment/123456/12345678/503a3d7b-072b-400f-9e7e-8ec15191c737

Example:

{
  "OfferId": "503a3d7b-072b-400f-9e7e-8ec15191c737",
  "PaymentLink": "https://www.saferpay.com/SecurePayGate/Payment/123456/12345678/503a3d7b-072b-400f-9e7e-8ec15191c737"
}

SecurePayGate SingleUsePaymentLink

GET
This function may be used to fetch the status of a previously created single use payment link

Request URL:

GET: /rest/customers/[customerId]/terminals/[terminalId]/spg-offers/[offerId]

Request

No body needed

Example:

No example available

Response

Arguments
OfferId
globally unique identifier
The Id of the SecurePayGate offer
Example: 503a3d7b-072b-400f-9e7e-8ec15191c737
PaymentLink
string
The SecurePayGate link for the payment
Example: https://www.saferpay.com/SecurePayGate/Payment/123456/12345678/503a3d7b-072b-400f-9e7e-8ec15191c737
Status
string
The status of the SecurePayGate offer
Possible values: OPEN, PAID, EXPIRED.
Example: PAID
TransactionId
string
The transaction id once a transaction was made
Example: vA3bhlAht2WlSAOKOvQSAOnbAdCb
Payment
object
Information about the payment (amount, currency, description, orderId)
CreationDate
date
The creation date and time of the SecurePayGate offer
Example: 2023-02-24T11:34:11.128+01:00
ExpirationDate
date
The date after which the offer expires
Example: 2023-04-20T00:00:00.000+02:00

Example:

{
  "OfferId": "503a3d7b-072b-400f-9e7e-8ec15191c737",
  "PaymentLink": "https://www.saferpay.com/SecurePayGate/Payment/123456/12345678/503a3d7b-072b-400f-9e7e-8ec15191c737",
  "Status": "OPEN",
  "Payment": {
    "Amount": {
      "Value": "100",
      "CurrencyCode": "CHF"
    },
    "OrderId": "cd0005bf21bb4906bcbea939d74cee72",
    "Description": "Hallo"
  },
  "CreationDate": "2023-03-01T11:37:47.682+01:00",
  "ExpirationDate": "2023-04-01T00:00:00+02:00"
}

DELETE
This function may be used to delete a single use payment link before it's expiry

Request URL:

DELETE: /rest/customers/[customerId]/terminals/[terminalId]/spg-offers/[offerId]

Request

No body needed

Example:

No example available

Response

Terminal GetTerminal

GET
This method is used to retrieve details of one terminal

Request URL:

GET: /rest/customers/[customerId]/terminals/[terminalId]

Request

No body needed

Example:

No example available

Response

Arguments
TerminalId
string
The Id of the terminal
Type
string
The type of the terminal
Possible values: ECOM, SPG, MPO.
Description
string
Description of the terminal
PaymentMethods
array of objects
Array of payment methods that are available for the terminal
Wallets
array of objects
Array of wallets that are available for the terminal

Example:

{
  "TerminalId": "1000001",
  "Type": "ECOM",
  "Description": "Terminal 1 for Payment Page / Ecommerce",
  "PaymentMethods": [
    {
      "PaymentMethod": "VISA",
      "Currencies": [
        "USD"
      ],
      "LogoUrl": "https://www.saferpay.com/static/logo/visa.svg?v=637381079349290910"
    },
    {
      "PaymentMethod": "MASTERCARD",
      "Currencies": [
        "EUR",
        "CHF"
      ],
      "LogoUrl": "https://www.saferpay.com/static/logo/mastercard.svg?v=637381079349290910"
    },
    {
      "PaymentMethod": "MAESTRO",
      "Currencies": [
        "EUR"
      ],
      "LogoUrl": "https://www.saferpay.com/static/logo/maestro.svg?v=637381079349290910"
    },
    {
      "PaymentMethod": "PAYPAL",
      "Currencies": [
        "EUR",
        "CHF",
        "USD"
      ],
      "LogoUrl": "https://www.saferpay.com/static/logo/paypal.svg?v=637381079349290910"
    }
  ],
  "Wallets": [
    {
      "WalletName": "APPLEPAY",
      "LogoUrl": "https://www.saferpay.com/static/logo/applepay.svg?v=637381079349290910"
    },
    {
      "WalletName": "GOOGLEPAY",
      "LogoUrl": "https://www.saferpay.com/static/logo/googlepay.svg?v=637381079349290910"
    }
  ]
}

TerminalInfo PaymentMethods

GET
DEPRECATED:: since Version 1.31. Please use instead: /rest/customers/{customerId}/terminals/{terminalId}/

This method is used to retrieve a list of all available payment methods and wallets for a terminal.

Request URL:

GET: /rest/customers/[customerId]/terminals/[terminalId]/payment-methods

Request

No body needed

Example:

No example available

Response

Arguments
PaymentMethods
array of objects
Array of payment methods that are available for the terminal
Wallets
array of objects
Array of wallets that are available for the terminal

Example:

{
  "PaymentMethods": [
    {
      "PaymentMethod": "VISA",
      "Currencies": [
        "USD"
      ],
      "LogoUrl": "https://www.saferpay.com/static/logo/visa.svg?v=637381079349290910"
    },
    {
      "PaymentMethod": "MASTERCARD",
      "Currencies": [
        "EUR",
        "CHF"
      ],
      "LogoUrl": "https://www.saferpay.com/static/logo/mastercard.svg?v=637381079349290910"
    },
    {
      "PaymentMethod": "MAESTRO",
      "Currencies": [
        "EUR"
      ],
      "LogoUrl": "https://www.saferpay.com/static/logo/maestro.svg?v=637381079349290910"
    },
    {
      "PaymentMethod": "PAYPAL",
      "Currencies": [
        "EUR",
        "CHF",
        "USD"
      ],
      "LogoUrl": "https://www.saferpay.com/static/logo/paypal.svg?v=637381079349290910"
    }
  ],
  "Wallets": [
    {
      "WalletName": "APPLEPAY",
      "LogoUrl": "https://www.saferpay.com/static/logo/applepay.svg?v=637381079349290910"
    },
    {
      "WalletName": "GOOGLEPAY",
      "LogoUrl": "https://www.saferpay.com/static/logo/googlepay.svg?v=637381079349290910"
    }
  ]
}

Terminals GetTerminals

GET
This method is used to retrieve all terminals

Request URL:

GET: /rest/customers/[customerId]/terminals

Request

No body needed

Example:

No example available

Response

Arguments
Terminals
array of objects
Array of terminals

Example:

{
  "Terminals": [
    {
      "TerminalId": "1000001",
      "Type": "ECOM",
      "Description": "Terminal 1 for Payment Page / Ecommerce"
    },
    {
      "TerminalId": "1000002",
      "Type": "MPO",
      "Description": "Terminal 2 for Mail Phone Order"
    },
    {
      "TerminalId": "1000002",
      "Type": "SPG",
      "Description": "Terminal 3 for Secure Pay Gate"
    }
  ]
}

Container Dictionary

Container "Common_Models_Data_AmountWithoutZero"

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

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

AddressSource
mandatory, string
Specifies if and where Saferpay should take the payer's address data from.
SAFERPAY will result in an address form being shown to the payer in the Saferpay Payment Page.
PREFER_PAYMENTMETHOD will retrieve the address data from the means of payment if supported. PREFER_PAYMENTMETHOD will fall back to SAFERPAY if not available with the chosen payment method.
For NONE no address form will be displayed and no address data will be retrieved from the means of payment.
Possible values: NONE, SAFERPAY, PREFER_PAYMENTMETHOD.
MandatoryFields
array of strings
List of fields which the payer must enter to proceed with the payment.
This is only applicable if Saferpay displays the address form.
If no mandatory fields are sent, all fields except SALUTATION, COMPANY and PHONE are mandatory.
Possible values: CITY, COMPANY, VATNUMBER, COUNTRY, EMAIL, FIRSTNAME, LASTNAME, PHONE, SALUTATION, STATE, STREET, ZIP.
Example: ["FIRSTNAME", "LASTNAME", "PHONE"]

Container "Common_Models_Data_DeliveryAddressForm"

AddressSource
mandatory, string
Specifies if and where Saferpay should take the payer's address data from.
SAFERPAY will result in an address form being shown to the payer in the Saferpay Payment Page.
PREFER_PAYMENTMETHOD will retrieve the address data from the means of payment if supported. PREFER_PAYMENTMETHOD will fall back to SAFERPAY if not available with the chosen payment method.
For NONE no address form will be displayed and no address data will be retrieved from the means of payment.
Possible values: NONE, SAFERPAY, PREFER_PAYMENTMETHOD.
MandatoryFields
array of strings
List of fields which the payer must enter to proceed with the payment.
This is only applicable if Saferpay displays the address form.
If no mandatory fields are sent, all fields except SALUTATION, COMPANY and PHONE are mandatory.
Possible values: CITY, COMPANY, COUNTRY, EMAIL, FIRSTNAME, LASTNAME, PHONE, SALUTATION, STATE, STREET, ZIP.
Example: ["FIRSTNAME", "LASTNAME", "PHONE"]

Container "Common_Models_Data_Payer"

IpAddress
string
IPv4 address of the card holder / payer if available. Dotted quad notation.
Example: 111.111.111.111
Ipv6Address
string
IPv6 address of the card holder / payer if available.
Example: 2001:0db8:0000:08d3:0000:8a2e:0070:7344
LanguageCode
string
Language to force Saferpay to display something to the payer in a certain language. Per default, Saferpay will determine the language using the payers browser agent.
The supported language codes are listed below. This list may be extended in the future as more languages become available. If the submitted language code has a valid format, but is not supported, then the default language is used.

Code-List:
bg - Bulgarian
cs - Czech
da - Danish
de - German
de-ch - Swiss German
el - Greek
en - English
es - Spanish
et - Estonian
fi - Finnish
fr - French
hr - Croatian
hu - Hungarian
is - Icelandic
it - Italian
ja - Japanese
lt - Lithuanian
lv - Latvian
nl - Dutch
nn - Norwegian
pl - Polish
pt - Portuguese
ro - Romanian
ru - Russian
sk - Slovak
sl - Slovenian
sv - Swedish
tr - Turkish
uk - Ukrainian
zh - Chinese
Example: de
BillingAddress
object
Information on the payers billing address
Id
string
Payer identifier defined by the merchant / shop. The ID can be numeric, alphabetical and contain any of the following special characters: .:!#$%&'*+-/=?^_`{|}~@.
For GDPR reasons we strongly discourage the use of ids containing any personal data (e.g. names) and instead recommend the usage of a merchant-side generated UUID for your customer.
PayerId[1..256]
DeliveryAddress
object
Information on the payers delivery address
AcceptHeader
string
Browser accept header
Example: text/html,application/xhtml\u002Bxml,application/xml
UserAgent
string
User agent
Example: Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Gecko/20100101 Firefox/47.0
JavaEnabled
boolean
Is Java enabled
JavaScriptEnabled
boolean
Is JavaScript enabled
ScreenWidth
integer
Screen width
Example: 1920
ScreenHeight
integer
Screen height
Example: 1080
ColorDepth
string
Color depth
Possible values: 1bit, 4bits, 8bits, 15bits, 16bits, 24bits, 32bits, 48bits.
Example: 32bits
TimeZoneOffsetMinutes
integer
Time zone offset in minutes
Example: 720 120

Container "Common_Models_Data_PaymentOptions"

PreAuth
boolean
Indicates the desired transaction type. When set to true the transaction is processed as a pre-authorization otherwise as a final authorization. Please note that not all payment methods support both options and the effective transaction type is determined by Saferpay.
AllowPartialAuthorization
boolean
When set to true, a transaction might be authorized with an amount less than requested authorization amount.

Important:

  • Not all the payment methods support this option.
  • This option is currently supported only in Transaction/Initialize and Transaction/AuthorizeDirect.
  • Using this option in Transaction/Initialize prevents DCC.

Container "Common_Models_Data_RequestAddress"

FirstName
string
The payer's first name
Utf8[1..100]
Example: John
LastName
string
The payer's last name
Utf8[1..100]
Example: Doe
Company
string
The payer's company
Utf8[1..100]
Example: ACME Corp.
Gender
string
The payer's gender
Possible values: MALE, FEMALE, DIVERSE, COMPANY.
Example: COMPANY
Street
string
The payer's street
Utf8[1..100]
Example: Bakerstreet 32
Zip
string
The payer's zip code
Utf8[1..100]
Example: 8000
City
string
The payer's city
Utf8[1..100]
Example: Zurich
CountryCode
string
The payer's country code
ISO 3166-1 alpha-2 country code
(Non-standard: XK for Kosovo)
Alphabetic[2..2]
Example: CH
Email
string
The payer's email address
Example: payer@provider.com
DateOfBirth
string
The payer's date of birth in ISO 8601 extended date notation
YYYY-MM-DD
AlphaNumeric[10..10]
Example: 1990-05-31
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
Phone
string
The payer's phone number
Utf8[1..100]
Example: +41 12 345 6789
CountrySubdivisionCode
string
The payer's country subdivision code
Allows country codes formatted as ISO 3166 or ISO 3166-2.
Iso3166[1..6]
Example: ZH / CH-ZH

Container "Common_Models_Data_RequestBillingAddress"

FirstName
string
The payer's first name
Utf8[1..100]
Example: John
LastName
string
The payer's last name
Utf8[1..100]
Example: Doe
Company
string
The payer's company
Utf8[1..100]
Example: ACME Corp.
Gender
string
The payer's gender
Possible values: MALE, FEMALE, DIVERSE, COMPANY.
Example: COMPANY
Street
string
The payer's street
Utf8[1..100]
Example: Bakerstreet 32
Zip
string
The payer's zip code
Utf8[1..100]
Example: 8000
City
string
The payer's city
Utf8[1..100]
Example: Zurich
CountryCode
string
The payer's country code
ISO 3166-1 alpha-2 country code
(Non-standard: XK for Kosovo)
Alphabetic[2..2]
Example: CH
Email
string
The payer's email address
Example: payer@provider.com
DateOfBirth
string
The payer's date of birth in ISO 8601 extended date notation
YYYY-MM-DD
AlphaNumeric[10..10]
Example: 1990-05-31
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
Phone
string
The payer's phone number
Utf8[1..100]
Example: +41 12 345 6789
VatNumber
string
The company's vat number
Utf8[1..25]
CountrySubdivisionCode
string
The payer's country subdivision code
Allows country codes formatted as ISO 3166 or ISO 3166-2.
Iso3166[1..6]
Example: ZH / CH-ZH

Container "Common_Models_Data_ResponseAddress"

FirstName
string
The payer's first name
Utf8[1..100]
Example: John
LastName
string
The payer's last name
Utf8[1..100]
Example: Doe
Company
string
The payer's company
Utf8[1..100]
Example: ACME Corp.
Gender
string
The payer's gender
Possible values: MALE, FEMALE, DIVERSE, COMPANY.
Example: COMPANY
Street
string
The payer's street
Utf8[1..100]
Example: Bakerstreet 32
Zip
string
The payer's zip code
Utf8[1..100]
Example: 8000
City
string
The payer's city
Utf8[1..100]
Example: Zurich
CountryCode
string
The payer's country code
ISO 3166-1 alpha-2 country code
(Non-standard: XK for Kosovo)
Alphabetic[2..2]
Example: CH
Email
string
The payer's email address
Example: payer@provider.com
DateOfBirth
string
The payer's date of birth in ISO 8601 extended date notation
YYYY-MM-DD
AlphaNumeric[10..10]
Example: 1990-05-31
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
Phone
string
The payer's phone number
Utf8[1..100]
Example: +41 12 345 6789
CountrySubdivisionCode
string
The payer's country subdivision code in ISO 3166-2
AlphaNumeric[1..3]
Example: ZH

Container "Common_Models_Data_ResponseBillingAddress"

FirstName
string
The payer's first name
Utf8[1..100]
Example: John
LastName
string
The payer's last name
Utf8[1..100]
Example: Doe
Company
string
The payer's company
Utf8[1..100]
Example: ACME Corp.
Gender
string
The payer's gender
Possible values: MALE, FEMALE, DIVERSE, COMPANY.
Example: COMPANY
Street
string
The payer's street
Utf8[1..100]
Example: Bakerstreet 32
Zip
string
The payer's zip code
Utf8[1..100]
Example: 8000
City
string
The payer's city
Utf8[1..100]
Example: Zurich
CountryCode
string
The payer's country code
ISO 3166-1 alpha-2 country code
(Non-standard: XK for Kosovo)
Alphabetic[2..2]
Example: CH
Email
string
The payer's email address
Example: payer@provider.com
DateOfBirth
string
The payer's date of birth in ISO 8601 extended date notation
YYYY-MM-DD
AlphaNumeric[10..10]
Example: 1990-05-31
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
Phone
string
The payer's phone number
Utf8[1..100]
Example: +41 12 345 6789
VatNumber
string
The company's vat number
Utf8[1..25]
CountrySubdivisionCode
string
The payer's country subdivision code in ISO 3166-2
AlphaNumeric[1..3]
Example: ZH

Container "Common_Models_Data_SpgBillingAddressForm"

AddressSource
mandatory, string
Specifies if and where Saferpay should take the payer's address data from.
SAFERPAY will result in an address form being shown to the payer in the Saferpay Payment Page.
PREFER_PAYMENTMETHOD will retrieve the address data from the means of payment if supported. PREFER_PAYMENTMETHOD will fall back to SAFERPAY if not available with the chosen payment method.
For NONE no address form will be displayed and no address data will be retrieved from the means of payment.
Possible values: NONE, SAFERPAY, PREFER_PAYMENTMETHOD.
MandatoryFields
array of strings
List of fields which the payer must enter to proceed with the payment.
This is only applicable if Saferpay displays the address form.
If no mandatory fields are sent, all fields except SALUTATION, COMPANY and PHONE are mandatory.
Possible values: CITY, COMPANY, VATNUMBER, COUNTRY, EMAIL, FIRSTNAME, LASTNAME, PHONE, SALUTATION, STATE, STREET, ZIP.
Example: ["FIRSTNAME", "LASTNAME", "PHONE"]

Container "Common_Models_Data_SpgPayer"

IpAddress
string
IPv4 address of the card holder / payer if available. Dotted quad notation.
Example: 111.111.111.111
Ipv6Address
string
IPv6 address of the card holder / payer if available.
Example: 2001:0db8:0000:08d3:0000:8a2e:0070:7344
LanguageCode
string
Language to force Saferpay to display something to the payer in a certain language. Per default, Saferpay will determine the language using the payers browser agent.
The supported language codes are listed below. This list may be extended in the future as more languages become available. If the submitted language code has a valid format, but is not supported, then the default language is used.

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

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, 1.11, 1.12, 1.13, 1.14, 1.15, 1.16, 1.17, 1.18, 1.19, 1.20, 1.21, 1.22, 1.23, 1.24, 1.25, 1.26, 1.27, 1.28, 1.29, 1.30, 1.31, 1.32, 1.33, 1.34, 1.35, 1.36, 1.37, 1.38, 1.39
Example: 1.39
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
Id generated by merchant system, for debugging purposes. Should be unique for each new request. If a request is retried due to an error, use the same request id. In this case, the RetryIndicator should be increased instead, to indicate a subsequent attempt.
Id[1..50]
Example: 33e8af17-35c1-4165-a343-c1c86a320f3b
RetryIndicator
mandatory, integer
0 if this specific request is attempted for the first time, >=1 if it is a retry.
Range: inclusive between 0 and 9
Example: 0
ClientInfo
object
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, 1.11, 1.12, 1.13, 1.14, 1.15, 1.16, 1.17, 1.18, 1.19, 1.20, 1.21, 1.22, 1.23, 1.24, 1.25, 1.26, 1.27, 1.28, 1.29, 1.30, 1.31, 1.32, 1.33, 1.34, 1.35, 1.36, 1.37, 1.38, 1.39
Example: 1.39

Container "Payment_Models_A2ARefund"

AccountHolderName
mandatory, string
The account holder name will be used if not already present in the authorization.
If no account holder name is present in the authorization and none provided in the refund request, the refund cannot be processed.
Utf8[1..50]
Example: John Doe

Container "Payment_Models_AlternativePayment_BancontactPaymentMethodOptions"

AppDefaultRedirectUrl
URI
This URL is called by the bancontact payment app when the payer cancels the payment.
The maximum allowed length for this URL is 256 characters.
AppCompletionRedirectUrl
URI
This URL is called by the bancontact payment app once the payment is authorized successfully.
The maximum allowed length for this URL is 256 characters.

Container "Payment_Models_AlternativePayment_PaymentMethodOptions"

Bancontact
object
bancontact-specific options for this payment

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

Result
mandatory, string
The result of the card holder authentication.
Possible values: OK, NOT_SUPPORTED.
Message
mandatory, string
More details, if available. Contents may change at any time, so don’t parse it.
Example: Card holder authentication with 3DSv2 successful.
Xid
string
Transaction Id, given by the MPI. References the 3D Secure version 2 process.
Example: 1ef5b3db-3b97-47df-8272-320d0bd18ab5

Container "Payment_Models_Data_AliasAuthenticationResultBase"

Result
mandatory, string
The result of the card holder authentication.
Possible values: OK, NOT_SUPPORTED.
Message
mandatory, string
More details, if available. Contents may change at any time, so don’t parse it.
Example: Card holder authentication with 3DSv2 successful.

Container "Payment_Models_Data_AliasDirectInsertCheck"

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_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 (subject to availability for the brand/acquirer).
ONLINE performs an online account check (one transaction point will be billed for such a check)
ONLINE_STRONG performs a strong customer authentication (SCA) which involves a 3DS v2 authentication and an online account check (for which one transaction point will be billed)
Possible values: ONLINE, ONLINE_STRONG.
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 card check.
Possible values: OK, OK_AUTHENTICATED, 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.
Authentication
object
More details about the card holder authentication.
IssuerReference
object

Container "Payment_Models_Data_AliasInsertDirectPaymentMeans"

SaferpayFields
object
Payment means data collected with SaferpayFields.
Card
object
Card data
Alias
object
Alias data if payment means was registered with Secure Card Data before.
SchemeToken
object
Surrogate values that replace the primary account number (PAN) according to the EMV Payment Tokenization Specification.
Note: LiabilityShift is only possible with Transaction Initialize, AuthorizeDirect and RefundDirect.
BankAccount
object
Bank account data for direct debit transaction
GooglePay
object
Payment Data from GooglePay
ApplePay
object
Payment Data from Apple Pay Wallet

Container "Payment_Models_Data_AliasNotification"

NotifyUrl
string
the url that should be called to notify when the process is done

Container "Payment_Models_Data_AliasPaymentMeansInfo"

Brand
mandatory, object
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: APPLEPAY
Card
object
Card data
BankAccount
object
Bank account data for direct debit transactions.
Twint
object
Twint data

Container "Payment_Models_Data_AlternativePaymentNotification"

MerchantEmails
array of strings
Email addresses to which a confirmation email will be sent to the merchants after successful authorizations.
A maximum of 10 email addresses is allowed.
Example: ["merchant1@saferpay.com", "merchant2@saferpay.com"]
PayerEmail
string
Email address to which a confirmation email will be sent to the payer after successful authorizations.
Example: payer@saferpay.com
StateNotificationUrl
mandatory, URI
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_AlternativePaymentProcessingData"

Bancontact
object
Bancontact specific data for processing payment

Container "Payment_Models_Data_ApplePay"

PaymentToken
mandatory, string
Base64 encoded ApplePayPaymentToken Json according to Apple's Payment Token Format Reference
Base64 encoded string

Container "Payment_Models_Data_AuthorizeDirectPaymentMeans"

SaferpayFields
object
Payment means data collected with SaferpayFields.
Card
object
Card data
Alias
object
Alias data if payment means was registered with Secure Card Data before.
SchemeToken
object
Surrogate values that replace the primary account number (PAN) according to the EMV Payment Tokenization Specification.
Note: LiabilityShift is only possible with Transaction Initialize, AuthorizeDirect and RefundDirect.
BankAccount
object
Bank account data for direct debit transaction
GooglePay
object
Payment Data from GooglePay
ApplePay
object
Payment Data from Apple Pay Wallet

Container "Payment_Models_Data_BancontactProcessingData"

QrCodeData
string
Data which should be integrated into a QR code. In order to make the scanning as easy as possible,
the recommended format of QR code encoding is version 3, with lower error rate correction level
in character mode, resulting with a 29 x 29 pixels image maximum.
IntentUrl
string
Url to be used for payment on the same device (web-to-app or app-to-app switch)

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

Amount
mandatory, object
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
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
Description
string
A human readable description provided by the merchant that can be displayed in web sites.
Utf8[1..1000]
Example: Description

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: ACCOUNTTOACCOUNT, ALIPAY, AMEX, BANCONTACT, BONUS, DINERS, CARD, DIRECTDEBIT, EPRZELEWY, EPS, GIROPAY, IDEAL, INVOICE, JCB, KLARNA, MAESTRO, MASTERCARD, MYONE, PAYCONIQ, PAYDIREKT, PAYPAL, POSTCARD, POSTFINANCE, POSTFINANCEPAY, SOFORT, TWINT, UNIONPAY, VISA, WLCRYPTOPAYMENTS.
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: VISA

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 lets you customize the holder name field on the card entry form. Per default, a holder name field is not shown.
Possible values: NONE, MANDATORY.
Example: MANDATORY

Container "Payment_Models_Data_CardFormInTransactionInitialize"

HolderName
string
This parameter lets you customize the holder name field on the card entry form. Per default, a holder name field is not shown.
Possible values: NONE, MANDATORY.
Example: MANDATORY
VerificationCode
string
This parameter can be used to display an entry form to request Verification Code (CVV, CVC) in case that an alias is used as PaymentMeans. Note that not all brands support Verification Code.
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
HolderSegment
string
The Segment of card holder. Only returned for Alias/AssertInsert, Alias/InsertDirect and Alias/Update calls if available.
Possible values: UNSPECIFIED, CONSUMER, CORPORATE, CORPORATE_AND_CONSUMER.
Example: CORPORATE
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_CustomPlan"

MinimumNumberOfInstallments
mandatory, integer
Maximum Number of Installments. Valid values are 2–99 and
MaximumNumberOfInstallments must be bigger or equal MinimumNumberOfInstallments.
MaximumNumberOfInstallments
mandatory, integer
Minimum Number of Installments. Valid values are 2–99 and
MinimumNumberOfInstallments must be smaller or equal MaximumNumberOfInstallments.
InterestRate
string
Interest rate in hundredth of a percent. e.g. value 125 means 1.25%.
Valid values are 0-99999
InstallmentFee
object
Installment Fee
AnnualPercentageRate
string
Annual percentage rate in hundreth of a percent. e.g. value 125 means 1.25%.
Valid values are 0-99999
TotalAmountDue
object
Total Amount Due

Container "Payment_Models_Data_DccInfo"

PayerAmount
mandatory, object
Amount in payer’s currency
Markup
mandatory, string
DCC markup fee
Example: 3%
ExchangeRate
mandatory, string
The used exchange rate including markup
The decimal separator used is '.' regardless of location
Example: 1.2345

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

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
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://).
If a custom CSS is provided, any design related settings set in the payment page config (PPConfig) will be ignored and the default design will be used.
Max length: 2000
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.

Container "Payment_Models_Data_GooglePay"

PaymentToken
mandatory, string
GooglePay Payment Token

Container "Payment_Models_Data_IdealOptions"

IssuerId
mandatory, string
Preselect the iDEAL issuer. If specified together with PaymentMethods preselection of iDEAL,
the user is redirected directly to the issuer bank.
If the IssuerId is set, it is mandatory to use iDEAL in PaymentMethods.

Container "Payment_Models_Data_InsertAliasSupportingPaymentMeans"

SaferpayFields
object
Payment means data collected with SaferpayFields.
Card
object
Card data

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

NumberOfInstallments
mandatory, integer
Number of Installments. Valid values are 2–99.
Range: inclusive between 2 and 99
InterestRate
string
Interest rate in hundredth of a percent. e.g. value 125 means 1.25%.
Valid values are 0-99999
InstallmentFee
object
Installment Fee
AnnualPercentageRate
string
Annual percentage rate in hundredth of a percent. e.g. value 125 means 1.25%.
Valid values are 0-99999
FirstInstallmentAmount
object
First Installment Amount
SubsequentInstallmentAmount
object
Subsequent Installment Amount
TotalAmountDue
object
Total Amount Due

Container "Payment_Models_Data_InvoiceInfo"

Payee
object
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_IssuerReference"

TransactionStamp
mandatory, string
TransactionStamp
Max length: 50
Example: 9406957728464714731817
SettlementDate
string
SettlementDate with the format MMDD
String length: inclusive between 4 and 4
Example: 0122

Container "Payment_Models_Data_IssuerReferenceInfo"

TransactionStamp
string
SCA transaction stamp, created by the card issuer
SettlementDate
string
SCA transaction settlement date, created by the card issuer. For MasterCard schemes only.

Container "Payment_Models_Data_KlarnaAttachment"

ContentType
mandatory, string
Utf8[1..1000]
Body
mandatory, string
Utf8[1..100000]

Container "Payment_Models_Data_KlarnaOptions"

Attachment
mandatory, object
Klarna extra merchant data (EMD).
Check Klarna's EMD documentation for further details.

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
Possible values: MERCHANT, THREEDS.
ThreeDs
object
Details about ThreeDs if applicable
InPsd2Scope
string
Determines if the transaction is in the PSD2 Scope (Payment Service Directive 2 of the European Union)
Possible values: YES, NO, UNKNOWN.

Container "Payment_Models_Data_MarketplaceCapture"

SubmerchantId
mandatory, string
The id of the marketplace submerchant on whose behalf a multipart capture or refund capture is being made.
Id[1..15]
Fee
object
The marketplace fee that will be charged from the marketplace to the submerchant.
The properties Fee and FeeRefund cannot be used simultaneously.
FeeRefund
object
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_MastercardIssuerInstallmentsOptions"

InstallmentPlans
array of objects
A maximum number of 12 fixed installment plans
If InstallmentPlans is present, CustomPlan must not be present
CustomPlan
object
An installment plan with customizable numbers of installments
If CustomPlan is present, InstallmentPlans must not be present

An installment plan with customizable numbers of installments
ReceiptFreeText
string
Receipt Free Text

Container "Payment_Models_Data_MastercardIssuerInstallmentsSelection"

ChosenPlan
object
Installment Payment Data, if applicable

A single, fixed installment plan

Container "Payment_Models_Data_Notification"

MerchantEmails
array of strings
Email addresses to which a confirmation email will be sent to the merchants after successful authorizations.
A maximum of 10 email addresses is allowed.
Example: ["merchant1@saferpay.com", "merchant2@saferpay.com"]
PayerEmail
string
Email address to which a confirmation email will be sent to the payer after successful authorizations.
Example: payer@saferpay.com
PayerDccReceiptEmail
string
Email address to which a confirmation email will be sent to the payer after successful authorizations processed with DCC.
This option can only be used when the field PayerEmail is not set.
Example: payer@saferpay.com
SuccessNotifyUrl
recommended, string
Url to which Saferpay will send the asynchronous success notification for the transaction. Supported schemes are http and https. You also have to make sure to support the GET-method.
Max length: 2000
Example: https://merchanthost/notify/123
FailNotifyUrl
recommended, string
Url to which Saferpay will send the asynchronous failure notification for the transaction. Supported schemes are http and https. You also have to make sure to support the GET-method.
Max length: 2000
Example: https://merchanthost/notify/123

Container "Payment_Models_Data_Order"

Items
mandatory, array of objects
Order items

Container "Payment_Models_Data_OrderItem"

Type
string
Order item type
Possible values: DIGITAL, PHYSICAL, SERVICE, GIFTCARD, DISCOUNT, SHIPPINGFEE, SALESTAX, SURCHARGE.
Id
string
Product id
Utf8[1..100]
Example: C123192
VariantId
string
Product variant id
Utf8[1..100]
Example: C123192-red
Name
string
Product name
Utf8[1..200]
Example: red swiss army knife
CategoryName
string
Category name
Utf8[1..100]
Example: knives
Description
string
Product description
Utf8[1..200]
Example: The well known swiss army knife
Quantity
integer
The quantity of the order item
Example: 2
UnitPrice
string
Price per single item in minor unit (CHF 15.50 ⇒ Value=1550). Only Integer values will be accepted!
Example: 1550
IsPreOrder
boolean
Flag, which indicates that the order item is a pre order. Per default, it is not a pre order.
Example: true
TaxRate
string
Tax rate of the item price in hundredth of a percent. e.g. value 1900 means 19.00%
Valid values are 0-99999
Range: inclusive between 0 and 99999
Example: 1900
TaxAmount
string
Total tax amount of the order item. This tax needs to be included in the UnitPrice and must take the Quantity of the order item into account.
Example: 480
DiscountAmount
string
Discount amount including tax
Example: 92
ProductUrl
string
URL to the product page
Max length: 2000
Example: https://merchanthost/product/1
ImageUrl
string
URL to an image showing the product
Max length: 2000
Example: https://merchanthost/product/1/image

Container "Payment_Models_Data_OriginalCreditTransfer"

Recipient
object
Address of the Recipient.

Container "Payment_Models_Data_PayerInfo"

Id
string
Payer identifier defined by the merchant / shop. The ID can be numeric, alphabetical and contain any of the following special characters: .:!#$%&'*+-/=?^_`{|}~@.
PayerId[1..256]
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
object
BillingAddress
object

Container "Payment_Models_Data_PayerProfile"

HasAccount
boolean
Does the payer have an account in the shop?
HasPassword
boolean
Does the payer have a password?
PasswordForgotten
boolean
Was the password reset by the payer using the "forgot my password" feature in the current session?
FirstName
string
The payer's first name
Utf8[1..100]
LastName
string
The payer's last name
Utf8[1..100]
Company
string
The payer's company
Utf8[1..100]
DateOfBirth
string
The payer's date of birth (ISO 8601)
YYYY-MM-DD
AlphaNumeric[10..10]
Example: 1990-05-31
LastLoginDate
date
The payer's last login (ISO 8601)
Example: 2018-05-25T18:12:43Z 2018-05-25T19:12:43+01:00
Gender
string
The payer's gender
Possible values: MALE, FEMALE, DIVERSE, COMPANY.
Example: COMPANY
CreationDate
date
Date and Time (ISO 8601) when user account was created
Example: 2018-05-25T18:12:43Z 2018-05-25T19:12:43+01:00
PasswordLastChangeDate
date
Date and Time (ISO 8601) when the account password was changed last time
Example: 2018-05-25T18:12:43Z 2018-05-25T19:12:43+01:00
Email
string
The payer's email address
Example: payer@provider.com
SecondaryEmail
string
The payer's secondary email address
Example: payer_secondary@provider.com
Phone
object
The payer's phone numbers

Container "Payment_Models_Data_Payment"

Amount
mandatory, object
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
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
Description
string
A human readable description provided by the merchant that can be displayed in web sites.
Utf8[1..1000]
Example: Description
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
object
Specific payment options
Recurring
object
Recurring options – cannot be combined with Installment.
Installment
object
Installment options – cannot be combined with Recurring.

Container "Payment_Models_Data_PaymentMeans"

SaferpayFields
object
Payment means data collected with SaferpayFields.
Card
object
Card data
Alias
object
Alias data if payment means was registered with Secure Card Data before.
SchemeToken
object
Surrogate values that replace the primary account number (PAN) according to the EMV Payment Tokenization Specification.
Note: LiabilityShift is only possible with Transaction Initialize, AuthorizeDirect and RefundDirect.
BankAccount
object
Bank account data for direct debit transaction
GooglePay
object
Payment Data from GooglePay
ApplePay
object
Payment Data from ApplePay

Container "Payment_Models_Data_PaymentMeansInfo"

Brand
mandatory, object
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: APPLEPAY
Card
object
Card data
BankAccount
object
Bank account data for direct debit transactions.
PayPal
object
PayPal data

Container "Payment_Models_Data_PaymentPagePayment"

Amount
mandatory, object
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
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
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
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
object
Specific payment options
Recurring
object
Recurring options – cannot be combined with Installment.
Installment
object
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','CANCELED', 'CAPTURED' or 'PENDING'
Possible values: AUTHORIZED, CANCELED, CAPTURED, PENDING.
Example: AUTHORIZED
Id
mandatory, string
Unique Saferpay transaction id. Used to reference the transaction in any further step.
Example: K5OYS9Ad6Ex4rASU1IM1b3CEU8bb
CaptureId
string
Unique Saferpay capture id.
Available if the transaction was already captured (Status: CAPTURED).
Must be stored for later reference (eg refund).
Id[1..64]
Example: ECthWpbv1SI6SAIdU2p6AIC1bppA
Date
mandatory, date
Date / time of the authorization
Example: 2011-09-23T14:57:23.023+02.00
Amount
mandatory, object
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: 109510
DirectDebit
object
Direct Debit information, if applicable
Example: AcquirerReference
Invoice
object
Invoice information, if applicable
IssuerReference
object
Issuer reference information, if applicable

Container "Payment_Models_Data_PayPalInfo"

PayerId
mandatory, string
PayerId from PayPal
Example: 5b9aefc5-9b48-4a95-ae47-cda20420d68e
SellerProtectionStatus
mandatory, string
Seller protection status from PayPal.
Possible values: ELIGIBLE, PARTIALLY_ELIGIBLE, NOT_ELIGIBLE.
Example: ELIGIBLE
Email
mandatory, string
The email address used in PayPal

Container "Payment_Models_Data_PendingNotification"

MerchantEmails
array of strings
Email addresses to which a confirmation email will be sent when the transaction is completed.
A maximum of 10 email addresses is allowed.
Example: ["merchant1@saferpay.com", "merchant2@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 or REFUND_PENDING). Up until now, this is only applicable for Paydirekt transactions or WL Crypto Payments refunds.
Example: https://merchanthost/pendingnotify

Container "Payment_Models_Data_Phone"

Main
string
The payer's main phone number
Utf8[1..100]
Example: +41 12 345 6789
Mobile
string
The payer's mobile number
Utf8[1..100]
Example: +41 79 345 6789
Work
string
The payer's work phone number
Utf8[1..100]
Example: +41 12 345 6789

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
If 'true', the given URL must either be used as the target of a form (POST) containing card data entered by the card holder or to redirect the browser to (GET). If ‘false’, a GET redirect without additional data must be performed.

Container "Payment_Models_Data_RedirectNotifyUrls"

Success
mandatory, string
Notification url called when the payer has completed the redirect steps successfully and the transaction is ready to be authorized.
Max length: 2000
Example: https://merchanthost/success/123
Fail
mandatory, string
Notification url called when the payer redirect steps have failed. The transaction cannot be authorized.
Max length: 2000
Example: https://merchanthost/fail/123

Container "Payment_Models_Data_Refund"

Amount
mandatory, object
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
RestrictRefundAmountToCapturedAmount
boolean
If set to true, the refund will be rejected if the sum of refunds exceeds the captured amount.
All authorized refunds are included in the calculation even if the have not been captured yet. Cancelled refunds are not included.
By default this check is disabled.

Container "Payment_Models_Data_RefundDirect"

Amount
mandatory, object
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_RefundDirectSupportingPaymentMeans"

SaferpayFields
object
Payment means data collected with SaferpayFields.
Card
object
Card data
Alias
object
Alias data if payment means was registered with Secure Card Data before.
SchemeToken
object
Surrogate values that replace the primary account number (PAN) according to the EMV Payment Tokenization Specification.
Note: LiabilityShift is only possible with Transaction Initialize, AuthorizeDirect and RefundDirect.

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','CANCELED', 'CAPTURED' or 'PENDING'
Possible values: AUTHORIZED, CANCELED, CAPTURED, PENDING.
Example: AUTHORIZED
Id
mandatory, string
Unique Saferpay transaction id. Used to reference the transaction in any further step.
Example: K5OYS9Ad6Ex4rASU1IM1b3CEU8bb
CaptureId
string
Unique Saferpay capture id.
Available if the transaction was already captured (Status: CAPTURED).
Must be stored for later reference (eg refund).
Id[1..64]
Example: ECthWpbv1SI6SAIdU2p6AIC1bppA
Date
mandatory, date
Date / time of the authorization
Example: 2011-09-23T14:57:23.023+02.00
Amount
mandatory, object
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: 109510
DirectDebit
object
Direct Debit information, if applicable
Example: AcquirerReference
Invoice
object
Invoice information, if applicable
IssuerReference
object
Issuer reference 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 default lifetime (1096 days) 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
object
If Success is 'true', information about the alias
Error
object
If Success is 'false', information on why the registration failed
AuthenticationResult
object
contains information whether the alias is saved with the strong authentication details or not.

Container "Payment_Models_Data_ReturnUrl"

Url
mandatory, string
Return url for successful, failed or aborted transaction
Max length: 2000
Example: https://merchanthost/return

Container "Payment_Models_Data_RiskFactors"

DeliveryType
string
Delivery method
Possible values: EMAIL, SHOP, HOMEDELIVERY, PICKUP, HQ.
PayerProfile
object
Information on the payer executing the transaction, generally referring to his/her customer profile in the shop (if any).
IsB2B
boolean
Is the transaction B2B?
DeviceFingerprintTransactionId
string
The customer's Session ID (mastered by DFP Device Fingerprinting), or the event ID if the session is not available
Max length: 1024

Container "Payment_Models_Data_SaferpayFields"

Token
mandatory, string
Saferpay Fields token

Container "Payment_Models_Data_SchemeToken"

Number
mandatory, string
Token number
ExpMonth
mandatory, integer
Expiry Month of the token.
Range: inclusive between 1 and 12
Example: 10
ExpYear
mandatory, integer
Expiry Year of the token.
Example: 2023
AuthValue
mandatory, string
TAVV Cryptogram
Eci
string
Saferpay E-Commerce Indicator. This indicator is just informational.
Example: 07
TokenType
mandatory, string
Type of the Scheme Token.
Possible values: APPLEPAY, GOOGLEPAY, SAMSUNGPAY, CLICKTOPAY, OTHER.

Container "Payment_Models_Data_StrongCustomerAuthenticationDirect"

Exemption
string
Type of Exemption
Possible values: LOW_VALUE, TRANSACTION_RISK_ANALYSIS, RECURRING.
IssuerReference
object
Contains data that is received from the issuer in the response of a successful payment by other payment providers and will be forwarded to scheme for only this payment.

Container "Payment_Models_Data_StrongCustomerAuthenticationInteractive"

Exemption
string
Type of Exemption
Possible values: LOW_VALUE, TRANSACTION_RISK_ANALYSIS.
ThreeDsChallenge
string
3DS Secure challenge options
Possible values: FORCE.

Container "Payment_Models_Data_StrongCustomerAuthenticationReferenced"

Exemption
string
Type of Exemption
Possible values: RECURRING.

Container "Payment_Models_Data_ThreeDsInfo"

Authenticated
mandatory, boolean
Indicates, whether the payer has successfuly authenticated him/herself or not.
Xid
mandatory, string
Transaction Id, given by the MPI. References the 3D Secure process.
Example: ARkvCgk5Y1t/BDFFXkUPGX9DUgs= for 3D Secure version 1 / 1ef5b3db-3b97-47df-8272-320d0bd18ab5 for 3D Secure version 2
Version
string
The 3D Secure Version.
Example: 2
AuthenticationType
string
Determines how the card holder was authenticated. Some 3D Secure Versions allow a Frictionless authentication.
Possible values: STRONG_CUSTOMER_AUTHENTICATION, FRICTIONLESS, ATTEMPT, EXEMPTION, NONE.
Example: StrongCustomerAuthentication

Container "Payment_Models_Data_Transaction"

Type
mandatory, string
Type of transaction. One of 'PAYMENT', 'REFUND'
Possible values: PAYMENT, REFUND.
Example: PAYMENT
Status
mandatory, string
Current status of the transaction. One of 'AUTHORIZED','CANCELED', 'CAPTURED' or 'PENDING'
Possible values: AUTHORIZED, CANCELED, CAPTURED, PENDING.
Example: AUTHORIZED
Id
mandatory, string
Unique Saferpay transaction id. Used to reference the transaction in any further step.
Example: K5OYS9Ad6Ex4rASU1IM1b3CEU8bb
CaptureId
string
Unique Saferpay capture id.
Available if the transaction was already captured (Status: CAPTURED).
Must be stored for later reference (eg refund).
Id[1..64]
Example: ECthWpbv1SI6SAIdU2p6AIC1bppA
Date
mandatory, date
Date / time of the authorization
Example: 2011-09-23T14:57:23.023+02.00
Amount
mandatory, object
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: 109510
DirectDebit
object
Direct Debit information, if applicable
Example: AcquirerReference
Invoice
object
Invoice information, if applicable
IssuerReference
object
Issuer reference information, if applicable

Container "Payment_Models_Data_TransactionNotification"

PayerDccReceiptEmail
string
Email address to which a confirmation email will be sent to the payer after successful authorizations processed with DCC.
Example: payer@saferpay.com

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

Id
mandatory, string
The id of the alias that should be updated.. 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 default lifetime (1096 days) will be used.
Range: inclusive between 1 and 1600
Example: 1000

Container "Payment_Models_Data_UpdateCreditCard"

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

Container "Payment_Models_Data_UpdatePaymentMeans"

Card
mandatory, object
Card data

Container "Payment_Models_FraudPrevention"

Result
string
The result of the performed fraud prevention check
Possible values: APPROVED, CHALLENGED.
Example: APPROVED

Container "Payment_Models_PaymentMethodsOptions"

Ideal
object
Optional. Options which only apply to IDEAL.
Klarna
object
Optional. Options which only apply to Klarna.

Container "Payment_Models_RefundPaymentMethodsOptions"

A2A
object
Optional. Options which only apply to account to account

Container "Payment_Models_RiskDetails"

BlockReason
string
Indicates the blocking reason of the transaction.
Possible values: BLACKLIST_IP, BLACKLIST_IP_ORIGIN, BLACKLIST_PAYMENT_MEANS, BLACKLIST_PAYMENT_MEANS_ORIGIN.
Example: BLACKLIST_IP_ORIGIN
IpLocation
string
Is the location of the payer and it can be either the two letter country-code (such as CH, DE, etc.)
or the special cases. The special cases are: PROXY and SATELLITE_PROVIDER.
Example: CH

Container "RestApi_Models_Data_Order"

Items
mandatory, array of objects
Order items

Container "RestApi_Models_Data_OrderItem"

Type
string
Order item type
Possible values: DIGITAL, PHYSICAL, SERVICE, GIFTCARD, DISCOUNT, SHIPPINGFEE, SALESTAX, SURCHARGE.
Id
string
Product id
Utf8[1..100]
Example: C123192
VariantId
string
Product variant id
Utf8[1..100]
Example: C123192-red
Name
string
Product name
Utf8[1..200]
Example: red swiss army knife
CategoryName
string
Category name
Utf8[1..100]
Example: knives
Description
string
Product description
Utf8[1..200]
Example: The well known swiss army knife
Quantity
integer
The quantity of the order item
Example: 3
UnitPrice
string
Price per single item in minor unit (CHF 2.00 ⇒ Value=200). Only Integer values will be accepted!
Example: 200
IsPreOrder
boolean
Flag, which indicates that the order item is a pre order. Per default, it is not a pre order.
Example: true
TaxRate
string
Tax rate of the item price in hundredth of a percent. e.g. value 125 means 1.25%
Valid values are 0-99999
Range: inclusive between 0 and 99999
Example: 2100
TaxAmount
string
Tax amount which is included in the item price
Example: 42
DiscountAmount
string
Discount amount including tax
Example: 10
ProductUrl
string
URL to the product page
Max length: 2000
Example: https://merchanthost/product/1
ImageUrl
string
URL to an image showing the product
Max length: 2000
Example: https://merchanthost/product/1/image

Container "RestApi_Models_Data_PaymentWithOptions"

Amount
mandatory, object
Amount data (currency, value, etc.)
OrderId
mandatory, 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..100]
Example: Description of payment
Options
object
Specific payment options

Container "RestApi_Models_Data_PaymentWithoutOptions"

Amount
mandatory, object
Amount data (currency, value, etc.)
OrderId
mandatory, 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..100]
Example: Description of payment

Container "RestApi_Models_Data_RegisterAlias"

IdGenerator
mandatory, string
Id generator to be used by Saferpay.
Possible values: RANDOM.
Example: RANDOM

Container "RestApi_Models_Feature"

Id
mandatory, string
Id of the feature
Example: SAFERPAY_EXAMPLE
DisplayName
mandatory, string
Display name of the feature
Example: Saferpay Example

Container "RestApi_Models_LicensePackage"

Id
mandatory, string
Id of the package
Example: SAFERPAY_EXAMPLE
DisplayName
mandatory, string
Display name of the package
Example: Saferpay Example

Container "RestApi_Models_PaymentMethodInfo"

PaymentMethod
string
Name of the payment method
Currencies
array of strings
Array of strings representing all the supported currencies for the payment method
LogoUrl
string
The logo of the payment method as url

Container "RestApi_Models_TerminalResult"

TerminalId
string
The Id of the terminal
Type
string
The type of the terminal
Possible values: ECOM, SPG, MPO.
Description
string
Description of the terminal
PaymentMethods
array of objects
Array of payment methods that are available for the terminal
Wallets
array of objects
Array of wallets that are available for the terminal

Container "RestApi_Models_WalletInfo"

WalletName
string
Name of the wallet
LogoUrl
string
The logo of the wallet as url

Changelog

Table of Contents

Version 1.39 (released 2024-03-19)

Version 1.38 (released 2024-01-23)

  • available on Sandbox: 2024-01-04
  • introduced version 1.38
  • added value 1.38 for SpecVersion
  • added 48 bits support to ColorDepth
  • removed Alipay from PaymentMethodOptions container PaymentPage/Initialize
  • added PaymentMethodsOptions to Transaction/Refund for A2A AccountHolderName
  • added WITH_SUCCESSFUL_THREE_DS_CHALLENGE value to Condition in SecurePayGate Create SingleUsePaymentLink requests
  • Token expiration increased for PaymentPage/Assert and pending transactions
  • improve case validation
  • common error message improvements

Version 1.37 (released 2023-11-14)

Version 1.36 (released 2023-09-12)

Version 1.35 (released 2023-07-18)

Version 1.34 (released 2023-05-16)

Version 1.33 (released 2023-03-21)

Version 1.32 (released 2023-01-17)

  • available on Sandbox: 2022-12-29
  • introduced version 1.32
  • added value 1.32 for SpecVersion
  • this method is now obsolete: /api/rest/customers/{customerid}/terminals/{terminalid}/payment-methods and replaced with this method: /api/rest/customers/{customerid}/terminals/{terminalid}
  • in addition, there is a new method that allows the merchant to query which terminals he has: /api/rest/customers/{customerid}/terminals
  • added values PAYCONIQ for Brand.PaymentMethod and PaymentMethods in PaymentPage/Initialize
  • container ReturnUrls (parameters Success and Fail) is replaced by container ReturnUrl (parameter Url)

Version 1.31 (released 2022-11-15)

  • available on Sandbox: 2022-11-01
  • introduced version 1.31
  • added value 1.31 for SpecVersion
  • added new function to Saferpay Management API for querying the license configuration of a customer

Version 1.30 (released 2022-09-20)

Version 1.29 (released 2022-07-19)

Version 1.28 (released 2022-05-17)

Version 1.27 (released 2022-03-15)

Version 1.26 (released 2022-01-18)

Version 1.25 (released 2021-11-16)

  • available on Sandbox: 2021-11-02
  • introduced version 1.25
  • added value 1.25 for SpecVersion
  • added value GOOGLEPAY for Wallets in PaymentPage/Initialize request to enable the preselection of Apple Pay
  • added container PayPal to PaymentPage/Assert response
  • added parameter RestrictRefundAmountToCapturedAmount to container Refund in Transaction/Refund request
  • added parameter LogoUrl to containers PaymentMethods and Wallets in Management API TerminalInfo PaymentMethods response

Version 1.24 (released 2021-09-14)

Version 1.23 (released 2021-07-13)

Version 1.22 (released 2021-05-18)

Version 1.21 (released 2021-03-23)

Version 1.20 (released 2020-11-10)

Version 1.19 (released 2020-09-15)

Version 1.18 (released 2020-07-14)

Version 1.17 (released 2020-05-12)

Version 1.16 (released 2020-03-17)

Version 1.15 (released 2020-01-21)

  • available on Sandbox: 2020-01-07
  • introduced version 1.15
  • added value 1.15 for SpecVersion
  • added container Ideal to PaymentPage/Initialize request to enable the preselection of an iDEAL issuer
  • added value APPLEPAY for Wallets in PaymentPage/Initialize request to enable the preselection of Apple Pay

Version 1.14 (released 2019-11-19)

Version 1.13 (released 2019-09-17)

  • available on Sandbox: 2019-09-10
  • introduced version 1.13
  • added value 1.13 for SpecVersion
  • added container PaymentMethodsOptions to Transaction/AlternativePayment to allow the setting of payment method specific options. Currently used for Bancontact specific settings
  • added new country code value XK (Kosovo) to field CountryCode
  • added new value DIVERSE in field Gender
  • added new error code PAYMENTMEANS_NOT_SUPPORTED with corresponding error message "Unsupported means of payment (e.g. non SEPA IBAN)"

Version 1.12 (released 2019-07-16)

  • available on Sandbox: 2019-07-02
  • introduced version 1.12
  • added value 1.12 for SpecVersion
  • added method Alias/Update for updating the details of an alias
  • added methods Transaction/AlternativePayment and Transaction/QueryAlternativePayment which enable the implementation of customized checkout processes (i.e. in mobile shopping apps) - at the moment only available for Bancontact
  • replaced MerchantEmail with MerchantEmails that can be filled with up to 10 email addresses to which the payment notification is sent

Version 1.11 (released 2019-05-21)

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