Skip to main content

​
Descripción

Los links de captura permiten obtener la información de un método de pago de un cliente sin que tengas que cumplir con la normativa PCI DSS. Cuando el cliente completa el formulario, OnePay envía este webhook con el identificador del método de pago capturado, para que puedas cobrarlo después sin volver a pedirle los datos. El evento se llama connect_link.completed y se genera una vez por cada formulario completado. El objeto event no incluye un identificador propio, así que para deduplicar hay que armarlo. No alcanza con connect_link.id: un link con single_use: false se puede completar muchas veces y todas las capturas comparten ese id, así que descartarlas por id te haría perder capturas legítimas. Usa connect_link.id junto con connect_link.completed, que es el número de captura y aumenta de a uno en cada una. Ese mismo campo te sirve para ordenar: si te llegan dos eventos del mismo link, el de completed más alto es el más reciente.
Cada entrega llega firmada. Antes de procesar el evento, verifica los headers como se explica en Autenticación de los eventos.

​
Los dos identificadores de cliente

El payload trae dos identificadores de cliente, y son cosas distintas. Es el punto que más confusión genera, así que conviene tenerlo claro antes de integrar:
Usa connect_link.customer_id en tus cobros siempre que lo tengas: es el cliente que tú registraste. Cuando el link se creó sin cliente —solo es posible desde el panel; la API exige customer_id— ese campo llega en null y el que debes usar es customer.id.
Que los dos identificadores no coincidan no es un error. El pagador puede elegir un método que ya tenía guardado contigo de un pago anterior, hecho a nombre de otro de tus clientes; en ese caso customer.id reporta ese cliente y no el que amarraste al link. El método sigue siendo cobrable: lo que POST /charges exige es que pertenezca a tu empresa.Si tu integración necesita que el método quede bajo un cliente concreto, compara los dos campos y actúa en consecuencia —no lo trates como una falla de la captura.

​
Qué identificador usar después

Una captura nueva no da de baja la anterior. Si el mismo cliente vuelve a completar un link, el método anterior sigue activo y cobrable.El payment_method.id que recibas puede ser el mismo de antes —si el pagador eligió un método que ya tenía guardado contigo— o uno nuevo, si volvió a ingresar los datos. Guarda siempre el del último evento, y si no quieres conservar el anterior, dalo de baja con DELETE /cards/{id} o DELETE /accounts/{id}.

​
Ejemplo

El payload real incluye además connect_link.company, con la configuración de tu empresa. Se omite en este ejemplo porque no lo necesitas para cobrar.

​
El objeto payment_method

Su forma depende de payment_method_type.

​
card

​
account

Una cuenta capturada con subtype: SAVINGS es una cuenta bancaria por riel ACH. No es lo mismo que una billetera enrolada: el enrolamiento de una billetera (Nequi, Daviplata) usa subtype: ELECTRONIC_DEPOSIT con el celular como número de cuenta, y requiere que el titular autorice la vinculación desde la app. Para capturar una billetera por link, habilita allows.wallets.

​
wallet