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:

Criar pedido com repasse de taxa ao comprador

Se o seu objetivo é criar e pagar um pedido realizando apenas uma requisição, selecione um dos guias disponíveis a seguir:

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:

Divisão do pagamento

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.