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.
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_...
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 |
