> ## Documentation Index
> Fetch the complete documentation index at: https://docs.plugtopay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Gateways da Empresa

> Configure e gerencie as credenciais dos gateways de pagamento da sua 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.

```http theme={null}
PUT /api/v1/company/gateways
Content-Type: application/json
X-Client-ID: client_...
X-API-Key: sk_...
```

```json theme={null}
{
  "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](#gateways-disponíveis) |
| `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   |

<Warning>
  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.
</Warning>

**Resposta `200`:**

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```http theme={null}
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   |