Subscribed Endpoint Validation

To protect you against malicious traffic, every endpoint must validate itself before receiving live events. Validation is completed using a standard Event Grid handshake.

How Validation Works

1. When your endpoint is subscribed, Event Streamer immediately sends a Subscription Validation Event to your webhook URL.

2. Your endpoint must respond within 30 seconds with the required validation code.

3. If no valid response is received, Event Streamer retries validation 5 seconds later.

4. Multiple validation events may occur because Event Streamer is deployed across multiple regions.

Example Validation Event

[
 { 
 "id": "2d1781af-3a4c-4d7c-bd0c-e34b19da4e66", 
 "topic": "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", 
 "subject": "", 
 "data": 
 { 
 "validationCode": "512d38b6-c7b8-40c8-89fe-f46f9e9622b6", 
 "validationUrl": "https://rp-eastus2.eventgrid.azure.net:553/eventsubscriptions/estest/validate?id=512d38b6-c7b8-40c8-89fe-f46f9e9622b6&t=2018-04-26T20:30:54.4538837Z&apiVersion=2018-05-01-preview&token=1A1A1A1A" 
 }, 
 "eventType": "Microsoft.EventGrid.SubscriptionValidationEvent", 
 "eventTime": "2018-01-25T22:12:19.4556811Z", 
 "metadataVersion": "1", "dataVersion": "1" 
 }
]

Required Response

Your endpoint must return HTTP 200 with:

{ 
 "validationResponse": "512d38b6-c7b8-40c8-89fe-f46f9e9622b6" 
}

If the endpoint cannot respond programmatically, you may manually validate it by opening the validationUrl contained in the event.

IP Addresses

Event Streamer operates inside Microsoft Azure data centres and uses dynamic IP ranges.
For current IPs, download:
https://www.microsoft.com/en-us/download/details.aspx?id=56519

Filter for:

• AzureEventGrid.UKSouth

• AzureEventGrid.UKWest

BACK TO TOP   ⇧

Retail Transaction Payload

Real‑time Retail Network events are generated by the latest in‑store terminals. Legacy terminals do not support event streaming.

Retail Transaction Payload Example

[ 
 { 
 "id": "500", 
 "subject": "Terminal Upload", 
 "data": 
 { 
 "SiteNumber": "10808", 
 "TerminalIdentifier": "22065059", 
 "TransactionNumber": "1224", 
 "TransDateTime": "2020-04-28 12:20:56", 
 "Amount": "100", 
 "CustomerNumber": "633729332662", 
 "TransType": "6", 
 "ClientId": "505", 
 "SchemeId": "2254", 
 "OriginalTransNumber": "0", 
 "TransStatus": "0", 
 "CreditFlag": "1", 
 "ServiceUserData": "323235343030373933" 
 }, 
 "eventType": "recordInserted", 
 "eventTime": "2020-04-28T15:47:24.486662Z", 
 "dataVersion": "1.0", 
 "metadataVersion": "1", 
 "topic": "/subscriptions/becb8d8f-f0ae-4df0-8c6e-ae68c5343783/resourceGroups/deaz-resr-mpa-uks/providers/Microsoft.EventGrid/topics/ukretailseventout-mp-1005-suk-egt" 
 } 
]

Event Parameters

• SiteNumber - The site identifier in the PayPoint Retail Network

• TerminalIdentifier - The terminal that took the transaction

• TransactionNumber - The unique transaction identifier

• TransDateTime - The date time transaction stamp (yyyy-mm-dd hh:mm:ss)

• Amount - The transaction amount in minor currency units, i.e. 1000 equals £10.00

• CustomerNumber - The customer identifier or Top-up PAN (Fixed 22 characters with prefixed whitespacing)

• TransType - 5=refund, 6=sale, 7=advice

• ClientId - PayPoint's unique identifier for you as a client

• SchemeId - PayPoint's unique identifier for your product/scheme

• OriginalTransNumber - The original transaction identifier that has been refunded or voided

• TransStatus - 0=success, 1=failure

• CreditFlag - Indicator for a Cash Out transaction

• ServiceUserData - Additional data regarding the transaction, i.e. a Vend UTRN

BACK TO TOP   ⇧

MultiPay Transaction Payload

These events provide real‑time visibility across all MultiPay digital channels: MOBILE / WEB / IVR / SMS / PAYBYLINK / MOTO / RECURRING

[ 
 { 
 "id": "500", 
 "subject": "Multipay Upload", 
 "data": 
 { 
 "TransactionNumber": "1000087235", 
 "Amount": "1300", 
 "ClientID": "612", 
 "TransDateTime": "2020-06-10 09:44:57Z", 
 "Channel": "MOBILE/WEB/IVR/SMS/PAYBYLINK/MOTO/RECURRING", 
 "CustomerNumber": "9826003801000000007", 
 "UserName": "Guest User"/null, 
 "TransType": "Sale/Verify/Refund", 
 "TransStatus": ""Payment Success", 
 "ClientKey": "{CLient Name}", 
 "UTRN": "0987654321123456789"/null
 }, 
 "eventType": "recordInserted", 
 "dataVersion": "v1", 
 "metadataVersion": "1", 
 "eventTime": "2020-06-10T09:45:18.0061503Z", 
 "topic": "/subscriptions/becb8d8f-f0ae-4df0-8c6e-ae68c5343783/resourceGroups/deaz-resr-mpa-uks/providers/Microsoft.EventGrid/topics/ukretailseventout-mp-1005-suk-egt" 
 } 
]

Event Parameters

• TransactionNumber - The unique transaction identifier

• Amount - The transaction amount in minor currency units, i.e. 1000 equals £10.00

• ClientId - PayPoint's unique identifier for you as a client

• TransDateTime - The date time transaction stamp (yyyy-mm-dd hh:mm)

• Channel - The sale channel that took the transaction: MOBILE/WEB/IVR/SMS/PAYBYLINK/MOTO/RECURRING

• CustomerNumber - The customer identifier or Top-up PAN

• UserName - The stored username/email of the customer if applicable, null if TransType=Refund

• TransType - Sale/Verify/Refund

• TransStatus - Payment Success/Payment Fail/Vend Fail/Refund Success/Other

• ClientKey - PayPoint's name for the client

• UTRN - Additional Data outside to the transaction authorisation, i.e. a Vend UTRN, null if TransType=Refund

BACK TO TOP   ⇧

Direct Debit Events

 When you subscribe to the Direct Debit Event Steamer you will receive events for the creation and management of the Direct Debit Instruction, and details of each of the payments take for that instruction. The following events are available: 

Instruction Events

•   InstructionImported

• InstructionCreated

• InstructionAmended

• ScheduleAmended

• InstructionSuspended

• InstructionResumed

• InstructionInvalidated

• InstructionCancelled

• InstructionReinstated

• InstructionSubmitted

• LiveInstructionChanged

Example Instruction Created Payload

{
  "event" : "instructionCreated",
  "date" : "2021-09-02T05:22:12",
  "originator" : "j.merryweather@baa.com",
  "application" : "PayPointPortal",
  "clientKey" : "OPT1245",
  "paymentInstruction" : {
    "instructionId": "908d03de-ce2e-4ea0-a9c0-541d725bb34d",
    "batchId": "111d03de-ce2e-2411-a9c0-441d725bb33f",
    "clientInstructionRef": "A987654321",
    "status": "Pending",
    "statusChangedDate": "2021-12-02T00:00:00",
    "paymentMethodId" : "DirectDebit",
    "paymentMethod": {
      "sun": "512622",
      "ddRef": "GFF re 124552",
      "ddInstructionType": "DDI",
      "ddTransaction" : "",
      "payer": {
         "tradingName": "",
         "name": "T Morgan",
         "address": {
           "address1": "3",
           "address2": "Tin Road,
           "address3": "",
           "town": "Marnseworth",
           "postCode": "TT12 4GF",
           "telephone": "01242 123 522"
         },
         "account": {
           "name": "T Morgan",
           "sortCode": "203044",
           "accountNumber": "12344321,
         },
         "notification": {
           "email": "t.morgan@hotmail.com",
           "mobile": "+448855654128"
         }
      }
  },
  "schedule": {
     "amount": "20.00",
     "interval": "Month",
     "intervalUnit": 1,
     "startDate": "2021-12-10T00:00:00",
     "endDate": "2022-12-10T00:00:00"
   }
 }
}

Payment Events

• PaymentScheduled

• PaymentAmended

• PaymentCancelled

• PaymentSubmitted

• PaymentCollected

• PaymentRejected

• PayByLinkRaised

Example Payment Collected Payload

{
  "event" : "paymentCollected",
  "date" : "2021-09-02T05:22:12",
  "originator" : "System",
  "application" : "System",
  "clientKey" : "OPT1245",
  "payment" : {
    "paymentId" : "77d8af94-61f2-4cc3-a03b-b7db729650f2",
    "amount": 45.50,
    "currency": "GBP",
    "collectionDate": "2021-05-01T00:00:00",
    "paymentMethodId": "DirectDebit",
    "paymentMethod": {
      "SUN": "512622",
      "ddRef": "DDI-12345678",
      "ddTransaction": "17"
    }
  }
}

For more examples of the different payloads, please contact your Client Manager.

BACK TO TOP   ⇧

i-movo Voucher Redemption Confirmation

The i-movo Voucher Redemption Confirmation event streamer has been designed to allow your back office services to be informed when an attempt to redeem a voucher from one of your campaigns is made. You will need to provide an URL for your endpoints/webhooks to receive the real time Redemption Confirmation event via HTTP.

Please email your i-movo Client Manager details of your endpoint to enable them to  validate the endpoint and enable this service.

The i-movo voucher  redemption confirmation event will be sent to your endpoint as shown in the examples below:

http://{CLIENT ENDPOINT URL/}?vnum=5739274739&address=Spar%2c+27+University+Avenue%2cBelfast&postcode=BT7+1GX&value=85.00&redemptiondate=17-07-10+12-34-32&narrative=Redeemed

Or

http://{CLIENT ENDPOINT URL/}?vnum=34536197946&address=Spar%2c+27+University+ Avenue%2cBelfast&postcode=BT7+1GX&value=&redemptiondate=13-01-2012+13-09-58&narrative= Redemption+Rejected%3AVoucher+Expired

Your endpoint   will need to accept the following parameters:

• vnum - [alphanumerical] The voucher number which has just been redeemed. Assuming your system has been integrated with i-movo to record the unique voucher number issued to each customer then your system will relate this number to the customer benefiting from the voucher.

• address  - [string] The address of the outlet which performed the voucher redemption.

• postcode  - [string] The postcode of the outlet which performed the voucher redemption.

• value  - [numerical] The face value of the voucher which was redeemed.

•  redemptiondate  - [date/time] The exact time recorded for when the redemption took place.

• narrative  - [string] Text to show the result of the redemption attempt e.g. “Redeemed”, “Redemption Rejected: Insufficient Balance” etc. The i-movo Voucher Service can be configured to sent you  an event  to your endpoint only as a result of a successful redemption, or only as a result of a rejection, or both.

BACK TO TOP   ⇧

Event Delivery & Retries

Event Streamer considers only the following HTTP response codes as successful deliveries. All other status codes are considered failed deliveries and will be retried or deadlettered as appropriate. When Event Streamer receives a successful status code, it considers delivery complete.

• 200 OK

• 201 Created

• 202 Accepted

• 203 Non-Authoritative Information

• 204 No Content

When Event Streamer receives an error for an event delivery attempt, Event Streamer decides whether it should retry the delivery, dead-letter the event, or drop the event based on the type of the error.

If the error returned by the subscribed endpoint is a configuration-related error that can't be fixed with retries (for example, if the endpoint is deleted), Event Streamer will perform dead-lettering on the event.

The following list describes the types of errors for which retry doesn't happen:

• 400 (Bad request)

• 413 (Request entity is too large)

• 401 (Unauthorized)

If the error returned by the subscribed endpoint isn't among the above list, Event Grid performs the retry as described below:

Event Streamer waits 30 seconds for a response after delivering a message. After 30 seconds, if the endpoint hasn’t responded, the message is queued for retry. Event Steamer uses an exponential backoff retry policy for event delivery. Event Stream retries delivery on the following schedule on a best effort basis:

• 10 seconds

• 30 seconds

• 1 minute

• 5 minutes

• 10 minutes

• 30 minutes

• 1 hour

• 3 hours

• 6 hours

• Every 12 hours up to 24 hours

If the endpoint responds within 3 minutes, Event Stream attempts to remove the event from the retry queue on a best effort basis, but duplicates may still be received.

Event Streamer adds a small randomisation to all retry steps and may opportunistically skip certain retries if an endpoint is consistently unhealthy, down for a long period, or appears to be overwhelmed.

BACK TO TOP   ⇧