Registration - API Checkout

20 min

Tentang Registration - API Checkout

Langkah pada Registration - API Checkout ini berfungsi untuk mendaftarkan sebuah request checkout belanja dari Pelanggan Anda kepada kami. Sehingga Pelanggan Anda dapat membayar jumlah transaksi yang ditagihkan pada payment page yang NICEPAY sediakan.

Pada prinsipnya, semua metode pembayaran pada Checkout API memiliki proses yang sama. Hanya saja yang membedakan adalah parameter pada setiap metode pembayaran.

Pada saat Pelanggan melakukan proses Checkout, sistem melakukan proses pendaftaran pesanan sebelum Pelanggan dapat melakukan proses pembayaran pada metode pembayaran yang diinginkan melalui tautan pembayaran yang didapatkan.

Silakan kunjungi halaman Payment - API Checkout untuk mengetahui penjelasan lebih rinci terkait API khusus pembayaran.

Registration - API Checkout (All Payment Method)

Untuk dapat menggunakan seluruh metode pembayaran pada API Checkout kecuali QRIS, Anda diperlukan untuk mendaftarkan transaksi tersebut dengan API Registrasi Checkout ini. Berikut parameternya:

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

Request Parameter for Registration - API Checkout

Parameter	Tipe	Ukuran	Deskripsi	Contoh / Catatan
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, if instmntType: 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	(Maks. 8 Digit Angka)
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	""

Konfigurasi Payment Method & Bank/Mitra untuk Pelanggan

Parameter payMethod memungkinkan Anda untuk mengatur metode pembayaran yang ditampilkan kepada Pelanggan pada halaman Checkout NICEPAY.

payMethod	Impact
00	Menampilkan semua metode pembayaran yang tersedia (default).
01 – 08	Menampilkan hanya satu metode pembayaran yang ditentukan.

Jika Anda ingin menampilkan seluruh metode pembayaran seperti biasa, silakan gunakan payMethod = '00' tanpa perlu menambahkan parameter bankCd maupun mitraCd.

Kode payMethod yang sesuai digunakan untuk mengarahkan Pelanggan ke metode pembayaran tertentu. Pada beberapa metode pembayaran, Anda juga dapat menentukan kanal pembayaran yang secara spesifik menggunakan parameter bankCd atau mitraCd.

Contoh:

Menampilkan semua metode pembayaran yang tersedia → payMethod = '00'.

Hanya menampilkan Credit Card → payMethod = '01'.

Hanya menampilkan Virtual Account BCA → payMethod = '02', bankCd = 'CENA'.

Hanya menampilkan E-Wallet DANA → payMethod = '05', mitraCd = 'DANA'.

Catatan penting mengenai penggunaan parameter Bank/Mitra:

Parameter bankCd hanya dapat digunakan untuk metode pembayaran Virtual Account (02).

Parameter mitraCd hanya dapat digunakan untuk metode pembayaran Convenience Store (03), Direct Debit (04), E-Wallet (05), dan Paylater (06).

Parameter bankCd dan mitraCd tidak dapat digunakan pada metode pembayaran Credit Card (01) dan QRIS (08).

Response Parameters for Registration - API Checkout

Parameter	Tipe	Ukuran	Deskripsi	Contoh / Catatan
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

Setelah transaksi Anda sudah didaftarkan, arahkan Pelanggan Anda langsung menuju halaman Payment kami untuk melakukan proses pembayaran. Silakan periksa halaman Payment - API Checkout untuk mengetahui penjelasan lebih rinci.

Sample Parameter for Registration - API Checkout

Request Parameter

$timestamp = "20251110141120";
$configBuilder = NICEPay::builder();
$config = $configBuilder
    ->setIsProduction(false)
    ->setIsCloudServer(false)
    ->build();
$reffNo = "ordNo20251110141120";
$amount = "10000";
$cartData = [
    "count" => "1",
    "item" => [[
        "goods_id" => "BB12345678",
        "goods_detail" => "BB123456",
        "goods_name" => "iPhone5S",
        "goods_amt" => $amount,  // Replace dynamically if needed
        "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\"}}]";

$RedirectBuilder = Redirect::builder();
$parameter = $RedirectBuilder
    ->setTimeStamp($timestamp)
    ->setIMid("IONPAYTEST")
    ->setPayMethod("00")
    ->setCurrency("IDR")
    ->setDescription("Testing Checkout API")
    ->setBankCd("")
    ->setAmt($amount)
    ->setReferenceNo($reffNo)
    ->setMerchantToken($timestamp, $this->iMidTest, $reffNo, $amount, $this->merchantKey) // Unchanged as requested
    ->setVacctValidDt("")
    ->setVacctValidTm("")
    ->setMerFixAcctId("")
    ->setDbProcessUrl("https://ptsv2.com/t/Sibedul/post")
    ->setCallBackUrl("https://dev.nicepay.co.id/IONPAY_CLIENT/paymentResult.jsp")
    ->setGoodsNm("Goods")
    ->setCartData(json_encode($cartData))
    ->setSellers($sellers)
    ->setBillingNm("Hantu Kesorean")
    ->setBillingPhone("081234567890")
    ->setBillingEmail("[email protected]")
    ->setBillingAddr("Jl. Sample Address")
    ->setBillingCity("South Jakarta")
    ->setBillingState("DKI Jakarta")
    ->setBillingPostCd("12800")
    ->setBillingCountry("Indonesia")
    ->setUserIP("127.0.0.1")
    ->setUserLanguage("ko-KR,en-US;q=0.8,ko;q=0.6,en;q=0.4")
    ->setDeliveryNm("John Doe")
    ->setDeliveryPhone("081234567890")
    ->setDeliveryAddr("Jln. Sample Address")
    ->setDeliveryCity("West Jakarta")
    ->setDeliveryState("DKI Jakarta")
    ->setDeliveryPostCd("12800")
    ->setDeliveryCountry("Indonesia")
    ->setInstmntType("1")
    ->setInstmntMon("1")
    ->setMitraCd("")
    ->setMsId("")
    ->setMsFee("")
    ->setMsFeeType("")
    ->setEscrowCl("")
    ->build();

$v2VaService = new V2RedirectService($config);

try {
    $response = $v2VaService->registration($parameter);
}

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

Cart Data pada Checkout API berguna untuk mendeklarasikan item apa saja yang akan di-checkout beserta rincian dan harga per item. Cart Data ini berlaku untuk semua metode pembayaran, kecuali metode pembayaran menggunakan Paylater dikarenakan metode pembayaran Paylater memiliki Cart Data khusus.

Cart Data for Registration - API Checkout

cartData harus dilepas dalam bentuk string.

Karakter spesial tidak didukung dalam cartData.

Pastikan bahwa count sama dengan jumlah object item.

Pastikan bahwa goods_amt x goods_quantity sama dengan parameter amt.

Parameter	Deskripsi	Contoh
Count	Total jumlah dari keseluruhan cart data	2
Item	Terbagi menjadi 5 macam parameter, yaitu img_url, goods_name, goods_detail, goods_amt, dan goods_quantity	-

Penjelasan detail pada parameter Item.

Parameter	Deskripsi	Contoh
img_url	URL Gambar Barang (Ukuran 50px x 50px)	http://img.aaa.com/ima1.jpg
goods_name	Nama Barang	Item 1 Name
goods_detail	Deskripsi Detail Barang	Item 1 Detail
goods_amt	Harga Barang	700
goods_quantity	Jumlah Barang	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	Deskripsi
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 wajib dilepas dalam format string.

{
  "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 secara spesifik untuk Paylater.

Pastikan parameter-parameter countberdasarkan dengan nomor tipe barang-barang.

Pastikan goods_sellers_id dan goods_sellers_name berisi sesuai dengan sellers pada Registration.

Paylater Sellers Data for Registration - API Checkout

Parameter	Deskripsi
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"
    }
  }
]