Referencia de la API de pago

Referencia completa de los endpoints de la API de pago. Úsalos cuando tengas el slug de un enlace de pago y quieras obtener los datos de pago, confirmarlo o cancelarlo.

URL base

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

Obtener el pago por slug

Obtén los datos de pago de un enlace de pago a partir de su slug. No requiere autenticación; úsalo para mostrar la información del pago antes de que el cliente pague.

GET /pay/:slug

Parámetros de ruta

Parámetro	Tipo	Obligatorio	Descripción
slug	string	Sí	Slug del enlace de pago (por ejemplo pl_abc123)

Respuesta

Devuelve los datos del pago, incluidos el importe, el token, la red y los metadatos necesarios para mostrar la página de pago.

{
  "id": 1,
  "title": "Payment for services",
  "slug": "pl_abc123",
  "amount": "0.1",
  "tokenId": 1,
  "networkId": 1,
  "status": "active",
  "expiresAt": "2024-12-31T23:59:59.000Z",
  "metadata": {},
  "createdAt": "2024-01-01T00:00:00.000Z"
}

Confirmar el pago

Confirma un payment intent por slug y obtén la URL de redirección a la app de pago alojada. La petición puede usar la cabecera Origin o Referer para fijar el origen del frontend en la URL de retorno.

POST /pay/:slug/confirm

Parámetros de ruta

Parámetro	Tipo	Obligatorio	Descripción
slug	string	Sí	Slug del enlace de pago

Cabeceras

Cabecera	Tipo	Obligatoria	Descripción
Origin	string	No	Origen del frontend (se usa en la URL de retorno)
Referer	string	No	Alternativa a Origin para el origen del frontend

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"
    }
  }
}

Redirige al cliente a nextAction.redirectToUrl.url para completar el pago en la página de pago alojada.

Cancelar el pago

Cancela el payment intent asociado al slug de un enlace de pago.

POST /pay/:slug/cancel

Parámetros de ruta

Parámetro	Tipo	Obligatorio	Descripción
slug	string	Sí	Slug del enlace de pago

Respuesta

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

Casos de uso

1. Obtener el pago: llama a GET /pay/:slug para mostrar el importe, el token y la red en tu página.
2. Iniciar el pago: llama a POST /pay/:slug/confirm y redirige al usuario a la URL devuelta.
3. Cancelar: llama a POST /pay/:slug/cancel si el usuario abandona o necesitas cancelar el intent.

Códigos de estado

Código de estado	Descripción
200	Correcto
400	Petición incorrecta
404	No encontrado (slug no válido)
500	Error interno del servidor

Consulta también

• Payment Intents: crea y gestiona payment intents por ID
• Pagos: enlaces de pago y transacciones
• Webhooks: recibe eventos de pago