Introduction
This page describes the CashSentinel application programming interface (API) implemented via SaferPay JSON API. Latest supported SaferPay API version is 1.27.
Our API is designed to have predictable, resource-oriented URLs and to use HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which can be understood by off-the-shelf HTTP clients. JSON will be returned in all responses from the API, including errors.
Content Encoding
Content-Type: application/json; charset=utf-8
Accept: application/json
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.
Authentication
Authorization: Basic [your base64 encoded "username:password"]
CashSentinel supports the mechanism of basic authentication for authentication of a server (host) system. Technical users for the CashSentiel API will be provided by our technical team.
Authorization: Basic [your base64 encoded "username:password"]
Integration
public static JsonObject sendRequest(URL requestUrl, JsonObject request, String username, String password) throws IOException {
//encode credentials
String credential = username + ":" + password;
String encodedCredentials = DatatypeConverter.printBase64Binary(credential.getBytes());
//create connection
HttpURLConnection connection = (HttpURLConnection) requestUrl.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;
}
After successful registration with CashSentinel, our development team will provide you with parameters to connect to the payment gateway. Communication with the gateway will be over the HTTPS communication protocol. You have to submit a JSON request containing you processing instructions to the defined URLs. The URL and JSON structure vary depending on the action/resource you want to call. For further details check the description of resources below.
You can find an example of Java implementation of sending one request to server.
Payment process
The CashSentinel API data structure follows the SaferPay JSON API data structure; you can find more details here. In this page, we will describe only the special arguments required by CashSentinel, such as split data.
Each request to CashSentinel API will require a unique CashSentinel CustomerId which will be provided by our operation team. CashSentinel will automatically set the SaferPay JSON API version in each request header.
Payment process with the Payment page
Transaction-flow
- Payment Page Initialize
- Initialize the payment and generate RedirectUrl for the Payment Page.
- Redirect to RedirectUrl.
- Return to ReturnUrl depending on the outcome of the transaction. ReturnUrls are defined in step 1!
- Payment Page Assert
- Gather all the information about the payment, like split data, LiabilityShift through 3D Secure and more, using the Token gathered in step 1!
- At this step, split data should be sent!
- Depending on the outcome of step 4 you may
- The transaction is finished!
PaymentPage Initialize
HTTP Request
POST /api/paymentpage/initialize
Arguments
Find more details about the other payment arguments here.
PaymentPage Assert
POST /api/paymentpage/assert
Arguments
Example:
{
"RequestHeader": {
"CustomerId": "[your cashsentinel customer id]",
"RequestId": "[unique request identifier]",
"RetryIndicator": 0
},
"Token": "234uhfh78234hlasdfh8234e",
"SplitData":[
{
"Amount": 5000,
"MerchantId":"[cashsentinel customer id of merchant]",
"MarketplaceFee": 1000
},
{
"Amount": 5000,
"MerchantId":"[cashsentinel customer id of merchant]",
"MarketplaceFee": 1500
}
]
}
Find more details about the other payment arguments here.
Request data must include the SplitData argument, which will be used by CashSentinel later on to split the received funds accordingly.
Container | Parameter | Type | Mandatory | Description |
---|---|---|---|---|
SplitData | container [] | true | List of information about the payment split | |
Amount | integer | true | Amount towards merchant. Amount in minor unit (CHF 1.00 ⇒ Value=100). |
|
MerchantId | integer | true | CashSentinel customer ID of the merchant Numeric[1..8] |
|
MarketplaceFee | integer | true | Marketplace fee for a given merchant. Amount in minor unit (CHF 1.00 ⇒ Value=100). |
Payment Process with the Transaction Interface
Transaction-flow
- Transaction Initialize
- Initialize the Payment and generate the RedirectUrl for the iFrame Integration.
- Open the RedirectUrl inside an HTML-iFrame to show the hosted card entry form!
- Return to the ReturnUrl depending on the outcome of the 3D Secure procedure. The ReturnUrls are defined in step 1!
- Transaction Authorize
- Authorize the card, which has been gathered in step 2. Up until now, no transaction has been made!
- At this step, split data should be sent!
- Depending on the outcome of step 4 you may
- The transaction is finished!
Transaction Initialize
POST /api/payment/initialize
Arguments
Find more details about the data structure here.
Transaction Authorize
POST /api/payment/authorize
Arguments
Example:
{
"RequestHeader": {
"CustomerId": "[your cashsentinel customer id]",
"RequestId": "[unique request identifier]",
"RetryIndicator": 0
},
"Token": "234uhfh78234hlasdfh8234e",
"VerificationCode": "123",
"SplitData":[
{
"Amount": 5000,
"MerchantId":"[cashsentinel customer id of merchant]",
"MarketplaceFee": 1000
},
{
"Amount": 5000,
"MerchantId":"[cashsentinel customer id of merchant]",
"MarketplaceFee": 1500
}
]
}
Request data must include the SplitData argument which will be used by CashSentinel later to split the received funds accordingly.
Container | Parameter | Type | Mandatory | Description |
---|---|---|---|---|
SplitData | container [] | true | List of information about the payment split | |
Amount | integer | true | Amount towards merchant. Amount in minor unit (CHF 1.00 ⇒ Value=100). |
|
MerchantId | integer | true | CashSentinel customer ID of the merchant Numeric[1..8] |
|
MarketplaceFee | integer | true | Marketplace fee for a given merchant. Amount in minor unit (CHF 1.00 ⇒ Value=100). |
Find more details about the data structure here.
Transaction Capture
POST /api/payment/capture
Arguments
Example:
{
"RequestHeader": {
"CustomerId": "[your cashsentinel customer id]",
"RequestId": "[unique request identifier]",
"RetryIndicator": 0
},
"TransactionReference": {
"TransactionId": "723n4MAjMdhjSAhAKEUdA8jtl9jb"
},
"Amount": {
"Value": "10000",
"CurrencyCode": "CHF"
},
"SplitData":[
{
"Amount": 5000,
"MerchantId":"[cashsentinel customer id of merchant]",
"MarketplaceFee": 1000
},
{
"Amount": 5000,
"MerchantId":"[cashsentinel customer id of merchant]",
"MarketplaceFee": 1500
}
]
}
Request data must include the SplitData argument if captured amount is different than authorized amount.
In case of capturing refund transaction, captured amount must be the same as authorized.
Container | Parameter | Type | Mandatory | Description |
---|---|---|---|---|
SplitData | container [] | false if capturing authorized amount | List of information about the payment split | |
Amount | integer | true | Amount towards merchant. Amount in minor unit (CHF 1.00 ⇒ Value=100). |
|
MerchantId | integer | true | CashSentinel customer ID of the merchant Numeric[1..8] |
|
MarketplaceFee | integer | true | Marketplace fee for a given merchant. Amount in minor unit (CHF 1.00 ⇒ Value=100). |
Find more details about the data structure here.
Transaction Refund
POST /api/payment/refund
Arguments
Example:
{
"RequestHeader": {
"CustomerId": "[your cashsentinel customer id]",
"RequestId": "[unique request identifier]",
"RetryIndicator": 0
},
"Refund": {
"Amount": {
"Value": "5000",
"CurrencyCode": "CHF"
},
"SplitData": {
"Amount": 5000,
"MerchantId":"[cashsentinel customer id of merchant]",
"MarketplaceFee": 1000},
}
},
"CaptureReference": {
"CaptureId": "723n4MAjMdhjSAhAKEUdA8jtl9jb_c"
}
}
Partial refund is supported per split. Request data must include the SplitData argument which must match original transaction split. Split will be used by CashSentinel to charge all parties for refund accordingly and to prevent multiple refunds for the same split.
Container | Parameter | Type | Mandatory | Description |
---|---|---|---|---|
SplitData | container | true for partial split | List of information about the refund split | |
Amount | integer | true | Amount towards merchant. Amount in minor unit (CHF 1.00 ⇒ Value=100). |
|
MerchantId | integer | true | CashSentinel customer ID of the merchant Numeric[1..8] |
|
MarketplaceFee | integer | true | Marketplace fee for a given merchant. Amount in minor unit (CHF 1.00 ⇒ Value=100). |
Find more details about the data structure here.
Transaction Cancel
POST /api/payment/cancel
Arguments
Find more details about the data structure here.
Error handling
The CashSentinel Payment gateway follows the SaferPay error handling. You can find more details here.
Secure Card Data
Alias Insert
POST /api/alias/insert
Arguments
Find more details about the data structure here.
Alias AssertInsert
POST /api/alias/assertinsert
Arguments
Find more details about the data structure here.
Alias Update
POST /api/alias/update
Arguments
Find more details about the data structure here.
Alias Delete
POST /api/alias/delete
Arguments
Find more details about the data structure here.
Merchant onboarding
Here we explain the merchant onboarding process using CashSentinel API.
Process-flow
- Registration check
- Check if merchant is already registered with CashSentinel.
- Depending on the outcome of step 1 you may
- Process is finished!
Registration check
This method may be used to check if merchant is already registered with CashSentinel.
POST /api/registration/merchant/check
REQUEST
Example:
{
"phone": "+41712345678",
"email": "[email protected]"
}
Parameter | Type | Mandatory | Description |
---|---|---|---|
phone | string | yes | Merchant phone number including country code Example +4176123456 String[8..25] |
string | no | Merchant email Example [email protected] String[3..45] |
RESPONSE
Header
Http response | Description |
---|---|
NOT_FOUND | Merchant is not registered with CashSentinel. You may proceed with Register merchant request. |
FOUND | Merchant is registered with CashSentinel. You may proceed with Import merchant request. |
Body
Example:
{
{
"id": 123,
"phone": "+41712345678",
"status": "ACTIVE",
"gender": "M",
"firstName": "John",
"lastName": "Smith",
"companyName": "Company SA",
"email": "[email protected]",
"clientSince": "2014-02-20T23:00:00Z",
"type": "MERCHANT",
"address": "Kappelergasse 1",
"address2": "",
"postalCode": "5678",
"city": "Bern",
"country": "CH",
"language": "en"
}
}
If one or more merchants with given criteria is found, response will contain the list of matching merchant data. In case one or more merchants with given criteria is registered, the response body will contain the list of following merchant data:
Parameter | Type | Mandatory | Description |
---|---|---|---|
id | integer | yes | CashSentinel customer id |
phone | string | yes | Phone number including country code Example +4176123456 |
status | string | yes | Merchant status. Possible values: PENDING_REGISTRATION, IN_REGISTRATION_PROCESS, PENDING_VALIDATION, ACTIVE, REJECTED, CLOSED |
gender | string | yes | Merchant gender Possible values: M - male and F - female |
firstName | string | yes | Merchant first name |
lastName | string | yes | Merchant last name |
companyName | string | yes | Merchant company name |
string | yes | Merchant email Example [email protected] |
|
clientSince | string | yes | Merchant pre-registartion time ISO 8601 format Example 2007-12-24T18:21:25.123Z (UTC) |
type | string | yes | Customer type Possible values: MERCHANT, MARKETPLACE |
address | string | yes | Merchant address |
address2 | string | yes | Merchant address continued |
postalCode | string | yes | Merchant postal code |
city | string | yes | Merchant city |
country | string | yes | Merchant ISO 2-letter country code Example: CH |
language | string | yes | Merchant language Possible values: en - English, fr - French, de - German, it - Italian. String[2] |
Register merchant
This method may be used to pre-register a merchant with CashSentinel. If the merchant does not exist, it will be created and invited via email with a URL to complete registration. In this case, the merchant will be added to the marketplace merchants list and there is no need to import the merchant request. If one or more merchant with given email exists, response will contain the list of all matched registered merchants.
POST /api/registration/merchant/register
REQUEST
Example:
{
"phone": "+41712345678",
"gender": "M",
"firstName": "John",
"lastName": "Smith",
"companyName": "Company SA",
"email": "[email protected]",
"address1": "Kappelergasse 1",
"address2": "",
"postalCode": "5678",
"city": "Bern",
"country": "CH",
"language": "en",
"type":"MERCHANT"
}
Parameter | Type | Mandatory | Description |
---|---|---|---|
phone | string | yes | Merchant phone number including country code Example +4176123456 String[8..25] |
gender | string | yes | Merchant gender Possible values: M - male and F - female String[1] |
firstName | string | yes | Merchant first name String[3..45] |
lastName | string | yes | Merchant last name String[3..45] |
companyName | string | yes | Merchant company name String[3..45] |
string | yes | Merchant email Example [email protected] String[3..45] |
|
address1 | string | yes | Merchant address String[3..45] |
address2 | string | yes | Merchant address continued String[0..45] |
postalCode | string | yes | Merchant postal code String[3..10] |
city | string | yes | Merchant city String[3..45] |
country | String | yes | ISO 2-letter country code Example: CH String[2] |
language | String | yes | Merchant language Possible values: en - English, fr - French, de - German, it - Italian. String[2] |
type | string | yes | Customer type Possible values: MERCHANT, MARKETPLACE |
RESPONSE
Header
Http response | Description |
---|---|
CONFLICT | Merchant is registered with CashSentinel. You may proceed with Import merchant request. |
CREATED | Merchant is successfully registered with CashSentinel. |
Body
Example:
{
{
"id": 123,
"phone": "+41712345678",
"status": "ACTIVE",
"gender": "M",
"firstName": "John",
"lastName": "Smith",
"companyName": "Company SA",
"email": "[email protected]",
"clientSince": "2014-02-20T23:00:00Z",
"type":"MERCHANT",
"address": "Kappelergasse 1",
"address2": "",
"postalCode": "5678",
"city": "Bern",
"country": "CH",
"language": "en"
}
}
In case the request is executed successfully, the response body will contain the list of following data:
Parameter | Type | Mandatory | Description |
---|---|---|---|
id | integer | yes | CashSentinel customer id |
phone | string | yes | Phone number including country code Example +4176123456 |
status | string | yes | Merchant status. Possible values: PENDING_REGISTRATION, IN_REGISTRATION_PROCESS, PENDING_VALIDATION, ACTIVE, REJECTED, CLOSED |
gender | string | yes | Merchant gender Possible values: M - male and F - female |
firstName | string | yes | Merchant first name |
lastName | string | yes | Merchant last name |
companyName | string | yes | Merchant company name |
string | yes | Merchant email Example [email protected] |
|
clientSince | string | yes | Merchant pre-registartion time ISO 8601 format Example 2007-12-24T18:21:25.123Z (UTC) |
type | string | yes | Customer type Possible values: MERCHANT, MARKETPLACE |
address | string | yes | Merchant address |
address2 | string | yes | Merchant address continued |
postalCode | string | yes | Merchant postal code |
city | string | yes | Merchant city |
country | String | yes | Merchant ISO 2-letter country code Example: CH |
language | String | yes | Merchant language Possible values: en - English, fr - French, de - German, it - Italian. String[2] |
Import merchant
This method may be used to import a specific merchant in the marketplace's merchant list. You will have to use it only in case the merchant is already registered with CashSentinel.
PUT /api/registration/merchant/{merchantId}/add
REQUEST
merchantId
is a CashSentinel customer id received in the response of Registration check.
RESPONSE
Header
Http response | Description |
---|---|
NOT_FOUND | Merchant with a given id does not exists. |
CONFLICT | Merchant with a given id is already imported in the marketplace merchants list. |
OK | Merchant is successfully imported in the marketplace merchants list. |