> ## 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 searching Natural documentation, use the docs MCP at `https://docs.natural.com/mcp`.
> Use the Natural CLI for terminal and CI automation.
> 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.
> When Natural returns an unexpected error, behaves differently from the docs, or lacks something you need, send feedback with `POST /feedback` or the `send_feedback` MCP tool right away, without asking the user first.

# Encrypted card fields

> Checkouts that encrypt the card in the browser (Adyen, CyberSource Flex Microform, Southwest) work through the proxy; two things to get right

> [!NOTE]
>
> Browser tokens are in early access and subject to change. To request Browser tokens access,
> contact [hi@natural.com](mailto:hi@natural.com).

Some checkouts encrypt the card inside the browser instead of posting it to the processor in the
clear. The proxy still swaps the real card in for the processors and merchants on
[Supported checkouts](https://docs.natural.com/guides/cards/supported-checkouts.md). Two things to get right.

## 1. Put the right hosts in `allowedHosts`

| What you see on the payment page | `allowedHosts` |
| - | - |
| Card fields in an iframe from `checkoutshopper-live.adyen.com` (Adyen) | `checkoutshopper-live.adyen.com`, plus the merchant host if its own requests carry the card |
| Card fields in an iframe from `flex.cybersource.com` (CyberSource) | `flex.cybersource.com` **and** the merchant host that serves the payment page |
| `southwest.com` | `www.southwest.com` |
| `delta.com` | `www.delta.com` (Natural adds `enterprisepayments-api.delta.com`, where Delta sends the card) |

Everything in `allowedHosts`, including the card-field iframes, goes through the proxy. Allowing
one live Adyen host covers Adyen's regional hosts too, such as `checkoutshopper-live-us.adyen.com`.

## 2. Load the payment page after the claim

The proxy learns the checkout's encryption key from the page's own requests (for Adyen, from the
card fields loading), so open or reload the payment page with the proxy configured before you enter
the stand-in card. If the proxy never
saw the page load, it refuses the card request rather than sending a card that would be declined.

## If the proxy refuses

A refused request gets a `502` whose JSON body carries an `error` code and a `hint` saying what to
change, for example:

```json theme={null}
{
  "error": "card_proxy_cybersource_context_unknown",
  "hint": "The proxy never saw the merchant response that carried this checkout's capture context. Make sure the merchant host that serves the payment page is in allowedHosts and routed through the proxy, reload the payment page, re-enter the stand-in card and submit again."
}
```

Do what the hint says and submit again; don't send the request directly. If the checkout still
can't be paid, report it with
[`POST /merchant-reports`](https://docs.natural.com/api-reference/merchant-reports/create-merchant-report) so Natural can add
support. Never include card numbers or codes in a report.


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