BNC v1.0

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

Process Flow

There is one method to integrate with BNC 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

DOKU Generate Payment Code

Integration Steps

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

1. How to generate Signature
2. Create Virtual Account
3. Display Virtual Account
4. Acknowledge payment result
5. Hit Check Status API

---

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/v1/transfer-va/create-va

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

1. DOKU Generate Payment Code

DOKU Generate Payment Code

post

DOKU Generate Payment Code

Header parameters

X-TIMESTAMPstring · utc timestampRequired

Client's current local time in yyyy-MM- ddTHH:mm:ssTZD format

Example: 2020-12-21T07:56:11.000Z

X-SIGNATUREstringRequired

Algorithm symmetric signature HMAC_SHA512 (clientSecret, stringToSign)

Example: 85be817c55b2c135157c7e89f52499bf0c25ad6eeebe04a986e8c862561b19a5

X-PARTNER-IDstringRequired

Unique ID for a partner (DOKU'S Client ID)

Example: 821508239190

X-EXTERNAL-IDstringRequired

Numeric String. Reference number that should be unique in the same day (request-id)

Example: 418075533589

X-DEVICE-IDstringRequired

Device identification on which the API services are currently being accessed by the end user (customer). Can’t contain symbols

Example: 95221

X-IP-ADDRESSstringOptional

conditional. IP address of the end user (customer) using IPv4 format

Example: 95221

AuthorizationstringRequired

Access Token obtained from Get B2B Token API

Example: Bearer eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjE2OTgwNTA3NDMsImlzcyI6IkRPS1UiLCJjbGllbnRJZCI6IkJSTi0wMjExLTE2OTY5MTk2NTE5MTgifQ.x-D5VlK6TlVZbLPUSCr-Gbfgh4tnp0QDJmedYFHJGHFjg1c4x39pszU4sLvRhr0Jk0vKdMIzxUZeNhKoesWqDJitnG3kfrNZNsMb_WYUC0tJW91onXzYOKXiTgsHwRNFoWPQHlXIEtT3RQm-SRlCpk_E0gsavgkQn2-kbJEBnPhIs4eKg5IUY9GYi4hRr-_GHsudDl8sd2B5UBB_rHYq36BRmLXH7i7MQADHPsB1ktPVgk3ZWF0jebEjI-lJ88p-omL1vQNvRseXej2HKBa9chGLmPDvXYBQaRmmstHz-tv1boFrHfwsHJebcUec-i3WE1vMvP_3EPXdbqb45N4ciQ

Body

trxIdstringRequired

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

Example: 23219829713

virtualAccountTrxTypestringRequired

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

Example: 1

expiredDatestringOptional

Expiration date for Virtual Account. ISO-8601

Example: 2023-01-01T10:55:00+07:00

partnerServiceIdstringRequired

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

Example: 90341537

customerNostringRequired

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

Example: 00000000000000000000

virtualAccountNostringRequired

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

Example: 0000000000000000000000000000

virtualAccountNamestringRequired

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

Example: Toru Yamashita

virtualAccountEmailstringOptional

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

Example: [e-mail]

virtualAccountPhonestringOptional

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

Example: 0816291271826

Responses

200

item created

application/json

400

invalid input, object invalid

application/json

post

HTTPcURLJavaScriptPython

POST /bi-snap-va/bnc/v1/transfer-va/create-va HTTP/1.1
Host: {api-domain}
X-TIMESTAMP: 2020-12-21T07:56:11.000Z
X-SIGNATURE: 85be817c55b2c135157c7e89f52499bf0c25ad6eeebe04a986e8c862561b19a5
X-PARTNER-ID: 821508239190
X-EXTERNAL-ID: 418075533589
X-DEVICE-ID: 95221
Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjE2OTgwNTA3NDMsImlzcyI6IkRPS1UiLCJjbGllbnRJZCI6IkJSTi0wMjExLTE2OTY5MTk2NTE5MTgifQ.x-D5VlK6TlVZbLPUSCr-Gbfgh4tnp0QDJmedYFHJGHFjg1c4x39pszU4sLvRhr0Jk0vKdMIzxUZeNhKoesWqDJitnG3kfrNZNsMb_WYUC0tJW91onXzYOKXiTgsHwRNFoWPQHlXIEtT3RQm-SRlCpk_E0gsavgkQn2-kbJEBnPhIs4eKg5IUY9GYi4hRr-_GHsudDl8sd2B5UBB_rHYq36BRmLXH7i7MQADHPsB1ktPVgk3ZWF0jebEjI-lJ88p-omL1vQNvRseXej2HKBa9chGLmPDvXYBQaRmmstHz-tv1boFrHfwsHJebcUec-i3WE1vMvP_3EPXdbqb45N4ciQ
Content-Type: application/json
Accept: */*
Content-Length: 844

{
  "trxId": "23219829713",
  "virtualAccountTrxType": "1",
  "expiredDate": "2023-01-01T10:55:00+07:00",
  "partnerServiceId": "90341537",
  "customerNo": "00000000000000000000",
  "virtualAccountNo": "0000000000000000000000000000",
  "virtualAccountName": "Toru Yamashita",
  "virtualAccountEmail": "[e-mail]",
  "virtualAccountPhone": "0816291271826",
  "totalAmount": {
    "value": "11500.00",
    "currency": "IDR"
  },
  "feeAmount": {
    "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"
    }
  ],
  "additionalInfo": {
    "channel": "VIRTUAL_ACCOUNT_BNC"
  }
}

{
  "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": {
      "channel": "VIRTUAL_ACCOUNT_BNC"
    },
    "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"
    }
  }
}

1. Merchant Generate Payment Code

Merchant Generate Payment Code

post

Merchant Generate Payment Code

Header parameters

X-TIMESTAMPstring · utc timestampRequired

Client's current local time in yyyy-MM- ddTHH:mm:ssTZD format

Example: 2020-12-21T07:56:11.000Z

X-SIGNATUREstringRequired

Algorithm symmetric signature HMAC_SHA512 (clientSecret, stringToSign)

Example: 85be817c55b2c135157c7e89f52499bf0c25ad6eeebe04a986e8c862561b19a5

X-PARTNER-IDstringRequired

Unique ID for a partner (DOKU'S Client ID)

Example: 821508239190

X-EXTERNAL-IDstringRequired

Numeric String. Reference number that should be unique in the same day (request-id)

Example: 418075533589

X-DEVICE-IDstringRequired

Device identification on which the API services are currently being accessed by the end user (customer). Can’t contain symbols

Example: 95221

X-IP-ADDRESSstringOptional

conditional. IP address of the end user (customer) using IPv4 format

Example: 95221

AuthorizationstringRequired

Access Token obtained from Get B2B Token API

Example: Bearer eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjE2OTgwNTA3NDMsImlzcyI6IkRPS1UiLCJjbGllbnRJZCI6IkJSTi0wMjExLTE2OTY5MTk2NTE5MTgifQ.x-D5VlK6TlVZbLPUSCr-Gbfgh4tnp0QDJmedYFHJGHFjg1c4x39pszU4sLvRhr0Jk0vKdMIzxUZeNhKoesWqDJitnG3kfrNZNsMb_WYUC0tJW91onXzYOKXiTgsHwRNFoWPQHlXIEtT3RQm-SRlCpk_E0gsavgkQn2-kbJEBnPhIs4eKg5IUY9GYi4hRr-_GHsudDl8sd2B5UBB_rHYq36BRmLXH7i7MQADHPsB1ktPVgk3ZWF0jebEjI-lJ88p-omL1vQNvRseXej2HKBa9chGLmPDvXYBQaRmmstHz-tv1boFrHfwsHJebcUec-i3WE1vMvP_3EPXdbqb45N4ciQ

Body

trxIdstringRequired

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

Example: 23219829713

virtualAccountTrxTypestringRequired

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

Example: 1

expiredDatestringOptional

Expiration date for Virtual Account. ISO-8601

Example: 2023-01-01T10:55:00+07:00

partnerServiceIdstringRequired

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

Example: 90341537

customerNostringRequired

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

Example: 00000000000000000001

virtualAccountNostringRequired

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

Example: 9034153700000000000000000001

virtualAccountNamestringRequired

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

Example: Toru Yamashita

virtualAccountEmailstringOptional

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

Example: [e-mail]

virtualAccountPhonestringOptional

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

Example: 0816291271826

Responses

200

item created

application/json

400

invalid input, object invalid

application/json

post

HTTPcURLJavaScriptPython

POST /bi-snap-va/bnc/v1/transfer-va/create-va HTTP/1.1
Host: {api-domain}
X-TIMESTAMP: 2020-12-21T07:56:11.000Z
X-SIGNATURE: 85be817c55b2c135157c7e89f52499bf0c25ad6eeebe04a986e8c862561b19a5
X-PARTNER-ID: 821508239190
X-EXTERNAL-ID: 418075533589
X-DEVICE-ID: 95221
Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjE2OTgwNTA3NDMsImlzcyI6IkRPS1UiLCJjbGllbnRJZCI6IkJSTi0wMjExLTE2OTY5MTk2NTE5MTgifQ.x-D5VlK6TlVZbLPUSCr-Gbfgh4tnp0QDJmedYFHJGHFjg1c4x39pszU4sLvRhr0Jk0vKdMIzxUZeNhKoesWqDJitnG3kfrNZNsMb_WYUC0tJW91onXzYOKXiTgsHwRNFoWPQHlXIEtT3RQm-SRlCpk_E0gsavgkQn2-kbJEBnPhIs4eKg5IUY9GYi4hRr-_GHsudDl8sd2B5UBB_rHYq36BRmLXH7i7MQADHPsB1ktPVgk3ZWF0jebEjI-lJ88p-omL1vQNvRseXej2HKBa9chGLmPDvXYBQaRmmstHz-tv1boFrHfwsHJebcUec-i3WE1vMvP_3EPXdbqb45N4ciQ
Content-Type: application/json
Accept: */*
Content-Length: 844

{
  "trxId": "23219829713",
  "virtualAccountTrxType": "1",
  "expiredDate": "2023-01-01T10:55:00+07:00",
  "partnerServiceId": "90341537",
  "customerNo": "00000000000000000001",
  "virtualAccountNo": "9034153700000000000000000001",
  "virtualAccountName": "Toru Yamashita",
  "virtualAccountEmail": "[e-mail]",
  "virtualAccountPhone": "0816291271826",
  "totalAmount": {
    "value": "11500.00",
    "currency": "IDR"
  },
  "feeAmount": {
    "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"
    }
  ],
  "additionalInfo": {
    "channel": "VIRTUAL_ACCOUNT_BNC"
  }
}

{
  "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": {
      "channel": "VIRTUAL_ACCOUNT_BNC"
    },
    "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.