Consulta por párametros

Esta consulta permite filtrar dispersiones del comercio de acuerdo a los diferentes parámetros definidos en cada solicitud. Es factible combinar más de dos parámetros en una única consulta.

Ruta

GET /v1/merchant/payout/

Encabezado

Name	Description
x-auth-token*	Es el código generado a partir del proceso de autenticación. Ejemplo: 8dsa819dj736f1d87fdhd172f12ddw
Content-Type*	Es el tipo de contenido que se está enviando en la solicitud. Ejemplo: application/json

Párametros

Name	Type	Description
description	string	Detalles clave sobre la dispersión. Ejemplo: Servicio de entrega
currency	string	Código que identifica la divisa del pago en formato ISO 4217. COP | USD | MXN
amount	numeric	Monto exacto de la dispersión. Ejemplo: 54000
amount_<gt>	numeric	gt: Significa "mayor que" (greater than). lt: Significa "menor que" (less than). ge: Significa "mayor o igual que" (greater than or equal to). le: Significa "menor o igual que" (less than or equal to). Ejemplo: 50000
status	string	Es el estado de la transacción al momento de creación. created | pending | scheduled | processing | verifying | success
reference_one reference_two reference_three reference_four	string	Información adicional de la transacción (número de factura, ordenes de compra, categoría), visible para los usuarios. Ejemplo: FAC123
channel	string	Es la forma como se realiza el cobro. whatsapp | email | none
process_id	string	Es el identificador utilizado para hacer referencia a la transacción en el proceso de conciliación. Ejemplo: a1a2a-a3a4a
source	string	Hace referencia a la fuente o origen de la transacción, indicando cómo se inició o generó dicha operación. dashboard | api | inmediata | automated
merchant_phone	string	Número de celular del usuario que genera el cobro (incluir el código de área del país). Ejemplo: 573112229999
merchant_email	string	Correo del usuario al que se enviarán las notificaciones. Ejemplo: [email protected]
merchant_id_number	string	Número del documento de identificación del usuario. Ejemplo: 10000000
receiver_phone	string	Número de celular del cliente (incluir el código de área del país) Ejemplo: 573112223333
receiver_email	string	Correo del cliente al que se enviarán las notificaciones. Ejemplo: [email protected]
receiver_id_number	string	Número del documento de identificación del cliente. Ejemplo: 10000000
created_at_start_date	date	Es la fecha de creación desde la cual se quiere realizar la consulta. Formato: MM/DD/AAAA Ejemplo: 10/20/2023
created_at_end_date	date	Es la fecha de creación hasta la cual se quiere realizar la consulta. Formato: MM/DD/AAAA Ejemplo: 10/20/2023
updated_at_start_date	date	Es la fecha de la última actualización desde la cual se quiere realizar la consulta. Formato: MM/DD/AAAA Ejemplo: 10/20/2023
updated_at_end_date	date	Es la fecha de la última actualización hasta la cual se quiere realizar la consulta. Formato: AAAA/MM/DD Ejemplo: 2025/01/30
bank_account_entity	string	Código que identifica a la entidad bancaria del destinatario. Ver cómo consultar códigos. Ejemplo: 1007
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.

Para los parámetros numéricos, utilizar el punto como separador decimal en caso de ser necesario.

Respuesta

200

{
    "payouts": [
        {
        "currency": COP,
        "amount": "10000.00",
        "description": "Pago de servicios externos",
        "reference_one": "Octubre",
        "reference_two": "A1234",
        "reference_three": "REF3",
        "reference_four": "REF4",
        "channel": "none",
        "type": "payout",
        "approval": "otp",
        "merchant_phone": "573998887777",
        "merchant_email": "[email protected]",
        "receiver": {
            "phone": "573778889999",
            "email": "[email protected]",
            "first_name": "Nombre",
            "last_name": "Apellido",
            "id_type": "CC",
            "id_number": "12345678"
                },
        "bank_account": {
            "entity": "1007",
            "type": "savings",
            "number": "12345678"
                },
        "created_at": "2023-12-21T18:41:48.106Z",
        "updated_at": "2023-12-21T18:41:49.348Z"
        }
    ]
}

400

404

Ejemplo

cURL

curl --location '{{base_url}}/v1/merchant/payout/?description=Dispersi%C3%B3n%20Prueba&currency=COP&amount_gt=500&amount_ge=800&status=CANCELED&reference_one=REF123' \
--header 'x-auth-token: {{token}}'

NodeJS (Axios)

Python

El request solo ejemplifica a partir de cuatro párametros. No obstante, es posible realizar el mismo con todos los filtros necesarios.

---

Casos de uso

¿Cuántas dispersiones se han completado hoy?

Usa la consulta por parámetros con filtros de fecha.

curl --location --request GET '{{base_url}}/v1/merchant/payout/?updated_at_start_date=01/20/2024' \
--header 'x-auth-token: {{token}}'

¿Cuántas veces ha dispersado a un usuario específico este mes?

Consulta con los parámetros de número celular o documento del cliente y fecha la fecha deseada.

curl --location --request GET '{{base_url}}/v1/merchant/payout/?receiver_phone=573111111111&created_at_start_date=01/20/2024' \
--header 'x-auth-token: {{token}}'

¿Cuál ha sido el método de pago más usado en las dispersiones exitosas?

Usa la consulta por parámetros con filtros como bank_account_number, bank_account_entity, entre otros.

curl --location --request GET '{{base_url}}/v1/merchant/payout/?status=success' \
--header 'x-auth-token: {{token}}'

---