# 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 : ```json // 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.