Skip to main content

OrcaRail Demo App

A simple, open-source demo application that shows how to accept crypto payments with OrcaRail using the Node.js SDK and hosted pay.

Repository​

Live and sandbox demos​

The same demo runs twice: the live demo uses mainnet networks and tokens, and the sandbox demo uses testnets with free test tokens. The mode comes from the API key (ak_test_ means sandbox). The sandbox demo shows a blinking Testnet light and links to the live demo, and the live demo links back to the testnet demo. On the sandbox demo you can finish checkout with Simulate payment, no wallet needed.

Features​

  • Split and get your commission — Use an API key with a commission % to earn a share of every payment; commission is shown at checkout and sent to your withdrawal address
  • "Pay with Crypto" button and product card
  • Create and confirm Payment Intent via Node.js SDK (@orcarail/node)
  • Currency selector populated with orcarail.rates.getCurrencies({ active: true })
  • Fiat quote via orcarail.rates.getFiatQuote({ amount, currency }) for the quote box
  • Redirect to OrcaRail hosted pay
  • Success page with payment status
  • Webhook endpoint for payment events (with signature verification)
  • Ready for Vercel deployment

Tech Stack​

  • Framework: Next.js (App Router)
  • SDK: @orcarail/node
  • Styling: Tailwind CSS

Quick Start​

  1. Clone the repo

    git clone https://github.com/OrcaRail/demo.git
    cd demo

  2. Install dependencies

    npm install

  3. Configure environment

    Copy .env.local.example to .env.local and set:

    • ORCARAIL_API_KEY – Your API key (e.g., ak_live_xxx)
    • ORCARAIL_API_SECRET – Your API secret (e.g., sk_live_xxx)
    • ORCARAIL_WEBHOOK_SECRET – Optional; for webhook signature verification
    • NEXT_PUBLIC_APP_URL – Your app URL (e.g., http://localhost:3001)

    Token and network are chosen in the demo UI (or sent in the request body to /api/pay). You can optionally send withdrawal_address in the body to override where funds are withdrawn for that payment.

    For local development with a local API:

    • ORCARAIL_API_BASE_URL – e.g., http://127.0.0.1:3000/api/v1

  4. Run the demo

    npm run dev

    Open the app (default: http://localhost:3001), click "Pay with Crypto", and complete the flow on the hosted pay app.

Flow​

  1. User clicks "Pay with Crypto" → frontend calls /api/pay.
  2. Backend uses the SDK to create and confirm a Payment Intent.
  3. User is redirected to OrcaRail hosted pay.
  4. User completes payment on-chain.
  5. User is redirected to the success page; the app calls /api/complete and /api/status to mark the intent as processing and show status.
  6. Your webhook at /api/webhooks receives events such as payment_intent.completed and payment_intent.processing.

Webhooks​

The demo includes a webhook route at /api/webhooks that:

  • Verifies the x-webhook-signature header using your webhook secret
  • Handles events: payment_intent.completed, payment_intent.processing, payment_intent.canceled, payment_intent.requires_payment_method, payment_intent.requires_confirmation

Configure your webhook URL in the OrcaRail dashboard (e.g., https://your-app.vercel.app/api/webhooks).

Deploy to Vercel​

  1. Push the demo to your GitHub and import the project in Vercel.
  2. Add the same environment variables in the Vercel project settings.
  3. Set NEXT_PUBLIC_APP_URL to your Vercel URL.
  4. Deploy. Vercel will detect Next.js and set up the build.

See Also​