LogoLogo
  • 🧩i'mport Payment Integration Docs
    • 🚗GET STARTED
  • 🛫Setup
    • 🖥️1. Create an account
    • 🧷2. Set up PG
      • 🏢Payment gateway settings
        • ⌨️NHN KCP
        • ⌨️KG INICIS
        • ⌨️NICE Payments
        • ⌨️Toss Payments
        • ⌨️KICC
        • ⌨️Paymentwall
        • ⌨️Daou
        • ⌨️다날 설정
        • ⌨️JTNET 설정
        • ⌨️세틀뱅크 설정
        • ⌨️KG모빌리언스 설정
        • ⌨️스마트로 설정
        • ⌨️페이팔 설정
        • ⌨️엑심베이 설정
        • ⌨️블루월넛 설정
      • ⛺간편 결제사
        • ⌨️카카오페이 설정
        • ⌨️토스간편결제 설정
        • ⌨️네이버페이(결제형) 설정
        • ⌨️페이코 설정
        • ⌨️차이 설정
        • ⌨️알리페이 설정
    • ✔️3. Check required info
  • Payment window
    • 🖥️Authenticated payment
      • 📒Definition
      • 🌠1. Add i'mport library
      • 💡2. Initialize IMP object
      • 🪧3. Request payment
      • 🎁4. Process payment result
        • 🪟Iframe method
        • 🖼️Redirect method
      • 🔦5. Verify payment information
      • 🛬6. Complete payment
    • ⏰Non-authenticated payment
      • 🏍️Request billing key payment
        • 🖱️REST API
        • 🛡️PG window
      • 💳Key-in payment using card info
      • 🪧Subscription payment using billing key
    • 💸Payment cancellation (refund)
      • 💷Virtual account refund
  • Payment result
    • ⚒️Set up a webhook
  • Other Services
    • 📱Mobile identity verification
      • 📔1. Prepare for verification
      • 🥏2. Request verification
      • 🚚3. Send verification result
      • 🤹4. Get verification info
    • 🚚Integrated identity verification
      • 📒Prepare for verification
      • 🥏Request verification
      • 🚚Send verification result
      • 🤹Get verification info
    • 💳Credit card identity verification
      • 📒1. Prepare for verification
      • 🥏2. Request verification
      • 🚚3. Send verification result
      • 🤹4. Get verification info
    • 💻Generate payment URL
    • 🛩️Integrate budget handler
    • 📟Native mobile SDKs
  • TIPS
    • 🌽Tax exemption on payments
    • ✅Service launch checklist
    • 🔏Confirm Process
    • 🎼i'mport payment flow
    • 🎈Agency & Tier
    • 📦Billing key issuance by PG
    • 🏦Bank codes by PG
    • 🧾PG codes
    • 🚚Courier codes
    • 🪧What is redirection?
    • 📰PG error codes
  • Admin console
    • 🎡Admin console guide
      • Apply for online payment
      • My ID & API keys
      • Manage admin & sub-merchant accounts
      • Integrate payment
      • Payment activity
    • 💻Integrating Multiple PGs
  • API
    • 📋i'mport API overview
    • 🖇️REST API Access Token
    • 💳Payment API
      • ⌨️Cancel payment API
      • ⌨️Get payment API
      • ⌨️Get payments API
      • ⌨️Get payments by status API
      • ⌨️Get payments by order ID, status (All)
      • ⌨️Get payments by order ID, status (Top 1)
      • ⌨️Get balance API (for split payment transaction)
      • ⌨️Get payments by billing key API
      • ⌨️Save payment amount API
      • ⌨️Update payment amount API
      • ⌨️Get payment amount API
    • 📝Billing key API
      • ⌨️Request billing key API
      • ⌨️Delete billing key API
      • ⌨️Get billing key API
      • ⌨️Get billing keys API
      • ⌨️Get scheduled payments API
    • 🧭Subscription payment API
      • ⌨️Schedule payment API
      • ⌨️Cancel scheduled payment API
      • ⌨️Get scheduled payments API
      • ⌨️Get scheduled payment API
      • ⌨️Get scheduled payments by billing key API
    • 🪂Non-authenticated payment API
      • ⌨️Request non-authenticated payment (billing key) API
      • ⌨️Request non-authenticated payment (one-time) API
    • 🇺🇲🇺🇲 Overseas PG API
      • ⌨️Paymentwall delivery API
    • 👮‍♂️👮♂ Identity verification API
      • ⌨️Get identity verification result API
      • ⌨️Delete identity verification API
      • ⌨️Request identity verification API
      • ⌨️Confirm identity verification API
    • 🎫Simple payment service API
      • 🧽Kakao Pay
        • ⌨️Get order API
      • 🛩️KCP Quick Pay
        • ⌨️Delete user API
      • 🧰PAYCO
        • ⌨️Update order status API
      • 📗Naver Pay
        • ⌨️Confirm escrow order API
        • ⌨️Accrue points API
        • ⌨️Get cash receipt amount API
    • 🏦Escrow API
      • ⌨️Get delivery info API
      • ⌨️Add delivery info API
      • ⌨️Update delivery info API
    • 💵Cash receipt API
      • ⌨️Cancel cash receipt transaction API
      • ⌨️Get cash receipt API
      • ⌨️Request cash receipt API
      • ⌨️Cancel cash receipt (external) API
      • ⌨️Get cash receipt (external) API
      • ⌨️Request cash receipt (external) API
    • 🏛️Virtual account API
      • ⌨️Request virtual account API
      • ⌨️Cancel virtual account API
      • ⌨️Update virtual account API
      • ⌨️Get account holder API
    • 🍶Miscellaneous API
      • 🎽Benepia point
        • ⌨️Get points API
        • ⌨️Request point payment API
      • 🏪Convenience store payment
        • ⌨️Request barcode API
        • ⌨️Cancel barcode API
      • 🗃️Financial institution codes
        • ⌨️Get credit card codes (All) API
        • ⌨️Get credit card name API
        • ⌨️Get bank codes (All) API
        • ⌨️Get bank name API
      • 🛖PG information
        • ⌨️Get PG MIDs API
  • SDK
    • 📚Javascript SDK
      • 💿Payment request parameters
      • 📀Payment response parameters
      • 💿Identity verification request parameters
      • 📀Identity verification response parameters
      • ✏️SDK Release Notes
  • FAQ
    • ⁉️FAQ
  • 🔑Payment integration by PG
    • 🏢Payment gateways
      • ⌨️NHH KCP
      • ⌨️KG INICIS
      • ⌨️Toss Payments
      • ⌨️NICE Payments
      • ⌨️KICC
      • ⌨️Daou (PAYJOA)
        • 📍Precautions for using PAYJOA
      • ⌨️KG Mobilians
      • ⌨️Paymentwall
      • ⌨️Danal
      • ⌨️Settlebank
      • ⌨️JTNET
      • ⌨️Smartro
      • ⌨️PayPal
      • ⌨️Eximbay
      • ⌨️Blue Walnut
    • ⛺Simple payments
      • ⌨️Naver Pay (Standard)
      • ⌨️Kakao Pay
      • ⌨️PAYCO
      • ⌨️Alipay
      • ⌨️Toss
  • Korean Integration Docs
Powered by GitBook
On this page
  1. Payment result

Set up a webhook

Set up a webhook to handle the payment result in a reliable way.

PreviousVirtual account refundNextMobile identity verification

Last updated 2 years ago

Use the i'mport webhook to synchronize payment information on the i'mport server with the merchant server to compensate for data loss due to device or network instability.

What is a webhook?

A webhook is a mechanism for sending notifications to other services or applications when a specific event occurs. The webhook provider sends event information to the callback URL (endpoint) by creating an HTTP POST request when the event occurs. Webhooks are much more efficient in terms of resources and communication as they can only receive information related to desired events without polling data periodically. Using webhooks, you can extend functionality by integrating with custom functions or other applications.

Is webhook integration required?

When the i'mport server sends a response to the client, the client may not receive the response after the payment process is complete for reasons, such as Wi-Fi disconnection or automatic browser reload. In this case, the i'mport server sends a webhook event to the server so that the payment information can be synchronized.

i'mport webhook is called when:

  • Payment is approved (all payment methods) (status : paid)

  • Virtual account is issued (status : ready)

  • Payment is deposited into virtual account (status : paid)

  • Scheduled payment is attempted (status : paid or failed)

  • Refund is processed from Admin console (status : cancelled)

A webhook is not invoked when payment fails!

Webhook URL can be set in the following two ways:

Content-Type can be specified as application/json or application/x-www-form-urlencoded. To test the URL, click the Test Webhook button to the right of the Notification URL field.

Set the notice_url parameter when calling the JavaScript SDK request_pay function to receive a webhook notification. Use this method to specify a different webhook URL for each payment request.

(If this parameter is specified, the Admin console's webhook setting is ignored.)

client-side
function requestPay() {
    // IMP.request_pay(param, callback) call payment window
    IMP.request_pay({
        ...            // Omitted
        notice_url : 'https://Webhook URL',   // Set Webhook URL
        ...            // Omitted
    }, function (rsp) { // callback
        if (rsp.success) {
            console.log(rsp);
        } else {
            console.log(rsp);
        }
    });
}

You cannot set multiple webhook URLs.

Verify webhook request

Since an i'mport webhook endpoint is a public URL, you must verify that the request's client IP is an i'mport IP. An i'mport webhook request must originate from one of the following static IPs.

  • 52.78.100.19

  • 52.78.48.223

  • 52.78.5.241 (when invoked via Test Webhook button)

When a webhook event is called, the following POST request is generated for the notification URL endpoint.

curl -H "Content-Type: application/json" -X POST -d '{ "imp_uid": "imp_1234567890", "merchant_uid": "order_id_8237352", "status": "paid" }' { NotificationURL }

The body of the webhook POST request contains the following information. The server can get the information and use it to query the payment information from the i'mport server and verify and store the payment information.

  • imp_uid: payment ID

  • merchant_uid: order ID

  • status: payment result

Sample code of receiving a POST request to webhook endpoint URL

Create an endpoint to receive the webhook event's POST request as follows and then parse, verify, and save the payment information.

server-side
app.use(bodyParser.json());
  ...
  // Route POST request to "/iamport-webhook"
  app.post("/iamport-webhook", async (req, res) => {
    try {
        const { imp_uid, merchant_uid } = req.body; // Get imp_uid and merchant_uid from 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
        ...
        // Query for original requested amount from the database
        const order = await Orders.findById(paymentData.merchant_uid);
        const amountToBePaid = order.amount; // Original requested amount
        ...
        // Verify payment amount
        const { amount, status } = paymentData;
        if (amount === amountToBePaid) { // Amounts match. Processed amount === Original requested amount
          await Orders.findByIdAndUpdate(merchant_uid, { $set: paymentData }); // Save payment info in DB
          switch (status) {
            case "ready": // Issue virtual account
              // Save virtual account info in DB
              const { vbank_num, vbank_date, vbank_name } = paymentData;
              await Users.findByIdAndUpdate("/* customer id */", { $set: { vbank_num, vbank_date, vbank_name }});
              // Send virtual account issuance text message
              SMS.send({ text: \`Virtual account has been issued. Account information \${vbank_num} \${vbank_date} \${vbank_name}\`});
              res.send({ status: "vbankIssued", message: "Virtual account issued successfully" });
              break;
            case "paid": // Payment complete
              res.send({ status: "success", message: "Payment successful." });
              break;
          }
        } else { // Amount mismatch. Forged/falsified payment.
          throw { status: "forgery", message: "Forged/falsified payment attempted" };
        }
    } catch (e) {
      res.status(400).send(e);
    }
  });

i'mport does not guarantee the order of payment information delivery

Can you re-send a webhook?

By default, a webhook can only be sent once. However, it can be re-sent up to 5 times as per merchant's request. Webhooks are re-sent every 1 minute until a successful response is received from the merchant (up to 5 times).

To set the webhook's notification URL to send the payment information to, log in to the Admin console and then go to tab and set the URL in the Endpoint URL field to receive the webhook data.

In general, after i'mport server calls webhook, it does not guarantee the order in which the payment information arrives at the server. This is because i'mport sends a 302 redirect response to the client without waiting for a webhook response from the server. However, you can submit a special request to configure i'mport to wait for a webhook response before sending a 302 redirect or callback response to the client so that the server always receives payment information from i'mport first. To make a request to guarantee the prioritized delivery of webhooks, contact with the merchant ID.

⚒️
Payments->Live Settings
support@iamport.kr