Asynchronous Webhooks

Apaya provides asynchronous webhook notifications upon particular events taking place in our platform. Your platform can receive these webhooks by providing Apaya with a URL to your handler using the format shown below.

Example webhook format:

Type 1 - Subscription
https://www.example.com/?mx=nRjrQf7rkGX-437Y6)5gR)5uMlRi3cy-3Ft9s2qvzD4&mcc=234&mnc=02&productId=92000000&type=1&pt=Your_pass_through_value&sid=8100000

Type 2 - Subscription Cancellation
https://www.example.com/?mx=nRjrQf7rkGX-437Y6)5gR)5uMlRi3cy-3Ft9s2qvzD4&mcc=234&mnc=02&productId=92000000&type=2&pt=Your_pass_through_value&sid=8100000

Type 3 - Subscription Reactivation
https://www.example.com/?mx=nRjrQf7rkGX-437Y6)5gR)5uMlRi3cy-3Ft9s2qvzD4&mcc=234&mnc=02&productId=92000000&type=3&pt=Your_pass_through_value&sid=8100000

Type 5 - Successful and Failed Bill Transactions
https://www.example.com/?mx=nRjrQf7rkGX-437Y6)5gR)5uMlRi3cy-3Ft9s2qvzD4&mcc=234&mnc=02&productId=92000000&type=5&pt=Your_pass_through_value&chargeAmount=20&currencyCode=AED&productDescription=Your+product+description&transactionStatus=00&txid=3AA1BAXX-873X-4D8X-AF1X-1A5A132AXXXX

Webhook retry policy

Your platform must provide a '200 OK' HTTP status code upon receiving and handling the Apaya webhook notification.

The notification will retry once per second if a '200 OK' status is not received.

Webhook parameters:

Each of the following parameters can be returned in the async webhook notifications

  • txid - Billing transactions only: Transaction ID associated with the initiating transaction

  • productId - Product ID for the initiating transaction

  • type - Integer value which indicates the type of interaction that has been performed

    • 1 - Subscription

    • 2 - Subscription Cancellation

    • 3 - Subscription Reactivation

    • 5 - Successful and Failed billing transactions

  • pt - The pass-through value provided in the initiating transaction

  • sid - Subscriptions only: The subscriptionID relating to the productID

  • chargeAmount - Billing transactions only: The transaction amount for the product in decimal format e.g. 0.25 = 25p, 1 = £1.00, 20= £20.00

  • currencyCode - Billing transactions only: Currency code

  • transactionStatus - Billing transactions only: The success or error status relating to the transaction.

    • 00 - Successfully billed

    • 10, 30 - Transaction pending

    • AA - Error - Insufficient credit

    • A5 - Error - Operator Bar

    • A3 - Error - Mobile number not recognised by the mobile network.

    • A6, A7, A8, A9, AB, AC, AD - Error - Expenditure limit reached

    • 01, 48, 74, A0, A1, A2, A4, AF - Error - Billing attempt has failed

  • mx - Encrypted mobile number (for DCB only)

  • mnc - Mobile Network Code (for DCB only)

  • mcc - Mobile Country Code (for DCB only)

  • productDescription - Billing transactions only: The product description shown to the end user at transaction.