# How to upload your payment files into the CDQ Trust Score Data Pool: A Step-by-Step Guide

This guide explains how you can securely upload either an unconsolidated payment extract (e.g., `SAP REGUH` file) or a consolidated payment summary into your private Bank Account Storage within CDQ.

## Overview

The primary purpose of this upload is to enable your organization to protect itself against payment fraud. By storing, structuring, and analyzing your outgoing payment transactions, CDQ’s Fraud Prevention Services—including the Trust Score—help you evaluate the bank accounts you're paying to and avoid sending money to fraudulent accounts.

Your uploaded payment data—whether unconsolidated or consolidated—becomes the basis for:

- Identifying previously used and reliable beneficiary bank accounts
- Recognizing suspicious or unverified accounts
- Enhancing CDQ's Trust Score and alerting mechanisms
- Strengthening your internal controls before each payment run


In addition, your anonymized data contributes to the broader CDQ Data Sharing Community, improving fraud prevention insights across participating organizations—including yours.

The upload process consists of four essential and secure steps:

1. Requesting a pre-signed upload link
2. Uploading the file
3. Triggering the import
4. Optionally checking the status of the job


**Learning Goals**

In this tutorial, you will learn how to:

- Prepare unconsolidated and consolidated payment files for upload
- Understand the differences and requirements for each file type
- Request a secure upload link from CDQ
- Upload your payment file to CDQ's cloud environment
- Trigger the import and select feature toggles
- Check the status of your import job
- Understand data sharing options and implications for fraud prevention


## Prerequisites

### Authorization

Before trying CDQ APIs, user must be authenticated:

1. Paste the API Key in the console's security bar into the `X-API-KEY` field.


![](/assets/auth7.0d4fb05fa55bc16d828c76e9976f979930ffadb949cfc149a6617cc6518ab57d.6fde6558.png)

1. After pasting the API Key, the green padlock will appear.


![](/assets/auth8.28e02515b78db57ec32c07fd6bd7d296484e64f65ef6a3bc5296520cb1da8d65.6fde6558.png)

Be careful
Green padlock doesn't mean that the API Key was pasted correctly.

1. Check your API key for missing characters or extra space before trying.


#### No API Key?

1. Check how to get one on [authentication page](/documentation/instructions/authentication).
2. Follow the steps above.


### Documentation

Check the [Bankaccount Data API Documentation](/documentation/api/bankaccount-data/quickstart) for more details.

## Step 1: File Extraction and Preparation

There are two types of payment files that CDQ supports for fraud prevention and bank account monitoring:

1. **Unconsolidated Payment Files** – These contain individual transaction records (e.g., `SAP REGUH` extract). Each row reflects a single payment made to a bank account. This is the preferred approach due to its precision and flexibility.
2. **Consolidated Payment Files** – These are pre-aggregated on the level of a bank account and summarize payment relationships. While still useful, consolidated files must meet several specific preparation requirements.


### Differences between Unconsolidated and Consolidated Files

| Aspect | Unconsolidated Files (e.g., REGUH) | Consolidated Files |
|  --- | --- | --- |
| Content | Individual payments to bank accounts | Aggregated history per bank account |
| Preferred? | Yes | Use only if no transactional data is available |
| Data Freshness Filtering | Performed automatically by CDQ | Must be done by you before upload |
| First / Last Payment Dates | Optional (can be derived) | Mandatory (must be included) |
| Inclusion in Fraud Pool | All rows processed | Rows **without last payment date** are excluded |


#### Preparation for Consolidated Files

If you decide to submit a consolidated file, please ensure you:

- **Filter your data:** Only include payments made between 90 days ago and 2 years ago. CDQ cannot filter consolidated data.
- **Include time range:** Both the first payment date and last payment date to the payee must be provided.
- **Avoid missing values:** Records without a valid last payment date will not be considered for Fraud Prevention scoring and will only be stored in your private Bank Account Storage.


### Required CSV Structure

| # | Payment System Field (sourceAttributes) | CDQ Field (targetAttributes) | Description | REGUH Import |
|  --- | --- | --- | --- | --- |
| 1 | ziban | internationalBankAccountIdentifier | IBAN of the account used in the transaction | Mandatory |
| 2 | zbnkn | nationalBankAccountIdentifier | National-format account number | Mandatory |
| 3 | zswif | bank.internationalBankIdentifier | SWIFT/BIC of the executing/receiving bank | Mandatory |
| 4 | zbnkl | bank.nationalBankIdentifier | National bank code (e.g., BLZ, Sort Code) | Mandatory |
| 5 | zbnks | bank.address.country.shortName | Country of the bank (e.g., DE, FR in [ISO 3166-2-format](https://en.wikipedia.org/wiki/ISO_3166-2)) | Mandatory |
| 6 | zaldt | vendorPaymentSummary.lastPaymentDate | Most recent payment date to this payee (format: yyyy-MM-dd, e.g., 2024-07-15) | Mandatory |
| 7 | first_zaldt | vendorPaymentSummary.firstPaymentDate | First recorded payment date to this payee (format: yyyy-MM-dd, e.g.,2024-07-15) | Not used in REGUH import |
| 8 | name1 | payees[0].name | Name of the payee | Mandatory |
| 9 | nop | vendorPaymentSummary.numberOfPayments | Total number of payments made to this payee | Not used in REGUH import |


Each row in your CSV represents either a single payment (in the case of unconsolidated files) or a summary of historical transactions with a bank account (in the case of consolidated files). Both structures are supported by CDQ.

If required fields are missing or misnamed, the import will not proceed.
Fields marked as 'Not used in REGUH import' are instead used for the import of consolidated data (formerly referred to as "whitelist import").

## Step 2: Requesting an Upload Link from CDQ

To begin the upload, you must first inform CDQ of the file you intend to send. This creates a secure and traceable upload session tied to your organization. This link will invalidate itself after first use.

CDQ will respond with a pre-signed, one-time upload URL. This URL ensures that only your organization can upload this file and that the file is properly attributed in the import process.

### What you need to do

Send a request to CDQ’s upload endpoint:

1. Use the **Request File Upload** endpoint,
2. Adjust the **Body** section by specifying the payment file name,
3. Send the request,


1. Check the response for the `uploadLink`.


Save the returned `uploadLink` for the next step.

In the response, you will find three important parameters:

- The `uploadLink` with the link to be used in the next step.
- The `uploadMethod` with the method to be used during the upload.
- The `url` with the link to your uploaded file.


Response example:


```json
{
    "uploadLink": "https://example.org/some.line", # This will be dynamically assigned
    "uploadMethod": "PUT",
    "url": "customer-uploads/cdq/user-id/acme_bankdata_2025-07.csv"
}
```

## Step 3: Uploading Your File to CDQ

With the upload link in hand, use it to transfer the actual file into CDQ’s cloud-based staging environment. At this point, the file is stored securely, but not yet processed. It’s simply held and ready for you to trigger the import.

### What you need to do

Use an HTTP PUT request to upload your file:


```http
PUT <uploadLink>
Body: Binary content of acme_bankdata_2025-07.csv
```

Once completed, the file is staged and ready to be imported.

## Step 4: Triggering the Import into Your Bank Account Storage

After uploading, you must explicitly trigger the import. This final step activates CDQ’s processing engine to:

- Validate the file structure
- Transform the contents according to your configured mapping
- Store the data securely in your private Bank Account Storage


Once imported, your data is available to:

- Power Trust Scores for the payee accounts you interact with
- Alert you to unusual account usage patterns
- Enhance your fraud prevention workflows


You can optionally enable feature toggles to control how the import is executed:

**Available feature toggles:**

- **`CLEAR_STORAGE`**: Clears all previously imported data from your Bank Account Storage before importing the new file. This will result in only the newly uploaded data remaining in the storage. Use this option **only with special consideration**, as it effectively resets your Bank Account Storage and removes all historic data. Only one of the feature toggles should be used at the same time.
- **`MERGE_PAYMENTS`**: This is the default behavior. It consolidates transaction records into existing bank account entries when applicable, allowing CDQ to merge multiple payments into a single aggregated view. It does not delete existing entries in the Bank Account Storage and ensures that historical data remains intact. Only one of the feature toggles should be used at the same time.


### What you need to do

Send a request to CDQ’s upload endpoint:

1. Use the **Import Bank Accounts** endpoint,
2. Adjust the **Body** section by specifying:
  - `dataTransformationDefinitionId`,
  - `url`,
  - `featuresOn`,
3. Send the request,


## Step 5 (Optional): Check the Status of the Import Job

If you want to confirm that your file was successfully processed, you can check the status of the import job using the job ID returned in Step 4.

### How to Check the Job Status

Send a GET request to CDQ’s status endpoint:

1. Use the **Import Job Progress** endpoint,
2. Adjust the **Path** section by specifying:
  - `id`,
  - `storageId`,
3. Send the request,


### Example Response


```json
{
  "id": "9203753a-d64e-4a06-bebd-3f366b72da7",
  "status": "FINISHED",
  "progress": 100,
  "parameters": {
    "url": "customer-uploads/cdq/your.file.csv",
    "featuresOn": ["CLEAR_STORAGE", "MERGE_PAYMENTS"]
  }
}
```

#### Possible Status Values

| Status | Meaning |
|  --- | --- |
| `UNKNOWN` | The job status is not known |
| `CREATED` | Job was created but not started |
| `PERSISTED` | Job was stored in the system |
| `SCHEDULED` | Job will start at a scheduled time |
| `WAITING` | Job is waiting for a condition |
| `RUNNING` | Import is currently in progress |
| `FINISHED` | Job completed successfully |
| `FAILED` | Job completed but failed |
| `CANCELED` | Job was canceled |
| `DIED` | Job terminated unexpectedly |


If your job status is **FAILED** or **DIED**, check your file format, retry the import, or contact CDQ support with the job ID.

## Summary

The diagram below illustrates the full process of uploading either **unconsolidated** (preferred) or **consolidated** payment files to CDQ. It highlights:

- The initial decision point: whether you’re uploading detailed payment records or a pre-aggregated summary.
- Specific requirements for each file type:
  - **Unconsolidated:** Each row is a payment; no manual filtering needed.
  - **Consolidated:** Must exclude payments <90 days or >2 years old and must contain both first and last payment dates.
- A unified upload and import workflow for both file types:
  - Step-by-step: Register → Upload → Trigger Import → (optional) Status Check.
- The effect of feature toggles:
  - **MERGE_PAYMENTS** (default): Adds to existing data.
  - **CLEAR_STORAGE:** Replaces all existing entries — use with caution!
This diagram helps clarify each action, its conditions, and its outcome, reducing the risk of missteps.
![](/assets/upf-img001.4acc9a196788adccef0d88d4ad0d83026a9675d24c2a1d235442794fbc4d91dc.106d4904.png)


### Workflow Steps

| Step | What You Do | What Happens |
|  --- | --- | --- |
| Step 1 | Export **unconsolidated** payment data and format as CSV | You prepare your unconsolidated data file (preferred method) |
| Step 1 (alt.) | Export **consolidated** payment data and format as CSV | You prepare a pre-aggregated account-level summary for upload |
| Step 2 | Register file with CDQ | You receive a secure upload URL |
| Step 3 | Upload the CSV via PUT | File is stored safely in CDQ’s cloud |
| Step 4 | Start processing and validation | Data is imported and ready for fraud prevention |
| Step 5 | Use GET /import/{jobId} | Confirm success or investigate issues |


## Data Sharing of Uploaded Data

Once uploaded, the payment data is stored in the **CDQ Bank Account Data Mirror**, which can be accessed via the CDQ Cloud Apps under [this](https://apps.cdq.com/dashboard/management?tab=Bank+Account+Data+Mirror) link.

![](/assets/upf-img002.d479b57e46d5cbe1ebb9002798953d2a7624fb836379ddd7009247a7bf898bc2.106d4904.png)

The Bank Account Data Mirror is automatically created for your organization.

- **Sharing is enabled by default**.
- **Sharing applies to the entire storage**, not on a record-level.
- If desired, you can disable sharing under the "**Edit Bank Account Data Mirror**" menu in the app.


Disabling sharing means that your uploaded payment information will only be used internally and not contributed to the CDQ Data Sharing Community. Records once shared cannot be removed from the Sharing Pool.

## Why This Process Matters

This process is essential to protect your organization against payment fraud. Uploading your payment data gives you the ability to:

- Evaluate the trustworthiness of payee accounts
- Avoid payments to risky or previously unseen accounts
- Identify accounts that lack positive payment history
- Receive real-time support from CDQ’s Trust Score and fraud prevention tools


By securely uploading your transaction history, you gain transparency over your payment behavior and activate intelligent services that help you avoid financial losses.

And while your anonymized data also contributes to the CDQ Data Sharing Community, the primary value is for you—to reduce your exposure to fraud, proactively safeguard your payment operations, and increase trust in your daily financial processes.

## Your opinion matters!

We are constantly working on providing an outstanding user experience with our products. Please share your opinion about this tutorial!