Introduction

THIS API-VERSION IS OUTDATED! You can always find the current version under http://saferpay.github.io/jsonapi!

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.

Base URL production system:

https://www.saferpay.com/api

Base URL test system:

https://test.saferpay.com/api

Test accounts:

Request your personal test account
View shared test account data

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 for authentication of a server (host) system.

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

HTTP Header:

Authorization: Basic [your base64 encoded user name + password]

Integration

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 neccessary to integrate your only 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 depening 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.

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!

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 = string.Format("{0}:{1}", 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)
        {
            Trace.WriteLine("Web exception occured");
            // handle error response here
            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;
}
//$username and $password for the http-Basic Authentication
//$url is the SaferpayURL eg. https://www.saferpay.com/api/Payment/v1/Transaction/Initialize
//$payload is a multidimensional array, that assembles the JSON structure
function do_post($username, $password, $url, array $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"
	));
	//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
	curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, true);
	curl_setopt($curl, CURLOPT_SSL_VERIFYHOST, 0);
	//HTTP-Basic Authentication for the Saferpay JSON-API
	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) {
            die("Error: call to URL $url failed with status $status, response $jsonResponse, curl_error " . curl_error($curl) . ", curl_errno " . curl_errno($curl) . "HTTP-Status: " . $status . "<||||> DUMP: URL: ". $url . " <|||> JSON: " . var_dump($payload));
	}
	//IMPORTANT!!!
	//Close connection!
	curl_close($curl);
	//Convert response into an Array
	$response = json_decode($jsonResponse, true);
	
	return $response;
}
      

If you include the redirect pages into 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:

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

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

Error Message

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

Example:

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

List of behaviors:

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

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

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

Payment Page

PaymentPage Initialize

This interface provides a simple integration of Saferpay without the need to implement a user interface for card data entry (the 'eCommerce' Saferpay license). You will get a redirect link to our payment page.

After the payment page processing was finished, the payer is redirected back to the shop. The redirect address is chosen depending on the outcome of the request (success, failure, abort). If the payer is returned to the success url provided in the InitializeRequest, an authorization or even a completed transaction will have been done. So even if you don’t call Verify or Capture, the financial flow may have been triggered (depending on the payment provider – please consult the provider specific information).

Important: the payer might modify the return address (e.g. replace failure address with success url). If the payer returns to your success url, be sure to retrieve the outcome of the transaction and more information on it by calling PaymentPage/Verify Assert for the given token.

POST /Payment/v1/PaymentPage/Initialize

Request

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

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

Example:

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

Response

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

Example:

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

PaymentPage Assert

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

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

POST /Payment/v1/PaymentPage/Assert

Request

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

Example:

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

Response

Arguments
ResponseHeader
mandatory, container
Contains general informations about the response.
Transaction
mandatory, container
Information about the transaction
PaymentMeans
mandatory, container
Information about the means of payment
Payer
container
Information about the payer / card holder
RegistrationResult
container
Information about the SCD registration outcome
ThreeDs
container
3d-secure information if applicable
Dcc
container
Dcc information, if applicable

Example:

{
  "ResponseHeader": {
    "SpecVersion": "1.3",
    "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"
  },
  "PaymentMeans": {
    "Brand": {
      "PaymentMethod": "SAFERPAYTEST",
      "Name": "Saferpay Test Card"
    },
    "DisplayText": "9123 45xx xxxx 1234",
    "Card": {
      "MaskedNumber": "912345xxxxxx1234",
      "ExpYear": 2015,
      "ExpMonth": 9,
      "HolderName": "Max Mustermann",
      "CountryCode": "CH"
    }
  }
}

Transaction

Transaction Initialize Business license

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

POST /Payment/v1/Transaction/Initialize

Request

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

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

Example:

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

Response

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

Example:

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

Transaction Authorize Business license

This function may be called to complete an authorization which was started by a call to Transaction/Initialize.

POST /Payment/v1/Transaction/Authorize

Request

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

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

Example:

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

Response

Arguments
ResponseHeader
mandatory, container
Contains general informations about the response.
Transaction
mandatory, container
Information about the transaction
PaymentMeans
mandatory, container
Information about the means of payment
Payer
container
Information about the payer / card holder
RegistrationResult
container
Information about the Secure Card Data registration outcome.
ThreeDs
container
3d-secure information if applicable
Dcc
container
Dcc information, if applicable

Example:

{
  "ResponseHeader": {
    "SpecVersion": "1.3",
    "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"
  },
  "PaymentMeans": {
    "Brand": {
      "PaymentMethod": "SAFERPAYTEST",
      "Name": "SaferpayTestCard"
    },
    "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"
  },
  "ThreeDs": {
    "Authenticated": true,
    "LiabilityShift": true,
    "Xid": "ARkvCgk5Y1t/BDFFXkUPGX9DUgs=",
    "VerificationValue": "AAABBIIFmAAAAAAAAAAAAAAAAAA="
  }
}

Transaction QueryPaymentMeans Business license

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

POST /Payment/v1/Transaction/QueryPaymentMeans

Request

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

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

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

Example:

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

Response

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

Example:

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

Transaction AdjustAmount Business license

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

POST /Payment/v1/Transaction/AdjustAmount

Request

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

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

Example:

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

Response

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

Example:

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

Transaction AuthorizeDirect Business license

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

POST /Payment/v1/Transaction/AuthorizeDirect

Request

Arguments
RequestHeader
mandatory, container
General information about the request.
TerminalId
mandatory, string
Saferpay Terminal-Id
Numeric[8..8]
Example: 12341234
Payment
mandatory, container
Information about the payment (amount, currency, ...)
PaymentMeans
mandatory, container
Information on the means of payment
RegisterAlias
container
Controls whether the given means of payment should be stored inside the saferpay Secure Card Data storage.
Payer
container
Information on the payer (IP-address)

Example:

{
  "RequestHeader": {
    "SpecVersion": "1.3",
    "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",
      "VerifivationCode": "123"
    }
  }
}

Response

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

Example:

{
  "ResponseHeader": {
    "SpecVersion": "1.3",
    "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"
  },
  "PaymentMeans": {
    "Brand": {
      "PaymentMethod": "SAFERPAYTEST",
      "Name": "SaferpayTestCard"
    },
    "DisplayText": "9123 45xx xxxx 1234",
    "Card": {
      "MaskedNumber": "912345xxxxxx1234",
      "ExpYear": 2015,
      "ExpMonth": 7,
      "HolderName": "Max Mustermann",
      "CountryCode": "CH"
    }
  },
  "Payer": {
    "IpAddress": "1.2.3.4",
    "IpLocation": "DE"
  }
}

Transaction AuthorizeReferenced Business license

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

POST /Payment/v1/Transaction/AuthorizeReferenced

Request

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

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

Example:

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

Response

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

Example:

{
  "ResponseHeader": {
    "SpecVersion": "1.3",
    "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"
  },
  "PaymentMeans": {
    "Brand": {
      "PaymentMethod": "SAFERPAYTEST",
      "Name": "SaferpayTestCard"
    },
    "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

POST /Payment/v1/Transaction/Capture

Request

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

Exactly one element must be set.
Amount
container
Currency must match the original transaction currency (request will be declined if currency does not match)
Billpay
container
Optional Billpay specific options.
Partial
container
Optional partial capture options.
Note: Partial-Captures are only available with PayPal!

Example:

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

Response

Arguments
ResponseHeader
mandatory, container
Contains general informations about the response.
TransactionId
mandatory, string
Id of the referenced transaction.
AlphaNumeric[1..64]
Example: 723n4MAjMdhjSAhAKEUdA8jtl9jb
OrderId
string
OrderId of the referenced transaction. If present.
Id[1..80]
Example: c52ad18472354511ab2c33b59e796901
Date
mandatory, date
Date and time of capture.
AlphaNumeric[11..11]
Example: 2014-04-25T08:33:44.159Z
Invoice
container
Optional infos for invoice based payments.

Example:

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

Transaction Refund Business license

This method may be called to refund a previous transaction.

POST /Payment/v1/Transaction/Refund

Request

Arguments
RequestHeader
mandatory, container
General information about the request.
Refund
mandatory, container
Information about the refund (amount, currency, ...)
TransactionReference
mandatory, container
Reference to the transaction you want to refund. Note, that not all processors support refunds.

Example:

{
  "RequestHeader": {
    "SpecVersion": "1.3",
    "CustomerId": "[your customer id]",
    "RequestId": "[your request id]",
    "RetryIndicator": 0
  },
  "Refund": {
    "Amount": {
      "Value": "100",
      "CurrencyCode": "CHF"
    }
  },
  "TransactionReference": {
    "TransactionId": "723n4MAjMdhjSAhAKEUdA8jtl9jb"
  }
}

Response

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

Example:

{
  "ResponseHeader": {
    "SpecVersion": "1.3",
    "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"
  },
  "PaymentMeans": {
    "Brand": {
      "PaymentMethod": "SAFERPAYTEST",
      "Name": "Saferpay Test Card"
    },
    "DisplayText": "9123 45xx xxxx 1234",
    "Card": {
      "MaskedNumber": "912345xxxxxx1234",
      "ExpYear": 2015,
      "ExpMonth": 9,
      "HolderName": "Max Mustermann",
      "CountryCode": "CH"
    }
  }
}

Transaction RefundDirect Business license

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

POST /Payment/v1/Transaction/RefundDirect

Request

Arguments
RequestHeader
mandatory, container
General information about the request.
TerminalId
mandatory, string
Saferpay Terminal-Id
Numeric[8..8]
Example: 12341234
Refund
mandatory, container
Information about the refund (amount, currency, ...)
PaymentMeans
mandatory, container
Information on the means of payment

Example:

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

Response

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

Example:

{
  "ResponseHeader": {
    "SpecVersion": "1.3",
    "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"
  },
  "PaymentMeans": {
    "Brand": {
      "PaymentMethod": "SAFERPAYTEST",
      "Name": "Saferpay Test Card"
    },
    "DisplayText": "9123 45xx xxxx 1234",
    "Card": {
      "MaskedNumber": "912345xxxxxx1234",
      "ExpYear": 2015,
      "ExpMonth": 9,
      "HolderName": "Max Mustermann",
      "CountryCode": "CH"
    }
  }
}

Transaction Cancel

POST /Payment/v1/Transaction/Cancel

Request

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

Exactly one element must be set.

Example:

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

Response

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

Example:

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

Transaction RedirectPayment Business license

POST /Payment/v1/Transaction/RedirectPayment

Request

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

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

Example:

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

Response

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

Example:

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

Transaction AssertRedirectPayment Business license

Caution: Please DO NOT use the Assert-Request for polling. You should alweays await the reception of the Success-url and/or NotifyUrl.

POST /Payment/v1/Transaction/AssertRedirectPayment

Request

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

Example:

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

Response

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

Example:

{
  "ResponseHeader": {
    "SpecVersion": "1.3",
    "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"
  },
  "PaymentMeans": {
    "Brand": {
      "PaymentMethod": "SAFERPAYTEST",
      "Name": "Saferpay Test Card"
    },
    "DisplayText": "9123 45xx xxxx 1234",
    "Card": {
      "Number": "912345678901234",
      "MaskedNumber": "912345xxxxxx1234",
      "ExpYear": 2015,
      "ExpMonth": 9,
      "HolderName": "Max Mustermann",
      "CountryCode": "CH"
    }
  }
}

Secure Card Data

Alias Insert

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

POST /Payment/v1/Alias/Insert

Request

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

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

Code-List:
de - German
en - English
fr - French
da - Danish
cs - Czech
es - Spanish
hr - Croatian
it - Italian
hu - Hungarian
nl - Dutch
no - Norwegian
pl - Polish
pt - Portuguese
ru - Russian
ro - Romanian
sk - Slovak
sl - Slovenian
fi - Finnish
sv - Swedish
tr - Turkish
el - Greek
ja - Japanese
zh - Chinese
Example: de
Check
container
Parameters for checking the means of payment before registering.

Example:

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

Response

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

Example:

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

Alias AssertInsert

POST /Payment/v1/Alias/AssertInsert

Request

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

Example:

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

Response

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

Example:

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

Alias InsertDirect

POST /Payment/v1/Alias/InsertDirect

Request

Arguments
RequestHeader
mandatory, container
General information about the request.
RegisterAlias
mandatory, container
Registration parameters
PaymentMeans
mandatory, container
Means of payment to register

Example:

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

Response

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

Example:

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

Alias Delete

POST /Payment/v1/Alias/Delete

Request

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

Example:

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

Response

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

Example:

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

Batch

Batch Close

No documentation available

POST /Payment/v1/Batch/Close

Request

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

Example:

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

Response

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

Example:

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

Container Dictionary

Container "Common_RequestHeader"

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

Container "Common_ResponseHeader"

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

Container "Payment_Models_BankAccountInfo"

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

Container "Payment_Models_Data_Address"

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

Container "Payment_Models_Data_AddressForm"

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

Container "Payment_Models_Data_Alias"

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

Container "Payment_Models_Data_AliasInfo"

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

Container "Payment_Models_Data_AliasInsertCheck"

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

Container "Payment_Models_Data_Amount"

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

Container "Payment_Models_Data_BankAccount"

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

Container "Payment_Models_Data_BasicPayment"

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

Container "Payment_Models_Data_BillpayCapture"

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

Container "Payment_Models_Data_Brand"

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

Container "Payment_Models_Data_CaptureTransactionReference"

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
OrderPartId
string
OrderPartId of the reference transaction if a partial capture should be referenced and the TransactionId of the partial capture is not available.
Id[1..80]
Example: kh9ngajrfe6wfu3d0c

Container "Payment_Models_Data_Card"

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

Container "Payment_Models_Data_CardForm"

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

Container "Payment_Models_Data_CardInfo"

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

Container "Payment_Models_Data_ClientInfo"

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

Container "Payment_Models_Data_DccInfo"

PayerAmount
mandatory, container
Amount in payer’s currency

Container "Payment_Models_Data_DirectDebitInfo"

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

Container "Payment_Models_Data_InstallmentOptions"

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

Container "Payment_Models_Data_InvoiceInfo"

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

Container "Payment_Models_Data_Notification"

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

Container "Payment_Models_Data_PartialCapture"

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

Container "Payment_Models_Data_Payer"

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

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

Container "Payment_Models_Data_PayerInfo"

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

Container "Payment_Models_Data_Payment"

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

Container "Payment_Models_Data_PaymentMeans"

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

Container "Payment_Models_Data_PaymentMeansInfo"

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

Container "Payment_Models_Data_PaymentOptions"

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

Container "Payment_Models_Data_PaymentPagePayment"

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

Container "Payment_Models_Data_RecurringOptions"

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

Container "Payment_Models_Data_Redirect"

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

Container "Payment_Models_Data_Refund"

Amount
mandatory, container
Amount data
OrderId
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_RegisterAlias"

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

Container "Payment_Models_Data_RegistrationErrorInfo"

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

Container "Payment_Models_Data_RegistrationResult"

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

Container "Payment_Models_Data_ReturnUrls"

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

Container "Payment_Models_Data_Styling"

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

Container "Payment_Models_Data_ThreeDsInfo"

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

Container "Payment_Models_Data_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', 'CAPTURED'
Possible values: AUTHORIZED, CAPTURED.
Example: AUTHORIZED
Id
mandatory, string
Unique Saferpay transaction id. Used to reference the transaction in any further step.
Example: K5OYS9Ad6Ex4rASU1IM1b3CEU8bb
Date
mandatory, date
Date / time of the authorization
Example: 2011-09-23T14:57:23.023+02.00
Amount
mandatory, container
Amount (currency, value, etc.) that has been authorized.
OrderId
string
OrderId given with request
Id[1..80]
Example: c52ad18472354511ab2c33b59e796901
AcquirerName
string
Name of the acquirer
Example: AcquirerName
AcquirerReference
string
Reference id of the acquirer (if available)
Example: AcquirerReference
DirectDebit
container
Direct Debit information, if applicable
Example: AcquirerReference
Invoice
container
Invoice information, if applicable

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

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