# Batch Upload For merchants who have their own billing schedule, DOKU have this feature to make batch payments according to the data the merchant uploads. It is a one time transaction to automatically charged your customer without scheduler. You can adjust when the deduction running from column "Execute Date" in template that you upload. There are two channels for DOKU Account Billing Batch Upload: Back Office or SFTP. This document are specific for merchants that connect with DOKU Account Billing by SFTP. Here is the overview of how to integrate with DOKU Account Billing Batch Upload SFTP: 1. First payment 2. Get Token List 3. Upload SFTP 4. Merchant notify DOKU (optional) 5. DOKU notify Merchant when report available 6. Download SFTP report file

## First Payment and Get Token List Create first payment with credit or debit card, direct debit, or e-wallet. Then get token from API get token list. Token is binding from customer payment credential & customer id. Customer id can be filled with billing number. Save token as data in file upload. Direct API availability for first payment: 1. [Credit Card](/accept-payments/direct-api/non-snap/cards.md) 2. [Direct Debit](/accept-payments/direct-api/snap/integration-guide/direct-debit/bri-direct-debit.md) (BRI) 3. [E-Wallet](/accept-payments/direct-api/snap/integration-guide/e-wallet/ovo.md) (OVO) API Token: 1. [Get Token List](/archive/non-snap/tokenization-v1.md) ## SFTP Flow

### Access DOKU will create user access for merchants to Read & Write in SFTP DOKU according the environment. Merchants will send their IP for DOKU Whitelist. ### Encrypt File Phase encryption 1. File encrypted with AES 256 using symmetric key 2. This symmetric key being encrypted using Public-Private Key 3. DOKU generate Public-Private Key. (this need to be changed annually / bi-annually) 4. DOKU share the Public Key to Merchant and store the Private Key

Procedure: 1. Merchants generate random Symmetric Key using SALT. 2. Merchants encrypt file data with AES 256 using the generated Symmetric Key. 3. Merchants encrypt the generate Symmetric Key using Public Key given by DOKU type RSA No Padding. 4. Merchants append Encrypted Symmetric Key into the Encrypted File. 5. Merchants append length Symmetric Key 4 String at front ( 128 ). ### Folder After connected to DOKU SFTP, merchants got folders with different function according to the folder name.

* download ( Batch Upload Transaction ) Folder for merchants to upload file to be executed on Batch Upload. The file 'ExampleBatch.txt' contains sample data that the merchant needs to provide for DOKU to retrieve and process. * upload ( Report Batch Upload Transaction ) Folder for merchants to get report of Batch Upload Transaction. ### SFTP File #### Batch File Before put file in SFTP, first we need to setup the file it self. You will need to create it in TXT Format. Please be sure to include the prefix "TKN" in the file name. Example file name: TKN\_202510ABC.TXT

Parameter	Type	Requirement	Description
BILLING REF / BILLING NUMBER	Alphanumeric(128)	MANDATORY	Merchant Unique ID
DESCRIPTION	Alphanumeric(256)	OPTIONAL	Billing Description
INVOICE NUMBER	Alphanumeric(64)	MANDATORY	Invoice Number
CURRENCY	Alpha(3)	MANDATORY	Only IDR Currency
AMOUNT	Numbers(10,2)	MANDATORY	Example: no decimal 10000 decimal 10000.00
TOKEN	Numbers(32)	MANDATORY	Credit / Debit / Direct Debit / E-Money Token
CARD HOLDER NAME	Alphanumeric(128)	OPTIONAL	Customer name
CARD HOLDER EMAIL	Alphanumeric(128)	OPTIONAL	Customer email
CARD HOLDER PHONE	Numbers(32)	OPTIONAL	Customer phone number
CARD HOLDER CITY	Alphanumeric(128)	OPTIONAL	Customer city location
CARD HOLDER REGION	Alphanumeric(128)	OPTIONAL	Customer region location
CARD HOLDER COUNTRY	Alpha(2)	OPTIONAL	Example: ID
CARD HOLDER ADDRESS	Alphanumeric(128)	OPTIONAL	Customer address
CARD HOLDER POSTAL CODE	Alphanumeric(16)	OPTIONAL	Customer postal code
CARD HOLDER BIRTHDATE	Numbers(8)	OPTIONAL	Customer birth date
EXECUTE DATE	Numbers(32)	OPTIONAL	Date transaction want to execute (YYYYMMDD)

#### Batch Report File After transaction finish DOKU will generate report in TXT format, like Picture below. Merchant can get the data in the folder “upload”.

Value	Parameter	Type
48907854	TOTAL AMOUNT	Numbers(12)
200	TOTAL TRANSACTION	Numbers(11)
200	TOTAL SUCCESS	Numbers(11)
0	TOTAL FAILED	Numbers(11)
411111******7548	CARD NUMBER	NS(16)
DOKU1234567	INVOICE NUMBER	Alphanumeric(64)
200000	AMOUNT	Numbers(12,2)
IDR	CURRENCY	Alpha(3)
00	RESPONSE CODE	Alphanumeric(2)
SUCCESS	RESPONSE MESSAGE	Alphanumeric(256)
890123	APPROVAL CODE	Alphanumeric(16)
20170123121030	PAYMENT DATE TIME	Numbers(14)
100	BANK CODE	Numbers(3)

BANK CODE\ \- 100 : BNI\ \- 350 : BANK MANDIRI\ \- 400 : BCA\ \- 150 : BANK CIMB\ \- 151 : BRI PAYMENT DATE TIME\ Sample : 20170123121030\ \- 2017 : YEAR\ \- 01 : MONTH\ \- 23 : DATE\ \- 12 : HOURS\ \- 10 : MINUTES\ \- 30 : SECONDS ## API Merchant notify to DOKU After merchants put file data in SFTP, merchants will trigger DOKU to get data file in SFTP with this API. This request is optional. #### Request | Type | Value | | ----------------------------- | ----------------------------------------------------- | | **HTTP Method** | POST | | **API endpoint (Sandbox)** | `https://api-sandbox.doku.com/batch-upload/v1/notify` | | **API endpoint (Production)** | `https://api.doku.com/batch-upload/v1/notify` | Here is the sample of request header to notify DOKU: ``` Client-Id: MCH-0001-10791114622547 Request-Id: b266c265-3d61-4708-9860-c0d5b9a98f8c Request-Timestamp: 2020-08-11T08:45:42Z Signature: HMACSHA256=9UPUFzOqJc47aJzD9ESOTcWg6TMsg3mqSP+DnUO8ENE= ```

Parameter	Description
`client-id`	Client ID retrieved from DOKU Back Office
`request-id`	Unique random string (max 128 characters) generated from merchant side to protect duplicate request
`request-timestamp`	Timestamp request on UTC time in ISO8601 UTC+0 format. It means to proceed transaction on UTC+7 (WIB), merchant need to subtract time with 7. Ex: to proceed transaction on September 22th 2020 at 08:51:00 WIB, the timestamp should be 2020-09-22T01:51:00Z
`signature`	Security parameter that needs to be generated on merchant Backend and placed to the header request to ensure that the request is coming from valid merchant. Please refer to this section to generate the signature

Here is the sample of request body to notify DOKU: ```json { "file_name":"example.txt" } ```

Parameter	Data Type	Requirement	Description
file_name	String (128)	Mandatory	File name merchant put in DOKU sftp download folder

#### Response After hitting the above API request, DOKU will give the response. | Type | Value | | --------------- | ---------- | | **HTTP Status** | 201 | | **Result** | IN PROCESS | {% tabs %} {% tab title="In Process" %} HTTP Status `201 Created` ```json { "name":"example.txt" "status":IN_PROCESS } ``` {% endtab %} {% tab title="Signature not valid " %} HTTP Status `400 Bad Request` ```json {"error":{ "code": "invalid_signature", "message": "invalid header signature", "type": "Invalid Signature" } } ``` {% endtab %} {% tab title="Invalid Parameter" %} HTTP Status `400 Bad Request` ```json {"error":{ "code": "invalid_parameter", "message": "file_name must not be empty", "type": "Not input object file_name" } } ``` {% endtab %} {% tab title="Idempotent" %} HTTP Status Code `400 Bad Request` ```json {"error":{ "code": "idempotent_request", "message": "idempotent request", "type": "Duplicate file name" } } ``` {% endtab %} {% endtabs %} | Parameter | Data Type | Requirement | Description | | ------------- | ------------ | ----------- | -------------------- | | name | String (128) | Mandatory | File name | | status | String (128) | Mandatory | IN\_PROCESS response | | error.code | | | | | error.message | | | | | error.type | | | | ## API DOKU notify to Merchant After DOKU create report in SFTP, DOKU will notify merchant to get report. Guide how to handle payment notification can refer to [this section](/get-started-with-doku-api/notification.md). #### Request | Type | Value | | --------------- | ----- | | **HTTP Method** | POST | Here is the sample of request header DOKU send to merchant: ``` Client-Id: MCH-0001-10791114622547 Request-Id: b266c265-3d61-4708-9860-c0d5b9a98f8c Request-Timestamp: 2020-08-11T08:45:42Z Signature: HMACSHA256=9UPUFzOqJc47aJzD9ESOTcWg6TMsg3mqSP+DnUO8ENE= ``` Here is the sample of request body DOKU send to merchant: ```json { "service":{ "id":"BATCH_UPLOAD" }, "batch_file":{ "name":"example.txt", "status":"DONE", "date":"2021-07-29T13:52:53Z" } } ``` | Parameter | Data Type | Requeirement | Description | | ------------------ | --------- | ------------ | ----------------------------- | | service.id | | Mandatory | Batch Upload Service | | batch\_file.name | | Mandatory | Batch file Upload name | | batch\_file.status | | Mandatory | Status of processed file Done | | batch\_file.date | | Mandatory | Date file finish processed | ## Batch Upload Executable Script for Merchant ### Encrypt Process #### Encrypt Command Example: java -jar target/tkn-utility.jar encrypt /users/jonathan/doku/project/jar-java/data/TEST\_FILE\_1.txt /users/jonathan/doku/project/jar-java/data/TEST\_FILE\_1.enc.txt /users/jonathan/doku/project/jar-java/key/PUBLICKEY\_120078\_20210115111404.key 012345678901234567890 #### Encrypt Command Explanation: \ encrypt \ \ \ \ Salt = Harus 21 karakter bebas ### Decrypt Process #### Decrypt Command Example java -jar target/tkn-utility.jar decrypt /users/jonathan/doku/project/jar-java/data/TEST\_FILE\_1.enc.txt /users/jonathan/doku/project/jar-java/data/TEST\_FILE\_1.dec.txt /users/jonathan/doku/project/jar-java/key/PRIVATEKEY\_120078\_20210115111404.key #### Decrypt Command Explanation: \ decrypt \ \ \ --- # Agent Instructions: 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: ``` GET https://developers.doku.com/flexibill/account-billing/batch-upload.md?ask= ``` The question should be specific, self-contained, and written in natural language. 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.