Skip to main content

Handle Redirect Session Events

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

  • RedirectSessionCancelled event could be handled by the Merchant Backend so that a potential reservation of wallet funds or order can be reliably reverted/cancelled in case the customer abandons the payment flow

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/redirect-session-events
Content-Type: application/json
x-api-key: $ZastrpayToMerchantApiKey

{
  "specversion": 1,
  "id": "92fb87e5-4b0c-4070-8c20-a258d82125e4",
  "source": "/customer-authentication-service",
  "time": "2019-01-31T11:59:59Z",
  "datacontenttype": "application/json",
  "type": "RedirectSessionCancelled",
  "data": {
    "id": "1516f8a1-f877-46e2-9784-8a1d7673fcb0",
    "state": "Cancelled",
    "type": "NewTransactionIntent",
    "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 redirectSessionId property is equal to the redirectSessionId generated and submitted by the Merchant in the Create a Redirect Session for a new Transaction Intent or Create Redirect Session for a new Customer Registration API call.

So as long as the Merchant saves the redirectSessionId (= Zastrpay transactionIntentId, transactionId or customerId) together with its own transaction/payment or customerId before redirecting the customer to Zastrpay, then it can match the incoming notification and find the corresponding merchant entity in the Merchant Backend.

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 Redirect Session 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-authentication-service/v1/redirect-session-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": [ "RedirectSessionCancelled" ]

}


Create Subscription Response Zastrpay Backend -> Merchant Backend
201 OK

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

note

Even though Zastrpay will attempt to capture any customer UI actions for cancelling the session (e.g. clicking on the X button top-right corner) and update the redirect session state in Zastrpay Backend which will automatically trigger RedirectSessionCancelled notification to the listener endpoint, it is still possible that the customer simply closes the browser/app which cannot be captured/reflected/notified. That is why the merchant must have additional measures in place to handle cases whereby it receives no RedirectSessionCancelled notification from Zastrpay but the customer states that the flow was cancelled.

note

It's recommended for the merchant to check that no TransactionIntent was created from the session when receiving the RedirectSessionCancelled event before taking any additional actions on their side. Zastrpay only guarantees that a customer is not able create a TransactionIntent from a cancelled session. It's still possible that a session gets cancelled, but the TransactionIntent was already created and could potentially be processed into a valid Transaction.

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 Redirect Session 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-authentication-service/v1/redirect-session-events/subscriptions/09e01040-ecba-459b-b5fa-ef5128906886
x-api-key: $merchantToZastrpayApiKey

Delete Subscription Response Zastrpay Backend -> Merchant Backend
200 OK

See Unsubscribe from Redirect Session Events API Reference for more information.