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

# Create a card payment intent

> Create a card payment intent and hand the payer a hosted checkout link.

Create a card payment intent for any amount, send the payer a checkout link Natural returns, and follow the lifecycle of the payment. Everything settles into your wallet like any other payment.

<Snippet file="shared/prerequisites.mdx" />

<Note>
  Taking card payments for a **customer** instead of your own business? Pass their party ID as
  `customerPartyId` on every call below. See [Collecting for a
  customer](/guides/concepts/payment-intents#collecting-for-a-customer).
</Note>

<Snippet file="shared/cents-note.mdx" />

## Create the intent

Create the intent with [`POST /payment-intents`](/api-reference/payment-intents/create-payment-intent). There is no mutability, modifications to totals must be submitted as a new intent.

<Snippet file="shared/instance-id-note.mdx" />

```bash cURL theme={null}
# NATURAL_API_KEY=ak_ntl_prod_... (the agent's key)
curl -X POST https://api.natural.com/payment-intents \
  -H "Authorization: Bearer $NATURAL_API_KEY" \
  -H "X-Instance-ID: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "attributes": {
        "amountMinor": 4620,
        "currency": "USD",
        "description": "Order 8842",
        "taxMode": "exclusive",
        "taxAmountMinor": 420,
        "lineItems": [
          {
            "merchantReference": "menu_item_31",
            "description": "Margherita pizza",
            "quantity": 2,
            "unitAmountMinor": 1800,
            "subtotalMinor": 3600,
            "taxMinor": 320,
            "totalMinor": 3920,
            "taxCode": "prepared_food"
          },
          {
            "merchantReference": "menu_item_77",
            "description": "Sparkling water",
            "quantity": 1,
            "unitAmountMinor": 600,
            "subtotalMinor": 600,
            "taxMinor": 100,
            "totalMinor": 700,
            "taxCode": "beverage"
          }
        ]
      }
    }
  }'
```

The response carries the response object and, in the `meta.payUrl` field, the hosted checkout link. Line items are optional. Totals must add up to `amountMinor`, and `taxAmountMinor` must equal the sum of line tax.

## Hand the payer the link

Send `payUrl` to the payer however you already reach them. The page it opens is Natural's hosted checkout: they enter their card, or use Apple Pay where it is available, and pay the amount shown. Returning payers can pay with a saved card after verifying their email. Natural integrates natively with 3-D Secure and handles the payer receipt.

## Follow the payment

Read the intent with [`GET /payment-intents/{paymentIntentId}`](/api-reference/payment-intents/get-payment-intent). Its `status` and the embedded `cardPayment` tell you where the payment stands.

```bash cURL theme={null}
curl https://api.natural.com/payment-intents/pmi_019d0a1b2c3d4e5f60718293a4b5c6d7 \
  -H "Authorization: Bearer $NATURAL_API_KEY"
```

<Snippet file="api-examples/paymentIntents.get.response.mdx" />

A paid intent reads `completed` with a `succeeded` card payment. A declined card leaves the intent `open` and the card payment `failed`, with `declineCode` and `declineAdvice` saying why and what to do next:

<Snippet file="api-examples/paymentIntents.get.response.declined.mdx" />

## Reconcile

[`GET /payment-intents`](/api-reference/payment-intents/list-payment-intents) lists your intents newest first. Filter by `status`, `createdAfter`, and `createdBefore`, and page with `cursor`. Pass `customerPartyId` to list one customer's intents instead.

```bash cURL theme={null}
curl "https://api.natural.com/payment-intents?status=open&limit=20" \
  -H "Authorization: Bearer $NATURAL_API_KEY"
```

<Snippet file="api-examples/paymentIntents.list.response.mdx" />

A platform that creates intents for many customers can call [`GET /payment-intents/created`](/api-reference/payment-intents/list-created-payment-intents) instead: one feed of every intent you created, whoever it was for.

Every succeeded card payment and every refund also lands in [Transactions](/guides/concepts/transactions). A card payment is a `payment` transaction that relates to its `cardPayment`, so you can join the settled amount back to the intent; set `type=refund` on [`GET /transactions`](/api-reference/transactions/list-transactions) to see only refunds.

## Cancel an intent

Cancel an open intent with [`POST /payment-intents/{paymentIntentId}/cancel`](/api-reference/payment-intents/cancel-payment-intent). The checkout link stops working.

```bash cURL theme={null}
curl -X POST https://api.natural.com/payment-intents/pmi_019d0a1b2c3d4e5f60718293a4b5c6d7/cancel \
  -H "Authorization: Bearer $NATURAL_API_KEY" \
  -H "X-Instance-ID: $(uuidgen)"
```

<Snippet file="api-examples/paymentIntents.cancel.response.mdx" />

<Note>
  An intent with a payment in progress cannot be canceled, and neither can one that already
  completed. Refund a completed payment instead: see [Refund a card
  payment](/guides/accept/refund-a-card-payment).
</Note>