> ## 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 使商家能够使用信用卡和借记卡处理跨多个国家和多种货币的一次性付款。

本指南概述了通过 Localpayment 的 API 发起一次性卡支付的过程，详细说明了所需的参数、处理响应以及解释状态代码。

## 开始之前

开始之前，请确保您已准备好：

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

***

## 第一步：申请刷卡付款

要发起一次性卡支付，您需要向 [Create Payin](https://docs.localpayment.com/zh/reference/payins.md) endpoint 发送 `POST` 请求。

### 关键请求参数

该请求需要几个关键对象：

| 参数 | 说明 | 必需的 |
| - | - | - |
| `payer` | 付款方合规信息 | ✅ |
| `merchant` | 商家/企业详情 | ✅ |
| `paymentMethod` | 支付方式配置 | ✅ |
| `amount` | 交易金额 | ✅ |
| `currency` | 交易货币代码 | ✅ |
| `country` | 目标国家/地区代码 | ✅ |

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

查看请求中所有[可用的参数](https://docs.localpayment.com/zh/reference/payins.md)。

### 使用代币化卡支付

如果您之前已对客户的银行卡进行令牌化处理，则可以使用该令牌代替发送完整的银行卡信息来处理一次性付款。这提高了安全性，并简化了支付流程，无需再次请求银行卡信息。

有关卡片令牌化的详细信息，请参阅[令牌化](https://docs.localpayment.com/zh/docs/tokenization.md)文档。

### 使用 3D 安全支付

如果持卡人需要额外身份验证，流程将通过 3D Secure 进行。在这种情况下，Localpayment 会在 API 响应中返回发卡行的验证 URL，商家有责任将客户重定向到该 URL 或在结账流程中显示验证信息。这样，持卡人即可完成所需的验证。具体的 3D Secure 体验可能因发卡行和客户所在国家/地区而异。

有关 3D Secure 支付的详细信息，请参阅 [3D Secure](https://docs.localpayment.com/zh/docs/3d-secure.md) 文档。

***

## 步骤 2：处理响应

### 成功响应

成功的响应应包含详细的交易信息和跟踪标识符：

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

### 关键响应字段

| 参数 | 说明 | 用例 |
| - | - | - |
| `internalId` | Localpayment的唯一交易标识符。 | 交易跟踪和支持。 |
| `externalId` | 您的参考编号。 | 内部核对。 |
| `status.code` | 当前交易状态码。 | 状态监控。 |
| `date.creationDate` | 交易创建时。 | 审计跟踪。 |
| `date.processedDate` | 交易开始处理时。 | 处理时间计算。 |

### 错误响应

请求失败时，您将收到详细的错误信息：

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "externalId": "46014bdc-c3a7-1b15-8dcf-c7050c1c8199",
  "internalId": "caa4e9aa-f634-497c-ba75-7f88b005ca62",
  "status": {
    "code": "801",
    "description": "REJECTED",
    "detail": "Params error"
  },
  "errors": [
    {
      "code": "300",
      "detail": "Invalid param + [paymentMethod] + doesn´t exists for MEX"
    },
    {
      "code": "300",
      "detail": "Invalid param + [payer.bank.account.[number, type | alias]] + must not be null"
    },
    {
      "code": "300",
      "detail": "Invalid param + [payer.document.type] + is invalid for country MEX"
    },
    {
      "code": "300",
      "detail": "Invalid param + [payer.document] + is invalid for payer type"
    },
    {
      "code": "701",
      "detail": "IncorrectAccountNumber"
    }
  ]
}
```

***

## 步骤 3：跟踪交易状态

发起一次性付款后，可通过以下方式监控付款进度：

> [card] [Webhooks（推荐）](https://docs.localpayment.com/zh/docs/webhooks.md)
>
> 交易状态变更时接收实时通知。最适用于生产环境。

> [card] [状态 API endpoint](https://docs.localpayment.com/zh/reference/get-transaction-status.md)
>
> 以编程方式查询事务状态。可用于轮询或恢复丢失的 webhook 通知。

> [card] [Business Portal 视图](https://docs.localpayment.com/zh/docs/dashboard-overview.md)
>
> 用于监控交易的可视化界面。非常适合人工监督和详细的交易分析。

### 常用状态码

Localpayment API 提供各种状态代码，以在响应中指示付款的进度和结果。

| 代码 | 状态 | 说明 |
| :- | :- | :- |
| `103` | `APPROVED` | 付款已确认，但尚未到账。 |
| `200` | `Completed` | 付款已完成。 |
| `300` | `Rejected` | 无效参数 + \[参数名称] + \[原因]。 |

> [!NOTE]
>
> **APPROVED 不是最终状态。** 它表示银行卡付款已确认，但资金尚未计入您的余额。您可以看到该付款，但在状态变为 Completed 之前无法提取资金。这通常需要 1 到 2 天，具体取决于服务商。

> [!NOTE]
>
> **完整参考**
>
> 请查看我们的[交易状态文档](https://docs.localpayment.com/zh/reference/transaction-status-error-codes)，了解所有状态代码。

***

## 测试您的集成

### 测试场景

请确认您的集成方案能够处理以下场景：

1. **交易成功**：标准支付流程
2. **验证错误**：无效的银行账户，缺少字段
3. **处理延迟**：需要时间处理的事务
4. **交易失败**：资金不足、收款人被冻结
5. **状态更新**：Webhook 处理和状态轮询

***

## 后续步骤

一次性付款处理完毕后，您可能需要执行其他操作，例如：

> [card] [退款](https://docs.localpayment.com/zh/docs/refund-card-payment)
>
> 如有必要，您可以将款项退还给客户。详情请参阅相关文档。

> [card] [处理拒付](https://docs.localpayment.com/zh/docs/chargebacks.md)
>
> 如果发生争议，您可能需要处理拒付事宜。请参阅相关文档了解具体流程。

> [card] [查看交易详情](https://docs.localpayment.com/zh/reference/get-transaction-status.md)
>
> 您可以使用 Localpayment API 获取交易信息，以获得更详细的分析。


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