Asynchronous Webhooks

Apaya provides asynchronous webhook notifications upon events taking place in our platform. The webhook notifications are of type "POST" and consist of a payload body with the option to have some of the webhook data also passed in the query string.

Configure your platform's webhook handler endpoint and choose from the available webhook types by logging into the Apaya Portal and going to the 'Manage Product' page of your product.
Sandbox: https://sandbox-portal.apaya.io
Production: https://portal.apaya.io

Watch this quick 5 minute video on how to setup your webhooks.

Payload and Query string example

QUERY STRING
https://www.example.com/?typeId=1&productId=93000000&pt=Your_pass_through_reference&txid=170XXXXX&transactionStatus=CAP%20REACHED&providerId=1003&currencyCode=AED&chargeAmountExcTax=1.00&chargeAmountIncTax=1.05

PAYLOAD

Type 1 - Successful and Failed Bill Transactions
Type 5 - Successful refunds

{ 
   "id":2022090500000000360,
   "result":"Error",
   "productId":93000000,
   "identityId":1234,
   "identityTypeId":4,
   "pt":"Your_pass_through_reference",
   "initialDatetimeUtc":"2022-09-01T14:56:27.8531641Z",
   "txid":"170XXXXX",
   "paymentType":3,
   "checksum":null,
   "transactionStatus":"CAP REACHED",
   "providerId":1003,
   "providerName":"VISA",
   "typeId":1,
   "chargeAmountIncTax":1.05,
   "chargeAmountExcTax":1.00, 
   "currencyCode":"AED",
   "externalMerchantId":"YourOptionalID",
}
Type 7 - Successful Consent Setup

{
  "id": 2022090500000000360,
  "result": "Success",
  "productId": 93000000,
  "identityId": 1234,
  "identityTypeId": 4,
  "pt": "Your_pass_through_reference",
  "initialDatetimeUtc": "2022-09-01T14:56:27.8531641Z",
  "txid": "170XXXXX",
  "paymentType": 3,
  "transactionStatus": "SETUP_SUCCESS",
  "providerId": 1003,
  "providerName":"VISA",
  "typeId": 7,
  "chargeAmountIncTax": 1.05,
  "chargeAmountExcTax": 1,
  "currencyCode": "AED",
  "hashedIdentifier": "XXXXXXXXXXXX1993",
  "identityPrefix": "112233",
  "userConsentToken": "ye4xVlBxxxxxtTtItRRY)MxxxxxNkf5Adpxxxx)ht8%3d__jJN39IVLMeKxo-xxxxaLUphr5MiMFxxx0hY3x3eXhY%3d",
  "identityExpiry": "1024",
  "externalMerchantId":"YourOptionalID",
}

Parameters:

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

  • id - Unique ID for the webhook/notification

  • result - A high-level status of the transaction. Values can contain any of the following:
    (Note: If a SUCCESS status webhook is received, it will be the final status in the sequence, even if other statuses are received afterwards for the same TXID)
    - Success
    - Initiated
    - Pending
    - Error
    - Unknown Error

  • typeId - Integer value indicating the type of webhook interaction performed
    - 1 (Successful and failed billing transactions)
    - 5 (Successful refunds)
    - 7 (Successful consent setup)

  • productId - Your Product ID for the initiating transaction

  • identityId - Unique ID for the customer

  • identityTypeId - A type ID referring to the unique data returned in the identityId parameter.
    - 1 (DCB - Direct Carrier Billing)
    - 2 (Email)
    - 3 (Banking)
    - 4 (Credit Card)
    - 5 (Address)

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

  • initialDatetimeUtc - The date and time when the Apaya platform initiated the webhook.

  • txid - Apaya's Transaction ID

  • paymentType - The type of payment from the following list:
    - 1 (DCB - Direct Carrier Billing)
    - 2 (Direct Debit)
    - 3 (Debit/Credit card)
    - 4 (Wallet)
    - 6 (Bank Transfer)
    - 7 (Buy Now Pay Later (BNPL))

  • providerId - The Apaya-defined providerId utilised as part of the transaction. See Providers for a full list of IDs.

  • providerName - The payment provider utilised as part of the transaction. See Providers for a full list of names.

  • transactionStatus - The success or error status relating to the transaction.
    (Note: If a SUCCESS status webhook is received, it will be the final status in the sequence, even if other statuses are received afterwards for the same TXID)

    • 'SUCCESS' - Successfully billed

    • 'NOT PAID PENDING' - The transaction has not yet completed.

    • 'INSUFFICIENT CREDIT' - Error - The customer’s credit balance is too low for the amount being charged.

    • 'BARRED' - Error - The payment provider has a restriction on this account, which prevents the customer from paying for services.

    • 'BLACKLISTED' - Error - The payment provider, or Apaya, has blacklisted (completely restricted) this customer or their mobile number from paying for services. This is based on previous usage by the customer that breached specific terms and conditions.

    • 'USER HAS PORTED' - Error - The Mobile number is not recognised by the mobile network.

    • 'CAP REACHED' - Error - The customer has reached their expenditure limit.

    • 'NOT PAID', 'INTERNAL ERROR' - Error - The transaction attempt has failed.

  • currencyCode - Currency code

  • chargeAmountExcTax - The tax-exclusive transaction amount for the product in decimal format e.g. 0.25 = 25p, 1 = £1.00, 20= £20.00.

  • chargeAmountIncTax - The tax-inclusive transaction amount for the product in decimal format e.g. 0.25 = 25p, 1 = £1.00, 20= £20.00

  • externalMerchantId - An optional ID that you can configure in the Apaya platform which relates to an ID in your environment for this merchant account. It can be an ID associated with your own merchant account, or associated with one of your child-merchant accounts.

    The parameters below are for Consent Setup webhooks only

  • hashedIdentifier - Contains a 'hashed' user identifier (card number, mobile number, or other) which you can display on your UI after being decoded.

    • Card numbers will be hashed with an 'X' character except for the final 4 digits E.g. XXXXXXXXXXXX6417

  • userConsentToken - The encrypted consent token created by the Apaya platform. Store this in your platform for use in future interactions with Apaya APIs to trigger reserve/authorization and when capturing a charge.

  • identityPrefix - The first 6 to 8 digits of the customer's card number.

  • identityExpiry - The card expiry date of the customer's card in mmyy format.

Webhook retry policy

Your platform must provide one of the following HTTP status codes upon receiving the Apaya webhook notification, otherwise our platform will consider it a failure and trigger a retry (if retries are configured):

200 (OK)
202 (Accepted)
204 (No Content)

The notification can be retried by the Apaya platform up to once per minute if one of the successful statuses are not received. Please provide your desired retry policy requirements to your Apaya Account Manager.