Saltar al contenido principal

Primeros pasos

Empieza con la API de OrcaRail para aceptar pagos con criptomonedas mediante stablecoins como USDT y USDC.

Panel y app​

Desde el Panel de OrcaRail puedes registrarte, iniciar sesión, completar la configuración guiada de tu organización, crear claves de API y gestionar usuarios.

Las organizaciones son el espacio de trabajo de tu cuenta de OrcaRail. Tus pagos, claves de API, miembros del equipo y ajustes de facturación viven dentro de una organización.

UsoRuta
Iniciar sesión/sign-in
Registrarse/sign-up
Configuración guiadaRedirección tras iniciar sesión si la organización aún necesita configurarse
Claves de API/api-keys
Usuarios/users
Olvidé mi contraseña/forgot-password
Ajustes/settings
Panel principal/

Visión general​

OrcaRail ofrece una API y SDK estándar y fáciles de usar para aceptar pagos con criptomonedas. Con OrcaRail puedes:

  • Aceptar pagos con stablecoins de tus clientes
  • Crear payment intents que redirigen a los usuarios a una página de pago alojada
  • Recibir notificaciones de webhook de los eventos de pago
  • Gestionar tus claves de API y la autenticación

Crear una cuenta​

Para empezar con OrcaRail necesitas crear una cuenta.

Desde el panel​

  1. Regístrate — Abre Panel → Registrarse, introduce tu correo, contraseña y nombre, y envía el formulario.
  2. Confirma tu correo — Revisa tu bandeja de entrada y haz clic en el enlace de confirmación (o usa el endpoint de confirmación de la API que aparece más abajo).
  3. Inicia sesión — Abre Panel → Iniciar sesión e introduce tus credenciales; se te redirigirá al panel.
  4. Crea tu primera organización — Después de iniciar sesión, OrcaRail necesita una organización para que puedas continuar en el panel. Si tu cuenta aún no tiene una, se te redirige a la configuración guiada. Introduce el nombre de la organización, confirma o edita el slug generado y créala; pasarás a ser su propietario.
  5. Completa la configuración guiada — Elige un modo de venta, genera o edita productos y precios, crea tu primera clave de API y crea un widget. El panel permanece bloqueado hasta completar esos pasos obligatorios para esa organización.
  6. Copia tus credenciales de API — Durante la configuración guiada, copia de inmediato la key y el secret. El secret solo se muestra una vez y no se puede recuperar después.
  7. Equipo y usuarios (opcional) — Para invitar a miembros del equipo, usa Panel → Usuarios (invitación por correo y gestión de roles). Los miembros se invitan a tu organización.

Alternativa: mediante la API​

Endpoint de registro​

POST /api/v1/auth/email/register

Cuerpo de la solicitud:

{
  "email": "[email protected]",
  "password": "secure-password",
  "firstName": "John",
  "lastName": "Doe"
}

Respuesta: 204 No Content

Tras el registro recibirás un correo de confirmación. Haz clic en el enlace del correo para activar tu cuenta.

Confirmación del correo​

POST /api/v1/auth/email/confirm

Cuerpo de la solicitud:

{
  "hash": "confirmation-token-from-email"
}

:::tip Empieza en el sandbox Haz clic en Go to sandbox en el panel para obtener una copia de tu organización solo con testnets, claves ak_test_, USDC de prueba gratis y pagos simulados. Consulta Organizaciones sandbox. :::

Crear claves de API​

Una vez confirmada tu cuenta y creada tu primera organización, puedes crear claves de API para autenticar tus solicitudes. Lo más sencillo es hacerlo desde el panel: ve a Panel → API Keys, haz clic en Create API key, asigna un nombre (y opcionalmente una URL de webhook) y copia la key y el secret de inmediato.

Alternativa con la API: crear una clave de API​

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

Esto crea una clave de API para la organización identificada por :organizationId. El bearer token debe tener acceso a esa organización.

Cuerpo de la solicitud:

{
  "name": "Production API Key"
}

Respuesta:

{
  "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 Importante ¡Guarda tu secret de inmediato! Solo se muestra una vez y no se puede recuperar después. Si lo pierdes, tendrás que crear una nueva clave de API. :::

Alternativa con la API: listar tus claves de API​

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

Respuesta:

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

Alternativa con la API: revocar una clave de API​

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

Autenticación​

OrcaRail admite dos métodos de autenticación:

  1. Bearer Token (JWT) - Para solicitudes autenticadas por un usuario
  2. Clave de API (Basic Auth) - Para solicitudes de servidor a servidor

Uso de Bearer Tokens​

Primero, inicia sesión para obtener un JWT token:

POST /api/v1/auth/email/login

Cuerpo de la solicitud:

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

Respuesta:

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

Después usa el token en las siguientes solicitudes:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Uso de claves de API​

Para solicitudes de servidor a servidor, usa Basic Authentication con tu clave de API:

Authorization: Basic base64(key:secret)

Ejemplo con curl:

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

Usar el SDK de Node.js​

La forma más sencilla de integrar pagos es con el SDK oficial de Node.js. Instálalo desde npm:

npm install @orcarail/node

Después crea un cliente y usa Payment Intents, Pay y 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',
})

Consulta la guía del SDK de Node.js para la instalación completa, la configuración, los payment intents y la verificación de webhooks.

Usar el SDK de PHP​

Para aplicaciones PHP 8.1+, instala el SDK oficial con 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',
]);

Consulta la guía del SDK de PHP para la configuración, las suscripciones, las utilidades de catálogo y la verificación de webhooks.

Prueba la app de demostración​

Una app de demostración de código abierto muestra el flujo completo: crear el intent, redirigir a la página de pago, página de éxito y webhooks.

Clónala, configura tu clave y secret de API y ejecútala en local o despliégala en Vercel.

Próximos pasos​

Ahora que tienes una cuenta y claves de API, puedes: