Payment Routing

How Decal routes payments to the right destination — destination types, default behavior, and overrides for multi-location and multi-entity merchants.

Payment destinations

A payment destination is the target where Decal routes settled funds when a customer pays. Every order has exactly one resolved payment destination, determined by your routing configuration.

Today, all payment destinations are wallets — either a Decal-managed orchestration wallet or a settlement wallet you own. The destination concept is intentionally broader to accommodate future settlement targets.

Settlement wallets

Settlement wallets are wallets you own and control externally to the Decal platform. They are the final destination for your funds — where your revenue ends up. You add them in the dashboard by connecting and verifying them.

Manage wallets: Dashboard > Finances > Settlement Wallets

Each wallet gets a typed ID (e.g., sw_live_abc123) that you can pass as a paymentDestination value in API requests. You can add multiple wallets and assign them to different locations or use them for per-order overrides.

Requirements for a settlement wallet to receive payments:

Verified (e.g. signed the ownership challenge)
Active (not disabled or deleted)
Belongs to your organization
Mode matches your API key (sw_live_ for live, sw_test_ for test)

Orchestration wallets

Orchestration wallets are platform-managed MPC wallets that Decal provisions automatically for your organization. They serve as the default payment destination — a secure intermediary between your customers and your settlement wallets.

You don't create or manage orchestration wallets directly. Decal handles provisioning, key management, and security.

Why orchestration wallets are the default:

Fee handling — platform fees are calculated and deducted before settlement
Yield — funds held in orchestration earn yield while awaiting payout
Compliance — provides an auditable payment receipt layer
Security — MPC key management means no single point of compromise

Funds flow from orchestration wallets to your settlement wallets automatically based on your payout schedule or manual payout requests.

How routing works

When a customer pays through Decal — whether by stablecoin, card, or stored value — the platform resolves the payment destination for the order. This happens automatically based on your configuration, with sensible defaults and optional overrides for advanced use cases.

Payment routing decides where settled funds land. It is separate from Smart Payments, which decides which stablecoins the customer pays with. Smart Payments runs first on the customer side; payment routing runs after, on the merchant side.

Default behavior

By default, all payments are routed to your orchestration wallet — Decal's managed MPC wallet for your organization. Funds are then settled to your settlement wallet based on your payout schedule.

Customer  ───── pays ─────  Orchestration Wallet  ───── payout ─────  Your Settlement Wallet
                             (default destination)                     (your wallet)

This two-step flow gives you:

Automatic fee handling — fees are calculated before settlement
Yield optimization — funds in orchestration earn yield while awaiting settlement
Clean accounting — each payout is a discrete, auditable settlement event

No configuration is required. Once your organization is set up, payments route automatically.

Overrides

For merchants who need more control over where funds land, Decal supports overrides at two levels. Overrides bypass the orchestration wallet and send funds directly to the specified settlement wallet.

Per-order override

Specify a paymentDestination when creating an order or checkout session via the API. This is the highest priority — it overrides everything else.

curl -X POST https://api.usedecal.com/v0/checkout/sessions \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [{ "name": "Event Ticket", "quantity": 1, "unitPrice": 5000 }],
    "paymentDestination": "sw_live_abc1234567890",
    "successUrl": "https://yoursite.com/confirmed?session={SESSION_ID}"
  }'

Customer  ───── pays ─────  Settlement Wallet (specified in API request)

You can pass either:

A settlement wallet ID from your dashboard: sw_live_abc1234567890
A Solana address of one of your verified wallets: 7xKXtg2Cw87d97TXJSDpbD...

When to use this: Multi-entity operations, franchise routing, partner payouts, treasury segregation.

Important: The paymentDestination can only be set when the order or session is created. It cannot be changed after creation. This is a security measure — once a checkout URL has been shared with a customer, the payment destination is locked to prevent funds from being redirected mid-transaction.

Per-location override

Assign a settlement wallet to a location in your dashboard. All orders at that location automatically route to the assigned wallet — no API changes needed.

Customer at Location A  ───── pays ─────  Wallet assigned to Location A
Customer at Location B  ───── pays ─────  Wallet assigned to Location B

Configure this via Dashboard > Locations > [Location] > Settings > Settlement Wallet.

When to use this: Multi-location businesses that want per-store fund separation.

Priority order

When multiple overrides could apply, Decal uses this priority (highest first):

Priority	Override	How to set it
0	Order override	`paymentDestination` field in API request
1	Location override	Dashboard: location settings
2	Default	Orchestration wallet (automatic, no config)

If an order has both a paymentDestination and a location with an assigned wallet, the paymentDestination wins.

Payment methods

All payment methods use the same routing logic:

Method	How funds move
Stablecoins	USDC transferred on Solana to the resolved destination
Card	Card charged via processor, settled as USDC to the resolved destination
Stored value spend	No fund movement — balance tokens are burned from the customer's balance

Stored value top-ups

When a customer purchases stored value balance (via stablecoin, card, etc), the payment follows the same routing rules above. After the payment confirms, "balance tokens" are minted to the customer's Stored Value balance account separately.

                                     ┌─── payment ───  Resolved Destination (same routing as above)
Customer  ───── buys balance ────────┤
                                     └─── tokens ────  Customer's Stored Value Account (minted)

Stored value redemptions

When a customer spends their stored value balance, balance tokens are burned from their account. No funds move to any destination — the burn reduces the outstanding token supply, which directly tracks the stored value program's liability for unredeemed balances.

Coming soon

Per-location orchestration wallets

Today, each organization has a single orchestration wallet. We're adding support for per-location orchestration wallets, giving you on-chain fund segregation between locations. Customers at different locations will see different destination addresses, adding a layer of financial privacy.

Customer at Location A  ─── pays ───  Location A Orchestration Wallet  ─── payout ───  Your Wallet
Customer at Location B  ─── pays ───  Location B Orchestration Wallet  ─── payout ───  Your Wallet

Orchestration wallet overrides via API

The paymentDestination field will be extended to accept orchestration wallet IDs (ow_live_xyz789), letting you route specific orders through dedicated orchestration wallets for maximum fund segregation.

Payment Routing

On this page