Payments

O template oferece deposito e saque com suporte a multiplos metodos de pagamento por pais.

Metodos suportados

Metodo	Paises	Descricao
PIX	Brasil	QR code ou copia-e-cola
SPEI	Mexico	Transferencia bancaria (CLABE)
OXXO	Mexico	Pagamento em loja (barcode)
Credit Card	Chile, Mexico, Peru, Finlandia	Gateway de pagamento (iframe)
Kushki	Chile	Tokenizacao de cartao no browser (SDK)
Bank Transfer	Chile	Transferencia bancaria (iframe)
Khipu	Chile	Pagamento via Khipu (iframe)
Wallet/MACH	Chile	QR code + deep-link para app
AstroPay	Multi	Redirect para AstroPay
Worldline	Multi	Redirect para Worldline
WebPay	Chile	Redirect externo (nova aba)
Crypto	Multi	Carteira de criptomoedas

Os metodos disponiveis sao determinados pelo BFF, a partir do pais e moeda da marca. O front nunca exibe um metodo que o BFF nao devolveu.

Arquivos de configuracao

Todos ficam em app/config/payments/ e sao overridaveis por marca (overrides/<brand-key>/app/config/payments/<arquivo>.ts):

Arquivo	Export	Para que serve
deposit.ts	depositConfig	Atalhos de valor por moeda
methods.ts	paymentsConfig	Allow-list de metodos em deposito e saque
kushki.ts	kushkiConfig	merchantId do gateway Kushki (Chile)
testers.ts	paymentTestersConfig	IDs de usuario que enxergam metodos marcados como teste pelo BFF

:::danger Override e substituicao do arquivo inteiro Nao ha deep-merge: se o arquivo existe no diretorio da sua marca, ele substitui o do base por completo. Copie o arquivo base e edite os valores. :::

Restringindo os metodos disponiveis

Por default o template passa tudo que o BFF retornar:

// app/config/payments/methods.ts
export const paymentsConfig: PaymentsConfig = {
  deposit: "all",
  withdraw: "all",
  groupPixProviders: true,
};

Campo	Valores	Efeito
deposit	"all" ou array de slugs	Metodos aceitos no deposito. Array vazio = nenhum metodo visivel.
withdraw	"all" ou array de slugs	Idem para saque, independente do deposito.
groupPixProviders	boolean (default true)	Colapsa multiplos providers Pix em um unico card "Pix" no seletor. false expoe cada banco separadamente.

Use a allow-list quando precisar remover um metodo que o BFF expoe (ex: tirar crypto da sua marca) — o filtro e sempre subtrativo sobre a resposta do BFF.

Para habilitar um metodo que o BFF ainda nao expoe, fale com o time da plataforma: isso e configuracao de backend, nao do fork.

Kushki (Chile)

O merchantId do Kushki e publico — ele vai ao browser na propria chamada do SDK de tokenizacao. As secret keys, que autorizam transacoes, ficam no backend.

// overrides/<brand-key>/app/config/payments/kushki.ts
export const kushkiConfig: KushkiConfig = {
  merchantId: "seu-merchant-id-publico",
  testEnvironment: false,
};

Com merchantId vazio (default do base) o hook opera em modo de desenvolvimento e retorna tokens simulados. Marcas que nao usam Kushki nao precisam declarar nada — o metodo nem aparece no seletor.

Atalhos de valor

Edite app/config/payments/deposit.ts para personalizar os valores de atalho por moeda:

export const depositConfig = {
  shortcuts: {
    BRL: [
      { value: 20 },
      { value: 50, hot: true },  // destaque visual
      { value: 100 },
      { value: 250, hot: true },
      { value: 500 },
      { value: 1000, hot: true },
    ],
    CLP: [
      { value: 5000 },
      { value: 20000, hot: true },
      { value: 50000, hot: true },
      { value: 200000 },
      { value: 400000, hot: true },
      { value: 800000 },
    ],
    // MXN, ARS, COP, UYU, INR, NGN, PEN, PHP, EUR...
  },
  defaultShortcuts: [
    { value: 20 },
    { value: 50, hot: true },
    { value: 100 },
    { value: 250, hot: true },
    { value: 500 },
    { value: 1000, hot: true },
  ],
};

• value — valor em unidades da moeda (nao em centavos)
• hot: true — adiciona destaque visual ao botao
• Moedas sem configuracao usam defaultShortcuts
• Moedas com atalhos pre-configurados: BRL, MXN, ARS, CLP, COP, UYU, INR, NGN, PEN, PHP, EUR

Limites

Os limites de deposito e saque sao definidos pela API (brand settings). O template so usa os valores abaixo como fallback quando a API nao devolve o limite — em centavos:

Limite	Fallback (centavos)
Deposito minimo	100
Deposito maximo	4.900.000
Saque minimo	100
Saque maximo	50.000

Nao ajuste esses fallbacks no fork esperando mudar os limites reais da marca — os limites de producao vem da API.

observação

Atencao a unidade: limites em centavos (vem da API), atalhos de valor em unidades da moeda (config do fork). Nao e inconsistencia — sao duas fontes diferentes, e o template converte na hora de comparar.

Contrato v3 (paymentsV3)

Existe uma flag paymentsV3 em app/config/features/features.ts, desligada por default. Ela troca o contrato de pagamentos com o backend (identificador idempotente de requisicao, novo codigo de provider, nova maquina de estados).

aviso

Nao ligue essa flag por conta propria — ela depende de o backend da sua marca ja estar no contrato v3. Fale com o time da plataforma antes.

Cupom promocional

O modal de deposito inclui campo de cupom. Cupons sao validados via API e aplicam bonus ao deposito.

Chave PIX (Brasil)

Para marcas brasileiras, o template gerencia a chave PIX do usuario (tipos: CPF, CNPJ, email, telefone, aleatoria). A chave e exibida/atualizada no fluxo de saque.

Conta bancaria (Mexico)

Para marcas mexicanas, o template gerencia a conta bancaria SPEI (CLABE + banco) para saques.

Conta bancaria (Chile)

Para marcas chilenas, o template gerencia a conta bancaria generica (tipo de conta, codigo do banco, numero) para saques via bank-transfer.

Icones de pagamento

Os icones dos metodos de pagamento sao fornecidos automaticamente pelo pacote @cactus-agents/payments. Nao e necessario gerenciar icones manualmente — eles sao copiados para public/icons/ automaticamente pelo build.

Para adicionar icones customizados, coloque SVGs em public/icons/payments/ (eles terao prioridade sobre os do pacote).