Pix

Cobrança imediata

Com esta funcionalidade você pode criar um QR Code de cobrança imediata.

Case de uso:

Como SaaS, quero gerar cobranças preenchendo apenas o valor do produto e nada mais

Regras condicionais (COBV): name e cep do customer só são aceitos junto com expiration. Havendo expiration e customer, o trio documentNumber, name e cep passa a ser obrigatório em bloco.

Resposta: os campos vêm na raiz — emv e qrCode, não aninhados sob pix. O qrCode já é uma data URL PNG pronta para exibir; não é preciso gerar a imagem no seu lado.

Correlação com o pedido: envie metadata na criação e ele volta na resposta e no payload do webhook payment.success. É a forma recomendada de amarrar o pagamento ao seu pedido.

⚠️ Esta rota não tem idempotência. externalId é aceito e descartado; duas chamadas iguais criam duas cobranças. Controle duplicidade no seu lado (índice pedido → cobrança) ou use POST /v1/charges, que responde 409 DUPLICATE_CHARGE. O campo externalTxid documentado aqui identifica loja, caixa ou vendedor — não serve como chave de idempotência.

POST/v1/charges/pix

Base URL Produção:https://api.validapay.com.br

Base URL Sandbox:https://sandbox.validapay.com.br

Authorizations

bearer

Authorization

string · header · required

Cabeçalho de autenticação Bearer no formato Bearer {{token}} onde {{token}} é o seu token OAuth2.

Escopos requeridos

pix.cob/write

Body

application/json

Content-Type:application/json

{
  "amount": 10.00,
  "paymentMethod": "pix",
  "expiration": "2026-12-31",
  "externalTxid": "loja-01-caixa-03",
  "metadata": { "orderId": "pedido-1001" },
  "customer": {
    "documentNumber": "12345678901",
    "name": "Joao da Silva",
    "cep": "01310100",
    "phone": "+5511999998888",
    "email": "joao@email.com"
  },
  "split": [
    {
      "type": "fixed",
      "accountNumber": "896532569",
      "amount": 0.10
    }
  ]
}

Schema

amountnumberRequired

Regra:0.01

Valor em reais, nunca em centavos

paymentMethodstringOptional

Valores aceitos:pix

Fixo "pix"; o padrao ja e pix

expirationstringOptional

Regra:^\d{4}-\d{2}-\d{2}$

Vencimento (COBV). Nao aceita data passada

externalTxidstringOptional

Regra:até 100 caracteres

Identifica loja, caixa ou vendedor

metadataobject

customerobjectOptional

Dados do pagador. Com expiration, vira COBV

split[1]arrayOptional

Divisao do valor entre recebedores

← Anterior

Status de cobrança

Cobrança imediata com split

const url = 'https://sandbox.validapay.com.br/v1/charges/pix';

const options = {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer {{token}}',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
  "amount": 10.00,
  "paymentMethod": "pix",
  "expiration": "2026-12-31",
  "externalTxid": "loja-01-caixa-03",
  "metadata": { "orderId": "pedido-1001" },
  "customer": {
    "documentNumber": "12345678901",
    "name": "Joao da Silva",
    "cep": "01310100",
    "phone": "+5511999998888",
    "email": "joao@email.com"
  },
  "split": [
    {
      "type": "fixed",
      "accountNumber": "896532569",
      "amount": 0.10
    }
  ]
})
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

Response Examples

200200

{
    "chargeId": "cha_1771511282731_9p1wo3tql",
    "emv": "00020101021226910014br.gov.bcb.pix…",
    "qrCode": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
    "metadata": {
        "orderId": "pedido-1001"
    }
}

← Anterior

Status de cobrança

Cobrança imediata com split