---
title: "Collections event"
---
Collection events notify you when the status of a payment collection changes. These events help you track incoming payments in real time as customers complete transactions through card, mobile money, or bank transfer methods.

## When collection events are sent

Gravv sends collection events when:

* A collection transaction is initiated and processing begins.
* The transaction fails due to payment issues or validation errors.
* The transaction completes successfully and funds are received.

## Collection event types

The following event types are available for collections:

| Event type                  | Description                         |
| :-------------------------- | :---------------------------------- |
| collection.status.pending   | collection initiated and processing |
| collection.status.failed    | collection failed                   |
| collection.status.completed | collection completed successfully   |

## Onramp status values

The `onramp_status` field in collection events indicates the payment processor status:

| Onramp status        | Collection status | Description                    |
| :------------------- | :---------------- | :----------------------------- |
| initialize           | pending           | payment initialization started |
| transfer_queued      | pending           | payment queued for processing  |
| transfer_initialized | pending           | payment processing in progress |
| transfer_failed      | failed            | payment processing failed      |
| transfer_completed   | completed         | payment successfully processed |

## Collection event structure

The `event_data` object for collection events contains the following fields:

| Field              | Type   | Description                                                          |
| :----------------- | :----- | :------------------------------------------------------------------- |
| card_bin           | string | first six digits of card number, only present for card payments      |
| card_exp_month     | string | card expiration month, only present for card payments                |
| card_exp_year      | string | card expiration year, only present for card payments                 |
| card_name          | string | card product name, only present for card payments                    |
| card_type          | string | card type: debit or credit, only present for card payments           |
| card_segment       | string | card segment: consumer or commercial, only present for card payments |
| card_brand         | string | card brand: VISA, MASTERCARD, etc., only present for card payments   |
| transaction_id     | string | unique identifier for the collection transaction                     |
| onramp_status      | string | payment processor status                                             |
| transaction_status | string | current status: pending, failed, or completed                        |
| amount             | string | amount collected                                                     |
| asset              | string | stablecoin received, either USDC or USDT                             |
| network            | string | blockchain network where funds were received                         |
| reference          | string | client reference identifier from the collection request              |
| metadata           | object | custom data attached to the collection request                       |
| tx_hash            | string | blockchain transaction hash, only present when status is completed   |
| remark             | string | failure reason, only present when status is failed                   |
| customer_id        | string | Gravv identifier for the customer associated with this collection    |
| client_customer_id | string | your own customer identifier, passed when creating the collection    |

The following is a sample payload for a completed collection event:

```json title="sample completed collection event payload"
{
    "event_data": {
      "card_bin": "411111",
      "card_exp_month": "09",
      "card_exp_year": "45",
      "card_name": "Visa Classic",
      "card_type": "debit",
      "card_segment": "consumer",
      "card_brand": "VISA",
      "transaction_id": "90950347-d40b-4ab9-aa77-f1882750477c",
      "onramp_status": "transfer_completed",
      "transaction_status": "completed",
      "amount": "1.20",
      "asset": "USDC",
      "network": "polygon",
      "reference": "trasdfjausdaa",
      "tx_hash": "0x56713ddd7478bbe69925a4aa477d9cb74b56c4c041a304ca3160b2289b6e3a44",
      "metadata": {
        "order_id": "12345"
      }
    },
    "event_id": "c1d2e3f4-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
    "tenant_id": "89fa0d5e-3acf-4834-968f-6a9f0186ab59",
    "timestamp": "2025-11-03T09:12:44Z",
    "event_category": "collection",
    "event_type": "collection.status.completed",
    "event_group_id": "90950347-d40b-4ab9-aa77-f1882750477c"
  }
```

For the required fields in all Gravv webhook payloads, see [Webhook payload structure](/platform/webhooks/webhooks-overview#webhook-payload-structure).