Guide d'implementation API

$timestamp = time();
$nonce = bin2hex(random_bytes(16));
$body = json_encode(['amount' => 5000, 'currency' => 'XAF']);

$signature = hash_hmac('sha256', $timestamp . '.' . $body, $apiSecret);

$headers = [
    'X-API-KEY'    => $apiKey,
    'X-SIGNATURE'  => $signature,
    'X-TIMESTAMP'  => $timestamp,
    'X-NONCE'      => $nonce,
    'Content-Type' => 'application/json',
];

// Requete
{
    "amount": 5000,
    "currency": "XAF",
    "provider": "mtn_momo",
    "customer_identifier": "+242064000000",
    "description": "Commande #1234",
    "external_reference": "ORDER-2026-001",
    "environment": "sandbox",
    "metadata": { "order_id": "1234" }
}

// Reponse 201
{
    "id": "01952f3a-7abc-...",
    "status": "succeeded",
    "amount": 5000,
    "currency": "XAF",
    "provider": "mtn_momo",
    "environment": "sandbox",
    "created_at": "2026-03-09T10:00:00+00:00"
}

// Paiement en production
{
    "amount": 5000,
    "currency": "XAF",
    "provider": "mtn_momo",
    "customer_identifier": "+242064000000",
    "environment": "production"
}

// Paiement en sandbox (defaut si omis)
{
    "amount": 5000,
    "currency": "XAF",
    "provider": "mtn_momo",
    "customer_identifier": "+242064000000",
    "environment": "sandbox"
}

{
    "amount": 10000,
    "currency": "XAF",
    "payment_method": "MTN",
    "customer_phone": "242060000000",
    "callback_url": "https://example.com/webhook",
    "reference": "CMD-2026-001",
    "description": "Commande en ligne",
    "environment": "sandbox"
}

// Methodes acceptees : MTN, AIRTEL, PAYPAL, 2CHECKOUT
// environment : "sandbox" (defaut) ou "production"

// Remboursement total
{ "payment_intent_id": "01952f3a-7abc-..." }

// Remboursement partiel
{
    "payment_intent_id": "01952f3a-7abc-...",
    "amount": 2500,
    "reason": "Client insatisfait"
}

// Reponse 201
{
    "id": "01952f3b-...",
    "status": "succeeded",
    "amount": 2500,
    "payment_intent_id": "01952f3a-7abc-..."
}

// Requete
{
    "to": "[email protected]",
    "subject": "Confirmation de paiement",
    "body_html": "<h1>Merci !</h1><p>Votre paiement a ete confirme.</p>",
    "body_text": "Merci ! Votre paiement a ete confirme.",
    "from_email": "[email protected]",
    "from_name": "Mon Application",
    "provider": "smtp",
    "environment": "production"
}

// Reponse 200
{
    "success": true,
    "message_id": "abc123",
    "provider": "smtp"
}

// Requete
{
    "to": "+242064000000",
    "message": "Votre code de validation est : 123456",
    "from": "PAYHUB",
    "provider": "allmysms",
    "environment": "production"
}

// Reponse 200
{
    "success": true,
    "message_id": "sms_xyz",
    "provider": "allmysms"
}

POST /api/v1/webhook-endpoints
{
    "url": "https://example.com/webhooks/payhub",
    "events": ["payment_intent.succeeded", "payment_intent.failed"]
}

// events vide = recevoir tous les evenements

$header = $_SERVER['HTTP_X_PAYHUB_SIGNATURE'];
preg_match('/t=(\d+),v1=(.+)/', $header, $m);
$timestamp = $m[1];
$receivedSig = $m[2];

$payload = file_get_contents('php://input');
$expected = hash_hmac('sha256',
    $timestamp . '.' . $payload, $endpointSecret);

if (!hash_equals($expected, $receivedSig)) {
    http_response_code(401);
    exit('Signature invalide');
}

// Verifier la fraicheur (< 5 min)
if (abs(time() - (int)$timestamp) > 300) {
    http_response_code(401);
    exit('Timestamp expire');
}

$event = json_decode($payload, true);
// Traiter l'evenement...

{
    "event": "payment_intent.succeeded",
    "timestamp": "2026-03-09T10:05:00+01:00",
    "data": {
        "id": "01952f3a-7abc-...",
        "status": "succeeded",
        "amount": 5000,
        "currency": "XAF",
        "provider": "mtn_momo",
        "customer_identifier": "+242064000000"
    }
}

{ "error": "error_type", "message": "Description lisible" }

use PayHub\PayHubClient;

$client = new PayHubClient('pk_live_xxx', 'sk_live_xxx',
    'https://pay.example.com');

// Creer un paiement
$payment = $client->createPayment(
    amount: 5000,
    currency: 'XAF',
    provider: 'mtn_momo',
    customerIdentifier: '242060000000',
    options: ['description' => 'Commande #1234',
              'environment' => 'production']
);
echo $payment['status']; // "succeeded"

// Rembourser
$refund = $client->createRefund($payment['id'],
    amount: 2500, reason: 'Retour produit');

// Verifier un webhook
$valid = PayHubClient::verifyWebhookSignature(
    $rawBody, $signatureHeader, $endpointSecret);

const PayHub = require('@senprog/payhub-sdk');

const client = new PayHub('pk_live_xxx', 'sk_live_xxx',
    'https://pay.example.com');

// Creer un paiement
const payment = await client.createPayment(
    5000, 'XAF', 'mtn_momo', '242060000000',
    { description: 'Commande #1234', environment: 'production' }
);
console.log(payment.status); // "succeeded"

// Rembourser
const refund = await client.createRefund(payment.id,
    2500, 'Retour produit');

// Verifier un webhook (Express.js)
app.post('/webhook', (req, res) => {
    const valid = PayHub.verifyWebhookSignature(
        req.rawBody, req.headers['x-payhub-signature'],
        process.env.WEBHOOK_SECRET);
    if (!valid) return res.status(401).end();
    // Traiter l'evenement...
    res.status(200).end();
});

import hmac, hashlib, time, secrets, json, requests

API_KEY = 'pk_live_xxx'
API_SECRET = 'sk_live_xxx'
BASE_URL = 'https://pay.example.com'

def payhub_request(method, path, body=None):
    timestamp = str(int(time.time()))
    nonce = secrets.token_hex(16)
    body_str = json.dumps(body) if body else ''
    signature = hmac.new(
        API_SECRET.encode(),
        f'{timestamp}.{body_str}'.encode(),
        hashlib.sha256
    ).hexdigest()

    resp = requests.request(method, BASE_URL + path,
        headers={
            'X-API-KEY': API_KEY,
            'X-SIGNATURE': signature,
            'X-TIMESTAMP': timestamp,
            'X-NONCE': nonce,
            'Content-Type': 'application/json',
        },
        data=body_str or None)
    return resp.json()

# Creer un paiement
payment = payhub_request('POST', '/api/v1/payment-intents', {
    'amount': 5000,
    'currency': 'XAF',
    'provider': 'mtn_momo',
    'customer_identifier': '242060000000',
    'environment': 'production',
})
print(f"ID: {payment['id']}, Status: {payment['status']}")

TIMESTAMP=$(date +%s)
BODY='{"amount":5000,"currency":"XAF","provider":"mtn_momo","customer_identifier":"242060000000","environment":"production"}'
SIGNATURE=$(echo -n "${TIMESTAMP}.${BODY}" | openssl dgst -sha256 -hmac "$API_SECRET" | cut -d' ' -f2)

curl -X POST https://pay.example.com/api/v1/payment-intents \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: $API_KEY" \
  -H "X-SIGNATURE: $SIGNATURE" \
  -H "X-TIMESTAMP: $TIMESTAMP" \
  -H "X-NONCE: $(uuidgen)" \
  -d "$BODY"