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.

{
  "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.

{
  "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.

{
  "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 to retrieve the current state, and Get Transaction History for audit and reconciliation.