NICEPAY API
API Version 1 (V1)
V1 Professional
23 min
❕ this {{section}} contains reference of previous {{nicepay}} {{api}} version {{nicepay}} recommend {{merchant}} to use {{the}} newest {{api}} nicepay professional {{nicepay}} professional steps the {{customer}} registers {{the}} {{transaction}} {{nicepay}} redirects {{the}} {{customer}} to {{nicepay}} secure {{paymentproduct}} page finish {{the}} {{payment}} in {{nicepay}} secure {{paymentproduct}} page {{nicepay}} will redirect {{the}} {{customer}} to {{merchant}} callbackurl to give {{the}} {{payment}} {{information}} guide flow v1 professional steps description the {{customer}} sends a {{checkout}} request the {{customer}} sends card data to {{the}} {{merchant}} to create an {{order}} {{merchant}} sends {{the}} card data to {{nicepay}} {{nicepay}} will make {{paymentproduct}} page and txid {{nicepay}} sends {{the}} {{paymentproduct}} page and txid to {{the}} {{merchant}} the {{merchant}} receives {{the}} {{paymentproduct}} page and txid and then save txid into {{the}} database the {{customer}} will redirect to {{the}} {{paymentproduct}} page the {{customer}} visits {{nicepay}} {{paymentproduct}} page and inputs {{the}} {{transaction}} detail {{nicepay}} sends {{transaction}} detail to {{bank}} the {{bank}} sends {{transaction}} result {{nicepay}} receives {{transaction}} result the {{customer}} will view {{the}} {{paymentproduct}} result page {{nicepay}} sends a {{notification}} to {{merchant}} the {{merchant}} receives {{the}} {{notification}} and checks {{the}} {{payment}} {{status}} {{nicepay}} receives and sends {{the}} {{status}} response to {{the}} {{merchant}} the {{merchant}} receives {{the}} response {{status}} from {{nicepay}} the {{merchant}} updates {{the}} {{status}} into database the {{merchant}} sends {{the}} confirmation to {{the}} {{customer}} transaction registration registration api specifications api end point /nicepay/api/orderregist do request method application application /x www form urlencoded /x www form urlencoded post post description perform transaction registration merchant token sha256 ( imid + referenceno + amt + merchantkey) payment methods 01 {{cc}} 02 {{va}} 03 {{cvs}} 04 {{directdebit}} 05 {{ewallet}} 08 {{qris}} 09 {{gpn}} card registration api parameters sample api request // payment mandatory field nicepay setpaymethod("01"); nicepay setcurrency("idr"); nicepay setamt("1000"); nicepay setinstmntmon("1"); nicepay setreferenceno("merchantreferencenumber001"); nicepay setgoodsnm("merchant goods 1"); nicepay setbillingnm("john doe"); nicepay setbillingemail("buyer\@merchant com"); nicepay setbillingphone("081234567890"); nicepay setbillingaddr("billing address"); nicepay setbillingcity("jakarta"); nicepay setbillingstate("jakarta"); nicepay setbillingpostcd("12345"); nicepay setbillingcountry("indonesia"); nicepay setdeliverynm("john doe delivery"); nicepay setdeliveryphone("081234567890"); nicepay setdeliveryaddr("billing address "); nicepay setdeliverycity("jakarta"); nicepay setdeliverystate("jakarta"); nicepay setdeliverypostcd("12345"); nicepay setdeliverycountry("indonesia"); nicepay setcallbackurl("https //merchant com/api/callbackurl"); nicepay setdbprocessurl("https //merchant com/api/dbprocessurl/notif"); nicepay setvat("0"); nicepay setfee("0"); nicepay setnotaxamt("0"); nicepay setdescription("description"); nicepay setuserip("127 0 0 1"); nicepay shopid("nicepay"); nicepay setmerchanttoken(nicepay maketoken(nicepay getamt(), nicepay getreferenceno())); nicepay setcartdata("{}"); nicepay setinstmntmon("1"); nicepay setinstmnttype("1"); nicepay setreccuropt("0"); // payment optional field nicepay setreqdt("20160301"); nicepay setreqtm("135959"); nicepay setreqdomain("www merchant com"); nicepay setreqserverip("127 0 0 1"); nicepay setreqclientver("1 0"); nicepay setusersessionid("usersessionid"); nicepay setuseragent("mozilla"); nicepay setuserlanguage("en us"); nicepay setmerfixacctid("9999000000000001"); nicepay setvacctvaliddt("20160303"); nicepay setvacctvalidtm("135959"); nicepay setpaymentexpirydt("20160303"); nicepay setpaymentexpirytm("135959"); // payment request nicepay paypage(); // payment response system out println("response string " + nicepay getresponsestring()); // json in string format string resultcd = nicepay get("resultcd"); string resultmsg = nicepay get("resultmsg"); string txid= nicepay get("txid"); string requesturl= nicepay get("requesturl"); sample api response { "apitype" "m0", "txid" "ionpaytest01202002130920175001", "requestdate" "20200213092017", "responsedate" "20200213092017", "data" { "txid" "ionpaytest01202002130920175001", "resultcd" "0000", "resultmsg" "success", "requesturl" "https //dev nicepay co id/nicepay/api/orderinquiry do" } } parameter type size description example value imid required required an 10 {{merchant}} id ionpaytest merchanttoken required required an 255 {{merchant}} token 6cfccfc0046773c1b589d8e98f paymethod required required n 2 https //docs nicepay co id/api v1 professional en html#payment method 01 currency required required a 3 currency idr amt required required n 12 transaction amount 10000 cartdata required required json string 4000 transaction cart data https //docs nicepay co id/api v1 professional en html#cart data json referenceno required required ans 40 {{merchant}} order number merchantreferencenumber1 goodsnm required required an 100 goods name {{merchant}} goods 1 callbackurl required required ans 255 {{paymentproduct}} result page url https //merchant com/callbackurl dbprocessurl required required ans 255 push notification url https //merchant com/dbprocessurl userip required required an 15 user ip address 127 0 0 1 description required required an 100 transaction description this is test order billingnm required required a 30 billing name buyer name billingphone required required n 15 billing phone number 2123456789 billingemail required required ans 40 billing e mail buyer\@merchant com billingcity required required a 50 billing city jakarta utara billingstate required required a 50 billing state dki jakarta billingpostcd required required a 10 billing postcode 10160 billingcountry required required a 10 billing country {{indonesia}} billingaddr an 100 billing address billing address merfixacctid required for fix type va required for fix type va n 40 {{merchant}} fix va number 14015824 instmnttype required for cc required for cc n 2 https //docs nicepay co id/api v1 professional en html#installment type 1 instmntmon required required for cc n 2 installment month 1 deliverynm a 30 delivery name delivery name deliveryphone n 15 delivery phone number 2123456789 deliveryaddr an 100 delivery address delivery address deliverycity a 50 delivery city jakarta utara deliverystate a 50 delivery state dki jakarta deliverypostcd n 10 delivery postcode 10160 deliverycountry a 10 delivery country {{indonesia}} vat n 12 vat number 0 fee n 12 service fee 0 notaxamt n 12 tax free amount 0 reqdt n 8 request date 20180303 reqtm n 6 request time 135959 reqdomain ans 100 request domain merchant com reqserverip ans 15 request server ip address 127 0 0 1 reqclientver an 50 request client version 1 usersessionid an 100 user session id usersessionid useragent required for cc required for cc ans 100 user agent information mozilla userlanguage ans 2 user language en us worker an 10 worker worker vacctvaliddt n 8 {{va}} valid date ( yyyymmdd ) 20180404 vacctvalidtm n 6 {{va}} valid time ( hh24miss ) 235959 paymentexpdt n 8 {{paymentproduct}} expired date ( yyyymmdd ) 20180404 paymentexptm n 6 {{paymentproduct}} expired time ( hh24miss ) 235959 payvaliddt n 8 cvs valid date ( yyyymmdd ) 20180404 payvalidtm n 6 cvs valid time ( hh24miss ) 235959 mrefno n 18 {{bank}} reference number bankcd123456789 timestamp n 14 timestamp ( yyyymmddhh24miss ) 20180404165639 mitracd a 4 https //docs nicepay co id/api v1 professional en html#mitra code eshp version an version {{nicepay}} lite shopid required for qris required for qris an 32 shop id {{nicepay}} note for jenius {{please}} use imid tnicecp041 and paymethod 04 then request to staging for developmental purposes cart data api v1 { "count" "2", "item" \[ { "img url" "http //img aaa com/ima1 jpg", "goods name" "item 1 name", "goods detail" "item 1 detail", "goods amt" "700" }, { "img url" "http //img aaa com/ima2 jpg", "goods name" "item 2 name", "goods detail" "item 2 detail", "goods amt" "300" } ] } parameter description count total cart data count item item > img url good's image url (50x50 size) item > goods name good's name item > goods detail good's description item > goods amt good's amount after {{the}} {{transaction}} registers successfully, don't forget to redirect your client to {{nicepay}} {{paymentproduct}} {{page}} nicepay secure payment page payment method selection when {{the}} {{customer}} click {{the}} change {{button}} , they can see {{the}} {{page}} above and change their preferred {{paymethod}} note for shopeepay {{ewallet}} in order to better user experience to {{the}} {{customer}} , please request give a warning message to {{the}} {{customer}} so they will open their mobile device payment method qris option confirm {{the}} {{payment}} after {{the}} {{customer}} open {{the}} {{ewallet}} application and scan {{the}} qr code then click process {{nicepay}} will redirect end user to {{merchant}} callbackurl to give {{the}} {{payment}} {{information}} payment method jenius option after {{the}} {{customer}} choose jenius and click process {{button}} , then input cashtag id after that confirmation, {{payment}} can be done via jenius application transaction payment payment api specifications api endpoint /nicepay/api/orderinquiry do request method application application /x www form urlencoded /x www form urlencoded post post description url redirect to {{nicepay}} {{paymentproduct}} page payment parameters url https //www nicepay co id/nicepay/api/orderinquiry do?txid=ionpaytest01201608291733081257\&optdisplaycb=0\&optdisplaybl=0 sample api request if (nicepay get("resultcd") equals("0000")) { string site = nicepay get("requesturl") + "\&optdisplaycb=0" + "\&optdisplaybl=0"; response setstatus(response sc moved temporarily); response setheader("location", site); } parameter type size description example value txid required required an 30 transaction id ionpaytest02201607291027025291 optdisplaycb n 2 display change {{button}} show = 0 hide = 1 optdisplaybl n 2 display back link show = 0 hide = 1 to prevent your client changing {{the}} {{paymethod}} , set optdisplaycb = 1 payment response parameters sample response to callbackurl with parameter https //merchant com/result?resultcd=0000\&resultmsg=success\&bankvacctno=44779000090927472371\&txid=ionpaytest02202011050927472371\&referenceno=order%2020201105091192\&transdt=20201105\&transtm=092747\&amount=150000\&bankcd=cena\&description=payment+of+referenceno+order+20201105091192 note {{paymentproduct}} response parameter will be sent through callbackurl using url string query parameter type size description example / notes resultcd n 4 docid logd 07e0vrfugu0nldf 0000 resultmsg an 255 docid logd 07e0vrfugu0nldf success txid an 30 {{nicepay}} trans id ionpaytest 02201607291027025291 when success referenceno ans 40 {{merchant}} order no ordno20160525000 when success authno n 10 {{bank}} auth no 123456 when success (cc) amount n 12 amount 1000 when success transdt n 8 transaction date 20200303 when success transtm n 6 transaction time 135959 when success description an 100 transaction description {{paym}} of ordno20160525000 when success bankvacctno n 20 {{va}} number 123457891011 when success (va) bankcd a 4 docid logd 07e0vrfugu0nldf bmri when success (va) reccuring token when {{the}} {{merchant}} signs contract as a recurring {{merchant}} , {{nicepay}} give a recurringtoken to {{the}} {{paymentproduct}} {{api}} response api endpoint /nicepay/api/recurringtoken do request method application application /x www form urlencoded /x www form urlencoded post post description request {{cc}} one time use transaction token recurringtoken do is almost same onepasstoken do the difference is whether using card info or using recurringtoken merchant token sha256 ( merchant id + reference number + amount + merchant key ) request parameter for token parameter type size description remark amt n 12 amount 10000 referenceno an 40 {{merchant}} order no 20220623095906 merchanttoken an 255 {{paymentproduct}} amount 141fd2368aa80ea0e600b1b4d7a42c1e731e74a27a03521e8e28150cc00bc05b imid an 10 {{merchant}} id bmritest01 recurringtoken an 100 recurring token d4ef98b26f917a697691807cf737251cc15ef570a01457d15211a4f06e38ae64 instmnttype an 2 docid logd 07e0vrfugu0nldf instmntmon n 2 installment month 1 response parameter for token parameter type size description remark resultcd n 4 docid logd 07e0vrfugu0nldf 0000 resultmsg an 255 docid logd 07e0vrfugu0nldf success cardtoken an 64 one time use {{transaction}} token c954f03ef83a363f94fa26bef6ec4d08fa7693590a735386fcce6e2ef1caae8a paymenttype an 1 docid logd 07e0vrfugu0nldf 1 3ds 2 keyin when callback to your callbackurl is received, we strongly recommend {{merchant}} s to verify {{the}} status by using inquiry {{api}}