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.

Client onboarding

Here we explain the client onboarding process using CashSentinel API. 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 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

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

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_REGISTRATION, IN_REGISTRATION_PROCESS, PENDING_VALIDATION, ACTIVE, REJECTED, CLOSED
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-uploadIdFront,
ID-uploadIdBack,
ID-uploadIdNonExpired,
ID-uploadIdReadable,
ID-uploadAccepted,
DOC-uploadProofOfAddress,
DOC-uploadGreyCard,
DOC-uploadRIB,
DOC-uploadZefix,
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.
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 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]

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

PUT api/contract/create

REQUEST

Example:


    {
        "buyer": {
             "id":123
        },
        "type": "VEHICLE",
        "subType": "PROFESSIONAL",
        "vehicleData":{
            "model":"Cayenne S",
            "brand":"Porsche",
            "year":"03-09-2019",
            "km":"120000",
            "power":"420",
            "licencePlateNumber":"ZH445789",
            "registrationNumber":"REGNUM",
            "description":"Desc"
        },
        "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"
                }
            ]
        }

    }

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.

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",
            "km":"120000",
            "power":"420",
            "licencePlateNumber":"ZH445789",
            "registrationNumber":"REGNUM",
            "description":"Desc"
        },
        "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"
                }
            ]
        }

    }

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.

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

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.

Notifications

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 int 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",
        "vehicleData": {
            "model":"Cayenne S",
            "brand":"Porsche",
            "year":"03-09-2019",
            "km":"120000",
            "power":"420",
            "licencePlateNumber":"ZH445789",
            "registrationNumber":"REGNUM",
            "description":"Desc"
        },
        "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]
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"
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.

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 "yyyy-MM-dd"
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]