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

<figure><img src="https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2FvCIDBrTQOE1Sah6lllZY%2Fabu.png?alt=media&#x26;token=dc55ed68-d834-422c-b58d-fa20f06d6ac0" alt=""><figcaption></figcaption></figure>

Integration Steps

* Upload File card registration via ABU SFTP  Folder
* Hit API Notification to DOKU
* Consume Notification from DOKU
* Download the result file from DOKU Result Folder

<figure><img src="https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2Fw9EdQYiH3u9yiwsBdMeJ%2FABU%20Sequence%20Diagram.JPG?alt=media&#x26;token=34e6bbc0-fad8-4ca8-84cc-1c0393826c68" alt=""><figcaption><p>DOKU Automatic Billing Updater Flow Diagram</p></figcaption></figure>

### Access&#x20;

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.

<figure><img src="https://lh7-us.googleusercontent.com/docsz/AD_4nXdRahv71H_zDjQLjw_NIjHHLFBO-PysGsEpIbsOyl76UvVy07MAW_jSQFoNN9cKnUG18ldjRDT8LWv90Hv-cTtXXQwXOZQ-Wc4xAFBFSCBKQ9dyMQ_gdjwD6AjFC-VfLFQ-QhuluAvliVzBogeWDdo5HJkzX4fKJgghQMv7Vg?key=vg0lJoiTVHqzGlT4QARvVQ" alt=""><figcaption></figcaption></figure>

### Encryption Procedure

Encryption Procedure

1. Merchants generate random String with length 32 digit Alfa Numeric as SALT.
2. Merchants encrypt plain card data using AES 256 Key Size, Chiper ECB, pkcs5 padding with SALT to Base64 encoded format. <https://www.devglan.com/online-tools/aes-encryption-decryption>
3. Merchants encrypt the SALT using a DOKU RSA Public Key 2048 bit - No Padding to Base64 encoded format. <https://www.devglan.com/online-tools/rsa-encryption-decryption>
4. Merchants put the data on file (txt format) with content format : {Length\_Of\_Encrypted\_SALT}+{Encrypted\_SALT}+{Encrypted\_Plain\_Card\_Data}
   * {Length\_Of\_Encrypted\_SALT} : add padding left with "0", so there will be 4 digits (ex : 0344).
   * {Encrypted\_SALT} : in Base64 format.
   * {Encrypted\_Plain\_Card\_Data} : in Base64 format.
5. The txt file data ready to put on DOKU SFTP ./download/ folder

### Decryption Procedure

1. Get the length of the Encrypted SALT:
   * Extract the first 4 digits from the data. These 4 digits represent the length of the encrypted SALT.
   * Cast this value into an integer, which will tell you how long the encrypted SALT is.
2. Extract the Encrypted SALT:
   * Use the length obtained in Step 1.
   * Extract a substring from the data starting at index 4. This substring runs from index 4 to (index 4 + the length of the encrypted SALT)&#x20;
3. Decrypt the Encrypted SALT:
   * Use Merchant RSA Private Key 2048 bit - No Padding decryption to decrypt the extracted Encrypted SALT value.
4. Extract the Encrypted Data:
   * Now, get the remaining part of the card data, starting from index (4 + length of the Encrypted SALT) to the end of the data. This is the encrypted card data.
5. Decrypt the Encrypted Data:
   * Use AES 256 with SALT obtained from step 3 to decrypt the encrypted card data.

### Folder

<figure><img src="https://lh7-us.googleusercontent.com/docsz/AD_4nXchFZshMBN2eaiW5SX0XNO8DW7_OcBuebSzo-akHB06hyf1qrWtthSgA6lfbB3h-T06Zp5UVFCese0wrs39ex5ONOC4KYJ3D-4SypL2b6AtTBBGip4bFFiNX6KNeLfwBgSwLIR9ExmYe-pGp9jNSIAIS-fQAXUSlWgNFNKGGQ?key=vg0lJoiTVHqzGlT4QARvVQ" alt=""><figcaption></figcaption></figure>

### SFTP File

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

Before putting the file in SFTP, we first need to set up the file itself. You will need to create it in TXT Format.

**Example .TXT File :**

```json
D000001999128616DOKU0001  5XXXXNNNNNNNNNNN   YYMMAAAAA00001
D000001999128616DOKU0002  5XXXXNNNNNNNNNNN   YYMMAAAAA00002
```

### File Explanation <a href="#id-1-obtain-paymenturl-on-backend" id="id-1-obtain-paymenturl-on-backend"></a>

<table><thead><tr><th width="167">Field Name</th><th>Length</th><th width="40">Type</th><th>Position</th><th>Description</th></tr></thead><tbody><tr><td><strong><code>detail-identifier</code></strong></td><td>1</td><td>AN</td><td>1</td><td>Value 'D'</td></tr><tr><td><strong><code>merchant-id</code></strong></td><td>15</td><td>AN</td><td>2-16</td><td>Valid merchant ID or Payment Facilitator ID</td></tr><tr><td><strong><code>merchant-request-identifier-1</code></strong></td><td>10</td><td>AN</td><td>17-26</td><td>Tracking number for merchant, <strong>must be unique per batch file</strong></td></tr><tr><td><strong><code>PAN number</code></strong></td><td>19</td><td>N</td><td>27-45</td><td>Old PAN Number</td></tr><tr><td><strong><code>Expiry Date</code></strong></td><td>4</td><td>N</td><td>46-49</td><td>YYMM Format</td></tr><tr><td><strong><code>merchant-request-identifier-2</code></strong></td><td>20</td><td>AN</td><td>50-69</td><td>Tracking number for merchant</td></tr><tr><td><strong><code>filler</code></strong></td><td>20</td><td>AN</td><td>70-89</td><td>Blank spaces</td></tr></tbody></table>

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

<table><thead><tr><th width="167">Field Name</th><th>Length</th><th width="68">Type</th><th>Position</th><th>Description</th></tr></thead><tbody><tr><td><strong>detail-identifier</strong></td><td>1</td><td>AN</td><td>1</td><td>Value 'D'</td></tr><tr><td><strong>merchant-id</strong></td><td>15</td><td>AN</td><td>2-16</td><td>Valid merchant ID or Payment Facilitator ID</td></tr><tr><td><strong>merchant-request-identifier-1</strong></td><td>10</td><td>AN</td><td>17-26</td><td>Tracking number for merchant</td></tr><tr><td><strong>Old PAN Number</strong></td><td>19</td><td>AN</td><td>27-45</td><td>Old PAN Number</td></tr><tr><td><strong>New PAN Number</strong></td><td>19</td><td>AN</td><td>46-64</td><td>New PAN Number</td></tr><tr><td><strong>Old Expiry Date</strong></td><td>4</td><td>N</td><td>65-68</td><td>YYMM Format</td></tr><tr><td><strong>New Expiry Date</strong></td><td>4</td><td>AN</td><td>69-72</td><td>YYMM Format</td></tr><tr><td><strong>Reason Identifier</strong></td><td>6</td><td>AN</td><td>73-78</td><td>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.) </td></tr><tr><td><strong>merchant-request-identifier-2</strong></td><td>20</td><td>AN</td><td>79-98</td><td>Tracking number for merchant</td></tr><tr><td><strong>response indicator</strong></td><td>1</td><td>A</td><td>99</td><td>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</td></tr><tr><td><strong>filler</strong></td><td>19</td><td>AN</td><td>100-118</td><td>Blank Spaces</td></tr></tbody></table>

## Merchant Notification

### Notification API

### Request&#x20;

Here is the sample of request header to notify DOKU

```json
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 <a href="#id-1-obtain-paymenturl-on-backend" id="id-1-obtain-paymenturl-on-backend"></a>

<table><thead><tr><th width="167">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><strong><code>client-id</code></strong></td><td>Client ID retrieved from DOKU Back Office</td></tr><tr><td><strong><code>request-id</code></strong></td><td>Unique random string (max 128 characters) generated from merchant side to protect duplicate request</td></tr><tr><td><strong><code>request-timestamp</code></strong></td><td>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</td></tr><tr><td><strong><code>signature</code></strong></td><td>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 <a href="https://dashboard.doku.com/docs/docs/technical-references/generate-signature">this section</a> to generate the signature</td></tr></tbody></table>

### Merchant Notify to DOKU

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

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

```json
{
  "file_name": "example.txt"
}
```

#### Response Body

| name          | String (128)            | Mandatory           | File name                   |
| ------------- | ----------------------- | ------------------- | --------------------------- |
| status        | String (128)            | Mandatory           | IN\_PROCESS response        |
| error.code    | <p>String (128)<br></p> | <p><br>Optional</p> | <p><br>Response Code</p>    |
| error.message | <p>String (128)<br></p> | <p>Optional<br></p> | <p>Response Message<br></p> |
| error.type    | <p>String (128)<br></p> | <p>Optional<br></p> | <p><br>Error Type</p>       |

**Example Response  Success:**

Http status code: 201

```json
{
  "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         | <p><br>string</p>    | Mandatory | Batch Upload Service          |
| ------------------ | -------------------- | --------- | ----------------------------- |
| batch\_file.name   | <p>string<br></p>    | Mandatory | Batch file Upload name        |
| batch\_file.status | <p><br>string</p>    | Mandatory | Status of processed file Done |
| batch\_file.date   | <p><br>timestamp</p> | Mandatory | Date file finish processed    |

Example :

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