Pular para o conteúdo principal
Todos os sistemas operacionaisNovidadesv1
Entrar

API Direta

Crie uma experiência de pagamento de propriedade do comerciante com APIs de servidor DEUNA.

Última atualização: October 12, 2026
Nesta página
Método de integração

Controle a interface e coordene pagamentos pelo seu backend.

Crie a jornada do cliente no seu aplicativo e use as APIs da DEUNA para operações de pagamento, usuário, cartão e orquestração.

Interface
Frontend e backend controlados pelo lojista
Modelo de entrega
APIs servidor a servidor com suporte no cliente quando necessário
Ideal para
Equipes que precisam de controle máximo do produto
Comparar métodosAbrir referência

Utilize a API direta quando sua equipe possui a interface de checkout e interage com a DEUNA através de um backend de um parceiro confiável. Seu cliente coleta ou tokeniza o instrumento de pagamento, seu backend cria o pagamento, e ambas as partes lidam com qualquer ação do cliente necessária antes do estado final de pagamento.

Siga o caminho de integração.#

1. Configure o acessoSelecione a chave pública, a chave privada e, opcionalmente, o token Bearer do cliente corretos.2. Prepare o ambienteDefina as URLs base, Postman, acesso à rede, tentativas, limites de taxa e timeouts do cliente.3. Colete os detalhes do pagamentoTokenize os dados da carteira ou colete os campos necessários para o método de pagamento selecionado.4. Crie o pagamentoImplemente a solicitação Purchase V2, as respostas, os cabeçalhos e o contrato de idempotência.5. Gerencie todos os estadosImplemente ações do cliente, processamento pendente, sucesso, rejeição, captura, cancelamento e reembolso.6. Reconcilie atualizaçõesReceba notificações de status assíncronas e confirme o estado autoritativo do pedido.

1. Configure o comerciante e o ambiente#

Antes de enviar a solicitação de pagamento:

  1. Complete configuração da conta e obtenha as credenciais para o ambiente de sandbox.
  2. Leia Autenticação e chaves de API para separar as credenciais públicas do cliente, as credenciais privadas do backend e, opcionalmente, a identidade do cliente.
  3. Configure pelo menos uma conexão de pagamento e uma estratégia de roteamento elegíveis. Utilize Recursos dos provedores para confirmar o suporte para país, método, moeda e operação, e revise Estratégias de pagamento.
  4. Aplique os requisitos de ambiente e rede compartilhados em Fundamentos de integração da API.
  5. Use as URLs suportadas Coleção do Postman quando você deseja inspecionar as requisições do ambiente de testes antes de implementar um cliente.

Os ambientes de testes e produção utilizam URLs, credenciais, conexões com provedores e dados de pagamento diferentes. Não misture recursos entre os ambientes.

2. Colete os dados do titular da carteira com segurança#

O comerciante possui a interface Direct API, mas o tratamento de dados de cartão ainda depende do seu escopo PCI.

  • Se o cliente precisa evitar o tratamento de dados de cartão brutos no backend do comerciante, utilize as URLs suportadas Fluxo de tokenização de cartão e envie o token do método de pagamento resultante para o backend.
  • Se o provedor de prevenção de fraude configurado exigir dados do navegador ou dispositivo, implemente o Fluxo de impressão digital de dispositivo via API.
  • Para carteiras e métodos de pagamento alternativos, comece com Recursos dos provedores, e siga o guia de conexão vinculado para os requisitos necessários. payment_source, specific_fields, redirecionamento, QR, voucher ou comportamento de retorno de chamada.
  • Se um token de pedido existente estiver disponível, o backend pode recuperá-lo e obter suas configurações. Métodos de pagamento antes do processamento.

3. Criar e processar o pagamento#

As novas integrações devem começar com POST /v2/merchants/orders/purchase. Ele suporta dois modelos de requisição válidos:

ModeloQuando usarDocumentação
Pedido inline · RecomendadoCrie o pedido e processe o pagamento em uma única solicitação de Compra V2.Contrato de solicitação de pagamento e Exemplos práticos de uso
Token de pedido existente · OpcionalCrie o pedido apenas quando outro canal ou experiência necessitar do order_token pagamento.Criar pedido, depois Processar o pedido existente

Use a Configuração rápida de pagamento no ambiente de testes Para o fluxo de backend mais curto possível. catálogo de endpoints é o inventário oficial das operações publicadas e seus chamadores suportados.

Para cada solicitação de alteração de pagamento suportada, gere uma X-Idempotency-Key no backend. Utilize a mesma chave e corpo de solicitação idêntico, quando tentar novamente uma solicitação incerta. Siga o procedimento completo. Diretrizes para requisições idempotentes, incluindo seu período de retenção e tratamento de conflitos.

4. Trate a resposta e a ação do cliente#

Uma HTTP 2xx Resposta significa que a solicitação da API foi aceita ou processada; ela não comprova, por si só, que houve transferência de fundos. order.payment.data.status e qualquer ação subsequente retornada.

Selecione o ciclo de vida que corresponde ao método escolhido:

Fluxo de pagamento com cartãoGerenciar compras, autorizações, análise de risco, captura, cancelamento, reembolso e estados finais do cartão.3D SecureApresentar um desafio de API direto suportado e avaliar o estado do pagamento resultante.Fluxo de trabalho do APMGerenciar redirecionamentos, códigos QR, vouchers, confirmação bancária, cancelamento e expiração.

Não utilize a URL de retorno do navegador, callback do SDK ou redirecionamento do provedor como prova de pagamento. Mantenha a transação bloqueada enquanto o pagamento estiver pendente, em processamento, em análise ou aguardando ação do cliente.

5. Confirmar resultados assíncronos#

Configurar Webhooks de status de pedido e pagamento para o comerciante e o ambiente. Verifique a assinatura, aceite entregas repetidas de forma idempotente e confirme a solicitação antes de executar a lógica de negócios lenta.

Quando a resposta síncrona é perdida ou uma notificação é atrasada, recupere o pedido original com GET /merchants/orders/{order_token}. Reconcilie o estado do pagamento recuperado antes da entrega ou antes de criar uma tentativa significativamente nova.

Para timeouts de rede, siga Gerenciamento de timeouts do cliente. Um timeout do cliente não significa que o pagamento falhou.

6. Implemente operações pós-pagamento#

Exponha apenas as operações suportadas pela conexão selecionada e pelo estado atual do pagamento:

CapturarCapture toda ou parte de uma autorização elegível.VazioLibere uma autorização elegível antes do captura.ReembolsoCrie um reembolso total ou parcial para um pagamento processado.

Para um comportamento avançado das operações, continue em Múltiplas Capturas Parciais, Vários reembolsos parciaise Reembolsos assíncronos.

Verificação de prontidão para produção#

  • As chaves privadas são armazenadas apenas na configuração do backend protegida e são removidas dos logs.
  • Credenciais de teste e produção, URLs base, conexões e dados são isolados.
  • Cada recurso acessível Status do pagamento e a ação necessária do cliente é implementada.
  • O backend mantém os identificadores de pedidos, os corpos das solicitações e as chaves de idempotência para fins de recuperação.
  • Testam-se assinaturas de webhooks, entregas duplicadas, entregas atrasadas e atualizações fora de ordem.
  • O comportamento de timeout do cliente segue o acordado Tempo limite e modelo de reconciliação.
  • 429 e erros da plataforma Diretrizes de limite de taxa e o Referência de erro.
  • As funcionalidades de captura, cancelamento e reembolso só são exibidas quando suportadas pela conexão e pelo estado atual.
  • Os cenários de sucesso, falha, 3DS, pendência, timeout, retentativa e falha do provedor são certificados antes da utilização em produção.