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.
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
File encrypted with AES 256 using symmetric key
This symmetric key is encrypted using Public-Private Key
DOKU generates Public-Private Key.
DOKU share the Public Key to Merchant and store the Private Key
Procedure
Merchants generate random Symmetric Key using SALT.
Merchants encrypt data with AES 256 using the generated Symmetric Key.
Merchants encrypt the generate Symmetric Key using Public Key given by DOKU type RSA No Padding.
Merchants append Encrypted Symmetric Key into the Encrypted File.
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 :
File Explanation
Field Name | Length | Type | Position | Description |
---|---|---|---|---|
| 1 | AN | 1 | Value 'D' |
| 15 | AN | 2-16 | Valid merchant ID or Payment Facilitator ID |
| 10 | AN | 17-26 | Tracking number for merchant |
| 19 | N | 27-45 | Old PAN Number |
| 4 | N | 46-49 | YYMM Format |
| 20 | AN | 50-69 | Tracking number for merchant |
| 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”.
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
Request Header Explanation
Parameter | Description |
---|---|
| Client ID retrieved from DOKU Back Office |
| Unique random string (max 128 characters) generated from merchant side to protect duplicate request |
| 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 |
| 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) |
|
API endpoint (Production) |
|
Request Body
Parameter | Data Type | Type | Description |
---|---|---|---|
file_name | String(128) | Mandatory | File name merchant put in DOKU sftp download folder |
Example Request:
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
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 :
Last updated