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

bash

curl "$BASE_URL/api/v1/admin/pix/config" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Configuração devolvida

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"
}

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

Status	Quando	Corpo
401	Sem token ou token inválido	`{"error":"missing authorization header"}`
403	Sem o privilégio exigido, ou módulo desligado	`{"error":"module_disabled","module":"pix-payments"}` / `{"error":"insufficient privileges","required":"manage_payments"}`
500	Falha 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

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

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
  }'

Resposta

200Configuração gravada

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"
}

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

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

Veja também

Transações e estornos

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.

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

Sem parâmetros.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/pix/config" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Configuração devolvida

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"
}

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

Status	Quando	Corpo
401	Sem token ou token inválido	`{"error":"missing authorization header"}`
403	Sem o privilégio exigido, ou módulo desligado	`{"error":"module_disabled","module":"pix-payments"}` / `{"error":"insufficient privileges","required":"manage_payments"}`
500	Falha 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

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

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
  }'

Resposta

200Configuração gravada

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"
}

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

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

Veja também

Transações e estornos