Registration - API Virtual Account
Virtual Account is one of the payment methods offered at NICEPAY. Customers have more payment options via ATM, SMS Banking, Internet Banking, and Mobile Banking using this method. There are real-time notifications that are sent automatically to the Customer as soon as the Customer completes the payment.
- If you want to see a general explanation of virtual account payment methods, you can visit VA Payment Guide.
- For integration settings for Fix Open and NICEPAY Inquiry Virtual Account features, you can visit the page Virtual Account - Advance API.
As explained on the Virtual Account Structure, the length of the VA number that can be created varies from each Bank.
The length of the VA can be determined according to business needs as long as the VA number does not exceed the maximum length capacity that includes the NICEPAY and Bank prefix. The following is a table of requirements for VA length number for some Banks.
Bank | NICEPAY + Bank Prefix Length | Max Total VA |
BCA | 8 | 23 |
BRI | 8 | 18 |
Mandiri | 8 | 19 |
Maybank | 8 | 16 |
BNI | 7 | 16 |
Permata & Syariah | 7 | 16 |
CIMB | 7 | 19 |
Danamon | 7 | 16 |
HANA | 7 | 16 |
BJB | 7 | 16 |
BNC | 11 | 19 |
DKI | 9 | 16 |
Note:
- NICEPAY+Bank Prefix Length is the number length requirement for NICEPAY and Bank prefix numbers.
A Case Study:
If you as a Merchant want to integrate Mandiri Bank VA, then you are required to provide a space of 8 digits for the VA prefix which consists of the NICEPAY and Bank prefix.
Later, the number after the prefix will be divided into 2 types according to the type of VA you want to create.
- Fixed VA: You can customize the number after the VA prefix number that NICEPAY refers to as the customer id or merFixAcctId with a note that the number is no longer than the maximum 19 digits length for VA numbers from Bank Mandiri.
- Normal VA: You cannot customize the number after the VA prefix number because that number will be generated automatically and randomly by the system with a note that the number is no longer than the maximum 19 digits length for VA numbers from Bank Mandiri.
The default length of VA number is 16 digits. Unless there are a special schemes from Banks, NICEPAY, and Merchants.
Although each Bank may have different length of the VA number, Merchants are considered to be able to accommodate a VA number lengths maximum of 30 digits in a row.
Virtual Account Registration aims so that the Merchant can connect to a virtual account payment system with a system from NICEPAY. So, the payment system that has to provide and hosted from the Merchant side can integrate with the system from NICEPAY.
API Endpoint | /nicepay/direct/v2/registration |
Request Method | POST |
Description | Performs Transaction Regist to NICEPAY |
Merchant Token | SHA256(timeStamp+iMid+referenceNo+amt+merchantKey) |
Request Format | application/json |
The following is a list of parameters for requesting registration of the Virtual Account payment method. This parameter is used through the API testing platform as one of the stages so that the merchant's system can connect with services from NICEPAY.
Parameter | Type | Size | Description | Example / Notes |
timeStamp Required | N | 14 | Request Timestamp (YYYYMMDDHH24MISS) | 20221214151286 |
iMid Required | AN | 10 | Merchant ID | NORMALTEST |
payMethod Required | N | 2 | 02 | |
currency Required | A | 3 | Currency | IDR |
amt Required | N | 12 | Amount | 10000 |
referenceNo Required | ANS | 40 | Merchant's RefNo. | ordNo20221214151286 |
goodsNm Required | AN | 100 | Goods Name | Goods For Testing Virtual Account |
billingNm Required | A | 100 | Buyer Name | John Doe |
billingPhone Required | N | 15 | Buyer Phone No. | 081288998899 |
billingEmail Required | ANS | 40 | Buyer E-mail | |
billingAddr Required | AN | 100 | Buyer Address | Jln. Raya Kasablanka Kav.88 |
billingCity Required | A | 50 | Buyer City | South Jakarta |
billingState Required | A | 50 | Billing State | DKI Jakarta |
billingPostCd Required | N | 10 | Billing Post Number | 12800 |
billingCountry Required | A | 10 | Billing Country | Indonesia |
cartData | JSONstring | 4000 | Cart Data | {} |
bankCd Required for VA | A | 4 | | CENA |
vacctValidDt Required | N | 8 | VA Expiry Date (YYYYMMDD) | 20221231 |
vacctValidTm Required | N | 6 | VA Expiry Time (HH24MISS) | 235959 |
merFixAcctId Required | AN | 40 | Merchant Reserved VA ID | - |
userIP Required for CC, E-Wallet, Payloan,QRIS | AN | 15 | User IP | 127.0.0.1 |
dbProcessUrl Required | ANS | 255 | Notification URL | https://ptsv2.com/t/merchant/post/ |
merchantToken Required | AN | 255 | Merchant Token | c94d31f554faea1c5f28617dd0a9de70fcb4dc8de55a343bb887d032d95dd60a |
deliveryNm | A | 30 | Delivery Name | |
deliveryPhone | N | 15 | Delivery Phone | 081288998899 |
deliveryAddr | AN | 100 | Delviery Address | Jln. Raya Kasablanka Kav.88 |
deliveryCity | A | 50 | Delivery City | South Jakarta |
deliveryState | A | 50 | Delivery State | DKI Jakarta |
deliveryPostCd | N | 10 | Delivery Post Code | 12800 |
deliveryCountry | A | 10 | Delivery Country | Indonesia |
description | AN | 100 | Transaction Description | Testing Registration Virtual Account |
reqDomain | ANS | 100 | Request Domain | merchant.com |
reqServerIP | ANS | 15 | Request Server IP | 127.0.0.1 |
userSessionID | AN | 100 | User Session ID | 697D6922C961070967D3BA1BA5699C2C |
userAgent | ANS | 100 | User Agent | Mozilla |
userLanguage | A | 2 | User Language | en-US |
Please visit Virtual Account (VA) section to learn general information about Virtual Account payment methods. The parameters below contain additional information regarding Virtual Account Registration information.
The following is a parameter response from the request parameter results to register the Virtual Account payment method.
Parameter | Type | Size | Description | Example / Notes |
resultCd | N | 14 | Result Code | 0000 |
resultMsg | AN | 255 | Result Message: Error Code | SUCCESS |
tXid | AN | 30 | Transaction ID | NORMALTEST02202212141509411648 |
referenceNo | ANS | 40 | Merchant Ref No | ordNo20221214151286 |
payMethod | N | 2 | 02 | |
amt | N | 12 | Payment Amount | 1000 |
transDt | N | 8 | Transaction Date (YYYYMMDD) | 20221214 |
transTm | N | 6 | Transaction Time (HH24MISS) | 150941 |
description | AN | 100 | Description | Testing Registration Virtual Account |
bankCd | AN | 4 | CENA | |
vacctNo | N | 20 | VA Number | 9912304000001486 |
mitraCd | AN | 4 | null | |
payNo | N | 12 | Payment Number | null |
currency | AN | 3 | Currency | IDR |
goodsNm | AN | 100 | Goods Name | Goods For Testing Virtual Account |
billingNm | A | 100 | Buyer Name | John Doe |
vacctValidDt | N | 8 | VA Expiry Date (YYYYMMDD) | 20221231 |
vacctValidTm | N | 6 | VA Expiry Time (HH24MISS) | 235959 |
payValidDt | N | 8 | Expiry Date (YYYYMMDD) | null |
payValidTm | N | 6 | Expiry Time (HH24MISS) | null |
requestURL | ANS | 360 | Request URL | null |
paymentExpDt | N | 8 | QR Payment Expiry Date (YYYYMMDD) | null |
paymentExpTm | N | 6 | QR Payment Expiry Time (HH24MISS) | null |
qrContent | ANS | 360 | QR String in Plain Text | null |
qrUrl | ANS | 360 | URL for QR Image, Valid for 5 minutes | null |