Démarrer

Authentification

Chaque appel à l'API est authentifié par votre clé secrète, envoyée dans l'en-tête Authorization. Il n'y a ni jeton à rafraîchir ni session à maintenir.

Récupérer vos clés

Connectez-vous à votre tableau de bord, puis ouvrez Développeurs → API (/admin/dev/api). Vous y trouvez deux valeurs :

Clé	Rôle
`public_key`	Identifie votre compte. Elle n'ouvre aucun droit à elle seule et peut apparaître dans un journal.
`secret_key`	Autorise les appels. Elle vaut un mot de passe : elle ne doit jamais quitter votre serveur.

Chaque valeur existe en deux exemplaires, un par environnement. Le préfixe les distingue : sk_test_… pilote le bac à sable, sk_… la production. C'est la clé, et elle seule, qui détermine le mode — il n'y a aucun paramètre à passer dans vos requêtes.

Ne l'exposez jamais côté client

La secret_key permet de créer des paiements, de demander des remboursements et de lire tout votre historique. Elle n'a rien à faire dans une application mobile, dans du JavaScript de navigateur ni dans un dépôt Git. Gardez-la dans une variable d'environnement côté serveur. Si elle a fuité, régénérez-la immédiatement depuis le tableau de bord. Une clé sk_test_… qui traîne est moins grave — elle ne donne accès qu'à des données fictives — mais elle expose tout de même votre configuration webhook : traitez-la avec le même soin.

Signer une requête

Envoyez la clé secrète en bearer token sur chaque appel :

curl https://api.mivaapay.com/api/v1/balance \
  -H "Authorization: Bearer $MIVAAPAY_SECRET_KEY"

$response = Http::withToken(env('MIVAAPAY_SECRET_KEY'))
    ->get('https://api.mivaapay.com/api/v1/balance');

$balance = $response->json('data');

const res = await fetch('https://api.mivaapay.com/api/v1/balance', {
  headers: { Authorization: `Bearer ${process.env.MIVAAPAY_SECRET_KEY}` }
});

const { data } = await res.json();

import os, requests

res = requests.get(
    'https://api.mivaapay.com/api/v1/balance',
    headers={'Authorization': f"Bearer {os.environ['MIVAAPAY_SECRET_KEY']}"},
    timeout=30,
)
data = res.json()['data']

Les requêtes qui envoient un corps doivent aussi porter Content-Type: application/json.

Forme historique

Les intégrations antérieures envoient la paire d'en-têtes X-Public-Key et X-Secret-Key. Elle reste acceptée et continuera de l'être sur toute la durée de vie de v1, mais les nouvelles intégrations doivent utiliser Authorization: Bearer.

Forme historique — toujours acceptée

curl https://api.mivaapay.com/api/v1/balance \
  -H "X-Public-Key: $MIVAAPAY_PUBLIC_KEY" \
  -H "X-Secret-Key: $MIVAAPAY_SECRET_KEY"

Erreurs d'authentification

HTTP	Code	Cause
401	`unauthorized`	En-tête absent, ou clé inconnue. Vérifiez que vous envoyez bien la clé secrète.
401	`key_expired`	La clé a passé sa date d'expiration. Régénérez-la depuis le tableau de bord.
403	`merchant_inactive`	Votre compte marchand n'est pas actif : KYC en cours, ou compte suspendu. Seul le live est concerné : vos clés `sk_test_…` restent utilisables, pour que l'intégration puisse avancer pendant l'instruction du dossier.

401 — clé manquante

{
  "success": false,
  "error": {
    "code": "unauthorized",
    "message": "Clé API manquante. Envoyez l'en-tête « Authorization: Bearer <secret_key> »."
  }
}

Portée d'une clé

Une clé est rattachée à un seul compte marchand. Tout ce que vous lisez ou créez avec elle appartient à ce compte, et il est impossible d'atteindre les données d'un autre marchand : les listes et les recherches par référence sont toutes filtrées côté serveur. Si vous exploitez plusieurs comptes marchands, chacun a ses propres clés.

Rotation

Régénérer vos clés depuis le tableau de bord invalide immédiatement les anciennes, dans les deux environnements à la fois : il n'y a pas de période de recouvrement. Prévoyez donc de déployer la nouvelle valeur en même temps que vous la générez, de préférence hors des heures d'affluence.

Bonnes pratiques

Stockez la clé dans une variable d'environnement ou un gestionnaire de secrets, jamais en dur.
N'écrivez jamais l'en-tête Authorization dans vos journaux applicatifs.
Utilisez des clés distinctes par application, pour pouvoir en révoquer une sans tout casser.
Faites tourner la clé après tout départ d'une personne y ayant eu accès.