> ## Documentation Index
> Fetch the complete documentation index at: https://imprint-b3c5d5af-partner-docs-latest.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Event notifications

Event Notifications contain

* an `object` field which designates the type of event notification, e.g. `APPLICATION`, `PAYMENT_METHOD`, `TRANSACTION`, `REWARD`, `CUSTOMER_LINK`, `STREAK`, or `ACCOUNT_STATUS`.
* a `data` field that includes details about the event

The event types documented below use the v2 payload format. On v2 payloads, `data` also carries `merchant_key` (when a merchant key is configured for the product) and `customer_metadata` (when the customer has partner metadata containing it). Both are enrichments applied at delivery time, so treat them as present on a best-effort basis rather than guaranteed.

### Application Event

Receive a notification regarding a credit card application.

`object` equals `APPLICATION`

`data` field structure

| PROPERTY NAME | REQUIRED | TYPE | DESCRIPTION |
| - | - | - | - |
| `merchant_key` | FALSE | String | Unique identifier for the merchant associated with this event. Present when a merchant key is configured for the product. |
| `customer_id` | FALSE | String | Unique identifier of the customer. Present once a customer profile exists; may be absent on a `REJECTED` event if no profile was created. |
| `partner_customer_id` | FALSE | String | Partner's unique identifier of the customer. Present only if provided at session creation. |
| `application_id` | TRUE | String | Imprint's unique identifier for the application. Pass it to `GET /v2/applications/{application_id}` for the full application state. |
| `status` | TRUE | String | Current status of the application. Uses the same vocabulary returned by `GET /v2/applications/{application_id}`. |
| `reason_code` | FALSE | String | Why the application reached this status. Present for `REJECTED` and `IDV_REQUIRED`. Treat an unrecognized code as an unhandled default rather than an error. |
| `recoverable` | FALSE | Boolean | Whether the applicant can act to move this outcome forward. Present for `REJECTED` and `IDV_REQUIRED`. |
| `created_at` | TRUE | Timestamp | RFC-3339 date application was created |
| `updated_at` | TRUE | Timestamp | RFC-3339 date application was updated |
| `expires_at` | FALSE | Timestamp | The RFC-3339 timestamp after which the application expires if it has not been completed. Omitted when not yet known, such as on the initial `IN_PROGRESS` / `EVALUATING` event. |
| `upgraded` | TRUE | Boolean | Whether this application represents an upgrade/graduation of an existing account. Currently always `false`. |
| `customer_metadata` | FALSE | Object | Key-value pairs of metadata attached to the customer. Present when the customer has partner metadata containing it; delivered on a best-effort basis. |

Example:

```json theme={null}
{
  "object": "APPLICATION",
  "data": {
    "merchant_key": "MERCHANT_ABC",
    "customer_id": "2EE24580-B97B-4949-A65C-929CCB9B9B8D",
    "partner_customer_id": "PARTNER_USER_456",
    "application_id": "APP-7F3C1E20-4B8A-4E11-9C6D-2A5F0B7D3E91",
    "status": "OFFER_ACCEPTED",
    "created_at": "2025-02-13T19:08:07.000Z",
    "updated_at": "2025-02-13T19:08:07.000Z",
    "expires_at": "2025-03-10T19:08:07.000Z",
    "upgraded": false,
    "customer_metadata": {
      "loyalty_id": "840012345678",
      "membership_tier": "gold"
    }
  }
}
```

Example of a rejected application, where `reason_code` and `recoverable` are populated:

```json theme={null}
{
  "object": "APPLICATION",
  "data": {
    "merchant_key": "MERCHANT_ABC",
    "customer_id": "2EE24580-B97B-4949-A65C-929CCB9B9B8D",
    "partner_customer_id": "PARTNER_USER_456",
    "application_id": "APP-7F3C1E20-4B8A-4E11-9C6D-2A5F0B7D3E91",
    "status": "REJECTED",
    "reason_code": "CREDIT_FILE_FROZEN",
    "recoverable": true,
    "created_at": "2025-02-13T19:08:07.000Z",
    "updated_at": "2025-02-13T19:08:07.000Z",
    "expires_at": "2025-03-10T19:08:07.000Z",
    "upgraded": false
  }
}
```

### Application Statuses

Application `status` values include:

| Status | Description |
| - | - |
| `OFFER_ACCEPTED` | The credit offer has been accepted by the customer, and they are now a member. This is a terminal state — the application is complete and will not change status again. |
| `REJECTED` | The application has been rejected by Imprint. This is a terminal state — the application is complete and will not change status again. |

### Payment Method Event

Receive a notification when a payment method is created (e.g. new credit card account) or updated (e.g. virtual card reissued)

`object` equals `PAYMENT_METHOD`

`data` field structure

| PROPERTY NAME | REQUIRED | TYPE | DESCRIPTION |
| - | - | - | - |
| `merchant_key` | FALSE | String | Unique identifier for the merchant associated with this event. Present when a merchant key is configured for the product. |
| `payment_method_id` | TRUE | String | Unique identifier of the payment method |
| `customer_id` | TRUE | String | Unique identifier of the customer |
| `partner_customer_id` | FALSE | String | Partner's unique identifier of the customer |
| `card_design_id` | FALSE | String | Unique identifier of the card design |
| `card_type` | TRUE | String | Type of card: `VIRTUAL`, `PHYSICAL`, or `UNIFIED` |
| `product_type` | FALSE | String | Type of financial product the payment method belongs to: `CREDITCARD` or `SECUREDCREDITCARD` |
| `previous_status` | FALSE | String | Old status of the payment method: `ACTIVE`, `INACTIVE`, or `CANCELED` |
| `new_status` | FALSE | String | New status of the payment method: `ACTIVE`, `INACTIVE`, or `CANCELED` |
| `tokens` | FALSE | Array | List of tokens associated with the payment method. Only present if the card is tokenized (see below) |
| `created_at` | TRUE | Timestamp | RFC-3339 date payment method was created |
| `updated_at` | FALSE | Timestamp | RFC-3339 date payment method was updated |
| `customer_metadata` | FALSE | Object | Key-value pairs of metadata attached to the customer. Present when the customer has partner metadata containing it; delivered on a best-effort basis. |

`tokens` field structure

| PROPERTY NAME | REQUIRED | TYPE | DESCRIPTION |
| - | - | - | - |
| `type` | TRUE | String | Token provider: `ADYEN`, `APPLE_WALLET`, `CYBERSOURCE`, or `WORLDPAY` |
| `token` | TRUE | String | The token, as defined by the processor |
| `created_at` | TRUE | Timestamp | RFC-3339 date token was created |
| `updated_at` | TRUE | Timestamp | RFC-3339 date token was updated |
| `pan_reference_id` | FALSE | String | An ID that represents the PAN and is defined by the processor. Only present for processors that expose a separate PAN reference |
| `expires_at` | FALSE | Timestamp | Only present for tokens that expire. If this field is absent, the token has no expiration and no action is needed. When present, the RFC-3339 date after which the token can no longer be used. A timestamp in the past means the token is stale and should not be used. Retrieving the payment method refreshes expired tokens where possible; if a newly retrieved token's `expires_at` is still in the past, it cannot be used. |

Example:

```json theme={null}
{
  "object": "PAYMENT_METHOD",
  "data": {
    "merchant_key": "MERCHANT_ABC",
    "payment_method_id": "DCBFC736-2286-42DD-897D-160DCA80AED2",
    "customer_id": "2EE24580-B97B-4949-A65C-929CCB9B9B8D",
    "partner_customer_id": "PARTNER_USER_456",
    "card_design_id": "3b9c1f3e-52a0-44c1-b131-a7ab0099a214",
    "card_type": "VIRTUAL",
    "product_type": "CREDITCARD",
    "new_status": "ACTIVE",
    "tokens": [
      {
        "type": "WORLDPAY",
        "token": "<string>",
        "created_at": "2025-02-13T19:08:07.000Z",
        "updated_at": "2025-02-13T19:08:07.000Z",
        "expires_at": "2025-02-14T19:08:07.000Z"
      }
    ],
    "created_at": "2025-02-13T19:08:07.000Z",
    "updated_at": "2025-02-13T19:08:07.000Z",
    "customer_metadata": {
      "loyalty_id": "840012345678",
      "membership_tier": "gold"
    }
  }
}
```

Payment method `status` values include:

* `ACTIVE` - Payment method is active and available for use.

* `INACTIVE` - Payment method is paused or has not yet been activated by the customer.

* `CANCELED` - Payment method has been permanently canceled due to customer request or account closure.

#### Status Transitions By Card Type

**Virtual Cards**

Virtual cards are always created in `ACTIVE` status.

* `ACTIVE` → `INACTIVE` — Customer pauses their card.
* `ACTIVE` → `CANCELED` — Customer cancels their card or closes their account.
* `INACTIVE` → `CANCELED` — Customer cancels their card or closes their account.

**Physical Cards**

Physical cards are always created in `INACTIVE` status and transition to `ACTIVE` when the customer initiates activation.

* `INACTIVE` → `ACTIVE` — Customer activates their physical card.
* `ACTIVE` → `INACTIVE` — Customer pauses their card.
* `ACTIVE` → `CANCELED` — Customer cancels their card or closes their account.
* `INACTIVE` → `CANCELED` — Customer cancels their card or closes their account.

**Unified Cards**

Unified cards are created in `ACTIVE` status. They serve both online and in-person use cases with a single set of card details.

* `ACTIVE` → `INACTIVE` — Customer pauses their card.
* `ACTIVE` → `CANCELED` — Customer cancels their card or closes their account.
* `INACTIVE` → `CANCELED` — Customer cancels their card or closes their account.

**Reissued Cards**

When a card is reissued (virtual or physical), you will receive:

1. A `CANCELED` webhook for the old card.
2. A new payment method webhook for the replacement card (`ACTIVE` for virtual, `INACTIVE` for physical).

### Transaction Event

Receive a notification when a `transaction` is created or transitions statuses.

`object` equals `TRANSACTION`

`data` field structure

| PROPERTY NAME | REQUIRED | TYPE | DESCRIPTION |
| - | - | - | - |
| `merchant_key` | FALSE | String | Unique identifier for the merchant associated with this event. Present when a merchant key is configured for the product. |
| `transaction_id` | TRUE | String | Unique identifier of the transaction |
| `event_id` | TRUE | String | Unique identifier of the event |
| `intent_id` | FALSE | String | Unique identifier of the transaction intent. Nullable. |
| `payment_method_id` | TRUE | String | Unique identifier of the payment method |
| `customer_id` | TRUE | String | Unique identifier of the customer |
| `partner_customer_id` | FALSE | String | Partner's unique identifier of the customer |
| `status` | TRUE | String | New status of the transaction |
| `created_at` | TRUE | Timestamp | RFC-3339 date transaction was first approved |
| `updated_at` | FALSE | Timestamp | RFC-3339 date of the event. Nullable. |
| `amount` | TRUE | Integer | Amount of the transaction, all positive values |
| `authorization_code` | FALSE | String | Code used to authorize the transaction. Nullable. |
| `network_transaction_id` | FALSE | String | Unique identifier of the transaction, assigned by the payment network, e.g. Visa, Mastercard, Amex. Nullable. |
| `purchase_method` | FALSE | String | How the purchase was completed |
| `product_type` | FALSE | String | The type of financial product the transaction belongs to. One of `CREDITCARD` or `SECUREDCREDITCARD`. Present only for card products. |
| `currency` | TRUE | String | Currency of the transaction, e.g. "USD" |
| `merchant` | FALSE | Object | Merchant information. Contains nested fields (see below). |
| `customer_metadata` | FALSE | Object | Key-value pairs of metadata attached to the customer. Present when the customer has partner metadata containing it; delivered on a best-effort basis. |

`merchant` field structure

| Property Name | Required | Type | Description |
| - | - | - | - |
| `network_id` | TRUE | String | Unique identifier of the merchant, assigned by the payment network (e.g., Visa, Mastercard, Amex). |
| `name` | TRUE | String | Name of the merchant where the transaction occurred. |
| `address` | FALSE | Object | Merchant address details (see below). |
| `category` | FALSE | String | Name of the merchant category (e.g., `"Grocery Stores"`). |
| `category_code` | FALSE | String | Code associated with the merchant category (e.g., `"5411"`). |

`address` Field Structure

| Property Name | Required | Type | Description |
| - | - | - | - |
| `street_line1` | FALSE | String | First line of the merchant's address. |
| `street_line2` | FALSE | String | Second line of the merchant's address. |
| `city` | FALSE | String | City in the merchant's address. |
| `state` | FALSE | String | State in the merchant's address. |
| `postal_code` | FALSE | String | Postal code in the merchant's address. |
| `country` | FALSE | String | Country in the merchant's address. |

Example:

```json theme={null}
{
  "object": "TRANSACTION",
  "data": {
    "merchant_key": "MERCHANT_ABC",
    "transaction_id": "e2806932-5f1b-4518-8b15-156d773e9496",
    "event_id": "e2806932-5f1b-4518-8b15-156d773e9496",
    "intent_id": "intent-12345",
    "payment_method_id": "7f754378-dd84-4a9a-b1ce-0646bb769c29",
    "customer_id": "e0549550-90e9-4acb-b7e9-2e4738b7def2",
    "partner_customer_id": "PARTNER_USER_456",
    "status": "APPROVED",
    "created_at": "2025-02-27T18:11:32.358Z",
    "updated_at": "2025-02-27T18:15:00.000Z",
    "amount": 5000,
    "currency": "USD",
    "authorization_code": "645432",
    "network_transaction_id": "txn-789456",
    "purchase_method": "CHIP",
    "product_type": "CREDITCARD",
    "merchant": {
      "network_id": "234923454545",
      "name": "Target",
      "category": "Grocery Stores",
      "category_code": "5411",
      "address": {
        "street_line1": "123 Main St",
        "street_line2": "Apt 4B",
        "city": "San Francisco",
        "state": "CA",
        "postal_code": "94105",
        "country": "USA"
      }
    },
    "customer_metadata": {
      "loyalty_id": "840012345678",
      "membership_tier": "gold"
    }
  }
}
```

Transaction `purchase_method` values include:

* `CHIP`

* `CONTACTLESS`

* `KEYEDIN`

* `ONLINE`

* `SWIPE`

* `QRCODE`

* `OCR`

Transaction`status` values include:

* `APPROVED` - Authorization request was received from the merchant and approved by Imprint. This creates a pending transaction on the customer's statement.

* `UPDATED` - Authorization request was updated by the merchant. The pending transaction was updated.

* `VOIDED` - Approved authorization has been cancelled by the merchant or expired by Imprint, resulting in the pending transaction being removed from the customer's statement.

* `CAPTURED` - Approved authorization has been captured, or a force capture has been created (bypassing the authorization step). This creates a confirmed purchase transaction on the customer's statement.

* `REFUNDED` - Refund has been created by the merchant, either related to a previous capture or standalone (e.g. blind return). This results in a confirmed refund transaction on the customer's statement.

<img src="https://mintcdn.com/imprint-b3c5d5af-partner-docs-latest/4ntTQ7yQXjXq_7bP/images/2.17_APIDocs-TransactionsFlow(3).png?fit=max&auto=format&n=4ntTQ7yQXjXq_7bP&q=85&s=5f89227cad201c9693b9ed0d3bc75d4c" alt="" width="4417" height="1196" data-path="images/2.17_APIDocs-TransactionsFlow(3).png" />

#### Transaction Event Examples

Webhook 1: Customer's successfully authorized a \$50 transaction at Shell

```json theme={null}
{
  "object": "TRANSACTION",
  "data": {
    "amount": 5000,
    "authorization_code": "645432",
    "created_at": "2025-02-27T18:11:32.358Z",
    "currency": "USD",
    "customer_id": "e0549550-90e9-4acb-b7e9-2e4738b7def2",
    "event_id": "e2806932-5f1b-4518-8b15-156d773e9496",
    "merchant": {
      "address": {
        "city": "New York",
        "country": "USA",
        "postal_code": "10002",
        "state": "NY",
        "street_line1": "",
        "street_line2": ""
      },
      "category": "Gas Station",
      "category_code": "5541",
      "network_id": "234923454545",
      "name": "Shell Gas"
    },
    "object": "TRANSACTION",
    "payment_method_id": "7f754378-dd84-4a9a-b1ce-0646bb769c29",
    "product_type": "CREDITCARD",
    "purchase_method": "CHIP",
    "status": "APPROVED",
    "transaction_id": "e2806932-5f1b-4518-8b15-156d773e9496",
    "updated_at": "2025-02-27T18:11:32.358Z"
  }
}
```

Webhook 2: Customer's authorization was updated to \$34.51

```json theme={null}
{
  "object": "TRANSACTION",
  "data": {
    "amount": 3451,
    "authorization_code": "645432",
    "created_at": "2025-02-27T18:11:32.358Z",
    "currency": "USD",
    "customer_id": "e0549550-90e9-4acb-b7e9-2e4738b7def2",
    "event_id": "8a13cc75-0432-4255-91d1-ac7e8e0db1b0",
    "merchant": {
      "address": {
        "city": "New York",
        "country": "USA",
        "postal_code": "10002",
        "state": "NY",
        "street_line1": "",
        "street_line2": ""
      },
      "category": "Gas Station",
      "category_code": "5541",
      "network_id": "234923454545",
      "name": "Shell Gas"
    },
    "object": "TRANSACTION",
    "payment_method_id": "7f754378-dd84-4a9a-b1ce-0646bb769c29",
    "product_type": "CREDITCARD",
    "purchase_method": "CHIP",
    "status": "UPDATED",
    "transaction_id": "e2806932-5f1b-4518-8b15-156d773e9496",
    "updated_at": "2025-02-28T01:11:32.358Z"
  }
}
```

Webhook 3: Transaction was captured

```json theme={null}
{
  "object": "TRANSACTION",
  "data": {
    "amount": 3451,
    "authorization_code": "645432",
    "created_at": "2025-02-27T18:11:32.358Z",
    "currency": "USD",
    "customer_id": "e0549550-90e9-4acb-b7e9-2e4738b7def2",
    "event_id": "8b272a5c-0e40-4144-81e8-b9b1f5d0b6e1",
    "merchant": {
      "address": {
        "city": "New York",
        "country": "USA",
        "postal_code": "10002",
        "state": "NY",
        "street_line1": "",
        "street_line2": ""
      },
      "category": "Gas Station",
      "category_code": "5541",
      "network_id": "234923454545",
      "name": "Shell Gas"
    },
    "object": "TRANSACTION",
    "payment_method_id": "7f754378-dd84-4a9a-b1ce-0646bb769c29",
    "product_type": "CREDITCARD",
    "purchase_method": "CHIP",
    "status": "CAPTURED",
    "transaction_id": "e2806932-5f1b-4518-8b15-156d773e9496",
    "updated_at": "2025-02-28T01:11:32.358Z"
  }
}
```

Webhook 4: Customer requested a refund for the transaction and was issued the refund

```json theme={null}
{
  "object": "TRANSACTION",
  "data": {
    "amount": 3451,
    "authorization_code": "645432",
    "created_at": "2025-02-27T18:11:32.358Z",
    "currency": "USD",
    "customer_id": "e0549550-90e9-4acb-b7e9-2e4738b7def2",
    "event_id": "202dce63-57a1-48c0-b623-6d9295afd7a9",
    "merchant": {
      "address": {
        "city": "New York",
        "country": "USA",
        "postal_code": "10002",
        "state": "NY",
        "street_line1": "",
        "street_line2": ""
      },
      "category": "Gas Station",
      "category_code": "5541",
      "network_id": "234923454545",
      "name": "Shell Gas"
    },
    "object": "TRANSACTION",
    "payment_method_id": "7f754378-dd84-4a9a-b1ce-0646bb769c29",
    "product_type": "CREDITCARD",
    "purchase_method": "CHIP",
    "status": "REFUNDED",
    "transaction_id": "e2806932-5f1b-4518-8b15-156d773e9496",
    "updated_at": "2025-03-01T01:11:32.358Z"
  }
}
```

### Reward Event

Receive a notification when a reward is created or transitions statuses.

`object` equals `REWARD`

`data` field structure

| PROPERTY NAME | REQUIRED | TYPE | DESCRIPTION |
| - | - | - | - |
| `merchant_key` | FALSE | String | Unique identifier for the merchant associated with this event. Present when a merchant key is configured for the product. |
| `reward_id` | TRUE | String | Unique identifier of the reward. Use this with the Retrieve a reward API for full details. |
| `customer_id` | TRUE | String | Unique identifier of the customer |
| `transaction_id` | FALSE | String | Identifies the transaction related to this reward, for `TRANSACTION` typed rewards |
| `type` | TRUE | String | Reward type: `OFFER`, `TRANSACTION`, `ONE_TIME`, `STATEMENT`, or `REFERRAL` |
| `amount` | TRUE | Integer | Amount of the reward in the smallest currency unit (e.g. cents for USD) |
| `status` | TRUE | String | Reward status, e.g. `PENDING`, `AVAILABLE`, `PENDING_DEDUCTION`, or `DEDUCTED`. Deduction statuses indicate a clawback; the `amount` is always a positive magnitude, with direction carried by the status. |
| `currency` | TRUE | String | ISO-4217 currency code (e.g. `USD`) or a reward unit (e.g. `POINTS`) |
| `created_at` | TRUE | Timestamp | RFC-3339 date the reward was created |
| `metadata` | FALSE | Object | Additional metadata about the reward. For `OFFER` type rewards this includes `offer_id`. Not present for other reward types. |
| `customer_metadata` | FALSE | Object | Key-value pairs of metadata attached to the customer. Present when the customer has partner metadata containing it; delivered on a best-effort basis. |

Example:

```json theme={null}
{
  "object": "REWARD",
  "data": {
    "merchant_key": "MERCHANT_ABC",
    "reward_id": "DCBFC736-2286-42DD-897D-160DCA80AED2",
    "customer_id": "2EE24580-B97B-4949-A65C-929CCB9B9B8D",
    "transaction_id": "34E24580-B97B-4949-A65C-929CCB9B9B8D",
    "type": "TRANSACTION",
    "amount": 5000,
    "status": "PENDING",
    "currency": "POINTS",
    "created_at": "2025-02-13T19:08:07.000Z",
    "customer_metadata": {
      "loyalty_id": "840012345678",
      "membership_tier": "gold"
    }
  }
}
```

### Customer Link Event

Receive a notification when a customer linked their partner account.

`object` equals `CUSTOMER_LINK`

`data` field structure

| PROPERTY NAME | REQUIRED | TYPE | DESCRIPTION |
| - | - | - | - |
| `merchant_key` | FALSE | String | Unique identifier for the merchant associated with this event. Present when a merchant key is configured for the product. |
| `customer_id` | TRUE | String | Unique identifier of the customer |
| `partner_customer_id` | TRUE | String | Partner's unique identifier of the customer |
| `status` | TRUE | String | Status of the customer link |
| `created_at` | TRUE | Timestamp | RFC-3339 date customer link was created |
| `updated_at` | FALSE | Timestamp | RFC-3339 date customer link was updated |
| `customer_metadata` | FALSE | Object | Key-value pairs of metadata attached to the customer. Present when the customer has partner metadata containing it; delivered on a best-effort basis. |

Example:

```json theme={null}
{
  "object": "CUSTOMER_LINK",
  "data": {
    "merchant_key": "MERCHANT_ABC",
    "customer_id": "2EE24580-B97B-4949-A65C-929CCB9B9B8D",
    "partner_customer_id": "PARTNER_USER_456",
    "status": "ACTIVE",
    "created_at": "2025-02-13T19:08:07.000Z",
    "updated_at": "2025-02-13T19:08:07.000Z",
    "customer_metadata": {
      "loyalty_id": "840012345678",
      "membership_tier": "gold"
    }
  }
}
```

Customer link `status` values include:

* `ACTIVE` - Customer link is active.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.