Chargebacks upload

Send historical chargeback feedback to your anti-fraud providers through DEUNA.

Ask your DEUNA Technical Account Manager which environments, anti-fraud connections, file-delivery method, directories, and processing schedule are enabled for your merchant before sending production data. Not every dispute is evidence of fraud; include only the chargeback feedback agreed for the configured anti-fraud provider.

How chargebacks work#

DEUNA enables you to upload received chargeback feedback by email or SFTP and forward it to the configured anti-fraud provider. This feedback can help the provider improve its risk models.

Without timely outcome feedback, an anti-fraud provider has less information with which to identify similar fraud patterns.

Improve antifraud results

Learn how chargebacks improve your anti-fraud strategy.

Corrects "False Negatives"

The model's main job is to score transactions.

When a chargeback represents confirmed fraud, it is a strong false-negative signal: the model treated the transaction as acceptable, but the later outcome showed that it was fraudulent.

By uploading agreed chargeback feedback, the provider can use those outcomes to identify patterns it previously missed.

Powers Pattern Recognition

The anti-fraud model analyzes thousands of data points.

When it receives a chargeback, it re-evaluates all the data associated with that failed transaction:

1. What email address was used?
2. What device fingerprint?
3. What was the shipping address?
4. What was the time of day?

The model can now find new, hidden patterns. For example, it might learn that transactions from a specific IP range using a new email and buying digital goods are suddenly much riskier than it originally thought.

Enables Link Analysis

Fraudsters often reuse emails, devices, or shipping addresses.

When you upload a chargeback, the provider links that fraud to every data point in the transaction.

1. Before: The fraudster's device (Device_XYZ) was seen as safe.
2. After: You upload a chargeback for that transaction. Device_XYZ is now flagged as high-risk.
3. Result: The next time any transaction comes from Device_XYZ.

The provider can use the new signal when evaluating later transactions associated with the same risk indicators. The resulting decision still depends on the provider's model and your configured risk policy.

Keeps the Model Up-to-Date

Fraud tactics change constantly. The patterns that worked for fraudsters last month will be different next month.

Uploading chargebacks the closest to real-time is the only way to ensure the machine learning model is adapting to these new tactics as fast as they appear.

In short, uploading chargebacks is not just an administrative task; it is the core of the machine learning process.

It's how you actively teach the system to get smarter and stop losing your money, and DEUNA helps you in this journey.

Required chargeback information

The following information is required per chargeback event to properly feed back to the anti-fraud providers:

Chargeback options

DEUNA offers two options depending on the merchant's requirements, timing, and environment:

• Send the chargebacks in a CSV file to chargebacks@deuna.com

  • Only for Production transactions.

  • The CSV file name must be in the format UUID-DDMMAA.csv

    • DEUNA merchant ID (UUID): 37e21ead-3951-4cbc-b075-9c635f4b8933
    • Date in DDMMAA: 051225
    • Example:37e21ead-3951-4cbc-b075-9c635f4b8933-051225.csv

  • The data format should be as follows

    transaction_id	external_id	chargeback_identifier	chargeback_status	chargeback_reason_code	chargeback_case_id	merchant_chargeback_id	chargeback_amount	detail	chargeback_date
    a596f725-e22b-411f-ac51-c94b2386b39b	merchant_test_5	chargeback_test_5	open	0003	cbk_test_5	merchant_cbk_test_5	2000	En proceso judicial	2025-10-30T11:20:00Z
    d3daecd7-6f3a-4cb4-98a8-c077cfd5b9d9	merchant_test_6	chargeback_test_6	lost	4837	cbk_test_6	merchant_cbk_test_6	550	Goods/Services not received	2025-10-30T11:21:00Z

    
    
• Send chargebacks in JSON format through SFTP by following the guide below.
  • For either Sandbox and Production transactions.
  • Processing begins after the file is received. Confirm the expected schedule with your DEUNA Technical Account Manager.

Requisites

To complete this process, you need the following information:

• Your Merchant ID (provided by DEUNA)
• Your SSH private key for authentication (explained below)
• The JSON file you want to upload

Upload a SFTP file#

Upload chargebacks to our SFTP servers.

1. Create the SSH Key

Generate your computer Key

1. Open Terminal App (Windows 10, Windows 11)

2. Run the command ssh-keygen -t rsa -b 4096

3. Enter a passkey (suggested 4 or 6-digit numeric Pin) when asked for passphrase and press Enter (Hint: it won’t show the keys that you are pressing)

4. Enter again your passkey and press Enter

5. You will see the key confirmation like the following image

Expand

6. Obtain your SSH Key by entering cat ~/.ssh/id_rsa.pub , you will receive a response with the key like the following example:

Expand

2. Register the SSH key to DEUNA

Register your computer key with DEUNA.

1. Copy you SSH Key
2. Share it with your DEUNA TPM: ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAACAQC8YDqXwxnvJkXOK5Dne0Fzcmt/f5MlD5WpcICgJxVtOYYGP1M+zn+Z2e3EHcssxblOPykFmBax/WBtVbcgtxUxMypTUMqsKtUtbg9D9DSMIKPbk7+BpQpG1dAx/SPmK7v/Zq0tUdw5np8z3KFnyH7q1Bw4NFd9jk48/CqOftEJn28lprJRus8/K8Jy+3S2vyTl2g8YuVHYvznl59aVKKCtm//D79OjPKKsdN3upCN6mo8FTCf0Ku+KS/F6kCIXn/gwKtRNuMwffJq+g7/qaMmo3FGBiaw9DCTbL5D+INgvAlbfpruqOa7GsmPreq7371+Om5BsQz2I79WvJtbPwrv+YrbOm2FVaaeKg4LKs8uqlcgs/DXaRBNtdQLQVGND37dvxVNc6ZsFagdQF+OKRxPc5MsIwDZH1Fd6m9qAN/Vxgfl8a5gg57ovkd2yJC40Blmn1nRAFxTdVceV+9c0a6qG7RTMyli9se8PzSS4Ckk/IL5TBzzNyimDYYtQWZ7INPNiFxRUKBTAeqwI+5Xava2hWHA35WmPh+5kl/J9gS3noALSBe/DT4ie9IXP68r7Ril2vPkvY8ONIc2usTsyIRmVCIss3Ww7ekMYwfpx/D8lroWoqC8Go6eI5lMCKYXkkzz0nsWwASTVG8jhbDWs7sebxzX5EmWup3Rf/0fokJfN9w== admin@DESKTOP-T7IE9FG

Once registered, the key will be stored in your computer and no further steps will be required regarding key generation and registration.

3. Connect to DEUNA SFTP server

1. Open the Terminal App

2. Sandbox Environment

   1. Enter the following command sftp -i ~/.ssh/id_rsa developer@transfer-sftp.chargebacks.sandbox.deuna.io

3. Production Environment

   1. Enter the following command sftp -i ~/.ssh/id_rsa developer@transfer-sftp.chargebacks.prod.deuna.io

4. You will receive the following response with the question Are you sure you want to continue connecting (yes/no/[fingerprint])?:

Expand

5. Press yes and enter
6. You will be asked the following: Enter passphrase for key 'C:\Users\Admin/.ssh/id_rsa’
7. Enter your passkey and press enter
8. You will receive the confirmation Connected to [transfer-sftp.chargebacks.sandbox.deuna.io](http://transfer-sftp.chargebacks.sandbox.deuna.io/)

Expand

4. Create a JSON file with the chargeback entries

1. The JSON file must have the following structure (example for two entries):

   JSONCopy

   {
   "version" : "1.0",
   "records" : [
           {
               "transaction_id": "a596f725-e22b-411f-ac51-c94b2386b39b", 
               "external_id" : "merchant_test_5",
               "chargeback_identifier":"chargeback_test_5",
               "chargeback_status": "open" ,
               "chargeback_reason_code": "0003", 
               "chargeback_case_id": "cbk_test_5", 
               "merchant_chargeback_id": "merchant_cbk_test_5",
               "chargeback_amount": 2000, 
               "detail": "En proceso judicial",
               "chargeback_date": "2025-10-30T11:20:00Z"
           },
           {
               "transaction_id": "d3daecd7-6f3a-4cb4-98a8-c077cfd5b9d9", 
               "external_id" : "merchant_test_6",
               "chargeback_identifier":"chargeback_test_6",
               "chargeback_status": "lost",
               "chargeback_reason_code": "4837", 
               "chargeback_case_id": "cbk_test_6", 
               "merchant_chargeback_id": "merchant_cbk_test_6",
               "chargeback_amount": 550, 
               "detail": "Goods/Services not received",
               "chargeback_date": "2025-10-30T11:21:00Z"
           }
       ]
   }

2. The body is composed by a field named version with the constant value 1.0, followed by an array named records.

3. Each object inside the records array, contains a chargeback entry, which must have the following structure:

4. Save the file with a TIMESTAMP as its name YYYYMMDD_HHMMSS.json. Example 20251104_193100.json
5. Store it in an easy-to-access folder, for example C:\Deuna_chargebacks\.

Expand

5. Test the SFTP connection

Send the file using the SFTP connection in the Sandbox environment

1. Navigate to Sandbox environment: cd /deuna-chargebacks-sbx

2. Enter the command to upload the file in the SFTP server directory for the selected environment: put {{route/to/file/in/pc-local}}/{{chargeback file name}} inbound/merchants/{{merchant_id}}

3. Example: put C:\Deuna_chargebacks\20251104_193100.json inbound/merchants/38696c00-9b00-4be9-84bc-60e7d7a7ba57

4. You will receive a message with the progress and results

Expand

5. In case you receive the message Couldn’t send packet: Broken pipe, you should reconnect to the SFTP with the command sftp -i ~/.ssh/id_rsa [developer@transfer-sftp.chargebacks.sandbox.deuna.io](mailto:developer@transfer-sftp.chargebacks.sandbox.deuna.io) and enter your passkey as the passphrase for key, and then retry to upload the file using starting from point 1
6. Disconnect with the command bye.

6. See the test results file

If needed, you can download a results file with the following steps:

1. Connect again to the SFTP server with the command sftp -i ~/.ssh/id_rsa developer@transfer-sftp.chargebacks.sandbox.deuna.io and enter your SSH key passphrase.
2. Navigate to the sandbox environment: cd /deuna-chargebacks-sbx
3. Navigate to the outbound merchant folder with cd /outbound/merchants/{{merchant_id}}.
4. Example cd /outbound/merchants/38696c00-9b00-4be9-84bc-60e7d7a7ba57
5. Enter get YYYYMMDD_HHMMSS_output.json, where YYYYMMDD_HHMMSS is the timestamp of the chargeback file uploaded previously.
6. The file will be downloaded to the folder where the chargeback file is located
7. Example get 20251104_193100_output.json
8. Complementary, you can add a specific location to download the file as well: get YYYYMMDD_HHMMSS_output.json /path/to/local/destination/

7. Send the file to Production

Send the file using the SFTP connection in Production environment

1. Enter the command to upload the file in the SFTP server directory for the selected environment put {{route/to/file/in/pc-local}}/{{chargeback file name}} inbound/merchants/{{merchant_id}}

2. Example: put C:\Deuna_chargebacks\20251104_193100.json inbound/merchants/38696c00-9b00-4be9-84bc-60e7d7a7ba57

3. You will receive a message with the progress and results

Expand

1. If you receive Couldn’t send packet: Broken pipe, reconnect with sftp -i ~/.ssh/id_rsa developer@transfer-sftp.chargebacks.prod.deuna.io, enter your SSH key passphrase, and retry the upload from step 1.

2. Disconnect with the command bye

8. See the production results file

If needed, you can download a results file:

1. Connect again to the SFTP server with the command sftp -i ~/.ssh/id_rsa developer@transfer-sftp.chargebacks.prod.deuna.io and enter your SSH key passphrase.
2. Navigate to the outbound merchant folder with cd /outbound/merchants/{{merchant_id}}.
3. Example cd /outbound/merchants/38696c00-9b00-4be9-84bc-60e7d7a7ba57
4. Enter get YYYYMMDD_HHMMSS_output.json, where YYYYMMDD_HHMMSS is the timestamp of the chargeback file uploaded previously.
5. The file will be downloaded to the folder where the chargeback file is located
6. Example get 20251104_193100_output.json
7. Complementary, you can add a specific location to download the file as well: get YYYYMMDD_HHMMSS_output.json /path/to/local/destination/

Troubleshooting#

Learn how to troubleshoot common issues.

Connection refused

If you have problems with connections, do as following:

• Verify your private key has the correct permissions: chmod 600 /path/to/private_key
• Ensure you're using the correct private key file
• Confirm your IP address is whitelisted (contact support if needed)

Permission denied

If you have permission problems, check the following:

• Verify you're using the correct Merchant ID
• Ensure your account has upload permissions for this directory
• Contact support if the issue persists

File already exists

If you get file errors, do as following

• Use a unique timestamp for each upload
• Check the directory with ls before uploading

Result file not found

If you have problems with file finding, do as following

• Allow sufficient time for processing (typical processing time: [specify your SLA])
• Verify you're checking the correct outbound directory for your Merchant ID
• Ensure the input filename matches exactly (timestamps must match)
• Contact support if the file doesn't appear within the expected timeframe

Cannot download result file

If you have problems with file downloads, do as following

• Verify you have read permissions on the outbound directory
• Check that you're using the exact filename including the _output.json suffix
• Ensure sufficient local disk space for the download

Support

If you encounter any issues or have questions:

• Email: support@deuna.io
• Include your Merchant ID and a description of the issue

Security best practices

Keep in mind the following security practices:

• Keep your private key secure and never share it
• Use strong file permissions on your private key (chmod 600)
• Only upload files during your scheduled processing windows
• Verify file contents before uploading to production