Cobranças

Criar cobrança

POST/api/v1/charges

Cria uma cobrança PIX ou cartão num único endpoint. Use o campo method como discriminador — "pix" ou "credit_card". Valores em centavos. O corpo do PIX é o mesmo do /api/v1/pix: customer e payer são aceitos como sinônimos.

Requisição · PIX

curl -X POST https://beta.venopayments.com/api/v1/charges \
  -H "Authorization: Bearer veno_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "method": "pix",
    "amount": 3599,
    "external_id": "order-123",
    "callback_url": "https://seu-servidor.com/webhook",
    "customer": {
      "name": "João Silva",
      "email": "joao@email.com",
      "document": "12345678900",
      "phone": "11999999999"
    },
    "products": [
      { "external_ref": "prod-1", "name": "Escova elétrica 9 em 1", "price": 3599, "quantity": 1 }
    ]
  }'

Resposta · 200 (PIX)

{
  "id": "uuid-do-deposito",
  "method": "pix",
  "status": "pending",
  "amount": 3599,
  "qr_code_image": "payload-pix-copia-cola",
  "pix_copy_paste": "payload-pix-copia-cola",
  "expires_at": "2026-03-23T15:00:00Z"
}

Requisição · cartão

curl -X POST https://beta.venopayments.com/api/v1/charges \
  -H "Authorization: Bearer veno_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "method": "credit_card",
    "amount": 10000,
    "installments": 1,
    "customer": {
      "name": "João Silva",
      "email": "joao@email.com",
      "document": "12345678900",
      "phone": "11999999999"
    },
    "card": {
      "token": "<token do veno.js>",
      "three_ds": "<three_ds do veno.js>"
    }
  }'

Parâmetros do body

methodstringObrigatório

"pix" ou "credit_card".

amountintegerObrigatório

Valor em centavos. 10000 = R$ 100,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 a cobrança original sem criar duplicata.

callback_urlstring

URL que recebe os webhooks desta cobrança.

installmentsinteger

Número de parcelas (cartão). Padrão: 1.

currencystring

ISO 4217. Padrão BRL. Moeda diferente de BRL só é aceita com method = "credit_card" e exige o mercado global habilitado na conta.

customerobjectObrigatório

Dados do comprador. Mesmo formato do payer do /api/v1/pix.

payerobject

Sinônimo de customer, com os mesmos campos — aceito para que o corpo do /api/v1/pix funcione aqui sem alteração. Se os dois forem enviados, customer prevalece.

productsarray

Itens da cobrança. Obrigatório no PIX. A soma de price × quantity de todos os itens deve ser igual a amount. No cartão é opcional: sem ele, a cobrança vai com um item único montado a partir de description.

cardobject

Obrigatório quando method = "credit_card". O token e o three_ds vêm do veno.js no browser — ambos são necessários para capturar a cobrança (3DS / liability shift).

utm_* / src / sckstring

Parâmetros de rastreamento (utm_source, utm_campaign, utm_medium, utm_content, utm_term, src, sck), armazenados no depósito.

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

Idempotência

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

Consultar

GET /api/v1/charges/{id} devolve a cobrança. Para PIX, /api/v1/pix/{id}/status também funciona com o mesmo id.