Subscribed Endpoint Validation

To allow the events to be sent to your endpoint, we require that the endpoint is validated to prevent a malicious user from flooding your service.

To validate your endpoint, it needs to participate in a handshake with Event Streamer.

When your endpoint has been subscribed to the event streamer, it will immediately send a validation event (as shown below) to your endpoint URL.

[
 { 
 "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" 
 }
]

Upon receiving the validation event your endpoint must echo back the validation code with a 200 response:

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

The validation response must be completed in 30 seconds of receiving the event or the Event Streamer will issue another validation event 5 seconds later.

If you unable to return the validation code in a 200 response, then you can manually validate your endpoint by visiting the validationURL contained in the validation event.

Please note: You may receive multiple validation events as the Event Streamer is hosted in multiple cloud locations for redundancy.

When the endpoint has been validated you will start to receive JSON event payloads from the Retail Network or MultiPay Service.

Note:  The Event Streamer runs within the Microsoft's Azure Datacenters where they have a range of rolling IP addresses, for details on the current IP addresses from which an event will be sent from, please refer to: https://www.microsoft.com/en-us/download/details.aspx?id=56519

BACK TO TOP   ⇧

Retail Transaction Payload

You can receive transaction events from our Retailer’s latest in store terminals, however legacy terminals unfortunately are unable to preform this real-time event function.

The retail transaction event payload will be sent to your endpoint in the following JSON format:

[ 
 { 
 "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" 
 } 
]

The data contained in the payload can then be extracted and used to update your internal systems for cash transactions that occurred across the Retail Network.

• 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

The MultiPay transaction event payload will be sent to your endpoint in the following JSON format:

[ 
 { 
 "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" 
 } 
]

Again the data contained in the payload can then be extracted and used to update your internal system for transactions that occurred across all MultiPay Payment Channels.

• 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   ⇧