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.

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	0
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

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. También incluye un indicador para distinguir entre transacciones reales y de prueba.

Parámetro	Tipo	Descripción	Enum/Restricciones
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"}]`
test	boolean	Indica si el intento de pago es de un agente de prueba	Requerido. Ejemplo: true
payer	object	Información del pagador	Payer
payment_method	object	Método de pago utilizado	PaymentMethod
device_fingerprint	object	Huella digital del dispositivo	DeviceFingerprintWeb

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 merchant	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	-
status	string	Estado de la intención de pago	["ACTIVE", "PROCESSING", "PENDING", "DISABLED", "PAYED"]
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
device_fingerprint	object	Huella digital del dispositivo	DeviceFingerprintWeb

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
reference_id	string	Identificador único de la referencia del pago	Requerido. 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"
confirm	boolean	Indica si se envía el intento de pago inmediatamente	Ejemplo: true
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	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
payment_method	object	Método de pago	PaymentMethod

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: "Jhon 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

Address

Define la estructura estandarizada para representar una dirección física, ya sea de facturación o envío para la validacion 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á"
postal_code	string	Código postal	Ejemplo: "170008"
province	string	Provincia o estado	Ejemplo: "Cundinamarca"
country_code	string	Código del país formato ISO 3166-1	Requerido. Ejemplo: "CO"
phone	string	Teléfono asociado	Ejemplo: "3123456789"

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: "Jhon Doe"
phone	string	Teléfono del pagador	Ejemplo: "3123456789"
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"
terms_and_conditions	object	Aceptación de términos	PolicyAcceptanceData
data_treatment	object	Aceptación tratamiento de datos	PolicyAcceptanceData

PolicyAcceptanceData

Utilizado para registrar la aceptación formal de políticas o términos y condiciones o tratamiento de datos personales.

Parámetro	Tipo	Descripción	Enum/Restricciones
acceptance_date	string	Fecha de aceptación	Requerido, format: date-time
version	string	Versión de términos aceptados	Requerido

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
type	string	Tipo de método de pago	Requerido
-	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
type	string	Tipo de método de pago	["CREDIT_CARD"]
card	object	Información de la tarjeta	Card Object
billing_address	object	Dirección de facturación	Billing Address Object

Card Object

Parámetro	Tipo	Descripción	Enum/Restricciones
brand	string	Marca de la tarjeta	Requerido. Ejemplo: "VISA"
cardholder_name	string	Nombre del titular	Requerido. Ejemplo: "Jhon Doe"
exp_month	integer	Mes de vencimiento	Requerido. Ejemplo: 12
exp_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

Esquema para pagos electrónicos mediante PSE (Pagos Seguros en Línea). Incluye el código del banco seleccionado por el usuario y su dirección, elementos necesarios para redirigir correctamente al cliente a la plataforma bancaria correspondiente.

Parámetro	Tipo	Descripción	Enum/Restricciones
type	string	Tipo de método de pago	["PSE"]
bank_code	string	Código del banco	Requerido. Ejemplo: "3456"
address	string	Dirección del pagador	Requerido. Ejemplo: "Calle 123 # 34 56"

Nequi

Estructura para pagos realizados a través de la billetera móvil Nequi. No requiere campos adicionales, ya que se basa en la autenticación del usuario en la aplicación Nequi.

Parámetro	Tipo	Descripción	Enum/Restricciones
type	string	Tipo de método de pago	["NEQUI"]

Bancolombia

Esquema para pagos realizados utilizando la plataforma de Bancolombia y solo requiere el tipo de método de pago, pues la gestión detallada ocurre en el entorno bancario.

Parámetro	Tipo	Descripción	Enum/Restricciones
type	string	Tipo de método de pago	["BANCOLOMBIA"]

DeviceFingerprintWeb

Parámetro	Tipo	Descripción	Enum/Restricciones
ip	string	Dirección IP	Requerido
device_type	string	Tipo de dispositivo	Requerido
os	string	Sistema operativo	Requerido
browser	string	Navegador	Requerido
accept_header	string	Cabecera HTTP Accept	Requerido
user_agent	string	User Agent	Requerido
java_enabled	boolean	Java habilitado	Requerido
language	string	Idioma del dispositivo	Requerido
color_depth	integer	Profundidad de color	Requerido
screen_height	integer	Altura de pantalla	Requerido
screen_width	integer	Ancho de pantalla	Requerido
time_zone_offset	integer	Zona horaria	Requerido
latitude	string	Latitud	Nullable
longitude	string	Longitud	Nullable
model	string	Modelo del dispositivo	Nullable
platform	string	Plataforma	Nullable

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	Requerido. Ejemplo: "TXNFD76543"
reference_id	string	ID de referencia	Requerido. Ejemplo: "ORDEN-999"
status	string	Estado de la transacción	["APPROVED", "REJECTED", "PROCESSING", "PENDING"]
amount	object	Información del monto	Amount
payment_method	object	Método de pago usado	PaymentMethodResponse
payer	object	Información del pagador	Payer
sale_date	string	Fecha de la transacción	Requerido
metadata	array	Metadatos del cliente	Requerido. Ejemplo: `[{"key":"custom-id", "value":"999"}]`

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	["PROCESSING"]

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"]

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

ValidationError

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
detail	array	Lista de errores	Detail Array Item

Detail Array Item

Parámetro	Tipo	Descripción	Enum/Restricciones
loc	array	Ubicación del error	Requerido
msg	string	Mensaje de error	Requerido
type	string	Tipo de error	Requerido

Applink