Checkout Transparente

Gerar cobrança Cartão

Para gerar uma cobrança no cartão de crédito sem 3DS é necessário que o seu frontend tokenize o cartão via SDK (Os detalhes podem ser consultados neste link), de modo que os dados sensíveis (PAN e CVV) nunca passem pelo seu servidor. O SDK de tokenização retorna cardToken e deviceId que deverão ser utilizados na cobrança.

POST/v1/charges

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

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

subscriptionId só vem quando a cobrança é recorrente. Esta rota cria cobranças avulsas e recorrentes. Com items de um preço recorrente, a resposta traz subscriptionId, o ID da assinatura criada. A cobrança avulsa (enviada com amount, ou com items só de preços de pagamento único) não é assinatura e não traz o campo: identifique-a por chargeId. A mesma regra vale para o webhook charge.created e para GET /v1/charges/{chargeId}, onde a avulsa vem com subscription: null.

Visão geral

O cardToken e deviceId retornados pelo SDK de tokenização devem ser enviados no body do request de geração de cobrança.

ℹ️ Sem 3DS, o risco de chargeback por fraude fica com a sua conta. Com o pacote @validapay/3ds, o banco confirma o dono do cartão antes da cobrança.

Campos do cartão

cardToken (obrigatório) — vem de tokenize(...) no pacote @validapay/tokenize. Representa o cartão, vale 5 minutos, é de uso único e só funciona na conta que o gerou.
deviceId (obrigatório) — vem de collectDevice(...) no mesmo pacote. Identifica o dispositivo do comprador e alimenta o antifraude.

SEU_ID_PUBLICO está no painel em Gerenciamento > Minha Conta > Id Público. É público: pode ficar no código da página.

Idempotência

Envie externalId como chave de idempotência do pedido. Se duas cobranças forem enviadas com o mesmo valor, a segunda é recusada com 409 DUPLICATE_CHARGE e o corpo traz o chargeId da cobrança original em error.details.chargeId.

⚠️ O cardToken expira em 5 minutos. A idempotência não devolve a resposta da cobrança original: a segunda chamada com o mesmo externalId é recusada com 409 DUPLICATE_CHARGE e o cartão não é reprocessado. Para cobrar de novo, gere um cardToken novo e use outro externalId.

Use externalTxid só para identificar a loja, o caixa ou o vendedor. Ele não entra na idempotência.

Correlação com o pedido: use externalId — ele é persistido e devolvido. O campo metadata é aceito nesta rota, mas não é gravado na cobrança nem volta no webhook; ele só é persistido em POST /v1/charges/pix.

Produto, valor e parcelas

Envie items com os produtos ou amount para uma cobrança avulsa — nunca os dois.
Dá para parcelar com installments e, se quiser, repassar as taxas ao comprador.

Notificações por e-mail

Use notifications para escolher quais e-mails saem nesta cobrança:

oneoff.payment.success — confirmação ao comprador quando o cartão é aprovado
oneoff.payment.failed — aviso ao comprador quando o cartão é recusado
new.sale — avisa você (vendedor) da venda paga

Eventos destinados ao comprador exigem customer.email. Sem o campo, uma cobrança avulsa (amount) não dispara e-mail nenhum; com items de um produto, vale a configuração do produto, e notifications no payload tem precedência.

Resposta

200 — cartão aprovado: success: true, chargeId, customerId, status: "paid".
402 — cartão recusado pelo banco ou adquirente: success: false, status: "failed" e o motivo em error (texto).

Erros comuns

400 MISSING_CARD_DATA — faltou o cardToken
400 CARD_TOKEN_EXPIRED — passou dos 5 minutos: gere outro na página
404 CARD_TOKEN_NOT_FOUND — token inexistente ou de outra conta
404 PRICE_NOT_FOUND — o priceId de algum item não existe
409 DUPLICATE_CHARGE — o externalId já foi usado; use o chargeId retornado
400 INVALID_DATA — esta rota não aceita split no cartão; use Cobrança no cartão com split
402 — pagamento recusado pelo banco (card_declined, insufficient_funds, etc.)

Cartões de teste (sandbox)

Em conta de sandbox nenhuma cobrança é cobrada de verdade — o número digitado na tokenização define o resultado:

4111111111111111 — aprovado
4000000000000002 — recusado (card_declined)
4000000000000004 — saldo insuficiente (insufficient_funds)
4000000000000006 — cartão expirado (expired_card)
4000000000000008 — CVV inválido (invalid_cvv)
4000000000000010 — suspeita de fraude (fraud_suspected)

Qualquer outro número de 16 dígitos é aprovado. CVV, validade e nome do titular podem ser quaisquer valores válidos. Em produção o número não muda nada: quem decide é o banco emissor.

Boas práticas

Obtenha o cardToken imediatamente antes de chamar esta rota. Ele expira em 5 minutos e é de uso único.
Envie deviceId sempre — ele alimenta o antifraude.
Prefira 3DS quando puder: veja Gerar cobrança Cartão 3DS.
Não use metadata para correlacionar o pedido nesta rota — use externalId.

Authorizations

bearer

Authorization

string obrigatório

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

Escopos requeridos

charges/write

Body

application/json

Content-Type:application/json

JSON

{
  "paymentMethod": "creditcard",
  "externalId": "pedido-2026-0001",
  "externalTxid": "loja-01-caixa-03",
  "customer": {
    "name": "João da Silva",
    "email": "joao@email.com",
    "documentNumber": "12345678901",  
    "metadata": { "origem": "site" },
    "phone": "+5511999998888",  
    "cep": "01310100",
    "address": {
      "type": "BILLING",
      "street": "Av. Paulista",
      "number": "1000",
      "complement": "Apto 52",
      "neighborhood": "Bela Vista",
      "city": "Sao Paulo",
      "state": "SP",
      "zipCode": "01310100",
      "country": "BR",
      "cityCode": "3550308"
    }
  },
  "cardToken": "ctk_9f8s7d6f5g4h3j2k1l0",
  "deviceId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "amount": 10.00,
  "items": [
    {
      "priceId": "price_abc123",
      "quantity": 1,
      "isOrderBump": false
    }
  ],
  "installments": 1,
  "freeInstallments": 1,
  "passFeesToCustomer": false,
  "couponCode": "PROMO10",
  "metadata": { "referencia": "pedido-001" },
  "description": "Assinatura Premium",
  "allowedPaymentMethods": ["pix", "creditcard"],
  "nfConfigId": "nfc_1788364755079_psuecwgdc",
  "notifications": ["oneoff.payment.success", "oneoff.payment.failed", "new.sale"],
  "discounts": [
    {
      "type": "percentage",
      "value": 10,
      "paymentMethod": "creditcard",
      "couponCode": "PROMO10"
    }
  ],
  "cartId": "cart_2026_0001",
  "productId": "prod_123456_example"
}

Schema

paymentMethodstringobrigatório

Forma de pagamento (fixo: creditcard)

Valores aceitos:pixcreditcardboletopix_automatico

customerobjectobrigatório

Dados do comprador

cardTokenstringobrigatório

Token do cartão, gerado no navegador do comprador pelo SDK @validapay/tokenize. Vale 5 minutos e só funciona na conta que o gerou. Os dados do cartão nunca passam pelo seu servidor

deviceIdstringobrigatório

Identificação do dispositivo do comprador, devolvida pelo collectDevice do mesmo SDK. É o que alimenta a análise antifraude: envie sempre

externalIdstringopcional

Identificador único do pedido no seu sistema; usado como idempotencyKey (evita cobrança duplicada)

Regra:até 100 caracteres

externalTxidstringopcional

Identifica a loja, o caixa ou o vendedor responsável pela cobrança

Regra:até 100 caracteres

amountnumberopcional

Valor total em reais para cobrança avulsa. Ignorado quando items é enviado

Regra:0.01

itemsarray[1]opcional

Produtos da compra (ou use amount para cobrança avulsa)

installmentsnumberopcional

Parcelas no cartão, de 1 a 12

Regra:1 a 12

freeInstallmentsnumberopcional

Parcelas sem juros para o comprador, de 0 a 12

Regra:0 a 12

passFeesToCustomerbooleanopcional

Repassa a taxa de parcelamento ao comprador

couponCodestringopcional

Código de cupom de desconto

metadataobjectopcional

Aceito mas NÃO persistido nesta rota; para correlacionar o pedido use externalId

descriptionstringopcional

Descrição livre da cobrança

allowedPaymentMethodsarray[2]opcional

Métodos aceitos quando a cobrança vira link

Valores aceitos:pixcreditcardboletopix_automatico

nfConfigIdstringopcional

Emite nota fiscal com esta configuração. Exige customer.address e customer.email

notificationsarray[3]opcional

E-mails disparados nesta cobrança

Valores aceitos:oneoff.pix.generatedoneoff.boleto.generatedoneoff.payment.successoneoff.payment.failednew.saleseller.charge.pending

discountsarray[1]opcional

Descontos aplicados a cobrança

cartIdstringopcional

Agrupa numa única compra as assinaturas criadas juntas e deduplica o evento de conversão

productIdstringopcional

Cria a cobrança a partir de um produto

Regra:^prod_

Headers

Content-Typeopcional

application/json

← Anterior

Gerar cobrança Boleto

Gerar cobrança Cartão 3DS

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",
  "externalId": "pedido-2026-0001",
  "externalTxid": "loja-01-caixa-03",
  "customer": {
    "name": "João da Silva",
    "email": "joao@email.com",
    "documentNumber": "12345678901",  
    "metadata": { "origem": "site" },
    "phone": "+5511999998888",  
    "cep": "01310100",
    "address": {
      "type": "BILLING",
      "street": "Av. Paulista",
      "number": "1000",
      "complement": "Apto 52",
      "neighborhood": "Bela Vista",
      "city": "Sao Paulo",
      "state": "SP",
      "zipCode": "01310100",
      "country": "BR",
      "cityCode": "3550308"
    }
  },
  "cardToken": "ctk_9f8s7d6f5g4h3j2k1l0",
  "deviceId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "amount": 10.00,
  "items": [
    {
      "priceId": "price_abc123",
      "quantity": 1,
      "isOrderBump": false
    }
  ],
  "installments": 1,
  "freeInstallments": 1,
  "passFeesToCustomer": false,
  "couponCode": "PROMO10",
  "metadata": { "referencia": "pedido-001" },
  "description": "Assinatura Premium",
  "allowedPaymentMethods": ["pix", "creditcard"],
  "nfConfigId": "nfc_1788364755079_psuecwgdc",
  "notifications": ["oneoff.payment.success", "oneoff.payment.failed", "new.sale"],
  "discounts": [
    {
      "type": "percentage",
      "value": 10,
      "paymentMethod": "creditcard",
      "couponCode": "PROMO10"
    }
  ],
  "cartId": "cart_2026_0001",
  "productId": "prod_123456_example"
})
};

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

Response Examples

200▾

JSON

{
  "success": true,
  "customerId": "cus_xxx",
  "chargeId": "cha_abc123",
  "subscriptionId": "sub_1790920815522_46aumd4fa", 
  "status": "paid"
}

Campos da resposta

successboolean

customerIdstring

chargeIdstring

subscriptionIdstringopcional

Só em cobrança recorrente: ID da assinatura criada. Ausente na cobrança avulsa

statusstring

402▾

JSON

{
    "success": false,
    "chargeId": "cha_1784065113577_5dw2oyfic",
    "status": "failed",
    "error": "Cartão recusado"
}

400MISSING_CARD_DATA▾

JSON

{
  "error": {
    "message": "cardToken é obrigatório na cobrança com cartão; gere um com o SDK @validapay/tokenize",
    "code": "MISSING_CARD_DATA"
  }
}

404PRICE_NOT_FOUND▾

JSON

{
  "error": {
    "message": "Preço não encontrado",
    "code": "PRICE_NOT_FOUND"
  }
}

409DUPLICATE_CHARGE▾

JSON

{
  "error": {
    "message": "Cobrança duplicada: já existe uma cobrança para este pedido",
    "code": "DUPLICATE_CHARGE",
    "details": {
      "chargeId": "cha_1784065113577_5dw2oyfic"
    },
    "timestamp": "2026-07-14T21:39:36.322Z"
  }
}

← Anterior

Gerar cobrança Boleto

Gerar cobrança Cartão 3DS