> ## Documentation Index
> Fetch the complete documentation index at: https://nexus-docs.ticto.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Tokenizar cartão

> Como obter o card_code exigido pelo checkout com cartão de crédito sem que o número do cartão passe pelo seu servidor.

O `POST /financial/checkout` com `payment_method: credit_card` **não aceita o número do cartão**. Ele exige um `card_code`, gerado pelo **Icarus**, o serviço de tokenização de front-end da Ticto. O Icarus roda no browser do comprador: captura os dados do cartão, criptografa com o SDK da adquirente, grava o cartão tokenizado no core de pagamentos da Ticto e devolve apenas um código opaco. O PAN e o CVV nunca chegam ao seu backend, o que mantém sua integração fora do escopo PCI-DSS.

<Steps>
  <Step title="Carregue o script na sua página de checkout">
    ```html theme={null}
    <script src="https://icarus.ticto.dev/embed/tokenize.js" async></script>
    ```

    Quando o script termina de inicializar, ele expõe `window.Ticto` e dispara o evento `ticto:ready`. Aguarde esse evento antes de chamar qualquer função.
  </Step>

  <Step title="Informe a origem Nexus">
    ```javascript theme={null}
    window.Ticto.setOrigin('nexus');
    ```

    Isso faz o core de pagamentos vincular o comprador e o cartão ao seu cliente de API. Sem essa chamada o cartão é gravado com origem padrão e pode não ser encontrado no checkout.
  </Step>

  <Step title="Tokenize o cartão">
    Chame `window.Ticto.encryptCard` com os dados do cartão, do titular e do comprador, mais o `offer_code` da oferta que será cobrada. O código da oferta define quais adquirentes o produtor tem habilitadas.

    ```javascript theme={null}
    const result = await window.Ticto.encryptCard({
      cardData: {
        holder: "NOME IMPRESSO NO CARTAO",
        number: "4111111111111111",
        expMonth: "12",
        expYear: "2030",
        securityCode: "123"
      },
      cardholder: {
        name: "Nome do titular",
        email: "comprador@exemplo.com.br",
        identification: { type: "CPF", number: "<cpf_valido>" }
      },
      customerData: {
        name: "Nome do comprador",
        email: "comprador@exemplo.com.br",
        cpf: "<cpf_valido>",
        cnpj: "",
        type: "person",
        is_foreign: false
      },
      offerCode: "<offer_code>"
    });
    ```
  </Step>

  <Step title="Use o card_code no checkout">
    Em caso de sucesso o retorno é `{ code, customer_code }`. Envie `code` como `card_code` no `POST /financial/checkout`. O `customer_code` pode substituir o objeto `customer`, já que o comprador foi criado durante a tokenização.

    ```json theme={null}
    {
      "offer_code": "<offer_code>",
      "payment_method": "credit_card",
      "installments": 1,
      "customer_code": "<customer_code retornado pelo Icarus>",
      "card_code": "<code retornado pelo Icarus>"
    }
    ```
  </Step>
</Steps>

## Parâmetros de `encryptCard`

Todos os campos de cartão devem ser enviados como **string**, inclusive número, mês, ano e CVV.

<ParamField body="cardData.holder" type="string" required>
  Nome impresso no cartão.
</ParamField>

<ParamField body="cardData.number" type="string" required>
  Número do cartão, só dígitos.
</ParamField>

<ParamField body="cardData.expMonth" type="string" required>
  Mês de validade com dois dígitos. Ex.: `"12"`.
</ParamField>

<ParamField body="cardData.expYear" type="string" required>
  Ano de validade. Ex.: `"2030"`.
</ParamField>

<ParamField body="cardData.securityCode" type="string" required>
  CVV.
</ParamField>

<ParamField body="cardholder.name" type="string" required>
  Nome do titular.
</ParamField>

<ParamField body="cardholder.email" type="string">
  E-mail do titular. Se omitido, o Icarus usa `customerData.email`.
</ParamField>

<ParamField body="cardholder.identification" type="object" required>
  `{ type: "CPF" | "CNPJ", number: "<documento>" }`.
</ParamField>

<ParamField body="customerData" type="object" required>
  Dados do comprador usados para criar o cliente no core de pagamentos: `name`, `email`, `cpf`, `cnpj`, `type` (`person` ou `company`) e `is_foreign` (boolean). Envie `cpf` ou `cnpj` e deixe o outro como string vazia.
</ParamField>

<ParamField body="offerCode" type="string" required>
  Código da oferta que será cobrada. Alternativa: `userCode` com o `code` do produtor. Pelo menos um dos dois é obrigatório.
</ParamField>

## Retorno

<ResponseField name="code" type="string">
  Código do cartão tokenizado. É o `card_code` do checkout.
</ResponseField>

<ResponseField name="customer_code" type="string">
  Código do comprador criado ou reaproveitado no core de pagamentos. Pode ser enviado como `customer_code` no checkout.
</ResponseField>

<ResponseField name="errors" type="array">
  Presente apenas em falha. Lista de objetos `{ message }`. Quando existe, `code` não vem.
</ResponseField>

```javascript theme={null}
if (result.errors?.length) {
  // exiba result.errors[0].message ao comprador
  return;
}
const cardCode = result.code;
```

## Cartões de teste do tokenizador

No ambiente de testes o Icarus usa a adquirente em modo sandbox. Use titular `APRO`, validade futura, CVV `123` e um CPF válido algoritmicamente:

| Bandeira | Número |
| - | - |
| Visa | `4111 1111 1111 1111` |
| Mastercard | `5555 5555 5555 4444` |
| Elo | `6362 9700 0045 7013` |

<Warning>
  O script deve ser carregado diretamente do domínio da Ticto e executado no browser do comprador. Não faça proxy do script nem envie os dados do cartão para o seu servidor para chamar o Icarus de lá: isso quebra a premissa PCI-DSS da integração.
</Warning>

<Note>
  O checkout também aceita o campo `card_token`, um formato legado (JSON em base64 com tokens PagSeguro e MercadoPago gerados pelo próprio parceiro). Novas integrações devem usar `card_code` via Icarus.
</Note>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.