apr_*) holds a payment or other money movement that broke one of your limits. Nothing moves until it’s approved. To learn more, see Approve or deny a held payment.
Example
GET /approvals/{approvalId}
{
"data": {
"relationships": {
"initiatorAgent": {
"data": {
"type": "agent",
"id": "agt_019cd1798d637a4da75dce386343931d"
}
}
},
"type": "approval",
"id": "apr_019cd1798d8a74dd75c16fc6d843db81",
"attributes": {
"status": "pending",
"target": {
"type": "payment",
"id": "pay_019cd1798d794c2f2ccf31b4e8394f2d"
},
"payment": {
"amount": 500000,
"currency": "USD"
},
"fee": {
"amount": 100,
"currency": "USD",
"payer": "sender",
"applied": "on_top"
},
"reasons": [
{
"type": "limitExceeded",
"limitType": "perTransactionAmount",
"limitAmount": 250000,
"actualAmount": 500000,
"currency": "USD"
}
],
"customer": null,
"ach": null,
"realtime": null,
"wire": null,
"check": null,
"denialReason": null,
"createdAt": "2026-01-04T15:30:00.000Z",
"updatedAt": "2026-01-04T15:30:00.000Z",
"resolvedAt": null
}
}
}
data. The field names below are relative to it: attributes.status is data.attributes.status in the response.
Fields
The approval’s details.
Hide attributes
Hide attributes
Approval status. One of:
pending, approved, denied, canceled. See Statuses.Operation that needs approval.
Hide target
Hide target
Fee the sender pays on top of
payment.amount. Before the operation is submitted, including just after approval, a quote at the price in effect when it was created. After, the same fee the operation’s own resource reports. Null when no fee applies, including denied or canceled approvals, operations that ended before submission, and operations whose own resource hides the fee. Also null when Billing can’t quote the fee at read time; the fee still applies when the operation is submitted.Reasons this approval is under review.
Hide reasons
Hide reasons
Type of limit that was exceeded. One of:
perTransactionAmount, dailyAmount, monthlyAmount.ACH-specific review context. Null unless the target is an ACH.
Hide ach
Hide ach
Description for the sender’s internal reference, or null. Never shared with the counterparty or the banking network.
RFC 3339 timestamp when the funds are expected to be available, or null when unknown.
Counterparty and masked account, or null when it can no longer be resolved.
Hide counterparty
Hide counterparty
Wire-specific review context. Null unless the target is a wire.
Hide wire
Hide wire
Description for the sender’s internal reference, or null. Never shared with the counterparty or the banking network.
Destination party and masked account, or null when it can no longer be resolved.
Hide counterparty
Hide counterparty
Check-specific review context. Null unless the target is a check.
Hide check
Hide check
Realtime-specific review context. Null unless the target is a realtime payment.
Hide realtime
Hide realtime
Description for the sender’s internal reference, or null. Never shared with the counterparty or the banking network.
Destination party and masked account, or null when it can no longer be resolved.
Hide counterparty
Hide counterparty
Statuses
| Status | Meaning | Can become |
|---|---|---|
pending | Waiting for an approver. The operation it holds doesn’t move while it’s pending. | approved, denied, canceled |
approved | An approver released the hold. Natural checks the operation again before it is sent: it can still need another limit owner’s approval, or be canceled or denied. | canceled |
denied | An approver or Natural’s policy refused the operation, which ends as APPROVAL_DENIED without moving money. denialReason holds the approver’s reason, when one was given. | Final |
canceled | The operation was canceled while it was held, or could no longer run after it was approved, for example because a permission it relied on was removed. | Final |
Who resolves an approval
An approval belongs to the party that owns the limit it breached, and only that party sees it. A hold from your party’s limits or your agents’ limits is yours; a hold from a limit a customer set on their connection with your agent is that customer’s. Owners, admins and API keys withpayments.create can approve or deny; agents can’t.
Events
approval.required: A customer approval is required before the payment can continue.approval.approved: A customer approval was approved.approval.denied: A customer approval was denied.approval.canceled: A customer approval was canceled before completion.