# Deprecations

Usages that still work but should be updated, the notice Moolre returns when it sees them, and the dates that matter.

## How deprecations are announced

A deprecated usage keeps working. When Moolre sees it, the response carries a notice in meta.notices (and the Deprecation: true and Link response headers) that names the problem and links here. Fix the usage at your own pace; the notice stops when the usage does.

Notices are advisory: do not treat a non-empty meta.notices as a failure, and do not parse the message text. Branch on the notice code.

```json
{
  "status": 1,
  "code": "AVD01",
  "message": "Successful",
  "data": "JANE DOE",
  "go": null,
  "meta": {
    "requestid": "req_c68f4c66115c26725c796242",
    "notices": [
      {
        "code": "DEPRECATED_NUMERIC_CHANNEL",
        "message": "Use the channel name (MTN, TELECEL, AT, BANK) instead of the numeric channel id.",
        "docs": "https://docs.moolre.com/guides/channels"
      }
    ]
  }
}
```

## Notice codes



| Notice code | Raised when | What to do |
| --- | --- | --- |
| DEPRECATED_KEY_IN_QUERY | An API key (for example X-API-VASKEY) is sent in the URL. | Send keys in request headers. URLs are written to access logs and browser history. |
| DEPRECATED_KEY_IN_BODY | apikey or username is sent in the request body. | Send X-API-KEY and X-API-USER as headers. |
| DEPRECATED_NUMERIC_CHANNEL | A numeric channel id such as 13 or 6 is used. | Send the channel name: MTN, TELECEL, AT or BANK (GHQR where supported). See Supported channels. |
| PUBKEY_RESIGN | A public key was signed with a retiring signing key. | Generate a new public key before the date given in the notice. The old key keeps working until then. |
| WEBHOOK_SIGNATURE_AVAILABLE | Sent inside webhook payloads. | Verify the X-Moolre-Signature header instead of data.secret. data.secret will be removed after 2027-03-31. |

## Dates to plan for



| Date | What happens |
| --- | --- |
| Now | Webhooks are signed with X-Moolre-Signature and carry event_id, event and created. data.secret is still sent. |
| 2026-12-31 | End of the TLS grace period for webhook endpoints. Until then a callback that fails TLS verification is retried once without verification. After it, a TLS failure is a failed delivery. |
| 2027-03-31 | data.secret is removed from webhook payloads. Verify the signature header before then. |

> **No other date is set:** Keys in the URL or body, and numeric channel ids, still work and have no removal date. Moolre will announce a date in the changelog and in notices well before any of them stops working.

## Migrating in three steps



- Move credentials into headers: X-API-USER and X-API-KEY (or X-API-PUBKEY, X-API-VASKEY). Never in the URL or body.
- Replace numeric channel ids with names: MTN, TELECEL, AT, BANK. The numeric mapping differs per endpoint (13 is MTN for collections but GhQR for payouts), which is exactly why names are safer.
- Verify X-Moolre-Signature on every webhook, reject stale timestamps, and dedupe on event_id. Then stop reading data.secret.

- [Authentication](https://docs.moolre.com/authentication)
- [Supported channels](https://docs.moolre.com/guides/supported-channels)
- [Webhooks and callbacks](https://docs.moolre.com/guides/webhooks-and-callbacks)
