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

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
   
   • Capture/Finalize the Transaction
   • Cancel/Abort the Transaction.
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.

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
   • Capture/Finalize the Transaction
   • Cancel/Abort the Transaction.
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.

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.

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.

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
   • Register merchant
   • Import merchant
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"
}

RESPONSE

Header

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:

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

RESPONSE

Header

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:

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