Guides
Subscribe to event notifications
Receive and react to real-time event notifications from Imprint
Overview
You can subscribe to specific event types to receive real-time event notifications. This enables you to build efficient, event-driven workflows and respond promptly to changes in transaction activity, account status, and other critical events.How event notifications work
When an event occurs, Imprint willPOST to the endpoint configured. This event notification contains a JSON payload with details about the event.
As part of event notification enrollment, you will receive a secret shared only between Imprint and you.All requests are signed (HMAC SHA-256) using the shared secret.
For increased security, you can restrict your endpoint to only allow requests from Imprint’s IP Ranges, which can be provided by your Imprint team.
Your system should acknowledge events with a 2XX HTTP response status to confirm successful receipt. If a delivery fails, Imprint will retry the request based on an exponential back-off strategy.
Setup
To start receiving event notifications, please coordinate the following with your Imprint team:- Select events: subscribe to specific event types. For a description of each event notification, see the reference pages.
- Register your endpoint(s): provide at least one publicly accessible URL where events should be sent. You may provide multiple endpoints, e.g. one per event type. All endpoints must use HTTPS to ensure encrypted communication.
-
Store event signing token: your Imprint team will provide the secret key that you will use to validate the signature of incoming requests. Please see the signature verification page for more detail on how to interpret the
X-IMPRINT-HMAC-SIGNATUREheader. - Retry logic: implement idempotency handling to avoid processing duplicate events, as Imprint will retry failed webhook deliveries.
Examples
Transaction notifications
Below, we have provided more detail regarding the possible transaction statuses and expected transaction scenarios.Transaction statuses
| Status | Description |
|---|---|
APPROVED | Authorization request was received from the merchant and approved by Imprint, which creates a pending transaction on the customer’s statement. |
UPDATED | Authorization request was updated by the merchant, which updates the pending transaction on the customer’s statement. |
VOIDED | Approved authorization has been cancelled by the merchant or expired by Imprint, which removes the pending transaction from the customer’s statement. |
CAPTURED | Approved authorization has been captured, or a force capture has been created (e.g., bypassing the authorization step), which creates a confirmed transaction on the customer’s statement with the final purchase amount. |
REFUNDED | Refund has been created by the merchant, either related to a previous capture or standalone (e.g., “blind return”), which creates a confirmed transaction on the customer’s statement with the final refund amount. |
Use
transaction_id to track a transaction throughout the lifecycle of different statuses and event_id to identify each step uniquelyCommon transaction scenarios
1
Customer completes $50 purchase
As soon as the customer pays with their card, you will receive an
APPROVED event. However, it may take several hours for the merchant to finalize the transaction through the card network. Once a transaction is finalized, you will receive a CAPTURED event with the confirmed purchase amount. | Event ID | Transaction ID | Amount | Status |
|---|---|---|---|
| 123 | 123 | $50 | APPROVED |
| 234 | 123 | $50 | CAPTURED |
In some cases, merchants may bypass the
APPROVED step (e.g., force capture) or capture for more/less than the APPROVED amount. Regardless, CAPTURED always represents a confirmed purchase amount.2
Customer completes $50 purchase, which is partially captured multiple times
It’s possible for a merchant to capture a single transaction multiple times (e.g., single order split into multiple shipments). When this happens, you will receive multiple
CAPTURED events with the amount encompassing each individual charge. | Event ID | Transaction ID | Amount | Status | … |
|---|---|---|---|---|
| 123 | 123 | $50 | APPROVED | … |
| 234 | 123 | $20 | CAPTURED | … |
| 345 | 123 | $30 | CAPTURED | … |
3
Merchant updates transaction amount
It’s possible for merchants to authorize one amount initially and later request an updated authorization amount that is higher/lower. For example, automated fuel dispensers which authorize for ~$100 immediately and then update the authorization to the final purchase amount after the customer has finished pumping.
| Event ID | Transaction ID | Amount | Status | … |
|---|---|---|---|---|
| 123 | 123 | $100 | APPROVED | … |
| 234 | 123 | $50 | UPDATED | … |
| … | … | … | … | … |
4
Merchant cancels the order
If a merchant reverses an
APPROVED authorization or lets the authorization expire (e.g., after nine days without capture), you will receive a VOIDED event. | Event ID | Transaction ID | Amount | Status | … |
|---|---|---|---|---|
| 123 | 123 | $50 | APPROVED | … |
| 234 | 123 | $50 | VOIDED | … |
5
Customer completes $50 purchase, then receives a $30 refund
There can be multiple refunds associated with a transaction and you will receive a
REFUNDED event for each. In most cases, refunds are linked to an existing transaction (e.g., example below), but standalone refunds are possible as well.| Event ID | Transaction ID | Amount | Status | … |
|---|---|---|---|---|
| 123 | 123 | $50 | APPROVED | … |
| 234 | 123 | $50 | CAPTURED | … |
| 345 | 123 | $30 | REFUNDED | … |
6
$50 purchase is disputed and won by the customer
If the
CAPTURED transaction is disputed and won by the customer (e.g., example below), it translates to a new refund. If the dispute is lost, no change - it’s still a purchase on the customer’s statement. | Event ID | Transaction ID | Amount | Status | … |
|---|---|---|---|---|
| 123 | 123 | $50 | APPROVED | … |
| 234 | 123 | $50 | CAPTURED | … |
| 345 | 123 | $50 | REFUNDED | … |