This documentation is deprecated and no longer maintained. For the most up-to-date information, Please visit   docs.portone.cloud.

Nhảy tới nội dung

Webhook Integration

Webhooks refers to a combination of elements that collectively create a notification and reaction system within a larger integration. PortOne uses webhooks to notify your application when an event happens in your account. Webhooks are particularly useful for asynchronous events like when the status of a payment transaction gets updated.

Webhook Configuration#

  • Create a webhook endpoint on your server with POST method.
  • Register the webhook endpoint on PortOne Merchant portal in API Settings > Webhooks.

PortOne Webhooks#

Currently following webhook types are supported on PortOne

PAYIN - Payment Status Update#

This webhook gets triggered whenever the status of the payment transaction gets updated at payment channel's end. Refer following sample payload received in Webhooks.

{
"currency": "USD",
"amount": 500,
"order_ref": "2mbbExY77pp8iC0AQ1ucWymnd3c",
"channel_order_ref": "20240926HULUNYGP6MA2",
"merchant_order_ref": "2mbbDi9wX3wAgLUDCnRMbQwkwZm_1",
"country_code": "US",
"status": "Success",
"channel_key": "PAYLETTER",
"method_name": "Payletter Credit Card",
"method_key": "PAYLETTER_CREDIT_CARD",
"method_sub_type": "INT_CREDIT_CARD",
"buyer_name": "N K",
"buyer_email": "nitesh@portone.io",
"buyer_phone": "+919089797890",
"buyer_address1": "address",
"buyer_address2": "address_2",
"buyer_city": "City",
"buyer_country": "US",
"signature_hash": "lSzZqm8I4G46b4nDtCqSUQ5/YgAhWn+IsFU893hciFM=",
"status_code": "2000",
"status_reason": "SUCCESS",
"status_channel_reason": "SUCCESS | Transaction is success",
"created_at": "2024-09-26 10:55:14.573735 +0000 UTC",
"is_refund_allowed": true,
"is_multi_refund_allowed": true,
"user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/129.0.0.0 Safari/537.36",
"description": "Test payment",
"ip_address": "103.23.238.249",
"link_order_ref": "54A42644707B254",
"payment_link_ref": "2mbbDODqt4ZojDHa14IaiYwM4AM",
"source": "checkout",
"payment_method_used": "테스트카드 | ************4242",
"merchant_name": "ShopCity",
"merchant_key": "qcFJvupbcbdcyNFg",
"merchant_email_address": "nitesh@portone.io",
"channel_name": "PAYLETTER",
"environment": "sandbox",
"user_message": "The transaction is successful.",
"receipt_url": "https://test-merchant.payletter.com/Receipt/OpenReceipt?id=5061796d656e74323031352334215061796c6574746572504f518a125381e51a6fe576e2d9bb88e0f5d9930060ebb3043d158a0afe8d779574a6a13c0544\u0026pgcode=PL",
"masked_card_number": "************4242",
"cross_border_data": {},
"additional_payment_details": {},
"installment_details": {}
}

Merchant will receive the following data as webhook response after payment completion:

Parameter list#

amount#
float64#

The amount of the transaction

currency#
string#

The currency of the transaction

merchant_order_ref#
string#

Order Reference sent by merchant to initiate transaction

order_ref#
string#

PortOne's Order Reference, used further for refund and other disputes

channel_order_ref#
string#

Payment Channel's Order Reference for the transaction

payment_link_ref#
string#

Payment Link's Order Reference

link_order_ref#
string#

Order Reference sent by merchant to initiate payment link

country_code#
string#

The country code of the transaction

user_message#
string#

The user message of the transaction

status#
string#

The current status of the transaction

status_channel_reason#
string#

The reason given by the PSP for the status

status_code#
string#

The status code of the transaction

status_reason#
string#

The reason for the transaction status

signature_hash#
string#

Calculate hash as mentioned at [Hash Generation Reference], verify if it is equal to signature_hash

buyer_address1#
string#

The primary address of the buyer

buyer_address2#
string#

The secondary address of the buyer

buyer_city#
string#

The city of the buyer

buyer_country#
string#

The country code of the buyer

buyer_email#
string#

The email address of the buyer

buyer_name#
string#

The name of the buyer

buyer_phone#
string#

The phone number of the buyer

channel_key#
string#

The key of the payment channel

channel_name#
string#

The name of the payment channel

method_key#
string#

The key of the payment method used for the transaction

method_name#
string#

The name of the payment method used for the transaction

method_sub_type#
string#

The sub type of the payment method used for the transaction

merchant_key#
string#

The key of the merchant

merchant_name#
string#

The name of the merchant

merchant_email_address#
string#

The email address of the merchant

source#
string#

The source of the transaction

ip_address#
string#

The IP address of the buyer

user_agent#
string#

The user agent of the transaction

created_at#
string#

The date and time when the transaction was created

is_refund_allowed#
boolean#

Whether refund is allowed for the transaction

is_multi_refund_allowed#
boolean#

Whether multiple refunds are allowed for the transaction

environment#
string#

The environment of the transaction

description#
string#

The description of the transaction

payment_method_used#
string#

The payment method used for the transaction

receipt_url#
string#

The URL of the receipt of the transaction

masked_card_number#
string#

The masked card number of the transaction

cross_border_data#
object#

The cross border data of the transaction provided by the payment channel

additional_payment_details#
object#

The additional data of the transaction provided by the payment channel

installment_details#
object#

The installment details of the transaction provided by the payment channel

PAYIN - Refund Status Update#

This webhook gets triggered whenever the status of the refund transaction gets updated at the payment channel's end. Refer following sample payload received in Webhooks.

{
"refund_date": "2024-09-26 10:42:24.650023 +0000 UTC",
"refund_id": "oKYR4vZ7ddvEAbfm9U9w2c",
"psp_refund_id": "281m16unk3u60obtagljvxhyn",
"amount": 500,
"currency": "JPY",
"refund_status": "SUCCESS",
"refund_type": "full",
"refund_reason": "duplicate",
"merchant_id": "6539",
"description": "Refund for transaction oKYR4vZ7ddvEAbfm9U9w2c",
"payment_txn_ref": "2mbZeehV4ZhkLTwVcL2fHukBg4J",
"payment_channel": "KOMOJU",
"payment_method": "Alipay wallet via KOMOJU"
}

Merchant will receive the following data as webhook response after a successful refund:

Parameter list#

refund_date#
string#

The date and time when the refund was created

refund_id#
string#

The unique ID of the refund provided by merchant

psp_refund_id#
string#

The unique ID of the refund provided by PSP

amount#
float64#

The amount of the refund transaction

currency#
string#

The currency of the refund transaction

refund_status#
string#

The status of the refund transaction

refund_type#
string#

The type of the refund full or partial

refund_reason#
string#

The reason of the refund

merchant_id#
string#

Order Reference sent by merchant to initiate transaction

description#
string#

The description of the refund

payment_txn_ref#
string#

The payment transaction reference of the refund

payment_channel#
string#

The payment channel of the refund transaction

payment_method#
string#

The payment method of the refund transaction

PAYIN - Payment Link Status Update#

This webhook gets triggered whenever the status of the payment link gets updated at the payment channel's end. Refer following sample payload received in Webhooks.

{
"link_ref": "2mbaHZ6VVokmHJNtKafVCyIZIxv",
"link": "https://checkout.portone.cloud?ref=2mbaHZ6VVokmHJNtKafVCyIZIxv",
"currency": "JPY",
"amount": 500,
"countryCode": "JP",
"chaipaykey": "qcFJvupbcbdcyNFg",
"status": "Success",
"success_url": "https://checkout.portone.cloud/success.html",
"cancel_url": "https://checkout.portone.cloud/failure.html",
"merchant_order_ref": "1779AA6E40071177",
"is_billing_shipping_same": false,
"merchant_name": "ShopCity",
"merchant_logo": "",
"merchant_back_url": "https://admin.portone.cloud",
"merchant_shipping_charges": 0,
"merchant_promo_code": "NA",
"merchant_promo_discount": 0,
"user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/129.0.0.0 Safari/537.36",
"ip_address": "103.23.238.249",
"expiry_hours": 48,
"created_at": "2024-09-26T10:47:22.372093Z",
"source": "default",
"description": "Payment for Order: 1779AA6E40071177",
"mobile_redirect_url": "",
"show_shipping_details": false,
"show_back_button": true,
"default_guest_checkout": false,
"is_checkout_embed": false,
"notify_by_email": true,
"notify_by_phone": true,
"show_items": true,
"merchant_key": "qcFJvupbcbdcyNFg",
"merchant_email_address": "nitesh@portone.io",
"customer_name": "Nitesh",
"customer_email_address": "nitesh@portone.io",
"customer_phone_number": "+819870987690",
"payment_page_ref": "",
"unit_amount": 0,
"stock_quantity": 0,
"signature_hash": "OEsM7zzpWbZRN/IHJLyqSnZqrF09DrMAv/I9dn1aZHM=",
"show_saved_cards": true,
"portone_key": "qcFJvupbcbdcyNFg",
"user_configured_field1": "",
"user_configured_field2": "",
"user_configured_field3": "",
"user_configured_field4": "",
"user_configured_field5": ""
}

Merchant will receive the following data as webhook response after a successful payment link status update:

Parameter list#

link_ref#
string#

The unique ID of the payment link provided by merchant

link#
string#

The link of the payment link provided by merchant used for payment

status#
string#

The status of the payment link

amount#
float64#

The amount of the transaction

currency#
string#

The currency of the transaction

chaipaykey#
string#

The key provided by Portone

countryCode#
string#

The country code of the transaction

success_url#
string#

The success URL of the merchant

cancel_url#
string#

The cancel URL of the merchant

merchant_order_ref#
string#

Order Reference sent by merchant to initiate transaction

is_billing_shipping_same#
boolean#

If billing and shipping address are same or not

merchant_key#
string#

The key of the merchant

merchant_name#
string#

The name of the merchant

merchant_logo#
string#

The logo of the merchant

merchant_back_url#
string#

The back URL of the merchant

merchant_shipping_charges#
float64#

The shipping charges of the merchant

merchant_promo_code#
string#

The promo code of the merchant

merchant_promo_discount#
float64#

The promo discount of the merchant

user_agent#
string#

The user agent of the merchant

ip_address#
string#

The IP address of the merchant

expiry_hours#
integer#

The expiry hours of the payment link

created_at#
string#

Time of creation of the payment link

source#
string#

The source of the payment link

description#
string#

The description of the payment link

mobile_redirect_url#
string#

The mobile redirect URL of the payment link

show_shipping_details#
boolean#

The show shipping details of the payment link

show_back_button#
boolean#

The show back button flag of the payment link

default_guest_checkout#
boolean#

The defaultguest checkout flag of the payment link

is_checkout_embed#
boolean#

The ischeckout embed flag of the payment link

notify_by_email#
boolean#

The notify by email of the payment link

notify_by_phone#
boolean#

The notify by phone of the payment link

show_items#
boolean#

The show items of the payment link

merchant_email_address#
string#

The email address of the merchant

customer_name#
string#

The name of the customer

customer_email_address#
string#

The email address of the customer

customer_phone_number#
string#

The phone number of the customer

payment_page_ref#
string#

The payment page ref of the payment link

signature_hash#
string#

The signature hash of the payment link

unit_amount#
float64#

The unit amount of the payment link

stock_quantity#
integer#

The stock quantity of the item

show_saved_cards#
boolean#

The show saved cards of the payment link

portone_key#
string#

The key provided by PortOne

user_configured_field1#
string#

The user configured field 1

user_configured_field2#
string#

The user configured field 2

user_configured_field3#
string#

The user configured field 3

user_configured_field4#
string#

The user configured field 4

user_configured_field5#
string#

The user configured field 5

PAYIN - Subscription Status Update#

This webhook gets triggered whenever the status of the payment subscription gets updated at payment channel's end. Refer following sample payload received in Webhooks.

{
"allow_accumulate": "N",
"recurring_amount": 103,
"chaipaykey": "qcFJvupbcbdcyNFg",
"currency": "VND",
"customer_email_address": "nitesh@portone.io",
"customer_name": "Nitesh",
"customer_phone_number": "+916367890986",
"environment": "sandbox",
"frequency": 1,
"expired_at": "2024-10-01T11:58:40.007Z",
"link": "https://subscription.portone.cloud/?ref=2mbiztAoKWCBpciTKJiqKLjHu7A",
"merchant_order_ref": "Subscription_1727351941734",
"name": "Test - Plan - Ondemand",
"notify_by_email": false,
"notify_by_phone": false,
"order_ref": "2mbiztAoKWCBpciTKJiqKLjHu7A",
"plan_order_ref": "2mbiB58OfN2ZGbLw6zJRaJ4jBJ0",
"period": "H",
"quantity": 1,
"recurrance_count": 4,
"source": "checkout",
"started_at": "2024-09-26T11:59:01.987138Z",
"created_at": "2024-09-26T11:59:01.988803Z",
"status": "Active",
"subscription_type": "REGULAR",
"signature_hash": "E2K0I3Nl8F2srV/6W5FdInszHXARHJAAQgV73nfwzqI=",
"total_amount": 412,
"collected_amount": 103,
"ip_address": "103.23.238.249",
"collected_count": 1,
"portone_key": ""
}

Merchant will receive the following data as webhook response after a successful subscription status update:

Parameter list#

allow_accumulate#
string#

Whether allow accumulate is enabled or not

recurring_amount#
float64#

The recurring amount of the subscription

chaipaykey#
string#

The key provided by Portone

currency#
string#

The currency of the subscription

customer_email_address#
string#

The email address of the customer

customer_name#
string#

The name of the customer

customer_phone_number#
string#

The phone number of the customer

environment#
string#

The environment of the subscription

frequency#
integer#

The frequency of the subscription

expired_at#
string#

The expiry date of the subscription

link#
string#

The link of the subscription

merchant_order_ref#
string#

The order reference of the subscription provided by merchant

name#
string#

The name of the subscription plan

notify_by_email#
boolean#

The notify by email flag of the subscription

notify_by_phone#
boolean#

The notify by phone flag of the subscription

order_ref#
string#

The Portone order reference of the subscription

plan_order_ref#
string#

The plan order reference of the subscription

period#
string#

The period of the subscription

quantity#
integer#

The quantity of the subscription

recurrance_count#
integer#

The recurrance count of the subscription

source#
string#

The source of the subscription

started_at#
string#

The start date of the subscription

created_at#
string#

The created date of the subscription

status#
string#

The status of the subscription

subscription_type#
string#

The type of the subscription

signature_hash#
string#

The signature hash of the subscription

total_amount#
float64#

The total amount of the subscription

collected_amount#
float64#

The collected amount of the subscription

ip_address#
string#

The IP address of the subscription

collected_count#
integer#

The collected count of the subscription

portone_key#
string#

The key provided by Portone

PAYOUT - Payout Status Update#

This webhook gets triggered whenever the status of the payout transaction gets updated at payment channel's end. Refer following sample payload received in Webhooks.

{
"vaaccount_no": "qcFJvupbcbdcyNFg-12345678911_sandbox",
"txn_ref": "TGmRjfF7UjeJ9q6DQ5sZdR",
"merchant_txn_ref": "txnref_43EB10A8C07B643",
"status": "Success",
"status_channel_reason": "Success",
"is_approved": true,
"approved_by": "ShopCity",
"approved_time": "2024-09-26 11:39:48.818125 +0000 UTC",
"is_verified": true,
"verified_by": "ShopCity",
"verified_time": "2024-09-26 11:39:45.310667 +0000 UTC",
"due_date": "2024-09-26 11:39:13 +0000 UTC",
"to_account_no": "7771000241",
"channel_ref": "240926000105828",
"amount": 1000,
"currency": "THB",
"environment": "sandbox",
"approved_status": "Approved",
"verified_status": "Verified",
"remarks": "",
"user_message": "",
"send_email": false,
"send_sms": false,
"bank_name": "",
"account_name": "",
"email_notification_sent": false,
"sms_notification_sent": false,
"sms_sent": "",
"email_sent": "",
"is_split_payout": false,
"is_parent_split": false,
"split_count": 0,
"original_merchant_txn_ref": "txnref_43EB10A8C07B643",
"transaction_type": "",
"fund_source": "",
"recipient_emails": null
}

Merchant will receive the following data as webhook response after a successful payout status update:

Parameter list#

vaaccount_no#
string#

The virtual account number of the payment channel

txn_ref#
string#

The transaction reference of the payment channel

merchant_txn_ref#
string#

The merchant transaction reference of the payment channel

status#
string#

The status of the payout transaction

status_channel_reason#
string#

The status reason of the payout transaction

is_approved#
boolean#

The approval status of the payout transaction

approved_by#
string#

The approved by of the payout transaction

approved_time#
string#

The approved time of the payout transaction

is_verified#
boolean#

The verification status of the payout transaction

verified_by#
string#

The verified by of the payout transaction

verified_time#
string#

The verified time of the payout transaction

due_date#
string#

The due date of the payout transaction

to_account_no#
string#

The account number of the payout transaction to be paid

channel_ref#
string#

The channel reference of the payout transaction

amount#
float64#

The amount of the payout transaction

currency#
string#

The currency of the payout transaction

environment#
string#

The environment of the payout transaction

approved_status#
string#

The approved status of the payout transaction

verified_status#
string#

The verified status of the payout transaction

remarks#
string#

The remarks of the payout transaction

user_message#
string#

The user message of the payout transaction

send_email#
boolean#

The send email flag of the payout transaction

send_sms#
boolean#

The send sms flag of the payout transaction

bank_name#
string#

The bank name of the payout transaction

account_name#
string#

The account name of the payout transaction

email_notification_sent#
boolean#

The email notification sent flag of the payout transaction

sms_notification_sent#
boolean#

The sms notification sent flag of the payout transaction

sms_sent#
string#

The sms sent of the payout transaction

email_sent#
string#

The email sent of the payout transaction

is_split_payout#
boolean#

The split payout flag of the payout transaction

is_parent_split#
boolean#

The parent split flag of the payout transaction

split_count#
integer#

The split count of the payout transaction

original_merchant_txn_ref#
string#

The original merchant transaction reference of the payout transaction

transaction_type#
string#

The transaction type of the payout transaction

fund_source#
string#

The fund source of the payout transaction

recipient_emails#
string#

The recipient emails of the payout transaction

tip

During testing you can use FOSS Webhook server to setup webhook endpoint. Create a sample webhook at webhook.site