> For the complete documentation index, see [llms.txt](https://docs.coda.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coda.co/https-coda-payments.gitbook.io-zhong-wen-coda-private-technical-documentation/codapay/tuo-guan-zu-jian-ji-cheng/ka-pian/bu-fen-geng-xin-jiao-yi.md).

# 部分更新交易

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

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

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

#### 端点 <a href="#endpoint" id="endpoint"></a>

方法：`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`

> **注意：**&#x6B64;接口仅在 v2.0 版本中可用。

#### 部分更新交易接受的条件 <a href="#when-a-patch-is-accepted" id="when-a-patch-is-accepted"></a>

* 状态限制：仅`Pending`可更新交易状态。成功或失败交易的请求将被拒绝。待处理交易包括：初始化/结账/等待确认
* 速率限制：一个交易只能被修补一次。后续请求将会失败。
* 时间窗口：超过 3 个月的交易记录无法更新。

#### 请求正文 <a href="#request-body" id="request-body"></a>

以JSON格式发送请求体。

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

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

**示例请求**

```json
{
  "patchRequest": {
    "apiKey": "live_****************************",
    "projectId": "21",
    "txnId": 7714940366302672840,
    "profile": {
      "entry": [
        {
          "key": "email",
          "value": "jane.doe@example.com"
        }
      ]
    }
  }
}
```

#### 回复 <a href="#response" id="response"></a>

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

{% tabs %}
{% tab title="成功" %}

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

{% endtab %}

{% tab title="最终拒绝状态" %}

<pre class="language-json"><code class="lang-json"><strong>{
</strong>  "patchResult": {
    "resultCode": 231,
    "resultDesc": "Transaction already marked as completed, cannot be processed again. (error:231)",
    "txnId": 7714940366302672840
  }
}
</code></pre>

{% endtab %}

{% tab title="无效的电子邮件" %}

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

{% endtab %}
{% endtabs %}

**响应参数**

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

#### 错误代码 <a href="#notes" id="notes"></a>

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

### 典型流程 <a href="#typical-flow" id="typical-flow"></a>

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

#### 笔记 <a href="#notes-1" id="notes-1"></a>

* **默认情况下未启用收据发送功能。**&#x8981;为您的项目启用自动收据发送功能，请联系支付支持团队，邮箱地址为<codapay_integration@coda.co>。
* **上次更新的值会生效。**&#x5982;果`email`该值在初始化时或之前的补丁中已经设置过，则新值会替换它。使用字段已有的值进行补丁操作会返回成功，并且不会更改任何内容。
* **补丁不会发送 webhook。**&#x73B0;有交易完成通知仍会照常在根目录`Success`/`Failed`上触发。如果`email`已设置且启用了收据传递，则收据会发送到交易成功时当前对应的地址。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.coda.co/https-coda-payments.gitbook.io-zhong-wen-coda-private-technical-documentation/codapay/tuo-guan-zu-jian-ji-cheng/ka-pian/bu-fen-geng-xin-jiao-yi.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.