Coda Transaction Report Delivery Options

Introduction

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

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

Sample of Publisher Transaction Report.csv

1KB

Open

Data Points & Types

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	The date and time when the transaction was successfully completed. It is always based on the transaction’s local timezone.
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	The status of the transaction. It is always shown as ‘Successful’, as only successful transactions are returned.
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	The value of any rewards or discounts applied by the publisher to the transaction if they choose to co-fund a sponsorship with Coda. By default, this should be 0.
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	The basis or structure of the fee. Values can be 'Transaction value exclusive of any tax' or 'Transaction value inclusive of any tax'.
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	The overall structure or type of the transaction. Values can be 'Sale of Digital Content' or ''Payment Orchestration Service'.

Report Schedule

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

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

Overview

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:

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

• 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)

Overview

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

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

• 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

Overview

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

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:

{
   "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:

notificationType	string	Type of notification. Will be “report”
data	object	Contains payload of the notification
data.reportCycle	string	Frequency of the report sent: daily / weekly / monthly
data.reportUrl	string	File address of the report
data.reportName	string	Name of the report
data.reportPeriodStart	string	starting transaction date in local country timezone
data.reportPeriodEnd	string	ending transaction date in local country timezone
data.reportEnvironment	string	Environment solution of the transaction

Sample payload for invoice notification:

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

Invoice notification parameters

notificationType	string	Type of notification. Will be “invoice”
data	object	Contains payload of the notification
data.reportCycle	string	Frequency of the report sent: monthly
data.reportUrl	string	File address of the report
data.reportName	string	Name of the report
data.reportPeriodStart	string	Invoice date
data.reportPeriodEnd	string	Invoice due date
data.reportEnvironment	string	Environment solution of the transaction

Responses

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

Code	Description
200	OK

Key Considerations

• 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

Method	Delivery Time	Setup Complexity	Security Level	Automation Potential
Email	2nd day of each month	Low	Moderate (email security depends on the recipient)	Low
SFTP	2nd day of each month	Moderate	High (secure transfer)	High (automated file handling)
Webhook	2nd day of each month	Moderate	High (requires secure endpoint)	High (full automation of report retrieval)

Conclusion

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.

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.

What types of reports do you provide?

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

What is the format of the transaction report?

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.

What data points are included in the transaction report?

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 to see the details.

What is the estimated size of each report?

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.

How can we automate the process of sending transaction reports to our system?

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

For webhook notification, how many webhook notifications can be sent in parallel?

Does the webhook always need to return a 200 OK status?

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

How long is the report download URL valid?

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

Are the reports processed in real-time?

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.

Version History

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