Saltar al contenido principal
API docs by Redocly

API Merchants Finantial (1.0.0)

Download OpenAPI specification:Download

Integración de puntos de venta y servicios merchant con Seguridad JWT.

Merchants

Registrarte como comercio

Endpoint público para registro (Onboarding). Crea un nuevo merchant y devuelve su ID.

Request Body schema: application/json
required
legalName
required
string

Nombre legal del comercio.

taxId
required
string

RIF o identificación fiscal del comercio.

email
required
string <email>

Dirección de correo electrónico.

password
required
string

Contraseña de acceso del usuario.

phone
string

Número de teléfono.

address
string

Dirección del comercio.

Responses

Request samples

Content type
application/json
{
  • "legalName": "Inversiones Spidi C.A.",
  • "taxId": "J-12345678-0",
  • "email": "admin@comercio.com",
  • "password": "string",
  • "phone": "+584141234567",
  • "address": "Av. Principal, Edif. Central"
}

Response samples

Content type
application/json
{
  • "status": 200,
  • "title": "Comercio Recuperado",
  • "detail": "Los detalles del comercio han sido obtenidos exitosamente de la base de datos.",
  • "data": {
    }
}

Iniciar Sesión como comercio

Te permite intercambiar tus credenciales como por un token de acceso (JWT).

Request Body schema: application/json
required
email
required
string <email>

Dirección de correo electrónico.

password
required
string

Contraseña de acceso del usuario.

Responses

Request samples

Content type
application/json
{
  • "email": "[EMAIL_ADDRESS]",
  • "password": "[PASSWORD]"
}

Response samples

Content type
application/json
{
  • "status": 200,
  • "title": "Autenticación Exitosa",
  • "detail": "Se ha generado el token de acceso correctamente y el usuario ha sido autenticado.",
  • "data": {
    }
}

Generar OTP para Pairing

Solicita vincular un sistema terminal con el Serial de Hardware y genera un código de activación (OTP).

Authorizations:
BearerAuth
Request Body schema: application/json
required
serial
required
string

Serial de Hardware del dispositivo POS.

Responses

Request samples

Content type
application/json
{
  • "serial": "string"
}

Response samples

Content type
application/json
{
  • "status": 200,
  • "title": "OTP Generado",
  • "detail": "El código de activación ha sido generado exitosamente para el terminal solicitado.",
  • "data": {
    }
}

Solicitar Pago

Crea una transacción en el sistema. Nótese que las transacciones deben ser confirmadas; el hecho de que esté creada no significa que esté confirmada.

Authorizations:
BearerAuth
path Parameters
merchantId
required
string <uuid>
Example: 3ddc4cfb-c09a-43de-92c1-e4a069732e90

Identificador único en formato UUID del comercio

Request Body schema: application/json
required
orderId
required
string <uuid>

Identificador único de la orden generado por el comercio.

amountReference
required
number <double>

Monto de referencia en la moneda especificada en currencyReference con 2 decimales.

currencyReference
string
Enum: "USD" "EUR" "COP" "USDT" "VES"

Moneda de referencia que se fija para el pago. Usada para calcular el monto en bolívares con la tasa vigente.

allowAmountChange
boolean
Default: false

Si es true, permite editar el monto en el POS.

clientIdentification
string

Cédula o RIF del cliente.

terminalSerial
string

Serial del terminal físico.

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.

Responses

Request samples

Content type
application/json
{
  • "orderId": "3ddc4cfb-c09a-43de-92c1-e4a069732e90",
  • "amountReference": "100.001",
  • "currencyReference": "USD",
  • "allowAmountChange": false,
  • "clientIdentification": "V14143800",
  • "terminalSerial": "98202003219630",
  • "deeplinkConfig": {
    }
}

Response samples

Content type
application/json
{
  • "status": 200,
  • "title": "Operación Procesada",
  • "detail": "La transacción ha sido procesada y se ha devuelto el estado actual de la operación.",
  • "data": {
    }
}

Consultar pago

Consulta información sobre una transacción por medio de su id incluyendo el estado actual

Authorizations:
BearerAuth
path Parameters
merchantId
required
string <uuid>
Example: 3ddc4cfb-c09a-43de-92c1-e4a069732e90

Identificador único en formato UUID del comercio

orderId
required
string

Responses

Response samples

Content type
application/json
{
  • "status": 200,
  • "title": "Operación Procesada",
  • "detail": "La transacción ha sido procesada y se ha devuelto el estado actual de la operación.",
  • "data": {
    }
}

Anular Pago

Solicita la cancelación o anulación de una transacción. Si la transacción está en estado PENDING (no confirmada por el POS), pasa a CANCELED. Si la transacción está en estado PAID (ya confirmada por el POS), pasa a VOID_PENDING a la espera de la confirmación de anulación por parte del POS.

Authorizations:
BearerAuth
path Parameters
merchantId
required
string <uuid>
Example: 3ddc4cfb-c09a-43de-92c1-e4a069732e90

Identificador único en formato UUID del comercio

orderId
required
string

Responses

Response samples

Content type
application/json
{
  • "status": 200,
  • "title": "string",
  • "detail": "string",
  • "data": { }
}

Listar Cierres de Lote de Terminal

Obtiene el historial de cierres de lote del terminal especificado para el comercio.

Authorizations:
BearerAuth
path Parameters
merchantId
required
string <uuid>
Example: 3ddc4cfb-c09a-43de-92c1-e4a069732e90

Identificador único en formato UUID del comercio

serialNumber
required
string
Example: 98202003219630

Serial del terminal físico.

query Parameters
page
integer
Default: 1

Número asociado a la página solicitada (Indizado desde 1).

size
integer
Default: 20

Cantidad máxima de elementos por página.

sort
string
Default: "-closedAt"

Criterio de ordenamiento. Usar el prefijo - para orden descendente. Ejemplo: -closedAt o +name.

Responses

Response samples

Content type
application/json
{
  • "status": 200,
  • "title": "Listado de Cierres",
  • "detail": "Se ha recuperado el historial de cierres de lote del terminal.",
  • "data": [
    ]
}

Terminales

Activar dispositivo POS

Valida el código OTP ingresado en el punto de venta y genera el Secret Key del dispositivo.

Request Body schema: application/json
required
serial
required
string

Serial de Hardware del dispositivo POS.

code
required
string

Código de activación (OTP) generado en la fase de Pairing.

Responses

Request samples

Content type
application/json
{
  • "serial": "string",
  • "code": "string"
}

Response samples

Content type
application/json
{
  • "status": 200,
  • "title": "Dispositivo Activado",
  • "detail": "La vinculación ha sido completada y el dispositivo ha recuperado su Secret Key.",
  • "data": {
    }
}

Listar pagos del POS

Listar pagos del POS

Authorizations:
POSSignature
path Parameters
serialNumber
required
string
Example: 98202003219630

Identificador / Serial del terminal.

query Parameters
object

Filtro dinámico (LHS Brackets) para filtrar transacciones por estado. Ej: ?status=PENDING

Request Body schema: application/json
required
orderId
required
string <uuid>

Identificador único de la orden generado por el comercio.

amountReference
required
number <double>

Monto de referencia en la moneda especificada en currencyReference con 2 decimales.

currencyReference
string
Enum: "USD" "EUR" "COP" "USDT" "VES"

Moneda de referencia que se fija para el pago. Usada para calcular el monto en bolívares con la tasa vigente.

allowAmountChange
boolean
Default: false

Si es true, permite editar el monto en el POS.

clientIdentification
string

Cédula o RIF del cliente.

terminalSerial
string

Serial del terminal físico.

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.

Responses

Request samples

Content type
application/json
{
  • "orderId": "3ddc4cfb-c09a-43de-92c1-e4a069732e90",
  • "amountReference": "100.001",
  • "currencyReference": "USD",
  • "allowAmountChange": false,
  • "clientIdentification": "V14143800",
  • "terminalSerial": "98202003219630",
  • "deeplinkConfig": {
    }
}

Response samples

Content type
application/json
{
  • "status": 200,
  • "title": "Listado de Transacciones",
  • "detail": "Se ha recuperado el historial de transacciones del terminal solicitado.",
  • "data": [
    ]
}

Consultar el estado de un pago desde el POS

Consulta información sobre una transacción por medio de su id incluyendo el estado actual

Authorizations:
POSSignature
path Parameters
serialNumber
required
string
Example: 98202003219630

Serial del POS

orderId
required
string

Responses

Response samples

Content type
application/json
{
  • "status": 200,
  • "title": "Operación Procesada",
  • "detail": "La transacción ha sido procesada y se ha devuelto el estado actual de la operación.",
  • "data": {
    }
}

Confirmar Pago

Pasa una transacción que estaba en estado PENDING a PAID. Adicionalmente, si la orden fue cancelada (estado CANCELED) antes de la confirmación del POS, emitir esta llamada sobrescribirá la cancelación y confirmará el pago con estado PAID.

Authorizations:
POSSignature
path Parameters
serialNumber
required
string
Example: 98202003219630

Serial del terminal físico.

orderId
required
string
Request Body schema: application/json
required
authorizationCode
string

Código de autorización bancaria.

processCode
string
commitAt
string <date-time>

Fecha y hora de la confirmacion de la operacion (ISO 8601).

amountReference
number <double>

Monto de referencia en la moneda especificada en currencyReference con 2 decimales.

terminalNumber
string

Numero de terminal.

trace
string

Número de traza (Trace).

utcDate
string

Timestamp UTC del banco.

cardTypeForRpt
string

Tipo de tarjeta (C=Crédito, D=Débito).

visOrMccCard
string

Franquicia de la tarjeta.

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.

Responses

Request samples

Content type
application/json
{
  • "authorizationCode": "171599",
  • "processCode": "002000",
  • "commitAt": "2019-08-24T14:15:22Z",
  • "amountReference": "100.001",
  • "terminalNumber": "98202003219630",
  • "trace": "000535",
  • "utcDate": "1007151715",
  • "cardTypeForRpt": "C",
  • "visOrMccCard": "MCC",
  • "batchNumber": 3
}

Response samples

Content type
application/json
{
  • "status": 200,
  • "title": "Operación Procesada",
  • "detail": "La transacción ha sido procesada y se ha devuelto el estado actual de la operación.",
  • "data": {
    }
}

Confirmar Anulación

Confirma la ejecución de la anulación.

Authorizations:
POSSignature
path Parameters
serialNumber
required
string
Example: 98202003219630

Serial del terminal físico.

orderId
required
string

Responses

Response samples

Content type
application/json
{
  • "status": 200,
  • "title": "string",
  • "detail": "string",
  • "data": { }
}

Listar Cierres

Obtiene el historial de cierres de lote.

Authorizations:
POSSignature
path Parameters
serialNumber
required
string
Example: 98202003219630

Serial del terminal físico.

query Parameters
page
integer
Default: 1

Número asociado a la página solicitada (Indizado desde 1).

size
integer
Default: 20

Cantidad máxima de elementos por página.

sort
string
Default: "-closedAt"

Criterio de ordenamiento. Usar el prefijo - para orden descendente. Ejemplo: -closedAt o +name.

Responses

Response samples

Content type
application/json
{
  • "status": 200,
  • "title": "Listado de Cierres",
  • "detail": "Se ha recuperado el historial de cierres de lote del terminal.",
  • "data": [
    ]
}

Crear Cierre

Con este endpoint el pos notifica el cierre del lote.

Authorizations:
POSSignature
path Parameters
serialNumber
required
string
Example: 98202003219630

Serial del terminal físico.

Request Body schema: application/json
required
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.

transactionCount
integer
closedAt
string <date-time>
currencyReference
string
Enum: "USD" "EUR" "COP" "USDT" "VES"

Moneda de referencia que se fija para el pago. Usada para calcular el monto en bolívares con la tasa vigente.

object
debitBatch
string

Falta ser definido por Carlos Cardenas

Responses

Request samples

Content type
application/json
{
  • "batchNumber": 3,
  • "transactionCount": 12,
  • "closedAt": "2023-04-04T15:26:51.187Z",
  • "currencyReference": "USD",
  • "terminal": {
    },
  • "debitBatch": "string"
}

Response samples

Content type
application/json
{
  • "status": 200,
  • "title": "Cierre de Lote",
  • "detail": "Detalles del cierre de lote solicitado.",
  • "data": {
    }
}

Consultar Cierre

Obtiene la información detallada de un cierre específico.

Authorizations:
BearerAuth
path Parameters
serialNumber
required
string
Example: 98202003219630

Serial del terminal físico.

batchNumber
required
integer

Responses

Response samples

Content type
application/json
{
  • "batchNumber": 3,
  • "transactionCount": 12,
  • "closedAt": "2023-04-04T15:26:51.187Z",
  • "currencyReference": "USD",
  • "terminal": {
    },
  • "debitBatch": "string"
}