Registration - API Virtual Account SNAP

12 min

About Registration - API Virtual Account SNAP

This API with the SNAP standards uses to request registration before executing payment using the Virtual Account payment method.

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.

Virtual Account Length Number Specification

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 Name	NICEPAY + Bank Prefix Length	Max Total VA Length
Bank Central Asia (BCA)	8	23
Bank Rakyat Indonesia (BRI)	8	18
Bank Mandiri	8	19
Bank Maybank	8	16
Bank Nasional Indonesia (BNI)	7	16
Bank Permata	7	16
Bank Permata Syariah	7	16
Bank Commerce International Merchant Bankers (CIMB)	7	19
Bank Danamon	7	16
Bank KEB Hana	7	16
Bank Jabar Banten (BJB)	7	16
Bank Neo Commerce (BNC)	11	19
Bank Jakarta	9	16
Bank Syariah Indonesia (BSI)	8	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.

Registration - API Virtual Account SNAP

Please request the access token firsthand before doing the authentication through the Request Access Token API - SNAP section.

Service Code	27
API Endpoint	/api/v1.0/transfer-va/create-va
HTTP Method	POST
Description	To request the VA transaction process
Content-Type	application/json

Request Registration Header Parameter

Parameter	Type	Length	Required	Description	Example
Content-Type	String		Mandatory	Application / JSON
Authorization	String		Mandatory	Bearer “access_token”
X-TIMESTAMP	String		Mandatory	Using ISO 8601 as timestamp format. Transaction date time, in format YYYYMMDDTHH:mm:ss+07:00. Time must be in GMT+7 (Jakarta time). 2022-03-21T10:11:40+07:00.
X-SIGNATURE	String		Mandatory	Signature will be generated by Merchant. Panduan X-Signature - Symmetric
X-PARTNER-ID	String	20	Mandatory	X-PARTNER-ID = CLIENT_ID
X-EXTERNAL-ID	String	40	Mandatory	Unique Reference Number (41807553358950093184)
CHANNEL-ID	String		Mandatory	Unique Channel Merchant Credential ID Number. Client ID + "01" = Channel ID "IONPAYTEST" + "01" = "IONPAYTEST01"	IONPAYTEST01

Request Registration Body Parameter

For partnerServiceId and virtualAccountNo parameters can send with an empty value.

Parameter	Type	Length	Required	Description
partnerServiceId	String	20	Mandatory	Partner Service ID / Prefix
customerNo	String	40	Mandatory	Customer Number (Mandatory for Fix type)
virtualAccountNo	String	25	Mandatory	Virtual Account Number
virtualAccountName	String	100	Mandatory	Virtual Account Name
trxId	String	40	Mandatory	Transaction ID (Reference Number from Merchant)
totalAmount	Object		Optional	"totalAmount": { ... }
value	String	12	Mandatory	Transaction Amount
currency	String	3	Mandatory	Currency
additionalInfo	Object		Optional	"additionalInfo": { ... }
bankCd	String	4	Mandatory	Bank Code - API SNAP
goodsNm	String	200	Mandatory	Goods Name
dbProcessUrl	String		Mandatory	Notification URL
vacctValidDt	String	8	Optional	Virtual Account Valid Date
vacctValidTm	String	6	Optional	Virtual Account Valid Time
msId	String	20	Optional	Merchant Seller ID
msFee	String	7	Optional	Merchant Seller Fee
msFeeType	String	2	Optional	Merchant Seller Fee Type
mbFee	String	7	Optional	Merchant Balance Fee
mbFeeType	String	2	Optional	Merchant Balance Fee Type

Response Registration Parameter

Parameter	Type	Length	Required	Description
responseCode	String		Mandatory	General Response Code and Message - API SNAP
responseMessage	String		Mandatory	Response Message
virtualAccountData	Object		Mandatory	"virtualAccountData": { ..., "totalAmount": { ... } }
partnerServiceId	String	20	Conditional	Partner Service ID / Prefix (Mandatory for Fix type)
customerNo	String	40	Mandatory	Customer Number (Mandatory for Fix type)
virtualAccountNo	String	25	Mandatory	Virtual Account Number
virtualAccountName	String	100	Mandatory	Virtual Account Name
trxId	String	40	Mandatory	From Create VA Request (Reference Number from Merchant)
totalAmount	Object		Optional	"totalAmount": { ... }
value	String	12	Mandatory	Transaction Amount
currency	String	3	Mandatory	Currency
additionalInfo	Object		Optional	Optional "additionalInfo": { ... }
bankCd	String	4	Mandatory	Bank Code - API SNAP
tXidVa	String	30	Mandatory	Transaction ID of Virtual Account
goodsNm	String	200	Mandatory	Goods Name
vacctValidDt	String	8	Mandatory	Virtual Account Valid Date
vacctValidTm	String	6	Mandatory	Virtual Account Valid Time
msId	String	20	Optional	Merchant Seller ID
msFee	String	7	Optional	Merchant Seller Fee
msFeeType	String	2	Optional	Merchant Seller Fee Type
mbFee	String	7	Optional	Merchant Balance Fee
mbFeeType	String	2	Optional	Merchant Balance Fee Type

Sample Parameter for Registration API Virtual Account SNAP

Request Parameter

bodyCreateToken = (
    builderAccessToken.BuildAccessToken()
    .setGrantType("client_credentials")
    .setAdditionalInfo("")
    .build()
)

totalAmount = {
    "value": "10000.00",
    "currency": "IDR"
}

additionalInfo = {
    "bankCd": "BMRI",
    "goodsNm": "John Doe",
    "dbProcessUrl": "https://testing.co.id/",
    "vacctValidDt": "",
    "vacctValidTm": "",
    "msId": "",
    "msFee": "",
    "msFeeType": "",
    "mbFee": "",
    "mbFeeType": ""
}

bodyCreateVA = (
    builderVirtualAccount.BuildCreateVA()
    .setPartnerServiceId("")
    .setCustomerNo("")
    .setVirtualAccountNo("")
    .setVirtualAccountName("John Doe")
    .setTrxId("2022020100000000000001")
    .setTotalAmount(totalAmount)
    .setAdditionalInfo(additionalInfo)
    .build()
)

environment = (
    builderEnvironment.BuildEnvironment()
    .isCloud(False)
    .isProduction(False)
    .build()
)

result = SnapService.serviceTransaction(
    bodyCreateToken.jsonAccessToken(),
    bodyCreateVA.jsonVACreate(),
    ConstantsEndpoints.createVA(),
    environment
)

Response Parameter

{
    "responseCode": "2002700",
    "responseMessage": "Successful",
    "virtualAccountData": {
        "partnerServiceId": "",
        "customerNo": "",
        "virtualAccountNo": "70014000091733551548",
        "virtualAccountName": "Jhon Doe",
        "trxId": "2022020100000000000001",
        "totalAmount": {
            "value": "10000.00",
            "currency": "IDR"
        },
        "additionalInfo": {
            "msId": "",
            "msFee": "",
            "msFeeType": "",
            "mbFee": "",
            "mbFeeType": "",
            "bankCd": "BMRI",
            "tXidVA": "IONPAYTEST02202410141733551548",
            "goodsNm": "Jhon Doe",
            "vacctValidDt": "20241016",
            "vacctValidTm": "173355"
        }
    }
}

Registration - API Virtual Account SNAP

About Registration - API Virtual Account SNAP

Virtual Account Length Number Specification

Registration - API Virtual Account SNAP

Request Registration Header Parameter

Request Registration Body Parameter

Response Registration Parameter

Sample Parameter for Registration API Virtual Account SNAP

Request Parameter

Response Parameter

Welcome to NICEPAY DOCS