API Reference

Webhooks and Events

Webhooks

Webhooks play a critical role in integrating payments with Chimoney. They provide a means for Chimoney to keep you informed about events that occur on your account, such as successful payments or failed transactions.

To receive notifications about these events, you'll need to set up a webhook URL. This is an endpoint on your server that will be able to receive the notifications. When an event occurs, we will make a POST request to this endpoint, sending a JSON body that contains details about the event, including its type and associated data.

Structure of Webhook Payload

An example structure of a webhook payload:

The Chimoney API webhook includes,

  • an eventType field that displays the event type
  • a status field that shows the transaction status.
  • a data object with in-depth details of the transaction

Example

{
  "data": {
    "account_number": "00000031",
    "amount": 5000,
    "bank_code": "044",
    "bank_name": "ACCESS BANK NIGERIA",
    "complete_message": "",
    "created_at": "2023-02-10T13:23:12.000Z",
    "currency": "NGN",
    "debit_currency": "NGN",
    "fee": 10.75,
    "full_name": "Jane Doe",
    "id": 393594,
    "is_approved": 1,
    "meta": {
      "chiRef": "34cedc371-232d-49d0-9ca5-f8c065b9505b",
      "country": "NG",
      "currency": "NGN",
      "type": "bank",
      "valueInUSD": 50
    },
    "reference": "8cedc371-232d-49d0-9ca5-f8c065b9505b_1676035392178",
    "requires_approval": 0,
    "status": "NEW"
  },
  "eventType": "payout.bank.initiated",
  "message": "Transfer Queued Successfully",
  "status": "success"
}

How To Enable Webhooks

Here is how to setup your webhook for your Chimoney API:

  • Log in to your Dashboard (sandbox.chimoney.io for Sandbox)
  • Click on the Developers tab.
  • Then a sub-section titled App WebHooks.
  • Then navigate to the Endpoints part and click on Add Endpoint.
  • Under the message filtering section, check all boxes best aligns with your use case.

Events 🚀🚀

The Chimoney API has an array of events that includes but is not limited to the following:

  • chimoney.payment.completed
  • chimoney.redeem.completed
  • payout.bank.completed
  • payout.bank.failed
  • payout.bank.initiated
  • payout.gift-card.completed
  • payout.gift-card.failed
  • payout.gift-card.initiated

This can be found in the Developers segment of the sandbox env.