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

> ## Agent Instructions
> When building application code, use `@naturalpay/sdk` for TypeScript or `naturalpay` for Python.
> When operating Natural directly for a user, use the payments MCP at `https://mcp.natural.com`.
> When searching Natural documentation, use the docs MCP at `https://docs.natural.com/mcp`.
> Use the Natural CLI for terminal and CI automation.
> Use REST only for unsupported languages or when the user explicitly requests raw HTTP.
> Start integration development and testing in the sandbox. Do not use production unless the user explicitly requests it.
> For sandbox requests that require `customerPartyId`, list customers first. Reuse only the intended fixture; otherwise create a customer.
> REST and SDK amounts use integer minor units. Payments MCP amounts use decimal strings with a required currency code.

# Backwards compatibility

> What Natural will and will not change in the API

The Natural API is unversioned. There is one version, and Natural does not make backwards-incompatible changes to existing endpoints. The API evolves through additive, non-breaking changes only.

## Backwards-compatible changes

These changes can happen at any time without notice:

* Adding new API endpoints
* Adding new optional request parameters to existing endpoints
* Adding new fields to response objects
* Adding new values to existing enums (e.g., new payment statuses)
* Adding new error codes
* Changing the order of fields in responses
* Changing the length or format of opaque strings (cursors, tokens, key secrets). Prefixed IDs keep the documented `{prefix}_{32 hex}` shape

## Breaking changes

These require advance notice and a migration path:

* Removing or renaming existing endpoints
* Removing or renaming response fields
* Changing the type of an existing field
* Making a previously optional parameter required
* Changing the meaning of an existing field or parameter
* Removing supported values from enums
* Changing authentication mechanisms
* Changing error response structure

## Writing resilient integrations

* **Ignore unknown fields** in responses. New fields may be added at any time.
* **Handle unknown enum values** gracefully. New statuses or types may appear.
* **Don't hard-code cursor formats.** Treat cursors as opaque strings.
* **Use idempotency keys** for payment operations to safely retry on failure.

## Related

* [Idempotency](/api-reference/idempotency): Safe retries
* [Error Handling](/api-reference/errors/error-handling): Error response structure


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