Guide d'intégration

Demandez la création de votre compte marchand auprès de l'équipe Neka Paie. Vous recevrez :

• Un API Key et un API Secret (à stocker en coffre-fort).
• Un accès au portail marchand.
• L'environnement Sandbox configuré pour vos tests.

Voici un exemple complet en PHP qui initie un paiement et redirige le client vers Orange Money.

PHP<?php
// 1. Configuration
$apiBase = 'https://nekapaie.com/api/v1';
$apiKey = 'nk_test_xxxxxxxxxxxxxxxxxxxxxxxx';
$apiSecret = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx';

// 2. Préparation du payload
$payload = [
    'merchant_order_id' => 'order_' . uniqid(),
    'amount' => 50000,                  // 500 XOF en centimes
    'currency' => 'XOF',
    'customer_msisdn' => '+22376123456',
    'country_code' => 'ML',
    'return_url' => 'https://shop.example.com/success',
    'notify_url' => 'https://api.example.com/webhooks/nekapay',
    'metadata' => ['order_id' => 1234, 'user_id' => 5678],
];

// 3. Signature HMAC
$body = json_encode($payload);
$timestamp = (string) time();
$signature = hash_hmac('sha256', $timestamp . $body, $apiSecret);

// 4. Envoi de la requête
$ch = curl_init($apiBase . '/payments/cashin');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'X-NekaPay-Key: ' . $apiKey,
    'X-NekaPay-Timestamp: ' . $timestamp,
    'X-NekaPay-Signature: ' . $signature,
]);
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$data = json_decode($response, true);

if ($httpCode === 202) {
    // 5. Rediriger l'utilisateur vers la page de paiement Orange
    header('Location: ' . $data['data']['payment_url']);
    exit;
} else {
    // Gérer l'erreur
    error_log('Cashin failed: ' . $response);
}

Sur votre URL notify_url, vérifiez la signature et mettez à jour votre commande.

PHP<?php
// webhook.php

$apiSecret = getenv('NEKAPAY_API_SECRET');

$timestamp = $_SERVER['HTTP_X_NEKAPAY_TIMESTAMP'] ?? '';
$signature = $_SERVER['HTTP_X_NEKAPAY_SIGNATURE'] ?? '';
$body = file_get_contents('php://input');

// Anti-replay
if (!$timestamp || abs(time() - (int)$timestamp) > 300) {
    http_response_code(401);
    exit('Timestamp invalid');
}

// Vérification de signature
$expected = hash_hmac('sha256', $timestamp . $body, $apiSecret);
if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    exit('Signature mismatch');
}

// Traitement
$event = json_decode($body, true);

switch ($event['status']) {
    case 'SUCCESS':
        markOrderAsPaid($event['merchant_order_id'], $event['transaction_id']);
        break;
    case 'FAILED':
    case 'EXPIRED':
        markOrderAsFailed($event['merchant_order_id'], $event['status']);
        break;
    case 'REVERSED':
        refundOrder($event['merchant_order_id']);
        break;
}

http_response_code(200);
echo json_encode(['received' => true]);

Pour reverser des fonds à un client (gain de jeu, remboursement, salaire) :

PHP$payload = [
    'merchant_order_id' => 'payout_' . uniqid(),
    'amount' => 100000,
    'beneficiary_msisdn' => '+22376987654',
    'currency' => 'XOF',
    'reason' => 'Gain de la session du 28/04',
];

// Même signature HMAC + POST sur /api/v1/payments/cashout

Si vous ne recevez pas le webhook après quelques minutes, vous pouvez interroger le statut :

PHP$ch = curl_init($apiBase . '/payments/' . $transactionId);
$timestamp = (string) time();
$signature = hash_hmac('sha256', $timestamp . '', $apiSecret);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-NekaPay-Key: ' . $apiKey,
    'X-NekaPay-Timestamp: ' . $timestamp,
    'X-NekaPay-Signature: ' . $signature,
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$tx = json_decode(curl_exec($ch), true);
echo 'Status: ' . $tx['data']['status'];