Criar cobrança PIX

Use a API Aprovei para criar cobranças PIX de forma programática na loja informada pelo header X-Store-Slug.

POST

POST /v1/pix

Cria uma cobrança PIX e retorna os dados de pagamento.

https://api.aproveicheckout.com.br/v1/pix

Autenticação

A API Key precisa ter a permissão pix:create. A loja alvo é sempre definida por X-Store-Slug; o endpoint não escolhe loja automaticamente.

Headers

Authorization: Bearer SEU_TOKEN
X-Store-Slug: SLUG_DA_LOJA
Content-Type: application/json

Body

Envie dados do cliente, produtos e pagamento. Produtos físicos exigem endereço; pedidos 100% digitais podem enviar frete zerado.

JSON

{
  "customer": {
    "name": "João da Silva",
    "email": "joao@example.com",
    "document": "12345678900",
    "phone": "+5511999999999",
    "address": {
      "street": "Av. Paulista",
      "number": "1000",
      "district": "Bela Vista",
      "city": "São Paulo",
      "state": "SP",
      "zipCode": "01310100"
    }
  },
  "items": [
    {
      "externalRef": "produto-001",
      "title": "Produto Teste",
      "unitPrice": 9900,
      "quantity": 1,
      "isDigital": false
    }
  ],
  "payment": {
    "paymentMethod": "pix",
    "amount": 9900,
    "freightValue": 0,
    "discountValue": 0,
    "externalRef": "pedido-123",
    "currency": "BRL"
  },
  "postbackUrl": "https://exemplo.com/webhooks/aprovei"
}

Exemplo cURL

cURL

curl -X POST "https://api.aproveicheckout.com.br/v1/pix" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "X-Store-Slug: SLUG_DA_LOJA" \
  -H "Content-Type: application/json" \
  -d @payload.json

Resposta

200 OK

{
  "data": {
    "transactionToken": "APIA1B2C3D4",
    "externalRef": "pedido-123",
    "amount": 9900,
    "paymentMethod": "pix",
    "paymentStatus": "pending",
    "pixCopyPaste": "000201...",
    "pixQrCode": "https://..."
  },
  "message": "Transação criada com sucesso",
  "status": "success"
}

Erros principais

Código	Quando ocorre
`AUTH_MISSING_BEARER_TOKEN`	Header `Authorization: Bearer` ausente.
`AUTH_INVALID_BEARER_TOKEN`	API Key inválida ou revogada.
`AUTH_STORE_HEADER_MISSING`	Header `X-Store-Slug` ausente.
`AUTH_STORE_FORBIDDEN`	Loja sem vínculo com o dono da key ou key sem `pix:create`.
`AUTH_IP_NOT_ALLOWED`	IP fora da allowlist configurada na API Key.
`VALIDATION_ERROR`	Payload inválido ou campos obrigatórios ausentes.
`PIX_GATEWAY_NOT_CONFIGURED`	A loja não possui gateway PIX ativo para esta operação.
`STORE_NOT_READY_FOR_API_CHECKOUT`	A loja não tem plataforma ou assinatura ativa exigida para checkout via API.

Segurança

Nunca exponha sua API Key em JavaScript público, HTML, app mobile distribuído ao usuário ou repositório Git. Use a key apenas em backend, server function, edge function privada ou outro ambiente seguro.