API PIX

Receba pagamentos PIX e seja notificado via webhook quando forem confirmados.

Simples

2 endpoints. Crie um PIX e consulte o status.

Webhook

Receba notificacao automatica quando o PIX for pago.

Seguro

Autenticacao via API Key com prefixo veno_live_.

Autenticacao

Todas as requisicoes da API PIX usam autenticacao via API Key no header Authorization.

header

Authorization: Bearer veno_live_a1b2c3d4e5f6...

Como obter sua API Key

Acesse Dashboard → API Keys e clique em "Nova Chave". A chave sera exibida uma unica vez — guarde-a em local seguro.

Charges

SDK de Cartão (veno.js) — Tokenização + 3DS

Para checkout com cartão no navegador (checkout transparente), use o veno.js. Ele tokeniza o cartão e roda o 3DS no browser, e devolve { token, three_ds } — padronizado, independente do adquirente. O número do cartão não passa pelo seu servidor. Depois, o seu backend cria a cobrança em /api/v1/charges com a secret key.

1. Obtenha sua publishable key

bash

curl https://beta.venopayments.com/api/v1/publishable-key \
  -H "Authorization: Bearer veno_live_..."
# => { "publishable_key": "pk_veno_..." }

2. No browser: tokenize + 3DS

html

<script src="https://beta.venopayments.com/veno.js"></script>
<div id="tds-method" style="display:none"></div>
<div id="tds-challenge"></div>

javascript

const veno = Veno.create({
  apiBase: "https://beta.venopayments.com",
  publishableKey: "pk_veno_...",
});

const { token, three_ds } = await veno.authenticate({
  card: {
    number: "4111111111111111", cvv: "123",
    exp_month: "12", exp_year: "2030",
    holder_name: "JOAO SILVA", holder_document: "12345678900",
    // line_1 precisa ter 3 partes: "<numero>, <rua>, <bairro>"; line_2 obrigatório
    billing_address: { line_1: "100, Rua A, Centro", line_2: "ap 1",
      zip_code: "01001000", city: "Sao Paulo", state: "SP", country: "BR" },
  },
  customer: { name: "JOAO SILVA", email: "joao@ex.com", document: "12345678900",
    phones: { mobile_phone: { country_code: "55", area_code: "11", number: "999999999" } } },
  amount: 10000, installments: 1,
  containers: {
    method: document.getElementById("tds-method"),
    challenge: document.getElementById("tds-challenge"),
  },
});
// envie { token, three_ds } para o SEU backend

3. No seu backend: cobre

bash

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,
       "card":{"token":"<token>","three_ds":<three_ds>}}'

Segurança: a pk_veno_ é pública (pode ficar no front) — só inicia a sessão 3DS, nunca cobra nem lê dados. A cobrança é sempre feita no seu backend com a veno_live_ (secret). O PAN é tokenizado no browser e não transita pelo seu servidor.

Charges

Criar Cobrança

Cria uma cobrança PIX ou cartão de crédito. Use o campo method como discriminator.

POST/api/v1/charges

Campo	Tipo	Obrigatorio	Descricao
`method`	string	Sim	"pix" ou "credit_card".
`amount`	integer	Sim	Valor em centavos (R$1,00 = 100).
`external_id`	string	Nao	Sua referência. Usado para idempotência.
`description`	string	Nao	Descrição da cobrança.
`callback_url`	string	Nao	URL para webhook de confirmação.
`installments`	integer	Nao	Parcelas (apenas cartão, padrão: 1).
`customer.name`	string	Nao	Nome do pagador.
`customer.email`	string	Nao	Email do pagador.
`customer.document`	string	Nao	CPF ou CNPJ.
`card.token`	string	Nao	Token do cartão retornado pelo veno.js (ver "SDK de Cartão"). Obrigatório quando method = "credit_card".
`card.three_ds`	object	Nao	Resultado da autenticação 3DS do veno.js. Necessário p/ capturar a cobrança (liability shift).

bash

# 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":10000,"external_id":"order-1"}'

# Cartão — token + three_ds vêm do veno.js (ver "SDK de 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,
       "card":{"token":"<token>","three_ds":<three_ds>}}'

Consultar Cobrança

Retorna o status atual de uma cobrança.

GET/api/v1/charges/{id}

bash

curl https://beta.venopayments.com/api/v1/charges/{id} \
  -H "Authorization: Bearer veno_live_..."

Estornar Cobrança

Estorna integralmente uma cobrança paid. O valor é devolvido ao pagador pelo adquirente e o saldo correspondente é debitado da sua conta. Apenas cobranças pagas podem ser estornadas.

POST/api/v1/charges/{id}/refund

bash

curl -X POST https://beta.venopayments.com/api/v1/charges/{id}/refund \
  -H "Authorization: Bearer veno_live_..."

Resposta

json

{
  "id": "0190a1b2-...",
  "status": "refunded",
  "amount": 10000,
  "refunded_at": "2026-06-26T12:34:56Z"
}

Observações: estorno total no v1 (sem parcial). O suporte a estorno depende do adquirente que processou a cobrança — adquirentes sem suporte retornam422. Estado da cobrança não muda quando o estorno falha.

Erros

Campo	Tipo	Obrigatorio	Descricao
`404`	not_found	Nao	Cobrança não encontrada para esta conta.
`409`	conflict	Nao	Cobrança não está em estado estornável (somente paid).
`422`	unprocessable	Nao	Estorno não suportado pelo adquirente da cobrança.

Dados da Empresa (Seller)

Retorna os dados cadastrais da conta autenticada (nome, status e — quando o cadastro PJ estiver concluído — razão social, nome fantasia e CNPJ).

GET/api/v1/seller

bash

curl https://beta.venopayments.com/api/v1/seller \
  -H "Authorization: Bearer veno_live_..."

Resposta

json

{
  "id": "0190a1b2-...",
  "name": "Minha Loja",
  "status": "active",
  "company_name": "Minha Loja Ltda",
  "trade_name": "Minha Loja",
  "document": "00.000.000/0001-00",
  "kyc_status": "approved",
  "created_at": "2026-01-10T09:00:00Z"
}

Criar PIX

Cria uma cobranca PIX e retorna o QR Code para pagamento.

POST/api/v1/pix

Request Body

Campo	Tipo	Obrigatorio	Descricao
`amount`	integer	Sim	Valor em centavos. R$100,00 = 10000. Min: 100, Max: 100000000.
`callback_url`	string	Nao	URL para receber webhook quando o PIX for pago.
`external_id`	string	Nao	Referencia do seu sistema. Usado para idempotencia.
`description`	string	Nao	Descricao do pagamento.
`payer.name`	string	Nao	Nome do pagador.
`payer.email`	string	Nao	Email do pagador.
`payer.document`	string	Nao	CPF ou CNPJ do pagador.
`payer.phone`	string	Nao	Telefone do pagador.
`payer.address`	string	Nao	Endereco do pagador.
`payer.city`	string	Nao	Cidade do pagador.
`payer.state`	string	Nao	UF do pagador (2 caracteres, ex: SP).
`payer.zip_code`	string	Nao	CEP do pagador (8 digitos).
`utm_source`	string	Nao	Parametro UTM source (ex: facebook, google).
`utm_campaign`	string	Nao	Parametro UTM campaign (ex: black-friday).
`utm_medium`	string	Nao	Parametro UTM medium (ex: cpc, email).
`utm_content`	string	Nao	Parametro UTM content (ex: banner-topo).
`utm_term`	string	Nao	Parametro UTM term (ex: pix desconto).
`src`	string	Nao	Parametro Utmify src.
`sck`	string	Nao	Parametro Utmify sck.
`splits`	array	Nao	Lista de splits. Cada item: {account_id: string, amount: integer}.
`splits[].account_id`	string	Sim	UUID da conta que recebera parte do valor.
`splits[].amount`	integer	Sim	Valor em centavos a enviar para esta conta.

Request

curl

curl -X POST https://beta.venopayments.com/api/v1/pix \
  -H "Authorization: Bearer veno_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10000,
    "callback_url": "https://seusite.com/webhook",
    "external_id": "pedido-123",
    "description": "Pedido #123",
    "payer": {
      "name": "Joao Silva",
      "email": "joao@email.com",
      "document": "12345678900",
      "phone": "11999999999",
      "city": "Sao Paulo",
      "state": "SP"
    },
    "utm_source": "facebook",
    "utm_campaign": "black-friday",
    "utm_medium": "cpc",
    "splits": [
      {"account_id": "019c4586-aaaa-bbbb-cccc-000000000001", "amount": 3000}
    ]
  }'

Response 201

json

{
  "id": "019c4586-07f3-7312-8472-0e8c708b33ab",
  "txid": "pagloop-txid-abc123",
  "status": "pending",
  "amount": 10000,
  "qr_code": "00020101021226870014br.gov.bcb.pix...",
  "qr_code_image": "00020101021226870014br.gov.bcb.pix...",
  "pix_copy_paste": "00020101021226870014br.gov.bcb.pix...",
  "expires_at": "2026-03-01T15:00:00Z",
  "splits": [
    {"account_id": "019c4586-aaaa-bbbb-cccc-000000000001", "amount": 3000}
  ]
}

Idempotencia

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

Rastreamento (UTMs + Origem)

Os parametros UTM sao armazenados no deposito e exibidos nos detalhes da transacao no dashboard. O dominio de origem e capturado automaticamente do header HTTP Origin ou Referer.

Consultar Status

Retorna o status atual de um PIX.

GET/api/v1/pix/{id}/status

Request

curl

curl https://beta.venopayments.com/api/v1/pix/{id}/status \
  -H "Authorization: Bearer veno_live_xxxxx"

Response 200

json

{
  "id": "019c4586-07f3-7312-8472-0e8c708b33ab",
  "txid": "pagloop-txid-abc123",
  "status": "paid",
  "amount": 10000,
  "paid_at": "2026-03-01T14:32:00Z",
  "end_to_end_id": "E12345678202603...",
  "external_id": "pedido-123",
  "payer_name": "Joao Silva",
  "payer_document": "12345678900"
}

Response Fields

Campo	Tipo	Obrigatorio	Descricao
`id`	string	Sim	ID unico do deposito.
`txid`	string	Sim	ID da transacao no adquirente.
`status`	string	Sim	Status atual do PIX.
`amount`	integer	Sim	Valor em centavos.
`paid_at`	string \| null	Nao	Data/hora do pagamento (ISO 8601).
`end_to_end_id`	string \| null	Nao	ID end-to-end do BACEN.
`external_id`	string \| null	Nao	Sua referencia, se enviada.
`payer_name`	string \| null	Nao	Nome do pagador.
`payer_document`	string \| null	Nao	CPF/CNPJ do pagador.

Split de Pagamento

Divida o valor de um PIX entre multiplas contas no gateway. Ideal para marketplaces, afiliados e comissoes.

Como funciona

• Adicione o campo splits ao criar o PIX com account_id e amount (centavos)
• A taxa e cobrada somente na conta dona da API Key (quem cria o PIX)
• As contas receptoras recebem o valor do split sem desconto de taxa
• Os splits sao creditados automaticamente quando o PIX e pago

Regras

• Soma dos splits nao pode exceder o valor total do PIX
• Nao e possivel fazer split para a propria conta
• Maximo de 10 splits por pagamento
• Todas as contas receptoras devem existir e estar ativas

Exemplo

PIX de R$100,00 com split de R$30,00 para outra conta (taxa de 2%):

Conta	Calculo	Recebe
Dona do PIX	R$100 - R$2 (taxa) - R$30 (split)	R$ 68,00
Receptora do Split	R$30 (sem taxa)	R$ 30,00

curl

curl -X POST https://beta.venopayments.com/api/v1/pix \
  -H "Authorization: Bearer veno_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10000,
    "callback_url": "https://seusite.com/webhook",
    "splits": [
      {
        "account_id": "019c4586-aaaa-bbbb-cccc-000000000001",
        "amount": 3000
      }
    ]
  }'

Webhook

Quando um PIX e pago, enviamos um POST para a callback_url que voce informou ao criar o PIX.

Headers Enviados

`Content-Type`	application/json
`User-Agent`	VenoPayments/2.0

Payload

json

{
  "event": "pix.paid",
  "data": {
    "id": "019c4586-07f3-7312-8472-0e8c708b33ab",
    "txid": "pagloop-txid-abc123",
    "external_id": "pedido-123",
    "status": "paid",
    "amount": 10000,
    "paid_at": "2026-03-01T14:32:00Z",
    "end_to_end_id": "E12345678202603011432abcdef",
    "payer": {
      "name": "Joao Silva",
      "document": "12345678900",
      "email": "joao@email.com",
      "phone": "11999999999",
      "city": "Sao Paulo",
      "state": "SP"
    }
  }
}

Eventos

Evento	Descricao
`pix.paid`	PIX foi pago e confirmado.
`pix.expired`	PIX expirou sem pagamento.
`pix.refunded`	Estorno realizado.

Retentativas

Se seu servidor nao responder com HTTP 2xx, retentamos automaticamente:

Tentativa	Intervalo
1a tentativa	Imediato
2a tentativa	+2 segundos
3a tentativa	+4 segundos

Boas praticas

• Responda 200 OK o mais rapido possivel.
• Processe a logica de negocio de forma assincrona.
• Use id ou external_id para idempotencia — voce pode receber o mesmo webhook mais de uma vez.
• Valide com GET /api/v1/pix/{id}/status se necessario.

Status do PIX

Status	Label	Descricao	Equivalente
`pending`	Pendente	Aguardando pagamento	`pending`
`paid`	Pago	Pagamento confirmado	`paid`
`expired`	Expirado	Expirou sem pagamento	`refused`
`cancelled`	Cancelado	Cancelado / não concluído	`refused`
`refunded`	Estornado	Valor devolvido ao pagador	`refunded`
`authorized`	Autorizado	Cartão autorizado, ainda não capturado	`pending`
`captured`	Capturado	Cartão capturado (equivale a pago)	`paid`
`denied`	Negado	Recusado pelo adquirente	`refused`
`chargeback`	Chargeback	Contestação com débito	`refunded`
`disputed`	Em disputa	Contestação em análise	`pending`

Codigos de Erro

Todos os erros retornam JSON com os campos code e message.

json

{
  "code": "BAD_REQUEST",
  "message": "amount must be greater than 0"
}

HTTP	Code	Descricao
400	`BAD_REQUEST`	Request invalido (body, parametros, amount fora do range).
401	`UNAUTHORIZED`	API Key invalida, ausente ou expirada.
404	`NOT_FOUND`	Recurso nao encontrado ou nao pertence a sua conta.
500	`INTERNAL_ERROR`	Erro interno do servidor.