VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Pagamentos

Formas de pagamento

Lista as formas ativas da loja e as elegíveis para um pedido.

Antes de cobrar, o checkout precisa saber como o cliente pode pagar. Estas duas rotas públicas respondem: o catálogo completo de formas ativas e a lista filtrada pelas regras da loja para um pedido específico.

Listar formas de pagamento

Devolve o catálogo de formas de pagamento ativas, sem aplicar regra nenhuma de elegibilidade. Serve para telas informativas ("aceitamos Pix, cartão e boleto"). Para saber o que este cliente pode usar em este pedido, use formas elegíveis.

GET/api/v1/storefront/payment-methodsPública

Todas as formas de pagamento ativas da loja

Parâmetros de consulta

vendoruuid
Seller do carrinho. Inclui os métodos próprios dele além dos da loja inteira.
vendor_idsstring
Vários sellers, separados por vírgula. Só os métodos da loja inteira valem quando há mais de um seller distinto, porque o checkout tem uma única escolha de pagamento.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/storefront/payment-methods"

Resposta

200Formas de pagamento
json
{
  "methods": [
    {
      "id": "02000000-0000-0000-0000-000000000001",
      "name": "PIX",
      "code": "pix",
      "processor_type": "online",
      "gateway": "pix",
      "provider": "pix",
      "status": "A",
      "position": 1,
      "uses_credit_limit": false,
      "min_order_amount": 0,
      "max_order_amount": 0,
      "surcharge_fixed": 0,
      "surcharge_percent": 0,
      "payment_id": "02000000-0000-0000-0000-000000000001",
      "payment": "PIX",
      "template": "pix",
      "processor": "pix",
      "payment_category": "online"
    },
    {
      "id": "263a89fd-f437-4486-b7c3-81c7337febf2",
      "name": "Boleto",
      "code": "boleto",
      "processor_type": "online",
      "gateway": "pagarme",
      "provider": "boleto",
      "status": "A",
      "position": 3,
      "uses_credit_limit": false,
      "min_order_amount": 50000,
      "max_order_amount": 0,
      "surcharge_fixed": 0,
      "surcharge_percent": 0,
      "payment_id": "263a89fd-f437-4486-b7c3-81c7337febf2",
      "payment": "Boleto",
      "template": "boleto",
      "processor": "pagarme",
      "payment_category": "online"
    },
    {
      "id": "02000000-0000-0000-0000-000000000010",
      "name": "Pagamento na Entrega (COD)",
      "code": "pagamento-na-entrega",
      "instructions": "O pagamento será cobrado na entrega do pedido.",
      "processor_type": "offline",
      "gateway": "",
      "provider": "offline",
      "status": "A",
      "position": 10,
      "uses_credit_limit": false,
      "min_order_amount": 0,
      "max_order_amount": 0,
      "surcharge_fixed": 0,
      "surcharge_percent": 0,
      "payment_id": "02000000-0000-0000-0000-000000000010",
      "payment": "Pagamento na Entrega (COD)",
      "template": "pagamento-na-entrega",
      "processor": "",
      "payment_category": "offline"
    }
  ],
  "total": 3
}

Campos da resposta

methodsarray
Formas de pagamento, ordenadas por position. Campos abaixo.
totalinteger
Quantidade de itens em methods.
iduuid
Id da forma de pagamento.
namestring
Nome para exibir ao cliente.
codestring
Código estável (slug), por exemplo pix, credit_card, boleto. É o valor de payment_method_code ao pagar. O catálogo é da loja: podem existir códigos próprios.
descriptionstring
Texto descritivo. Ausente se não houver.
instructionsstring
Instruções ao cliente (formas offline: dados bancários, "pague na entrega"). Ausente se não houver.
processor_typestring
onlineofflineinvoiced
online: cobrado por um gateway. offline: a loja confirma o pagamento depois (entrega, transferência). invoiced: boleto faturado, que consome o limite de crédito do cliente.
gatewaystring
Gateway que processa (por exemplo pagarme, pix). Vazio nas formas offline.
providerstring
Tipo semântico (pix, boleto, credit_card, offline...).
statusstring
Sempre A (ativa) nesta lista.
positioninteger
Ordem de exibição.
uses_credit_limitboolean
true quando o método consome o limite de crédito do cliente.
vendor_iduuid
Seller dono do método. Ausente nos métodos da loja inteira.
min_order_amountinteger
Pedido mínimo, em centavos, para o método aparecer. 0 ou ausente = sem mínimo.
max_order_amountinteger
Pedido máximo, em centavos. 0 ou ausente = sem máximo.
surcharge_fixedinteger
Acréscimo fixo em centavos. Negativo é desconto.
surcharge_percentinteger
Acréscimo percentual. Negativo é desconto.
pix_discount_bpsinteger
Só no Pix: desconto em pontos-base (1 bps = 0,01%; 200 = 2%). Ausente se não configurado.
pix_expiry_minutesinteger
Só no Pix: por quantos minutos o código vale. Ausente se não configurado.
installment_plansarray
Só em invoiced: planos de prazo habilitados (id, name, terms_days...).
credit_limit_centsinteger
Só em uses_credit_limit e só na rota de elegíveis, com cliente logado: limite total aprovado, em centavos.
credit_available_centsinteger
Idem: limite ainda disponível, em centavos.
credit_blockedboolean
Idem: true quando o cliente não pode usar o método (sem limite ou limite menor que o pedido).
credit_blocked_reasonstring
Idem: a frase, em português, para mostrar ao cliente.

Erros

StatusQuandoCorpo de exemplo
500Falha ao ler as formas de pagamento.{"error":"failed to get payment methods","detail":"..."}
Sem seller, só métodos da loja

Um método criado por um seller específico nunca aparece como se fosse da loja inteira. Sem vendor/vendor_ids você vê apenas os métodos da loja.

Formas de pagamento elegíveis

É a lista que o checkout deve mostrar. Aplica as regras da loja ao pedido: valor mínimo e máximo, forma de envio, estado de entrega, quantidade de itens, grupos de clientes e exceções por cliente. Funciona sem login (visitante) e melhora com o token: logado, os grupos e as exceções do cliente são lidos no servidor e as formas que usam crédito trazem o limite.

GET/api/v1/storefront/payments/eligiblePública

O que este cliente pode usar neste pedido

Parâmetros de consulta

order_totalintegerpadrão: 0
Total do pedido em centavos. Sem ele, formas com valor mínimo (como boleto) somem da lista.
shipping_method_iduuid
Forma de envio escolhida; algumas formas de pagamento dependem dela.
statestring
UF de entrega (SP).
countrystring
País de entrega (BR).
item_countintegerpadrão: 0
Quantidade de itens no carrinho.
user_group_idsstring
Grupos de clientes, separados por vírgula. Só vale para visitante; com token, é ignorado e o servidor usa os grupos reais do cliente.
vendoruuid
Seller do carrinho. Inclui os métodos próprios dele além dos da loja inteira.
vendor_idsstring
Vários sellers, separados por vírgula. Só os métodos da loja inteira valem quando há mais de um seller distinto, porque o checkout tem uma única escolha de pagamento.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/storefront/payments/eligible?order_total=60000&state=SP&item_count=3" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Formas elegíveis
json
{
  "methods": [
    {
      "id": "02000000-0000-0000-0000-000000000001",
      "name": "PIX",
      "code": "pix",
      "processor_type": "online",
      "gateway": "pix",
      "provider": "pix",
      "status": "A",
      "position": 1,
      "uses_credit_limit": false,
      "min_order_amount": 0,
      "max_order_amount": 0,
      "surcharge_fixed": 0,
      "surcharge_percent": 0,
      "payment_id": "02000000-0000-0000-0000-000000000001",
      "payment": "PIX",
      "template": "pix",
      "processor": "pix",
      "payment_category": "online"
    },
    {
      "id": "263a89fd-f437-4486-b7c3-81c7337febf2",
      "name": "Boleto",
      "code": "boleto",
      "processor_type": "online",
      "gateway": "pagarme",
      "provider": "boleto",
      "status": "A",
      "position": 3,
      "uses_credit_limit": false,
      "min_order_amount": 50000,
      "max_order_amount": 0,
      "surcharge_fixed": 0,
      "surcharge_percent": 0,
      "payment_id": "263a89fd-f437-4486-b7c3-81c7337febf2",
      "payment": "Boleto",
      "template": "boleto",
      "processor": "pagarme",
      "payment_category": "online"
    },
    {
      "id": "02000000-0000-0000-0000-000000000010",
      "name": "Pagamento na Entrega (COD)",
      "code": "pagamento-na-entrega",
      "instructions": "O pagamento será cobrado na entrega do pedido.",
      "processor_type": "offline",
      "gateway": "",
      "provider": "offline",
      "status": "A",
      "position": 10,
      "uses_credit_limit": false,
      "min_order_amount": 0,
      "max_order_amount": 0,
      "surcharge_fixed": 0,
      "surcharge_percent": 0,
      "payment_id": "02000000-0000-0000-0000-000000000010",
      "payment": "Pagamento na Entrega (COD)",
      "template": "pagamento-na-entrega",
      "processor": "",
      "payment_category": "offline"
    }
  ],
  "total": 3
}

Campos da resposta

methodsarray
Formas elegíveis, no mesmo formato de Listar formas de pagamento.
totalinteger
Quantidade de itens em methods.

Erros

StatusQuandoCorpo de exemplo
500Falha ao aplicar as regras.{"error":"failed to filter payment methods","detail":"..."}
Método bloqueado por crédito continua na lista

Quando o cliente não tem limite suficiente, a forma de pagamento não é removida: vem com credit_blocked: true e a frase em credit_blocked_reason. Mostre-a desabilitada e com o motivo, em vez de esconder. Visitante vê as formas de crédito sempre bloqueadas ("Entre na sua conta").

Veja também

  • Iniciar um pagamento
  • Parcelas
Anterior
Pagamentos
Próxima
Parcelas
Nesta página
  • Listar formas de pagamento
  • Formas de pagamento elegíveis
  • Veja também