Skip to main content

Payment Intents Overview

Payment Intents are the primary way to accept crypto payments with OrcaRail. They provide a secure, flexible way to collect payments from your customers.

What are Payment Intents?​

A Payment Intent represents your intent to collect payment from a customer. It tracks the payment's lifecycle from creation through completion.

The Payment Intent flow uses a familiar create–confirm–redirect pattern for stablecoin payments:

  1. Create a PaymentIntent to receive a client_secret
  2. Confirm the intent to receive a next_action.redirect_to_url.url
  3. Redirect the user to the hosted pay app
  4. After payment confirmation, the user is redirected to your return_url with query params

Payment Intent Statuses​

Payment Intents go through several statuses during their lifecycle:

  • requires_payment_method - The PaymentIntent has been created, but no payment method has been attached yet
  • requires_confirmation - The PaymentIntent has a payment method attached, but needs to be confirmed
  • processing - The PaymentIntent is being processed
  • succeeded - The PaymentIntent has succeeded and payment has been processed
  • canceled - The PaymentIntent was canceled

Supported Payment Methods​

Currently, OrcaRail supports:

  • Crypto - Stablecoin payments (USDC, USDT, etc.)

Supported Networks​

OrcaRail supports payments on multiple blockchain networks. You'll need to specify both a tokenId and networkId when creating a Payment Intent.

Common networks include:

  • Ethereum
  • Polygon
  • Base
  • Arbitrum

For the full picture on supported networks and currencies (powered by Relay and updated automatically), see our blog: Supported Networks and Currencies.

Payment Flow​

Key Concepts​

Client Secret​

The client_secret is a unique identifier for a Payment Intent. It's used to confirm the Payment Intent and should be kept secure. It's only shown once when the Payment Intent is created.

Return URL​

The return_url is where customers are redirected after completing or canceling a payment. You should handle both success and failure cases on this page.

Metadata​

You can attach custom metadata to Payment Intents. This is useful for storing additional information about the payment, such as order IDs or customer information.

Withdrawal address​

When creating or updating a Payment Intent, you can optionally set withdrawal_addresses (key-value object: chain type to address, e.g. { "evm": "0x...", "solana": "..." }). If set for a chain type, funds are withdrawn to that address when auto-withdrawal runs. If omitted or empty for a chain, your account's default from Withdrawal Settings for that chain type is used.

Fees and minimums​

Hosted usage: see Hosted platform pricing for per-transaction pricing and the free tier on cloud OrcaRail.

Per payment (quote): payments can include a support fee, commission (from your API key), and a bridge fee when the payer uses a different token or network. Amounts are also subject to payment minimums and optional withdrawal minimums. For full details, see Fees & limits.

Next Steps​