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

Account Billing Batch Upload

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
2. Direct Debit (BRI)
3. E-Wallet (OVO)

API Token:

1. Get Token List

SFTP Flow

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

Encryption Process

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.

Folder Structure

• 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

File Content Example

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”.

Report File Example

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:

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

In Process

HTTP Status 201 Created

{
    "name":"example.txt"
    "status":IN_PROCESS  
}

Signature not valid

HTTP Status 400 Bad Request

{"error":{
    "code": "invalid_signature",
    "message": "invalid header signature",
    "type": "Invalid Signature"
    }
}

Invalid Parameter

HTTP Status 400 Bad Request

{"error":{
    "code": "invalid_parameter",
    "message": "file_name must not be empty",
    "type": "Not input object file_name"
    }
} 

Idempotent

HTTP Status Code 400 Bad Request

{"error":{
    "code": "idempotent_request",
    "message": "idempotent request",
    "type": "Duplicate file name"
    }
}

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.

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:

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

<jar file> encrypt <input file> <output file> <public key> <salt>

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:

<jar file> decrypt <input file> <output file> <private key>