C2B (Customer-to-Business) Callbacks

Receive a signed notification when a customer payment reaches its final state. The callback is sent to the notifyUrl you supplied in the initiate-payment request.

Payload Format

{
  "txnId": "TXN123456789",
  "status": "completed",
  "amount": 100.50,
  "txnType": "c2b",
  "currency": "ETB"
}

Field Reference

Field	Type	Description
`txnId`	string	Unique transaction identifier
`status`	string	Final status: `completed`, `failed`, `expired`, or `cancelled`
`amount`	number	Payment amount
`txnType`	string	Always `"c2b"` for customer-to-business transactions
`currency`	string	Currency code (may be omitted)

Callbacks are only sent for final states. There is no pending callback — a transaction that never completes eventually produces an expired callback.

Verify, Then Process

Always verify the Ed25519 signature before trusting the payload — see Signature Verification for complete verification code in Node.js, Python, and Go. The examples below assume verifyCallback / verify_callback from that page.

Node.js
Python
Go

app.post('/c2b-webhook', async (req, res) => {
    if (!verifyCallback(req)) {
        return res.status(401).json({ error: 'Invalid signature' });
    }

    const { txnId, status, amount, txnType, currency } = req.body;
    if (txnType !== 'c2b') {
        return res.status(400).json({ error: 'Unexpected transaction type' });
    }

    // Dedupe: retries can deliver the same settlement more than once
    if (await alreadyProcessed(req.headers['x-request-id'])) {
        return res.status(200).json({ message: 'Already processed' });
    }

    // Acknowledge fast, process async
    res.status(200).json({ message: 'OK' });

    switch (status) {
        case 'completed':
            await updatePaymentStatus(txnId, 'completed');
            await fulfillOrder(txnId);
            break;
        case 'failed':
        case 'expired':
        case 'cancelled':
            await updatePaymentStatus(txnId, status);
            break;
    }
});

@app.route("/c2b-webhook", methods=["POST"])
def c2b_webhook():
    if not verify_callback(request):
        abort(401)

    data = request.get_json()
    if data.get("txnType") != "c2b":
        return {"error": "Unexpected transaction type"}, 400

    # Dedupe: retries can deliver the same settlement more than once
    if already_processed(request.headers["X-Request-ID"]):
        return {"message": "Already processed"}, 200

    txn_id = data["txnId"]
    status = data["status"]

    if status == "completed":
        update_payment_status(txn_id, "completed")
        fulfill_order(txn_id)
    elif status in ("failed", "expired", "cancelled"):
        update_payment_status(txn_id, status)

    return {"message": "OK"}, 200

type c2bCallback struct {
    TxnID    string  `json:"txnId"`
    Status   string  `json:"status"`
    Amount   float64 `json:"amount"`
    TxnType  string  `json:"txnType"`
    Currency string  `json:"currency"`
}

func c2bWebhookHandler(w http.ResponseWriter, r *http.Request) {
    body, err := io.ReadAll(http.MaxBytesReader(w, r.Body, 1<<20))
    if err != nil {
        http.Error(w, "bad request", http.StatusBadRequest)
        return
    }
    if !verifyCallback(r, body) {
        http.Error(w, "invalid signature", http.StatusUnauthorized)
        return
    }

    var cb c2bCallback
    if err := json.Unmarshal(body, &cb); err != nil || cb.TxnType != "c2b" {
        http.Error(w, "unexpected payload", http.StatusBadRequest)
        return
    }

    // Dedupe: retries can deliver the same settlement more than once
    if alreadyProcessed(r.Header.Get("X-Request-ID")) {
        w.WriteHeader(http.StatusOK)
        return
    }

    // Acknowledge fast, process async
    w.WriteHeader(http.StatusOK)
    go processC2BSettlement(cb)
}

Sample Payloads

Successful Payment

{
  "txnId": "TXN20260812001234",
  "status": "completed",
  "amount": 250.00,
  "txnType": "c2b",
  "currency": "ETB"
}

Failed Payment

{
  "txnId": "TXN20260812001235",
  "status": "failed",
  "amount": 150.75,
  "txnType": "c2b",
  "currency": "ETB"
}

Expired Session

{
  "txnId": "TXN20260812001236",
  "status": "expired",
  "amount": 500.00,
  "txnType": "c2b",
  "currency": "ETB"
}

Best Practices

Security

Always verify the Ed25519 signature against the raw body bytes before parsing JSON
Enforce a timestamp freshness window and dedupe on X-Request-ID
Never fulfill an order based on the browser redirect to successUrl alone — wait for the completed callback

Performance

Respond 2xx within 10 seconds; queue heavy work for asynchronous processing
Index your transactions table on txnId for fast lookups
Log the X-Request-ID of every delivery — it is the correlation handle for support

Getting Started

Accept Payments

Make Transfers

Webhooks

Resources

C2B Callbacks

C2B (Customer-to-Business) Callbacks

Payload Format

Field Reference

Verify, Then Process

Sample Payloads

Successful Payment

Failed Payment

Expired Session

Best Practices

​C2B (Customer-to-Business) Callbacks

​Payload Format

​Field Reference

​Verify, Then Process

​Sample Payloads

​Successful Payment

​Failed Payment

​Expired Session

​Best Practices

C2B (Customer-to-Business) Callbacks

Payload Format

Field Reference

Verify, Then Process

Sample Payloads

Successful Payment

Failed Payment

Expired Session

Best Practices