Prepare a Notification Page

Why the Notification

The notification link/url (notif_url) is called by Paynah to notify you of the status of a payment. This URL must be available to handle HTTP POST requests and return the HTTP 200 OK status. Paynah will not post any data via GET; the server pings your URL to ensure it is available.

The notif_url should be the only mechanism to implement to automatically synchronize payments to your merchant site. Paynah will call this link after each update to notify you of status changes during a transaction.

At the end of a payment, Paynah systematically calls the notification URL for the concerned service. This call aims to inform the merchant site of the payment status (even if the client does not return to the site). The merchant can then validate their order if the payment is verified and accepted.

The notification URL is not necessary if you don't need to have the payment status in your database, as you have the history of your payments in your Paynah backoffice.

Ex: Donation collection application

Steps to Configure the Notification URL

1-RECEIVE A NOTIFICATION

The server executes a POST type request on your notification URL containing:

Request header:

x-token: An HMAC token to allow verification on the partner side. For more information, please consult the section dedicated to the HMAC token. Request body:

To ensure the integrity of the data you are processing, you must perform certain checks:

Your notification URL must be an API that expects a POST call with the parameter cpm_trans_id (Corresponding to the variable transaction_id) After obtaining it, you must check in your database that the status of the concerned payment is already successful: If yes, then you do not make any more updates; If no, you must make a call to the transaction verification API to obtain the transaction status at Paynah and thus update the status in your database.

2-CHECK THE TRANSACTION STATUS

Note

Paynah will not send you information on the transaction status to avoid certain security flaws like man in the middle. The notification URL can be called several times. You will always have to make a call to the "Transaction Verification" API of payment to have the real values of the payment.

To know the status of a transaction, you must send the following information in JSON format. Using this URL on GET request: https://payin.api-v2.paynah.com/v1/intents/{{reference}}/status (opens in a new tab)

3-DELIVER A SERVICE

When the payment is successful, you will receive this response from Paynah:

{
    "code": "200",
    "message": "SUCCESS",
    "data": {
        "amount": "100",
        "currency": "XOF",
        "status": "Approved",
        "payment_method": "CI_MTN",
        "description": "Description",
        "transaction_id": "123e4567-e89b-12d3-a456-426614174000"
    }
}

Then you should deliver the service. Don't forget to update your database.

In case of failure, you will receive this response from Paynah:

{
    "code": "200",
    "message": "CANCELLED",
    "data": {
        "amount": "100",
        "currency": "XOF",
        "status": "Declined",
        "payment_method": "CI_MTN",
        "description": "Test Payment",
        "transaction_id": "123e4567-e89b-12d3-a456-426614174000"
    }
}

No service should be delivered. Don't forget to update your database.

Not Receiving Notifications?

This usually occurs when your notification URL is not accessible or is misconfigured. The table below summarizes the probable reasons why you are not receiving notifications.

Using an HTTP request application like PostMan, you can test your notification URL.

But before, make sure that your notification URL is available in POST and accessible by a public server.

If the error obtained is not in the table below, write to us at this address: support@paynah.com