Cartão salvo

O cartão é digitado uma vez, nos campos de cartão da SuyPay, e vira um card_…. A partir daí, qualquer conta conectada que aceite cartão salvo cobra esse cartão, inclusive em assinaturas. Se uma conta cair, a cobrança passa para a próxima, como no Pix e no boleto.

O número do cartão não passa pelo seu site nem pela SuyPay. Ele é digitado num quadro do cofre de cartões da SuyPay, fica guardado lá criptografado e só sai no momento da cobrança, direto para a conta. Com isso, seu site fica no nível mais simples do PCI DSS (SAQ A). Como o cofre protege o cartão está em Segurança.

1. Mostre os campos de cartão

Peça a configuração do modo em que você está (o publishable_key pode ir para o navegador):

curl https://api.suypay.com/v1/cards/config -H "Authorization: Bearer suy_test_..."

{ "vault": { "script": "https://vault.../elements/v1/suy.js", "publishable_key": "pk_test_..." } }

No seu checkout:

<script src="https://vault.../elements/v1/suy.js"></script>
<input id="holder" placeholder="Nome impresso no cartão">
<div id="card"></div>
<button id="pay">Pagar</button>
<script>
  const card = SuyPay.card({ publishableKey: 'pk_test_...' }).mount('#card')
  card.on('change', (s) => { document.querySelector('#pay').disabled = !s.complete })
  document.querySelector('#pay').onclick = async () => {
    const token = await card.tokenize()          // { id: "tok_...", card: { brand, last4, ... } }
    await fetch('/meu-backend/pagar', { method: 'POST', body: JSON.stringify({ token: token.id, holder: holder.value }) })
  }
</script>

Quem digita é o cliente: os campos de número, validade e CVV ficam dentro do quadro, e o seu código recebe só o tok_…. Para combinar com o seu site, passe style com text, muted, border, focus, error, bg (cores), radius, size e font.

Só nos seus sites

Por padrão, qualquer site consegue mostrar os campos com a sua chave pública. Diga quais são os seus, e o cofre recusa o quadro e os tokens vindos de qualquer outro (ele trava o quadro com frame-ancestors e confere a origem de cada token):

curl -X PATCH https://api.suypay.com/v1/cards/config \
  -H "Authorization: Bearer suy_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "allowed_origins": ["https://loja.com.br", "https://www.loja.com.br"] }'

Use só o começo do endereço, com https:// (no modo de teste, http://localhost também vale). A página de pagamento da SuyPay entra sozinha na lista, para os links continuarem funcionando. Uma lista vazia volta a liberar qualquer site. No painel, fica em Chaves e MCP → Campos de cartão.

2. Salve o cartão

Do seu servidor, em até 24 horas:

curl https://api.suypay.com/v1/cards \
  -H "Authorization: Bearer suy_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "vault_token": "tok_...", "holder_name": "ANA LIMA", "customer": { "name": "Ana Lima", "document": "52998224725" } }'

{
  "id": "card_4Fh...",
  "object": "card",
  "brand": "visa",
  "last4": "1111",
  "exp_month": 12,
  "exp_year": 2030,
  "holder_name": "ANA LIMA",
  "fingerprint": "Xk2...",
  "cvc_available_until": "2026-10-19T18:30:00.000Z"
}

O fingerprint é igual para o mesmo número de cartão, mesmo em clientes diferentes. Use para achar cartões repetidos.

3. Cobre

{
  "method": "card",
  "amount": 25000,
  "card": { "id": "card_4Fh...", "installments": 3 },
  "customer": { "name": "Ana Lima", "document": "52998224725", "email": "ana@exemplo.com" }
}

Cobrar cartão salvo exige uma chave completa: uma chave restrita só de cobranças não cobra cartão salvo, porque isso cobra o cliente sem ele estar presente.

CVV

O CVV fica guardado só até a primeira aprovação e no máximo 1 hora. É a regra do PCI DSS. O campo cvc_available_until diz até quando ele existe.

• Algumas contas pedem o CVV na primeira cobrança do cartão nelas. Depois, a própria conta guarda o cartão e as cobranças seguintes vão sem CVV. A SuyPay lembra disso por conta.
• Passado o prazo, a SuyPay pula as contas que ainda precisariam do CVV e usa as outras. Se nenhuma servir, a cobrança falha com account_not_enabled e a mensagem explica.

Por isso, cobre a primeira vez logo depois de salvar, enquanto o cliente está no checkout.

Quais contas cobram cartão salvo

Apagar

DELETE /v1/cards/{id} apaga o cartão também do cofre. Nenhuma conta consegue mais cobrar esse cartão pela SuyPay. Um cartão que paga uma assinatura ativa só pode ser apagado depois que a assinatura for cancelada.

Link de pagamento

No link de pagamento, quando alguma conta aceita cartão salvo, o cliente digita o cartão nos campos da SuyPay, ali mesmo na página. O cartão fica salvo no cliente da cobrança, com metadata.source = "payment_link".