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
tx_hash	string	blockchain transaction hash, only present when status is completed
remark	string	failure reason, only present when status is failed

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

{
    "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": "completed",
      "transaction_status": "completed",
      "amount": "1.20",
      "asset": "USDC",
      "network": "polygon",
      "reference": "trasdfjausdaa",
      "tx_hash": "0x56713ddd7478bbe69925a4aa477d9cb74b56c4c041a304ca3160b2289b6e3a44"
    },
    "tenant_id": "89fa0d5e-3acf-4834-968f-6a9f0186ab59",
    "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.