Upsell em um clique

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.

Nota 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:

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.

{
  "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:

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.

Atenção 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.

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, 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. 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#

Veja também Recorrência, para a cobrança que se repete sozinha.