NAV

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.

Client onboarding

Here we explain the client onboarding process using CashSentinel API.index.html images fonts javascripts stylesheets 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.

Client 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 3 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. You can always request list of onboarded clients per client type.

POST /api/registration/customer

REQUEST

Example:


{
    "phone": "+41712345678",
    "phoneCode": "+41",
    "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]
phoneCode string yes Client phone number country code
Example +41
String[3..6]
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",
    "registrationUrl": "https://app.cashsentinel.com/register/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_REGISTRATION, IN_REGISTRATION_PROCESS, 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

Clients list

This method may be used to retrieve details of all onboarded clients per client type.

POST /api/registration/customers

REQUEST

Header

Http parameter Description
customerType Client type
Possible values:
PRIVATE_INDIVIDUAL, PROFESSIONAL

RESPONSE

Header

Http response Description
OK Client data retrieved.

Body

In case the request is executed successfully, the response body will contain the list of client details data

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

In case the request is executed successfully, the response body will contain the list of client details data

Client details data

Example:

    [
        {
            "id": 123,
            "status": "ACTIVE",
            "name":"Mr John Doe",
            "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",
            "name":"Mr Max Mustermann",
            "wallets": [
                {
                    "id": 161234,
                    "balance": 0,
                    "currency": "CHF",
                    "bank": "SWISSQUOTE"
                }
            ],
            "missingDocuments": [
                {
                    "date": "2019-04-18T09:23:56.000+0000",
                    "type": "ID-uploadAccepted",
                    "customType": ""
                }
            ]
        }
    ]
Parameter Type Mandatory Description
id integer yes CashSentinel customer id.
status string yes Client status.
Possible values:
PENDING_REGISTRATION, IN_REGISTRATION_PROCESS, PENDING_VALIDATION, ACTIVE, REJECTED, CLOSED
name string yes Client name.
wallets[] structure yes Client wallets.
missingDocuments[] structure yes Documents CashSentinel needs for operational puprosses.

Wallet data

Parameter Type Mandatory Description
id integer yes Wallet Id.
balance integer yes Balance on specific wallet.
Amount in minor unit (CHF 1.00 ⇒ Value=100).
currency string yes ISO 4217 3-letter currency code (CHF, USD, EUR, ...)
Example: CHF
bank string yes Bank holding funds on escrow.

Missing document data

Parameter Type Mandatory Description
date string yes Date when document requested.
type string yes Type of document.
Possible values:
ID-upload,
ID-uploadIdFront,
ID-uploadIdBack,
ID-uploadIdNonExpired,
ID-uploadIdReadable,
ID-uploadImageCut,
ID-uploadAccepted,
DOC-uploadProofOfAddress,
DOC-uploadGreyCard,
DOC-uploadRIB,
DOC-uploadZefix,
DOC-uploadLeasing,
DOC-uploadThirdParty,
DOC-uploadDA,
DOC-uploadProcuration,
DOC-uploadOriginOfFunds,
DOC-uploadUboRbe,
DOC-uploadSiv,
DOC-uploadProofOfTransfer,
DOC-uploadOther
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.
contractId Contract id. Non mandatory parameter in case document is linked to the contract.
docType Document type
Possible values:
ID, ZEFIX, PROOF_OF_ADDRESS, GREY_CARD, RIB, LEASING, THIRD_PARTY, DA, SIV, PROCURATION, ORIGIN_OF_FUNDS, UBO_RBE, 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 occurred.
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"
    }
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

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",
        "address": "Kappelergasse 1",
        "address2": "",
        "postalCode": "5678",
        "city": "Bern",
        "country": "CH",
        "language": "en"

    }

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

Parameter Type Mandatory Description
id integer yes CashSentinel customer id
status string yes Client status.
Possible values:
PENDING_REGISTRATION, IN_REGISTRATION_PROCESS, 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]

Service payments

Here we explain the service payment processing using CashSentinel API.

Process-flow

  1. Onboard agent and payer
  2. Create a payment service
  3. Use redirection URL you received in response for step 2 to access the payment page.
  4. Depending of the outcome of step 3 there are two scenarios:
    • 4.1 Payment fails: payment process will be re-initiated with appropriate error message.
    • 4.2 Payment successful: client will be redirected to the success URL specified in step 2.
    • 4.3 Payment cancelled: client will be redirected to the originUrl URL specified in step 2.
  5. Depending of the outcome of step 4 there are two scenarios:
  6. Process is finished!

You can skip step 1 and include payer onboarding in step 2 as described here. You can always request payment service details for a specific payment service, list by status or list by closed date.

Payment service creation

This method may be used to create a payment service and retrieve redirection URL to access the payment page on our portal. Once created, service payment will be valid for 14 days.

PUT api/service-payment/create

REQUEST

Example:


    {
        "product":"Reservation for Porsche Cayenne S",
        "payer": {
             "registrationData":{
                    "phone": "+41712345678",
                    "phoneCode": "+41",
                    "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"
             }
        },
        "agent":{
            "id":128
        },
        "contractId":1232,
        "amount":{
            "value":10000,
            "currency":"CHF"
        },
        "description":"Reservation for Porsche Cayenne S",
        "successUrl":"https://www.your-website.com/sucesfull-payment-redirection",
        "originUrl":"https://www.your-website.com/return-redirection",
        "notifyPayer":"true"
    }

Service payment request

Parameter Type Mandatory Description
product string yes Payment product
String[3..100]
payer structure yes Payer information.
agent structure yes Dealership agent information.
contractId integer no Contract id for the reference, if payment is related to the contract.
amount structure yes Amount to be paid.
description string yes Payment description
String[3..1000]
successUrl string yes URL for redirection in case payment is successful
String[3..200]
originUrl string yes URL for redirection in case payment is cancelled
String[3..200]
notifyPayer boolean no Notification should be sent to the payer? Default value is true

RESPONSE

Header

Http response Description
BAD_REQUEST Service payment data not valid.
NOT_FOUND Agent or payer id not found.
FORBIDDEN It is not allowed to create payment service.
CREATED Service payment is successfully created with CashSentinel.

Body

Service payment response

In case the request is executed successfully, the response body will contain service payment response data.

Payment service modification

This method may be used to update existing payment service. Payment service can be updated only if status is "NEW". Once it's updated, exiration date will be updated as well as payment page Url.

POST api/service-payment/{serviceId}/update

REQUEST

serviceId is a CashSentinel service payment id

Example:


    {
        "product":"Reservation for Porsche Cayenne S",
        "payer": {
             "registrationData":{
                    "phone": "+41712345678",
                    "phoneCode": "+41",
                    "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"
             }
        },
        "agent":{
            "id":128
        },
        "contractId":1232,
        "amount":{
            "value":10000,
            "currency":"CHF"
        },
        "description":"Reservation for Porsche Cayenne S",
        "successUrl":"https://www.your-website.com/sucesfull-payment-redirection",
        "originUrl":"https://www.your-website.com/return-redirection",
        "notifyPayer":"true"
    }

Service payment request

Parameter Type Mandatory Description
product string yes Payment product
String[3..100]
payer structure yes Payer information.
agent structure yes Dealership agent information.
contractId integer no Contract id for the reference, if payment is related to the contract.
amount structure yes Amount to be paid.
description string yes Payment description
String[3..1000]
successUrl string yes URL for redirection in case payment is successful
String[3..200]
originUrl string yes URL for redirection in case payment is cancelled
String[3..200]
notifyPayer boolean no Notification should be sent to the payer? Default value is true

RESPONSE

Header

Http response Description
BAD_REQUEST Service payment data not valid.
NOT_FOUND Service id not recognized. Agent or payer id not recognized.
FORBIDDEN It is not allowed to modify payment service with given id.
OK Service payment is successfully updated with CashSentinel.

Body

Service payment response

In case the request is executed successfully, the response body will contain service payment response data.

Payment service cancellation

This method may be used to cancel existing payment service. Payment service can be cancelled only if status is "NEW".

POST api/service-payment/{serviceId}/cancel

REQUEST

serviceId is a CashSentinel service payment id

RESPONSE

Header

Http response Description
NOT_FOUND Service id not recognized.
FORBIDDEN It is not allowed to cancel payment service with given id.
OK Service payment is successfully updated with CashSentinel.

Payment service refund

This method may be used to request refund for existing payment service. Payment service can be refunded only if status is "PAID". Refund function may not happen instantly as it requires manual check by operations team.

POST api/service-payment/{serviceId}/request-refund

REQUEST

serviceId is a CashSentinel service payment id

RESPONSE

Header

Http response Description
NOT_FOUND Service id not recognized.
FORBIDDEN It is not allowed to request refund for payment service with given id.
OK Refund request successfully sent to CashSentinel.

Payment service release funds

This method may be used to request funds transfer to the dealership's bank account. Payment service funds can be released only if status is "PAID". CashSentinel creates payment instructions towards the bank every night and payment should be visible on client's account next business day.

POST api/service-payment/{serviceId}/release-funds

REQUEST

serviceId is a CashSentinel service payment id

RESPONSE

Header

Http response Description
NOT_FOUND Service id not recognized.
FORBIDDEN It is not allowed to release funds for payment service with given id.
OK Refund request successfully sent to CashSentinel.

Payment service details

This method may be used to check status of existing payment service.

POST api/service-payment/{serviceId}

REQUEST

serviceId is a CashSentinel service payment id

RESPONSE

Header

Http response Description
NOT_FOUND Service id not recognized.
FORBIDDEN It is not allowed to request details of payment service with given id.
OK Service payment data retrieved.

Body

Service payment response

In case the request is executed successfully, the response body will contain service payment response data.

Payment service list

This method may be used to retrieve all payment services filtered by status.

POST api/service-payment/list

REQUEST

Body

Example:

["NEW","PAID"]

List of payment statuses. Possible values: NEW, PAID, EXPRD, CANX, RFND, CLSD

RESPONSE

Header

Http response Description
BAD_REQUEST Body is empty.
FORBIDDEN It is not allowed to request details of any payment service.
OK Service payment data retrieved.

Body

Service payment list response

In case the request is executed successfully, the response body will contain a list of service payment response data.

Payment service list closed

This method may be used to retrieve all payment services closed on specific date.

POST api/service-payment/list-closed

REQUEST

Http parameter Description
date Valid date in format yyyy-MM-dd

Example:

"2021-02-09"

RESPONSE

Header

Http response Description
BAD_REQUEST Invalid date format.
FORBIDDEN It is not allowed to request details of any payment service.
OK Service payment data retrieved.

Body

Service payment list response

In case the request is executed successfully, the response body will contain a list of service payment response data.

Contracts

Here we explain the contract processing using CashSentinel API.

Process-flow

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

You can request contract details or missing documents for specific contract or retrieve list of contracts with main information. Optionally, CashSentinel can setup webhook notifications for several contract actions.

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.

PUT api/contract/create

REQUEST

Example:


    {
        "buyer": {
             "id":123
        },
        "type": "VEHICLE",
        "subType": "PROFESSIONAL",
        "vehicleData":{
            "model":"Cayenne S",
            "brand":"Porsche",
            "year":"03-09-2019",
            "proofOfOwnershipDocDate":"2022-10-30",
            "km":"120000",
            "power":"420",
            "licencePlateNumber":"ZH445789",
            "registrationNumber":"REGNUM",
            "description":"Desc",
            "owner": {
                "gender":"M",
                "firstName":"John",
                "lastName":"Smith",
                "isCompany":false
            }
        },
        "seller":{
            "id":128
        },
        "leasingReference":"CS1232",
        "renting":{
            "client":{
                "id":122
            },
            "paying":false
        },
        "payment":{
            "currency":"CHF",
            "sellerNet":{
                "amount":8000000,
                "paymentMethod":"CS"
            },
            "sellerDeposit":{},
            "commission":{
                "amount":130000,
                "paymentMethod":"CS"
            },
            "commissionOnOrder":{
                "amount":50000,
                "paymentMethod":"CS"
            },
            "rentingPayment":{
                "amount":150000,
                "paymentMethod":"CS"
            },
            "thirdPartyPayments":[
                {
                    "recipient":{
                        "id":1234
                    },
                    "payment":{
                        "amount":150000,
                        "paymentMethod":"CS"
                    },
                    "comment":"3rd party payment"
                }
            ]
        },
        "estimatedDeliveryDate":"2023-11-24"

    }

Contract request

Parameter Type Mandatory Description
buyer structure yes Buyer information.
type string yes Contract type
Possible values: VEHICLE and BOAT
String[3..45]
subType string yes Contract subtype
Possible values: PROFESSIONAL
String[3..45]
vehicleData structure yes in case contract type is VEHICLE Vehicle information.
boatData structure yes in case contract type is BOAT Boat information.
tradeInContract structure no Trade in contract details.
seller structure yes Seller information.
leasingReference string no Payment reference for leasing company
renting structure no Renting client data.
payment structure yes Payment information.
estimatedDeliveryDate string yes Estimated contract delivery date
Valid date in format yyyy-MM-dd

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

Contract response

In case the request is executed successfully, the response body will contain contract response data.

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, CONTRACT_MARKETING
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

In case the request is executed successfully, the response body will contain document data.

Submit contract for approval

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

POST 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 can be modified only before vehicle delivery step and only payments that are not paid can be modified. It's not allowed to modify cancelled contract. Once contract is modified, in needs to be sent for approval and approved by the client.

Third party payment modification

It is possible to add new third party payment by adding additional third party payment structure without id parameter. If existing third party payment is not sent in the structure, it will be considered as deleted and it will be removed from the contract.

POST api/contract/{contractId}/modify

REQUEST

contractId is a CashSentinel contract id

REQUEST

Example:


    {
        "buyer": {
             "id":123
             },
        "type": "VEHICLE",
        "subType": "PROFESSIONAL",
        "vehicleData":{
            "model":"Cayenne S",
            "brand":"Porsche",
            "year":"03-09-2019",
            "proofOfOwnershipDocDate":"2022-10-30",
            "km":"120000",
            "power":"420",
            "licencePlateNumber":"ZH445789",
            "registrationNumber":"REGNUM",
            "description":"Desc",
            "owner": {
                "gender":"M",
                "firstName":"John",
                "lastName":"Smith",
                "isCompany":false
            }
        },
        "seller":{
            "id":128
        },
        "leasingReference":"CS1232",
        "renting":{
            "client":{
                "id":122
            },
            "paying":false
        },
        "payment":{
            "currency":"CHF",
            "sellerNet":{
                "amount":8000000,
                "paymentMethod":"CS"
            },
            "sellerDeposit":{},
            "commission":{
                "amount":130000,
                "paymentMethod":"CS"
            },
            "commissionOnOrder":{
                "amount":50000,
                "paymentMethod":"CS"
            },
            "rentingPayment":{
                "amount":150000,
                "paymentMethod":"CS"
            },
            "thirdPartyPayments":[
                {
                    "id":123,
                    "recipient":{
                        "id":1234
                    },
                    "payment":{
                        "amount":150000,
                        "paymentMethod":"CS"
                    },
                    "comment":"3rd party payment"
                }
            ]
        },
        "estimatedDeliveryDate":"2023-11-24"
    }

Contract request

Parameter Type Mandatory Description
buyer structure yes Buyer information.
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]
vehicleData structure yes in case contract type is VEHICLE Vehicle information.
boatData structure yes in case contract type is BOAT Boat information.
tradeInContract structure no Trade in contract details.
seller structure yes Seller information.
leasingReference string no Payment reference for leasing company
renting structure no Renting client data.
payment structure yes Payment information.
estimatedDeliveryDate string yes Estimated contract delivery date
Valid date in format yyyy-MM-dd

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

In case the request is executed successfully, the response body will contain contract response data.

Contract cancellation

This method may be used to cancel the existing contract.

POST 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.

Release funds

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

POST 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.

Instant payout

This method may be used to request instant payout for the seller. Outcome of this request depends on the seller's bank. If bank does not accept instant payments, it is not possible to execute it.

POST api/contract/{contractId}/instant_payout

REQUEST

contractId is a CashSentinel contract id

RESPONSE

Header

Http response Description
FORBIDDEN It is not allowed to request instant payout for a given contract.
NOT_FOUND Contract with a given id does not exist.
NOT_ACCEPTABLE Instant payout action is not acceptable at this point.
OK Instant payout is successfully completed and seller should receive funds promptly.

Contract details

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

GET api/contract/{contractId}/data

REQUEST

contractId is a 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

In case the request is executed successfully, the response body will contain contract response data.

Missing documents

This method may be used to retrieve details of the requested missing documents for specific contract.

POST api/contract/{contractId}/missing-documents

REQUEST

contractId is a CashSentinel contract id

RESPONSE

Header

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

Body

In case the request is executed successfully, the response body will contain the list of contract missing documents data.

List of contracts

This method may be used to retrieve list of contracts.

POST api/contract/list

REQUEST

Example:


    {
    "filter": [
        {
            "field": "status",
            "criteria": [
                {
                    "operator": "=",
                    "values": [
                        "NEW",
                        "DRAFT",
                        "SENT",
                        "ACCEPTED",
                        "CLOSED"
                    ]
                }
            ]
        }
    ],
    "page": 0,
    "size": 50,
    "sort": "ID:DESC"
}

Contracts list request

Parameter Type Mandatory Description
filter[] structure yes Filters for contracts list.
page integer yes Number of the page, starting with 0
Positive integer
size integer yes Size of the page
Positive integer[1..250]
sort string yes List sorting order
Possible values: ID:DESC and ID:ASC

RESPONSE

Header

Http response Description
BAD_REQUEST Contract list filter is not valid.
OK Contracts list successfully retrieved.

Body

In case the request is executed successfully, the response body will contain contracts list response data.

Contract notifications

CashSentinel can setup webhook for several contract actions. Using webhook, we send POST request to the specified URL. Optionally, we can set basic authentication to connect to the webhook.

REQUEST

Example:


{
    "clientId":1233,
    "action":"CONTRACT_COMPLIANT",
    "contractId":123
}
Parameter Type Mandatory Description
clientId integer yes CashSentinel customer id of the agency.
action string yes Action on contract
Possible values: CONTRACT_COMPLIANT, FUNDS_RECEIVED, CONTRACT_ACCEPTED, VEHICLE_DELIVERY
contractId integer yes CashSentinel contract id

Common data structures

Client request information

Parameter Type Mandatory Description
id integer yes CashSentinel id.

Client response information

Parameter Type Mandatory Description
id integer yes CashSentinel id.
name string yes Client name.

Document response information

Example:


    {
        "id": 15068,
        "docType": "GREY_CARD",
        "files": [
            {
                 "fid": "34679",
                 "name": "DOC_728333_20190621_144010_0.png",
                 "size": 53582
             }
         ]
     }
Parameter Type Mandatory Description
id integer yes CashSentinel document id.
docType string yes Document type
Possible values:
GREY_CARD, CONTRACT_MARKETING
files[] array yes Document files

File response information

Parameter Type Mandatory Description
fid string yes CashSentinel file id.
name string yes File name
size integer yes File size

Contract response information

Example:


    "contract": {
        "id": 4949,
        "status": "NEW",
        "statusName": "New",
        "owner": {
            "id": 24227,
            "name": "Mr. John Doe, Doe Cars SA"
        },
        "buyer": {
            "id": 24644,
            "name": "Mr. Peter Smith, +41781234567, CS7747590",
            "type": "OTHER_CLIENT",
            "phone": "+41781234567"
        },
        "type": "VEHICLE",
        "subType": "PROFESSIONAL",
        "estimatedDeliveryDate":"2023-11-24",
        "vehicleData": {
            "model":"Cayenne S",
            "brand":"Porsche",
            "year":"03-09-2019",
            "proofOfOwnershipDocDate":"2022-10-30",
            "km":"120000",
            "power":"420",
            "licencePlateNumber":"ZH445789",
            "registrationNumber":"REGNUM",
            "description":"Desc",
            "owner": {
                "gender":"M",
                "firstName":"John",
                "lastName":"Smith",
                "isCompany":false
            }
        },
        "proofOfOwnershipDoc": {
            "id": 28224,
            "docType": "GREY_CARD",
            "privateFlag": true,
            "files": [
                {
                    "fid": "59092",
                    "name": "DOC_24227_20200908_100308137_0.jpg",
                    "size": 885633,
                    "thumbnail": "th-59092"
                }
            ]
        },
        "seller": {
            "id": 24645,
            "name": "Mr. Anas Lapardi, +41761234567, CS2233996",
            "type": "OTHER_CLIENT",
            "subType": "OTHER_CLIENT",
            "phone": "+41761234567"
        },
        "payment": {
            "currency": "CHF",
            "sellerNet": {
                "amount": 8000000,
                "paymentMethod": "CS",
                "paid": false
            },
            "commission": {
                "amount": 130000,
                "paymentMethod": "CS",
                "paid": false
            },
            "commissionOnOrder": {
                "amount": 50000,
                "paymentMethod": "CS",
                "paid": false
            },
            "rentingPayment":{
                "amount":150000,
                "paymentMethod":"CS",
                "paid": false
            },
             "thirdPartyPayments":[
                {
                    "id":123,
                    "recipient":{
                        "id":1234
                    },
                    "payment":{
                        "amount":150000,
                        "paymentMethod":"CS"
                    },
                    "comment":"3rd party payment"
                }
            ]
        },
        "requiredAmount": {
            "value": 8430000,
            "currency": "CHF"
        },
        "totalAmount": {
            "value": 8430000,
            "currency": "CHF"
        },
        "paidAmount": {
            "value": 0,
            "currency": "CHF"
        },
        "fundedAmount": {
            "value": 0,
            "currency": "CHF"
        },
        "history": [
            {
                "date": 1599555467,
                "action": "Contract created",
                "user": "Agent(Mr. John Doe)",
                "comment": ""
            }
        ]
    }
Parameter Type Mandatory Description
id integer yes Contract id
status string yes Contract status.
Possible values: DRAFT, NEW, SENT, ACCEPTED, FUNDED, COMPLETED, CLOSED, CANCELLED
statusName string yes Contract status descriptive name.
owner structure yes Owner information.
buyer structure yes Buyer information.
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]
estimatedDeliveryDate string yes Estimated contract delivery date
Valid date in format yyyy-MM-dd
vehicleData structure yes in case contract type is VEHICLE Vehicle information.
boatData structure yes in case contract type is BOAT Boat information.
proofOfOwnershipDoc structure yes Vehicle certificate of title.
marketingDoc structure yes Vehicle certificate of title.
tradeInContract structure no Trade in contract details.
seller structure yes Seller information.
leasingReference string no Payment reference for leasing company
renting structure no Renting client data.
payment structure yes Payment information.
requiredAmount structure yes Required amount for contract completion.
totalAmount structure yes Required amount for contract completion.
paidAmount structure yes Required amount for contract completion.
fundedAmount structure yes Required amount for contract completion.
history[] structure yes Contract history.

Vehicle information

Parameter Type Mandatory Description
model string yes Vehicle model.
brand string yes Vehicle brand.
year string yes Date of the first vehicle registration.
Accepted format "dd-MM-yyyy"
proofOfOwnershipDocDate string yes Date of the provided Certificate of Title document.
Accepted format "yyyy-MM-dd"
km string yes Vehicle kilometres traveled.
Accepted format numeric
power string yes Vehicle power.
Accepted format numeric
licencePlateNumber string yes Licence plate number of the vehicle.
registrationNumber string yes Vehicle registration number.
description string yes Additional information about the vehicle.
owner structure yes Vehicle owner (field C.1 on a French Certificate of Title).
coOwner structure no Vehicle owner (field C 4.1 on a French Certificate of Title).

Vehicle owner information

Parameter Type Mandatory Description
gender string yes if isCompany = false Client gender
Possible values: M - male and F - female
String[1]
firstName string yes if isCompany = false Client first name
String[3..45]
lastName string yes if isCompany = false Client last name
String[3..45]
isCompany boolean yes true if vehicle is owner by the company, false otherwise
companyName string yes if isCompany = true Company name
String[3..70]

Boat information

Parameter Type Mandatory Description
model string yes Boat model.
brand string yes Boat brand.
year string yes Date of the first boat registration.
Accepted format "dd-MM-yyyy"
type string yes Type of boat.
Possible values: SAILING_BOAT and MOTOR_BOAT
length string yes Length of boat.
Accepted format numeric with two decimals
registrationNumber string yes Boat registration number.
description string yes Additional information about the boat.

Contract renting information

Parameter Type Mandatory Description
client structure yes Renter information.
paying boolean yes Renter is paying?

Contract payment information

Parameter Type Mandatory Description
currency string yes Contract currency ISO 4217 3-letter currency code (CHF, USD, EUR, ...)
Example: CHF String[3]
sellerNet structure yes Total amount towards seller (Including deposit if exists).
sellerDeposit structure yes Deposit amount towards seller (Included in sellerNet).
commission structure yes Commission amount towards agent (Including commission on order if exists).
commissionOnOrder structure yes Commission amount towards agent received on contract acceptance (Included in commission amount).
rentingPayment structure yes Renting client payment. Payment towards renting client in case renting -> paying is false, otherwise towards financial institution.
thirdPartyPayments[] structure yes Payments towards 3rd party clients.

Contract history information

Parameter Type Mandatory Description
date integer yes Contract action timestamp in unixtime format
action string yes Contract action
user string yes User
comment string no Comment added by the user

Third party payment information

Parameter Type Mandatory Description
id integer no Third party payment id included in response and it is mandatory in case of modification.
recipient structure yes Payment recipient.
thirdPartyPayments structure yes Payment towards specific 3rd party client.
comment string no Comment
String[3..45]

Payment information

Parameter Type Mandatory Description
amount integer yes Amount in minor unit (CHF 1.00 ⇒ Value=100)
paymentMethod string yes Payment method.
Possible values: CS and NON_CS
String[3..45]

Contract missing document information

Example:

[
    {
        "id": 29516,
        "customerId": 49543,
        "customerName": "Mr. Max Musterman, +336184xxxxx, CS1855689",
        "message": "Please provide a complete and valid ID document.",
        "title": "Update identity document - non accepted",
        "textBeforeField": "Please provide a new copy of a valid ID. The one you sent us previously did not fulfill our conditions.",
        "textAfterField": "We need a readable, sharp and complete picture of your ID. Upload it here.<br />All you need is :<br />- Identity card (front/back)<br />- Passport<br />- Driving Licence (card format)<br />- Work permit",
        "fieldLabel": "Identity documents",
        "maxFiles": 2,
        "docType": "ID"
    },
    {
        "id": 29520,
        "customerId": 49543,
        "customerName": "Mr. Max Musterman, +336184xxxxx, CS1855689",
        "message": "Please provide your bank account details.",
        "title": "Banking information",
        "textBeforeField": "Once your transaction has taken place, your funds will be wired to the bank account provided below.<br />Please ensure this account is registered in your name (or your company's name, if you are selling on behalf of a company).",
        "textAfterField": "Please upload a copy of your bank account details (IBAN and BIC).",
        "fieldLabel": "Bank account details",
        "maxFiles": 3,
        "docType": "RIB"
    }
]
Parameter Type Mandatory Description
id integer yes Missing document request id.
customerId integer yes CashSentinel client id.
customerName string yes Client name.
message string yes Message to be displayed on client document upload page.
title string yes Title to be displayed on client document upload page.
textBeforeField string yes Text to be displayed on client document upload page.
textAfterField string yes Text to be displayed on client document upload page.
fieldLabel string yes Label for the client document upload field.
maxFiles integer yes Maximum number of files allowed for upload.
docType string yes Document type
Possible values:
ID, ZEFIX, PROOF_OF_ADDRESS, GREY_CARD, RIB, LEASING, THIRD_PARTY, DA, SIV, PROCURATION, ORIGIN_OF_FUNDS, UBO_RBE, OTHER.

Contracts list response information

Parameter Type Mandatory Description
contracts[] structure yes Contract list item information.
requestPage[] structure yes Contracts list page information.

Contracts list item information

Example:


    {
        "contractId": 15068,
        "date": 1645888475,
        "seller": "Mr. John Smith, Smith Cars SA",
        "buyer": "Mr John Doe, +417612344555",
        "object": "Porsche Cayenne S",
        "requiredAmount": {
            "value": 9899100,
            "currency": "EUR"
        },
        "fundedAmount": {
            "value": 0,
            "currency": "EUR"
        },
        "statusName": "Accepted",
        "status": "ACCEPTED",
        "statusLevel": "WARN",
        "subcontracts": [],
        "compliant": true,
        "estimatedDeliveryDate": "2021-11-24"
    }
Parameter Type Mandatory Description
contractId integer yes Contract id.
date integer yes Contract creation timestamp in unixtime format.
seller string yes Name of the seller.
buyer string yes Name of the buyer.
object string yes Object name, contains vehicle brand and model.
requiredAmount structure yes Amount required for fully funded contract.
fundedAmount structure yes Amount currently funded for contract.
statusName string yes Contract status name in language of the client. Can be used for display.
status string yes Contract status.
Possible values: DRAFT, NEW, SENT, ACCEPTED, FUNDED, COMPLETED, CLOSED, CANCELLED
statusLevel string yes Contract status level which can be used for display colour.
Possible values: DEFAULT, GOOD, WARN, VERY_BAD,BAD
compliant boolean no Contract compliant flag set by CashSentinel operations team.
subcontracts structure yes Contract related to the main contract (trade-in or renting).
estimatedDeliveryDate string no Estimated contract delivery date
Valid date in format yyyy-MM-dd

Contracts list page information

Parameter Type Mandatory Description
page integer yes Number of the page, starting with 0
Positive integer
total integer yes Total number of contracts with given criteria.
Positive integer
size integer yes Size of the page
Positive integer[1..250]
sort string yes List sorting order
Possible values: ID:DESC and ID:ASC
filter[] structure yes Filters for contracts list.

Contracts list filter information

Parameter Type Mandatory Description
field string yes Fileld used for filtering.
Possible values: status
String[3..45]
criteria[] structure yes Criteria used for filtering.

Contracts list filter criteria information

Parameter Type Mandatory Description
operator string yes Criteria operator used for filtering.
Possible values: "="
values[] string yes List of criteria values used for filtering.
Possible values: DRAFT, NEW, SENT, ACCEPTED, COMPLETED, CLOSED, CANCELLED

Payer request information

Exactly one parameter should be set, id or registration data.

Parameter Type Mandatory Description
id integer no CashSentinel id.
registrationData structure no Onboarding data

Payer registration information

Language set for payer will be used as payment page language.

Parameter Type Mandatory Description
phone string yes Client phone number including country code
Example +4176123456
String[8..25]
phoneCode string yes Client phone number country code
Example +41
String[3..6]
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 no Client email
Example john.smith@mail.com
String[3..45]
address string no Client address
String[3..45]
address2 string no Client address continued
String[0..45]
postalCode string no Client postal code
String[3..10]
city string no 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

Agent request information

Parameter Type Mandatory Description
id integer no CashSentinel id.

Amount information

Parameter Type Mandatory Description
amount integer yes Amount in minor unit (CHF 1.00 ⇒ Value=100)
currency string yes ISO 4217 3-letter currency code (CHF, USD, EUR, ...)
Example: CHF

Service payment response information

Example:


    {
        "id": 15068,
        "agent": {
            "id":123,
            "name": "Mr. John Smith, Smith Cars SA"
        },
        "payer": {
            "id": 234,
            "name": "Mr John Doe, +417612344555"
        },
        "product":"Reservation for Porsche Cayenne S",
        "contractId":1232,
         "amount":{
            "value":10000,
            "currency":"CHF"
        },
        "description":"Reservation for Porsche Cayenne S",
        "status":"NEW",
        "statusName":"New",
        "expiration":1611590349338,
        "reserved":false,
        "paymentUrl":"https://www.portal.cashsentinel.com/payment/q3HX6EctPq3HX6EctPwe"
     }
Parameter Type Mandatory Description
id integer yes Service payment id
agent structure yes Agent data
payer structure yes Payer data
product string yes Payment product
String[3..100]
contractId integer no Contract id for the reference, if payment is related to the contract.
amount structure yes Amount to be paid.
description string yes Payment description
String[3..1000]
status string yes Payment status
Possible values:
NEW, PAID, EXPRD, CANX, RFND, CLSD
statusName string yes Payment status descriptive
reserved boolean yes Funds reserved on escrow?
expiration long yes Payment expiration time in miliseconds (14 days initially)
paymentUrl string yes URL for redirection to the payment page
String[3..200]