2 - Notifications (IPN)

Étape 2 : Gérer les notifications de paiement instantanées (IPN)

Une notification de paiement est envoyée après chaque paiement à une URL de rappel configurée soit dans votre tableau de bord, soit définie dans le lien de paiement.

Demande de notification de paiement instantanée

POST callbackUrl InstantPayment Notification method

Response codes

Success

Code	Reason
200 - Ok	Request was successful.
204 - No Content	Request was successful and has no content.

Error

Code	Reason
400 - Bad Request	Request was successful.
401 - Unauthorized	User must authenticate before making a request.
403 - Forbidden	Policy does not allow current user to do this operation.

Request Parameters

Name	Location	Type	Description
id	body	string	The transaction's unique identifier.
payment	body	Payment	The transaction's related payment.
payment.id	body	string	The payment's unique identifier.
payment.type	body	enum	The payment's type. The avalaible values are full and partial.
payment.application	body	object	The payment's application identifier.
payment.invoice	body	invoice	The payment's invoice.
payment.extras	body	object	The payment's invoice.
payment.totalAmountAlreadyPaid	body	float	The payment total amount already paid.
invoice	body	invoice	The information of the invoice paid.
invoice.id	body	string	The invoice's unique identifier.
invoice.customerId	body	string	The customer's unique identifier.
invoice.totalAmount.amount	body	float	The total amount paid for the invoice.
invoice.totalAmount.currency	body	string	The currency of the total amount paid for the invoice. The currency must be in ISO 4217 format.
invoice.issuedAt	body	string	The date on which the invoice was issued. The date must be in ISO 8601 format.
invoice.dueDate	body	string	The date on which the invoice will be due. The date must be in ISO 8601 format.
invoice.expiresAt	body	string	The date on which the invoice will expires. The date must be in ISO 8601 format.
paymentFee.amount	body	float	The amount of payment fees applied to the transaction.
paymentFee.currency	body	string	The currency of payment fees applied to the transaction. The currency must be in ISO 4217 format.
externalTransactionId	body	string	The transaction external identifier provide by payment processor.
result	body	object	The transaction's result.
result.origin	body	object	The transaction's result originator.
result.status	body	enum	The transaction's result status. The avalaible values are: COMPLETED, NEEDS_MERCHANT_VALIDATION, CANCELED, REFUSED , FAILED and REVERSED .
result.statusReason	body	string	The transaction's result status reason.
Authorization	header	string	The request is secured by the HTTP Signature Authentication protocol.
Content-Type	header	string	Set the MIME type for the request.

Exemple de requête avec authentification par mot de passe

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=NjQzMWNjYWMwNjdkYTA5ZWFiZTJiZDMyMDU3NmQxOWEyM2RmNTYyMzMyMDcyOTliMTJmMzAx
YjY1ZDZkOTYzMg==' \
-H 'Signature: keyId="fbab3ccc-719e-11ed-93ad-02420a0003c1",algorithm="hmac-
sha256",headers="(request-target) content-type date
digest",signature="fiFBCK8NWWhvk6fJul8ezzpVXSh9q30VRO8qn3XGxTQ="' \
-H 'Authorization: Signature keyId="2bc56634-673c-11ed-acf4-
0242ac13000e",algorithm="hmac-sha256",headers="(request-target) content-type
date digest",signature="fiFBCK8NWWhvk6fJul8ezzpVXSh9q30VRO8qn3XGxTQ="' \
-d '{
    "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"
        },
        "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"
    },
    "id": "63a368858622d5ded108e4b3",
    "result": {
        "origin": "processor",
        "status": "COMPLETED"
    }
}'

Comment valider une demande de notification de paiement ?

La demande de notification de paiement instantanée (IPN) est sécurisée par l'authentification par signature HTTP.

Vous trouverez ci-dessous un exemple de code PHP permettant de traiter les demandes de notification de paiement :

// Fetch application secret configuration parameters.
$applicationSecret = 'app!secret';
$body = json_decode(file_get_contents('php://input'), true);
$transactionId = $body['id'];
$transactionStatus = $body['result']['status'];
$invoiceId = $body['invoice']['id'];
$invoiceTotalAmount = $body['invoice']['totalAmount']['amount'];
$paymentFee = $body['paymentFee']['amount'];
/**
* Validate callback authenticity.
*/
$components = [];
$headers = array_change_key_case(getallheaders(), \CASE_LOWER);
foreach (explode(',', $headers['signature'] ?? '') as $value) {
    if (!$component = explode('=', $value, 2)) {
        continue;
    }
    $components[$component[0]] = trim($component[1], '"');
}
if (array_diff(['keyId', 'algorithm', 'headers', 'signature'],
array_keys($components))) {
    die('Payment failed');
}
if ('hmac-sha256' !== $components['algorithm']) {
    die('Payment failed');
}
$signature = [];
foreach (explode(' ', strtolower($components['headers'])) as $header) {
    $signature[] = sprintf('%s: %s', $header, '(request-target)' !== $header
? $headers[$header] : sprintf('%s %s',
strtolower($_SERVER['REQUEST_METHOD']), $_SERVER['REQUEST_URI']));
}
if (false === hash_equals(base64_encode(hash_hmac('sha256',
implode(\PHP_EOL, $signature), applicationSecret, true)),
$components['signature'])) {
    die('Payment failed');
}
/**
* Validate transaction status.
*/
if ('COMPLETED' !== transactionStatus) {
die('Payment failed');
}
// Busines Logic here
// ...

Statut de la transaction

La valeur et la description du statut de la transaction

Value	Reason
PENDING	We’re reviewing the transaction. We’ll send your payment to the recipient after your payment source has been verified.
PROCESSING	We’re processing your payment and the transaction should be completed shortly.
CANCELED	You canceled your payment, and the money was credited back to your account.
COMPLETED	The transaction was successful and the money is in the recipient’s account.
REFUSED	The recipient didn’t receive your payment. If you still want to make your payment, we recommend that you try again.
FAILED	Your payment didn’t go through. We recommend that you try your payment again.
RESERVED	Either you canceled the transaction or we did.
NEEDS_MERCHANT_VALIDATION	Either you awaiting merchant validation.