Skip to main content
The Bank Response webhook is sent to merchants when banks respond to billing requests on behalf of their customers. This webhook contains the final payment confirmation or decline.

​
When This Webhook is Sent

Trigger Event

Sent to merchants when a bank responds to a billing request via POST /v1/billing/bank-response after customer approval or decline.
Webhook Type: billing.response Recipient: Merchants and Providers Frequency: Real-time (immediate)

​
Webhook Payload Structure

{
  "entityId": "merchant_001",
  "entityType": "merchant",
  "webhookType": "billing.response",
  "timestamp": "2024-01-15T11:05:00.000Z",
  "batchId": "batch_response_890",
  "data": [
    {
      "customerId": "customer_123",
      "amount": 1500,
      "currency": "NGN",
      "reference": "billing_ref_xyz789",
      "merchant": {
        "id": "merchant_001",
        "name": "Netflix Nigeria"
      },
      "customerAction": "accepted",
      "isSettled": false,
      "bankTransactionId": "bank_txn_abc123",
      "processedAt": "2024-01-15T11:05:00.000Z"
    }
  ],
  "totalAmount": 1500,
  "itemCount": 1
}

​
Customer Actions

accepted

Customer approved the payment. Transaction will be processed and settled.

declined

Customer declined the payment. No funds will be transferred.

​
Implementation Guide

app.post('/webhooks/peere/billing-response', (req, res) => {
  try {
    const signature = req.headers['x-peere-signature'];
    if (!verifySignature(req.body, signature)) {
      return res.status(401).send('Invalid signature');
    }
    
    const { webhookType, data } = req.body;
    
    if (webhookType === 'billing.response') {
      handleBillingResponse(data);
    }
    
    res.status(200).send('OK');
  } catch (error) {
    console.error('Webhook processing error:', error);
    res.status(500).send('Internal Server Error');
  }
});

async function handleBillingResponse(responseData) {
for (const response of responseData) {
const { customerId, amount, reference, customerAction } = response;

    if (customerAction === 'accepted') {
      // Payment approved - update order status
      await updateOrderStatus(reference, 'paid', response);
      await fulfillOrder(reference);
      await sendPaymentConfirmation(customerId, response);
    } else {
      // Payment declined
      await updateOrderStatus(reference, 'payment_declined', response);
      await offerAlternativePayment(customerId, reference);
    }

}
}

​
Best Practices

Order Management

  • Update order status immediately - Use database transactions - Implement error handling - Log all payment events

Customer Communication

  • Send immediate confirmations - Provide clear payment details - Offer alternatives for declined payments - Include support information

​
Next Steps

Order Management

Learn advanced order processing techniques

API Reference

Explore merchant API endpoints