Descripción general
Las tarjetas regalo digitales y las tarjetas prepago de valor almacenado permiten a comercios, cafeterías, marcas hoteleras y minoristas emitir saldo de compra corporativo directamente a Apple Wallet y Google Wallet. Los clientes llevan siempre su saldo disponible en el teléfono inteligente, mientras los equipos financieros mantienen un libro mayor inmutable de doble entrada para la conciliación contable.
Arquitectura del backend y entidades de valor almacenado
La funcionalidad de valor almacenado en Passinstance se apoya en modelos financieros dedicados para el control de saldos en el esquema de Passinstance database:
-
Tipo de pase (pass type):
storeCard(muestra el saldo monetario en directo de forma destacada en las zonas principales de la tarjeta). -
Plantilla de demostración del catálogo:
gift-card. -
Tipo de mecánica (mechanic type):
PREPAID_CARD. -
Modelos financieros principales:
- prepaid account: Registra el saldo monetario activo mediante aritmética de enteros en unidades monetarias mínimas (balanceMinor) y códigos de divisa (currency: "EUR" | "USD"). - prepaid ledger entry: Libro mayor inmutable de auditoría que registra cada abono, cargo, recarga y ajuste con marcas de tiempo, identificadores de operador, referencias de terminal POS y claves de idempotencia.
Reglas del motor de mecánicas y salvaguardas contables
Pass Mechanics Engine aplica invariantes financieros estrictos sobre las operaciones de valor almacenado:
-
1
Representación en unidades monetarias mínimas: Los saldos se calculan en enteros de unidad mínima (por ejemplo,
2500representa 25,00 USD y1550representa 15,50 EUR). Esto elimina errores de redondeo en coma flotante durante transacciones minoristas de alta frecuencia. -
2
Prevención de saldo negativo (
disallowNegativeBalance: true): El servidor rechaza estrictamente cualquier cargo dondecurrentBalanceMinor - debitAmountMinor < 0, devolviendo HTTP 400 con el código de errorINSUFFICIENT_FUNDS. -
3
Salvaguardas de recarga (
disableAutoRecharge: true): Impide activaciones automáticas de recarga salvo autorización expresa mediante métodos de pago guardados del cliente. -
4
Protección de idempotencia: Cada solicitud de cargo o recarga acepta una clave única
idempotencyKey. Las solicitudes duplicadas en el TPV provocadas por reintentos de red devuelven con seguridad la respuesta original exitosa sin cobrar dos veces al cliente.
Canje atómico en POS y recarga de saldo
Los operadores de caja, los terminales POS integrados y las cajas de autopago se comunican con la Reader Orchestration API o con los endpoints de escaneo en mostrador:
Solicitud HTTP
/api/v1/reader/redeem
{
"customerId": "8f94d930-b302-4fc8-9f12-000000000001",
"passId": "4a71b2d0-5e3a-4e8c-8f21-000000000002",
"amount": "12.50",
"idempotencyKey": "pos_tx_20261115_0091",
"operatorId": "cashier_alex"
}
Respuesta HTTP (200 OK)
{
"success": true,
"resultingValue": "37.50"
}
Nota: El personal de mostrador también puede cargar o abonar saldos mediante
POST /api/v1/scans(conx-scanner-key) oPOST /api/v1/passes/:id/use/POST /api/v1/passes/:id/adjust-value(con autenticación Bearer / clave API), y auditar transacciones medianteGET /api/v1/balance-changes?passId=<passId>. Las reglas de valor almacenado admitenStoredValueOperation(NONE,ADD,SUBTRACT,SET) yStoredValueAmountSource(FIXED,OPERATOR,MECHANIC). UtiliceexternalIden la creación para correlacionar tarjetas del monedero con numeraciones externas de tarjetas regalo del POS.
Sesiones públicas de autorecarga para clientes
Los titulares pueden consultar saldos y añadir crédito de compra en línea:
-
Los comercios pueden emitir enlaces de autorecarga respaldados por
GET /api/v1/public/reload-sessions/:tokeny consultar el estado del pago enGET /api/v1/public/reload-sessions/:sessionId/status. -
La sesión de recarga se integra con Stripe, PayPal, Paystack o Mobile Money (MTN MoMo, Orange Money) para procesar el pago, abonar al instante en
prepaid accounty enviar por push el saldo actualizado a Apple Wallet y Google Wallet.
Importante: Configure siempre
changeMessage: "Nuevo saldo: %@"en el campo del saldo dentro del editor visual de plantillas. Cuando se produce un cargo o una recarga, el teléfono del cliente se ilumina al instante con una notificación nativa en la pantalla de bloqueo mostrando el nuevo saldo disponible.
Descubra más en nuestro Caso de uso de tarjetas regalo.
