> ## Documentation Index
> Fetch the complete documentation index at: https://docs.balaipedia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Best practices

> Recommendations for a reliable integration.

* Send an `Idempotency-Key` on `POST /orders` (optional, but recommended so the same order is never created twice); reuse the same key when retrying.
* Store our order `id` next to your own order. Use `reference` to link them. Keep your own copy of every order and its final status: we only keep them retrievable for 60 days.
* Use [webhooks](https://docs.balaipedia.com/webhooks.md) as the primary source of status; poll only as a fallback.
* Check the HTTP status before parsing the body, and handle a non-JSON `5xx` as retryable.
* Read `currency` from responses instead of assuming it.
* Treat unknown fields in responses as additive: we may add new fields without notice.
* Keep the API key and webhook secret in server-side secret storage.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.