Gateways da Empresa

Visão geral

Cada empresa precisa cadastrar as credenciais dos gateways que deseja usar. Somente gateways com credenciais válidas e habilitados participam do roteamento de pagamentos. Os endpoints de escrita (PUT, PATCH) aceitam X-Client-ID + X-API-Key. A listagem está disponível via painel com Bearer JWT.

Adicionar ou atualizar credenciais

PUT /api/v1/company/gateways — requer X-Client-ID + X-API-Key. Envia um array de gateways. Gateways já cadastrados são atualizados; novos são criados. A operação é idempotente.

PUT /api/v1/company/gateways
Content-Type: application/json
X-Client-ID: client_...
X-API-Key: sk_...

{
  "gateways": [
    {
      "gateway_slug": "pagarme",
      "secret_key": "ak_live_abc123...",
      "client_id": "client_xyz",
      "sandbox_secret_key": "ak_test_...",
      "sandbox_client_id": "sandbox_xyz",
      "order": 1
    },
    {
      "gateway_slug": "safe2pay",
      "secret_key": "sk_live_xyz...",
      "order": 2
    }
  ]
}

Campo	Tipo	Obrigatório	Descrição
`gateway_slug`	string	sim	Identificador do gateway — veja a tabela de gateways
`secret_key`	string (max 500)	sim	Chave secreta de produção
`client_id`	string (max 255)	não	Client ID exigido por alguns gateways (ex: Pagarme)
`sandbox_secret_key`	string (max 500)	não	Chave de sandbox para testes
`sandbox_client_id`	string (max 500)	não	Client ID de sandbox
`order`	inteiro (≥ 1)	não	Prioridade no roteamento por ordem. Se omitido, é atribuído sequencialmente

As chaves secretas são armazenadas criptografadas. Nas respostas da API, apenas os 4 últimos caracteres são exibidos — o restante é mascarado com *. Para rotacionar uma credencial, envie um novo PUT com o valor atualizado.

Resposta 200:

{
  "data": [
    {
      "id": 1,
      "client_id": "client_xyz",
      "secret_key": "************a1b2",
      "sandbox_secret_key": null,
      "is_subaccount": false,
      "enabled": true,
      "order": 1,
      "gateway": {
        "id": 1,
        "name": "Pagarme",
        "slug": "pagarme",
        "has_split": true,
        "is_active": true
      }
    }
  ]
}

Listar gateways configurados

GET /api/v1/user/company/gateways — requer Bearer JWT. Retorna todos os gateways cadastrados para a empresa autenticada, com status de habilitação e ordem atual.

{
  "data": [
    {
      "id": 1,
      "client_id": "client_xyz",
      "secret_key": "************a1b2",
      "sandbox_secret_key": null,
      "is_subaccount": false,
      "enabled": true,
      "order": 1,
      "gateway": {
        "id": 1,
        "name": "Pagarme",
        "slug": "pagarme",
        "has_split": true,
        "is_active": true
      }
    },
    {
      "id": 2,
      "client_id": null,
      "secret_key": "************z9y8",
      "sandbox_secret_key": null,
      "is_subaccount": false,
      "enabled": true,
      "order": 2,
      "gateway": {
        "id": 4,
        "name": "Safe2Pay",
        "slug": "safe2pay",
        "has_split": false,
        "is_active": true
      }
    }
  ]
}

Campo	Descrição
`enabled`	Se `false`, o gateway não participa do roteamento
`order`	Ordem de prioridade no fallback — menor valor = maior prioridade
`gateway.has_split`	Se `true`, o gateway suporta split de pagamento
`gateway.is_active`	Se `false`, o gateway foi desativado globalmente pela PlugToPay

Habilitar ou desabilitar gateway

PATCH /api/v1/company/gateways/{slug} — requer X-Client-ID + X-API-Key. Alterna o campo enabled do gateway. Corpo vazio.

PATCH /api/v1/company/gateways/safe2pay
X-Client-ID: client_...
X-API-Key: sk_...

Quando enabled: false:

O gateway é excluído do roteamento automático (ordem e percentual)
As credenciais permanecem armazenadas
O gateway pode ser reativado a qualquer momento

Gateways disponíveis

Gateway	Slug	Cartão	PIX	Split
Pagarme	`pagarme`	✓	✓	✓
Stripe	`stripe`	✓	—	—
Safe2Pay	`safe2pay`	✓	✓	—
PagBank	`pagbank`	✓	✓	✓
Asaas	`asaas`	✓	—	—
eRede	`erede`	✓	—	—

Referência rápida de rotas

Método	Rota	Auth	Descrição
`PUT`	`/api/v1/company/gateways`	`X-Client-ID` + `X-API-Key`	Adicionar/atualizar credenciais
`GET`	`/api/v1/user/company/gateways`	`Bearer JWT`	Listar gateways configurados
`PATCH`	`/api/v1/company/gateways/{slug}`	`X-Client-ID` + `X-API-Key`	Habilitar/desabilitar gateway

Introdução

Conceitos principais

Orquestração

Pagamentos

Assinaturas

Recursos

Gateways da Empresa

Visão geral

Adicionar ou atualizar credenciais

Listar gateways configurados

Habilitar ou desabilitar gateway

Gateways disponíveis

Referência rápida de rotas

​Visão geral

​Adicionar ou atualizar credenciais

​Listar gateways configurados

​Habilitar ou desabilitar gateway

​Gateways disponíveis

​Referência rápida de rotas

Visão geral

Adicionar ou atualizar credenciais

Listar gateways configurados

Habilitar ou desabilitar gateway

Gateways disponíveis

Referência rápida de rotas