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

Criar, alterar e apagar formas

Cadastra uma forma de pagamento, altera suas regras e a apaga.

Três escritas, todas com manage_payments. Cada uma é registrada no log de ações (tipo payments).

Criar uma forma

POST/api/v1/admin/payment-methodsAdmin

Cria uma forma de pagamento

Corpo da requisição

namestringobrigatório
Nome mostrado ao cliente.
slugstringobrigatório
Código único e estável (ex.: pix). Não muda depois.
providerstring
Tipo (pix, boleto, credit_card...). Se vazio, usa o gateway; sem gateway, o slug.
processor_typestringpadrão: online
onlineofflineinvoiced
online (padrão), offline ou invoiced.
gatewaystring
Gateway. Veja as opções.
statusstringpadrão: active
active ou inactive (ou A/D). Padrão: ativa.
configobject
Config livre. No invoiced: installment_plans e installment_rounding.
positioninteger
Ordem de exibição.
vendor_iduuid
Cria a forma para um seller. Vazio = loja toda.
min_order_amountinteger
Pedido mínimo em centavos.
max_order_amountinteger
Pedido máximo em centavos.
allowed_user_groupsarray
Grupos de clientes permitidos (ids).
blocked_user_groupsarray
Grupos bloqueados.
allowed_shipping_methodsarray
Ids de formas de envio permitidas.
allowed_statesarray
UFs permitidas.
surcharge_fixedinteger
Sobretaxa fixa em centavos.
surcharge_percentinteger
Sobretaxa em pontos-base.
internal_code_1string
Código interno 1.
internal_code_2string
Código interno 2.
payment_period_daysinteger
Prazo em dias.
uses_credit_limitboolean
Consome o limite de crédito do cliente.
uses_supplier_credit_limitboolean
Consome o limite do fornecedor.

Exemplo de requisição

Resposta

201Forma criada

Campos da resposta

iduuid
Id da forma.
display_idinteger
Número curto para o painel (ex.: forma nº 26).
namestring
Nome mostrado ao cliente.
codestring
O slug informado na criação.
processor_typestring
onlineofflineinvoiced
online, offline ou invoiced.
gatewaystring
Gateway que processa.
providerstring
Tipo do pagamento (pix, boleto, credit_card...). Aparece só em algumas leituras.
statusstring
AD
A ativa ou D desativada.
configobject
Configuração livre do método; no boleto faturado traz installment_plans.
positioninteger
Ordem de exibição.
vendor_iduuid
Dono (seller). Ausente = vale para a loja toda.
vendor_namestring
Nome do seller dono.
min_order_amountinteger
Pedido mínimo em centavos.
max_order_amountinteger
Pedido máximo em centavos. 0 ou ausente = sem teto.
allowed_user_groupsarray
Ids de grupos de clientes permitidos.
blocked_user_groupsarray
Grupos bloqueados.
allowed_shipping_methodsarray
Ids de formas de envio permitidas.
allowed_statesarray
UFs permitidas.
surcharge_fixedinteger
Sobretaxa fixa em centavos aplicada ao total.
surcharge_percentinteger
Sobretaxa em pontos-base (250 = 2,50%).
uses_credit_limitboolean
Consome o limite de crédito do cliente (B2B).
uses_supplier_credit_limitboolean
Consome o limite do fornecedor.
payment_period_daysinteger
Prazo de pagamento em dias.
internal_code_1string
Código interno 1 para ERP.
internal_code_2string
Código interno 2 para ERP.
payment_codestring
Código do método usado pelas regras por cliente e pelo ERP.
created_atstring
Criação (RFC 3339).

Erros

StatusQuandoCorpo de exemplo
400name ou slug ausente; min_exceeds_max; invalid_installment_plan.{"error":"min_exceeds_max","code":"admin.payments.minExceedsMax"}
401Sem token ou token inválido.{"error":"missing authorization header"}
403O usuário não tem o privilégio manage_payments (leitura aceita view_payments).{"error":"insufficient privileges","required":"manage_payments"}
422Gateway não disponível para a loja.{"error":"gateway_not_available","code":"admin.payments.gatewayNotAvailable"}

Alterar uma forma

Atualização parcial: só os campos enviados mudam. Para limpar uma lista (ex.: allowed_states), envie []. Um campo desconhecido no corpo é rejeitado em vez de ignorado quando a loja está nesse modo.

PUT/api/v1/admin/payment-methods/{id}Admin

Altera uma forma de pagamento

Parâmetros de caminho

iduuidobrigatório
Id da forma.

Corpo da requisição

namestring
Novo nome.
statusstring
active/inactive ou A/D.
is_activeboolean
Apelido de status (true = A). Também active e enabled.
processor_typestring
online, offline ou invoiced.
gatewaystring
Gateway.
configobject
Substitui a config.
positioninteger
Ordem.
min_order_amountinteger
Pedido mínimo em centavos.
max_order_amountinteger
Pedido máximo em centavos.
allowed_user_groupsarray
Grupos permitidos.
blocked_user_groupsarray
Grupos bloqueados.
allowed_shipping_methodsarray
Envios permitidos.
allowed_statesarray
UFs permitidas.
surcharge_fixedinteger
Sobretaxa fixa em centavos.
surcharge_percentinteger
Sobretaxa em pontos-base.
payment_period_daysinteger
Prazo em dias.
uses_credit_limitboolean
Limite do cliente.
uses_supplier_credit_limitboolean
Limite do fornecedor.
internal_code_1string
Código interno 1.
internal_code_2string
Código interno 2.

Exemplo de requisição

Resposta

200Forma alterada

Campos da resposta

iduuid
Id da forma.
display_idinteger
Número curto para o painel (ex.: forma nº 26).
namestring
Nome mostrado ao cliente.
codestring
O slug informado na criação.
processor_typestring
onlineofflineinvoiced
online, offline ou invoiced.
gatewaystring
Gateway que processa.
providerstring
Tipo do pagamento (pix, boleto, credit_card...). Aparece só em algumas leituras.
statusstring
AD
A ativa ou D desativada.
configobject
Configuração livre do método; no boleto faturado traz installment_plans.
positioninteger
Ordem de exibição.
vendor_iduuid
Dono (seller). Ausente = vale para a loja toda.
vendor_namestring
Nome do seller dono.
min_order_amountinteger
Pedido mínimo em centavos.
max_order_amountinteger
Pedido máximo em centavos. 0 ou ausente = sem teto.
allowed_user_groupsarray
Ids de grupos de clientes permitidos.
blocked_user_groupsarray
Grupos bloqueados.
allowed_shipping_methodsarray
Ids de formas de envio permitidas.
allowed_statesarray
UFs permitidas.
surcharge_fixedinteger
Sobretaxa fixa em centavos aplicada ao total.
surcharge_percentinteger
Sobretaxa em pontos-base (250 = 2,50%).
uses_credit_limitboolean
Consome o limite de crédito do cliente (B2B).
uses_supplier_credit_limitboolean
Consome o limite do fornecedor.
payment_period_daysinteger
Prazo de pagamento em dias.
internal_code_1string
Código interno 1 para ERP.
internal_code_2string
Código interno 2 para ERP.
payment_codestring
Código do método usado pelas regras por cliente e pelo ERP.
created_atstring
Criação (RFC 3339).

Erros

StatusQuandoCorpo de exemplo
400immutable_field (slug, provider ou vendor_id), invalid_payment_method_status, min_exceeds_max ou invalid_installment_plan.{"error":"immutable_field","detail":"o campo \"slug\" não pode ser alterado por este endpoint: ..."}
401Sem token ou token inválido.{"error":"missing authorization header"}
403O usuário não tem o privilégio manage_payments (leitura aceita view_payments).{"error":"insufficient privileges","required":"manage_payments"}
404Forma inexistente.{"error":"payment method not found"}
422Gateway não disponível para a loja.{"error":"gateway_not_available","code":"admin.payments.gatewayNotAvailable"}
Mensagens em português

Os textos de immutable_field e invalid_payment_method_status vêm em português, como o servidor devolve.

Apagar uma forma

Remove a forma de forma definitiva.

DELETE/api/v1/admin/payment-methods/{id}Admin

Apaga uma forma de pagamento

Parâmetros de caminho

iduuidobrigatório
Id da forma.

Exemplo de requisição

Resposta

200Apagada

Erros

StatusQuandoCorpo de exemplo
401Sem token ou token inválido.{"error":"missing authorization header"}
403O usuário não tem o privilégio manage_payments (leitura aceita view_payments).{"error":"insufficient privileges","required":"manage_payments"}
404Forma inexistente.{"error":"payment method not found"}
500Falha ao apagar, por exemplo por vínculo existente.{"error":"failed to delete payment method","detail":"..."}
Prefira desativar

Não há lixeira. Para tirar a forma do checkout sem perder a configuração, envie {"status":"inactive"} no PUT.

Veja também

  • Formas de pagamento
Anterior
Consultar formas de pagamento
Próxima
Dependências da forma de pagamento
Nesta página
  • Criar uma forma
  • Exemplo de requisição
  • Resposta
  • Erros
  • Alterar uma forma
  • Exemplo de requisição
  • Resposta
  • Erros
  • Apagar uma forma
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também
bash
curl -X POST "$BASE_URL/api/v1/admin/payment-methods" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "PIX",
    "slug": "pix",
    "provider": "pix",
    "gateway": "pix",
    "processor_type": "online",
    "min_order_amount": 1000,
    "surcharge_percent": 0
  }'
bash
curl -X PUT "$BASE_URL/api/v1/admin/payment-methods/08fd91cd-ce15-4b28-9482-db37b8778b36" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "inactive",
    "max_order_amount": 500000
  }'
bash
curl -X DELETE "$BASE_URL/api/v1/admin/payment-methods/08fd91cd-ce15-4b28-9482-db37b8778b36" \
  -H "Authorization: Bearer $TOKEN"
json
{
  "id": "08fd91cd-ce15-4b28-9482-db37b8778b36",
  "display_id": 26,
  "name": "PIX",
  "code": "pix",
  "processor_type": "online",
  "gateway": "pix",
  "status": "A",
  "uses_credit_limit": false,
  "payment_period_days": 0,
  "uses_supplier_credit_limit": false,
  "config": null,
  "position": 0,
  "created_at": "2026-07-08T02:58:06Z",
  "min_order_amount": 1000,
  "max_order_amount": 0,
  "surcharge_fixed": 0,
  "surcharge_percent": 0
}
json
{
  "id": "08fd91cd-ce15-4b28-9482-db37b8778b36",
  "display_id": 26,
  "name": "Boleto Faturado",
  "code": "boleto-faturado",
  "processor_type": "invoiced",
  "gateway": "invoiced",
  "status": "D",
  "uses_credit_limit": false,
  "payment_period_days": 0,
  "uses_supplier_credit_limit": false,
  "config": {
    "installment_plans": [
      {
        "id": "30-60-90",
        "name": "30/60/90",
        "enabled": true,
        "terms_days": [
          30,
          60,
          90
        ],
        "installments": 3
      }
    ]
  },
  "position": 0,
  "created_at": "2026-07-08T02:58:06Z",
  "min_order_amount": 5000,
  "max_order_amount": 500000,
  "surcharge_fixed": 0,
  "surcharge_percent": 0
}
json
{
  "message": "payment method deleted"
}