Saltar al contenido principal
  • Colombia
  • Español

    • Usa nuestra API de Pagos a Terceros

    1. Funcionamiento del API​

    Nuestra API de pagos resuelve este problema al ofrecer una herramienta robusta, optimizada para procesar pagos en tiempo real y adaptada a múltiples escenarios de negocio, buscando que nuestros clientes puedan realizar su dispersión de pagos desde plataformas o aplicaciones propias.

    El API de Pagos a Terceros de Wompi facilita la dispersión de pagos a cuentas bancarias en Colombia mediante la creación y gestión de lotes de pagos. Los usuarios pueden enviar pagos de manera individual o en lotes, utilizando archivos compatibles o mediante solicitudes JSON.

    • Contamos con un ambiente Sandbox para que los clientes puedan simular pagos, consultar respuestas, simular recargas de saldo de cuentas origen y validar reportes de pagos en ambiente de prueba.
    • El API permite utilizar múltiples cuentas origen: Wompi cuenta, cuentas Bancolombia y cuentas de otros bancos autorizados.
    • Se ha incorporado soporte de idempotencia para evitar la duplicidad de pagos.
    • Notificación de eventos mediante un webhook.
    • Adicionalmente, ofrecemos un Dashboard donde los clientes pueden:
      • Consultar trazabilidad de transacciones en producción.
      • Visualizar el debugger de los eventos API.
      • Descargar reportes de pagos procesados.

    2. Tipos de pagos disponibles a través del API​

    Nuestra API de dispersión de pagos ofrece flexibilidad para adaptarse a diferentes necesidades de negocio. A través de la integración, puedes realizar los siguientes tipos de pagos:

    Pagos inmediatos: Permite ejecutar una orden de pago en el momento en que se solicita. Ideal para operaciones que requieren procesamiento en tiempo real, como pagos a proveedores o desembolsos a usuarios finales.

    info

    Tener en cuenta los ciclos de procesamiento ACH y cuenta origen de la dispersión

    Pagos programados: Permite agendar pagos para que se procesen en una fecha específica futura. Esta funcionalidad es útil para planificar pagos de nómina, obligaciones recurrentes o pagos a terceros en fechas pactadas.

    Pagos recurrentes: Permite configurar pagos que se ejecuten de manera periódica (por ejemplo, semanal, quincenal o mensual). Esta opción es ideal para automatizar pagos recurrentes como membresías o servicios periódicos.

    Cada tipo de pago puede ser gestionado de manera sencilla a través de los endpoints de creación de órdenes de pago, definiendo los parámetros necesarios como el tipo de programación, la fecha deseada de ejecución y el detalle de los destinatarios.

    Nota

    Importante: Los pagos programados y recurrentes quedarán registrados en el sistema y serán ejecutados de acuerdo con la configuración establecida al momento de la creación. Consulta más adelante cómo realizar la configuración de cada tipo de pago.

    3. Flujo general para la integración​

    3.1. Autenticación​

    Obtener las llaves de autenticación (API Key y ID Usuario Principal) desde el dashboard de Wompi.

    Ver Llaves de autenticación

    3.2. Creación de Lote​

    • Pago uno a uno: Enviar una solicitud POST al endpoint /payouts con el detalle de las transacciones en formato JSON. Ver Crea tu primer lote
    • Pago mediante archivo: Enviar una solicitud POST al endpoint /payouts/file adjuntando un archivo en uno de los formatos soportados (WOMPI, SAP, PAB, DISFON, BANCO_OCCIDENTE_FC, DAVIVIENDA). Ver Crea un lote de pago por archivo

    3.3 Validación de los datos enviados:​

    Wompi valida los datos proporcionados y los envía a procesar.

    3.4 Procesamiento de los lotes de pago e inicio del proceso de pago​

    Wompi procesa las transacciones enviadas en los lotes y realiza el proceso de pago, utilizando el mismo banco o ACH según la cuenta seleccionada.

    3.5. Consultas y eventos del cambio de estado de las transacciones​

    Consultar el estado de los lotes y transacciones utilizando los endpoints proporcionados para obtener información detallada o la actualización de cada pago enviadas a través del webhook.

    Ver más sobre Consultas

    Ver más sobre Eventos

    3.6. Reportes:​

    Reportes consolidados por lotes y transacciones disponibles a través del API o el dashboard de Wompi.

    Ver más sobre Reportes

    4. Consideraciones generales​

    • Moneda: Todas las transacciones se realizan en pesos colombianos (COP).
    • Montos: Los montos se manejan en centavos y en formato entero, donde los dos ultimos digitos corresponden a los centavos Ej. 100000 equivalente a $1000,00
    • Llaves de Autenticación: Es esencial obtener las llaves de autenticación (API Key y ID Usuario Principal) desde el dashboard de Wompi para interactuar con el API. Ver Llaves de autenticación
    • Formatos de archivo soportados: Al crear lotes mediante archivos, el API está en la capacidad de soportar y traducir los siguientes formatos: Plantilla Wompi, PAB y SAP Bancolombia, DISFON Banco de Bogotá, Banco de Occidente FC, Davivienda.
    • Límites y restricciones: Existe un límite transaccional diario de $1.500.000.000 este límite se puede ampliar o disminuir si el cliente lo requiere. Existen restricciones en cuanto al número de lotes diarios que se pueden enviar por cliente el cual es de 3.800 lotes diarios, sin embargo, cada lote no tiene restricciones en cuanto al número de transacciones que puede contener. En caso de necesitar ajustar los límites, contáctate con soporte.
    • Idempotencia: Implementada para evitar pagos duplicados usando una llave unica generada por el cliente y que expira en 24 horas.
    • Sandbox: Entorno disponible para simular escenarios de prueba equivalente al entorno productivo.
    • Horarios de procesamiento: Los pagos se procesan en los horarios establecidos por Wompi y las entidades bancarias. Es recomendable consultar estos horarios para garantizar el procesamiento oportuno de las transacciones.

    Horarios procesamiento

    5. Datos requeridos para un pago​

    Al crear un lote de pagos, se deben proporcionar los siguientes datos para cada transacción:

    • legalIdType (String): Tipo de identificación del beneficiario (CC, NIT, CE).
    • legalId (String): Número de identificación del beneficiario.
    • bankId (UUID): Identificador único del banco, obtenido del endpoint /banks.
    • accountType (String): Tipo de cuenta bancaria (AHORROS, CORRIENTE).
    • accountNumber (String): Número de la cuenta bancaria. Debe contener solo números y ser diferente de cero.
    • name (String): Nombre completo del beneficiario.
    • email (String): Correo electrónico del beneficiario.
    • amount (Integer): Monto a transferir en centavos (por ejemplo, $10,000 COP se representa como 1000000).
    • reference (String): Referencia única para la transacción.
    • accountId (String): Identificador de la cuenta de origen, obtenido del endpoint /accounts.
    • paymentType (String): Tipo de pago (PAYROLL, PROVIDERS, OTHER).

    6. Tipos de cuenta bancaria​

    Los tipos de cuenta bancaria admitidos por el API son:

    • AHORROS: Cuenta de ahorros.
    • CORRIENTE: Cuenta corriente.

    7. Códigos de Bancos en Colombia​

    Para obtener la lista actualizada de bancos y sus identificadores únicos (bankId), se debe consultar el endpoint /banks proporcionado por Wompi.

    BancoCódigo
    BANCO DE BOGOTA1001
    BANCO POPULAR1002
    ITAU antes Corpbanca1006
    BANCOLOMBIA1007
    CITIBANK1009
    BANCO GNB SUDAMERIS1012
    BBVA COLOMBIA1013
    ITAU1014
    SCOTIABANK COLPATRIA S.A1019
    BANCO DE OCCIDENTE1023
    BANCOLDEX S.A.1031
    BANCO CAJA SOCIAL BCSC SA1032
    BANCO AGRARIO1040
    BANCO MUNDO MUJER1047
    BANCO DAVIVIENDA SA1051
    BANCO AV VILLAS1052
    BANCO W S.A1053
    BANCAMIA S.A1059
    BANCO PICHINCHA1060
    BANCOOMEVA1061
    BANCO FALABELLA S.A.1062
    BANCO FINANDINA S.A.1063
    BANCO SANTANDER DE NEGOCIOS CO1065
    BANCO COOPERATIVO COOPCENTRAL1066
    MIBANCO S.A.1067
    BANCO SERFINANZA S.A1069
    LULO BANK S.A.1070
    BANCO J.P. MORGAN COLOMBIA S.A1071
    FINANCIERA JURISCOOP S.A. COMP1121
    COOPERATIVA FINANCIERA DE ANTI1283
    JFK COOPERATIVA FINANCIERA1286
    COOTRAFA COOPERATIVA FINANCIER1289
    CONFIAR COOPERATIVA FINANCIERA1292
    BANCO UNION S.A1303
    COLTEFINANCIERA S.A1370
    NEQUI1507
    DAVIPLATA1551
    BANCO CREDIFINANCIERA SA.1558
    PIBANK1560
    IRIS1637
    MOVII1801
    DING TECNIPAGOS SA1802
    POWWI1803
    Ualá1804
    BANCO BTG PACTUAL1805
    BOLD CF1808
    NU1809
    RAPPIPAY1811
    COINK1812
    GLOBAL661814
    BANCO CONTACTAR S.A.1819

    8. Validaciones Bancarias​

    El número de cuenta debe ser numérico y tener entre 6 y 20 caracteres.

    • El código del banco debe ser válido y estar en la lista de bancos admitidos.
    • Los pagos a cuentas bloqueadas o inactivas serán rechazados.
    • El beneficiario debe coincidir con el titular de la cuenta en algunos bancos.
    • Validaciones de saldo y límites diarios antes de procesar el pago.

    9. Estados de Lotes y Transacciones​

    Estados de un lote​

    Estado lotes¿Es un estado final?Descripción
    PENDING_APPROVALPor aprobarNoEstado inicial del lote, que será revisado y aprobado / rechazado por parte del rol aprobador. Aplica a pagos creados solo desde el dashboard de Wompi.
    PENDINGEn procesoNoLote de pago aprobado por el rol aprobador, que está en proceso de ejecución.
    NOT_APPROVEDNo aprobadoNoLote de pago que ha sido rechazado por el rol aprobador.
    REJECTEDRechazadoSíLote de pago rechazado por incumplimiento de políticas, errores bancarios, errores del archivo o restricciones de cuenta.
    PARTIAL_PAYMENTPago parcialNoSe da cuando un lote de pagos contiene transacciones en diferentes estados, algunas ya finalizadas y otras aun en proceso.
    TOTAL_PAYMENTProcesadoSíTodas las transacciones del lote han sido gestionadas y cuentan con un estado final, ya sea aprobado o rechazado.

    Estados de Transacción:​

    Estado transacciones¿Es un estado final?Descripción
    PENDINGEn procesoNoLa transacción está en trámite o pendiente de ser aplicada en la cuenta del beneficiario.
    APPROVEDPagadoSiLa transacción se aplicó exitosamente en la cuenta del beneficiario.
    CANCELLEDCanceladoSiLa transacción no fue procesada y debe ser cargada nuevamente. Se genera cuando el aprobador rechaza el pago.
    FAILEDRechazadoSiLa transacción no se acreditó al beneficiario debido a información incorrecta o restricciones en la cuenta destino.

    10. Causales de rechazo más comunes​

    CodigoDescripciónEstado
    D02Banco no existeFAILED
    D04Tipo transacción invalidoFAILED
    D06Oficina pago no numéricaFAILED
    D07Numero cuenta no existeFAILED
    D09Código referencia no numéricoFAILED
    D10Cuenta no autorizada para acreditarFAILED
    D11Cuenta Nit no correspondenFAILED
    D12Nit proveedor no inscrito para pagosFAILED
    D14Valor errado en transacción no monetariaFAILED
    D15Pago cheque o efectivo no permitidoFAILED
    D18Nit no numéricoFAILED
    D19Fondos insuficientesFAILED
    D21Falta nombre beneficiarioFAILED
    D24Valor 0 en destinoFAILED
    D25Nit en cerosFAILED
    D29Nit pagador no inscrito servicio tarjetasFAILED
    D30Transacción no válida para clase de pagoFAILED
    D31Estado cuenta pensión canceladaFAILED
    D32Código de banco no numéricoFAILED
    D33Código banco en cerosFAILED
    D34Número de cuenta no numéricoFAILED
    D35Fecha de aplicación invalidaFAILED
    D37Oficina no validaFAILED
    D39Tipo identificación invalidoFAILED
    D40Oficina no autorizada para transacciónFAILED
    D41Pago sin cedula de autorizadoFAILED
    D44Pensionado no inscrito para la entidadFAILED
    D45Cuenta pensión no inscrita para entidad pagadoraFAILED
    D49Código de banco no permitidoFAILED

    Inicio rápido.Widget & Checkout Web

    Copyright © 2023 Wompi