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

# 令牌化

使用 Localpayment 的令牌化技术可以安全地处理卡片信息，降低安全风险，简化未来的交易。

## 工作原理

该过程包括以下关键步骤：

1. **卡片信息收集**：卡片信息通过您应用程序中的表单安全收集，然后传输到 Localpayment API。
2. **令牌生成**：Localpayment 安全地存储卡片信息，并生成一个代表卡片详细信息的唯一且不可逆的令牌。此令牌将随 API 响应一起返回。
3. **使用已令牌化的卡片**：在后续的卡片支付中，您将发送 `card.token` 属性，而不是客户的实际卡片信息。

***

## 开始之前

在对卡片进行标记化之前，请确保已完成以下步骤：

> [card] [API凭证](https://docs.localpayment.com/zh/docs/api-keys-and-environments.md)
>
> 用于身份验证的有效 API 凭据和访问令牌。

> [card] [账户设置](https://docs.localpayment.com/zh/docs/make-your-first-test-payment.md)
>
> 为您的目标国家/地区正确设置账户并进行业务验证。

> [card] [IP白名单](https://docs.localpayment.com/zh/docs/dashboard-whitelist-your-ips.md)
>
> 将服务器 IP 地址加入 API 访问白名单。

> [card] [Webhook endpoint](https://docs.localpayment.com/zh/docs/webhooks.md)
>
> 设置 webhook URL 以接收付款通知。

***

## 令牌化方法

卡片标记化有两种可用方法：

* [卡片令牌化 endpoint](#option-1-endpoint-for-card-tokenization)
* [支付过程中的卡片令牌化](#option-2-card-tokenization-during-payment)

### 选项 1：卡片令牌化 endpoint

您可以通过专用 endpoint 安全地对卡片信息进行令牌化处理，以便将来使用。

要对卡片进行令牌化，请向[卡片令牌化](https://docs.localpayment.com/zh/reference/tokenize-card.md)endpoint 发送 `POST` 请求，并包含以下参数：

| 参数 | 说明 | 必填 |
| - | - | - |
| `name` | 持卡人姓名。 | ✅ |
| `number` | 卡号。 | ✅ |
| `cvv` | 卡片验证值。 | ✅ |
| `expirationMonth` | 卡片到期月份。 | ✅ |
| `expirationYear` | 卡片到期年份。 | ✅ |

#### 示例请求

```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"
}
'
```

#### 成功响应示例

作为响应，API 返回卡令牌：

```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": []
}
```

#### 关键响应字段

| 字段 | 说明 |
| - | - |
| `card.token` | 令牌化卡片。 |

### 选项 2：支付过程中的卡片令牌化

Localpayment 允许商户在[支付处理](https://docs.localpayment.com/zh/docs/one-time-payments.md)期间，通过在支付请求中包含 `save` 参数来对卡片进行令牌化。这种简化的方式让您只需一次 API 调用，即可同时处理交易并存储卡片详细信息。

要对卡片进行令牌化，请向[创建 Payin](https://docs.localpayment.com/zh/reference/payins.md) endpoint 发送 `POST` 请求，并在您的 Payin 请求中将 `card.save` 属性设置为 `true`。

#### 示例请求

```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
    }
}'
```

#### 成功响应示例

作为响应，API 返回卡令牌：

```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": []
}
```

#### 关键响应字段

| 字段 | 说明 |
| - | - |
| `card.token` | 令牌化卡片。 |

***

## 使用代币化卡片

要使用已令牌化的卡片进行支付，请在您的支付请求中包含 `card.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"
    }
}'
```

***

## 获取卡片信息

卡片完成令牌化后，您可以使用 Localpayment API 获取其详细信息。这样，您就可以在满足 PCI 合规性要求的同时，向客户展示已存储的支付方式。

要获取卡片信息，请向[获取卡片详情](https://docs.localpayment.com/zh/reference/get-card.md)endpoint 发送 `GET` 请求，并将该卡片的令牌作为查询参数传入。

### 示例请求

```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>'
```

### 成功响应示例

API 会返回卡片详细信息：

```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": []
}
```

***

## 删除已标记的卡片

通过专用 API 接口永久删除已存储的卡片令牌。此不可逆操作有助于遵守数据隐私法规，并实现妥善的卡片生命周期管理。

要删除已令牌化的卡片，请向[删除令牌化卡](https://docs.localpayment.com/zh/reference/delete-card.md)endpoint 发送 `DELETE` 请求，并将该卡片的令牌作为查询参数传入。

### 示例请求

```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>'
```

### 成功响应示例

成功删除操作通常会返回一个空的 JSON 对象：

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

***

## 后续步骤

现在您已成功对卡片进行令牌化，可以使用生成的令牌在 Localpayment 的支付服务中进行安全处理：

> [card] [一次性付款](https://docs.localpayment.com/zh/docs/one-time-payments.md)
>
> 使用该令牌处理单笔即时付款。

> [card] [订阅](https://docs.localpayment.com/zh/docs/subscriptions-overview.md)
>
> 使用令牌卡设置自动定期付款周期。

> [card] [分期付款](https://docs.localpayment.com/zh/docs/installments.md)
>
> 使用代币化卡为您的客户提供分期付款选项。

> [card] [3D 安全](https://docs.localpayment.com/zh/docs/3d-secure.md)
>
> 使用 3D Secure 认证增强令牌化卡支付的安全性。


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