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. Si deseas conocer como obtener tus llaves de integración puedes consultar esta documentación.

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

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 metodos 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 (datafonos) 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"
        }
    }
}

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.