Agreement Webhooks

Agreement webhooks notify merchants about agreement lifecycle changes. All agreement webhooks use notifyType: AGREEMENT_STATUS.

eventType Values

Agreement webhooks use the following eventType values: SIGNED, REJECTED, UNSIGNED, SUSPENDED, EXPIRED, TIMEOUT

---

Sign Result Notification

Notifies merchant when user completes or fails the sign process.

data Fields

Parameter	Type	Description
agreementNo	string	Platform agreement number
externalAgreementNo	string	Merchant agreement number
agreementType	string	Sign type: CYCLE / NON_CYCLE / SINGLE
eventType	string	Event type: SIGNED
status	string	Sign status: SIGNED
userId	string	Platform user ID
merchantUserId	string	Merchant-side user ID
sceneCode	string	Scene code
signTime	string	Sign time (on success)
failureCode	string	Failure error code (on failure, 9-digit string)
failureReason	string	Failure reason description (on failure)

Example (Success)

{
  "notifyId": "NOTIFY202601070001",
  "notifyType": "AGREEMENT_STATUS",
  "notifyTime": "2026-01-07T10:30:05+08:00",
  "merchantId": "M123456789",
  "data": {
    "agreementNo": "AGR202601070001",
    "externalAgreementNo": "MERCHANT_AGR_001",
    "agreementType": "CYCLE",
    "eventType": "SIGNED",
    "status": "SIGNED",
    "userId": "U_123456789",
    "merchantUserId": "merchant_user_123",
    "sceneCode": "SUBSCRIPTION",
    "signTime": "2026-01-07 10:30:00"
  },
}

Sign Failure Handling

• If user actively cancels signing → See Sign Rejected Notification below (eventType=REJECTED)
• If system error causes sign failure → See Sign Failed Notification below (eventType=AGREEMENT_SIGN_RESULT)

---

Sign Rejected Notification

Notifies merchant when user actively cancels signing on the cashier page.

data Fields

Parameter	Type	Description
agreementNo	string	Platform agreement number
externalAgreementNo	string	Merchant agreement number
eventType	string	Event type: REJECTED
status	string	Agreement status: REJECTED
merchantId	string	Merchant ID
failureReason	string	Rejection reason

Example

{
  "notifyId": "NOTIFY202601070015",
  "notifyType": "AGREEMENT_STATUS",
  "notifyTime": "2026-01-07T10:45:00+08:00",
  "merchantId": "M123456789",
  "data": {
    "agreementNo": "AGR202601070003",
    "externalAgreementNo": "MERCHANT_AGR_003",
    "eventType": "REJECTED",
    "status": "REJECTED",
    "merchantId": "M123456789",
    "failureReason": "User canceled signing"
  }
}

---

Sign Failed Notification (System Error)

Notifies merchant when sign process fails due to system error (e.g., payment failure in sign-with-pay scenario). Uses notifyType: TRANSACTION_RESULT.

data Fields

Parameter	Type	Description
agreementNo	string	Platform agreement number
externalAgreementNo	string	Merchant agreement number
eventType	string	Event type: AGREEMENT_SIGN_RESULT
status	string	Status: FAILED
merchantId	string	Merchant ID
failureReason	string	Failure reason

Example

{
  "notifyId": "NOTIFY202601070016",
  "notifyType": "TRANSACTION_RESULT",
  "notifyTime": "2026-01-07T10:45:00+08:00",
  "merchantId": "M123456789",
  "data": {
    "eventType": "AGREEMENT_SIGN_RESULT",
    "status": "FAILED",
    "agreementNo": "AGR202601070004",
    "externalAgreementNo": "MERCHANT_AGR_004",
    "merchantId": "M123456789",
    "failureReason": "Payment confirmation failed: Insufficient balance"
  }
}

---

Unsign Notification

Notifies merchant when an agreement is terminated.

data Fields

Parameter	Type	Description
agreementNo	string	Platform agreement number
externalAgreementNo	string	Merchant agreement number
eventType	string	Event type: UNSIGNED
status	string	Agreement status: UNSIGNED
unsignType	string	Unsign type: USER / MERCHANT / EXPIRED / SYSTEM
unsignTime	string	Unsign time

Example

{
  "notifyId": "NOTIFY202601070006",
  "notifyType": "AGREEMENT_STATUS",
  "notifyTime": "2026-01-07T15:30:05+08:00",
  "merchantId": "M123456789",
  "data": {
    "agreementNo": "AGR202601070001",
    "externalAgreementNo": "MERCHANT_AGR_001",
    "eventType": "UNSIGNED",
    "status": "UNSIGNED",
    "unsignType": "USER",
    "unsignTime": "2026-01-07 15:30:00"
  },
}

---

Suspend Notification

Notifies merchant when an agreement is suspended due to risk control or abnormality.

data Fields

Parameter	Type	Description
agreementNo	string	Platform agreement number
externalAgreementNo	string	Merchant agreement number
eventType	string	Event type: SUSPENDED
status	string	Agreement status: SUSPENDED
suspendReason	string	Suspend reason: RISK / ABNORMAL / MANUAL
suspendTime	string	Suspend time

Example

{
  "notifyId": "NOTIFY202601070007",
  "notifyType": "AGREEMENT_STATUS",
  "notifyTime": "2026-01-07T16:30:05+08:00",
  "merchantId": "M123456789",
  "data": {
    "agreementNo": "AGR202601070001",
    "externalAgreementNo": "MERCHANT_AGR_001",
    "eventType": "SUSPENDED",
    "status": "SUSPENDED",
    "suspendReason": "RISK",
    "suspendTime": "2026-01-07 16:30:00"
  },
}

---

Resume Notification

Notifies merchant when a suspended agreement returns to normal.

data Fields

Parameter	Type	Description
agreementNo	string	Platform agreement number
externalAgreementNo	string	Merchant agreement number
eventType	string	Event type: SIGNED
status	string	Agreement status: SIGNED
resumeTime	string	Resume time

Example

{
  "notifyId": "NOTIFY202601070008",
  "notifyType": "AGREEMENT_STATUS",
  "notifyTime": "2026-01-07T18:30:05+08:00",
  "merchantId": "M123456789",
  "data": {
    "agreementNo": "AGR202601070001",
    "externalAgreementNo": "MERCHANT_AGR_001",
    "eventType": "SIGNED",
    "status": "SIGNED",
    "resumeTime": "2026-01-07 18:30:00"
  },
}

---

Expired Notification

Notifies merchant when an agreement expires automatically (reaching validity period set at sign time).

data Fields

Parameter	Type	Description
agreementNo	string	Platform agreement number
externalAgreementNo	string	Merchant agreement number
eventType	string	Event type: EXPIRED
status	string	Agreement status: EXPIRED
expireTime	string	Expire time

Example

{
  "notifyId": "NOTIFY202601070020",
  "notifyType": "AGREEMENT_STATUS",
  "notifyTime": "2026-01-07T23:59:05+08:00",
  "merchantId": "M123456789",
  "data": {
    "agreementNo": "AGR202601070001",
    "externalAgreementNo": "MERCHANT_AGR_001",
    "eventType": "EXPIRED",
    "status": "EXPIRED",
    "expireTime": "2026-01-07 23:59:00"
  }
}

---

Sign Timeout Notification

Notifies merchant when sign link/QR code expires.

data Fields

Parameter	Type	Description
agreementNo	string	Platform agreement number
externalAgreementNo	string	Merchant agreement number
agreementType	string	Sign type: CYCLE / NON_CYCLE / SINGLE
eventType	string	Event type: TIMEOUT
status	string	Agreement status: TIMEOUT
userId	string	Platform user ID
merchantUserId	string	Merchant-side user ID
sceneCode	string	Scene code
timeoutTime	string	Timeout time

Example

{
  "notifyId": "NOTIFY202601070011",
  "notifyType": "AGREEMENT_STATUS",
  "notifyTime": "2026-01-07T11:00:05+08:00",
  "merchantId": "M123456789",
  "data": {
    "agreementNo": "AGR202601070003",
    "externalAgreementNo": "MERCHANT_AGR_003",
    "agreementType": "CYCLE",
    "eventType": "TIMEOUT",
    "status": "TIMEOUT",
    "userId": "U_123456789",
    "merchantUserId": "merchant_user_123",
    "sceneCode": "SUBSCRIPTION",
    "timeoutTime": "2026-01-07 11:00:00"
  },
}