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

{
    "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"
        }
    ]
}

Ejemplo

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}}'

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}}'

Última actualización