Link de pagamento

Criar link

POST /api/v2/checkout no API Gateway cria a cobrança e devolve o link de pagamento.

POST /api/v2/checkout

Scope: checkout.write

Cria uma cobrança no API Gateway e devolve checkout_url, a URL do link de pagamento. Envie essa URL ao pagador. Não chame o host da Minha Conta.

Valores monetários vão em centavos (15000 = R$ 150,00).

Curl

O exemplo abaixo é uma cobrança com itens. A soma das linhas é 2 × 5000 = 10000, então amount é 10000. O frete não entra nessa conferência.

curl -X POST 'https://api-h.nuvende.com.br/api/v2/checkout' \
  -H 'Authorization: Bearer {{access_token}}' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
  "reference_id": "PEDIDO-123",
  "amount": 10000,
  "due_date": "2026-09-20",
  "description": "Pedido loja 123",
  "observations": "Entregar após a confirmação do pagamento",
  "shipping_fee": 1500,
  "discount": {
    "type": "VALUE",
    "value": 0
  },
  "late_fee": 2.0,
  "interest_rate": 1.0,
  "payment_methods": [
    { "type": "PIX" },
    { "type": "BOLETO" },
    { "type": "CREDIT", "max_installments": 12 }
  ],
  "items": [
    {
      "code": "SKU-CAMISETA-M",
      "name": "Camiseta M",
      "description": "Algodão",
      "quantity": 2,
      "unit_amount": 5000
    }
  ],
  "customer": {
    "name": "Maria Silva",
    "tax_id": "00000000000",
    "email": "[email protected]",
    "phone": "11999999999",
    "address": {
      "postal_code": "01310100",
      "street": "Av. Paulista",
      "number": "1000",
      "complement": "Sala 1",
      "neighborhood": "Bela Vista",
      "city": "São Paulo",
      "state": "SP"
    }
  },
  "redirect_url": "https://loja.exemplo/retorno",
  "notification_url": "https://loja.exemplo/hooks/checkout",
  "notification_secret": "{{notification_secret}}"
}'

Cobrança só por valor, sem itens: omita items e envie amount. Com BOLETO, o endereço do cliente continua obrigatório.

Resposta

201 na primeira criação. status é PENDING.
200 se você repetir o mesmo reference_id com o mesmo pedido (os mesmos campos de negócio, inclusive URLs e segredo). O id não muda.
409 se o mesmo reference_id já existir nesta conta com qualquer diferença. Nada é atualizado.

{
  "id": "018f1b2c-3d4e-7a89-b012-3456789abcde",
  "reference_id": "PEDIDO-123",
  "status": "PENDING",
  "type": "SMART",
  "amount": 10000,
  "due_date": "2026-09-20",
  "payment_methods": [
    { "type": "PIX" },
    { "type": "BOLETO" },
    { "type": "CREDIT", "max_installments": 12 }
  ],
  "customer": {
    "name": "Maria Silva",
    "tax_id": "00000000000",
    "email": "[email protected]"
  },
  "items": [
    { "code": "SKU-CAMISETA-M", "name": "Camiseta M", "quantity": 2, "unit_amount": 5000 }
  ],
  "checkout_url": "https://pagamento-h.nuvende.com.br/018f1b2c-3d4e-7a89-b012-3456789abcde",
  "links": [
    { "rel": "SELF", "href": "/api/v2/checkout/018f1b2c-3d4e-7a89-b012-3456789abcde", "method": "GET" },
    { "rel": "PAY", "href": "https://pagamento-h.nuvende.com.br/018f1b2c-3d4e-7a89-b012-3456789abcde", "method": "GET" },
    { "rel": "INACTIVATE", "href": "/api/v2/checkout/018f1b2c-3d4e-7a89-b012-3456789abcde/inactivate", "method": "POST" }
  ]
}

Sem itens, type é UNIQUE e items vem vazio. checkout_url é a página do pagador, não o host do Gateway. Em homologação essa página costuma ser pagamento-h.nuvende.com.br. Use sempre o valor devolvido. O exemplo acima chama o Gateway de homologação (api-h). Em produção, o mesmo path fica em https://api.nuvende.com.br.

Glossário

Campo	Obrigatório	Descrição
`reference_id`	Sim	Identificador do pedido no seu sistema. Na mesma conta, repetir o mesmo conjunto devolve o link existente. Qualquer diferença devolve `409`.
`amount`	Sem itens, sim	Total em centavos. Com itens, se enviado, deve ser igual à soma `quantity × unit_amount` das linhas. Frete e desconto não entram nessa soma.
`due_date`	Sim	Vencimento `YYYY-MM-DD`.
`description`	Não	Nome curto da cobrança.
`observations`	Não	Texto livre, até 550 caracteres. Aparece na descrição de Pix e boleto.
`shipping_fee`	Não	Frete em centavos. Soma no valor cobrado.
`discount.value`	Não	Desconto em centavos. É o valor que reduz o total.
`discount.percentage`	Não	Percentual informativo. Sozinho não reduz o total nesta versão.
`discount.deadline`	Não	Data do desconto. Não altera o valor cobrado nesta versão.
`conditional_discount.value`	Não	Desconto em centavos se o pagamento ocorrer até `expiration_date`.
`conditional_discount.expiration_date`	Não	Data `YYYY-MM-DD`.
`late_fee`	Não	Multa em percentual, de `0` a `2`. Não é centavo. Vale para Pix e boleto, não para cartão.
`interest_rate`	Não	Juros em percentual, de `0` a `1`. Não é centavo. Vale para Pix e boleto, não para cartão.
`payment_methods`	Sim, ao menos um	`PIX`, `BOLETO` e/ou `CREDIT`.
`payment_methods[].max_installments`	Se `CREDIT`	Parcelas máximas, de 1 a 12.
`items`	Não	Omitido ou `[]` gera `type` `UNIQUE`. Com itens, `type` `SMART`.
`items[].code`	Se houver item	SKU na sua conta. O mesmo código atualiza o produto, não cria outro.
`items[].name`	Se houver item	Nome do produto.
`items[].quantity`	Se houver item	Inteiro maior ou igual a 1.
`items[].unit_amount`	Se houver item	Preço unitário em centavos.
`customer.name`	Sim	Nome do pagador.
`customer.tax_id`	Sim	CPF ou CNPJ. Na mesma conta, o documento atualiza o cadastro existente.
`customer.address`	Com boleto, sim	Obrigatório se algum método for `BOLETO`.
`redirect_url`	Não	URL `https` absoluta. O pagador volta para ela só depois de pagar. Host livre, sem cadastro prévio de domínio.
`notification_url`	Não	URL `https` pública. Recebe um POST quando o status fica `PAID`.
`notification_secret`	Não	Se informado, o POST usa `Authorization: Bearer` com esse valor. Não volte esse segredo em link nem em log.

account_id no corpo é ignorado. Não envie Account-Id, Application-Id, Partner-Id, seller-id nem HMAC. Esses headers, quando existem, o Gateway coloca.

Cliente e itens: Cliente e itens. Depois de criar: Consultar.

Autenticação

Consultar link

GET /api/v2/checkout/{id} no API Gateway devolve o link da conta autenticada.