Guide d'intégration
Tout ce dont vous avez besoin pour intégrer Chap Chap Pay dans votre application.
Introduction
Chap Chap Pay est une passerelle de paiement unifiée qui vous permet d'accepter et d'envoyer des paiements via plusieurs méthodes populaires en Guinée. Notre API RESTful est conçue pour être simple à intégrer tout en offrant des fonctionnalités avancées.
Méthodes de paiement supportées
PayCard
Orange Money
MTN MoMo
Visa / Mastercard
Nos services
E-Commerce
Générez des liens de paiement pour vos ventes en ligne.
Paiement QR
Créez des codes QR pour vos points de vente physiques.
PULL API
Collectez des paiements directement via API.
PUSH API
Envoyez de l'argent à vos clients programmatiquement.
Inscription
Pour commencer à utiliser Chap Chap Pay, vous devez créer un compte professionnel.
Contactez notre équipe commerciale
Envoyez un email à sales@chapchappay.com ou utilisez notre formulaire de contact.
Soumettez vos documents KYC
Fournissez : registre de commerce, pièce d'identité du dirigeant, et coordonnées bancaires.
Validation de votre compte
Notre équipe vérifie vos documents et active votre compte sous 24-48 heures ouvrées.
Accédez à votre tableau de bord
Connectez-vous avec votre compte Google, GitHub, Microsoft ou LinkedIn.
Clés API
Chaque appel API doit inclure votre clé API dans l'en-tête HTTP. Vous disposez de deux clés distinctes :
| Type | Usage |
|---|---|
| Clé Test | Développement et tests. Aucune transaction réelle. |
| Clé Production | Transactions réelles. Utilisez uniquement en production. |
Vos clés API sont des chaînes hexadécimales de 64 caractères, générées depuis votre tableau de bord dans la section Clés API.
CCP-Api-Key: a1b2c3d4e5f6...
Protégez vos clés
Ne partagez jamais vos clés API et ne les incluez pas dans votre code source public.
Agents
Les agents permettent de déléguer des accès spécifiques à votre compte sans partager vos identifiants. Il existe deux types d'agents :
Agent Personne
Pour vos employés ou collaborateurs. Accès via l'application mobile avec code d'accès et PIN.
Agent API
Pour vos intégrations techniques. Permet d'utiliser les API PULL, PUSH et Payout.
Agent Personne
Idéal pour vos caissiers, gérants ou tout membre de votre équipe qui doit accéder au compte depuis l'application mobile.
| Permission | Description |
|---|---|
| Voir le solde | Permet de consulter le solde du compte |
| Demander un règlement | Permet de soumettre des demandes de règlement |
| Voir les statistiques | Permet de consulter les statistiques de ventes |
Agent API
Destiné aux intégrations techniques nécessitant un accès programmatique aux services avancés.
| Permission | Description |
|---|---|
| PULL API | Permet de collecter des paiements via l'API PULL |
| PUSH API | Permet d'envoyer de l'argent via l'API PUSH |
| Payout API | Permet de déclencher des règlements via API |
Authentification des agents
Chaque agent reçoit un code d'accès (6 chiffres) et un code PIN (4 chiffres) lors de sa création.
Sécurité
Le code PIN est affiché une seule fois lors de la création. Vous pouvez le réinitialiser à tout moment depuis le tableau de bord.
Environnement
Toutes les API Chap Chap Pay sont accessibles via une URL unique.
https://chapchappay.com/api
Vous disposez de deux clés API distinctes pour gérer vos modes de fonctionnement :
| Clé | Usage |
|---|---|
| Clé Test | Pour le développement et les tests. Aucune transaction réelle n'est effectuée. |
| Clé Production | Pour les transactions réelles. À utiliser uniquement en production. |
Mode Test vs Production
Le mode est déterminé par la clé API utilisée. Utilisez votre clé Test pour le développement et votre clé Production pour les transactions réelles.
Pour les marchands (Pro)
L'application Pro est une PWA (Progressive Web App) destinée aux marchands et leurs agents. Elle permet de gérer les encaissements depuis un smartphone ou une tablette.
Connexion
L'agent se connecte avec son code d'accès à 6 chiffres. Si l'agent a oublié son code, il peut le récupérer par SMS en saisissant son numéro de téléphone.
Fonctionnalités
L'application offre plusieurs fonctionnalités selon les permissions de l'agent :
Codes QR
Afficher, partager et créer des codes QR pour les points de vente.
Liens de paiement
Créer et partager des liens de paiement avec un montant prédéfini.
Transactions
Consulter l'historique des transactions reçues.
Statistiques
Voir les statistiques de ventes (si permission accordée).
Permissions additionnelles
| Fonctionnalité | Permission |
|---|---|
| Voir le solde du compte | Voir le solde |
| Demander un règlement | Demander un règlement |
| Consulter les statistiques | Voir les statistiques |
Multi-comptes
Un agent peut sauvegarder plusieurs comptes dans l'application et basculer entre eux facilement. Cela est utile si une même personne gère plusieurs points de vente ou entreprises.
Prérequis
L'application Pro nécessite que le service Paiement QR soit activé pour votre entreprise.
Pour les clients (App)
L'application Client est destinée aux consommateurs pour scanner des codes QR, payer les marchands, et suivre leurs transactions.
Bientôt disponible
Cette application est en cours de développement et sera disponible prochainement à l'adresse /app.
Installation
Nos applications sont des PWA (Progressive Web Apps) qui s'installent directement depuis le navigateur, sans passer par un store.
Sur Android (Chrome)
- Ouvrez Chrome et accédez à l'application (
/pro) - Appuyez sur le menu ⋮ (trois points) en haut à droite
- Sélectionnez "Installer l'application" ou "Ajouter à l'écran d'accueil"
- Confirmez en appuyant sur "Installer"
- L'application apparaîtra sur votre écran d'accueil
Sur iOS (Safari)
- Ouvrez Safari et accédez à l'application (
/pro) - Appuyez sur le bouton Partager en bas de l'écran
- Faites défiler et sélectionnez "Sur l'écran d'accueil"
- Donnez un nom à l'application et appuyez sur "Ajouter"
- L'application apparaîtra sur votre écran d'accueil
Avantages d'une PWA
Une fois installée, l'application fonctionne comme une app native : écran complet, icône sur l'écran d'accueil, et accès hors ligne pour certaines fonctionnalités.
E-Commerce
Le service E-Commerce vous permet de générer des liens de paiement que vous pouvez partager avec vos clients ou intégrer dans votre site web.
Créer une opération
{
"amount": 10000
}
Réponse
{
"business_name": "Ma Boutique",
"operation_id": "2db401d7-cad3-449f-9e3e-ec2cf9e48472",
"order_id": "ORD12345",
"amount": 10000,
"amount_formatted": "10 000 GNF",
"payment_url": "https://chapchappay.com/pay/2db401d7-cad3-449f-9e3e-ec2cf9e48472",
"payment_methods": ["paycard", "orange_money", "mtn_momo"]
}
Redirigez votre client vers payment_url pour qu'il complète le paiement.
Paiement QR
Idéal pour les points de vente physiques, le paiement QR permet à vos clients de scanner un code et payer instantanément.
Créez un code QR
Depuis votre tableau de bord, créez un code QR pour votre point de vente.
Affichez le QR code
Imprimez et affichez le code QR à votre caisse ou point de vente.
Le client scanne et paie
Le client scanne le code, choisit sa méthode de paiement et confirme.
Recevez une notification
Vous êtes notifié instantanément du paiement via webhook.
PULL API
L'API PULL vous permet de collecter des paiements directement depuis votre application. Cette API nécessite un Agent API avec la permission PULL.
Signature HMAC requise
Les appels PULL API nécessitent l'en-tête CCP-HMAC-Signature calculé avec votre clé d'encryptage.
Initier un paiement
{
"account_number": "111222333",
"payment_channel": "paycard",
"amount": 10000
}
Canaux disponibles
| Canal | Valeur | Format du compte |
|---|---|---|
| PayCard | paycard |
Numéro PayCard (9 chiffres) |
| Orange Money | orange_money |
Numéro de téléphone (9 chiffres) |
| MTN MoMo | mtn_momo |
Numéro de téléphone (9 chiffres) |
PUSH API
L'API PUSH vous permet d'envoyer de l'argent vers les comptes de vos clients, partenaires ou employés. Cette API nécessite un Agent API avec la permission PUSH.
Signature HMAC requise
Les appels PUSH API nécessitent l'en-tête CCP-HMAC-Signature calculé avec votre clé d'encryptage.
Envoyer un paiement
{
"account_number": "111222333",
"payment_channel": "paycard",
"amount": 10000
}
Canaux disponibles
| Canal | Valeur |
|---|---|
| PayCard | paycard |
Solde suffisant requis
Assurez-vous que votre compte dispose d'un solde suffisant avant d'initier un transfert.
Webhooks
Les webhooks vous permettent de recevoir des notifications en temps réel lorsqu'une opération est terminée. Configurez votre notify_url lors de la création de l'opération.
Comment ça marche
Configurez votre URL de notification
Lors de la création d'une opération E-Commerce ou PULL/PUSH, spécifiez votre notify_url.
Recevez les notifications
Lorsque l'opération change de statut, nous envoyons une requête POST à votre URL avec les détails.
Vérifiez la signature
Chaque webhook inclut une signature HMAC que vous devez vérifier pour garantir l'authenticité.
Traitez la notification
Mettez à jour votre système en fonction du statut reçu (succès, échec, annulation, etc.).
Notifications multiples
Plusieurs webhooks peuvent être envoyés pour la même opération (ex: échec puis succès après une nouvelle tentative). Identifiez toujours l'opération via son ID unique et traitez les notifications de manière idempotente.
Statuts possibles
| Statut | Description |
|---|---|
success |
L'opération a été réalisée avec succès |
failed |
L'opération a échoué |
canceled |
L'opération a été annulée |
expired |
Le lien de paiement a expiré |
error |
Une erreur s'est produite |
Documentation technique
Consultez la Référence API pour les détails techniques : format des payloads, en-têtes HTTP et exemples de code.
Sécurité
La sécurité est au cœur de Chap Chap Pay. Nous utilisons plusieurs mécanismes pour protéger vos transactions.
Mesures de sécurité
Signature HMAC
Chaque requête sensible (PULL/PUSH) doit être signée avec HMAC-SHA256 pour garantir son intégrité.
Chiffrement TLS
Toutes les communications sont chiffrées via HTTPS/TLS 1.3.
Clés API séparées
Clés distinctes pour le test et la production, avec possibilité de rotation.
Agents & Permissions
Contrôle d'accès granulaire avec des agents et permissions spécifiques.
Bonnes pratiques
HTTPS obligatoire
Toutes vos URLs de callback doivent utiliser HTTPS.
Rotation des clés
Changez régulièrement vos clés API et mots de passe d'encryption.
Vérification webhooks
Validez toujours la signature HMAC des webhooks reçus.
Vérification des montants
Validez toujours les montants côté serveur avant de confirmer une transaction.
Implémentation technique
Consultez la Référence API pour les exemples de code de signature HMAC en Python, JavaScript, PHP et cURL.
Prêt à intégrer Chap Chap Pay ?
Consultez notre référence API complète ou contactez notre équipe.