VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Cupons, vales, pagamentos e NF-e

Formas de pagamento do seller

Cria e mantém as formas de pagamento que o seller oferece para os próprios produtos.

Algumas lojas deixam cada seller decidir como quer receber: um aceita PIX, outro só boleto faturado para empresas. Estas rotas gerenciam essas formas. Elas são aplicadas no checkout pelos itens do seller; as formas globais da loja continuam sendo do administrador.

Status vem como letra

Você cria e atualiza com active / inactive, mas a resposta traz A / D. Outros textos de status são gravados sem conferência e podem falhar com 500.

Boleto faturado

Com processor_type: "invoiced" o método vende a prazo, em parcelas. config.installment_plans precisa ter planos com ao menos 1 parcela, um prazo (terms_days) por parcela, sem prazos negativos e em ordem crescente.

Listar formas de pagamento

Uma forma de pagamento é uma opção do checkout (PIX, boleto, cartão, boleto faturado...). O seller pode ter as suas, oferecidas só para os itens dele; as da loja inteira são do administrador e não aparecem aqui. Lista as do seller por ordem de position.

GET/api/v1/vendor/payment-methodsSeller

Formas de pagamento próprias do seller

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso de um usuário seller (veja Tokens).

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/vendor/payment-methods" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Formas de pagamento
json
{
  "methods": [
    {
      "id": "0b7f7a58-0f3e-4b5c-9a7c-3c2a8e6f1d21",
      "display_id": 47,
      "name": "PIX da Loja",
      "code": "pix",
      "processor_type": "online",
      "gateway": "pix",
      "provider": "pix",
      "status": "A",
      "uses_credit_limit": false,
      "payment_period_days": 0,
      "uses_supplier_credit_limit": false,
      "payment_code": "pix",
      "config": {},
      "position": 1,
      "created_at": "2026-10-01T12:00:00Z",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "min_order_amount": 1000,
      "surcharge_fixed": 0,
      "surcharge_percent": 0
    }
  ],
  "total": 1
}

Campos da resposta

methodsobject[]

Formas de pagamento.

iduuid
Id da forma de pagamento.
display_idinteger
Número curto para exibição.
namestring
Nome mostrado no checkout.
codestring
Tipo semântico (pix, boleto, credit_card...), igual a payment_code. Não é o slug técnico.
processor_typestring
onlineofflineinvoiced
Como é processado.
gatewaystring
Gateway que roteia (pagarme, pix, offline...).
providerstring
Tipo de pagamento enviado na criação.
statusstring
AD
Letra: A ativa, D inativa.
uses_credit_limitboolean
Em Boleto Faturado, se consome o limite de crédito do cliente.
uses_supplier_credit_limitboolean
Se consome o limite do fornecedor.
payment_period_daysinteger
Prazo de pagamento em dias.
internal_code_1string
Código interno 1 (ERP). Omitido se vazio.
internal_code_2string
Código interno 2. Omitido se vazio.
payment_codestring
Código do método para regras por cliente e ERP.
configobject
Configuração livre; em invoiced carrega installment_plans.
positioninteger
Ordem de exibição.
created_atstring
Criação, RFC 3339.
vendor_iduuid
Seller dono. Sempre o seu.
min_order_amountinteger
Pedido mínimo (centavos) para oferecer o método. Omitido = sem mínimo.
max_order_amountinteger
Pedido máximo (centavos). Omitido = sem máximo.
allowed_user_groupsstring[]
Grupos de clientes que podem usar. Omitido = todos.
blocked_user_groupsstring[]
Grupos bloqueados.
allowed_shipping_methodsstring[]
Formas de envio com que o método combina. Omitido = todas.
allowed_statesstring[]
UFs atendidas (SP, RJ...). Omitido = todas.
surcharge_fixedinteger
Acréscimo fixo em centavos.
surcharge_percentinteger
Acréscimo percentual em pontos-base (250 = 2,5%).
totalinteger
Quantidade.

Erros

StatusQuandoCorpo de exemplo
401Token ausente, inválido, expirado ou revogado.{"error":"missing authorization header"}
403O token não é de um usuário seller (por exemplo, é de administrador), ou o usuário não está vinculado a nenhum seller.{"error":"insufficient permissions"}
403Sub-conta do seller sem nenhum dos privilégios de configurações (a lista completa vem em privilege_required_any; o exemplo está cortado). O dono da loja passa sempre.{"error":"insufficient vendor privileges","privilege_required_any":["vendor_settings","vendor_view_settings"]}
403O usuário não está vinculado a nenhum seller.{"error":"no vendor account associated with this user"}

Criar forma de pagamento

Cria uma forma de pagamento do seller. O vendor_id do corpo é ignorado e o slug é gerado pela plataforma (não é aceito). Em carrinhos com itens de um único seller o checkout oferece as formas dele mais as da loja; com vários sellers, só as da loja.

POST/api/v1/vendor/payment-methodsSeller

Criar uma forma de pagamento

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso de um usuário seller (veja Tokens).
Content-Typestringobrigatório
application/json.

Corpo da requisição

namestringobrigatório
Nome mostrado no checkout.
providerstringobrigatório
Tipo do pagamento, por exemplo pix, boleto, credit_card, offline. Não pode ser alterado depois.
processor_typestringpadrão: online
onlineofflineinvoiced
Como é processado. invoiced é o Boleto Faturado e exige config.installment_plans válido.
gatewaystring
Gateway. Em offline e invoiced, se omitido, vira o próprio processor_type.
statusstringpadrão: active
activeinactive
Situação inicial.
configobject
Configuração livre. Em invoiced: installment_plans (lista de planos com name, installments, terms_days, enabled, surcharge_percent, code_1, code_2).
positioninteger
Ordem de exibição.
min_order_amountinteger
Pedido mínimo, centavos. Não pode passar de max_order_amount.
max_order_amountinteger
Pedido máximo, centavos.
allowed_user_groupsstring[]
Grupos de clientes permitidos.
blocked_user_groupsstring[]
Grupos bloqueados.
allowed_shipping_methodsstring[]
Formas de envio permitidas.
allowed_statesstring[]
UFs permitidas.
surcharge_fixedinteger
Acréscimo fixo, centavos.
surcharge_percentinteger
Acréscimo percentual, 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

bash
curl -X POST "$BASE_URL/api/v1/vendor/payment-methods" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "PIX da Loja",
  "provider": "pix",
  "processor_type": "online",
  "gateway": "pix",
  "position": 1,
  "min_order_amount": 1000
}'

Resposta

201Forma criada
json
{
  "id": "0b7f7a58-0f3e-4b5c-9a7c-3c2a8e6f1d21",
  "display_id": 47,
  "name": "PIX da Loja",
  "code": "pix",
  "processor_type": "online",
  "gateway": "pix",
  "provider": "pix",
  "status": "A",
  "uses_credit_limit": false,
  "payment_period_days": 0,
  "uses_supplier_credit_limit": false,
  "payment_code": "pix",
  "config": {},
  "position": 1,
  "created_at": "2026-10-01T12:00:00Z",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "min_order_amount": 1000,
  "surcharge_fixed": 0,
  "surcharge_percent": 0
}

Campos da resposta

iduuid
Id da forma de pagamento.
display_idinteger
Número curto para exibição.
namestring
Nome mostrado no checkout.
codestring
Tipo semântico (pix, boleto, credit_card...), igual a payment_code. Não é o slug técnico.
processor_typestring
onlineofflineinvoiced
Como é processado.
gatewaystring
Gateway que roteia (pagarme, pix, offline...).
providerstring
Tipo de pagamento enviado na criação.
statusstring
AD
Letra: A ativa, D inativa.
uses_credit_limitboolean
Em Boleto Faturado, se consome o limite de crédito do cliente.
uses_supplier_credit_limitboolean
Se consome o limite do fornecedor.
payment_period_daysinteger
Prazo de pagamento em dias.
internal_code_1string
Código interno 1 (ERP). Omitido se vazio.
internal_code_2string
Código interno 2. Omitido se vazio.
payment_codestring
Código do método para regras por cliente e ERP.
configobject
Configuração livre; em invoiced carrega installment_plans.
positioninteger
Ordem de exibição.
created_atstring
Criação, RFC 3339.
vendor_iduuid
Seller dono. Sempre o seu.
min_order_amountinteger
Pedido mínimo (centavos) para oferecer o método. Omitido = sem mínimo.
max_order_amountinteger
Pedido máximo (centavos). Omitido = sem máximo.
allowed_user_groupsstring[]
Grupos de clientes que podem usar. Omitido = todos.
blocked_user_groupsstring[]
Grupos bloqueados.
allowed_shipping_methodsstring[]
Formas de envio com que o método combina. Omitido = todas.
allowed_statesstring[]
UFs atendidas (SP, RJ...). Omitido = todas.
surcharge_fixedinteger
Acréscimo fixo em centavos.
surcharge_percentinteger
Acréscimo percentual em pontos-base (250 = 2,5%).

Erros

StatusQuandoCorpo de exemplo
400name ou provider ausentes.{"error":"name is required"}
400min_order_amount maior que max_order_amount.{"error":"payment method: min_order_amount must be ≤ max_order_amount"}
400Plano de parcelas inválido em um método invoiced.{"error":"invalid_installment_plan","code":"admin.payments.invoiced.invalidPlan"}
401Token ausente, inválido, expirado ou revogado.{"error":"missing authorization header"}
403O token não é de um usuário seller (por exemplo, é de administrador), ou o usuário não está vinculado a nenhum seller.{"error":"insufficient permissions"}
403Sub-conta do seller sem nenhum dos privilégios de configurações (a lista completa vem em privilege_required_any; o exemplo está cortado). O dono da loja passa sempre.{"error":"insufficient vendor privileges","privilege_required_any":["vendor_settings","vendor_view_settings"]}
403O usuário não está vinculado a nenhum seller.{"error":"no vendor account associated with this user"}

Ver forma de pagamento

Devolve uma forma de pagamento do seller.

GET/api/v1/vendor/payment-methods/{id}Seller

Detalhe de uma forma de pagamento

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso de um usuário seller (veja Tokens).

Parâmetros de caminho

iduuidobrigatório
Id da forma de pagamento.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/vendor/payment-methods/0b7f7a58-0f3e-4b5c-9a7c-3c2a8e6f1d21" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Forma
json
{
  "id": "0b7f7a58-0f3e-4b5c-9a7c-3c2a8e6f1d21",
  "display_id": 47,
  "name": "PIX da Loja",
  "code": "pix",
  "processor_type": "online",
  "gateway": "pix",
  "provider": "pix",
  "status": "A",
  "uses_credit_limit": false,
  "payment_period_days": 0,
  "uses_supplier_credit_limit": false,
  "payment_code": "pix",
  "config": {},
  "position": 1,
  "created_at": "2026-10-01T12:00:00Z",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "min_order_amount": 1000,
  "surcharge_fixed": 0,
  "surcharge_percent": 0
}

Campos da resposta

iduuid
Id da forma de pagamento.
display_idinteger
Número curto para exibição.
namestring
Nome mostrado no checkout.
codestring
Tipo semântico (pix, boleto, credit_card...), igual a payment_code. Não é o slug técnico.
processor_typestring
onlineofflineinvoiced
Como é processado.
gatewaystring
Gateway que roteia (pagarme, pix, offline...).
providerstring
Tipo de pagamento enviado na criação.
statusstring
AD
Letra: A ativa, D inativa.
uses_credit_limitboolean
Em Boleto Faturado, se consome o limite de crédito do cliente.
uses_supplier_credit_limitboolean
Se consome o limite do fornecedor.
payment_period_daysinteger
Prazo de pagamento em dias.
internal_code_1string
Código interno 1 (ERP). Omitido se vazio.
internal_code_2string
Código interno 2. Omitido se vazio.
payment_codestring
Código do método para regras por cliente e ERP.
configobject
Configuração livre; em invoiced carrega installment_plans.
positioninteger
Ordem de exibição.
created_atstring
Criação, RFC 3339.
vendor_iduuid
Seller dono. Sempre o seu.
min_order_amountinteger
Pedido mínimo (centavos) para oferecer o método. Omitido = sem mínimo.
max_order_amountinteger
Pedido máximo (centavos). Omitido = sem máximo.
allowed_user_groupsstring[]
Grupos de clientes que podem usar. Omitido = todos.
blocked_user_groupsstring[]
Grupos bloqueados.
allowed_shipping_methodsstring[]
Formas de envio com que o método combina. Omitido = todas.
allowed_statesstring[]
UFs atendidas (SP, RJ...). Omitido = todas.
surcharge_fixedinteger
Acréscimo fixo em centavos.
surcharge_percentinteger
Acréscimo percentual em pontos-base (250 = 2,5%).

Erros

StatusQuandoCorpo de exemplo
404A forma de pagamento não existe ou não é do seller.{"error":"payment method not found"}
500id não é um UUID válido (hoje 500).{"error":"failed to get payment method","detail":"o valor \"xyz\" não é um uuid válido..."}
401Token ausente, inválido, expirado ou revogado.{"error":"missing authorization header"}
403O token não é de um usuário seller (por exemplo, é de administrador), ou o usuário não está vinculado a nenhum seller.{"error":"insufficient permissions"}
403Sub-conta do seller sem nenhum dos privilégios de configurações (a lista completa vem em privilege_required_any; o exemplo está cortado). O dono da loja passa sempre.{"error":"insufficient vendor privileges","privilege_required_any":["vendor_settings","vendor_view_settings"]}
403O usuário não está vinculado a nenhum seller.{"error":"no vendor account associated with this user"}

Atualizar forma de pagamento

Altera só os campos enviados. Listas (allowed_*, blocked_*) enviadas vazias limpam a restrição. O provider não muda depois de criado.

PUT/api/v1/vendor/payment-methods/{id}Seller

Alterar uma forma de pagamento

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso de um usuário seller (veja Tokens).
Content-Typestringobrigatório
application/json.

Parâmetros de caminho

iduuidobrigatório
Id da forma de pagamento.

Corpo da requisição

namestring
Nome mostrado no checkout.
processor_typestring
onlineofflineinvoiced
Como é processado. invoiced é o Boleto Faturado e exige config.installment_plans válido.
gatewaystring
Gateway. Em offline e invoiced, se omitido, vira o próprio processor_type.
statusstring
activeinactive
Nova situação.
configobject
Configuração livre. Em invoiced: installment_plans (lista de planos com name, installments, terms_days, enabled, surcharge_percent, code_1, code_2).
positioninteger
Ordem de exibição.
min_order_amountinteger
Pedido mínimo, centavos. Não pode passar de max_order_amount.
max_order_amountinteger
Pedido máximo, centavos.
allowed_user_groupsstring[]
Grupos de clientes permitidos.
blocked_user_groupsstring[]
Grupos bloqueados.
allowed_shipping_methodsstring[]
Formas de envio permitidas.
allowed_statesstring[]
UFs permitidas.
surcharge_fixedinteger
Acréscimo fixo, centavos.
surcharge_percentinteger
Acréscimo percentual, 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

bash
curl -X PUT "$BASE_URL/api/v1/vendor/payment-methods/0b7f7a58-0f3e-4b5c-9a7c-3c2a8e6f1d21" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "inactive"
}'

Resposta

200Forma atualizada
json
{
  "id": "0b7f7a58-0f3e-4b5c-9a7c-3c2a8e6f1d21",
  "display_id": 47,
  "name": "PIX da Loja",
  "code": "pix",
  "processor_type": "online",
  "gateway": "pix",
  "provider": "pix",
  "status": "D",
  "uses_credit_limit": false,
  "payment_period_days": 0,
  "uses_supplier_credit_limit": false,
  "payment_code": "pix",
  "config": {},
  "position": 1,
  "created_at": "2026-10-01T12:00:00Z",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "min_order_amount": 1000,
  "surcharge_fixed": 0,
  "surcharge_percent": 0
}

Campos da resposta

iduuid
Id da forma de pagamento.
display_idinteger
Número curto para exibição.
namestring
Nome mostrado no checkout.
codestring
Tipo semântico (pix, boleto, credit_card...), igual a payment_code. Não é o slug técnico.
processor_typestring
onlineofflineinvoiced
Como é processado.
gatewaystring
Gateway que roteia (pagarme, pix, offline...).
providerstring
Tipo de pagamento enviado na criação.
statusstring
AD
Letra: A ativa, D inativa.
uses_credit_limitboolean
Em Boleto Faturado, se consome o limite de crédito do cliente.
uses_supplier_credit_limitboolean
Se consome o limite do fornecedor.
payment_period_daysinteger
Prazo de pagamento em dias.
internal_code_1string
Código interno 1 (ERP). Omitido se vazio.
internal_code_2string
Código interno 2. Omitido se vazio.
payment_codestring
Código do método para regras por cliente e ERP.
configobject
Configuração livre; em invoiced carrega installment_plans.
positioninteger
Ordem de exibição.
created_atstring
Criação, RFC 3339.
vendor_iduuid
Seller dono. Sempre o seu.
min_order_amountinteger
Pedido mínimo (centavos) para oferecer o método. Omitido = sem mínimo.
max_order_amountinteger
Pedido máximo (centavos). Omitido = sem máximo.
allowed_user_groupsstring[]
Grupos de clientes que podem usar. Omitido = todos.
blocked_user_groupsstring[]
Grupos bloqueados.
allowed_shipping_methodsstring[]
Formas de envio com que o método combina. Omitido = todas.
allowed_statesstring[]
UFs atendidas (SP, RJ...). Omitido = todas.
surcharge_fixedinteger
Acréscimo fixo em centavos.
surcharge_percentinteger
Acréscimo percentual em pontos-base (250 = 2,5%).

Erros

StatusQuandoCorpo de exemplo
400min_order_amount maior que max_order_amount.{"error":"payment method: min_order_amount must be ≤ max_order_amount"}
400Plano de parcelas inválido em um método invoiced.{"error":"invalid_installment_plan","code":"admin.payments.invoiced.invalidPlan"}
404A forma de pagamento não existe ou não é do seller.{"error":"payment method not found"}
401Token ausente, inválido, expirado ou revogado.{"error":"missing authorization header"}
403O token não é de um usuário seller (por exemplo, é de administrador), ou o usuário não está vinculado a nenhum seller.{"error":"insufficient permissions"}
403Sub-conta do seller sem nenhum dos privilégios de configurações (a lista completa vem em privilege_required_any; o exemplo está cortado). O dono da loja passa sempre.{"error":"insufficient vendor privileges","privilege_required_any":["vendor_settings","vendor_view_settings"]}
403O usuário não está vinculado a nenhum seller.{"error":"no vendor account associated with this user"}

Excluir forma de pagamento

Remove a forma de pagamento do seller. Para só tirar do checkout, use PUT com status: "inactive".

DELETE/api/v1/vendor/payment-methods/{id}Seller

Excluir uma forma de pagamento

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso de um usuário seller (veja Tokens).

Parâmetros de caminho

iduuidobrigatório
Id da forma de pagamento.

Exemplo de requisição

bash
curl -X DELETE "$BASE_URL/api/v1/vendor/payment-methods/0b7f7a58-0f3e-4b5c-9a7c-3c2a8e6f1d21" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Forma excluída
json
{
  "message": "payment method deleted"
}

Erros

StatusQuandoCorpo de exemplo
404A forma de pagamento não existe ou não é do seller.{"error":"payment method not found"}
401Token ausente, inválido, expirado ou revogado.{"error":"missing authorization header"}
403O token não é de um usuário seller (por exemplo, é de administrador), ou o usuário não está vinculado a nenhum seller.{"error":"insufficient permissions"}
403Sub-conta do seller sem nenhum dos privilégios de configurações (a lista completa vem em privilege_required_any; o exemplo está cortado). O dono da loja passa sempre.{"error":"insufficient vendor privileges","privilege_required_any":["vendor_settings","vendor_view_settings"]}
403O usuário não está vinculado a nenhum seller.{"error":"no vendor account associated with this user"}

Veja também

  • Cupons
  • Visão geral
Anterior
Vales-presente do seller
Próxima
NF-e do seller
Nesta página
  • Listar formas de pagamento
  • Exemplo de requisição
  • Resposta
  • Erros
  • Criar forma de pagamento
  • Exemplo de requisição
  • Resposta
  • Erros
  • Ver forma de pagamento
  • Exemplo de requisição
  • Resposta
  • Erros
  • Atualizar forma de pagamento
  • Exemplo de requisição
  • Resposta
  • Erros
  • Excluir forma de pagamento
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também