Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Términos de relevancia

Aquí encontrarás una explicación más detallada de los conceptos que te ayudarán a comprender mejor la documentación.

Tipos de dispersión

  1. Dispersion normal: Este método genera una dispersión que se completará según los tiempos estimados para una transferencia de acuerdo a los ciclos ACH. type: normal.

  2. Dispersion inmediata: Este método genera una dispersión que se procesará de forma inmediata, es decir, que se completará a mas tardar en una hora después de confirmada. type: instant.

  3. Dispersion programada: Programa dispersiones que deben realizarse en fechas posteriores a la actual. El valor se descontará de tu saldo. En caso de anulación, se reintegrará el saldo a tu cuenta. type: scheduled.

Las dispersiones tardan entre dos y tres ciclos ACH en reflejarse en la entidad bancaria del receptor, y entre cuatro y cinco ciclos en recibir la confirmación de la entidad receptora. Se recomienda que se realicen antes de las 12:30 PM para ser recibidas el mismo día hábil; de lo contrario, serán recibidas el siguiente día hábil.

Tipos de canales

Las dispersiones cuentan con tres canales de comunicación que puede ser usados según la necesidad del comercio:

  • Notificación por WhatsApp: envía una notificación de la dispersión a tus usuarios por medio de WhatsApp. El usuario recibirá los detalles y un comprobante para hacer el seguimiento a la misma. channel: whatsapp

  • Notificación por correo: notifica a tus usuarios de la dispersión por medio de correo electrónico. El usuario recibirá los detalles y un comprobante adjunto con los que podrá hacer el seguimiento a la misma. channel: email

  • Sin notificación: el usuario no recibirá ninguna notificación. channel: none

El destinatario puede recibir un mensaje inicial y/o final según las notificaciones definidas en el acuerdo comercial y la configuración de la cuenta.

Tipos de autorización

Las dispersiones deben autorizarse según el método vigente al momento de su generación. Si están programadas, la autorización se realizará al activarse la dispersión. Es fundamental ser cuidadoso con la autorización utilizada, ya que un manejo incorrecto puede comprometer la seguridad de las dispersiones y su dinero.

El objeto approval es obligatorio y define cómo se autorizará la dispersión previo al envío a la entidad bancaria:

  • NONE: Sin requerimiento de aprobación posterior. La dispersión se procesa de forma directa e inmediata. Ideal para integraciones automatizadas de confianza.

  • MESSAGE: Aprobación mediante código numérico OTP enviado al aprobador autorizador. La dispersión queda registrada bajo un identificador process_id en estado congelado (CREATED/PENDING) a la espera de ser confirmada consumiendo POST /v1/merchant/payout/confirm/message.

    • Jerarquía de Canal OTP: Si se envían approval.email y approval.phone simultáneamente, el sistema prioriza enviar el OTP por Correo Electrónico (email). Si sólo se envía approval.phone, se remite por WhatsApp.

  • TOKEN: Aprobación mediante token firmado JWT enviado al correo del autorizador (approval.email). La dispersión permanece congelada hasta que se confirme consumiendo POST /v1/merchant/payout/confirm.

Reglas de Validación del Aprobador (rol admin / coordinator)

Cuando se utiliza approval.type igual a MESSAGE o TOKEN:

  1. El teléfono (approval.phone, formato internacional sin '+' ej. 573001234567) o el email (approval.email) deben corresponder a un usuario (merchant) registrado y activo en la base de datos.

  2. El usuario aprobador debe pertenecer obligatoriamente al mismo comercio (payment_id) que origina la dispersión.

  3. El aprobador debe contar con rol admin o coordinator. De no cumplirse estos requisitos o si el aprobador no existe, la API devolverá HTTP 400 Bad Request.

Ten en cuenta que, al crear una dispersión, recibirás un evento (ver webhooks) con la información procesada. Solo en caso de seleccionar la autorización por token, recibirás un campo adicional con dicha información.

Tipos de estados

En Trazo, disponemos de diversos estados de transacción que determinan el comportamiento de una dispersión.

Estado
Descripción
Modificable

CREATED Creada

Cuando se inicia un proceso de dispersión normal o inmediata.

Si

SCHEDULED Programada

Cuando se inicia un proceso de dispersión programado para ser enviado en el futuro.

Si

PENDING Pendiente

Cuando la dispersión fue autorizada y el proceso está próximo a ejecutarse.

No

PROCESSING En proceso

Cuando se realizó el envío de la dispersión a la entidad del destinatario.

No

VERIFYING En confirmación

Cuando se estima que la dispersión debe haberse acreditado en la cuenta del destinatario pero se está esperando confirmación.

No

SUCCESS Exitosa

Cuando la dispersión ha sido completada/pagada.

No

CANCELED Cancelada

Cuando un miembro del equipo con el rol adecuado cancela la dispersión.

No

DECLINED Declinada

Cuando la entidad bancaria rechaza el pago y/o el sistema no encuentra alternativas para procesarlo.

No

BLOCKED Bloqueada

Cuando la dispersión ha sido bloqueado por sospecha de fraude.

No

Última actualización