Checkouts

Checkout Transparente

Você envia os dados do cliente, método de pagamento e itens diretamente pela API, sem redirecionar o usuário para uma página externa. Toda a experiência de compra acontece na sua própria interface (site, app, sistema) e envia os dados de pagamento para a ValidaPay.

Métodos de pagamento suportados: creditcard, pix, boleto

Os itens do pedido referenciam preços (priceId) previamente cadastrados via rota de produtos. Para pagamentos com cartao de crédito, os dados do cartão devem ser enviados no objeto card.

Case de uso:

Como SaaS, quero oferecer assinaturas com pagamento por cartão de crédito diretamente no meu app, sem redirecionar o usuário para outra página. Cadastro meus planos como produtos, e na hora do pagamento envio o priceId do plano escolhido junto com os dados do cartão.

Como e-commerce, quero oferecer PIX e boleto como opções de pagamento no meu próprio checkout customizado. Monto o carrinho com os priceId dos produtos, coleto os dados do cliente e processo tudo numa única chamada.

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",
  "customer": {
    "name": "Isaac Newton",
    "email": "isaac.newton@validapay.com.br",
    "documentNumber": "12345678920",
    "phone": "11975896541",
    "address": {
      "type": "BILLING",
      "street": "Rua das Flores",
      "number": "123",
      "complement": "Apto 45",
      "neighborhood": "Centro",
      "city": "Florianópolis",
      "state": "SC",
      "zipCode": "88010000",
      "country": "BR",
      "cityCode": "4205407"
    }
  },
  "card": {
    "number": "5230552482605921",
    "cvv": "100",
    "name": "Issac Newton",
    "expiration": "12/2030"
  },
  "items": [
    {
     "priceId": "price_1769679249534_3hhtbkmkj",
      "quantity": 1
    }
  ],
  "metadata": {
    "source": "website"
  }
}

Schema

Field	Type	Required	Description
paymentMethod	string	Required	[creditcard, pix, boleto]
customer	object	-	-
card	object	Optional	É obrigatório apenas quando paymentMethod: creditcard
items[1]	array	-	-
metadata	object	-	-

← Anterior

Saldo subcontas

Criar Produto

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",
  "customer": {
    "name": "Isaac Newton",
    "email": "isaac.newton@validapay.com.br",
    "documentNumber": "12345678920",
    "phone": "11975896541",
    "address": {
      "type": "BILLING",
      "street": "Rua das Flores",
      "number": "123",
      "complement": "Apto 45",
      "neighborhood": "Centro",
      "city": "Florianópolis",
      "state": "SC",
      "zipCode": "88010000",
      "country": "BR",
      "cityCode": "4205407"
    }
  },
  "card": {
    "number": "5230552482605921",
    "cvv": "100",
    "name": "Issac Newton",
    "expiration": "12/2030"
  },
  "items": [
    {
     "priceId": "price_1769679249534_3hhtbkmkj",
      "quantity": 1
    }
  ],
  "metadata": {
    "source": "website"
  }
})
};

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

Response Examples

404404

{
    "error": {
        "message": "Price price_1769550554939_2litgla99 não encontrado",
        "code": "PRICE_NOT_FOUND",
        "details": null,
        "timestamp": "2026-01-28T11:10:54.750Z"
    }
}

200200

{
    "success": true,
    "customerId": "cus_1772230075378_21n6ykyb9",
    "paymentId": "sandbox_card_17723961707554498"
}

200200

{
    "success": true,
    "customerId": "cus_1772230075378_21n6ykyb9",
    "chargeId": "cha_1772398220843_9ovrhe4po",
    "pix": {
        "emv": "00020126330014br.gov.bcb.pix01110000000000052040000530398654089.905802BR5925VALIDAPAY SANDBOX6014SAO PAULO62070503***63044BDX"
    }
}

← Anterior

Saldo subcontas

Criar Produto