Approve or deny a held payment

Release or deny a payment that a limit put on hold.

When a payment breaches one of your limits, Natural does not reject it. Natural holds the payment and opens an approval (apr_*). The call that sent the payment still returns 2xx, and no money moves until someone approves. See the Approvals overview.

List what is held

GET /approvals lists pending holds. status accepts pending, approved, denied, or canceled.

approvals = client.approvals.list(status="pending")

const approvals = await client.approvals.list({ status: "pending" });

natural approvals list --status pending --limit 50

curl "https://api.natural.com/approvals?status=pending&limit=50" \
  -H "Authorization: Bearer $NATURAL_API_KEY"

Each record names the payment it holds and every reason it was held:

Approve or deny

POST /approvals/{approvalId}/approve releases the original payment. POST /approvals/{approvalId}/deny ends it in APPROVAL_DENIED. Send reason (up to 500 characters) to record why.

import uuid

client.approvals.approve("apr_019cd1798d8a74dd75c16fc6d843db81", idempotency_key=str(uuid.uuid4()))
# or
client.approvals.deny(
    "apr_019cd1798d8a74dd75c16fc6d843db81",
    reason="Over budget for this vendor",
    idempotency_key=str(uuid.uuid4()),
)

await client.approvals.approve({
  approvalId: "apr_019cd1798d8a74dd75c16fc6d843db81",
  idempotencyKey: crypto.randomUUID(),
});
// or
await client.approvals.deny({
  approvalId: "apr_019cd1798d8a74dd75c16fc6d843db81",
  reason: "Over budget for this vendor",
  idempotencyKey: crypto.randomUUID(),
});

natural approvals approve --approval-id apr_019cd1798d8a74dd75c16fc6d843db81 --idempotency-key "$(uuidgen)"
# or
natural approvals deny --approval-id apr_019cd1798d8a74dd75c16fc6d843db81 --json '{"reason": "Over budget for this vendor"}' --idempotency-key "$(uuidgen)"

curl -X POST https://api.natural.com/approvals/apr_019cd1798d8a74dd75c16fc6d843db81/approve \
  -H "Authorization: Bearer $NATURAL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

The record comes back resolved, with status now approved and resolvedAt set: Approving clears only the gate you own. If the payment also breached a gate owned by someone else, it stays held until that owner acts too. When several breached gates share one owner, they merge into one hold that lists every reason, and the highest breached limit is the one you are clearing.

Overview

Common use cases

Products

Guides

Approve or deny a held payment

List what is held

Approve or deny

​List what is held

​Approve or deny

List what is held

Approve or deny