Checkouts

Checkout Transparente

Cria uma sessao de pagamento via checkout transparente. Voce envia os dados do cliente, metodo de pagamento e itens diretamente pela API, sem redirecionar o usuario para uma pagina externa. Toda a experiencia de compra acontece na sua propria interface.

Metodos de pagamento suportados: creditcard, pix, boleto

Os itens do pedido referenciam precos (priceId) previamente cadastrados via rota de produtos. Para pagamentos com cartao de credito, os dados do cartao devem ser enviados no objeto card.

Case de uso:

Como SaaS, quero oferecer assinaturas com pagamento por cartao de credito diretamente no meu app, sem redirecionar o usuario para outra pagina. Cadastro meus planos como produtos, e na hora do pagamento envio o priceId do plano escolhido junto com os dados do cartao.

Como e-commerce, quero oferecer PIX e boleto como opcoes de pagamento no meu proprio checkout. Monto o carrinho com os priceId dos produtos, coleto os dados do cliente e envio tudo numa unica chamada

POST/v1/charge

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

Listar cobranças

Criar Produto

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

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,
    "subscriptionId": "sub_1772276504666_egn1a6rod",
    "customerId": "cus_1772230075378_21n6ykyb9",
    "clientName": "User teste2",
    "clientDocument": "00896589644",
    "status": "TRIALING",
    "paymentMethod": "creditcard",
    "invoiceId": "inv_1772276504826_kb0fpd2ft",
    "chargeId": "cha_1772276504906_4w7c2646e",
    "paymentId": "sandbox_card_trial_17722765049058102",
    "trial": {
        "days": 7,
        "startDate": "2026-02-28T11:01:44.208Z",
        "endDate": "2026-03-07T11:01:44.208Z"
    },
    "currentCycle": {
        "number": 0,
        "amount": 0,
        "status": "trialing"
    },
    "nextCycle": {
        "number": 1,
        "amount": 400,
        "chargeDate": "2026-03-07T11:01:44.208Z",
        "freeTrial": true
    },
    "priceSchedulePreview": [
        "C1:R$400.00",
        "C2:R$400.00",
        "C3:R$400.00",
        "C4:R$400.00"
    ]
}

← Anterior

Listar cobranças

Criar Produto