Clasica · Documentacion

Recargar, listar y trackear una Clasica

Esta pagina describe los endpoints disponibles y la data necesaria para cada accion. Los requests protegidos usan firma RSA-SHA256 con x-api-key, x-nonce y x-signature.

POST /recharges GET /transactions GET /transactions/:reference GET /health

Autenticacion

Todos los endpoints protegidos requieren una firma con la informacion de la peticion. Enviala en headers: x-api-key, x-nonce y x-signature.

Nonce

Formato del nonce

x-nonce debe ser unico por request. Lo recomendado es usar un UUID v4, por ejemplo 3ad97c75-5b21-4a83-91c5-16bb0ec13e3e.

El valor debe tener al menos 8 caracteres y no puede repetirse para el mismo cliente.

Signature

Como formar la firma

La firma se calcula con RSA-SHA256 sobre esta secuencia:

${apiKey}.${nonce}.${sha256(canonicalRequest)}

Luego se firma ese texto con la llave privada del cliente y se envia en x-signature en formato base64 o base64url.

Canonical request

Datos que entran en la firma

La peticion canónica incluye method, path, query, params y body.

{
  "method": "POST",
  "path": "/recharges",
  "query": {},
  "params": {},
  "body": {
    "recharges": [...]
  }
}

Para GET /transactions?batchId=..., usa el path /transactions, el query con batchId y body vacio. Para GET /transactions/:reference, usa el path con la referencia y el parametro reference.

Crear una recarga Clasica

Usa POST /recharges para crear una o varias recargas en una sola peticion. Cada item debe incluir los datos necesarios para procesar la operacion.

Paso 1

Enviar la data

Incluye apiKey, nonce, signature y el arreglo recharges.

Paso 2

Campos por recarga

Cada recarga requiere reference, cardNumber, amount, beneficiaryFullName, beneficiaryIdentification, beneficiaryNationality y callbackUrl.

cardNumber debe pasar el algoritmo de Luhn. Se aceptan espacios o guiones, pero la API lo normaliza antes de validar.

curl

curl -X POST http://127.0.0.1:3000/recharges   -H 'Content-Type: application/json'   -H 'x-api-key: business-a'   -H 'x-nonce: 7d7e7f31-5f62-4b3d-9d31-1f6c9f4b7d1a'   -H 'x-signature: base64-or-base64url-signature'   -d '{
    "apiKey": "business-a",
    "nonce": "7d7e7f31-5f62-4b3d-9d31-1f6c9f4b7d1a",
    "signature": "base64-or-base64url-signature",
    "recharges": [
      {
        "reference": "business-ref-2026-0001",
        "cardNumber": "9760039012345673",
        "amount": 10,
        "beneficiaryFullName": "Juan Perez",
        "beneficiaryIdentification": "12345678901",
        "beneficiaryNationality": "CUB",
        "callbackUrl": "https://business.example/callbacks/clasica"
      }
    ]
  }'

La respuesta devuelve batchId y el detalle de cada recarga creada.

respuesta

{
  "batchId": "5245172a-b998-4663-8436-d0264fdae358",
  "items": [
    {
      "transaction": {
        "id": "9cf7b6e7-3e8f-4a7e-8d0c-5b1d2d8a7e11",
        "reference": "business-ref-2026-0001",
        "status": "PENDING",
        "amount": 10,
        "cardNumber": "9760039012345673"
      }
    }
  ]
}

Listar recargas

Usa GET /transactions para consultar recargas. Puedes filtrar por batchId, status o cardNumber.

batchId

Ver un grupo de recargas

Devuelve solo las transacciones asociadas a un lote concreto.

status o cardNumber

Refinar la consulta

Aplica un filtro adicional cuando necesites resultados mas especificos.

curl

curl "http://127.0.0.1:3000/transactions?batchId=5245172a-b998-4663-8436-d0264fdae358"   -H 'x-api-key: business-a'   -H 'x-nonce: 3ad97c75-5b21-4a83-91c5-16bb0ec13e3e'   -H 'x-signature: base64-or-base64url-signature'

La firma debe construirse sobre el path /transactions y el query completo.

respuesta

[
  {
    "id": "9cf7b6e7-3e8f-4a7e-8d0c-5b1d2d8a7e11",
    "batchId": "5245172a-b998-4663-8436-d0264fdae358",
    "reference": "business-ref-2026-0001",
    "status": "PENDING",
    "amount": 10
  }
]

Trackear una recarga

Usa GET /transactions/:reference para consultar una recarga puntual por su reference.

Paso 1

Usar la referencia

La reference debe ser la misma que se envio al crear la recarga.

Paso 2

Leer el estado

La respuesta incluye el estado actual de la transaccion y los datos asociados a esa referencia.

curl

curl "http://127.0.0.1:3000/transactions/business-ref-2026-0001"   -H 'x-api-key: business-a'   -H 'x-nonce: 9d2f16ce-1f77-4d6d-a63f-4f7a8b3bcf10'   -H 'x-signature: base64-or-base64url-signature'

La firma debe construirse sobre el path /transactions/:reference y el parametro reference.

respuesta

{
  "id": "9cf7b6e7-3e8f-4a7e-8d0c-5b1d2d8a7e11",
  "batchId": "5245172a-b998-4663-8436-d0264fdae358",
  "reference": "business-ref-2026-0001",
  "status": "COMPLETED",
  "amount": 10,
  "callbackStatus": "SENT"
}

Errores comunes

400 Invalid payload: faltan credenciales o la estructura enviada no coincide con el esquema.
400 Invalid card number: el cardNumber no pasa Luhn o no tiene un formato aceptado.
401 Invalid signature: la firma no corresponde al payload canonico.
401 Unknown client: el apiKey no existe o esta inactiva.
409 Nonce already used: el nonce ya fue consumido y no se puede reutilizar.