Diccionario de datos

Todos los campos que verás en la API Merchant, con su tipo y qué significan. Se actualiza con cada versión del contrato.

Algunos nombres significan cosas distintas según dónde aparezcan —status es un código HTTP en un error y el estado de un pago en una transacción—, así que esos salen con una fila por cada sentido, indicando el esquema del que vienen.

Campo	Tipo	Descripción
accessToken	string	Token JWT para usar en los headers Authorization.
address	string	Dirección del comercio.
affiliateCode	string	sin descripción en el contrato
allowAmountChange	boolean	Si es true, permite editar el monto en el POS.
amountReference	number	Monto de referencia en la moneda especificada en currencyReference con 2 decimales.
authorizationCode	string	Código de autorización bancaria.
bankCode	string	Código del banco. Solo acepta 3–4 dígitos (p.ej., 105 o 0137).
bankId	string	sin descripción en el contrato
batchNumber	integer	Este campo será un número autoincremental gestionado directamente desde el POS. El POS debe enviarlo para identificar correctamente el número de lote de las operaciones.
cancellationDara	object	Nota del portal: el nombre del campo lleva una errata en el contrato; se entiende cancellationData. Úsalo tal como lo devuelve la API.
cardTypeForRpt	string	Tipo de tarjeta (C=Crédito, D=Débito).
clientIdentification	string	Cédula o RIF del cliente.
closedAt	string	Fecha y hora en que el terminal cerró el lote, en ISO 8601 UTC. †
code en PairingResponse	string	Código de activación (OTP) generado para el dispositivo POS.
code en PairingActivateRequest	string	Código de activación (OTP) generado en la fase de Pairing.
commitAt	string	Fecha y hora de la confirmacion de la operacion (ISO 8601).
confirmData	object	Datos de confirmación bancaria. Este campo SOLO está definido y presente cuando el 'status' es 'PAID_COMPLETE'. En estados pendientes o cancelados, este campo será null o no existirá. Nota del portal: el contrato dice PAID_COMPLETE, un estado que no existe. El estado de un pago confirmado es PAID.
createdAt	string	Fecha y hora de creación en formato ISO 8601.
currencyReference	string	Moneda de referencia que se fija para el pago. Usada para calcular el monto en bolívares con la tasa vigente. Uno de: USD, EUR, COP, USDT, VES.
data en LoginResponse, MerchantResponse, PairingActivateResponse y 4 más	object	Representa una entidad única de negocio.
data en successDetails	—	Contenedor de información que puede almacenar un objeto único o una lista de objetos.
data en SettlementsResponse, TransactionsResponse, successDetailsArray	array	Representa una colección de entidades de negocio.
debitBatch	string	Identificador del lote de débito asociado al cierre (p. ej. DB-9901). †
deeplinkConfig	object	Configuración para el retorno a la app (Deep Linking). Estos campos se usan cuando la app merchant se ubica en el punto, pues al terminar la transacción de compra, el app financiero va a abrir la app en la pantalla específica esperada por parte del merchant.
detail en LoginResponse, MerchantResponse, PairingActivateResponse y 5 más	—	sin descripción en el contrato
detail en problemDetails	string	Una explicación legible por humanos específica para esta ocurrencia del problema.
detail en problemDetails	string	Descripción técnica del error.
detail en successDetails	string	Una explicación legible por humanos específica para esta ocurrencia del éxito.
email	string	Dirección de correo electrónico.
errors	array	Lista de errores específicos de validación con punteros JSON (RFC 6901).
expiresIn	integer	Tiempo en segundos antes de expirar.
id en MerchantResponse	string	Identificador único en formato UUID del comercio
id en TransactionEntity, TransactionResponse, TransactionsResponse	string	Identificador único en formato UUID.
instance	string	Una referencia URI que identifica la ocurrencia específica del problema.
legalName	string	Nombre legal del comercio.
merchantId	string	Identificador único en formato UUID del comercio
message	—	sin descripción en el contrato
number	string	Numero de terminal.
orderId	string	Identificador único de la orden generado por el comercio.
password	string	Contraseña de acceso del usuario.
phone	string	Número de teléfono.
pointer	string	Puntero al campo específico en el cuerpo de la solicitud.
processCode	string	Código de proceso de la transacción devuelto por el banco (p. ej. 002000). †
returnActivity	string	sin descripción en el contrato
returnPackage	string	sin descripción en el contrato
secret_key	string	Clave secreta generada (ej. SHA-256) en el servidor vinculada al Serial, para autenticación mediante HMAC.
serial en PairingActivateRequest, PairingRequest	string	Serial de Hardware del dispositivo POS.
serial en SettlementResponse, SettlementsResponse, settlementSummary y 1 más	string	Serial del terminal físico.
status en MerchantResponse	string	Uno de: ACTIVE, PENDING.
status en problemDetails	integer	El código de estado HTTP generado por el servidor de origen.
status en TransactionEntity, TransactionResponse, TransactionsResponse	string	Indica el status del pago. PENDING: la orden fue creada y el POS aún no ha confirmado el pago. CANCELED: el sistema merchant canceló la orden antes de la confirmación del POS (si el POS confirma el pago después, este estado es sobrescrito a PAID). PAID: el POS confirmó exitosamente el pago. VOID_PENDING: se solicitó la anulación de un pago ya confirmado y se espera la confirmación del POS. VOIDED: el POS confirmó la anulación del pago. Uno de: PENDING, CANCELED, PAID, VOID_PENDING, VOIDED.
status en successDetails	integer	El código de estado HTTP generado por el servidor de origen (ej. 200, 201).
taxId	string	RIF o identificación fiscal del comercio.
terminal	object	Serial del terminal que envía el cierre de lote. †
terminalNumber	string	Numero de terminal.
terminalSerial	string	Serial del terminal físico.
title en LoginResponse, MerchantResponse, PairingActivateResponse y 5 más	—	sin descripción en el contrato
title en problemDetails	string	Un resumen breve y legible por humanos sobre el tipo de problema.
title en successDetails	string	Un resumen breve y legible por humanos sobre el tipo de éxito.
tokenType	string	Tipo de token de autenticación.
trace	string	Número de traza (Trace).
transactionCount	integer	Cantidad de transacciones incluidas en el cierre de lote. †
type	string	Una referencia URI que identifica el tipo de problema.
utcDate	string	Timestamp UTC del banco.
visOrMccCard	string	Franquicia de la tarjeta.

† Descripción documentada por SPIDI en los ejemplos de sus guías, todavía no incorporada al contrato OpenAPI.