¿Qué es el ambiente de pruebas de API Integrations?

Esta funcionalidad de API Integrations permite simular, probar y verificar el funcionamiento de tu integración, creando transacciones y obteniendo notificaciones en el Webhook sin necesidad de utilizar dinero real.

¿Cómo funciona?

Similar al funcionamiento de API Integrations, la integración se realiza mediante el uso de una llave de identidad, que permite la autenticación frente al sistema de Bold, y a su vez, identificar la intención de utilizar el ambiente de pruebas.

¿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. 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). Para que la transacción que estés realizando se haga en el ambiente de pruebas, tienes que seleccionar la llave de identidad que se encuentre en la sección Llaves de 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 al ambiente de pruebas de 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. Los medios de pago habilitados para el ambiente de pruebas son los mismos que tengas activos en el ambiente productivo. 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. Los terminales disponibles para el ambiente de pruebas son los mismos que tengas disponibles en el ambiente productivo. 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. Recuerda incluir tu llave de identidad de prueba para iniciar el flujo dentro de este ambiente.

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 ambiente de pruebas te permite simular que respuesta quieres obtener a la transacción según el valor de esta, es decir, lo que envíes en el campo total_amount. A continuación, se muestran los rangos y/o valores juntos con la respuesta que obtendras al momento de finalizar el flujo de la transacción dentro del ambiente de pruebas:

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": []
}

¿Cómo identificar el ambiente de una transacción?

Con el fin de facilitar y dar a conocer el ambiente que estas utilizando al momento de realizar una transacción, se agregó una marcación dentro del flujo en el datáfono, que te indicará si la transacción que estás realizando es de pruebas. Esta marcación se mostrará durante todo el flujo del pago, desde el inicio hasta que obtienes el recibo con el estado de la transacción.

El recibo luce de la siguiente manera:

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. Ten presente que deberás tener configurado el Webhook catalogado como Sandbox, ya que las notificaciones del ambiente de pruebas solo se enviarán a este.

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.