Track a payment

Follow a payment (pay_*) you sent 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. For the lifecycle, read the Payments overview.

Get one payment

Look up a payment with GET /payments/{paymentId} to read its current status.

payment = client.payments.get("pay_019cd1798d77ef3e74d16143bd39940a")
status = payment.data.attributes.status

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

natural payments get --payment-id pay_019cd1798d77ef3e74d16143bd39940a

What's the status of payment pay_019cd1798d77ef3e74d16143bd39940a?

curl https://api.natural.com/payments/pay_019cd1798d77ef3e74d16143bd39940a \
  -H "Authorization: Bearer $NATURAL_API_KEY"

The response carries the payment’s status, amount, and the parties on each side: 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 returns every transaction (txn_*) on your account: payments, transfers (deposits, withdrawals, internal), and refunds, newest first.

transactions = client.transactions.list(limit=20)

const transactions = await client.transactions.list({ limit: 20 });

natural transactions list --limit 20

List my recent transactions.

curl "https://api.natural.com/transactions?limit=20" \
  -H "Authorization: Bearer $NATURAL_API_KEY"

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

Cancel a payment

Cancel a payment with POST /payments/{paymentId}/cancel while it is still PENDING_CLAIM. Once the recipient starts claiming, cancel returns 409. Canceling an already canceled payment returns it unchanged.

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()),
)

// 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(),
  },
);

# NATURAL_API_KEY=ak_ntl_prod_... (the agent's key)
natural payments cancel \
  --payment-id pay_019cd1798d77ef3e74d16143bd39940a \
  --x-instance-id "$(uuidgen)" \
  --idempotency-key "$(uuidgen)"

Cancel payment pay_019cd1798d77ef3e74d16143bd39940a.

# 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)"

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

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.

Overview

Common use cases

Products

Guides

Get one payment

List all money movement

Cancel a payment

​Get one payment

​List all money movement

​Cancel a payment

Get one payment

List all money movement

Cancel a payment