NAV Navbar

Introduction

This page describes the CashSentinel application programming interface (API) implemented via SaferPay JSON API.

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

  1. Payment Page Initialize
    • Initialize the payment and generate RedirectUrl for the Payment Page.
  2. Redirect to RedirectUrl.
  3. Return to ReturnUrl depending on the outcome of the transaction. ReturnUrls are defined in step 1!
  4. 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!
  5. Depending on the outcome of step 4 you may
  6. 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]
Item string false Information about the item sold
Id[1..1000]
Quantity string false Information about the item quantity
Id[1..45]
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

  1. Transaction Initialize
    • Initialize the Payment and generate the RedirectUrl for the iFrame Integration.
  2. Open the RedirectUrl inside an HTML-iFrame to show the hosted card entry form!
  3. Return to the ReturnUrl depending on the outcome of the 3D Secure procedure. The ReturnUrls are defined in step 1!
  4. 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!
  5. Depending on the outcome of step 4 you may
  6. 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]
Item string false Information about the item sold
Id[1..1000]
Quantity string false Information about the item quantity
Id[1..45]
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

Find more details about the data structure here.

Transaction Refund

POST /api/payment/refund

Arguments

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

  1. Registration check
    • Check if merchant is already registered with CashSentinel.
  2. Depending on the outcome of step 1 you may
  3. 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": "john.smith@mail.com"
}
Parameter Type Mandatory Description
phone string yes Merchant phone number including country code
Example +4176123456
String[8..25]
email string no Merchant email
Example john.smith@mail.com
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": "john.smith@mail.com",
        "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
email string yes Merchant email
Example john.smith@mail.com
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": "john.smith@mail.com",
    "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]
email string yes Merchant email
Example john.smith@mail.com
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": "john.smith@mail.com",
        "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
email string yes Merchant email
Example john.smith@mail.com
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.