--- title: Registration - API Virtual Account SNAP slug: nicepay-api-snap-registration-virtual-account description: Informasi tentang Registration - API Virtual Account SNAP yang terdapat pada sistem NICEPAY image: https://archbee-image-uploads.s3.amazonaws.com/ZHvSjR5ZrsoxwKbJa3xmo/rg-CoeIHTDi7QXGJex4Pg_microsoftteams-image.png icon: {"faIcon":"fa-solid fa-book"} docTags: createdAt: 2023-02-17T10:53:04.000Z --- # Tentang Registration - API Virtual Account SNAP *** API dengan standar SNAP ini digunakan untuk mengajukan pendaftaran sebelum melakukan pembayaran menggunakan metode pembayaran Virtual Account. :::hint{type="info"} - Jika Anda ingin melihat penjelasan umum metode pembayaran Virtual Account, Anda dapat mengunjungi [Panduan Bayar VA](docId\:bSNUZMHNlj9h0wRndsQYj). - Untuk pengaturan integrasi fitur NICEPAY Inquiry Virtual Account, Anda dapat mengunjungi halaman [API NICEPAY Inquiry Virtual Account SNAP](docId\:W-Zwlzxm-p6FyqA3tqaDD). ::: ## Spesifikasi Panjang Nomor Virtual Account Seperti yang sudah jelaskan pada halaman [Struktur Virtual Account](docId:9tV3ro3_Lj1f-guZ2gark), 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. | **Nama Bank** | **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 | Catatan: - NICEPAY+Bank Prefix Length merupakan persyaratan panjang angka untuk nomor prefix NICEPAY dan Bank. :::hint{type="info"} **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: 1. **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. 2. **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. ::: :::hint{type="warning"} 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 *** :::hint{type="warning"} Silakan mengajukan akses token terlebih dahulu untuk melakukan autentikasi melalui bagian [Request Access Token API - SNAP](docId\:GcGqBIYXG1Etcd0Ji9cHX). ::: | **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](docId\:UZex33ReLyENKOgbJJnYp) | | | `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 :::hint{type="info"} 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](docId:9WOQy5-1hlf_uCwshSDHO) | | `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](docId\:lKqJXSl5CMKdXYXxHYYSs) | | `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](docId:9WOQy5-1hlf_uCwshSDHO) | | `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 :::CodeblockTabs cURL ```curl curl -X POST "https://dev.nicepay.co.id/nicepay/api/v1.0/transfer-va/create-va" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJJT05QQVlURVNUIiwiaXNzIjoiTklDRVBBWSIsIm5hbWUiOiJCUklOIiwiZXhwIjoiMjAyNC0wMi0xMVQwODowOTozNVoifQ==.aIybLX36dYwfFvW7dcoenXkOe2EAwIYq84ZtPuIf3K8=" \ -H "X-TIMESTAMP: 2024-04-30T10:11:40+07:00" \ -H "X-SIGNATURE: ufBw7R8RhW79IOiV/Hlv607M60qzAYBv8uZmbSrYb6/Thlo/FhQVP4xRyelUehoSS9o+QS6vWTKb/ygtucC+tQ==" \ -H "X-PARTNER-ID: IONPAYTEST" \ -H "X-EXTERNAL-ID: tXid202410142300021707638093" \ -H "CHANNEL-ID: IONPAYTEST" \ -d '{ "partnerServiceId": "", "customerNo": "", "virtualAccountNo": "", "virtualAccountName": "John Doe", "trxId": "2022020100000000000001", "totalAmount": { "value": "10000.00", "currency": "IDR" }, "additionalInfo": { "bankCd": "BMRI", "goodsNm": "John Doe", "dbProcessUrl": "https://testing.co.id/", "vacctValidDt": "", "vacctValidTm": "", "msId": "", "msFee": "", "msFeeType": "", "mbFee": "", "mbFeeType": "" } }' ``` Node.js ```nodejs const config = { isProduction: false, privateKey: cons.privateKey, clientSecret: cons.clientSecret, clientId: cons.clientId, isCloudServer: false, }; const parameter = { body: { partnerServiceId: "", customerNo: "", virtualAccountNo: "", virtualAccountName: "John Doe", trxId: "2022020100000000000001", totalAmount: { value: "10000.00", currency: "IDR", }, additionalInfo: { bankCd: "BMRI", goodsNm: "John Doe", dbProcessUrl: "https://testing.co.id/", vacctValidDt: "", vacctValidTm: "" }, }, headers: { X_EXTERNAL_ID: "tXid202410142300021707638093", CHANNEL_ID: "IONPAYTEST", }, }; let snap = new Snap(config); let endPoint = `/api/v1.0/transfer-va/create-va`; let response = snap.requestSnapTransaction(parameter, endPoint, accessToken, "POST"); ``` ```java config = NICEPay.builder() .isProduction(false) .clientSecret(DATA.CLIENT_SECRET) .partnerId(PARTNER_ID) .externalID(DATA.EXTERNAL_ID) .timestamp("2024-04-30T10:11:40+07:00") .privateKey(DATA.PRIVATE_KEY) .build(); var accessToken = Optional.ofNullable((NICEPayResponse) getToken()) .map(NICEPayResponse::getAccessToken) .orElseThrow(() -> new IllegalArgumentException("Token is null")); VirtualAccount virtualAccount = VirtualAccount.builder() .partnerServiceId("") .customerNo("") .virtualAccountNo("") .virtualAccountName("John Doe") .trxId("2022020100000000000001") .totalAmount("10000.00","IDR") .additionalInfo(new HashMap() { { put("bankCd","BMRI"); put("goodsNm", "John Doe"); put("dbProcessUrl", "https://testing.co.id/"); put("vacctValidDt", ""); put("vacctValidTm", ""); put("msId", ""); put("msFee", ""); put("msFeeType", ""); put("mbFee", ""); put("mbFeeType", ""); } }) .build(); NICEPayResponse response = SnapVaService.callGeneratedVA(virtualAccount, accessToken, config); ``` ```python 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 ) ``` C# ```csharp TestingConstantService config = new TestingConstantService(); string clientId = config.ClientId; string privateKey = config.PrivateKey; string timestamp = "2024-04-30T10:11:40+07:00"; string clientSecret = config.ClientSecret; string channelId = "IONPAYTEST"; string externalId = "tXid202410142300021707638093"; bool isProduction = false; bool isCloudServer = false; string accessToken = accessTokenObject.accessToken; ApiEndpoints apiEndpoints = new ApiEndpoints(); APIService vaService = new APIService(apiEndpoints, clientSecret, clientId, channelId, isProduction, isCloudServer); var bodyBuilder = new VirtualAccountBuilder() .SetVirtualAccountSnap( partnerServiceId: "", customerNo: "", virtualAccountNo: "", virtualAccountName: "John Doe", trxId: "2022020100000000000001", value: "10000.00", currency: "IDR", bankCd: "BMRI", goodsNm: "John Doe", dbProcessUrl: "https://testing.co.id/", vacctValidDt: "", vacctValidTm: "", msId: "", msFee: "", msFeeType: "", mbFee: "", mbFeeType: "" ).Build(); string createResponse = await vaService.SendPostRequest(apiEndpoints.CreateVA, accessToken, timestamp, bodyBuilder, externalId); ``` Laravel ```php protected $useProd = false; protected $useCloud = false; protected $create_va_endpoint = "/api/v1.0/transfer-va/create-va"; protected $client_id = "CLIENT_KEY_MERCHANT"; protected $key = "_PRIVATE_KEY_MERCHANT"; protected $client_secret = "_CLIENT_SECRET_MERCHANT"; protected $access_token = "_ACCESS_TOKEN_MERCHANT"; $url = HttpUtil::getNicepayDomain($this->useProd, $this->useCloud) . "/nicepay" . $this->create_va_endpoint; $helper = new Helpers(); $http_method = "POST"; $date = Carbon::now(); $x_time_stamp = $date->toIso8601String(); $time_stamp = $date->format("YmdHis"); $partner_id = $this->client_id; $client_secret = $this->client_secret; $access_token = $helper->generateAccessToken($this->client_id, $this->key); $external_id = "tXid202410142300021707638093"; $totalAmount = [ "value" => "15000.00", "currency" => "IDR" ]; $additionalInfo = [ "bankCd" => "CENA", "goodsNm" => "CENA", "dbProcessUrl" => "https://ptsv2.com/t/jhon/post", "vacctValidDt" => "", "vacctValidTm" => "", "msId" => "", "msFee" => "", "mbFee" => "", "mbFeeType" => "" ]; $body = [ "partnerServiceId" => "", "customerNo" => "", "virtualAccountNo" => "", "virtualAccountName" => "Testing Create Virtual Account Nicepay", "trxId" => "2022020100000000000001", "totalAmount" => $totalAmount, "additionalInfo" => $additionalInfo ]; $string_to_sign = $helper->generateStringToSign( $http_method, $this->create_va_endpoint, $access_token, $body, $x_time_stamp ); $signature = $helper->hmacSHA512Encoded( $string_to_sign, $client_secret, OPENSSL_ALGO_SHA512 ); $header = $helper->generateHeader( $access_token, $x_time_stamp, $signature, $partner_id, $external_id, $partner_id . "02" ); try { $response = HttpUtil::postJsonRequestWithHeader($url, $body, $header); } catch (\Exception $e) { echo "Request failed: " . $e->getMessage(); } ``` PHP Native ```php $timestamp = "2024-04-30T10:11:40+07:00"; $externalID = "tXid202410142300021707638093"; $config = NICEPay::builder() ->setIsProduction(false) ->setPrivateKey($this->oldKeyFormat) ->setClientSecret($this->clientSecret) ->setPartnerId($this->iMidTest) ->setExternalID($externalID) ->setTimestamp($timestamp) ->build(); $virtualAccountBuilder = VirtualAccount::builder(); $parameter = $virtualAccountBuilder ->setPartnerServiceId("") ->setCustomerNo("") ->setVirtualAccountNo("") ->setVirtualAccountName("John Doe") ->setTrxId("2022020100000000000001") ->setTotalAmount("10000.00", "IDR") ->setAdditionalInfo([ 'bankCd' => 'BMRI', 'goodsNm' => 'John Doe', 'dbProcessUrl' => 'https://testing.co.id/', 'vacctValidDt' => '', 'vacctValidTm' => '', 'msId' => '', 'msFee' => '', 'msFeeType' => '', 'mbFee' => '', 'mbFeeType' => '' ]) ->build(); $accessToken = self::getAccessToken($config); $snapVAService = new SnapVAService($config); $response = $snapVAService->generateVA($parameter, $accessToken); ``` ```kotlin val config: NICEPay = NICEPay.Builder() .isProduction(false) .clientSecret(TestingConstants.IONPAYTEST_CLIENT_SECRET) .partnerId("IONPAYTEST") .externalID("tXid202410142300021707638093") .timestamp("2024-04-30T10:11:40+07:00") .privateKey(TestingConstants.PRIVATE_KEY) .build() val accessToken = "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJJT05QQVlURVNUIiwiaXNzIjoiTklDRVBBWSIsIm5hbWUiOiJCUklOIiwiZXhwIjoiMjAyNC0wMi0xMVQwODowOTozNVoifQ==.aIybLX36dYwfFvW7dcoenXkOe2EAwIYq84ZtPuIf3K8=" val snapVirtualAccountService: SnapVirtualAccountService = SnapVirtualAccountServiceImpl() val virtualAccount = SnapVirtualAccount.Builder() .partnerServiceId("1234") .customerNo("") .virtualAccountNo("") .virtualAccountName("TESTVaName") .trxId(DEFAULT_REFERENCE_NO) .totalAmount(DEFAULT_AMOUNT, "IDR") .additionalInfo( mapOf( "bankCd" to "BRIN", "goodsNm" to "TESTGoodsNm", "dbProcessUrl" to "https://merchant.com/test", "vacctValidDt" to "", "vacctValidTm" to "", "msId" to "", "msFee" to "", "msFeeType" to "", "mbFee" to "", "mbFeeType" to "" ) ) .build() val response: NICEPayResponse? = snapVirtualAccountService.createVA(virtualAccount, accessToken, config) ``` CodeIgniter ```php $const = new NicepayTestConst(); $this->clientSecret = $const::IMID_TEST_CLIENT_SECRET; $this->oldKeyFormat = $const::IMID_TEST_PRIVATE_KEY; $this->iMidTest = $const::IMID_TEST; $this->merchantKey = $const::IMID_COMMON_MERCHANT_KEY; $timestamp = Helper::getFormattedDate(); $config = NICEPay::builder() ->setIsCloudServer(isCloudServer: true) ->setPrivateKey($this->oldKeyFormat) ->setClientSecret($this->clientSecret) ->setPartnerId($this->iMidTest) ->setExternalID("tXid202410142300021707638093") ->setTimestamp($timestamp) ->build(); $virtualAccountBuilder = VirtualAccount::builder(); $parameter = $virtualAccountBuilder ->setPartnerServiceId("") ->setCustomerNo("") ->setVirtualAccountNo("") ->setVirtualAccountName("Nicepay PHP Test") ->setTrxId("2022020100000000000001") ->setTotalAmount('10000.00', 'IDR') ->setAdditionalInfo([ 'bankCd' => 'BMRI', 'goodsNm' => 'Jhon Doe', 'dbProcessUrl' => 'https://dev.nicepay.co.id/IONPAY_CLIENT/paymentResult.jsp', ]) ->build(); $accessToken = self::getAccessToken($config); $snapVAService = new SnapVAService(); try { $response = $snapVAService->generateVA($parameter, $accessToken, $config); } catch (\Exception $e) { // Handle exception if needed } ``` ::: ## Response Parameter :::CodeblockTabs Sample Response ```json { "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" } } } ``` :::