Skip to main content

Handle Transaction Events

Zastrpay Backend notifies the Distributor Backend about relevant transaction events (distributor should be interested mostly in the ...Completed ones) - e.g.

  • PassthroughDeposit (combined cash deposit + transfer to merchant) TransactionCompleted event could be handled by the Distributor Backend so that the transaction is added in the distributor's database, or submitted to tamper-proof cash register (Registrierkasse, KassenSichV)
  • CustomerDeposit (cash -> customer wallet) TransactionCompleted event - same as above
  • PassthroughWithdrawal (combined transfer merchant -> customer + cash withdrawal) TransactionCompleted event - same as above
  • CustomerWithdrawal (customer wallet -> cash) TransactionCompleted event - same as above
  • PassthroughDeposit TransactionDeclined/TransactionCancelled events result in no financial transaction, so may be of no interest to the distributor
  • PassthroughWithdrawal TransactionDeclined/TransactionCancelled events - same as above

For that purpose the Distributor 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 Distributor 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 Distributor supplies to Zastrpay upon creating the subscription.

note

The x-api-key for Zastrpay -> Distributor Backend calls is not the same as the x-api-key used for Distributor -> Zastrpay Backend calls (e.g. Get Transaction Intent Details). It is the one supplied upon creation of the subscription - see Subscribe, apiKey payload attribute below.

Handle Notification Request Zastrpay Backend -> Distributor Backend
POST https://distributor-host.com/zastrpay-listener/transaction-events
Content-Type: application/json
x-api-key: $ZastrpayToDistributorApiKey

{
  "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",
    "distributorId": "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"
  }
}
Handle Notification Response Distributor 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.

See Handle Transaction Event API Reference for more information.

Subscribe​

Subscription can be created in the following way:

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

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

}


Create Subscription Response Zastrpay Backend -> Distributor Backend
201 OK

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

note

Only Transaction events for transactions of the distributor (determined by the distributorToZastrpayApiKey) and specified event types will be sent to the listener endpoint.

note

The apiKey in the payload is used afterwards in the Zastrpay Backend -> Distributor 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 Distributor Backend -> Zastrpay Backend
DELETE https://host.com/transaction-service/v1/transaction-events/subscriptions/09e01040-ecba-459b-b5fa-ef5128906886
x-api-key: $distributorToZastrpayApiKey

Delete Subscription Response Zastrpay Backend -> Distributor Backend
200 OK

See Unsubscribe from Transaction Events API Reference for more information.