> ## 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.

# Formats

> Data formats and units used across the API

## Monetary amounts

Monetary amounts are **integer cents**.

| API value | Dollars |
| - | - |
| `100` | \$1.00 |
| `500000` | \$5,000.00 |
| `1234` | \$12.34 |

```json theme={null}
{
  "amount": 500000,
  "currency": "USD"
}
```

Amounts are always integers, never strings or floats. Maximum precision is 2 decimal places (1 cent).

<Note>
  Integer cents apply to the REST API and SDKs. Tools on the hosted [MCP
  server](/guides/platform/mcp#amounts-and-currencies) instead take decimal-string amounts with a
  required currency (`"amount": "10.50", "currency": "USD"`); the MCP server converts between the
  two encodings at the boundary.
</Note>

## Currency codes

[ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) three-letter uppercase codes. Natural accepts `USD`. Every request that takes `currency` accepts an omitted value as `USD`, except payment intents, which require it.

```json theme={null}
{
  "currency": "USD"
}
```

## Timestamps

[ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) / [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339), always UTC.

```json theme={null}
{
  "createdAt": "2026-01-04T15:30:00.000Z"
}
```

Timestamps are RFC 3339 with millisecond precision in UTC (the `Z` suffix); the API does not return local time offsets. Timestamps you send must be RFC 3339 with an explicit `Z` or offset; a timestamp without a zone is rejected with `invalid_value`.

## Phone numbers

[E.164](https://en.wikipedia.org/wiki/E.164) international format: plus sign, country code, subscriber number.

```json theme={null}
{
  "phone": "+14155551234"
}
```


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