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

# Track a payment

> Follow a payment through its lifecycle.

Follow a payment you [sent](/guides/payments/send-payment) or [requested](/guides/payments/request-payment) through its lifecycle, list every money movement on your account, and cancel a payment before it settles.

<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_550e8400e29b41d4a716446655440000")
  status = payment.data.attributes.status
  ```

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

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

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

  ```bash cURL theme={null}
  curl https://api.natural.com/payments/pay_550e8400e29b41d4a716446655440000 \
    -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 all your transactions: every payment, transfer, deposit, and withdrawal, in reverse-chronological order.

<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 a customer's transactions instead of your own, add the `customerPartyId` query param.

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

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

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

  agent_client = Natural(
      x_agent_id="agt_019cd1798d637a4da75dce386343931d",
      x_instance_id=str(uuid.uuid4()),
  )

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

  ```typescript TypeScript theme={null}
  const canceled = await client.payments.cancel(
    {
      paymentId: "pay_550e8400e29b41d4a716446655440000",
      idempotencyKey: crypto.randomUUID(),
    },
    {
      xAgentId: "agt_019cd1798d637a4da75dce386343931d",
      xInstanceId: crypto.randomUUID(),
    },
  );
  ```

  ```bash CLI theme={null}
  natural payments cancel \
    --payment-id pay_550e8400e29b41d4a716446655440000 \
    --x-agent-id agt_019cd1798d637a4da75dce386343931d \
    --x-instance-id "$(uuidgen)" \
    --idempotency-key "$(uuidgen)"
  ```

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

  ```bash cURL theme={null}
  curl -X POST https://api.natural.com/payments/pay_550e8400e29b41d4a716446655440000/cancel \
    -H "Authorization: Bearer $NATURAL_API_KEY" \
    -H "X-Agent-ID: agt_019cd1798d637a4da75dce386343931d" \
    -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>
  Cancellation only works before settlement. Once a payment reaches `PROCESSING`, the funds are
  already moving and it can no longer be canceled.
</Note>