部分更新交易

使用此端点可在交易发起后、最终完成前向交易添加非关键数据。第一个支持的字段是email字段，用于在付款成功后发送数字收据。

当您无法在发起交易之前收集电子邮件时，此功能非常有用——例如，访客结账、后端发起的交易，或者在稍后的屏幕上输入电子邮件的流程。

部分更新交易端点在托管支付页面和托管组件集成中均可用。两者的请求和响应完全相同，只有基本 URL 不同。

端点

方法：POST

环境基本 URL

沙盒

https://sandbox.codapayments.com/airtime/api/restful/v2.0/Payment/component/patch.json

生产

https://airtime.codapayments.com/airtime/api/restful/v2.0/Payment/component/patch.json

注意：此接口仅在 v2.0 版本中可用。

部分更新交易接受的条件

• 状态限制：仅Pending可更新交易状态。成功或失败交易的请求将被拒绝。待处理交易包括：初始化/结账/等待确认

• 速率限制：一个交易只能被修补一次。后续请求将会失败。

• 时间窗口：超过 3 个月的交易记录无法更新。

请求正文

以JSON格式发送请求体。

参数	类型	是否必需	描述
patchRequest	Object	Yes	必须是有效的JSON对象。
patchRequest.apiKey	String	Yes	您的 Coda API 密钥。
patchRequest.projectId	String	Yes	您的项目 ID。
patchRequest.txnId	Numeric	Yes	返回的交易 ID init.json。
patchRequest.profile	Object	No	用户个人资料信息，采用与以下相同的结构init.json。
patchRequest.profile.entry	Array	No	键值对列表。今天处理的唯一键是email。
patchRequest.profile.entry[].key	String	No	个人资料条目键（例如email）。
patchRequest.profile.entry[].value	String	No	个人资料条目值。对于email，这是成功后发送收据的地址。

如果请求中不包含任何个人资料条目，则会被视为空操作并返回成功。

示例请求

{
  "patchRequest": {
    "apiKey": "live_****************************",
    "projectId": "21",
    "txnId": 7714940366302672840,
    "profile": {
      "entry": [
        {
          "key": "email",
          "value": "[e-mail]"
        }
      ]
    }
  }
}

回复

补丁成功后会返回resultCode 0结果。响应与之前相同txnId。

成功

{
  "patchResult": {
    "resultCode": 0,
    "resultDesc": "Success",
    "txnId": 7714940366302672840
  }
}

最终拒绝状态

{
  "patchResult": {
    "resultCode": 231,
    "resultDesc": "Transaction already marked as completed, cannot be processed again. (error:231)",
    "txnId": 7714940366302672840
  }
}

无效的电子邮件

{
  "patchResult": {
    "resultCode": 103,
    "resultDesc": "A parameter in the request message sent to Coda is incorrect. (error:103)",
    "txnId": 7714940366302672840
  }
}

响应参数

参数	类型	介绍
patchResult	Object	用于存放补丁结果的容器。
patchResult.resultCode	Numeric	0成功时返回结果。否则返回错误代码（见下文）。仅描述补丁调用的结果，不涉及交易的支付状态。
patchResult.resultDesc	String	"Success"成功则返回错误描述；否则返回错误描述。
patchResult.txnId	Numeric	txnId与请求内容一致。

错误代码

结果代码	介绍	故障排除/原因
103	无效参数	缺少必填字段或电子邮件格式无效。
204	身份验证失败	无效apiKey或projectId。
208	无效状态	交易未处于任何Pending状态。
236	商家不匹配	这笔交易属于另一位商家。
241	交易记录已过期	该交易已超过3个月。
413	未找到交易	无效或无法识别txnId。
473	已更新过	此交易已更新过一次。

典型流程

创建交易
      │
      ▼
交易状态 = Pending
      │
      ├── 更新资料 (允许, 仅一次)
      │
      ▼
继续交易处理
      │
      ▼
成功 / 失败 / 超时
      │
      ▼
不允许再更新资料

笔记

• 默认情况下未启用收据发送功能。要为您的项目启用自动收据发送功能，请联系支付支持团队，邮箱地址为[e-mail]。

• 上次更新的值会生效。如果email该值在初始化时或之前的补丁中已经设置过，则新值会替换它。使用字段已有的值进行补丁操作会返回成功，并且不会更改任何内容。

• 补丁不会发送 webhook。现有交易完成通知仍会照常在根目录Success/Failed上触发。如果email已设置且启用了收据传递，则收据会发送到交易成功时当前对应的地址。