Referencia de la API de Payment Intents

Referencia completa de los endpoints de la API de Payment Intents.

URL base

https://api.orcarail.com/api/v1

La versión de la API va en la ruta (v1). Para usar otra versión, usa la URL base correspondiente (por ejemplo https://api.orcarail.com/api/v2). El SDK de Node usa baseUrl y apiVersion en la configuración; consulta SDK de Node.

Crear un Payment Intent

Crea un nuevo Payment Intent.

POST /payment_intents

Autenticación

• Token Bearer (JWT) o clave de API (Basic Auth)

Cuerpo de la petición

Parámetro	Tipo	Obligatorio	Descripción
amount	string	Sí	Importe a cobrar (por ejemplo "100.00")
currency	string	Sí	Código de moneda (por ejemplo "usd")
payment_method_types	array	Sí	Debe incluir "crypto"
tokenId	number	Sí	ID del token (por ejemplo USDC, USDT)
networkId	number	Sí	ID de la red (por ejemplo Ethereum, Polygon)
return_url	string	Sí	URL de retorno tras el pago
cancel_url	string	No	URL de cancelación
description	string	No	Descripción del pago
metadata	object	No	Metadatos personalizados
expires_at	string	No	Marca de tiempo de caducidad ISO 8601
withdrawal_addresses	object	No	Direcciones de retiro por tipo de cadena. Claves: tipos de cadena válidos (evm, solana, bitcoin, tron, cosmos, polkadot, move, ton). Omítelo o déjalo vacío para una cadena para usar el valor por defecto de tu cuenta en la configuración de retiros.

Respuesta

{
  "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",
  "paymentLink": {
    "id": 1,
    "link": "https://pay.orcarail.com/pay/pl_abc123"
  },
  "createdAt": "2024-01-01T00:00:00.000Z"
}

Obtener un Payment Intent

Obtén los detalles de un Payment Intent.

GET /payment_intents/:id

Autenticación

• Token Bearer (JWT) o clave de API (Basic Auth)

Parámetros de ruta

Parámetro	Tipo	Obligatorio	Descripción
id	string	Sí	ID del Payment Intent (por ejemplo 550e8400-e29b-41d4-a716-446655440000)

Respuesta

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "amount": "100.00",
  "currency": "usd",
  "status": "succeeded",
  "paymentMethodTypes": ["crypto"],
  "latestTransaction": {
    "id": "txn_1234567890",
    "status": "completed",
    "hash": "0x1234567890abcdef...",
    "amount": "100.00"
  },
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-01T00:00:00.000Z"
}

Confirmar un Payment Intent

Confirma un Payment Intent para obtener la URL de redirección.

POST /payment_intents/:id/confirm

Autenticación

• Token Bearer (JWT) o clave de API (Basic Auth)

Parámetros de ruta

Parámetro	Tipo	Obligatorio	Descripción
id	string	Sí	ID del Payment Intent

Cuerpo de la petición

Parámetro	Tipo	Obligatorio	Descripción
client_secret	string	Sí	Client secret del Payment Intent
return_url	string	No	Sustituye la URL de retorno
payment_method_data	object	No	Datos del método de pago

Respuesta

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "requires_confirmation",
  "nextAction": {
    "type": "redirect_to_url",
    "redirectToUrl": {
      "url": "https://pay.orcarail.com/pay/pl_abc123?payment_intent=550e8400-e29b-41d4-a716-446655440000&payment_intent_client_secret=550e8400-e29b-41d4-a716-446655440000_secret_abc123"
    }
  }
}

Cancelar un Payment Intent

Cancela un Payment Intent. Una vez cancelado, no se puede usar para pagar.

POST /payment_intents/:id/cancel

Autenticación

• Clave de API (Basic Auth): obligatoria

Parámetros de ruta

Parámetro	Tipo	Obligatorio	Descripción
id	string	Sí	ID del Payment Intent

Respuesta

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "canceled",
  "updatedAt": "2024-01-01T12:00:00.000Z"
}

Completar un Payment Intent

Marca un Payment Intent como en procesamiento y lanza el webhook payment_intent.processing. Llámalo cuando el cliente haya vuelto a tu URL de retorno (por ejemplo, desde tu página de éxito) para que tu backend marque el intent como en procesamiento mientras consultas o esperas el webhook final payment_intent.complete.

POST /payment_intents/:id/complete

Autenticación

• Clave de API (Basic Auth): obligatoria

Parámetros de ruta

Parámetro	Tipo	Obligatorio	Descripción
id	string	Sí	ID del Payment Intent

Respuesta

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "updatedAt": "2024-01-01T12:00:00.000Z"
}

Simular un pago (solo sandbox)

Completa un Payment Intent sin transferencia on-chain, solo en una organización sandbox. El pago sigue el flujo normal y emite los webhooks habituales con livemode: false, y su transacción tiene simulated: true. Los pagos simulados nunca se pueden retirar.

POST /payment_intents/:id/simulate

Autenticación

• Clave de API (Basic Auth) de una organización sandbox (ak_test_…): obligatoria

Errores

Estado	Código	Cuándo
403	SIMULATION_SANDBOX_ONLY	El intent pertenece a una organización live

La página de pago alojada usa el equivalente público POST /payments/links/:slug/simulate (solo enlaces sandbox).

Actualizar un Payment Intent

Actualiza un Payment Intent antes de confirmarlo.

PATCH /payment_intents/:id

Autenticación

• Token Bearer (JWT) o clave de API (Basic Auth)

Parámetros de ruta

Parámetro	Tipo	Obligatorio	Descripción
id	string	Sí	ID del Payment Intent

Cuerpo de la petición

Todos los campos son opcionales. Incluye solo los campos que quieras actualizar.

Parámetro	Tipo	Obligatorio	Descripción
amount	string	No	Importe actualizado
currency	string	No	Moneda actualizada
description	string	No	Descripción actualizada
metadata	object	No	Metadatos actualizados
return_url	string	No	URL de retorno actualizada
cancel_url	string	No	URL de cancelación actualizada
withdrawal_addresses	object	No	Direcciones de retiro por tipo de cadena; omítelo para usar el valor por defecto de la cuenta

Respuesta

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "amount": "150.00",
  "currency": "usd",
  "status": "requires_payment_method",
  "updatedAt": "2024-01-01T12:00:00.000Z"
}

Códigos de estado

Código de estado	Descripción
200	Correcto
201	Creado
400	Petición incorrecta
401	No autorizado
404	No encontrado
500	Error interno del servidor

Formato de las respuestas de error

{
  "statusCode": 400,
  "message": "Invalid request",
  "error": "Bad Request"
}

Límites de frecuencia

Las peticiones a la API tienen límites de frecuencia. Límites actuales:

• Peticiones autenticadas: 100 peticiones por minuto por clave de API/usuario
• Peticiones no autenticadas: 10 peticiones por minuto por IP

Las respuestas incluyen cabeceras de límite de frecuencia:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200

Consulta también

• Guía de Payment Intents: guías detalladas
• Webhooks: recibe notificaciones de pago