O que é esta integração?

A integração In-Store permite que estabelecimentos físicos ofereçam Parcelamento via Pix no caixa. O lojista identifica o cliente pelo CPF, envia os termos de aceite via WhatsApp e exibe um QR Code Pix para pagamento da 1ª parcela. As demais parcelas são cobradas automaticamente pela Pagaleve.

Telas que compõem o fluxo no PDV

Etapa	Endpoint principal	Objetivo
1. Autenticação	POST /v1/authentication	Obter Bearer Token (JWT) para autorizar as chamadas
2. Análise de crédito	POST /v1/machine-integration/checkouts	Coletar CPF e verificar elegibilidade ao Parcelamento via Pix
2.1 Análise de crédito (multi oferta)	POST /v1/machine-integration/generate-plan-from-simulation	Quando há mais de uma simulação retornada no passo 2
3. Envio dos termos	POST /v1/machine-integration/send-terms	Enviar termos de aceite via WhatsApp ao cliente
4. Pagamento (QR Code)	GET /v1/checkouts/{id}	Consultar o checkout para acompanhar aceite, autorização ou conclusão
5. Sucesso	Webhook / GET /v1/checkouts/{id}	Confirmar state = AUTHORIZED/COMPLETED
6. Criar Pagamento	POST /v1/payments	Criar a autorização ou captura do pagamento usando o checkout autorizado

Conta e credenciais

É necessário ter uma conta aprovada na Pagaleve. Após aprovação, você receberá:

Variável	Descrição	Uso
API_KEY	Chave pública do lojista	Campo username no login
API_SECRET	Chave secreta do lojista	Campo password no login
BEARER_TOKEN	JWT gerado pela autenticação	Header Authorization em todas as chamadas

Checklist inicial

Conta aprovada na Pagaleve
API Key e API Secret em mãos
URL de webhook HTTPS configurada
Ambiente sandbox ativo para testes
Acesso ao simulador de pagamento Pagaleve

Diagrama de sequência

Interação completa entre PDV, Pagaleve e Cliente (WhatsApp) ao longo do fluxo In-Store.

sequenceDiagram
    autonumber
    participant PDV as PDV (Lojista)
    participant PAG as Pagaleve API
    participant CLI as Cliente (WhatsApp)
    PDV->>PAG: POST /v1/authentication
    PAG-->>PDV: 201 Created (Bearer Token)
    Note over PDV,PAG: Tela 1 — Identificação
    PDV->>PAG: POST /v1/machine-integration/checkouts
(individual_id, order_amount, provider)
    PAG-->>PDV: 200 OK (checkout + simulações)
    opt Passo 2.1 — Análise de crédito (multi oferta)
        PDV->>PAG: POST /v1/machine-integration/generate-plan-from-simulation
        PAG-->>PDV: 200 OK (plano escolhido)
    end
    Note over PDV,PAG: Tela 2 — Aprovação (envio dos termos)
    PDV->>PAG: POST /v1/machine-integration/send-terms
(checkout_id, merchant_id, phone_number)
    PAG-->>PDV: 200 OK
    PAG->>CLI: Envia termos de aceite via WhatsApp
    CLI-->>PAG: Aceita ou recusa os termos (SIM / NÃO)
    PAG->>PDV: Webhook: {action: "terms", accepted: true|false, id}
    loop Polling a cada 5s (fallback) — até confirmar aceite
        PDV->>PAG: GET /v1/checkouts/{checkout_id}
        PAG-->>PDV: 200 OK (state/aceite)
    end
    Note over PDV,PAG: Passo 4 — Pagamento (QR Code)
    PDV->>PAG: GET /v1/checkouts/{checkout_id}
    PAG-->>PDV: 200 OK (checkout atualizado)
    CLI->>PAG: Paga 1ª parcela via Pix
    alt Finalização do pagamento via Webhook (recomendado)
        PAG->>PDV: Webhook: state = AUTHORIZED / COMPLETED
    else Finalização do pagamento via Polling (fallback)
        PDV->>PAG: GET /v1/checkouts/{checkout_id}
(mínimo 5s)
        PAG-->>PDV: state = AUTHORIZED / COMPLETED
    end
    Note over PDV: Tela 4 — Sucesso (pedido finalizado)
    PDV->>PAG: POST /v1/payments
(checkout_id, amount, currency, intent)
    PAG-->>PDV: 201 Created (pagamento criado)

Fluxo passo a passo

1

Autenticação — obter Bearer Token (JWT) POST /v1/authentication

Primeira chamada do fluxo para autenticar o PDV na API Pagaleve.
Retorna o token Bearer usado nos endpoints seguintes.

↓

2

Análise de crédito — CPF + valor do pedido POST /v1/machine-integration/checkouts

Cria o checkout In-Store e valida a elegibilidade do cliente.
O checkout_id retornado deve ser usado nos próximos passos.

↓

2.1

Análise de crédito (multi oferta) POST /v1/machine-integration/generate-plan-from-simulation

Usado quando simulations[] retorna múltiplas ofertas de parcelamento para o cliente.
Ao selecionar uma oferta, envie checkout_id, customer_id e simulation_id para gerar o plano definitivo.

↓

3

Envio dos termos POST /v1/machine-integration/send-terms

Envia os termos e condições para o telefone do cliente.
O cliente deve responder SIM no WhatsApp para autorizar o parcelamento.
Ao receber a resposta do cliente, a Pagaleve dispara o webhook de aceite de termos (action: "terms") para a webhook_url informada.
Como fallback, use polling em GET /v1/checkouts/{checkout_id} a cada 5 segundos até confirmar o aceite.

↓

4

Pagamento (QR Code) GET /v1/checkouts/{id}

Consulta o checkout informado pelo id.
Use para acompanhar o estado do checkout e confirmar quando ele estiver AUTHORIZED ou COMPLETED.

↓

5

Sucesso Webhook / GET /v1/checkouts/{checkout_id}

Exibir sucesso quando o polling retornar state === "AUTHORIZED" ou state === "COMPLETED".
Use polling com intervalo mínimo de 5 segundos quando o parceiro não consumir webhooks.
As demais parcelas são cobradas automaticamente via WhatsApp pela Pagaleve.

↓

6

Criar Pagamento POST /v1/payments

Cria a autorização ou captura do pagamento para o checkout informado.
Use Idempotency-Key em retentativas para evitar duplicidade.

Dependência obrigatória: 1 → 2 → (2.1) → 3 → 3.1 (aceite) → 3.2 (polling a cada 5s) → 4 → 5 → 6. O checkout_id retornado em 2 é usado nos passos seguintes. As demais parcelas são cobradas automaticamente via WhatsApp pela Pagaleve.

Importante: não há webhook para criação do checkout — ela é confirmada pela resposta do próprio endpoint. Para o aceite dos termos, a Pagaleve dispara o webhook action: "terms"; use polling em GET /v1/checkouts/{checkout_id} a cada 5 segundos apenas como fallback. Para a confirmação do pagamento, prefira Webhook quando disponível; use polling apenas como fallback.

Quando usar cada fluxo

Cenário	Fluxo	Como funciona
PDV não tem CPF/telefone do cliente	Fluxo A (Fluxo completo)	O cliente escolhe Pagaleve na tela de métodos, o PDV coleta o CPF e só então roda a análise de crédito.
PDV já tem CPF e telefone do cliente	Fluxo B (este)	O checkout/análise de crédito acontece antes de exibir os métodos de pagamento. O Pagaleve é exibido já com as propostas de parcelas aprovadas.

Os endpoints são os mesmos do Fluxo A — o que muda é o momento de cada chamada. Nada de novo precisa ser implementado além da antecipação dos passos 1, 2 e 2.1.

Diagrama de sequência

Análise de crédito antecipada e exibição das propostas na própria tela de métodos de pagamento do PDV.

sequenceDiagram
    autonumber
    participant PDV as PDV (Lojista)
    participant PAG as Pagaleve API
    participant CLI as Cliente (WhatsApp)
    Note over PDV: PDV já possui CPF e telefone do cliente
    PDV->>PAG: POST /v1/authentication
    PAG-->>PDV: 201 Created (Bearer Token)
    Note over PDV,PAG: Antes de exibir os métodos de pagamento
    PDV->>PAG: POST /v1/machine-integration/checkouts
(individual_id, order_amount, webhook_url)
    PAG-->>PDV: 200 OK (checkout_id + simulations[])
    alt Cliente elegível
        PDV->>PDV: Exibe Pagaleve na tela de métodos
com as propostas de Parcelamento via Pix
    else Não elegível
        PDV->>PDV: Não exibe Pagaleve na tela de métodos
    end
    Note over PDV: Cliente seleciona Pagaleve e escolhe a proposta
    opt Mais de uma simulação retornada
        PDV->>PAG: POST /v1/machine-integration/generate-plan-from-simulation
(checkout_id, customer_id, simulation_id)
        PAG-->>PDV: 200 OK (plano escolhido)
    end
    PDV->>PAG: POST /v1/machine-integration/send-terms
(checkout_id, merchant_id, phone_number)
    PAG-->>PDV: 200 OK
    PAG->>CLI: Envia termos de aceite via WhatsApp
    CLI-->>PAG: Aceita ou recusa os termos (SIM / NÃO)
    PAG->>PDV: Webhook: {action: "terms", accepted: true|false, id}
    loop Polling a cada 5s (fallback) — até confirmar aceite
        PDV->>PAG: GET /v1/checkouts/{checkout_id}
        PAG-->>PDV: 200 OK (state/aceite)
    end
    PDV->>PAG: GET /v1/checkouts/{checkout_id}
    PAG-->>PDV: 200 OK (QR Code Pix da 1ª parcela)
    CLI->>PAG: Paga 1ª parcela via Pix
    alt Webhook (recomendado)
        PAG->>PDV: state = AUTHORIZED / COMPLETED
    else Polling (fallback, mínimo 5s)
        PDV->>PAG: GET /v1/checkouts/{checkout_id}
        PAG-->>PDV: state = AUTHORIZED / COMPLETED
    end
    Note over PDV: Tela de Sucesso (pedido finalizado)
    PDV->>PAG: POST /v1/payments
(checkout_id, amount, currency, intent)
    PAG-->>PDV: 201 Created (pagamento criado)

Fluxo passo a passo

1

Autenticação — obter Bearer Token (JWT) POST /v1/authentication

Executado normalmente pelo PDV antes de qualquer chamada.
Pode ser feito na abertura do caixa/sessão, já que ocorre antes da tela de métodos.

↓

2

Análise de crédito antecipada — antes da tela de métodos POST /v1/machine-integration/checkouts

Como o PDV já tem individual_id (CPF) e telefone, o checkout é criado antes de exibir os métodos de pagamento.
Envie a webhook_url do parceiro, igual ao Fluxo A.
A resposta traz checkout_id e o array simulations[] com as propostas de parcelas daquele cliente.
Se o cliente não for elegível, o PDV simplesmente não exibe o Pagaleve na tela de métodos.

↓

3

Tela de métodos de pagamento — Pagaleve já com as propostas Sem chamada de API

O PDV monta o card do Pagaleve usando os dados já retornados em simulations[] (número de parcelas, valor da parcela e valor total).
O cliente escolhe o Pagaleve e a proposta desejada diretamente nessa tela — sem digitar CPF novamente.
Atenção ao tempo de expiração do checkout: se o cliente demorar, refaça o passo 2.

↓

3.1

Confirmar a proposta escolhida (multi oferta) POST /v1/machine-integration/generate-plan-from-simulation

Necessário quando simulations[] retornou mais de uma oferta.
Envie checkout_id, customer_id e o simulation_id da proposta selecionada pelo cliente.

↓

4

Envio dos termos — após escolher o Pagaleve POST /v1/machine-integration/send-terms

Os termos só são disparados depois que o cliente seleciona o Pagaleve na tela de métodos.
O cliente deve responder SIM no WhatsApp — o aceite é obrigatório.
A Pagaleve dispara o webhook de aceite de termos (action: "terms") assim que o cliente aceita ou recusa.
Fallback: acompanhe o aceite por polling em GET /v1/checkouts/{checkout_id} a cada 5 segundos.

↓

5

Pagamento (QR Code) GET /v1/checkouts/{id}

Após o aceite, consulte o checkout para obter o QR Code Pix da 1ª parcela.
Mantenha o polling de 5 segundos até o estado mudar.

↓

6

Sucesso Webhook / GET /v1/checkouts/{checkout_id}

Exiba a tela de sucesso quando state === "AUTHORIZED" ou state === "COMPLETED".
As demais parcelas são cobradas automaticamente via WhatsApp pela Pagaleve.

↓

7

Criar Pagamento POST /v1/payments

Cria a autorização ou captura do pagamento para o checkout autorizado.
Use Idempotency-Key em retentativas para evitar duplicidade.

Atenção: a análise de crédito antecipada usa o valor do pedido no momento da chamada. Se o valor do carrinho mudar depois (descontos, itens adicionados), refaça o POST /v1/machine-integration/checkouts antes de prosseguir.

POST /v1/authentication

Endpoint no padrão da documentação pública da Pagaleve. Envie as credenciais fornecidas pela Pagaleve no corpo da requisição.

Base URL — Sandbox

https://sandbox-api.pagaleve.io/v1/authentication

Headers

accept: application/json
content-type: application/json

Request body

{
  "username": "{{API_KEY}}",
  "password": "{{API_SECRET}}"
}

Campo	Tipo	Req.	Descrição
username	string	Sim	E-mail ou API key fornecida pela Pagaleve para acesso à API
password	string	Sim	Senha ou API Secret fornecida pela Pagaleve para acesso à API

Exemplo cURL

curl --request POST \
  --url https://sandbox-api.pagaleve.io/v1/authentication \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --data '{"username":"{{API_KEY}}","password":"{{API_SECRET}}"}'

Respostas possíveis

201Autenticação realizada com sucesso. Use o token retornado como Authorization: Bearer {{token}}.

403Problema no processo de autenticação, como usuário inexistente ou conflito de e-mail e/ou senha.

Armazene o token com segurança e renove a autenticação quando necessário. Todas as próximas chamadas protegidas exigem o header Authorization.

Tela 1 — Identificação do cliente POST /v1/machine-integration/checkouts

Tela de Identificação do Cliente no PDV — campos CPF, telefone, valor e provider

Coleta CPF, telefone, referência e valor do pedido. Ao clicar em Verificar Elegibilidade, o PDV chama o endpoint para criar o checkout e validar a aprovação do cliente.

POST /v1/machine-integration/checkouts

Headers obrigatórios: Authorization: Bearer {{token}} e Idempotency-Key: {{uuid-v4}}. Em retentativas, reutilize o mesmo Idempotency-Key.

Headers obrigatórios

Authorization: Bearer {{token}}
Idempotency-Key: {{uuid-v4}}
Content-Type: application/json

Request body

{
  "individual_id":    "50324177852",
  "phone_number":     "11999998888",
  "order_amount":     25000,
  "order_reference":  "123",
  "provider":         "INTERNAL_INVITE",
  "webhook_url":      "https://seu-dominio.com/webhooks/pagaleve"
}

Campo	Tipo	Req.	Descrição
individual_id	string	Sim	CPF do cliente (somente dígitos)
phone_number	string	Sim	Telefone celular do cliente com DDD (somente dígitos, ex: 11999998888)
order_amount	integer	Sim	Valor do pedido em centavos (R$ 250,00 = 25000)
order_reference	string	Sim	Referência interna do pedido
provider	string	Sim	Provedor de integração (ex: VTEX, INTERNAL_INVITE)
webhook_url	string (URL)	Sim	Endpoint HTTPS do lojista onde a Pagaleve enviará as notificações de status do checkout (pagamento aprovado, expirado, cancelado, etc.).

Response — oferta única (200)

{
  "checkout": {
    "id":          "chk_a1b2c3d4...",
    "merchant_id": "mer_xyz789",
    "order": {
      "amount":    25000,
      "reference": "123"
    },
    "plan": {
      "current_installment": {
        "qr_code": { "code": "00020126580014br.gov.bcb.pix..." }
      }
    }
  },
  "simulations": [{ "installments": 6, "amount": 62721 }]
}

Respostas possíveis

2001 simulação — oferta única. Próximo passo: tela de Aprovação (send-terms).

200Múltiplas simulações — exibir tela de multi-oferta para o cliente escolher.

400DecisionPreApproveException — cliente não aprovado.

Tela — Multi-Oferta simulations[]

Tela de PDV com opções de parcelamento mensal e quinzenal para o cliente escolher

Cada card de oferta é montado a partir de um item do array simulations[] retornado no endpoint de Análise de crédito.

📦 Como montar a tela de Multi-Oferta

Os dados vêm do array simulations retornado na resposta do endpoint de criação de checkout In-Store (POST /v1/machine-integration/checkouts). Cada item em simulations[] representa uma oferta de parcelamento disponível para o cliente.

Campo	Descrição
id	Identificador da simulação usado na confirmação.
number_of_installments	Quantidade de parcelas.
rate	Taxa de juros mensal. Quando for 0, a oferta é sem juros.
amount	Valor total a pagar, com juros quando houver.
order_amount	Valor original do pedido.
current_installment.amount	Valor da 1ª parcela exibida como “Pague agora”.
installments[]	Detalhamento de todas as parcelas.
iof	Valor do IOF quando há juros.

POST /v1/machine-integration/generate-plan-from-simulation

Ao selecionar uma oferta, chame este endpoint com checkout_id, customer_id, e simulation_id.

Request body

{
  "checkout_id":   "chk_a1b2c3d4...",
  "customer_id":   "cus_12345...",
  "simulation_id": "sim_12345..."
}

Exemplo de leitura das simulações

response.simulations.forEach(sim => {
  console.log(sim.number_of_installments + "x");
  console.log("Taxa:", sim.rate + "%");
  console.log("1ª parcela:", sim.current_installment.amount);
});

// Ao selecionar
const chosen = simulations[selectedIndex];
generatePlan({ simulation_id: chosen.id });

200 OK

{
  "current_installment": {
    "qr_code": {
      "code": "00020126580014br.gov.bcb.pix..."
    }
  },
  "installments": 6,
  "amount":       62721
}

Tela 2 — Aprovação · Enviar compra para o cliente POST /v1/machine-integration/send-terms

Tela 'Cliente Aprovado' com campo de telefone e botão Enviar Compra para Usuário

Mensagem da Pagaleve no WhatsApp do cliente com os termos do parcelamento e botões SIM/NÃO

O PDV exibe a confirmação da aprovação e o telefone do cliente. Ao clicar em Enviar Compra para Usuário, a Pagaleve dispara os termos via WhatsApp; em seguida, o PDV deve iniciar o polling a cada 5 segundos até o cliente responder SIM e autorizar o parcelamento.

O valor aprovado a ser exibido na tela vem de checkout.order.amount da resposta do passo 2.

POST /v1/machine-integration/send-terms

Disparado ao clicar em "Enviar Compra para Usuário" na tela de Aprovação.

Request body

{
  "checkout_id":  "chk_a1b2c3d4...",
  "merchant_id":  "mer_xyz789",
  "phone_number": "+5511947022679"
}

Campo	Tipo	Req.	Descrição
checkout_id	string	Sim	ID do checkout criado no passo 2
merchant_id	string	Sim	ID do merchant (vem da resposta do checkout)
phone_number	string	Sim	Telefone com prefixo internacional (ex: +5511999999999)

200 OK

Em caso de sucesso (200), o cliente recebe os termos no celular via WhatsApp/SMS, com detalhamento das parcelas, datas de cobrança e valor total. Após essa chamada, a Pagaleve dispara o webhook de aceite de termos quando o cliente responder; como fallback, o PDV pode consultar GET /v1/checkouts/{checkout_id} a cada 5 segundos até identificar o aceite. Ao responder SIM, o fluxo segue para o pagamento da 1ª parcela via QR Code Pix.

Como identificar que o cliente aceitou os termos?

Existem duas formas: (1) Webhook de aceite de termos — a Pagaleve envia um POST para a webhook_url assim que o cliente aceita ou recusa; (2) Polling em GET /v1/checkouts/{checkout_id} a cada 5 segundos, como fallback.

Webhook de aceite de termos

{
  "action":   "terms",
  "accepted": true,
  "id":       "01HXYZ...checkoutId"
}

GET /v1/checkouts/{checkout_id}

Execute a consulta a cada 5 segundos até identificar que os termos foram aceitos e o fluxo pode avançar para o QR Code.

Nunca faça polling em intervalo inferior a 5 segundos.

Tela 3 — QR Code · Aguardando pagamento GET /v1/checkouts/{id}

Tela com QR Code Pix, código copia-e-cola e mensagem 'Aguardando Pagamento'

O PDV renderiza o QR Code Pix e o código copia-e-cola retornados pelo checkout de pagamento. Os dados da tela vêm do pedido, do cliente e do plano confirmado nos passos anteriores.

GET /v1/checkouts/{id}

Endpoint no padrão da documentação pública de consulta de checkout. Use para consultar o checkout informado e acompanhar estados como aceite, autorização ou conclusão.

Base URL — Sandbox

https://sandbox-api.pagaleve.io/v1/checkouts/{id}

Headers

Authorization: Bearer {{token}}
Subsidiary-Id: {{subsidiary_id}}
accept: application/json

Header	Tipo	Req.	Descrição
Authorization	string	Sim	Token de autorização Bearer
Subsidiary-Id	string	Não	Para uma holding consultar dados de uma subsidiária, esse campo deve ser preenchido com o ID da subsidiária.

Parâmetro	Tipo	Req.	Descrição
id	string	Sim	ID do checkout consultado.

Exemplo cURL

curl --request GET \
  --url https://sandbox-api.pagaleve.io/v1/checkouts/{{checkout_id}} \
  --header 'accept: application/json' \
  --header 'Authorization: Bearer {{token}}'

Respostas possíveis

200Checkout encontrado e retornado com sucesso.

404Checkout com o ID informado não encontrado.

Acompanhamento do pagamento

A finalização deve ocorrer preferencialmente via Webhook, informado em webhook_url. O polling em GET /v1/checkouts/{checkout_id} deve ser usado apenas como fallback e nunca com intervalo inferior a 5 segundos.

Simulação de pagamento (sandbox)

Para testar, copie o código Pix exibido no PDV e cole na aba "Simular Pagamento" dentro das configurações (⚙️) do ambiente de staging. Isso confirma o pagamento sem necessidade de Pix real.

Sandbox — Simular Pagamento Staging

Modal Configurações com aba Simular Pagamento e campo para colar o código Pix

Modal de Simular Pagamento com mensagem 'Pagamento simulado com sucesso' e payload JSON da transação

Cole o código Pix copiado da Tela 3 e clique em Simular Pagamento. Em sucesso, o webhook confirma o pagamento e o PDV avança para a Tela 4 — Sucesso.

📦 Como montar a tela de Sucesso

Detalhes de integração para parceiros.

Quando exibir?

Exiba esta tela quando o polling de GET /v1/checkouts/{checkout_id} retornar state === "AUTHORIZED" ou state === "COMPLETED".

Tela 4 — Pagamento confirmado state = AUTHORIZED / COMPLETED

Tela de Pagamento Confirmado com detalhes do parcelamento sem juros via Parcelamento via Pix Pagaleve

Tela final exibida quando o pagamento da 1ª parcela é confirmado. O valor total e a quantidade de parcelas são lidos de checkout.order.amount e checkout.ccb_terms_and_condition.numberOfInstallments.

Dados exibidos

Campo	Caminho na resposta	Uso
Valor total	checkout.order.amount	Valor total da compra (em centavos)
Número de parcelas	checkout.ccb_terms_and_condition.numberOfInstallments	Quantidade de parcelas do plano

Fluxo concluído. Neste ponto, o pagamento da 1ª parcela foi confirmado. As demais parcelas serão cobradas automaticamente via WhatsApp.

POST /v1/payments

Use este endpoint para criar o pagamento informando o pedido, valor, moeda e intenção da operação.

Base URL — Sandbox

https://sandbox-api.pagaleve.io/v1/payments

Headers

Authorization: Bearer {{token}}
Idempotency-Key: {{uuid-v4}}
Subsidiary-Id: {{subsidiary_id}}
accept: application/json
content-type: application/json

Header	Tipo	Req.	Descrição
Authorization	string	Sim	Token de autorização Bearer.
Idempotency-Key	string	Não	Chave para segurança em retentativas, evitando executar a mesma operação duas vezes.
Subsidiary-Id	string	Não	Para holdings consultarem dados de uma subsidiária, informe o ID da subsidiária.

Request body

{
  "amount": 25000,
  "checkout_id": "chk_a1b2c3d4...",
  "currency": "BRL",
  "intent": "AUTH",
  "reference": "PEDIDO-123"
}

Campo	Tipo	Req.	Descrição
amount	number	Sim	Valor em centavos. Deve ser maior ou igual a 1.
checkout_id	string	Sim	ID do pedido.
currency	string	Sim	Moeda utilizada. Valores permitidos: BRL ou USD.
intent	string	Sim	AUTH para autorização com captura posterior, ou CAPTURE para autorizar e capturar automaticamente.
reference	string	Não	ID de referência utilizado na raiz do checkout.

Exemplo cURL

curl --request POST \
  --url https://sandbox-api.pagaleve.io/v1/payments \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'Authorization: Bearer {{token}}' \
  --header 'Idempotency-Key: {{uuid-v4}}' \
  --data '{{request_body}}'

Respostas possíveis

201Pagamento criado com sucesso.

404Checkout informado não encontrado.

409Checkout já foi iniciado.

412Checkout já foi completado ou não está autorizado.

422Valor do pagamento diferente do valor autorizado.

POST /v1/payments/{id}/refund

Use este endpoint para reembolsar um pagamento capturado. Podem ser feitos reembolsos totais, parciais ou múltiplos, respeitando o valor total já capturado.

Base URL — Sandbox

https://sandbox-api.pagaleve.io/v1/payments/{id}/refund

Headers

Authorization: Bearer {{token}}
Idempotency-Key: {{uuid-v4}}
Subsidiary-Id: {{subsidiary-id}} (opcional)

Header	Tipo	Req.	Descrição
Authorization	string	Sim	Token Bearer.
Idempotency-Key	string	Não	Evita reprocessar a mesma operação em retentativas.
Subsidiary-Id	string	Não	Obrigatório apenas quando uma holding consulta em nome de uma subsidiária.

Parâmetro	Tipo	Req.	Descrição
id	string	Sim	ID do pagamento capturado que será reembolsado.

Request body

{
  "amount": 2000,
  "description": "Motivo do reembolso",
  "reference": "ref-loja-123",
  "reason": "REQUESTED_BY_CUSTOMER"
}

Campo	Tipo	Req.	Descrição
amount	number	Sim	Valor a reembolsar, em centavos.
description	string	Não	Observações sobre o reembolso.
reference	string	Não	ID do reembolso vindo do lojista.
reason	string (enum)	Não	DUPLICATE, FRAUDULENT ou REQUESTED_BY_CUSTOMER.

Exemplo cURL

curl --request POST \
  --url https://sandbox-api.pagaleve.io/v1/payments/{id}/refund \
  --header 'Authorization: Bearer {{token}}' \
  --header 'Content-Type: application/json' \
  --data '{"amount": 2000, "reason": "REQUESTED_BY_CUSTOMER"}'

Resposta de sucesso (200)

{
  "amount": 2000,
  "id": "3c0db7b0-c145-4af6-aecd-82fb964665a4",
  "timestamp": "2022-12-09T13:36:00.489Z",
  "reference": "PD2L0046"
}

Respostas possíveis

200Reembolso processado com sucesso.

400Requisição inválida.

404Pagamento não encontrado.

409Já existe um reembolso em processamento para esse payment_id ou para essa idempotency_key.

412Reembolso não permitido para o status atual do pagamento.

Para consultar os reembolsos já realizados de um pagamento, use o endpoint complementar GET /payments/{id}/refunds, que retorna a lista de reembolsos associados ao payment_id.

GET /v1/merchant-search/list-subsidiaries

Use este endpoint para listar todas as subsidiárias vinculadas à holding autenticada, com filtros opcionais de período e paginação.

Base URL — Sandbox

https://sandbox-api.pagaleve.io/v1/merchant-search/list-subsidiaries

Headers

Authorization: Bearer {{token}}

Header	Tipo	Req.	Descrição
Authorization	string	Sim	Token Bearer.

Parâmetro	Tipo	Req.	Descrição
page	integer	Não	Número de página para iniciar (>= 0).
size	integer	Não	Número máximo de itens a serem retornados (limitado em 200).
start_date	string	Não	Data inicial no formato ISO (UTC-0).
end_date	string	Não	Data final no formato ISO (UTC-0).
timezone	string	Não	Timezone usado para o filtro de datas.

Exemplo cURL

curl --request GET \
  --url 'https://sandbox-api.pagaleve.io/v1/merchant-search/list-subsidiaries?page=0&size=20' \
  --header 'Authorization: Bearer {{token}}'

Resposta de sucesso (200)

{
  "items": [
    {
      "id": "bd0e0361-8df5-4888-bd58-72ef786ed9b4",
      "business_name": "Exemplo Store",
      "business_number": "12345678000190"
    }
  ]
}

Respostas possíveis

200Lista de subsidiárias retornada com sucesso.

400O merchant autenticado não é uma holding company (IllegalHoldingCompanyStateException).

404Merchant com o id informado não encontrado (MerchantNotFoundException).

Este endpoint só retorna resultados quando o merchant autenticado é do tipo holding company. Para consultar dados de uma subsidiária específica em outras chamadas, utilize o header Subsidiary-Id com o id retornado aqui.

POST {webhook_url do lojista}

Direção: Pagaleve → servidor do lojista. A URL é a informada no campo webhook_url durante a análise de crédito (POST /v1/machine-integration/checkouts). Este evento substitui a necessidade de polling para identificar o aceite — o polling em GET /v1/checkouts/{checkout_id} a cada 5 segundos permanece disponível como fallback.

Payload

{
  "action":   "terms",
  "accepted": true,
  "id":       "01HXYZ...checkoutId"
}

Campo	Tipo	Descrição
action	string	Sempre "terms" — identifica o evento de aceite de termos.
accepted	boolean	true quando o cliente aceita os termos; false quando recusa.
id	string	checkout_id ao qual o aceite se refere.

Como tratar

accepted: trueAvance para o Passo 4 — Pagamento (QR Code).

accepted: falseCliente recusou: encerre o fluxo Pagaleve e ofereça outro meio de pagamento.

Responda sempre com HTTP 200 em menos de 5 segundos e processe de forma assíncrona. O mesmo evento pode ser entregue mais de uma vez — implemente idempotência usando o id do checkout.

#	Etapa	Método	Endpoint	Depende de	Req.
1	Autenticação	POST	/v1/authentication	—	Sim
2	Análise de crédito	POST	/v1/machine-integration/checkouts	Token #1	Sim
2.1	Análise de crédito (multi oferta)	POST	/v1/machine-integration/generate-plan-from-simulation	checkout_id #2	Condicional
3	Envio dos termos	POST	/v1/machine-integration/send-terms	checkout_id + merchant_id	Sim
3.1	Aceite dos termos — webhook action: "terms" (polling a cada 5s como fallback)	GET	/v1/checkouts/{checkout_id}	send-terms #3	Sim
4	Pagamento (QR Code)	GET	/v1/checkouts/{id}	Aceite #3.1	Sim
5	Sucesso	—	inbound lojista (webhook_url)	Config no #4	Preferencial
5b	Polling de fallback	GET	/v1/checkouts/{checkout_id}	checkout #4	Fallback
6	Criar Pagamento	POST	/v1/payments	checkout autorizado #5	Sim

API Pagaleve

Sandbox

https://sandbox-api.pagaleve.io

Use para desenvolvimento, homologação e simulação de pagamento

Produção

https://api.pagaleve.com.br

Somente após validação em sandbox

Exemplo de URL completa

POST https://sandbox-api.pagaleve.io/v1/machine-integration/checkouts

200Success — Success

400Bad Request — Requisição inválida

401Unauthorized — Falha na autenticação

403Forbidden — Sua aplicação não está autorizada a acessar o recurso

404Not Found — Requisição válida, mas o item não foi encontrado

409Conflict — Solicitação aceita, mas em conflito com as regras de negócios

500Internal Server Error — Um erro interno ocorreu

Direção: Pagaleve → Servidor do lojista (POST para a webhook_url enviada no /v1/checkouts). Use webhook para confirmação de pagamento e para o aceite de termos (action: "terms").

Payload recebido inferido

{
  "event":           "CHECKOUT_AUTHORIZED",
  "checkout_id":     "chk_a1b2c3d4...",
  "state":           "AUTHORIZED",
  "order_amount":    25000,
  "order_reference": "123",
  "individual_id":   "50324177852",
  "timestamp":       "2026-04-24T11:43:31.472Z"
}

Eventos disponíveis

Evento	Quando
CHECKOUT_AUTHORIZED	1ª parcela paga via Pix (state = AUTHORIZED)
CHECKOUT_COMPLETED	Fluxo concluído (state = COMPLETED)
CHECKOUT_CANCELLED	Cancelado pelo lojista ou cliente
CHECKOUT_EXPIRED	QR Code expirou sem pagamento

Não há evento de webhook para checkout criado — use a própria resposta da criação. O aceite de termos possui webhook próprio (action: "terms"), documentado na seção Webhooks → Aceite de termos.

Responda sempre com HTTP 200 em menos de 5 segundos. Processe de forma assíncrona. O mesmo evento pode ser entregue mais de uma vez — implemente idempotência.

Credenciais de produção (API_KEY / API_SECRET) configuradas em variáveis de ambiente
Webhook HTTPS configurado e enviado em webhook_url no checkout de pagamento
Renovação automática do Bearer Token antes dos 60 min
Idempotency-Key único (UUID v4) por chamada de /checkouts
Tratamento dos estados: CREATED, PENDING, AUTHORIZED, COMPLETED, CANCELLED, EXPIRED
Tela de multi-oferta implementada para resposta com múltiplas simulações
Webhook de aceite de termos (action: "terms") recebido e tratado, com polling a cada 5s como fallback
Tratamento de DecisionPreApproveException (cliente não aprovado)
Telefone do cliente formatado com prefixo +55 antes do send-terms
QR Code Pix renderizado a partir de qr_code.code com botão "copia e cola"
Logs de todas as chamadas para auditoria
Testes no sandbox usando "Simular Pagamento" das configurações

Documentação Pagaleve | API In-Store

Pagaleve In-Store API

O que é esta integração?

Telas que compõem o fluxo no PDV

Pré-requisitos

Conta e credenciais

Checklist inicial

Fluxo completo

Diagrama de sequência

Fluxo passo a passo

Fluxo com CPF prévio

Quando usar cada fluxo

Diagrama de sequência

Fluxo passo a passo

Passo 1 — Autenticação

Respostas possíveis

Passo 2 — Análise de crédito

Respostas possíveis

Passo 2.1 — Análise de crédito (multi oferta)

📦 Como montar a tela de Multi-Oferta

Passo 3 — Envio dos termos

Como identificar que o cliente aceitou os termos?

Passo 4 — Pagamento (QR Code)

Respostas possíveis

Acompanhamento do pagamento

Simulação de pagamento (sandbox)

Passo 5 — Sucesso

📦 Como montar a tela de Sucesso

Quando exibir?

Dados exibidos

Passo 6 — Criar Pagamento

Respostas possíveis

Passo 6.1 — Reembolsar Pagamento Capturado

Respostas possíveis

Passo 7 — Listar Subsidiárias

Respostas possíveis

Webhook — Aceite de termos

Como tratar

Mapeamento técnico

Ambientes & URLs

API Pagaleve

Exemplo de URL completa

HTTP status codes

Webhook

Eventos disponíveis

Checklist go-live