Integración con Banco Digital de los Trabajadores (BDT)

Esta guía describe cómo integrarse con el servicio de webhook del Banco Digital de los Trabajadores (BDT) para recibir notificaciones de transacciones bancarias.

Información General

Este webhook permite recibir notificaciones en tiempo real sobre transacciones realizadas a través del Banco Digital de los Trabajadores. El sistema procesa automáticamente estas transacciones y las registra en la plataforma.

Endpoint

URL: /V2/bank-transaction/webhook/bdt

Método: POST

Content-Type: application/json

Autenticación

El endpoint requiere autenticación mediante un token personalizado en el header x-token-partner.

Headers Requeridos

Nombre	Tipo	Descripción
Content-Type	String	Debe ser application/json
x-token-partner	String	Token para acceder al ambiente correspondiente

Tipos de Transacciones

El sistema soporta el siguiente tipo de transacción:

• P2C - Pago a Comercio (Person to Commerce)

Parámetros del Body

Campo	Tipo	Descripción
payment_type	String	Tipo de pago. En este caso, P2C.
reference	String	Referencia única de la transacción.
source_bank	String	Código del banco de origen.
amount	String	Monto de la transacción en formato decimal.
source_phone	String	Teléfono asociado a la cuenta de origen (formato internacional).
payment_date	String	Fecha y hora del pago en formato YYYY-MM-DD HH:mm:ss
source_account	String	Número de cuenta de origen (puede estar vacío).
document	String	Documento del remitente (como cédula o identificación).
description	String	Descripción o nota sobre el pago.

Ejemplo de Body

{
    "payment_type": "P2C",
    "reference": "663040991",
    "source_bank": "0175",
    "amount": "500.00",
    "source_phone": "04142778519",
    "payment_date": "2024-07-10 08:30:00",
    "source_account": "",
    "document": "V22102546",
    "description": "Pago de prueba"
}

Ejemplo con cURL

curl -X POST "{{Ambiente}}/V2/bank-transaction/webhook/bdt" \
  -H "Content-Type: application/json" \
  -H "x-token-partner: <TOKEN>" \
  -d '{
    "payment_type": "P2C",
    "reference": "663040991",
    "source_bank": "0175",
    "amount": "500.00",
    "source_phone": "04142778519",
    "payment_date": "2024-07-10 08:30:00",
    "source_account": "",
    "document": "V22102546",
    "description": "Pago de prueba"
  }'

Respuestas del Servidor

Respuesta Exitosa (200 OK)

Cuando la transacción se procesa correctamente:

{
  "success": true,
  "data": {
    // Información de la transacción procesada
  }
}

Respuesta de Error (4xx o 5xx)

Cuando ocurre un error en el procesamiento:

{
  "success": false,
  "error": {
    // Descripción del error
  }
}

Consideraciones Importantes

1. Idempotencia: El sistema es idempotente. Si se envía la misma transacción múltiples veces, solo se procesará la primera vez.

2. Manejo de Errores: En caso de error, el sistema retornará un código de estado HTTP apropiado junto con la descripción del error.

3. Timeout: Se recomienda configurar un timeout adecuado en las peticiones (mínimo 30 segundos).

4. Formato de Datos: Asegúrese de enviar los datos en el formato especificado, especialmente las fechas y montos.

Soporte

Para cualquier duda o problema con la integración, por favor contacte al equipo de desarrollo proporcionando:

• Tipo de transacción que se intenta enviar
• Código de error recibido (si aplica)
• Body de la petición (sin datos sensibles)
• Timestamp de la petición