Pagos en línea
Integración vía API

Integración vía API

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

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.

Autenticación de peticiones

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

LlaveValor
Authorizationx-api-key <llave_de_identidad>

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:

LlaveValor
Authorizationx-api-key DZSkDqh2iWmpYQg204C2fLigQerhPGXAcm5WyujxwYH

URL base

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

https://integrations.api.bold.co

Funcionalidades y servicios

Consulta de métodos de pago con límites respectivos

Este servicio permite a los comercios consultar los métodos de pago habilitados y los montos permitidos respectivos. La solicitud se realiza mediante una petición GET al endpoint /online/link/v1/payment_methods. A continuación, se detalla la estructura de la respuesta.

Endpoint

GET /online/link/v1/payment_methods

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

Request

GET /online/link/v1/payment_methods

Respuesta La respuesta contiene un objeto payload que incluye la información sobre los métodos de pago disponibles y sus respectivos límites.

{
    "payload": {
        "payment_methods": {
            "CREDIT_CARD": {
                "max": 5000000,
                "min": 1000
            },
            "PSE": {
                "max": 5000000,
                "min": 1000
            },
            "BOTON_BANCOLOMBIA": {
                "max": 10000000,
                "min": 1000
            },
            "NEQUI": {
                "max": 10000000,
                "min": 1000
            }
        }
    },
    "errors": []
}

Creación de link de pago mediante API

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

Endpoint

POST /online/link/v1

Parámetros

Obligatorios

  • amount_type (tipo de monto): Este campo indica si el monto a pagar es abierto o cerrado. Dependiendo de esto, el tratamiento del monto será diferente.
    • OPEN (abierto): El pagador decide el monto que quiere pagar. En este caso, NO es obligatorio especificar el monto en los parámetros.
    • CLOSE (cerrado): El comerciante (merchant) establece el monto a pagar. Aquí, SI es obligatorio incluir el monto en los parámetros.

Opcionales

  • amount (monto): Un objeto que especifica el monto total de la transacción, incluidos impuestos y propinas. Si es monto abierto no es requerido este campo.
    • currency (moneda): La moneda en la que se realiza la transacción. Ejemplo: "COP".
    • taxes (impuestos): Esta sección muestra una lista de los impuestos que se aplican a la transacción. Los datos que puedes ingresar son:
      • type (tipo): Actualmente, solo aceptamos el IVA como impuesto, y se debe enviar utilizando la referencia VAT.
      • base (base): Este es el monto sobre el cual se aplicará el impuesto.
      • value (valor): Es el valor final del impuesto que se va a cobrar.
    • tip_amount (monto de propina): El monto de propina incluido en la transacción.
    • total_amount (monto total): El monto total de la transacción, incluidos impuestos y propinas.
  • description (descripción): Una descripción breve de la transacción. Ejemplo: "Compra de productos electrónicos". Esta descripción debe tener un minimo de 2 caracteres y máximo de 100 caracteres.
  • expiration_date (fecha de expiración): La fecha y hora en la que el link de pago expirará, representada en nanosegundos desde la época Unix.
  • callback_url (URL redirección): URL a la que redirigir al cliente tras finalizar una transacción. Debe ser una URL válida, debe iniciar con el protocolo https:// y a ser posible del dominio de tu negocio online.
  • payment_methods (métodos de pago): Este campo es una lista de los métodos de pago disponibles para la transacción, ver api listado de la consulta de métodos de pagos disponibles. Si no se incluye este parámetro en la solicitud, se mostrarán todos los métodos de pago disponibles ofrecidos por Bold. Ejemplo: ["CREDIT_CARD", "PSE", "BOTON_BANCOLOMBIA", "NEQUI"].
  • payer_email (correo del pagador): Correo al cual se le quiere enviar el link cuando se cree. Ejemplo: cliente@dominio.com.
  • image_url (URL de imagen): URL de la imagen del producto/servicio que se quiere mostrar al abrir el link de pago. Debe ser una URL válida, debe iniciar con el protocolo https:// y debe finalizar en .png o .jpg. Ejemplo: https://robohash.org/sad.png (opens in a new tab).

Ejemplo como generar fecha en formato Unix:

import time
 
current_nanoseconds = int(time.time() * 1e9)  # Convertir segundos a nanosegundos
ten_minutes_in_nanoseconds = 10 * 60 * int(1e9)  # 10 minutos en nanosegundos
future_nanoseconds = current_nanoseconds + ten_minutes_in_nanoseconds

Request

{
  "amount_type": "OPEN"
}

Respuesta

{
    "payload": {
        "payment_link": "LNK_H7S4xxx",
        "url": "https://checkout.bold.co/LNK_H7S4xxx"
    },
    "errors": []
}

Consulta de estado y datos del link de pago

Este servicio permite a los usuarios consultar el estado y los datos asociados a un link de pago específico. La consulta se realiza mediante una solicitud GET al endpoint /online/link/v1/{payment_link}, donde {payment_link} representa el identificador único del link de pago del cual se desea obtener información. A continuación, se detalla la estructura de la solicitud y la respuesta.

Endpoint

GET /online/link/v1/{payment_link}

Parámetros

  • payment_link: El identificador único del link de pago del cual se desea obtener información. Este parámetro debe ser pasado en la URL.

Request

GET /online/link/v1/LNK_H7S4XXXX

Respuesta

La respuesta de la API contendrá los datos asociados al link de pago consultado, incluyendo su estado actual y otros detalles relevantes.

  • api_version: La versión de la API utilizada. Ejemplo: "1.0".
  • id: El identificador único del link de pago. Ejemplo: "123456789".
  • total: El monto total de la transacción. Ejemplo: 150.00.
  • subtotal: El monto subtotal de la transacción, sin incluir propinas ni impuestos. Ejemplo: 130.00.
  • tip_amount: El monto de propina incluido en la transacción. Ejemplo: 5.00.
  • taxes: Esta sección muestra una lista de los impuestos que se aplican a la transacción. Los datos que puedes ingresar son:
    • type: Actualmente, solo aceptamos el IVA como impuesto, y se debe enviar utilizando la referencia VAT.
    • base: Este es el monto sobre el cual se aplicará el impuesto.
    • value: Es el valor final del impuesto que se va a cobrar.
  • status: Este indica la situación actual del link de pago. Los posibles estados son:
    • ACTIVE: El link está disponible para ser pagado. Esto puede suceder porque no se ha iniciado un pago o porque un pago anterior falló y el link está listo para ser usado nuevamente.
    • PROCESSING: El pago está en curso y aún no se ha completado la transacción.
    • PAID: El pago se ha realizado con éxito.
    • EXPIRED: El link está vencido y no puede ser pagado.
  • expiration_date: La fecha de expiración del link de pago, representada en un formato de tiempo UNIX. Ejemplo: 1627846267000.
  • creation_date: La fecha de creación del link de pago, representada en un formato de tiempo UNIX. Ejemplo: 1719242727607215713.
  • description: Una descripción breve o un mensaje asociado al link de pago. Ejemplo: "Compra de productos electrónicos".
  • payment_method: El método de pago utilizado para esta transacción. Ejemplo: "credit_card".
  • transaction_id: El identificador único de la transacción asociada a este link de pago. Ejemplo: "txn_001".
  • amount_type: Este campo indica si el monto es abierto (OPEN) o cerrado (CLOSE).
    • OPEN: El pagador decide el monto que desea pagar.
    • CLOSE: El comerciante establece el monto a pagar.
  • is_sandbox: Un indicador booleano que especifica si el entorno es de pruebas ("sandbox") o no. Ejemplo: true.
{
    "api_version": 1,
    "id": "LNK_H7S4XXXX",
    "total": 10000,
    "subtotal": 8403,
    "tip_amount": 0,
    "taxes": [
        {
            "type": "VAT",
            "base": 8403,
            "value": 1597
        }
    ],
    "status": "ACTIVE",
    "expiration_date": null,
    "creation_date": 1719242727607215713,
    "description": null,
    "payment_method": "PSE",
    "transaction_id": null,
    "amount_type": "CLOSE",
    "is_sandbox": false
}
info

El estado de las transacciones del link creado tambien se notifican al webhook que tengas configurado en el panel de comercios.

Flujo de trabajo

En los siguientes diagramas se muestra el flujo en alto nivel del funcionamiento de los diferentes servicios. Estos diagramas proporcionan una visión general del proceso de creación y consulta de links de pago mediante la API. A continuación, se detallan cada uno de los procesos involucrados:

Creación de link de pago

El proceso de creación de un link de pago permite a los comercios generar links que sus clientes pueden utilizar para realizar pagos. El flujo general es el siguiente:

  1. Solicitud de Creación: El comercio envía una solicitud POST a la API con los detalles del pago, como el monto, la descripción y los métodos de pago permitidos.
  2. Validación: La API valida los datos proporcionados y verifica la autenticidad de la solicitud utilizando la Llave de identidad.
  3. Generación del Link: Si la solicitud es válida, la API genera un link de pago único y lo asocia con los detalles de la transacción.
  4. Respuesta al Comercio: La API envía una respuesta al comercio con el link de pago generado y los detalles de la transacción.
Creación de Link

Consulta de link de pago

El proceso de consulta proporciona información actualizada sobre el estado y los datos asociados al link. El flujo general es el siguiente:

  1. Solicitud de Consulta: El comercio puede enviar una solicitud GET a la API para obtener el estado y los datos actuales del link de pago.
  2. Respuesta de Consulta: La API responde con los detalles actualizados del link, incluyendo el estado, el monto total, los métodos de pago y cualquier otra información relevante.
Consulta de Link

¡Felicidades! 🎉

Nos complace informarte que ahora tienes acceso a la API para la creación de links de pago. Esta poderosa herramienta te permitirá integrar de manera sencilla y eficiente la generación y gestión de links de pago en tus aplicaciones y plataformas existentes. Aquí tienes un resumen de lo que puedes hacer con nuestra API:

Características destacadas

  • Creación de Links de Pago: Genera links personalizados para tus transacciones de forma rápida y segura.
  • Consulta: Modifica los detalles de tus links de pago y consulta su estado y datos en cualquier momento.
  • Seguridad: Todas las operaciones están protegidas mediante autenticación por API Key para garantizar la seguridad de tus datos.

Con esta API, podrás optimizar tus procesos de pago, personalizar la experiencia de tus clientes y aprovechar al máximo las capacidades de nuestra plataforma. Estamos seguros de que esta herramienta será un gran valor añadido para tu negocio.

¡Estamos ansiosos por ver cómo aprovechas esta nueva herramienta para llevar tus operaciones al siguiente nivel!

Saludos cordiales,

El equipo de Online

Dudas de integraciónSeguimiento de transacciones