Set up two or more payment gateways in Spreedly (e.g., primary Stripe gateway and backup Braintree gateway) and obtain gateway tokens for each.
Implement a routing layer in your application that attempts the transaction against the primary gateway token first using Spreedly's Purchase or Authorize API.
On receiving a gateway error response (network connectivity failure or gateway timeout — not a card decline), catch the error and resubmit the transaction to the backup gateway token using the same Spreedly payment method token.
Do NOT failover on hard card declines (do_not_honor, stolen_card, insufficient_funds) — these represent issuer decisions that will be the same regardless of which gateway submits the transaction.
Log the gateway token used, attempt sequence, and outcome for each transaction to enable per-gateway performance monitoring.
Use Spreedly's built-in metadata fields to store routing decisions alongside the transaction record for reconciliation.
Known gotchas
Failover on soft gateway errors risks double-charging if the original gateway processed the transaction but failed to return a response — use idempotency keys or check for existing authorizations before failing over.
Different gateways may return different error code vocabularies for the same underlying decline reason; normalize error codes to a common taxonomy before applying failover logic.
PCI scope expands if the failover gateway requires raw PAN transmission — use a vault provider (like Spreedly) that transmits tokens rather than PANs to each downstream gateway.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp