"Notify" API - reference manual

Table of contents

Introduction to main steps

Which strategy shall I choose?

Which transport shall I choose?

Shall I sign the message?

The message itself

Computing the signature

Message transport

Other considerations with HTTPS/REST and FTP/FTPS

Other considerations HTTPS/REST

Examples with PHP

Other endpoint: check a contract

Product specific information

Introduction to main steps

As seen earlier in this document: "NOTIFY" is a notification protocol. You will use it to inform us that your platform just sold an insurance.

What "NOTIFY" doesn't do ?

Your platform remains autonomous for the insurance sale: there will be no interaction with us in your booking flow:

You will freely decide if an insurance should be presented, and if there are several plans, which one is relevant for the package your selling.

You will have to compute the insurance premium (rules are usually pretty simple, e.g. a percentage of the total basket amount). We have a "QUOTE" API, but except for some specific situations, we do not recommend using it, as computing the premium is really easy in most cases, and using the API would introduce an external connection during your booking process, which is never a good idea (...). 

You will prompt the customer's choice (radio button) "No, I don't want an insurance" (radio button) "Yes, I take out the insurance (+€ 10.00)".

When does "NOTIFY" start ?

Once the booking is finished (along with the insurance sale) your platform will « notify » us (send a message that contains the main characteristics of the insured booking).

The below diagram explains the different steps of this process:

Step 1: booking flow / premium calculation

When the booking is ready, you should evaluate the premium(s) for the insurance(s) you want to offer.

The premium (=insurance price) calculation is generally very easy to achieve, typically it could be:

- For a cancellation insurance, the premium might be based on the total booking price (e.g. 4% minimum 10€ per pax);

- For an assistance insurance, the premium might be based on the destination and/or the stay duration (e.g. 0-10 days=10€, 11-25 days=25€, …);

- etc.

Of course, we will provide you the premium calculation formula, for the relevant insurance products.

Step 2: booking flow / get client’s choice

At some point, your system will propose the insurance, announce the price, and get the user’s choice, e.g.:

« Would you like to insure your trip? (learn more)

|_| Yes, cancellation insurance only (+€ 22 / pax)

|_| Yes, multi-risk insurance (+€ 37 / pax)

|X| No, I do not want any insurance »

Note: the link « learn more » will lead to some page, popup, « overlay div », describing the insurance options and/or at least, to the Terms & Conditions PDF.

Note: it is not legal to pre-check an insurance option. On the other hand, we recommend NOT to tick the “No…” option in advance, as this would reduce the take rate, but also (and most important) because making this choice compulsory will be the proof that you did propose an insurance solution.

Step 3: invoicing

When the insurance is chosen by the client, it is added to the booking price (no VAT applies to insurance premium), and your invoice must show it distinctively (as a separate line).

Step 4: notification... here is "NOTIFY"

Once the payment of the booking is confirmed your platform will transmit all relevant information to Chapka about the insurance that was just sold.

To achieve this, you have to prepare a message and send it to Chapka.

You have a choice between different strategies:

• Individual (only one insurance per message/transmission);
• Batch (several insurances per message/transmission).

Different transport modes are possible:

• EMAIL, in the body or as an attachment;
• FTP or SFTP (upload of a file to our server);
• HTTPS (REST API).

The technical aspect of the protocol is detailed later on in this document:

• One by one or Batch? See “Which strategy shall I choose?”
• Email, FTP, SFTP or HTTPS? See “Which transport shall I choose?”
• Authentication/Signature? See “Shall I sign the message?”
• Once you’ve made up your mind, you can dive to the other parts of this document…

Step 5: on Chapka’s side…

Chapka handles notifications as soon as they arrive.

Insurance subscriptions are inserted into our database and will (among other things) enable the calculation of the monthly invoice sent to you.

Step 6: Email confirmation of the insurance

Also, Chapka will send an email to your client (of course, if the « EMAIL » field was present in the message). The email body usually shows your logo, confirms the insurance, and indicates the procedure “in case of disaster/in case assistance is needed/cancellation before departure”.

Step 7: Monthly invoice

As Chapka now knows how many insurances were sold in the past month, we will issue an invoice, sent by email to you.

The invoice shows the “retailed price” (paid by the customer) and the “bought price” (invoiced to you). The difference being your commission.

Which strategy shall I choose?

The table below summarizes the pros and cons of both strategies (individual/batch):

Which transport shall I choose?

The choice is here strongly depending on the possibilities of your technical environment (and knowledges).

The table below summarizes the pros and cons of those transport modes:

Note: as email delivery is not guaranteed, WE DON’T RECOMMEND THIS TRANSPORT, except if you have no other solution. You might want to keep this transport as a fall-back strategy, should the connection fail with FTP/SFTP or HTTPS/REST.

Shall I sign the message?

We offer a signing solution (SHA1…) in case you want to use EMAIL or HTTPS/REST. We strongly recommend the use of the signature (in fact it’s pretty simple), as without such signature, a third party could transmit messages on your behalf…

The message itself

The notification message holds the insurance policy characteristics.

The message format depends on the chosen « strategy » and « transport », as in the table below:

See below some examples of those formats (simplified, as for your specific case, we will send you the exact list of fields):

Computing the signature

Note: no signature is needed with FTP/SFTP transmissions, as they are authentified by a login/password (or login/key) step.

For « individual strategy » (« TEXT » or « JSON » formats):

Your message will consist in a list of parameters (Pi) each with its value (Vi):

P1 = V1
P2 = V2
P3 = V3
…

The signature is computed as follows: 

1) Sort alphabetically the parameters Pi;
2) Concatenate the corresponding Vi and then concatenate the authentication key (transmitted by Chapka);
3) Compute the « SHA1 » of the resulting string.

Then, the signature must be included in your message as an extra parameter names “SIGN”:

- « TEXT » format: SIGN = 123456ab789ef123…
- « JSON » format: "SIGN" : "123456ab789ef123…"

Note with JSON: in a JSON, if a parameter is a number (let’s say "PRIME" : 340.00), concatenating will involve a “number to string” conversion, and the decimal might disappear, leading to "340" (a number) instead of "340.00" (a string).

This might result into the client and the server not computing the same signature… In order to avoid this, we recommend only “string” parameters in the JSON phrase.

Precisely do this:

"PRIME" : "340.00"

Not that:

"PRIME" : 340.00

For « batch strategy » (« CSV » format):

The signature is computed as follows: 

1) Concatenate the CSV texta long with the authentication key (transmitted by Chapka);
2) Compute the « SHA1 » of the resulting string.

Then, the signature will be transmitted as follows:

-  « EMAIL transport » (body or attachment): add the signature, in the subject, between brackets. Example: « Notify message [123456ab789ef123…] »
-  « HTTPS/REST transport »: add a POST parameter named « SIGN ».

Note: SHA1 is a string not a number!

SHA1 produces a 160 bits string, which leads to a 20 bytes string, which results into a 40 characters string. Hence, leading zeros shall not be destroyed!!!

Message transport

Other considerations with HTTPS/REST and FTP/FTPS

What to do in case of connection failure?

Should the connection fail (due to network issues or our server temporarily not responding, for example), one should choose between the following strategies:

- Fall-back to EMAIL transport;

or

- Retry the connection, let’s say 1 hour later
(and fall-back to email if the failure remains after several retries).

Other considerations with HTTPS/REST

Reply:

- The « HTTP header » holds a « status » and « message ».

Example: « 200 successfully created » (if success);

In case of failure, the HTTP code will be 400.

- The « HTTP content » holds a JSON with the ID confirming the correct reception of your message.

Example: {"id":12345, "status":"OK"}

In case of failure, the "status" will be "KO", and a member "msg" will hold the error message:

Example: {"status":"KO","msg":"Empty or incorrect JSON"}

Troubleshooting - step by step:

Should you encounter difficulties, you might want to call the "healthcheck" function.

Here is a step by step proposal to troubleshoot your problem:

1/ Make a simple call first:

From your browser, then your app., call this URL:

http://api.chapka.fr/notify/index.php

You should get this (failure) answer:

{"status":"KO","msg":"Missing URL parameter 'request'"}

You've successfully made a "GET" request with no URL parameter and no body parameter.

You can try with the "POST" method as well: you should get the same answer.

2/ Add a parameter to the URL:

Then add the "request" URL parameter, calling this:

http://api.chapka.fr/notify/index.php?request=healthcheck

You should get this type of (success) answer:

{"time": "2021-05-17 09:45:19","status": "OK"}

Here again, you may try "GET" and "POST" as well.

3/ Add a body parameter:

This cannot be achieved from your browser, as you will need to provide a body parameter.

Do the same request (as above), but also include a body parameter named "message".

When the parameter is empty, you should get this (faillure) response:

{"status":"KO","msg":"Missing URL parameter 'request'"}

When the parameter is a valid JSON array, like:

{"hello":"good bye"}

you should get this (success) response:

{"time": "2021-05-17 09:45:19","status": "OK"}

4/ Then try signing the message:

Do the same request  as above (GET or POST), with a body parameter named "message" containing:

{"emetteur":"...your sender's name...","sign":"...the signature you've computed..."}

NOTE: this "healthcheck" request does not need a signature. But if you provide a signature, it will be tested, revealing your abllity to compute the correct signature string.

Errors:

When the status is not “200”, it will always be “400”, meaning the request was rejected. The message explains the reason:

400 – Missing parameter GET[request]

Means the GET variable “?request=XXX” is missing in the URL

400 – Incorrect request XXX

Means the GET variable “?request=XXX” is present, but is neither “create” nor “delete”.

400 – Missing parameter POST[message]

Means the POST variable “message” was not found.

400 – Missing signature (in message or in POST[sign]

Means the signature was not found, neither in the message (in a “sign” field), neither as a POST variable “sign”.

400 – Missing parameter ‘SENDER/EMETTEUR’

Means that in the message, the “SENDER”(or “EMETTEUR”) field was not found.

400 – Unknown sender (XXX)

Means that in the message, the “SENDER” field was found (value is “XXX”), but doesn’t correspond to an existing/authorized sender.

400 – Key not set

Means that in our database, the authentication key was not set (our mistake…).

400 - Incorrect method - should be POST / DELETE

Means that with “?request=create” (or “?request=delete”) you should perform a method HTTP POST (or HTTP DELETE).

Examples with PHP

You’ll find below complete running examples with PHP, for both strategies (individual and batch) using the HTTP/REST transport.

The code is pretty simple and the reader should be able to transpose to other language, other transport (EMAIL or FTP), …

Compute the signature:

With JSON: the below function computes the signature from an array, first by sorting by keys, then concatenating values:

function ComputeSignature_FromArray($data, $key)
{
  // Sort by keys
  ksort($data);

  // Empty string
  $string = '';

  // Concatenate values
  foreach($data as $value)
     $string .= $value;

  // Concatenate key
  $string .= $key;

  // Compute SHA1
  $sign = SHA1($string);

  return $sign;
}

With CSV: this function computes the signature by concatenating the CSV with the key:

function ComputeSignature_FromString($string, $key)
{
  // Concatenate key
  $string .= $key;

  // Compute SHA1
  $sign = SHA1($string);

  return $sign;
}

Key initialization:

// Your key (as transmitted by Chapka)
$key = "ce95328d41aba3e79af5e8ff7d90145f";

Below a complete example with JSON:

// Array with sample parameters
$data = array
(
"emetteur"     => "AGENCE VN",    //SENDER’S NAME
"produit"      => "FOOBARLAND",   //PRODUCT NAME
"reference"    => "FB14Q",        //YOUR REFERENCE
"prime"        => "123.45",       //CONTRAT PREMIUM
"email"        => "joe@mail.com", //CLIENT EMAIL
"destination"  => "AU",           //DESTINATION
"nb"           => "1",            //NUMBER OF INSURED
"depart"       => "01/11/2018",   //DEPARTURE DATE
"retour"       => "07/11/2018",   //RETURN DATE
"montant"      => "800,00",       //TRIP AMOUNT
"devise"       => "EUR",          //CURRENCY
"genre"        => "MR",           //CLIENT TITLE
"prenom"       => "Dupont",       //CLIENT FIRSTNAME
"nom"          => "Jean",         //CLIENT LASTNAME
);

// Compute signature
$sign = ComputeSignature_FromArray($data, $key);

// Add « sign » parameter
$data['sign'] = $sign ;

// Encode to JSON
$message = json_encode($data);

// Generate POST data
$postdata = http_build_query(
   array(
         'message' => $message,
         'mode'    => 'json',
        )
   );

Below a complete example with CSV:

// A string with header row and 2 insurances
$data = "EMETTEUR,PRODUIT,ARRIVEE,DEPART,PROVENANCE,DESTINATION,NOMBRE,VA,CA,PRENOM,NOM,REFERENCE,EMAIL,LANGUE,ANNULATION
AGENCE_VN,ASSURANCE_LOCATAIRE,06/11/2017,07/11/2017,FR,FR,1,20.00,9.9,Jean,DUPONT,d_68786,jean@mail.fr,FR,
AGENCE_VN,ASSURANCE_LOCATAIRE,06/11/2017,10/11/2017,FR,FR,1,112.00,16.80,Alice,DURAND,d_68775,alice@mail.com,FR,";

// Compute signature
$sign = ComputeSignature_FromString($data, $key);

// Generate POST data
$postdata = http_build_query(
   array(
         'message' => $message,
        'sign'    => $sign,
         'mode'    => 'csv',
        )
   );

Proceed to transport:

// Build HTTP request
$postNotify = array('http' =>
array(
    'method'  => 'POST',
    'header'  => 'Content-type: application/x-www-form-urlencoded',
    'content' => $postdata,
   )
);

// Build context
$contextNotify = stream_context_create($postNotify);

// Send request
$url = "https://api.chapka.fr/notify/?request=create";
$resultNotify = file_get_contents($url, false, $contextNotify);

Decode the response:

echo "Header=" . $http_response_header[0] . "<br>";
echo "Content=" . $resultNotify . "<br>";

$data_response = json_decode($resultNotify, true);
echo "<br>" . print_r($data_response, true) . "\n";

The output will show:

Header=HTTP/1.1 200 successfully created
Content={"id":12424}
Array
(
    [id] => 12424
)

Note: you might want to decode easily the server’s response. In this case, add the « &dirty=1 » parameter to the endpoint URL.

In this case, the HTTP header will show « 200 OK » and the JSON return will hold two extra parameters « status » and « msg ».

The output will show:

Header=HTTP/1.1 200 OK
Content={"id":12415,"status":200,"msg":"successfully created"}
Array
(
    [id] => 12415
    [status] => 200
    [msg] => successfully created
)

NB: this “id” refers to the received message (your message). Messages are handled slightly after reception (up to a few minutes). The “checkcontract” endpoint (see below) can be fed with this “id” in order to verify that the insurance contract was successfully created.

Other endpoint: check a contract

Once a notification is sent, it is not immediately computed. This might take up to a few minutes.

You might want to verify if the insurance contract was issue properly.

We provide another endpoint “checkcontract”:

- in the Url, change “?request=create” to “?request=checkcontract”;

- use method “GET” (and not “POST”).

The JSON should include the following parameters:

{
"emetteur": "AGENCE VN", 
"notify": …provide here the ID received with the “create” call
"sign": …compute the relevant signature
}

Or:

{
"emetteur": "AGENCE VN", 
"reference": …provide here your reference as transmitted with the "create" call
"sign": …compute the relevant signature
}

If the contract exists (was successfully created), the API will reply with:

{
"contract_number": "1234567", 
"contract_url": "https://www.chapka.fr/..."
"status": "OK"
}

See also: the "webhook" capability in the "create" endpoint.

Product specific information

Message parameters can be sorted into two sets:

• common parameters;
• product specific parameters.

Common parameters

The common parameters are:

Parameters for product CAP EXPLORER

CAP EXPLORER is a general travel insurance product, gathering multiple covers.

For product cover details and pricing, please see here.

The parameter "PRODUCT" (or "PRODUIT") will have the following value: "CAP-EXPLORER".

Below are the product specific parameters:

Parameters for product TRANQUILOC

TRANQUILOC has been advised to you if you offer appartments or villas for rent.

For product cover details and pricing, please see here.

The parameter "PRODUCT" (or "PRODUIT") will have the following value: "TRANQUILOC".

Below are the product specific parameters:

Parameters for product CAP ANNULATION

CAP ANNULATION is a cancellation only insurance.

The product pricing is based on the individual trip amount:

NB: for 3 pax and more, apply a -15% discount.

For example, 2 pax paying each € 1000, hence a total trip amount of € 2000, will have a total premium of € 37x2 = € 74.

The product specific parameters are: