Pagos

Un pago es un intento de cobro con su resultado real: aprobado, rechazado, anulado o expirado. Aquí está el historial completo de tu cuenta, venga del checkout o de una tarjeta guardada.

Estados

Campo	Tipo	Descripción
`APPROVED`	string	Cobrado. El dinero está en TipTap Go y entra a tu próxima liquidación. Es el único estado que significa “te pagaron”.
`PENDING`	string	El cliente está en medio del pago (por ejemplo, en la verificación 3DS del banco). Todavía no hay cargo.
`FAILED`	string	El banco rechazó la tarjeta o falló la verificación. Sin cargo.
`VOIDED`	string	Se autorizó pero lo anulamos nosotros (cupo del link agotado en una carrera, o autorización parcial). Al cliente no se le cobra.
`TIMEOUT`	string	El procesador no respondió a tiempo; mandamos una anulación defensiva. Sin cargo.

Solo APPROVED cuenta

Si tu sistema marca órdenes como pagadas, hazlo únicamente con APPROVED. Los demás estados existen para que puedas mostrarle al cliente qué pasó y para conciliar.

Listar pagos

GET/v1/payments

Filtros

Campo	Tipo	Descripción
`status`	string	APPROVED, PENDING, FAILED, VOIDED o TIMEOUT.
`payment_link_id`	string	Pagos de un link específico.
`customer_id`	string	Todos los cobros de un cliente, incluidos los de sus planes.
`created_after`	ISO-8601	Desde esta fecha (inclusive).
`created_before`	ISO-8601	Hasta esta fecha.
`limit · starting_after`	—	Paginación por cursor.

curl

curl "https://go.paytiptap.com/api/v1/payments?status=APPROVED&created_after=2026-07-01T00:00:00Z&limit=100" \
  -H "Authorization: Bearer tiptap_sk_TU_LLAVE"

Consultar un pago

GET/v1/payments/{id}

200 OK

{
  "object": "payment",
  "id": "cmqbbfsbd000fjy7yy29qmahh",
  "amount": 7.5,
  "currency": "USD",
  "status": "APPROVED",
  "payer": { "name": "Carlos Ruiz", "email": "carlos@ejemplo.com" },
  "customer_id": "cmqb2lvku000bjy9s7p3v071f",
  "payment_link": {
    "id": "cmqbbfpsc000djy7y33dylouo",
    "title": "Mensualidad julio",
    "url": "https://go.paytiptap.com/pay/odpDAk0FERxq"
  },
  "authorization_code": "202123",
  "processor_reference": "7812922904586158104805",
  "settlement_id": "cmqbds2xv0001jy9ang3a2wnw",
  "created_at": "2026-06-12T19:24:51.097Z"
}

Campo	Tipo	Descripción
`payer`	object	Nombre y correo que puso quien pagó. En cobros a tarjeta guardada, los datos del cliente.
`customer_id`	string \| null	El cliente asociado, si el cobro salió de un cliente o de un plan.
`authorization_code`	string \| null	Código de aprobación del banco. Útil para reclamos.
`processor_reference`	string \| null	Identificador de la transacción en el procesador. Es el número que pide el soporte del banco.
`settlement_id`	string \| null	La liquidación que incluyó este pago. `null` = todavía no te lo hemos transferido.

Conciliar con tu sistema

El patrón recomendado: escucha payment.succeeded para reaccionar en el momento, y una vez al día corre una conciliación que traiga los pagos del período y los cruce con tus órdenes. Así no dependes de que ningún webhook haya llegado.

Conciliación diaria (Node.js)

const desde = new Date(Date.now() - 24 * 3600 * 1000).toISOString();
const url = `https://go.paytiptap.com/api/v1/payments?status=APPROVED&created_after=${desde}&limit=100`;

const res = await fetch(url, {
  headers: { Authorization: `Bearer ${process.env.TIPTAP_API_KEY}` },
});
const { data } = await res.json();

for (const pago of data) {
  const ordenId = pago.payment_link?.id;   // o pago.metadata que guardaste en el link
  await marcarPagadaSiHaceFalta(ordenId, pago.id, pago.amount);
}

Devoluciones

Todavía no hay endpoint de devoluciones. Si necesitas devolverle a un cliente, escríbenos con el processor_reference del pago y lo procesamos; el ajuste se refleja en tu liquidación.

← Clientes y tarjeta guardada Liquidaciones y saldo →