Skip to main content
Syncgram Pay sends a webhook event whenever the status of a payment, payout, refund, or conversion changes. Each event has a type field that identifies what happened and a data object with details specific to that event.
Use POST /api/v1/notifications/webhooks/test to send a test collection.succeeded event to your endpoint at any time. See Webhooks overview for setup instructions.

​
Collection events

Collection events fire when the status of an incoming payment changes.
When it fires: A payment was completed and funds were received in full.
FieldTypeDescription
referencestringYour payment reference.
statusstringAlways "success".
amountstringAmount received, formatted for the currency.
currencystringISO 4217 currency code (e.g., "USD", "NGN").
settlement_amountstringAmount credited to your balance after fees.
settlement_currencystringCurrency of your settlement.
customerobjectCustomer details (e.g., email).
completed_atstringISO 8601 timestamp when the payment completed.
{
  "id": "evt_3f9a1b2c4d5e6f7a8b9c0d1e",
  "type": "collection.succeeded",
  "created_at": "2024-01-15T10:30:00Z",
  "data": {
    "reference": "order_9182",
    "status": "success",
    "amount": "50.00",
    "currency": "USD",
    "settlement_amount": "49.25",
    "settlement_currency": "USD",
    "customer": {
      "email": "customer@example.com"
    },
    "completed_at": "2024-01-15T10:30:00Z"
  }
}
When it fires: A payment attempt was declined or could not be processed.
FieldTypeDescription
referencestringYour payment reference.
statusstringAlways "failed".
amountstringAmount that was attempted.
currencystringISO 4217 currency code.
customerobjectCustomer details.
failed_atstringISO 8601 timestamp when the failure was recorded.
{
  "id": "evt_7c2d4e5f6a7b8c9d0e1f2a3b",
  "type": "collection.failed",
  "created_at": "2024-01-15T11:00:00Z",
  "data": {
    "reference": "order_9183",
    "status": "failed",
    "amount": "75.00",
    "currency": "USD",
    "customer": {
      "email": "customer@example.com"
    },
    "failed_at": "2024-01-15T11:00:00Z"
  }
}
When it fires: A customer started but did not complete a checkout before it expired or was abandoned.
FieldTypeDescription
referencestringYour payment reference.
statusstringAlways "abandoned".
amountstringAmount that was requested.
currencystringISO 4217 currency code.
customerobjectCustomer details.
{
  "id": "evt_a1b2c3d4e5f6a7b8c9d0e1f2",
  "type": "collection.abandoned",
  "created_at": "2024-01-15T12:00:00Z",
  "data": {
    "reference": "order_9184",
    "status": "abandoned",
    "amount": "30.00",
    "currency": "USD",
    "customer": {
      "email": "customer@example.com"
    }
  }
}
When it fires: A payment was received, but the amount was less than the amount requested. This can occur with crypto payments that support partial delivery.
FieldTypeDescription
referencestringYour payment reference.
statusstringAlways "underpaid".
amountstringAmount requested.
amount_receivedstringAmount actually received.
currencystringISO 4217 currency code.
customerobjectCustomer details.
{
  "id": "evt_b2c3d4e5f6a7b8c9d0e1f2a3",
  "type": "collection.underpaid",
  "created_at": "2024-01-15T13:00:00Z",
  "data": {
    "reference": "order_9185",
    "status": "underpaid",
    "amount": "100.00",
    "amount_received": "80.00",
    "currency": "USD",
    "customer": {
      "email": "customer@example.com"
    }
  }
}

​
Payout events

Payout events fire when the status of an outgoing payment changes.
When it fires: A payout was created and accepted for processing.
FieldTypeDescription
payout_idstringSyncgram Pay payout ID.
statusstringAlways "created".
payout_amountstringAmount being sent, formatted for the currency.
payout_currencystringCurrency of the payout.
created_atstringISO 8601 timestamp when the payout was created.
{
  "id": "evt_c3d4e5f6a7b8c9d0e1f2a3b4",
  "type": "payout.created",
  "created_at": "2024-01-15T14:00:00Z",
  "data": {
    "payout_id": "pay_4f5a6b7c8d9e0f1a",
    "status": "created",
    "payout_amount": "200.00",
    "payout_currency": "USD",
    "created_at": "2024-01-15T14:00:00Z"
  }
}
When it fires: A payout was successfully delivered to the destination.
FieldTypeDescription
payout_idstringSyncgram Pay payout ID.
statusstringAlways "paid".
payout_amountstringAmount delivered.
payout_currencystringCurrency of the payout.
completed_atstringISO 8601 timestamp when delivery was confirmed.
{
  "id": "evt_d4e5f6a7b8c9d0e1f2a3b4c5",
  "type": "payout.paid",
  "created_at": "2024-01-15T14:05:00Z",
  "data": {
    "payout_id": "pay_4f5a6b7c8d9e0f1a",
    "status": "paid",
    "payout_amount": "200.00",
    "payout_currency": "USD",
    "completed_at": "2024-01-15T14:05:00Z"
  }
}
When it fires: A payout could not be delivered to the destination.
FieldTypeDescription
payout_idstringSyncgram Pay payout ID.
statusstringAlways "failed".
payout_amountstringAmount that was attempted.
payout_currencystringCurrency of the payout.
failed_atstringISO 8601 timestamp when the failure was recorded.
{
  "id": "evt_e5f6a7b8c9d0e1f2a3b4c5d6",
  "type": "payout.failed",
  "created_at": "2024-01-15T14:10:00Z",
  "data": {
    "payout_id": "pay_4f5a6b7c8d9e0f1a",
    "status": "failed",
    "payout_amount": "200.00",
    "payout_currency": "USD",
    "failed_at": "2024-01-15T14:10:00Z"
  }
}

​
Refund events

Refund events fire when the status of a refund changes.
When it fires: A refund was initiated.
FieldTypeDescription
refund_idstringSyncgram Pay refund ID.
statusstringAlways "created".
amountstringRefund amount.
currencystringISO 4217 currency code.
referencestringOriginal payment reference.
{
  "id": "evt_f6a7b8c9d0e1f2a3b4c5d6e7",
  "type": "refund.created",
  "created_at": "2024-01-16T09:00:00Z",
  "data": {
    "refund_id": "ref_1a2b3c4d5e6f7a8b",
    "status": "created",
    "amount": "50.00",
    "currency": "USD",
    "reference": "order_9182"
  }
}
When it fires: A refund was successfully returned to the customer.
FieldTypeDescription
refund_idstringSyncgram Pay refund ID.
statusstringAlways "paid".
amountstringRefund amount.
currencystringISO 4217 currency code.
referencestringOriginal payment reference.
completed_atstringISO 8601 timestamp when the refund was delivered.
{
  "id": "evt_a7b8c9d0e1f2a3b4c5d6e7f8",
  "type": "refund.paid",
  "created_at": "2024-01-16T09:05:00Z",
  "data": {
    "refund_id": "ref_1a2b3c4d5e6f7a8b",
    "status": "paid",
    "amount": "50.00",
    "currency": "USD",
    "reference": "order_9182",
    "completed_at": "2024-01-16T09:05:00Z"
  }
}
When it fires: A refund could not be delivered to the customer.
FieldTypeDescription
refund_idstringSyncgram Pay refund ID.
statusstringAlways "failed".
amountstringRefund amount.
currencystringISO 4217 currency code.
referencestringOriginal payment reference.
{
  "id": "evt_b8c9d0e1f2a3b4c5d6e7f8a9",
  "type": "refund.failed",
  "created_at": "2024-01-16T09:10:00Z",
  "data": {
    "refund_id": "ref_1a2b3c4d5e6f7a8b",
    "status": "failed",
    "amount": "50.00",
    "currency": "USD",
    "reference": "order_9182"
  }
}

​
Conversion events

Conversion events fire when a currency conversion changes status.
When it fires: A currency conversion was executed successfully.
FieldTypeDescription
from_amountstringAmount debited in the source currency.
from_currencystringSource currency code.
to_amountstringAmount credited in the destination currency.
to_currencystringDestination currency code.
completed_atstringISO 8601 timestamp when the conversion completed.
{
  "id": "evt_c9d0e1f2a3b4c5d6e7f8a9b0",
  "type": "conversion.completed",
  "created_at": "2024-01-16T10:00:00Z",
  "data": {
    "from_amount": "1000.00",
    "from_currency": "USD",
    "to_amount": "1540000",
    "to_currency": "NGN",
    "completed_at": "2024-01-16T10:00:00Z"
  }
}
When it fires: A currency conversion could not be completed.
FieldTypeDescription
from_amountstringAmount that was attempted.
from_currencystringSource currency code.
to_currencystringDestination currency code.
failed_atstringISO 8601 timestamp when the failure was recorded.
{
  "id": "evt_d0e1f2a3b4c5d6e7f8a9b0c1",
  "type": "conversion.failed",
  "created_at": "2024-01-16T10:05:00Z",
  "data": {
    "from_amount": "1000.00",
    "from_currency": "USD",
    "to_currency": "NGN",
    "failed_at": "2024-01-16T10:05:00Z"
  }
}

​
All event types

Event typeCategoryDescription
collection.succeededCollectionPayment completed and funds received.
collection.failedCollectionPayment attempt was declined or failed.
collection.abandonedCollectionCheckout was not completed before expiry.
collection.underpaidCollectionPayment received for less than the requested amount.
payout.createdPayoutPayout accepted and queued for delivery.
payout.paidPayoutPayout successfully delivered to the destination.
payout.failedPayoutPayout delivery failed.
refund.createdRefundRefund initiated.
refund.paidRefundRefund successfully returned to the customer.
refund.failedRefundRefund delivery failed.
conversion.completedConversionCurrency conversion executed successfully.
conversion.failedConversionCurrency conversion could not be completed.

​
Full production payload example

The following is a complete collection.succeeded payload as delivered to your endpoint in production: 
{
  "id": "evt_3f9a1b2c4d5e6f7a8b9c0d1e",
  "type": "collection.succeeded",
  "created_at": "2024-01-15T10:30:00.123456+00:00",
  "data": {
    "reference": "order_9182",
    "status": "success",
    "amount": "50.00",
    "currency": "USD",
    "settlement_amount": "49.25",
    "settlement_currency": "USD",
    "customer": {
      "email": "customer@example.com"
    },
    "completed_at": "2024-01-15T10:30:00.123456+00:00"
  }
}
The id field on test events delivered via POST /api/v1/notifications/webhooks/test is always evt_test_webhook. Use this to distinguish test events from live events in your handler.