Docs API

Intégrations

SDK officiels

Deux clients fins, sans dépendance de runtime, qui enveloppent l'API v1 telle que documentée ici : mêmes champs, mêmes codes d'erreur, même schéma de signature de webhook. Ce que vous lisez ailleurs dans cette doc s'applique directement.

LangagePaquetCode source
Node.js 18+ npm install asukapay github.com/lkousse/asukapay_sdk_js
PHP 8.1+ composer require asukapay/sdk github.com/lkousse/asukapay_sdk_php

Installation

npm install asukapay
composer require asukapay/sdk

Créer un paiement

external_id rend l'appel idempotent — voir Créer un paiement. 

import { AsukaPay } from 'asukapay';

const client = new AsukaPay({ secretKey: process.env.ASUKAPAY_SECRET_KEY });

const payment = await client.payments.create({
  amount: 5000,
  operator: 'mtn',
  phone_number: '22997000000',
  external_id: 'cmd_1042',
});
use Asukapay\Client;

$client = new Client($_ENV['ASUKAPAY_SECRET_KEY']);

$payment = $client->payments->create([
    'amount' => 5000,
    'operator' => 'mtn',
    'phone_number' => '22997000000',
    'external_id' => 'cmd_1042',
]);

Gérer les erreurs

Chaque erreur porte le code stable de la référence des erreurs — branchez-vous toujours dessus, jamais sur le message. 

import { AsukaPayApiError } from 'asukapay';

try {
  await client.payments.create({ amount: 5000, operator: 'mtn', phone_number: '22997000000' });
} catch (err) {
  if (err instanceof AsukaPayApiError) {
    if (err.code === 'invalid_request') afficherErreursChamps(err.details);
    else if (err.code === 'rate_limited') reprogrammer(err.retryAfter);
    else incidentTechnique(err.code);
  }
}
use Asukapay\Exception\ApiException;

try {
    $client->payments->create(['amount' => 5000, 'operator' => 'mtn', 'phone_number' => '22997000000']);
} catch (ApiException $e) {
    match ($e->getErrorCode()) {
        'invalid_request' => afficherErreursChamps($e->getDetails() ?? []),
        'rate_limited' => reprogrammer($e->getRetryAfter()),
        default => incidentTechnique($e->getErrorCode()),
    };
}

Vérifier un webhook

Le calcul est celui documenté dans Vérifier la signature : HMAC SHA-256 sur le corps brut, tolérance de 5 minutes. Les deux SDK l'implémentent pour vous. 

import { verifyWebhookSignature, AsukaPayWebhookSignatureError } from 'asukapay';

app.post('/webhooks/asukapay', express.raw({ type: 'application/json' }), (req, res) => {
  try {
    const event = verifyWebhookSignature({
      payload: req.body.toString(),
      header: req.get('X-AsukaPay-Signature') ?? '',
      secret: process.env.ASUKAPAY_WEBHOOK_SECRET,
    });

    // … traitement idempotent sur event.id, puis :
    res.status(204).end();
  } catch (err) {
    if (err instanceof AsukaPayWebhookSignatureError) return res.status(400).send(err.message);
    throw err;
  }
});
use Asukapay\Webhook;
use Asukapay\Exception\WebhookSignatureException;

$raw = file_get_contents('php://input');
$header = $_SERVER['HTTP_X_ASUKAPAY_SIGNATURE'] ?? '';

try {
    $event = Webhook::verifySignature($raw, $header, $_ENV['ASUKAPAY_WEBHOOK_SECRET']);
    // … traitement idempotent sur $event['id'], puis :
    http_response_code(204);
} catch (WebhookSignatureException $e) {
    http_response_code(400);
    echo $e->getMessage();
}

Ce qui est couvert

Les deux SDK exposent l'intégralité de l'API v1 : paiements, remboursements, liens de paiement, catalogue et simulation de frais, solde, configuration et journal des webhooks. Rien au-delà — pas de rétro-compatibilité automatique, pas de logique métier ajoutée : ce que fait l'API, le SDK le relaie tel quel.

Pas encore de SDK Python ou Go

Pour l'instant, deux langages seulement. En attendant, la référence API reste directement utilisable avec n'importe quel client HTTP — les exemples de cette documentation couvrent déjà cURL, Python et Node.js sans SDK.

Précédent ← WooCommerce