Pre-Auth & Capture - Payment API Credit Card
About Pre-Auth & Capture - Payment API Credit Card
After You proceed with Credit Card registration with Pre-Auth & Capture feature type on Pre-Auth & Capture - Registration API Credit Card, You can proceed to the next payment step on that transaction through this API Payment.
Learn about Credit Card Payment with RecurringToken on the Credit Card Feature page or visit the technical explanation about Pre-Auth Capture in Pre-Auth & Capture - Payment API Credit Card page.
Pre-Auth - Payment API Credit Card (Hold Fund)
API Endpoint | /nicepay/direct/v2/payment |
|---|---|
Request Method | POST |
Description | Pre-Auth (Hold Fund) |
Merchant Token | SHA256(timeStamp+iMid+referenceNo+amt+merchantKey) |
Request Format | application/json |
Request Parameter for Pre-Auth - Payment API Credit Card (Hold Fund)
To able the Pre-auth feature from Your Customer transaction, You need to fill in the tXid parameter from the response result on Pre-Auth & Capture - Registration API Credit Card that You have already done.
Parameter | Type | Size | Description | Example / Notes |
|---|---|---|---|---|
timeStamp Required | N | 14 | Request Timestamp (YYYYMMDDHH24MISS) | 20230522130518 |
tXid Required | AN | 30 | Transaction ID | IONPAYTEST01202305161007570327 |
referenceNo Required | ANS | 40 | Merchant Order Number | This Is The Description Of The Payment |
merchantToken Required | AN | 255 | Merchant Token | ff139e49606387091cd9baeadff3161aff6afd9406e1f481e0fdb8b46d1ae5ae |
cardNo Required | N | 20 | Credit Card Number | Credit Card Number 443426******0008 |
cardExpYymm Required | A | 4 | Card Expiry (YYMM) | 3901 |
cardHolderNm Required | AN | 45 | Card Holder Name | John Doe Only alphabet allowed |
cardHolderEmail Required | ANS | 100 | Card Holder Email | |
cardCvv Required | N | 4 | Card CVV | 100 |
callBackUrl Required | AN | 255 | Payment Result Forward URL | https://www.merchant.com/callbackUrl/ |
You also need cardNo, cardExpYymm, cardHolderNm, cardHolderEmail & cardCvv parameters that You can get from Your Customer so the billing transaction can be processed.
Response Parameter for Pre-Auth - Payment API Credit Card (Hold Fund)
The following is a response parameter from the request Pre-Auth Payment (Hold Fund) result.
Parameter | Type | Size | Description | Example / Notes |
|---|---|---|---|---|
timeStamp | N | 14 | Response Date (YYYYMMDDHH24MISS) | 20230516135959 |
resultCd | N | 4 | Result Code | 0000 |
resultMsg | AN | 255 | Result Message: Error Code | SUCCESS |
tXid | AN | 30 | Transaction ID | IONPAYTEST01202305161007570327 |
referenceNo | ANS | 40 | Merchant Order Number | MerchantReferenceNumber001 |
payMethod | N | 2 | 01 When Success | |
amount | N | 12 | Payment Amount | 10000 When Success |
currency | AN | 3 | Currency | IDR When Success |
goodsNm | AN | 100 | Goods Name | Merchant Goods 1 When Success |
billingNm | AN | 100 | Buyer Name | John Doe When Success |
transDt | N | 8 | Transaction Date (YYYYMMDD) | 20230522 When Success |
transTm | N | 6 | Transaction Time (HH24MISS) | 135959 When Success |
description | AN | 100 | Description | This Is The Description Of The Payment When Success |
authNo | N | 10 | Approval Number | 123456 When Success |
issuBankCd | A | 4 | CENA When Success | |
acquBankCd | A | 4 | BNIA When Success | |
cardNo | AN | 20 | Card Number (Masked) | 443426******0008 When Success
|
cardExpYymm | N | 4 | Card Expiry (YYMM) | 3901 When Success |
instmntMon | N | 2 | Installment Month | 1 When Success |
instmnType | N | 2 | 1 When Success | |
preauthToken | AN | 64 | Pre-Auth Token | 5c6ba40e61c45d9fa37e763ea1f86b9d6ac5f1f7ed279e4d4531191c83279320 When Success |
ccTransType | AN | 2 | 3 When Success | |
vat | N | 12 | Value Added Tax (VAT) | 0 When Success |
fee | N | 12 | Service Fee | 0 When Success |
notaxAmt | N | 12 | Tax Free Amount | 0 When Success |
acquBankNm | A | 255 | Acquiring Bank Name | CIMB |
issuBankNm | A | 255 | Issuing Bank Name | BCA |
If this process is successful, the paid fund will automatically hold, and You will get the needed preauthToken to go through the later capture process.
Please proceed capture process immediately after the Pre-Auth process is finished before the transaction fund expiry and will be considered void (the transaction fund will return to the cardholder)
The expiration date on the Pre-Auth transaction type usually takes up to 7 days.
Sample Parameter for Pre-Auth - Payment API Credit Card (Hold Fund)
Request Parameter
let secondVersion = new SecondApiVersion(config);
let parameterPayment = {
amt: "10000",
referenceNo: "ordNo20251001101069",
tXid: "TESTMPGS0501202510011026450166",
cardNo: "5123450000000008",
callBackUrl: "https://dev.nicepay.co.id/IONPAY_CLIENT/paymentResult.jsp?order_id=RECURRTEST01202509301555563979",
cardExpYymm: "3106",
cardCvv: "100",
cardHolderNm: "Nicepay Test",
preauthToken: "", // Leave empty for hold fund
cardHolderEmail: "[email protected]",
};
let response = secondVersion.requestPayment(parameterPayment);Response Parameter
<head>
<style>
body {
min-width: 100%;
height: auto;
min-height: 500px;
overflow: none;
border: none;
.wrapper {
position: absolute;
top: 0;
left: 0;
background-color: transparent;
display: flex;
justify-content: center;
align-items: center;
height: 100%;
width: 100%;
z-index: 10
}
.loader {
color: #6ac9ca;
font-size: 10px;
width: 1em;
height: 1em;
border-radius: 50%;
position: relative;
text-indent: -9999em;
animation: 1.3s linear infinite mulShdSpin;
transform: translateZ(0)
}
@keyframes mulShdSpin {
0%,
100% {
box-shadow: 0 -3em 0 .2em, 2em -2em 0 0, 3em 0 0 -1em, 2em 2em 0 -1em, 0 3em 0 -1em, -2em 2em 0 -1em, -3em 0 0 -1em, -2em -2em 0 0
}
12.5% {
box-shadow: 0 -3em 0 0, 2em -2em 0 .2em, 3em 0 0 0, 2em 2em 0 -1em, 0 3em 0 -1em, -2em 2em 0 -1em, -3em 0 0 -1em, -2em -2em 0 -1em
}
25% {
box-shadow: 0 -3em 0 -.5em, 2em -2em 0 0, 3em 0 0 .2em, 2em 2em 0 0, 0 3em 0 -1em, -2em 2em 0 -1em, -3em 0 0 -1em, -2em -2em 0 -1em
}
37.5% {
box-shadow: 0 -3em 0 -1em, 2em -2em 0 -1em, 3em 0 0 0, 2em 2em 0 .2em, 0 3em 0 0, -2em 2em 0 -1em, -3em 0 0 -1em, -2em -2em 0 -1em
}
50% {
box-shadow: 0 -3em 0 -1em, 2em -2em 0 -1em, 3em 0 0 -1em, 2em 2em 0 0, 0 3em 0 .2em, -2em 2em 0 0, -3em 0 0 -1em, -2em -2em 0 -1em
}
62.5% {
box-shadow: 0 -3em 0 -1em, 2em -2em 0 -1em, 3em 0 0 -1em, 2em 2em 0 -1em, 0 3em 0 0, -2em 2em 0 .2em, -3em 0 0 0, -2em -2em 0 -1em
}
75% {
box-shadow: 0 -3em 0 -1em, 2em -2em 0 -1em, 3em 0 0 -1em, 2em 2em 0 -1em, 0 3em 0 -1em, -2em 2em 0 0, -3em 0 0 .2em, -2em -2em 0 0
}
87.5% {
box-shadow: 0 -3em 0 0, 2em -2em 0 -1em, 3em 0 0 -1em, 2em 2em 0 -1em, 0 3em 0 -1em, -2em 2em 0 0, -3em 0 0 0, -2em -2em 0 .2em
}
}
</style>
</head>
<body onload='javascript:getBrowserInfo();'>
<div class='wrapper' id='loader'><span class='loader'></span></div>
<div style='visibility:hidden'>
<div id="initiate3dsSimpleRedirect" xmlns="http://www.w3.org/1999/html"> <iframe id="methodFrame"
name="methodFrame" height="100" width="200"> </iframe>
<form id="initiate3dsSimpleRedirectForm" method="POST"
action="https://mtf.gateway.mastercard.com/acs/mastercard/v2/method" target="methodFrame"> <input type="hidden" name="threeDSMethodData" value="eyJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIjoiaHR0cHM6Ly9tdGYuZ2F0ZXdheS5tYXN0ZXJjYXJkLmNvbS9jYWxsYmFja0ludGVyZmFjZS9nYXRld2F5L2Q2ZWRlMjU4N2VjNmVmY2Y4ODc4YWIxZjBhMWViMTc0YTkwZDA5N2E0YWJhZDVhOTQzNzM5ZmVmMTdjNzZhZDUiLCJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjZkYjBhY2I4LTdjMDYtNDc5Yy04MTNmLTQ4YTA4NWYzNjU0ZSJ9" />
</form>
<script id="initiate-authentication-script">
var e=document.getElementById("initiate3dsSimpleRedirectForm"); if (e) { e.submit(); if (e.parentNode !== null) { e.parentNode.removeChild(e); } }
</script>
</div>
</div>
<form name="mpgsAuthFrm" id="mpgsAuthFrm" method="post" action='https://dev.nicepay.co.id/nicepay/api/mpgsAuth.do'>
<input type='hidden' name='tXid' value='TESTMPGS0501202510011026450166'>
<input type='hidden' name='cardNo' value='5123450000000008'>
<input type='hidden' name='cardExpYymm' value='3106'>
<input type='hidden' name='cardCvv' value='100'>
<input type='hidden' name='callbackUrl' value='https://dev.nicepay.co.id/IONPAY_CLIENT/paymentResult.jsp?order_id=TESTMPGS0501202510011026450166'>
<input type='hidden' name='registered' value='true'>
<input type='hidden' name='directV1' value='false'>
<input type='hidden' name='authResult' value='false'>
<input type='hidden' name='browser' value=''>
<input type='hidden' name='browserJavaEnabled' value='false'>
<input type='hidden' name='browserJavascriptEnabled' value='2'>
<input type='hidden' name='browserLanguage' value=''>
<input type='hidden' name='browserScreenColorDepth' value=''>
<input type='hidden' name='browserScreenHeight' value='0'>
<input type='hidden' name='browserScreenWidth' value='0'>
<input type='hidden' name='browserTimeZone' value='0'>
</form>
<script>
function getBrowserInfo() {
document.mpgsAuthFrm.browser.value = navigator.userAgent;
document.mpgsAuthFrm.browserJavaEnabled.value = window.navigator.javaEnabled() === true ? 'true' : 'false';
document.mpgsAuthFrm.browserJavascriptEnabled.value = "1";
document.mpgsAuthFrm.browserLanguage.value = navigator.language;
document.mpgsAuthFrm.browserScreenColorDepth.value = screen.colorDepth;
document.mpgsAuthFrm.browserScreenHeight.value = screen.height;
document.mpgsAuthFrm.browserScreenWidth.value = screen.width;
document.mpgsAuthFrm.browserTimeZone.value = new Date().getTimezoneOffset();
document.mpgsAuthFrm.submit();
}
</script>
</body>
Capture - Payment API Credit Card
API URL | /nicepay/direct/v2/payment |
|---|---|
Request Method | POST |
Description | Capture Process from Pre-Auth |
Merchant Token | SHA256(timeStamp+iMid+referenceNo+amt+merchantKey) |
Request Format | application/json |
Request Parameter for Capture - Payment API Credit Card
After you get the preauthToken on the paid transaction from your Customer on API Pre-Auth Payment (Hold) process.
The next step is going through capture process on the earlier held fund. However to proceed with that, You need to register again with the new transaction on Pre-Auth & Capture - Registration API Credit Card with the capture amount must be less or equal to the hold amount from the previous Pre-Auth process.
If you already success registered the transaction again, You can use this API Capture.
The capture process can be executed multiple times as long as the total amount that already went through pre-auth still available for capture include the pre-auth transaction still not yet expired or hasn't considered void.
The following is a list of parameter to integrate for the Credit Card payment process using PreauthToken without cardNo, cardExpYymm , or cardCvv.
Parameter | Type | Size | Description | Example / Notes |
|---|---|---|---|---|
timeStamp Required | N | 14 | Request Timestamp (YYYYMMDDHH24MISS) | 20230516135959 |
tXid Required | AN | 30 | Transaction ID | IONPAYTEST01202305161007570327 |
referenceNo Required | ANS | 40 | Merchant Order Number | MerchantReferenceNumber001 |
merchantToken Required | AN | 255 | Merchant Token | ff139e49606387091cd9baeadff3161aff6afd9406e1f481e0fdb8b46d1ae5ae |
cardHolderNm Required | AN | 45 | Card Holder Name | John Doe Only alphabet allowed |
cardCvv | N | 6 | Card CVV | 100 |
callBackUrl Required | ANS | 255 | Payment Result URL | https://www.nicepay.co.id/IONPAY_CLIENT/paymentResult.jsp |
preauthToken Required For Capture Process in Pre-Auth | AN | 64 | Pre-Auth Token | 5976c263fe6116503645057bb00be809c3a6f9c1e355efa12ef2cda2be03d5eb |
tXid will never be similar with the request (pre-auth - hold). The Capture process will ensure that the capture amount value won't exceed the funds You already pre-auth.
Response Parameter for Capture - Payment API Credit Card
Parameter | Type | Size | Description | Example / Notes |
|---|---|---|---|---|
timeStamp | N | 14 | Response Date (YYYYMMDDHH24MISS) | 20230516135959 |
resultCd | N | 4 | Result Code | 0000 |
resultMsg | AN | 255 | Result Message: Error Code | SUCCESS |
tXid | AN | 30 | Transaction ID | IONPAYTEST01202305161007570327 |
referenceNo | ANS | 40 | Merchant Order Number | MerchantReferenceNumber001 |
payMethod | N | 2 | 01 When Success | |
amount | N | 12 | Payment Amount | 10000 When Success |
currency | AN | 3 | Currency | IDR When Success |
goodsNm | AN | 100 | Goods Name | Merchant Goods 1 When Success |
billingNm | AN | 100 | Buyer Name | John Doe When Success |
transDt | N | 8 | Transaction Date (YYYYMMDD) | 20230522 When Success |
transTm | N | 6 | Transaction Time (HH24MISS) | 224343 When Success |
description | AN | 100 | Description | This Is The Description Of The Payment When Success |
authNo | N | 10 | Approval Number | 123456 When Success |
issuBankCd | A | 4 | CENA When Success | |
acquBankCd | A | 4 | BNIA When Success | |
cardNo | AN | 20 | Card Number (Masked) | 51234500****0008 When Success
|
cardExpYymm | N | 4 | Card Expiry (YYMM) | 3901 When Success |
instmntMon | N | 2 | Installment Month | 1 When Success |
instmnType | N | 2 | 1 When Success | |
ccTransType | AN | 2 | 3 When Success | |
vat | N | 12 | Value Added Tax (VAT) | 0 When Success |
fee | N | 12 | Service Fee | 0 When Success |
notaxAmt | N | 12 | Tax Free Amount | 0 When Success |
acquBankNm | A | 255 | Acquiring Bank Name | CIMB |
issuBankNm | A | 255 | Issuing Bank Name | BCA |
tXid will never similar with the request hold. Capture process will ensure that the capture amount value won't exceed the owned funds.
Sample Parameter for Capture - Payment API Credit Card
Request Parameter
let secondVersion = new SecondApiVersion(config);
let parameterPayment = {
amt: "100",
referenceNo: "ordNo20251001171009",
tXid: "TESTMPGS0501202510011716431018",
callBackUrl: "https://dev.nicepay.co.id/IONPAY_CLIENT/paymentResult.jsp?order_id=RECURRTEST01202509301555563979",
cardHolderNm: "Nicepay Test",
preauthToken: "a513eff039c80a8c617fe57dbb401c52dbfd683b5d48fb3df61312f5a6665f35", // Preauth token
cardHolderEmail: "[email protected]",
};
let response = secondVersion.requestPayment(parameterPayment);Response Parameter
<!-- <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 5.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> -->
<!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
<script type="text/javascript" src="/nicepay/js/bootstrap.js"></script>
<link rel="stylesheet" type="text/css" href="/nicepay/css/bootstrap.css" />
<link rel="stylesheet" type="text/css" href="/nicepay/css/bootstrap_backup.css" />
<link rel="stylesheet" type="text/css" href="/nicepay/css/bootstrap.min.css" />
<link rel="stylesheet" type="text/css" href="/nicepay/css/form.css" />
<link rel="stylesheet" type="text/css" href="/nicepay/css/bootstrap-responsive.css" />
<link rel="stylesheet" type="text/css" href="/nicepay/css/basic.css" />
<link rel="shortcut icon" href="https://www.nicepay.co.id/favicon.ico" type="image/x-icon" />
<link rel="icon" href="https://www.nicepay.co.id/favicon.ico" type="image/x-icon" />
<script type="text/javascript" src="/nicepay/js/jquery.js"></script>
<script type="text/javascript" src="/nicepay/js/jquery.min.js"></script>
<script type="text/javascript" src="/nicepay/js/common.js"></script>
</head>
<body >
<html>
<head>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<script type = "text/javascript">
function setAcsInfo(){
if ('01' != '05') {
document.tranMgr.action = $("#callbackUrl").val();
} else if ('01' == '05' && '' != null && '' == 'OVOE') {
document.tranMgr.action = $("#callbackUrl").val();
}
if (document.tranMgr.cardBrand.value == null || document.tranMgr.cardBrand.value == "")
document.tranMgr.cardBrand.setAttribute("disabled", true);
document.tranMgr.submit();
}
</script>
</head>
<style>
body {
min-width: 100%;
height:auto;
min-height: 500px;
overflow: none;
border: none;
}
.wrapper {
position: absolute;
top: 0;
left: 0;
background-color: transparent;
display: flex;
justify-content: center;
align-items: center;
height: 100%;
width: 100%;
z-index: 10;
}
.loader {
color: #79CDBD;
font-size: 10px;
width: 1em;
height: 1em;
border-radius: 50%;
position: relative;
text-indent: -9999em;
animation: mulShdSpin 1.3s infinite linear;
transform: translateZ(0);
}
@keyframes mulShdSpin {
0%,
100% {
box-shadow: 0 -3em 0 0.2em,
2em -2em 0 0em, 3em 0 0 -1em,
2em 2em 0 -1em, 0 3em 0 -1em,
-2em 2em 0 -1em, -3em 0 0 -1em,
-2em -2em 0 0;
}
12.5% {
box-shadow: 0 -3em 0 0, 2em -2em 0 0.2em,
3em 0 0 0, 2em 2em 0 -1em, 0 3em 0 -1em,
-2em 2em 0 -1em, -3em 0 0 -1em,
-2em -2em 0 -1em;
}
25% {
box-shadow: 0 -3em 0 -0.5em,
2em -2em 0 0, 3em 0 0 0.2em,
2em 2em 0 0, 0 3em 0 -1em,
-2em 2em 0 -1em, -3em 0 0 -1em,
-2em -2em 0 -1em;
}
37.5% {
box-shadow: 0 -3em 0 -1em, 2em -2em 0 -1em,
3em 0em 0 0, 2em 2em 0 0.2em, 0 3em 0 0em,
-2em 2em 0 -1em, -3em 0em 0 -1em, -2em -2em 0 -1em;
}
50% {
box-shadow: 0 -3em 0 -1em, 2em -2em 0 -1em,
3em 0 0 -1em, 2em 2em 0 0em, 0 3em 0 0.2em,
-2em 2em 0 0, -3em 0em 0 -1em, -2em -2em 0 -1em;
}
62.5% {
box-shadow: 0 -3em 0 -1em, 2em -2em 0 -1em,
3em 0 0 -1em, 2em 2em 0 -1em, 0 3em 0 0,
-2em 2em 0 0.2em, -3em 0 0 0, -2em -2em 0 -1em;
}
75% {
box-shadow: 0em -3em 0 -1em, 2em -2em 0 -1em,
3em 0em 0 -1em, 2em 2em 0 -1em, 0 3em 0 -1em,
-2em 2em 0 0, -3em 0em 0 0.2em, -2em -2em 0 0;
}
87.5% {
box-shadow: 0em -3em 0 0, 2em -2em 0 -1em,
3em 0 0 -1em, 2em 2em 0 -1em, 0 3em 0 -1em,
-2em 2em 0 0, -3em 0em 0 0, -2em -2em 0 0.2em;
}
}
</style>
<body onLoad="javascript:setAcsInfo();">
<div class="wrapper" id="loader">
<span class="loader"></span>
</div>
<form name="tranMgr" method="post" action="">
<input type="hidden" id="callbackUrl" value="https://dev.nicepay.co.id/IONPAY_CLIENT/paymentResult.jsp?order_id=TESTMPGS0501202510011716431018">
<input type="hidden" name="resultCd" value="0000">
<input type="hidden" name="resultMsg" value="SUCCESS">
<input type="hidden" name="tXid" value="TESTMPGS0501202510011716431018">
<input type="hidden" name="referenceNo" value="ordNo20251001171009">
<input type="hidden" name="payMethod" value="01">
<input type="hidden" name="amt" value="100">
<input type="hidden" name="transDt" value="20251001">
<input type="hidden" name="transTm" value="171643">
<input type="hidden" name="description" value="">
<input type="hidden" name="authNo" value="259296">
<input type="hidden" name="issuBankCd" value="BTPN">
<input type="hidden" name="acquBankCd" value="BNIA">
<input type="hidden" name="cardNo" value="51234500****0008">
<input type="hidden" name="receiptCode" value="">
<input type="hidden" name="mitraCd" value="">
<input type="hidden" name="recurringToken" value="">
<input type="hidden" name="preauthToken" value="">
<input type="hidden" name="currency" value="IDR">
<input type="hidden" name="goodsNm" value="Goods">
<input type="hidden" name="billingNm" value="Nicepay test TESTMPGS05">
<input type="hidden" name="ccTransType" value="4">
<input type="hidden" name="mRefNo" value="">
<input type="hidden" name="instmntType" value="1">
<input type="hidden" name="instmntMon" value="1">
<input type="hidden" name="cardExpYymm" value="3901">
<input type="hidden" name="issuBankNm" value="BTPN">
<input type="hidden" name="acquBankNm" value="CIMB">
<input type="hidden" name="timeStamp" value="20251001171714">
<input type="hidden" name="merchantToken" value="5a96b2ec2e748454714d78ccee174ed74b095fad2612eb9370e9a15e516cddec">
<input type="hidden" name="cardBrand" value="">
</form>
</body>
</html>
</body>
</html>
CallBack Handling for Pre-Auth & Capture - Payment API Credit Card
When your callback already received callbackUrl, we recommended the Merchant do the status verification using the Status Inquiry - API Credit Card.
CallBack Handling is very important to minimize the Fraud act, we highly recommend the Merchant to do the verification using callBack Handling .
{
"resultCd":"0000",
"resultMsg":"SUCCESS",
"tXid":"IONPAYTEST01202212141112221428",
"referenceNo":"",
"payMethod":"01",
"amt":"10000",
"transDt":"20221212",
"transTm":"121212",
"description":"Testing Credit Card Transaction",
"authNo":"080623",
"issuBankCd":"OTHR"
"acquBankCd":"BMRI",
"cardNo":"453211*****1111",
"goodsNm":"Test Transaction Nicepay"
"billingNm":"John Doe",
"currency":"IDR",
"timeStamp":"20221212121212",
"merchantToken":"2035d2295d9578fffb40137186f0203474142ae3e57992d4847826c5fcaffce6",
"cardExpYymm":"2712",
"instmntMon":"1",
"instmntType":"1",
"ccTransType":"1"
}