> 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/coda-hou-tai/jiao-yi-bao-gao-chuan-di-fang-shi.md).

# 交易报告传递方式

## 概览

\
本文档向发布商概述了 Coda 的交易报告选项以及访问和设置这些报告传递所需的具体步骤。为了帮助发布商及时了解交易详细信息，Coda 提供灵活的报告频率：

* **每日报告（Daily）**
* **每周报告（Weekly）**
* **每月报告（Monthly）**

发行商可以根据自身业务需求选择适合的报告频率，以便高效管理和分析交易数据。

## 报告样本

报告将通过 CSV 文件发送。请参阅以下报告示例：

{% file src="/files/tjTTnHdjJQi5qifa6l0q" %}

## 数据点与类型

交易报告提供了全面的数据点，使发行商能够深入了解每笔交易。**默认情况下，报告会按国家分别生成。**例如，如果交易发生在四个不同的国家，您将收到四个独立的报告文件。

每份报告包含以下字段：

<table><thead><tr><th width="301">字段名称</th><th>描述</th></tr></thead><tbody><tr><td>Transaction Completed Time</td><td><p>交易成功完成的日期和时间。</p><p>它始终基于交易的当地时区。</p></td></tr><tr><td>Coda Transaction ID</td><td>Coda 为每笔交易分配一个唯一的标识符，以供跟踪和参考。</td></tr><tr><td>Merchant Order ID</td><td>发布商或商家为每个订单生成的标识符用于匹配其系统中的交易。</td></tr><tr><td>Merchant ID</td><td>与 Coda 系统内的发布商或商家帐户关联的唯一标识符。</td></tr><tr><td>Payment Channel</td><td>交易的支付渠道名称。</td></tr><tr><td>Processing Status</td><td><p>交易状态。</p><p>它始终显示为<strong>“成功 (Successful)”</strong>，因为仅返回成功的交易。</p></td></tr><tr><td>Item Name</td><td>交易中购买的商品 (SKU) 名称或描述。</td></tr><tr><td>Currency</td><td>交易的货币，由三个字母的 ISO 代码表示<br>（例如 USD、SGD、IDR）。</td></tr><tr><td>Publisher Base Amount</td><td>发布商提供的金额或商品价格。</td></tr><tr><td>Publisher Used Reward Amount</td><td><p>如果发行商选择与 Coda 共同资助赞助，则他们在交易中应用的任何奖励或折扣的价值。</p><p>默认情况下，该值应为 0。</p></td></tr><tr><td>Final Transaction Amount</td><td>扣除奖励后的交易总金额（不包括 Coda 费用）。</td></tr><tr><td>Publisher Applicable Tax</td><td>根据发布商的税务设置应用于交易的税额。</td></tr><tr><td>End User Tax Surcharge (US / CA)</td><td>专门适用于美国或加拿大最终用户的附加费金额，用于支付纳税义务</td></tr><tr><td>Fee Basis</td><td>费用的基础或结构。<br>值可以是 <strong>'不包括任何税费的交易金额'</strong> 或 '<strong>包括任何税费的交易金额'</strong>。</td></tr><tr><td>Percentage-based fee</td><td>作为交易金额百分比收取的费用（以百分比表示）。</td></tr><tr><td>Per-transaction fee</td><td>每笔交易收取的固定费用金额，无论交易金额大小。</td></tr><tr><td>Publisher Applicable WHT</td><td>适用于发布商本次交易的预扣税 (WHT) 金额（以百分比表示）。</td></tr><tr><td>Transaction Structure</td><td><p>交易的总体基础或类型。</p><p>值可以是“<strong>数字内容销售</strong>”或“<strong>支付编排服务</strong>”。</p></td></tr></tbody></table>

## **报告发送时间表**

我们的系统会根据所选的频率生成并发送报告。以下是报告的发送时间安排：

* **每日报告**：在次日 **新加坡时间（SGT）下午 3 点** 左右发送。
* **每周报告**：在下一周的**第一天**发送。
* **每月报告**：在下一月的 **第二天** 发送。

***

## 传递方式

接收 Coda 每月交易报告有三种不同的方式：

1. **电子邮件** – 将报告直接发送到您的收件箱。
2. **SFTP** – 使用安全文件传输协议（SFTP）进行自动化检索。
3. **Webhook 通知** – 在报告准备好时实时通知。

每种方式都有特定的设置要求，本指南将详细介绍如何设置，以确保交易数据的顺利和准确传递。通过本文档，您将获得配置首选报告方式、及时接收报告并将其无缝集成到工作流程中的所有必要信息。

***

## 1. 通过电子邮件传递

### 概述

每日/每周/每月的交易报告可以直接发送到您的电子邮件收件箱。这是一种简单直接的传递方式，适用于那些更喜欢通过电子邮件系统接收和管理报告的用户。

### **设置电子邮件**传递**的步骤：**

1. **联系信息：** 提供我们您希望接收月度交易报告的电子邮件地址。如果需要，可以指定多个收件人。
2. **报告格式：** 报告将以 **CSV** 格式发送。
3. **频率：** 电子邮件将在每个月的第二天发送，涵盖前一个月的所有交易。
4. **主题：** 电子邮件的主题通常遵循以下格式：

> 邮件标题：
>
> Codapay 交易报告 **\[您的结算实体名称] - \[年月]**\
> Codapay Transaction Report(s) for **\[Your Settlement Entity Name] - \[Month Year]**

### **关键注意事项**

* 请将我们的电子邮件域名添加到您的安全发件人列表，以避免报告被发送到垃圾邮件/垃圾文件夹。

***

## **2. 通过 SFTP（安全文件传输协议）**&#x4F20;递

### **概述**

SFTP 是一种安全的方式，将每月的交易报告直接传输到您的服务器。这个选项非常适合希望将数据自动导入内部系统或需要更高安全性的组织，尤其是处理敏感数据时。

### **设置 SFTP** 传递**的步骤：**

1. **服务器设置：** 您必须拥有一个可用的 SFTP 服务器，我们可以将每月的交易报告上传到该服务器。该服务器应该已配置为接受连接并允许文件上传。
2. **提供服务器信息：** 我们的 Codapay 技术支持团队将要请您提供以下信息：

* **IP 地址：** 提供您的 SFTP 服务器的 IP 地址和接口号 (Port Number)。
* **用户名：** 创建并提供用于访问服务器的用户名。
* **密码或 SSH 密钥：** 您可以提供密码或设置 SSH 密钥进行身份验证。我们推荐使用 SSH 密钥进行身份验证，以提高安全性。

3. **将 Coda 的 IP 地址列入白名单：** 请将以下 IP 地址列入白名单，以确保我们能够将文件发送到您的系统：\
   54.251.135.133\
   52.76.92.206\
   52.221.161.77\
   52.221.30.252\
   13.228.212.196
4. **文件夹路径 (Folder Path)：** 指定在 SFTP 服务器上存放文件的具体目录路径。确保该目录具有足够的权限，以允许文件上传。
5. **测试连接：** 在发送第一个报告之前，将建立一个测试连接，以验证我们的系统是否能够安全地连接到您的 SFTP 服务器。
6. **文件命名规范：** 文件将采用以下结构命名：\
   \- codapay\_transaction\_report\_\[公司名称] \_ \[月份] \_  \[年份].csv

**关键注意事项：**

* 确保您的服务器有足够的存储空间来保存每月的报告文件。
* 确保定期更新服务器的凭据，特别是在启用密码轮换策略时。
* 如果使用 SSH 密钥认证，确保安全地存储和管理密钥。

***

## **3. 通过 Webhook 通知**传递

### **概述**

Webhook 通知提供了一种近乎实时的方法，通知您的系统月度交易报告何时可用。与通过电子邮件或 SFTP 检索报告不同，Webhook 将通知您的系统，您可以从安全的 URL 下载报告。

### **设置 Webhook** 传递**的步骤：**

1. **Webhook URL：** 您需要提供一个 Webhook 接口（URL），我们将在月度报告生成并准备好下载时，向该 URL 发送 POST 请求。
2. **将 Coda 的 IP 地址列入白名单：** 请将以下 IP 地址列入白名单，以确保我们能够将文件发送到您的系统。\
   生产环境 IP 地址： "52.221.161.77", "52.221.30.252", "13.228.212.196"
3. **身份验证：**
   1. 可选：Webhook 可以包含**身份验证标题**（例如 Bearer token 或 API 密钥）以提高安全性。
   2. 如果您需要此身份验证，请提供必要的凭据。

**Webhook Payload：** 当报告准备好时，我们将向您的 Webhook URL 发送一个 POST 请求，并附带以下 JSON 格式的payload：

**报告通知示例：**

```json
{
   "notificationType": "report",
   "data": {
            "reportCycle": "daily"|"weekly"|"monthly",
            "reportUrl": "finance-files.codapayments.com/fileurl",
            "reportName": "PublisherName_Transaction_Report_date.csv.csv",
            "reportPeriodStart": "yyyymmdd",
            "reportPeriodEnd": "yyyymmdd",
            "reportEnvironment": "all"|"codapay"|"distribution"|"codashop"|"xshop"|"custom-commerce"
         }
}
```

**报告通知参数：**

<table><thead><tr><th></th><th width="183"></th><th></th></tr></thead><tbody><tr><td>notificationType</td><td>string</td><td>通知类型。将会是“Report”</td></tr><tr><td>data</td><td>object</td><td>包含有效负载的通知</td></tr><tr><td>data.reportCycle</td><td>string</td><td>报告发送频率：每日/每周/每月</td></tr><tr><td>data.reportUrl</td><td>string</td><td>报告的文件地址</td></tr><tr><td>data.reportName</td><td>string</td><td>报告名称</td></tr><tr><td>data.reportPeriodStart</td><td>string</td><td>当地国家时区的开始交易日期</td></tr><tr><td>data.reportPeriodEnd</td><td>string</td><td>当地国家时区的结束交易日期</td></tr><tr><td>data.reportEnvironment</td><td>string</td><td>交易环境解决方案</td></tr></tbody></table>

**发票通知示例：**

```json
{
    "notificationType": "invoice",
    "data": {
        "reportCycle": "monthly",
        "reportUrl": "finance-files.codapayments.com/fileurl",
        "reportName": "PublisherName_Invoice_date.csv",
        "reportPeriodStart": "yyyymmdd",
        "reportPeriodEnd": "yyyymmdd",
        "reportEnvironment": "all"
    }
}
```

**发票通知参数：**

<table><thead><tr><th></th><th width="187"></th><th></th></tr></thead><tbody><tr><td>notificationType</td><td>string</td><td>通知类型。将会是“Invoice”</td></tr><tr><td>data</td><td>object</td><td>包含通知的payload</td></tr><tr><td>data.reportCycle</td><td>string</td><td>报告发送频率：每日/每周/每月</td></tr><tr><td>data.reportUrl</td><td>string</td><td>报告的文件地址</td></tr><tr><td>data.reportName</td><td>string</td><td>报告名称</td></tr><tr><td>data.reportPeriodStart</td><td>string</td><td>发票日期</td></tr><tr><td>data.reportPeriodEnd</td><td>string</td><td>发票到期日</td></tr><tr><td>data.reportEnvironment</td><td>string</td><td>交易环境解决方案</td></tr></tbody></table>

**响应**

响应无需包含 **Response Body**，但状态码必须返回 **200**。

| 代码  | 描述 |
| --- | -- |
| 200 | OK |

**关键注意事项：**

* 确保您的 Webhook URL 对外部来源可访问，并且通过身份验证机制保护，以避免未经授权的访问。
* 提供的报告下载 URL 会在一定时间后过期（**通常为 30 天**），因此请确保及时下载文件。
* 在您的系统中实现日志记录功能，以跟踪 Webhook 通知以及报告检索过程中的任何潜在错误。

***

## 传递方式对比

<table><thead><tr><th>方法</th><th>传递时间</th><th width="109">设置复杂性</th><th>安全等级</th><th>自动化潜力</th></tr></thead><tbody><tr><td>电子邮件</td><td>每个月的第 2 天</td><td>低</td><td>中等（电子邮件安全性取决于收件人）</td><td>低</td></tr><tr><td>SFTP（安全文件传输协议）</td><td>每个月的第 2 天</td><td>中等</td><td>高（安全传输）</td><td>高（自动文件处理）</td></tr><tr><td>Webhook</td><td>每个月的第 2 天</td><td>中等</td><td>高（需要安全接口）</td><td>高（报告检索完全自动化）</td></tr></tbody></table>

## **结论**

我们提供三种机动的方式来传送您的月度交易报告，每种方式都根据安全性、自动化和易用性方面的不同需求量身定制。无论您是偏好简单的电子邮件传送、通过 SFTP 进行安全的文件传输，还是通过 Webhook 通知触发自动化系统，我们都能满足您的需求。

如果您有任何问题或需要帮助设置任何传送方式，请联系我们的支持团队以获取指导。

## **常见问题（FAQ）**

本部分解答了关于我们的报告系统的常见问题，包括报告类型、交付时间表、文件格式以及 Webhook 处理方式。如果您需要进一步的说明，请查阅以下常见问题或联系我们的支持团队获取帮助。

<details>

<summary>您提供哪些类型的报告？</summary>

我们目前提供 **每日、每周和每月** 交易报告。您可以选择最适合您需求的选项。

</details>

<details>

<summary>交易报告的格式是什么？</summary>

报告将以 **CSV 格式** 提供。默认情况下，文件将按 **国家** 分开。如果您的交易涉及 **五个国家**，您将相应地收到 **五个独立的文件**。

</details>

<details>

<summary>交易报告包含哪些数据点？</summary>

交易报告包含一整套 **详细的数据点**，例如：**交易完成时间、Coda 交易 ID、支付渠道** 等。

请参考 [#shu-ju-dian-yu-lei-xing](#shu-ju-dian-yu-lei-xing "mention") 以查看详细信息。

</details>

<details>

<summary>每个报告的预计大小是多少？</summary>

每个报告的大小受 **单个 CSV 文件** 的限制，每个 CSV 文件最多可包含 **900,000 条记录**。\
如果记录总数超过此限制，将会生成多个 **CSV 文件**，并捆绑在 **ZIP 文件** 中，以便于访问。

</details>

<details>

<summary>如何自动化发送交易报告到我们的系统？</summary>

您可以使用 **SFTP** 或 **Webhook 通知**：

* **SFTP** 直接将交易报告传输到您的服务器。
* **Webhook 通知** 在交易报告可用时通知您的系统，让您可以从一个安全的 **URL** 下载报告

</details>

<details>

<summary>Webhook 是否始终需要返回 HTTP  Status Code = 200 <kbd>OK</kbd> 状态？</summary>

是的，目前系统仅识别并处理 **200 OK** 状态。如果未来支持更多状态，我们会相应更新。

</details>

<details>

<summary>报告下载 URL 的有效期是多久？</summary>

报告下载 URL **有效期为 12 个月**，到期后将无法访问。

</details>

<details>

<summary>报告是否是实时处理的？</summary>

否，报告并不是实时处理的：

* **每日报告** 在次日 **新加坡时间（SGT）下午 3 点左右** 生成并发送。
* **月度报告** 在 **次月的第 2 天** 发送。

</details>

## 版本历史

|       | 日期               | 变更日志        |
| ----- | ---------------- | ----------- |
| 1.0.0 | 2024 年 10 月 22 日 | 第一稿版本       |
| 1.0.1 | 2025 年 1 月 3 日   | 添加数据点       |
| 1.0.2 | 2024 年 2 月 18 日  | 添加报告样本      |
| 1.0.3 | 2024 年 2 月 25 日  | 添加常见问题（FAQ） |


---

# 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/coda-hou-tai/jiao-yi-bao-gao-chuan-di-fang-shi.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.