Configuração do Pagar.me

Lê e grava as chaves e o ambiente do gateway, e testa se a chave de API autentica.

A configuração guarda as credenciais da conta Pagar.me da loja e liga ou desliga o gateway. Cada loja tem a sua. Exigem o módulo pagarme e o privilégio manage_payments ou view_payments.

Ler a configuração

Devolve a configuração salva. As chaves secretas voltam mascaradas: só os 4 últimos caracteres aparecem (****c73a). Uma loja que nunca salvou nada recebe os valores de ambiente da plataforma, com sandbox: true.

GET/api/v1/admin/pagarme/configAdmin

Lê a configuração do Pagar.me

Exemplo de requisição

bash

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

Resposta

200Configuração devolvida

json

{
  "id": 1,
  "api_key": "****c73a",
  "public_key": "pk_test_xxxxxxxxxxxxxxxx",
  "secret_key": "****9f2d",
  "api_base_url": "https://api.pagar.me/core/v5/",
  "marketplace_recipient_id": "re_cm0exampleexampleexample0",
  "sandbox": true,
  "enabled": true,
  "created_at": "2026-05-25T19:09:38Z",
  "updated_at": "2026-10-01T22:28:34Z"
}

Campos da resposta

idinteger

Identificador do registro (a loja tem um só).

api_keystring

Chave secreta da API (sk_...), mascarada.

public_keystring

Chave pública (pk_...), usada pelo navegador para tokenizar o cartão. Não é segredo e vem inteira.

secret_keystring

Segredo de assinatura dos webhooks, mascarado.

api_base_urlstring

Endereço da API do gateway. Vazio usa o padrão do Pagar.me v5.

marketplace_recipient_idstring

Recebedor (re_...) da loja, que fica com a comissão no split. Vazio quando a loja não usa split.

sandboxboolean

true para o ambiente de testes.

enabledboolean

Se o gateway está ligado para o checkout.

created_atstring

Criação, RFC 3339.

updated_atstring

Última alteração, RFC 3339.

Erros

Status	Quando	Corpo
401	Sem token	`{"error":"missing authorization header"}`
403	Sem privilégio	`{"error":"insufficient privileges","privilege_required_any":["manage_payments","view_payments"]}`
403	Módulo desligado	`{"error":"module_disabled","module":"pagarme"}`
500	Falha ao ler	`{"error":"failed to retrieve pagarme configuration","detail":"..."}`

Gravar a configuração

Altera só os campos enviados; os ausentes mantêm o valor salvo. Um segredo que começa com * é tratado como "mantenha o atual": reenviar o valor mascarado que você leu no GET é seguro e não apaga a chave.

PUT/api/v1/admin/pagarme/configAdmin

Grava a configuração do Pagar.me

Corpo da requisição

api_keystring

Chave secreta da API (sk_live_... em produção, sk_test_... em testes). Mascarada ou ausente mantém a atual.

public_keystring

Chave pública (pk_...).

secret_keystring

Segredo dos webhooks. Mascarado ou ausente mantém o atual.

api_base_urlstring

Endereço da API. Normalmente não precisa mudar.

marketplace_recipient_idstring

Recebedor da loja para a comissão do split.

sandboxboolean

Ambiente de testes.

enabledboolean

Liga ou desliga o gateway no checkout.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/pagarme/config" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "sk_test_exemplo0000000000000000",
    "public_key": "pk_test_exemplo0000000000",
    "marketplace_recipient_id": "re_cm0exampleexampleexample0",
    "sandbox": true,
    "enabled": true
  }'

Resposta

200Configuração gravada

json

{
  "id": 1,
  "api_key": "sk_test_exemplo0000000000000000",
  "public_key": "pk_test_exemplo0000000000",
  "secret_key": "whsec_exemplo",
  "api_base_url": "https://api.pagar.me/core/v5/",
  "marketplace_recipient_id": "re_cm0exampleexampleexample0",
  "sandbox": true,
  "enabled": true,
  "created_at": "2026-05-25T19:09:38Z",
  "updated_at": "2026-10-11T22:50:00Z"
}

Os campos são os do GET, mas, ao contrário dele, sem máscara.

Erros

Status	Quando	Corpo
400	JSON inválido	`{"error":"invalid request body","detail":"..."}`
500	Falha ao gravar	`{"error":"failed to update pagarme configuration","detail":"..."}`

Testar a conexão

Faz uma chamada leve e autenticada ao gateway (lista no máximo 1 recebedor) para confirmar que a chave funciona. Sem corpo, testa a chave salva; com api_key, testa uma chave nova antes de salvá-la.

POST/api/v1/admin/pagarme/test-connectionAdmin

Testa a chave de API do Pagar.me

Corpo da requisição (opcional)

api_keystring

Chave a testar. Ausente, vazia ou mascarada (****...) usa a chave salva.

sandboxboolean

Aceito por compatibilidade, mas ignorado: o ambiente vem da configuração salva.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/pagarme/test-connection" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "api_key": "sk_test_exemplo0000000000000000" }'

Resposta

200Credenciais válidas

json

{ "success": true, "message": "pagarme credentials are valid" }

Erros

Status	Quando	Corpo
502	Chave recusada pelo gateway	`{"error":"pagarme connection test failed","detail":"pagarme: invalid credentials (HTTP 401)"}`
502	Nenhuma chave salva nem enviada	`{"error":"pagarme connection test failed","detail":"pagarme: no API key configured"}`
502	Gateway fora do ar ou resposta inesperada	`{"error":"pagarme connection test failed","detail":"pagarme: connection failed: ..."}`

Veja também

API atual/Referência completa/Pagar.me

Configuração do Pagar.me

Lê e grava as chaves e o ambiente do gateway, e testa se a chave de API autentica.

A configuração guarda as credenciais da conta Pagar.me da loja e liga ou desliga o gateway. Cada loja tem a sua. Exigem o módulo pagarme e o privilégio manage_payments ou view_payments.

Ler a configuração

GET/api/v1/admin/pagarme/configAdmin

Lê a configuração do Pagar.me

Exemplo de requisição

bash

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

Resposta

200Configuração devolvida

json

{
  "id": 1,
  "api_key": "****c73a",
  "public_key": "pk_test_xxxxxxxxxxxxxxxx",
  "secret_key": "****9f2d",
  "api_base_url": "https://api.pagar.me/core/v5/",
  "marketplace_recipient_id": "re_cm0exampleexampleexample0",
  "sandbox": true,
  "enabled": true,
  "created_at": "2026-05-25T19:09:38Z",
  "updated_at": "2026-10-01T22:28:34Z"
}

Campos da resposta

idinteger

Identificador do registro (a loja tem um só).

api_keystring

Chave secreta da API (sk_...), mascarada.

public_keystring

Chave pública (pk_...), usada pelo navegador para tokenizar o cartão. Não é segredo e vem inteira.

secret_keystring

Segredo de assinatura dos webhooks, mascarado.

api_base_urlstring

Endereço da API do gateway. Vazio usa o padrão do Pagar.me v5.

marketplace_recipient_idstring

Recebedor (re_...) da loja, que fica com a comissão no split. Vazio quando a loja não usa split.

sandboxboolean

true para o ambiente de testes.

enabledboolean

Se o gateway está ligado para o checkout.

created_atstring

Criação, RFC 3339.

updated_atstring

Última alteração, RFC 3339.

Erros

Status	Quando	Corpo
401	Sem token	`{"error":"missing authorization header"}`
403	Sem privilégio	`{"error":"insufficient privileges","privilege_required_any":["manage_payments","view_payments"]}`
403	Módulo desligado	`{"error":"module_disabled","module":"pagarme"}`
500	Falha ao ler	`{"error":"failed to retrieve pagarme configuration","detail":"..."}`

Gravar a configuração

PUT/api/v1/admin/pagarme/configAdmin

Grava a configuração do Pagar.me

Corpo da requisição

api_keystring

Chave secreta da API (sk_live_... em produção, sk_test_... em testes). Mascarada ou ausente mantém a atual.

public_keystring

Chave pública (pk_...).

secret_keystring

Segredo dos webhooks. Mascarado ou ausente mantém o atual.

api_base_urlstring

Endereço da API. Normalmente não precisa mudar.

marketplace_recipient_idstring

Recebedor da loja para a comissão do split.

sandboxboolean

Ambiente de testes.

enabledboolean

Liga ou desliga o gateway no checkout.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/pagarme/config" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "sk_test_exemplo0000000000000000",
    "public_key": "pk_test_exemplo0000000000",
    "marketplace_recipient_id": "re_cm0exampleexampleexample0",
    "sandbox": true,
    "enabled": true
  }'

Resposta

200Configuração gravada

json

{
  "id": 1,
  "api_key": "sk_test_exemplo0000000000000000",
  "public_key": "pk_test_exemplo0000000000",
  "secret_key": "whsec_exemplo",
  "api_base_url": "https://api.pagar.me/core/v5/",
  "marketplace_recipient_id": "re_cm0exampleexampleexample0",
  "sandbox": true,
  "enabled": true,
  "created_at": "2026-05-25T19:09:38Z",
  "updated_at": "2026-10-11T22:50:00Z"
}

Os campos são os do GET, mas, ao contrário dele, sem máscara.

Erros

Status	Quando	Corpo
400	JSON inválido	`{"error":"invalid request body","detail":"..."}`
500	Falha ao gravar	`{"error":"failed to update pagarme configuration","detail":"..."}`

Testar a conexão

POST/api/v1/admin/pagarme/test-connectionAdmin

Testa a chave de API do Pagar.me

Corpo da requisição (opcional)

api_keystring

Chave a testar. Ausente, vazia ou mascarada (****...) usa a chave salva.

sandboxboolean

Aceito por compatibilidade, mas ignorado: o ambiente vem da configuração salva.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/pagarme/test-connection" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "api_key": "sk_test_exemplo0000000000000000" }'

Resposta

200Credenciais válidas

json

{ "success": true, "message": "pagarme credentials are valid" }

Erros

Status	Quando	Corpo
502	Chave recusada pelo gateway	`{"error":"pagarme connection test failed","detail":"pagarme: invalid credentials (HTTP 401)"}`
502	Nenhuma chave salva nem enviada	`{"error":"pagarme connection test failed","detail":"pagarme: no API key configured"}`
502	Gateway fora do ar ou resposta inesperada	`{"error":"pagarme connection test failed","detail":"pagarme: connection failed: ..."}`