Número único da operação
Ele conecta o jogador, valor, moeda, método de pagamento, provedor de pagamento e todo o histórico de processamento.
Documentação / Fluxo de Pagamentos
Como funciona a API de pagamentos
Veja o caminho completo do pagamento: desde a criação de um depósito e a confirmação do pagamento até o crédito de fundos, saques, reembolsos e conciliação financeira.
Depósito
criação e crédito
Pagamento
verificação e envio
Status
confirmação da operação
Conciliação
controle financeiro
Fluxo de pagamentos
Da solicitação ao resultado final
01
Criar a operação
Registrar o jogador, valor, moeda, método de pagamento e número único da operação.
02
Confirmar o pagamento
Redirecionar o jogador para a página de pagamento, solicitar confirmação bancária ou processar o pagamento diretamente.
03
Receber o status final
Verificar a resposta do provedor de pagamento e confirmar o resultado final da operação.
04
Atualizar saldo e contabilidade
Creditar ou debitar fundos uma única vez, contabilizar a taxa e registrar a operação para conciliação.
Visão geral
Cada pagamento segue etapas controladas
A plataforma atribui seu próprio número de operação, vincula-o à resposta do provedor de pagamento e altera o estado financeiro somente após um resultado confirmado. Uma requisição repetida não deve criar um segundo débito ou crédito.
Status claros
A operação avança apenas pelas etapas permitidas e não altera um resultado concluído sem um ajuste separado.
Contabilidade financeira separada
O status do pagamento, a alteração de saldo, a taxa e o lançamento contábil são vinculados, mas verificados separadamente.
Fluxo de depósito
Fluxo típico de depósito
Um depósito começa com uma operação interna e termina com um único crédito após a confirmação do provedor de pagamento.
01
Validar a solicitação e criar a operação
A plataforma verifica o jogador, KYC, limites, moeda, valor e método de pagamento e, em seguida, atribui um número interno à operação.
02
Enviar o pagamento ao provedor
O provedor recebe o valor, moeda, dados do jogador, URL de retorno, URL de notificação e os dados de pagamento necessários.
03
Confirmar o pagamento
O jogador confirma o pagamento em uma página externa, por 3-D Secure ou em um aplicativo bancário.
04
Receber a confirmação e creditar os fundos
Depois de validar a assinatura e o status final, a plataforma aumenta o saldo do jogador uma única vez e conclui a operação.
Saque e reembolso
Saques, cancelamentos e reembolsos
Operações de saída exigem verificação do jogador, saldo disponível, risco, dados de pagamento e resposta final do provedor de pagamento.
Verificação do jogador
KYC, idade, status da conta, limites, autoexclusão e métodos de saque permitidos.
Verificações de risco
AML, indicadores de fraude, condições de apostas, origem dos fundos e aprovação da operadora.
Reservar o valor
O valor fica retido no saldo até o recebimento do resultado final do pagamento.
Enviar ao provedor de pagamento
Uma solicitação de pagamento separada é criada com número único e dados verificados do destinatário.
Aguardar o resultado
A plataforma aceita status intermediários e não debita o valor novamente.
Reembolso
Um reembolso é criado como uma operação separada, vinculada ao pagamento original e ao seu próprio valor.
Cancelamento
O cancelamento só é possível antes da etapa irreversível e não substitui o reembolso de uma operação já concluída.
Conciliação final
O relatório do provedor, os dados de pagamento, as taxas e as alterações de saldo devem apresentar o mesmo resultado.
Status da operação
Modelo de status recomendado
Os status internos normalizam diferentes respostas dos provedores de pagamento em um modelo único e claro para a plataforma.
Criada
A operação foi criada dentro da plataforma, mas ainda não foi enviada nem aceita pelo provedor.
Ação necessária
O jogador precisa confirmar o pagamento, inserir dados ou realizar uma ação junto ao banco.
Em processamento
O provedor aceitou a operação, mas o resultado final ainda não foi confirmado.
Concluída
A operação foi concluída com sucesso e, depois disso, o saldo é alterado uma única vez.
Rejeitada
A operação foi encerrada com rejeição, mantendo o motivo e sem novo débito ou crédito.
Não confirmada
O resultado da operação é desconhecido devido a uma falha de conexão, atraso de resposta ou dados conflitantes.
Um resultado desconhecido não pode ser tratado como rejeição
O pagamento pode ter sido aceito pelo provedor mesmo sem uma resposta em tempo hábil. Primeiro solicite o status atual ou aguarde a confirmação e só então decida se outra operação é necessária.
Confiabilidade e conciliação
Proteção contra duplicidades e conciliação financeira
A confiabilidade da API de pagamentos depende de um comportamento seguro diante de requisições repetidas, confirmações atrasadas e falhas parciais.
Proteção contra operações repetidas
Cada depósito, saque e reembolso recebe um número único.
Uma requisição repetida retorna o resultado existente e não cria uma nova operação financeira.
Uma notificação repetida é verificada pelo número do evento e pelo estado atual do pagamento.
A alteração de saldo é vinculada ao número do pagamento e aplicada apenas uma vez.
Contabilidade financeira e conciliação
Armazene separadamente o valor, a taxa, o valor líquido, a moeda e a referência do provedor.
Não reescreva retroativamente um lançamento concluído; crie um ajuste separado.
Concilie operações da API, relatórios do provedor, alterações de saldo e pagamentos.
Registre cada divergência, sua causa, responsável e resultado da resolução.
Testes
O que testar antes do lançamento
Teste pagamento bem-sucedido, rejeição, perda de conexão, confirmação repetida, resultado desconhecido, reembolso e conciliação financeira.
Depósito e saque bem-sucedidos
Todos os status intermediários, confirmação, alteração de saldo e relatório final.
Rejeição da operação
Fundos insuficientes, dados inválidos, limite excedido, rejeição bancária, análise de risco e método de pagamento indisponível.
Perda de conexão
A conexão cai após o envio da requisição, e a confirmação chega depois ou é solicitada separadamente.
Requisições repetidas
A mesma operação ou confirmação chega novamente depois que o processamento já foi concluído.
Reembolso e cancelamento
Reembolso total e parcial, cancelamento antes do processamento e proibição de cancelar uma operação concluída.
Conciliação
O valor, a taxa, o status final, o saldo e o relatório do provedor coincidem após todos os cenários.
Checklist antes do lançamento
Os pagamentos em produção são ativados após a verificação de status, confirmações, proteção contra duplicidades, saldos e relatórios financeiros.
Os ambientes de teste e produção usam credenciais, endpoints de notificação e contas diferentes.
O retorno do usuário ao site não é usado como prova de pagamento bem-sucedido.
A assinatura e o número do evento são verificados antes de alterar o saldo.
Depósitos, saques e reembolsos são protegidos contra execução repetida.
Um status desconhecido é esclarecido com o provedor e verificado durante a conciliação.
Alertas de erro, relatórios dos PSPs e um processo de investigação de divergências estão configurados.
Precisa projetar um fluxo de pagamentos?
Envie a lista de PSPs, métodos de pagamento, moedas, mercados, regras de saldo e status. A APIACE ajudará a estruturar depósitos, saques, reembolsos, confirmação e conciliação financeira.