Generar Cobro

Esta API permite crear y gestionar cobros de manera flexible, adaptándose a diferentes escenarios de pago: creados, programados y normales. Los cobros pueden personalizarse con reglas de vencimiento, recargos, descuentos anticipados y notificaciones automatizadas, garantizando una integración sencilla y escalable para el comercio. Es esencial que te asegures de generar un único cobro por cada venta, pedido o interacción con el cliente, según sea apropiado.

Ruta

POST /v1/merchant/transaction

Encabezado

Name
Value

Content-Type*

application/json

x-auth-token*

{token}

Cuerpo

Información general

Name
Type
Description

status

string

Es el estado del cobro al momento de creación. Para más información de los estados. created | pending | scheduled

currency*

string

Código que identifica la divisa del cobro en formato ISO 4217.

cop | usd

amount*

numeric

Es el importe final que se debe recibir por el producto o servicio ofrecido. Se debe emplear el punto como separador decimal.

ℹ️ El monto debe ser mayor a 0.

Ejemplo: 54000.85

description*

string

Proporciona detalles clave sobre el cobro y es lo que se refleja en los comprobantes de pago.

ℹ️ La descripción debe contener mínimo 5 caracteres. Ejemplo: Servicio de entrega

reference_one reference_two reference_three reference_four reference_five reference_six reference_seven reference_eight

string

Información adicional del cobro (número de factura, ordenes de compra, categoría), visible para los usuarios. Ejemplo: FAC123

channel

string

Es el canal por el que se notificará al cliente, bien sea el cobro o el comprobante de pago.

ℹ️ Por defecto es enlace de pago (link). whatsapp | link | email

user_notification

string

Define si se quiere enviar una notificación del cobro al usuario. Por defecto el valor es true.

ℹ️ Por defecto es false. Si el channel es link, no se enviará ninguna notificación. true | false

expected_amount

numeric

Es el valor esperado del cobro. Es un valor meramente informativo y no afecta en absoluto el proceso de cobro.

ℹ️ En caso de no suministrar ningún valor se asignara por defecto el amount. Ejemplo: 10000

expected_date

date

Es la fecha estimada de finalización de la transacción. Es un valor meramente informativo y no afecta en absoluto el proceso de cobro. Formato: AAAA/MM/DD Ejemplo: 2025/01/30

reminder_date

date

Corresponde a la fecha en la que quieres activar un cobro programado. Al activarse se envía una notificación al cliente. Formato: AAAA/MM/DD Ejemplo: 2025/01/30

limit_date

date

Es la fecha en la que vence el cobro para el cliente.

ℹ️ Si se quieren usar recargos o pagos anticipados, este campo es obligatorio. Formato: AAAA/MM/DD Ejemplo: 2025/01/30

merchant_id_number*

string

Número de documento del usuario que genera el cobro. Ejemplo: 100110000

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 que genera el cobro. Ejemplo: [email protected]

return_url

string

Es la url a la que quieres llevar al usuario después de completar el pago. Aplica para pagos por PSE o con link de pago. Ejemplo:https://minegocio.com/mi-aplicacion

expiration

boolean

Define si la transacción debe cancelarse al alcanzar la limit date. Por defecto, este valor es false.

attachment

string

Adjunto que funciona como soporte del cobro.

comments

string

Comentario opcional para tener como referencia al consultar las transacciones en el dashboard.

Solo es obligatorio uno de los campos: merchant_id_number, merchant_phone o merchant_email.

Información cliente/pagador

Name
Type
Description

payer.phone

string

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

Obligatorio en caso del que el channel sea whatsapp y el status no sea created. Ejemplo: 573112223333

payer.email

string

Correo del cliente al que se enviarán las notificaciones. Obligatorio en caso del que el channel sea email y el status no sea created. Ejemplo: [email protected]

payer.user_id_type

string

Tipo de documento de identificación del cliente. CC | CE | NIT | PASAPORTE | DNI | EIN

payer.user_id_number

string

Número del documento de identificación del cliente. Ejemplo: 11119999

payer.first_name

string

Primer nombre del cliente, el cual se usa para la validación del número de documento. Ejemplo: Andrés

Los campos: payer.user_id_type, payer.user_id_number y payer.first_name deben completarse de manera conjunta en la API. Esto significa que si se proporciona uno de estos campos, los otros dos también deben ser proporcionados. Son interdependientes y necesarios para garantizar la integridad de la información del usuario en la plataforma.

Información de afiliados

Name
Type
Description

affiliate.id_type

string

Tipo de documento de identificación del afiliado. CC | CE | NIT | PASAPORTE | DNI | EIN

affiliate.id_number

string

Número del documento de identificación del afiliado. Ejemplo: 11119999

Información de facturación

Name
Type
Description

invoice.provider

string

Agrega el software contable con el que realizaste la integración.

Obligatorio para el objeto invoice. alegra | siigo

invoice.type

string

Elige el tipo de vinculación que quieres realizar para esta transacción con tu software contable.

Obligatorio para el objeto invoice. link | balance | create

invoice.id

string

Corresponde al identificador de la factura o el cliente según el tipo de vinculación definido. Ejemplo: FV-2-1234 | GR1234 | 41515fb0-d815-40ac-86c0-4081eb642fa2

invoice.retentions

string

Solo si la vinculación es create, agregar las retenciones aplicables para la creación de la factura. Tener en cuenta que el valor de la factura será el valor de la transacción mas las retenciones definidas. Formato: enviar las retenciones separadas por comas Ejemplo: [1,2,3]

Información de recargos

Name
Type
Description

late_fees.condition_type

string

Tipo de recargo que se desea aplicar. En el caso de fixed, es posible personalizar completamente los periodos y los montos. Con la opción automated, los recargos se generan automáticamente a partir de los parámetros: type, value, frequency y limit. fixed | automated

late_fees.type

string

Tipo de incremento del valor. Selecciona amount si deseas sumar valores fijos, o percentage para aplicar incrementos porcentuales.

Obligatorio en caso del que el condition_type sea automated. amount | percentage

late_fees.value

string

Valor fijo o porcentual que se suma al monto. En el caso de porcentajes, deben expresarse en formato decimal (por ejemplo, 0.05 para un 5%).

Obligatorio en caso del que el condition_type sea automated. Ejemplo: 1234.5

late_fees.frequency

string

Frecuencia, en días, con la que se aplicará el aumento. El valor máximo permitido es de 30 días.

Obligatorio en caso del que el condition_type sea automated. Ejemplo: 3

late_fees.limit

string

Límite de veces que se aplicará el aumento. El valor máximo permitido es 30. Ejemplo: 5

late_fees.fixed

array

Corresponde a una lista de objetos que contienen los aumentos y sus fechas correspondientes.

Obligatorio en caso del que el condition_type sea fixed.

late_fees.fixed[].value

numeric

Valor correspondiente al aumento. Obligatorio en caso del que el condition_type sea fixed. Ejemplo: 5000

late_fees.fixed[].date

date

Fecha correspondiente al aumento. Obligatorio en caso del que el condition_type sea fixed. Formato: AAAA/MM/DD Ejemplo: 2025/01/30

late_fees.fixed[].reminder

boolean

En caso de que se desee recibir una notificación en el momento en que se aplique el recargo. Por defecto: false

late_fees.fixed[].reminder_template

string

Nombre del mensaje que se le envía para dicho recargo. Obligatorio en caso del que el reminder sea true.

late_fees.fixed[].reminder_channel

string

Canal por el cual se le va enviar la notificación. Obligatorio en caso del que el reminder sea true. whatsapp | email

Información de pagos anticipados

Name
Type
Description

advance_payment.condition_type

string

Tipo de incentivos que se desea aplicar. En el caso de fixed, es posible personalizar completamente los periodos y los montos. Con la opción automated, los descuentos se generan automáticamente a partir de los parámetros: type, value, frequency y limit. fixed | automated

advance_payment.type

string

Tipo de incentivo del valor. Selecciona amount si deseas sumar valores fijos, o percentage para aplicar descuentos porcentuales.

Obligatorio en caso del que el condition_type sea automated. amount | percentage

advance_payment.value

string

Valor fijo o porcentual que se resta al monto. En el caso de porcentajes, deben expresarse en formato decimal (por ejemplo, 0.05 para un 5%).

Obligatorio en caso del que el condition_type sea automated. Ejemplo: 1234.5

advance_payment.frequency

string

Frecuencia, en días, con la que se aplicará el descuento. El valor máximo permitido es de 30 días.

Obligatorio en caso del que el condition_type sea automated. Ejemplo: 3

advance_payment.limit

string

Límite de veces que se aplicará el descuento. El valor máximo permitido es 30. Ejemplo: 5

advance_payment.fixed

array

Corresponde a una lista de objetos que contienen los aumentos y sus fechas correspondientes.

Obligatorio en caso del que el condition_type sea fixed.

advance_payment.fixed[].value

numeric

Valor correspondiente al descuento. Obligatorio en caso del que el condition_type sea fixed. Ejemplo: 5000

advance_payment.fixed[].date

date

Fecha correspondiente al descuento. Obligatorio en caso del que el condition_type sea fixed. Formato: AAAA/MM/DD Ejemplo: 2025/01/30

advance_payment.fixed[].reminder

boolean

En caso de que se desee recibir una notificación en el momento en que se aplique el incentivo. Por defecto: false

advance_payment.fixed[].reminder_template

string

Nombre del mensaje que se le envía para dicho incentivo. Obligatorio en caso del que el reminder sea true.

advance_payment.fixed[].reminder_channel

string

Canal por el cual se le va enviar la notificación. Obligatorio en caso del que el reminder sea true. whatsapp | email

Respuesta

{
    "external_reference": "f6a886",
    "channel": "WHATSAPP",
    "link": "https://pago.trazo.co/prueba/t/a1a2a3",
    "process_id": "a1a2a3a4-a123-b456-c7890-b1b2b3b4b5b6",
    "created_at": "2024-08-26T21:07:23+00:00"
}

Ejemplo

curl --location '{{base_url}}/v1/merchant/transaction' \
--header 'x-auth-token: {{token}}' \
--header 'Content-Type: application/json' \
--data '{
    "status": "PENDING",
    "amount": 100000,
    "currency": "COP",
    "description": "Descripción Transacción",
    "reference_one": "Referencia 1",
    "reference_two": "Referencia 2",
    "reference_three": "Referencia 3",
    "reference_four": "Referencia 4",
    "reference_five": "Referencia 5",
    "reference_six": "Referencia 6",
    "reference_seven": "Referencia 7",
    "reference_eight": "Referencia 8",
    "return_url": "https://www.trazo.com",
    "channel": "WHATSAPP",
    "user_notification": "true",
    "merchant_phone": "573112223333",
    "reminder_date": "02/10/2025",
    "expected_date": "10/20/2025",
    "payer": {
        "phone": "573112223333"
    },
    "affiliate": {
        "id_number": "1234567890"
    },
    "invoice": {
        "provider": "siigo",
        "type": "link",
        "id": "FV-12-12345678"
    }
}'

Caso de uso

Cobro inmediato con notificación en WhatsApp (con datos de usuario)
curl --location --request POST '{base_url}/v1/merchant/transaction' \
--header 'x-auth-token: {token}' \
--header 'Content-Type: application/json' \

--data-raw '{
    "status": "created",
    "amount": 100000,
    "currency": "COP",
    "description": "Descripción Transacción",
    "reference_one": "Referencia 1",
    "reference_two": "Referencia 2",
    "reference_three": "Referencia 3",
    "reference_four": "Referencia 4",
    "reference_five": "Referencia 5",
    "reference_six": "Referencia 6",
    "channel": "whatsapp",
    "merchant_phone": "573112223333",
    "return_url": "https://www.qentaz.com/",
    "reminder_date": "02/10/2023",
   "expected_amount": 100000,
   "expected_date": "10/20/2023",
    "payer": {
        "phone": "573112223333"
    }
    
}'
Cobro sin vencimiento con notificación en correo (con datos de usuario)
curl --location --request POST '{base_url}/v1/merchant/transaction' \
--header 'x-auth-token: {token}' \
--header 'Content-Type: application/json' \

--data-raw '{
    "status": "unlimit",
    "amount": 100000,
    "currency": "COP",
    "description": "Descripción Transacción",
    "reference_one": "Referencia 1",
    "reference_two": "Referencia 2",
    "reference_three": "Referencia 3",
    "reference_four": "Referencia 4",
    "reference_five": "Referencia 5",
    "reference_six": "Referencia 6",
    "channel": "email",
    "merchant_phone": "573112223333",
    "return_url": "https://www.qentaz.com/",
    "reminder_date": "02/10/2023",
   "expected_amount": 100000,
   "expected_date": "10/20/2023",
    "payer": {
        "email": "[email protected]"
    }
    
}'
Cobro programado con notificación en correo (con datos de usuario)
curl --location --request POST '{base_url}/v1/merchant/transaction' \
--header 'x-auth-token: {token}' \
--header 'Content-Type: application/json' \

--data-raw '{
    "status": "unlimit",
    "amount": 100000,
    "currency": "COP",
    "description": "Descripción Transacción",
    "reference_one": "Referencia 1",
    "reference_two": "Referencia 2",
    "reference_three": "Referencia 3",
    "reference_four": "Referencia 4",
    "reference_five": "Referencia 5",
    "reference_six": "Referencia 6",
    "channel": "email",
    "merchant_phone": "573112223333",
    "return_url": "https://www.qentaz.com/",
    "reminder_date": "02/10/2023",
   "expected_amount": 100000,
   "expected_date": "10/20/2023",
    "payer": {
        "phone": "573112223333",
        "email": "[email protected]",
        "first_name": "Andrés",
        "user_id_type": "CC",
        "user_id_number": "123456789"
    }
    
}'

Última actualización