Generar dispersión

Realiza dispersiones a tus clientes, proveedores o colaboradores con la información que consideres necesaria, el canal de comunicación que desees usar y el tipo de dispersión que corresponda. A continuación encontrarás todos los parámetros necesarios para la generación de dispersiones.

Existen algunos campos que pueden completarse o modificarse al actualizar una dispersión, es importante tener en cuenta que, únicamente pueden actualizarse las dispersiones en estado created.

Ruta

POST /v1/merchant/payout

Encabezado

Name
Type
Description

x-auth-token*

string

Es el código generado a partir del proceso de autenticación.

Ejemplo: 8dsa819dj736f1d87fdhd172f12ddw

Content-Type*

string

Es el tipo de contenido que se está enviando en la solicitud.

Ejemplo: application/json

Cuerpo

Name
Type
Description

currency*

string

Código que identifica la divisa del pago en formato ISO 4217. COP | USD

amount*

numeric

Valor de la dispersión. No incluir decimales (comas o puntos).

Ejemplo: 54000

description*

string

Hace referencia a la descripción de la dispersión. Máximo 200 caracteres.

Ejemplo: Caja de chocolates x12 unidades, sabores variados.

reference_one reference_two reference_three reference_four

string

Información adicional de la dispersión (número de factura, ordenes de compra, categoría), visible para los usuarios.

Ejemplo: FT-2034

channel*

string

Es la forma como se notifica al usuario de la dispersión.

whatsapp | email | none

additional_channel

string

Es un canal adicional para notificar al usuario de la dispersión. whatsapp | email | none

additional_channel_value

string

El número de celular o correo electrónico según el additional_channel que se haya escogido. Obligatorio si existe additional_channel.

type*

string

Es el método que se usará para la dispersión.

normal | instant | scheduled

send_date

string

Es la fecha en la que se debe realizar la dispersión programada al destinatario.

Formato: AAAA/MM/DD Ejemplo: 2025/01/30

Obligatorio si el status es scheduled

attachment

string

Adjunto que funciona como soporte de la dispersión.

Información cliente/receptor

El objeto receiver es obligatorio. Cuenta con los siguientes campos:

Name
Type
Description

receiver.phone

string

Número de celular del destinatario (incluir el código de área del país)

Ejemplo: 573112223333

Obligatorio si channel es whatsapp o none.

receiver.email

string

Correo del destinatario al que se enviarán las notificaciones.

Ejemplo: [email protected]

Obligatorio si channel es email o si no existe receiver.phone.

receiver.first_name*

string

Nombres del destinatario. Ejemplo: Andrés

receiver.last_name

string

Apellidos del destinatario.

Ejemplo: Ramírez

receiver.id_type*

string

Tipo de documento de identificación del destinatario.

CC | CE | NIT | PASAPORTE | DNI | EIN

receiver.id_number*

string

Número del documento de identificación del destinatario.

Ejemplo: 11119999

Información del aprovador

El objeto approval es obligatorio. Cuenta con los siguientes campos:

Name
Type
Description

approval.type*

string

Tipo de autorización definida para la dispersión.

none | message | otp

approval.phone

string

Número de celular del usuario que va a aprobar la dispersión (incluir el código de área del país). El usuario debe tener rol admin o coordinator.

Ejemplo: 573112223333 Obligatorio si el approval.type es message. Solo se debe suministrar el approval.phone o el approval.email.

approval.email

string

Correo del destinatario que va a aprobar la dispersión. El usuario debe tener rol admin o coordinator.

Ejemplo: [email protected]

Obligatorio si el approval.type es message. Solo se debe suministrar el approval.phone o el approval.email.

Información del banco receptor

El objeto bank_account es obligatorio. Cuenta con los siguientes campos:

Name
Type
Description

bank_account.entity*

string

Código que identifica a la entidad bancaria del destinatario. Ver cómo consultar códigos.

Ejemplo: 1007

bank_account.type*

string

Tipo de cuenta a la que se va realizar la dispersión. savings | checking | agreement

[savings = ahorros checking = corriente agreement = convenio]

bank_account.number*

string

Número de cuenta a la que se va realizar la dispersión.

Ejemplo: 123456789

bank_account.reference

string

Referencia adicional para el pago en la entidad bancaria. Aplica únicamente para agreement.

Respuesta

{
    "external_reference": "c5f37bfe",
    "process_id": "eca33e56-3772-4f63-b7a0-0f1c65c6fffc",
    "channel": "EMAIL",
    "type": "NORMAL",
    "approval": "TOKEN",
    "created_at": "2024-08-27T14:25:32+00:00"
}

Ejemplo

curl --location '{{base_url}}/v1/merchant/payout/' \
--header 'x-auth-token: token' \
--data-raw '{
    "currency": "cop",
    "amount": 20000,
    "description": "PRUEBA",
    "reference_one": "Referencia 1",
    "reference_two": "Referencia 2",
    "reference_three": "Referencia 3",
    "reference_four": "Referencia 4",
    "channel": "email",
    "additional_channel": "whatsapp",
    "additional_channel_value": "573112222333",
    "type": "normal",
    "approval": {
        "type": "token"
    },
    "receiver": {
        "email": "[email protected]",
        "first_name": "Diego",
        "id_type": "CC",
        "id_number": "12345678999"
    },
    "bank_account": {
        "entity": "1023",
        "type": "savings",
        "number": "9876543210"
    }
}'

Última actualización