Actualizar cobro

Modifica o habilita un cobro previamente creado. Además, al habilitar el cobro, tendrás la opción de determinar si deseas enviar una notificación al usuario.

Ruta

PATCH /v1/merchant/transaction/{external_reference}

Encabezado

Name	Value
Content-Type*	application/json
x-auth-token*	{token}

Cuerpo

Al actualizar o activar esta transacción, puedes completar o cambiar los siguientes campos. Ten en cuenta que los nuevos valores reemplazarán los anteriores, por lo que se perderá la información anterior.

Es importante destacar que los campos: payer_email ypayer_phoneno son modificables. Si envías información para estos campos, se creará un nuevo usuario con los datos proporcionados.

Información general

Name	Type	Description
description	string	Proporciona detalles clave sobre la transacción y es lo que se refleja en los comprobantes de pago. Ejemplo: Servicio de entrega
currency	string	Código que identifica la divisa del pago en formato ISO 4217. COP | USD | MXN
amount	numeric	Es el código generado a partir del proceso de autenticación. Ejemplo: 54000
status	string	Es el estado de la transacción al momento de creación. Para más información de los estados. pending | unlimit | scheduled | created
reference_one reference_two reference_three reference_four reference_five reference_six reference_seven reference_eight	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 | link | email
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
expected_amount	numeric	Es el valor esperado de la transacción. Ejemplo: 10000
expected_date	date	Es la fecha estimada de finalización de la transacción. Formato: AAAA/MM/DD Ejemplo: 2025/01/30
reminder_date	date	Es la fecha en la que quieres enviarle un recordatorio de pago al cliente. Formato: AAAA/MM/DD Ejemplo: 2025/01/30
limit_date	date	Es la fecha en la que vence el pago para el cliente. Solo aplica cuando status es igual scheduled. 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 cliente al que se enviarán las notificaciones. Ejemplo: [email protected]
user_notification	boolean	Define si se quiere enviar una notificación del cobro al usuario. Por defecto el valor es true. true | false
process_type	string	Método que se usará para el proceso de cobro. Según el método utilizado, el estado de la transacción se ajusta automáticamente. En el caso de cash, el estado se convierte en REVIEW, para digital en PENDING, para credit en CREDIT, para return_pending en RET_PENDING y para return_success en RET_SUCCESS. cash | digital | credit | return | express | split | direct | external
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.

Si el campo user_notification está establecido como true, se enviará la notificación solo si el campo channel está configurado como whatsapp o email. Además, cuando el canal es whatsapp, el campo payer.phone es obligatorio, y cuando el canal es email, el campo payer.email es obligatorio.

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.

Pagos en devolución

Este objeto es obligatorio cuando el process type sea return.

Name	Type	Description
return.type*	string	Tipo de devolución. Si se selecciona pending, el estado se actualiza a RET_PENDING y debe ser aprobado manualmente desde el dashboard para cambiar a RET_SUCCESS. En cambio, si se selecciona success, el estado se establece directamente como RET_SUCCESS. pending | success
return.reason*	string	Razón de la devolución. Ejemplo: No se encontró el cliente

Pagos express

Este objeto es obligatorio cuando el process type sea express.

Name	Type	Description
express.method*	string	Método de pago. En el caso de qr, la respuesta incluirá el enlace de la imagen QR en el campo qr_url. nequi| daviplata | qr
express.reference	string	Identificador del usuario al que se le realizará el cobro. Para Nequi, debe ser el número de celular; mientras que para Daviplata, debe ser el número de documento con el que el usuario se registró en la aplicación. Obligatorio en caso del que el method sea nequi o daviplata. Ejemplo: No se encontró el cliente

Pagos externos

Este objeto es obligatorio cuando el process type sea external.

Name	Type	Description
external.reason*	string	Razón por el cual es un pago externo. Ejemplo: Pago directo

Pagos divididos

Array de objetos, es obligatorio cuando el process type sea split. El objeto se compone de la siguiente manera:

Name	Type	Description
split[].amount*	numeric	Fracción o monto del pago que se va a realizar. Ejemplo: 5000
split[].payment_method*	string	Medio de pago a través del cual se realizará la fracción del pago. cash | digital | credit | return | express | direct | external
split[].return	objeto	El objeto se compone de la misma manera que return: Pagos en devolución Obligatorio en caso del que el payment_method sea return.
split[].express	objeto	El objeto se compone de la misma manera que express: Pagos express Obligatorio en caso del que el payment_method sea express.
split[].external	objeto	El objeto se compone de la misma manera que external: Pagos externos Obligatorio en caso del que el payment_method sea external.

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

Array de objetos, para aplicar recargos:

Name	Type	Description
late_fees[].action*	numeric	Valor correspondiente al recargo. Obligatorio en caso del que el condition_type sea fixed. add | edit | delete
late_fees[].id	string	Identificador que permite ubicar o referenciar el recargo que se va a actualizar. Obligatorio si el action es edit o delete. Ejemplo: a1b2c3
late_fees[].date	string	Fecha correspondiente al recargo. Obligatorio si el action es add. Formato: AAAA/MM/DD Ejemplo: 2025/01/30
late_fees[].value	string	Valor al cual se va actualizar el monto. Obligatorio si el action es add. Ejemplo: 1234.5
late_fees[].reminder	string	En caso de que se desee recibir una notificación en el momento en que se aplique el incremento.
late_fees[].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[].reminder_channel	array	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

Array de objetos, para aplicar pagos anticipados:

Name	Type	Description
advance_payment[].action*	numeric	Valor correspondiente al descuento. Obligatorio en caso del que el condition_type sea fixed. add | edit | delete
advance_payment[].id	string	Identificador que permite ubicar o referenciar el descuento que se va a actualizar. Obligatorio si el action es edit o delete. Ejemplo: a1b2c3
advance_payment[].date	string	Fecha correspondiente al descuento. Obligatorio si el action es add. Formato: AAAA/MM/DD Ejemplo: 2025/01/30
advance_payment[].value	string	Valor al cual se va actualizar el monto. Obligatorio si el action es add. Ejemplo: 1234.5
advance_payment[].reminder	string	En caso de que se desee recibir una notificación en el momento en que se aplique el incentivo.
advance_payment[].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[].reminder_channel	array	Canal por el cual se le va enviar la notificación. Obligatorio en caso del que el reminder sea true. whatsapp | email

Respuesta

200

{
    "message": "Succesfully Updated",
    "external_reference": "90d085",
    "link": "https://pago.qentaz.com/prueba/t/90d085",
    "created_at": "2024-08-26T20:46:25+00:00"
}

400

{
    "error": "The transaction cannot be modified because it is in an unmodifiable state (REVIEW). The transaction status must be one of the following: PENDING, UNLIMIT, PROCESSING, CREATED, SCHEDULED, OVERDUE."
}

401

{
    "status": "unauthorized",
    "code": "Q103",
    "error": "El x-auth-token se encuentra vencido. Por favor genera un nuevo token y reintenta de nuevo el cobro."
}

Ejemplo

cURL

curl --location --request PATCH '{{base_url}}/v1/merchant/transaction/{{reference}}' \
--header 'x-auth-token: token' \
--data '{
    "amount": 2000,
    "merchant_phone": "573112222222",
    "status": "CREATED",
    "channel": "WHATSAPP",
    "expected_amount": 2000,
    "expected_date": "10/03/2024",
    "reference_one": "REFERENCIA",
    "description": "Descripción de la transacción",
    "process_type": "CASH",
    "user_notification": false,
    "payer": {
        "phone": "573112222222"
    },
    "affiliate": {
        "id_type": "CC",
        "id_number": "34000000"
    }
}'

NodeJS (Axios)

const axios = require('axios');
let data = JSON.stringify({
  "amount": 2000,
  "merchant_phone": "573112222222",
  "status": "CREATED",
  "channel": "WHATSAPP",
  "expected_amount": 2000,
  "expected_date": "10/03/2024",
  "reference_one": "REFERENCIA",
  "description": "Descripción de la transacción",
  "process_type": "CASH",
  "user_notification": false,
  "payer": {
    "phone": "573112222222"
  },
  "affiliate": {
    "id_type": "CC",
    "id_number": "34000000"
  }
});

let config = {
  method: 'patch',
  maxBodyLength: Infinity,
  url: `${base_url}/v1/merchant/transaction/${reference}`,
  headers: { 
    'x-auth-token': token //Agregar el token
  },
  data : data
};

axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});

Python

import requests
import json

url = f"{base_url}/v1/merchant/transaction/{reference}" #Agregar base_url y reference

payload = json.dumps({
  "amount": 2000,
  "merchant_phone": "573112222222",
  "status": "CREATED",
  "channel": "WHATSAPP",
  "expected_amount": 2000,
  "expected_date": "10/03/2024",
  "reference_one": "REFERENCIA",
  "description": "Descripción de la transacción",
  "process_type": "CASH",
  "user_notification": False,
  "payer": {
    "phone": "573112222222"
  },
  "affiliate": {
    "id_type": "CC",
    "id_number": "34000000"
  }
})
headers = {
  'x-auth-token': token #Agregar token
}

response = requests.request("PATCH", url, headers=headers, data=payload)

print(response.text)

---

Caso de uso

Actualizar cobro con notificación en WhatsApp (con datos de usuario)

curl --location --request PATCH '{base_url}/v1/merchant/transaction/be83f3' \
--header 'x-auth-token: {token}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "amount": 20900,
    "currency": "COP",
    "description": "Servicio de consultoría",
    "reference_one": "Mayo 2023",
    "reference_two": "FT1235",
    "reference_three": "Prueba 2",
    "reference_four": "C3D4",
    "channel": "whatsapp",
    "status": "pending",
    "merchant_phone": 573999999999,
    "return_url": "https://minegocio.com/resultado",

    "payer": {
        "first_name": "Prueba",
        "user_id_type": "CC",
        "user_id_number": "99999999"
    },
    
    "user_notification": true
}'

Actualizar cobro a programado con notificación en correo (sin datos de usuario)

curl --location --request PATCH '{base_url}/v1/merchant/transaction/be83f3' \
--header 'x-auth-token: {token}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "amount": 34600,
    "currency": "COP",
    "description": "Servicio de consultoría",
    "reference_one": "Junio 2023",
    "reference_two": "FT4679",
    "reference_three": "Test",
    "reference_four": "E5F6",
    "channel": "email",
    "status": "scheduled",
    "merchant_phone": 573999999999,
    "return_url": "https://minegocio.com/resultado",
    
    "reminder_date": "10/31/2023",
    "limit_date": "11/05/2023",
    
    "user_notification": true
}'

---