Saferpay json api v1.2
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 Api version 1.2.
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
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 two mechanisms basic authentication and client certificate 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]
Client certificate authentication
Authentication by client certificate must be enabled by SIX before being available. If you intend on using this kind of authentication, please make sure you have sufficient knowledge to manage client certificates.
The following points are important to consider:
- Client certificates have a limited validity (2 years) and must be renewed before this validity expires. Saferpay will not accept any requests which are being sent with an expired client certificate.
- Client certificates should be kept in a safe place, just like basic authentication credentials.
These steps must be followed in order to create a client certificate for accessing the Saferpay api:
- Create a PKCS#10 certificate request with your company's name as organization, Saferpay Api as organizational unit, you customer id as common name, and use RSA key length of 2048 bits
- Submit the certificate signing request to Saferpay by uploading in the Saferpay Backoffice.
- Download the signed certificate from the Saferpay Backoffice.
- Depending on the technology you’re using, load the certificate including the private key into the corresponding certificate store for use by your application.
- Have your application send the client certificate with every call to the Saferpay Api (only server-to-server calls). The Saferpay Api will not specifically require a client certificate to be present, so you need to force it being sent with the initial request.
PKCS#10 CSR:
Organization (O) | [your company name] (no brackets) |
Organizational Unit (OU) | Saferpay Api |
Common Name (CN) | [Saferpay CustomerId] (no brackets) |
RSA Key length | 2048 bits |
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.2", "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 | |
RETRY_LATER | |
OTHER_MEANS |
List of error names (these names will not change, so you may parse these and attach your logic to the ErrorName):
AUTHENTICATION_FAILED |
Wrong password, wrong client certificate, invalid token, wrong HMAC. Solution: Use proper credentials, fix HMAC calculation, use valid token |
ALIAS_INVALID |
The alias is not known or already used (in case of registration). Solution: Use another alias for registration |
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 |
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 |
PAYMENTMEANS_INVALID | Invalid means of payment (e.g. invalid card) |
INTERNAL_ERROR |
Internal error in Saferpay Solution: Try again |
3DS_AUTHENTICATION_FAILED |
3D-secure authentication failed – the transaction must be aborted. Solution: Use another card or means of payment |
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 |
PERMISSION_DENIED | No permission (e.g. terminal does not belong to the customer) |
TRANSACTION_DECLINED |
Declined by the processor. Solution: Use another card or check details. |
VALIDATION_FAILED |
Validation failed. Solution: Fix request |
AMOUNT_INVALID | The amount does not adhere to the restrictions for this action. E.g. it might be exceeding the allowed capture amount. |
CURRENCY_INVALID | Currency does not match referenced transaction currency. |
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. |
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_IN_WRONG_STATE | |
ACTION_NOT_SUPPORTED | |
TRANSACTION_NOT_FOUND | |
CONDITION_NOT_SATISFIED | The condition which was defined in the request could not be satisfied. |
TRANSACTION_NOT_STARTED |
The transaction was not started by the payer. Therefore, no final result for the transaction is available. Solution: Try again later. |
TRANSACTION_ABORTED | The transaction was aborted by the payer. |
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:
- Initialize via secure server-to-server call
- Integrate Iframe to redirect your customer
- 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.
Server-to-server communication:
private object SubmitRequest(string sfpUrl, object request, string sfpLogin, string sfpPassword) { using (var client = new WebClient()) { 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; } } }
todo
//JSONObj is a multidimensional Array, that assembles the JSON structure //$username and $password for the http-Basic Authentication //$url is the SaferpayURL eg. https://www.saferpay.com/api/Payment/v1/Transaction/Initialize function do_post($username,$password,$url, $JSONObj){ //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")); //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($JSONObj)); //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 $json_response, curl_error " . curl_error($curl) . ", curl_errno " . curl_errno($curl) . "HTTP-Status: " . $status . "<||||> DUMP: URL: ". $url . " <|||> JSON: " . var_dump($JSONObj)); } //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 JavaSript events from Saferpay:
$(window).bind('message', function (e) { switch (e.originalEvent.data.message) { case 'css': $('#iframe').css('height', e.originalEvent.data.height + "px"); break; } });
Interfaces
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.
|
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, DIRECTDEBIT, INVOICE, BONUS, DINERS, EPRZELEWY, EPS, GIROPAY, IDEAL, JCB, MAESTRO, MASTERCARD, MYONE, PAYPAL, 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)
|
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.2", "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.2", "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.2", "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.2", "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.
|
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)
|
Styling container |
Styling options
|
Example:
{ "RequestHeader": { "SpecVersion": "1.2", "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.2", "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.2", "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.2", "RequestId": "[your request id]" }, "Transaction": { "Type": "PURCHASE", "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 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.2", "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.2", "RequestId": "[your request id]" }, "Transaction": { "Type": "PURCHASE", "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
|
Example:
{ "RequestHeader": { "SpecVersion": "1.2", "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
Example:
{ "ResponseHeader": { "SpecVersion": "1.2", "RequestId": "[your request id]" }, "Transaction": { "Type": "PURCHASE", "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 Capture
POST /Payment/v1/Transaction/Capture
Request
Arguments | |
---|---|
RequestHeader mandatory, container |
General information about the request.
|
TransactionReference mandatory, container |
Reference to authorization.
|
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.
|
Example:
{ "RequestHeader": { "SpecVersion": "1.2", "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.2", "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.2", "CustomerId": "[your customer id]", "RequestId": "[your request id]", "RetryIndicator": 0 }, "Refund": { "Amount": { "Value": "100", "CurrencyCode": "CHF" } }, "TransactionReference": { "TransactionId": "723n4MAjMdhjSAhAKEUdA8jtl9jb" } }
Response
Example:
{ "ResponseHeader": { "SpecVersion": "1.2", "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.0", "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": "1.2", "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
Example:
{ "RequestHeader": { "SpecVersion": "1.2", "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.2", "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)
|
Styling container |
Custom styling resource
|
Notification container |
Notification options
|
Example:
{ "RequestHeader": { "SpecVersion": "1.2", "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.2", "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
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.2", "CustomerId": "[your customer id]", "RequestId": "[unique request identifier]", "RetryIndicator": 0 }, "Token": "234uhfh78234hlasdfh8234e" }
Response
Example:
{ "ResponseHeader": { "SpecVersion": "1.2", "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 Alias Store
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.
|
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.2", "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.2", "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.2", "CustomerId": "[your customer id]", "RequestId": "[unique request identifier]", "RetryIndicator": 0 }, "Token": "234uhfh78234hlasdfh8234e" }
Response
Example:
{ "ResponseHeader": { "SpecVersion": "1.2", "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
Example:
{ "RequestHeader": { "SpecVersion": "1.2", "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": "1.2", "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
Id[1..40]
Example: alias35nfd9mkzfw0x57iwx
|
Example:
{ "RequestHeader": { "SpecVersion": "1.2", "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.2", "RequestId": "[your request id]" } }
Batch
Batch Close
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.2", "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.2", "RequestId": "[your request id]" } }