> ## Documentation Index
> Fetch the complete documentation index at: https://docs.centryos.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Collections event

This webhook event notifies your application when collection payments are processed. Collections can complete successfully, fail, or be explicitly blocked by processor/fraud controls. Timed-out pending checkout sessions are handled internally and do not emit a collection webhook.

## Event Schema

| Field                            | Type   | Description                                                                                         |
| -------------------------------- | ------ | --------------------------------------------------------------------------------------------------- |
| `eventType`                      | string | `COLLECTION` for standard collection outcomes; `TRANSACTION.BLOCKED` for terminal blocked outcomes. |
| `status`                         | string | `SUCCESS`, `FAILED`, or `BLOCKED`.                                                                  |
| `payload.method`                 | string | Payment method used (for example `CREDIT_CARD`, `DEBIT_CARD`, `ACH`, `CASHAPP`).                    |
| `payload.transactionId`          | string | Internal transaction identifier.                                                                    |
| `payload.walletId`               | string | Wallet that received the collection.                                                                |
| `payload.entityId`               | string | ID of the business/user that owns the wallet.                                                       |
| `payload.entityType`             | string | Entity type (for example `USER`, `BUSINESS`).                                                       |
| `payload.summary`                | string | Human-readable summary of the outcome.                                                              |
| `payload.entry`                  | string | Transaction entry direction (`CREDIT`).                                                             |
| `payload.amount`                 | string | Transaction amount (as string).                                                                     |
| `payload.feeCharged`             | string | Fee charged for the transaction. For failed/blocked outcomes this is typically `0`.                 |
| `payload.currency`               | string | Currency code (for example `USD`).                                                                  |
| `payload.timestamp`              | number | Unix timestamp in milliseconds.                                                                     |
| `payload.metadata`               | object | Additional metadata (for example checkout form data, external references).                          |
| `payload.reason`                 | string | Merchant-safe reason for failures or blocked outcomes when available.                               |
| `payload.paymentLink`            | object | Payment link information when payment originated from a link.                                       |
| `payload.paymentLink.id`         | string | Payment link UUID.                                                                                  |
| `payload.paymentLink.token`      | string | Payment link token.                                                                                 |
| `payload.paymentLink.externalId` | string | Merchant external reference, when available.                                                        |

## Statuses

| Status    | When it fires                                                                                            |
| --------- | -------------------------------------------------------------------------------------------------------- |
| `SUCCESS` | The payment has been authorized/captured and recorded successfully.                                      |
| `FAILED`  | The payment could not be completed (issuer decline, processing issue, or validation/processing failure). |
| `BLOCKED` | The payment was blocked by processor fraud/risk controls (terminal non-success).                         |

## Example: SUCCESS

Sent when a collection payment is completed successfully.

```json theme={null}
{
  "eventType": "COLLECTION",
  "status": "SUCCESS",
  "payload": {
    "method": "CREDIT_CARD",
    "transactionId": "7794112b-094e-443d-8454-7192aee10557",
    "walletId": "44805633-c437-4140-a312-0e626c6feb19",
    "entityId": "9b5e1e96-5796-4648-94d4-62253728291e",
    "entityType": "BUSINESS",
    "summary": "Payment received",
    "entry": "CREDIT",
    "amount": "100.00",
    "currency": "USD",
    "timestamp": 1771347620788,
    "feeCharged": "3.20",
    "metadata": {
      "orderId": "ORD-456",
      "customerId": "CUST-12345"
    },
    "paymentLink": {
      "id": "70475cd7-f610-4d3b-8016-111122223333",
      "token": "sATV6OtvtVejkLRdCi2tHBl_xxxx",
      "externalId": "INV-1002"
    },
    "reason": ""
  }
}
```

## Example: FAILED

Sent when a collection payment attempt fails.

```json theme={null}
{
  "eventType": "COLLECTION",
  "status": "FAILED",
  "payload": {
    "method": "CREDIT_CARD",
    "transactionId": "7794112b-094e-443d-8454-7192aee10557",
    "walletId": "44805633-c437-4140-a312-0e626c6feb19",
    "entityId": "9b5e1e96-5796-4648-94d4-62253728291e",
    "entityType": "BUSINESS",
    "summary": "Payment could not be processed",
    "entry": "CREDIT",
    "amount": "100.00",
    "currency": "USD",
    "timestamp": 1771347635000,
    "feeCharged": "0",
    "metadata": {
      "orderId": "ORD-456",
      "customerId": "CUST-12345"
    },
    "paymentLink": {
      "id": "70475cd7-f610-4d3b-8016-111122223333",
      "token": "sATV6OtvtVejkLRdCi2tHBl_xxxx",
      "externalId": "INV-1002"
    },
    "reason": "Your payment could not be processed. Please try a different card."
  }
}
```

## Example: BLOCKED

Sent when the payment processor flags the attempt as blocked.

```json theme={null}
{
  "eventType": "TRANSACTION.BLOCKED",
  "status": "BLOCKED",
  "payload": {
    "method": "CREDIT_CARD",
    "transactionId": "7794112b-094e-443d-8454-7192aee10557",
    "walletId": "44805633-c437-4140-a312-0e626c6feb19",
    "entityId": "9b5e1e96-5796-4648-94d4-62253728291e",
    "entityType": "BUSINESS",
    "summary": "Payment could not be processed",
    "entry": "CREDIT",
    "amount": "100.00",
    "currency": "USD",
    "timestamp": 1771347650000,
    "feeCharged": "0",
    "metadata": {
      "orderId": "ORD-456",
      "customerId": "CUST-12345"
    },
    "paymentLink": {
      "id": "70475cd7-f610-4d3b-8016-111122223333",
      "token": "sATV6OtvtVejkLRdCi2tHBl_xxxx",
      "externalId": "INV-1002"
    },
    "reason": "Blocked by processor fraud controls"
  }
}
```

### Possible `reason` values on FAILED/BLOCKED

| `reason`                                                            | Scenario                                      |
| ------------------------------------------------------------------- | --------------------------------------------- |
| `Your payment could not be processed. Please try a different card.` | Generic card decline or processing rejection. |
| `Transaction declined for compliance reasons.`                      | Payment blocked by compliance/business rules. |
| `Duplicate transaction detected.`                                   | Duplicate payment attempt detected.           |
| `Payment was cancelled.`                                            | Payment was cancelled before completion.      |
| `Blocked by processor fraud controls`                               | Processor/Radar-style risk block.             |

## Missed a webhook?

If your system misses a delivery, use [Get Transaction Status](/guides/get-transaction-status) to retrieve the current state, and [Get Transaction History](/guides/get-transaction-history) for audit and reconciliation.