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

# 3D 安全

使用 3D Secure（标准身份验证协议）增强您的在线支付安全性。通过额外的验证层减少未经授权的交易，在不影响用户体验的前提下保护您的业务和客户。

3D Secure (3DS) 是一种旨在增强在线信用卡交易安全性的身份验证协议。它通过在支付过程中要求持卡人进行额外验证，帮助防止未经授权的信用卡使用。这一额外的身份验证层可以减少欺诈，并确保交易是由信用卡的合法持有人进行的。

3D Secure 被商家、支付服务商和金融机构广泛使用，以提高交易安全性，同时保持流畅的客户体验。

***

## 3D安全验证的工作原理

当客户发起在线购买且支付处理器启用了 3D 安全验证时，会发生以下过程：

1. **交易发起**：客户在您的网站上输入其银行卡信息。
2. **身份验证请求**：交易被发送到 Localpayment，由 Localpayment 评估是否需要身份验证。
3. **用户验证**：如果需要身份验证，客户将被重定向到一个安全页面，他们必须在该页面验证身份（例如，使用一次性密码、生物识别或银行应用程序验证）。如果不需要持卡人身份验证（无缝流程），则您网站上建立的支付流程将根据请求处理结果继续进行。
4. **认证结果**：
   * 如果身份验证成功，客户将被重定向到请求中 `redirectUrl.onSuccess` 属性指定的 URL。
   * 如果身份验证失败，客户将被重定向到 `redirectUrl.onError` 属性指定的 URL。
   * 身份验证结果也会在 API 响应中返回。
5. **支付完成**：如果身份验证成功，交易将照常进行。如果身份验证失败，则支付将被拒绝。

### 身份验证流程图

下面的步骤展示了两种可能的结果：无摩擦流程（无需验证）和验证流程，其中持卡人必须在发卡机构的验证页面上输入一次性密码 (OTP)。

```mermaid theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#31467c', 'primaryTextColor': '#ffffff', 'primaryBorderColor': '#0c1a29', 'actorBkg': '#31467c', 'actorBorder': '#0c1a29', 'actorTextColor': '#ffffff', 'actorLineColor': '#0c1a29', 'signalColor': '#0c1a29', 'signalTextColor': '#0c1a29', 'labelBoxBkgColor': '#31467c', 'labelBoxBorderColor': '#0c1a29', 'labelTextColor': '#ffffff', 'loopTextColor': '#0c1a29', 'noteBkgColor': '#ffffff', 'noteBorderColor': '#31467c', 'noteTextColor': '#0c1a29'}}}%%
sequenceDiagram
    actor Cardholder as 持卡人
    participant Merchant as 商户
    participant LP as Localpayment
    participant Issuer as 发卡行

    Cardholder->>Merchant: 使用银行卡支付
    Merchant->>LP: 创建 payin
    LP->>Issuer: 请求身份验证

    alt 无感验证
        Issuer-->>LP: 已批准，无需挑战验证
        LP-->>Merchant: 返回最终状态的响应
    else 挑战验证（OTP）
        Issuer-->>LP: 需要挑战验证
        LP-->>Merchant: 返回状态为 INPROGRESS 及 redirectUrl 的响应
        Issuer-->>Cardholder: 重定向至挑战验证页面
        Cardholder->>Issuer: 输入 OTP
        alt OTP 有效
            Issuer-->>LP: 验证通过
            LP->>Merchant: 携带最终状态的 Webhook
        else OTP 无效或已过期
            Issuer-->>LP: 验证失败
            LP->>Merchant: 状态为 REJECTED 的 Webhook
        end
    end
```

Localpayment 发送给商家的最终状态（在 API 响应或 webhook 中）取决于支付的捕获流程：

* **已授权**：适用于两步交易（授权和捕获分别进行）。
* **已批准**：交易已确认，但资金尚未到账。状态变为 COMPLETE 后即可提取资金，通常需要 1 到 2 天，具体取决于服务商。
* **已完成**：资金已实时结算。
* **已拒绝**：身份验证失败或过期，或者交易因其他原因被拒绝（例如，资金不足）。

### 持卡人在验证流程中看到的内容

> [!NOTE]
>
> 以下验证屏幕属于持卡人的发卡银行和卡组织（例如 Visa 或 Mastercard），而非 Localpayment。具体的措辞、品牌和布局因发卡机构而异。以下示例使用虚构数据，仅用于说明一般模式。

**第一步——选择验证方法**

根据发卡机构的不同，验证流程可能允许持卡人选择接收一次性密码 (OTP) 的方式（例如，电子邮件或短信），如下所示。其他发卡机构则省略此选择，通过单一的固定渠道发送验证码。

![](https://mintcdn.com/localpayment-1fee3d41/oFZuSE0fcOk5ECyA/images/docs/d3bf89f19e47d8647762da8849ef88e9717ba27cc239695a4a2c1630254774e9-3ds-otp-step1-method.png?fit=max\&auto=format\&n=oFZuSE0fcOk5ECyA\&q=85\&s=2d9d706d0652b4772d946eff72e43e01)

**步骤 2 — 输入验证码**

![](https://mintcdn.com/localpayment-1fee3d41/x0nXcqwNUmbD9R8W/images/docs/6654bf3f70288b52620dd59666ea4e8d743cebccbb3d3f2bb296c9be6c37e5aa-3ds-otp-step2-code.png?fit=max\&auto=format\&n=x0nXcqwNUmbD9R8W\&q=85\&s=ef48f418780ebd9d43d0a993d7ac45c5)

如果持卡人未完成验证或输入无效代码，交易将被拒绝，并被重定向至 `redirectUrl.onError`，如下文步骤 2 所述。

### 主要参与者

3D Secure流程涉及多个实体：

* **持卡人**：使用信用卡或借记卡进行交易的人。
* **商家**：接受银行卡支付的在线企业。
* **发卡机构**：向客户发行银行卡的金融机构（例如，银行）。
* **收单机构**：管理商户交易的金融机构（Localpayment）。
* **3D 安全服务器 (3DSS)**：一种促进商户、发卡机构和支付网络之间身份验证的系统。
* **访问控制服务器 (ACS)**：由发卡机构管理的系统，用于在身份验证期间验证持卡人的身份。
* **目录服务器**：由卡组织（例如 Visa、Mastercard）管理的系统，用于帮助将身份验证请求路由到正确的发卡机构。

### 3D 安全验证的优势

实施 3D 安全验证可为商家和顾客带来诸多好处：

* **增强安全性**：通过确保只有持卡人才能授权付款，降低欺诈交易的风险。
* **提升客户信任度**：提供额外的保护，让客户在网上购物时更有信心。
* **降低欺诈率**：显著降低未经授权的交易和潜在的经济损失。

***

## 开始之前

请确保您已备好：

> [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 以接收付款通知。

***

## 步骤 1：3D 安全认证

在发起[一次性支付](https://docs.localpayment.com/zh/reference/payins.md)或[订阅](https://docs.localpayment.com/zh/reference/create-a-subscription.md)时，请发送 `redirectUrl` 对象，并包含 `onSuccess` 和 `onError` 属性。这些属性分别定义了客户在身份验证成功或出错时将被重定向到的 URL。

`paymentMethod.code` 取决于国家/地区、银行卡品牌以及产品（信用卡或借记卡）。在秘鲁，它还取决于币种。完整列表请参阅[银行卡支付方式代码](https://docs.localpayment.com/zh/docs/card-payment-methods.md)。

### 示例请求

以下是使用 `curl` 的示例：

```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"
    },
    "redirectUrl": {
        "onSuccess": "https://example.com/success/?id={externalId}",
        "onError": "https://example.com/error/?id={externalId}"
    }
}'
```

***

## 步骤 2：处理响应

### 成功响应

如果支付过程中需要额外的身份验证，API 响应将包含 `redirectUrl` 属性。该 URL 指向一个应向持卡人显示的模态窗口或页面，使其能够与发卡机构完成身份验证挑战。

```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": {
    "bin": "400000",
    "brand": "VISA",
    "country": "RS",
    "name": "John Doe",
    "last4": "0002",
    "expirationYear": 2029,
    "expirationMonth": 12
  },
  "errors": [],
  "redirectUrl": "https://web-checkout.stage.localpayment.com/redirect/aXX0cXX6Ly9ob29xxx5zdHJpcXXuY29tLzNkX3NlY0VyXX0yL0hvc3RlZD9tZXJjaGFudX1hY0N0XzFKdHJmYkw5RVZiU1oySkgmcGF5bWVudF9xxxRlbnQ9cXlfM05weERZTDlFVmXXXjXXXXXXXXXXa2kyJnBheW1lbnRfaW50ZW50X2NsaWVudF9zXXXyZXQ9cGlfM05weERZTDlFVmJTWjXXXXXXXXXXXa2kyX3NlY3JldF9hek5FV1cyQm1BU3RDZHpjRzF0MkVTQ3BuJnB1Ymxpc2hhYmxlX2tleT1wa190ZXN0XzUxSnRyZmJMOUVWYlNaMkpISUF2WjJGREh0aWpwd0JFUWE5SG4xbTA1WHlPS0d3MjlncW1PTGJ6R3hUTm01M0V6VGVBbkk0aTRHWnFpUDliNkJuME5DWDFjMDBrbFNZdmwxQiZzb3VyY2U9cGF5YXR0XzNOcHhXXXw5RVZiU1oySkgxbXX1Q3XrxX"
}
```

如果交易需要持卡人进行身份验证，则在身份验证完成之前，该交易将保持 `INPROGRESS` 状态。根据支付的捕获流程，身份验证成功后交易将变为 `AUTHORIZED`（等待捕获的两步交易）、`APPROVED`（等待结算）或 `COMPLETE`（资金已实时结算）。如果身份验证失败、过期，或交易因其他原因被拒绝（例如，资金不足），则状态为 `REJECTED`。

客户完成身份验证后（无论成功与否），客户将根据结果被重定向到请求中指定的 URL。`internalId` 和 `externalId` 属性将作为查询参数包含在内，使您能够实现必要的逻辑（例如，检查交易状态并向用户显示消息）。


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