Skip to content
Guia da Central de AjudaFase de integração 2
3 min de leituraVerificado 2026-11-16

Cartões-presente e pré-pagos

Configure mecânicas de Saldo Armazenado para cartões-presente recarregáveis com registo contabilístico auditável.

Neste guia

Inspecione capturas de ecrã exatas do painel e detalhes ampliados relacionados com este guia.

Foco ampliado da interface
Elementos-chave da interface

Seletor «Adicionar uma mecânica de cartão» (Zoom)

Escolha entre 6 mecânicas integradas: Cartão de carimbos, Resgate de carimbos, Valor armazenado, Pontos e níveis, Validação uma vez por dia ou Prolongar validade.

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.

FLUXO DE ARQUITETURA
ARQUITETURA INTERATIVA
TRANSAÇÃO NO LIVRO-RAZÃO DE SALDO PRÉ-PAGO
ATORES DE SISTEMA PARTICIPANTES
P1 Leitor POS / E-Commerce
P2 API Principal Passinstance
P3 Base de Dados Passinstance database e Ledger
ETAPA 1 PEDIDO / AÇÃO POST/api/v1/reader/redeem
ETAPA 2 PEDIDO / AÇÃO Obter Conta
›
(Saldo Atual)
ETAPA 3 PEDIDO / AÇÃO Verificações Invariantes:
›
Status === ACTIVE
›
Saldo >= Débito
ETAPA 4 PEDIDO / AÇÃO Transação Atómica
›
Atualizar prepaid account
›
Inserir LedgerEntry
ETAPA 5 RESPOSTA 200 OK (resultingValue)
ETAPA 6 PEDIDO / AÇÃO Push APNs Silencioso
›
(Ecrã Bloq. Apple
›
e Google REST PATCH
›
"Pago €12,50. Novo
›
saldo: €37,50")

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. 1
    Representação em unidades monetárias mínimas: Os saldos são calculados em unidades inteiras mínimas (ex.: 2500 representa $25.00 USD e 1550 representa €15,50 EUR). Isto elimina erros de arredondamento de vírgula flutuante em transações de retalho de alta frequência.
  2. 2
    Prevenção de saldo negativo (disallowNegativeBalance: true): O servidor rejeita estritamente qualquer pedido de débito em que currentBalanceMinor - debitAmountMinor < 0, devolvendo HTTP 400 com o código de erro INSUFFICIENT_FUNDS.
  3. 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. 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

POST /api/v1/reader/redeem
Cabeçalhos
X-Reader-Secret <reader integration secret>
Content-Type application/json
JSON
{
  "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)

JSON
{
  "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 (com x-scanner-key) ou POST /api/v1/passes/:id/use / POST /api/v1/passes/:id/adjust-value (com autenticação Bearer/Chave API) e auditar transações via GET /api/v1/balance-changes?passId=<passId>. As regras de saldo pré-pago suportam StoredValueOperation (NONE, ADD, SUBTRACT, SET) e StoredValueAmountSource (FIXED, OPERATOR, MECHANIC). Utilize externalId na 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/:token e consultar o estado do pagamento em GET /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 account e 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.

Documentação de produto e API relacionada

Pronto para lançar o seu primeiro programa de cartões Wallet?

Crie o seu espaço de trabalho, configure o seu modelo e teste um cartão real na Apple Wallet e Google Wallet antes de escalar.