Terminaux de paiement

Un terminal de paiement (TPE, caisse, tablette de vendeur) encaisse avec sa propre clé, sans jamais connaître la clé secrète de votre service. Vous le créez, il s'active avec un code à usage unique, et vous pouvez le couper à tout moment. Ses transactions portent le canal pos, le terminal et, le cas échéant, le collaborateur qui a encaissé.

Principe

1. Création : depuis votre serveur (clé secrète) ou le portail (Développeurs › Terminaux de paiement), vous créez un terminal ; CashChap remet un code d'activation à usage unique, valable 15 minutes.
2. Activation : le terminal envoie ce code ; il reçoit en retour sa clé de terminal (tk_live_… ou tk_test_…), affichée une seule fois et conservée par CashChap sous forme d'empreinte.
3. Encaissement : le terminal appelle l'API v2 avec Authorization: Bearer tk_…, comme n'importe quel client.
4. Validation par CashChap : l'équipe CashChap valide le terminal pour qu'il bénéficie du tarif des terminaux. Tant qu'il n'est pas validé, il encaisse normalement au tarif du canal api.
5. Révocation : vous révoquez le terminal (perte, vol, fin de contrat) ; sa clé est refusée immédiatement (terminal_revoked).

Le titulaire du service reçoit un e-mail à l'activation, à la validation et à la révocation d'un terminal.

Créer un terminal

POST /v2/terminals — clé secrète. Corps : label (nom, 80 caractères au plus, obligatoire), point_of_sale (lieu, 120 caractères au plus), kind (pos par défaut). Réponse 201 :

curl -X POST https://api.cashchap.com/v2/terminals \
  -H "Authorization: Bearer $CASHCHAP_CLE_SECRETE" \
  -H "Content-Type: application/json" \
  -d '{ "label": "Caisse 1", "point_of_sale": "Boutique de Cadjèhoun" }'

{
  "data": {
    "id": "5d4c3b2a-1f0e-4d9c-8b7a-6f5e4d3c2b1a",
    "object": "terminal",
    "kind": "pos",
    "label": "Caisse 1",
    "point_of_sale": "Boutique de Cadjèhoun",
    "status": "pending_activation",
    "approved": false,
    "mode": "live",
    "key_last4": null,
    "device": { "model": null, "serial": null },
    "last_seen_at": null,
    "created_at": "2026-10-11T08:00:00Z",
    "revoked_at": null,
    "activation_code": "K7MP-Q2XA",
    "activation_expires_at": "2026-10-11T08:15:00Z"
  },
  "meta": { "request_id": "req_…" }
}

Le code d'activation n'est montré qu'une fois : transmettez-le à la personne qui installe le terminal. Le mode du terminal (Live ou Sandbox) est celui de la clé secrète utilisée.

Activer le terminal

POST /v2/terminals/activate — sans clé, depuis le terminal. Corps : activation_code et, facultatif, device (model, serial).

curl -X POST https://api.cashchap.com/v2/terminals/activate \
  -H "Content-Type: application/json" \
  -d '{ "activation_code": "K7MP-Q2XA", "device": { "model": "Sunmi V2", "serial": "V2-001234" } }'

{
  "data": {
    "terminal": { "id": "5d4c3b2a-…", "object": "terminal", "status": "active", "approved": false, "...": "..." },
    "terminal_key": "tk_live_8fQ2…"
  },
  "meta": { "request_id": "req_…" }
}

• Gardez terminal_key dans le stockage sécurisé du terminal : elle ne sera plus jamais affichée. Perdue, elle ne se récupère pas : révoquez le terminal et créez-en un autre.
• Code inconnu, déjà utilisé ou expiré : 422 activation_code_invalid. Au plus 5 essais par heure depuis une même adresse.

Encaisser depuis un terminal

Avec sa clé, un terminal peut appeler :

Un terminal ne peut ni faire de retrait, ni gérer d'autres terminaux (terminal_not_allowed), ni accepter la carte (payment_method_not_allowed_on_channel). Les données des clients lui sont rendues masquées.

Sessions de caisse

Quand plusieurs collaborateurs se relaient sur une caisse, votre serveur ouvre pour chacun une session de caisse : un jeton ts_… de courte durée qui encaisse au nom de ce collaborateur. Ma boutique, dans le portail, fonctionne ainsi.

POST /v2/terminals/{id}/sessions — clé secrète. Corps : operator_id (identifiant du collaborateur, ou absent pour le titulaire) et ttl_minutes (1 à 480, 480 par défaut).

{
  "data": {
    "id": "0e9d8c7b-6a5f-4e3d-2c1b-0a9f8e7d6c5b",
    "object": "terminal_session",
    "token": "ts_Yb3k…",
    "expires_at": "2026-10-11T16:00:00Z",
    "terminal": { "id": "5d4c3b2a-…", "object": "terminal", "...": "..." },
    "operator": { "id": "c1d2e3f4-…", "name": "Afi Dossou", "kind": "collaborator" }
  },
  "meta": { "request_id": "req_…" }
}

• Le jeton s'utilise comme une clé : Authorization: Bearer ts_…. Les transactions portent alors operator (le collaborateur).
• Le rôle du collaborateur doit lui permettre d'encaisser (operator_cannot_collect, operator_suspended sinon).
• Session expirée ou fermée : 401 session_expired ; ouvrez-en une nouvelle.
• Fermer une session (fin de service, déconnexion) : POST /v2/terminals/{id}/sessions/{session}/revoke avec la clé secrète.
• L'ouverture d'une session directement depuis un terminal partagé (avec un code personnel du caissier) n'est pas encore disponible (sessions_by_terminal_disabled) : ouvrez les sessions depuis votre serveur.

Lister et révoquer

• GET /v2/terminals (clé secrète) : vos terminaux, avec status (pending_activation, active, revoked), approved (validé par CashChap), appareil, 4 derniers caractères de la clé et dernière activité. GET /v2/terminals/{id} : un terminal (clé secrète ou le terminal lui-même).
• POST /v2/terminals/{id}/revoke (clé secrète) : révocation définitive, sessions comprises. Un terminal déjà révoqué répond 409 cannot_revoke.
• Dans le portail, Développeurs › Terminaux de paiement (titulaire et administrateurs) montre les mêmes informations pour l'environnement affiché, avec un bouton Révoquer par terminal, et le bloc Créer un terminal : nom du terminal, point de vente (facultatif) et votre mot de passe, puis Créer le terminal ; le code d'activation s'affiche une seule fois.

Tarifs des terminaux

CashChap peut appliquer aux terminaux des frais différents de ceux de l'API ou du widget, et même un taux propre à un terminal donné. La règle appliquée figure dans fees.rule de chaque transaction (channel = pos, terminal = l'identifiant du terminal le cas échéant). Un terminal non encore validé par CashChap paie le tarif du canal api. Voir frais par canal et par terminal.