API legada/Referência completa/Pagamentos e impostos

Formas de pagamento

Lista, consulta, cria, altera e remove as formas de pagamento que a loja oferece no checkout.

Uma forma de pagamento é uma opção que o cliente escolhe ao fechar o pedido: Pix, boleto, cartão, pagamento na entrega. Estas rotas leem e mantêm esse cadastro. Todas exigem um usuário administrador. As credenciais do gateway ficam guardadas no servidor e nunca voltam na resposta.

GET/api/v1.0/paymentsAdmin

Listar as formas de pagamento

Devolve as formas de pagamento da loja, ativas e desativadas, em páginas.

Parâmetros de consulta

pageintegerpadrão: 1

Página, a partir de 1.

items_per_pageintegerpadrão: 10

Itens por página, de 1 a 250. Fora disso vale 10.

GET/api/v1.0/payments/{id}Admin

Consultar uma forma de pagamento

Devolve uma forma de pagamento.

Parâmetros de caminho

idstringobrigatório

Id da forma de pagamento (UUID).

POST/api/v1.0/paymentsAdmin

Criar uma forma de pagamento

Cria a forma de pagamento e responde 201 com o id. O identificador interno da forma é derivado do nome (minúscula, hífen no lugar dos espaços).

Corpo da requisição

paymentstringobrigatório

Nome que o cliente vê no checkout.

processor_typestringpadrão: offline

onlineofflineinvoiced

Tipo de processamento: online (gateway), offline (pagamento na entrega, transferência) ou invoiced (boleto faturado, que exige installment_plans em processor_params).

statusstring

AD

A, active ou enabled ativam. Qualquer outro valor, inclusive vazio, cria a forma desativada.

processor_paramsobject

Configuração do meio de pagamento, objeto livre. Para pagamento na entrega, instructions guarda o texto mostrado ao cliente. Para invoiced, installment_plans lista os planos de parcelas.

positioninteger

Ordem de exibição.

PUT/api/v1.0/payments/{id}Admin

Alterar uma forma de pagamento

Altera só o que você enviar e responde 200 com o id.

Parâmetros de caminho

idstringobrigatório

Id da forma de pagamento.

Corpo da requisição

paymentstring

Novo nome.

statusstring

AD

A, active ou enabled ativam; qualquer outro valor desativa. Se o campo for omitido, o status não muda.

processor_typestring

onlineofflineinvoiced

Tipo de processamento.

processor_paramsobject

Configuração do meio de pagamento. Substitui a configuração anterior.

positioninteger

Ordem de exibição (só vale acima de 0).

DELETE/api/v1.0/payments/{id}Admin

Remover uma forma de pagamento

Remove a forma de pagamento e responde 204 sem corpo. Se ela já foi usada em pedidos, prefira desativá-la com PUT.

Parâmetros de caminho

idstringobrigatório

Id da forma de pagamento.

Exemplo de requisição

bash

curl -u "$EMAIL:$API_KEY" -X POST "$BASE_URL/api/v1.0/payments" \
  -H "Content-Type: application/json" \
  -d '{"payment":"Pagamento na Entrega","processor_type":"offline","status":"A","processor_params":{"instructions":"O pagamento será cobrado na entrega do pedido."},"position":10}'

curl -u "$EMAIL:$API_KEY" "$BASE_URL/api/v1.0/payments?items_per_page=10"

Resposta

200Lista de formas de pagamento

json

{
  "params": { "page": 1, "items_per_page": 10, "total_items": 2 },
  "payments": [
    {
      "payment_id": "02000000-0000-0000-0000-000000000001",
      "payment": "PIX",
      "description": "",
      "instructions": "",
      "template": "",
      "processor_params": {},
      "status": "A",
      "company_id": "",
      "position": 1,
      "processor_id": 0,
      "processor": "pix",
      "processor_type": "P",
      "processor_status": "A",
      "surcharge": 0,
      "a_surcharge": 0,
      "p_surcharge": 0,
      "tax_ids": "",
      "usergroup_ids": "",
      "venddor_processor_type": "online"
    },
    {
      "payment_id": "02000000-0000-0000-0000-000000000010",
      "payment": "Pagamento na Entrega (COD)",
      "description": "",
      "instructions": "O pagamento será cobrado na entrega do pedido.",
      "template": "",
      "processor_params": { "instructions": "O pagamento será cobrado na entrega do pedido." },
      "status": "A",
      "company_id": "",
      "position": 10,
      "processor_id": 0,
      "processor": "",
      "processor_type": "P",
      "processor_status": "A",
      "surcharge": 0,
      "a_surcharge": 0,
      "p_surcharge": 0,
      "tax_ids": "",
      "usergroup_ids": "",
      "venddor_processor_type": "offline"
    }
  ]
}

201Forma criada

json

{ "payment_id": "5b2f4d0e-3c8a-4a8e-9a37-2f6f0c7d9e11" }

Campos da resposta

payment_idstring

Id da forma (UUID).

paymentstring

Nome mostrado ao cliente.

descriptionstring

Descrição, quando existe.

instructionsstring

Texto de instruções ao cliente, tirado de processor_params.instructions. Vazio quando não há.

templatestring

Sempre vazio.

processor_paramsobject

Configuração do meio de pagamento, sem as chaves secretas (chaves de API, tokens, senhas e semelhantes).

statusstring

AD

A ativa, D desativada.

company_idstring

Identificador da loja; pode vir vazio.

positioninteger

Ordem de exibição.

processor_idinteger

Sempre 0.

processorstring

Nome do gateway (pix, pagarme...). Vazio em formas offline sem gateway.

processor_typestring

Sempre P, por compatibilidade.

processor_statusstring

Sempre A.

surchargenumber

Sempre 0.

a_surchargenumber

Acréscimo fixo, em decimal da moeda da loja (3.5 = R$ 3,50).

p_surchargenumber

Acréscimo percentual (2.5 = 2,5%).

tax_idsstring

Sempre vazio.

usergroup_idsstring

Ids de grupos de usuários que podem usar a forma, separados por vírgula. Vazio para todos.

venddor_processor_typestring

onlineofflineinvoiced

Tipo real de processamento.

paramsobject

page, items_per_page e total_items.

Erros

Status	Quando	Corpo
400	Corpo que não é JSON	`{"message":"invalid request body","status":400}`
400	Falta `payment` na criação	`{"message":"payment name is required","status":400}`
400	Dados rejeitados (por exemplo, planos de parcelas inválidos em `invoiced`)	`{"message":"...","status":400}`
401	Sem credenciais	`{"message":"Authentication required. Use HTTP Basic with email:api_key or Bearer <jwt>.","status":401}`
403	Usuário que não é administrador	`{"message":"Forbidden: admin scope required","status":403}`
404	Forma inexistente	`{"message":"payment method not found","status":404}`

Veja também

Formas de pagamento

Lista, consulta, cria, altera e remove as formas de pagamento que a loja oferece no checkout.

GET/api/v1.0/paymentsAdmin

Listar as formas de pagamento

Devolve as formas de pagamento da loja, ativas e desativadas, em páginas.

Parâmetros de consulta

pageintegerpadrão: 1

Página, a partir de 1.

items_per_pageintegerpadrão: 10

Itens por página, de 1 a 250. Fora disso vale 10.

GET/api/v1.0/payments/{id}Admin

Consultar uma forma de pagamento

Devolve uma forma de pagamento.

Parâmetros de caminho

idstringobrigatório

Id da forma de pagamento (UUID).

POST/api/v1.0/paymentsAdmin

Criar uma forma de pagamento

Cria a forma de pagamento e responde 201 com o id. O identificador interno da forma é derivado do nome (minúscula, hífen no lugar dos espaços).

Corpo da requisição

paymentstringobrigatório

Nome que o cliente vê no checkout.

processor_typestringpadrão: offline

onlineofflineinvoiced

Tipo de processamento: online (gateway), offline (pagamento na entrega, transferência) ou invoiced (boleto faturado, que exige installment_plans em processor_params).

statusstring

AD

A, active ou enabled ativam. Qualquer outro valor, inclusive vazio, cria a forma desativada.

processor_paramsobject

Configuração do meio de pagamento, objeto livre. Para pagamento na entrega, instructions guarda o texto mostrado ao cliente. Para invoiced, installment_plans lista os planos de parcelas.

positioninteger

Ordem de exibição.

PUT/api/v1.0/payments/{id}Admin

Alterar uma forma de pagamento

Altera só o que você enviar e responde 200 com o id.

Parâmetros de caminho

idstringobrigatório

Id da forma de pagamento.

Corpo da requisição

paymentstring

Novo nome.

statusstring

AD

A, active ou enabled ativam; qualquer outro valor desativa. Se o campo for omitido, o status não muda.

processor_typestring

onlineofflineinvoiced

Tipo de processamento.

processor_paramsobject

Configuração do meio de pagamento. Substitui a configuração anterior.

positioninteger

Ordem de exibição (só vale acima de 0).

DELETE/api/v1.0/payments/{id}Admin

Remover uma forma de pagamento

Remove a forma de pagamento e responde 204 sem corpo. Se ela já foi usada em pedidos, prefira desativá-la com PUT.

Parâmetros de caminho

idstringobrigatório

Id da forma de pagamento.

Exemplo de requisição

bash

curl -u "$EMAIL:$API_KEY" -X POST "$BASE_URL/api/v1.0/payments" \
  -H "Content-Type: application/json" \
  -d '{"payment":"Pagamento na Entrega","processor_type":"offline","status":"A","processor_params":{"instructions":"O pagamento será cobrado na entrega do pedido."},"position":10}'

curl -u "$EMAIL:$API_KEY" "$BASE_URL/api/v1.0/payments?items_per_page=10"

Resposta

200Lista de formas de pagamento

json

{
  "params": { "page": 1, "items_per_page": 10, "total_items": 2 },
  "payments": [
    {
      "payment_id": "02000000-0000-0000-0000-000000000001",
      "payment": "PIX",
      "description": "",
      "instructions": "",
      "template": "",
      "processor_params": {},
      "status": "A",
      "company_id": "",
      "position": 1,
      "processor_id": 0,
      "processor": "pix",
      "processor_type": "P",
      "processor_status": "A",
      "surcharge": 0,
      "a_surcharge": 0,
      "p_surcharge": 0,
      "tax_ids": "",
      "usergroup_ids": "",
      "venddor_processor_type": "online"
    },
    {
      "payment_id": "02000000-0000-0000-0000-000000000010",
      "payment": "Pagamento na Entrega (COD)",
      "description": "",
      "instructions": "O pagamento será cobrado na entrega do pedido.",
      "template": "",
      "processor_params": { "instructions": "O pagamento será cobrado na entrega do pedido." },
      "status": "A",
      "company_id": "",
      "position": 10,
      "processor_id": 0,
      "processor": "",
      "processor_type": "P",
      "processor_status": "A",
      "surcharge": 0,
      "a_surcharge": 0,
      "p_surcharge": 0,
      "tax_ids": "",
      "usergroup_ids": "",
      "venddor_processor_type": "offline"
    }
  ]
}

201Forma criada

json

{ "payment_id": "5b2f4d0e-3c8a-4a8e-9a37-2f6f0c7d9e11" }

Campos da resposta

payment_idstring

Id da forma (UUID).

paymentstring

Nome mostrado ao cliente.

descriptionstring

Descrição, quando existe.

instructionsstring

Texto de instruções ao cliente, tirado de processor_params.instructions. Vazio quando não há.

templatestring

Sempre vazio.

processor_paramsobject

Configuração do meio de pagamento, sem as chaves secretas (chaves de API, tokens, senhas e semelhantes).

statusstring

AD

A ativa, D desativada.

company_idstring

Identificador da loja; pode vir vazio.

positioninteger

Ordem de exibição.

processor_idinteger

Sempre 0.

processorstring

Nome do gateway (pix, pagarme...). Vazio em formas offline sem gateway.

processor_typestring

Sempre P, por compatibilidade.

processor_statusstring

Sempre A.

surchargenumber

Sempre 0.

a_surchargenumber

Acréscimo fixo, em decimal da moeda da loja (3.5 = R$ 3,50).

p_surchargenumber

Acréscimo percentual (2.5 = 2,5%).

tax_idsstring

Sempre vazio.

usergroup_idsstring

Ids de grupos de usuários que podem usar a forma, separados por vírgula. Vazio para todos.

venddor_processor_typestring

onlineofflineinvoiced

Tipo real de processamento.

paramsobject

page, items_per_page e total_items.

Erros

Status	Quando	Corpo
400	Corpo que não é JSON	`{"message":"invalid request body","status":400}`
400	Falta `payment` na criação	`{"message":"payment name is required","status":400}`
400	Dados rejeitados (por exemplo, planos de parcelas inválidos em `invoiced`)	`{"message":"...","status":400}`
401	Sem credenciais	`{"message":"Authentication required. Use HTTP Basic with email:api_key or Bearer <jwt>.","status":401}`
403	Usuário que não é administrador	`{"message":"Forbidden: admin scope required","status":403}`
404	Forma inexistente	`{"message":"payment method not found","status":404}`