Cobranças PIX

Criar uma cobrança

POST /pix — permissão payments:create — exige Idempotency-Key.

Campo	Tipo	Obrigatório	Observações
amount	inteiro	sim	Em centavos. Mínimo 100 (R$ 1,00).
customer.name	texto	sim	2 a 200 caracteres.
customer.email	texto	sim	E-mail válido.
customer.phone	texto	sim	8 a 30 caracteres.
customer.document_type	texto	sim	CPF ou CNPJ.
customer.document_value	texto	sim	11 a 20 caracteres.
description	texto	não	Até 500 caracteres.
external_id	texto	não	Seu identificador (por exemplo, o número do pedido).
product_name	texto	não	Até 120 caracteres.
delivery	objeto	não	street, number, neighborhood, city, state (2 letras), zipcode; opcional complement.

Exemplo

curl -X POST https://seventyonepay.online/api/v1/pix \
  -H "Authorization: Bearer SUA_CHAVE_DE_API" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-1001" \
  -d '{
    "amount": 1990,
    "description": "Pedido 1001",
    "external_id": "1001",
    "customer": {
      "name": "Maria Souza",
      "email": "maria@exemplo.com",
      "phone": "11999998888",
      "document_type": "CPF",
      "document_value": "12345678909"
    }
  }'

Resposta — 201 Created

{
  "success": true,
  "data": {
    "payment_id": "0b9f1c2e-0000-0000-0000-000000000001",
    "pix": {
      "id": "7a1d2c3e-0000-0000-0000-000000000002",
      "payment_id": "0b9f1c2e-0000-0000-0000-000000000001",
      "merchant_id": "5c4d3e2f-0000-0000-0000-000000000003",
      "txid": "…",
      "qr_code": "…",
      "copy_paste_code": "000201…",
      "payer_name": null,
      "payer_document": null,
      "payer_masked": true,
      "status": "waiting_payment",
      "expires_at": "2026-01-01T12:30:00.000Z",
      "paid_at": null,
      "metadata": {},
      "created_at": "2026-01-01T12:00:00.000Z",
      "updated_at": "2026-01-01T12:00:00.000Z",
      "account": { "id": "9d8c7b6a-0000-0000-0000-000000000004", "name": "Conta Principal" }
    }
  }
}

account informa a conta de processamento pela qual a cobrança foi gerada (o mesmo campo aparece em GET /pix/{id} e nos webhooks).

Exiba copy_paste_code (PIX copia e cola) e qr_code ao cliente. Guarde payment_id: é o identificador que também chega nos webhooks.

Status

Status	Significado
pending	Criada, ainda sem QR Code disponível.
waiting_payment	Aguardando o pagamento do cliente.
paid	Paga e confirmada.
expired	O prazo para pagar terminou.
cancelled	Cancelada.

paid, expired e cancelled são estados finais.

Consultar

• GET /pix/{id} — detalha uma cobrança (permissão payments:read). Não existe listagem de PIX: para listar, use GET /payments (paginação).
• GET /pix/payment/{paymentId} — encontra a cobrança a partir do payment_id.
• GET /pix/{id}/events — histórico de mudanças de status.

Cancelar e sincronizar

• POST /pix/{id}/cancel — cancela uma cobrança que ainda não foi paga. Se ela já mudou de situação, a API informa que não pode mais ser cancelada.
• POST /pix/{id}/sync — força a verificação do status junto ao processador. Útil se o seu sistema não recebeu um webhook; o uso normal é aguardar o webhook.

Ambos exigem payments:create.

Confie nos webhooks, confirme na API

Trate o webhook payment.approved como o sinal para liberar o pedido. Se quiser dupla verificação, faça GET /pix/{id} e confira status = paid antes de entregar.