Policy Engine v2: transaction status changes

Ripple is rolling out Policy Engine v2, which runs policy checks and transaction approvals in a single policy phase. Until now, a transaction that required approvals passed its policy checks first and then waited in a separate approval phase. With Policy Engine v2, the transaction stays in the policy phase until policy rules and any required approvals all complete.

This changes the sequence of status values that transactions emit. If you poll the transactions API or consume TRANSACTION webhooks, review the changes below and update any automation that depends on the approval statuses.

New transactions no longer transition through APPROVAL_CHECK_PENDING or APPROVAL_CHECK_PASSED. Instead, the transaction remains in POLICY_CHECK_PENDING while approvers act on it.

Both values remain valid members of the TransactionStatus enum. Clients that deserialize the enum keep working, and historical transactions keep the status history they already have. Transactions already in flight when Ripple enables Policy Engine v2 complete on the path they started, so they might still emit these statuses for a short time after the switch.

Ripple Custody (Wallet) still emits POLICY_CHECK_PASSED for every allowed transaction, but later in the lifecycle. It now means that the transaction passed policy evaluation and all required approvals, and compilation is about to start. Previously, Ripple Custody (Wallet) emitted it before any approval round started.

The status sequence for an allowed outbound transaction becomes:

REQUESTED → POLICY_CHECK_PENDING → POLICY_CHECK_PASSED → COMPILATION_PENDING → COMPILED → SIGNATURE_PENDING → SIGNED → PUBLISH_PENDING → PUBLISHED → CONFIRMATION_PENDING → CONFIRMED

When a policy rule, an approver, or an expired approval rejects a transaction during the policy phase, the transaction moves from POLICY_CHECK_PENDING to REJECTED. This is the same transition a policy rejection makes today.

Because approvals now happen inside the policy phase, a transaction can stay in POLICY_CHECK_PENDING for the full approval window, which can be hours or until the approval expires. Previously, this status typically lasted milliseconds. Review any timeout or alerting logic that depends on time spent in POLICY_CHECK_PENDING.

When the policy phase rejects a transaction, Ripple Custody (Wallet) adds a structured entry to the transaction's problems array that explains why. Each entry includes:

Read the problems entry rather than parsing the free-text reasons array. Transactions created before the rollout don't carry a policy-stamped problems entry, so treat its absence as no information rather than as an error.

• Approver experience. Ripple Custody (Wallet) still creates approval requests for transactions that require them. Approvers receive and action them in the web console and passkey flows exactly as before.
• Approvals API and approval webhooks. In-progress approval visibility, such as who has approved so far, stays in the approvals API and APPROVAL domain webhooks. An open approval request for a transaction means it's waiting on approvers while the transaction itself sits in POLICY_CHECK_PENDING.
• Webhook event types. There are no new TRANSACTION webhook events. Notifications for the two approval statuses stop arriving for new transactions because those transitions no longer happen.
• API schema. Ripple isn't removing any fields or enum values.
• Approval groups, quorums, and policy configuration. Your existing policies and approval groups continue to apply without changes.
• Terminal statuses. CONFIRMED, REJECTED, and FAILED behave exactly as today.

Before Ripple enables Policy Engine v2 in your environment:

1. Remove any state-machine logic that requires APPROVAL_CHECK_PENDING or APPROVAL_CHECK_PASSED to occur. Don't remove the values from your client-side enum definitions.
2. If your integration waits for APPROVAL_CHECK_PASSED before it treats a transaction as progressing, wait for POLICY_CHECK_PASSED or any later status instead.
3. If you interpret POLICY_CHECK_PASSED as "policy passed, approvals may still be pending," update that interpretation. After the change, it means the whole policy phase, including approvals, is complete.
4. If you treat APPROVAL_CHECK_PENDING as "awaiting approval," use POLICY_CHECK_PENDING together with the approvals API or APPROVAL webhooks to detect that state.
5. Adjust any timeout or alerting logic that depends on time spent in POLICY_CHECK_PENDING.
6. Optionally, read the structured problems entry on REJECTED transactions instead of the deprecated reasons array.

These changes apply equally to API polling and to TRANSACTION webhook consumers, because webhook notifications carry the same status values.

Every organization now has access to Policy Engine v2 in Sandbox and Production.

Until Ripple enables Policy Engine v2 in an environment, transactions there continue to emit the legacy status sequence, including APPROVAL_CHECK_PENDING and APPROVAL_CHECK_PASSED.

• How transactions work for the complete status reference
• Webhooks overview for TRANSACTION webhook payloads
• Approvals for how approval requests work
• Ripple Custody (Wallet) API for the transaction and approvals endpoints