Conecta tu Datafono Bold a la Aplicación de tu Comercio de Forma Sencilla

Para conectar el flujo de pagos de Bold con tu sistema, hemos desarrollado una integración vía API que te permitirá enlazar tu aplicación directamente con tus datáfonos Bold.

¿Qué es API Integrations?

Esta nueva funcionalidad te ofrece la capacidad de integrar fácilmente la creación y gestión de pagos en tu plataforma existente. Con esta API, se podrán automatizar procesos, personalizar la experiencia de pago y aprovechar al máximo las capacidades de nuestra plataforma.

¿Cómo funciona?

El proceso de integración se realiza a través de una API que permite la comunicación directa entre tu aplicación (web o mobile) y los datáfonos Bold. Cuando tu sistema envía una notificación a la API, esta se encarga de indicarle al datáfono que debe iniciar el proceso de pago. El datáfono recibirá la instrucción y comenzará automáticamente el flujo de cobro, ya sea con tarjeta o medios de pago alternativos. Todo ocurre de manera automatizada y en tiempo real, facilitando una experiencia de pago rápida y sin intervención manual desde el datáfono.

¿Cómo lo integro?

Para usar API Integrations, ten en cuenta las siguientes consideraciones:

• Tener una cuenta Bold habilitada
• Tener vinculado al menos un datáfono SmartPro a tu cuenta Bold.
• El datáfono debe estar encendido y con la aplicación abierta o en modo background.

A continuación, te guiaré para integrar API Integrations en tu sistema:

1. Seguridad

La API funciona bajo un esquema de seguridad utilizando una llave de identidad (API key), la cual deberá ser enviada en las cabeceras de cada petición.

¿Cómo acceder a tus llaves de integración?

Para poder integrar cualquiera de las soluciones de pagos de Bold en tu sitio web vas a necesitar primero unas Llaves de integración de API que son diferentes a las llaves de integración de Botón de pagos. Mediante estas llaves Bold identifica tu comercio y garantiza la integridad de tus transacciones.

Llave de identidad: Bold identifica tu comercio gracias a esta llave única (también llamada API key).

Si sospechas que alguien no autorizado dispone de esta llave, puedes solicitar la revocación de la misma escribiendo al correo de soporte: Soporte Bold. Sin embargo, ten en cuenta que esto generará una nueva llave, y deberás ajustar tu integración con la nueva llaves para que todo vuelva a funcionar con normalidad.

Llaves y ambientes Bold pone a tu disposición un ambiente de pruebas para que puedas integrar nuestras soluciones de pago sin tener que usar dinero real durante la fase de desarrollo. Para cada llave existe una versión de pruebas que puedes usar mientras te integras con Bold.

Consulta más detalles en la documentación del ambiente de pruebas.

Dónde obtengo mis llaves

Para obtener tus llaves de integración debes acceder a panel.bold.co (opens in a new tab) e iniciar sesión con la cuenta con la que se registró el comercio para el cual quieres hacer la integración.

Una vez hayas iniciado sesión deberás acceder a la sección Integraciones que encontrarás en el menú lateral (desplegable si accedes desde un dispositivo móvil).

La primera vez que accedas a esta sección (y si todavía no has solicitado tus llaves) deberás hacer clic en el botón Activar llaves para poder visualizarlas.

Tras presionar el botón deberías poder ver tras unos segundos las llaves para los tipos de integraciones soportadas, en este punto seleccionaremos API. Aquí podrémos encontrar las llaves de los ambientes de producción y pruebas

2. Autenticación de peticiones

Para autenticar tus peticiones, incluye la siguiente cabecera (header) en cada solicitud:

Asegúrate de reemplazar <llave de identidad> con la correspondiente a tu comercio.

Por ejemplo, si la llave de identidad es:

DZSkDqh2iWmpYQg204C2fLigQerhPGXAcm5WyujxwYH

Quedaría de la siguiente forma:

3. URL base

Todas las solicitudes a los servicios deben realizarse utilizando la siguiente URL base:

https://integrations.api.bold.co

Ten presente que, independientemente del ambiente que estés utilizando, pruebas o productivo, las respuestas seguiran la misma estructura.

4. Consulta de métodos de pago disponibles

Este servicio permite a los comercios consultar los métodos de pago habilitados. La solicitud se realiza mediante una petición GET al endpoint /payments/payment-methods. A continuación, se detalla la estructura de la respuesta.

Endpoint

GET /payments/payment-methods

Parámetros No se requieren parámetros adicionales en la solicitud GET.

Request

GET /payments/payment-methods
--header 'Authorization: x-api-key <llave_de_identidad>'

Respuesta La respuesta contiene un objeto payload que incluye la información sobre los métodos de pago disponibles para la integración.

{
    "payload": {
        "payment_methods": [
            {
                "name": "DAVIPLATA",
                "enabled": true
            },
            {
                "name": "NEQUI",
                "enabled": true
            },
            {
                "name": "PAY_BY_LINK",
                "enabled": true
            },
            {
                "name": "POS",
                "enabled": true
            }
        ]
    },
    "errors": []
}

Los posibles métodos son: POS para pago con tarjeta, NEQUI para pagos con Nequi mediante Push o QR, DAVIPLATA para pagos mediante la aplicación de Daviplata y PAY_BY_LINK para crear un link de pago y que tu cliente pueda realizar el pago en la web.

5. Consulta de terminales de pago disponibles

Este servicio permite a los comercios consultar las terminales (datáfonos) de pago habilitadas, actualmente se soportan terminales Smart Pro únicamente. La solicitud se realiza mediante una petición GET al endpoint /payments/binded-terminals. A continuación, se detalla la estructura de la respuesta.

Endpoint

GET /payments/binded-terminals

Parámetros No se requieren parámetros adicionales en la solicitud GET.

Request

GET /payments/binded-terminals
--header 'Authorization: x-api-key <llave_de_identidad>'

Respuesta La respuesta contiene un objeto payload que incluye la información sobre las terminales de pago disponibles para la integración.

{
    "payload": {
        "available_terminals": [
            {
                "terminal_model": "N86",
                "terminal_serial": "N860W000000",
                "status": "BINDED",
                "name": "SPRO0000"
            }
        ]
    },
    "errors": []
}

6. Creación de pagos mediante API

Para facilitar la creación de pagos a través de nuestra API, hemos diseñado una interfaz intuitiva que permite a los desarrolladores enviar solicitudes POST al endpoint /payments/app-checkout. A continuación, se detallan los parámetros requeridos y opcionales que pueden incluirse en la solicitud.

Endpoint

POST /payments/app-checkout

Parámetros

Obligatorios

Opcionales

Request

{
    "amount": {
        "currency": "COP",
        "taxes": [
            {
                "type": "VAT",
                "base": 10000,
                "value": 1000
            }
        ],
        "tip_amount": 0,
        "total_amount": 1230000
    },
    "payment_method": "POS",
    "terminal_model": "N86",
    "terminal_serial": "N860W000000",
    "reference": "d9b10690-981d-494d-bcb0-66a1dacab51d",
    "user_email": "vendedor@comercio.com",
    "description": "Compra de Prueba",
    "payer": {
        "email": "pagador@hotmail.com",
        "phone_number": "3100000000",
        "document": {
            "document_type": "CEDULA",
            "document_number": "1010140000"
        }
    }
}

El objeto taxes dentro de amount posee diferentes configuraciones validas, según las cuales se pueden enviar menos campos, permitiendo así una integración más sencilla. A continuación, se listan las diferentes opciones:

• Impuesto por etiqueta: Se puede enviar unicamente la etiqueta del impuesto que se quiere calcular con base en el total de la venta. Los valores disponibles son: IVA_19, IVA_5, IAC_8. Estos valores hacen referencia al IVA del 19% y del 5% y al impuesto al consumo del 8%, respectivamente. Cabe destacar que, en esta configuración, solo se permite especificar un impuesto. Ejemplo:

{
    "amount": {
        "currency": "COP",
        "taxes": [
            {
                "type": "IVA_19",
            }
        ],
        "tip_amount": 0,
        "total_amount": 1230000
    }
}

• Impuesto por valor: En este caso, solo es necesario especificar el tipo de impuesto VAT (para IVA) o CONSUMPTION (para impuesto al consumo), junto con el valor del impuesto, y nosotros nos encargaremos de calcular la base gravable. En este caso, puedes enviar un impuesto, o los dos. Ejemplo:

{
    "amount": {
        "currency": "COP",
        "taxes": [
            {
                "type": "VAT",
                "value": 1000
            },
            {
                "type": "CONSUMPTION",
                "value": 1000
            }
        ],
        "tip_amount": 0,
        "total_amount": 1230000
    }
}

Respuesta

Si la solicitud fue exitosa, se obtendrá un código HTTP 201 junto con la siguiente respuesta. El campo integration_id en la respuesta es un identificador único de la integración que se creó, por lo cual sirve para obtener soporte en caso de ser necesario.

{
    "payload": {
        "integration_id": "e1eeb06d-e2c4-461e-8346-f0982b4be1fc"
    },
    "errors": []
}

Seguimiento de la transacción

Con el Webhook de Bold, puedes recibir actualizaciones sobre el estado del pago iniciado mediante el API y acceder al valor de referencia asociado. Esto te permite seguir el flujo completo del pago, desde su inicio hasta conocer el estado de la transacción y tomar acciones correspondientes dentro de tu sistema en función de estos estados.

Posibles errores

A continuación, se detallan los códigos de error definidos, junto a una explicación, que te ayudará a identificar y corregir posibles fallos presentes durante la integración.