Skip to main content

Virtual Account Direct Inquiry

Virtual Account Direct Inquiry adalah proses ketika bank melakukan permintaan informasi (inquiry) ke sistem merchant atau payment gateway secara real-time.

Hal ini terjadi saat nasabah bank memasukkan nomor Virtual Account di channel bank (ATM, mobile banking, internet banking). Sebelum menampilkan detail pembayaran, sistem bank akan melakukan Direct Inquiry ke host merchant/payment gateway untuk:

  • Mengecek apakah Virtual Account tersebut valid dan masih aktif.
  • Mengambil detail informasi seperti nama pemilik, deskripsi, dan nominal pembayaran (jika fixed amount).
  • Mendapatkan status apakah VA tersebut bisa digunakan untuk transaksi.

Flow Diagram Virtual Account Direct Inquiry​

Customer No Rule​

Bank ChannelMax Length Customer No
BNI_VA14
CIMB_VA6
PERMATA_VA6
BRI_VA7
MANDIRI_VA5

Signature​

Asymmetric​

Formula:

stringToSign = ClientKey + “|” + Timestamp
hash = SHA256withRSA(stringToSign, privateKey)
signature = Base64(hash)

Penjelasan formula stringToSign.

  1. ClientKey adalah client ID untuk kirimo yang digenerate-kan oleh merchant.
  2. Timestamp menggunakan ISO-8601.
  3. privateKey adalah kunci RSA yang Anda buat. Untuk mekanisme direct VA inquiry, kirimo akan memberikan public key untuk digunakan merchant saat process validasi signature.

Hash stringToSign menggunakan SHA256withRSA cryptographic dan secret key. Kemudian, encode dengan Base 64. Masukkan nilainya ke X-SIGNATURE.

Symmetric​

Formula:

stringToSign = HttpMethod + “:” + Endpoint + “:” + AccessToken + “:” + LowerCase(HexEncode(SHA-256(Minify(RequestBody)))) + “:” + Timestamp
hash = HMAC_SHA512(stringToSign, secretKey)
signature = Base64(hash)

Penjelasan formula stringToSign.

  1. HttpMethod adalah string nama metode yang sedang digunakan. Bisa saja POST, PUT, atau DELETE.

  2. Endpoint adalah relative URL atau full path URL yang mana tanpa host atau domainnya.

  3. AccessToken adalah nilai token yang didapatkan dari API Get Token.

  4. RequestBody adalah payload yang ingin Anda kirim.

  5. Timestamp menggunakan ISO-8601.

  6. secretKey akan digenerate-kan oleh merchant saat proses integrasi.

Hash stringToSign menggunakan HMAC_SHA512 cryptographic dan secret key. Kemudian, encode dengan Base 64. Masukkan nilainya ke X-SIGNATURE.

Get Token API​

  • Method: POST
  • Type: application/json
  • Development: https://yourdomain.com/v1.0/access-token/b2b
  • Service Code: 73

Header :

ParameterTipeMandatoriKeteranganContoh
Content-Typestring✓String yang menunjukkan jenis media.application/json
X-TIMESTAMPstring✓ISO-86012022-09-16T13:00:00+07:00
X-SIGNATUREstring✓Pemeriksaan Non-Repudiasi & Integritas X-Signature dengan algoritma asimetris.
X-CLIENT-KEYstring✓Client ID untuk kirimo yang digenerate-kan oleh merchant.DXXXX

body:

ParameterTipeMandatoriKeteranganContoh
grantTypestring✓The value is client_credentials"client_credentials"

response:

CodeMessageKeterangan
2007300SuccessfulBerhasil di proses dan mendapatkan accessToken.
4007301Invalid Field Format {grantType}Nilai value yang tidak tepat untuk parameter grantType.
4007302Invalid Mandatori Field {grantType}Parameter grantType tidak ada.
4007302Invalid Client Key or Timestamp or SignatureTerjadi kesalahan di antara Client Key, Timestamp atau Signature.
4017300Invalid Client KeyKekeliruan pada Client Key.
4017300Invalid SignatureKekeliruan pada Signature.

Inquiry Virtual Account​

  • Method: POST
  • Type: application/json
  • URL: https://yourdomain.com/v1.0/transfer-va/inquiry
  • Service Code: 24
ParameterTipeMandatoriKeteranganContoh
X-TIMESTAMPstring✓ISO-86012025-09-03T16:23:58+07:00
X-SIGNATUREstring✓Lihat Symmetric Signature Inquiry RequestdZuUi/OjZ21QrjRStx655lYdWtypdTK...
X-PARTNER-IDstring✓Partner ID yang digenerate-kan merchant untuk kirimo12345
X-EXTERNAL-IDstring(64)✓Request ID yang unik.1756891439401023433
CHANNEL-IDstring✓Channel transaksi12345
AUTHORIZATIONstring✓Bearer tokenBearer <token>

Body​

ParameterTipeMandatoriKeteranganContoh
partnerServiceIdstring✓Prefix dari Kirimo1899103003
customerNostring✓Nomor untuk VA1121123456722
virtualAccountNostring✓Nomor Virtual Account untuk dibayar18991121123456722
inquiryRequestIdstring✓ID Transaksi dari sisi merchant, unik setiap VA Number1756891438256771593
trxDateInitstring✗Waktu transaksi dalam format ISO-86012025-09-03T16:23:58+07:00
channelCodestring✗Kode channel6011
additionalInfoobject✓Informasi tambahanlihat tabel di bawah

additionalInfo​

ParameterTipeMandatoriKeteranganContoh
channelstring✓Channel transaksi VAVIRTUAL_ACCOUNT_BANK_CIMB

Response​

ParameterTipeMandatoriKeteranganContoh
responseCodestring✓Kode response, lihat bagian daftar Response Code di bawah2003600
responseMessagestring✓Penjelasan terhadap response code yang diterimaInquiry successful
virtualAccountDataobject✓Lihat tabel di bawah ini

virtualAccountData​

ParameterTipeMandatoriKeteranganContoh
inquiryStatusstring✓Status dari VA number00
• 00: Success
• 01: Initiated
• 02: Paying
• 03: Pending
• 04: Refunded
• 05: Canceled
• 06: Failed
• 07: Not found
inquiryReasonobject✓Alasan status inquirylihat tabel bawah
partnerServiceIdstring✓Prefix dari Kirimo1899
customerNostring✓Nomor untuk VA1121123456722
virtualAccountNostring✓Nomor Virtual Account untuk dibayar18991121123456722
virtualAccountNamestring✓Nama pemilik akunJohn Doe
virtualAccountEmailstring✓Email pemilik akunjohndoe@example.com
virtualAccountPhonestring✓Nomor telepon pemilik akun6281234567890
inquiryRequestIdstring✓ID InquiryDIPCVA011T25...
totalAmountobject✓Nominal pembayaran VAlihat tabel bawah
paymentFlagStatusstring✓Status pembayaran01
virtualAccountTrxTypestring✓Jenis transaksi (C/D)C
expiredDatestring✓Tanggal kedaluwarsa2025-08-20T...

inquiryReason​

ParameterTipeMandatoriKeteranganContoh
englishstring✓Pesan dalam bahasa InggrisValid account
indonesiastring✓Pesan dalam bahasa IndonesiaRekening valid

totalAmount​

ParameterTipeMandatoriKeteranganContoh
valuestring✓Nominal pembayaran dengan 2 desimal10000.00
currencystring✓Kode mata uang, hanya IDRIDR

Example Request​

{
  "partnerServiceId": "1899103003",
  "customerNo": "1121123456722",
  "virtualAccountNo": "    18991121123456722",
  "inquiryRequestId": "1756891438256771593",
  "trxDateInit": "2025-09-03T16:23:58+07:00",
  "channelCode": "6011",
  "additionalInfo": {
    "channel": "VIRTUAL_ACCOUNT_BANK_CIMB"
  }
}

Example Response​

{
  "responseCode": "2003600",
  "responseMessage": "Inquiry successful",
  "virtualAccountData": {
    "inquiryStatus": "00",
    "inquiryReason": {
      "english": "Valid account",
      "indonesia": "Rekening valid"
    },
    "partnerServiceId": "    1899",
    "customerNo": "1121123456722",
    "virtualAccountNo": "    18991121123456722",
    "virtualAccountName": "John Doe",
    "virtualAccountEmail": "johndoe@example.com",
    "virtualAccountPhone": "081234567890",
    "inquiryRequestId": "DIPCVA011T250819131202268TcCS1PXfuBb",
    "totalAmount": {
      "value": "10000.00",
      "currency": "IDR"
    },
    "paymentFlagStatus": "01",
    "virtualAccountTrxType": "C",
    "expiredDate": "2025-08-20T23:59:59+07:00"
  }
}

Payment VA​

  • Method: POST
  • Type: application/json
  • URL: https://yourdomain.com/v1.0/transfer-va/payment
  • Service Code: 25

Header​

ParameterTipeMandatoriKeteranganContoh
X-TIMESTAMPstring✓ISO-86012025-09-03T16:23:58+07:00
X-SIGNATUREstring✓Lihat Symmetric Signature Inquiry RequestdZuUi/OjZ21QrjRStx655lYdWtypdTK...
X-PARTNER-IDstring✓Partner ID yang digenerate-kan merchant untuk kirimo12345
X-EXTERNAL-IDstring(64)✓Request ID yang unik.1756891439401023433
CHANNEL-IDstring✓Channel transaksi12345
AUTHORIZATIONstring✓Bearer tokenBearer <token>

Body​

ParameterTipeMandatoriKeteranganContoh
partnerServiceIdstring✓Prefix dari Kirimo1899103003
customerNostring✓Nomor untuk VA1121123456722
virtualAccountNostring✓Nomor Virtual Account untuk dibayar18991121123456722
virtualAccountNamestring✓Nama pemilik akunJohn Doe
virtualAccountEmailstring✗Email pemilik akunjohndoe@example.com
virtualAccountPhonestring✗Nomor telepon pemilik akun081234567890
trxIdstring✓ID transaksi unik (dari bank / upstream)abc123
paymentRequestIdstring✓ID unik setiap pembayaran1755583922855...
channelCodestring✗Kode channel6011
hashedSourceAccountNostring✗Nomor rekening sumber dalam bentuk hash
sourceBankCodestring✗Kode bank sumber
paidAmountobject✓Nominal yang dibayarlihat tabel bawah
cumulativePaymentAmountnumber✗Jumlah kumulatif pembayarannull
paidBillsstring✗Informasi tagihan yang dibayar
totalAmountobject✓Total dari inquirylihat tabel bawah
trxDateTimestring✓Waktu transaksi dalam format ISO-86012025-09-04T09...
referenceNostring✗Nomor referensi transaksi dari bank175558392285557
journalNumstring✗Nomor jurnal
paymentTypestring✗Jenis pembayaran
flagAdvisestring✗Flag notifikasi adviseN
subCompanystring✗Sub company
billDetailsobject✗Detail tagihan (opsional)null
freeTextsobject✗Catatan tambahannull
additionalInfoobject✓Informasi tambahanlihat tabel bawah

totalAmount​

ParameterTipeMandatoriKeteranganContoh
valuestring✓Nominal pembayaran dengan 2 desimal10000.00
currencystring✓Kode mata uang, hanya IDRIDR

additionalInfo​

ParameterTipeMandatoriKeteranganContoh
channelstring✗Channel transaksi VAVIRTUAL_ACCOUNT_BANK_CIMB

Response​

ParameterTipeMandatoriKeteranganContoh
responseCodestring✓Kode response, lihat bagian daftar Response Code di bawah2003600
responseMessagestring✓Penjelasan terhadap response code yang diterimaSuccessful
virtualAccountDataobject✓Lihat tabel di bawah ini

virtualAccountData​

ParameterTipeMandatoriKeteranganContoh
partnerServiceIdstring✓Prefix dari Kirimo12345
customerNostring✓Nomor untuk VA1111
virtualAccountNostring✓Nomor Virtual Account untuk dibayar123456567
paymentRequestIdstring✓ID unik setiap pembayaran123
paidAmountobject✓Nominal pembayaranlihat bawah
virtualAccountNamestring✗Nama ditampilkan di sisi bankKirimo

Example Request​

{
  "partnerServiceId": "    1899103003",
  "customerNo": "1121123456722",
  "virtualAccountNo": "18991121123456722",
  "virtualAccountName": "John Doe",
  "virtualAccountEmail": "johndoe@example.com",
  "virtualAccountPhone": "081234567890",
  "trxId": "",
  "paymentRequestId": "1755583922855573699",
  "channelCode": 6011,
  "hashedSourceAccountNo": "",
  "sourceBankCode": "",
  "paidAmount": {
    "value": "10000.00",
    "currency": "IDR"
  },
  "cumulativePaymentAmount": null,
  "paidBills": "",
  "totalAmount": {
    "value": "10000.00",
    "currency": "IDR"
  },
  "trxDateTime": "2025-09-04T09:42:00+07:00",
  "referenceNo": "175558392285557",
  "journalNum": "",
  "paymentType": "",
  "flagAdvise": "N",
  "subCompany": "",
  "billDetails": null,
  "freeTexts": null,
  "additionalInfo": {
    "channel": "VIRTUAL_ACCOUNT_BANK_CIMB"
  }
}

Example Response​

{
  "responseCode": "2003600",
  "responseMessage": "Successful",
  "virtualAccountData": {
    "partnerServiceId": "12345",
    "customerNo": "1111",
    "virtualAccountNo": "123456567",
    "paymentRequestId": "123",
    "paidAmount": {
      "value": "10000.00",
      "currency": "IDR"
    },
    "virtualAccountName": "Kirimo"
  }
}