Registration - API Virtual Account SNAP

11 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
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.
﻿
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
Sample Request
Sample Response
{
    "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"
        }
    }
}
{
    "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"
        }
    }
}
﻿
﻿

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

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

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

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

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

API Virtual Account SNAP

Notification - API Virtual Account SNAP

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

Welcome to NICEPAY DOCS