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

# Track a payment

> Follow a payment through its lifecycle

Follow a payment (`pay_*`) you [sent](/guides/payments/send-payment) through its lifecycle, list every money movement on your account, and cancel a payment the recipient has not yet claimed. To follow a payment request you created, read the request itself, as on [Request a payment](/guides/payments/request-payment#track-it). For the lifecycle, read the [Payments overview](/guides/concepts/payments).

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

<Snippet file="shared/mcp-callout.mdx" />

## Get one payment

Look up a payment with [`GET /payments/{paymentId}`](/api-reference/payments/get-payment) to read its current status.

<CodeGroup>
  ```python Python theme={null}
  payment = client.payments.get("pay_019cd1798d77ef3e74d16143bd39940a")
  status = payment.data.attributes.status
  ```

  ```typescript TypeScript theme={null}
  const payment = await client.payments.get({
    paymentId: "pay_019cd1798d77ef3e74d16143bd39940a",
  });
  const status = payment.data.attributes.status;
  ```

  ```bash CLI theme={null}
  natural payments get --payment-id pay_019cd1798d77ef3e74d16143bd39940a
  ```

  ```text MCP theme={null}
  What's the status of payment pay_019cd1798d77ef3e74d16143bd39940a?
  ```

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

The response carries the payment's `status`, amount, and the parties on each side:

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

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

A healthy payment moves `CREATED` to `PROCESSING` to `COMPLETED`. It can pause at `PENDING_CLAIM` while it waits for a new recipient to claim the funds, or at `IN_REVIEW` during a compliance hold. It ends at `FAILED`, `RETURNED`, `CANCELED`, or `APPROVAL_DENIED`.

## List all money movement

[`GET /transactions`](/api-reference/transactions/list-transactions) returns every transaction (`txn_*`) on your account: payments, transfers (deposits, withdrawals, internal), and refunds, newest first.

<CodeGroup>
  ```python Python theme={null}
  transactions = client.transactions.list(limit=20)
  ```

  ```typescript TypeScript theme={null}
  const transactions = await client.transactions.list({ limit: 20 });
  ```

  ```bash CLI theme={null}
  natural transactions list --limit 20
  ```

  ```text MCP theme={null}
  List my recent transactions.
  ```

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

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

To read the transactions your agent ran for a customer, add the `customerPartyId` query param. It returns delegated activity only.

<Snippet file="shared/webhook-track-money.mdx" />

## Cancel a payment

Cancel a payment with [`POST /payments/{paymentId}/cancel`](/api-reference/payments/cancel-payment) while it is still `PENDING_CLAIM`. Once the recipient starts claiming, cancel returns 409. Canceling an already canceled payment returns it unchanged.

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

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

  # NATURAL_API_KEY=ak_ntl_prod_... (the agent's key)
  agent_client = Natural(
      instance_id=str(uuid.uuid4()),
  )

  canceled = agent_client.payments.cancel(
      "pay_019cd1798d77ef3e74d16143bd39940a",
      idempotency_key=str(uuid.uuid4()),
  )
  ```

  ```typescript TypeScript theme={null}
  // NATURAL_API_KEY=ak_ntl_prod_... (the agent's key)
  const canceled = await client.payments.cancel(
    {
      paymentId: "pay_019cd1798d77ef3e74d16143bd39940a",
      idempotencyKey: crypto.randomUUID(),
    },
    {
      instanceId: crypto.randomUUID(),
    },
  );
  ```

  ```bash CLI theme={null}
  # NATURAL_API_KEY=ak_ntl_prod_... (the agent's key)
  natural payments cancel \
    --payment-id pay_019cd1798d77ef3e74d16143bd39940a \
    --x-instance-id "$(uuidgen)" \
    --idempotency-key "$(uuidgen)"
  ```

  ```text MCP theme={null}
  Cancel payment pay_019cd1798d77ef3e74d16143bd39940a.
  ```

  ```bash cURL theme={null}
  # NATURAL_API_KEY=ak_ntl_prod_... (the agent's key)
  curl -X POST https://api.natural.com/payments/pay_019cd1798d77ef3e74d16143bd39940a/cancel \
    -H "Authorization: Bearer $NATURAL_API_KEY" \
    -H "X-Instance-ID: $(uuidgen)" \
    -H "Idempotency-Key: $(uuidgen)"
  ```
</CodeGroup>

The payment moves to `CANCELED` and no funds leave your wallet:

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

<Note>
  Only a `PENDING_CLAIM` payment can be canceled, and only until the recipient begins claiming.
  Direct payments and payments held at `IN_REVIEW` cannot be canceled here.
</Note>


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