C6 Pix — Setup Operacional | Valmor Nascimento

C6 Pix — Setup Operacional

Configuração do C6 Bank como provedor Pix da loja via OAuth2 e mTLS no Cloudflare Workers.

Este runbook configura o C6 Bank como provedor Pix da loja. O fluxo usa OAuth2 client_credentials com mTLS: o certificado .crt/.key baixado no onboarding do C6 precisa ser enviado para a Cloudflare e exposto no worker pelo binding C6_MTLS.

Não coloque valores reais de secret em wrangler.toml ou no repositório.

1. Onboarding no portal C6

Acesse o Web Banking PJ do C6 e habilite a API Pix.
Gere as credenciais da aplicação:
- client_id
- client_secret
Anote a base URL real da API Pix (C6_API_BASE). Ela aparece na tela de credenciais do Web Banking PJ, no mesmo lugar do certificado e das credenciais, ou no e-mail de credenciamento. O portal developers.c6bank.com.br, após login, também mostra as bases; sandbox e produção têm URLs distintas.
Baixe o pacote de certificado do onboarding. O .zip deve conter, no mínimo:
- certificado cliente .crt
- chave privada .key
Guarde os arquivos em uma pasta local fora do repositório. O certificado do C6 tem validade de 12 meses; agende a renovação antes do vencimento.

2. Subir o certificado mTLS na Cloudflare

Rode o upload usando os arquivos baixados do C6:

npx wrangler mtls-certificate upload --cert c6.crt --key c6.key --name c6-pix

O comando retorna um certificate_id. No wrangler.toml, descomente o bloco de mTLS no final do arquivo e substitua o placeholder pelo id retornado:

[[mtls_certificates]]
binding = "C6_MTLS"
certificate_id = "<CERTIFICATE_ID retornado no upload>"

O nome do binding precisa continuar C6_MTLS, porque o código chama as APIs C6 por env.C6_MTLS.fetch().

3. Configurar secrets no Cloudflare Pages

Configure todos os valores pelo Wrangler. Cole cada valor quando o comando solicitar:

npx wrangler pages secret put C6_CLIENT_ID --project-name=webapp
npx wrangler pages secret put C6_CLIENT_SECRET --project-name=webapp
npx wrangler pages secret put C6_PIX_KEY --project-name=webapp
npx wrangler pages secret put C6_WEBHOOK_TOKEN --project-name=webapp
npx wrangler pages secret put C6_API_BASE --project-name=webapp

Secrets opcionais:

npx wrangler pages secret put C6_OAUTH_TOKEN_PATH  --project-name=webapp
npx wrangler pages secret put C6_OAUTH_SCOPE       --project-name=webapp
npx wrangler pages secret put C6_OAUTH_AUTH_STYLE  --project-name=webapp
npx wrangler pages secret put C6_ENV               --project-name=webapp
npx wrangler pages secret put PIX_PROVIDER         --project-name=webapp

C6_OAUTH_SCOPE sobrescreve o scope enviado no token; use none para omitir o parâmetro scope (alguns endpoints de sandbox rejeitam scopes desconhecidos). C6_OAUTH_AUTH_STYLE aceita basic (default, header Basic Auth) ou body (envia client_id/client_secret no corpo) — ajuste conforme o portal do C6.

C6_API_BASE é obrigatório: sem ele o provedor C6 deve ser pulado, porque o host/base URL não é público e vem do credenciamento da conta. Use C6_OAUTH_TOKEN_PATH só se o portal C6 indicar um path de token diferente; o default esperado é /oauth/token. Use C6_ENV como sandbox ou production, quando o backend estiver preparado para diferenciar os ambientes.

4. Registrar o webhook no C6

Registre o webhook da chave Pix da conta PJ com PUT /webhook/{chave-pix} no ambiente C6 correto. A URL pública deve apontar para:

https://valmor.net.br/api/payments/c6-webhook/<C6_WEBHOOK_TOKEN>

O valor de C6_WEBHOOK_TOKEN vira um segmento secreto do path. Use um token longo, aleatório e diferente das demais credenciais. O backend não deve confiar no corpo da notificação: ao receber o webhook, ele consulta novamente a cobrança no C6 por mTLS.

5. Alternar provedor Pix

PIX_PROVIDER seleciona explicitamente o provedor sem mudança de código:

c6
mercadopago
static

Para trocar, atualize o secret no Cloudflare Pages:

npx wrangler pages secret put PIX_PROVIDER --project-name=webapp

Quando PIX_PROVIDER não estiver definido, a aplicação usa autodetecção na ordem C6, Mercado Pago e Pix estático, conforme os secrets e bindings disponíveis. Atualizar um secret no Pages muda a configuração operacional sem redeploy de código, mas chamadas que já estejam em execução podem continuar com a configuração antiga por alguns instantes.

6. Desenvolvimento local e sandbox

O sandbox de homologação do C6 não usa mTLS (e não segue OAuth2 à risca). Por isso, com C6_ENV=sandbox o provedor C6 dispensa o binding C6_MTLS e roda no astro dev comum. Crie um .dev.vars com as credenciais de sandbox:

# .dev.vars (NÃO commitar)
C6_ENV=sandbox
PIX_PROVIDER=c6
C6_CLIENT_ID=...
C6_CLIENT_SECRET=...
C6_PIX_KEY=...
C6_API_BASE=https://<base-url-sandbox-do-portal>   # pegar no portal, não é público
# C6_OAUTH_TOKEN_PATH=/oauth/token   # se o portal indicar outro path
# C6_OAUTH_SCOPE=none                # se o sandbox rejeitar scopes
# C6_OAUTH_AUTH_STYLE=body           # se o token exigir creds no corpo

Lembre que o sandbox do C6 só responde de segunda a sexta, das 7h às 23h; fora disso as chamadas falham e o checkout cai no Pix estático (fail-open).

O binding mTLS da Cloudflare só funciona em produção/preview remoto. Em dev local normal (sem C6_ENV=sandbox), C6_MTLS fica undefined e o provedor C6 é tratado como não configurado, caindo para o próximo provedor.

Para validar o caminho de produção com mTLS fora de produção, use preview/remoto:

npx wrangler pages dev dist --remote

7. Checklist de validação

Faça deploy/preview com C6_MTLS configurado e secrets C6 ativos.
Crie um pedido de valor baixo.
Confirme em payment_metadata que pix_provider ficou como c6.
Pague o Pix de teste.
Verifique se o webhook confirma o pedido como pago.
Reabra a página do pedido e confirme que o polling ativo também reconcilia o status como rede de segurança.
Valide que, sem C6_MTLS em dev local, o C6 não quebra o checkout e a aplicação usa o próximo provedor configurado.