> 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/coda-portal/key-features/coda-transaction-report-delivery-options.md).

# Coda Transaction Report Delivery Options

## Introduction <a href="#w11xhfwyj91y" id="w11xhfwyj91y"></a>

This document provides publishers with an overview of Coda’s transaction reporting options and the specific steps required to access and set up the delivery of these reports. To help publishers stay up-to-date with transaction details, we offer reporting with flexible frequencies:

* **Daily**
* **Weekly**
* **Monthly**

## Sample of Report <a href="#ux08bk3ek5c3" id="ux08bk3ek5c3"></a>

The report will be sent through a CSV file. Please find the sample of the report below:

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

## Data Points & Types <a href="#report-data-points" id="report-data-points"></a>

The transaction report provides a comprehensive set of data points, offering publishers detailed insights into each transaction. **By default, the report is generated separately for each country**. For example, if transactions occur in four different countries, you will receive four separate report files.\
\
The following fields are returned in each report:

| Field Name                       | Description                                                                                                                                                                           |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Transaction Completed Time       | <p>The date and time when the transaction was successfully completed.<br></p><p>It is always based on the transaction’s local timezone.</p>                                           |
| Coda Transaction ID              | A unique identifier is assigned by Coda to each transaction for tracking and reference.                                                                                               |
| Merchant Order ID                | The identifier generated by the publisher or merchant for each order is used to match transactions in their system.                                                                   |
| Merchant ID                      | The unique identifier associated with the publisher or merchant account within the Coda system.                                                                                       |
| Payment Channel                  | The payment channel name used for the transaction.                                                                                                                                    |
| Processing Status                | <p>The status of the transaction.</p><p>It is always shown as ‘<strong>Successful’</strong>, as only successful transactions are returned.</p>                                        |
| Item Name                        | The name or description of the item (SKU) purchased in the transaction.                                                                                                               |
| Currency                         | The currency used for the transaction, represented by its three-letter ISO code (e.g., USD, SGD, IDR).                                                                                |
| Publisher Base Amount            | The base amount or item price provided by the publishers.                                                                                                                             |
| Publisher Used Reward Amount     | <p>The value of any rewards or discounts applied by the publisher to the transaction if they choose to co-fund a sponsorship with Coda.</p><p>By default, this should be 0.</p>       |
| Final Transaction Amount         | The total gross amount of the transaction after rewards deduction (excluding the Coda’s fee).                                                                                         |
| Publisher Applicable Tax         | The amount of tax applied to the transaction based on publisher's tax settings.                                                                                                       |
| End User Tax Surcharge (US / CA) | A surcharge amount applied specifically to end users in the United States or Canada to cover tax obligations.                                                                         |
| Fee Basis                        | <p>The basis or structure of the fee.</p><p>Values can be <strong>'Transaction value exclusive of any tax'</strong> or <strong>'Transaction value inclusive of any tax'.</strong></p> |
| Percentage-based fee             | The fee (in percentage) applied as a percentage of the transaction amount.                                                                                                            |
| Per-transaction fee              | A fixed fee amount charged per transaction, regardless of the transaction amount.                                                                                                     |
| Publisher Applicable WHT         | The amount (in percentage) of Withholding Tax (WHT) applicable to the publisher for this transaction.                                                                                 |
| Transaction Structure            | <p>The overall structure or type of the transaction.</p><p>Values can be <strong>'Sale of Digital Content'</strong> or <strong>''Payment Orchestration Service'.</strong></p>         |

## Report Schedule <a href="#ux08bk3ek5c3" id="ux08bk3ek5c3"></a>

Our system generates and delivers reports based on the selected frequency. Below is the schedule for report delivery:

* **Daily Report**: Sent on the next day at approximately **3 PM SGT**.
* **Weekly Report**: Sent on the **first day of the following week**.
* **Monthly Report**: Sent on the **2nd day of the following month**.

## Delivery Methods <a href="#ux08bk3ek5c3" id="ux08bk3ek5c3"></a>

There are three different methods for receiving Coda’s monthly transaction reports:

1. **Email** – Direct report delivery to your inbox.
2. **SFTP** – Secure File Transfer Protocol for automated retrieval.
3. **Webhook Notifications** – Notifications when a report is ready.

Each method has specific setup requirements, which this guide will walk you through in detail to ensure smooth and accurate delivery of transaction data. With this documentation, you’ll have all the information needed to configure your preferred reporting method, receive timely reports, and integrate them seamlessly into your workflows.

***

### 1. Delivery via Email <a href="#id-7zm9eqnbnmf" id="id-7zm9eqnbnmf"></a>

#### Overview <a href="#vdgtkoqhl6g6" id="vdgtkoqhl6g6"></a>

The daily/weekly/monthly transaction report can be sent directly to your email inbox. This is a simple and straightforward delivery method, suitable for those who prefer to receive and manage reports via their email system.

#### Steps to Set Up Email Delivery: <a href="#nvzmuj7vt844" id="nvzmuj7vt844"></a>

1. **Contact Information**: Provide us with the email address(es) where the monthly transaction report should be sent. You can specify multiple recipients if needed.
2. **Report Format**: The report will be delivered in a **CSV** format.
3. **Frequency**: The email will be sent on the 2nd day of each month and cover all transactions from the previous month.
4. **Subject Line**: The email subject will typically follow this format:
   * Subject: Codapay Transaction Report(s) for **\[Your Settlement Entity Name] - \[Month Year]**

#### Key Considerations <a href="#kinsicql57uu" id="kinsicql57uu"></a>

* Add our email domain to your safe sender list to avoid reports being sent to spam/junk folders.

***

### 2. Delivery via SFTP (Secure File Transfer Protocol) <a href="#pw46wd4vsq8q" id="pw46wd4vsq8q"></a>

#### Overview <a href="#q2slo9seqyp9" id="q2slo9seqyp9"></a>

SFTP is a secure method for transferring the monthly transaction report directly to your server. This option is ideal for organizations that want to automate the ingestion of data into internal systems or need higher security for sensitive data.

#### Steps to Set Up SFTP Delivery <a href="#ftfkpqcas8sy" id="ftfkpqcas8sy"></a>

1. **Server Setup**: You must have an active SFTP server where we can upload the monthly transaction report. This server should be configured to accept connections and allow file uploads.
2. **Provide Server Information**: Our Publisher Support team will ask for details regarding this information below
   * **IP Address**: Supply the IP address of your SFTP server & port number.
   * **Username**: Create and provide a username that will be used to access the server.
   * **Password or SSH Key**: You can either provide a password or set up an SSH key for authentication. We recommend SSH key authentication for higher security.
3. **Whitelist Coda’s IP Address:** Please whitelist these IP addresses to ensure we’re able to send the file to your system.\
   54.251.135.133

   52.76.92.206

   52.221.161.77

   52.221.30.252

   13.228.212.196
4. **Folder Path**: Indicate the specific directory path on your SFTP server where the file should be placed. Ensure that the directory has sufficient permissions to allow file uploads.
5. **Test Connection**: Before the first report is sent, a test connection will be established to verify that our system can securely connect to your SFTP server.
6. **File Naming Convention**: The file will be named using the following structure:
   * \[Settlement Entity Name]*(Settlement Id)*\[Merchant Group Id]*\[Country]Transaction\_Report\[Month]*\[Year].csv

#### Key Considerations <a href="#ellwe43klplq" id="ellwe43klplq"></a>

* Ensure your server has adequate storage for the monthly report files.
* Make sure to keep your server credentials updated, especially if password rotation policies are in place.
* If using SSH key authentication, ensure that you store and manage the key securely.

***

### 3. Delivery via Webhook Notification <a href="#k7xasgv2ptw2" id="k7xasgv2ptw2"></a>

#### Overview <a href="#id-2s39a9nncv14" id="id-2s39a9nncv14"></a>

Webhook notifications provide a method of alerting your system when the monthly transaction report is available. Instead of retrieving the report from email or SFTP, a webhook will notify your system, which can then download the report from a secure URL.

#### Steps to Set Up Webhook Delivery <a href="#n27slfkusfz" id="n27slfkusfz"></a>

1. **Webhook URL**: You need to provide a webhook endpoint (URL) where we will send a POST request once the monthly report is generated and ready for download.
2. Whitelist Coda’s IP Address. Please whitelist these IP addresses to ensure we’re able to send the file to your system\
   Production IPs: "52.221.161.77", "52.221.30.252", "13.228.212.196"
3. **Authentication**:
   * Optionally, the webhook can include an **authentication header** (such as a bearer token or API key) for security.
   * If you require this, provide the necessary credentials for the authentication process.

**Webhook Payload**: When the report is ready, we will send a POST request to your webhook URL with the following JSON payload:

**Sample payload for report notification:**

```json
{
   "notificationType": "report",
   "data": {
            "reportCycle": "daily"|"weekly"|"monthly",
            "reportUrl": "finance-files.codapayments.com/fileurl",
            "reportName": "[Settlement Entity Name]_(Settlement Id)_[Merchant Group Id]_[Country]_Transaction_Report_[Month]_[Year].csv ",
            "reportPeriodStart": "yyyymmdd",
            "reportPeriodEnd": "yyyymmdd",
            "reportEnvironment": "all"|"codapay"|"distribution"|"codashop"|"xshop"|"custom-commerce"
         }
}
```

**Report notification parameters:**

<table data-header-hidden><thead><tr><th>Parameter Name</th><th width="168">Type</th><th>Description</th></tr></thead><tbody><tr><td>notificationType</td><td>string</td><td>Type of notification. Will be “report”</td></tr><tr><td>data</td><td>object</td><td>Contains payload of the notification</td></tr><tr><td>data.reportCycle</td><td>string</td><td>Frequency of the report sent: daily / weekly / monthly</td></tr><tr><td>data.reportUrl</td><td>string</td><td>File address of the report</td></tr><tr><td>data.reportName</td><td>string</td><td>Name of the report</td></tr><tr><td>data.reportPeriodStart</td><td>string</td><td>starting transaction date in local country timezone</td></tr><tr><td>data.reportPeriodEnd</td><td>string</td><td>ending transaction date in local country timezone</td></tr><tr><td>data.reportEnvironment</td><td>string</td><td>Environment solution of the transaction</td></tr></tbody></table>

**Sample payload for invoice notification:**

<pre class="language-json"><code class="lang-json"><strong>{
</strong>    "notificationType": "invoice",
<strong>    "data": {
</strong>        "reportCycle": "monthly",
        "reportUrl": "finance-files.codapayments.com/fileurl",
        "reportName": "PublisherName_Invoice_date.csv",
        "reportPeriodStart": "yyyymmdd",
        "reportPeriodEnd": "yyyymmdd",
        "reportEnvironment": "all"
<strong>    }
</strong>}
</code></pre>

**Invoice notification parameters**<br>

<table data-header-hidden><thead><tr><th>Parameter Name</th><th width="220">Type</th><th>Description</th></tr></thead><tbody><tr><td>notificationType</td><td>string</td><td>Type of notification. Will be “invoice”</td></tr><tr><td>data</td><td>object</td><td>Contains payload of the notification</td></tr><tr><td>data.reportCycle</td><td>string</td><td>Frequency of the report sent: monthly</td></tr><tr><td>data.reportUrl</td><td>string</td><td>File address of the report</td></tr><tr><td>data.reportName</td><td>string</td><td>Name of the report</td></tr><tr><td>data.reportPeriodStart</td><td>string</td><td>Invoice date</td></tr><tr><td>data.reportPeriodEnd</td><td>string</td><td>Invoice due date</td></tr><tr><td>data.reportEnvironment</td><td>string</td><td>Environment solution of the transaction</td></tr></tbody></table>

**Responses**

No **Response** **body** is required for the response, the status code must be **200**.

| **Code** | **Description** |
| -------- | --------------- |
| 200      | OK              |

#### Key Considerations <a href="#y61xwaa5ar4" id="y61xwaa5ar4"></a>

* Ensure your webhook URL is accessible from external sources and secured with authentication to avoid unauthorized access.
* The URL provided for the report download will expire after a certain period (typically 30 days), so make sure to download the file in a timely manner.
* Implement logging in your system to track webhook notifications and any potential errors in the report retrieval process.

***

## Comparison of Delivery Methods <a href="#sl11morhtdl5" id="sl11morhtdl5"></a>

<table><thead><tr><th width="117">Method</th><th width="139">Delivery Time</th><th>Setup Complexity</th><th width="141">Security Level</th><th>Automation Potential</th></tr></thead><tbody><tr><td>Email</td><td>2nd day of each month</td><td>Low</td><td>Moderate (email security depends on the recipient)</td><td>Low</td></tr><tr><td>SFTP</td><td>2nd day of each month</td><td>Moderate</td><td>High (secure transfer)</td><td>High (automated file handling)</td></tr><tr><td>Webhook</td><td>2nd day of each month</td><td>Moderate</td><td>High (requires secure endpoint)</td><td>High (full automation of report retrieval)</td></tr></tbody></table>

## Conclusion <a href="#id-7147ttb80gcs" id="id-7147ttb80gcs"></a>

We offer three flexible methods to deliver your monthly transaction report, each tailored to different needs in terms of security, automation, and ease of use. Whether you prefer a simple email delivery, a secure file transfer via SFTP, or an automated system triggered by webhook notifications, we can accommodate your requirements.

If you have any questions or need assistance setting up any of the delivery methods, please contact our support team for guidance.<br>

### FAQ

This section provides answers to commonly asked questions about our reporting system, including report types, delivery schedules, file formats, and webhook handling. If you need further clarification, please refer to the FAQs below or reach out to our support team for assistance.

<details>

<summary><strong>What types of reports do you provide?</strong></summary>

We currently provide transaction reports on a daily, weekly, and monthly basis. You can choose the option that best suits your needs.

</details>

<details>

<summary><strong>What is the format of the transaction report?</strong></summary>

The report will be delivered in CSV format. By default, the file will be separated by country. If you have transactions from five countries, you will receive five separate files accordingly.

</details>

<details>

<summary><strong>What data points are included in the transaction report?</strong></summary>

The transaction report includes a comprehensive set of data points, such as Transaction Completion Time, Coda Transaction ID, Payment Channel, and more.

Refer [to this section](#report-data-points) to see the details.

</details>

<details>

<summary><strong>What is the estimated size of each report?</strong></summary>

Each report will follow the limit of a single CSV file, which can contain up to 900,000 records. If the total number of records exceeds this limit, multiple CSV files will be generated and bundled together in a single ZIP file for easy access.

</details>

<details>

<summary><strong>How can we automate the process of sending transaction reports to our system?</strong></summary>

You can use SFTP delivery or Webhook Notifications. SFTP delivery transfers transaction reports directly to your server while Webhook Notifications notify your system when a transaction report is available, allowing you to download it from a secure URL

</details>

<details>

<summary><strong>For webhook notification, how many webhook notifications can be sent in parallel?</strong></summary>

</details>

<details>

<summary><strong>Does the webhook always need to return a 200 OK status?</strong></summary>

Yes, currently only the 200 OK status is recognized and processed. We will update the status accordingly once we introduce more status

</details>

<details>

<summary><strong>How long is the report download URL valid?</strong></summary>

The report download URL is valid for 12 months before it expires.

</details>

<details>

<summary><strong>Are the reports processed in real-time?</strong></summary>

No, reports are not processed in real-time. The daily report is generated and sent the following day at around 3 PM SGT. The monthly report is sent on the 2nd day of the following month.

</details>

## Version History <a href="#id-7sqy8l3w2n" id="id-7sqy8l3w2n"></a>

| Version | Date        | Changelog               |
| ------- | ----------- | ----------------------- |
| 1.0.0   | 22 Oct 2024 | First Draft Version     |
| 1.0.1   | 03 Jan 2025 | Adding Data Points      |
| 1.0.2   | 18 Feb 2024 | Adding Sample of Report |
| 1.0.3   | 25 Feb 2024 | Adding FAQ Section      |


---

# 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/coda-portal/key-features/coda-transaction-report-delivery-options.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.