🪧Subscription payment using billing key

Request subscription (scheduled) payments using the customer_uid.

subscriptionsubscriptionYou can use the customer_uid obtained through the Get billing key or Non-authenticated payment (one-time) API to request a subscription or scheduled payment.

STEP 01. Request payment

You can schedule a payment for a desired time in the future by using the ChaiPort Schedule payment API.

server-side

Node.js

// Schedule payment
  axios({
    url: \`https://api.iamport.kr/subscribe/payments/schedule\`,
    method: "post",
    headers: { "Authorization": access_token }, // Add access token to authorization header
    data: {
      customer_uid: "gildong_0001_1234", // Unique ID for each card (billing key)
      schedules: [
        {
          merchant_uid: "order_monthly_0001", // Order ID
          schedule_at: 1519862400, // Schedule time in UNIX timestamp.
          amount: 8900,
          name: "Recurring payment for monthly subscription",
          buyer_name: "Hong Gildong",
          buyer_tel: "01012345678",
          buyer_email: "[e-mail]"
        }
      ]
    }
  });

STEP 02. Receive payment result

When payment is attempted at the scheduled time, a webhook event occurs and the payment ID (imp_uid) and order ID (merchant_uid) are sent to the specified callback URL on the server. After receiving the payment result via webhook, you can complete the payment processing based on the result.

i'mport Webhook

For information about the i'mport Webhook and how to set the callback URL, refer to the i'mport webhook guide.

Node.js

server-side

// Process POST request to "/iamport-callback/schedule"
    app.post("/iamport-callback/schedule", async (req, res) => {
      try {
        const { imp_uid, merchant_uid } = req.body;
        // Get 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; // Access token
        // Get payment info from i'mport server using imp_uid
        const getPaymentData = await axios({
          url: \`https://api.iamport.kr/payments/\${imp_uid}\`, // Pass imp_uid
          method: "get", // GET method
          headers: { "Authorization": access_token } // Add access token to authorization header
        });
        const paymentData = getPaymentData.data.response; // Save payment info
        const { status } = paymentData;
        if (status === "paid") { // If payment is successful
          // Save payment info in DB
          await Orders.findByIdAndUpdate(merchant_uid, { $set: paymentData }); // Mongoose
          ...
        } else {
          // Retry payment
        }
      } catch (e) {
        res.status(400).send(e);
      }
    });

Recurring payment

To implement recurring payments, recursively schedule a payment to the i'mport server. When a payment is attempted at the scheduled time, a notification is sent to the server through the webhook URL.

Node.js

server-side

    // Process POST request to "/iamport-callback/schedule"
    app.post("/iamport-callback/schedule", async (req, res) => {
      try {
        const { imp_uid, merchant_uid } = req.body;
        // Get access token
        /* ...Omitted ... */
        // Get payment info from i'mport server using imp_uid
        /* ...Omitted ... */
        const paymentData = getPaymentData.data.response; // Save payment info
        const { status } = paymentData;
        if (status === "paid") { // If payment is successful
          // Save payment info in DB
          await Orders.findByIdAndUpdate(merchant_uid, { $set: paymentData }); // Mongoose
          ...
          // Schedule next payment
          axios({
            url: "{URL to receive payment schedule}", // Example: https://api.iamport.kr/subscribe/payments/schedule
            method: "post",
            headers: { "Authorization": access_token }, // Add access token to authorization header
            data: {
              customer_uid: "gildong_0001_1234", // Unique ID for each card (billing key)
              schedules: [
                {
                  merchant_uid: "order_monthly_0001", // Order ID
                  schedule_at: 1519516800, // Schedule time in UNIX timestamp.
                  amount: 8900,
                  name: "Recurring payment for monthly subscription",
                  ...
                }
              ]
            }
          });
        } else {
          // Retry payment
        }
      } catch (e) {
        res.status(400).send(e);
      }
    });

The above example processes the webhook event that occurs when a scheduled payment is attempted. If the scheduled payment is completed successfully, the payment information is saved in the database and the next payment is scheduled.