KYC
Final results for standalone merchant KYC arrive as HTTP POST on your shared merchant callback URL. Enable it during onboarding; it is not a per-request notify_url, so do not repoint a URL that other products depend on. This product sends merchant callbacks only — no email, push, or in-app notice to the end user.
When it is sent
Approval:
kycStatusisAPPROVED.Final rejection:
kycStatusisREJECTEDwithreviewRejectTypeFINAL.Requests for additional information and retryable rejections (
RETRY) are not final results and send nothing.
Both outcomes settle the verification fee. Delivery is asynchronous and may be delayed or repeated, so a missing callback tells you nothing about the order or the fee. A received callback means the fee order is settled; confirm amounts with Query Order using feeOrderNo.
Security
Serve over HTTPS, and do not treat HTTPS as proof of origin. Never unlock business operations on an unsigned callback alone: check the request-to-user association you stored, then confirm with Query KYC Status. Contact MusePay if the two disagree.
Payload
Callback fields use camelCase, unlike the snake_case fields in API responses.
type
String
Always KYC_RESULT.
data
Object
Verification result, below.
data
feeOrderNo
String
Settled fee order, matching fee_order_no from the link response.
userId
Number
MusePay user ID. The API returns user_id as a string, so normalise before comparing.
requestId
String
The request_id of the original link request.
levelName
String
L1, L2, L1_AML, or L2_AML.
kycStatus
String
APPROVED or REJECTED.
kycLevel
Number
Highest level obtained through this product: 0/1/2. On rejection, the level held before it.
userXid
String
Optional merchant-side identifier; it may be omitted, so associate the user by requestId and userId.
moderationComment
String
Optional review comment.
rejectLabels
Array of String
Optional rejection labels.
reviewRejectType
String
Optional; FINAL for a final rejection.
Approval example
Final rejection example
The comment and labels are examples, not an enumeration.
Acknowledging
Deduplicate on
type,data.requestId, anddata.userId. Signature-based or user-only deduplication would drop later applications.Return HTTP
200once the message is durably stored; run slow checks in your own worker.Retries follow the Webhook retry policy. Handle duplicates and delays, and query or contact MusePay when a result is missing.
Last updated