Crear un Payment Intent

Crea un Payment Intent para empezar a cobrar un pago a un cliente.

Endpoint

POST /api/v1/payment_intents

La versión de la API va en la ruta de la URL (v1). No hay campo de versión en el cuerpo de la petición.

Versión de la API y SDK

Versión en la URL: la ruta base incluye la versión (por ejemplo /api/v1/payment_intents). La versión actual es v1. Cuando existan versiones nuevas, la ruta lo reflejará (por ejemplo /api/v2/payment_intents).
SDK de Node: el cliente acepta baseUrl (por defecto https://api.orcarail.com/api/v1) y apiVersion (por defecto "v1"). Para usar otra versión de la API, define baseUrl con la base versionada que quieras (por ejemplo https://api.orcarail.com/api/v2). Los parámetros de creación del Payment Intent no incluyen un campo de versión; el cliente usa la URL base. Consulta SDK de Node para la configuración completa.
SDK de PHP: el cliente acepta base_url (por defecto https://api.orcarail.com/api/v1). Apúntalo a otra base versionada para cambiar de versión de la API. Consulta SDK de PHP para la configuración completa.

Autenticación

Este endpoint admite ambos métodos de autenticación:

Token Bearer (JWT): Authorization: Bearer YOUR_JWT_TOKEN
Clave de API (Basic Auth): Authorization: Basic base64(key:secret)

Petición

Cuerpo de la petición

{
  "amount": "100.00",
  "currency": "usd",
  "payment_method_types": ["crypto"],
  "tokenId": 1,
  "networkId": 1,
  "return_url": "https://merchant.example.com/return",
  "cancel_url": "https://merchant.example.com/cancel",
  "description": "Payment for services",
  "metadata": {
    "order_id": "12345",
    "customer_id": "67890"
  },
  "expires_at": "2024-12-31T23:59:59Z",
  "withdrawal_addresses": { "evm": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb" }
}

Parámetros

Parámetro	Tipo	Obligatorio	Descripción
`amount`	string	Sí	El importe a cobrar, en la unidad más pequeña de la moneda (por ejemplo, céntimos para USD). Debe ser un número positivo.
`currency`	string	Sí	Código ISO de moneda de tres letras (por ejemplo `usd`, `eur`).
`payment_method_types`	array	Sí	Array de tipos de método de pago. Debe incluir `"crypto"`.
`tokenId`	number	Sí	El ID del token que se acepta (por ejemplo USDC, USDT).
`networkId`	number	Sí	El ID de la red blockchain (por ejemplo Ethereum, Polygon).
`return_url`	string	Sí	La URL a la que se redirige al cliente tras completar el pago.
`cancel_url`	string	No	La URL a la que se redirige al cliente si cancela el pago.
`description`	string	No	Una descripción opcional del pago.
`metadata`	object	No	Conjunto de pares clave-valor que puedes adjuntar al Payment Intent.
`expires_at`	string	No	Marca de tiempo ISO 8601 en la que caduca el Payment Intent.
`withdrawal_addresses`	object	No	Direcciones de retiro por tipo de cadena. Las claves deben ser tipos de cadena válidos: `evm`, `solana`, `bitcoin`, `tron`, `cosmos`, `polkadot`, `move`, `ton` (por ejemplo `{ "evm": "0x...", "solana": "..." }`). Si se omite o está vacío para una cadena, se usa el valor por defecto de tu cuenta en la configuración de retiros.

Respuesta

Respuesta correcta

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "amount": "100.00",
  "currency": "usd",
  "status": "requires_payment_method",
  "paymentMethodTypes": ["crypto"],
  "clientSecret": "550e8400-e29b-41d4-a716-446655440000_secret_abc123",
  "returnUrl": "https://merchant.example.com/return",
  "cancelUrl": "https://merchant.example.com/cancel",
  "description": "Payment for services",
  "metadata": {
    "order_id": "12345",
    "customer_id": "67890"
  },
  "paymentLink": {
    "id": 1,
    "link": "https://pay.orcarail.com/pay/pl_abc123"
  },
  "expiresAt": "2024-12-31T23:59:59.000Z",
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-01T00:00:00.000Z"
}

Campos de la respuesta

Campo	Tipo	Descripción
`id`	string	Identificador único del Payment Intent (por ejemplo `550e8400-e29b-41d4-a716-446655440000`).
`amount`	string	El importe a cobrar.
`currency`	string	El código de moneda.
`status`	string	Estado actual del Payment Intent.
`paymentMethodTypes`	array	Array de tipos de método de pago.
`clientSecret`	string	Importante: solo se muestra una vez. Úsalo para confirmar el Payment Intent.
`returnUrl`	string	La URL de retorno que indicaste.
`cancelUrl`	string	La URL de cancelación que indicaste (si la hay).
`description`	string	La descripción que proporcionaste (si la hay).
`metadata`	object	Los metadatos que proporcionaste (si los hay).
`paymentLink`	object	Contiene la URL de pago alojada en `link`.
`expiresAt`	string	Cuándo caduca el Payment Intent (si se indicó).
`createdAt`	string	Cuándo se creó el Payment Intent.
`updatedAt`	string	Cuándo se actualizó por última vez el Payment Intent.

Ejemplo

cURL

curl https://api.orcarail.com/api/v1/payment_intents \
  -X POST \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "100.00",
    "currency": "usd",
    "payment_method_types": ["crypto"],
    "tokenId": 1,
    "networkId": 1,
    "return_url": "https://merchant.example.com/return"
  }'

JavaScript (Node.js)

const response = await fetch(
  'https://api.orcarail.com/api/v1/payment_intents',
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${jwtToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      amount: '100.00',
      currency: 'usd',
      payment_method_types: ['crypto'],
      tokenId: 1,
      networkId: 1,
      return_url: 'https://merchant.example.com/return',
      description: 'Payment for services',
      metadata: {
        order_id: '12345',
      },
    }),
  }
)

const paymentIntent = await response.json()
console.log('Client Secret:', paymentIntent.clientSecret)
console.log('Payment Link:', paymentIntent.paymentLink.link)

Python

import requests

response = requests.post(
    'https://api.orcarail.com/api/v1/payment_intents',
    headers={
        'Authorization': f'Bearer {jwt_token}',
        'Content-Type': 'application/json',
    },
    json={
        'amount': '100.00',
        'currency': 'usd',
        'payment_method_types': ['crypto'],
        'tokenId': 1,
        'networkId': 1,
        'return_url': 'https://merchant.example.com/return',
        'description': 'Payment for services',
        'metadata': {
            'order_id': '12345',
        },
    },
)

payment_intent = response.json()
print(f"Client Secret: {payment_intent['clientSecret']}")
print(f"Payment Link: {payment_intent['paymentLink']['link']}")

PHP (SDK)

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://merchant.example.com/return',
    'description' => 'Payment for services',
    'metadata' => ['order_id' => '12345'],
]);

echo $intent->client_secret;
echo $intent->payment_link?->link;

payment_method_types vale ['crypto'] por defecto. Pasa price_id en lugar de los campos de importe para cobrar un precio del catálogo. Consulta SDK de PHP.

Próximos pasos

Después de crear un Payment Intent:

Confirma el Payment Intent: obtén la URL de redirección para tu cliente
Redirige al cliente a la app de pago alojada
Gestiona la llamada de vuelta a la URL de retorno

Endpoint​

Versión de la API y SDK​

Autenticación​

Petición​

Cuerpo de la petición​

Parámetros​

Respuesta​

Respuesta correcta​

Campos de la respuesta​

Ejemplo​

cURL​

JavaScript (Node.js)​

Python​

PHP (SDK)​

Próximos pasos​