Número único da operação
Ele liga o jogador, valor, moeda, método de pagamento, fornecedor 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, levantamentos, reembolsos e reconciliação financeira.
Depósito
criação e crédito
Pagamento
verificação e envio
Estados
confirmação da operação
Reconciliação
controlo financeiro
Fluxo de pagamentos
Do pedido ao resultado final
01
Criar a operação
Registar 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 estado final
Verificar a resposta do fornecedor 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 registar a operação para reconciliação.
Visão geral
Cada pagamento segue etapas controladas
A plataforma atribui o seu próprio número de operação, associa-o à resposta do fornecedor de pagamento e altera o estado financeiro apenas após um resultado confirmado. Um pedido repetido não deve criar um segundo débito ou crédito.
Estados 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 estado do pagamento, a alteração de saldo, a taxa e o lançamento contabilístico 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 fornecedor de pagamento.
01
Validar o pedido 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 fornecedor
O fornecedor 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 numa página externa, por 3-D Secure ou num aplicação bancário.
04
Receber a confirmação e creditar os fundos
Depois de validar a assinatura e o estado final, a plataforma aumenta o saldo do jogador uma única vez e conclui a operação.
Levantamento e reembolso
Levantamentos, cancelamentos e reembolsos
Operações de saída exigem verificação do jogador, saldo disponível, risco, dados de pagamento e resposta final do fornecedor de pagamento.
Verificação do jogador
KYC, idade, estado da conta, limites, autoeliminação e métodos de levantamento permitidos.
Verificações de risco
AML, indicadores de fraude, condições de apostas, origem dos fundos e aprovação do operador.
Reservar o valor
O valor fica retido no saldo até a receção do resultado final do pagamento.
Enviar ao fornecedor de pagamento
Um pedido de pagamento separada é criada com número único e dados verificados do destinatário.
Aguardar o resultado
A plataforma aceita estados 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.
Reconciliação final
O relatório do fornecedor, os dados de pagamento, as taxas e as alterações de saldo devem apresentar o mesmo resultado.
Estados da operação
Modelo de estados recomendado
Os estados internos normalizam diferentes respostas dos fornecedores de pagamento num 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 fornecedor.
Ação necessária
O jogador precisa confirmar o pagamento, inserir dados ou realizar uma ação junto ao banco.
Em processamento
O fornecedor 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 ligaçã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 fornecedor mesmo sem uma resposta em tempo hábil. Primeiro solicite o estado atual ou aguarde a confirmação e só então decida se outra operação é necessária.
Fiabilidade e reconciliação
Proteção contra duplicidades e reconciliação financeira
A fiabilidade da API de pagamentos depende de um comportamento seguro diante de pedidos repetidos, confirmações atrasadas e falhas parciais.
Proteção contra operações repetidas
Cada depósito, levantamento e reembolso recebe um número único.
Um pedido repetido devolve 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 reconciliação
Armazene separadamente o valor, a taxa, o valor líquido, a moeda e a referência do fornecedor.
Não reescreva retroativamente um lançamento concluído; crie um ajuste separado.
Concilie operações da API, relatórios do fornecedor, alterações de saldo e pagamentos.
Registe cada divergência, a sua causa, o responsável e o resultado da resolução.
Testes
O que testar antes do lançamento
Teste pagamento bem-sucedido, rejeição, perda de ligação, confirmação repetida, resultado desconhecido, reembolso e reconciliação financeira.
Depósito e levantamento bem-sucedidos
Todos os estados 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 ligação
A ligação cai após o envio do pedido, e a confirmação chega depois ou é solicitada separadamente.
Pedidos repetidos
A mesma operação ou confirmação volta a chegar depois de o processamento já ter sido concluído.
Reembolso e cancelamento
Reembolso total e parcial, cancelamento antes do processamento e proibição de cancelar uma operação concluída.
Reconciliação
O valor, a taxa, o estado final, o saldo e o relatório do fornecedor coincidem após todos os cenários.
Lista de verificação antes do lançamento
Os pagamentos em produção são ativados após a verificação de estados, 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 utilizador 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, levantamentos e reembolsos são protegidos contra execução repetida.
Um estado desconhecido é esclarecido com o fornecedor e verificado durante a reconciliaçã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 estados. A APIACE ajudará a estruturar depósitos, levantamentos, reembolsos, confirmação e reconciliação financeira.