DiscordStatus
Guias / Guides

Checkout para Pix

Exemplo de payload e fluxo de integração para criar um checkout avulso com pagamento via Pix, expiração e URLs de redirecionamento.

Crie um checkout avulso para receber um pagamento via Pix, definir quando o link expira e redirecionar o cliente de volta para o seu site.

Use este tipo de checkout quando você vende um produto ou serviço com pagamento único, como um curso, ingresso, pedido de e-commerce ou cobrança pontual. O cliente acessa o link do checkout, paga com Pix e retorna para a URL configurada conforme o resultado da jornada.

Antes de começar

  1. Defina as URLs do seu site para os cenários de sucesso, cancelamento e expiração.
  2. Liste os itens que serão cobrados, incluindo nome, quantidade e valor.
  3. Use customerData se quiser preencher os dados do cliente automaticamente durante a criação do checkout.

Fluxo de integração

  1. Monte o payload com billingTypes, chargeTypes, minutesToExpire, callback e items.
  2. Envie o payload no fluxo de criação de checkout da API.
  3. Depois que a API retornar o ID do checkout, use esse ID para exibir ou compartilhar o link de pagamento com o cliente.
  4. Direcione o cliente para o checkout para concluir o pagamento via Pix.
  5. Trate o retorno do cliente pela URL configurada em successUrl, cancelUrl ou expiredUrl.

Exemplo de payload

Use este corpo JSON ao criar o checkout:

{
  "billingTypes": ["PIX"],
  "chargeTypes": ["DETACHED"],
  "minutesToExpire": 60,
  "callback": {
    "cancelUrl": "https://meusite.com/cancelado",
    "expiredUrl": "https://meusite.com/expirado",
    "successUrl": "https://meusite.com/sucesso"
  },
  "items": [
    {
      "name": "Curso de Marketing",
      "description": "Curso completo de marketing digital",
      "quantity": 1,
      "value": 297.00
    }
  ]
}

Esse payload cria um checkout com:

  • Pagamento via Pix
  • Cobrança avulsa com chargeTypes definido como DETACHED
  • Link válido por 60 minutos
  • Produto chamado “Curso de Marketing” no valor de R$ 297,00
  • Redirecionamento para seu site após sucesso, cancelamento ou expiração

Parâmetros principais

CampoTipoObrigatórioDescrição
billingTypesarray de stringsSimDefine os meios de pagamento aceitos no checkout. Use ["PIX"] para aceitar Pix.
chargeTypesarray de stringsSimDefine o tipo de cobrança. Use ["DETACHED"] para uma cobrança avulsa.
minutesToExpirenúmeroSimDefine por quantos minutos o link do checkout permanece válido. No exemplo, 60 equivale a 1 hora.
callbackobjetoSim, quando você precisa redirecionar o clienteAgrupa as URLs para onde o cliente será enviado após sucesso, cancelamento ou expiração.
callback.cancelUrlstringSim, dentro de callbackURL para redirecionar o cliente quando ele cancelar ou abandonar a jornada pelo fluxo de cancelamento.
callback.expiredUrlstringSim, dentro de callbackURL para redirecionar o cliente quando o link do checkout estiver expirado.
callback.successUrlstringSim, dentro de callbackURL para redirecionar o cliente após a conclusão bem-sucedida do checkout.
itemsarray de objetosSimDefine o que você está vendendo. Inclua pelo menos um item.
items[].namestringSimNome do produto ou serviço exibido no checkout.
items[].descriptionstringNãoDescrição complementar do item.
items[].quantitynúmeroSimQuantidade do item vendido.
items[].valuenúmeroSimValor unitário do item em reais. No exemplo, 297.00 representa R$ 297,00.

Comportamentos importantes

  • O link deixa de ser válido após o período definido em minutesToExpire.
  • Se o cliente acessar um checkout expirado, use expiredUrl para explicar o próximo passo, como gerar um novo checkout.
  • Se o cliente cancelar a jornada, use cancelUrl para permitir que ele tente novamente ou volte ao carrinho.
  • Se o checkout for concluído com sucesso, use successUrl para mostrar a confirmação do pedido ou instruções pós-pagamento.
⚠️

Não use este payload para assinatura ou parcelamento sem incluir os campos específicos desses tipos de checkout. Para recorrência, use o tipo de cobrança adequado descrito na página de assinatura.

Boas práticas

  • Crie páginas de retorno claras para successUrl, cancelUrl e expiredUrl, informando o estado da compra e a próxima ação do cliente.
  • Valide se todos os itens têm name, quantity e value antes de enviar o payload.
  • Use valores consistentes com o carrinho ou pedido salvo no seu sistema para evitar divergência entre o checkout e a venda.
  • Gere um novo checkout quando o link expirar, em vez de reutilizar um link antigo.
  • Não dependa apenas do redirecionamento do navegador para conciliar pedidos; trate também os eventos e confirmações do seu fluxo de pagamento.

Próximos passos