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

Configuração do PIX

Define a chave, o recebedor, o provedor de confirmação e a validade do QR Code do PIX da loja.

PIX é o meio de pagamento instantâneo do Banco Central do Brasil. Para vender com PIX a loja precisa dizer qual chave recebe, quem é o recebedor e quem confirma que o dinheiro entrou (o próprio banco via webhook, ou um gateway como Pagar.me).

Consultar configuração

Devolve a configuração de PIX da loja. O segredo do webhook nunca é devolvido por inteiro.

GET/api/v1/admin/pix/configAdmin

Consulta a configuração do PIX da loja

Autenticação: Authorization: Bearer <token> de um administrador com view_payments ou manage_payments. Requer o módulo pix-payments ativo. Atenção: a gravação (PUT) aceita os dois privilégios, inclusive view_payments.

Sem parâmetros.

Exemplo de requisição

Resposta

200Configuração devolvida

Campos da resposta

idinteger
Sempre 1: há uma única configuração por loja.
pix_keystring
Chave PIX que recebe (CPF, CNPJ, e-mail, telefone ou chave aleatória).
merchant_namestring
Nome do recebedor mostrado no pagamento.
merchant_citystring
Cidade do recebedor mostrada no pagamento.
webhook_secretstring
Segredo do webhook de confirmação, mascarado: **** e os 4 últimos caracteres. Vazio se não houver.
providerstring
localpagarmegetneta27
Quem confirma os pagamentos: local, pagarme, getnet ou a27.
enabledboolean
Se o PIX está ligado.
expiry_minutesinteger
Quanto tempo o QR Code vale, em minutos (5 a 43200).
warningsarray
Avisos não bloqueantes. webhook_secret_missing: o PIX está ligado sem segredo de webhook.
created_atstring
Criação, RFC 3339 em UTC.
updated_atstring
Última alteração.

Erros

StatusQuandoCorpo
401Sem token ou token inválido{"error":"missing authorization header"}
403Sem o privilégio exigido, ou módulo desligado{"error":"module_disabled","module":"pix-payments"} / {"error":"insufficient privileges","required":"manage_payments"}
500Falha ao ler{"error":"failed to retrieve pix configuration"}

Gravar configuração

Altera a configuração do PIX. É uma alteração parcial: só os campos enviados mudam. Um corpo {} não apaga as credenciais.

PUT/api/v1/admin/pix/configAdmin

Grava a configuração do PIX da loja

Autenticação: Authorization: Bearer <token> de um administrador com view_payments ou manage_payments. Requer o módulo pix-payments ativo. Atenção: a gravação (PUT) aceita os dois privilégios, inclusive view_payments.

Corpo da requisição

pix_keystring
Chave PIX que recebe.
merchant_namestring
Nome do recebedor.
merchant_citystring
Cidade do recebedor.
webhook_secretstring
Segredo do webhook. Um valor que começa com * é tratado como "não mudou" (é o que a leitura devolve mascarado), então reenviar o que você leu não apaga o segredo.
providerstring
localpagarmegetneta27
local, pagarme, getnet ou a27. Não é validado: um valor desconhecido é gravado do mesmo jeito.
enabledboolean
Liga ou desliga o PIX.
expiry_minutesinteger
Validade do QR Code, de 5 a 43200 minutos.

Exemplo de requisição

Resposta

200Configuração gravada

Campos da resposta

idinteger
Sempre 1: há uma única configuração por loja.
pix_keystring
Chave PIX que recebe (CPF, CNPJ, e-mail, telefone ou chave aleatória).
merchant_namestring
Nome do recebedor mostrado no pagamento.
merchant_citystring
Cidade do recebedor mostrada no pagamento.
webhook_secretstring
Segredo do webhook de confirmação, mascarado: **** e os 4 últimos caracteres. Vazio se não houver.
providerstring
localpagarmegetneta27
Quem confirma os pagamentos: local, pagarme, getnet ou a27.
enabledboolean
Se o PIX está ligado.
expiry_minutesinteger
Quanto tempo o QR Code vale, em minutos (5 a 43200).
warningsarray
Avisos não bloqueantes. webhook_secret_missing: o PIX está ligado sem segredo de webhook.
created_atstring
Criação, RFC 3339 em UTC.
updated_atstring
Última alteração.

Erros

StatusQuandoCorpo
401Sem token ou token inválido{"error":"missing authorization header"}
403Sem o privilégio exigido, ou módulo desligado{"error":"module_disabled","module":"pix-payments"} / {"error":"insufficient privileges","required":"manage_payments"}
400Corpo inválido ou expiry_minutes fora de 5 a 43200{"error":"expiry_minutes must be between 5 and 43200"}
500Falha ao gravar{"error":"failed to update pix configuration"}
PIX ligado sem segredo de webhook derruba pedidos

Com o provedor local, a plataforma só aceita a confirmação de pagamento que traga o segredo. Se o PIX está enabled e o segredo está vazio, nenhum pagamento é confirmado e, passado o prazo, os pedidos são cancelados. Para provedores externos, sem segredo o endpoint de confirmação fica sem autenticação. Por isso a resposta traz webhook_secret_missing em warnings.

Veja também

  • Transações e estornos
Anterior
Taxas de gateway
Próxima
Disputas
Nesta página
  • Consultar configuração
  • Exemplo de requisição
  • Resposta
  • Erros
  • Gravar configuração
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também
bash
curl "$BASE_URL/api/v1/admin/pix/config" \
  -H "Authorization: Bearer $TOKEN"
bash
curl -X PUT "$BASE_URL/api/v1/admin/pix/config" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "pix_key": "pagamentos@minhaloja.example.com",
    "merchant_name": "MINHA LOJA LTDA",
    "merchant_city": "SAO PAULO",
    "enabled": true,
    "expiry_minutes": 30
  }'
json
{
  "id": 1,
  "pix_key": "pagamentos@minhaloja.example.com",
  "merchant_name": "MINHA LOJA LTDA",
  "merchant_city": "SAO PAULO",
  "webhook_secret": "****9f2a",
  "provider": "local",
  "enabled": true,
  "expiry_minutes": 30,
  "warnings": [],
  "created_at": "2026-05-27T12:07:27.72681Z",
  "updated_at": "2026-07-20T09:20:55.188676Z"
}
json
{
  "id": 1,
  "pix_key": "pagamentos@minhaloja.example.com",
  "merchant_name": "MINHA LOJA LTDA",
  "merchant_city": "SAO PAULO",
  "webhook_secret": "****9f2a",
  "provider": "local",
  "enabled": true,
  "expiry_minutes": 30,
  "warnings": [],
  "created_at": "2026-05-27T12:07:27.72681Z",
  "updated_at": "2026-07-20T09:20:55.188676Z"
}