Referencia de la API de pagos

Referencia completa de los endpoints de la API de pagos (enlaces de pago, transacciones, redes y tokens).

URL base

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

Enlaces de pago

Crear un enlace de pago

Crea un nuevo enlace de pago.

POST /payments/links

Autenticación

Token Bearer (JWT): obligatorio

Cuerpo de la petición

Parámetro	Tipo	Obligatorio	Descripción
`title`	string	Sí	Título del enlace de pago
`amount`	string	Sí	Importe (por ejemplo "0.1")
`tokenId`	string	Sí	ID del token (UUID)
`networkId`	string	Sí	ID de la red (UUID)
`expiresAt`	string	No	Marca de tiempo de caducidad ISO 8601
`metadata`	object	No	Metadatos personalizados

Respuesta

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Payment for services",
  "slug": "pl_abc123",
  "amount": "0.1",
  "tokenId": "550e8400-e29b-41d4-a716-446655440001",
  "networkId": "550e8400-e29b-41d4-a716-446655440002",
  "status": "active",
  "expiresAt": "2024-12-31T23:59:59.000Z",
  "metadata": {},
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-01T00:00:00.000Z"
}

Listar los enlaces de pago del usuario

Lista todos los enlaces de pago del usuario autenticado.

GET /payments/links

Autenticación

Token Bearer (JWT): obligatorio

Respuesta

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Payment for services",
    "slug": "pl_abc123",
    "amount": "0.1",
    "tokenId": "550e8400-e29b-41d4-a716-446655440001",
    "networkId": "550e8400-e29b-41d4-a716-446655440002",
    "status": "active",
    "createdAt": "2024-01-01T00:00:00.000Z"
  }
]

Obtener un enlace de pago por slug

Obtén un enlace de pago a partir de su slug (público, sin autenticación).

GET /payments/links/:slug

Parámetros de ruta

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

Respuesta

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Payment for services",
  "slug": "pl_abc123",
  "amount": "0.1",
  "tokenId": "550e8400-e29b-41d4-a716-446655440001",
  "networkId": "550e8400-e29b-41d4-a716-446655440002",
  "status": "active",
  "expiresAt": "2024-12-31T23:59:59.000Z",
  "metadata": {},
  "createdAt": "2024-01-01T00:00:00.000Z"
}

Actualizar un enlace de pago

Actualiza un enlace de pago existente.

PATCH /payments/links/:id

Autenticación

Token Bearer (JWT): obligatorio

Parámetros de ruta

Parámetro	Tipo	Obligatorio	Descripción
`id`	string	Sí	ID del enlace de pago (UUID)

Cuerpo de la petición

Todos los campos son opcionales.

Parámetro	Tipo	Obligatorio	Descripción
`title`	string	No	Título actualizado
`amount`	string	No	Importe actualizado
`tokenId`	string	No	ID del token actualizado (UUID)
`networkId`	string	No	ID de la red actualizado (UUID)
`status`	string	No	Estado: `active`, `inactive`, etc.
`expiresAt`	string	No	Caducidad actualizada (ISO 8601)
`metadata`	object	No	Metadatos actualizados

Respuesta

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Updated title",
  "slug": "pl_abc123",
  "amount": "0.2",
  "tokenId": "550e8400-e29b-41d4-a716-446655440001",
  "networkId": "550e8400-e29b-41d4-a716-446655440002",
  "status": "active",
  "updatedAt": "2024-01-01T12:00:00.000Z"
}

Eliminar un enlace de pago

Elimina un enlace de pago.

DELETE /payments/links/:id

Autenticación

Token Bearer (JWT): obligatorio

Parámetros de ruta

Parámetro	Tipo	Obligatorio	Descripción
`id`	string	Sí	ID del enlace de pago (UUID)

Respuesta

204 No Content

Cotización

Obtener cotización

Obtén una cotización para un enlace de pago con el token/red del pagador y la comisión de soporte opcionales. Para los precios de la plataforma alojada (por transacción y plan gratuito), consulta la visión general de comisiones y límites. Para ver cómo se aplican y devuelven los conceptos de la cotización (soporte, comisión, puente) y los mínimos, consulta Comisiones y límites.

POST /payments/links/:slug/quote

Parámetros de ruta

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

Cuerpo de la petición

Todos los campos son opcionales.

Parámetro	Tipo	Obligatorio	Descripción
`payerTokenId`	string	No	ID del token (UUID) con el que quiere pagar el pagador
`payerNetworkId`	string	No	ID de la red (UUID) en la que quiere pagar el pagador
`supportPercent`	number	No	Porcentaje de la comisión de soporte (por ejemplo 0.1 para 0,1 %)

Respuesta

{
  "originalAmount": "100.00",
  "supportPercent": "0.1",
  "supportAmount": "0.1",
  "originalTokenSymbol": "USDC",
  "payerTokenSymbol": "USDT",
  "bridgeFee": "0.001",
  "bridgeFeeUsd": "0.25",
  "bridgeFeeInPayerToken": "0.0001",
  "originalAmountInPayerToken": "1.0",
  "totalAmount": "100.0001",
  "requiresBridge": true,
  "payerTokenId": "550e8400-e29b-41d4-a716-446655440001",
  "payerNetworkId": "550e8400-e29b-41d4-a716-446655440002",
  "payerNetworkName": "Ethereum",
  "payerNetwork": {
    "id": "550e8400-e29b-41d4-a716-446655440002",
    "name": "Ethereum",
    "chainId": 1,
    "blockExplorerUrl": "https://etherscan.io",
    "publicRpcUrls": ["https://eth.llamarpc.com"],
    "isActive": true,
    "isTestnet": false,
    "listenerConfig": null,
    "requiredConfirmations": 12,
    "image": null,
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z",
    "deletedAt": null
  },
  "payerToken": {
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "networkId": "550e8400-e29b-41d4-a716-446655440002",
    "symbol": "USDT",
    "name": "Tether USD",
    "contractAddress": "0x...",
    "decimals": 6,
    "isNative": false,
    "isStablecoin": true,
    "isActive": true,
    "image": null,
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z",
    "deletedAt": null
  }
}

payerNetwork y payerToken son objetos completos (consulta Listar redes y Listar tokens por red para la descripción de los campos).

Transacciones

Crear una transacción

Crea una nueva transacción para un enlace de pago.

POST /payments/links/:slug/transactions

Parámetros de ruta

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

Cuerpo de la petición

Todos los campos son opcionales.

Parámetro	Tipo	Obligatorio	Descripción
`payerTokenId`	string	No	ID del token (UUID) con el que quiere pagar el pagador
`payerNetworkId`	string	No	ID de la red (UUID) en la que quiere pagar el pagador
`supportPercent`	number	No	Porcentaje de la comisión de soporte (por ejemplo 0.1)

Respuesta

{
  "id": "550e8400-e29b-41d4-a716-446655440003",
  "paymentLinkId": "550e8400-e29b-41d4-a716-446655440000",
  "amount": "0.1",
  "status": "pending",
  "payerTokenId": "550e8400-e29b-41d4-a716-446655440001",
  "payerNetworkId": "550e8400-e29b-41d4-a716-446655440002",
  "supportPercent": 0.1,
  "createdAt": "2024-01-01T00:00:00.000Z"
}

Obtener una transacción por ID

Obtén una transacción por su ID.

GET /payments/transactions/:id

Parámetros de ruta

Parámetro	Tipo	Obligatorio	Descripción
`id`	string	Sí	ID de la transacción (UUID)

Respuesta

{
  "id": "550e8400-e29b-41d4-a716-446655440003",
  "paymentLinkId": "550e8400-e29b-41d4-a716-446655440000",
  "amount": "0.1",
  "status": "completed",
  "payerTokenId": "550e8400-e29b-41d4-a716-446655440001",
  "payerNetworkId": "550e8400-e29b-41d4-a716-446655440002",
  "supportPercent": 0.1,
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-01T01:00:00.000Z"
}

Listar las transacciones del usuario

Lista todas las transacciones del usuario autenticado.

GET /payments/transactions

Autenticación

Token Bearer (JWT): obligatorio

Respuesta

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440003",
    "paymentLinkId": "550e8400-e29b-41d4-a716-446655440000",
    "amount": "0.1",
    "status": "completed",
    "createdAt": "2024-01-01T00:00:00.000Z"
  }
]

Obtener una transacción con toda la información del pagador

Obtén una transacción con todos los datos de la red y el token del pagador.

GET /payments/transactions/:id/full

Parámetros de ruta

Parámetro	Tipo	Obligatorio	Descripción
`id`	string	Sí	ID de la transacción (UUID)

Respuesta

{
  "id": "550e8400-e29b-41d4-a716-446655440003",
  "paymentLinkId": "550e8400-e29b-41d4-a716-446655440000",
  "amount": "0.1",
  "status": "completed",
  "payerTokenId": "550e8400-e29b-41d4-a716-446655440001",
  "payerNetworkId": "550e8400-e29b-41d4-a716-446655440002",
  "payerToken": {
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "symbol": "USDC",
    "decimals": 6,
    "contractAddress": "0x..."
  },
  "payerNetwork": {
    "id": "550e8400-e29b-41d4-a716-446655440002",
    "name": "Ethereum",
    "chainId": 1,
    "publicRpcUrls": ["https://eth.llamarpc.com"]
  },
  "createdAt": "2024-01-01T00:00:00.000Z"
}

Actualizar el pagador de una transacción

Actualiza el token y la red del pagador de una transacción.

PATCH /payments/transactions/:id/payer

Parámetros de ruta

Parámetro	Tipo	Obligatorio	Descripción
`id`	string	Sí	ID de la transacción (UUID)

Cuerpo de la petición

Parámetro	Tipo	Obligatorio	Descripción
`payerTokenId`	string	Sí	ID del token (UUID) con el que quiere pagar el pagador
`payerNetworkId`	string	Sí	ID de la red (UUID) en la que quiere pagar el pagador

Respuesta

{
  "id": "550e8400-e29b-41d4-a716-446655440003",
  "paymentLinkId": "550e8400-e29b-41d4-a716-446655440000",
  "amount": "0.1",
  "status": "pending",
  "payerTokenId": "550e8400-e29b-41d4-a716-446655440004",
  "payerNetworkId": "550e8400-e29b-41d4-a716-446655440005",
  "updatedAt": "2024-01-01T12:00:00.000Z"
}

Actualizar el soporte de una transacción

Actualiza el porcentaje de la comisión de soporte de una transacción.

PATCH /payments/transactions/:id/support

Parámetros de ruta

Parámetro	Tipo	Obligatorio	Descripción
`id`	string	Sí	ID de la transacción (UUID)

Cuerpo de la petición

Parámetro	Tipo	Obligatorio	Descripción
`supportPercent`	number	Sí	Porcentaje de la comisión de soporte (por ejemplo 0.1 para 0,1 %)

Respuesta

{
  "id": "550e8400-e29b-41d4-a716-446655440003",
  "paymentLinkId": "550e8400-e29b-41d4-a716-446655440000",
  "amount": "0.1",
  "status": "pending",
  "supportPercent": 0.2,
  "updatedAt": "2024-01-01T12:00:00.000Z"
}

Redes y tokens

Listar redes

Lista todas las redes compatibles.

GET /payments/networks

Parámetros de consulta

Parámetro	Tipo	Obligatorio	Descripción
`active`	string	No	Ponlo a `true` para devolver solo las redes activas
`testnet`	string	No	`true` = solo testnets (sandbox), `false` = solo mainnets (live). Omítelo para todas

Respuesta

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440002",
    "name": "Ethereum",
    "chainId": 1,
    "blockExplorerUrl": "https://etherscan.io",
    "publicRpcUrls": ["https://eth.llamarpc.com"],
    "isActive": true,
    "isTestnet": false,
    "listenerConfig": null,
    "requiredConfirmations": 12,
    "image": null,
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z",
    "deletedAt": null
  }
]

Listar tokens por red

Lista los tokens disponibles en una red concreta.

GET /payments/networks/:id/tokens

Parámetros de ruta

Parámetro	Tipo	Obligatorio	Descripción
`id`	string	Sí	ID de la red (UUID)

Respuesta

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "networkId": "550e8400-e29b-41d4-a716-446655440002",
    "symbol": "USDC",
    "name": "USD Coin",
    "decimals": 6,
    "contractAddress": "0x...",
    "isNative": false,
    "isStablecoin": true,
    "isActive": true,
    "image": null,
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z",
    "deletedAt": null
  }
]

Códigos de estado

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

Consulta también

Payment Intents: API de Payment Intents
Pago: pago por slug
Autenticación: métodos de autenticación

URL base​

Enlaces de pago​

Crear un enlace de pago​

Autenticación​

Cuerpo de la petición​

Respuesta​

Listar los enlaces de pago del usuario​

Autenticación​

Respuesta​

Obtener un enlace de pago por slug​

Parámetros de ruta​

Respuesta​

Actualizar un enlace de pago​

Autenticación​

Parámetros de ruta​

Cuerpo de la petición​

Respuesta​

Eliminar un enlace de pago​

Autenticación​

Parámetros de ruta​

Respuesta​

Cotización​

Obtener cotización​

Parámetros de ruta​

Cuerpo de la petición​

Respuesta​

Transacciones​

Crear una transacción​

Parámetros de ruta​

Cuerpo de la petición​

Respuesta​

Obtener una transacción por ID​

Parámetros de ruta​

Respuesta​

Listar las transacciones del usuario​

Autenticación​

Respuesta​

Obtener una transacción con toda la información del pagador​

Parámetros de ruta​

Respuesta​

Actualizar el pagador de una transacción​

Parámetros de ruta​

Cuerpo de la petición​

Respuesta​

Actualizar el soporte de una transacción​

Parámetros de ruta​

Cuerpo de la petición​

Respuesta​

Redes y tokens​

Listar redes​

Parámetros de consulta​

Respuesta​

Listar tokens por red​

Parámetros de ruta​

Respuesta​

Códigos de estado​

Consulta también​

URL base

Enlaces de pago

Crear un enlace de pago

Autenticación

Cuerpo de la petición

Respuesta

Listar los enlaces de pago del usuario

Autenticación

Respuesta

Obtener un enlace de pago por slug

Parámetros de ruta

Respuesta

Actualizar un enlace de pago

Autenticación

Parámetros de ruta

Cuerpo de la petición

Respuesta

Eliminar un enlace de pago

Autenticación

Parámetros de ruta

Respuesta

Cotización

Obtener cotización

Parámetros de ruta

Cuerpo de la petición

Respuesta

Transacciones

Crear una transacción

Parámetros de ruta

Cuerpo de la petición

Respuesta

Obtener una transacción por ID

Parámetros de ruta

Respuesta

Listar las transacciones del usuario

Autenticación

Respuesta

Obtener una transacción con toda la información del pagador

Parámetros de ruta

Respuesta

Actualizar el pagador de una transacción

Parámetros de ruta

Cuerpo de la petición

Respuesta

Actualizar el soporte de una transacción

Parámetros de ruta

Cuerpo de la petición

Respuesta

Redes y tokens

Listar redes

Parámetros de consulta

Respuesta

Listar tokens por red

Parámetros de ruta

Respuesta

Códigos de estado

Consulta también