PayRouterDocs

Démarrage rapide

Créez votre premier paiement de bout en bout. À la fin de cette page, vous aurez envoyé une transaction en sandbox et reçu son statut final sur votre serveur.

Prerequisites

  • Un compte PayRouter avec un profil marchand complété (inscription).
  • Un jeton API — générez-en un dans Profil → Clés API (comment faire).
  • L'URL de base : https://payrouter.io (production) ou http://127.0.0.1:8000 (local).

1. S'authentifier

Chaque requête authentifiée transporte votre jeton dans l'en-tête Authorization :

http
Authorization: Bearer <your-token>

Vérifiez que votre jeton fonctionne en récupérant votre profil :

cURL
curl https://payrouter.io/api/auth/me/ \
  -H "Authorization: Bearer $PAYROUTER_TOKEN"
JavaScript
const res = await fetch("https://payrouter.io/api/auth/me/", {
  headers: { Authorization: `Bearer ${process.env.PAYROUTER_TOKEN}` },
});
console.log(await res.json());
Python
import requests

res = requests.get(
    "https://payrouter.io/api/auth/me/",
    headers={"Authorization": f"Bearer {token}"},
)
print(res.json())
PHP
<?php
$ch = curl_init("https://payrouter.io/api/auth/me/");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ["Authorization: Bearer {$token}"],
]);
echo curl_exec($ch);

Un 200 avec le JSON de votre compte signifie que vous êtes prêt. Un 401 signifie que le jeton est absent, mal formé ou révoqué — voir Dépannage.

2. Créer une transaction

Envoyez une requête de paiement. Votre identité est dérivée du jeton — vous ne transmettez jamais votre identifiant de marchand ou d'utilisateur. Vous fournissez la devise et le service par leurs codes (p. ex. "CDF", "Vodacom"), pas par des UUID.

cURL
curl -X POST https://payrouter.io/api/payments/transaction/ \
  -H "Authorization: Bearer $PAYROUTER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_reference": "INV-2026-0001",
    "amount": "100.00",
    "currency": "CDF",
    "service": "Vodacom",
    "customer_number": "0810000000",
    "operation": "debit",
    "callback_url": "https://your-app.com/payments/webhook"
  }'
JavaScript
const res = await fetch("https://payrouter.io/api/payments/transaction/", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PAYROUTER_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    merchant_reference: "INV-2026-0001",
    amount: "100.00",
    currency: "CDF",
    service: "Vodacom",
    customer_number: "0810000000",
    operation: "debit",
    callback_url: "https://your-app.com/payments/webhook",
  }),
});
const txn = await res.json();
console.log(txn.reference, txn.transaction_status);
Python
import requests

res = requests.post(
    "https://payrouter.io/api/payments/transaction/",
    headers={"Authorization": f"Bearer {token}"},
    json={
        "merchant_reference": "INV-2026-0001",
        "amount": "100.00",
        "currency": "CDF",
        "service": "Vodacom",
        "customer_number": "0810000000",
        "operation": "debit",
        "callback_url": "https://your-app.com/payments/webhook",
    },
)
txn = res.json()
print(txn["reference"], txn["transaction_status"])
PHP
<?php
$ch = curl_init("https://payrouter.io/api/payments/transaction/");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer {$token}",
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "merchant_reference" => "INV-2026-0001",
        "amount" => "100.00",
        "currency" => "CDF",
        "service" => "Vodacom",
        "customer_number" => "0810000000",
        "operation" => "debit",
        "callback_url" => "https://your-app.com/payments/webhook",
    ]),
]);
echo curl_exec($ch);

Un appel réussi renvoie 201 avec la transaction créée, y compris la reference canonique de PayRouter et le fournisseur résolu :

json
{
  "reference": "9F3A1C2D4E5B6A7C8D9E0F1A2B3C4D5E",
  "merchant_reference": "INV-2026-0001",
  "transaction_status": "Received",
  "transaction_status_code": "200000",
  "amount": "100.00",
  "currency_abbr": "CDF",
  "service_name": "Vodacom",
  "provider_code_name": "freshpay",
  "operation": "debit",
  "customer_number": "0810000000",
  "callback_url": "https://your-app.com/payments/webhook",
  "created_at": "2026-06-27T10:21:00Z"
}

Note

Conservez la reference — c'est l'identifiant permanent de ce paiement chez PayRouter et la clé que vous utiliserez pour le retrouver et pour faire correspondre les webhooks entrants.

3. Recevoir le résultat

L'argent ne circule jamais de façon synchrone. PayRouter sollicite le paiement auprès du fournisseur, puis envoie en POST le statut final à votre callback_url :

json
{
  "reference": "9F3A1C2D4E5B6A7C8D9E0F1A2B3C4D5E",
  "merchant_reference": "INV-2026-0001",
  "transaction_status": "Success",
  "amount": "100.00",
  "currency": "CDF",
  "customer_number": "0810000000",
  "provider_reference": "FP-558213007"
}

Répondez 200 OK. Traitez les webhooks comme idempotents (vous pouvez en recevoir plus d'une fois) et basez votre traitement sur la reference. Tous les détails — y compris comment vérifier et que faire si vous n'avez pas encore de point de terminaison public — se trouvent dans Webhooks.

4. Vérifier le statut vous-même

Vous pouvez toujours interroger le statut faisant autorité :

bash
curl https://payrouter.io/api/payments/transaction/9F3A1C2D4E5B6A7C8D9E0F1A2B3C4D5E/ \
  -H "Authorization: Bearer $PAYROUTER_TOKEN"

Étapes suivantes

Démarrer
Authentification