Asynchronous events refer to payment flows where the final response is not received in real time. This is usually due to off-app authentication unique to the payment methods like Bank Transfers, USSD and NQR.

You can handle async events either by:

Polling the final status.
Using Webhooks

Polling Payment Status

To poll the final transaction status, send a request to the verify payment endpoint. We cover this in more details here.

Webhooks

What are webhooks?

Webhooks are event-triggered https messages sent to notify a system about an event change. Webhooks are a great way to get notified about your payment status.

What is the structure of a webhook?

A sample webhook contains the customer, order and payment information. Here is a sample webhook for a card payment:

{
  "Data": {
    "OrderReference": "ORD66DC8928903467356969",
    "PaymentReference": "PA-REF-CFE3DE37-29FB-46DE-84A0-D0E849EEF1D8",
    "ProductName": "Collection",
    "TotalAmountCharged": 11.4,
    "PaymentStatus": 5,
    "Status": "Successful",
    "PaymentMethod": "Card Payment",
    "PaymentResponseCode": "00",
    "PaymentResponseMessage": "Payment completed succesfully",
    "Narration": "Pay",
    "Remarks": "Order initiated and created successfully",
    "CurrencyId": 0,
    "CurrencyName": "USD",
    "Fee": 1.4,
    "FeeRate": 0.14,
    "SubsidiaryFee": 0,
    "CustomerFee": 1.4,
    "DateCreated": "2023-08-17T17:04:02.92Z",
    "DateUpdated": "2023-08-17T17:04:26.27Z",
    "DatePaymentConfirmed": "2023-08-17T17:04:26.27Z",
    "OrderPayments": [
      {
        "OrderId": 210,
        "OrderPaymentReference": "PA-REF-CFE3DE37-29FB-46DE-84A0-D0E849EEF1D8",
        "PaymentOptionId": 0,
        "PaymentOption": "Card Payment",
        "StatusId": 5,
        "PaymentStatus": "Successful",
        "ResponseCode": "00",
        "ResponseMessage": "Payment Completed successfully",
        "OrderPaymentInstrument": null,
        "Remarks": "Order payment initiated",
        "DateCreated": "2023-08-17T17:04:11.39Z",
        "DateUpdated": "2023-08-17T17:04:26.277Z"
      }
    ],
    "Customer": {
      "CustomerId": null,
      "FirstName": "Jane",
      "LastName": "Doe",
      "EmailAddress": "[email protected]",
      "CountryShortName": "NG",
      "CustomerGroup": "Default",
      "CountryId": 0,
      "GlobalStatusId": 2,
      "GlobalStatus": "Active",
      "MobileNumber": "+2348101234566",
      "IsBlacklisted": false,
      "ReasonBlacklisted": null,
      "DateCreated": "2023-06-26T20:26:39.783Z",
      "DateUpdated": null
    },
    "CardDetails": [
      {
        "OrderPaymentId": 184,
        "Status": true,
        "Country": "NG",
        "CardToken": "UFYzeGra16AvMxVzvRI8HDqZqiNQiywWKKypMsDryQA=",
        "CardExpiryMonth": "01 / 39",
        "CardExpiryYear": "01 / 39",
        "CardType": "N/A",
        "CardIssuer": "N/A",
        "CardFirstSixDigits": "512345",
        "CardLastFourDigits": "0008",
        "DateCreated": "2023-08-17T17:04:26.283Z",
        "AppEnvironmentId": 1
      }
    ]
  },
  "Status": "success",
  "StatusCode": "00",
  "Message": "Order details fetched successfully"
}

Setting up your webhooks

Use these steps to enable webhooks on your account:

Log into your Alliance Pay dashboard.
Navigate to settings - This is the last item on your menu.
Select "API keys and Webhooks" from the settings dropdown.
Enter your URL into the webhook URL field.
Click the "Add URL" button to confirm the setup.

Best practices

Setup a backup polling job for downtimes on your webhook server.
Avoid long running tasks or network calls on your server to prevent timeouts.
Be Idempotent.