# BRI Direct Debit

## Integration Steps

Overview of integration process with BRI Direct Debit

1. [Card Registration](#account-binding)
2. [OTP Verification](#otp-verification)
3. [Payment](#payment)
4. [Payment Notification](#payment-notification)
5. [Additional Feature](#additional-feature)

***

### 1. Card Registration

Card Registration process should be done before payment can be made and processed. Merchant will send card registration request from customer to DOKU. The request includes customer's card number that is registered to customer's BRI account. 

Each card/account can only registered/bind to one customer on one merchant. Customer needs to verify OTP and input PIN on BRI page.

**CBC Encryption**

To request card registration process, merchant requires to bring object cardData which value should be encrypted using CBC Algorithm.

CBC Encryption - Steps:

1. **Prepare shared key from DOKU as Secret Key**

   * Substring shared key only 16 digits
   * Example code:

   ```json
   private String getSharedKey(String sharedKey) {
       if (sharedKey.length() != 16) {
   sharedKey = sharedKey.length() > 16 ? sharedKey.substring(0, 16) : String.format("%-16s", sharedKey).replace(' ', '-');
       }
       return sharedKey;
   }
   ```
2. **Generate Initial Value (IV)**

   * Generate initial value with 16 bytes and then encode using Base 64
   * Example code:

   ```json
   byte[] iv = new byte[16];
   new SecureRandom().nextBytes(iv);
   IvParameterSpec ivParameterSpec = new IvParameterSpec(iv);
   String ivString = Base64.getEncoder().encodeToString(ivParameterSpec.getIV());
   ```
3. **Using Cipher CBC**

   * Value that will be encrypted combine with secret key generated before
   * After that encode the value using Base 64
   * Example code:

   ```json
   Cipher cipher = Cipher.getInstance("AES/CBC/PKCS5Padding"); //NOSONAR
   cipher.init(Cipher.ENCRYPT_MODE, key, ivParameterSpec);
   byte[] cipherText = cipher.doFinal(input.getBytes());
   String cipherString = Base64.getEncoder().encodeToString(cipherText);
   ```
4. **Combine CBC and IV**

   * Combine value CBC Cipher with IV value with separator (|)
   * Example code:

   <pre class="language-json"><code class="lang-json"><strong>String value = cipherString + "|" + ivString;
   </strong></code></pre>

Tools Using Java - Steps:

* Install JDK 17
* Go to folder
* Run with command java -jar cbc-tools.jar
* Input Value that you wish to be encrypted
* Input Key to encrypt&#x20;

Example Value:

```
{"bankCardNo":"6783","bankCardType":"D","identificationNo":"6013010111348228","identificationType":"02","email":"email@email.com","expiryDate":"0526"}
```

{% file src="/files/hIIYe2U7QDX432zkl8xy" %}
CBC Encryption Tools
{% endfile %}

**Card Registration Flow**

<figure><img src="/files/SO3BLIq4ATdTkYPRN7WQ" alt=""><figcaption><p>Card Registration Flow - BRI Direct Debit</p></figcaption></figure>

#### API Endpoint

<table><thead><tr><th width="184">Environment</th><th>Endpoint</th></tr></thead><tbody><tr><td>HTTP Method</td><td>POST</td></tr><tr><td>API Sandbox</td><td><a href="https://api-sandbox.doku.com">https://api-sandbox.doku.com</a></td></tr><tr><td>API Production</td><td><a href="https://api.doku.com">https://api.doku.com</a></td></tr><tr><td>Path</td><td><code>.../direct-debit/core/v1/registration-card-bind</code></td></tr></tbody></table>

**Sample of Request Header, Request Body and Response Body**

Notes:&#x20;

Parameter with (\*) is mandatory&#x20;

Paramater without (\*) is optional/conditional

{% openapi src="/files/MSY3vxegqub2HFQlFLUk" path="/direct-debit/core/v1/registration-card-bind" method="post" %}
[swagger-dd-bri.yaml](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2F1XAFuFMBkwdtqHQ5iIO9%2Fswagger-dd-bri.yaml?alt=media\&token=cd5eb7eb-201a-4383-8e4c-473acbd225d2)
{% endopenapi %}

***

### 2. OTP Verification

Once customer has registered their card through the platform, merchant needs to verify the card. Merchant can hit this API to verify the OTP.&#x20;

**OTP Verification Flow**

<figure><img src="/files/dWgHn2hE8mpe9sduoJx4" alt=""><figcaption><p>OTP Verification Flow - BRI Direct Debit</p></figcaption></figure>

#### API Endpoint

<table><thead><tr><th width="182">Environment</th><th>Endpoint</th></tr></thead><tbody><tr><td>HTTP Method</td><td>POST</td></tr><tr><td>API Sandbox</td><td><a href="https://api-sandbox.doku.com">https://api-sandbox.doku.com</a></td></tr><tr><td>API Production</td><td><a href="https://api.doku.com">https://api.doku.com</a></td></tr><tr><td>Path</td><td><code>.../direct-debit/core/v1/otp-verification</code></td></tr></tbody></table>

**Sample of Request Header, Request Body and Response Body**

Notes:&#x20;

Parameter with (\*) is mandatory&#x20;

Parameter without (\*) is optional/conditional

{% openapi src="/files/7pdcS4s1CMMwZBQSBC5z" path="/direct-debit/core/v1/otp-verification" method="post" %}
[swagger-dd-bri.yaml](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2FpLKl8wAHyiFtjVX7Cqxy%2Fswagger-dd-bri.yaml?alt=media\&token=bd8ac1d7-0477-41f0-b877-ce92f51a9766)
{% endopenapi %}

***

### 3. Payment&#x20;

After customer's card is registered, payment process can be requested by bringing the card token generated in card registration process. After merchant hit payment API, DOKU will deduct customer's balance.&#x20;

#### Payment - Tokenization

In tokenization scheme, every payment needs to be verified by customer with inputting OTP and/or PIN. In order to do that, merchant needs to bring parameter `paymentType : "SALE"`in payment request body.

And as the response, merchant will receive parameter `webRedirectUrl` to redirect the customer to merchant's page/platform to complete the payment by inputting OTP and/or PIN. After the payment is completed, merchant then will receive the notification.

#### Payment - Recurring

In recurring scheme, the payment process will be scheduled. Hence, verification using OTP and/or PIN is not required in every payment. Customers only need to do the verification during card registration process and it will give merchant the authorization to run scheduled payment. In order to do that, merchant needs to bring parameter `CHANNEL-ID : "H2H"` in request header and`paymentType : "RECURRING"`in payment request body.

And as the response, merchant will not receive parameter `webRedirectUrl` to redirect the customer to merchant's page/platform to complete the payment. Payment request will be directly processed by acquirer and merchant will receive the notification.

**Payment Flow**

This below payment flow is for tokenization scheme.

<figure><img src="/files/BeHbdbUNU635d0LVBTyO" alt=""><figcaption><p>Payment Flow - BRI Direct Debit - Tokenization Scheme</p></figcaption></figure>

#### API Endpoint

<table><thead><tr><th width="204">Environment</th><th>Endpoint</th></tr></thead><tbody><tr><td>HTTP Method</td><td>POST</td></tr><tr><td>API Sandbox</td><td><a href="https://api-sandbox.doku.com">https://api-sandbox.doku.com</a></td></tr><tr><td>API Production</td><td><a href="https://api.doku.com">https://api.doku.com</a></td></tr><tr><td>Path</td><td><code>.../direct-debit/core/v1/debit/payment-host-to-host</code></td></tr></tbody></table>

**Sample of Request Header, Request Body and Response Body**

Notes:&#x20;

Parameter with (\*) is mandatory&#x20;

Paramater without (\*) is optional/conditional

{% openapi src="/files/S8omMmJ0nsEXGiuxQNSk" path="/direct-debit/core/v1/debit/payment-host-to-host" method="post" %}
[swagger-dd-bri.yaml](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2FTGgubuuwtHMTILYzd3P9%2Fswagger-dd-bri.yaml?alt=media\&token=9adec817-0618-412e-a2c9-7c1e5816b57a)
{% endopenapi %}

***

### 4. Payment Notification

After payment is completed, DOKU will send **HTTP Notification** to merchant's defined `Notification URL`.  Learn how to [handle the notification from DOKU](/get-started-with-doku-api/notification.md).

***

### 5. Additional Feature

### Online Refund

This endpoint is used to create refund request for previous successful payment. Merchant can request a transaction refund to DOKU. Full refund and partial refund are available to be requested.

**Online Refund Flow**&#x20;

<figure><img src="/files/19LtMmU2HX8P149hythn" alt=""><figcaption><p>Online Refund Flow - BRI Direct Debit</p></figcaption></figure>

#### API Endpoint

<table><thead><tr><th width="196">Environment</th><th>Endpoint</th></tr></thead><tbody><tr><td>HTTP Method</td><td>POST</td></tr><tr><td>API Sandbox</td><td><a href="https://api-sandbox.doku.com">https://api-sandbox.doku.com</a></td></tr><tr><td>API Production</td><td><a href="https://api.doku.com">https://api.doku.com</a></td></tr><tr><td>Path</td><td><code>.../direct-debit/core/v1/debit/refund</code></td></tr></tbody></table>

**Sample of Request Header, Request Body and Response Body**

Notes:&#x20;

Parameter with (\*) is mandatory&#x20;

Paramater without (\*) is optional/conditional

{% openapi src="/files/D5UAq40JBNsanHPhCXoq" path="/direct-debit/core/v1/debit/refund" method="post" %}
[swagger-dd-bri.yaml](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2FOhI0Ei3qPMqmoZkS1UIc%2Fswagger-dd-bri.yaml?alt=media\&token=38081cd0-ad98-4035-b75d-7baf20564a51)
{% endopenapi %}

### Card Registration Unbinding

If a registered customer no longer wants their account/card to be bind/linked and wish to remove themself from DOKU's and merchant’s system, merchant can send account unbinding request that is initiated by customer.

#### API Endpoint&#x20;

<table><thead><tr><th width="187">Environment</th><th>Endpoint</th></tr></thead><tbody><tr><td>HTTP Method</td><td>POST</td></tr><tr><td>API Sandbox</td><td><a href="https://api-sandbox.doku.com">https://api-sandbox.doku.com</a></td></tr><tr><td>API Production</td><td><a href="https://api.doku.com">https://api.doku.com</a></td></tr><tr><td>Path</td><td><code>.../direct-debit/core/v1/registration-card-unbind</code></td></tr></tbody></table>

**Sample of Request Header, Request Body and Response Body**

Notes:&#x20;

Parameter with (\*) is mandatory&#x20;

Paramater without (\*) is optional/conditional

{% openapi src="/files/mQlH1uvQbhB9dFREghty" path="/direct-debit/core/v1/registration-card-unbind" method="post" %}
[swagger-dd-bri.yaml](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2F7Rb8w8TAxshJTAGyRklH%2Fswagger-dd-bri.yaml?alt=media\&token=a3e21c10-eda5-428b-9197-8474c8c8212b)
{% endopenapi %}


---

# 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/accept-payments/direct-api/snap/integration-guide/direct-debit/bri-direct-debit.md?ask=<question>
```

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.