CIMB Virtual Account

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

Integration methods​

There are two methods to integrate with CIMB VA:

1. Create VA: The VA number will be registered to DOKU and Acquirer will inquiry to our side when the customer make payment at the acquirer channel (ATM, mobile banking, internet banking, etc.)

   1. DOKU Generated Payment Code (DGPC): The VA number is generated by DOKU. Suitable for e-commerce business model.

   2. Merchant Generated Payment Code (MGPC): The VA number is generated by Merchant. Suitable for top up business model.

2. Direct Inquiry (DIPC): The VA number is registered on merchant side and DOKU will forward Acquirer inquiry request to merchant side when the customer make payment at the acquirer channel (ATM, mobile banking, internet banking, etc.)

Integration Steps

Precondition

Get Token API

As client who hit DOKU's API such as Create VA, you need to obtain an access token first. Learn how to do it in this section.

Generate Signature

X- SIGNATURE is a security parameter that needs to be generated on merchant's Backend to verify the request authenticity.

So, it's very crucial for merchant to generate the X-SIGNATURE. Learn how to do it in this section

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

1. Create Virtual Account

   a. DOKU Generate Payment Code

   b. Merchant Generate Payment Code

   c. Display Virtual Account

   d. Acknowledge Payment Result

   e. Hit DOKU Check Status API

   f. Delete Virtual Account

   g. Update Virtual Account

---

1. Create VA

To create VA, 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	/virtual-accounts/bi-snap-va/v1.1/transfer-va/create-va

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

a. DOKU Generate Payment Code

Check this flow diagram to get know about this method

DOKU Generate Payment Code

Request Header

Parameter	Type	Mandatory	Description
X- TIMESTAMP	String	Mandatory	Client's current local time in yyyy-MM-ddTHH:mm:ssZ format
X-SIGNATURE	String	Mandatory	Algorithm symmetric signature HMAC_SHA2512(clientSecret, stringToSign) Refer to this Docs
X-PARTNER-ID	String	Mandatory	Unique ID for a partner (Merchant Client ID )
X-EXTERNAL-ID	String	Mandatory	Numeric string. Reference number that should be unique in the same day ( request-id)
CHANNEL-ID	String	Mandatory	channel ID for VA. Please fill with H2H (Host-To-Host)
Authorization	String	Mandatory	Bearer "access token" obtainedn from Get B2B Token API , refer to this Docs

DOKU Generate Payment Code

DOKU Generate Payment Code

POSThttps://{api-domain}/virtual-accounts/bi-snap-va/v1.1/transfer-va/create-va

Header parameters

Body

application/json

Create VA SNAP request

partnerServiceId*string

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

Example: " 1899"

customerNo*string

Prefix Sub BIN Merchant. | Mandatory | min length: 1 | max length: 20

Example: "0"

virtualAccountNo*string

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

Example: " 18990"

virtualAccountName*string

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

Example: "Customer Name"

virtualAccountEmailstring

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

Example: "[e-mail]"

virtualAccountPhonestring

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

Example: "0816291271826"

trxId*string

Invoice number in Partner system. | Mandatory | min length: 1 | max length: 64

Example: "23219829713"

totalAmount*TotalAmountRef (object)

additionalInfo*AdditionalInfoCreateVARequestRef (object)

virtualAccountTrxType*VirtualAccountTrxTypeRef (string)

Transaction type for this transaction. C (Closed Amount), O (Open Amount) | Mandatory | min length: 1 | max length: 1

Example: "C"

expiredDatestring

Expiration date for Virtual Account. ISO-8601

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

freeTextFreeTextsRefs (array of object)

Free text for additional description. | Optional | min length: 1 | max length: 64

Response

200400403404409500504

item created

Body

application/json

responseCode*string

Response Code with format HTTP status code + service code + case code. service code and status code refer to: https://developers.doku.com/getting-started-with-doku-api/error-handling/http-status-and-case-code#id-1.-virtual-account . | Mandatory | min length: 1 | max length: 7.

Example: "2002700"

responseMessage*string

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

Example: "Successful"

virtualAccountData*object

Request

JavaScriptCurlPython

const response = await fetch('https://{api-domain}/virtual-accounts/bi-snap-va/v1.1/transfer-va/create-va', {
    method: 'POST',
    headers: {
      "X-TIMESTAMP": "2024-03-19T14:39:01+07:00",
      "X-SIGNATURE": "85be817c55b2c135157c7e89f52499bf0c25ad6eeebe04a986e8c862561b19a5",
      "X-PARTNER-ID": "BRN-0259-1678068334526",
      "X-EXTERNAL-ID": "418075533589",
      "CHANNEL-ID": "H2H",
      "Authorization": "Bearer eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjE2OTgwNTA3NDMsImlzcyI6IkRPS1UiLCJjbGllbnRJZCI6IkJSTi0wMjExLTE2OTY5MTk2NTE5MTgifQ.x-D5VlK6TlVZbLPUSCr-Gbfgh4tnp0QDJmedYFHJGHFjg1c4x39pszU4sLvRhr0Jk0vKdMIzxUZeNhKoesWqDJitnG3kfrNZNsMb_WYUC0tJW91onXzYOKXiTgsHwRNFoWPQHlXIEtT3RQm-SRlCpk_E0gsavgkQn2-kbJEBnPhIs4eKg5IUY9GYi4hRr-_GHsudDl8sd2B5UBB_rHYq36BRmLXH7i7MQADHPsB1ktPVgk3ZWF0jebEjI-lJ88p-omL1vQNvRseXej2HKBa9chGLmPDvXYBQaRmmstHz-tv1boFrHfwsHJebcUec-i3WE1vMvP_3EPXdbqb45N4ciQ",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "partnerServiceId": "    1899",
      "customerNo": "0",
      "virtualAccountNo": "    18990",
      "virtualAccountName": "Customer Name",
      "trxId": "23219829713",
      "virtualAccountTrxType": "C",
      "totalAmount": {
        "value": "11500.00",
        "currency": "IDR"
      },
      "additionalInfo": {
        "channel": "VIRTUAL_ACCOUNT_BANK_CIMB"
      }
    }),
});
const data = await response.json();

Response

200400403404409500504

{
  "responseCode": "2002700",
  "responseMessage": "Successful",
  "virtualAccountData": {
    "partnerServiceId": "    1899",
    "customerNo": "00000000000000000001",
    "virtualAccountNo": "    189900000000000000000001",
    "virtualAccountName": "Customer Name",
    "virtualAccountEmail": "[e-mail]",
    "virtualAccountPhone": "081293912081",
    "trxId": "23219829713",
    "totalAmount": {
      "value": "11500.00",
      "currency": "IDR"
    },
    "virtualAccountTrxType": "C",
    "expiredDate": "2023-01-01T10:55:00+07:00",
    "additionalInfo": {
      "channel": "VIRTUAL_ACCOUNT_BANK_CIMB",
      "howToPayPage": "https://app.doku.com/how-to-pay/virtual-account/cimb/189900000000000000000001/2226240319101120691107165798734001192511",
      "howToPayApi": "https://api.doku.com/pay-instruction/cimb/189900000000000000000001/2226240319101120691107165798734001192511"
    }
  }
}

Learn what are the response codes!

b. Merchant Generate Payment Code

Check this flow diagram to get know about this method

Merchant Generate Payment Code

Request Header

Parameter	Type	Mandatory	Description
X- TIMESTAMP	String	Mandatory	Client's current local time in yyyy-MM-ddTHH:mm:ssZ format
X-SIGNATURE	String	Mandatory	Algorithm symmetric signature HMAC_SHA2512(clientSecret, stringToSign) Refer to this Docs
X-PARTNER-ID	String	Mandatory	Unique ID for a partner (Merchant Client ID )
X-EXTERNAL-ID	String	Mandatory	Numeric string. Reference number that should be unique in the same day ( request-id)
CHANNEL-ID	String	Mandatory	channel ID for VA. Please fill with H2H (Host-To-Host )
Authorization	String	Mandatory	Bearer "access token" obtained from Get B2B Token API , refer to this Docs

Merchant Generate Payment Code

Merchant Generate Payment Code

POSThttps://{api-domain}/virtual-accounts/bi-snap-va/v1.1/transfer-va/create-va

Header parameters

Body

application/json

Create VA SNAP request

partnerServiceId*string

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

Example: " 1899"

customerNo*string

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

Example: "00000000000000000001"

virtualAccountNo*string

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

Example: " 189900000000000000000001"

virtualAccountName*string

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

Example: "Customer Name"

virtualAccountEmailstring

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

Example: "[e-mail]"

virtualAccountPhonestring

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

Example: "0816291271826"

trxId*string

Invoice number in Partner system. | Mandatory | min length: 1 | max length: 64

Example: "23219829713"

totalAmount*TotalAmountRef (object)

additionalInfo*AdditionalInfoCreateVARequestRef (object)

virtualAccountTrxType*VirtualAccountTrxTypeRef (string)

Transaction type for this transaction. C (Closed Amount), O (Open Amount) | Mandatory | min length: 1 | max length: 1

Example: "C"

expiredDatestring

Expiration date for Virtual Account. ISO-8601

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

freeTextFreeTextsRefs (array of object)

Free text for additional description. | Optional | min length: 1 | max length: 64

Response

200400403404409500504

item created

Body

application/json

responseCode*string

Response Code with format HTTP status code + service code + case code. service code and status code refer to: https://developers.doku.com/getting-started-with-doku-api/error-handling/http-status-and-case-code#id-1.-virtual-account . | Mandatory | min length: 1 | max length: 7.

Example: "2002700"

responseMessage*string

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

Example: "Successful"

virtualAccountData*object

Request

JavaScriptCurlPython

const response = await fetch('https://{api-domain}/virtual-accounts/bi-snap-va/v1.1/transfer-va/create-va', {
    method: 'POST',
    headers: {
      "X-TIMESTAMP": "2024-03-19T14:39:01+07:00",
      "X-SIGNATURE": "85be817c55b2c135157c7e89f52499bf0c25ad6eeebe04a986e8c862561b19a5",
      "X-PARTNER-ID": "BRN-0259-1678068334526",
      "X-EXTERNAL-ID": "418075533589",
      "CHANNEL-ID": "H2H",
      "Authorization": "Bearer eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjE2OTgwNTA3NDMsImlzcyI6IkRPS1UiLCJjbGllbnRJZCI6IkJSTi0wMjExLTE2OTY5MTk2NTE5MTgifQ.x-D5VlK6TlVZbLPUSCr-Gbfgh4tnp0QDJmedYFHJGHFjg1c4x39pszU4sLvRhr0Jk0vKdMIzxUZeNhKoesWqDJitnG3kfrNZNsMb_WYUC0tJW91onXzYOKXiTgsHwRNFoWPQHlXIEtT3RQm-SRlCpk_E0gsavgkQn2-kbJEBnPhIs4eKg5IUY9GYi4hRr-_GHsudDl8sd2B5UBB_rHYq36BRmLXH7i7MQADHPsB1ktPVgk3ZWF0jebEjI-lJ88p-omL1vQNvRseXej2HKBa9chGLmPDvXYBQaRmmstHz-tv1boFrHfwsHJebcUec-i3WE1vMvP_3EPXdbqb45N4ciQ",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "partnerServiceId": "    1899",
      "customerNo": "00000000000000000001",
      "virtualAccountNo": "    189900000000000000000001",
      "virtualAccountName": "Customer Name",
      "trxId": "23219829713",
      "virtualAccountTrxType": "C",
      "totalAmount": {
        "value": "11500.00",
        "currency": "IDR"
      },
      "additionalInfo": {
        "channel": "VIRTUAL_ACCOUNT_BANK_CIMB"
      }
    }),
});
const data = await response.json();

Response

200400403404409500504

{
  "responseCode": "2002700",
  "responseMessage": "Successful",
  "virtualAccountData": {
    "partnerServiceId": "    1899",
    "customerNo": "00000000000000000001",
    "virtualAccountNo": "    189900000000000000000001",
    "virtualAccountName": "Customer Name",
    "virtualAccountEmail": "[e-mail]",
    "virtualAccountPhone": "081293912081",
    "trxId": "23219829713",
    "totalAmount": {
      "value": "11500.00",
      "currency": "IDR"
    },
    "virtualAccountTrxType": "C",
    "expiredDate": "2023-01-01T10:55:00+07:00",
    "additionalInfo": {
      "channel": "VIRTUAL_ACCOUNT_BANK_CIMB",
      "howToPayPage": "https://app.doku.com/how-to-pay/virtual-account/cimb/19008000000000000000000001/2226240319101120691107165798734001192511",
      "howToPayApi": "https://api.doku.com/pay-instruction/cimb/19008000000000000000000001/2226240319101120691107165798734001192511"
    }
  }
}

Learn what are the response codes!

Pro Tips!

1. You can also show payment instruction link to your customer by using additionalInfo.howToPayPage

2. If you wish to customize the UI for the payment instruction, you can use the additionalInfo.howToPayApi

c. Display Virtual Account

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

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

Payment Notification

Payment Notification

POSThttps://{merchant-domain}/v1.1/transfer-va/payment

Header parameters

Body

application/json

Payment Notification SNAP request

partnerServiceId*string

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

Example: " 1899"

customerNo*string

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

Example: "00000000000000000001"

virtualAccountNo*string

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

Example: " 189900000000000000000001"

virtualAccountName*string

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

Example: "Customer Name"

virtualAccountEmailstring

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

Example: "[e-mail]"

trxId*string

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

Example: "23219829713"

paymentRequestIdstring

Unique identifier generated by PJP. If Payment comes from the Inquiry process, this value must be the same with inquiryRequestId. | Mandatory | min length: 1 | max length: 30

Example: "12839218738127830"

paidAmount*TotalAmountRef (object)

virtualAccountPhonestring

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

Example: "081293912081"

additionalInfo*AdditionalInfoRequestRef (object)

trxDateTimestring

DOKU's transaction date time

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

virtualAccountTrxTypeVirtualAccountTrxTypeRef (string)

Transaction type for this transaction. C (Closed Amount), O (Open Amount) | Mandatory | min length: 1 | max length: 1

Example: "C"

Response

200400403404409500504

item created

Body

application/json

responseCode*string

Response Code with format HTTP status code + service code + case code. service code and status code refer to: https://developers.doku.com/getting-started-with-doku-api/error-handling/http-status-and-case-code#id-1.-virtual-account . | Mandatory | min length: 1 | max length: 7.

Example: "2002500"

responseMessage*string

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

Example: "Success"

virtualAccountData*object

Request

JavaScriptCurlPython

const response = await fetch('https://{merchant-domain}/v1.1/transfer-va/payment', {
    method: 'POST',
    headers: {
      "X-TIMESTAMP": "2024-03-19T14:39:01+07:00",
      "X-SIGNATURE": "85be817c55b2c135157c7e89f52499bf0c25ad6eeebe04a986e8c862561b19a5",
      "X-PARTNER-ID": "821508239190",
      "X-EXTERNAL-ID": "418075533589",
      "CHANNEL-ID": "H2H",
      "Authorization": "Bearer eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjE2OTgwNTA3NDMsImlzcyI6IkRPS1UiLCJjbGllbnRJZCI6IkJSTi0wMjExLTE2OTY5MTk2NTE5MTgifQ.x-D5VlK6TlVZbLPUSCr-Gbfgh4tnp0QDJmedYFHJGHFjg1c4x39pszU4sLvRhr0Jk0vKdMIzxUZeNhKoesWqDJitnG3kfrNZNsMb_WYUC0tJW91onXzYOKXiTgsHwRNFoWPQHlXIEtT3RQm-SRlCpk_E0gsavgkQn2-kbJEBnPhIs4eKg5IUY9GYi4hRr-_GHsudDl8sd2B5UBB_rHYq36BRmLXH7i7MQADHPsB1ktPVgk3ZWF0jebEjI-lJ88p-omL1vQNvRseXej2HKBa9chGLmPDvXYBQaRmmstHz-tv1boFrHfwsHJebcUec-i3WE1vMvP_3EPXdbqb45N4ciQ",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "partnerServiceId": "    1899",
      "customerNo": "00000000000000000001",
      "virtualAccountNo": "    189900000000000000000001",
      "virtualAccountName": "Customer Name",
      "trxId": "23219829713",
      "paidAmount": {
        "value": "11500.00",
        "currency": "IDR"
      },
      "additionalInfo": {
        "channel": "VIRTUAL_ACCOUNT_BANK_CIMB"
      }
    }),
});
const data = await response.json();

Response

200400403404409500504

{
  "responseCode": "2002500",
  "responseMessage": "Success",
  "virtualAccountData": {
    "partnerServiceId": "    1899",
    "customerNo": "00000000000000000001",
    "virtualAccountNo": "    189900000000000000000001",
    "virtualAccountName": "Customer Name",
    "virtualAccountEmail": "[e-mail]",
    "paymentRequestId": "12839218738127830",
    "paidAmount": {
      "value": "11500.00",
      "currency": "IDR"
    },
    "virtualAccountTrxType": "C",
    "additionalInfo": {
      "channel": "VIRTUAL_ACCOUNT_BANK_CIMB",
      "virtualAccountConfig": {
        "minAmount": "10000.00",
        "maxAmount": "5000000.00"
      }
    }
  }
}

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

---

f. Delete Payment Code

If you wish to delete your virtual account, you can do that by hitting the API with this API :

Request Header

Parameter	Type	Mandatory	Description
X- TIMESTAMP	String	Mandatory	Client's current local time in yyyy-MM-ddTHH:mm:ssZ format
X-SIGNATURE	String	Mandatory	Algorithm symmetric signature HMAC_SHA2512(clientSecret, stringToSign) Refer to this Docs
X-PARTNER-ID	String	Mandatory	Unique ID for a partner (Merchant Client ID )
X-EXTERNAL-ID	String	Mandatory	Numeric string. Reference number that should be unique in the same day ( request-id)
CHANNEL-ID	String	Mandatory	channel ID for VA. Please fill with H2H (Host-To-Host)
Authorization	String	Mandatory	Bearer "access token" obtainedn from Get B2B Token API , refer to this Docs

Delete Payment Code

Delete Payment Code

DELETEhttps://{api-domain}/virtual-accounts/bi-snap-va/v1.1/transfer-va/delete-va

Header parameters

Body

application/json

Delete VA SNAP request

partnerServiceId*string

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

Example: " 1899"

customerNo*string

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

Example: "00000000000000000001"

virtualAccountNo*string

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

Example: " 189900000000000000000001"

trxId*string

Invoice number in Partner system. | Mandatory | min length: 1 | max length: 64

Example: "23219829713"

additionalInfo*AdditionalInfoCreateVARequestRef (object)

Response

200400403404409500504

item created

Body

application/json

responseCode*string

Response Code with format HTTP status code + service code + case code. service code and status code refer to: https://developers.doku.com/getting-started-with-doku-api/error-handling/http-status-and-case-code#id-1.-virtual-account . | Mandatory | min length: 1 | max length: 7.

Example: "2003100"

responseMessage*string

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

Example: "Successful"

virtualAccountData*object

Request

JavaScriptCurlPython

const response = await fetch('https://{api-domain}/virtual-accounts/bi-snap-va/v1.1/transfer-va/delete-va', {
    method: 'DELETE',
    headers: {
      "X-TIMESTAMP": "2024-03-19T14:39:01+07:00",
      "X-SIGNATURE": "85be817c55b2c135157c7e89f52499bf0c25ad6eeebe04a986e8c862561b19a5",
      "X-PARTNER-ID": "BRN-0259-1678068334526",
      "X-EXTERNAL-ID": "418075533589",
      "CHANNEL-ID": "H2H",
      "Authorization": "Bearer eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjE2OTgwNTA3NDMsImlzcyI6IkRPS1UiLCJjbGllbnRJZCI6IkJSTi0wMjExLTE2OTY5MTk2NTE5MTgifQ.x-D5VlK6TlVZbLPUSCr-Gbfgh4tnp0QDJmedYFHJGHFjg1c4x39pszU4sLvRhr0Jk0vKdMIzxUZeNhKoesWqDJitnG3kfrNZNsMb_WYUC0tJW91onXzYOKXiTgsHwRNFoWPQHlXIEtT3RQm-SRlCpk_E0gsavgkQn2-kbJEBnPhIs4eKg5IUY9GYi4hRr-_GHsudDl8sd2B5UBB_rHYq36BRmLXH7i7MQADHPsB1ktPVgk3ZWF0jebEjI-lJ88p-omL1vQNvRseXej2HKBa9chGLmPDvXYBQaRmmstHz-tv1boFrHfwsHJebcUec-i3WE1vMvP_3EPXdbqb45N4ciQ",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "partnerServiceId": "    1899",
      "customerNo": "00000000000000000001",
      "virtualAccountNo": "    189900000000000000000001",
      "trxId": "23219829713",
      "additionalInfo": {
        "channel": "VIRTUAL_ACCOUNT_BANK_CIMB"
      }
    }),
});
const data = await response.json();

Response

200400403404409500504

{
  "responseCode": "2003100",
  "responseMessage": "Successful",
  "virtualAccountData": {
    "partnerServiceId": "    1899",
    "customerNo": "00000000000000000001",
    "virtualAccountNo": "    189900000000000000000001",
    "trxId": "23219829713",
    "additionalInfo": {
      "channel": "VIRTUAL_ACCOUNT_BANK_CIMB",
      "virtualAccountConfig": {
        "status": "DELETED",
        "minAmount": "10000.00",
        "maxAmount": "5000000.00"
      }
    }
  }
}

g. Update Payment Code

If you wish to update your virtual account, you can do that by hitting the API with this API :

Request Header

Parameter	Type	Mandatory	Description
X- TIMESTAMP	String	Mandatory	Client's current local time in yyyy-MM-ddTHH:mm:ssZ format
X-SIGNATURE	String	Mandatory	Algorithm symmetric signature HMAC_SHA2512(clientSecret, stringToSign) Refer to this Docs
X-PARTNER-ID	String	Mandatory	Unique ID for a partner (Merchant Client ID )
X-EXTERNAL-ID	String	Mandatory	Numeric string. Reference number that should be unique in the same day ( request-id)
CHANNEL-ID	String	Mandatory	channel ID for VA. Please fill with H2H (Host-To-Host)
Authorization	String	Mandatory	Bearer "access token" obtainedn from Get B2B Token API , refer to this Docs

Update Payment Code

Update Payment Code

PUThttps://{api-domain}/virtual-accounts/bi-snap-va/v1.1/transfer-va/update-va

Header parameters

Body

application/json

Update VA SNAP request

partnerServiceId*string

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

Example: " 1899"

customerNo*string

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

Example: "00000000000000000001"

virtualAccountNo*string

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

Example: " 189900000000000000000001"

virtualAccountNamestring

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

Example: "Customer Name"

virtualAccountEmailstring

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

Example: "[e-mail]"

virtualAccountPhonestring

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

Example: "0816291271826"

trxId*string

Invoice number in Partner system. | Mandatory | min length: 1 | max length: 64

Example: "23219829713"

totalAmountTotalAmountRef (object)

additionalInfo*AdditionalInfoUpdateVARequestRef (object)

virtualAccountTrxTypeVirtualAccountTrxTypeRef (string)

Transaction type for this transaction. C (Closed Amount), O (Open Amount) | Mandatory | min length: 1 | max length: 1

Example: "C"

expiredDatestring

Expiration date for Virtual Account. ISO-8601

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

Response

200400403404409500504

item created

Body

application/json

responseCode*string

Response Code with format HTTP status code + service code + case code. service code and status code refer to: https://developers.doku.com/getting-started-with-doku-api/error-handling/http-status-and-case-code#id-1.-virtual-account . | Mandatory | min length: 1 | max length: 7.

Example: "2002800"

responseMessage*string

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

Example: "Successful"

virtualAccountData*object

Request

JavaScriptCurlPython

const response = await fetch('https://{api-domain}/virtual-accounts/bi-snap-va/v1.1/transfer-va/update-va', {
    method: 'PUT',
    headers: {
      "X-TIMESTAMP": "2024-03-19T14:39:01+07:00",
      "X-SIGNATURE": "85be817c55b2c135157c7e89f52499bf0c25ad6eeebe04a986e8c862561b19a5",
      "X-PARTNER-ID": "BRN-0259-1678068334526",
      "X-EXTERNAL-ID": "418075533589",
      "CHANNEL-ID": "H2H",
      "Authorization": "Bearer eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjE2OTgwNTA3NDMsImlzcyI6IkRPS1UiLCJjbGllbnRJZCI6IkJSTi0wMjExLTE2OTY5MTk2NTE5MTgifQ.x-D5VlK6TlVZbLPUSCr-Gbfgh4tnp0QDJmedYFHJGHFjg1c4x39pszU4sLvRhr0Jk0vKdMIzxUZeNhKoesWqDJitnG3kfrNZNsMb_WYUC0tJW91onXzYOKXiTgsHwRNFoWPQHlXIEtT3RQm-SRlCpk_E0gsavgkQn2-kbJEBnPhIs4eKg5IUY9GYi4hRr-_GHsudDl8sd2B5UBB_rHYq36BRmLXH7i7MQADHPsB1ktPVgk3ZWF0jebEjI-lJ88p-omL1vQNvRseXej2HKBa9chGLmPDvXYBQaRmmstHz-tv1boFrHfwsHJebcUec-i3WE1vMvP_3EPXdbqb45N4ciQ",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "partnerServiceId": "    1899",
      "customerNo": "00000000000000000001",
      "trxId": "23219829713",
      "virtualAccountNo": "    189900000000000000000001",
      "additionalInfo": {
        "channel": "VIRTUAL_ACCOUNT_BANK_CIMB"
      }
    }),
});
const data = await response.json();

Response

200400403404409500504

{
  "responseCode": "2002800",
  "responseMessage": "Successful",
  "virtualAccountData": {
    "partnerServiceId": "    1899",
    "customerNo": "00000000000000000001",
    "virtualAccountNo": "    189900000000000000000001",
    "virtualAccountName": "Customer Name",
    "virtualAccountEmail": "[e-mail]",
    "virtualAccountPhone": "081293912081",
    "trxId": "23219829713",
    "totalAmount": {
      "value": "11500.00",
      "currency": "IDR"
    },
    "virtualAccountTrxType": "C",
    "expiredDate": "2023-01-01T10:55:00+07:00",
    "additionalInfo": {
      "channel": "VIRTUAL_ACCOUNT_BANK_CIMB",
      "virtualAccountConfig": {
        "status": "INACTIVE",
        "minAmount": "10000.00",
        "maxAmount": "5000000.00"
      }
    }
  }
}

---

2. Direct Inquiry

Type	Value
Service Code	24
HTTP Method	POST
API Endpoint Sandbox	https://api-sandbox.doku.com/.../
API Endpoint Production	https://api.doku.com/..../
Path	/virtual-accounts/bi-snap-va/v1.1/transfer-va/inquiry

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

1. Direct Inquiry

   a. Setup Inquiry URL on DOKU Dashboard

   b. Generate Payment Code on your End

   c. Receive Inquiry Request from DOKU

   d. Acknowledge Payment Notification

   e. Hit DOKU Check Status API

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

Direct Inquiry

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

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

b. Generate Payment Code on your end

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

c. Receive Inquiry Request from DOKU

Here is the sample request header, request body from DOKU

Request Header

Parameter	Type	Mandatory	Description
X- TIMESTAMP	String	Mandatory	Client's current local time in yyyy-MM-ddTHH:mm:ssZ format
X-SIGNATURE	String	Mandatory	Algorithm symmetric signature HMAC_SHA2512(clientSecret, stringToSign) Refer to this Docs
X-PARTNER-ID	String	Mandatory	Unique ID for a partner (Merchant Client ID )
X-EXTERNAL-ID	String	Mandatory	Numeric string. Reference number that should be unique in the same day ( request-id)
CHANNEL-ID	String	Mandatory	channel ID for VA. Please fill with H2H (Host-To-Host )
Authorization	String	Mandatory	Bearer "access token" obtainedn from Get B2B Token API , refer to this Docs

Direct Inquiry

Direct Inquiry

POSThttps://{merchant-domain}/v1.1/transfer-va/inquiry

Header parameters

Body

application/json

Direct Inquiry SNAP request

partnerServiceId*string

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

Example: " 1899"

customerNo*string

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

Example: "00000000000000000001"

virtualAccountNo*string

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

Example: " 189900000000000000000001"

channelCodestring

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

Example: "1"

trxDateInit*string

Transaction date. | Mandatory

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

languagestring

Language | min length: 1 | max length: 2

Example: "ID"

inquiryRequestId*string

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

Example: "12839218738127830"

additionalInfo*AdditionalInfoDirectInquiyVARequestRef (object)

Response

200400403404409500504

item created

Body

application/json

responseCode*string

Response Code with format HTTP status code + service code + case code. service code and status code refer to: https://developers.doku.com/getting-started-with-doku-api/error-handling/http-status-and-case-code#id-1.-virtual-account . | Mandatory | min length: 1 | max length: 7.

Example: "2002400"

responseMessage*string

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

Example: "Successful"

virtualAccountData*object

Request

JavaScriptCurlPython

const response = await fetch('https://{merchant-domain}/v1.1/transfer-va/inquiry', {
    method: 'POST',
    headers: {
      "X-TIMESTAMP": "2024-03-19T14:39:01+07:00",
      "X-SIGNATURE": "85be817c55b2c135157c7e89f52499bf0c25ad6eeebe04a986e8c862561b19a5",
      "X-PARTNER-ID": "BRN-0259-1678068334526",
      "X-EXTERNAL-ID": "418075533589",
      "CHANNEL-ID": "H2H",
      "Authorization": "Bearer eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjE2OTgwNTA3NDMsImlzcyI6IkRPS1UiLCJjbGllbnRJZCI6IkJSTi0wMjExLTE2OTY5MTk2NTE5MTgifQ.x-D5VlK6TlVZbLPUSCr-Gbfgh4tnp0QDJmedYFHJGHFjg1c4x39pszU4sLvRhr0Jk0vKdMIzxUZeNhKoesWqDJitnG3kfrNZNsMb_WYUC0tJW91onXzYOKXiTgsHwRNFoWPQHlXIEtT3RQm-SRlCpk_E0gsavgkQn2-kbJEBnPhIs4eKg5IUY9GYi4hRr-_GHsudDl8sd2B5UBB_rHYq36BRmLXH7i7MQADHPsB1ktPVgk3ZWF0jebEjI-lJ88p-omL1vQNvRseXej2HKBa9chGLmPDvXYBQaRmmstHz-tv1boFrHfwsHJebcUec-i3WE1vMvP_3EPXdbqb45N4ciQ",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "partnerServiceId": "    1899",
      "customerNo": "00000000000000000001",
      "virtualAccountNo": "    189900000000000000000001",
      "trxDateInit": "2023-01-01T10:55:00+07:00",
      "inquiryRequestId": "12839218738127830",
      "additionalInfo": {
        "channel": "VIRTUAL_ACCOUNT_BANK_CIMB"
      }
    }),
});
const data = await response.json();

Response

200400403404409500504

{
  "responseCode": "2002400",
  "responseMessage": "Successful",
  "virtualAccountData": {
    "partnerServiceId": "    1899",
    "customerNo": "00000000000000000001",
    "virtualAccountNo": "    189900000000000000000001",
    "virtualAccountName": "Customer Name",
    "virtualAccountEmail": "[e-mail]",
    "virtualAccountPhone": "081293912081",
    "totalAmount": {
      "value": "11500.00",
      "currency": "IDR"
    },
    "virtualAccountTrxType": "C",
    "expiredDate": "2023-01-01T10:55:00+07:00",
    "additionalInfo": {
      "channel": "VIRTUAL_ACCOUNT_BANK_CIMB",
      "trxId": "INV-001",
      "virtualAccountConfig": {
        "reusableStatus": false,
        "minAmount": "10000.00",
        "maxAmount": "5000000.00"
      }
    },
    "inquiryStatus": "00",
    "inquiryReason": {
      "english": "Success",
      "indonesia": "Sukses"
    },
    "inquiryRequestId": "12839218738127830",
    "freeText": [
      {
        "english": "Free text",
        "indonesia": "Tulisan Bebas"
      }
    ]
  }
}

d. Acknowledge payment notification

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 .

Payment Notification

Payment Notification

POSThttps://{merchant-domain}/v1.1/transfer-va/payment

Header parameters

Body

application/json

Payment Notification SNAP request

partnerServiceId*string

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

Example: " 1899"

customerNo*string

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

Example: "00000000000000000001"

virtualAccountNo*string

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

Example: " 189900000000000000000001"

virtualAccountName*string

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

Example: "Customer Name"

virtualAccountEmailstring

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

Example: "[e-mail]"

trxId*string

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

Example: "23219829713"

paymentRequestIdstring

Unique identifier generated by PJP. If Payment comes from the Inquiry process, this value must be the same with inquiryRequestId. | Mandatory | min length: 1 | max length: 30

Example: "12839218738127830"

paidAmount*TotalAmountRef (object)

virtualAccountPhonestring

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

Example: "081293912081"

additionalInfo*AdditionalInfoRequestRef (object)

trxDateTimestring

DOKU's transaction date time

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

virtualAccountTrxTypeVirtualAccountTrxTypeRef (string)

Transaction type for this transaction. C (Closed Amount), O (Open Amount) | Mandatory | min length: 1 | max length: 1

Example: "C"

Response

200400403404409500504

item created

Body

application/json

responseCode*string

Response Code with format HTTP status code + service code + case code. service code and status code refer to: https://developers.doku.com/getting-started-with-doku-api/error-handling/http-status-and-case-code#id-1.-virtual-account . | Mandatory | min length: 1 | max length: 7.

Example: "2002500"

responseMessage*string

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

Example: "Success"

virtualAccountData*object

Request

JavaScriptCurlPython

const response = await fetch('https://{merchant-domain}/v1.1/transfer-va/payment', {
    method: 'POST',
    headers: {
      "X-TIMESTAMP": "2024-03-19T14:39:01+07:00",
      "X-SIGNATURE": "85be817c55b2c135157c7e89f52499bf0c25ad6eeebe04a986e8c862561b19a5",
      "X-PARTNER-ID": "821508239190",
      "X-EXTERNAL-ID": "418075533589",
      "CHANNEL-ID": "H2H",
      "Authorization": "Bearer eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjE2OTgwNTA3NDMsImlzcyI6IkRPS1UiLCJjbGllbnRJZCI6IkJSTi0wMjExLTE2OTY5MTk2NTE5MTgifQ.x-D5VlK6TlVZbLPUSCr-Gbfgh4tnp0QDJmedYFHJGHFjg1c4x39pszU4sLvRhr0Jk0vKdMIzxUZeNhKoesWqDJitnG3kfrNZNsMb_WYUC0tJW91onXzYOKXiTgsHwRNFoWPQHlXIEtT3RQm-SRlCpk_E0gsavgkQn2-kbJEBnPhIs4eKg5IUY9GYi4hRr-_GHsudDl8sd2B5UBB_rHYq36BRmLXH7i7MQADHPsB1ktPVgk3ZWF0jebEjI-lJ88p-omL1vQNvRseXej2HKBa9chGLmPDvXYBQaRmmstHz-tv1boFrHfwsHJebcUec-i3WE1vMvP_3EPXdbqb45N4ciQ",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "partnerServiceId": "    1899",
      "customerNo": "00000000000000000001",
      "virtualAccountNo": "    189900000000000000000001",
      "virtualAccountName": "Customer Name",
      "trxId": "23219829713",
      "paidAmount": {
        "value": "11500.00",
        "currency": "IDR"
      },
      "additionalInfo": {
        "channel": "VIRTUAL_ACCOUNT_BANK_CIMB"
      }
    }),
});
const data = await response.json();

Response

200400403404409500504

{
  "responseCode": "2002500",
  "responseMessage": "Success",
  "virtualAccountData": {
    "partnerServiceId": "    1899",
    "customerNo": "00000000000000000001",
    "virtualAccountNo": "    189900000000000000000001",
    "virtualAccountName": "Customer Name",
    "virtualAccountEmail": "[e-mail]",
    "paymentRequestId": "12839218738127830",
    "paidAmount": {
      "value": "11500.00",
      "currency": "IDR"
    },
    "virtualAccountTrxType": "C",
    "additionalInfo": {
      "channel": "VIRTUAL_ACCOUNT_BANK_CIMB",
      "virtualAccountConfig": {
        "minAmount": "10000.00",
        "maxAmount": "5000000.00"
      }
    }
  }
}

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

---

Additional Feature

Open Amount

DOKU supports open payment meaning that your customer can input their own payment amount. To use open amount, you need to set virtualAccountTrxType = O and you need to send totalAmount.value = 0and totalAmount.currency = IDR DOKU. Here is the sample:

Create VA

{
    "partnerServiceId": "    1899",
        ...
    "totalAmount": {
        "value": "0",
        "currency": "IDR"
      },
      ...
    "virtualAccountTrxType": "O",
    ...
}

Direct Inquiry

{
  ...
  "virtualAccountData": {
    "partnerServiceId": "    1899",
    ...
    "totalAmount": {
      "value": "0",
      "currency": "IDR"
    },
    "virtualAccountTrxType": "O",
    "expiredDate": "2023-01-01T10:55:00+07:00",
    ...
    },
    ...
}

Limit Amount

DOKU supports limit amount payment meaning that your customer can input their own payment amount at the range that you defined. Limit amount only available when virtualAccountTrxType type is O and V.To use limit amount, you need to set virtualAccountConfig.minAmount >= 0 or virtualAccountConfig.maxAmount > 0 to DOKU.

Create VA

{
    "partnerServiceId": "    1899",
        ...
    "totalAmount": {
        "value": "0",
        "currency": "IDR"
      },
    "additionalInfo": {
        "channel" : "VIRTUAL_ACCOUNT_BANK_CIMB",
        "virtualAccountConfig" : {
            "minAmount" : "10000.00"
            "maxAmount" : "5000000.00"
            }
        },
    "virtualAccountTrxType": "O" / "V",
    ...
}

Direct Inquiry

{
  ...
  "virtualAccountData": {
    "partnerServiceId": "    1899",
    ...
    "totalAmount": {
      "value": "0",
      "currency": "IDR"
    },
    "additionalInfo": {
        "channel" : "VIRTUAL_ACCOUNT_BANK_CIMB",
        "virtualAccountConfig" : {
            "minAmount" : "10000.00"
            "maxAmount" : "5000000.00"
            }
        },
    "virtualAccountTrxType": "O" / "V",
    ...
    },
}

---