Approvals

When a payment breaches a limit whose action is hold, Natural does not reject it. Natural holds the payment and opens an approval process. The call that sent the payment still returns 2xx, and no money moves until someone approves.

List what is held

GET /approvals lists what is held, showing pending holds by default.

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 cancels it.

import uuid

client.approvals.approve("apr_550e8400e29b41d4a716446655440000", idempotency_key=str(uuid.uuid4()))
# or
client.approvals.deny("apr_550e8400e29b41d4a716446655440000", idempotency_key=str(uuid.uuid4()))

await client.approvals.approve({
  approvalId: "apr_550e8400e29b41d4a716446655440000",
  idempotencyKey: crypto.randomUUID(),
});
// or
await client.approvals.deny({
  approvalId: "apr_550e8400e29b41d4a716446655440000",
  idempotencyKey: crypto.randomUUID(),
});

natural approvals approve --approval-id apr_550e8400e29b41d4a716446655440000 --idempotency-key "$(uuidgen)"
# or
natural approvals deny --approval-id apr_550e8400e29b41d4a716446655440000 --idempotency-key "$(uuidgen)"

curl -X POST https://api.natural.com/approvals/apr_550e8400e29b41d4a716446655440000/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

List what is held

Approve or deny

​List what is held

​Approve or deny

List what is held

Approve or deny