# Webhook Examples

## Webhook Overview

Our API can **push real‑time notifications** to your application every time a transaction is created, updated, or otherwise changes state. These event callbacks---**webhooks**---eliminate the need for constant polling and let you trigger downstream business logic (e.g., ledger updates, email receipts, or risk checks) the moment they happen.

### How it works 🚀

1. **Receive**\
   When a qualifying event occurs, we send a signed `POST` request containing a JSON payload like the samples shown below.
2. **Acknowledge**\
   Return an HTTP `2xx` status within 10 seconds. Any non‑2xx code triggers an automatic retry with exponential back‑off (up to 24 hours).
3. **Verify (recommended)**\
   Use the `X‑Signature` header to validate the payload's HMAC‑SHA256 signature against your webhook secret.

> **Need a sandbox?**\
> Point your endpoint to `https://webhook.site/...` (or any catcher) to inspect payloads while you build.

The sections that follow contain **de‑identified sample payloads** for each transaction type---purchase authorizations, reloads, ATM withdrawals, balance inquiries, and more. Copy them into your tests or monitoring tools to simulate live traffic and ensure your integration is production‑ready.

### Purchase (Internet / Phone Authorization) — PP80DS

```json
{
  "MessageType": "Transaction",
  "Amount": "114013",
  "ApprovalCode": "377907",
  "CalculatedFeeAmount": "",
  "CardNumber": "6970",
  "CardStatus": "ACT",
  "TimeStamp": "2025-04-18 14:55:28",
  "PostTransactionCardBalance": "0",
  "PostTransactionHoldsBalance": "114013",
  "TerminalAddress": "BIOPLUS SP PHARMACYINDIA",
  "TerminalCity": "INDIANAPOLIS",
  "TerminalCountry": "US",
  "TerminalID": "0001",
  "TerminalNameLocation": "",
  "TerminalOwner": "Sample Pharmacy",
  "TransactionCode": "PP80DS",
  "TransactionDescription": "Purchase (Internet / Phone Authorization)",
  "TransactionId": "967297ae-e208-4268-a0ea-e1bea1d1b75d",
  "TransactionOrigin": "POS",
  "UniqueRequestId": "",
  "MCC": "5912",
  "RetailPackId": "1000000001",
  "IssuerName": "HealthCo Rx",
  "ProductType": "Virtual Rx Sample Plan",
  "ISOFullMessage": "ISO0260…(truncated)",
  "AdditionalDataCode": "",
  "AdditionalDataCodeDesc": "",
  "AdditionalFeeOperation": "Credit",
  "AdditionalFee": "0",
  "BusinessProcessId": "29342e21:19649b139bd:-4f4c"
}

```

### Authorization — PP00DS

```json
{
  "MessageType": "Transaction",
  "Amount": "39625",
  "ApprovalCode": "339792",
  "CalculatedFeeAmount": "",
  "CardNumber": "3803",
  "CardStatus": "ACT",
  "TimeStamp": "2025-04-18 14:52:36",
  "PostTransactionCardBalance": "0",
  "PostTransactionHoldsBalance": "39625",
  "TerminalAddress": "OPTUM ",
  "TerminalCity": "+18000000000",
  "TerminalCountry": "US",
  "TerminalID": "SSVQDG73",
  "TerminalNameLocation": "",
  "TerminalOwner": "Sample Specialty Pharma",
  "TransactionCode": "PP00DS",
  "TransactionDescription": "Authorization",
  "TransactionId": "7b7a0b2e-dbc2-4243-957b-26f535d8655c",
  "TransactionOrigin": "POS",
  "UniqueRequestId": "",
  "MCC": "5912",
  "RetailPackId": "1000000002",
  "IssuerName": "HealthCo Rx",
  "ProductType": "Juice Payroll 1",
  "ISOFullMessage": "ISO0260…(truncated)",
  "AdditionalDataCode": "",
  "AdditionalDataCodeDesc": "",
  "AdditionalFeeOperation": "Credit",
  "AdditionalFee": "0",
  "BusinessProcessId": "-3c9fb275:19649a97fa3:-4d74"
}

```

### Balance Inquiry — XP31DS

```json
{
  "MessageType": "Transaction",
  "Amount": "0",
  "ApprovalCode": "NA",
  "CalculatedFeeAmount": "",
  "CardNumber": "2675",
  "CardStatus": "ACT",
  "TimeStamp": "2025-04-18 14:52:34",
  "PostTransactionCardBalance": "226302",
  "PostTransactionHoldsBalance": "0",
  "TerminalAddress": "",
  "TerminalCity": "Glendale",
  "TerminalCountry": "US",
  "TerminalID": "user",
  "TerminalNameLocation": "",
  "TerminalOwner": "AgriTech Payments",
  "TransactionCode": "XP31DS",
  "TransactionDescription": "Balance Inquiry",
  "TransactionId": "bc21cfa6-d6a0-437c-8c59-c913d6f3de86",
  "TransactionOrigin": "PRX",
  "UniqueRequestId": "a48d8f62-0951-49d9-8557-2fe993ed4a0c",
  "MCC": "",
  "RetailPackId": "1000000003",
  "IssuerName": "AgriTech Payments",
  "ProductType": "AgriCard EMV Sample",
  "ISOFullMessage": "",
  "AdditionalDataCode": "",
  "AdditionalDataCodeDesc": "",
  "AdditionalFeeOperation": "",
  "AdditionalFee": "",
  "BusinessProcessId": "-670803ed:19649aeffa9:-4f9e"
}
```

### VRX Reload — XP20DS

```json
{
  "MessageType": "Transaction",
  "Amount": "39625",
  "ApprovalCode": "NA",
  "CalculatedFeeAmount": "",
  "CardNumber": "3803",
  "CardStatus": "ACT",
  "TimeStamp": "2025-04-18 14:52:33",
  "PostTransactionCardBalance": "39625",
  "PostTransactionHoldsBalance": "0",
  "TerminalAddress": "",
  "TerminalCity": "Scottsdale",
  "TerminalCountry": "US",
  "TerminalID": "User",
  "TerminalNameLocation": "",
  "TerminalOwner": "HealthCo Rx",
  "TransactionCode": "XP20DS",
  "TransactionDescription": "VRX Reload",
  "TransactionId": "81cf8891-5548-455d-a8d1-bb0b9943885e",
  "TransactionOrigin": "PRX",
  "UniqueRequestId": "aaf922b8-a590-a16b-0cf4-4f2583c54418",
  "MCC": "",
  "RetailPackId": "1000000002",
  "IssuerName": "HealthCo Rx",
  "ProductType": "Virtual Rx Sample Plan",
  "ISOFullMessage": "",
  "AdditionalDataCode": "",
  "AdditionalDataCodeDesc": "",
  "AdditionalFeeOperation": "",
  "AdditionalFee": "",
  "BusinessProcessId": "-3c9fb275:19649a97fa3:-4d86"
}
```

### VRX Unload — XP25DS

```json
{
  "MessageType": "Transaction",
  "Amount": "119843",
  "ApprovalCode": "NA",
  "CalculatedFeeAmount": "",
  "CardNumber": "3905",
  "CardStatus": "ACT",
  "TimeStamp": "2025-04-18 14:52:26",
  "PostTransactionCardBalance": "0",
  "PostTransactionHoldsBalance": "0",
  "TerminalAddress": "",
  "TerminalCity": "Scottsdale",
  "TerminalCountry": "US",
  "TerminalID": "User",
  "TerminalNameLocation": "",
  "TerminalOwner": "HealthCo Rx",
  "TransactionCode": "XP25DS",
  "TransactionDescription": "VRX Unload",
  "TransactionId": "44e4c517-222a-4cce-91b6-4f23dd58867d",
  "TransactionOrigin": "PRX",
  "UniqueRequestId": "3299d8f1-083b-554b-85af-dfd4ccca453b",
  "MCC": "",
  "RetailPackId": "1000000004",
  "IssuerName": "HealthCo Rx",
  "ProductType": "Virtual Rx Sample Plan",
  "ISOFullMessage": "",
  "AdditionalDataCode": "",
  "AdditionalDataCodeDesc": "",
  "AdditionalFeeOperation": "",
  "AdditionalFee": "",
  "BusinessProcessId": "-3c9fb275:19649a97fa3:-4d94"
}
```

### ATM Withdrawal — AP01DS

```json
{
  "MessageType": "Transaction",
  "Amount": "40400",
  "ApprovalCode": "879913",
  "CalculatedFeeAmount": "",
  "CardNumber": "5352",
  "CardStatus": "ACT",
  "TimeStamp": "2025-04-18 14:54:58",
  "PostTransactionCardBalance": "311",
  "PostTransactionHoldsBalance": "22785",
  "TerminalAddress": "HAPO COMMUNITY CUPascoWA",
  "TerminalCity": "Pasco",
  "TerminalCountry": "US",
  "TerminalID": "G8814A",
  "TerminalNameLocation": "",
  "TerminalOwner": "Sample Community CU",
  "TransactionCode": "AP01DS",
  "TransactionDescription": "ATM Withdrawal",
  "TransactionId": "a132aba2-a461-4fa7-85e7-847377ce6dc0",
  "TransactionOrigin": "ATM",
  "UniqueRequestId": "",
  "MCC": "6011",
  "RetailPackId": "1000000008",
  "IssuerName": "AgriTech Payments",
  "ProductType": "AgriCard EMV Sample",
  "ISOFullMessage": "ISO0160…(truncated)",
  "AdditionalDataCode": "",
  "AdditionalDataCodeDesc": "",
  "AdditionalFeeOperation": "Debit",
  "AdditionalFee": "2",
  "BusinessProcessId": "-3c9fb275:19649a97fa3:-4cc0"
}

```