Merchant Events
GrailPay emits dedicated webhook events when a merchant entity is created or updated on the platform. These events provide real-time notifications that allow you to synchronize merchant records, trigger onboarding or verification flows, and monitor compliance status.
Merchants in GrailPay are a distinct type of business that must complete Know Your Business (KYB) verification. Each payload includes detailed metadata, enabling accurate reconciliation of merchant status across your systems. For more information about KYB verification and requirements, refer to the KYB Overview guide.
All payloads below are shown in full, including the event envelope.
merchant.created
Section titled “merchant.created”This webhook is triggered each time a new merchant has been successfully onboarded and registered within the GrailPay platform.
{ "event": "merchant.created", "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": { "merchant": { "uuid": "b8f1e132-3bfc-4e23-89f7-9e541e8ffb33", "business_type": "merchant", "kyb_status": "IN_REVIEW", "kyb_rejected_reason": null, "name": "John Incorporation", "tin": "123456789", "trading_name": "John Incorporation", "entity_type": "Sole Trader", "incorporation_date": "2024-02-02", "incorporation_state": "CO", "address_type": "Registered", "address": { "line_1": "123 Main St", "line_2": "Apt 4B", "city": "Denver", "state": "CO", "zip": "80203" }, "transaction_fee_percent": 2.5, "transaction_fee_fixed": 100, "maximum_transaction_fee": 5000, "payout_type": "individual", "client_reference_id": "bus_123456789", "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" } ] }, "timestamps": { "created_at": "2024-06-25 13:57:03" } }, "person": { "client_reference_id": "person_98345", "uuid": "7c41f6a2-a4b9-4df8-9225-2c1b7312042e", "status": "APPROVED", "first_name": "Jane", "last_name": "Doe", "email": "test@grailpay.com", "phone": "1234567890", "address": { "line_1": "123 Main St", "line_2": "Apt 4B", "city": "Denver", "state": "CO", "zip": "80203" }, "payout_type": "individual", "timestamps": { "created_at": "2024-06-25 13:57:03" } }, "bank_account": { "uuid": "9b97f121-a449-4b52-9f36-6c55f18394d6", "aggregator_type": "manual", "provider_type": "manual", "account_name": "Acme, Inc", "account_type": "checking", "account_number": "1111222233330000", "routing_number": "011401533", "institution_name": "Bank of America", "aggregator": "mx", "is_default": true, "client_reference_id": "client-1234", "status": "connected", "timestamps": { "created_at": "2024-06-25 13:57:03" } } }}merchant.updated
Section titled “merchant.updated”This webhook is triggered whenever a merchant’s details have been updated within the GrailPay platform. This may include changes to business name, address, or other KYB-related fields.
{ "event": "merchant.updated", "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": { "merchant": { "uuid": "b8f1e132-3bfc-4e23-89f7-9e541e8ffb33", "business_type": "merchant", "kyb_status": "IN_REVIEW", "kyb_rejected_reason": null, "name": "John Incorporation", "tin": "123456789", "trading_name": "John Incorporation", "entity_type": "Sole Trader", "incorporation_date": "2024-02-02", "incorporation_state": "CO", "address_type": "Registered", "address": { "line_1": "123 Main St", "line_2": "Apt 4B", "city": "Denver", "state": "CO", "zip": "80203" }, "transaction_fee_percent": 2.5, "transaction_fee_fixed": 100, "maximum_transaction_fee": 5000, "payout_type": "individual", "client_reference_id": "bus_123456789", "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" } ] }, "timestamps": { "created_at": "2024-06-25 13:57:03" } }, "person": { "client_reference_id": "person_98345", "uuid": "7c41f6a2-a4b9-4df8-9225-2c1b7312042e", "status": "APPROVED", "first_name": "Jane", "last_name": "Doe", "email": "test@grailpay.com", "phone": "1234567890", "address": { "line_1": "123 Main St", "line_2": "Apt 4B", "city": "Denver", "state": "CO", "zip": "80203" }, "payout_type": "individual", "timestamps": { "created_at": "2024-06-25 13:57:03" } }, "bank_account": { "uuid": "9b97f121-a449-4b52-9f36-6c55f18394d6", "aggregator_type": "manual", "provider_type": "manual", "account_name": "Acme, Inc", "account_type": "checking", "account_number": "1111222233330000", "routing_number": "011401533", "institution_name": "Bank of America", "aggregator": "mx", "is_default": true, "client_reference_id": "client-1234", "status": "connected", "timestamps": { "created_at": "2024-06-25 13:57:03" } } }}Maintained by EkLine