Integrate with Mobile Authentication


The mobile authentication service is a service that verifies the identity of the user and the accuracy of the information entered through an authentication process that takes the minimum personal information using a personal mobile phone.When a customer attempts to authenticate for signing up for a website or for payment, a mobile authentication window appears, and the customer’s authentication information (name, date of birth, and mobile phone number) is entered. After that, by entering the authentication number in a received text message, it will authenticate whether the customer owns the mobile phone. The customers can verify their identity through the 2-step verification, and the merchant can identify the customer.

Merchants can use the mobile authentication service in many ways. For example, if you only need to create one account per person, or if you need to set age limits for each product or service, you can check the date of birth to determine whether to allow it.

Information obtained after the authentication

After the mobile 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)
  • Unique identification key for each site(unique_in_site)
In addition to the above information, it is possible to obtain a mobile phone number(phone), a carrier(carrier), or whether the customer is a foreigner(foreigner) (after posting the terms and conditions of the agreement to collect and use personal information on the site, you can obtain it by applying to cs@iamport.kr).

How to integrate

Through the following process, you can set up the Iamport mobile authentication service on your website and obtain the authentication result.
STEP1Add Iamport library
Add <script> lines below to the payment HTML page. Since Iamport library is based on jQuery, jQuery 1.0 or higher must be installed. Mobile authentication function is supported from Iamport JavaScript v1.1.4.
  <!-- 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.
  // Call IMP.certification(param, callback) 
  IMP.certification({ // param
    merchant_uid: "ORD20180131-0000011"
  }, 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.4)
stringUnique order number created/managed by the merchantrandom(Optional) Internal order number related to the authentication
min_age
(supported from v1.1.4)
numberMinimum allowed international ageundefined(Optional) Use the age considering the date of birthFor example, if June 1, 1992 is your birthday and you try the authentication on May 1, 2018 (25 years old), it succeeds with min_age: 25, but it fails with min_age: 26.
name
(supported from v1.1.4)
stringName to authenticate(Optional) Automatically fill in the name field on the authentication screen
phone
(supported from v1.1.4)
stringPhone number to authenticate(Optional) Automatically fill in the phone number field on the authentication screen Specify any valid number such as 010-1234-1234 or 01012341234. (Delimiters such as - and . are allowed in the number.)
carrier
(supported from v1.1.4)
stringCarrier to authenticate(Optional) When entering the user authentication screen, restrict the selection to only specified carriers. Choose one of the following four:
  • SKT : SKT
  • KT : KTF
  • LGU+ : LGT
  • Mobile virtual network operator : MVNO

birth
(supported from v1.1.4)
stringDate of birth for the authenticationDanal does not support this parameter anymore
(Optional) Automatically fill in the date of birth field on the authentication screen. Since Iamport removes any non-numeric values in accordance with the policy of mobile carriers, it accepts any string containing 8 digits in YYYYMMDD format of date-of-birth, such as 19821231 or 1982-12-31.
company
(supported from v1.1.4)
stringService domain URL or namefalse(Optional) It is not a parameter that affects the authentication behavior, but it is recommended to work with KISA’s ePrivacy Clean service.
For merchant’s development convenience, Iamport automatically specifies the URL domain where IMP.certification() is called. However, if IMP.certification() is called through local HTML from the app, such as ReactNative / Ionic, the URL domain cannot be recognized, so this parameter is recommended to be specified. (If not specified, Iamport is passed)
You can specify the URL of the representative domain of your service (e.g. https://www.iamport.co.kr) or the name of the service (e.g. Iamport)
popup
(supported from v1.1.6)
booleanWhether to show authentication screen in a popup windowfalse(Optional) By default, the authentication screen is displayed on the top layer of the existing screen. Set to true to open the authentication screen in a new window.
STEP4Pass the retrieved value (imp_uid) to the server
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
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"
  app.post("/certifications", async (request, response) => {
    const { imp_uid } = request.body; // Extract imp_uid from request body
  })
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

unique_key value is a unique personal identification key assigned to each individual. Instead of using the personal information of the mobile phone number as the key value, the customer can be identified with a unique identification key that corresponds 1:1 to the mobile phone number.

unique_in_site value is a unique personal identification key for each site. It is a unique key to identify a customer that is also unique across the site.