> For the complete documentation index, see [llms.txt](https://startbutton.gitbook.io/startbutton-product-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://startbutton.gitbook.io/startbutton-product-api/webhooks/collection-events/under-overpayment-webhook-behavior.md).

# Under/Overpayment Webhook Behavior

### Webhook Samples for Under and Overpaid transactions:

#### Overpayment webhook behavior:

When an overpayment occurs, two separate webhooks are triggered:

1. **Expected Transaction Webhook**
2. **Overpaid Transaction Webhook**

**Breakdown**

1. **Expected Transaction Webhook**: This is the first webhook sent. It represents the original expected transaction and includes an indicator that the amount received exceeded the expected value.
   * Look out for the field:

```json
"isOverPaid": true
```

* This means the amount received was **greater than** the expected amount.
* Note: The expected amount is treated as a **standalone transaction**, even in the case of overpayment.

2. **Overpaid Transaction Webhook:** This second webhook captures the excess amount paid. It is treated as a new transaction record, with a unique reference.
   * It includes an `extraInformation` object, which contains details about the original transaction the overpayment is linked to.
   * The overpaid value is recorded under the field:

```json
"amount": <value_in_fractional_units>
```

{% tabs %}
{% tab title="Underpayment" %}

```json
{
  "event": "collection.verified",
  "data": {
    "transaction": {
      "_id": "67d946xxxx",
      "transType": "collection",
      "status": "successful",
      "merchantId": "64xxxxxxxxxxxx",
      "transactionReference": "09026725031811120xxxxxxxx",
      "customerEmail": "test@customer.com",
      "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"
    }
  }
}
```

{% endtab %}

{% tab title="First Webhook for Overpaid transactions" %}

```json
{
  "event": "collection.completed",
  "data": {
    "transaction": {
      "_id": "687xxxxxxxxxxxxxxxx",
      "transType": "collection",
      "status": "successful",
      "merchantId": "648xxxxxxxxxxxxxxxx",
      "transactionReference": "b91f8xxxxx",
      "customerEmail": "tester@gmail.com",
      "paymentPartnerId": "65fbxxxxxxxxxxxxxxxxx",
      "paymentCode": "f35xxxxxxxxx",
      "isRecurrent": false,
      "postProcess": null,
      "createdAt": "2025-07-18T11:02:51.706Z",
      "updatedAt": "2025-07-18T11:04:24.635Z",
      "feeAmount": 10240,
      "amount": 20000,
      "currency": "NGN",
      "initialAmount": 20000
    },
    "authorizationCode": null,
    "extraInformation": {
      "isOverPaid": true
    }
  }
}
```

{% endtab %}

{% tab title="Second Webhook for Overpayment" %}

```json
{
  "event": "collection.verified",
  "data": {
    "transaction": {
      "_id": "67d946xxxx",
      "transType": "collection",
      "status": "successful",
      "merchantId": "64xxxxxxxxxxxx",
      "transactionReference": "0102672556781120xxxxxxxx",
      "customerEmail": "test@customer.com",
      "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": "b079dxxx",
      "userTransactionReference": "TEST613",
      "expectedAmount": 100000,
      "paymentCollectionType": "OVERPAYMENT"
    },
    "payerInformation": {
      "sessionId": "01678954xxxxxxxxxx",
      "accountNumber": "**********",
      "bankName": "KUDA MICROFINANCE BANK"
    }
  }
}
```

{% endtab %}
{% endtabs %}

If a `reference` is passed when initiating a transaction; a `userTransactionReference` will be returned in your webhook for completed transactions as well as under or overpayments.

The `userTransactionReference`will have the value passed in as reference during initialization.