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​

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.price.getCurrencies({ active: true })
  • Fiat quote via orcarail.price.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​