Esquema de datos
Aquí encontrarás los esquemas de datos utilizados en los procesos de pago y las interacciones con el sistema. Los esquemas detallan cómo se deben estructurar y manejar los diferentes tipos de información, como montos, métodos de pago, y datos de los usuarios, para garantizar una integración efectiva y sin problemas. Cada esquema incluye una descripción clara de los parámetros necesarios y sus valores posibles, asegurando que puedas implementar la funcionalidad de pago correctamente en tu plataforma.
Response
Define la estructura de una respuesta exitosa
| Parámetro | Tipo | Descripción | Enum/Restricciones |
|---|---|---|---|
| payload | object | Resultado de la petición | El objeto a retornar depende la petición realizada |
| errors | array | Lista de errores |
PaymentIntent
Define la estructura para crear una nueva intención de pago en el sistema. Incluye todos los parámetros necesarios para iniciar un proceso de pago, como los datos del cliente, información del monto, detalles de facturación y envío, y el método de pago.
| Parámetro | Tipo | Descripción | Enum/Restricciones | Requerido |
|---|---|---|---|---|
| reference_id | string | Identificador único de la referencia del pago | Ejemplo: “ORDER-999” | ✓ |
| amount | object | Información del monto | Amount | ✓ |
| expiration_date | string | Fecha de expiración de la intención de pago | Formato ISO 8601 Ejemplo: “2025-05-27T23:01:25-05:00” | |
| description | string | Descripción de la intención de pago | Ejemplo: “Pago de mi orden 999” | |
| metadata | object | Lista de metadatos clave-valor | Máximo 3 Ejemplo: {"custom-id":"id", "value":"123"} | |
| customer | object | Información del cliente | Customer | |
| payment_method | object | Método de pago | PaymentMethod | |
| callback_url | string | URL a la cual se redirige al pagador al finalizar la transacción en el banco | Requerido para los métodos de pagos PSE y Bancolombia. “https://example.com/finalizar-transaccion ” |
PaymentIntentResponse
Representa la respuesta del sistema al crear o consultar una intención de pago. Contiene información completa sobre el estado actual de la intención, incluyendo detalles de la transacción, información del cliente, datos de seguimiento y, si corresponde, el identificador de la transacción.
| Parámetro | Tipo | Descripción | Enum/Restricciones |
|---|---|---|---|
| reference_id | string | Identificador único de la referencia del pago enviado por el comercio | Ejemplo: “ORDER-999” |
| amount | object | Información del monto | Amount |
| description | string | Descripción de la intención de pago | Ejemplo: “Pago de mi orden 999” |
| creation_date | string | Fecha de creación del intento de pago | Formato ISO 8601 Ejemplo: “2025-05-27T23:01:25-05:00” |
| expiration_date | string | Fecha de expiración de la intención de pago | Formato ISO 8601 Ejemplo: “2025-05-27T23:01:25-05:00” |
| status | string | Estado de la intención de pago | [“ACTIVE”, “PROCESSING”, “PENDING”, “DISABLED”, “PAID”, “EXPIRED”] |
| status_detail | string | Descripción del estado del pago | ”Payment aprproved correctly” |
| bold_transaction_id | string | Id de la transacción de bold si esta ya se encuentra pagada | Ejemplo: “TXNMH97555” |
| callback_url | string | Url de redirección una vez realizado el pago | Ejemplo: “https://bold.co ” |
| metadata | object | Lista de metadatos clave-valor | Ejemplo: {"key":"custom-id", "value":"999"} |
| customer | object | Información del cliente | Customer |
PaymentAttempt
Describe la estructura de un intento de pago. Contiene toda la información necesaria para procesar una transacción, incluyendo la referencia única del pago, metadatos personalizados, información del pagador y detalles del método de pago seleccionado.
| Parámetro | Tipo | Descripción | Enum/Restricciones | Requerido |
|---|---|---|---|---|
| reference_id | string | Identificador único de la referencia del pago | Requerido. Ejemplo: “ORDER-999” | ✓ |
| metadata | object | Lista de metadatos clave-valor | Máximo 3 Ejemplo: {"custom-id":"id", "value":"123"} | |
| payer | object | Información del pagador | Payer | ✓ |
| payment_method | object | Método de pago utilizado | PaymentMethod | ✓ |
| device_fingerprint | object | Huella digital del dispositivo | DeviceFingerprint | ✓ Requerido para 3DS |
PaymentAttemptResponse
Esquema que representa la respuesta inmediata del sistema al realizar un intento de pago. Incluye el identificador único de la transacción, su estado inicial (siempre es “PROCESSING”) y, si es necesario, instrucciones para completar acciones adicionales requeridas, como redirecciones a plataformas bancarias.
| Parámetro | Tipo | Descripción | Enum/Restricciones |
|---|---|---|---|
| transaction_id | string | ID de transacción | Requerido. Ejemplo: “TXNFD76543” |
| next_actions | object | Acción requerida | Next Action Object |
| status | string | Estado de la transacción | [“APPROVED”, “REJECTED”,“RUNNING”] |
PaymentAttemptStatusResponse
Representa la respuesta del sistema al consultar el estado de un intento de pago. Proporciona información completa sobre el estado actual de la transacción, incluyendo si fue aprobada o rechazada, y todos los detalles relevantes de la operación.
| Parámetro | Tipo | Descripción | Enum/Restricciones |
|---|---|---|---|
| transaction_id | string | ID de transacción | Ejemplo: “TXNFD76543” |
| reference_id | string | ID de referencia | Ejemplo: “ORDEN-999” |
| status | string | Estado de la transacción | [“APPROVED”, “REJECTED”, “PROCESSING”, “PENDING”] |
| amount | object | Información del monto | Amount |
| payment_method | string | Método de pago usado | [Ejemplo : “CREDIT_CARD”] |
| payer | object | Información del pagador | Payer |
| attempt_date | string | Fecha de la transacción | |
| metadata | object | Lista de metadatos clave-valor | Ejemplo: {"key":"custom-id", "value":"999"} |
PaymentVoid
Define la estructura para anular un pago previamente realizado.
| Parámetro | Tipo | Descripción | Enum/Restricciones |
|---|---|---|---|
| transaction_id | string | ID de la transacción a anular | Requerido. Ejemplo: “TXNFD76543” |
PaymentRefund
Define la estructura para solicitar un reembolso de un pago previamente realizado.
| Parámetro | Tipo | Descripción | Enum/Restricciones |
|---|---|---|---|
| transaction_id | string | ID de la transacción a reembolsar | Requerido. Ejemplo: “TXN0987654321” |
| reference_id | string | Referencia del pago | Opcional. Si se envía junto con transaction_id, ambos deben corresponder al mismo pago |
| reason | string | Motivo del reembolso | Opcional. Por defecto OTHER. Se envía el nombre del valor. Cualquier otro valor devuelve 400 |
| reason_description | string | Texto libre con más detalle del motivo | Opcional |
Valores permitidos para reason:
| Valor | Descripción |
|---|---|
| MERCHANT_RETURNS_BUSINESS_RULE | Política de devoluciones del comercio |
| PRODUCT_OR_SERVICE_NOT_RECIVED | Producto o servicio no recibido |
| DEFECTIVE_PRODUCT_OR_SERVICE | Producto o servicio defectuoso o insatisfactorio |
| ORDER_CANCELLED_BEFORE_DELIVERY | Pedido cancelado antes de la entrega |
| DUPLICATE_PAYMENT | Cobro duplicado |
| INCORRECT_AMOUNT | Monto incorrecto |
| MANUAL_REVERSE_BY_MERCHANT | Reembolso manual por el comercio |
| UNRECOGNIZED_PAYMENT_BY_CLIENT | Cobro no reconocido por el cliente |
| PROCESSING_ISSUES | Problemas de procesamiento |
| PURCHASE_WITHDRAWAL | Cancelación de la compra por derecho de retracto |
| VOID_FROM_APP | Anulación desde la aplicación |
| OTHER | Otro (valor por defecto) |
PaymentVoidResponse
Respuesta al solicitar una anulación.
| Parámetro | Tipo | Descripción | Enum/Restricciones |
|---|---|---|---|
| payload | object | Información de la operación | |
| payload.transaction_id | string | ID de la transacción | Ejemplo: “CXXXXXXXX” |
| payload.status | string | Estado de la operación | Ejemplo: “running” |
| payload.next_actions | object | Acciones siguientes | Puede ser null |
| payload.status_detail | string | Detalle del estado | Puede ser null |
| payload.uuid_token | string | Token de la operación | Puede ser null |
| payload.message | string | Mensaje de la operación | Puede ser null |
| payload.errors | array | Errores de la operación | Puede ser null |
| payload.status_code | number | Código de estado | Puede ser null |
| errors | array | Lista de errores | Vacía si no hay errores |
PaymentRefundCreated
Respuesta al solicitar un reembolso (201).
| Parámetro | Tipo | Descripción | Enum/Restricciones |
|---|---|---|---|
| payload.refund_id | string | ID del reembolso | Ejemplo: “RFD123456” |
| payload.status | string | Estado del reembolso | [“REQUESTED”, “PROCESSING”, “REFUNDED”, “REJECTED”] |
| payload.code | string | Código de respuesta del procesador | Solo aparece cuando tiene valor |
| payload.refund_result | string | Mensaje del resultado del procesador | Solo aparece cuando tiene valor |
| errors | array | Lista de errores | Vacía si no hay errores |
PaymentRefundDetail
Detalle completo de un reembolso (consulta por refund_id).
| Parámetro | Tipo | Descripción | Enum/Restricciones |
|---|---|---|---|
| payload.refund_id | string | ID del reembolso | |
| payload.transaction_id | string | ID del pago reembolsado | |
| payload.status | string | Estado del reembolso | [“REQUESTED”, “PROCESSING”, “REFUNDED”, “REJECTED”] |
| payload.refund_reason | string | Motivo enviado al crear el reembolso | Ver valores de reason |
| payload.reason_description | string | Texto libre enviado al crear el reembolso | Solo aparece cuando tiene valor |
| payload.amount | object | Total del pago reembolsado | Contiene currency y value |
| payload.payer_email | string | Correo del pagador registrado en el pago | |
| payload.code | string | Código de respuesta del procesador | Solo aparece cuando tiene valor |
| payload.refund_result | string | Mensaje del resultado del procesador | Solo aparece cuando tiene valor |
| errors | array | Lista de errores | Vacía si no hay errores |
PaymentRefundList
Lista de reembolsos de un pago (consulta por transaction_id).
| Parámetro | Tipo | Descripción | Enum/Restricciones |
|---|---|---|---|
| payload.transaction_id | string | ID del pago consultado | |
| payload.refunds | array | Reembolsos del pago | Vacío si no tiene reembolsos |
| payload.refunds[].refund_id | string | ID del reembolso | |
| payload.refunds[].status | string | Estado del reembolso | [“REQUESTED”, “PROCESSING”, “REFUNDED”, “REJECTED”] |
| payload.refunds[].refund_reason | string | Motivo del reembolso | Ver valores de reason |
| payload.refunds[].amount | object | Total del pago reembolsado | Contiene currency y value |
| payload.refunds[].code | string | Código de respuesta del procesador | Solo aparece cuando tiene valor |
| payload.total | number | Cantidad de reembolsos de la lista | |
| errors | array | Lista de errores | Vacía si no hay errores |
Next Action Object
| Parámetro | Tipo | Descripción | Enum/Restricciones |
|---|---|---|---|
| redirect_url | string | URL de redirección al banco o autenticación 3DS | Formato: URL. Ejemplo: “https://mi-banco.com/pago-pse ” |
| redirect_method | string | Método HTTP | [“POST”, “GET”] |
| qr_payload | string | base64 del QR | Solo para Método de pago con QR |
| expires_at | string | Fecha de caducidad del QR en nanosegundos | Solo para Método de pago con QR |
Amount
Representa los detalles monetarios de una transacción. Define la estructura para especificar la moneda, el valor total del pago, propinas opcionales y los diversos impuestos aplicados.
| Parámetro | Tipo | Descripción | Enum/Restricciones |
|---|---|---|---|
| currency | string | Moneda del monto | ”COP” o “USD” |
| total_amount | number | Monto total del pago | |
| tip_amount | number | Monto de la propina | No puede exceder el 30% del total |
| taxes | array | Lista de impuestos aplicados | [ ] o [Tax] |
Tax
Define la estructura para representar información detallada sobre impuestos aplicados a una transacción. Permite especificar el tipo de impuesto (como IVA o impuesto al consumo), el valor base sobre el cual se calcula el impuesto y el monto resultante del cálculo.
| Parámetro | Tipo | Descripción | Enum/Restricciones |
|---|---|---|---|
| type | string | Tipo de impuesto | [“VAT”, “CONSUMPTION”] |
| base | number | Base del impuesto | 0 |
| value | number | Valor del impuesto | 0 |
Customer
Contiene la información personal del cliente que realiza una compra.
| Parámetro | Tipo | Descripción | Enum/Restricciones |
|---|---|---|---|
| name | string | Nombre completo del cliente | Requerido. Ejemplo: “John Doe” |
| phone | string | Número de teléfono del cliente | Ejemplo: “3123456789” |
| string | Correo electrónico del cliente | Ejemplo: “pagador@example.com” | |
| billing_address | object | Dirección de facturación | Address |
| shipping_address | object | Dirección de envío | Address |
Payer
Representa la información de la persona o entidad que realiza el pago. A diferencia del esquema Customer, este incluye datos específicos para el procesamiento de pagos, como tipo de persona (natural o jurídica), documentos de identificación y registros de aceptación de políticas.
| Parámetro | Tipo | Descripción | Enum/Restricciones |
|---|---|---|---|
| person_type | string | Tipo de persona | [“NATURAL_PERSON”, “LEGAL_PERSON”] |
| name | string | Nombre completo o razón social | Ejemplo: “John Doe” |
| phone | string | Teléfono del pagador | Ejemplo: “3123456789” sin el código de país, 10 caracteres |
| string | Correo electrónico | Ejemplo: “pagador@example.com” | |
| document_type | string | Tipo de documento | [“CEDULA”, “CEDULA_EXTRANJERIA”, “TARJETA_IDENTIDAD”, “PASAPORTE”, “NIT”] |
| document_number | string | Número de documento | Ejemplo: “987654321” |
| billing_address | object | Dirección de facturación | Address |
Address
Define la estructura estandarizada para representar una dirección física, ya sea de facturación o envío para la validación del método de pago.
| Parámetro | Tipo | Descripción | Enum/Restricciones |
|---|---|---|---|
| street1 | string | Dirección línea 1 | Requerido. Ejemplo: “Calle 123 # 34 56” |
| street2 | string | Dirección línea 2 | Ejemplo: “Barrio Primero de Julio” |
| city | string | Ciudad | Requerido. Ejemplo: “Bogotá” |
| zip_code | string | Código postal | Ejemplo: “170008” |
| province | string | Provincia o estado | Ejemplo: “Cundinamarca” |
| country | string | Código del país formato ISO 3166-1 | Requerido. Ejemplo: “CO” |
| phone | string | Teléfono asociado | Ejemplo: “3123456789” |
PaymentMethod
Esquema base que define la estructura para los diferentes métodos de pago soportados. Funciona como un contenedor que puede albergar cualquiera de los tipos de pago específicos como tarjetas de crédito, PSE, Nequi o Bancolombia.
| Parámetro | Tipo | Descripción | Enum/Restricciones |
|---|---|---|---|
| - | object | Método de pago utilizado para el intento | oneOf: PSE, CreditCard, Nequi, Bancolombia, QR |
CreditCard
Estructura específica para pagos con tarjeta de crédito. Incluye información detallada de la tarjeta y la dirección de facturación asociada, asegurando que se capture toda la información necesaria para procesar transacciones con este método de pago.
| Parámetro | Tipo | Descripción | Enum/Restricciones |
|---|---|---|---|
| name | string | Tipo de método de pago | ”CREDIT_CARD” |
| cardholder_name | string | Nombre del titular | Requerido. Ejemplo: “John Doe” |
| expiration_month | integer | Mes de vencimiento | Requerido. Ejemplo: 12 |
| expiration_year | integer | Año de vencimiento | Requerido. Ejemplo: “2032” |
| installments | integer | Número de cuotas | Requerido. Ejemplo: 1 |
| card_number | string | Número de tarjeta | Requerido. Ejemplo: “4111111111111111” |
| cvc | string | Código de seguridad | Requerido. Ejemplo: “123” |
Billing Address Object
| Parámetro | Tipo | Descripción | Enum/Restricciones |
|---|---|---|---|
| city | string | Ciudad | Requerido. Ejemplo: “Bogotá” |
| country_code | string | Código del país formato ISO 3166-1 | Requerido. Ejemplo: “CO” |
| street | string | Dirección | Requerido. Ejemplo: “Calle 123 # 34 56” |
| zip_code | string | Código postal | Requerido. Ejemplo: “170003” |
| state | string | Estado o región | Requerido. Ejemplo: “Cundinamarca” |
PSE
Estructura específica para pagos con PSE. Incluye información del banco y datos necesarios para redirigir al pagador.
| Parámetro | Tipo | Descripción | Enum/Restricciones |
|---|---|---|---|
| name | string | Tipo de método de pago | Requerido. “PSE” |
| bank_code | integer | Código del banco | Requerido. “1234” |
| bank_name | string | Nombre del banco | Requerido. “Bold CF” |
Bancolombia
Estructura específica para pagos con Botón Bancolombia.
| Parámetro | Tipo | Descripción | Enum/Restricciones |
|---|---|---|---|
| name | string | Tipo de método de pago | Requerido. “BOTON_BANCOLOMBIA” |
Nequi
Estructura específica para pagos con Nequi.
| Parámetro | Tipo | Descripción | Enum/Restricciones |
|---|---|---|---|
| name | string | Tipo de método de pago | Requerido. “NEQUI” |
QR
Estructura específica para pagos con QR de Bre-B.
| Parámetro | Tipo | Descripción | Enum/Restricciones |
|---|---|---|---|
| name | string | Tipo de método de pago | Requerido. “QR” |
| qr_format | string | Formato de entrega del código QR. Determina si se recibe una imagen procesada o el contenido en texto. | Por defecto: “TEXT”. Ver opciones abajo. |
Valores permitidos para qr_format:
- “TEXT”: Retorna la cadena de texto original. Permite al integrador generar y personalizar su propio código QR.
- “PLAIN_BASE64”: Imagen en Base64 en blanco y negro, sin logotipos ni estilos adicionales.
- “BOLD_BASE64”: Imagen en Base64 que incluye el logotipo y la identidad visual de Bold.
DeviceFingerprint
| Parámetro | Tipo | Descripción | Enum/Restricciones | Requerido |
|---|---|---|---|---|
| ip | string | Dirección IP del dispositivo | Requerido | ✓ |
| device_type | string | Tipo de dispositivo | ”DESKTOP” “MOBILE” | |
| os | string | Sistema operativo | ||
| browser | string | Navegador | ||
| java_enabled | boolean | Java habilitado | Requerido para 3ds | ✓ |
| language | string | Idioma del dispositivo | Requerido para 3ds | ✓ |
| color_depth | integer | Profundidad de color | Requerido para 3ds | ✓ |
| screen_height | integer | Altura de pantalla | Requerido para 3ds | ✓ |
| screen_width | integer | Ancho de pantalla | Requerido para 3ds | ✓ |
| time_zone_offset | integer | Zona horaria | Requerido para 3ds | ✓ |
| latitude | string | Latitud | Nullable | |
| longitude | string | Longitud | Nullable | |
| model | string | Modelo del dispositivo | Nullable | |
| platform | string | Plataforma | Nullable |
PaymentMethodResponse
Esquema contenedor para la respuesta específica según el método de pago utilizado. Similar al esquema PaymentMethod, pero contiene la información de respuesta tras el procesamiento del pago, que puede variar según el método utilizado.
| Parámetro | Tipo | Descripción | Enum/Restricciones |
|---|---|---|---|
| - | object | Método de pago con el que se pagó | oneOf: PSEResponse, CreditCardResponse, Nequi, Bancolombia |
CreditCardResponse
Esquema que contiene la información de respuesta para pagos realizados con tarjeta de crédito. Incluye detalles procesados de la tarjeta y la dirección de facturación.
| Parámetro | Tipo | Descripción | Enum/Restricciones |
|---|---|---|---|
| type | string | Tipo de método de pago | Requerido |
| card | object | Información de la tarjeta | Requerido |
| billing_address | object | Dirección de facturación | Requerido |
PSEResponse
Representa la información de respuesta específica para pagos realizados a través de PSE. Incluye datos como el nombre del banco utilizado y el identificador único de la transacción en el sistema PSE (CUS).
| Parámetro | Tipo | Descripción | Enum/Restricciones |
|---|---|---|---|
| type | string | Tipo de método de pago | [“PSE”] |
| bank_name | string | Nombre del banco para pagos PSE | Ejemplo: “Bancolombia” |
| cus | string | ID pago PSE | Ejemplo: “CUS12345678” |
PSEBankListResponse
Define la estructura de respuesta para la consulta de bancos disponibles para pagos PSE. Incluye una lista de bancos con sus respectivos códigos y nombres, permitiendo a los usuarios seleccionar el banco adecuado para realizar su pago.
| Parámetro | Tipo | Descripción | Enum/Restricciones |
|---|---|---|---|
| banks | array | Lista de bancos disponibles | Bank Item |
BankItem
| Parámetro | Tipo | Descripción | Enum/Restricciones |
|---|---|---|---|
| bank_code | string | Código del banco | Ejemplo: “1234” |
| bank_name | string | Nombre del banco | Ejemplo: “Bold CF” |
Error
Define la estructura de respuesta cuando ocurre un error de validación en la solicitud. Proporciona información detallada sobre la naturaleza del error, facilitando su identificación y corrección.
| Parámetro | Tipo | Descripción | Enum/Restricciones |
|---|---|---|---|
| payload | object | Lista de errores | Payload Item |
| errors | array | Lista de errores |
Payload Item
| Parámetro | Tipo | Descripción | Enum/Restricciones |
|---|---|---|---|
| status_code | string | Código de error | Requerido |
| message | string | Mensaje general de error | Requerido |