Cobranças

Criar Cobrança com Cartão

POST/v1/charges

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

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

Autenticação

bearerAuthorizationstring · header · obrigatório

Envie no header:

Authorization: Bearer {{token}}

Cria uma cobrança via cartão de crédito para seu cliente.

Criar cobrança

Cria uma cobrança avulsa para o seu cliente. O método de pagamento é definido no campo paymentMethod — escolha entre Pix, boleto ou cartão de crédito.

Autenticação: token de acesso (Bearer). Se você opera como conta principal e quer emitir a cobrança em nome de uma subconta, informe o número dela no cabeçalho X-Sub-Account.

Métodos de pagamento disponíveis:

Método (`paymentMethod`)	Como o cliente paga
`pix`	QR Code / Pix Copia e Cola, com pagamento na hora
`boleto`	Boleto bancário com data de vencimento
`creditcard`	Cartão de crédito, à vista ou parcelado

Cartão — duas formas de enviar:

paymentMethodId (recomendado): ID de um cartão já tokenizado via /v1/payment-methods/tokenize. Não trafega dados sensíveis.
card (dados brutos): o cartão é tokenizado e salvo automaticamente no cliente, ficando reutilizável como paymentMethodId nas próximas cobranças.

⚠️ customer é obrigatório quando o cartão é enviado para pagamento (via card ou paymentMethodId), pois o cartão é vinculado a um cliente — informe ao menos customer.documentNumber. Se você apenas cria a cobrança (sem cartão, para capturar depois), customer é opcional e o retorno traz installmentOptions.

Campos principais:

Campo	Obrig.	Tipo	Descrição
`paymentMethod`	✅	string	Método de pagamento: `pix`, `boleto` ou `creditcard`
`amount`	✅	number	Valor da cobrança, em reais
`title`	✅	string	Título da cobrança (2 a 100 caracteres)
`description`	❌	string	Descrição exibida ao cliente (até 500 caracteres)
`customer`	✅*	object	Dados do cliente. Obrigatório quando há `card` ou `paymentMethodId`. Campos: `name`, `documentNumber`, `email`, `phone`, `address`
`paymentMethodId`	✅*	string	ID de cartão tokenizado. Alternativa a `card`.
`card`	✅*	object	Dados brutos do cartão. Alternativa a `paymentMethodId`. Campos: `number` (13-19 dígitos), `cvv` (3-4 dígitos), `name`, `expiration` (`MM/YYYY`)
`installments`	❌	number	Número de parcelas (1 a 12, padrão 1)
`passFeesToCustomer`	❌	boolean	Repassa as taxas ao cliente
`freeInstallments`	❌	number	Parcelas sem juros (1 a 12, padrão 1)
`split`	❌	array	Divisão do valor entre contas (`type`, `accountNumber`, `amount`)
`metadata`	❌	object	Dados adicionais de sua escolha
`nfConfigId`	❌	string	Configuração de nota fiscal a ser usada

Os campos marcados com * são obrigatórios conforme o cenário. Para cobrar cartão, envie card ou paymentMethodId (nunca os dois) e inclua customer.

Scope OAuth necessário: checkouts/write

Body

application/json

Content-Type:application/json

{
  "paymentMethod": "creditcard",
  "amount": 399.9,
  "title": "Compra avulsa",
  "description": "Produto Premium",
  "customer": {
    "name": "João da Silva",
    "documentNumber": "12345678901",
    "email": "joao@email.com",
    "phone": "+5511999998888"
  },
  "paymentMethodId": "pm_abc123",
  "installments": 3,
  "passFeesToCustomer": false,
  "freeInstallments": 1,
  "metadata": {
    "orderId": "ORD-001"
  }
}

Schema

Field	Type	Required	Description
paymentMethod	string	-	-
amount	number	-	-
title	string	-	-
description	string	-	-
customer	object	-	-
paymentMethodId	string	-	-
installments	number	-	-
passFeesToCustomer	boolean	-	-
freeInstallments	number	-	-
metadata	object	-	-

Headers

Name	Type	Value	Required
Content-Type	-	application/json	Optional

← Anterior

Criar Cobrança Boleto

Listar Cobranças

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

const options = {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer {{token}}',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
  "paymentMethod": "creditcard",
  "amount": 399.9,
  "title": "Compra avulsa",
  "description": "Produto Premium",
  "customer": {
    "name": "João da Silva",
    "documentNumber": "12345678901",
    "email": "joao@email.com",
    "phone": "+5511999998888"
  },
  "paymentMethodId": "pm_abc123",
  "installments": 3,
  "passFeesToCustomer": false,
  "freeInstallments": 1,
  "metadata": {
    "orderId": "ORD-001"
  }
})
};

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

Response Examples

200200 Cartão (cobrança imediata)

{
  "success": true,
  "chargeId": "cha_xxx",
  "status": "paid"
}

200200 Link (sem cartão)

{
  "chargeId": "cha_xxx",
  "installmentOptions": [
    { "installments": 1, "amount": 399.9, "total": 399.9 },
    { "installments": 2, "amount": 199.95, "total": 399.9 },
    { "installments": 3, "amount": 133.3, "total": 399.9 }
  ]
}

402402 Recusado

{
  "success": false,
  "chargeId": "cha_xxx",
  "status": "failed",
  "error": "declined"
}

400400 tokenização

{
  "code": "CARD_TOKENIZATION_FAILED"
}

400400 customer obrigatório

{
  "message": "Cliente é obrigatório para salvar cartão",
  "code": "CUSTOMER_REQUIRED"
}

400400 cartão não tokenizado

{
  "message": "Cartão não tokenizado no provider ativo",
  "code": "CARD_NOT_TOKENIZED"
}

← Anterior

Criar Cobrança Boleto

Listar Cobranças