Liquidaciones y saldo

TipTap Go cobra por ti y después te transfiere a tu cuenta bancaria. Una liquidación es una de esas transferencias, con el detalle de qué pagos incluyó y cuánto se descontó de comisión.

El recorrido del dinero

Tu cliente paga → el pago queda APPROVED y el dinero llega a TipTap Go.
Ese monto aparece en tu saldo disponible (available).
TipTap Go genera una liquidación: agrupa todos tus pagos sin liquidar, descuenta la comisión y queda PENDING (transferencia en camino).
Hecha la transferencia bancaria, la liquidación pasa a PAID con su referencia.

Tu saldo

GET/v1/balance

200 OK

{
  "object": "balance",
  "currency": "USD",
  "available": {
    "payment_count": 12,
    "gross_amount": 480.00,
    "fee_amount": 16.80,
    "net_amount": 463.20
  },
  "in_transit": 159.21,
  "paid_out": 2840.55,
  "fee_schedule": { "percent": 3.5, "fixed": 0 }
}

Campo	Tipo	Descripción
`available`	object	Lo cobrado que todavía no entra en ninguna liquidación. net_amount es lo que recibirías si te liquidáramos ahora.
`in_transit`	number	Suma neta de las liquidaciones PENDING: ya generadas, transferencia en camino.
`paid_out`	number	Total neto que ya te transferimos históricamente.
`fee_schedule`	object	Tu comisión vigente: `percent` sobre el monto más `fixed` por transacción. Aplica a los cobros nuevos; el `fee_amount` de `available` es la comisión que se congeló al aprobarse cada pago pendiente — si tu tarifa cambió después, pueden diferir.

Cómo se calcula la comisión

Por cada pago: comisión = monto × percent / 100 + fixed, redondeado a dos decimales. La liquidación suma las comisiones pago por pago (no aplica el porcentaje al total), y el neto es bruto − comisión.

Listar liquidaciones

GET/v1/settlements

Filtro status: PENDING (en camino), PAID (transferida) o DEBT (neto ≤ 0: no hay transferencia y el saldo queda como deuda del comercio). Paginación por cursor como el resto de los listados.

curl

curl "https://go.paytiptap.com/api/v1/settlements?status=PAID&limit=12" \
  -H "Authorization: Bearer tiptap_sk_TU_LLAVE"

Detalle de una liquidación

GET/v1/settlements/{id}

Además de los totales, el detalle trae payments: cada pago que entró en esa transferencia. Es lo que necesitas para cuadrar contra tu contabilidad.

200 OK

{
  "object": "settlement",
  "id": "cmqbds2xv0001jy9ang3a2wnw",
  "status": "PAID",
  "currency": "USD",
  "gross_amount": 165.00,
  "fee_amount": 5.79,
  "net_amount": 159.21,
  "payment_count": 8,
  "period_start": "2026-06-11T23:44:15.707Z",
  "period_end": "2026-06-12T19:24:51.097Z",
  "bank_account": { "bank_name": "Banco General", "account_last4": "5678" },
  "reference": "ACH-2026-0612-001",
  "paid_at": "2026-06-12T20:30:51.000Z",
  "created_at": "2026-06-12T20:10:03.000Z",
  "payments": [
    { "id": "cmqbbfsbd000fjy7yy29qmahh", "amount": 7.5, "payer_name": "Carlos Ruiz", "created_at": "2026-06-12T19:24:51.097Z" }
  ]
}

Campo	Tipo	Descripción
`period_start · period_end`	ISO-8601	Fecha del pago más antiguo y del más reciente incluidos. No es un mes calendario: la liquidación agrupa todo lo pendiente al momento de generarla.
`bank_account`	object \| null	Foto de la cuenta destino al generar la liquidación, aunque después la cambies.
`reference`	string \| null	Referencia de la transferencia bancaria. Se llena al marcarla como pagada.

Enterarte automáticamente

Dos webhooks cubren el ciclo: settlement.created cuando generamos la liquidación y settlement.paid cuando la transferencia sale. Ambos traen el objeto completo, así puedes registrar el ingreso en tu contabilidad sin consultar nada más.

Cambiar tu cuenta bancaria

La cuenta de destino sale de tu verificación (KYC) y se cambia desde el panel o escribiéndonos, no por API — es un dato sensible que requiere validación.

← Pagos Webhooks →