Referencia

API REST

JSON sobre HTTPS en https://talopartnerhub.vercel.app. También está como OpenAPI 3.1 para generar clientes.

Autenticación

Mandá tu API key en cada pedido. Creala con npx talo-hub keys create o desde el dashboard.

header

Authorization: Bearer tph_test_…

Opcional: Talo-Hub-Client con el nombre de tu integración, para identificar el origen de cada pedido.

Cada endpoint indica el permiso mínimo de la key: read, charge o full. Ver credenciales.

Errores

4xx / 5xx

{ "error": { "code": "invalid_amount", "message": "amount must be a positive number of ARS." } }

Código	Qué significa
`unauthorized`	Falta la key o fue revocada (401).
`talo_reconnect_required`	Talo ya no acepta la autorización de la cuenta: volvé a conectarla (409).
`talo_rejected`	Talo rechazó el pedido; el motivo viene en `details.talo_message`.
`insufficient_scope`	La key no tiene el permiso que pide la operación (403).
`sandbox_only`	La operación solo existe con keys de sandbox (403).
`talo_unavailable`	Talo no respondió bien: reintentá (502).
`link_not_found`, `link_disabled`	No hay un link de pago con ese ID en tu cuenta (404), o ya estaba desactivado (410).
`not_found`	La vista pública no encontró el pago para ese `checkout_token` (404): no dice si el token es inválido, venció o es de otro pago.

Estados de un pago

PENDING	Esperando la transferencia.
SUCCESS	Pagado exacto.
OVERPAID	Pagó de más.
UNDERPAID	Pagó de menos: no entregues, pedí el resto.
EXPIRED	Venció sin pagarse.

Pagos

POST/api/v1/paymentscharge

Crea un pago por transferencia y devuelve el CVU y el alias para pagarlo.

Repetir el mismo external_id devuelve el pago existente: los reintentos nunca cobran dos veces. La respuesta trae payment_url (la página de Talo del pago) y checkout_token, un token de solo lectura de ese pago para el widget (ver Checkout).

Body

amount numberrequerido — Monto en ARS.

external_id string — Tu ID de orden. Hace seguros los reintentos.

motive string — Concepto que ve el comprador.

redirect_url string — Adónde vuelve el comprador desde la página de pago de Talo.

client_data object — first_name, last_name, email, phone, dni, cuit.

GET/api/v1/paymentsread

Pagos de un período (por defecto, los últimos 30 días).

Talo no les deja listar pagos a las integraciones de partners: entonces el hub devuelve los que se crearon a través de él, con el último estado que registró, y `source: "hub"` (con `source: "talo"`, la lista viene de Talo). GET /api/v1/payments/{id} trae el detalle completo.

Query

from string — Fecha ISO 8601.

to string — Fecha ISO 8601.

GET/api/v1/payments/{id}read

Estado, montos pagados y reembolsados, y reembolsos de un pago.

paid y refunded son números (0 si no hay). refunds: [{ id, status: PENDING|SUCCESS|FAILED, type: FULL|PARTIAL, amount, currency, created_at }]. Leer un pago también pone al día sus eventos y trae un checkout_token nuevo (15 días).

PUT/api/v1/payments/{id}/pricefull

Cambia el monto. Talo recalcula el estado de un pago ya pagado.

Body

amount numberrequerido — Nuevo monto en ARS.

PUT/api/v1/payments/{id}/expirationfull

Extiende el vencimiento de un pago PENDING.

Body

expires_at stringrequerido — Fecha ISO 8601.

POST/api/v1/payments/{id}/refundsfull

Reembolsa un pago, total o parcial. Asincrónico: empieza PENDING.

Body

amount number — ARS para un reembolso parcial. Sin amount, reembolso total.

Checkout

POST/api/v1/payment-linkscharge

Crea un link de pago reutilizable (/l/<id>): cada comprador que toca Pagar recibe un pago nuevo y va a la página de Talo con el CVU y el alias.

Mandá amount (precio fijo) o min_amount y max_amount (el comprador escribe el monto). Devuelve url y qr_url. Sus pagos llevan external_id link_<id>_<al azar> (el id tiene 12 letras y números: external_id.slice(5, 17)) y motive = title, y el pedido se entrega con el webhook firmado, como cualquier pago. Hasta 20 pagos por hora desde una misma red (IP) por link, y un freno de 200 por link cada 10 minutos; quien vuelve al link recupera el pago que ya había empezado (también si transfirió de menos), y eso no cuenta.

Cómo usarlos, el widget y el checkout_token: Checkout.

Body

title stringrequerido — Qué se paga, de 1 a 80 caracteres. Lo ve el comprador y es el motive de cada pago.

description string — Hasta 280 caracteres.

amount number — Precio fijo en ARS: positivo, hasta 2 decimales y 100.000.000.

min_amount number — Con max_amount y sin amount: el comprador escribe el monto, dentro de ese rango.

max_amount number — El monto más alto que puede escribir el comprador.

redirect_url string — URL https adonde la página de Talo devuelve al comprador (http solo para localhost).

GET/api/v1/payment-linksread

Tus links de pago, del más nuevo al más viejo (hasta 100), con los desactivados (active: false).

GET/api/v1/payment-links/{id}read

Un link de pago y los pagos que se crearon con él: payments [{ id, status, amount, external_id, created_at }], del más nuevo al más viejo.

DELETE/api/v1/payment-links/{id}charge

Desactiva un link de pago para siempre. Los pagos que ya empezaron con él se pueden seguir pagando.

No se puede reactivar: creá otro. Un link que ya estaba desactivado responde 410 link_disabled.

GET/api/public/payments/{id}sin key

La vista pública de un pago, para el widget o tu propia página: estado, monto, pagado, CVU, alias, vencimiento y payment_url.

Sin API key: la autoriza el checkout_token del pago (lo devuelven POST /api/v1/payments y GET /api/v1/payments/{id}), que solo sirve para leer ese pago y vence a los 15 días. Cualquier origen puede llamarla (CORS *) y el CDN guarda cada respuesta 3 segundos. Un token inválido, vencido o de otro pago, una cuenta desconectada y un pago que no existe responden lo mismo: 404 not_found.

Query

token stringrequerido — El checkout_token del pago (ct_…).

Sandbox

POST/api/v1/sandbox/transferschargesolo sandbox

Simula la transferencia del comprador a un pago de sandbox.

Con menos monto probás UNDERPAID; con más, OVERPAID. Dispara los mismos eventos que una transferencia real.

Body

payment_id stringrequerido — El pago a pagar.

amount number — ARS. Por defecto, el monto del pago.

Eventos

GET/api/v1/eventsread

Eventos de la cuenta, para escuchar sin exponer un servidor.

Con after: los posteriores a ese ID, del más viejo al más nuevo (seguí con next_after). Con recent: los últimos n, del más nuevo al más viejo.

Query

after number — Devuelve los eventos posteriores a este ID.

recent number — Los últimos n eventos (1 a 200).

limit number — Hasta 200.

payment_id string — Solo los eventos de ese cobro.

type string — Solo ese tipo, p. ej. payment.paid.

GET/api/v1/webhook-endpointsread

Tus webhooks.

POST/api/v1/webhook-endpointsfull

Registra un webhook https. Devuelve el secreto de firma una sola vez.

Body

url stringrequerido — URL https que recibe los eventos.

DELETE/api/v1/webhook-endpoints/{id}full

Da de baja un webhook.

POST/api/v1/webhook-endpoints/{id}/testcharge

Manda ya un evento webhook.test firmado y dice si tu endpoint respondió 2xx.

No mueve plata: sirve en sandbox y en producción para verificar tu handler.

Movimientos

GET/api/v1/balanceread

Saldo de la cuenta.

Talo todavía no lo habilita para integraciones de partner: hoy responde talo_partner_unsupported (501).

GET/api/v1/transactionsread

Transferencias entrantes y salientes, paginadas.

Talo todavía no lo habilita para integraciones de partner: hoy responde talo_partner_unsupported (501). El estado de cada cobro siempre está en /api/v1/payments.

Query

from string — Fecha ISO 8601.

to string — Fecha ISO 8601.

limit number — Hasta 200.

cursor string — El next_cursor de la página anterior.

Cuenta

GET/api/v1/accountread

Cuenta Talo conectada: estado de activación y, cuando Talo los informa, prefijo de alias y vencimiento de pagos.

PATCH/api/v1/accountfull

Configura la cuenta. Solo cambian los campos enviados.

Body

alias_prefix string — Hasta 8 caracteres: minúsculas, números y guiones bajos.

cancellation_period_minutes number — Vencimiento de los pagos nuevos, de 5 a 20160 minutos.

automatic_cancellation boolean — Cancela solos los pagos vencidos.

DELETE/api/v1/accountfull

Desconecta la cuenta del hub, todo junto: borra la copia de la autorización de Talo, revoca todas las keys, desactiva los webhooks y cierra las sesiones del dashboard.

Los pagos y la plata siguen en Talo, y el hub conserva su registro de pagos y eventos pasados. Para volver, autorizá de nuevo (npx talo-hub login). Es para la persona dueña de la cuenta: un agente no debería llamarlo sin que se lo pida.

GET/api/v1/readinessread

Checklist para pasar a producción: qué está hecho y cómo resolver lo que falta.

Keys

GET/api/v1/api-keysread

Tus API keys (solo el prefijo).

POST/api/v1/api-keysfull

Crea una API key. Se muestra una sola vez.

Solo con una key full (o desde el dashboard). La nueva puede tener cualquier scope y es charge si no pedís otro.

Body

name string — Para reconocerla después.

scope string — read, charge o full (por defecto charge).

DELETE/api/v1/api-keys/{id}full

Revoca una API key.