Checkout hospedado

Visão geral

1. Sua loja chama POST /checkouts com a Connect Key e recebe id, url e links.
2. Redirecione o comprador para url (ou links com rel: PAY).
3. A página hospedada coleta dados e processa o pagamento. Sua loja é avisada via notification_urls (webhook).

Valores em centavos (7900 = R$ 79,00). Create com sucesso = HTTP 201.

reusable: false (padrão) fecha a sessão no primeiro pagamento. reusable: true gera um pedido novo a cada pagamento.

Autenticação

Todos os endpoints abaixo usam Authorization: Bearer {connectKey}.

• Prefixo CONVD… / CONVDSANDBOX… → API v1 (Vindi).
• Keys CON… / CONSANDBOX… (PagBank) não autenticam nesta API v1.

Validação rápida: GET https://api.pbintegracoes.com/v1/connectInfo com o mesmo Bearer.

curl -sS 'https://api.pbintegracoes.com/v1/connectInfo' \
  -H "Authorization: Bearer $CONNECT_KEY" \
  -H "Accept: application/json"

Endpoints (lojista)

A página hospedada usa rotas internas (tokenização, parcelas, frete, pagamento). Sua integração não precisa chamá-las — basta criar a sessão e enviar o comprador para url.

POST /checkouts

POSThttps://api.pbintegracoes.com/v1/checkouts→ 201

Cria a sessão e devolve o link de pagamento.

Body

Exemplo

{
  "reference_id": "pedido-1001",
  "customer_modifiable": true,
  "customer": {
    "name": "Maria Silva",
    "email": "maria@example.com",
    "tax_id": "39053344705",
    "phone": "11999990000",
    "address": {
      "street": "Avenida Brigadeiro Faria Lima",
      "number": "1384",
      "complement": "cj 12",
      "locality": "Pinheiros",
      "city": "São Paulo",
      "region_code": "SP",
      "country": "BRA",
      "postal_code": "01452002"
    }
  },
  "items": [
    {
      "reference_id": "sku-1",
      "name": "Camiseta",
      "quantity": 1,
      "unit_amount": 7900,
      "image_url": "https://loja.example/produtos/camiseta.jpg"
    }
  ],
  "discount_amount": 0,
  "shipping": {
    "type": "FIXED",
    "service_type": "SEDEX",
    "amount": 1234,
    "estimated_delivery_time_in_days": 5,
    "address_modifiable": true
  },
  "payment_methods": [
    { "type": "CREDIT_CARD" },
    { "type": "PIX" },
    { "type": "BOLETO" }
  ],
  "payment_methods_configs": [
    {
      "type": "credit_card",
      "config_options": [
        { "option": "INSTALLMENTS_LIMIT", "value": "12" },
        { "option": "INTEREST_FREE_INSTALLMENTS", "value": "3" }
      ]
    }
  ],
  "notification_urls": ["https://loja.example/webhook"],
  "return_url": "https://loja.example/pedido/obrigado",
  "cancel_url": "https://loja.example/pedido/cancelado",
  "reusable": false,
  "branding": {
    "name": "Loja Exemplo",
    "theme": "painel",
    "colors": ["#171717", "#171717", "#f5f5f4", "#171717", "#ffffff"],
    "font": "inter",
    "logo_url": "https://loja.example/logo.png"
  },
  "extras": {
    "summary_background_image": "https://loja.example/bg.jpg"
  },
  "analytics": {
    "ga4_measurement_id": "G-XXXXXXXX"
  }
}

curl -sS -X POST 'https://api.pbintegracoes.com/v1/checkouts' \
  -H "Authorization: Bearer $CONNECT_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d @checkout-session.json

Resposta e links

{
  "id": "chk_…",
  "url": "https://checkout.pbintegracoes.com/c/chk_…",
  "status": "OPEN",
  "expires_at": null,
  "expiration_date": null,
  "links": [
    {
      "rel": "SELF",
      "href": "https://api.pbintegracoes.com/v1/checkouts/chk_…",
      "method": "GET"
    },
    {
      "rel": "PAY",
      "href": "https://checkout.pbintegracoes.com/c/chk_…",
      "method": "GET"
    },
    {
      "rel": "INACTIVATE",
      "href": "https://api.pbintegracoes.com/v1/checkouts/chk_…/inactivate",
      "method": "POST"
    }
  ]
}

url é a página do comprador. Os links trazem rel, href e method:

Diferente do PagBank: aqui SELF é a API e PAY é o checkout. Não trate as duas URLs como iguais.

GET /checkouts/{id}

GEThttps://api.pbintegracoes.com/v1/checkouts/{id}→ 200

Com Bearer: status, order_ids, notification_urls, url e links. Útil para acompanhar se a sessão ainda está OPEN ou já gerou pedidos.

POST /checkouts/{id}/inactivate

POSThttps://api.pbintegracoes.com/v1/checkouts/{id}/inactivate→ 200

Fecha a sessão. Resposta: { "id", "status": "INACTIVE" }.

POST /subscriptions/{id}/cancel

POSThttps://api.pbintegracoes.com/v1/subscriptions/{id}/cancel→ 200

Cancela assinatura criada por um checkout com recurrence. Id no formato sub_….

Cobrança vs entrega

No create, customer.address é o endereço de cobrança (prefill). Não existe billing_address separado. O endereço de entrega, quando houver frete, é tratado na página hospedada.

Frete no create (shipping)

Configure no body do POST /checkouts:

address_modifiable (default true): se false, shipping.address é obrigatório.

Snapshot canônico: após o pagamento, GET /checkouts/{id}, o order do complete e os webhooks devolvem o frete efetivo (address de entrega, amount, type, service_type/provider/method) — seja FIXED do create ou CALCULATE cotado na página. No complete, com frete físico envie shipping.address (entrega); customer.address continua sendo cobrança.

Compatibilidade: quote: "envio_facil" → CALCULATE; só amount (sem type) → FIXED.

Parcelas no create

Defina limites em payment_methods_configs. A página hospedada calcula e exibe as opções ao comprador.

{
  "type": "credit_card",
  "config_options": [
    { "option": "INSTALLMENTS_LIMIT", "value": "12" },
    { "option": "INTEREST_FREE_INSTALLMENTS", "value": "3" }
  ]
}

• INSTALLMENTS_LIMIT — máx. 1–12 (default 12).
• INTEREST_FREE_INSTALLMENTS — 0 ou ≥ 2; nunca 1.

Branding e extras

Recorrência

Só cartão. interval.unit = MONTH ou YEAR com length: 1. billing_cycles opcional.

{
  "name": "Assinatura mensal",
  "interval": { "unit": "MONTH", "length": 1 },
  "billing_cycles": 12
}

A primeira cobrança fica na página hospedada; renovações são cobradas pelo job da PB. Cancele com POST /subscriptions/{id}/cancel.