meCash Webhooks

Webhooks are a way for meCash to send your application automatic notifications whenever specific events take place. Instead of your application constantly asking meCash for updates, meCash pushes the information to you in real-time.

How they work

• You provide meCash with a specific web address (a webhook URL) where you want to receive these notifications.
• When an event you've subscribed to happens, meCash sends a message (a webhook payload) to that URL using a standard web request (specifically, a POST request).

How to Configure a Webhook in meCash

1. Navigate to the Webhooks Page

• In the Developers section of your meCash dashboard, select Webhooks from the left-hand menu.

  

2. Click on "Create Webhook"

• To add a new webhook, click on the Create Webhook button at the top right of the page.

  

3. Enter the Webhook URL

• Provide the URL where you want to receive webhook events.

• Ensure that your endpoint is publicly accessible and can handle incoming POST requests.

• Your endpoint should return an HTTP 2XX status code to acknowledge receipt.

  

4. Confirm and Activate

• Click Confirm to register the webhook.
• Once added, the webhook will appear in the list along with its status.

Supported Webhook Events

This section lists the different types of events that meCash can notify you about via webhooks:

• collection.completed (FUNDING): This event is triggered when a collection or funding process (like a user adding money to their wallet) has been successfully finished.
• collection.failed (FUNDING): This event is triggered when a collection or funding process has failed.
• payout.completed (SEND): This event is triggered when a payout (sending money to someone else) has been successfully completed.
• payout.failed (SEND): This event is triggered when a payout has failed.
• payout.pending (SEND): This event is triggered when a payout request has been initiated but is still being processed and hasn't yet completed or failed.

Transaction States

This explains the different possible statuses of a transaction that you might see within the webhook payload:

Transaction Types

The payout type field in a webhook shows the transaction category:

Webhook Payload Format

When an event occurs, meCash sends a POST request to your webhook URL with a JSON payload.

Example: collection.completed

This payload is sent when a funding transaction (e.g., from a bank) is completed and successfully credited to a wallet.

{
   "event":"collection.completed",
   "data":{
      "id":"866be9f6-1e3c-4083-87a5-8ab51c16b252",
      "referenceNumber":"V6FUNZNGIV8BY",
      "amount":200,
      "type":"FUNDING",
      "state":"COMPLETED",
      "destination":"NGN wallet",
      "source":{
         "bankName":"GTBANK",
         "accountName":"OMOLOKUN OMOYEMI",
         "accountNumber":"0211232342"
      },
      "created": "2025-03-28T11:37:32.390606321",
      "processed": "2025-03-28T11:37:32.390606321"
   }
}

Payload Breakdown

Example: payout.completed (NGN to CNY)

This is a sample payload sent when a payout transaction from a NGN source to a CNY destination is successfully completed.

 
{
  "event": "payout.completed",
  "data": {
    "id": "79d3acd4-1465-87hj-xft6-cf5t3b12a56b",
    "referenceNumber": "RRT6ADX1KLFOP",
    "remark": null,
    "type": "SEND",
    "state": "COMPLETED",
    "quote": {
      "id": "79d3acd4-1465-87hj-xft6-cf5t3b12a56b",
      "sourceCurrency": "NGN",
      "sourceAmount": 30000,
      "targetCurrency": "CNY",
      "targetAmount": 136.15,
      "rate": 220.3431138,
      "fees": [
        {
          "paymentChannel": "WECHAT",
          "amount": 5
        }
      ]
    },
    "recipient": {
      "name": "Zui len",
      "firstName": "Zui",
      "lastName": "len",
      "relationship": "SELF",
      "account": {
        "sortCode": "",
        "accountNumber": "8612343562723",
        "branchCode": ""
      },
      "currency": "CNY",
      "country": "CN",
      "stored": false
    },
    "created": "2025-05-13T15:23:15.258847784",
    "processed": "2025-05-13T15:23:16.258847784"
  }
}
 

Payload Breakdown

Top-Level Fields

quote Object

recipient Object

Example: payout.pending

This payload is sent when a payout request is created but still in progress (not yet completed or failed).

{
  "event": "payout.pending",
  "data": {
    "id": "8b99b9d8-998a-48db-9102-d0719d1bda25",
    "referenceNumber": "RRT6CBX1NMGUJ",
    "remark": null,
    "type": "SEND",
    "state": "PENDING",
    "quote": {
      "id": "68d2bae4-7365-42fc-bbc2-cf8e3b12a16a",
      "sourceCurrency": "NGN",
      "sourceAmount": 3000,
      "targetCurrency": "CNY",
      "targetAmount": 13.62,
      "rate": 220.3431138,
      "fees": [
        {
          "paymentChannel": "WECHAT",
          "amount": 5
        }
      ]
    },
    "recipient": {
      "name": "Zui len",
      "firstName": "Zui",
      "lastName": "len",
      "relationship": "SELF",
      "account": {
        "sortCode": "",
        "accountNumber": "8612343562723",
        "branchCode": ""
      },
      "currency": "CNY",
      "country": "CN",
      "stored": false
    },
    "created": "2025-03-13T15:28:37.258847784",
    "processed": "2025-03-13T15:28:37.258847784"
  }
}

Payload structure and field definitions are the same as in payout.completed.

Securing Your Webhooks

To ensure webhook integrity:

• Validate the x-mecash-signature header, which is included in every webhook request.
• Respond with HTTP status 200 OK upon successful receipt.
• Implement retry logic in case of network failures.