Skip to content

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
transaction_status string current status: pending, failed, or completed
amount string amount collected
reference string client reference identifier from the collection request
metadata object custom data attached to the collection request
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",
      "transaction_status": "completed",
      "amount": "1.20",
      "reference": "trasdfjausdaa",
      "metadata": {
        "order_id": "12345",
      }
    },
    "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.