🛡ī¸PG window

Get a billing key through the payment window provided by the PG.

You can enter the card information through the PG's payment window to get a billing key.

  • Pros: no need to establish additional security process for transmitting card information because the data is transmitted directly to PG without going through the server or i'mport server.

  • Cons: cannot customize card registration form since billing key is requested through the PG's payment window via web browser (cannot implement merchant site friendly UI/UX).

STEP 01. Request billing key

As with authenticated payment, use the JavaScript SDK to call the PG's payment window. To get a billing key, specify the following additional parameters.

customer_uid: unique key that maps 1:1 with billing key

client-side
  IMP.request_pay({ // Refer to above mentioned PG specific guide for param settings
    customer_uid: "gildong_0001_1234", // Unique ID for each card (billing key)
    /* ...Omitted... */
  }, function (rsp) { // callback
    if (rsp.success) {
      // Billing key request successful
    } else {
      // Billing key request failed
    }
  });

What is a customer_uid?

It is a unique value specified by the merchant that maps 1:1 with the billing key issued by PG. A unique customer_uid must be created for each card.

Example: If a customer named Hong Gildong requests for a billing key from A card, the customer_uid must be issued for the specified member's credit card number

STEP 02. Handle response

client-side
  IMP.request_pay({ // param
    /* ...Omitted... */
  }, function (rsp) { // callback
    if (rsp.success) {
      // Billing key request successful
      // jQuery HTTP request
      jQuery.ajax({
        url: "{URL to receive customer-uid}", // Example: https://www.myservice.com/billings/
        method: "POST",
        headers: { "Content-Type": "application/json" },
        data: {
          customer_uid: "gildong_0001_1234", // Unique ID for each card (billing key)
        }
      });
    } else {
      // Billing key request failed
    }
  });

Once the billing key is issued successfully, the customer_uid is sent to the merchant server. The server creates an API endpoint that receives the customer_uid from the client. The server can use the customer_uid to request future payments.

server-side
  app.post("/billings", async (req, res) => {
    try {
      const { customer_uid } = req.body; // Get customer_uid from req.body

        ...
    } catch (e) {
      res.status(400).send(e);
    }
  });

Save the customer_uid in the merchant's database and use it to request future payments.

STEP 03. Request payment

Use the saved customer_uid and call the i'mport Non-authenticated payment (billing key) API to request payment.

To use the i'mport REST API, you must first get an access token.

server-side
app.post("/billings", async (req, res) => {
    try {
      const { customer_uid } = req.body; // Get customer_uid from req.body
      // Get billing key
      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; // Access token
      ...
      // Request payment (for first or nth time)
      const paymentResult = await axios({
        url: \`https://api.iamport.kr/subscribe/payments/again\`,
        method: "post",
        headers: { "Authorization": access_token }, // Add access token to authorization header
        data: {
          customer_uid,
          merchant_uid: "order_monthly_0001", // Order ID
          amount: 8900,
          name: "recurring payments for monthly subscription"
        }
      });
      ...
      const { code, message } = paymentResult;
      if (code === 0) { // Successful communication with the card company (additional check is required to confirm whether the payment was successful)
        if ( paymentResult.status === "paid" ) { // Payment approved
          res.send({ ... });
        } else { // Payment not approved (Example: card limit exceeded, card suspended, insufficient balance)
          // paymentResult.status: failed is returned
          res.send({ ... });
        }
        res.send({ ... });
      } else { // Card company rejected payment (paymentResult is null)
        res.send({ ... });
      }
    } catch (e) {
      res.status(400).send(e);
    }
  });

Last updated