Skip to main content

Handle Customer Events

Zastrpay Backend notifies the Merchant Backend about relevant customer events - e.g.

  • CustomerRegistered event should be handled by the Merchant Backend so that the customer can be marked in the Merchant's database as already registered with Zastrpay

For that purpose the Merchant has to first implement a webhook/notification listener endpoint, and then subscribe to the notifications by creating a subscription in Zastrpay Backend.

Implement a Listener Endpoint​

An https endpoint should be exposed by the Merchant for receiving notifications from Zastrpay. The endpoint should be secured by Source IP Restriction and authentication based on an API Key in x-api-key header, which the Merchant supplies to Zastrpay upon creating the subscription.

note

The x-api-key for Zastrpay -> Merchant Backend calls is not the same as the x-api-key used for Merchant -> Zastrpay Backend calls (e.g. Create Redirect Session for a new Customer Registration). It is the one supplied upon creation of the subscription - see Subscribe, apiKey payload attribute below.

Handle Notification Request Zastrpay Backend -> Merchant Backend
POST https://merchant-host.com/zastrpay-listener/customer-events
Content-Type: application/json
x-api-key: $ZastrpayToMerchantApiKey

{
  "specversion": 1,
  "id": "92fb87e5-4b0c-4070-8c20-a258d82125e4",
  "source": "/customer-service",
  "time": "2019-01-31T11:59:59Z",
  "datacontenttype": "application/json",
  "type": "CustomerRegistered",
  "data": {
    "id": "1516f8a1-f877-46e2-9784-8a1d7673fcb0",
    "state": "Active",
    "createdOn": "2023-01-30T11:09:24.759Z",
    "lastModifiedOn": "2023-01-31T11:09:19.759Z",
  }
}
Handle Notification Response Merchant Backend -> Zastrpay Backend
204 No Content
tip

The data.id or the Zastrpay customerId property is equal to the redirectSessionId generated and submitted by the Merchant in the Create Redirect Session for a new Customer Registration API call.

So as long as the Merchant saves the redirectSessionId (= Zastrpay customerId) together with its own customerId before redirecting the customer to Zastrpay, then it can match the incoming notification and mark the customer as registered at Zastrpay.

note

Note that Zastrpay Backend retries the notification only in case the listener returns 408 (timeout) and 429 (too many requests) as well as 5xx codes. In case of all other https status codes there is no retry.

See Handle Customer Event API Reference for more information.

Subscribe​

Subscription can be created in the following way:

Create Subscription Request Merchant Backend -> Zastrpay Backend
PUT https://host.com/customer-service/v1/customer-events/subscriptions/09e01040-ecba-459b-b5fa-ef5128906886
x-api-key: $merchantToZastrpayApiKey
X-Request-ID: e28ef801-f8f8-476a-9f5d-ed3844e8bb12

{
  "callbackUrl": "https://merchant-host.com/send/callback/here",
  "apiKey": "4EFRLXTFHJKmYKIE7yIsOk7EuLh6Gmh9aBF1FVO4",
  "eventTypes": [ "CustomerRegistered" ]

}


Create Subscription Response Zastrpay Backend -> Merchant Backend
201 OK

{
  "id": "{subscriptionId}",
  "callbackUrl": "https://merchant-host.com/send/callback/here",
  "eventTypes": [ "CustomerRegistered" ]
}

note

Only Customer events for customers whose registration was triggered by the merchant (determined by the merchantToZastrpayApiKey) and specified event types will be sent to the listener endpoint.

note

The apiKey in the payload is used afterwards in the Zastrpay Backend -> Merchant Backend webhook/notification call.

note

Create a single subscription for a set of event types.

Currently the uniqueness of subscriptions is validated only on the basis of the subscriptionId (passed in the path in case of creation/PUT operation, in case of retry the same "hardcoded" subscriptionId should be used), however Zastrpay reserves the right of introducing additional validations, as well as deleting duplicate subscriptions.

See Subscribe to Customer Events API Reference for more information.

Unsubscribe​

If an existing subscription is not desired anymore, then it can be deleted in the following way:

Delete Subscription Request Merchant Backend -> Zastrpay Backend
DELETE https://host.com/customer-service/v1/customer-events/subscriptions/09e01040-ecba-459b-b5fa-ef5128906886
x-api-key: $merchantToZastrpayApiKey

Delete Subscription Response Zastrpay Backend -> Merchant Backend
200 OK

See Unsubscribe from Customer Events API Reference for more information.