Referencia de la API

Todos los endpoints de la versión 1. Cada uno se explica en detalle en la sección correspondiente.

https://go.paytiptap.com/api/v1Bearer tiptap_sk_…Descargar OpenAPI

Cuenta

GET	/v1/me	Datos de la cuenta detrás de la API key.
GET	/v1/balance	Saldo: disponible, en camino y ya transferido.

Links de pago

POST	/v1/payment_links	Crea un link y devuelve su URL de cobro.
GET	/v1/payment_links	Lista links. Filtros: status, created_after/before.
GET	/v1/payment_links/{id}	Consulta un link.
POST	/v1/payment_links/{id}/cancel	Cierra el link para nuevos pagos.

Pagos

GET	/v1/payments	Historial. Filtros: status, payment_link_id, customer_id, fechas.
GET	/v1/payments/{id}	Consulta un pago con su referencia del procesador.

Clientes

GET	/v1/customers	Lista clientes. Filtros: phone, email, external_ref, status.
POST	/v1/customers	Crea un cliente (el celular es único).
GET	/v1/customers/{id}	Consulta un cliente y su tarjeta guardada.
PATCH	/v1/customers/{id}	Actualiza nombre, celular, correo, notas o estado.
POST	/v1/customers/{id}/charges	Cobra: tarjeta guardada al instante o link para pagar.

Liquidaciones

GET	/v1/settlements	Lista tus transferencias. Filtro: status.
GET	/v1/settlements/{id}	Detalle con los pagos incluidos.

Convenciones

Todos los objetos traen un campo object (account, payment_link, payment, customer, charge, settlement, balance, list).
Los campos van en snake_case; los ids son cadenas opacas — no asumas formato ni longitud.
Los montos son números decimales (no centavos) y las fechas ISO‑8601 en UTC.
Los listados devuelven { object: "list", data, has_more, next_cursor }.
Ignora los campos que no conozcas: podemos agregar campos nuevos sin cambiar de versión. No quitamos ni renombramos los existentes.

Reintentos sin cobrar dos veces

Si se te cae la red justo después de pedir un cobro, no sabes si pasó. Manda el header Idempotency-Key (una cadena única tuya, por ejemplo un UUID) y el reintento te devuelve el mismo cobro en vez de cobrarle otra vez a tu cliente. La respuesta repetida viene marcada con Idempotent-Replay: true.

bash

curl -X POST https://go.paytiptap.com/api/v1/customers/cus_123/charges \
  -H "Authorization: Bearer tiptap_sk_..." \
  -H "Idempotency-Key: 6f1c8a2e-4b7d-4a11-9d3e-2c9f0b5a7e18" \
  -H "Content-Type: application/json" \
  -d '{"amount": 29, "use_saved_card": true, "description": "Plan mensual"}'

La llave vale por ruta: la misma cadena en otro endpoint es otra operación.
Entre 8 y 255 caracteres. Si mandas el header con algo fuera de ese rango respondemos 400 invalid_idempotency_key en vez de cobrar sin protección: peor que no tenerla es creer que la tienes.
Reusarla con un cuerpo distinto responde 422 idempotency_key_reused — así no crees que cobraste $50 cuando te devolvimos el cobro de $29.
Un rechazo del banco también queda guardado en la llave: para volver a intentar el cobro de verdad, usa una llave nueva.
Si te respondemos 409 charge_unresolved, perdimos la conexión con el procesador y no sabemos si cobró. No lo damos por rechazado a propósito: reintentar con la misma llave te dirá lo mismo hasta que verifiques en GET /v1/payments.
Si te respondemos 409 idempotency_unresolved, la petición original se cortó a medias y no sabemos si el dinero se movió. Revisa GET /v1/payments antes de reintentar, y hazlo con una llave nueva: nunca reejecutamos un cobro por nuestra cuenta.

Especificación OpenAPI

Sirve para generar un cliente en tu lenguaje o para importarla en Postman / Insomnia:

bash

curl https://go.paytiptap.com/api/v1/openapi.json -o clara-openapi.json

Eventos de webhook

payment.succeeded, payment.failed, payment_link.completed, customer.created, settlement.created, settlement.paid. Ver webhooks.

← Webhooks