NAV Navbar

Introduction

This page describes the CashSentinel application programming interface (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.

Error handling

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.

RESPONSE

Body

Example:

{
    "name": "VALIDATION_FAILED",
    "behavior": "ABORT",
    "details": [
        "Invalid document type. docType possible values are: OTHER, AML, ZEFIX, PROOF_OF_ADDRESS, GREY_CARD, RIB, ID, FINANCING, TERMS"
    ]
}
Parameter Type Mandatory Description
name String yes Name of the error. These names will not change, so you may parse these and attach your logic to the name.
Possible values: VALIDATION_FAILED
behavior String yes What can be done to resolve the error?
Possible values: ABORT, RETRY
details string yes More details, if available.
The contents of this element might change without notice, so do not parse it.

Partial client onboarding

Here we explain the client onboarding process using CashSentinel API and website. CashSentinel offers full and partial onboarding process. With partial onboarding process client is pre-registered via API and registration should be completed on our website.

Partial onboarding process-flow

  1. Register client
  2. Receive a notification when client registration is completed
  3. Process is finished!

Register client

This method may be used to register a client with CashSentinel. If the client does not exist, it will be partially created on platform. Response will contain URL which should be sent to the client to complete registration process. If client with given phone exists, response will contain registered client data.

POST /api/registration/customer

REQUEST

Example:


{
    "phone": "+41712345678",
    "gender": "M",
    "firstName": "John",
    "lastName": "Smith",
    "address": "Kappelergasse 1",
    "address2": "",
    "postalCode": "5678",
    "city": "Bern",
    "country": "CH",
    "language": "en",
    "type":"PRIVATE_INDIVIDUAL"
}
Parameter Type Mandatory Description
phone string yes Client phone number including country code
Example +4176123456
String[8..25]
gender string yes Client gender
Possible values: M - male and F - female
String[1]
firstName string yes Client first name
String[3..45]
lastName string yes Client last name
String[3..45]
address string yes Client address
String[3..45]
address2 string no Client address continued
String[0..45]
postalCode string yes Client postal code
String[3..10]
city string yes Client city
String[3..45]
country String yes ISO 2-letter country code
Example: CH
String[2]
language String yes Client language
Possible values: en - English, fr - French, de - German, it - Italian.
String[2]
type string yes Client type
Possible values:
PRIVATE_INDIVIDUAL, PROFESSIONAL

RESPONSE

Header

Http response Description
CONFLICT Client is registered with CashSentinel.
CREATED Client 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":"PRIVATE",
        "address": "Kappelergasse 1",
        "address2": "",
        "postalCode": "5678",
        "city": "Bern",
        "country": "CH",
        "language": "en",
        "registrationUrl": "https://www.cashsentinel.com/en-CH/user/register?p=KzMzNjgxMjMxMjIy&t=ce492c73-f212-47ca-8c50-e1a6f542c844"
    }
}

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 Client status.
Possible values:
PENDING_VALIDATION, ACTIVE, REJECTED, CLOSED
gender string yes Client gender
Possible values: M - male and F - female
firstName string yes Client first name
lastName string yes Client last name
companyName string yes Client company name
email string yes Client email
Example john.smith@mail.com
clientSince string yes Client registartion time ISO 8601 format
Example 2007-12-24T18:21:25.123Z (UTC)
type string yes Client type
Possible values:
PRIVATE, PROFESSIONAL
address string yes Client address
address2 string yes Client address continued
postalCode string yes Client postal code
city string yes Client city
country String yes Client ISO 2-letter country code
Example: CH
language String yes Client language
Possible values: en - English, fr - French, de - German, it - Italian.
String[2]
registrationUrl String yes URL for client registration

Full client onboarding

Here we explain the client onboarding process using CashSentinel API. CashSentinel offers full and partial onboarding process. With full onboarding process client is completely registered via API and all communication should be via API.

Full onboarding process-flow

  1. Register client
  2. Depending on the outcome of step 1 you may
  3. Receive a notification when client is validated or CashSentinel requires additional documents
  4. Depending on the outcome of step 4 you may
  5. Process is finished!

Register client

This method may be used to register a client with CashSentinel. If the client does not exist, it will be created on platform. If one or more clients with given email exists, response will contain the list of all matched registered clients.

POST /api/registration/customer/register

REQUEST

Example:


{
    "phone": "+41712345678",
    "gender": "M",
    "firstName": "John",
    "lastName": "Smith",
    "companyName": "Company SA",
    "email": "john.smith@mail.com",
    "address": "Kappelergasse 1",
    "address2": "",
    "postalCode": "5678",
    "city": "Bern",
    "country": "CH",
    "language": "en",
    "type":"PRIVATE_INDIVIDUAL"
}
Parameter Type Mandatory Description
phone string yes Client phone number including country code
Example +4176123456
String[8..25]
gender string yes Client gender
Possible values: M - male and F - female
String[1]
firstName string yes Client first name
String[3..45]
lastName string yes Client last name
String[3..45]
companyName string no Client company name
String[3..45]
email string yes Client email
Example john.smith@mail.com
String[3..45]
address string yes Client address
String[3..45]
address2 string no Client address continued
String[0..45]
postalCode string yes Client postal code
String[3..10]
city string yes Client city
String[3..45]
country String yes ISO 2-letter country code
Example: CH
String[2]
language String yes Client language
Possible values: en - English, fr - French, de - German, it - Italian.
String[2]
type string yes Client type
Possible values:
PRIVATE_INDIVIDUAL, PROFESSIONAL

RESPONSE

Header

Http response Description
CONFLICT Client is registered with CashSentinel.
You may proceed with Request client details request.
CREATED Client 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":"PRIVATE",
        "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 Client status.
Possible values:
PENDING_VALIDATION, ACTIVE, REJECTED, CLOSED
gender string yes Client gender
Possible values: M - male and F - female
firstName string yes Client first name
lastName string yes Client last name
companyName string yes Client company name
email string yes Client email
Example john.smith@mail.com
clientSince string yes Client registartion time ISO 8601 format
Example 2007-12-24T18:21:25.123Z (UTC)
type string yes Client type
Possible values:
PRIVATE, PROFESSIONAL
address string yes Client address
address2 string yes Client address continued
postalCode string yes Client postal code
city string yes Client city
country String yes Client ISO 2-letter country code
Example: CH
language String yes Client language
Possible values: en - English, fr - French, de - German, it - Italian.
String[2]

Client details

This method may be used to retrieve current client status, missing documents, account balance. You will have to use it only in case the client is registered with CashSentinel. In case client is not registered or API user have no permission to retrieve specific client information, client data will not be displayed in the response.

POST /api/registration/user-status

REQUEST

Body

Example:

[123,124]

List of CashSentinel customer Id.

RESPONSE

Header

Http response Description
OK Client data retrieved.

Body

Example:

    [
        {
            "id": 123,
            "status": "ACTIVE",
            "wallets": [
                {
                    "id": 16123,
                    "balance": 100000,
                    "currency": "CHF",
                    "bank": "SWISSQUOTE"
                }
            ],
            "missingDocuments": [
                {
                    "date": "2019-03-01T17:31:44.000+0000",
                    "type": "DOC-uploadProofOfAddress",
                    "customType": ""
                },
                {
                    "date": "2019-03-01T17:31:46.000+0000",
                    "type": "DOC-uploadGreyCard",
                    "customType": ""
                }
            ]
        },
        {
            "id": 124,
            "status": "PENDING_VALIDATION",
            "wallets": [
                {
                    "id": 161234,
                    "balance": 0,
                    "currency": "CHF",
                    "bank": "SWISSQUOTE"
                }
            ],
            "missingDocuments": [
                {
                    "date": "2019-04-18T09:23:56.000+0000",
                    "type": "ID-uploadAccepted",
                    "customType": ""
                }
            ]
        }
    ]

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.
status string yes Client status.
Possible values:
PENDING_VALIDATION, ACTIVE, REJECTED, CLOSED
wallets[] structure yes Client wallets.
wallet -> id integer yes Wallet Id.
wallet -> balance integer yes Balance on specific wallet.
Amount in minor unit (CHF 1.00 ⇒ Value=100).
wallet -> currency String yes ISO 4217 3-letter currency code (CHF, USD, EUR, ...)
Example: CHF
wallet -> bank String yes Bank holding funds on escrow.
missingDocuments[] structure yes Documents CashSentinel needs for operational puprosses.
missingDocuments -> date String yes Date when document requested.
missingDocuments -> type String yes Type of document.
Possible values:
ID-uploadIdFront,
ID-uploadIdBack,
ID-uploadIdNonExpired,
ID-uploadIdReadable,
ID-uploadAccepted,
DOC-uploadProofOfAddress,
DOC-uploadGreyCard,
DOC-uploadRIB,
DOC-uploadZefix,
DOC-uploadOther
missingDocuments -> customType String no In case of DOC-uploadOther this parameter will contain description of the missing document.

Client documents

This method may be used to upload client documents such us identity document, register of commerce, proof of address, banking informations or other. You will have to use it only in case the client is registered with CashSentinel.

POST /api/upload/files

REQUEST

Http parameter Description
customerId CashSentinel customer id.
docType Document type
Possible values:
ID, ZEFIX, PROOF_OF_ADDRESS, GREY_CARD, RIB, OTHER
files Document files
Accepted document types: JPEG, JPG, PNG, PDF, DOC, DOCX

RESPONSE

Header

Http response Description
BAD_REQUEST Document type is not accepted or files are not set.
FORBIDDEN It is not allowed to submit documents for a given client.
NOT_FOUND Client with a given customerId does not exist.
INTERNAL_SERVER_ERROR Error occured.
CREATED Client documents successfully created.

Beneficial owners

This method may be used to create beneficial owners for professional clients in case company have shareholders owning more than 25 % of the company shares and it is not listed on the stock market. For each beneficial owner, CashSentinel requires identity document for private individuals and commerce register excerpt for professionals. In case beneficial owner is professional, CashSentinel requires all beneficial owners of registered company. Process is the same.

POST api/registration/{customerId}/beneficial-owner/add

REQUEST

customerId is a CashSentinel customer id for which beneficial owners should be created

Example:


    {
        "gender": "M",
        "firstName": "John",
        "lastName": "Smith",
        "companyName": "Company SA",
        "ownershipPercentage":"56.23",
        "email": "john.smith@mail.com",
        "address": "Kappelergasse 1",
        "address2": "",
        "postalCode": "5678",
        "city": "Bern",
        "country": "CH",
        "language": "en",
        "type":"RECORD_COMPANY"
    }
Parameter Type Mandatory Description
gender string yes Client gender
Possible values: M - male and F - female
String[1]
firstName string yes Client first name
String[3..45]
lastName string yes Client last name
String[3..45]
companyName string no Client company name
String[3..45]
ownershipPercentage string yes Percentage of ownership in the company
String[3..6]
email string yes Client email
Example john.smith@mail.com
String[3..45]
address string yes Client address
String[3..45]
address2 string no Client address continued
String[0..45]
postalCode string yes Client postal code
String[3..10]
city string yes Client city
String[3..45]
country String yes ISO 2-letter country code
Example: CH
String[2]
language String yes Client language
Possible values: en - English, fr - French, de - German, it - Italian.
String[2]
type string yes Client type
Possible values:
RECORD_COMPANY, RECORD_PRIVATE

RESPONSE

Header

Http response Description
FORBIDDEN It is not allowed to create beneficial owners for a given client.
NOT_FOUND Client with a given customerId does not exist.
CREATED Client is successfully registered with CashSentinel.

Body

Example:

    {
        {
            "id": 123,
            "status": "PENDING_VALIDATION",
            "gender": "M",
            "firstName": "John",
            "lastName": "Smith",
            "companyName": "Company SA",
            "email": "john.smith@mail.com",
            "clientSince": "2014-02-20T23:00:00Z",
            "type":"RECORD_COMPANY",
            "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
status string yes Client status.
Possible values:
PENDING_VALIDATION, ACTIVE, REJECTED, CLOSED
gender string yes Client gender
Possible values: M - male and F - female
firstName string yes Client first name
lastName string yes Client last name
companyName string yes Client company name
email string yes Client email
Example john.smith@mail.com
clientSince string yes Client registartion time ISO 8601 format
Example 2007-12-24T18:21:25.123Z (UTC)
type string yes Client type
Possible values:
PRIVATE, PROFESSIONAL
address string yes Client address
address2 string yes Client address continued
postalCode string yes Client postal code
city string yes Client city
country String yes Client ISO 2-letter country code
Example: CH
language String yes Client language
Possible values: en - English, fr - French, de - German, it - Italian.
String[2]

Contracts

Here we explain the contract processing using CashSentinel API.

Process-flow

  1. Create a contract
  2. Submit contract documents
  3. Submit contract for approval
  4. Receive a notification when contract is approved or rejected
  5. Depending on the outcome of step 4 you may
  6. Receive a notification when contract is funded
  7. Release the funds when vehicle is delivered
  8. Process is finished!

You can request always request contract details for specific contract or the list of contracts.

Contract creation

This method may be used to create a contract between the buyer and the seller. Once contract is created, CashSentinel will add a milestone with fees according to the total amount of contract. CashSentinel gives an option to create a contract using client id or phone number. It is possible to create contract with non registered client by providing a phone number. Additionally, client can be notified by sms to register on CashSentinel platform.

PUT api/contract/create

REQUEST

Example:


    {
        "buyer": {
             "id":123
             },
        "type": "VEHICLE",
        "subtype": "PROFESSIONAL",
        "currency": "CHF",
        "vehicleContractData":{
            "model":"Cayenne S",
            "brand":"Porsche",
            "year":"2018-03-12",
            "km":"120000",
            "power":"420",
            "licencePlateNumber":"ZH445789",
            "registrationNumber":"REGNUM",
            "description":"Desc"
        },
        "milestones": [
            {
                "recipient":{
                        "phone":"+4176123456",
                        "notify":true   
                },
                "recipientRole":"SELLER",
                "amount":8000000,
                "trigger":"VEHICLE_DELIVER",
                "name":"Payment to the seller",
                "description":"Payment to the seller"
            },
            {
                "recipient":{
                        "id":128
                },
                "recipientRole":"AGENCY",
                "amount":50000,
                "trigger":"APPROVE",
                "name":"Reservation fee",
                "description":"Reservation fee"
            },
            {
                "recipient":{
                        "id":128
                }
                "recipientRole":"AGENCY",
                "amount":80000,
                "trigger":"VEHICLE_DELIVER",
                "name":"Dealership costs",
                "description":"Dealership costs"
            }
        ]
    }
Parameter Type Mandatory Description
buyer structure yes Buyer information.
buyer -> id integer no CashSentinel buyer id.
buyer -> phone string no Buyer's phone number.
buyer -> notify boolean no Notification flag. It should be used in case phone is not registered and CashSentinel should send notification.
type string yes Contract type
Possible values: VEHICLE and BOAT
String[3..45]
subtype string yes Contract subtype
Possible values: PRIVATE and PROFESSIONAL
String[3..45]
currency string yes Contract currency ISO 4217 3-letter currency code (CHF, USD, EUR, ...)
Example: CHF String[3]
vehicleContractData structure yes in case contract type is VEHICLE Vehicle information.
vehicleContractData -> model String yes Vehicle model.
vehicleContractData -> brand String yes Vehicle brand.
vehicleContractData -> year String yes Date of the first vehicle registration.
Accepted format "yyyy-MM-dd"
vehicleContractData -> km String yes Vehicle kilometres traveled.
Accepted format numeric
vehicleContractData -> power String yes Vehicle power.
Accepted format numeric
vehicleContractData -> licencePlateNumber String yes Licence plate number of the vehicle.
vehicleContractData -> registrationNumber String yes Vehicle registration number.
vehicleContractData -> description String yes Additional information about the vehicle.
boatContractData structure yes in case contract type is BOAT Boat information.
boatContractData -> model String yes Boat model.
boatContractData -> brand String yes Boat brand.
boatContractData -> year String yes Date of the first boat registration.
Accepted format "yyyy-MM-dd"
boatContractData -> type String yes Type of boat.
Possible values: SAILING_BOAT and MOTOR_BOAT
boatContractData -> length String yes Length of boat.
Accepted format numeric with two decimals
boatContractData -> registrationNumber String yes Boat registration number.
boatContractData -> description String yes Additional information about the boat.
milestones[] structure yes Contract payment milestones.
milestone -> recipient -> id integer no CashSentinel id of milestone funds recipient.
milestone -> recipient -> phone String no Milestone funds recipient's phone number.
milestone -> recipient -> notify boolean no Notification flag. It should be used in case phone is not registered and CashSentinel should send notification.
milestone -> recipientRole String yes Role of milestone recipient.
Possible values: SELLER, AGENCY or THIRD_PARTY
String[3..45]
milestone -> amount integer yes Milestone amount.
Amount in minor unit (CHF 1.00 ⇒ Value=100)
milestone -> trigger String yes Action triggering funds transfer for a given milestone.
Possible values: APPROVE and VEHICLE_DELIVER
String[3..45]
milestone -> name String yes Milestone name
String[3..45]
milestone -> description String yes Milestone description
String[3..45]

RESPONSE

Header

Http response Description
BAD_REQUEST Contract data not valid.
FORBIDDEN It is not allowed to create contract.
CREATED Contract is successfully created with CashSentinel.

Body

Example:


    {
        "id": 12345 
        "buyer": {
                "id":123
                }
        "type": "VEHICLE",
        "subtype": "PROFESSIONAL",
        "currency": "CHF",
        "vehicleContractData":{
            "model":"Cayenne S",
            "brand":"Porsche",
            "year":"2018-03-12",
            "km":"120000",
            "power":"420",
            "licencePlateNumber":"ZH445789",
            "registrationNumber":"REGNUM",
            "description":"Desc"
        },
        "milestones": [
            {
                "id":123451,
                "recipient":{
                        "phone":"+4176123456",
                        "notified":"true"
                        },
                "recipientRole":"SELLER",
                "amount":8000000,
                "trigger":"VEHICLE_DELIVER",
                "name":"Payment to the seller",
                "description":"Payment to the seller"
            },
            {
                "id":123452,
                "recipient":{
                        "id":128
                        },
                "recipientRole":"AGENCY",
                "amount":50000,
                "trigger":"CONTRACT_APPROVED",
                "name":"Reservation fee",
                "description":"Reservation fee"
            },
            {
                "id":123453,
                "recipient":{
                        "id":128
                        },
                "recipientRole":"AGENCY",
                "amount":80000,
                "trigger":"VEHICLE_DELIVER",
                "name":"Dealership costs",
                "description":"Dealership costs"
            },
            {
                "id":123454,
                "recipient":{
                        "id":1
                        },
                "recipientRole":"CS",
                "amount":22900,
                "trigger":"CONTRACT_APPROVED",
                "name":"CashSentinel fee",
                "description":"CashSentinel fee"
            }
        ]
    }

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 contract id.
buyer structure yes Buyer information.
buyer -> id integer no CashSentinel buyer id.
buyer -> phone string no CashSentinel buyer phone. It should be used in case buyer is not registered.
buyer -> notified boolean no Notification flag. If client is notified by sms, it is set to true.
type string yes Contract type
Possible values: VEHICLE and BOAT
String[3..45]
subtype string yes Contract subtype
Possible values: PRIVATE and PROFESSIONAL
String[3..45]
currency string yes Contract currency ISO 4217 3-letter currency code (CHF, USD, EUR, ...)
Example: CHF String[3]
vehicleContractData structure yes in case contract type is VEHICLE Vehicle information.
vehicleContractData -> model String yes Vehicle model.
vehicleContractData -> brand String yes Vehicle brand.
vehicleContractData -> year String yes Date of the first vehicle registration.
Accepted format "yyyy-MM-dd"
vehicleContractData -> km String yes Vehicle kilometres traveled.
Accepted format numeric
vehicleContractData -> power String yes Vehicle power.
Accepted format numeric
vehicleContractData -> licencePlateNumber String yes Licence plate number of the vehicle.
vehicleContractData -> registrationNumber String yes Vehicle registration number.
vehicleContractData -> description String yes Additional information about the vehicle.
boatContractData structure yes in case contract type is BOAT Boat information.
boatContractData -> model String yes Boat model.
boatContractData -> brand String yes Boat brand.
boatContractData -> year String yes Date of the first boat registration.
Accepted format "yyyy-MM-dd"
boatContractData -> type String yes Type of boat.
Possible values: SAILING_BOAT and MOTOR_BOAT
boatContractData -> length String yes Length of boat.
Accepted format numeric with two decimals
boatContractData -> registrationNumber String yes Boat registration number.
boatContractData -> description String yes Additional information about the boat.
milestones[] structure yes Contract payment milestones.
milestone -> id integer yes Milestone id.
milestone -> recipient -> id integer no CashSentinel id of milestone funds recipient.
milestone -> recipient -> phone String no Milestone funds recipient's phone number.
milestone -> recipient -> notified boolean no Notification flag. If client is notified by sms, it is set to true.
milestone -> recipientRole String yes Role of milestone recipient.
Possible values: SELLER, AGENCY or THIRD_PARTY
String[3..45]
milestone -> amount integer yes Milestone amount.
Amount in minor unit (CHF 1.00 ⇒ Value=100)
milestone -> trigger String yes Action triggering funds transfer for a given milestone.
Possible values: APPROVE and VEHICLE_DELIVER
String[3..45]
milestone -> name String yes Milestone name
String[3..45]
milestone -> description String yes Milestone description
String[3..45]

Contract documents

This method may be used to submit contract documents.

POST /api/upload/contract/files

REQUEST

Http parameter Description
contractId CashSentinel contract id
docType Document type
Possible values:
GREY_CARD, OTHER
private If file should be shared with all counterparts it should be set to false, otherwise it should be set too true.
files Document files
Accepted document types: JPEG, JPG, PNG, PDF, DOC, DOCX

RESPONSE

Header

Http response Description
BAD_REQUEST Document type is not accepted or files are not set.
FORBIDDEN It is not allowed to submit documents for a given contract.
NOT_FOUND Contract with a given contractId does not exist.
CREATED Contract documents successfully created.

Body

Example:


    {
        "id": 15068,
        "docType": "OTHER",
        "files": [
            {
                 "fid": "34679",
                 "name": "DOC_728333_20190621_144010_0.png",
                 "size": 53582
             }
         ]
     }

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 document id.
docType String yes Document type
Possible values:
GREY_CARD, OTHER
files[] array yes Document files
files -> fid String yes CashSentinel file id.
files -> name String yes File name
files -> size int yes File size

Submit contract for approval

This method may be used to submit contract to the buyer for approval.

GET api/contract/{contractId}/submit

REQUEST

contractId is a CashSentinel contract id

RESPONSE

Header

Http response Description
FORBIDDEN It is not allowed to submit given contract.
NOT_FOUND Contract with a given id does not exist.
NOT_ACCEPTABLE Submit action is not acceptable at this point.
OK Contract is successfully sent for approval.

Contract modification

This method may be used to modify existing contract. Contract may be modified only before vehicle delivery step. Once contract is modified, in needs to be sent for approval and approved by the client. In case milestone amount is changed, CashSentinel fee will be recalculated and updated.

Milestone modification

It is possible to add new milestone by adding additional milestone structure without milestoneId parameter. If existing milestone is not sent in the structure, it will be considered as deleted and it will be removed from the contract. It is not possible to remove or modify CashSentinel milestone.

POST api/contract/modify

REQUEST


    {
        "id": 12345 
        "buyer": {
                "id":123
                }
        "type": "VEHICLE",
        "subtype": "PROFESSIONAL",
        "currency": "CHF",
        "vehicleContractData":{
                "model":"Cayenne S",
                "brand":"Porsche",
                "year":"2018-03-12",
                "km":"120000",
                "power":"420",
                "licencePlateNumber":"ZH445789",
                "registrationNumber":"REGNUM",
                "description":"Desc"
        },
        "milestones": [
            {
                "id":123451,
                "recipient":{
                        "id":124
                        },
                "recipientRole":"SELLER",
                "amount":6000000,
                "trigger":"VEHICLE_DELIVER",
                "name":"Payment to the seller",
                "description":"Payment to the seller"
            },
            {
                "id":123452,
                "recipient":{
                        "id":128
                    },
                "recipientRole":"AGENCY",
                "amount":50000,
                "trigger":"APPROVE",
                "name":"Reservation fee",
                "description":"Reservation fee"
            },
            {
                "recipient":{
                        "id":129
                        },
                "recipientRole":"THIRD_PARTY",
                "amount":200000,
                "trigger":"VEHICLE_DELIVER",
                "name":"Financing payout",
                "description":"Financing payout"
            },
            {
                "id":123453,
                "recipient":{
                        "id":128
                        }
                "recipientRole":"AGENCY",
                "amount":80000,
                "trigger":"VEHICLE_DELIVER",
                "name":"Dealership costs",
                "description":"Dealership costs"
            }
        ]
    }
Parameter Type Mandatory Description
id integer yes CashSentinel contract id.
buyer structure yes Buyer information.
buyer -> id integer no CashSentinel buyer id.
buyer -> phone string no CashSentinel buyer phone. It should be used in case buyer is not registered.
type string yes Contract type
Possible values: VEHICLE and BOAT
String[3..45]
subtype string yes Contract subtype
Possible values: PRIVATE and PROFESSIONAL
String[3..45]
currency string yes Contract currency ISO 4217 3-letter currency code (CHF, USD, EUR, ...)
Example: CHF String[3]
vehicleContractData structure yes in case contract type is VEHICLE Vehicle information.
vehicleContractData -> model String yes Vehicle model.
vehicleContractData -> brand String yes Vehicle brand.
vehicleContractData -> year String yes Date of the first vehicle registration.
Accepted format "yyyy-MM-dd"
vehicleContractData -> km String yes Vehicle kilometres traveled.
Accepted format numeric
vehicleContractData -> power String yes Vehicle power.
Accepted format numeric
vehicleContractData -> licencePlateNumber String yes Licence plate number of the vehicle.
vehicleContractData -> registrationNumber String yes Vehicle registration number.
vehicleContractData -> description String yes Additional information about the vehicle.
boatContractData structure yes in case contract type is BOAT Boat information.
boatContractData -> model String yes Boat model.
boatContractData -> brand String yes Boat brand.
boatContractData -> year String yes Date of the first boat registration.
Accepted format "yyyy-MM-dd"
boatContractData -> type String yes Type of boat.
Possible values: SAILING_BOAT and MOTOR_BOAT
boatContractData -> length String yes Length of boat.
Accepted format numeric with two decimals
boatContractData -> registrationNumber String yes Boat registration number.
boatContractData -> description String yes Additional information about the boat.
milestones[] structure yes Contract payment milestones.
milestone -> id integer yes Milestone id.
milestone -> recipient integer yes CashSentinel id of milestone funds recipient.
milestone -> recipientRole String yes Role of milestone recipient.
Possible values: SELLER, AGENCY or THIRD_PARTY
String[3..45]
milestone -> amount integer yes Milestone amount.
Amount in minor unit (CHF 1.00 ⇒ Value=100)
milestone -> trigger String yes Action triggering funds transfer for a given milestone.
Possible values: APPROVE and VEHICLE_DELIVER
String[3..45]
milestone -> name String yes Milestone name
String[3..45]
milestone -> description String yes Milestone description
String[3..45]

RESPONSE

Header

Http response Description
FORBIDDEN It is not allowed to modify contract with a given id.
BAD_REQUEST Contract is not valid.
NOT_FOUND Contract with a given id does not exist.
OK Contract is successfully updated.

Body

Example:


    {
        "id": 12345 
        "buyer": {
        "id":123
    },
        "type": "VEHICLE",
        "subtype": "PROFESSIONAL",
        "currency": "CHF",
    "vehicleContractData":{
            "model":"Cayenne S",
            "brand":"Porsche",
            "year":"2018-03-12",
            "km":"120000",
            "power":"420",
            "licencePlateNumber":"ZH445789",
            "registrationNumber":"REGNUM",
            "description":"Desc"
        },
        "milestones": [
            {
                "id":123451,
                "recipient":124,
                "recipientRole":"SELLER",
                "amount":6000000,
                "trigger":"VEHICLE_DELIVER",
                "name":"Payment to the seller",
                "description":"Payment to the seller"
            },
            {
                "id":123452,
                "recipient":{
            "id":128
        },
                "recipientRole":"AGENCY",
                "amount":50000,
                "trigger":"APPROVE",
                "name":"Reservation fee",
                "description":"Reservation fee"
            },
            {
                "id":123453,
                "recipient":{
            "id":128
        },
                "recipientRole":"AGENCY",
                "amount":80000,
                "trigger":"VEHICLE_DELIVER",
                "name":"Dealership costs",
                "description":"Dealership costs"
            },
            {
                "id":123455,
                "recipient":{
            "id":129
        },
                "recipientRole":"THIRD_PARTY",
                "amount":200000,
                "trigger":"VEHICLE_DELIVER",
                "name":"Financing payout",
                "description":"Financing payout"
            },
            {
                "id":123454,
                "recipient":{
            "id":1
        },
                "recipientRole":"CS",
                "amount":22900,
                "trigger":"VEHICLE_DELIVER",
                "name":"CashSentinel fee",
                "description":"CashSentinel fee"
            }
        ]
    }

In case request is executed successfully, the response body will contain the list of following data:

Parameter Type Mandatory Description
id integer yes CashSentinel contract id.
buyer structure yes Buyer information.
buyer -> id integer no CashSentinel buyer id.
buyer -> phone string no CashSentinel buyer phone. It should be used in case buyer is not registered.
type string yes Contract type
Possible values: VEHICLE and BOAT
String[3..45]
subtype string yes Contract subtype
Possible values: PRIVATE and PROFESSIONAL
String[3..45]
currency string yes Contract currency ISO 4217 3-letter currency code (CHF, USD, EUR, ...)
Example: CHF String[3]
vehicleContractData structure yes in case contract type is VEHICLE Vehicle information.
vehicleContractData -> model String yes Vehicle model.
vehicleContractData -> brand String yes Vehicle brand.
vehicleContractData -> year String yes Date of the first vehicle registration.
Accepted format "yyyy-MM-dd"
vehicleContractData -> km String yes Vehicle kilometres traveled.
Accepted format numeric
vehicleContractData -> power String yes Vehicle power.
Accepted format numeric
vehicleContractData -> licencePlateNumber String yes Licence plate number of the vehicle.
vehicleContractData -> registrationNumber String yes Vehicle registration number.
vehicleContractData -> description String yes Additional information about the vehicle.
boatContractData structure yes in case contract type is BOAT Boat information.
boatContractData -> model String yes Boat model.
boatContractData -> brand String yes Boat brand.
boatContractData -> year String yes Date of the first boat registration.
Accepted format "yyyy-MM-dd"
boatContractData -> type String yes Type of boat.
Possible values: SAILING_BOAT and MOTOR_BOAT
boatContractData -> length String yes Length of boat.
Accepted format numeric with two decimals
boatContractData -> registrationNumber String yes Boat registration number.
boatContractData -> description String yes Additional information about the boat.
milestones[] structure yes Contract payment milestones.
milestone -> id integer yes Milestone id.
milestone -> recipient integer yes CashSentinel id of milestone funds recipient.
milestone -> recipientRole String yes Role of milestone recipient.
Possible values: SELLER, AGENCY, THIRD_PARTY or CS
String[3..45]
milestone -> amount integer yes Milestone amount.
Amount in minor unit (CHF 1.00 ⇒ Value=100)
milestone -> trigger String yes Action triggering funds transfer for a given milestone.
Possible values: APPROVE and VEHICLE_DELIVER
String[3..45]
milestone -> name String yes Milestone name
String[3..45]
milestone -> description String yes Milestone description
String[3..45] milestone -> description

Contract cancellation

This method may be used to cancel the existing contract.

GET api/contract/{contractId}/cancel

REQUEST

contractId is a CashSentinel contract id

RESPONSE

Header

Http response Description
FORBIDDEN It is not allowed to cancel given contract.
NOT_FOUND Contract with a given id does not exist.
OK Contract is successfully cancelled.

CashSentinel banking details

This method may be used to retrieve CashSentinel banking details for account funding.

GET api/contract/{contractId}/funding-info

REQUEST

contractId is a CashSentinel contract id

RESPONSE

Header

Http response Description
FORBIDDEN It is not allowed to retrieve banking details for a given contract.
NOT_FOUND Contract with a given id does not exist.
OK Banking details successfully retrieved.

Body

Example:


    {
        "IBAN": "CH9300762011623852957" 
        "BIC": "SWQBCHZZXXX",
        "bank": "Swissquote Bank",
        "accountHolder": "CashSentinel SA",
        "address": "Avenue de Tivoli 19 bis",
        "addressCont": "CH-1007 Lausanne",
        "fundingAmount": 6352900,
        "fundingCurrency": "CHF"
    }

In case request is executed successfully, the response body will contain the list of following data:

Parameter Type Mandatory Description
IBAN string yes CashSentinel escrow account IBAN.
BIC string yes CashSentinel escrow account BIC code.
bank string yes CashSentinel escrow account Bank.
accountHolder string yes CashSentinel company name.
address string yes CashSentinel address.
addressCont string yes CashSentinel address.
fundingAmount int yes Required amount for a given contract.
fundingCurrency string yes Required currency for a given contract.

Release funds

This method may be used to on vehicle delivery in order to release funds to the contract milestone recipients and complete contract.

GET api/contract/{contractId}/complete

REQUEST

contractId is a CashSentinel contract id

RESPONSE

Header

Http response Description
FORBIDDEN It is not allowed to release funds for a given contract.
NOT_FOUND Contract with a given id does not exist.
NOT_ACCEPTABLE Complete action is not acceptable at this point.
OK Contract is successfully completed and funds are transferred to the milestone recipient wallets.

Contract details

This method may be used to retrieve details of the specific contracts.

POST api/contract/data

REQUEST

Body

Example:

[12345, 12346]

List of CashSentinel contract Id.

RESPONSE

Header

Http response Description
FORBIDDEN It is not allowed to retrieve details of a given contract.
NOT_FOUND Contract with a given id does not exist.
OK Contract details successfully retrieved.

Body

Example:


    [
         {
                "id": 12345 
                 "buyer":{
                        "id":123
                        },
                "type": "VEHICLE",
                "subtype": "PROFESSIONAL",
                "currency": "CHF",
                "vehicleContractData":{
                    "model":"Cayenne S",
                    "brand":"Porsche",
                    "year":"2018-03-12",
                    "km":"120000",
                    "power":"420",
                    "licencePlateNumber":"ZH445789",
                    "registrationNumber":"REGNUM",
                    "description":"Desc"
                },
                "milestones": [
                {
                        "id":123451,
                        "recipient": {
                               "id":124
                               }
                         "recipientRole":"SELLER",
                         "amount":6000000,
                         "trigger":"VEHICLE_DELIVER",
                         "name":"Payment to the seller",
                         "description":"Payment to the seller"
                },
                {
                         "id":123452,
                         "recipient":{
                                "id":128
                                },
                         "recipientRole":"AGENCY",
                         "amount":50000,
                         "trigger":"APPROVE",
                         "name":"Reservation fee",
                         "description":"Reservation fee"
                },
                {
                         "id":123453,
                         "recipient":{
                                "id":128
                                },
                         "recipientRole":"AGENCY",
                         "amount":80000,
                         "trigger":"VEHICLE_DELIVER",
                         "name":"Dealership costs",
                         "description":"Dealership costs"
                },
                {
                         "id":123455,
                         "recipient":{
                                 "id":129
                                 },
                         "recipientRole":"THIRD_PARTY",
                         "amount":200000,
                         "trigger":"VEHICLE_DELIVER",
                         "name":"Financing payout",
                         "description":"Financing payout"
                },
                {
                         "id":123454,
                         "recipient":{
                                  "id":1
                                  },
                         "recipientRole":"CS",
                         "amount":22900,
                         "trigger":"VEHICLE_DELIVER",
                         "name":"CashSentinel fee",
                         "description":"CashSentinel fee"
               }
               ],
               "documents": [
                        {
                         "id": 14614,
                         "docType": "OTHER",
                         "files": [
                                {
                                 "fid": "34531",
                                 "name": "DOC_1232_20190611_120321_0.jpg",
                                 "size": 6569
                         }
                ]
         }
    ]

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 contract id.
buyer structure yes Buyer information.
buyer -> id integer no CashSentinel buyer id.
buyer -> phone string no CashSentinel buyer phone. It should be used in case buyer is not registered.
type string yes Contract type
Possible values: VEHICLE and BOAT
String[3..45]
subtype string yes Contract subtype
Possible values: PRIVATE and PROFESSIONAL
String[3..45]
currency string yes Contract currency ISO 4217 3-letter currency code (CHF, USD, EUR, ...)
Example: CHF String[3]
vehicleContractData structure yes in case contract type is VEHICLE Vehicle information.
vehicleContractData -> model String yes Vehicle model.
vehicleContractData -> brand String yes Vehicle brand.
vehicleContractData -> year String yes Date of the first vehicle registration.
Accepted format "yyyy-MM-dd"
vehicleContractData -> km String yes Vehicle kilometres traveled.
Accepted format numeric
vehicleContractData -> power String yes Vehicle power.
Accepted format numeric
vehicleContractData -> licencePlateNumber String yes Licence plate number of the vehicle.
vehicleContractData -> registrationNumber String yes Vehicle registration number.
vehicleContractData -> description String yes Additional information about the vehicle.
boatContractData structure yes in case contract type is BOAT Boat information.
boatContractData -> model String yes Boat model.
boatContractData -> brand String yes Boat brand.
boatContractData -> year String yes Date of the first boat registration.
Accepted format "yyyy-MM-dd"
boatContractData -> type String yes Type of boat.
Possible values: SAILING_BOAT and MOTOR_BOAT
boatContractData -> length String yes Length of boat.
Accepted format numeric with two decimals
boatContractData -> registrationNumber String yes Boat registration number.
boatContractData -> description String yes Additional information about the boat.
milestones[] structure yes Contract payment milestones.
milestone -> id integer yes Milestone id.
milestone -> recipient integer yes CashSentinel id of milestone funds recipient.
milestone -> recipientRole String yes Role of milestone recipient.
Possible values: SELLER, AGENCY, THIRD_PARTY or CS
String[3..45]
milestone -> amount integer yes Milestone amount.
Amount in minor unit (CHF 1.00 ⇒ Value=100)
milestone -> trigger String yes Action triggering funds transfer for a given milestone.
Possible values: APPROVE and VEHICLE_DELIVER
String[3..45]
milestone -> name String yes Milestone name
String[3..45]
milestone -> description String yes Milestone description
String[3..45] milestone -> description
documents[] structure yes Contract documents.
document -> id integer yes CashSentinel document id.
document -> docType String yes Document type
Possible values:
GREY_CARD, OTHER
document -> files[] array yes Document files
document -> file -> fid String yes CashSentinel file id.
document -> file -> name String yes File name
document -> file -> size int yes File size

Notifications