Skip to main content

Payment Collection Events

Event NameEvent TypeDescription
Payment Successfulpayment_successfulTriggered when a payment is successfully processed.
Payment Failedpayment_failedOccurs when a payment attempt fails due to customer errors, declined cards, or other issues.

Payload Example Structure

Payment Collection Successful

{
  "event": "payment_successful",
  "data": {
    "id": "f78ada70-3290-48d3-b751-6fd1a0c42564",
    "reference": "ref-2d2dc728-57be-48b0-a1e1-ae798017f44c",
    "spotflowReference": "SPF-PSK-a564bb4d43674d9c83c35ee99758cc7c",
    "amount": 100,
    "currency": "NGN",
    "channel": "card",
    "status": "successful",
    "customer": {
      "id": "2f39de57-e110-4423-8a66-9e643103da0a",
      "name": "Olly",
      "email": "olly@gmail.com",
      "phoneNumber": "09098788901"
    },
    "providerMessage": "successful",
    "rate": 18.5,
    "region": "Nigeria",
    "card": {
      "type": "Mastercard",
      "firstSix": "555555",
      "lastFour": "4444"
    },
    "createdAt": "2025-10-28T19:07:38Z",
    "metadata": {
      "Test-Webhook": "test"
    },
    "totalTaxAmount": 0,
    "totalLocalAmount": 100,
    "planId": "95mn9078d-b11a-44b2-8422-a1955ca0lo7d"
  }
}

Payment Collection Failed

{
    "event": "payment_failed",
    "data": {
        "id": "8da0788a-ef1d-43ac-915d-f2daf39f2940",
        "reference": "ref-08ab300d-3f3a-443d-b928-312c400b3828",
        "spotflowReference": "SPF-ISW-e68a4286577447d2a0baf3a6bcb3c110",
        "amount": 2000.00,
        "currency": "NGN",
        "channel": "card",
        "status": "failed",
        "customer": {
            "id": "2f39de57-e110-4423-8a66-9e643103da0a",
            "name": "Olly",
            "email": "olly@gmail.com",
            "phoneNumber": "07001228900"
        },
        "providerMessage": "Error processing payment",
        "rate": 1699.5,
        "region": "Nigeria",
        "card": {
            "type": "Visa",
            "firstSix": "408408",
            "lastFour": "4081"
        },
        "createdAt": "2025-11-12T13:58:08Z",
        "metadata": {
            "SubscriptionPlan": "Test Trial",
            "productName": "Free Trial"
        },
        "totalTaxAmount": 0.0000,
        "totalLocalAmount": 2000.0000
    }
}