Go directly to content

Chapka travel Insurance

"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 entry point: 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 "NOTIFY" starts ?

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:

process.png

 

 

 

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:

Different transport modes are possible:

 

The technical aspect of the protocol is detailed later on in 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):

STRATEGY ADVANTAGES DRAWBACKS
INDIVIDUAL

For the client: immediate reception of its insurance confirmation.

For your platform: more professional towards clients.

For the client: -

For your platform: involves a change in the « post-sale » process, in order to operate the transmission.

BATCH

For the client: -

For your platform: setup of a « cron » task that as no impact with the post-sale process.

For the client: reception of the insurance confirmation with a delay.

For the platform: less professional towards clients.

 

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:

TRANSPORT ADVANTAGES DRAWBACKS
EMAIL, in the body In general, quite simple (simplest?) to setup. Although emails are usually reliable, there is no real guaranty of delivery (antispam…).
EMAIL, as an attachment A little less simple (as adding an attachment to an email can be trickier with some languages or require a specific library). Same as above.
FTP or SFTP Reliable (because if the upload finishes with success [no error], you can be reasonably certain of the delivery). -
HTTPS/REST

More modern and upgradable protocol.

Setup is (slightly) more complex.

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:

TRANSPORT

Chosen strategy:

INDIVIDUAL

Chosen strategy:

BATCH

Will you get a

RESPONSE ?

NOTE
EMAIL, in the body TEXT CSV - Body as "PLAIN" (avoid "HTML")
EMAIL, as attachment TEXT CSV -

Empty body (will not be read);

Authorized extensions: TXT and CSV.

FTP or SFTP TEXT CSV - Unique file name.
HTTPS/REST JSON CSV HTTP status + JSON response REST protocol.

 

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

TEXT

(email, FTP or SFTP)

EMETTEUR = AGENCE-XYZ // who is sending?
PRODUIT = PRODUIT-ABC // which insurance?
REFERENCE = REF-123 // your booking reference
PRIME = 340.00 // premium calculated by you
EMAIL = joe@mail.com // client’s email address
DEPART = 15/10/2017 // start date
RETOUR = 20/10/2017 // end date

JSON

(HTTPS/REST)

{
    "EMETTEUR" : "AGENCE-XYZ",
    "PRODUIT" : "PRODUIT-ABC",
    "REFERENCE" : "REF-123",
    "PRIME" : "340.00",
    "EMAIL" : "joe@mail.com",
    "DEPART" : "15/10/2017",
    "RETOUR" : "20/10/2017",
    …
}

CSV

(batch)

EMETTEUR ; PRODUIT ; REFERENCE ; DEPART ; …            // headers
AGENCE-XYZ ; PRODUIT-ABC ; REF-123 ; 15/11/2017 ; …    // insurance 1
AGENCE-XYZ ; PRODUIT-ABC ; REF-456 ; 18/12/2017 ; …    // insurance 2

 

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

TRANSPORT DESTINATION/SERVER/ENDPOINT NOTE
EMAIL (body or attachment) notify@chapka.fr Signature added between […] in the email subject.
FTP or SFTP ftp.chapka.fr

Login and password transmitted separately.

No signature.

HTTPS/REST

https://api.chapka.fr/notify/?request=create
(POST)

https://api.chapka.fr/notify/?request=delete
(DELETE)

HTTP request parameters:

Message in parameter « message »

Signature in parameter « sign »
(in case of a CSV format)

 

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” entry point (see below) can be fed with this “id” in order to verify that the insurance contract was successfully created.

 

Other entry-point: 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 entry-point “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
}

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

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

Product specific information

Message parameters can be sorted into two sets:

 

Common parameters

The common parameters are:

Parameter name

(in French)

Parameter alias

(in English)

Example

Meaning
EMETTEUR SENDER MY_COMPANY Holds your company name
PRODUIT PRODUCT PRODUCT1 Tells us which insurance product you've sold
REFERENCE REFERENCE XYZ-123 Your unique reference (e.g. the booking refenrece in your system)
EMAIL EMAIL john.smith@gmail.com Customer's email. If present, we will send him/her the insurance document.
PRIME PREMIUM 123.45 The insurance premium that you've calculated. Currency is EUR.
NOMBRE NUMBER 2 Number of insured persons
For i ranging from 1 to NOMBRE...
GENREi TITLEi Mr Title of insured i 
PRENOMi FIRSTNAMEi John Firstname of insured i
NOMi LASTNAMEi SMITH Lastname of insured i

 

Parameters for CAP EXPLORER product

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:

 

Parameter name Example Meaning
DEPART 01/02/2021 Departure date (format dd/mm/yyyy)
RETOUR 15/02/2021 Return date (format dd/mm/yyyy)
FORMULE MR

AN=Annulation seule (Cancellation only)

MR=MultiRisque (Comprehensive)

CB=Complémentaire carte Bancaire (French card holder only)

AS=ASsistance seule (Assistance only)

PROVENANCE FR

Country of origin ISO code (2 characters; FR=France, ES=Spain, IT=Italy, etc.)

DESTINATION US,CA

Country of destination ISO code(s). When multiple destinations, use a comma.

MONTANTi 1234.56

Booking amount for insured i (currency is EUR).

For i ranging from 1 to the number of insured (see common parameters).

 

Parameters for TRANQUILOC product

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:

 

Parameter name Example Meaning
NUMPAX 4

Total number of participants.

Idealy, NUMPAX=NUMBER, meaning all participants are listed.

But, should you have only one name, then: NUMBER=1, hence only one insured name is listed (TITLE1, FIRSTNAME1, LASTNAME1), but NUMPAX gives the total number of participants.

ARRIVEE 01/02/2021 Date of arrival of guests (format dd/mm/yyyy)
DEPART 15/02/2021 Date of departure of guests (format dd/mm/yyyy)
DATE_RESA 28/11/2020

Date of booking (format dd/mm/yyyy)

FORMULE 1

1=Annulation seule (Cancellation only)

2=MultiRisque (Comprehensive)

MONTANT 1234.56

Total amount of rent (currency is EUR).

PROVENANCE FR

Country of origin ISO code (2 characters; FR=France, ES=Spain, IT=Italy, etc.)

DESTINATION IT

Country of destination ISO code.