Compliance Status Events
GrailPay provides webhook events to notify you when the compliance status of a merchant changes. These events are crucial for maintaining up-to-date records and ensuring that your operations align with regulatory requirements. By subscribing to these events, you can automate workflows that respond to compliance status updates, such as pausing transactions, triggering additional verification steps, or notifying relevant stakeholders.
Compliance status moves through four states, each with its own event: compliance_status.processing when KYB and KYC checks begin, compliance_status.in_review when the merchant needs manual KYB review, and compliance_status.approved or compliance_status.rejected for the final determination. Only an approved merchant is eligible to transact.
All payloads below are shown in full, including the event envelope.
compliance_status.processing
Section titled “compliance_status.processing”This webhook event is triggered when compliance verification has begun processing for a Merchant. This includes KYB verification for the business entity and/or KYC verification for its associated Beneficial Owners.
{ "event": "compliance_status.processing", "event_uuid": "019d072d-1203-7695-842b-a15567fbb0d8", "event_occurred_at": "2026-04-05 14:28:33", "event_version": 3, "vendor_uuid": "019e2711-5a92-735d-a7d5-669aec76b54f", "data": { "entity": { "type": "merchant", "uuid": "019e0383-8075-7704-bcb6-9d8c08137977" }, "compliance": { "status": "REJECTED", "kyb": { "status": "APPROVED", "message": null, "updated_at": "2025-12-11 13:59:21" }, "kyc": [ { "uuid": "7f4e8a02-3d5a-4c3b-b823-d8c3125b3f8d", "first_name": "John", "last_name": "Doe", "status": "PASSED", "message": null, "updated_at": "2025-12-11 13:59:21" }, { "uuid": "9e2a7cb7-34c1-4c52-a0df-4f9f5704e6e2", "first_name": "Jane", "last_name": "Doe", "status": "FAILED", "message": "Invalid Address", "updated_at": "2025-12-11 13:59:21" } ] } }}compliance_status.in_review
Section titled “compliance_status.in_review”This webhook event is triggered when a Merchant’s compliance status has moved to in review. This occurs when all associated Beneficial Owners have passed KYC verification, but the Merchant’s KYB verification requires manual review before a final determination can be made. A Merchant with an in_review compliance status is not eligible to transact.
{ "event": "compliance_status.in_review", "event_uuid": "019d072d-1203-7695-842b-a15567fbb0d8", "event_occurred_at": "2026-04-05 14:28:33", "event_version": 3, "vendor_uuid": "019e2711-5a92-735d-a7d5-669aec76b54f", "data": { "entity": { "type": "merchant", "uuid": "019e0383-8075-7704-bcb6-9d8c08137977" }, "compliance": { "status": "REJECTED", "kyb": { "status": "APPROVED", "message": null, "updated_at": "2025-12-11 13:59:21" }, "kyc": [ { "uuid": "7f4e8a02-3d5a-4c3b-b823-d8c3125b3f8d", "first_name": "John", "last_name": "Doe", "status": "PASSED", "message": null, "updated_at": "2025-12-11 13:59:21" }, { "uuid": "9e2a7cb7-34c1-4c52-a0df-4f9f5704e6e2", "first_name": "Jane", "last_name": "Doe", "status": "FAILED", "message": "Invalid Address", "updated_at": "2025-12-11 13:59:21" } ] } }}compliance_status.approved
Section titled “compliance_status.approved”This webhook event is triggered when a Merchant’s compliance status has been approved. This means all associated Beneficial Owners have passed KYC verification and the Merchant has passed KYB verification. The Merchant is now eligible to transact.
{ "event": "compliance_status.approved", "event_uuid": "019d072d-1203-7695-842b-a15567fbb0d8", "event_occurred_at": "2026-04-05 14:28:33", "event_version": 3, "vendor_uuid": "019e2711-5a92-735d-a7d5-669aec76b54f", "data": { "entity": { "type": "merchant", "uuid": "019e0383-8075-7704-bcb6-9d8c08137977" }, "compliance": { "status": "REJECTED", "kyb": { "status": "APPROVED", "message": null, "updated_at": "2025-12-11 13:59:21" }, "kyc": [ { "uuid": "7f4e8a02-3d5a-4c3b-b823-d8c3125b3f8d", "first_name": "John", "last_name": "Doe", "status": "PASSED", "message": null, "updated_at": "2025-12-11 13:59:21" }, { "uuid": "9e2a7cb7-34c1-4c52-a0df-4f9f5704e6e2", "first_name": "Jane", "last_name": "Doe", "status": "FAILED", "message": "Invalid Address", "updated_at": "2025-12-11 13:59:21" } ] } }}compliance_status.rejected
Section titled “compliance_status.rejected”This webhook event is triggered when a Merchant’s compliance status has been rejected. This occurs when either the Merchant’s KYB verification has failed or any of its associated Beneficial Owners have failed KYC verification. A Merchant with a rejected compliance status is not eligible to transact.
{ "event": "compliance_status.rejected", "event_uuid": "019d072d-1203-7695-842b-a15567fbb0d8", "event_occurred_at": "2026-04-05 14:28:33", "event_version": 3, "vendor_uuid": "019e2711-5a92-735d-a7d5-669aec76b54f", "data": { "entity": { "type": "merchant", "uuid": "019e0383-8075-7704-bcb6-9d8c08137977" }, "compliance": { "status": "REJECTED", "kyb": { "status": "APPROVED", "message": null, "updated_at": "2025-12-11 13:59:21" }, "kyc": [ { "uuid": "7f4e8a02-3d5a-4c3b-b823-d8c3125b3f8d", "first_name": "John", "last_name": "Doe", "status": "PASSED", "message": null, "updated_at": "2025-12-11 13:59:21" }, { "uuid": "9e2a7cb7-34c1-4c52-a0df-4f9f5704e6e2", "first_name": "Jane", "last_name": "Doe", "status": "FAILED", "message": "Invalid Address", "updated_at": "2025-12-11 13:59:21" } ] } }}Maintained by EkLine