Início Rápido

Siga este guia passo a passo para realizar sua primeira cobrança PIX em produção.

🚧

Pré-requisito obrigatório

Sua empresa precisa ter o KYC aprovado no Dashboard da Legacy antes de utilizar a API. Sem essa aprovação, todas as requisições retornarão 403 Forbidden.

1. Obtenha suas chaves de API

Acesse o Dashboard da Legacy e navegue até a seção Integrações. Lá você pode gerar seu par de chaves de acesso à produção:

❗

Guarde sua Secret Key com segurança

A sk_live_... é exibida apenas uma vez no momento da criação. Armazene-a em um cofre de segredos (como AWS Secrets Manager ou HashiCorp Vault) e nunca a exponha em código-fonte ou repositórios.

2. Autentique-se na API

Todas as requisições utilizam HTTP Basic Auth. Combine sua Public Key e Secret Key separadas por :, codifique em Base64 e envie no cabeçalho Authorization:

Authorization: Basic base64(pk_live_xxxx:sk_live_yyyy)

Exemplo em Node.js:

const publicKey = 'pk_live_xxxxxx';
const secretKey = 'sk_live_yyyyyy';
const credentials = Buffer.from(`${publicKey}:${secretKey}`).toString('base64');

// Use em todas as requisições:
headers: { Authorization: `Basic ${credentials}` }

Veja o guia completo de Autenticação para exemplos em PHP e Python.

3. Crie sua primeira cobrança PIX

Envie uma requisição POST /payin com o método PIX. O campo amount deve estar em centavos — para R$100,00, envie 10000.

POST /payin HTTP/1.1
Host: api.holdinglegacy.io
Content-Type: application/json
Authorization: Basic base64(pk_live_xxxx:sk_live_yyyy)

{
  "paymentMethod": "PIX",
  "amount": 10000,
  "referenceId": "pedido-001",
  "webhookUrl": "https://sua-api.com/webhooks/legacy",
  "isPhysicalProduct": false,
  "payerIp": "200.100.50.3",
  "customer": {
    "name": "Maria Silva",
    "document": "83416281085",
    "email": "[email protected]",
    "phone": "5511999999999",
    "address": {
      "street": "Rua Exemplo",
      "number": "123",
      "zipCode": "01000-000",
      "city": "São Paulo",
      "state": "SP"
    }
  },
  "items": [
    {
      "title": "Produto Exemplo",
      "quantity": 1,
      "unitPrice": 10000
    }
  ]
}

4. Interprete a resposta

A API retorna 201 Created com o QR Code e o código PIX Copia e Cola:

{
  "id": "payin_1A2B3C",
  "externalId": "tx_998877",
  "referenceId": "pedido-001",
  "status": "PENDING",
  "amount": 10000,
  "paymentMethod": "PIX",
  "createdAt": "2026-03-02T12:00:00.000Z",
  "pix": {
    "qrcode": "00020101021126360014br.gov.bcb.pix0114+5511999999999..."
  }
}

Exiba o campo pix.qrcode para o seu cliente como QR Code ou como texto Copia e Cola.

5. Receba a confirmação de pagamento

Quando o PIX for pago pelo cliente, a Legacy enviará um evento POST para a webhookUrl informada:

{
  "id": "payin_1A2B3C",
  "status": "APPROVED",
  "paymentMethod": "PIX",
  "amount": 10000,
  "referenceId": "pedido-001",
  "customer": {
    "name": "Maria Silva",
    "email": "[email protected]"
  },
  "updatedAt": "2026-03-02T12:05:00.000Z"
}

👍

Seu endpoint de webhook deve responder com qualquer status 2xx

Se a sua URL retornar erro, a Legacy tentará reenviar em intervalos crescentes. Consulte o guia de Webhooks para mais detalhes sobre a política de reenvio.

Próximos passos

• Autenticação — entenda os dois métodos de autenticação disponíveis
• Criar Payin — referência completa com Boleto e Cartão de Crédito
• Criar Payout — realize saques do seu saldo via PIX
• Webhooks — configure notificações em tempo real