NICEPAY API
...
Payment API - SNAP
API Virtual Account SNAP

Registration - API Virtual Account SNAP

11min

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.

  1. 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.
  2. 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

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

Request message signature

(EIFYcRuFfFh8nkVhLZrkGKYfk36SDM8VvV3EW/OoKbkCspqMCiU/9ZhCiO29EjUEF0j7vjkQpSidvtIpt/BkLg ==)

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

Channel Identification with name of Merchant + 2 digits number (mid01)



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

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

Attribute

Description

responseCode

String



Mandatory

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

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