Visão geral
Os cartões-presente digitais e os cartões de saldo pré-pago permitem a retalhistas, cafés, marcas de hotelaria e comerciantes emitir crédito de compras personalizado diretamente para a Apple Wallet e Google Wallet. Os clientes transportam sempre o saldo disponível no smartphone, enquanto as equipas financeiras mantêm um livro-razão de auditoria imutável de partidas dobradas para reconciliação financeira.
Arquitetura no backend e entidades de saldo pré-pago
A funcionalidade de saldo pré-pago na Passinstance é assegurada por modelos financeiros dedicados no esquema Passinstance database:
-
Tipo de Passe (pass type):
storeCard(apresenta saldos monetários em direto em destaque nas zonas principais do cartão). -
Modelo Demo de Catálogo:
gift-card. -
Tipo de Mecânica (mechanic type):
PREPAID_CARD. -
Principais Modelos Financeiros:
- prepaid account: Mantém o saldo monetário ativo usando aritmética inteira nas unidades monetárias mínimas (balanceMinor) e códigos de moeda (currency: "EUR" | "USD"). - prepaid ledger entry: Livro-razão imutável de auditoria que regista cada crédito, débito, carregamento e ajuste com carimbos temporais, IDs de operador, referências de terminal POS e chaves de idempotência.
Regras do motor de mecânicas e proteções contabilísticas
O Pass Mechanics Engine aplica invariantes financeiros rigorosos nas operações de saldo pré-pago:
-
1
Representação em unidades monetárias mínimas: Os saldos são calculados em unidades inteiras mínimas (ex.:
2500representa $25.00 USD e1550representa €15,50 EUR). Isto elimina erros de arredondamento de vírgula flutuante em transações de retalho de alta frequência. -
2
Prevenção de saldo negativo (
disallowNegativeBalance: true): O servidor rejeita estritamente qualquer pedido de débito em quecurrentBalanceMinor - debitAmountMinor < 0, devolvendo HTTP 400 com o código de erroINSUFFICIENT_FUNDS. -
3
Proteções de recarregamento (
disableAutoRecharge: true): Impede acionadores automáticos de carregamento salvo autorização explícita dos métodos de pagamento guardados pelo cliente. -
4
Proteção por idempotência: Cada pedido de débito ou carregamento aceita uma
idempotencyKeyúnica. Pedidos POS duplicados provocados por novas tentativas de rede devolvem em segurança a resposta original bem-sucedida sem duplicar cobranças ao cliente.
Resgate atómico em POS e carregamento de saldo
Operadores de caixa, hardware POS integrado e terminais automáticos de self-checkout comunicam com a API de Orquestração de Leitores ou com os endpoints de leitura ao balcão:
Pedido 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"
}
Resposta HTTP (200 OK)
{
"success": true,
"resultingValue": "37.50"
}
Nota: A equipa de balcão também pode debitar ou creditar saldos através de
POST /api/v1/scans(comx-scanner-key) ouPOST /api/v1/passes/:id/use/POST /api/v1/passes/:id/adjust-value(com autenticação Bearer/Chave API) e auditar transações viaGET /api/v1/balance-changes?passId=<passId>. As regras de saldo pré-pago suportamStoredValueOperation(NONE,ADD,SUBTRACT,SET) eStoredValueAmountSource(FIXED,OPERATOR,MECHANIC). UtilizeexternalIdna criação para correlacionar os cartões em carteira com números de cartão-presente do seu POS externo.
Sessões públicas de carregamento pelo cliente
Os titulares dos cartões podem consultar saldos e adicionar crédito de compras online:
-
Os comerciantes podem emitir ligações de autocarregamento suportadas por
GET /api/v1/public/reload-sessions/:tokene consultar o estado do pagamento emGET /api/v1/public/reload-sessions/:sessionId/status. -
A sessão de carregamento integra com Stripe, PayPal, Paystack ou Mobile Money (MTN MoMo, Orange Money) para processar o pagamento, creditar instantaneamente a
prepaid accounte enviar o saldo atualizado por push para a Apple Wallet e Google Wallet.
Importante: Configure sempre
changeMessage: "New balance: %@"no campo de saldo no editor visual de modelos. Sempre que ocorre um débito ou carregamento, o telemóvel do cliente acorda de imediato com uma notificação nativa no ecrã bloqueado indicando o novo saldo disponível.
Descubra mais no nosso Caso de uso Cartões-Presente.
