Proceso de Integración

BETA

La API de Pagos de Bold está diseñada con una arquitectura REST simple y poderosa. Utiliza URL predecibles orientadas a recursos, acepta cuerpos de solicitud en formato JSON y emplea verbos HTTP estándar para interactuar con tus aplicaciones de manera intuitiva. Además, garantiza respuestas en JSON bien estructuradas y utiliza códigos de estado HTTP convencionales para facilitar el manejo de errores y respuestas.

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

Crea una intención de pago

Este endpoint permite iniciar un proceso de pago creando una "intención de pago". Funciona como el primer paso en el flujo de procesamiento de pagos, donde registras los detalles de la transacción como el monto, la moneda, información del cliente y detalles del método de pago.

La intención de pago tiene un identificador único su reference_id que podrás utilizar para seguir y gestionar esta transacción a lo largo de su ciclo de vida.

Endpoint

POST /online/payment-intent

Solicitud

Datos necesarios para crear un intento de pago.

Esquema: PaymentIntent

Content-Type: application/json

{
  "reference_id": "ORD-12345",
  "amount": {
    "currency": "COP",
    "total_amount": 100000,
    "tip_amount": 10000,
    "taxes": [
      {
        "type": "VAT",
        "base": 5000,
        "value": 500
      }
    ]
  },
  "description": "Compra de productos electrónicos",
  "confirm": true,
  "callback_url": "https://mi-tienda.com/confirmacion-pago",
  "metadata": [
    {
      "key": "promo_code",
      "value": "DESCUENTO10"
    }
  ],
  "test": true,
  "customer": {
    "name": "Juan Pérez",
    "phone": "3001234567",
    "email": "juan.perez@example.com",
    "billing_address": {
      "street1": "Calle 123 #45-67",
      "street2": "Apto 202",
      "city": "Bogotá",
      "postal_code": "110111",
      "province": "Cundinamarca",
      "country_code": "CO",
      "phone": "3001234567"
    },
    "shipping_address": {
      "street1": "Carrera 98 #34-56",
      "street2": "Casa 5",
      "city": "Medellín",
      "postal_code": "050001",
      "province": "Antioquia",
      "country_code": "CO",
      "phone": "3012345678"
    }
  },
  "payment_method": {  //Ver lista de metodos de pago que se pueden usar para el pago.
    "type": "CREDIT_CARD",
    "card": {
      "brand": "VISA",
      "cardholder_name": "Jhon Doe",
      "exp_month": "12",
      "exp_year": "2035",
      "installments": 1,
      "card_number": "4111111111111111",
      "cvc": "123"
    },
    "billing_address": {
      "street1": "Calle 123 #45-67",
      "street2": "Apto 202",
      "city": "Bogotá",
      "postal_code": "110111",
      "province": "Cundinamarca",
      "country_code": "CO",
      "phone": "3001234567"
    }
  },
  "device_fingerprint": {
    "ip": "192.168.1.1",
    "device_type": "Smartphone",
    "os": "iOS 15.4",
    "browser": "Safari",
    "accept_header": "text/html,application/xhtml+xml",
    "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 15_4 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/15.0 Mobile/15E148 Safari/604.1",
    "java_enabled": false,
    "language": "es-CO",
    "color_depth": 24,
    "screen_height": 844,
    "screen_width": 390,
    "time_zone_offset": -300,
    "latitude": "4.6097100",
    "longitude": "-74.0817500",
    "model": "iPhone 13",
    "platform": "iOS"
  }
}

Respuestas

{
  "reference_id": "ORD-12345",
  "amount": {
    "currency": "COP",
    "total_amount": 100000,
    "tip_amount": 10000,
    "taxes": [
      {
        "type": "VAT",
        "base": 5000,
        "value": 500
      }
    ]
  },
  "description": "Compra de productos electrónicos",
  "creation_date": "192345678900",
  "status": "ACTIVE",
  "bold_transaction_id": "TXN1234567890",
  "callback_url": "https://mi-tienda.com/confirmacion-pago",
  "metadata": [
    {
      "key": "promo_code",
      "value": "DESCUENTO10"
    }
  ],
  "test": true,
  "customer": {
    "name": "Juan Pérez",
    "phone": "3001234567",
    "email": "juan.perez@example.com",
    "billing_address": {
      "street1": "Calle 123 #45-67",
      "street2": "Apto 202",
      "city": "Bogotá",
      "postal_code": "110111",
      "province": "Cundinamarca",
      "country_code": "CO",
      "phone": "3001234567"
    },
    "shipping_address": {
      "street1": "Carrera 98 #34-56",
      "street2": "Casa 5",
      "city": "Medellín",
      "postal_code": "050001",
      "province": "Antioquia",
      "country_code": "CO",
      "phone": "3012345678"
    }
  }
}
  • 400: Error de validación. 
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Obtener la información de una intención de pago

Este endpoint te permite consultar todos los detalles de una intención de pago previamente creada utilizando su referencia única reference_id.

Es útil para verificar el estado actual de un pago, confirmar los detalles del pedido o para mostrar información actualizada al cliente sobre su transacción en proceso.

Endpoint

POST /online/payment-intent/{reference_id} //Referencia de pago

Respuestas

{
  "reference_id": "ORD-12345",
  "amount": {
    "currency": "COP",
    "total_amount": 100000,
    "tip_amount": 10000,
    "taxes": [
      {
        "type": "VAT",
        "base": 5000,
        "value": 500
      }
    ]
  },
  "description": "Compra de productos electrónicos",
  "creation_date": "192345678900",
  "status": "ACTIVE",
  "bold_transaction_id": "TXN1234567890",
  "callback_url": "https://mi-tienda.com/confirmacion-pago",
  "metadata": [
    {
      "key": "promo_code",
      "value": "DESCUENTO10"
    }
  ],
  "test": true,
  "customer": {
    "name": "Juan Pérez",
    "phone": "3001234567",
    "email": "juan.perez@example.com",
    "billing_address": {
      "street1": "Calle 123 #45-67",
      "street2": "Apto 202",
      "city": "Bogotá",
      "postal_code": "110111",
      "province": "Cundinamarca",
      "country_code": "CO",
      "phone": "3001234567"
    },
    "shipping_address": {
      "street1": "Carrera 98 #34-56",
      "street2": "Casa 5",
      "city": "Medellín",
      "postal_code": "050001",
      "province": "Antioquia",
      "country_code": "CO",
      "phone": "3012345678"
    }
  }
}
  • 404: PaymentNotFound.

Actualizar la información de una intención de pago

Con este endpoint puedes modificar los datos de una intención de pago existente y aun no se haya pagado, como actualizar montos, información del cliente o cualquier otro parámetro relevante

Esto resulta especialmente útil cuando hay cambios en el pedido después de haber creado la intención inicial o cuando necesitas corregir información proporcionada anteriormente.

Endpoint

PUT /online/payment-intent

Solicitud

Datos necesarios para actualizar una intención de pago.

Esquema: PaymentIntent

Content-Type: application/json

{
  "reference_id": "ORD-12345",
  "amount": {
    "currency": "COP",
    "total_amount": 100000,
    "tip_amount": 10000,
    "taxes": [
      {
        "type": "VAT",
        "base": 5000,
        "value": 500
      }
    ]
  },
  "description": "Compra de productos electrónicos",
  "creation_date": "192345678900",
  "status": "ACTIVE",
  "bold_transaction_id": "TXN1234567890",
  "callback_url": "https://mi-tienda.com/confirmacion-pago",
  "metadata": [
    {
      "key": "promo_code",
      "value": "DESCUENTO10"
    }
  ],
  "test": true,
  "customer": {
    "name": "Juan Pérez",
    "phone": "3001234567",
    "email": "juan.perez@example.com",
    "billing_address": {
      "street1": "Calle 123 #45-67",
      "street2": "Apto 202",
      "city": "Bogotá",
      "postal_code": "110111",
      "province": "Cundinamarca",
      "country_code": "CO",
      "phone": "3001234567"
    },
    "shipping_address": {
      "street1": "Carrera 98 #34-56",
      "street2": "Casa 5",
      "city": "Medellín",
      "postal_code": "050001",
      "province": "Antioquia",
      "country_code": "CO",
      "phone": "3012345678"
    }
  }
}

Respuestas

{
  "reference_id": "ORD-12345",
  "amount": {
    "currency": "COP",
    "total_amount": 100000,
    "tip_amount": 10000,
    "taxes": [
      {
        "type": "VAT",
        "base": 5000,
        "value": 500
      }
    ]
  },
  "description": "Compra de productos electrónicos",
  "creation_date": "192345678900",
  "status": "ACTIVE",
  "bold_transaction_id": "TXN1234567890",
  "callback_url": "https://mi-tienda.com/confirmacion-pago",
  "metadata": [
    {
      "key": "promo_code",
      "value": "DESCUENTO10"
    }
  ],
  "test": true,
  "customer": {
    "name": "Juan Pérez",
    "phone": "3001234567",
    "email": "juan.perez@example.com",
    "billing_address": {
      "street1": "Calle 123 #45-67",
      "street2": "Apto 202",
      "city": "Bogotá",
      "postal_code": "110111",
      "province": "Cundinamarca",
      "country_code": "CO",
      "phone": "3001234567"
    },
    "shipping_address": {
      "street1": "Carrera 98 #34-56",
      "street2": "Casa 5",
      "city": "Medellín",
      "postal_code": "050001",
      "province": "Antioquia",
      "country_code": "CO",
      "phone": "3012345678"
    }
  }
}
  • 400: Error de validación. 
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}
  • 404: PaymentNotFound.

Realizar un intento de pago

Este endpoint ejecuta el procesamiento efectivo del pago utilizando los datos del método de pago seleccionado por el cliente.

Es el paso que realmente inicia la autorización y captura de fondos basado en una intención de pago existente. Dependiendo del método de pago utilizado, puede requerir acciones adicionales como redirecciones para autenticación o confirmación por parte del usuario.

Endpoint

POST /online/payment

Solicitud

Datos necesarios para crear un intento de pago.

Esquema: PaymentAttempt

Content-Type: application/json

{
  "reference_id": "ORD-123456",
  "metadata": [
    {
      "key": "campaign",
      "value": "black-friday"
    }
  ],
  "test": true,
  "payer": {
    "person_type": "NATURAL_PERSON",
    "name": "Laura Gómez",
    "phone": "3001234567",
    "email": "laura.gomez@example.com",
    "document_type": "CEDULA",
    "document_number": "1012345678",
    "terms_and_conditions": {
      "acceptance_date": "2025-02-17T15:18:22.671Z",
      "version": "string"
    },
    "data_treatment": {
      "acceptance_date": "2025-02-17T15:18:22.671Z",
      "version": "string"
    }
  },
  "payment_method": {  //Ver lista de metodos de pago que se pueden usar para el pago.
    "type": "CREDIT_CARD",
    "card": {
      "brand": "VISA",
      "cardholder_name": "Jhon Doe",
      "exp_month": "12",
      "exp_year": "2035",
      "installments": 1,
      "card_number": "4111111111111111",
      "cvc": "123"
    },
    "billing_address": {
      "street1": "Calle 123 #45-67",
      "street2": "Apto 202",
      "city": "Bogotá",
      "postal_code": "110111",
      "province": "Cundinamarca",
      "country_code": "CO",
      "phone": "3001234567"
    }
  },
  "device_fingerprint": {
    "ip": "192.168.1.1",
    "device_type": "Smartphone",
    "os": "iOS 15.4",
    "browser": "Safari",
    "accept_header": "text/html,application/xhtml+xml",
    "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 15_4 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/15.0 Mobile/15E148 Safari/604.1",
    "java_enabled": false,
    "language": "es-CO",
    "color_depth": 24,
    "screen_height": 844,
    "screen_width": 390,
    "time_zone_offset": -300,
    "latitude": "4.6097100",
    "longitude": "-74.0817500",
    "model": "iPhone 13",
    "platform": "iOS"
  }
}

Respuestas

{
  "transaction_id": "TXN0987654321",
  "next_action": { // Presente si existe una accion requerida para poder continuar con el pago como autenticacion o validacion de un tercero
    "redirect_url": "https://mi-banco.com/pago-pse",
    "redirect_method": "POST"
  },
  "status": "PROCESSING" // Estado actual de la transacción (siempre será PROCESSING en esta respuesta).
}
  • 400: Error de validación. 
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Obtener el estado de un intento de pago

Este endpoint te permite consultar el estado actual de un pago específico mediante su referencia única (reference_id). Proporciona información detallada sobre si el pago ha sido aprobado, rechazado o se encuentra en procesamiento, así como los detalles completos de la transacción.

Es complemento para actualizar tus sistemas internos y notificar al cliente sobre el resultado de su pago, recomendamos utilizarlo en conjunto con el webhook para recibir notificaciones en tiempo real.

Endpoint

POST /online/payment/{reference_id} //Referencia de pago

Respuestas

{
  "transaction_id": "TXN0987654321",
  "reference_id": "ORD-123456",
  "status": "APPROVED",
  "amount": {
    "currency": "COP",
    "total_amount": 100000,
    "tip_amount": 10000,
    "taxes": [
      {
        "type": "VAT",
        "base": 5000,
        "value": 500
      }
    ]
  },
  "payment_method": {  //Ver lista de metodos de pago que se pueden usar para el pago.
    "type": "CREDIT_CARD",
    "card": {
      "brand": "VISA",
      "cardholder_name": "Jhon Doe",
      "exp_month": "12",
      "exp_year": "2035",
      "installments": 1,
      "card_number": "4111111111111111",
      "cvc": "123"
    },
    "billing_address": {
      "street1": "Calle 123 #45-67",
      "street2": "Apto 202",
      "city": "Bogotá",
      "postal_code": "110111",
      "province": "Cundinamarca",
      "country_code": "CO",
      "phone": "3001234567"
    }
  },
  "payer": {
    "person_type": "NATURAL_PERSON",
    "name": "Laura Gómez",
    "phone": "3001234567",
    "email": "laura.gomez@example.com",
    "document_type": "CEDULA",
    "document_number": "1012345678",
    "terms_and_conditions": {
      "acceptance_date": "2025-02-17T17:43:17.531Z",
      "version": "string"
    },
    "data_treatment": {
      "acceptance_date": "2025-02-17T17:43:17.531Z",
      "version": "string"
    }
  },
  "sale_date": "2025-02-17T17:43:17.531Z",
  "metadata": [
    {
      "key": "campaign",
      "value": "black-friday"
    }
  ]
}
  • 404: PaymentNotFound.
Applink