Copy page

Documentação

Perguntas frequentes

Perguntas gerais

O que é Fluxis?

Fluxis é uma plataforma de infraestrutura de pagamentos que permite que empresas aceitem pagamentos com criptomoedas em múltiplas redes blockchain. Fornecemos uma API unificada que simplifica a integração de pagamentos com ativos digitais em seus sistemas existentes, seja você operando uma loja de e-commerce, um app móvel ou um terminal físico de ponto de venda.

Como o Fluxis difere de outros processadores de pagamento com cripto?

O Fluxis usa o padrão NASPIP (Native Asset Signed Payment Instructions Protocol), que oferece:

• Suporte multirrede - Aceite stablecoins EVM em redes compatíveis (ex.: Polygon, Base, Avalanche, Arbitrum e redes adicionais conforme a configuração da sua conta) a partir de uma única integração
• Flexibilidade de ativos - Suporte a múltiplas stablecoins e criptomoedas simultaneamente
• Segurança criptográfica - Todas as instruções de pagamento são assinadas e verificáveis
• Protocolo padronizado - Compatível com qualquer carteira conforme NASPIP

Saiba mais em nosso Guia de comparação.

Preciso de conhecimento em blockchain para integrar o Fluxis?

Não. O Fluxis abstrai a complexidade das interações com blockchain. Você trabalha com uma API REST simples — cria solicitações de pagamento, monitora mudanças de status e recebe notificações por webhook. Nossa API trata de todas as operações específicas de blockchain nos bastidores.

Quais criptomoedas posso aceitar?

O Fluxis suporta qualquer token compatível com EVM em redes compatíveis. A maioria dos comerciantes aceita stablecoins como USDC e USDT para evitar volatilidade. Você pode configurar quais ativos aceitar pelas opções de pagamento do seu Point of Sale.

Veja a lista completa de redes e ativos compatíveis em nossa documentação UAI.

Primeiros passos

Como me cadastro como comerciante?

Siga nosso guia de Cadastro de comerciantes. Você precisará de:

• Nome legal do negócio
• Número de identificação fiscal
• País de registro
• E-mail do proprietário

Após o envio, nossa equipe analisa sua solicitação (1-2 dias úteis) e envia credenciais API após aprovação.

Quanto tempo leva o processo de aprovação?

Normalmente 1-2 dias úteis. Verificamos as informações do seu negócio para garantir conformidade com requisitos KYB (Know Your Business). Você receberá um e-mail quando sua solicitação for aprovada ou se forem necessárias informações adicionais.

Quais são os requisitos de integração?

Você precisa de:

• Servidor backend - Para armazenar credenciais API com segurança e tratar autenticação
• Endpoint HTTPS - Para receber notificações por webhook (recomendado)
• Conhecimento básico de API REST - Para fazer requisições HTTP à nossa API

Nosso guia de Autenticação e configuração orienta todo o processo de configuração.

Existe ambiente sandbox ou de testes?

Sim. O Fluxis oferece um ambiente de staging para testes de integração antes do go-live em produção.

• Host API staging: https://api.stgfluxis.us
• Host API produção: https://api.fluxis.us

Chaves API de staging são emitidas pelo seu representante Fluxis (formato: fxs.stg.<uuid>). Use staging para construir e testar sua integração; credenciais de produção são habilitadas após aprovação em staging.

Consulte o Guia de integração da API para detalhes dos ambientes.

Pontos de venda

O que é um Point of Sale?

Um Point of Sale (PoS) é um ponto de coleta de pagamentos dentro do Fluxis. Pense nele como um caixa virtual onde você gera solicitações de pagamento. Cada PoS pode ter sua própria configuração, incluindo quais criptomoedas aceitar e branding do comerciante. Webhooks são configurados no nível da conta (POST /v1/account/{accountID}/webhook), não por PoS — consulte Webhooks.

Leia mais em nosso Guia de Point of Sale.

Quantos Point of Sales posso criar?

Não há limite no número de Point of Sales que você pode criar. Muitos comerciantes criam instâncias PoS separadas para:

• Diferentes locais físicos
• Diferentes unidades de negócio ou departamentos
• Diferentes categorias de produtos
• Ambientes de desenvolvimento, staging e produção

Posso atualizar a configuração do meu Point of Sale?

Sim. Você pode atualizar a qualquer momento o nome, opções de pagamento e informações do comerciante do seu Point of Sale pela API. Use o endpoint de atualização de Point of Sale em nossa Referência da API.

O que são opções de pagamento?

Opções de pagamento são a lista de criptomoedas e redes que seu Point of Sale aceita. São definidas usando Unique Asset Identifiers (UAIs). Por exemplo:

• npolygon_t0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359 - USDC na Polygon
• nerc20_t0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 - USDC na Ethereum

Ao criar uma solicitação de pagamento, clientes podem pagar com qualquer opção de pagamento configurada.

Solicitações de pagamento

Por quanto tempo uma solicitação de pagamento permanece ativa?

A expiração depende do fluxo de pagamento:

• Intenção de pagamento (modo caixa): A intenção ativa expira 5 minutos após a criação.
• Solicitação de pagamento (após o pagador selecionar um ativo): A solicitação geralmente é válida por 8 minutos a partir da atribuição (timestamp Unix expiration na resposta da API).

Se uma solicitação expirar antes da conclusão do pagamento, crie uma nova solicitação de pagamento ou intenção de pagamento. Uma vez com status expired, a plataforma não continua associando novos depósitos on-chain a essa solicitação — incentive pagadores a concluir o pagamento antes da expiração e exiba uma contagem regressiva na sua UI.

O que acontece se um cliente pagar após a expiração?

Pagamentos devem chegar ao endereço atribuído enquanto a solicitação de pagamento ainda estiver em status created ou processing. Após a solicitação ser marcada como expired, crie uma nova solicitação de pagamento para tentativas subsequentes.

Posso criar solicitações de pagamento sem valor fixo?

Atualmente, todas as solicitações de pagamento exigem um valor específico. O campo amount garante verificação e rastreamento de status do pagamento. Para cenários de preço variável, calcule o valor na sua aplicação antes de criar a solicitação de pagamento.

O que é um token NASPIP?

NASPIP (Native Asset Signed Payment Instructions Protocol) é o token assinado criptograficamente que contém todas as instruções de pagamento. Ao criar uma solicitação de pagamento, o Fluxis gera um token NASPIP que você pode:

• Exibir como código QR para carteiras móveis
• Compartilhar como link de pagamento para carteiras web
• Compartilhar como deep link ou URL de checkout hospedado (suporte a proximidade/NFC varia conforme o app de carteira)

O token inclui endereço de pagamento, valor, ativo, rede e expiração — tudo que uma carteira precisa para concluir o pagamento.

Saiba mais sobre NASPIP.

Posso reutilizar uma solicitação de pagamento?

Não. Cada solicitação de pagamento é de uso único e vinculada a uma transação específica. Uma vez concluída, expirada ou cancelada, você deve criar uma nova solicitação de pagamento para transações subsequentes. Isso garante integridade do pagamento e contabilidade correta.

Monitoramento de pagamentos

Como sei quando um pagamento é concluído?

Há duas abordagens:

1. Webhooks (Recomendado) - Configure uma URL de webhook para receber notificações em tempo real quando o status do pagamento mudar. Consulte Webhooks.

2. Polling - Verifique periodicamente o status da solicitação de pagamento usando o endpoint GET. Consulte nossa Referência da API.

Para sistemas de produção, recomendamos fortemente implementar webhooks para notificações instantâneas.

Qual é a diferença entre 'processing' e 'completed'?

• processing - Pagamento detectado on-chain; aguardando verificações de finalidade
• completed - Valor do pagamento corresponde à solicitação e requisitos de finalidade foram atendidos
• confirmed - Uma transação confirmada no ledger foi registrada para o pagamento

Aguarde completed (ou seu status terminal acordado) antes de cumprir pedidos. Use webhooks em vez de polling quando possível.

E se um cliente pagar a menos ou a mais?

Solicitações de pagamento podem resultar em três estados de caso limite:

• underpaid - Cliente pagou menos que o valor solicitado
• overpaid - Cliente pagou mais que o valor solicitado
• failed - Erro inesperado durante o processamento

Para pagamentos underpaid ou overpaid, use a API de reembolsos (POST /v1/refunds/payment-request/{paymentRequestID}) para devolver fundos a um endereço on-chain especificado. O valor é opcional — para pagamentos overpaid, omitir o valor reembolsa o excedente por padrão.

Entre em contato com [email protected] se precisar de ajuda para escolher a resolução correta conforme suas regras de negócio.

Consulte Casos limite do fluxo de pagamento, o Guia de integração da API e Webhooks.

Quantas confirmações de blockchain o Fluxis aguarda?

Requisitos de finalidade são específicos da rede e configurados por implantação. O Fluxis aguarda até que o limiar de finalidade configurado seja atingido antes de tratar um pagamento como final (geralmente refletido como status completed ou confirmed).

Monitoramento de blocos em produção roda atualmente em Polygon, Base, Avalanche e Arbitrum. Outras redes podem aparecer nas opções de pagamento (UAIs) mas nem todas são monitoradas ativamente em todos os ambientes — confirme redes compatíveis com seu representante Fluxis.

Não codifique contagens de confirmação na sua integração; confie no status da solicitação de pagamento e nos webhooks.

Segurança e autenticação

Como mantenho minhas credenciais API seguras?

Siga estas boas práticas:

• Nunca faça commit de credenciais em sistemas de controle de versão
• Use variáveis de ambiente ou um gerenciador de segredos (AWS Secrets Manager, HashiCorp Vault)
• Rotacione credenciais regularmente para maior segurança
• Limite o acesso apenas a membros da equipe que precisem
• Monitore o uso em busca de atividade suspeita

Consulte nosso guia de Boas práticas de segurança.

Por quanto tempo os tokens de acesso são válidos?

Tokens de acesso expiram após 1 hora. Armazene em cache e reutilize tokens até expirarem em vez de solicitar um novo token a cada chamada à API. Implemente renovação automática de tokens na sua aplicação para manter serviço ininterrupto.

Posso revogar credenciais API?

Sim. Administradores da organização podem desabilitar chaves API no painel Fluxis. Chaves desabilitadas não podem mais obter tokens de acesso. Se suspeitar que uma credencial foi comprometida, desabilite-a imediatamente e solicite substituição ao seu representante Fluxis.

Como verifico a autenticidade dos webhooks?

Ao criar um webhook de conta, o Fluxis retorna um segredo uma única vez. Cada entrega inclui os headers X-Request-Signature e X-Request-Timestamp. Verifique a assinatura HMAC-SHA256 sobre o corpo JSON completo antes de processar o payload.

Consulte Verificação de assinatura de webhooks para o algoritmo, exemplo resolvido e endpoint de teste. Registro e tipos de evento estão em Webhooks.

Cobrança e preços

Quanto custa o Fluxis?

Informações de preços e planos estão disponíveis entrando em contato com nossa equipe comercial em [email protected]. Oferecemos preços flexíveis com base em volume de transações, recursos e requisitos de suporte.

Há taxas por transação?

Taxas por transação variam conforme plano e volume. Entre em contato com [email protected] para informações detalhadas de preços adaptadas às necessidades do seu negócio.

Pago taxas de rede blockchain?

Clientes pagam as taxas de rede blockchain (gas) ao enviar o pagamento. O Fluxis trata consolidação e tesouraria, o que pode ter custos associados conforme seu plano.

Perguntas técnicas

Quais limites de taxa existem na API?

Limites de taxa são projetados para ser generosos em uso normal enquanto previnem abusos. Limites específicos dependem do seu plano. Se encontrar erros de limitação de taxa, implemente backoff exponencial e entre em contato com suporte para discutir aumento dos seus limites.

Quais linguagens de programação são compatíveis?

Fluxis é uma API REST que funciona com qualquer linguagem de programação capaz de fazer requisições HTTP.

SDKs oficiais para Node.js/TypeScript, Python e Go estão planejados mas ainda não foram lançados. Integre via HTTP usando o Guia de integração da API e a Referência da API.

Entre na lista de acesso antecipado em Documentação de SDK se quiser receber notificações sobre SDKs.

Posso usar Fluxis em um app móvel?

Sim. Porém, nunca armazene credenciais API em código client-side (apps móveis, navegadores web). Em vez disso:

1. Seu app móvel se comunica com seu servidor backend
2. Seu servidor backend autentica com segurança no Fluxis
3. Seu backend cria solicitações de pagamento e as retorna ao app
4. Seu app exibe o token NASPIP (como código QR) ao cliente

Essa arquitetura mantém credenciais seguras enquanto permite integração móvel.

O Fluxis suporta webhooks?

Sim. Webhooks são a forma recomendada de receber atualizações de status de pagamento em tempo real. Registre endpoints de webhook no nível da conta via POST /v1/account/{accountID}/webhook. O Fluxis enviará POST com mudanças de status de pagamento ao seu endpoint quando eventos correspondentes ocorrerem para essa conta.

Consulte Webhooks e o Guia de integração da API.

Saiba mais em nossa Documentação de webhooks.

Quais métodos HTTP a API usa?

A API Fluxis segue convenções RESTful:

• GET - Recuperar recursos (solicitações de pagamento, Point of Sales, etc.)
• POST - Criar novos recursos (solicitações de pagamento, Point of Sales, etc.)
• PUT - Atualizar recursos existentes (configuração de Point of Sale, etc.)
• DELETE - Remover recursos (Point of Sales, etc.)

Consulte nossa Referência da API para documentação completa de endpoints.

Solução de problemas

Estou recebendo erros de autenticação. O que devo verificar?

Problemas comuns de autenticação:

1. Credenciais inválidas - Verifique sua chave API e segredo; obtenha um novo token via POST /v1/auth/token
2. Token expirado - Tokens de acesso expiram após 1 hora; solicite um novo
3. Headers ausentes - Rotas protegidas exigem ambos Authorization: Bearer <token> e x-fluxis-api-key: <api_key>
4. Ambiente errado - Use staging (api.stgfluxis.us + chaves fxs.stg.*) vs produção (api.fluxis.us) de forma consistente

Teste sua autenticação em nosso API Playground - Authentication.

A criação de solicitação de pagamento falha. Por quê?

Causas comuns:

• ID de Point of Sale inválido - Verifique se o PoS existe e pertence à sua organização
• UAI inválido - Verifique se o Unique Asset ID está formatado corretamente
• Valor inválido - O valor deve ser uma string decimal positiva (ex.: "49.99")
• Token expirado - Renove seu token de autenticação

Revise a mensagem de erro na resposta da API para detalhes específicos.

Cliente pagou mas o status não atualiza. O que está errado?

Verifique estes cenários:

• Endereço errado - Cliente pode ter enviado pagamento para endereço incorreto
• Rede errada - Pagamento enviado em rede diferente da especificada
• Ativo errado - Pagamento enviado com token diferente do solicitado
• Confirmação pendente - Transação ainda aguardando confirmações de blockchain
• Congestionamento de rede - Rede blockchain pode estar com atrasos

Peça ao cliente o hash da transação e verifique em um explorador de blockchain.

Webhooks não estão sendo recebidos. Como depuro?

Passos de solução de problemas:

1. Confirme registro do webhook de conta - Use POST /v1/account/{accountID}/webhook (não configurações do PoS)
2. Verifique se a URL é pública - Teste acessar seu endpoint de webhook externamente
3. Verifique certificado SSL - Garanta certificado HTTPS válido
4. Revise logs do servidor - Procure requisições entrantes do Fluxis
5. Envie entrega de teste - POST /v1/account/{accountID}/webhook/{webhookID}/test
6. Verifique bloqueios de firewall - Garanta que IPs do Fluxis não estejam bloqueados
7. Verifique resposta do endpoint - Handler de webhook deve retornar código de status 2xx

Se entregas chegam mas seu handler as rejeita, consulte Verificação de assinatura de webhooks para JSON canônico e solução de problemas HMAC.

Entre em contato com suporte se problemas persistirem após essas verificações.

Suporte e recursos

Como entro em contato com suporte?

• E-mail: [email protected]
• Tempo de resposta: Dentro de 24 horas em dias úteis
• Para problemas urgentes: Inclua "URGENT" no assunto do e-mail

Onde encontro exemplos de código?

• API Playground: Exemplos interativos para todos os endpoints em /api
• Tutoriais: Guias passo a passo em nossa seção de desenvolvedores
• Documentação de SDK: Exemplos específicos por linguagem em nossa documentação de SDK

Existe uma comunidade de desenvolvedores?

Estamos construindo nossos recursos de comunidade de desenvolvedores. Fique atento a:

• Canal Discord/Slack para desenvolvedores
• Discussões no GitHub
• Fórum comunitário
• Office hours regulares

Assine nossa newsletter ou siga nosso blog para anúncios.

Onde posso reportar bugs ou solicitar recursos?

Para reportes de bugs ou solicitações de recursos:

• E-mail: [email protected]
• Inclua: Descrição detalhada, passos para reproduzir, comportamento esperado vs atual
• Solicitações de recursos: Inclua caso de uso e justificativa de negócio

Consulte nosso Roadmap para ver recursos futuros.

---

Ainda tem dúvidas?

Se sua pergunta não foi respondida aqui, entre em contato conosco em [email protected]. Estamos aqui para ajudar!