Skip to content
Guia da Central de Ajuda · Resgates e transações
4 min de leituraVerificado 2026-11-16

Movimentos em cartões-presente e saldo

Debite compras, processe carregamentos, impeça saldos negativos e consulte registos de transações.

Neste guia

Visão geral

Os cartões presente, passes de crédito em loja e carteiras pré-pagas de circuito fechado na Passinstance assentam num livro-razão imutável de partida dobrada (modelos prepaid account e prepaid ledger entry) em vez de um campo de texto desprotegido. Todos os montantes monetários são armazenados e calculados em unidades inteiras na subunidade monetária mínima (balanceMinor, como cêntimos), com bloqueio estrito ao nível da linha e invariantes de saldo não negativo (disallowNegativeBalance: true).

Importante: As deduções de valor armazenado falham de forma segura (fail closed) com decision: "FAILED" e reasonCode: "OUT_OF_BALANCE" sempre que a dedução solicitada exceder balanceMinor numa conta configurada com disallowNegativeBalance: true. Nunca calcule saldos no cliente; submeta sempre a variação da transação e deixe o livro-razão de backend confirmar o novo saldo.

Arquitetura do Livro-Razão de Valor Armazenado

FLUXO DE ARQUITETURA
ARQUITETURA INTERATIVA
FLUXO DA ARQUITETURA DO SISTEMA: DÉBITO EM RAZÃO PRÉ-PAGO E RESGATE EM LEITOR DE HARDWARE
ATORES DE SISTEMA PARTICIPANTES
P1 Scanner / Leitor de Hardware
P2 Controlador Scan / Reader / POS
P3 BD prepaid account & Razão
ETAPA 1a PEDIDO / AÇÃO POST/api/v1/scans
›
(StoredValueOp.SUBTRACT)
ETAPA 1b PEDIDO / AÇÃO POST/api/v1/reader/redeem
ETAPA 2 PEDIDO / AÇÃO SELECT ... FOR UPDATE
ETAPA 1c PEDIDO / AÇÃO POST/v1/pos/redeem
›
(Bloqueia linha conta)
›
(operation: DEDUCT_VALUE)
ETAPA 3 PEDIDO / AÇÃO Valida disallowNegativeBalance:
›
balanceMinor >= amountMinor
ETAPA 4 PEDIDO / AÇÃO Insere prepaid ledger entry
›
e Atualiza balanceMinor
ETAPA 5 RESPOSTA 200 OK (remainingBalance)
ETAPA 6 PEDIDO / AÇÃO Push APNs / Google Wallet

Superfícies de Resgate e Ajuste de Valor Armazenado

Consoante a sua configuração física de caixa ou fluxo de trabalho na consola de suporte, pode deduzir ou recarregar saldos pré-pagos através de quatro endpoints dedicados:

SuperfícieEndpointAutenticaçãoCaso de Utilização Principal
Scanner Móvel / WebPOST /api/v1/scansx-scanner-keyAplicação scanner da equipa configurada com StoredValueOperation (`NONEADDSUBTRACTSET) e StoredValueAmountSource (FIXEDOPERATORMECHANIC`).
Leitor NFC de HardwarePOST /api/v1/reader/redeemX-Reader-SecretOrquestração servidor-para-leitor que submete request payload (customerId, passId, amount, idempotencyKey). (Utilize POST /api/v1/reader/validate para verificação de entrada por código de barras.)
Terminal POS de RetalhoPOST /v1/pos/redeemToken do Terminal POS / BearerCaixas registadoras integradas que executam PosOperation.DEDUCT_VALUE com passRef (serialNumber, código de barras ou externalId) e clientTxRef.
Carregamento no Painel / AdminPOST /api/v1/passes/:id/adjust-valueJWT do Espaço de Trabalho / Chave API (pass:manage)Carregamentos manuais de cartão presente (action: "CREDIT"), reembolsos ou correções administrativas (action: "DEBIT").

1. Débito no Scanner de Balcão (POST /api/v1/scans)

Quando uma ScannerConfiguration utiliza StoredValueOperation.SUBTRACT e StoredValueAmountSource.OPERATOR, o operador de caixa introduz o total da compra e submete:

POST /api/v1/scans
Cabeçalhos
x-scanner-key sk_live_gift_register_02
x-idempotency-key scan-debit-20261116-4401
Content-Type application/json
JSON
{
  "scannedBarcodeValue": "PI-GFT-901244",
  "scannerConfigurationId": "scfg_giftcard_debit",
  "validationData": {
    "amount": 24.50,
    "currency": "EUR"
  },
  "operatorId": "emp_cashier_04"
}

Resposta (200 OK):

JSON
{
  "decision": "SUCCESS",
  "status": "ACCEPTED",
  "remainingBalance": "75.50",
  "effects": {
    "oldBalance": "100.00",
    "newBalance": "75.50",
    "transactionAmount": 24.50,
    "currency": "EUR",
    "amountBalanceBehavior": "ADD_VALUE"
  },
  "passSnapshot": {
    "id": "pass_gft_901244",
    "templateId": "tmpl_giftcard_eur",
    "serialNumber": "PI-GFT-901244",
    "externalId": "shopify_gift_901244",
    "status": "ACTIVE",
    "storedValue": "75.50"
  },
  "display": {
    "title": "€24.50 Deducted",
    "subtitle": "Remaining Balance: €75.50",
    "color": "success"
  }
}

2. Orquestração de Leitores de Hardware (POST /api/v1/reader/redeem)

Os gateways de leitores óticos e sem contacto do lado do servidor autenticam-se com o cabeçalho X-Reader-Secret (reader integration secret) e submetem request payload diretamente para /api/v1/reader/redeem (quando amount é omitido, o motor executa VALIDATE; quando fornecido, executa DEBIT):

POST /api/v1/reader/redeem
Cabeçalhos
X-Reader-Secret rsec_live_reader_terminal_09a8f1
Content-Type application/json
JSON
{
  "customerId": "c1a2b3c4-d5e6-4f7a-8b9c-0123456789ab",
  "passId": "f9e8d7c6-b5a4-4321-9876-543210fedcba",
  "amount": "15.00",
  "idempotencyKey": "nfc-01:tx-883920",
  "operatorId": "nfc_gate_berlin_01"
}

Resposta (200 OK):

JSON
{
  "success": true,
  "resultingValue": "60.50"
}

3. Integração POS de Retalho (POST /v1/pos/redeem)

Os sistemas de ponto de venda executam deduções atómicas com POST /v1/pos/redeem (montado sob /v1/pos, fora de /api/v1). passRef corresponde a qualquer token de passe, código de barras, serialNumber ou ao seu externalId de origem:

JSON
{
  "idempotencyKey": "tenant_01:reg_03:tx_994812",
  "passRef": "PI-GFT-901244",
  "terminalId": "reg_03",
  "operation": "DEDUCT_VALUE",
  "amount": 15.00,
  "currency": "EUR",
  "clientTxRef": "POS-INV-2026-994812"
}

Os valores PosOperation suportados são DISCOUNT, ADD_POINTS, DEDUCT_VALUE, ADD_STAMPS, VOID e CUSTOM. A resposta devolve walletPropagation (PosWalletPropagationStatus: QUEUED ou SKIPPED) quando as atualizações push em tempo real são colocadas em fila para APNs/Google Wallet.

4. Carregamentos Manuais e Correções (POST /api/v1/passes/:id/adjust-value)

Para reembolsos, créditos de apoio ao cliente ou carregamentos de cartões presente a partir do Painel ou de uma integração ERP, chame POST /api/v1/passes/:id/adjust-value com Idempotency-Key:

JSON
{
  "action": "CREDIT",
  "amount": "25.00",
  "reason": "Customer return store credit",
  "operatorId": "support_lead_02",
  "idempotencyKey": "adj-20261116-0041"
}

As ações de ajuste suportadas são CREDIT (adicionar saldo) e DEBIT (subtrair saldo).

Modelo de Livro-Razão de Partida Dobrada (prepaid account e prepaid ledger entry)

Cada passe de valor armazenado mantém um registo prepaid account emparelhado com linhas só de acréscimo (append-only) prepaid ledger entry:

CampoModeloTipoDescrição
balanceMinorprepaid accountIntSaldo atual na subunidade monetária mínima (ex.: 7550 = €75.50).
currencyprepaid accountStringCódigo de moeda ISO 4217 de 3 letras (EUR, USD, GBP, CHF).
disallowNegativeBalanceprepaid accountBooleanPredefinido como true; impõe balanceMinor >= 0 na camada de transação da base de dados.
deltaMinorprepaid ledger entryIntVariação inteira com sinal (-2450 para débito, +5000 para carregamento).
balanceAfterMinorprepaid ledger entryIntInstantâneo de balanceMinor imediatamente após o lançamento.
idempotencyKeyprepaid ledger entryStringChave única de transação que evita débitos duplicados em repetições de rede.

Para auditar todos os débitos históricos, carregamentos e referências de operadores, consulte GET /api/v1/mechanics/:mechanicId/passes/:passId/ledger ou GET /api/v1/balance-changes. Saiba mais em Cartões Presente e Cartões Pré-Pagos e Leitores NFC Compatíveis.

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.