"Notify" API - reference manual
Table of contents
Which strategy shall I choose?
Which transport shall I choose?
Other considerations with HTTPS/REST and FTP/FTPS
Other considerations HTTPS/REST
Other endpoint: check a contract
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):
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? |
JSON (HTTPS/REST) |
{ |
CSV (batch) |
EMETTEUR ; PRODUIT ; REFERENCE ; DEPART ; … // headers |
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.com | 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 https://api.chapka.fr/notify/?request=delete |
HTTP request parameters: Message in parameter « message » Signature in parameter « sign » |
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:
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) |
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 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:
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 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:
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. |
Parameters for product CAP ANNULATION
CAP ANNULATION is a cancellation only insurance.
The product pricing is based on the individual trip amount:
Trip amount | 0-300 | 300-600 | 600-900 | 900-1300 | 1300-1600 | 1600-2500 | 2500-3500 | 3500-4500 | 4500-6000 | 6000-8000 |
Premium | 18 | 22 | 30 | 39 | 52 | 70 | 82 | 108 | 124 | 174 |
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:
Parameter name | Example | Meaning |
DATE_RESA | 31/12/2021 | Booking date (format dd/mm/yyyy) |
DEPART | 05/03/2022 | Departure date (...) |
RETOUR | 31/03/2022 | Return date (...) |
PROVENANCE | FR | Country of origin |
DESTINATION | TZ | Country of destination |
MONTANTi | 1234.56 | Amount for pax i. Present for each pax. |