API de gateway de pagamentos cripto: faturas, webhooks, payouts e marca branca

O que faz a API de um gateway de pagamentos cripto?

A API esconde a blockchain do seu código. Em vez de gerir nós, derivar endereços e contar confirmações, chama um endpoint para criar uma fatura, guarda o identificador do gateway e aguarda notificações. O gateway fixa a taxa de câmbio, vigia as redes, aplica o rastreio de AML e liquida no seu saldo.

A maioria dos gateways expõe os mesmos blocos com nomes diferentes: faturas ou encomendas para pagamentos de entrada, IPN ou callbacks para notificações, endpoints de conversão e saldo, e payouts ou levantamentos para transferências de saída. Existem sandboxes na maioria dos prestadores, por exemplo um anfitrião sandbox separado na CoinGate e uma conta sandbox na NOWPayments, e devem ser usadas antes de qualquer teste na mainnet.

• API de faturas: criar, consultar e cancelar pedidos de pagamento com preço em moeda fiduciária, ativos aceites, referência da encomenda e URL de callback
• Notificações: webhooks ou IPN a cada mudança de estado, normalmente assinados
• API de payouts: enviar criptomoedas ou moeda fiduciária a clientes, parceiros ou à sua própria carteira
• Taxas e moedas: listar ativos, redes e montantes mínimos suportados e cotações em tempo real
• Plugins e SDK: módulos prontos para plataformas de comércio eletrónico sobre a mesma API

Como funciona o ciclo de vida da fatura?

Cada gateway tem o seu próprio modelo de estados, pelo que deve mapeá-los para um pequeno conjunto interno antes de escrever a lógica de negócio. Só um estado final de pago deve libertar os bens; os estados intermédios existem porque uma transação pode ser vista na blockchain muito antes de ser seguro aceitá-la.

A tabela mapeia dois modelos de estados publicados para os estados de que a maioria das plataformas precisa. A CoinGate, por exemplo, faz expirar uma fatura por pagar 20 minutos depois de o cliente escolher um ativo e marca como inválidos os pagamentos sinalizados pelos controlos de AML.

Como verificar webhooks e IPN de criptomoedas?

Trate cada notificação como não fiável até estar verificada. Os gateways usam esquemas diferentes: a NOWPayments assina o corpo JSON ordenado com HMAC-SHA512 e envia-o no cabeçalho x-nowpayments-sig, a CoinGate envia um token que define na encomenda e a BitPay recomenda obter a fatura pela API após cada notificação em vez de confiar no seu conteúdo.

O padrão mais seguro combina ambos: verificar a assinatura e depois ler a fatura pela API e agir com base nessa resposta. Custa um pedido por mudança de estado e protege-o de callbacks forjados ou repetidos.

• Verificar assinaturas com comparação em tempo constante e rejeitar pedidos não assinados
• Voltar a obter a fatura pelo seu ID no gateway antes de alterar o estado da encomenda
• Devolver HTTP 200 rapidamente e processar de forma assíncrona; os gateways repetem em caso de erro
• Guardar cada notificação com o respetivo evento ou estado para ignorar duplicados
• Nunca confiar em montantes ou moedas enviados no redirecionamento do navegador

Como tratar pagamentos a menos, a mais e tardios?

As carteiras e exchanges deduzem taxas de levantamento e os clientes copiam mal os montantes, pelo que não se pode presumir um pagamento exato. Defina uma tolerância e uma regra para cada caso antes do lançamento e dê visibilidade do resultado à equipa de suporte.

Como funcionam a idempotência e a reconciliação?

Crie as faturas com a sua própria referência de encomenda e torne a chamada segura para repetir: se o pedido expirar, procure a fatura pela referência antes de criar outra, ou use uma chave de idempotência quando o gateway a suporte. A mesma regra vale para payouts, onde um pedido duplicado envia dinheiro real duas vezes.

Para a reconciliação, guarde o ID da fatura no gateway, o hash da transação, o montante em moeda fiduciária, o montante em criptomoeda, a taxa e as comissões. Os relatórios de liquidação listam os payouts em lotes, pelo que o cruzamento vai da encomenda à fatura e ao payout, e não da encomenda à linha bancária.

O que precisa uma API de payouts face à Travel Rule?

Os endpoints de payout enviam criptomoedas do saldo do seu gateway para um endereço, muitas vezes em lotes para comissões de afiliados, vendedores de marketplaces ou levantamentos de clientes. A maioria exige lista branca de endereços, aprovação com dois fatores ou uma chave de API com permissões de payout separadas.

Na UE, o Regulamento (UE) 2023/1113 exige que o gateway transmita as informações do ordenante e do beneficiário com cada transferência e verifique a titularidade de carteiras próprias acima de 1000 €. Conte com pedidos de payout que incluam o nome do beneficiário e o tipo de endereço, e preveja transferências que esperam por estes dados.

Que opções de gateway de pagamentos cripto em marca branca existem?

As plataformas que revendem pagamentos aos seus próprios comerciantes querem muitas vezes a página de pagamento com a sua marca. Há três níveis, e o preço sobe com o controlo. A Plisio, por exemplo, indica 0,5 % para a API e 1,5 % para a marca branca, e a NOWPayments vende um produto de marca branca separado.

A marca branca completa desloca responsabilidade além da imagem. Se integrar comerciantes e detiver os seus saldos, pode precisar da sua própria autorização MiCA; usar o modelo de subcomerciantes de um gateway autorizado mantém essa obrigação no gateway.

Como ligar APIs de gateways cripto através da OrsunPay?

A OrsunPay uniformiza estados, webhooks e reembolsos de gateways cripto numa só API, ao lado dos seus prestadores de cartões e pagamentos bancários, usando as suas próprias contas de gateway. Não guarda criptomoedas nem faz payouts a partir de um saldo próprio: encaminha os pedidos para o gateway escolhido e devolve eventos assinados e sem duplicados.

Como integrar a API de um gateway de pagamentos em criptomoedas

1. Abrir contas sandbox Crie contas sandbox e de produção no gateway, gere chaves de API separadas para faturas e payouts e defina o segredo do IPN.
2. Mapear os estados Traduza os estados do gateway para os seus estados internos e decida qual liberta os bens.
3. Criar faturas de forma idempotente Envie montante em moeda fiduciária, moeda, referência da encomenda e URL de callback; procure pela referência antes de repetir uma chamada que expirou.
4. Verificar as notificações Verifique a assinatura, volte a obter a fatura pela API e processe o evento uma só vez.
5. Tratar os casos limite Implemente tolerância, complemento, reembolso e expiração, e teste cada um no sandbox.
6. Reconciliar as liquidações Guarde hash da transação, taxa e comissões por fatura e cruze diariamente os lotes de payouts com as encomendas.