Webhook server

To simplify the development of the notification server needed to process AgoraPay webhook events, this reference implementation is provided.

You will get the following features to help you develop your own server:

Your "Webhook" URL will be set so that you can receive POST request from Agorapay
A HMAC key and a Key ID
An Implementation guide of the HMAC control processing (To verify the webhook)

The implementation manager will ask you for an URL so that agorapay events can be sent to that link. (Multiple URLS can be given for different types of processes , or you can use 1 URL for all processes).

Example:

https://YourMarketPlace.fr/webhookPayment (Payment Process)
https://YourMarketPlace.fr/webhookOperation (Operation Process)

The manager will give you a Key id and a Hmac Key that you will be using for the HMAC control process.

It's up to your marketplace needs on how you can approach the implementation of the webhook server, AgoraPay includes the authentication mechanism so you can verify that incoming events have been genuinely created by AgoraPay.

It's information sent to your "Webhook Server" about different proccesses in your marketplace, these events can be triggered by a card payment for exemple.

For more info , please go to Agorapay events.

Here is a Webhook exemple you can receive after a card payment (webhook Operation version 3):

JSON

Copy

Copied

{
   "amount":"5.00",
   "authNumber":"462242",
   "commissionAmount":"0.05",
   "contractRef":"2102019",
   "currencyCode":"EUR",
   "eventCode":"operation",
   "eventStatusLabel":"None",
   "exchangeFees":"0.00",
   "maskedPAN":"**************91",
   "metaData":
     {
       "metadata":" "
     },
   "operationDate":"20240731",
   "operationSide":"1",
   "operationStatus":"R",
   "operationType":"1",
   "orderRef":"Spadaro-2024-07-31 11:43:34",
   "paymentFees":"0.00",
   "paymentMethodTypeId":"4",
   "relatedMsgStatus":"0",
   "schemeFees":"0.00",
   "transRefNo":"38125957",
   "transactionId":"7562722",
   "versionNumber":"3.0"
}

Copy

Copied

Since your notification server will be publicly accessible, AgoraPay includes an authentication mechanism so you can verify that incoming events have been genuinely created by AgoraPay.

For more info , please go to Implementation guide

PHP

Copy

Copied

// Function to verify computed Hmac
function computedHmac($authorizationElements , $request_body){

    $url ='';
    $Hmac = 'HMAC KEY';

    // Ensure the authorization elements are set and not empty
    if (!empty($authorizationElements) && isset($authorizationElements[4])) {

        //compute the HMAC 
        $bodySha256 = strtoupper(hash("sha256", $request_body));
        $plainTextToComputeHmac = 'POST' . ';' . $url . ';' . $bodySha256 . ';' . $authorizationElements[1] . ';' . $authorizationElements[2];
        $hmac256 = hash_hmac('sha256', $plainTextToComputeHmac, pack("H*",$Hmac));

        
        $computedHmacOnHeader = $authorizationElements[4];    
        //compare hmacs
        if (strtoupper($computedHmacOnHeader) === strtoupper($hmac256)) {
            return true;
        }else{
            return false;
        }
    }
    return false;
}

Copy

Copied

What is the impact of a domain change between development and production, or only in production?

You need to inform AgoraPay whenever there is a domain change so that the support team can provide you a new token allowing the platform's use.

The token is checked on every incoming API call. It is possible to call AgoraPay APIs regardless of the environment/URL as long as the token (API key) is valid and is sent.

In order to push transaction events through webhooks (asynchronous with respect to your API calls), AgoraPay is whitelisting the URLs and create a dedicated token linked to the URL :

This is why you must provide us with the URLs as soon as possible so that a new token can be created.

AgoraPay can push webhooks to multiple environments/URLs. The marketplace must analyze the information of the webhook sent to match with the environment at the origin of the operation and which will process this webhook. For other environments that do not know the transaction, it will have to be rejected. This allows the MKP to juggle several environments, especially during the approval phase.

Reference Webhook Server Copy section link Copied!

Implementation of the Webhooks Server Copy section link Copied!

Agorapay Event Copy section link Copied!

Webhook Authentication Copy section link Copied!

Questions Copy section link Copied!