Skip to main content

Handle Transaction Events

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

  • PassthroughDeposit (combined cash deposit + transfer to merchant) TransactionCompleted event should be handled by the Merchant Backend so that the deposited amount can be put onto the customer's wallet
  • CustomerToMerchantTransfer TransactionCompleted - same as above
  • PassthroughWithdrawal (combined transfer merchant -> customer + cash withdrawal) TransactionCompleted event should be handled by the Merchant Backend so that any initially blocked funds can be finally removed from the customer's wallet
  • MerchantToCustomerTransfer TransactionCompleted event - same as above
  • PassthroughWithdrawal TransactionDeclined/TransactionCancelled events should be handled by the Merchant Backend so that any initially blocked funds can be returned back to the customer's wallet
  • MerchantToCustomerTransfer TransactionDeclined/TransactionCancelled events - same as above

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 Transaction Intent). 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/transaction-events
Content-Type: application/json
x-api-key: $ZastrpayToMerchantApiKey

{
  "specversion": 1,
  "id": "92fb87e5-4b0c-4070-8c20-a258d82125e4",
  "source": "/transaction-service",
  "time": "2019-01-31T11:59:59Z",
  "datacontenttype": "application/json",
  "type": "TransactionCompleted",
  "data": {
    "id": "1516f8a1-f877-46e2-9784-8a1d7673fcb0",
    "customerId": "2c9c3085-86d7-4d2e-862d-6f32699614c3",
    "merchantId": "6b5fe448-3aa6-4435-8f12-51c235fb1465",
    "amount": 100.0,
    "currency": "EUR",
    "state": "Completed",
    "status": "Succeeded",
    "type": "PassthroughWithdrawal",
    "createdOn": "2023-01-30T11:09:24.759Z",
    "lastModifiedOn": "2023-01-31T11:09:19.759Z",
    "externalReference": "234abc22-33de-4444-5555-222222222222"
  }
}
Handle Notification Response Merchant Backend -> Zastrpay Backend
204 No Content
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.

note

The externalReference property contains the value submitted by the Merchant in the Create Redirect Session for a new Transaction Intent API call. This value can be used for looking up any transaction entity in the Merchant System which has been potentially created before redirecting the customer to Zastrpay.

See Handle Transaction 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/transaction-service/v1/transaction-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": [ "TransactionCompleted" ]

}


Create Subscription Response Zastrpay Backend -> Merchant Backend
201 OK

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

note

Only Transaction events for transactions of 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 Transaction 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/transaction-service/v1/transaction-events/subscriptions/09e01040-ecba-459b-b5fa-ef5128906886
x-api-key: $merchantToZastrpayApiKey

Delete Subscription Response Zastrpay Backend -> Merchant Backend
200 OK

See Unsubscribe from Transaction Events API Reference for more information.