Track a payment

Follow a payment you sent or requested through its lifecycle, list every money movement on your account, and cancel a payment before it settles.

Get one payment

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

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

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

natural payments get --payment-id pay_550e8400e29b41d4a716446655440000

What's the status of payment pay_550e8400e29b41d4a716446655440000?

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

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

Cancel a payment

Cancel a payment with POST /payments/{paymentId}/cancel while it is still PENDING_CLAIM.

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

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

natural payments cancel \
  --payment-id pay_550e8400e29b41d4a716446655440000 \
  --x-agent-id agt_019cd1798d637a4da75dce386343931d \
  --x-instance-id "$(uuidgen)" \
  --idempotency-key "$(uuidgen)"

Cancel payment pay_550e8400e29b41d4a716446655440000.

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

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

Cancellation only works before settlement. Once a payment reaches PROCESSING, the funds are already moving and it can no longer be canceled.

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