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

# Tokenização

A tokenização com Localpayment oferece uma maneira segura de lidar com informações de cartão, reduzindo seus riscos de segurança e simplificando transações futuras.

## Como funciona

O processo envolve estas etapas principais:

1. **Coleta de informações do cartão**: As informações do cartão são coletadas com segurança por meio de um formulário em seu aplicativo e, em seguida, transmitidas para a API Localpayment.
2. **Geração de token**: O Localpayment armazena com segurança as informações do cartão e gera um token único e irreversível que representa os dados do cartão. Esse token é retornado na resposta da API.
3. **Uso do cartão tokenizado**: Para pagamentos subsequentes com cartão, você enviará a propriedade `card.token` em vez dos dados reais do cartão do cliente.

***

## Antes de começar

Antes de tokenizar um cartão, certifique-se de ter concluído o seguinte:

> [card] [Credenciais da API](https://docs.localpayment.com/pt-br/docs/api-keys-and-environments.md)
>
> Credenciais de API e token de acesso válidos para autenticação.

> [card] [Configuração da conta](https://docs.localpayment.com/pt-br/docs/make-your-first-test-payment.md)
>
> Configuração adequada da conta para o país de destino e verificação da empresa.

> [card] [Lista branca de IPs](https://docs.localpayment.com/pt-br/docs/dashboard-whitelist-your-ips.md)
>
> Adicione os endereços IP do seu servidor à lista de permissões para acesso à API.

> [card] [Endpoint do webhook](https://docs.localpayment.com/pt-br/docs/webhooks.md)
>
> Configure um URL de webhook para receber notificações de pagamento.

***

## Métodos de tokenização

Existem dois métodos disponíveis para tokenizar um cartão:

* [Endpoint para tokenização de cartões](#option-1-endpoint-for-card-tokenization)
* [Tokenização do cartão durante o pagamento](#option-2-card-tokenization-during-payment)

### Opção 1: Endpoint para tokenização de cartões

Você pode tokenizar com segurança as informações do cartão para uso futuro por meio de um endpoint dedicado.

Para tokenizar um cartão, envie uma requisição `POST` para o endpoint [Tokenize Card](https://docs.localpayment.com/pt-br/reference/tokenize-card.md) com os seguintes parâmetros:

| Parâmetro | Descrição | Obrigatório |
| - | - | - |
| `name` | Nome do Titular. | ✅ |
| `number` | Número do cartão. | ✅ |
| `cvv` | Valor de verificação do cartão. | ✅ |
| `expirationMonth` | Mês de vencimento do cartão. | ✅ |
| `expirationYear` | Ano de validade do cartão. | ✅ |

#### Exemplo de solicitação

```bash curl theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
curl --request POST \
     --url https://api.stage.localpayment.com/api/card \
     --header 'Authorization: Bearer <your_access_token>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "name": "John Doe",
  "number": "4000000000000002",
  "cvv": "123",
  "expirationMonth": "11",
  "expirationYear": "2029"
}
'
```

#### Exemplo de resposta bem-sucedida

Em resposta, a API retorna o token do cartão:

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "card": {
    "token": "xsWMaLcYjS3L11aBwxl465%2F2d8J85FXPAaBFIKfr0Fx%3D",
    "bin": "400000",
    "brand": "VISA",
    "country": "US",
    "name": "John Doe",
    "last4": "0002",
    "expirationYear": 2029,
    "expirationMonth": 11
  },
  "errors": []
}
```

#### Campos de resposta principais

| Campo | Descrição |
| - | - |
| `card.token` | Cartão tokenizado. |

### Opção 2: Tokenização do cartão durante o pagamento

A Localpayment permite que os comerciantes tokenizem cartões durante o [processamento do pagamento](https://docs.localpayment.com/pt-br/docs/one-time-payments.md)  incluindo o parâmetro `save` nas requisições de pagamento. Essa abordagem simplificada permite processar uma transação e armazenar os dados do cartão em uma única chamada de API.

Para tokenizar um cartão, envie uma requisição `POST` para o endpoint [Criar Payin](https://docs.localpayment.com/pt-br/reference/payins.md) e inclua a propriedade `card.save` definida como `true` na sua requisição de Payin.

#### Exemplo de solicitação

```bash curl theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
curl --request POST \
  --url https://api.stage.localpayment.com/api/payin/ \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_access_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "paymentMethod": {
        "type": "CreditCard",
        "code": "1600",
        "flow": "DIRECT"
    },
    "externalId": "dffbd2a6-6e65-469b-8bbe-dac269882220",
    "country": "MEX",
    "currency": "MXN",
    "amount": 1000,
    "accountNumber": "{{accountNumber}}",
    "conceptCode": "0001",
    "merchant": {
        "type": "COMPANY",
        "name": "Company",
        "document": {
            "type": "RFC",
            "id": "XXX840510XX1"
        },
        "email": "mail@company.com"
    },
    "payer": {
        "type": "INDIVIDUAL",
        "name": "John",
        "lastname": "Doe",
        "document": {
            "type": "RFC",
            "id": "YYY180222YY6"
        },
        "email": "john.doe@example.com"
    },
    "card": {
        "number": "4000000000000002",
        "cvv": "123",
        "expirationMonth": "12",
        "expirationYear": "2029",
        "save": true
    }
}'
```

#### Exemplo de resposta bem-sucedida

Em resposta, a API retorna o token do cartão:

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "transactionType": "PayIn",
  "externalId": "dffbd2a6-6e65-469b-8bbe-dac269882220",
  "internalId": "22b29c98-92af-44bd-a164-1863ae2f1bb3",
  "paymentMethod": {
    "type": "CreditCard",
    "code": "1000",
    "flow": "DIRECT"
  },
  "country": "MEX",
  "currency": "MXN",
  "amount": 1000,
  "accountNumber": "{{accountNumber}}",
  "confirmed": {
    "currency": "MXN",
    "amount": 1000,
    "fxQuote": 1,
    "exchangeRateToken": null
  },
  "payment": {
    "installment": null,
    "currency": "MXN",
    "fxQuote": 1,
    "financingFee": 0,
    "amount": 1000
  },
  "localTaxes": [],
  "withHoldings": [],
  "fees": {
    "description": "Fee",
    "currency": "MXN",
    "fxSource": 210.8,
    "fxQuote": 1,
    "amount": 13.02,
    "account": "{{accountNumber}}"
  },
  "status": {
    "code": "103",
    "description": "APPROVED",
    "detail": "The payin was confirmed but not credited yet"
  },
  "ticket": null,
  "qr": null,
  "beneficiary": null,
  "merchant": {
    "type": "COMPANY",
    "name": "Company"
  },
  "payer": {
    "type": "INDIVIDUAL",
    "name": "John",
    "lastname": "Doe",
    "document": {
      "id": "YYY180222YY6",
      "type": "RFC"
    },
    "email": "john.doe@example.com",
    "address": null,
    "birthdate": null,
    "nationality": null
  },
  "intermediaries": [],
  "wireInstructions": null,
  "date": {
    "creationDate": "2024-05-19T19:02:44.018+00:00",
    "processedDate": "2024-05-19T19:02:44.799618",
    "expirationDate": "0001-01-01T00:00:00"
  },
  "card": {
    "token": "xsWMaLcYjS3L11aBwxl465%2F2d8J85FXPAaBFIKfr0Fx%3D",
    "bin": "400000",
    "brand": "VISA",
    "country": "RS",
    "name": "John Doe",
    "last4": "0002",
    "expirationYear": 2029,
    "expirationMonth": 12
  },
  "errors": []
}
```

#### Campos de resposta principais

| Campo | Descrição |
| - | - |
| `card.token` | Cartão tokenizado. |

***

## Usando Cartões Tokenizados

Para usar um cartão tokenizado em um pagamento, inclua o `card.token` na sua requisição de pagamento.

### Exemplo de solicitação com token

```bash curl theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
curl --request POST \
  --url https://api.stage.localpayment.com/api/payin/ \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_access_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "paymentMethod": {
        "type": "CreditCard",
        "code": "1600",
        "flow": "DIRECT"
    },
    "externalId": "dffbd2a6-6e65-469b-8bbe-dac269882220",
    "country": "MEX",
    "currency": "MXN",
    "amount": 1000,
    "accountNumber": "{{accountNumber}}",
    "conceptCode": "0001",
    "merchant": {
        "type": "COMPANY",
        "name": "Company",
        "document": {
            "type": "RFC",
            "id": "XXX840510XX1"
        },
        "email": "mail@company.com"
    },
    "payer": {
        "type": "INDIVIDUAL",
        "name": "John",
        "lastname": "Doe",
        "document": {
            "type": "RFC",
            "id": "YYY180222YY6"
        },
        "email": "john.doe@example.com"
    },
    "card": {
        "token": "WleV6CZ111IMxqp53SIrqzOn1JsGKCef8oBh2mbi56M%3D",
        "cvv": "123",
        "installments": "1"
    }
}'
```

***

## Obtenha informações sobre o cartão

Após a tokenização de um cartão, você pode recuperar seus detalhes usando a API Localpayment. Isso permite exibir os métodos de pagamento armazenados aos clientes, mantendo a conformidade com o PCI.

Para obter as informações do cartão, envie uma requisição `GET` para o endpoint [Get Card Details](https://docs.localpayment.com/pt-br/reference/get-card.md), incluindo o token do cartão como parâmetro de consulta.

### Exemplo de solicitação

```bash curl theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
curl --location 
--request GET 'https://api.stage.localpayment.com/api/card/?token={token}' \
--header 'Authorization: Bearer <your_access_token>'
```

### Exemplo de resposta bem-sucedida

Em resposta, a API retorna os dados do cartão:

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
 {
  "card": {
    "token": "WleV6CZ111IMxqp53SIrqzOn1JsGKCef8oBh2mbi56M%3D",
    "bin": "400000",
    "brand": "VISA",
    "country": "US",
    "name": "",
    "last4": "0002",
    "expirationYear": 2029,
    "expirationMonth": 11
  },
  "errors": []
}
```

***

## Excluir um cartão tokenizado

Remova permanentemente os tokens de cartão armazenados por meio de um endpoint de API dedicado. Essa ação irreversível ajuda a manter a conformidade com as regulamentações de privacidade de dados e permite o gerenciamento adequado do ciclo de vida do cartão.

Para excluir um cartão tokenizado, envie uma requisição `DELETE` para o endpoint [Delete Tokenized Card](https://docs.localpayment.com/pt-br/reference/delete-card.md), incluindo o token do cartão como parâmetro de consulta.

### Exemplo de solicitação

```bash curl theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
curl --location \
--request DELETE 'https://api.stage.localpayment.com/api/card/?token={token}' \
--header 'Authorization: Bearer <your_access_token>'
```

### Exemplo de resposta bem-sucedida

Uma exclusão bem-sucedida normalmente retornará um objeto JSON vazio:

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "errors": []
}
```

***

## Próximos passos

Agora que você tokenizou um cartão com sucesso, pode usar o token gerado para processamento seguro em todos os serviços de pagamento da Localpayment:

> [card] [Pagamentos únicos](https://docs.localpayment.com/pt-br/docs/one-time-payments.md)
>
> Utilize o token para processar pagamentos únicos e imediatos.

> [card] [Assinaturas](https://docs.localpayment.com/pt-br/docs/subscriptions-overview.md)
>
> Configure ciclos de faturamento recorrentes automatizados usando o cartão tokenizado.

> [card] [Parcelas](https://docs.localpayment.com/pt-br/docs/installments.md)
>
> Ofereça opções de pagamento parcelado aos seus clientes usando o cartão tokenizado.

> [card] [3D Secure](https://docs.localpayment.com/pt-br/docs/3d-secure.md)
>
> Aprimore a segurança dos pagamentos com cartão tokenizado com a autenticação 3D Secure.


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