Backend Integration

---

Setup

You can start by downloading your private and public keys to encrypt file and you also have to setup a notification URL so that DOKU can send a notification that the file being processed is completed.

Merchant Configuration Page

Integration Steps

• Upload File card registration via ABU SFTP Folder

• Hit API Notification to DOKU

• Consume Notification from DOKU

• Download result file from DOKU Result Folder

Access

DOKU will create user access for merchants to Read & Write in SFTP DOKU according to the environment. Merchants will send their IP for DOKU Whitelist.

Encrypt Procedure

1. File encrypted with AES 256 using symmetric key

2. This symmetric key is encrypted using Public-Private Key

3. DOKU generates Public-Private Key.

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

SFTP File

In this document will explain in details how to create file for transaction using SFTP. File Upload

Before put file in SFTP, first we need to setup the file itself. You will need to create it in TXT Format.

Example .TXT File :

D000001999128616DOKU0001  5XXXXNNNNNNNNNNN   YYMMAAAAA00001
D000001999128616DOKU0002  5XXXXNNNNNNNNNNN   YYMMAAAAA00002

File Explanation

Field Name	Length	Type	Position	Description
detail-identifier	1	AN	1	Value 'D'
merchant-id	15	AN	2-16	Valid merchant ID or Payment Facilitator ID
merchant-request-identifier-1	10	AN	17-26	Tracking number for merchant
PAN number	19	N	27-45	Old PAN Number
Expiry Date	4	N	46-49	YYMM Format
merchant-request-identifier-2	20	AN	50-69	Tracking number for merchant
filler	20	AN	70-89	Blank spaces

File Report

After transaction finish DOKU will generate report in TXT format, like Example below. Merchant can get the data in to folder “upload”.

D000000000000002AAAA0001  5185515000000334   5185515000000334   22122212VALID AAAAA00001          V                   
D000000000000002AAAA0002  5185693000000115   5185693000000115   22122212VALID AAAAA00002          V                   
D000000000000002AAAA0003  4005550010538560   5410221000000112   11052212UPDATEAAAAA00003                              

Field Name	Length	Type	Position	Description
detail-identifier	1	AN	1	Value 'D'
merchant-id	15	AN	2-16	Valid merchant ID or Payment Facilitator ID
merchant-request-identifier-1	10	AN	17-26	Tracking number for merchant
Old PAN Number	19	AN	27-45	Old PAN Number
New PAN Number	19	AN	46-64	New PAN Number
Old Expiry Date	4	N	65-68	YYMM Format
New Expiry Date	4	AN	69-72	YYMM Format
Reason Identifier	6	AN	73-78	Contains one of the following values for account requests that had a match: • UPDATE—Match made; update data provided (includes issuer Reason Codes R, B, and P) • CONTAC—Match made; account closed (includes Issuer Reason Code C) • EXPIRY—Match made; expiration date changed (includes Issuer Reason Code E) • VALID—No updates were found but the account is valid. • UNKNWN—The account number could not be found in the ABU database. (See the Response Indicator for further explanation.)
merchant-request-identifier-2	20	AN	79-98	Tracking number for merchant
response indicator	1	A	99	ABU Validation Response Indicator (displayed only when the Reason Identifier is VALID or UNKNWN) • V—matches the account as reported by the issuer • P—No match, participating BIN/ issuer • N—No match, non-participating BIN/issuer
filler	19	AN	100-118	Blank Spaces

Merchant Notification

Notification API

Request

Here is the sample of request header to notify DOKU

Client-Id: MCH-0001-10791114622547
Request-Id: fdb69f47-96da-499d-acec-7cdc318ab2fe
Request-Timestamp: 2020-08-11T08:45:42Z
Signature: HMACSHA256=1jap2tpgvWt83tG4J7IhEwUrwmMt71OaIk0oL0e6sPM=

Request Header Explanation

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

Merchant Notify to DOKU

After merchants put file data in SFTP, merchants will trigger DOKU to get data file in SFTP with this API.

Format: REST API (JSON)

Type	Value
HTTP Method	POST
API endpoint (Sandbox)	https://api-sandbox.doku.com/abu/notify
API endpoint (Production)	https://api.doku.com/abu/notify

Request Body

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

Example Request:

{
  "file_name": "example.txt"
}

Response Body

name	String (128)	Mandatory	File name
status	String (128)	Mandatory	IN_PROCESS response
error.code	String (128)	Optional	Response Code
error.message	String (128)	Optional	Response Message
error.type	String (128)	Optional	Error Type

Example Response Success:

Http status code: 201

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

List of error message

invalid header signature	invalid_signature	400	Invalid Signature
idempotent request	idempotent_request	400	Double request with same request id under 20 second
file_name must not be empty	invalid_parameter	400	Not input object file_name
File not found in SFTP	not_found	404	File not found in DOKU sftp download folder

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: https://jokul.doku.com/docs/docs/http-notification/overview

Request

Format: REST API (JSON)

service.id	string	Mandatory	Batch Upload Service
batch_file.name	string	Mandatory	Batch file Upload name
batch_file.status	string	Mandatory	Status of processed file Done
batch_file.date	timestamp	Mandatory	Date file finish processed

Example :

{
  "service": {
    "id": "ABU"
  },
  "abu_file": {
    "name": "example.txt",
    "status": "DONE",
    "message": "SUCCESS",
    "date": "2021-07-29T13:52:53Z"
  }
}