Integrate with Credit card Authentication


The credit card authentication service is a service that allows you to verify the personal information (name, date of birth, gender, and whether you are a foreigner and KISA unique identification value) of the credit card holder through the credit card authentication.With the service, accurate personal information (name, date of birth, and gender) can be filled in during the sign-up, and it can be also checked if a person has already signed up using KISA’s unique identification value. In addition, if you provide age-restricted services, you can increase the user’s convenience if it is used together with the mobile authentication.

Information obtained after the authentication

After the credit card authentication is completed, the merchant can obtain and use the customer’s information. Merchants can obtain the following information.
  • Name(name)
  • Gender(gender)
  • Date of birth(birth)
  • Personal identification unique key(unique_key) : CI value issued from KISA
  • Unique identification key for each site(unique_in_site) : DI value from KISA

How to integrate

Through the following process, you can set up the Iamport credit card authentication service on your website and obtain the authentication result.
STEP1Add Iamport library
Add <script> lines below to the authentication HTML page. Since Iamport library is based on jQuery, jQuery 1.0 or higher must be included. Credit card authentication function is supported from Iamport JavaScript v1.1.7.
  <!-- jQuery -->
  <script type="text/javascript" src="https://code.jquery.com/jquery-1.12.4.min.js" ></script>
  <!-- iamport.payment.js -->
  <script type="text/javascript" src="https://cdn.iamport.kr/js/iamport.payment-1.1.8.js"></script>
STEP2Identify merchant
Put [Merchant ID](/implementation/account-info?lang=en) into the argument of IMP object init method and call it from the authentication page of the website. JavaScript
  var IMP = window.IMP; // Can be skipped.
  IMP.init("imp00000000"); // Replace "imp00000000" with the issued "Merchant ID".
In the code, a random number is used for the argument of init() function. Check Merchant ID in your Admin Dashboard and use it as the argument of the function.
STEP3Add code to call authentication window
Call IMP.certification(param, callback). The first argument of the function, param, can be used to configure for the authentication.

  • PC environment : A pop-up window opens and the credit card authentication screen appears. After authentication is completed, the callback function specified as the second argument is executed.
  • Mobile environment :
    • popup : false(default) : Existing page is redirected to the authentication page. After authentication is completed, you will be redirected back to m_redirect_url.
    • popup : true : Like PC environment, it is processed in a popup window. After authentication is completed, the callback function specified as the second argument is executed. (For an environment where a popup is blocked such as WebView, it is recommended to set popup : false
  // Call IMP.certification(param, callback)
  IMP.certification({ // param
    merchant_uid: "ORD20180131-0000011",
    m_redirect_url : "https://www.myservice.com/certifications/redirect", // Required if popup: false (default) in mobile environment
    popup : false // popup parameter is ignored in PC environment and always applied as true
  }, function (rsp) { // callback
    if (rsp.success) {
      ...,
      // Logic of successful authentication,
      ...
    } else {
      ...,
      // Logic on authentication failure,
      ...
    }
  });

IMP.certification param object properties

PropertyData typeDescriptionDefautMisc
merchant_uid
(supported from v1.1.7)
stringUnique order number created/managed by the merchantrandom(Optional) Internal order number related to the authentication
m_redirect_url
(supported from v1.1.7)
stringURL to be redirected after authentication in mobile environmentfalse(Optional) imp_uid, merchant_uid, success are passed as query string
popup
(Applied only to mobile environment. supported from v1.1.7)
booleanWhether to show authentication screen in a popup windowfalse(Optional) popup : true is forced for PC. For mobile, m_redirect_url must be specified when using popup : false
STEP4Pass the retrieved value (imp_uid) to the server
1If popup(true) in PC or mobile environment
If the authentication is successful (rsp.success: true) in the callback, write a logic to pass the imp_uid of rsp to the server.
  IMP.certification({
    /* ...code omitted here... */
  }, function (rsp) { // callback
    if (rsp.success) { // If the authentication succeeds
      // HTTP request using jQuery
      jQuery.ajax({
        url: "https://www.myservice.com/certifications", // Service web server
        method: "POST",
        headers: { "Content-Type": "application/json" },
        data: { imp_uid: rsp.imp_uid }
      });
    } else {
      alert("Authentication failed. Error: " +  rsp.error_msg);
    }
  });
If you pass imp_uid (unique number) to the merchant server, you can query the authentication information from the Iamport server with imp_uid. With queried information, you can acquire customer information and handle required logic.
2If popup(false) in mobile environment
When calling IMP.certification(), the page is 302 redirected to the URL specified in m_redirect_url with following query parameters.
  • imp_uid : Unique identifier in Iamport to authenticate with
  • merchant_uid : Unique merchant identifier to authenticate with
  • status : Whether the user authentication is successful. string type, true or false
GET {m_redirect_url}?imp_uid={}&merchant_uid={authenticating merchant_uid}&success={true or false}
m_redirect_url is set to the endpoint of the merchant server to acquire the imp_uid from the GET parameter, and the authentication information can be retrieved from the Iamport REST API.
STEP5Query the authentication information from the server
When the authentication completes, you can query the authentication information with with imp_uid, acquire customer information, and handle required logic.
1Create API endpoint
First, create an API endpoint that receives imp_uid from the server.
  app.use(bodyParser.json());
  ...
  // The controller to handle POST request for "/certifications": callback style 
  app.post("/certifications", async (request, response) => {
    const { imp_uid } = request.body; // Extract imp_uid from request body
  })
  ...
  // The controller to handle GET request for "/certifications/redirect": redirection style
  app.get("/certifications/redirect", async (request, response) => {
    const { imp_uid } = request.query; // Extract imp_uid from request query
  })
2Query authentication Information
Next, the authentication token is issued from https:\//api.iamport.kr/users/getToken using the REST API key and REST API Secret. Then, the authentication token and the extracted imp_uid are used to retrieve the payment information from https:\//api.iamport.kr/certifications/$imp_uid.
  app.use(bodyParser.json());
  ...
  // The controller to handle POST request for "/certifications"
  app.post("/certifications", async (request, response) => {
    const { imp_uid } = request.body; // Extract imp_uid from request body
    try {
      // Acquire access token
      const getToken = await axios({
        url: "https://api.iamport.kr/users/getToken",
        method: "post", // POST method
        headers: { "Content-Type": "application/json" }, // "Content-Type": "application/json"
        data: {
          imp_key: "imp_apikey", // REST API Key
          imp_secret: "ekKoeW8RyKuT0zgaZsUtXXTLQ4AhPFW3ZGseDA6bkA5lamv9OqDMnxyeB9wqOsuO9W3Mx9YSJ4dTqJ3f" // REST API Secret
        }
      });
      const { access_token } = getToken.data.response; // Authentication token
      ...
      // Query authentication information with imp_uid
      const getCertifications = await axios({
        url: \`https://api.iamport.kr/certifications/\${imp_uid}\`, // Pass imp_uid
        method: "get", // GET method
        headers: { "Authorization": access_token } // Append the authentication token to Authorization header
      });
      const certificationsInfo = getCertifications.data.response; // Retrieved authentication information
      ...
    } catch(e) {
      console.error(e);
    }
  });
In the code above, an authentication token was issued using the REST API Key and REST API Secret issued on Iamport account to retrieve payment information. The authentication token request was sent to https:\//api.iamport.kr/users/getToken using POST method, with application/json as Content-Type, imp_key: REST API key, and imp_secret: REST API Secret in the body.

When the server responses to the request, it stores the access_token, which is the authentication token included in the response data. Then, the URL https:\//api.iamport.kr/certifications/{imp_uid} was built with imp_uid, the issued authentication token access_token was added to Authorization, and finally the authentication information was queried by sending a request using GET method.
3Using authentication information
Extract customer information from the retrieved authentication information. Then, write the logic required in the service.
  // The controller to handle POST request for "/certifications"
  app.post("/certifications", async (request, response) => {
    const { imp_uid } = request.body; // Extract imp_uid from request body
    try {
      // Acquire access token
      /* ...code omitted here... */
      // Query authentication information with imp_uid
      /* ...code omitted here... */
      const certificationsInfo = getCertifications.data.response; // Retrieved authentication information
            // unique_key: Unique identifier for a person, unique_in_site: Unique identifier for a person for each site
      const { unique_key, unique_in_site, name, gender, birth } = certificationsInfo;
      ...
      // Age limit logic
      if (new Date(birth).getFullYear() <= 1999) {
        // Age satisfied
      } else {
        // Age not satisfied
      }
      ...
      // Logic to limit one account for one person
      // Query unique_key from the database and check if the user has already signed up
      Users.find({ certificationKey: unique_key })
      .then((user) => {
        if (!user) {
          // New user
        } else {
          // User already signed up
        }
      });
    } catch(e) {
      console.error(e);
    }
  });
Extract unique_key, unique_in_site, name, gender, and birth from the retrieved authentication information. If age restriction is required, birth information can be compared with the allowed age. If a "one person one account" policy is required, unique_key can be used to check if the person has already signed up.

The meaning of unique_key and unique_in_site

Even if there are multiple credit cards used for authentication, if the credit card holder is the same, unique_key and unique_in_site will be the same for every response.

The unique_key value is a CI value issued by KISA, and since it has a unique value for each individual, it can be used to identify/specify an individual instead of the social security number.

The unique_in_site value is also a DI value issued by KISA, which is unique within a service (site). Unlike unique_key, different values will be returned even for the same person if the service is different.