Checkout Transparente

Gerar cobrança Cartão

Gera uma cobrança via cartão de crédito pelo checkout transparente. O cliente informa os dados na sua própria interface e você os envia para a API.

Envie os dados do cartão no objeto card (dados brutos) ou use paymentMethodId/tokenId de um cartão tokenizado. É possível parcelar (installments) e repassar as taxas ao comprador.

Produto ou valor: envie items com os produtos OU amount para uma cobrança avulsa.

Notificações por e-mail: use notifications para escolher quais e-mails saem nesta cobrança. Eventos aceitos aqui: oneoff.payment.success (confirmação ao comprador quando o cartão é aprovado), oneoff.payment.failed (aviso ao comprador quando o cartão é recusado) e new.sale (avisa você, vendedor, da venda paga). Os eventos destinados ao comprador exigem customer.email. Sem o campo, uma cobrança avulsa (enviada com amount) não dispara e-mail nenhum; com items de um produto, vale a configuração de notificações do produto, e notifications no payload tem precedência sobre ela.

⚠️ Atenção: envie o campo externalId como chave de idempotência (idempotencyKey). Se duas cobranças forem enviadas com o mesmo externalId, a segunda é recusada com 409 DUPLICATE_CHARGE, retornando o chargeId da cobrança original.

Erros comuns: 409 DUPLICATE_CHARGE (externalId já utilizado), 402 (pagamento recusado pelo banco), 400 MISSING_CARD_DATA (faltam dados do cartão) e 404 PRICE_NOT_FOUND (preço inexistente).

Cartões de teste (sandbox): em conta de sandbox nenhuma cobrança chega ao adquirente — o número do cartão é que define o resultado:

  • 4111111111111111 — pagamento aprovado
  • 4000000000000002 — recusado pela operadora (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 emissor do cartão.

Use externalTxid para identificar a loja, o caixa ou o vendedor responsável pela cobrança.

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.

POST/v1/charges
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

checkouts/write

Body

application/json

Content-Type:application/json
{
  "paymentMethod": "creditcard",
  "externalId": "pedido-2026-0001",
  "externalTxid": "loja-01-caixa-03",
  "customer": {
    "name": "João da Silva",
    "email": "joao@email.com",
    "documentNumber": "12345678901",
    "phone": "+5511999998888"
  },
  "card": {
    "number": "4111111111111111",
    "cvv": "123",
    "name": "JOAO DA SILVA",
    "expiration": "12/2027"
  },
  "paymentMethodId": "pm_abc123",
  "items": [
    {
      "priceId": "price_abc123",
      "quantity": 1
    }
  ],
  "installments": 1,
  "passFeesToCustomer": false,
  "freeInstallments": 1,
  "couponCode": "PROMO10",
  "metadata": { "referencia": "pedido-001" },
  "description": "Assinatura Premium",
  "split": [
    { "type": "fixed", "accountNumber": "896532569", "amount": 0.10 }
  ],
  "installments": 1,
  "freeInstallments": 1,
  "passFeesToCustomer": false,
  "allowedPaymentMethods": ["pix", "creditcard"],
  "nfConfigId": "nfc_1788364755079_psuecwgdc",
  "notifications": ["oneoff.pix.generated", "oneoff.payment.success", "new.sale"],
  "discounts": [
    {
      "type": "percentage",
      "value": 10,
      "paymentMethod": "pix",
      "fromCycle": 1,
      "toCycle": 3,
      "durationMonths": 3
    }
  ],
  "tokenId": "tok_abc123",
  "productId": "prod_123456_example",
  "recurrencyStartDate": "2026-10-01",
  "prorataStartDate": "2026-09-15",
  "prorataDueDate": "2026-09-20",
  "mergeWithNextCycle": false
}

Schema

paymentMethodstringRequired
Valores aceitos:pixcreditcardboletopix_automatico

Forma de pagamento (fixo: creditcard)

customerobjectRequired

Dados do comprador

cardobjectRequired

Dados do cartão (ou use paymentMethodId/tokenId de um cartão salvo)

externalIdstringOptional
Regra:até 100 caracteres

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

externalTxidstringOptional
Regra:até 100 caracteres

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

paymentMethodIdstringOptional

Cartão tokenizado (alternativa ao objeto card)

items[1]arrayOptional

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

installmentsnumberOptional
Regra:1 a 12

Parcelas no cartao, de 1 a 12

passFeesToCustomerbooleanOptional

Repassa a taxa de parcelamento ao comprador

freeInstallmentsnumberOptional
Regra:0 a 12

Parcelas sem juros para o comprador, de 0 a 12

couponCodestringOptional

Código de cupom de desconto

metadataobject
descriptionstringOptional

Descricao livre da cobranca

split[1]arrayOptional

Divisao do valor. Nao suportado em creditcard nem pix_automatico

allowedPaymentMethods[2]array
Valores aceitos:pixcreditcardboletopix_automatico
nfConfigIdstringOptional

Emite nota fiscal com esta configuracao. Exige customer.address

notifications[3]array
Valores aceitos:oneoff.pix.generatedoneoff.boleto.generatedoneoff.payment.successoneoff.payment.failednew.saleseller.charge.pending
discounts[1]arrayOptional

Descontos aplicados a cobranca

tokenIdstringOptional

Alternativa a card e a paymentMethodId no cartao

productIdstringOptional
Regra:^prod_

Cria a cobranca a partir de um produto

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

Primeira cobranca da recorrencia (YYYY-MM-DD)

prorataStartDatestringOptional

Inicio do calculo pro rata

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

Vencimento da cobranca pro rata (YYYY-MM-DD)

mergeWithNextCyclebooleanOptional

Junta a pro rata com o proximo ciclo em vez de cobrar agora

Headers

NameTypeValueRequired
Content-Type-application/jsonOptional
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",
    "phone": "+5511999998888"
  },
  "card": {
    "number": "4111111111111111",
    "cvv": "123",
    "name": "JOAO DA SILVA",
    "expiration": "12/2027"
  },
  "paymentMethodId": "pm_abc123",
  "items": [
    {
      "priceId": "price_abc123",
      "quantity": 1
    }
  ],
  "installments": 1,
  "passFeesToCustomer": false,
  "freeInstallments": 1,
  "couponCode": "PROMO10",
  "metadata": { "referencia": "pedido-001" },
  "description": "Assinatura Premium",
  "split": [
    { "type": "fixed", "accountNumber": "896532569", "amount": 0.10 }
  ],
  "installments": 1,
  "freeInstallments": 1,
  "passFeesToCustomer": false,
  "allowedPaymentMethods": ["pix", "creditcard"],
  "nfConfigId": "nfc_1788364755079_psuecwgdc",
  "notifications": ["oneoff.pix.generated", "oneoff.payment.success", "new.sale"],
  "discounts": [
    {
      "type": "percentage",
      "value": 10,
      "paymentMethod": "pix",
      "fromCycle": 1,
      "toCycle": 3,
      "durationMonths": 3
    }
  ],
  "tokenId": "tok_abc123",
  "productId": "prod_123456_example",
  "recurrencyStartDate": "2026-10-01",
  "prorataStartDate": "2026-09-15",
  "prorataDueDate": "2026-09-20",
  "mergeWithNextCycle": false
})
};

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

Response Examples

200200
{
  "success": true,
  "customerId": "cus_xxx",
  "chargeId": "cha_abc123",
  "status": "paid"
}
402402
{
    "success": false,
    "chargeId": "cha_1784065113577_5dw2oyfic",
    "status": "failed",
    "error": "Cartão recusado"
}
400400 MISSING_CARD_DATA
{
  "error": {
    "message": "tokenId, card ou paymentMethodId é obrigatório",
    "code": "MISSING_CARD_DATA"
  }
}
404404 PRICE_NOT_FOUND
{
  "error": {
    "message": "Preço não encontrado",
    "code": "PRICE_NOT_FOUND"
  }
}
409409 DUPLICATE_CHARGE
{
  "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

Próximo →

Pagar em sandbox