Registration - API Checkout

20 min

About Registration - API Checkout

The purpose of this step on Registration - API Checkout is to register a checkout request from your Customer to us. So that your Customer can pay the transaction amount billed on the payment page provided by NICEPAY .

Based on the principle, all payment methods on the Checkout API have the same process. The difference is just the parameter on each payment method.

When the Customer proceeds with the Checkout process, the system proceeds the order registration firsthand before the Customer can do the payment process on the chosen payment method through the received payment link.

Please visit the Payment - API Checkout page to know further explanations related API specific for payment.

Registration - API Checkout (All Payment Method)

To be able uses all payment methods on Checkout API, you are required to register the transaction with this Checkout Registration API. Here are the parameters:

API URL	/nicepay/redirect/v2/registration
Request Method	POST
Header	Content-Type: application/json
Merchant Token	SHA256 (timestamp+ iMid+ referenceNo+ amt+ merchantKey)

Request Parameter for Registration - API Checkout

Parameter	Type	Size	Description	Remark
iMid Required	AN	10	Merchant ID	IONPAYTEST
timeStamp Required	N	14	Request Timestamp (YYYYMMDDHH24MISS)	20230516660517
payMethod Required	N	2	Payment Method Code	00
bankCd Optional for VA	A	4	Bank Code	CENA
currency Required	AN	3	Currency	IDR
amt Required	N	12	Transaction Amount	10000
referenceNo Required	ANS	40	Merchant Order Number	MerchantReferenceNumber001
merchantToken Required	AN	255	Merchant Token	4686062c297a3e48cf385953f411bbd48753bb70b041f2113a3e7c2e99c54f3c
callBackUrl Required	AN	255	Payment Result Forward URL	https://www.merchant.com/callbackUrl/
dbProcessUrl Required	AN	255	Payment Notification URL	https://www.merchant.com/dbProcessUrl
goodsNm Required	AN	100	Goods Name	Merchant Goods 1
mitraCd Optional For CVS, Direct Debit, E-Wallet & Paylater	AN	4	Mitra Code	DANA
vacctValidDt Required For VA	N	8	VA Expiry Date (YYYYMMDD)	20230531
vacctValidTm Required For VA	N	8	VA Expiry Time (HH24MISS)	235959
description Required	AN	100	Transaction Description	This Is The Description Of The Payment
billingNm Required	A	100	Billing Name	John Doe
billingPhone Required	N	15	Billing Phone	08123456789
billingEmail Required	AN	40	Billing E-mail	[email protected]
billingAddr	AN	100	Billing Address	Jln. Raya Casablanka Kav.88
billingCity Required	A	50	Billing City	South Jakarta
billingState Required	A	50	Billing State	DKI Jakarta
billingPostCd Required	N	10	Billing Post Number	10200
billingCountry Required	A	10	Billing Country	Indonesia
userIP	AN	15	User IP	127.0.0.1
cartData Required	AN	4000	Cart Data	{\"count\":\"1\",\"item\":[{\"goods_id\":\"BB12345678\",\"goods_detail\":\"BB123456\",\"goods_name\":\"iPhone5S\",\"goods_amt\":\"10000\",\"goods_type\":\"Smartphone\",\"goods_url\":\"http://merchant.com/cellphones/iphone5s_64g\",\"goods_quantity\":\"1\",\"goods_sellers_id\":\"SEL123\",\"goods_sellers_name\":\"Sellers1\"}]}
deliveryNm	A	30	Delivery Name	Merchant's Name
deliveryPhone	N	15	Delivery Phone	08123456789
deliveryAddr	AN	100	Delivery Address	Jln. Dr. Saharjo No.88
deliveryCity	A	50	Delivery City	South Jakarta
deliveryState	A	50	Delivery State	DKI Jakarta
deliveryPostCd	N	10	Delivery Post Number	10201
deliveryCountry	A	10	Delivery Country	Indonesia
vat	N	12	Value Added Tax (VAT)
fee	N	12	Service Fee
notaxAmt	N	12	Tax Free Amount
reqDt	N	8	Request Date (YYYYMMDD)
reqTm	N	6	Request Time (HH24MISS)
reqDomain	AN	100	Request Domain	merchant.com
reqServerIP	AN	15	Request Server IP	127.0.0.1
reqClientVer	AN	50	Request Client Version
userSessionID	AN	100	User Session ID
userAgent	AN	100	User Agent Information
userLanguage	A	2	User Language
sellers Required For Paylater	JSON String	4000	Seller Data	[{"sellersId": "SEL123","sellersNm": "Sellers 1","sellersEmail":"[email protected]","sellersAddress": {"sellerNm": "Sellers","sellerLastNm": "1","sellerAddr": "jalan berbangsa 1","sellerCity":"Jakarta Barat","sellerPostCd": "12344","sellerPhone":"08123456789","sellerCountry": "ID"}}]
instmntType Required For CC & Paylater	N	2	Installment Type Code	1 (For Pre-Auth & Recurring default 1)
instmntMon Required For CC & Paylater	N	2	Installment Month 1: 1 Month/Full Payment, ifinstmntType: null/1	1 (For Pre-Auth & Recurring default 1)
recurrOpt Required For CC	N	2	0: Automatic Cancel 1: Do not cancel 2: Do not make token	2
merFixAcctId Required For VA (Fixed Type)	AN	40	Merchant Reserved VA ID	(Max 8 Digit Numbers)
payValidDt Required For CVS	N	8	CVS Expiry Date (YYYYMMDD)	20221212
payValidTm Required For CVS	N	6	CVS Expiry Time (HH24MISS)	201012
paymentExpDt Required	N	8	QR Payment Expiry Date (YYYYMMDD)	20221208
paymentExpTm Required	N	6	QR Payment Expiry Time (HH24MISS)	092330
shopId	AN	25	Shop ID	""

Payment Method & Bank/Partner Configuration for Customers

The payMethod parameter enables you to manage which payment methods are displayed to the Customer on the NICEPAY Checkout page.

payMethod	Impact
00	Shows all available payment method s (default).
01 – 08	Shows only one specific payment method.

If you prefer to display all payment methods as usual, simply use payMethod = '00' without adding the bankCd or mitraCd parameters.

The designated payMethod code to direct the Customer to a specific payment method. For certain payment methods, you can specify which payment channel are using bankCd or mitraCd parameters.

Example:

Shows all available payment methods → payMethod = '00'.

Shows only Credit Card → payMethod = '01'.

Shows only Virtual Account BCA → payMethod = '02', bankCd = 'CENA'.

Shows only E-Wallet DANA → payMethod = '05', mitraCd = 'DANA'.

Important notes regarding the Bank/Mitra parameter:

The bankCd parameter can only be used for Virtual Account (02) payment method.

The mitraCd parameter can only be used for Convenience Store (03), Direct Debit (04), E-Wallet (05), dan Paylater (06) payment methods.

The bankCd and mitraCd parameters cannot be used for Credit Card (01) and QRIS (08) payment methods.

Response Parameters for API Checkout Registration

Parameter	Type	Size	Description	Remark
resultCd	N	4	Result Code	0000
resultMsg	AN	255	Result Message	SUCCESS
tXid	AN	30	Transaction ID	IONPAYTEST00202305161555223616 When Success
referenceNo	ANS	40	Merchant Order Number	MerchantReferenceNumber001
payMethod	N	2	Payment Method Code	00 When Success
amt	N	12	Amount	10000 When Success
transDt	N	8	Transaction Date (YYYYMMDD)	20230516 When Success
transTm	N	6	Transaction Time (HH24MISS)	135959 When Success
description	AN	100	Transaction Description	This Is The Description Of The Payment When Success
currency	AN	3	Currency	IDR When Success
goodsNm	AN	100	Goods Name	Merchant Goods 1 When Success
billingNm	A	100	Buyer Name	John Doe When Success
payValidDt	N	8	CVS Expiry Date (YYYYMMDD)	null
payValidTm	N	6	CVS Expiry Time (HH24MISS)	null
bankCd	A	4	Bank Code	CENA
mitraCd	A	4	Mitra Code	DANA
paymentURL	AN	40	Redirect URL NICEPAY	https://www.nicepay.co.id/nicepay/redirect/v2/payment

After your transaction has been registered, direct your Customer to our Payment page to proceed with the payment. Please check the Payment - API Checkout page to view the details.

Sample Parameter for Registration - API Checkout

Request Parameter

curl --location 'https://dev.nicepay.co.id/nicepay/redirect/v2/registration' \
--header 'Content-Type: application/json' \
--data-raw '{
    "timeStamp" : "20251110141120",
    "iMid" : "IONPAYTEST",
    "payMethod" : "00",
    "currency" : "IDR",
    "referenceNo" : "ordNo20251110141120",
    "merchantToken" : "9da3d4c498aab78d9aa5f320713d3fffad1d50acd4d2d1ea9d18bb164bbf0d60",
    "mitraCd" : "",
    "amt" : "10000",
    "instmntType" : "1",
    "instmntMon" : "1",
    "callBackUrl" : "https://dev.nicepay.co.id/IONPAY_CLIENT/paymentResult.jsp",
    "dbProcessUrl" : "https://ptsv2.com/t/Sibedul/post",
    "goodsNm" : "Goods",
    "billingNm" : "Hantu Kesorean",
    "billingPhone" : "081234567890",
    "billingEmail" : "[email protected]",
    "billingAddr" : "Jl. Sample Address",
    "billingCity" : "South Jakarta",
    "billingState" : "DKI Jakarta",
    "billingCountry" : "Indonesia",
    "billingPostCd" : "12800",
    "deliveryNm" : "John Doe",
    "deliveryPhone" : "081234567890",
    "deliveryAddr" : "Jln. Sample Address",
    "deliveryCity" : "West Jakarta",
    "deliveryState" : "DKI Jakarta",
    "deliveryCountry" : "Indonesia",
    "deliveryPostCd" : "12800",
    "description" : "Testing Checkout API",
    "userIP" : "127.0.0.1",
    "userLanguage" : "ko-KR,en-US;q=0.8,ko;q=0.6,en;q=0.4",
    "cartData" : "{\"count\":\"1\",\"item\":[{\"goods_id\":\"BB12345678\",\"goods_detail\":\"BB123456\",\"goods_name\":\"iPhone5S\",\"goods_amt\":\"10000\",\"goods_type\":\"Smartphone\",\"goods_url\":\"http://merchant.com/cellphones/iphone5s_64g\",\"goods_quantity\":\"1\",\"goods_sellers_id\":\"SEL123\",\"goods_sellers_name\":\"Sellers1\"}]}",
    "sellers" :"[{\"sellersId\":\"SEL123\",\"sellersNm\":\"Sellers1\",\"sellersEmail\":\"[email protected]\",\"sellersUrl\":\"http://nicestore.store\",\"sellersAddress\":{\"sellerNm\":\"Sellers\",\"sellerLastNm\":\"1\",\"sellerAddr\":\"jalanberbangsa1\",\"sellerCity\":\"JakartaBarat\",\"sellerPostCd\":\"12344\",\"sellerPhone\":\"08123456789\",\"sellerCountry\":\"ID\"}}]",
    "msId" : "",
    "msFee" : "",
    "msFeeType" : "",
    "escrowCl" : ""
}'

Response Parameter

{
    "resultCd": "0000",
    "resultMsg": "SUCCESS",
    "tXid": "IONPAYTEST00202511101446495037",
    "referenceNo": "ordNo20251110141120",
    "payMethod": "00",
    "amt": "10000",
    "transDt": "20251110",
    "transTm": "144649",
    "description": "Testing Checkout API",
    "currency": "IDR",
    "goodsNm": "Goods",
    "billingNm": "Hantu Kesorean",
    "payValidDt": null,
    "payValidTm": null,
    "bankCd": null,
    "mitraCd": null,
    "paymentURL": "https://dev.nicepay.co.id/nicepay/redirect/v2/payment"
}

Cart Data, Paylater Cart Data & Paylater Seller Data for Registration - API Checkout

The Card Data on Checkout API is useful for declaring what items will be checked out along with item details and prices per item. This Card Data applies to all payment methods, except payment method using Paylater because the Paylater payment method has special Cart Data.

Cart Data for Registration - API Checkout

cartData must be released in the string form.

Special characters are not supported in cartData.

Make sure that count is the same as the number of item object.

Make sure that goods_amt x goods_quantity is the same as the amt parameter.

Parameter	Description	Remark
Count	Total number of all cart data	2
Item	Divided into 5 kinds of parameters, namely img_url, goods_name, goods_detail, goods_amt, and goods_quantity	-

Detailed explanation of the Item parameters.

Parameter	Description	Remark
img_url	Goods Image URL (Size 50px x 50px)	http://img.aaa.com/ima1.jpg
goods_name	Goods Name	Item 1 Name
goods_detail	Goods Detail Description	Item 1 Detail
goods_amt	Goods Amount	700
goods_quantity	Goods Quantity	1

{
    "count": "2",  
    "item": [  
        {
            "img_url": "http://img.aaa.com/ima1.jpg",  
            "goods_name": "Item 1 Name",
            "goods_detail": "Item 1 Detail",
            "goods_amt": "700",
            "goods_quantity": "1"
        },  
        {
            "img_url": "http://img.aaa.com/ima2.jpg",
            "goods_name": "Item 2 Name",
            "goods_detail": "Item 2 Detail",
            "goods_amt": "300",
            "goods_quantity": "1"
        }  
        ] 
}

Paylater Cart Data for Registration - API Checkout

Parameter	Description
count	Total Cart Data Count
item	List of Goods
item -> goods_id	Goods ID
item -> goods_detail	Goods Detail
item -> goods_name	Goods Name
item -> goods_amt	Goods Amount
item -> goods_type	Goods Type
item -> goods_url	Goods URL
item -> goods_quantity	Goods Quantity
item -> goods_sellers_id	Seller's ID
item -> goods_sellers_name	Seller's Name

cartData is mandatory to be released in the string form.

{
  "count": "2",
  "item": [
    {
      "goods_id": "BB12345678",
      "goods_detail": "BB123456",
      "goods_name": "iPhone 5S",
      "goods_amt": "6000000",
      "goods_type": "Smartphone",
      "goods_url": "http://merchant.com/cel lphones/iphone5s_64g",
      "goods_quantity": "1",
      "goods_sellers_id": "SEL123",
      "goods_sellers_name": "Sellers 1"
    },
    {
      "goods_id": "AZ14565678",
      "goods_name": "Hailee Sneakers Blink Silver",
      "goods_amt": "250000",
      "goods_url": "http://merchant.com/fashion/shoes/sneakers-blinkshoes",
      "goods_type": "Sneakers",
      "goods_quantity": "2",
      "goods_sellers_id": "SEL124",
      "goods_ sellers_name": "Sellers 2"
    }
  ]
}

cartData is specifically for Paylater.

Make sure the count parameters are based on the goods' type number.

Make sure the goods_sellers_id and goods_sellers_name are contained according to the sellers on Registration.

Paylater Sellers Data for for Registration - API Checkout

Parameter	Description
sellersId	Seller's ID
sellersNm	Seller's Name
sellersEmail	Seller's E-mail
sellersUrl	Seller's URL
sellersAddress -> sellerNm	Seller's Name
sellersAddress -> sellerLastNm	Seller's Last Name
sellersAddress -> sellerAddr	Seller's Address
sellersAddress -> sellerCity	Seller's City
sellersAddress -> sellerPostCd	Seller's Postal Code
sellersAddress -> sellerPhone	Seller's Phone
sellersAddress -> sellerCountry	Seller's Country

[
  {
    "sellersId": "SEL123",
    "sellersNm": "Sellers 1",
    "sellersEmail": "[email protected]",
    "sellersUrl": "http://nicestore.store",
    "sellersAddress": {
      "sellerNm": "Sellers",
      "sellerLastNm": "1",
      "sellerAddr": "jalan berbangsa 1",
      "sellerCity": "Jakarta Barat",
      "sellerPostCd": "12344",
      "sellerPhone": "08123456789",
      "sellerCountry": "ID"
    }
  },
  {
    "sellersId": "SEL124",
    "sellersNm": "Sellers 2",
    "sellersEmail": "[email protected]",
    "sellersUrl": "http://nicestore.store",
    "sellersAddress": {
      "sellerNm": "Sellers",
      "sellerLastNm": "2",
      "sellerAddr": "jalan berkelok 3",
      "sellerCity": "Jakarta Utara",
      "sellerPostCd": "12222",
      "sellerPhone": "081255556789",
      "sellerCountry": "ID"
    }
  }
]