FrikPay API ← Guide de démarrage rapide
API docs by Redocly

API de paiement FrikPay (1.0.0)

Download OpenAPI specification:

URL: https://frikpay.digital

API publique FrikPay pour initier des paiements Mobile Money et suivre leur statut, en environnement sandbox (tests, aucun débit réel) et production (paiements réels).

Consultez le guide Démarrage rapide avant d'intégrer cette API : création de compte marchand, génération des clés API, premier paiement de test.

Guide de démarrage rapide

Limites actuelles — à lire avant d'intégrer

  • Devise : seul XOF (Franc CFA – BCEAO) est accepté aujourd'hui. Toute autre devise est refusée.
  • Fournisseur / réseau : seul MTN Mobile Money (Bénin) est actif en production. Moov Money et Kkiapay ne sont pas activés sur cette plateforme, quelle que soit la valeur envoyée.
  • Pays : seul BJ (Bénin) est pris en charge.
  • Webhooks : pas encore disponibles de façon fiable. Utilisez le polling sur GET /api/v1/payments/{reference} pour suivre le statut d'un paiement. Voir la page Webhooks.

Authentification

Toutes les requêtes doivent inclure deux en-têtes HTTP :

En-tête Obligatoire Description
X-FRIKLABEL-PUBLIC-KEY Oui Clé publique de votre application (pk_test_... en sandbox, pk_live_... en production)
X-FRIKLABEL-SECRET-KEY Oui Clé secrète associée (sk_test_... / sk_live_...)
X-FRIKLABEL-ENVIRONMENT Non sandbox ou production — à utiliser uniquement en cas d'ambiguïté ; par défaut l'environnement est déterminé automatiquement par le type de clé utilisée

L'environnement effectif d'une requête est toujours celui de la clé utilisée : une clé pk_test_... opère en sandbox, une clé pk_live_... opère en production. Il n'y a pas d'URL distincte pour le sandbox — c'est la clé qui détermine l'environnement, sur la même base d'URL.

Les clés API se génèrent depuis le portail marchand FrikPay (https://merchant.frikpay.digital, menu Applications → Clés API), pas via cette API publique.

Accès sandbox vs production

  • Sandbox : disponible immédiatement après la création de votre application et la génération de vos clés sandbox. Aucune vérification KYC n'est requise. Aucun appel n'est fait à un opérateur réel ; les paiements sandbox sont simulés en base de données à partir d'un numéro de téléphone de test préconfiguré.
  • Production : nécessite que le KYC de votre compte marchand soit approuvé (kyc_status = approved). Si ce n'est pas le cas, toute requête authentifiée avec une clé de production est refusée avec le message KYC marchand non validé pour la production. (HTTP 401).

Format des réponses

Toutes les réponses sont au format JSON avec l'enveloppe suivante :

{
  "success": true,
  "message": "Description lisible",
  "data": { }
}

En cas d'erreur :

{
  "success": false,
  "message": "Description lisible de l'erreur",
  "errors": []
}

Important : l'API ne renvoie pas de champ code d'erreur machine-lisible aujourd'hui. Pour distinguer les cas d'erreur côté intégration, basez-vous sur le code HTTP et, si nécessaire, sur le texte du message (en français). Le tableau des erreurs de chaque endpoint ci-dessous liste les messages exacts observés dans le code.

Paiements

Initier un paiement et suivre son statut.

Initier un paiement

Initie un paiement Mobile Money pour le montant, la devise et le numéro de téléphone client fournis.

Idempotence

merchant_reference sert de clé d'idempotence. Si vous rejouez une requête avec la même merchant_reference pour le même marchand, l'API ne crée pas de doublon : elle renvoie HTTP 200 avec success: false, le message Requête déjà traitée., et la transaction d'origine dans le champ errors (et non data — voir l'exemple Requête déjà traitée). Traitez cette réponse comme un succès idempotent, pas comme une erreur bloquante.

Comportement sandbox vs production

  • Sandbox : le paiement est simulé, sans aucun appel à un opérateur réel. Le résultat (succès, échec, etc.) dépend d'un numéro de téléphone de test préconfiguré par l'équipe FrikPay pour votre environnement — voir le guide de démarrage pour la liste des numéros de test disponibles. La réponse contient alors des champs supplémentaires (sandbox: true, fee_amount, customer_debited_amount, beneficiary_net_amount, etc.).
  • Production : un vrai paiement Mobile Money MTN est déclenché. La réponse HTTP confirme uniquement que la demande de paiement a été transmise (status: "pending") — pas que le client a payé. Utilisez GET /api/v1/payments/{reference} pour connaître le statut final (le client valide le paiement sur son téléphone, hors bande).
Authorizations:
(PublicKeySecretKey)
header Parameters
X-FRIKLABEL-ENVIRONMENT
string
Enum: "sandbox" "production"

sandbox ou production. Optionnel — à ne fournir qu'en cas de besoin explicite de forcer une vérification d'environnement ; normalement l'environnement effectif est déjà déterminé par le type de clé API utilisée.

Request Body schema: application/json
required
merchant_reference
required
string

Identifiant unique de la commande côté marchand. Sert de clé d'idempotence : la même valeur pour le même marchand ne crée jamais deux transactions.

amount
required
number <double>

Montant en XOF (nombre entier ou décimal), doit être strictement supérieur à 0.

currency
required
string
Value: "XOF"

Seule la devise XOF est acceptée aujourd'hui.

customer_phone
required
string

Numéro Mobile Money du client, réseau MTN Bénin.

payment_method
string
Default: "mobile_money"
Value: "mobile_money"

Optionnel. Seule la valeur mobile_money est prise en charge ; c'est la valeur par défaut.

country_code
string
Default: "BJ"
Value: "BJ"

Optionnel. Seul BJ (Bénin) est pris en charge ; c'est la valeur par défaut.

description
string

Optionnel. Libellé libre affiché dans les journaux et les relevés internes FrikPay.

customer_name
string

Optionnel. Nom du client final.

customer_email
string <email>

Optionnel. E-mail du client final.

fee_bearer
string
Default: "beneficiary"
Enum: "beneficiary" "customer"

Optionnel. Qui supporte les frais de transaction : beneficiary (vous, marchand — par défaut) ou customer (le client final, montant débité majoré des frais).

object

Optionnel. Objet libre (clé/valeur) que vous pouvez utiliser pour rattacher vos propres identifiants internes.

Responses

Response Schema: application/json
success
boolean
message
string
data
object
errors
object

Présent uniquement dans le cas "Requête déjà traitée" (rejeu idempotent) — contient alors la transaction d'origine.

Response Schema: application/json
success
boolean
message
string

Message d'erreur en français, à afficher tel quel ou à journaliser.

errors
any

Généralement un tableau vide ; peut contenir des données contextuelles selon l'endpoint (voir description).

Response Schema: application/json
success
boolean
message
string

Message d'erreur en français, à afficher tel quel ou à journaliser.

errors
any

Généralement un tableau vide ; peut contenir des données contextuelles selon l'endpoint (voir description).

Request samples

Content type
application/json
Example
{
  • "merchant_reference": "CMD-2026-000123",
  • "amount": 1500,
  • "currency": "XOF",
  • "customer_phone": "22961000001"
}

Response samples

Content type
application/json
Example
{
  • "success": true,
  • "message": "Paiement initié avec succès",
  • "data": {
    }
}

Consulter le statut d'un paiement

Renvoie le statut courant d'une transaction, identifiée par la reference_id FrikPay renvoyée lors de la création du paiement (le champ data.reference_id de la réponse de POST /api/v1/payments, au format FRIK-...) — pas votre merchant_reference.

La transaction doit appartenir au marchand authentifié par les clés API utilisées ; sinon l'API répond 404 Transaction introuvable. même si la référence existe pour un autre marchand.

C'est le moyen recommandé de connaître l'issue réelle d'un paiement en production : interrogez cet endpoint après l'initiation (par exemple toutes les 3 à 5 secondes pendant 1 à 2 minutes) jusqu'à obtenir un statut terminal (success ou failed). Les webhooks ne sont pas encore fiables — voir le guide de démarrage.

Authorizations:
(PublicKeySecretKey)
path Parameters
reference
required
string
Example: FRIK-20260821143012-9F2A7C1B

reference_id FrikPay de la transaction (format FRIK-...).

header Parameters
X-FRIKLABEL-ENVIRONMENT
string
Enum: "sandbox" "production"

sandbox ou production. Optionnel — à ne fournir qu'en cas de besoin explicite de forcer une vérification d'environnement ; normalement l'environnement effectif est déjà déterminé par le type de clé API utilisée.

Responses

Response Schema: application/json
success
boolean
message
string
object (PaymentTransaction)

Représentation publique d'une transaction de paiement.

Response Schema: application/json
success
boolean
message
string

Message d'erreur en français, à afficher tel quel ou à journaliser.

errors
any

Généralement un tableau vide ; peut contenir des données contextuelles selon l'endpoint (voir description).

Request samples 

curl https://api.frikpay.digital/api/v1/payments/FRIK-20260821143012-9F2A7C1B \
  -H "X-FRIKLABEL-PUBLIC-KEY: pk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-FRIKLABEL-SECRET-KEY: sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Success",
  • "data": {
    }
}