To start

In this first step, we are going to see how to use your API keys for the Cherry Checkout server identification. If you haven’t make it, connect you to your dashboard and get your test keys.


All the request you are making to the Cherry Checkout servers must be identify with a token. This token is made with your public keys, private keys, and a timestamp which must be increased for each calls. For security reason, this informations must by crypted from your side before you execute your request. We are here explaining the process to get this token.

Generate a timestamp

To invalidate the tokens after have been used, you must generate it with a timestamp. Or any value which increase with the time.

Generate a encrypted token

The method to generate a token must be employed with a very targeted manner. You have to encrypt your timestamp with your keys. The method change depending of the software langage but stay available for any else one.

  1. Concatenate your public keys with the timestamp that you have generate, in this order.
  2. Apply a function HMAC-SHA-256 on this concatenation, with an encrypting key, your private key.
  3. Encrypt the result in Base64.

Here how to apply this process with different software langage :

// Our API keys
$publicKey = 'pk_test_abc';
$privateKey = 'sk_test_456';

// Generate a timestamp
$timestamp = time();

// 1. Concatenate publicKey with timestamp
$concatenation = $publicKey.$timestamp;

// 2. HMAC-256 the concatenation, with our privateKey as encryption key
$hmac = hash_hmac('sha256', $concatenation, $privateKey);

// 3. Base 64 the result
$base64 = base64_encode($hmac);

/*  Require crypto
 *  See:
 *  Or: `npm install crypto --save`
var crypto = require('crypto');

// Our API Keys
var publicKey = 'pk_test_abc';
var privateKey = 'sk_test_456';

// Generate a timestamp
var timestamp = Math.floor( / 1000);

// 1. Concatenate publicKey with timestamp
var concatenation = publicKey + '' + timestamp;

// 2. HMAC-256 the concatenation, with our privateKey as encryption key
var hmac = new Buffer(crypto.createHmac('sha256', privateKey).update(concatenation).digest('hex'));

// 3. Base 64 the result
var base64 = hmac.toString('base64');
// Requirements
using System;
using System.Text;
using System.Security.Cryptography;
using System.IO;

// Our API keys
string publicKey = 'pk_test_abc';
string privateKey = 'sk_test_456';

// Generate a timestamp
int timestamp = (int)(DateTime.UtcNow.Subtract(new DateTime(1970, 1, 1))).TotalSeconds;

// 1. Concatenate publicKey with timestamp in a byte array
byte[] concatenation = Encoding.ASCII.GetBytes(publicKey + timestamp);

// 2. HMAC-256 the concatenation, with our privateKey as encryption key
HMACSHA256 fncHmac256 = new HMACSHA256(Encoding.ASCII.GetBytes(privateKey));
string hash = string.Join("", Array.ConvertAll(fncHmac256.ComputeHash(new MemoryStream(concatenation)), b => b.ToString("x2")));

// 3. Base 64 the result
string base64 = System.Convert.ToBase64String(System.Text.Encoding.UTF8.GetBytes(hash));

To verify that your method is working, you can use the following tool and compare with your result :

Detailed mode

Set-up the request headers

Now that you have encrypt your token, you’re ready to set-up your request headers.
If you’re using the tool bellow, you can see the headers examples.

timestamp {TIMESTAMP}
content-type application/json

First request

With your headers, you are now ready to execute your first request. You can use the method you want ( curl, Postman ou autre).

Make a call to the following road by filling the headers bellow.

Request :

Answer :

  "contract": {
    "name": "pragmatic",
    "charityOrderPercentage": 50,
    "gameOrderPercentage": 50,
    "nbOrderToDraw": 300,
    "priceScale": [
        "from": 0,
        "to": 60,
        "amount": 1
        "from": 60,
        "to": 140,
        "amount": 2
        "from": 140,
        "to": 220,
        "amount": 3
        "from": 220,
        "to": 300,
        "amount": 4
        "from": 300,
        "to": 999999,
        "amount": 5
  "plugin": {
     "fr": "<html>...</html>",
     "en": "<html>...</html>",
     "de": "<html>...</html>"
  "pdfContractLink": "",
  "pdfTermsAndConditionsLink": "",
  "charities": [
      "id": "5981e3ba116c24173362b357",
      "description": {
        "fr": "Description de l'œuvre caritative.",
        "en": "Description of the charity.",
        "de": "Beschreibung Liebe.",
        "es": "Descripción caridad.",
        "it": "Descrizione carità."
      "logo": {
        "fr": "",
        "en": "",
        "de": "",
        "es": "",
        "it": ""
      "name": {
        "fr": "Action Contre la Faim",
        "en": "Action Against Hunger",
        "de": "Aktion Gege, den Hunger",
        "es": "Acción Contra el Hambre",
        "it": "Azione Contro la Fame"
      "website": {
        "fr": "",
        "en": "",
        "de": "",
        "es": "",
        "it": ""
  "mode": "test"
200 - Success
contract Contract The Cherry Checkout contract conditions
plugin object An html code which will allow to display the Cherry Checkout banner. But you can also generate it yourself and skip this field.
pdfContractLink string The link to your contract.
pdfTermsAndConditionsLink string The link to the Game Terms and Conditions that you need to provide to your customer.
charities array of Charity The charities list linked to your account.
mode string The request mode ('test' if you’re using your test keys, or 'prod').
name string The type of contract you have with Cherry Checkout.
charityOrderPercentage integer For a participation, the part (over 100) given to the charity.
gameOrderPercentage integer For a participation, the part (over 100) used for the contest.
nbOrderToDraw integer Participation number needed to make a prize-draw.
priceScale PriceScale Participation amount needed, regarding the customer cart price.
id string Charity ID
name object Charity name
logo object Charity link
description object Charity description
website object Charity website URL
403 - Forbidden
missing authorization params 3401 The header 'authorization' is missing.
missing timestamp 3402 The header 'timestamp' is missing.
wrong authorization params 3403 The header 'authorization' isn’t well formated. It must contain your public key and your token, with the 'double dot' character.
invalid public key 3410 Your public key is not good.
invalid token 3411 Your token is not good.
invalid timestamp 3412 The timestamp you provided is expired.
invalid private key 3413 Your private key is not good.
no contract 3420 No contract has been set-up for your account. In this case please contact us.
restricted to test mode 3421 Your contract has not been validated yet, you can’t make any request in ‘production’ mode.


If you get an answer similar to the one described before, you’re ready for the next step. The identification works the same than for any request you are going to do.
Regarding this first request, it is not required for the next step, but if you do, we advise you to keep the answer in cache, because it will not change often.

Do you need help?

Don’t hesitate to contact our technical team if you have any problem.