Registration - API Virtual Account SNAP

11min

Tentang Registration - API Virtual Account SNAP
﻿
API dengan standar SNAP ini digunakan untuk mengajukan pendaftaran sebelum melakukan pembayaran menggunakan metode pembayaran Virtual Account.
Jika Anda ingin melihat penjelasan umum metode pembayaran Virtual Account, Anda dapat mengunjungi Panduan Bayar VA﻿.
Untuk pengaturan integrasi fitur NICEPAY Inquiry Virtual Account, Anda dapat mengunjungi halaman API NICEPAY Inquiry Virtual Account SNAP﻿.
﻿
Spesifikasi Panjang Nomor Virtual Account
Seperti yang sudah jelaskan pada halaman Struktur Virtual Account﻿, panjang dari nomor VA yang dapat dibuat berbeda-beda pada setiap Bank.
Panjang nomor VA dapat ditentukan sendiri sesuai dengan kebutuhan bisnis selama nomor VA tersebut tidak melebihi kapasitas panjang maksimum yang sudah termasuk dengan angka prefix Bank dan prefix NICEPAY. Berikut adalah tabel persyaratan panjang nomor VA untuk beberapa Bank.
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
Catatan:
NICEPAY+Bank Prefix Length merupakan persyaratan panjang angka untuk nomor prefix NICEPAY dan Bank.
Contoh Kasus:
Apabila Anda sebagai Merchant ingin melakukan integrasi dengan VA Bank Mandiri, maka Anda wajib untuk memberikan ruang sebesar 8 digit untuk prefix VA yang terdiri dari prefix Bank dan prefix NICEPAY. 
Selanjutnya, angka setelah prefix akan terbagi menjadi 2 tipe sesuai dengan tipe VA yang ingin buat: 
Fixed VA: Anda dapat melakukan kustomisasi angka setelah angka prefix VA yang NICEPAY sebut sebagai customer id atau merFixAcctId  dengan catatan bahwa angka tersebut tidak lebih dari 19 digit panjang maksimal untuk nomor VA dari Bank Mandiri.
Normal VA: Anda tidak dapat melakukan kustomisasi angka setelah angka prefix VA karena angka tersebut akan melalui proses generate secara otomatis dan acak oleh sistem dengan catatan bahwa angka tersebut tidak lebih dari 19 digit  panjang maksimal untuk nomor VA dari Bank Mandiri.
Panjang nomor VA secara default adalah 16 digit. Kecuali ada skema khusus dari Bank, NICEPAY, dan Merchant.

Meskipun setiap Bank dapat memiliki panjang nomor VA yang berbeda, Merchant disarankan untuk dapat mengakomodasi panjang nomor VA dalam satu deret maksimum 30 digit.
﻿
Registration - API Virtual Account SNAP
﻿
Silakan mengajukan akses token terlebih dahulu untuk melakukan autentikasi melalui bagian Request Access Token API - SNAP﻿.
Service Code
27
API Endpoint
/api/v1.0/transfer-va/create-va
HTTP Method
POST
Description
Untuk mengajukan pendaftaran transaksi VA
Content-Type
application/json
﻿
Request Registration Header Parameter
Parameter
Tipe
Ukuran
Kebutuhan
Deskripsi
Contoh
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
20
Mandatory
Unique Channel Merchant Credential ID Number.
Client ID + "01" =  Channel ID 
"IONPAYTEST" + "01" = "IONPAYTEST01" 
IONPAYTEST01
﻿
Request Registration Body Parameter
Untuk parameter partnerServiceId dan virtualAccountNo dapat dikirim dengan nilai kosong.
Parameter
Tipe
Ukuran
Kebutuhan
Deskripsi
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
Tipe
Ukuran
Kebutuhan
Deskripsi
responseCode
String
﻿
Mandatory
﻿General Response Code and Message - API SNAP﻿﻿
responseMessage
String
﻿
Mandatory
Response Message
virtualAccountData
Object
﻿
Mandatory
"virtualAccountData": {
    ...,
    "totalAmount": {
     ...
    }
  }
partnerServiceId
String
20
Mandatory
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
"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	Untuk mengajukan pendaftaran transaksi VA
Content-Type	application/json

Parameter	Tipe	Ukuran	Kebutuhan	Deskripsi	Contoh
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	20	Mandatory	Unique Channel Merchant Credential ID Number. Client ID + "01" = Channel ID "IONPAYTEST" + "01" = "IONPAYTEST01"	IONPAYTEST01

Parameter	Tipe	Ukuran	Kebutuhan	Deskripsi
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	Tipe	Ukuran	Kebutuhan	Deskripsi
responseCode	String		Mandatory	General Response Code and Message - API SNAP
responseMessage	String		Mandatory	Response Message
virtualAccountData	Object		Mandatory	"virtualAccountData": { ..., "totalAmount": { ... } }
partnerServiceId	String	20	Mandatory	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	"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

Tentang Registration - API Virtual Account SNAP

Spesifikasi Panjang Nomor Virtual Account

Registration - API Virtual Account SNAP

Request Registration Header Parameter

Request Registration Body Parameter

Response Registration Parameter

Sample Parameter

Selamat Datang di NICEPAY DOCS