> ## 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 API 的 API 响应格式、HTTP 状态码，以及所有交易状态和错误代码的完整参考。掌握这些响应模式和代码对于构建稳健的集成、准确跟踪交易生命周期、处理各种场景以及提供清晰的用户反馈至关重要。

Localpayment API 的响应通过 HTTP 状态码和结构化状态对象清晰地指示请求结果。虽然不同 endpoint 的响应结构可能有所不同，但它们始终包含正确处理请求的关键信息。

> [card] HTTP状态码
>
> 指示请求成功或失败的标准 HTTP 状态码

> [card] 状态对象
>
> 交易结果的详细状态信息

> [card] 清晰的错误处理
>
> 用于调试和解决的结构化错误信息

***

## HTTP状态码

API 使用标准的 HTTP 状态码来指示协议层面的请求结果。这些代码初步表明您的请求是否成功。

### 成功代码（2xx）

| 状态码 | 描述 | 典型应用案例 |
| - | - | - |
| 200 OK | 请求成功 | GET 请求、成功操作、数据检索 |
| 201 创建 | 资源创建成功 | 新的支付、虚拟账户、出款 |

### 客户端错误（4xx）

| 状态码 | 描述 | 常见原因 |
| - | - | - |
| 400 错误请求 | 请求格式错误或参数无效 | 缺少必填字段、数据格式无效、验证错误 |
| 401 未授权 | 需要身份验证或身份验证无效 | 缺少/无效的访问令牌、令牌过期、无效凭据 |
| 403 禁止访问 | 权限不足 | IP地址未列入白名单、账户受限、未经授权的访问 |
| 404 未找到 | 资源未找到 | 无效的交易 ID、错误的 endpoint、已删除的资源 |
| 429 请求过多 | 超出速率限制 | 短时间内 API 调用次数过多，超出配额 |

### 服务器错误（5xx）

| 状态码 | 描述 | 建议采取的措施 |
| - | - | - |
| 500 内部服务器错误 | 意外的服务器错误 | 使用指数退避策略重试，如果问题仍然存在，请联系技术支持。 |
| 502 错误网关 | 上游服务不可用 | 稍等片刻后重试，并检查系统状态 |
| 503 服务不可用 | 临时服务中断 | 查看状态页面，稍后重试，实施熔断机制 |

***

## 状态对象

`status` 对象提供有关交易结果的详细、Localpayment 特定信息，并包含在大多数涉及金融操作的 API 响应中。

### 状态对象结构

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "status": {
    "code": "103",
    "description": "APPROVED",
    "detail": "The payin was confirmed but not credited yet"
  }
}
```

### 状态对象字段

| 字段 | 类型 | 描述 | 例子 |
| - | - | - | - |
| `code` | string | Localpayment特定状态代码 | `103`, `200`, `701` |
| `description` | string | 人类可读的状态摘要 | `Approved`, "Completed", "Rejected" |
| `detail` | string | 补充说明或解释 | `The payin is pending the confirmation` |

***

## 常见响应模式

### 付款成功回复

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "transactionType": "PayIn",
  "externalId": "40bac59a-0381-4cc0-a6a5-33418d84c2e4",
  "internalId": "dd616d71-f5cd-4bb5-9c2c-f421241ab301",
  "paymentMethod": {
    "type": "BankTransfer",
    "code": "1099",
    "flow": "DIRECT"
  },
  "country": "ARG",
  "currency": "ARS",
  "amount": 2300,
  "accountNumber": "{{accountNumber}}",
  "confirmed": {
    "currency": "ARS",
    "amount": 2300,
    "fxQuote": 1
  },
  "payment": {
    "currency": "ARS",
    "fxQuote": 1,
    "financingFee": 0,
    "amount": 2300
  },
  "localTaxes": [],
  "withHoldings": [],
  "fees": {
    "description": "Fee",
    "currency": "USD",
    "fxSource": 1,
    "fxQuote": 1020.72259627,
    "amount": 0.6,
    "account": "{{accountNumber}}"
  },
  "status": {
    "code": "103",
    "description": "APPROVED",
    "detail": "The payin was confirmed but not credited yet"
  },
  "merchant": {
    "type": "COMPANY",
    "name": "LTDA",
    "document": {
      "type": "CUIL",
      "id": "30-31.145.201-7"
    },
    "email": "email@email.com",
    "phone": {
      "countryCode": "countryCode",
      "areaCode": "11",
      "number": "98789632"
    },
    "address": {
      "street": "Street",
      "number": "938",
      "city": "City",
      "state": "state",
      "country": "Argentina",
      "zipCode": "1688",
      "comment": "port 801"
    },
    "birthdate": "2000-01-01",
    "nationality": "nationality"
  },
  "payer": {
    "bank": {
      "name": "Bank Name",
      "code": "191",
      "account": {
        "type": "S",
        "number": "1910119655111901676653"
      }
    },
    "type": "INDIVIDUAL",
    "name": "Prueba",
    "lastname": "Test",
    "document": {
      "type": "CUIT",
      "id": "20276201078"
    },
    "email": "email@email.com",
    "phone": {
      "countryCode": "1",
      "areaCode": "11",
      "number": "98789632"
    },
    "address": {
      "street": "Street",
      "number": "1234",
      "city": "City",
      "state": "state",
      "country": "Country",
      "zipCode": "1686",
      "comment": "May the force be with you, always!"
    },
    "birthdate": "01/01/1990",
    "nationality": "American"
  },
  "intermediaries": [],
  "wireInstructions": {
    "beneficiary": {
      "bank": {
        "name": "BANCO MACRO S.A.",
        "code": "0118",
        "branch": {},
        "account": {
          "type": "S",
          "number": "2850328631194198460271"
        }
      },
      "type": "INDIVIDUAL",
      "name": "LOCALPAYMENT S.R.L.",
      "document": {
        "type": "CUIT",
        "id": "30716132028"
      }
    },
    "referenceCode": "1022000084"
  },
  "date": {
    "creationDate": "2024-12-30T18:50:10.124+00:00",
    "processedDate": "2024-12-30T18:50:10.6159529",
    "expirationDate": "2025-01-06T18:50:10.5803114"
  },
  "errors": []
}
```

### 错误响应模式

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "externalId": "8c0b537a-e907-4d87-93db-5dab9807e093",
  "internalId": "dddfde6c-b61c-4b0e-8916-d88886133c4d",
  "status": {
    "code": "701",
    "description": "REJECTED"
  },
  "errors": [
    {
      "code": "701",
      "detail": "Invalid bank account number. Account number verification failed."
    }
  ]
}
```

***

## 交易状态和错误指南

请在下方选择特定交易类型，查看其状态和错误代码的详细列表。

> [card] [Payin](https://docs.localpayment.com/zh/reference/payin-status-error-codes.md)
>
> 通过虚拟账户、Columns cols=2 和 APM 接收资金的状态和错误代码。

> [card] [Payout](https://docs.localpayment.com/zh/reference/payout-status-error-codes.md)
>
> 向受益人汇款的状态和错误代码。

> [card] [退款](https://docs.localpayment.com/zh/reference/refund-status-error-codes.md)
>
> 退款状态和错误代码。

> [card] [拒付](https://docs.localpayment.com/zh/reference/chargeback-status-error-codes.md)
>
> 争议交易和强制撤销的状态和错误代码。

> [card] [退回](https://docs.localpayment.com/zh/reference/return-status-error-codes.md)
>
> 退回付款和结算失败的状态和错误代码。

> [card] [召回](https://docs.localpayment.com/zh/reference/recall-status-error-codes.md)
>
> 付款召回和撤销的状态和错误代码。

> [card] [贷方](https://docs.localpayment.com/zh/reference/credit-status-error-codes.md)
>
> 信用交易和调整的状态和错误代码。

> [card] [借方](https://docs.localpayment.com/zh/reference/debit-status-error-codes.md)
>
> 借记交易和资金扣款的状态和错误代码。

> [card] [订阅](https://docs.localpayment.com/zh/reference/subscriptions-status-error-codes.md)
>
> 循环计费和订阅生命周期的状态和错误代码。

> [card] [货币兑换](https://docs.localpayment.com/zh/reference/currency-exchange-status-error-codes.md)
>
> 外汇交易状态和错误代码。

> [card] [Wire In](https://docs.localpayment.com/zh/reference/wire-in-status-error-codes.md)
>
> 汇入电汇的状态和错误代码。

> [card] [Wire Out](https://docs.localpayment.com/zh/reference/wire-out-status-error-codes.md)
>
> 汇出电汇的状态和错误代码。

> [card] [开支](https://docs.localpayment.com/zh/reference/expenses-status-error-codes.md)
>
> 费用扣除和支出交易的状态和错误代码。

> [card] [定期费用](https://docs.localpayment.com/zh/reference/recurring-fee-status-error-codes.md)
>
> 定期收费的状态和错误代码。

***

## 相关资源

> [card] [Webhooks 指南](https://docs.localpayment.com/zh/docs/webhooks.md)
>
> 了解如何接收实时状态更新

> [card] [错误处理](https://docs.localpayment.com/zh/docs/error-handling.md)
>
> 处理失败交易的指南

> [card] [支持](mailto:support@localpayment.com)
>
> 获取有关特定状态问题的帮助

> [!NOTE]
>
> **专业提示**
>
> 实施全面的日志记录，记录状态码和错误码及其时间戳。这能为合规性要求创建清晰的审计跟踪，并显著加快问题调试速度。日志中应包含完整的错误响应，而不仅仅是错误码。


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