Connectivity & File Security (SFTP)
Availability: 🇮🇩 Indonesian Business Account only
This page covers all technical requirements for connecting to the DOKU SFTP server, encrypting batch billing files, and understanding the folder structure, file format, and report output for Merchant Hosted Scheduler batch operations.
Features & Benefits
🔐 Two-Layer File Encryption
Batch files are protected with a two-layer encryption scheme — AES-256 for file content and RSA for key protection — ensuring that sensitive billing data is never exposed in transit or at rest on the SFTP server.
📁 Dedicated Inbound and Outbound Directories
DOKU provides separate folders on the SFTP server for uploading billing files and downloading result reports, with a clear naming convention that separates inbound from outbound operations.
📊 Structured Result Reports
After processing each batch, DOKU generates a .TXT report with a summary header and per-transaction detail rows — including response codes, approval codes, masked card numbers, and bank codes — for complete reconciliation.
🔔 Processing Completion Notification
DOKU notifies your merchant endpoint when the result report is ready, so your system does not need to poll the SFTP server.
SFTP Connection
SFTP credentials are provisioned per merchant account and per environment (Sandbox / Production). Contact your DOKU Account Manager to obtain credentials.
Provide the following to DOKU when requesting access:
Your server's IP address(es) for whitelisting — SFTP access is restricted to pre-approved IPs only
Your preferred authentication method: SSH key pair (recommended) or password
Connection parameters provided by DOKU:
Host
DOKU SFTP server hostname
Port
SFTP port
Username
Your merchant SFTP username
Authentication
SSH private key or password, as configured during setup
Recommended SFTP clients:
Command-line
sftp, scp
GUI
FileZilla, WinSCP, Cyberduck
Programmatic
paramiko (Python), JSch (Java), ssh2 (Node.js), or any standard SFTP library
SFTP credentials are environment-specific. Sandbox and Production credentials are different — never use Production credentials in a test environment. Contact your DOKU Account Manager immediately if credentials are compromised.
Folder Structure
After connecting to the DOKU SFTP server, you will find two folders:
/download
Merchant uploads here
Upload your encrypted batch billing files to this folder for DOKU to pick up and process
/upload
Merchant downloads from here
DOKU places result reports here after processing. Also where failed files land in the /upload/failed subfolder
The folder names are from DOKU's perspective, not the merchant's. DOKU downloads files from /download (i.e., picks up your uploads). DOKU uploads result reports to /upload (i.e., places them for you to retrieve). Think of it as: you write to /download, you read from /upload.
Subfolder for failures:
/upload/failed
Files that could not be processed — decryption failures, invalid filenames, or files where EXECUTE DATE is in the past. DOKU also sends a notification to your endpoint when a file lands here.
File Encryption
All batch billing files must be encrypted before upload. DOKU uses a two-layer encryption scheme:
Layer 1 (Content): File data encrypted with AES-256 using a symmetric key
Layer 2 (Key Protection): The symmetric key itself encrypted with DOKU's RSA public key
This ensures that even if the encrypted file is intercepted, the content cannot be decrypted without DOKU's RSA private key.
Encryption Process — Step by Step
Key requirements:
SALT
Exactly 21 characters — any alphanumeric combination. This is a hard requirement — a SALT of any other length will cause encryption failure
AES mode
AES-256
RSA padding
No Padding
DOKU Public Key
Provided by DOKU during setup. Must be renewed annually or bi-annually — contact your Account Manager before expiry
Key length prefix
128 (4 characters) prepended to the final file
If you upload a file encrypted with an expired DOKU public key, DOKU cannot decrypt it. The file will be placed in /upload/failed and a failure notification will be sent to your endpoint. Re-encrypt with the current public key and re-upload with a new filename.
DOKU Encryption Utility (Java)
DOKU provides a Java JAR utility (tkn-utility.jar) for encrypting and decrypting files. The same algorithm can also be implemented in any language that supports AES-256 and RSA — you are not required to use the Java utility.
Encrypt:
Example:
Decrypt (for verifying report files or testing):
Example:
The encrypt/decrypt utility is provided for convenience. The underlying encryption is standard AES-256 + RSA — you can implement it in any language. Use the JAR utility to validate your implementation in testing before building a programmatic integration.
Batch File Format
Batch files submitted to /download must follow this format:
File requirements:
Format
Plain text (.TXT)
Filename prefix
Must begin with TKN_ — e.g., TKN_202510ABC.TXT
Encoding
UTF-8
Encryption
AES-256 + RSA as described above — plaintext files will not be processed
For the full column definition of the batch file content → Merchant Hosted Scheduler — Column Definition
Report File Format
After DOKU processes a batch file, a result report in .TXT format is placed in the SFTP /upload folder. The report has two sections: a summary block at the top and per-transaction rows below.
Summary Block
The first rows of the report contain batch-level totals:
TOTAL AMOUNT
Number(12)
Sum of all successfully charged amounts in this batch
TOTAL TRANSACTION
Number(11)
Total number of records in the batch
TOTAL SUCCESS
Number(11)
Number of records charged successfully
TOTAL FAILED
Number(11)
Number of records that failed
Per-Transaction Rows
Each subsequent row represents one record from the batch file:
CARD NUMBER
NS(16)
Masked card number — e.g., 411111******7548
INVOICE NUMBER
Alphanumeric(64)
Invoice number as submitted in the batch file
AMOUNT
Number(12,2)
Amount charged for this record
CURRENCY
Alpha(3)
Currency code — e.g., IDR
RESPONSE CODE
Alphanumeric(2)
Result of the charge attempt. 00 = success. Other codes indicate failure — see below
RESPONSE MESSAGE
Alphanumeric(256)
Human-readable result description — e.g., SUCCESS, INSUFFICIENT FUNDS, INVALID TOKEN
APPROVAL CODE
Alphanumeric(16)
Bank approval code for successful charges. Empty for failed records
PAYMENT DATE TIME
Number(14)
Timestamp of the charge attempt in yyyyMMddHHmmss format — e.g., 20251005121030 = 5 Oct 2025 12:10:30
BANK CODE
Number(3)
Issuing bank identifier. See Bank Code lookup below
Bank Code Lookup
100
BNI
150
Bank CIMB
151
BRI
350
Bank Mandiri
400
BCA
PAYMENT DATE TIME Format
yyyyMMddHHmmss — parsed as follows:
RESPONSE CODE 00
00RESPONSE CODE: 00 means the charge was processed successfully. Any other code indicates a failure. The full list of response codes and their meanings is available from your DOKU Account Manager.
👉 Learn more of Bank and DOKU response code
Failure Scenarios
Window 1 — Before Payment Execution (File-Level Failures)
These failures occur before any charge is attempted. The entire file fails — no records are processed.
Decryption failure
Wrong or expired DOKU public key used for encryption; incorrect SALT length; encrypted symmetric key not appended correctly
File placed in /upload/failed; DOKU sends failure notification to merchant endpoint
Re-encrypt using the correct current DOKU public key with a 21-character SALT; re-upload with a new filename
Invalid filename
Missing TKN_ prefix or wrong file extension
File not recognized; no processing occurs
Rename file with TKN_ prefix and .TXT extension; re-upload
Past EXECUTE DATE
All records in the file have an EXECUTE DATE that has already passed
File placed in /upload/failed with INVALID EXECUTE DATE; DOKU sends failure notification
Correct EXECUTE DATE to today or a future date; re-encrypt and re-upload with a new filename
When re-uploading after a file-level failure, always use a new filename. The failed filename cannot be reused — submitting the same filename to the Trigger API will return a duplicate error.
Window 2 — After Payment Execution (Record-Level Failures)
These failures occur during charge execution. Valid records are charged; failed records are flagged in the result report. Other records in the same file are not affected.
Insufficient funds
FAILED + bank decline code
✅ Yes
Retry the customer in the next billing cycle with the same token
Expired card / invalid token
FAILED + token-related response code
❌ No
Initiate new First Payment with customer to obtain a new token; use new token in next cycle
Card blocked or stolen
FAILED + restriction response code
❌ No
Contact customer for a new payment method; initiate new First Payment once resolved
Already paid this month
ALREADY_PAID
✅ Yes
Send One Bill/Month is active and customer was already charged this month — no action needed
Terms & Conditions
SFTP access requires IP whitelisting — provide all server IPs to DOKU during setup. If your IP changes, re-whitelist before the change takes effect
Batch files must be encrypted using the current DOKU RSA public key — DOKU public keys must be renewed annually or bi-annually
SALT must be exactly 21 characters — any other length will cause encryption failure
Batch files must use the
TKN_filename prefix and.TXTextensionRaw card numbers, CVVs, and full PAN data must never appear in batch files — use DOKU-issued tokens only
Outbound report files in
/uploaddo not need to be encrypted — they are provided as plaintext.TXT
FAQ
What is the SALT and what are the requirements?
The SALT is a random string used during the AES-256 symmetric key generation step of the encryption process. It must be exactly 21 characters — alphanumeric, any combination. Using a SALT of any other length will cause encryption failure and the file will land in /upload/failed. The SALT does not need to be stored permanently — it is consumed during encryption and is not needed for decryption.
Where do I get DOKU's RSA public key and when does it expire?
DOKU provides the RSA public key during the Account Billing SFTP setup process. The key must be renewed annually or bi-annually — your DOKU Account Manager will notify you ahead of expiry. If you upload a file encrypted with an expired key, DOKU cannot decrypt it and the file will be placed in /upload/failed. Do not wait for expiry to request a renewal — rotate proactively as part of your annual security review.
Can I implement the encryption in a language other than Java?
Yes. The encryption algorithm is standard AES-256 + RSA No Padding — any language with support for these algorithms can implement it. The DOKU Java utility (tkn-utility.jar) is provided for convenience and testing, not as a requirement. Validate your implementation in Sandbox against the Java utility before deploying to Production.
Why is the upload folder called /download and vice versa?
The folder names are from DOKU's perspective. DOKU downloads (reads) files from /download — so that is where you upload your billing files. DOKU uploads (writes) result reports to /upload — so that is where you download your reports. As a merchant: write to /download, read from /upload.
What should I do if my server IP changes?
Contact your DOKU Account Manager to whitelist the new IP before the change takes effect. SFTP connections from non-whitelisted IPs are refused. If you have a dynamic IP, request that DOKU whitelist a static IP range or use a fixed NAT gateway for outbound SFTP connections.
What does RESPONSE CODE 00 mean in the result report?
RESPONSE CODE: 00 indicates a successful charge. Any other code indicates a failure. The RESPONSE MESSAGE column provides a human-readable description of the failure reason. Contact your DOKU Account Manager for the full response code reference applicable to your payment channels.
How do I parse PAYMENT DATE TIME in the report?
PAYMENT DATE TIME uses the format yyyyMMddHHmmss — a 14-digit string with no separators. For example, 20251005121030 = 5 October 2025 at 12:10:30 WIB. Parse by position: characters 1–4 = year, 5–6 = month, 7–8 = day, 9–10 = hour, 11–12 = minute, 13–14 = second.
Last updated
Was this helpful?