api

API de transacciones

La API de Transacciones cubre el ciclo de vida completo del pago: creación de sesiones de pago, consulta del estado de las transacciones y verificación de las confirmaciones en la blockchain.

Actualizado: 9/3/2026

La API de transacciones cubre el ciclo de vida completo del pago: creación de sesiones de pago, consulta del estado de las transacciones y verificación de las confirmaciones de la blockchain.

Resumen del flujo de pago

┌─────────────┐    ┌──────────────┐    ┌──────────────┐    ┌───────────────┐
│ Your Server │───>│ Create       │───>│ Customer     │───>│ Blockchain    │
│             │    │ Checkout     │    │ Pays on      │    │ Confirms      │
│ POST api.php│    │ Session      │    │ Payment Page │    │ Transaction   │
└─────────────┘    └──────────────┘    └──────────────┘    └───────────────┘
                         │                                        │
                         │ payment_url                             │
                         ▼                                        ▼
                   ┌──────────────┐                         ┌───────────────┐
                   │ Redirect     │                         │ Webhook POST  │
                   │ Customer     │                         │ to Your Server│
                   │ to pay.php   │                         │               │
                   └──────────────┘                         └───────────────┘

Tu servidorllama acreate-checkout-sessioncon el importe y la divisa del pago.
Recibes unapayment_urly rediriges al cliente a ella.
El cliente selecciona una criptomoneda, escanea el código QR y envía el pago.
QuantaPay monitoriza la blockchain y espera las confirmaciones.
Una vez confirmado, QuantaPay envía unwebhooka tu servidor y/o redirige al cliente.

create-checkout-session

Crea una nueva sesión de pago. Devuelve una URL de pago a la que redirigir a tu cliente.

Solicitud

curl -X POST https://cloud.quantapay.app/api.php \
  -d "function=create-checkout-session" \
  -d "api-key=YOUR_API_KEY" \
  -d "price=49.99" \
  -d "currency=USD"

Parámetros

Parámetro	Tipo	Obligatorio	Descripción
`price`	number	Sí	Importe del pago en la divisa especificada.
`currency`	string	Sí	Código de divisa ISO 4217 (p. ej.,`USD`, `EUR`, `GBP`).
`order_id`	string	No	Tu ID de pedido interno como referencia.
`redirect`	string	No	URL a la que redirigir al cliente tras el pago correcto.
`cancel_url`	string	No	URL a la que redirigir al cliente si cancela.
`note`	string	No	Nota interna adjunta a la transacción.
`items`	Cadena JSON	No	Array de partidas (ver más abajo).
`customer`	Cadena JSON	No	Objeto de información del cliente.
`signature`	string	No	Firma HMAC-SHA256 para protección contra manipulaciones.
`timestamp`	integer	No	Timestamp de Unix (obligatorio si se proporciona la firma).
`external_reference`	string	No	Referencia cifrada del plugin de WordPress.
`plugin`	string	No	Identificador del plugin de origen (p. ej.,`woo`, `edd`).

Formato de los Items

[
  {
    "name": "Product Name",
    "qty": 2,
    "price": 24.99,
    "image": "https://example.com/product.jpg"
  }
]

Máximo 50 items por sesión.
name: Máximo 200 caracteres.
image: Debe ser una URL HTTP o HTTPS, máximo 500 caracteres.

Respuesta

{
  "success": true,
  "response": {
    "session_id": "cs_a1b2c3d4e5f6a1b2c3d4",
    "payment_url": "https://cloud.quantapay.app/pay.php?session=cs_a1b2c3d4e5f6a1b2c3d4",
    "expires_at": "2026-03-08T11:00:00+00:00"
  }
}

session_id: Identificador de sesión único (formato:cs_+ 24 caracteres hexadecimales).
payment_url: URL para redirigir al cliente para completar el pago.
expires_at: Timestamp ISO 8601. Las sesiones expiran después de60 minutos.

Respuestas de Error

Message	Cause
`Faltan campos obligatorios: price, currency`	`price`es 0/falta o`currency`está vacío.
`Firma no válida`	Falló la verificación de la firma HMAC.
`Solicitud caducada`	La marca de tiempo excede en más de 5 minutos la hora del servidor.
`No se pudo crear la sesión de pago`	Error de la base de datos.

get-checkout-session

Consulta el estado actual de una sesión de pago.

Solicitud

curl -X POST https://cloud.quantapay.app/api.php \
  -d "function=get-checkout-session" \
  -d "api-key=YOUR_API_KEY" \
  -d "session_id=cs_a1b2c3d4e5f6a1b2c3d4"

Parámetros

Parámetro	Tipo	Obligatorio	Descripción
`session_id`	string	Sí	El ID de la sesión de pago (comienza con`cs_`).

Respuesta

{
  "success": true,
  "response": {
    "session_id": "cs_a1b2c3d4e5f6a1b2c3d4",
    "status": "paid",
    "price": 49.99,
    "currency": "usd",
    "order_id": "ORD-12345",
    "created_at": "2026-03-08T10:00:00+00:00",
    "expires_at": "2026-03-08T11:00:00+00:00",
    "paid_at": "2026-03-08T10:15:23+00:00"
  }
}

Estados de la sesión

Estado	Descripción
`active`	La sesión está abierta y esperando el pago.
`paid`	El pago se ha recibido y confirmado en la blockchain.
`expired`	La sesión caducó sin recibir el pago (después de 60 minutos).
`cancelled`	La sesión se canceló antes de recibir el pago.

get-transactions

Consulta una lista paginada de transacciones. Útil para la conciliación y la generación de informes.

Solicitud

curl -X POST https://cloud.quantapay.app/api.php \
  -d "function=get-transactions" \
  -d "api-key=YOUR_API_KEY" \
  -d "pagination=0"

Parámetros

Todos los parámetros son opcionales:

Parámetro	Tipo	Descripción
`pagination`	integer	Número de página (indexado desde 0). Cada página devuelve hasta 100 transacciones.
`search`	string	Búsqueda por ID de transacción, hash, importe o descripción.
`status`	string	Filtrar por estado:`C`(completada),`P`(pendiente),`X`(pago insuficiente),`E`(caducada).
`cryptocurrency`	string	Filtrar por código de criptomoneda (p. ej.,`btc`, `eth`).
`date_range`	array	Filtro de rango de fechas como un array de dos elementos:`date_range[0]=2026-01-01&date_range[1]=2026-03-01`.
`checkout_id`	string	Filtrar por ID de botón de pago/checkout.

Respuesta

Devuelve un array de objetos de transacción:

{
  "success": true,
  "response": [
    {
      "id": "123",
      "title": "Payment #ORD-12345",
      "description": "",
      "from": "0xCustomerAddress...",
      "to": "0xYourAddress...",
      "hash": "0xTransactionHash...",
      "amount": "0.025",
      "amount_fiat": "49.99",
      "cryptocurrency": "eth",
      "currency": "usd",
      "external_reference": "",
      "creation_time": "2026-03-08 10:00:00",
      "status": "C",
      "webhook": "1",
      "vat": ""
    }
  ]
}

Estados de la transacción

Código	Estado	Descripción
`C`	Completada	Pago confirmado en la blockchain.
`P`	Pendiente	Esperando el pago o la confirmación en la blockchain.
`X`	Pago insuficiente	Pago recibido, pero el importe fue inferior al requerido.
`E`	Expirada	El plazo de pago expiró sin que se realizara un pago suficiente.
`R`	Reembolsada	El pago ha sido reembolsado.

get-transaction

Obtener detalles de una sola transacción por ID.

Solicitud

curl -X POST https://cloud.quantapay.app/api.php \
  -d "function=get-transaction" \
  -d "api-key=YOUR_API_KEY" \
  -d "transaction_id=123"

Parámetros

Parámetro	Tipo	Obligatorio	Descripción
`transaction_id`	integer	Sí	El ID de la transacción.

Respuesta

Devuelve un único objeto de transacción (con el mismo formato queget-transactions).

check-transaction

Activar manualmente una comprobación de confirmación de blockchain para una transacción específica.

Solicitud

curl -X POST https://cloud.quantapay.app/api.php \
  -d "function=check-transaction" \
  -d "api-key=YOUR_API_KEY" \
  -d "transaction=TRANSACTION_JSON"

Parámetros

Parámetro	Tipo	Obligatorio	Descripción
`transaction`	Cadena JSON	Sí	El objeto de transacción que se va a comprobar (tal como lo devuelve`get-transaction`).

Respuesta

Devuelve el objeto de transacción actualizado con el estado de confirmación actual. Si se alcanza el número requerido de confirmaciones, el estado de la transacción cambia aC(completada).

Nota: Esta función no suele ser necesaria en el funcionamiento normal. QuantaPay comprueba automáticamente las confirmaciones a través de su sistema cron. Utilícela solo si necesita forzar una comprobación inmediata.