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.

Test accounts:

Request your personal test account
View shared test account data

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

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

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

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

HTTP Header:

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

Alternatively, Saferpay also supports authentication via a client certificate.

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.

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.

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!

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.

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.

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;
  }
});

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!

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

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:

Example:

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

AUTHENTICATION_FAILED - "Invalid credentials": In this case either the CustomerId, JSON API Password, JSON API User, or a combination of all three is not correct! You have to make sure, that all three things belong to the same Saferpay account!

Example:

{
  "ResponseHeader": {
    "SpecVersion": "[current Spec-Version]",
    "RequestId": "[your request id]"
  },
  "Behavior": "ABORT",
  "ErrorName": "AUTHENTICATION_FAILED",
  "ErrorMessage": "Unable to authenticate request",
  "ErrorDetail": [
    "Invalid credentials"
  ]
}

NO_CONTRACT: In this case, you are either asking for a payment method, that is not activated on your account, or the requested currency is not set up for you.

Example:

{
  "ResponseHeader": {
    "SpecVersion": "[current Spec-Version]",
    "RequestId": "[your request id]"
  },
  "Behavior": "ABORT",
  "ErrorName": "NO_CONTRACT",
  "ErrorMessage": "No contract for the combination of terminal, means of payment/service provider and currency",
  "TransactionId": "bAvfOzbpIlI5rAzG74IEA0x3j47b",
  "ProcessorResult": "",
  "ProcessorMessage": ""
}

PERMISSION_DENIED - "Invalid License": Should you get this error, you are trying to acces Saferpay Business functions, without the corresponding contract. More on that here.

Example:

{
 "ResponseHeader": {
   "SpecVersion": "[current Spec-Version]",
   "RequestId": "[your request id]"
 },
 "Behavior": "ABORT",
 "ErrorName": "PERMISSION_DENIED",
 "ErrorMessage": "Permission denied",
 "ErrorDetail": [
   "Invalid license"
 ]
}

TRANSACTION_IN_WRONG_STATE: This means, that there are steps in the transaction flow you have to execute, before the currently executed one, for example missing a redirect, or initializing and then authorizing the transaction, without providing the necessary means of payment. Please see our Integration Guide for more information about the available flows.

Example:

{
  "ResponseHeader": {
    "SpecVersion": "[current Spec-Version]",
    "RequestId": "[your request id]"
  },
  "Behavior": "ABORT",
  "ErrorName": "TRANSACTION_IN_WRONG_STATE",
  "ErrorMessage": "Invalid action"
}

List of behaviors:

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

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.

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

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

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

Request

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"
  },
  "ReturnUrls": {
    "Success": "[your shop payment success url]",
    "Fail": "[your shop payment fail url]"
  }
}

Response

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

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

Request

Example:

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

Response

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,
      "LiabilityShift": true,
      "Xid": "ARkvCgk5Y1t/BDFFXkUPGX9DUgs=",
      "VerificationValue": "AAABBIIFmAAAAAAAAAAAAAAAAAA="
    }
  }
}

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

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

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

Request

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"
  },
  "ReturnUrls": {
    "Success": "[your shop payment success url]",
    "Fail": "[your shop payment fail url]"
  },
  "Styling": {
    "CssUrl": "[your shop css url]"
  }
}

Response

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

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

Request

Example:

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

Response

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,
      "LiabilityShift": true,
      "Xid": "ARkvCgk5Y1t/BDFFXkUPGX9DUgs=",
      "VerificationValue": "AAABBIIFmAAAAAAAAAAAAAAAAAA="
    }
  }
}

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

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.

Example:

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

Response

Example:

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

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

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.

Example:

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

Response

Example:

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

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

Request

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

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

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

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

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

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

Request

Example:

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

Response

Example:

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

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

Request

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

Example:

{
  "ResponseHeader": {
    "SpecVersion": "[current Spec-Version]",
    "RequestId": "[unique request identifier]"
  },
  "CaptureId": "723n4MAjMdhjSAhAKEUdA8jtl9jb_c",
  "Status": "CAPTURED",
  "Date": "2018-08-08T13:45:22.258+02:00"
}

Request

Example:

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

Response

Example:

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

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

Request

Example:

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

Response

Example:

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

This method may be called to refund a previous transaction.

Request

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

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

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

Request

Example:

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

Response

Example:

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

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.

Request

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

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

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

Request

Example:

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

Response

Example:

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

Request

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",
  "ReturnUrls": {
    "Success": "[your shop payment success url]",
    "Fail": "[your shop payment fail url]"
  }
}

Response

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

Request

Example:

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

Response

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

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

Request

Example:

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

Response

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,
      "LiabilityShift": true,
      "Xid": "ARkvCgk5Y1t/BDFFXkUPGX9DUgs=",
      "VerificationValue": "AAABBIIFmAAAAAAAAAAAAAAAAAA="
    }
  }
}

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

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

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

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

Request

Example:

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

Response

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,
      "LiabilityShift": true,
      "Xid": "ARkvCgk5Y1t/BDFFXkUPGX9DUgs="
    }
  }
}

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

Request

Example:

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

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

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.

Request

Example:

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

Response

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

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

Request

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

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

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

Request

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

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

This method may be used to delete previously inserted aliases.

Request

Example:

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

Response

Example:

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

This chapter covers the Batch Close via API

Request

Example:

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

Response

Example:

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

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

Request

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

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

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

Request

This request allows to acquire an OmniChannel transaction.

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.

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

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

Instead of the RequestHeader container used in the JSON API, the REST 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.

HTTP Headers example:

Saferpay-ApiVersion: 1.14

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

This function may be used to create a SecurePayGateOffer

Request

Example:

{
  "Payment": {
    "Amount": {
      "Value": "404",
      "CurrencyCode": "CHF"
    },
    "OrderId": "094c2a7ce1374f7ca184591f123b154d",
    "Options": {
      "PreAuth": true
    }
  },
  "ExpirationDate": "2020-04-23",
  "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"
    }
  },
  "BillingAddressForm": {
    "Display": true
  }
}

Response

Example:

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