OnlinePay V2 SEPA EDD KYC asynchronous notification API documentation.

Overview

When a SEPA payment requires the merchant to submit KYC information, and the required KYC information is not provided in the payment request or existing user KYC records, OnlinePay will send an asynchronous notification to the eddNotifyUrl submitted in the payment request.

The V2 notification uses RSA+AES hybrid encryption to protect data security.

Encryption Flow

OnlinePay generates a random AES key

Business data + signature is encrypted with AES key → encryptedData

AES key is encrypted with RSA (platform private key) → encryptedKey

Merchant decrypts encryptedKey with OnlinePay public key to get AES key

Merchant decrypts encryptedData with AES key to get plaintext

Signing Flow

RSA256: signType = "RSA256", sign = RSA-SHA256(sorted key=value pairs, platform private key), verify with OnlinePay public key

Signing String Construction

Sort all fields alphabetically by key, exclude sign and signType, skip null or empty values, then join as key1=value1&key2=value2&....

Retry Mechanism

If OnlinePay does not receive HTTP 200 from the merchant, it will retry according to OnlinePay notification retry rules.

Base URLs:

Authentication

Notify

POST SEPA EDD KYC Notify Webhook API

POST your eddNotifyUrl

NOTE

This endpoint is implemented by the merchant. OnlinePay will POST the notification to the eddNotifyUrl submitted in the payment request.

Notification Trigger

OnlinePay sends this notification when all conditions below are met:

The SEPA payment field configuration requires KYC fields, such as iban, bicSwift, idFiles, bankStatementFiles, or kycReportFiles.

The required KYC information is not provided in the payment request.

OnlinePay does not already have complete KYC information for the same merNo + userId.

The payment request contains a valid eddNotifyUrl.

Notification Method

Request Method: POST

Data Format: application/json; charset=UTF-8

Character Encoding: UTF-8

Notification URL Configuration

The notification URL is obtained from the payment request parameter:

Priority 1: eddNotifyUrl submitted during payment

If eddNotifyUrl is not submitted, no EDD KYC notification will be sent.

What You Receive

{
  "encryptedData": "U2FsdGVkX1+ghi789...=",
  "encryptedKey": "aZLW7pFrNgc+kJxsT2...="
}

Step 1: Decrypt

// 1. RSA decrypt encryptedKey with OnlinePay Public Key → get AES key
// 2. AES decrypt encryptedData with AES key → get plaintext JSON below

Step 2: Decrypted Fields

Parameter	Type	Required	Description
tradeNo	String	Yes	Platform transaction order number
merOrderNo	String	Yes	Merchant order number
code	String	Yes	Notification type code, fixed value `3`
message	String	Yes	Notification message, fixed value `Please upload your identity information`
signType	String	Yes	Signature type, fixed value `RSA256`
sign	String	Yes	Signature value for verifying notification authenticity

Decrypted JSON Example

{
  "tradeNo": "T202309011234567890",
  "merOrderNo": "MER20230901001",
  "code": "3",
  "message": "Please upload your identity information",
  "signType": "RSA256",
  "sign": "d4e5f6g7h8..."
}

Step 3: Verify Signature

Sort all fields by key, exclude sign and signType, skip null or empty values

Join as key1=value1&key2=value2

Verify by RSA256: RSA-SHA256-Verify(signString, sign, OnlinePay_PublicKey)

Example

Fields: tradeNo, merOrderNo, code, message
Sign string: code=3&merOrderNo=MER20230901001&message=Please upload your identity information&tradeNo=T202309011234567890

Step 4: Respond

Return HTTP 200 to acknowledge receipt. If other status codes are returned, the system will consider the notification failed.

Security Recommendations

Must verify signature: Always verify the sign parameter after receiving notifications to ensure authenticity

Idempotency handling: The same EDD KYC notification may be sent multiple times, merchants need to handle idempotency

Timely response: Recommend responding within 5 seconds to avoid timeout retries

Log recording: Recommend logging all received notifications and processing results for troubleshooting

Body 请求参数

{
  "encryptedData": "U2FsdGVkX1+ghi789...=",
  "encryptedKey": "aZLW7pFrNgc+kJxsT2...="
}

请求参数

名称	位置	类型	必选	说明
body	body	V2EncryptedEnvelope	是	V2 encrypted notification envelope

返回结果

状态码	状态码含义	说明	数据模型
200	OK	Return HTTP 200 to acknowledge receipt	None

数据模型

V2EncryptedEnvelope

{
  "encryptedData": "string",
  "encryptedKey": "string"
}

V2 encrypted notification envelope.

Decrypt:

RSA-decrypt encryptedKey with OnlinePay Public Key to get AES key

AES-decrypt encryptedData with AES key to get JSON plaintext

Verify Signature:
Sort all fields by key, exclude sign and signType, skip null or empty values, join as key1=value1&key2=value2.

属性

名称	类型	必选	约束	中文名	说明
encryptedData	string	true	none		AES-encrypted JSON payload (Base64)
encryptedKey	string	true	none		RSA-encrypted AES key (Base64). Decrypt with OnlinePay Public Key.

EddKycNotifyPlaintext

{
  "tradeNo": "T202309011234567890",
  "merOrderNo": "MER20230901001",
  "code": "3",
  "message": "Please upload your identity information",
  "signType": "RSA256",
  "sign": "d4e5f6g7h8..."
}

属性

名称	类型	必选	约束	说明
tradeNo	string	true	none	Platform transaction order number
merOrderNo	string	true	none	Merchant order number
code	string	true	none	Notification type code, fixed value `3`
message	string	true	none	Notification message, fixed value `Please upload your identity information`
signType	string	true	none	Signature type, fixed value `RSA256`
sign	string	true	none	Signature value for verifying notification authenticity

SEPA EDD KYC Notify Webhook API

Overview#

Encryption Flow#

Signing Flow#

Signing String Construction#

Retry Mechanism#

Authentication#

Notify#

POST SEPA EDD KYC Notify Webhook API#

Notification Trigger#

Notification Method#

Notification URL Configuration#

What You Receive#

Step 1: Decrypt#

Step 2: Decrypted Fields#

Decrypted JSON Example#

Step 3: Verify Signature#

Example#

Step 4: Respond#

Security Recommendations#

请求参数#

返回结果#

数据模型#

V2EncryptedEnvelope#

属性#

EddKycNotifyPlaintext#

属性#

Overview

Encryption Flow

Signing Flow

Signing String Construction

Retry Mechanism

Authentication

Notify

POST SEPA EDD KYC Notify Webhook API

Notification Trigger

Notification Method

Notification URL Configuration

What You Receive

Step 1: Decrypt

Step 2: Decrypted Fields

Decrypted JSON Example

Step 3: Verify Signature

Example

Step 4: Respond

Security Recommendations

请求参数

返回结果

数据模型

V2EncryptedEnvelope

属性

EddKycNotifyPlaintext

属性