Webhook Notification

This contains information about the webhook request sent to the endpoint provided during transaction creation.

This notification is sent at the occurrence of certain events, the following are the available webhook events:

  • transaction_created: sent after transaction creation

  • transaction_sent: sent after the created transaction has been sent to the receiving party

  • transaction_accepted: sent after the receiving party has accepted the transaction

  • transaction_rejected: sent after the receiving party has rejected the transaction

  • milestone_delivered: sent when the seller has indicated the delivery of a milestone

  • milestone_delivery_accepted: sent after the buyer has accepted the delivery

  • milestone_delivery_rejected: sent after the buyer has rejected the delivery

  • due_date_extension_requested: sent when due date extension is requested

  • due_date_extension_approved: sent after due date extension has been approved

  • transaction_payment_successful: sent after successful payment

  • broker_bank_details_missing: sent if broker bank details are not found during disbursement

  • seller_bank_details_missing: sent if seller bank details are not found during disbursement

  • buyer_bank_details_missing: sent if buyer bank details are not found during disbursement

For transaction states, these are the currently in use states
{
"draft":   "Draft",
"sac":     "Sent - Awaiting Confirmation",
"sr":      "Sent - Rejected",
"af":      "Accepted - Funded",
"anf":     "Accepted - Not Funded",
"fr":      "Funded - Rejected",
"fac":     "Funded - Awaiting Confirmation",
"ip":      "In Progress",
"d":       "Delivered",
"da":      "Delivered - Accepted",
"dr":      "Delivered - Rejected",
"cdp":     "Closed - Disbursement Pending",
"cmdp":    "Closed - Manual Disbursement Pending",
"cdc":     "Closed - Disbursement Complete",
"cidb":    "Closed - Insufficient Disbursement Balance",
"cd":      "Closed - Disputed",
"cnf":     "Closed - Not Funded",
"closed":  "Closed",
"active":  "Active",
"cr":      "Closed - Refunded",
"deleted": "Deleted"
}

POST This is a post request to the provided webhook url

Headers

Request body

this is a sample request sent to your webhook URL for all events

NOTE: milestone_id is provided only if the event is milestone-specific, therefore this is the id of the affected milestone

{
  "event": "transaction_created",
  "milestone_id": "milestone_123",
  "data": {
    "transaction": {
      "id": 1,
      "transaction_id": "trans_123",
      "title": "Transaction Title",
      "type": "type_1",
      "description": "Transaction Description",
      "amount": 1000.00,
      "status": "completed",
      "payment_status": "paid",
      "currency": "NGN",
      "created_at": "2023-07-26T12:00:00Z",
      "country": "NG",
      "dispute_handler": "handler_name",
      "files": [
        {
          "url": "https://example.com/file1.pdf",
          "type": "pdf"
        }
      ],
      "amount_paid": 1000.00,
      "amount_left": 0.00,
      "escrow_charge": 10.00,
    },
    "milestones": [
      {
        "id": 1,
        "transaction_id": "trans_123",
        "milestone_id": "milestone_123",
        "amount": 500.00,
        "inspection_period": 24,
        "title": "Milestone Title",
        "description": "Milestone Description",
        "due_date": "2024-03-19 15:04:05",
        "grace_period": 24,
        "currency": "NGN",
        "status": "pending",
        "delivered_at": 0,
        "created_at": "2023-07-26T12:00:00Z"
      }
    ],
    "parties": [
      {
        "id": 1,
        "transaction_party_id": "party_123",
        "transaction_id": "trans_123",
        "user_id": "user_123",
        "email": "user@example.com",
        "phone": "+1234567890",
        "first_name": "John",
        "last_name": "Doe",
        "role": "buyer",
        "created_at": "2023-07-26T12:00:00Z",
        "role_description": "Buyer",
        "percentage": 50.0,
        "is_initiator": true,
        "bank_account": {
          "bank_name": "Bank Name",
          "bank_code": "1234",
          "account_number": "12345678",
          "account_name": "John Doe"
        },
        "has_accepted": true
      }
    ],
    "payments": [
      {
        "id": 1,
        "reference": "payment_123",
        "transaction_id": "trans_123",
        "redirect_url": "https://example.com/redirect",
        "currency": "USD",
        "amount": 1000.00,
        "charge": 20.00,
        "paid_amount": 1000.00,
        "paid_currency": "USD",
        "description": "Payment Description",
        "status": "successful",
        "payment_info": {
          "payment_link": "https://example.com/pay",
          "account_number": "12345678",
          "account_name": "John Doe",
          "bank_name": "Bank Name",
          "reservation_reference": "reservation_123",
          "status": "confirmed",
          "bank_code": "1234"
        },
        "payment_methods": ["credit_card", "bank_transfer"],
        "created_at": "2023-07-26T12:00:00Z"
      }
    ],
    "states": [
      {
        "id": 1,
        "transaction_id": "trans_123",
        "milestone_id": "milestone_123",
        "status": "initiated",
        "created_at": "2023-07-26T12:00:00Z"
      }
    ]
  }
}

Response

a 200 response is required from you

Last updated