2 - Notifications (IPN)

Étape 2 : Notification de paiement instantanée

Les notifications de paiement instantanées (IPN) sont envoyées à l’url de callback après le traitement d’un paiement. Cela permet un suivi en temps réel de l’état des transactions.

IPN Request Overview

• Method: POST

• Endpoint: The callbackUrl defined in your payment link or configured in your dashboard.

• Headers:

  • Authorization: Secured with HTTP Signature Authentication.

  • Content-Type: Specifies the MIME type of the request (e.g., application/json).

Request Parameters

Name	Location	Type	Description
id	Body	string	Unique identifier for the transaction.
payment	Body	object	Details about the related payment.
payment.id	Body	string	Unique identifier for the payment.
payment.type	Body	enum	Payment type. Available values are full and partial.
payment.application	Body	object	The payment's application identifier.
payment.invoice	Body	object	Details about the invoice associated with the payment.
payment.extras	Body	object	Additional data related to the payment.
payment.totalAmountAlreadyPaid	Body	float	Total amount already paid for the transaction.
invoice	Body	object	Details about the invoice being paid.
invoice.id	Body	string	Unique identifier for the invoice.
invoice.customerId	Body	string	Unique identifier for the customer.
invoice.totalAmount.amount	Body	float	Total amount for the invoice.
invoice.totalAmount.currency	Body	string	Currency for the total amount (ISO 4217 format).
invoice.issuedAt	Body	string	Date the invoice was issued (ISO 8601 format).
invoice.dueDate	Body	string	Due date of the invoice (ISO 8601 format).
invoice.expiresAt	Body	string	Expiration date of the invoice (ISO 8601 format).
paymentFee.amount	Body	float	Amount of payment fees applied to the transaction.
paymentFee.currency	Body	string	Currency of the payment fees (ISO 4217 format).
externalTransactionId	Body	string	External identifier for the transaction provided by the payment processor.
result	Body	object	Details about the transaction's result.
result.origin	Body	object	Originator of the transaction result.
result.status	Body	enum	Status of the transaction. Values include COMPLETED, FAILED, CANCELED, etc.
result.statusReason	Body	string	Additional details about the transaction's status.

Exemple d'IPN

{
  "id": "63a368858622d5ded108e4b3",
  "payment": {
    "id": "63a368858622d5ded108e4b2",
    "type": "full",
    "application": {
      "id": "b3695b9c-816b-11ed-8083-32706358435f",
      "name": "banking"
    },
    "invoice": {
      "id": "1",
      "customerId": "1",
      "totalAmount": {
        "amount": 1000,
        "currency": "XOF"
      },
      "issuedAt": "2022-12-21T20:11:49+00:00",
      "expiresAt": "2023-12-21T20:11:49+00:00"
    },
    "extras": [],
    "totalAmountAlreadyPaid": {
      "amount": 1000,
      "currency": "XOF"
    }
  },
  "invoice": {
    "id": "1",
    "customerId": "1",
    "totalAmount": {
      "amount": 1000,
      "currency": "XOF"
    },
    "issuedAt": "2022-12-21T20:11:49+00:00"
  },
  "paymentFee": {
    "amount": 0,
    "currency": "XOF"
  },
  "externalTransactionId": "ext-123456789",
  "result": {
    "origin": "processor",
    "status": "COMPLETED"
  }
}

Exemple d’authentification par mot de passe

Vous pouvez également authentifier les requêtes IPN à l’aide d’une authentification par mot de passe.

Exemple cURL

curl -X POST -i 'callbackUrl' \
-H 'Host: acme.org' \
-H 'Content-Type: application/json' \
-H 'Date: Thu, 01 Dec 2022 19:08:22 +0000' \
-H 'Digest: SHA-256=example-digest' \
-H 'Authorization: Signature keyId="application-id",algorithm="hmac-sha256",headers="(request-target) content-type date digest",signature="example-signature"' \
-d '{
  "id": "63a368858622d5ded108e4b3",
  "result": {
    "status": "COMPLETED"
  }
}'

Validation de la requête IPN

La requête IPN est sécurisée à l’aide de l’authentification par signature HTTP. Assurez-vous de l’authenticité de la requête en suivant les étapes suivantes :

1. Récupération du secret de l’application : obtenez-le depuis votre tableau de bord.

2. Extraction des en-têtes de signature : analysez l’en-tête Signature présent dans la requête.

3. Recalcul de la signature : utilisez la clé keyId fournie et l’algorithme de hachage (HMAC-SHA256).

4. Comparaison des signatures : comparez la signature recalculée avec celle incluse dans la requête.

Exemple PHP de validation

La requête de notification instantanée de paiement (IPN) est protégée par une authentification par signature HTTP. Voici un exemple de code en PHP permettant de traiter la requête de notification de paiement :

$applicationSecret = 'app!secret'; 

$body = json_decode(file_get_contents('php://input'), true); 
$headers = getallheaders();

// Validate signature components
$signatureComponents = [];
foreach (explode(',', $headers['Signature']) as $component) {
    list($key, $value) = explode('=', $component, 2);
    $signatureComponents[trim($key)] = trim($value, '"');
}

// Validate signature algorithm
if ($signatureComponents['algorithm'] !== 'hmac-sha256') {
    die('Invalid signature algorithm');
}

// Compute signature
$computedSignature = base64_encode(hash_hmac(
    'sha256', 
    json_encode($body), 
    $applicationSecret, 
    true
));

// Compare signatures
if (!hash_equals($computedSignature, $signatureComponents['signature'])) {
    die('Signature validation failed');
}

// Business logic
if ($body['result']['status'] === 'COMPLETED') {
    // Handle completed payment
}