Enlaces de pago

Incluye operaciones sensibles

Qué cubre#

Con este grupo el agente crea un enlace de cobro, consulta su detalle, lo borra y prepara el envío al cliente por WhatsApp o por correo. El envío por WhatsApp no manda el mensaje: devuelve un enlace listo para enviar.

Herramientas#

Crear cobro con enlace

Escritura

tilopay_create_charge

Crea un cobro y devuelve el enlace corto de Tilopay (tilo.co/s/…) que abre directo el formulario seguro de pago; si no está disponible, el enlace propio tilopay.shop/pagar/…. La respuesta trae url (la corta cuando exista) y fallback_url (la propia); ambas sirven. En WhatsApp envía de una vez el QR como imagen junto con el enlace; no llames la herramienta de QR después. Si faltan datos del cliente, la página del enlace los pide antes de cobrar.

Parámetros

Parámetro	Tipo	Obligatorio	Descripción
`amount`	number	sí	Monto a cobrar
`currency`	string	—	Moneda, ej. USD o CRC. Si se omite se usa la del país del comercio.
`reference`	string	sí	Referencia del cobro en texto normal, con espacios. No convertir a slug ni reemplazar espacios por guiones o guiones bajos.
`description`	string	sí	Concepto visible para el cliente. Conserva literalmente el texto del comercio con espacios, acentos y mayúsculas; por ejemplo 'prueba link', nunca 'prueba_link'.
`client`	string	—	Nombre del cliente
`client_email`	string	—	Correo del cliente
`client_phone`	string	—	Teléfono del cliente

Devuelve

{ code, url, fallback_url, orderNumber }

url = enlace corto (tilo.co/s/… o https://tilopay.shop/pagar/{code}); fallback_url = este último.

Detalle de un enlace de pago

Sólo lectura

tilopay_get_payment_link

Obtiene el detalle de un enlace de pago de Tilopay por su ID.

Operación del API: GET /api/v1/getDetailLinkPayment/{link_payment_id}/{api_key} — ver la página de la operación

Parámetros

Parámetro	Tipo	Obligatorio	Descripción
`linkPaymentId`	string	sí	ID del enlace de pago

Devuelve

{ result }

Respuesta cruda del API de Tilopay bajo la llave `result`.

Eliminar enlace de pago

Sensible

tilopay_delete_payment_link

Elimina un enlace de pago de Tilopay por su ID. Operación sensible: requiere segundo factor. Llámela primero sin `confirmation_code`: se envía un código de 6 dígitos al correo del comercio y la respuesta trae `requires_confirmation`. Repita la misma llamada agregando `confirmation_code`.

Exige confirmación: Confirmaciones que exige Tilopay

Operación del API: POST /api/v1/deleteLinkPayment — ver la página de la operación

Parámetros

Parámetro	Tipo	Obligatorio	Descripción
`id`	string	sí	ID del enlace de pago a eliminar
`confirmation_code`	string	—	Código de 6 dígitos recibido por correo para autorizar la operación

Devuelve

{ result }

Respuesta cruda del API de Tilopay bajo la llave `result`.

Enviar enlace de pago por WhatsApp

Escritura

tilopay_send_payment_link_whatsapp

Prepara el envío del enlace de pago por WhatsApp a un contacto: devuelve un enlace wa.me con el mensaje listo. Acepta el nombre de un contacto guardado o un teléfono.

Parámetros

Parámetro	Tipo	Obligatorio	Descripción
`link_url`	string	sí	URL del enlace de pago
`contact_name`	string	—	Nombre del contacto guardado o del cliente
`phone`	string	—	Teléfono de WhatsApp, ej. +50688887777
`amount`	number	—	Sólo se usa para redactar el mensaje; no cambia el enlace
`currency`	string	—	Sólo se usa para redactar el mensaje; no cambia el enlace
`description`	string	—	Sólo se usa para redactar el mensaje; no cambia el enlace
`message`	string	—	Texto propio del mensaje
`save_contact`	boolean	—	Guardar el contacto en la agenda
`send_now`	boolean	—	Obsoleto: se ignora. Siempre se devuelve el enlace wa.me para enviar con un toque.

Devuelve

{ to, message, whatsapp_url }

No envía el mensaje: devuelve el teléfono resuelto, el texto ya redactado y un enlace wa.me para enviarlo con un toque. Si no hay teléfono ni contacto guardado con ese nombre, devuelve error pidiéndolo. Guarda el contacto salvo que save_contact sea false.

Enviar enlace de pago por correo

Escritura

tilopay_send_payment_link_email

Envía el enlace de pago por correo electrónico al cliente. Acepta el nombre de un contacto guardado o un correo.

Parámetros

Parámetro	Tipo	Obligatorio	Descripción
`link_url`	string	sí	URL del enlace de pago
`email`	string	—	Correo del destinatario
`contact_name`	string	—	Nombre del contacto guardado o del cliente
`amount`	number	—	Sólo se usa para redactar el mensaje; no cambia el enlace
`currency`	string	—	Sólo se usa para redactar el mensaje; no cambia el enlace
`description`	string	—	Sólo se usa para redactar el mensaje; no cambia el enlace
`message`	string	—	Nota adicional para el cliente
`save_contact`	boolean	—	Guardar el contacto en la agenda

Devuelve

{ sent, to }

sent es true y to el correo al que se envió. Si no hay correo ni contacto guardado con ese nombre, devuelve error pidiéndolo.

QR de un enlace de pago o producto

Sólo lectura

tilopay_payment_link_qr

Genera el QR de un enlace de pago o de un producto del catálogo y lo envía como imagen (PNG) (el envío como imagen es solo en el Asistente de WhatsApp; en otros clientes se usa qr_url). Úsala cuando el comercio pida el QR para compartir o imprimir.

Parámetros

Parámetro	Tipo	Obligatorio	Descripción
`link_url`	string	—	Enlace de pago completo (https://...)
`catalog_id`	string	—	ID del producto del catálogo
`label`	string	—	Nombre para el pie de la imagen

Devuelve

{ link, qr_url }

link = enlace de pago; qr_url = imagen del código QR.

QR permanente de monto abierto

Sólo lectura

tilopay_static_payment_qr

Devuelve el enlace y el QR permanente de monto abierto del comercio (el cliente escanea, digita el monto y paga). Solo consulta: si el comercio no lo tiene activado, lo explica y no lo activa.

Parámetros

Sin parámetros.

Devuelve

{ enabled, link, qr_url }

enabled = si el QR estático está activo; link = enlace fijo del comercio; qr_url = imagen del código QR.

Última verificación: 2026-10-07

Ver como Markdown crudo