Endpoints de cuenta

Crear cuenta

Abre una cuenta de cobro por orden usando la API key de tu comercio. La respuesta devuelve alias, número de cuenta y account_id, que después se usan para mostrar instrucciones de pago y consultar el estado.

POST/api/v2/accountsEndpoint público

Endpoint

Cada intento de pago debería mapearse a una cuenta distinta. El worker crea la cuenta de cobro y persiste la referencia interna en D1.

POST/api/v2/accounts

Este endpoint requiere API key y usa las tus credenciales de cobro configuradas para la empresa asociada.

Cuerpo del request

Campos soportados por el handler actual.

Campo	Tipo	Requerido	Notas
customer_email	string	Sí	Email del comprador. Se guarda junto con la cuenta de cobro.
customer_name	string	No	Si no lo enviás, Transferfix usa la parte anterior al @ del email.
total_amount	number	Sí	Monto esperado para confirmar la operación.
currency	string	Sí	Moneda operativa del comercio, por ejemplo ARS.
order_reference	string	No	Referencia propia del comercio. Sirve para construir el alias.
metadata	object	No	Aceptado por compatibilidad. Persistí también tu contexto en tu sistema.

JSON del request

{
  "customer_email": "comprador@ejemplo.com",
  "customer_name": "Juan Perez",
  "total_amount": 12500,
  "currency": "ARS",
  "order_reference": "ENTRADA-00142",
  "metadata": {
    "order_id": "ORD-142",
    "event_slug": "festival-otono"
  }
}

Ejemplos

Ejemplos listos para usar desde backend.

curl -X POST "https://transferfix.com.ar/api/v2/accounts" \
  -H "X-API-Key: ck_live_12345678_abcd" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_email": "comprador@ejemplo.com",
    "customer_name": "Juan Perez",
    "total_amount": 12500,
    "currency": "ARS",
    "order_reference": "ENTRADA-00142"
  }'

Respuesta

La creación responde 200 con status pending como acuse de creación, no como estado operativo final del cobro.

Respuesta 200

{
  "success": true,
  "message": "Payment account created successfully",
  "data": {
    "account_id": 42,
    "cucuru_account_number": "0000277800000000560490",
    "cucuru_alias": "pianta.entrada-0014",
    "customer_email": "comprador@ejemplo.com",
    "total_amount": 12500,
    "currency": "ARS",
    "status": "pending"
  }
}

Importante

El campo status: "pending" pertenece al response del endpoint de alta. El estado que usás para decisiones de negocio se obtiene después con GET /api/v2/accounts/status.

Reglas de alias

La construcción del alias depende de order_reference y del alias_prefix configurado para la empresa.

Transferfix normaliza el alias: minúsculas, solo a-z, 0-9, punto y guion, con corte final a 20 caracteres.
Si el alias final queda con menos de 6 caracteres, la API devuelve error de validación. Si no enviásorder_reference, el worker genera una referencia interna.
Con alias_prefix = pianta y order_reference = ENTRADA-00142, un alias posible espianta.entrada-0014.
Persistí al menos account_id, order_reference, cucuru_alias,cucuru_account_number, total_amount y currency.