Gateways

Gateways disponíveis

Gateway	Slug	Cartão	PIX	Split
Pagarme	`pagarme`	✓	✓	✓
Safe2Pay	`safe2pay`	✓	✓	—
PicPay	`picpay`	—	✓	—

Lógica de roteamento

A PlugToPay seleciona o gateway em três etapas, na seguinte ordem de prioridade:

process_on_gateway no body da requisição — força um gateway específico naquela transação.
priority_gateway na CompanyConfig — gateway padrão configurado para a empresa.
Pagarme como fallback — usado quando nenhuma preferência está definida.

Não existe engine de regras dinâmicas no momento — o roteamento é determinístico pelas três etapas acima. Regras baseadas em BIN, valor, método de pagamento ou horário são escopo futuro (ver ADR 0003).

Fallback automático

Quando uma tentativa falha em um gateway, o orquestrador tenta o próximo gateway ativo configurado para a empresa, até o limite de max_retry_attempt na CompanyConfig. Cada tentativa fica registrada em transactions[] no PaymentResource.

Configurar credenciais

Registre as credenciais de cada gateway que deseja usar:

PUT /api/v1/user/company/gateways
Authorization: Bearer eyJ...
Content-Type: application/json

{
  "gateway_slug": "pagarme",
  "api_key": "ak_live_..."
}

As credenciais são armazenadas criptografadas e nunca retornadas nas respostas da API. Para rotacionar uma chave, faça um novo PUT com o valor atualizado.

Listar gateways conectados

GET /api/v1/user/gateways
Authorization: Bearer eyJ...

{
  "data": [
    { "id": 1, "name": "Pagarme", "slug": "pagarme", "description": null, "has_split": true },
    { "id": 2, "name": "Safe2Pay", "slug": "safe2pay", "description": null, "has_split": false }
  ]
}