Notifications
Receive notifications about any changes related to your payments.
Overview
Unzer supports notifications for payment events that you can configure as webhooks.
Webhooks are individually defined HTTP callbacks from one website to another. They can go either way and are usually triggered by events. To keep your app or website up to date with any changes happening to your payments, you can register a webhook triggered by relevant events. To send notifications, we’re using the standard HTTP/1.1 protocol.
For the full list of webhook events supported by the Unzer API go to Supported webhook events.
To get the updated state of a resource:
- Don’t use the event name as an indicator of the state of a resource. To get the latest state of the resource, you should always fetch the resource using the Unzer API.
- Don’t use the event’s
retrieveUrl
to fetch the event’s resource without making sure the domain is legit. - Always fetch the event by creating an API request for the affected resource with correct Unzer API domain.
Step 1: Prepare your API
Other than meeting the basic requirements your API should also fulfill the following:
- Accept
text/plain
content-type requests - Respond with the standard HTTP
200 OK
success code, to acknowledge a received notification and prevent sending it again.
Notification examples
You’ll get notifications based on your public key, as a JSON payload. For example:
{
"event":"types",
"publicKey":"s-pub-xxxxxxxxxx",
"retrieveUrl":"https://api.unzer.com/v1/types/card/s-crd-88xu7qjboupc"
}
{
"event":"payment.pending",
"publicKey":"s-pub-xxxxxxxxxx",
"retrieveUrl":"https://api.unzer.com/v1/payments/s-pay-774",
"paymentId":"s-pay-774"
}
Error handling
If our system doesn’t receive the standard HTTP 200 OK
success code within 20 seconds, it tries to resend the notification in the following intervals:
Retry attempt | Interval |
---|---|
1 | 1–2 minutes after the initial webhook event |
2 | 5–6 minutes after the 1st retry attempt |
3 | 10–11 minutes after the 2nd retry attempt |
4 | 30–31 minutes after the 3rd retry attempt |
5 | 60–61 minutes after the 4th retry attempt |
6–16 (10 times) | Every 60 minutes |
If your API doesn’t respond after the last retry attempt, the notification gets marked as undeliverable
, and you can’t retrieve it anymore.
Step 2: Register event notification
Register a URL to which you want to get notifications, and specify the events that you want to get notified about.
Selected event types
To enable notifications for selected event use event
key. For example to trigger notifications for all charge
related events:
// 1. Creating Unzer instance with your private key
// Replace "s-priv-xxxxxxxxxx" with your actual Unzer Private Key
Unzer unzer = new Unzer("s-priv-xxxxxxxxxx");
// 2. Register webhook for AUTHORIZE events
// Replace "https://your.notification.handler.url" with your actual webhook endpoint
Webhook webhook = unzer.registerSingleWebhook(
new Webhook(
"https://your.notification.handler.url",
WebhookEventEnum.AUTHORIZE
)
);
The method returns a Webhook
object that stores the Unzer API response.
{
"id": "s-whk-1",
"event": "charge",
"url": "https://www.yourApiUrl.com/notifications"
}
To enable notifications for multiple events with one request call registerMultipleWebhooks
:
The method returns a Webhooks
object that stores the eventList
from the Unzer API response.
// 1. Creating Unzer instance with your private key
// Replace "s-priv-xxxxxxxxxx" with your actual Unzer Private Key
Unzer unzer = new Unzer("s-priv-xxxxxxxxxx");
// 2. Register multiple webhooks for different events
// Replace "https://your.notification.handler.url" with your actual webhook endpoint
WebhookList webhook = unzer.registerMultiWebhooks(
new Webhook(
"https://your.notification.handler.url",
Arrays.asList(
WebhookEventEnum.AUTHORIZE, // Triggered when authorization occurs
WebhookEventEnum.CHARGE, // Triggered when charge occurs
WebhookEventEnum.SHIPMENT // Triggered when shipment occurs
)
)
);
{
"events": [
{
"id": "s-whk-3",
"url": "https://www.yourApiUrl.com/notifications",
"event": "authorize"
},
{
"id": "s-whk-4",
"url": "https://www.yourApiUrl.com/notifications",
"event": "charge"
},
{
"id": "s-whk-5",
"url": "https://www.yourApiUrl.com/notifications",
"event": "shipment"
}
]
}
All events
To get notified about every single event, set event
to all
, for example:
// 1. Creating Unzer instance with your private key
// Replace "s-priv-xxxxxxxxxx" with your actual Unzer Private Key
Unzer unzer = new Unzer("s-priv-xxxxxxxxxx");
// 2. Register webhook for ALL event types
// Replace "https://your.notification.handler.url" with your actual webhook endpoint
Webhook webhook = unzer.registerSingleWebhook(
new Webhook(
"https://your.notification.handler.url",
WebhookEventEnum.ALL // Registers webhook for all available event types
)
);
Step 3: Manage webhooks
Using Unzer API webhooks
endpoint you can retrieve, update and delete your webhooks.
Retrieve webhooks
The Java SDK does not support fetching by Webhook-ID as of now.
To retrieve all of your existing webhooks, call the Unzer.getWebhooks
method with no webhook ID:
// 1. Creating Unzer instance with your private key
// Replace "s-priv-xxxxxxxxxx" with your actual Unzer Private Key
Unzer unzer = new Unzer("s-priv-xxxxxxxxxx");
// 2. Retrieve all registered webhooks
WebhookList webhookList = unzer.getWebhooks();
Update webhooks
To update the URL of an existing webhook, call the Unzer.updateWebhook
method, with the edited webhook object.
// 1. Creating Unzer instance with your private key
// Replace "s-priv-xxxxxxxxxx" with your actual Unzer Private Key
Unzer unzer = new Unzer("s-priv-xxxxxxxxxx");
// 2. Update webhook with new URL
// First get the webhook object you want to update using webhookId
webhook.setUrl("https://newNotificationUrl.com"); // Replace with your new webhook URL
// 3. Update the webhook in Unzer system
// Replace "webhookId" with your actual webhook ID
unzer.updateSingleWebhook(webhookId, webhook);
Delete webhooks
To delete an existing webhook, call the Unzer::updateWebhook
method, with the webhook’s ID as parameter:
// 1. Creating Unzer instance with your private key
// Replace "s-priv-xxxxxxxxxx" with your actual Unzer Private Key
Unzer unzer = new Unzer("s-priv-xxxxxxxxxx");
// 2. Delete a specific webhook
// Replace "s-whk-1" with your actual webhook ID
Webhook webhook = unzer.deleteSingleWebhook("s-whk-1");
To delete all of your existing webhooks, call the Unzer::updateWebhook
method with no parameter:
// 1. Creating Unzer instance with your private key
// Replace "s-priv-xxxxxxxxxx" with your actual Unzer Private Key
Unzer unzer = new Unzer("s-priv-xxxxxxxxxx");
// 2. Delete all registered webhooks
WebhookList webhook = unzer.deleteMultiWebhook();
For details on Unzer API webhook calls, please check API reference guide.
Handle incoming events
Whenever an event is triggered, the corresponding URL is called. The POST request contains the json-information about the event which you can use to fetch the corresponding resource which in turn can be used to update the state of the order or payment in your shop.