Configuração do gateway de pagamento

Um gateway de pagamento é o que realmente movimenta o dinheiro. O GCM não mantém contas de merchant — em vez disso, nos conectamos a um gateway que você (ou a plataforma) já tem, e passamos os detalhes do cartão para ele em cada cobrança.

Este é o mesmo motor que alimenta o formulário de doação online, as doações recorrentes e o faturamento da sua assinatura mensal.

Padrão da plataforma vs seu próprio gateway

Quando você cria uma organização, o GCM usa por padrão o gateway da plataforma — os repasses caem na conta de retenção do GCM e remetemos para o seu banco semanalmente. Esta é a maneira mais rápida de começar a aceitar doações, e a maioria das igrejas permanece nele no primeiro mês.

Você troca para seu próprio gateway quando:

• Quer que os repasses caiam diretamente no banco da igreja, sem conta de retenção no meio.
• Seu processador oferece taxas mais baixas que o padrão da plataforma.
• Você opera em um país onde o padrão da plataforma não repassa.
• Seu conselho tem motivos de conformidade para ser dono da relação com o merchant.

Em Settings → Payment gateway, ative Use your own gateway. Os campos de credenciais aparecem abaixo.

TIP

Você pode voltar ao padrão da plataforma a qualquer momento. Doações recorrentes existentes continuam usando o gateway que registrou seu token — mas novas usam o gateway ativo.

Gateways suportados

Gateway	Tipo	Recorrente	Ideal para
PowerTranz (Direct)	API	sim	Caribe / LATAM; doação recorrente
PowerTranz (Hosted Page)	Redirecionamento	não (apenas único)	escopo PCI mínimo
Genius Checkout	Redirecionamento	sim (via tokens)	cobertura global, checkout hospedado

PowerTranz é o gateway mais usado em nossa base de usuários por causa da forte cobertura caribenha e latino-americana. Genius Checkout é a opção global — é uma página hospedada que repassa em mais de 52 moedas.

PowerTranz (Direct)

Direct significa que o GCM coleta os detalhes do cartão e faz POST para a API da PowerTranz. O pagador nunca sai do seu domínio. Isso é necessário se você quiser doação recorrente — apenas o adaptador direto suporta cartão em arquivo tokenizado.

Você precisará da sua gerente de conta da PowerTranz:

• PowerTranz ID — seu ID de merchant, ex.: 88803195.
• Password — a senha da API (somente escrita — criptografamos em repouso).
• Acquirer ID — às vezes exigido pelo seu adquirente (ex.: 464748).
• Environment — staging enquanto você testa, production quando entrar em produção.
• Capture mode — Sale (cobrar imediatamente) ou Auth + Capture (segurar os fundos, capturar depois).

Após salvar, clique em Test connection. Atingimos um endpoint de baixo custo que confirma que as credenciais chegam à PowerTranz com sucesso. Um badge verde aparece quando verificado.

PowerTranz (Hosted Page)

A versão página hospedada (HPP) da PowerTranz coloca o formulário de cartão no domínio da PowerTranz, não no seu. O pagador insere os detalhes do cartão lá e nunca vemos o PAN. Esta é a opção com menor exposição PCI.

Mesmas credenciais que o adaptador direct, mais:

• Hosted Page Set — o ID do conjunto de páginas que a PowerTranz provisionou para você.
• Hosted Page Name — a página dentro do conjunto.

Trade-off: o adaptador HPP não suporta doação recorrente. A PowerTranz só consegue tokenizar um cartão durante uma sessão de navegador, e cobranças recorrentes acontecem em um cronograma sem navegador. Se você quer recorrência com PowerTranz, use o adaptador direct.

Genius Checkout

Genius Checkout (GC) é nossa opção preferida para igrejas sem relação existente com processador. É uma página de pagamento hospedada como o PowerTranz HPP, mas também suporta cobranças recorrentes via tokens de longa duração.

Você só precisa de uma credencial:

• GC API key — começa com gc_test_… ou gc_live_….

A integração lida com tudo o mais automaticamente: sessões de checkout, redirecionamentos de sucesso / falha, callbacks de webhook assinados, mudanças de estado de assinatura. Mapeamos os códigos de moeda numéricos ISO 4217 internos do GCM para os códigos alfabéticos do GC — 52 moedas suportadas, incluindo USD, EUR, GBP, JMD, KES, NGN, ZAR.

Como os dados de cartão são armazenados

Uma vez que um cartão é tokenizado, armazenamos:

• Um token de gateway (o SpiToken da PowerTranz ou o tok_… do GC).
• A bandeira do cartão (Visa, Mastercard, …).
• Os últimos 4 dígitos.
• O mês + ano de validade.

O PAN completo nunca cai em nosso banco de dados. Para doações recorrentes e cartões salvos, o GCM cobra do token — o gateway o resolve de volta para o cartão subjacente do seu lado.

Testando o fluxo

Antes de ir para produção, faça uma doação de $1 pelo formulário de doação usando um cartão de teste:

Gateway	Cartão aprovado	Cartão recusado
PowerTranz	4111 1111 1111 1111	4000 0000 0000 0002
Genius Checkout	4242 4242 4242 4242	4000 0000 0000 9995

Todos os gateways aceitam qualquer data de validade futura e qualquer CVV de 3 dígitos em modo de teste.

Reembolsos e estornos

Ambos os gateways suportam reembolsos totais e parciais de dentro do GCM. Abra uma doação em Giving → Donations, clique no menu de ações e escolha Refund. O gateway processa o estorno, a linha de doação recebe um refunded_amount, e uma linha é anexada a payment_attempts para a trilha de auditoria.

Estornos (zerar uma autorização antes da captura) só fazem sentido em modo Auth + Capture — eles liberam a retenção sem nunca cobrar o cartão.

Trocando gateways depois

Quando você troca gateways ativos:

• Doações únicas começam a usar o novo gateway imediatamente.
• Doações recorrentes continuam cobrando no gateway antigo até você migrar os cartões — tokens não são portáteis entre processadores. Para a maioria das igrejas, o caminho mais limpo é enviar aos doadores um link "atualize seu cartão, por favor" em vez de tentar migrar tokens.

Referências cruzadas

• Formulário de doação online — onde esses gateways são realmente usados.
• Doações recorrentes — ciclo de vida de tokens e tratamento de renovação.
• Referência de webhooks — assinaturas de webhooks de gateway.