Pedidos e pagamentos (Order)
A API de Pedidos do PagBank, também conhecida como API Order, engloba todas as operações relacionadas ao processo de cobrança após a definição do pedido.
Serviços disponíveis
Tratando-se de uma API de Pedidos, um dos pontos mais importantes é a gama de meios de pagamento disponíveis. Atualmente, a API de Pedidos do PagBank proporciona as seguintes opções para a realização de pagamentos:
- Cartão de Crédito
- Cartão de Débito (Obrigatório 3DS)
- PIX
- Boleto Bancário
- Pagar com PagBank (carteira PagBank, pagamento pode ser realizado via saldo ou cartão de crédito)
Além da criação de pagamentos, a API de Pedidos disponibiliza outros recursos, como:
- Tokenização
- Repasse de taxa
- Autenticação 3DS
- Divisão do pagamento
Para mais detalhes sobre os serviços disponíveis, acesse Serviços de pedidos e pagamentos.
Fluxos de utilização da API
O fluxo convencional para a realização de um pagamento envolve a utilização de três endpoints para a criação de um pedido, realização do pagamento pelo cliente e captura desse pagamento. Entretanto, dependendo do meio de pagamento ou dos recursos incorporados, como tokenização, esse fluxo e o número de passos que você deve realizar pode ser alterado. Por esse motivo, você pode acessar a seção de Casos de uso para entender melhor todas as possibilidades disponibilizadas pela API de Pedidos do PagBank.
Explore os casos de uso
A seção de Casos de uso lista todas as variações do processo de criação e pagamento de um pedido. Se você está incerto em relação ao que você precisa para o seu negócio, recomendamos fortemente que verifique os guias passo a passo disponíveis.
Endpoints e webhooks
A utilização da API de Pedidos é feita através dos 8 endpoints principais relacionados a criação e consulta de pedidos. Esses endpoints são apresentados a seguir:
- Criar pedido: possibilita a criação de um pedido, incluindo a opção de efetuar o pagamento. Dependendo do método de pagamento selecionado, você pode criar e pagar o pedido utilizando apenas este endpoint.
- Consultar pedido: permite a consulta de pedidos anteriormente criados, utilizando um identificador único associado ao pedido.
- Consultar pedido através de parâmetros: possibilita a consulta de pedidos já existentes através de parâmetros específicos, como o identificador da cobrança.
- Consultar divisão do pagamento: permite recuperar os dados relacionados à divisão de um pagamento, oferecendo insights sobre a distribuição dos valores envolvidos.
- Pagar pedido: este endpoint viabiliza o processo de pagamento para um pedido previamente criado.
- Consultar pagamento: oferece a funcionalidade de consultar o status de um pagamento, proporcionando informações atualizadas sobre a transação.
- Capturar pagamento: permite a capture transações pré-autorizadas.
- Cancelar pagamento: possibilita a devolução do valor pago ao comprador, sendo aplicável tanto para desfazer uma pré-autorização quanto para reembolsar um pagamento já capturado.
Além desses endpoints, existem outros 3 que oferecem funcionalidades complementares aos processos de criação de pedido e pagamento. Esses serviços são cobertos pelos seguintes endpoints:
- Criar sessão de autenticação 3DS: permite gerar sessões que serão utilizadas para a autenticação de operações com autenticação 3DS do PagBank.
- Consultar juros de uma transação: permite que você consulte e exiba os juros de parcelamento das transações aos seus clientes.
- Validar e armazenar um cartão: permite que você valide e armazene um cartão no sistema do PagBank.
O PagBank também disponibiliza webhooks para notificação em tempo real sobre eventos relacionados à alteração de status em pedidos e pagamentos criados. Acesse a página de Webhooks para mais informações sobre as notificações cobertas e meios de integração.
Objetos
A API de Pedidos utiliza dois objetos principais nos processos de criação de pedidos (objeto Order) e criação de pagamentos (objeto Charge). Para identificar todos os parâmetros, seus respectivos tipos e exemplos de cada parâmetro do objeto, acesse as páginas do Objeto Order e do Objeto Charge.
Casos de uso
O PagBank oferece diversas opções para criar e pagar pedidos utilizando diferentes meios de pagamento. Nesta página, você encontrará guias que irão ajudá-lo a entender cada processo, além de exemplos de requisições e respostas. A lista foi dividida entre os processos que te permitem criar e pagar um pedido e aqueles que são utilizados apenas para criar pedidos.
Selecione o guia de criação de pedido que atenda a sua necessidade:
Caso você deseje criar um pedido com parcelamento do pagamento repassando juros ao comprador, utilize o link abaixo:
Se o seu objetivo é criar e pagar um pedido realizando apenas uma requisição, selecione um dos guias disponíveis a seguir:
- Criar e pagar pedido com cartão
- Criar e pagar pedido com cartão (Cliente PCI)
- Criar e pagar pedido com token de bandeira
- Criar e pagar pedido com token PagBank
- Criar e pagar pedido com indicação de recorrência
- Criar e pagar com autenticação 3DS externa
- Criar e pagar com autenticação 3DS do PagBank
- Criar e pagar pedido com Boleto
Você tembém pore explorar os casos de uso associados ao serviço Pagar com PagBank:
O PagBank também disponibiliza a opção de dividir o pagamento. Essa opção é útil caso você deseje realizar a distribuição dos fundos para todos os envolvidos já no momento do pagamento do pedido. Para entender melhor essa opção, acesse o link abaixo:
Essas informações serão úteis para orientá-lo em cada etapa do processo, permitindo que você escolha a melhor opção conforme as as suas necessidades.
Erros e bloqueios de pagamento
Ao utilizar os endpoints da API de Pagamentos, você pode se deparar com dois tipos de problemas. O primeiro diz respeito aos erros associados à realização de requisições e o segundo se relaciona a não autorização dos pagamentos.
Os erros relacionados à requisição aos endpoints estão normalmente associados ao fornecimento de parâmetros incorretos ou falta de autenticação. Para te auxiliar a entender os problemas ao executar as requisições, você pode acessar a página Códigos de erro, que lista os códigos que você pode receber e provê detalhes adicionais para cada erro.
A realização de um pagamento pode ser efetuada com sucesso ou ser bloqueada. No caso de um pagamento bloqueado, um erro não será necessariamente gerado. Para identificar o status da operação, você deverá checar o código da resposta da operação e a mensagem associada. A página Motivos de compra negada disponibiliza a lista de códigos que você pode receber ao tentar realizar um pagamento e descrições complementares.
Updated 5 months ago