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

# 寄送税款、账单或服务费

在墨西哥创建税款、账单或服务费付款，包含请求/响应示例、错误处理和 Webhook。

本指南介绍如何使用 API 创建税款、账单或服务费付款：请求结构、字段说明、响应处理和 Webhook 通知。请先阅读[税款、账单和服务付款概览](https://docs.localpayment.com/zh/docs/bill-pay-overview.md)，了解适用范围和付款流程。

## 开始之前

* 有效的 [API 凭证](https://docs.localpayment.com/zh/docs/api-keys-and-environments.md)（访问令牌）。
* 一个专门用于缴纳税款和账单的账户。
* 您计划支付的 `billType`，并已对照 [BillType 目录](https://docs.localpayment.com/zh/docs/bill-pay-overview.md#billtype-catalog)验证。
* 从纳税人或收费方获得的账单参考（例如墨西哥的 SAT 付款参考）。

***

## endpoint

要创建税款、账单或服务费付款，请向\*\*[创建付款](https://docs.localpayment.com/zh/reference/create-a-payout.md)\*\*endpoint 发送 `POST` 请求，并将 `paymentMethod.type` 设置为 `"BillPay"`。

```http theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
POST https://api.stage.localpayment.com/api/payout/
```

### 必需的标头

```http theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
Authorization: Bearer <your_access_token>
Content-Type: application/json
```

***

## 请求

```bash curl theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
curl --request POST \
     --url https://api.stage.localpayment.com/api/payout/ \
     --header 'Authorization: Bearer <your_access_token>' \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --data '{
  "externalId": "550e8400-e29b-41d4-a716-446655440000",
  "country": "MEX",
  "currency": "MXN",
  "amount": 100.00,
  "accountNumber": "{{accountNumber}}",
  "paymentMethod": {
    "type": "BillPay",
    "code": "0119",
    "flow": "DIRECT"
  },
  "beneficiary": {
    "billType": "0098",
    "billReference": "20260713000000000001"
  },
  "sender": {
    "type": "INDIVIDUAL",
    "name": "Jane",
    "lastName": "Doe"
  },
  "merchant": {
    "type": "COMPANY",
    "name": "Merchant Name"
  }
}'
```

### 关键请求参数

请求需要几个关键对象。完整字段列表（包括 `sender` 和 `merchant`）请参阅\*\*[创建付款](https://docs.localpayment.com/zh/reference/create-a-payout.md)\*\*参考。

| 字段 | 说明 | 必需的 |
| - | - | - |
| `paymentMethod.type` | 设置为 BillPay。 | ✅ |
| `paymentMethod.code` | 提供商代码。目前可用：0119。 | ✅ |
| beneficiary.billType | 标识税款或服务类型的代码。请参阅 [BillType 目录](https://docs.localpayment.com/zh/docs/bill-pay-overview.md#billtype-catalog)。 | ✅ |
| beneficiary.billReference | 由税务机关或收费方签发的官方参考（墨西哥为 SAT 付款参考）。请参阅[账单参考注意事项](#bill-reference-considerations)。 | ✅ |
| amount | 必须与 beneficiary.billReference 中编码的金额一致。 | ✅ |
| requireAuth | 如果为 true，交易将保持在 PendingAuth 状态，直到您调用[授权 endpoint](https://docs.localpayment.com/zh/docs/approvals-and-double-signature.md)。 | — |

***

## 处理响应

### 成功响应

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
    "externalId": "550e8400-e29b-41d4-a716-446655440000",
    "internalId": "5aced5da-40c1-4bec-85ff-c8cd1bcb4526",
    "paymentMethod": {
        "code": "0119",
        "name": "BILLPAY",
        "description": "string",
        "paymentMethodType": "BillPay"
    },
    "country": "MEX",
    "currency": "MXN",
    "amount": 100.00,
    "accountNumber": "{{accountNumber}}",
    "clientCode": "0001",
    "clientName": "Acme",
    "status": {
        "code": "200",
        "description": "COMPLETED",
        "detail": "The payout was processed successfully"
    },
    "beneficiary": {
        "billType": "0098",
        "billReference": "20260713000000000001"
    },
    "sender": {
        "type": "INDIVIDUAL",
        "name": "Jane",
        "lastname": "Doe"
    },
    "merchant": {
        "type": "COMPANY",
        "name": "Merchant Name"
    },
    "date": {
        "creationDate": "2026-07-13T15:04:22.0000000Z",
        "processedDate": "2026-07-13T15:04:23.0000000Z"
    },
    "errors": null
}
```

### 关键响应字段

| 字段 | 说明 |
| - | - |
| internalId | Localpayment 的唯一交易标识符。用于支持和幂等性检查。 |
| externalId | 您的参考编号，会从请求中原样返回。 |
| `status.description` | 当前交易状态。请参阅[交易状态](https://docs.localpayment.com/zh/docs/bill-pay-overview.md#transaction-states)。 |
| date.processedDate | 交易开始处理的时间。 |

### 错误响应

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
[
  {
    "externalId": "550e8400-e29b-41d4-a716-446655440000",
    "internalId": "5aced5da-40c1-4bec-85ff-c8cd1bcb4526",
    "status": {
      "code": "801",
      "description": "Rejected",
      "detail": "Params error"
    },
    "errors": [
      {
        "code": "300",
        "description": "Invalid param + [beneficiary.billReference] + reference is expired"
      }
    ]
  }
]
```

有关状态和错误代码的完整列表，请参阅[付款状态和错误代码](https://docs.localpayment.com/zh/reference/payout-status-error-codes.md)。

***

## 账单参考注意事项

对于墨西哥，`billReference` 是 SAT 付款参考：一个 20 位字母数字密钥，可唯一标识税种、纳税人和会计期间。

> [!WARNING]
>
> * SAT 付款参考的有效期有限，由 SAT 设定。Localpayment 只有在对照 SAT 完成验证后才会拒绝已过期的参考，因此该检查不一定是即时的，拒绝 Webhook 也可能不会立即触发。
> * Localpayment 不会验证 `amount` 是否与参考中编码的值一致，并且参考一旦支付便无法重复使用。您的集成必须在提交请求之前验证这些条件。

***

## 在 Stage 中测试

为了让您在上线前验证端到端流程，只要您提交的 `beneficiary.billReference` 与下方目录中的某个固定捕获行一致，Localpayment 就会在 **Stage** 中模拟收费方的响应。

| 捕获行 (billReference) | 模拟结果 |
| - | - |
| 0100000000000000001 | COMPLETED |
| 0100000000000000002 | COMPLETED |
| 0100000000000000003 | 已拒绝：错误 741，InvalidBillReference - BillReference not found or invalid |
| 0100000000000000004 | 已拒绝：错误 741，InvalidBillReference - BillReference not found or invalid |
| 0100000000000000005 | 已拒绝：错误 811，Invalid amount |

完整列表请参阅[付款状态和错误代码](https://docs.localpayment.com/zh/reference/payout-status-error-codes.md)。

> [!WARNING]
>
> * 这些捕获行仅在 **Stage** 中有效，在 Production 中未启用。
> * 此目录之外的任何 `billReference` 在 Stage 中都无法解析：由于收费方一侧没有可供验证的真实沙箱，交易会无限期停留在 `IN_PROGRESS` 状态。请使用上述值之一进行 Stage 测试。

***

## Webhooks

Localpayment 通过 Webhook 通知您最终交易状态，其载荷结构与上述响应相同。通知包含最终的 `status`、`externalId`，以及带有 `billType` 和 `billReference` 的 `beneficiary` 对象。有关载荷示例、签名验证和设置，请参阅 [Webhooks](https://docs.localpayment.com/zh/docs/webhooks.md)。

### 重试

* Localpayment 会对失败的 Webhook 投递使用指数退避策略最多重试 3 次。
* 您的 endpoint 必须以 HTTP 200 响应以确认已收到。任何其他状态码都视为投递失败。
* 如果 3 次重试均失败，交易将保持其最终状态，您可以通过 API 手动检索。

***

## 后续步骤

> [card] [税款、账单和服务付款概览](https://docs.localpayment.com/zh/docs/bill-pay-overview.md)
>
> 适用范围、付款流程和交易状态。

> [card] [审批与双重签名](https://docs.localpayment.com/zh/docs/approvals-and-double-signature.md)
>
> 授权使用 requireAuth 创建的付款。


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