Webhook

Webhooks allow you to set up a notification system that can be used to receive updates on certain requests made to the Startbutton API.

With webhooks, Startbutton sends updates to your server when the status of your request changes. You will typically listen to these events on your webhook URL - a POST endpoint, the URL needs to parse a JSON request and return a 200 OK.

Supported events for payment collection:

1. collection.verified

2. collection.completed

Verified

{
  "event": "collection.verified",
  "data": {
    "transaction": {
      "_id": "65042a1a0d32920xxxxxxxxx",
      "transType": "collection",
      "status": "verified",
      "merchantId": "64c7bd870821e83xxxxxxxxx",
      "transactionReference": "be6eaxxxxxxx",
      "customerEmail": "[e-mail]",
      "userTransactionReference": "aedxxxx",
      "paymentCode": "a78a18df1fdc1fa7f2fb665b54afa21cf1c0d81b741f44527989f492e2a6094cdb24281fb7d577c4636978xxxxxxxxxx",
      "isRecurrent": false,
      "postProcess": null,
      "gatewayReference": null,
      "createdAt": "2023-09-15T09:55:38.492Z",
      "updatedAt": "2023-09-15T09:57:30.522Z",
      "feeAmount": 115500,
      "narration": "Approved",
      "amount": 1030000,
      "currency": "ZAR"
    },
    "authorizationCode": null
  }
}

Completed

{
  "event": "collection.completed",
  "data": {
    "transaction": {
      "_id": "65042a1a0d3292066xxxxxxx",
      "transType": "collection",
      "status": "successful",
      "merchantId": "64c7bd870821e831cxxxxxxx",
      "transactionReference": "be6eaxxxxxxx",
      "customerEmail": "[e-mail]",
      "userTransactionReference": "aedxxxx",
      "paymentCode": "a78a18df1fdc1fa7f2fb665b54afa21cf1c0d81b741f44527989f492e2a6094cdb24281fb7d577c4636978xxxxxxxxxx",
      "isRecurrent": false,
      "postProcess": null,
      "gatewayReference": null,
      "createdAt": "2023-09-15T09:55:38.492Z",
      "updatedAt": "2023-09-15T09:59:01.089Z",
      "feeAmount": 115500,
      "narration": "Successful",
      "amount": 1030000,
      "currency": "ZAR"
    },
    "authorizationCode": null
  }
}

amount is in fractional unit

Supported events for transfer:

• transfer.pending

• transfer.successful

• transfer.failed

• transfer.reversed

Successful

{
  "event": "transfer.successful",
  "data": {
    "transaction": {
      "_id": "65042e420d3292066xxxxxxx",
      "transType": "transfer",
      "status": "successful",
      "feeAmount": 15,
      "merchantId": "64c7bd870821e831xxxxxxxx",
      "transactionReference": "6342d3xxxxxx",
      "isRecurrent": false,
      "gatewayReference": "6342d3xxxxxx",
      "createdAt": "2023-09-15T10:13:22.438Z",
      "updatedAt": "2023-09-15T10:13:25.212Z",
      "amount": 5000,
      "currency": "NGN",
      "recipient": {
        "recipientName": "JOHN DOE JAMES",
        "currency": "NGN",
        "institutionType": "nuban",
        "institutionName": "Zenith Bank",
        "institutionNumber": "2007xxxxxx",
        "_id": "64f4fb7e605c5280xxxxxxx"
      }
    },
    "authorizationCode": null
  }

Successful (KES)

{
  "event": "transfer.successful",
  "data": {
    "transaction": {
      "_id": "65e8xxxxxxxxxxxxxx",
      "transType": "transfer",
      "status": "successful",
      "feeAmount": 0,
      "merchantId": "64c7bd8xxxxxxxxxxxxx",
      "transactionReference": "df11xxxxxx",
      "isRecurrent": false,
      "createdAt": "2024-03-06T16:23:00.016Z",
      "updatedAt": "2024-03-06T16:23:02.957Z",
      "gatewayReference": "df11xxxxxxxx",
      "fromBalanceAfterLedger": 0,
      "fromBalanceAfterAvailable": 0,
      "toBalanceAfterLedger": 0,
      "toBalanceAfterAvailable": 0,
      "amount": 100,
      "currency": "KES",
      "recipient": {
        "recipientName": "11 - 07xxxxxxx",
        "currency": "KES",
        "institutionType": "mobile_money",
        "institutionName": "11",
        "institutionNumber": "07xxxxxxxx",
        "_id": "65e8xxxxxxxxxxxx"
      },
    },
    "authorizationCode": "1eexxxxxxxxx"
  }
}

Pending

{
  "event": "transfer.pending",
  "data": {
    "transaction": {
      "_id": "65042e420d3292066xxxxxxx",
      "transType": "transfer",
      "status": "pending",
      "feeAmount": 15,
      "merchantId": "64c7bd870821e831xxxxxxxx",
      "transactionReference": "6342d3xxxxxx",
      "isRecurrent": false,
      "gatewayReference": "6342d3xxxxxx",
      "createdAt": "2023-09-15T10:13:22.438Z",
      "updatedAt": "2023-09-15T10:13:25.212Z",
      "amount": 5000,
      "currency": "NGN",
      "recipient": {
        "recipientName": "JOHN DOE JAMES",
        "currency": "NGN",
        "institutionType": "nuban",
        "institutionName": "Zenith Bank",
        "institutionNumber": "2007xxxxxx",
        "_id": "64f4fb7e605c5280xxxxxxx"
      }
    },
    "authorizationCode": null
  }

Failed

{
  "event": "transfer.failed",
  "data": {
    "transaction": {
      "_id": "65042e420d3292066xxxxxxx",
      "transType": "transfer",
      "status": "failed",
      "feeAmount": 0,
      "merchantId": "64c7bd870821e831xxxxxxxx",
      "transactionReference": "6342d3xxxxxx",
      "isRecurrent": false,
      "gatewayReference": "6342d3xxxxxx",
      "createdAt": "2023-09-15T10:13:22.438Z",
      "updatedAt": "2023-09-15T10:13:25.212Z",
      "amount": 5000,
      "currency": "NGN",
      "recipient": {
        "recipientName": "JOHN DOE JAMES",
        "currency": "NGN",
        "institutionType": "nuban",
        "institutionName": "Zenith Bank",
        "institutionNumber": "2007xxxxxx",
        "_id": "64f4fb7e605c5280xxxxxxx"
      }
    },
    "authorizationCode": null
  }

Reversed

{
  "event": "transfer.reversed",
  "data": {
    "transaction": {
      "_id": "65042e420d3292066xxxxxxx",
      "transType": "transfer",
      "status": "reversed",
      "feeAmount": 0,
      "merchantId": "64c7bd870821e831xxxxxxxx",
      "transactionReference": "6342d3xxxxxx",
      "isRecurrent": false,
      "gatewayReference": "6342d3xxxxxx",
      "createdAt": "2023-09-15T10:13:22.438Z",
      "updatedAt": "2023-09-15T10:13:25.212Z",
      "amount": 5000,
      "currency": "NGN",
      "recipient": {
        "recipientName": "JOHN DOE JAMES",
        "currency": "NGN",
        "institutionType": "nuban",
        "institutionName": "Zenith Bank",
        "institutionNumber": "2007xxxxxx",
        "_id": "64f4fb7e605c5280xxxxxxx"
      }
    },
    "authorizationCode": null
  }

Webook Samples for Under and Overpaid transactions:

Underpayment

{
  "event": "collection.verified",
  "data": {
    "transaction": {
      "_id": "67d946xxxx",
      "transType": "collection",
      "status": "successful",
      "merchantId": "64xxxxxxxxxxxx",
      "transactionReference": "09026725031811120xxxxxxxx",
      "customerEmail": "[e-mail]",
      "paymentPartnerId": "65fbxxxxxxxx",
      "isRecurrent": false,
      "postProcess": null,
      "createdAt": "2025-03-18T10:12:08.298Z",
      "updatedAt": "2025-03-18T10:12:08.298Z",
      "amount": 20000,
      "currency": "NGN",
      "feeAmount": null
    },
    "authorizationCode": null,
    "extraInformation": {
      "originalReference": "c066f854fa8a",
      "userTransactionReference": "BTS2013",
      "expectedAmount": 200000,
      "paymentCollectionType": "UNDERPAYMENT",
      }
    "payerInformation": {
      "sessionId": "090267250xxxxxxxxxx",
      "accountNumber": "**********",
      "bankName": "KUDA MICROFINANCE BANK"
    }
  }
}

Overpayment

{
  "event": "collection.verified",
  "data": {
    "transaction": {
      "_id": "67d946xxxx",
      "transType": "collection",
      "status": "successful",
      "merchantId": "64xxxxxxxxxxxx",
      "transactionReference": "0102672556781120xxxxxxxx",
      "customerEmail": "[e-mail]",
      "paymentPartnerId": "65fb3c11xxxxxx",
      "isRecurrent": false,
      "postProcess": null,
      "createdAt": "2025-03-18T10:12:08.298Z",
      "updatedAt": "2025-03-18T10:12:08.298Z",
      "amount": 2000000,
      "currency": "NGN",
      "feeAmount": null
    },
    "authorizationCode": null,
    "extraInformation": {
      "originalReference": "b079dky083",
      "userTransactionReference": "TEST613",
      "expectedAmount": 100000,
      "paymentCollectionType": "OVERPAYMENT"
    },
    "payerInformation": {
      "sessionId": "01678954xxxxxxxxxx",
      "accountNumber": "**********",
      "bankName": "KUDA MICROFINANCE BANK"
    }
  }
}

If we have any issues sending you a webhook, we retry the webhook 5 times.

If a reference is passed when initiating a transaction; a userTransactionReference will be returned in your webhook for complete transactions as well as under or overpayments. The userTransactionReferencewill have the value passed in as reference during initialization

Webhook Verification

To ascertain that the request you received on your webhook is legit and not a bad actor, it's recommended that the webhook response is verified.

Events sent from Startbutton carry the x-startbutton-signature header. The value of this header is a HMAC SHA512 signature of the event payload signed using your secret key. Verifying the header signature should be done before processing the event.

Here is a sample code showing the webhook verification

Node (Express)

var crypto = require('crypto');
var secret = process.env.MERCHANT_SECRET_KEY;
// Using Express
app.post("/my/webhook/url", function(req, res) {
    //validate event
    const hash = crypto.createHmac('sha512', secret).update(JSON.stringify(req.body)).digest('hex');
    if (hash == req.headers['x-startbutton-signature']) {
    // Retrieve the request's body
    const event = req.body;
    // Do something with event  
    }
    res.send(200);
});

C#

using System;
using System.Text;
using System.Security.Cryptography;
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Http;
using Newtonsoft.Json;

public class WebhookController : ControllerBase
{
    private readonly string secret = Environment.GetEnvironmentVariable("MERCHANT_SECRET_KEY");

    [HttpPost("/my/webhook/url")]
    public IActionResult HandleWebhook([FromBody] WebhookData requestBody)
    {
        // Convert the request body to JSON
        string jsonBody = JsonConvert.SerializeObject(requestBody);

        // Validate the event
        string hash = CalculateHash(jsonBody);

        if (hash == Request.Headers["x-startbutton-signature"])
        {
            // Request is valid, process the event
            // You can access the JSON data in 'requestBody'
            // Do something with the event
        }

        return Ok();
    }

    private string CalculateHash(string data)
    {
        using (var hmac = new HMACSHA512(Encoding.UTF8.GetBytes(secret)))
        {
            byte[] hashBytes = hmac.ComputeHash(Encoding.UTF8.GetBytes(data));
            return BitConverter.ToString(hashBytes).Replace("-", "").ToLower();
        }
    }
    
    
    public class WebhookData
    {
        public string @event { get; set; }
        public WebhookDataObj data { get; set; }
    }
 

    public class WebhookDataObj
    {
        public WebhookTransaction transaction { get; set; }
        public string authorizationCode { get; set; }
    }

    public class WebhookTransaction
    {
        public string _id { get; set; }
        public string transType { get; set; }
        public string status { get; set; }
        public string merchantId { get; set; }
        public string transactionReference { get; set; }
        public string customerEmail { get; set; }
        public string paymentPartnerId { get; set; }
        public string paymentCode { get; set; }
        public string userTransactionReference { get; set; }
        public bool isRecurrent { get; set; }
        public string postProcess { get; set; }
        public string createdAt { get; set; }
        public string updatedAt { get; set; }
        public int feeAmount { get; set; }
        public int amount { get; set; }
        public string currency { get; set; }

}

}

Java (SpringBoot)

package com.example.demot;

import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.databind.ObjectMapper;
import lombok.Getter;
import lombok.Setter;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestHeader;
import org.springframework.web.bind.annotation.RestController;

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import java.util.Formatter;


@RestController
class WebhookController {

    private final String secret = System.getenv("MERCHANT_SECRET_KEY");
    private static final String HMAC_SHA512 = "HmacSHA512";

    @PostMapping("/webhook")
    public ResponseEntity<?> handleWebhook(@RequestHeader("x-startbutton-signature") String signature,
                                           @RequestBody ReqObject requestBody) throws JsonProcessingException, NoSuchAlgorithmException, InvalidKeyException {

        String requestBodyString = new ObjectMapper().writeValueAsString(requestBody);
        String returnedHash = calculateHMAC(requestBodyString, secret);
        return returnedHash.equals(signature) ? ResponseEntity.ok().build() : ResponseEntity.badRequest().build();
    }

    public static String calculateHMAC(String data, String key) throws NoSuchAlgorithmException, InvalidKeyException {
        SecretKeySpec secretKeySpec = new SecretKeySpec(key.getBytes(), HMAC_SHA512);
        Mac mac = Mac.getInstance(HMAC_SHA512);
        mac.init(secretKeySpec);
        byte[] bytes = mac.doFinal(data.getBytes());
        Formatter formatter = new Formatter();
        for (byte b : bytes) {
            formatter.format("%02x", b);
        }
        return formatter.toString();
    }

}

@Getter
@Setter
class ReqObject {
    private String event;
    private Data data;
}

@Getter
@Setter
class Data {
    private Transaction transaction;
    private Object authorizationCode;
}

@Getter
@Setter
class Transaction {
    private String _id;
    private String transType;
    private String status;
    private String merchantId;
    private String transactionReference;
    private String customerEmail;
    private String paymentCode;
    private String userTransactionReference;
    private Boolean isRecurrent;
    private String postProcess;
    private String createdAt;
    private String updatedAt;
    private Integer feeAmount;
    private Integer amount;
    private String currency;
}

Python (Flask)

import os
import json
import hashlib
from flask import Flask, request, jsonify

app = Flask(__name__)
secret = os.environ.get("MERCHANT_SECRET_KEY")

@app.route("/my/webhook/url", methods=["POST"])
def handle_webhook():
    # Get the request data as a JSON string
    request_data = request.data.decode("utf-8")

    # Validate the event
    hash_value = calculate_hash(request_data)

    if hash_value == request.headers.get("x-startbutton-signature"):
        # Request is valid, process the event
        event_data = json.loads(request_data)
        # Do something with the event data

    return "", 200

def calculate_hash(data):
    # Calculate HMAC-SHA512 hash of the data
    hmac = hashlib.new("sha512", secret.encode("utf-8"))
    hmac.update(data.encode("utf-8"))
    return hmac.hexdigest()

if __name__ == "__main__":
    app.run()

Ruby (Ruby on Rails)

class WebhookController < ApplicationController
  protect_from_forgery with: :null_session

  def handle_webhook
    secret = ENV['MERCHANT_SECRET_KEY']
    request_body = request.body.read
    signature = request.headers['x-startbutton-signature']

    if is_valid_signature?(secret, request_body, signature)
      # Request is valid, process the event
      event_data = JSON.parse(request_body)
      # Do something with the event data
    end

    head :ok
  end

  private

  def is_valid_signature?(secret, data, signature)
    calculated_signature = OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha512'), secret, data)
    calculated_signature == signature
  end
end

PHP (laravel)

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Illuminate\Http\Response;

class WebhookController extends Controller
{
    public function handleWebhook(Request $request)
    {
        $secret = env('MERCHANT_SECRET_KEY');
        $requestBody = $request->getContent();
        $signature = $request->header('x-startbutton-signature');

        if ($this->isValidSignature($secret, $requestBody, $signature)) {
            // Request is valid, process the event
            $eventData = json_decode($requestBody, true);
            // Do something with the event data
        }

        return response()->json([], Response::HTTP_OK);
    }

    private function isValidSignature($secret, $data, $signature)
    {
        $calculatedSignature = hash_hmac('sha512', $data, $secret);
        return hash_equals($calculatedSignature, $signature);
    }
}

Final Notes

To wrap up your webhook implementation, here is the ideal flow your webhook endpoint should follow

1. Verify request is from us using secret key and payload sent

2. Re-query transaction status after hit

3. Send 200 status back immediately and handle complex logic on your end

4. Ensure webhook responses are idempotent. Save the response and ensure value isn't give twice. since you can get multiple calls for a transaction.