BTN Virtual Account

DOKU has partnered with various banks and one of them is BTN to provide Virtual Account Payment. Learn more about how DOKU can help you integrate with BTN Virtual Account here.

Process Flow

There is one method to integrate with BTN VA:

VA From Acquirer

Merchant could hit create VA API (service code 27) to create their virtual account number by acquirer. The number created then will be inquired by acquirer, merchant can get the payment notification.

Check this flow diagram to get know about this method

Register VA Flow

Integration Steps

Here is the overview of how to integrate with Virtual Account:

1. Create Virtual Account

2. Display Virtual Account

3. Acknowledge payment result

---

1. Create Virtual Account

To create Virtual Account, you will need to hit this API through your Backend:

API Endpoint

Type	Value
Service Code	27
HTTP Method	POST
API Endpoint Sandbox	https://api-sandbox.doku.com/.../
API Endpoint Production	https://api.doku.com/..../
Path	/bi-snap-va/btn/v1/transfer-va/create-va

Here is the sample request header, request body and response body for BTN VA

1. DOKU Generate Payment Code

DOKU Generate Payment Code

DOKU Generate Payment Code

POSThttps://{api-domain}/bi-snap-va/btn/v1/transfer-va/create-va

Header parameters

Body

application/json

Create VA SNAP request

trxId*string

Transaction ID in Partner system. | min length: 1 | max length: 64

virtualAccountTrxType*string

Transaction ID in Partner system. Fil 1 for Closed Payment, fill 2 for Open Payment | min length: 1 | max length: 1

expiredDatestring

Expiration date for Virtual Account. ISO-8601

partnerServiceId*string

similar to company code/BIN,8 digit left padding space. | min length: 1 | max length: 8

customerNo*string

Unique number (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | min length: 1 | max length: 20

virtualAccountNo*string

partnerServiceId (8 digit left padding 0) + customerNo (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | min length: 1 | max length: 28

virtualAccountName*string

Customer Name | min length: 1 | max length: 255

virtualAccountEmailstring

Customer Email | min length: 1 | max length: 255

virtualAccountPhonestring

Customer Phone, Format: 62xxxxxxxxx xxxx | min length: 9 | max length: 30

totalAmount*TotalAmountRef (object)

feeAmountFeeAmountRef (object)

billDetailsBillDetailsRef (array of object)

freeTextsFreeTextRef (array of object)

additionalInfoAdditionalInfoCreateVARef (object)

Response

200400403404409500504

item created

Body

application/json

responseCode*string

Response Code with format HTTP status code + service code + case code. | min length: 1 | max length: 7

responseMessage*string

Response Description. | min length: 1 | max length: 150

virtualAccountDataobject

Request

JavaScriptCurl

const response = await fetch('https://{api-domain}/bi-snap-va/btn/v1/transfer-va/create-va', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "partnerServiceId": "90341537",
      "customerNo": "00000000000000000000",
      "virtualAccountNo": "0000000000000000000000000000",
      "virtualAccountName": "Toru Yamashita",
      "trxId": "23219829713",
      "virtualAccountTrxType": "1",
      "totalAmount": {}
    }),
});
const data = await response.json();

Response

{
  "responseCode": "2002700",
  "responseMessage": "Successful",
  "virtualAccountData": {
    "partnerServiceId": "90341537",
    "customerNo": "0000000000112",
    "virtualAccountNo": "903415370000000000112",
    "virtualAccountName": "Toru Yamashita",
    "virtualAccountEmail": "[e-mail]",
    "virtualAccountPhone": "081293912081",
    "trxId": "23219829713",
    "totalAmount": {
      "value": "11500.00",
      "currency": "IDR"
    },
    "billDetails": [
      {
        "billCode": "01",
        "billNo": "110292189291727",
        "billName": "A bill for Toru",
        "billShortName": "Bill T",
        "billDescription": {
          "english": "Maintenance",
          "indonesia": "Pemeliharaan"
        },
        "billSubCompany": "00001",
        "billAmount": {
          "value": "11500.00",
          "currency": "IDR"
        },
        "additionalInfo": {
          "id": "Hallo bro",
          "en": "Hallo world"
        }
      }
    ],
    "freeTexts": [
      {
        "id": "Hallo bro",
        "en": "Hallo world"
      }
    ],
    "virtualAccountTrxType": "1",
    "feeAmount": {
      "value": "11500.00",
      "currency": "IDR"
    },
    "expiredDate": "2023-01-01T10:55:00+07:00",
    "additionalInfo": {
      "channel": "VIRTUAL_ACCOUNT_BTN"
    },
    "howToPayInfo": {
      "howToPayPage": "https://sandbox.doku.com/bnc-virtual-acccount/v1/how-to-pay-page/0008889912345678901234567890",
      "howToPayApi": "https://api-sandbox.doku.com/bnc-virtual-acccount/v1/how-to-pay-api/0008889912345678901234567890"
    }
  }
}

2. Merchant Generate Payment Code

Merchant Generate Payment Code

Merchant Generate Payment Code

POSThttps://{api-domain}/bi-snap-va/btn/v1/transfer-va/create-va

Header parameters

Body

application/json

Create VA SNAP request

trxId*string

Transaction ID in Partner system. | min length: 1 | max length: 64

virtualAccountTrxType*string

Transaction ID in Partner system. Fil 1 for Closed Payment, fill 2 for Open Payment | min length: 1 | max length: 1

expiredDatestring

Expiration date for Virtual Account. ISO-8601

partnerServiceId*string

similar to company code/BIN,8 digit left padding space. | min length: 1 | max length: 8

customerNo*string

Unique number (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | min length: 1 | max length: 20

virtualAccountNo*string

partnerServiceId (8 digit left padding 0) + customerNo (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | min length: 1 | max length: 28

virtualAccountName*string

Customer Name | min length: 1 | max length: 255

virtualAccountEmailstring

Customer Email | min length: 1 | max length: 255

virtualAccountPhonestring

Customer Phone, Format: 62xxxxxxxxx xxxx | min length: 9 | max length: 30

totalAmount*TotalAmountRef (object)

feeAmountFeeAmountRef (object)

billDetailsBillDetailsRef (array of object)

freeTextsFreeTextRef (array of object)

additionalInfoAdditionalInfoCreateVARef (object)

Response

200400403404409500504

item created

Body

application/json

responseCode*string

Response Code with format HTTP status code + service code + case code. | min length: 1 | max length: 7

responseMessage*string

Response Description. | min length: 1 | max length: 150

virtualAccountDataobject

Request

JavaScriptCurl

const response = await fetch('https://{api-domain}/bi-snap-va/btn/v1/transfer-va/create-va', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "partnerServiceId": "90341537",
      "customerNo": "0000001702529163",
      "virtualAccountNo": "0000001702529163",
      "virtualAccountName": "Toru Yamashita",
      "trxId": "23219829713",
      "virtualAccountTrxType": "1",
      "totalAmount": {}
    }),
});
const data = await response.json();

Response

{
  "responseCode": "2002700",
  "responseMessage": "Successful",
  "virtualAccountData": {
    "partnerServiceId": "90341537",
    "customerNo": "0000000000112",
    "virtualAccountNo": "903415370000000000112",
    "virtualAccountName": "Toru Yamashita",
    "virtualAccountEmail": "[e-mail]",
    "virtualAccountPhone": "081293912081",
    "trxId": "23219829713",
    "totalAmount": {
      "value": "11500.00",
      "currency": "IDR"
    },
    "billDetails": [
      {
        "billCode": "01",
        "billNo": "110292189291727",
        "billName": "A bill for Toru",
        "billShortName": "Bill T",
        "billDescription": {
          "english": "Maintenance",
          "indonesia": "Pemeliharaan"
        },
        "billSubCompany": "00001",
        "billAmount": {
          "value": "11500.00",
          "currency": "IDR"
        },
        "additionalInfo": {
          "id": "Hallo bro",
          "en": "Hallo world"
        }
      }
    ],
    "freeTexts": [
      {
        "id": "Hallo bro",
        "en": "Hallo world"
      }
    ],
    "virtualAccountTrxType": "1",
    "feeAmount": {
      "value": "11500.00",
      "currency": "IDR"
    },
    "expiredDate": "2023-01-01T10:55:00+07:00",
    "additionalInfo": {
      "channel": "VIRTUAL_ACCOUNT_BTN"
    },
    "howToPayInfo": {
      "howToPayPage": "https://sandbox.doku.com/bnc-virtual-acccount/v1/how-to-pay-page/0008889912345678901234567890",
      "howToPayApi": "https://api-sandbox.doku.com/bnc-virtual-acccount/v1/how-to-pay-api/0008889912345678901234567890"
    }
  }
}

Pro Tips!

1. You can also show payment instruction link to your customer by using virtual_account_info.how_to_pay_page

2. If you wish to customize the UI for the payment instruction, you can use the virtual_account_info.how_to_pay_api

2. Display Virtual Account

You can display the payment code to your customer by using virtual_account_info.virtual_account_number that you retrieved from the API response.

3. Acknowledge payment result

After the payment is being made by your customer, DOKU will send HTTP Notification to your defined Notification URL. Learn how to handle the notification from DOKU .

4. Hit DOKU Check Status API

If you do not receive notifications from DOKU due to some issue, you can perform an API status check on the DOKU side to determine the updated transaction status. See the detailed request and response here Check Status API.

2. Direct Inquiry

Here is the overview of how to integrate Direct Inquiry BTN VA :

1. Setup Inquiry URL on DOKU Dashboard

2. Generate Payment Code on your End

3. Receive Inquiry Request from DOKU

4. Acknowledge Payment Notification

Check this flow to diagram to get know about this API :

To get Inquiry Request from DOKU, you will need to hit this API through your Backend:

1. Setup Inquiry URL on DOKU Dashboard

To receive the inquiry request from DOKU. You must set your Inquiry URL to DOKU. Please contact our team for the setup.

Please inform the Inquiry URL for Sandbox environment and Production environment.

2. Generate Payment Code on your end

Generate payment is done in your system. The payment code length maximum is 23 digits.

3. Receive Inquiry Request from DOKU

Here is the sample request header, request body from DOKU

Direct Inquiry

Direct Inquiry

POSThttps://{api-domain}/url-direct-inquiry-merchant

Header parameters

Body

application/json

Direct Inquiry SNAP request

partnerServiceId*string

similar to company code/BIN,8 digit left padding space. | min length: 1 | max length: 8

customerNo*string

Unique number (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | min length: 1 | max length: 20

virtualAccountNostring

partnerServiceId (8 digit left padding 0) + customerNo (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | min length: 1 | max length: 28

channelCodestring

Channel code from bank | min length: 1 | max length: 5

trxDateInit*string

Transaction date

languagestring

Language | min length: 1 | max length: 2

inquiryRequestId*string

Unique Inquiry request id | min length: 1 | max length: 30

additionalInfoAdditionalInfoRef (object)

Additional Information for custom use | min length: 1 | max length: Unlimited

Response

200400403404409500504

item created

Body

application/json

responseCode*string

Response Code with format HTTP status code + service code + case code. | min length: 1 | max length: 7

responseMessage*string

Response Description. | min length: 1 | max length: 150

virtualAccountData*object

Request

JavaScriptCurl

const response = await fetch('https://{api-domain}/url-direct-inquiry-merchant', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "partnerServiceId": "90341537",
      "customerNo": "00000000000000000000",
      "trxDateInit": "2023-01-01T10:55:00+07:00",
      "inquiryRequestId": "12839218738127830"
    }),
});
const data = await response.json();

Response

{
  "responseCode": "2007300",
  "responseMessage": "Successful",
  "virtualAccountData": {
    "partnerServiceId": "90341537",
    "customerNo": "0000000000112",
    "virtualAccountNo": "903415370000000000112",
    "virtualAccountName": "Toru Yamashita",
    "virtualAccountEmail": "[e-mail]",
    "virtualAccountPhone": "081293912081",
    "trxId": "23219829713",
    "totalAmount": {
      "value": "11500.00",
      "currency": "IDR"
    },
    "billDetails": [
      {
        "billCode": "01",
        "billNo": "110292189291727",
        "billName": "A bill for Toru",
        "billShortName": "Bill T",
        "billDescription": {
          "english": "Maintenance",
          "indonesia": "Pemeliharaan"
        },
        "billSubCompany": "00001",
        "billAmount": {
          "value": "11500.00",
          "currency": "IDR"
        },
        "additionalInfo": {
          "id": "Hallo bro",
          "en": "Hallo world"
        }
      }
    ],
    "freeTexts": [
      {
        "id": "Hallo bro",
        "en": "Hallo world"
      }
    ],
    "virtualAccountTrxType": "1",
    "feeAmount": {
      "value": "11500.00",
      "currency": "IDR"
    },
    "expiredDate": "2023-01-01T10:55:00+07:00",
    "additionalInfo": {
      "id": "Hallo bro",
      "en": "Hallo world"
    },
    "inquiryStatus": "SUCCESS",
    "inquiryReason": {
      "english": "Success",
      "indonesia": "Sukses"
    },
    "inquiryRequestId": "12839218738127830",
    "subCompany": "128392"
  }
}

3. Acknowledge payment result

After the payment is being made by your customer, DOKU will send HTTP Notification to your defined Notification URL. Learn how to handle the notification from DOKU .

4. Hit DOKU Check Status API

If you do not receive notifications from DOKU due to some issue, you can perform an API status check on the DOKU side to determine the updated transaction status. See the detailed request and response here Check Status API.