> ## 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 payment intent and get paid by link

> Create a payment intent and share its checkout link

Create a payment intent, share its checkout link, and track the 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). To change it while it's open, [update the intent](/api-reference/payment-intents/update-payment-intent); the pay page shows the new total before the payer pays.

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

<CodeGroup>
  ```python Python theme={null}
  import uuid
  from naturalpay import Natural

  # Set NATURAL_API_KEY to your agent's API key.
  client = Natural(instance_id=str(uuid.uuid4()))

  intent = client.payment_intents.create(
      amount=3920,
      currency="USD",
      description="Order 8842",
      idempotency_key=str(uuid.uuid4()),
  )
  ```

  ```typescript TypeScript theme={null}
  import Natural from "@naturalpay/sdk";

  // Set NATURAL_API_KEY to your agent's API key.
  const client = new Natural();
  const intent = await client.paymentIntents.create(
    {
      amount: 3920,
      currency: "USD",
      description: "Order 8842",
      idempotencyKey: crypto.randomUUID(),
    },
    { instanceId: crypto.randomUUID() },
  );
  ```

  ```bash CLI theme={null}
  natural payment-intents create \
    --amount 3920 \
    --currency USD \
    --description "Order 8842" \
    --x-instance-id "$(uuidgen)" \
    --idempotency-key "$(uuidgen)"
  ```

  ```text MCP theme={null}
  Create a checkout link for Order 8842 for $39.20.
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.natural.com/payment-intents \
    -H "Authorization: Bearer $NATURAL_API_KEY" \
    -H "X-Instance-ID: $(uuidgen)" \
    -H "Idempotency-Key: $(uuidgen)" \
    -H "Content-Type: application/json" \
    -d '{"data":{"attributes":{"amount":3920,"currency":"USD","description":"Order 8842"}}}'
  ```
</CodeGroup>

The response includes the checkout link in `data.attributes.payUrl`. You can also include [line items and tax](/guides/concepts/payment-intents#line-items-and-tax).

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

## Hand the payer the link

Send `payUrl` to the payer. They can enter a card, use Apple Pay where available, or use a saved card after verifying their email. Natural handles checkout, 3-D Secure, and the receipt.

## Follow the payment

Read the intent with [`GET /payment-intents/{paymentIntentId}`](/api-reference/payment-intents/get-payment-intent). Check its status to see whether it was paid.

<CodeGroup>
  ```python Python theme={null}
  payment = client.payment_intents.get(intent.data.id)
  ```

  ```typescript TypeScript theme={null}
  const payment = await client.paymentIntents.get({
    paymentIntentId: intent.data.id,
  });
  ```

  ```bash CLI theme={null}
  natural payment-intents get --payment-intent-id pmi_019d0a1b2c3d4e5f60718293a4b5c6d7
  ```

  ```text MCP theme={null}
  Has the payment intent for Order 8842 been paid?
  ```

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

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

A paid intent has status `completed`. Its `cardPayment` relationship identifies the successful payment. Funds become available after settlement.

Subscribe to `paymentIntent.completed`, `cardPayment.succeeded`, and `cardPayment.failed` [webhooks](/api-reference/event-catalog) for updates. See [Card payments](/guides/concepts/card-payments#failure-codes) for failed attempts.

## Reconcile

[List payment intents](/api-reference/payment-intents/list-payment-intents) to review recent activity. Filter by status or creation date. Use `cursor` for the next page and `customerPartyId` for a customer's intents.

<CodeGroup>
  ```python Python theme={null}
  intents = client.payment_intents.list(status="open", limit=20)
  ```

  ```typescript TypeScript theme={null}
  const intents = await client.paymentIntents.list({ status: "open", limit: 20 });
  ```

  ```bash CLI theme={null}
  natural payment-intents list --status open --limit 20
  ```

  ```text MCP theme={null}
  List my 20 most recent open payment intents.
  ```

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

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

Successful payments and refunds appear in [Transactions](/guides/concepts/transactions). Each payment transaction links to its card payment.

## 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. For cURL, send `data.attributes` even when empty.

<CodeGroup>
  ```python Python theme={null}
  canceled = client.payment_intents.cancel(
      intent.data.id,
      idempotency_key=str(uuid.uuid4()),
  )
  ```

  ```typescript TypeScript theme={null}
  const canceled = await client.paymentIntents.cancel(
    {
      paymentIntentId: intent.data.id,
      idempotencyKey: crypto.randomUUID(),
    },
    { instanceId: crypto.randomUUID() },
  );
  ```

  ```bash CLI theme={null}
  natural payment-intents cancel \
    --payment-intent-id pmi_019d0a1b2c3d4e5f60718293a4b5c6d7 \
    --x-instance-id "$(uuidgen)" \
    --idempotency-key "$(uuidgen)"
  ```

  ```text MCP theme={null}
  Cancel the unpaid payment intent for Order 8842.
  ```

  ```bash cURL theme={null}
  # NATURAL_API_KEY=ak_ntl_prod_... (the agent's key)
  curl -X POST https://api.natural.com/payment-intents/pmi_019d0a1b2c3d4e5f60718293a4b5c6d7/cancel \
    -H "Authorization: Bearer $NATURAL_API_KEY" \
    -H "X-Instance-ID: $(uuidgen)" \
    -H "Idempotency-Key: $(uuidgen)" \
    -H "Content-Type: application/json" \
    -d '{ "data": { "attributes": {} } }'
  ```
</CodeGroup>

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


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