Iamport Webhook

By using Iamport Webhook, you can synchronize the data stored in Iamport server to your server and make up for network instability.

What is Webhook?

Webhook is a concept that notifies an event through HTTP POST when a certain operation has been performed on the server. Web applications that implement Webhook create a POST request to the URL when a specific operation is executed. At this point, the web application users can specify their own URL (callback URL).

From the user’s point of view, they can be notified by Webhook only when important events occur, instead of constantly polling data to receive unnecessary information in most cases. It can be used to integrate with the user’s custom functions or other applications. It can also be used to extend existing features.

Iamport webhook is called when:

a payment is approved (all payment methods) - (status: paid)
a virtual account is issued
- (status: ready)
a payment is made in the virtual account
- (status: paid)
a scheduled payment is attempted
- (status: paid or failed)
a refund is made on Dashboard
- (status: cancelled)

Webhook is called, the following POST request is generated to the defined callback URL.

cURL

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

When calling Webhook, imp_uid, merchant_uid, and status attributes are included in the body of the POST request that is generated by Webhook. imp_uid is the Iamport order number, merchant_uid is the merchant order number, and status is the payment result.

After checking payment information through Iamport REST API using imp_uid and merchant_uid that were received from the callback URL, the data can be synchronized to the merchant server.

Set callback URL

When Iamport webhook is called, the callback URL to be notified of payment information can be set in "Notification URL for Payment" field at the bottom of System Settings > PG Link Settings page in Iamport Dashboard. You can enter the url of HTTP request and specify Content-Type as application/json or application/x-www-form-urlencoded.

Changes in the payment flow

For convenient payment integration, Iamport takes over the role of the merchant server that had to communicate directly with the PG server so far. There was a limitation in the development environment supported by PG for direct communication with their servers. It also had to handle complicated process such as compile and installation of PG modules on the merchant servers. Iamport, on the other hand, provides easy and convenient way to integrate the payment through simple standard attributes and REST API without any of the complexities.

However, as the flow of payment changes with Iamport, the method of synchronizing the payment data in merchant server will also change. When payment is made, payment data is first stored in Iamport database, and then payment information is stored in merchant database through Webhook or browser redirection.

1Direct integration with PG module

If the merchant has direct integration with PG module, the flow is as shown in the diagram above. First, the customer browser sends order and card authentication information to the merchant server through the order page. After that, the merchant server requests payment by sending order and card authentication information to the PG server. PG sends the received information to the card company, requests payment approval, and responds to the merchant server with the approval result. The merchant server stores the approval result received from the PG company in the merchant database. The transaction results are then displayed in the customer’s browser.

2Payment integration with Iamport

If the merchant accepts the payment through Iamport, the flow is as shown in the diagram above. First, the customer browser sends order and card authentication information to the Iamport server through the order page. After that, the Iamport server requests payment by sending order and card authentication information to the PG server. PG sends the received information to the card company, requests payment approval, and responds to the Iamport server with the approval result. Iamport server stores the approval result received from PG in Iamport database.

After that, the Iamport server calls Webhook to deliver payment information to the merchant server. It then generates a 302 redirect response (Location: m_redirect_url) in the customer’s browser. Then, when the callback of the customer’s browser is executed or redirected to m_redirect_url, payment information is transmitted to the merchant server. The merchant that received the payment information through two paths stores transaction information in the merchant database using the received information.

Utilizing Webhook

You can utilize Iamport Webhook as follows.

1Making up for the possibility of losing payment data

There could be a case where the customer’s browser receives a 302 redirect response (Location: m_redirect_url) from the Iamport server, but the generation of a GET request for the url fails due to network instability in customer’s payment device or the sudden termination of the browser. Therefore, it is possible to prevent the loss of data synchronization through payment information received from the Iamport server by utilizing Webhook.

2Notification for payment on a virtual account

If a virtual account is used as a payment method, it is necessary to update the merchant database that the payment has been made, at some point in the future after issuing the virtual account. Iamport Webhook can be used to automate the update of payment. Since it is called when the payment amount is transferred, It is possible to synchronize the merchant database after receiving payment information from the callback URL and ensure if the payment is made on the virtual account by checking the payment status.

3Handle the scheduled payment (regular payment)

You can use Iamport REST API, /subscribe/payments/schedule, to schedule payments at a future time. When the scheduled payment is attempted, Webhook is called to deliver payment information to callback URL. At this point, the merchant checks whether the payment was successful through the received payment information. If payment is successful, regular payments can be scheduled by setting up the next payment.

How to implement Webhook

You can find the implementation method from Set up Webhook and data synchronization in Implementing General Payments document about how to make up for the possibility of losing payment data and getting the notification for payment on a virtual account.

You can find how to implement handling of the scheduled payment from Schedule a payment in Implementing General Payments document.

Verifying the request

The endpoint in the merchant server processes the request created when Iamport Webhook is called. Because the endpoint is a public URL, you must make sure that the client of the request is Iamport. To verify the request, you can compare the IP address of the requesting client matches the IP address of Iamport

When Webhook is called, Iamport creates a request from the following two fixed IP addresses. - 52.78.100.19 - 52.78.48.223Therefore, at the endpoint that handles the request generated by calling Webhook, it is possible to determine whether the request was from Iamport by comparing the IP address of the requester with one of two addresses above. It must be ignored if requester’s IP address does not match either of the two above.

Can a new IP address be added?

Iamport uses a NAT gateway, and the IP address of Webhook request is fixed to the two addresses above. The IP addresses will remain fixed even if new servers are added.