Esquema De Datos

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"
callback_url	string	URL de retorno al completar el pago	Ejemplo: "https://bold.co (opens in a new tab)"
metadata	array	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

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"]
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 (opens in a new tab)"
metadata	array	Lista de metadatos clave-valor	Ejemplo: `[{"key":"custom-id", "value":"999"}]`
test	boolean	Indica si es una intención de pago de prueba	Ejemplo: true
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	array	Lista de metadatos clave-valor relacionados con el pago	Requerido. Ejemplo: `[{"key":"custom-id", "value":"999"}]`
payer	object	Información del pagador	Payer	✓
payment_method	object	Método de pago utilizado	PaymentMethod	✓
device_fingerprint	object	Huella digital del dispositivo	DeviceFingerprintWeb	✓ 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_action	object	Acción requerida	Next Action Object
status	string	Estado de la transacción	["APPROVED", "REJECTED","PROCESSING"]

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	array	Metadatos del cliente	Máximo 3 , si no tra se toman los de la intención de pago. Ejemplo: `[{"custom":"custom-id", "value":"999"}]`

Next Action Object

Parámetro	Tipo	Descripción	Enum/Restricciones
redirect_url	string	URL de redirección	Requerido, format: uri. Ejemplo: "https://mi-banco.com/pago-pse (opens in a new tab)"
redirect_method	string	Método HTTP	["POST", "GET"]

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"
total_amount	number	Monto total del pago	0
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"
email	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: "573123456789" incluyendo el código de país
email	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

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"

DeviceFingerprintWeb

Parámetro	Tipo	Descripción	Enum/Restricciones	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

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	Requerido. Ejemplo: "Bancolombia"
cus	string	ID pago PSE	Requerido. Ejemplo: "CUS12345678"

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

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 geenral de error	Requerido

Proceso de Integración Activacion