# Upsell em um clique

> Cobrar um segundo produto sem pedir o cartão de novo: o campo one_click_from, a resposta one_click e o que fazer quando ela vem false.

Fonte: https://app.thronecorporate.com/docs/cartao/oneclick

## O que é

Depois que o comprador paga uma venda de cartão, você pode oferecer um segundo produto e cobrar **sem pedir o cartão de novo**. É o upsell: o comprador vê o cartão que ele já usou, confirma e pronto.

Funciona com o mesmo `POST /elements/checkout` e o mesmo Throne Elements que você já usa. **Um campo novo** na criação, e nada mais muda: campos, respostas, erros, moedas, webhook e o elemento na página continuam iguais.

> [!NOTE]
> Nada a mudar no que já está no ar. Sem o campo novo, o checkout é o de hoje. O upsell é uma página nova do seu funil, não uma alteração nas suas páginas atuais.

## Antes de começar

O upsell em um clique é **habilitado por conta**, uma a uma, pelo time do Throne. Enquanto a sua conta não estiver habilitada, o campo é aceito, a resposta vem `one_click: false` e o comprador digita o cartão.

Vale também para o passado: só serve de origem uma venda paga **depois** de a sua conta ser habilitada.

Para pedir a habilitação, fale com o suporte.

## Como funciona, em três passos

**1. A primeira venda é a de sempre.** Você cria o checkout, o comprador paga, e você recebe o `transaction_id` no `201` e o `transaction.paid` no webhook.

**2. Na página de upsell, crie o checkout com `one_click_from`.** O valor é o `transaction_id` da venda que acabou de ser paga:

```bash
curl -X POST https://app.thronecorporate.com/api/v1/elements/checkout \
  --max-time 60 \
  -H "Authorization: Bearer $THRONE_PK:$THRONE_SK" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "amount_cents": 9700,
    "currency": "brl",
    "one_click_from": "a1b2c3d4-e5f6-4789-abcd-ef0123456789"
  }'
```

**3. Olhe o campo `one_click` na resposta.**

```json
{
  "transaction_id": "9f8e7d6c-5b4a-4321-9876-543210fedcba",
  "status": "pending",
  "checkout_url": "https://pay.example.com/checkout/7a6b5c4d3e2f10998877665544332211",
  "acquirer": "apex",
  "one_click": true,
  "one_click_card": { "brand": "mastercard", "last4": "2006" }
}
```

Com `one_click: true`, o elemento abre mostrando o cartão terminado em 2006 e um botão. Com `one_click: false`, ele abre o formulário de sempre e o comprador digita o cartão. **Nos dois casos a venda acontece**, e o seu código é o mesmo: você pode usar `one_click_card` para escrever na sua página algo como "confirmar no cartão terminado em 2006".

Os dois campos novos aparecem **só** quando você envia `one_click_from`. Sem ele, a resposta não ganha chave nenhuma.

## Quando `one_click` vem `false`

Nunca é erro, nunca é `4xx`: o checkout nasce normal e o comprador paga digitando. Acontece quando:

| Motivo | Detalhe |
|---|---|
| O upsell não está habilitado na sua conta | Habilitação por conta, pelo suporte |
| A venda citada não é da sua conta | Só o `transaction_id` de uma venda sua funciona, e o uso cruzado fica registrado |
| O valor não tem a forma de um `transaction_id` | Texto fora do formato, dentro dos 64 caracteres, não vira erro: vira `false` |
| A venda não está paga | Pendente, recusada, estornada ou contestada não serve |
| A venda de origem não tem cartão guardado | A origem tem de ser uma venda em que o comprador digitou o cartão. Upsell pago em um clique e cobrança de recorrência não deixam cartão guardado |
| Passou da janela | Padrão de **120 minutos** contados do pagamento |
| Teto de upsells atingido | Até **5** por venda paga. Checkout que morreu sem cobrar (recusado ou expirado) não ocupa vaga |
| Adquirente diferente | O upsell precisa cair na mesma adquirente da venda de origem |
| O comprador declarado é outro | Quando você envia `customer` no upsell, ele tem de ser a mesma pessoa da venda de origem |

Por isso: **escreva a sua página de upsell para funcionar nos dois casos.** Mostre o botão quando vier `true` e o elemento comum quando vier `false`.

> [!WARNING]
> O `customer` do upsell, quando enviado, tem de ser o mesmo comprador da venda de origem. É o que impede cobrar o cartão guardado de uma pessoa numa venda de outra, dentro da mesma conta. O caminho mais simples é **não** enviar `customer` no upsell: os dados vêm da venda de origem.

## O que o comprador vê

Com `one_click: true`, o elemento mostra o produto, o valor, a bandeira com os quatro últimos dígitos e um botão. Há também um link discreto para usar outro cartão, que abre o formulário completo na mesma tela.

Em alguns casos o banco pede o **código de segurança** para confirmar a recompra. Quando isso acontece, o elemento mostra um campo de três dígitos (quatro no Amex) abaixo do cartão, e o comprador confirma ali mesmo. Continua sem digitar número, validade ou nome, e **nenhuma tentativa é gasta** quando o código é pedido.

Quando o cartão guardado não serve mais no momento do clique, o formulário de sempre volta sozinho, sem aviso e sem gastar tentativa: para o comprador, nada aconteceu.

## Eventos na sua página

Os mesmos de sempre, sem evento novo: `throne-elements:ready`, `throne-elements:paid`, `throne-elements:error` e `throne-elements:resize`. Veja [Throne Elements](/docs/cartao/elements).

## Perguntas que aparecem sempre

**Preciso guardar o cartão do meu cliente?** Não. Você não recebe, não guarda e não manuseia dado de cartão em nenhum momento. Quem cuida disso é o Throne, e o que você usa é só o `transaction_id` da venda anterior, que você já tem.

**E se o comprador tiver fechado a aba entre a compra e o upsell?** Enquanto estiver dentro da janela de 120 minutos e você mandar o `one_click_from` certo, funciona. O reconhecimento não depende de cookie nem de sessão no navegador.

**Posso usar o mesmo `one_click_from` em dois upsells?** Sim, até 5 por venda paga. Cada um é uma venda independente, com o seu próprio `transaction_id` e o seu próprio webhook.

**Dá para fazer upsell de upsell?** Sim, mas a origem continua sendo a venda em que o comprador digitou o cartão: use sempre o `transaction_id` **dela** em `one_click_from`, inclusive no segundo e no terceiro upsell, dentro dos 120 minutos e do teto de 5. O `transaction_id` de um upsell pago em um clique não serve de origem: a resposta vem `one_click: false`.

**A janela conta do primeiro pagamento ou do último?** Do pagamento da venda que você citou em `one_click_from`.

**O valor pode ser diferente da primeira venda?** Sim, é uma venda nova: valor, moeda e produto são seus.

**O que aparece no extrato do comprador?** Duas cobranças separadas, com o mesmo descritor das suas vendas de cartão.

**Serve para Pix?** Não. O Pix não tem o que guardar: cada cobrança é um QR Code novo. O campo é aceito com um `transaction_id` de Pix, mas a resposta vem `one_click: false`.

## Em quais adquirentes funciona

No `POST /elements/checkout`, o campo `one_click_from` pode ser enviado sempre, em qualquer adquirente de cartão: o que muda é a resposta. No [Checkout Brasil](/docs/cartao/brasil), ele não existe e volta `422 field_not_supported`. Neste endpoint o um clique está disponível na **Apex**; nas outras, o campo é aceito e `one_click` volta `false`, sem erro. Consulte `GET /elements/acquirers` para ver o que a sua conta tem habilitado.

**Na Vortex o um clique existe por uma rota própria**, dentro da integração direta: o [`POST /api/v1/vortex/upsell`](/docs/cartao/vortex-direto#upsell-em-um-clique). Ele não usa `one_click_from` nem `card_token`, cobra o cartão guardado da venda de origem e pode ele mesmo ser recorrente. Precisa estar liberado na conta, à parte da integração direta.

Com roteamento de adquirente fixado na sua conta, o upsell cai na mesma adquirente de tudo o que você vende, e é justamente o caso em que ele acende sozinho.

## Referência do campo

| Campo | Onde | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `one_click_from` | corpo do `POST /elements/checkout` | string, até 64 caracteres | não | `transaction_id` de uma venda sua, paga, da mesma adquirente |
| `one_click` | resposta `201` | booleano | só quando `one_click_from` foi enviado | o checkout abre em um clique |
| `one_click_card` | resposta `201` | objeto | só quando `one_click` é `true` | `brand` e `last4`, para a sua página |

Veja também [Recorrência](/docs/cartao/recorrencias), para a cobrança que se repete sozinha.