Quick Start

Este guia segue os 6 passos pra ir de zero a uma cobrança real em produção.

1. Crie sua conta/merchant

Nesta entrega, contas são criadas por um administrador via Backoffice — não existe ainda um formulário público de "criar conta" (self-service signup). Um super_admin cria o tenant (sua empresa/plataforma) e um tenant_admin/merchant_admin cria o merchant dentro dele:

Backoffice → Merchants → Novo merchant → dê um nome.

Limitação desta entrega

Signup público self-service não existe nesta entrega — fale com quem administra sua instância do Gateway.

2. Gere uma API Key

Backoffice → Merchants → selecione o merchant → aba API Keys → Nova chave. Escolha o ambiente:

Sandbox (sk_test_...) — pra testar, com convenções determinísticas (ver Sandbox).
Produção (sk_live_...) — só depois que sua integração estiver validada.

A chave completa só aparece uma vez, na criação — guarde num secret manager, nunca no código-fonte.

3. Abra a documentação

Você já está aqui. Duas referências complementares:

Este site — guias e exemplos.
/v1/docs — Swagger UI interativo, gerado direto do código (sempre em dia com o que está de fato implantado).

4. Execute sua primeira cobrança em sandbox

Com uma chave sk_test_..., uma cobrança PIX não exige cartão nem dados sensíveis — é o jeito mais rápido de validar a integração ponta a ponta:

cURL

curl -X POST https://api.gateway.example/v1/pix/charges \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amountInCents": 5000,
    "payerDocument": "12345678900"
  }'

TypeScript

import { Gateway } from '@gateway/sdk';

const gateway = new Gateway({ apiKey: process.env.GATEWAY_API_KEY! });

const charge = await gateway.pix.create({
  amountInCents: 5000,
  payerDocument: '12345678900',
});

console.log(charge.qrCode, charge.copyPaste);

Quer testar um cartão? Use cardToken terminado em 0000 (recusado) ou 0002 (timeout) — qualquer outro valor é aprovado. Ver Sandbox pra todas as convenções.

5. Configure um webhook

Pra saber quando um PIX/boleto assíncrono é pago (sem precisar ficar consultando GET /v1/pix/charges/:id), cadastre um endpoint no Backoffice → Webhooks → Novo endpoint: informe sua URL e um secret (usado pra assinar cada entrega — ver Webhooks). Depois, inscreva-se nos eventos que te interessam (ex.: payment.paid, pix.paid).

6. Migre para produção

Gere uma chave sk_live_... (mesmo fluxo do passo 2, ambiente Produção).
Troque GATEWAY_API_KEY pela chave nova — nenhum outro código muda: os mesmos endpoints, os mesmos SDKs, a mesma forma de resposta.
As convenções de teste do sandbox (cardToken terminado em 0000/0002) nunca são interpretadas em produção — um cartão real com esses últimos dígitos é cobrado normalmente.
Confirme que seu endpoint de webhook está acessível publicamente (produção não usa localhost).

Pronto — sua integração está em produção.