Primeiros passos

Da conta até a primeira cobrança, em 5 etapas.

1. Crie sua conta

POST /v1/tenants cria o tenant e o primeiro usuário admin em uma única operação. 

curl -X POST https://api.paygrid.tech/v1/tenants \
  -H "Content-Type: application/json" \
  -d '{
    "business_name": "Minha Loja LTDA",
    "document": "12345678000199",
    "admin_name": "João",
    "admin_email": "joao@loja.com",
    "admin_password": "senha-forte"
  }'

Resposta: 201 com tenantId, adminId e adminEmail.

2. Autentique-se

A API aceita três fontes de credencial (a de maior prioridade vence):

CredencialUsoHeader
Chave de APIServidor-a-servidorX-Api-Key: sk_…
JWTSDKs / backendAuthorization: Bearer <jwt>
Cookie de sessãoDashboardsession (HttpOnly)
Para integração servidor-a-servidor, gere uma chave de API: POST /v1/api-keys. Use o X-Api-Key em todas as chamadas.

3. Configure um fluxo

O fluxo define o caminho da cobrança. Você pode criar um no painel (menu Fluxos) arrastando cards, ou via POST /v1/workflows. O template padrão é: cobrança → (aprovado | recusado).

4. Registre a conta do provedor

Cadastre a subconta do gateway que processa o pagamento: POST /v1/providers/accounts com a credencial do provedor.

5. Crie sua primeira cobrança

Exemplo com Pix:

curl -X POST https://api.paygrid.tech/v1/transactions \
  -H "X-Api-Key: sk_sua_chave" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-4211" \
  -d '{
    "workflowId": "22222222-2222-2222-2222-222222222222",
    "paymentMethod": "pix",
    "amount": 1990,
    "currency": "BRL",
    "reference": "pedido-4211",
    "customer": {
      "name": "João da Silva",
      "document": "12345678900",
      "phone": "+5511999999999"
    }
  }'
Pix exige pagador completo (nome, documento CPF/CNPJ e telefone) — o provedor recusa a cobrança se o documento estiver ausente.

O workflowId é obrigatório: é o id do fluxo que processa a cobrança. Pegue-o no painel (menu Fluxos) ou em GET /v1/workflows.

A resposta (202) traz transactionId, trackingId e status: "accepted" — a cobrança foi enfileirada. O QR (qrCodePix/qrCodePixUrl) sai em GET /v1/transactions/{transactionId} assim que o provedor responde. Veja o guia de Pix.

Próximos passos