Credit Card - API Checkout
There are several things that you must know when using Checkout API for Credit Card method so that your integration process will run smoothly with us:
- Flow 3Ds/Non-3Ds Process.
- Full Payment Feature.
- Installment Feature.
- Recurring Token Feature.
- Pre-Auth Token Feature.
Please visit the Credit Card Feature page to check the explanation about 3Ds.
![CC Payment Flow - Redirect 3Ds CC Payment Flow - Redirect 3Ds](https://images.archbee.com/ZHvSjR5ZrsoxwKbJa3xmo/-B7a6C3IMu5oNYpnz84pR_nicepay-archbee-payment-cc-new-cc-redirect-3ds.png?format=webp)
Description steps of redirect Credit Card payment flow with 3Ds:
- The Customer does checkout.
- The Customer sends checkout data to the Merchant.
- The Merchant requests checkout using Registration API to NICEPAY.
- NICEPAY registers the checkout data.
- NICEPAY redirects Merchant to the NICEPAY's payment page.
- The Merchant sends the NICEPAY's payment page to the Customer.
- The Customer selects the payment method.
- The Customer inputs the card data.
- The Customer sends the information of card data to NICEPAY.
- NICEPAY proceeds with the FDS calculation.
- NICEPAY requests 3Ds to Bank.
- Bank validates the 3Ds.
- Bank sends 3Ds URL response to NICEPAY.
- NICEPAY receives the verification response.
- NICEPAY redirects the Customer to ACS authentication page.
- Bank creates OTP response.
- Bank sends OTP to the Customer.
- The Customer receives OTP.
- The Customer inputs OTP.
- The Customer sends OTP to Bank.
- Bank verifies the OTP.
- Bank sends 3Ds result to NICEPAY.
- NICEPAY receives the checking result.
- NICEPAY requests the payment to Bank.
- Bank proceeds the payment.
- Bank sends payment notification to NICEPAY.
- NICEPAY performs callbackUrl redirect to the Merchant.
- The Merchant displays the callbackUrl result to the Customer.
- NICEPAY sends payment notification to the Merchant.
- The Merchant receives the notification.
- The Merchant requests inquiry status to NICEPAY.
- NICEPAY receives the request.
- NICEPAY automatically sends status inquiry response to the Merchant.
- The Merchant receives the final status.
- The Merchant sends the transaction result page to the Customer.
![CC Payment Flow - Redirect N 3Ds CC Payment Flow - Redirect N 3Ds](https://images.archbee.com/ZHvSjR5ZrsoxwKbJa3xmo/eAcndroEzJ_AXG8-rTp7B_nicepay-archbee-payment-cc-redirect-non3ds.png?format=webp)
Description steps of redirect credit card payment flow with Non-3Ds:
- The Customer performs checkout.
- The Customer requests checkout to the Merchant.
- The Merchant registers the checkout data.
- The Merchant sends the response in the form of card data form.
- The Customer requests checkout to the Merchant.
- The Merchant registers the order using Registration API to NICEPAY.
- NICEPAY stores the order registration.
- NICEPAY redirects Merchant to the NICEPAY's page.
- The Merchant sends NICEPAY's page to the Customer.
- The Customer selects the payment method.
- The Customer inputs card detail.
- The Customer requests payment using Payment API to NICEPAY.
- NICEPAY proceeds with the FDS calculation.
- NICEPAY requests the payment to Bank.
- Bank verifies the request.
- Bank sends payment confirmation request to the Customer.
- The Customer requests payment/charge to Bank.
- Bank proceeds the payment.
- Bank sends the response of payment to NICEPAY.
- NICEPAY sends payment notification using callBackUrl and dbProcessUrl to the Merchant.
- The Merchant receives the notification.
- The Merchant requests status checking to NICEPAY.
- NICEPAY sends the response of status checking.
- The Merchant receives the final status.
- The Merchant sends the order result to the Customer.
Please open the Credit Card Payment Guide page to provide your Customer with payment guide on the Credit Card method.
![Secure Payment Page Secure Payment Page](https://images.archbee.com/ZHvSjR5ZrsoxwKbJa3xmo/-zcoky3z8UPZEoqiHEvST_eng-new-secure-payment-page-gpn.png?format=webp)
The image above is a payment sample with a Credit Card using NICEPAY Secure Payment Page.
After the Customer selects the credit card method, the Customer will ask to input their card data. NICEPAY system will automatically recognize the type of Customer's BIN card like in the picture below, such as VISA or Mastercard, American Express, etc later the cards will be different according to the card types being used.
After completing the card data input, Your Customer can continue the payment process.
![Credit Secure Payment Page Credit Secure Payment Page](https://images.archbee.com/ZHvSjR5ZrsoxwKbJa3xmo/tjgTnkb7qcOiECfQklIWv_en-secure-payment.jpg?format=webp)
Then, the transaction will run. Once the transaction is successful, then the display of the NICEPAY payment page will appear as the image as follows.
![Success - NICEPAY Secure Payment Page Success - NICEPAY Secure Payment Page](https://images.archbee.com/ZHvSjR5ZrsoxwKbJa3xmo/gExWzZhgWejXvDBTO8ImB_eng-new-secure-payment-page-cc-2.png?format=webp)
Please visit the Payment - API Checkout page to know the next step regarding payment handling.
On the Full Payment Credit Card, the Customer paid fully the nominal billed at once. The following is the details API used on Credit Card payment.
Parameter | Type | Size | Description | Remark |
paymentURL Required | ANS | 14 | Payment URL | https://dev.nicepay.co.id/nicepay/redirect/v2/payment |
tXid Required | AN | 30 | Transaction ID | IONPAYTEST00202203211640309389 |
For Checkout Payment API, credit card payment method with Full Payment and Installment got the same response.
Parameter | Type | Size | Description | Remark |
status | N | 1 | 0 | |
tXid | AN | 30 | Transaction ID | IONPAYTEST00202212201540174369 When Success |
referenceNo | AN | 40 | Merchant Order Number | ordNo20221220151243 When Success |
payMethod | N | 2 | 01 When Success | |
amt | N | 12 | Transaction Amount | 1000 When Success |
notaxAmt | N | 12 | Tax Fee Amount | 0 When Success |
vat | N | 12 | Value Added Tax (VAT) | 0 When Success |
fee | N | 12 | Service Fee | 0 When Success |
currency | A | 3 | Currency | IDR When Success |
goodsNm | AN | 100 | Goods Name | Goods+For+Testing+Credit+Card When Success |
billingNm | A | 100 | Billing Name | John+Doe When Success |
transDt | N | 8 | Transaction Date (YYYYMMDD) | 20221220 When Success |
transTm | N | 6 | Transaction Time (HH24MISS) | 154017 When Success |
authNo | N | 10 | Approval Number | 174300 When Success (Additional) |
issuBankCd | A | 4 | BMRI When Success | |
acquBankCd | A | 4 | BMRI When Success | |
issuBankNm | A | 255 | Issuing Bank Name | Mandiri When Success |
acquBankNm | A | 255 | Acquiring Bank Name | Mandiri When Success |
ccTransType | AN | 2 | 1 When Success | |
cardNo | ANS | 20 | Card Number With Masking | 46161111****1111 When Success |
cardExpYymm | N | 4 | Card Expiration (YYMM) | 2707 When Success |
instmntType | N | 2 | 1 When Success | |
instmntMon | N | 2 | Installment Month 1: 1 Month/Full Payment, if instmntType: null/1 3: 3 Months 6: 6 Months 12: 12 Months | 1 When Success |
recurringToken | AN | 255 | Recurring Token | null When Success |
preauthToken | AN | 255 | Pre-Auth Token | null When Success |
matchCl | N | 1 | 1 When Success | |
merchantToken | AN | 255 | Merchant Token | 8f5b330a549c167b53b4b9fd5f2d2eba897a64235c1610524074ec59f8884e8a |
Note: Response parameter will be sent through callBackurl with Content-type: application/json and method: POST Parameter.
For the Payment integration process on Checkout API, the Response from Request received after performing Call Request API is a callback URL.
API URL | /nicepay/redirect/v2/payment |
Request Method | Redirect-GET |
Header | Content-Type: application/Form-UrlEncoded |
The endpoint above can use for credit card payment methods with Full Payment, Recurring, and PAC (Pre-Auth Capture) types.
After the Merchant completes Registration - API Checkout and Payment - API Checkout, then NICEPAY will provide recurringToken for the gain Payment - API Checkout response.
On the next transaction with the same Customer, Merchant can use that recurringToken by using on the Recurring - API Payment Credit Card.
Parameter | Type | Size | Description | Remark |
paymentURL Required | ANS | 14 | Payment URL | https://dev.nicepay.co.id/nicepay/redirect/v2/payment |
tXid Required | AN | 30 | Transaction ID | RECURRTEST00202212221422115631 |
Parameter | Type | Size | Description | Remark |
status | N | 1 | 0 | |
tXid | AN | 30 | Transaction ID | RECURRTEST00202212221422115631 When Success |
referenceNo | AN | 40 | Merchant Order Number | ordNo20221222141245 When Success |
payMethod | N | 2 | 01 When Success | |
amt | N | 12 | Transaction Amount | 1000 When Success |
notaxAmt | N | 12 | Tax Fee Amount | 0 When Success |
vat | N | 12 | Value Added Tax (VAT) | 0 When Success |
fee | N | 12 | Service Fee | 0 When Success |
currency | A | 3 | Currency | IDR When Success |
goodsNm | AN | 100 | Goods Name | Goods+For+Testing+Recurring+Token When Success |
billingNm | A | 100 | Billing Name | John+Doe When Success |
transDt | N | 8 | Transaction Date (YYYYMMDD) | 20221220 When Success |
transTm | N | 6 | Transaction Time (HH24MISS) | 142211 When Success |
authNo | N | 10 | Approval Number | 115631 When Success (Additional) |
issuBankCd | A | 4 | OTHR When Success | |
acquBankCd | A | 4 | BMRI When Success | |
issuBankNm | A | 255 | Issuing Bank Name | (empty) When Success |
acquBankNm | A | 255 | Acquiring Bank Name | Mandiri When Success |
ccTransType | AN | 2 | 1 When Success | |
cardNo | ANS | 20 | Card Number With Masking | 45321111****1111 When Success |
cardExpYymm | N | 4 | Card Expiry (YYMM) | 2712 When Success |
instmntType | N | 2 | 1 When Success | |
instmntMon | N | 2 | Installment Month 1: 1 Month/Full Payment, jika instmntType: null/1 3: 3 Months 6: 6 Months 12: 12 Months | 1 When Success |
recurringToken | AN | 255 | Recurring Token | 083333e129dea0535119b71813b1dc67b565e2704958411d2ee2ec2f430d745 When Success |
preauthToken | AN | 255 | Pre-Auth Token | null When Success |
matchCl | N | 1 | Payment Amount Match Flag: Notification Status Code | 1 When Success |
merchantToken | AN | 255 | Merchant Token | f083333e129dea0535119b71813b1dc67b565e2704958411d2ee2ec2f430d745 |
After proceeding with API registration (Registration - API Checkout) and Payment API integration (Payment - API Checkout) using Checkout API,
- If you want to proceed with Payment Credit Card Recurring using the same Recurring Token, please do the registration again on the Registration - API Checkout.
- Then proceeds payment by adding the Recurring Token also CVV on the recurringToken parameter.
When Merchants sign a contract as PAC Merchant (Pre-Auth/Capture), NICEPAY provides a preauthToken for Payment - API Checkout response. That token will later use on capture amount process to complete the transaction on Pre-Auth & Capture - Payment API Credit Card.
The following are parameter lists to perform requests with the Pre-Auth Token Credit Card. This parameter uses in the API testing platform as one of the steps to connect the Merchant's systems with NICEPAY services.
Parameter | Type | Size | Description | Remark |
paymentURL Required | ANS | 14 | Payment URL | https://dev.nicepay.co.id/nicepay/redirect/v2/payment |
tXid Required | AN | 30 | Transaction ID | PACTEST00100202212221548525731 |
Parameter | Type | Size | Description | Remark |
status | N | 1 | 5 | |
tXid | AN | 30 | Transaction ID | PACTEST00100202212221548525731 When Success |
referenceNo | AN | 40 | Merchant Order Number | ordNo20221222151220 When Success |
payMethod | N | 2 | 01 When Success | |
amt | N | 12 | Transaction Amount | 1000 When Success |
notaxAmt | N | 12 | Tax Fee Amount | 0 When Success |
vat | N | 12 | Value Added Tax (VAT) | 0 When Success |
fee | N | 12 | Service Fee | 0 When Success |
currency | A | 3 | Currency | IDR When Success |
goodsNm | AN | 100 | Goods Name | Goods+For+Testing+Pre+-+Auth+Token When Success |
billingNm | A | 100 | Billing Name | John+Doe When Success |
transDt | N | 8 | Transaction Date (YYYYMMDD) | 20221222 When Success |
transTm | N | 6 | Transaction Time (HH24MISS) | 154852 When Success |
authNo | N | 10 | Approval Number | 525731 When Success (Additional) |
issuBankCd | A | 4 | CENA When Success | |
acquBankCd | A | 44 | BMRI When Success | |
issuBankNm | A | 255 | Issuing Bank Name | BCA When Success |
acquBankNm | A | 255 | Acquiring Bank Name | Mandiri When Success |
ccTransType | AN | 2 | 1 When Success | |
cardNo | ANS | 20 | Card Number With Masking | 53079511****1111 When Success |
cardExpYymm | N | 4 | Card Expiry (YYMM) | 2712 When Success |
instmntType | N | 2 | 1 When Success | |
instmntMon | N | 2 | Installment Month 1: 1 Month/Full Payment, jika instmntType: null/1 3: 3 Months 6: 6 Months 12: 12 Months | 1 When Success |
recurringToken | AN | 255 | Recurring Token | null When Success |
preauthToken | AN | 255 | Pre-Auth Token | edc46eb30a81ac9753e34003d2d1e910d5aaf0dea620889dffcfcc18621864eb When Success |
matchCl | N | 1 | Payment Amount Match Flag: Notification Match Amount Indicator | 1 When Success |
merchantToken | AN | 255 | Merchant Token | 1bee4b7c84cfb4e04d9d26cd47285bf49a77f252f39a48370094f5e3250b9524 |
After proceeds registration and payment using Checkout API,
- If you wants to proceed with multiple-capture by using the same Pre-Auth Token, please do the registration again.
- Then captures on the Payment V2 Credit Card by adding the Pre-Auth Token also the CVV on the preauthToken parameter.
The tXid won't be the same as the request hold. The capture process will reassure that the captured amount value doesn't exceed the funds owned.
When Your callback already received callbackUrl, we recommended the Merchant to do the status verification using the Status Inquiry - API Checkout.
CallBack Handling is very important to minimize the Fraud act, we highly recommend the Merchant to do the verification using callBack parameter.
![Callback Handling Flow Callback Handling Flow](https://images.archbee.com/ZHvSjR5ZrsoxwKbJa3xmo/ccwlMZjgo0gOioQqjK2oO_nicepay-api-checkout-api-callback-handling-flow-1.png?format=webp)
![Callback Handling Flow Callback Handling Flow](https://images.archbee.com/ZHvSjR5ZrsoxwKbJa3xmo/jxLNB-_-hplRzCqTEywwd_nicepay-api-checkout-api-callback-handling-flowdrawio-2.png?format=webp)