PIX

Criar PIX

POST/api/v1/pix

Cria uma cobrança PIX e devolve o QR Code e o payload copia e cola.

Requisição

curl -X POST https://beta.venopayments.com/api/v1/pix \
  -H "Authorization: Bearer veno_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1000,
    "description": "Pedido #123",
    "external_id": "order-123",
    "callback_url": "https://seu-servidor.com/webhook",
    "payer": {
      "name": "João Silva",
      "email": "joao@email.com",
      "document": "12345678900",
      "phone": "11999999999"
    },
    "products": [
      { "external_ref": "prod-1", "name": "Assinatura Mensal", "price": 1000, "quantity": 1 }
    ]
  }'

Resposta · 201

{
  "id": "uuid-do-deposito",
  "txid": "identificador-pix",
  "status": "pending",
  "amount": 1000,
  "qr_code": "",
  "qr_code_image": "payload-pix-copia-cola",
  "pix_copy_paste": "payload-pix-copia-cola",
  "expires_at": "2026-03-23T15:00:00Z",
  "splits": [
    { "account_id": "uuid-da-conta", "amount": 500 }
  ]
}

Parâmetros do body

amountintegerObrigatório

Valor em centavos. 1000 = R$ 10,00.

descriptionstring

Descrição da cobrança, ex: "Pedido #123".

external_idstring

Seu ID interno, usado para idempotência: reenviar o mesmo external_id retorna o PIX original sem criar duplicata.

callback_urlstring

URL que recebe os webhooks desta cobrança.

productsarrayObrigatório

Itens da cobrança. A soma de price × quantity de todos os itens deve ser igual a amount.

payerobjectObrigatório

Dados do pagador.

splitsarray

Divide o valor entre outras contas. Máximo de 10. Veja as regras de split.

utm_* / src / sckstring

Parâmetros de rastreamento, armazenados no depósito.

Campos obrigatórios: os provedores de liquidação (Getnet/Stone) exigem products com ao menos um item e os dados completos do pagador (name, email, document e phone). Requisições sem esses campos são recusadas.

Idempotência

Se você enviar o mesmo external_id duas vezes, o segundo request retorna o PIX original sem criar duplicata.

Rastreamento

Os parâmetros UTM e Utmify são armazenados no depósito. O domínio de origem é capturado automaticamente dos headers Origin ou Referer.