Guides

Payment Controls

Composable rules attached to templates that execute at fixed points in the transaction lifecycle: time delays, verification, screening, and limits.

Last updated 2026-07-16View as Markdown

Controls are the core primitive of the Coinbax platform: composable rules that attach to a template and execute automatically at fixed points in the transaction lifecycle. A time delay before release, an SMS verification before escrow, a sanctions screen on both parties, an amount limit per transaction: each is a control, and a template composes them into a payment policy that every transaction inherits.

How controls execute

Every control declares an execution phase, which pins it to a point in the Coinbax Execution Framework:

Phase When it runs Typical controls
PRE_ESCROW Before any funds move (Verify) Compliance screening, sanctions checks, 2FA and SMS verification, amount limits
POST_ESCROW After funds lock in escrow (Fund) Time delays, ongoing transaction monitoring
PRE_RELEASE Immediately before funds release (Confirm) Final risk validation before settlement

Within a phase, controls run in their declared executionOrder. A required control that fails stops the transaction: a PRE_ESCROW failure means no funds ever move, and a PRE_RELEASE failure blocks the release while funds are still recoverable in escrow.

Every execution is recorded on the transaction. Each result captures the control type, phase, outcome, duration, and any data it produced (a computed release timestamp, a risk score), giving you a complete audit trail per payment.

Control types

Time delays

Holds escrowed funds for a configured period before auto-release, from one minute up to 30 days. The control computes a release timestamp at POST_ESCROW; a background job releases the escrow once the timestamp passes and all PRE_RELEASE controls succeed.

{
  "type": "TimeDelay",
  "executionPhase": "POST_ESCROW",
  "config": { "delayMinutes": 5, "autoRelease": true }
}

The delay is the recall window: refunds, rescinds, and disputes all operate against funds that are committed but not yet released.

Verification (2FA and SMS)

Requires a party to confirm the payment with a one-time code before escrow. The transaction pauses in an awaiting-verification state until the code is submitted; codes expire and can be resent. Verification happens either through your own UI (POST /controls/verify-2fa or POST /controls/verify-twilio-sms with the transaction ID and code) or through the hosted verification link Coinbax sends by SMS.

{
  "type": "TwilioSMS",
  "executionPhase": "PRE_ESCROW",
  "config": { "requiredFor": ["sender"], "codeExpiration": 5 }
}

Compliance screening

Screens wallet addresses, customers, and transactions against risk and sanctions data before funds move. Screening controls take a risk threshold (0 to 100) and can be configured to fail the transaction outright when the threshold is exceeded, or to flag it for review.

{
  "type": "ComplianceCheck",
  "executionPhase": "PRE_ESCROW",
  "config": { "riskThreshold": 70, "checkBothParties": true, "failOnHighRisk": true }
}

Transaction monitoring variants register the payment at POST_ESCROW and re-validate at PRE_RELEASE, so a risk signal that emerges during the escrow window still blocks settlement.

Amount limits

Caps the value of a single transaction under the template. Runs at PRE_ESCROW, so an over-limit payment is rejected before any funds move.

Templates carry controls

You do not attach controls to individual transactions. Controls live on templates: versioned, reusable payment policies managed in your workspace. A template declares its controls, their configuration, their phases, and their order.

When you create a transaction with a templateId, the transaction inherits the template’s controls exactly as published:

curl -X POST https://api-staging.coinbax.com/api/v1/transactions \
  -H "X-API-Key: $COINBAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fromAddress": "0x...",
    "toAddress": "0x...",
    "amount": 250,
    "orchestrationType": "coinbax",
    "templateId": "<template-id>"
  }'

Templates are semantically versioned, and every version change is tracked. Because the transaction records which template and version it ran under, plus the result of every control execution, you can answer “what policy governed this payment” for any transaction, ever.

Design principles

  • Composable. Each control is independent. A template stacks as many as the payment policy needs.
  • Deterministic. Controls run at declared phases in declared order. There are no side channels around them.
  • Fail-safe. Required controls block the transaction when they fail or when their upstream data source is unreachable. Uncertainty resolves toward not moving money.
  • Auditable. Every execution is logged with its outcome and timing on the transaction record.

Next steps