Skip to main content

Getting Started

Get started with OrcaRail API to accept crypto payments with stablecoins.

Dashboard & App​

You can sign up, sign in, complete guided setup for your organization, create API keys, and manage users from the OrcaRail Dashboard.

Organizations are the workspace for your OrcaRail account. Your payments, API keys, team members, and billing settings all live inside an organization.

PurposePath
Sign in/sign-in
Sign up/sign-up
Guided setupRedirected after sign-in if an organization still needs setup
API Keys/api-keys
Users/users
Forgot password/forgot-password
Settings/settings
Main dashboard/

Overview​

OrcaRail provides a standard, developer-friendly API and SDKs for accepting crypto payments. With OrcaRail, you can:

  • Accept stablecoin payments from your customers
  • Create payment intents that redirect users to a hosted pay app
  • Receive webhook notifications for payment events
  • Manage your API keys and authentication

Create an Account​

To get started with OrcaRail, you need to create an account.

From the Dashboard​

  1. Sign up — Open Dashboard → Sign up and enter your email, or continue with Google.
  2. Verify your email — Enter the 6-digit code sent to your inbox. Your account is created only after the email is verified, and you are signed in.
  3. Sign in later — Open Dashboard → Sign in and use an email code, Google, or a password once you have set one.
  4. Create your first organization — After you sign in, OrcaRail requires an organization before you can continue in the dashboard. If your account does not have one yet, you are redirected to guided setup. Enter the organization name, confirm or edit the generated slug, and create the organization; you become the owner.
  5. Complete guided setup — Pick a selling mode, generate or edit products and pricing, create your first API key, and create a widget. The dashboard stays locked until those required steps are complete for that organization.
  6. Copy your API credentials — During guided setup, copy the key and secret immediately. The secret is shown only once and cannot be retrieved later.
  7. Team & users (optional) — To invite team members, use Dashboard → Users (invite by email, manage roles). Team members are invited into your organization.

Alternatively, via API​

Sign up with an email code​

Request a code (rate limited, protected by reCAPTCHA):

POST /api/v1/auth/email/register/send-code
{ "email": "[email protected]" }

Then verify it. The account is created at this step and the response contains your tokens:

POST /api/v1/auth/email/register/verify-code
{ "email": "[email protected]", "code": "123456" }

Disposable (throwaway) email addresses cannot be used to create an account.

:::tip Start in the sandbox Click Go to sandbox in the dashboard to get a testnet-only copy of your organization with ak_test_ keys, free test USDC and simulated payments. See Sandbox organizations. :::

Create API Keys​

Once your account is confirmed and your first organization is created, you can create API keys to authenticate your requests. The easiest way is from the dashboard: go to Dashboard → API Keys, click Create API key, set a name (and optional webhook URL), and copy the key and secret immediately.

Alternatively, via API — Create an API Key​

POST /api/v1/organizations/:organizationId/api-keys
Authorization: Bearer YOUR_JWT_TOKEN

This creates an API key for the organization identified by :organizationId. The bearer token must have access to that organization.

Request Body:

{
  "name": "Production API Key"
}

Response:

{
  "apiKey": {
    "id": 1,
    "name": "Production API Key",
    "keyPrefix": "ak_live_",
    "status": "active",
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z"
  },
  "key": "ak_live_abc123def456",
  "secret": "sk_live_xyz789uvw012"
}

:::warning Important Save your secret immediately! It's only shown once and cannot be retrieved later. If you lose it, you'll need to create a new API key. :::

Alternatively, via API — List Your API Keys​

GET /api/v1/organizations/:organizationId/api-keys
Authorization: Bearer YOUR_JWT_TOKEN

Response:

[
  {
    "id": 1,
    "name": "Production API Key",
    "keyPrefix": "ak_live_",
    "status": "active",
    "createdAt": "2024-01-01T00:00:00.000Z"
  }
]

Alternatively, via API — Revoke an API Key​

POST /api/v1/api-keys/:id/revoke
Authorization: Bearer YOUR_JWT_TOKEN

Authentication​

OrcaRail supports two authentication methods:

  1. Bearer Token (JWT) - For user-authenticated requests
  2. API Key (Basic Auth) - For server-to-server requests

Using Bearer Tokens​

First, log in to get a JWT token:

POST /api/v1/auth/email/login

Request Body:

{
  "email": "[email protected]",
  "password": "secure-password"
}

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "refresh_token_here",
  "tokenExpires": 3600,
  "user": {
    "id": 1,
    "email": "[email protected]"
  }
}

Then use the token in subsequent requests:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Using API Keys​

For server-to-server requests, use Basic Authentication with your API key:

Authorization: Basic base64(key:secret)

Example with curl:

curl https://api.orcarail.com/api/v1/payment_intents \
  -u ak_live_abc123def456:sk_live_xyz789uvw012

Use the Node.js SDK​

The easiest way to integrate payments is with the official Node.js SDK. Install it from npm:

npm install @orcarail/node

Then create a client and use Payment Intents, Pay, and Webhooks:

const OrcaRail = require('@orcarail/node').default
const orcarail = new OrcaRail(
  process.env.ORCARAIL_API_KEY,
  process.env.ORCARAIL_API_SECRET
)

const intent = await orcarail.paymentIntents.create({
  amount: '100.00',
  currency: 'usd',
  payment_method_types: ['crypto'],
  tokenId: 1,
  networkId: 1,
  return_url: 'https://yourapp.com/success',
})

See the Node.js SDK guide for full installation, configuration, payment intents, and webhook verification.

Use the PHP SDK​

For PHP 8.1+ applications, install the official SDK with Composer:

composer require orcarail/orcarail-php
use OrcaRail\OrcaRailClient;

$orcarail = new OrcaRailClient([
    'api_key' => getenv('ORCARAIL_API_KEY'),
    'api_secret' => getenv('ORCARAIL_API_SECRET'),
]);

$intent = $orcarail->paymentIntents->create([
    'amount' => '100.00',
    'currency' => 'usd',
    'tokenId' => $tokenId,     // token UUID
    'networkId' => $networkId, // network UUID
    'return_url' => 'https://yourapp.com/success',
]);

See the PHP SDK guide for configuration, subscriptions, catalog helpers, and webhook verification.

Try the Demo App​

An open-source demo app shows a complete flow: create intent, redirect to hosted pay, success page, and webhooks.

Clone, set your API key and secret, and run locally or deploy to Vercel.

Next Steps​

Now that you have an account and API keys set up, you can: