Transactions

Une transaction est la source unique de vérité d'un paiement. Vous la créez ; le switch la route vers un fournisseur ; le statut final arrive sur votre webhook. Cette page documente l'appel de création et l'objet transaction complet.

Créer une transaction

Votre marchand, votre utilisateur et votre pays sont dérivés de votre jeton et de votre profil — ne les envoyez jamais. Fournissez currency et service sous forme de codes lisibles ; PayRouter les résout.

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"
  }'

const res = await fetch("https://payrouter.io/api/payments/transaction/", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${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",
  }),
});

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",
    },
)

<?php
$payload = [
    "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",
];
$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($payload),
]);
echo curl_exec($ch);

Champs de la requête

Réponse

Un 201 renvoie la transaction complète. Le statut est contrôlé par le serveur et démarre toujours à Received — l'argent ne circule jamais lors de cette requête.

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

Champs de réponse clés

Statuts

Le cycle de vie est protégé : Received → Pending → Success | Failed | Cancelled. Les états terminaux (Success, Failed, Cancelled) sont immuables — une fois atteints, ils ne changent jamais.

Lire une transaction

# One transaction (by PayRouter reference)
curl https://payrouter.io/api/payments/transaction/9F3A1C2D…5E/ \
  -H "Authorization: Bearer $PAYROUTER_TOKEN"

# Its full status timeline
curl https://payrouter.io/api/payments/transaction/9F3A1C2D…5E/history/ \
  -H "Authorization: Bearer $PAYROUTER_TOKEN"

# Your transactions (paginated)
curl "https://payrouter.io/api/payments/transaction/?ordering=-created_at&page=1" \
  -H "Authorization: Bearer $PAYROUTER_TOKEN"

Le point de terminaison de liste est limité à vos transactions et prend en charge ?search= (reference / merchant_reference / customer_number / provider_reference), ?ordering=-created_at, et les filtres : transaction_status, operation, provider_code_name, service. Les réponses sont paginées (count, next, previous, results).

Paiements groupés (versements en masse)

Pour les lots de type paie, groupez les bénéficiaires et payez-les ensemble :