Reason codes

Every decision carries reason codes from a fixed registry. There is no free text. A code you see on a payout, a change, a case or a trace means exactly what this page says.

Gate decisions

The six words: ALLOW, STEP_UP, HOLD, REROUTE, REVIEW, DENY. When two policies disagree, the strictest wins in that order.

Trust: beneficiaries and payouts

Code	Meaning
NEW_BENEFICIARY	This destination has never received a successful payout here.
BENEFICIARY_ACCOUNT_CHANGED_RECENTLY	The destination was changed recently.
BENEFICIARY_CHANGE_VELOCITY_HIGH	Changed more often than usual.
BENEFICIARY_NAME_MISMATCH	The account holder's name does not match the record.
BENEFICIARY_UNVERIFIED	The destination has not been verified.
COOLING_OFF_ACTIVE / COOLING_OFF_SATISFIED	A change is inside its window, or the window has elapsed.
SELLER_UNVERIFIED / SELLER_NEW / SELLER_RESTRICTED / SELLER_HISTORY_CLEAN	Seller signals.
PAYOUT_AMOUNT_ABOVE_BASELINE	Much larger than this seller's usual payout.
PAYOUT_AMOUNT_ABOVE_THRESHOLD	Above the amount that needs human approval.
FULFILLMENT_EVIDENCE_SUFFICIENT / _MISSING / _TIER_TOO_LOW	State of delivery evidence.
FULFILLMENT_REVERSED	A delivery record was later cancelled.
OPEN_CASE_ON_SUBJECT / OPEN_DISPUTE_ON_ORDER	Blocking open work.
ATO_SESSION_RULE	The requester changed credentials inside the takeover window.
DUAL_APPROVAL_REQUIRED / STEP_UP_REQUIRED / MANUAL_REVIEW_REQUESTED	Control requirements.
POLICY_DEFAULT	No rule matched; the defaults decided.

Routing: why a connection was excluded

Code	The filter that stopped it
ROUTE_CONNECTION_NOT_ACTIVE	Contracted: not active or not dispatchable.
ROUTE_ENVIRONMENT_MISMATCH	Environment.
ROUTE_METHOD_UNSUPPORTED	Method.
ROUTE_CURRENCY_UNSUPPORTED	Currency.
ROUTE_OPERATION_UNSUPPORTED	Operation (for example manual capture on PayNow).
ROUTE_AMOUNT_OUT_OF_RANGE	Amount.
ROUTE_CIRCUIT_OPEN / ROUTE_UNHEALTHY	Health.
ROUTE_RISK_BLOCKED	Risk: the Gate routed away from it.
ROUTE_RETRY_POLICY_BLOCKED	Retry: already tried for this payment.

Routing: why the winner won

Code	Meaning
ROUTE_ONLY_CANDIDATE	One connection survived every filter.
ROUTE_SCORE_WINNER	Several were eligible in the same health class; this one scored highest.
ROUTE_HEALTH_WINNER	A healthy connection was preferred over an impaired one before any score was compared.
NO_ELIGIBLE_ROUTE	Nothing survived.
ROUTE_FAILOVER_PRE_COLLECTION	A re-route after a pre-send technical failure, before any card was collected.
ROUTE_SAME_PROVIDER_RETRY	A retry after a soft decline.

Credentials

Code	Meaning
LIVE_KEY_IN_TEST_ENVIRONMENT	A live-shaped key in Test.
TEST_KEY_IN_LIVE_ENVIRONMENT	A test key in Live.
SECRET_KEY_NOT_ALLOWED_USE_RESTRICTED	A Stripe sk_ key. Use a restricted key.
KEY_PREFIX_UNRECOGNIZED	Not a credential shape this provider uses.
PROVIDER_AUTH_FAILED	The provider rejected it.
PROVIDER_SCOPE_INSUFFICIENT	It lacks the permissions the platform needs.
WEBHOOK_REGISTRATION_SCOPE_MISSING	Stripe: no Webhook Endpoints: Write. Stored DEGRADED.

Outcomes

Code	Meaning
PROVIDER_TIMEOUT / PROVIDER_RATE_LIMITED / PROVIDER_5XX	Transient provider failures.
OUTCOME_RESOLVED_BY_QUERY / OUTCOME_RESOLVED_BY_WEBHOOK	How an unknown outcome was settled.
OUTCOME_UNRESOLVED_ESCALATED	The query budget ran out; manual review.
PROVIDER_AMOUNT_MISMATCH / DUPLICATE_CHARGE_SUSPECTED	Observation conflicts.
PAID_THEN_FAILED_CONFLICT	A payout reported paid, then failed.
PEHMEN_ENTITLEMENT_REVOKED / LIVE_DAILY_CAP_EXCEEDED	Live gate refusals.

Normalized decline codes (on attempts)

Soft (one retry): INSUFFICIENT_FUNDS, ISSUER_UNAVAILABLE, PROCESSING_ERROR, TRY_AGAIN_LATER, VELOCITY_LIMIT. Hard (never retried): GENERIC_DECLINE, STOLEN_LOST_CARD, FRAUD_SUSPECTED, INVALID_CARD, EXPIRED_CARD, CURRENCY_UNSUPPORTED, AMOUNT_INVALID, DUPLICATE_TRANSACTION. Authentication: AUTHENTICATION_REQUIRED, AUTHENTICATION_FAILED. Technical: CONNECTION_FAILED_PRE_SEND, TIMEOUT, RATE_LIMITED, PROVIDER_5XX, CREDENTIAL_REVOKED, CONFIGURATION_ERROR. PayNow: QR_EXPIRED, PAYMENT_WINDOW_EXPIRED.

The provider's own code is always kept beside the normalized one.