# Sub-Accounts Webhooks ## Overview Ryft offers several webhook events specifically for **Sub-Accounts**. These events allow you to stay informed about important actions and changes related to your sub-accounts. At a minimum, you should consider subscribing to the following webhook events for sub-accounts: - **Account.created**: Triggered when a new Sub-Account is created. - **Account.updated**: Triggered when an existing Sub-Account is updated via the API or internally by Ryft (e.g., changes to account status). - **Person.created**: Triggered when a new person is created and associated with a Sub-Account. - **Person.updated**: Triggered when an existing person is updated via the API or internally by Ryft (e.g., changes to verification status). Overall, the `created` events will allow you to store the `id` of the newly created object in your database, while the `updated` events will allow you to monitor changes to the object over time. ## Account Events These events will be stored under the Main Account, so no `account` header is required when quering for these events using the [Events API](/documentation/api/reference/openapi#operation/Events). Account.created This event is triggered whenever a new Sub-Account is created using the [subAccountCreate](/documentation/api/reference/openapi#operation/subAccountCreate) endpoint. ```json Account.created - Payload Example { "id": "ev_XXXXXXXX", "eventType": "Account.created", "data": { "id": "ac_XXXXXXXX", "type": "Sub", "status": "ActionRequired", "actionsRequired": [ { "action": "PayoutDetailsRequired", "description": "Head over to our portal in order to get setup for payouts", } ], "onboardingFlow": "Hosted", "entityType": "Business", "business": { "name": "Test Company Ltd", "type": "PublicCompany", "registrationNumber": "12345678", "registeredAddress": { "lineOne": "13 Downing Street", "city": "London", "postalCode": "SW1 1AA", "country": "GB", }, "contactEmail": "test@email.com", }, "verification": {"status": "NotRequired", "persons": {"status": "NotRequired"}}, "frozen": false, "settings": {"payouts": {"schedule": {"type": "Automatic"}}}, "capabilities": { "visaPayments": { "status": "Enabled", "available": true, "enabledTimestamp": 1758299895, "lastUpdatedTimestamp": 1758299895, }, "mastercardPayments": { "status": "Enabled", "available": true, "enabledTimestamp": 1758299895, "lastUpdatedTimestamp": 1758299895, }, "amexPayments": { "status": "NotRequested", "available": true, "requiredFields": [ {"name": "business.phoneNumber"}, {"name": "business.websiteUrl"}, ], "lastUpdatedTimestamp": 1758299895, }, }, "createdTimestamp": 1758299895, }, "createdTimestamp": 1758299898, "lastUpdatedTimestamp": 1758299898, "deliveryStatus": "None", } ``` Account.updated This event is triggered whenever an existing Sub-Account is updated using the [subAccountUpdate](/documentation/api/reference/openapi#operation/subAccountUpdate) endpoint or internally by Ryft (e.g., changes to account status). ```json Account.updated - Payload Example { "id": "ev_XXXXXXXX", "eventType": "Account.updated", "data": { "id": "ac_XXXXXXXX", "type": "Sub", "entityType": "Business", "onboardingFlow": "NonHosted", "business": { "name": "Test Ltd", "type": "PublicCompany", "registrationNumber": "12345678", "registeredAddress": { "lineOne": "123 Street", "city": "Manchester", "country": "GB", "postalCode": "M1 1AA", }, "contactEmail": "contact@test.com", }, "frozen": false, "verification": { "status": "Required", "requiredFields": [ { "name": "business.registrationDate", } ], "requiredDocuments": [ { "category": "ProofOfBusiness", "types": ["ArticlesOfIncorporation", "BusinessRegistration"], "quantity": 2, } ], "persons": { "status": "Required", "required": [ {"role": "BusinessContact", "minQuantity": 1}, {"role": "Director", "minQuantity": 1}, {"role": "UltimateBeneficialOwner", "minQuantity": 1}, ], }, }, "metadata": {"yourAccountId": "123"}, }, "createdTimestamp": 1659538083, } ``` ## Person Events These events will be stored under the Sub-Account, so the `account` header with the Sub-Account ID is required when quering for these events using the [Events API](/documentation/api/reference/openapi#operation/Events). Person.created This event is triggered whenever a new person is created and associated with a Sub-Account using the [personCreate](/documentation/api/reference/openapi#operation/personCreate) endpoint. ```json Person.created - Payload Example { "id": "ev_XXXXXXXX", "eventType": "Person.created", "data": { "id": "per_XXXXXXXX", "firstName": "Test First Name", "lastName": "Test Last Name", "email": "test@example.com", "dateOfBirth": "1988-02-03", "gender": "Male", "nationalities": ["GB"], "address": { "lineOne": "88 Parker Street", "city": "Manchester", "region": "Greater Manchester", "postalCode": "SP4 7DE", "country": "GB", }, "phoneNumber": "+441234567891", "businessRoles": ["BusinessContact"], "verification": { "status": "Required", "requiredDocuments": [ { "category": "ProofOfIdentity", "types": ["DriversLicense", "NationalId", "Passport"], "quantity": 1, }, { "category": "Authorization", "types": ["LetterOfAuthorization"], "quantity": 1, }, ], }, "createdTimestamp": 1700675280, "lastUpdatedTimestamp": 1700675284, }, "accountId": "ac_XXXXXXXX", "createdTimestamp": 1700675296, } ``` Person.updated This event is triggered whenever an existing person is updated using the [personUpdate](/documentation/api/reference/openapi#operation/personUpdate) endpoint or internally by Ryft (e.g., changes to verification status). ```json Person.updated - Payload Example { "id": "ev_XXXXXXXX", "eventType": "Person.updated", "data": { "id": "per_XXXXXXXX", "firstName": "Test First Name", "lastName": "Test Last Name", "email": "test@example.com", "dateOfBirth": "1988-02-03", "gender": "Male", "nationalities": ["GB"], "address": { "lineOne": "88 Parker Street", "city": "Manchester", "region": "Greater Manchester", "postalCode": "SP4 7DE", "country": "GB", }, "phoneNumber": "+441234567891", "businessRoles": ["BusinessContact"], "verification": { "status": "Required", "requiredDocuments": [ { "category": "ProofOfIdentity", "types": ["DriversLicense", "NationalId", "Passport"], "quantity": 1, }, { "category": "Authorization", "types": ["LetterOfAuthorization"], "quantity": 1, }, ], }, "createdTimestamp": 1700675280, "lastUpdatedTimestamp": 1700675284, }, "accountId": "ac_XXXXXXXX", "createdTimestamp": 1700675296, } ``` Person.deleted This event is triggered whenever an existing person is deleted using the [personDelete](/documentation/api/reference/openapi#operation/personDelete) endpoint. ```json Person.deleted - Payload Example { "id": "ev_XXXXXXXX", "eventType": "Person.deleted", "data": { "id": "per_XXXXXXXX", "firstName": "Test First Name", "lastName": "Test Last Name", "email": "test@example.com", "dateOfBirth": "1988-02-03", "gender": "Male", "nationalities": ["GB"], "address": { "lineOne": "88 Parker Street", "city": "Manchester", "region": "Greater Manchester", "postalCode": "SP4 7DE", "country": "GB", }, "phoneNumber": "+441234567891", "businessRoles": ["BusinessContact"], "verification": { "status": "Required", "requiredDocuments": [ { "category": "ProofOfIdentity", "types": ["DriversLicense", "NationalId", "Passport"], "quantity": 1, }, { "category": "Authorization", "types": ["LetterOfAuthorization"], "quantity": 1, }, ], }, "createdTimestamp": 1700675280, "lastUpdatedTimestamp": 1700675284, }, "accountId": "ac_XXXXXXXX", "createdTimestamp": 1700677856, } ``` ## Payout Method Events These events will be stored under the Sub-Account, so the `account` header with the Sub-Account ID is required when quering for these events using the [Events API](/documentation/api/reference/openapi#operation/Events). PayoutMethod.created This event is triggered whenever a new payout method is created and associated with a Sub-Account using the [payoutMethodCreate](/documentation/api/reference/openapi#operation/payoutMethodCreate) endpoint. ```json PayoutMethod.created - Payload Example { "id": "ev_XXXXXXXX", "eventType": "PayoutMethod.created", "data": { "id": "pm_XXXXXXXX", "type": "BankAccount", "displayName": "My bank account", "status": "Valid", "currency": "GBP", "countryCode": "GB", "bankAccount": { "bankIdType": "SortCode", "bankId": "XXXXXX", "bankName": "My Bank", "accountNumberType": "UnitedKingdom", "last4": "XXXX", }, "createdTimestamp": 1700675204, "lastUpdatedTimestamp": 1700675207, }, "accountId": "ac_XXXXXXXX", "createdTimestamp": 1758627983, "lastUpdatedTimestamp": 1758627983, "deliveryStatus": "Success", } ``` PayoutMethod.updated This event is triggered whenever an existing payout method is updated using the [payoutMethodUpdate](/documentation/api/reference/openapi#operation/payoutMethodUpdate) endpoint or internally by Ryft (e.g., marked as invalid). ```json PayoutMethod.updated - Payload Example { "id": "ev_XXXXXXXX", "eventType": "PayoutMethod.updated", "data": { "id": "pm_XXXXXXXX", "type": "BankAccount", "displayName": "My updated bank account", "status": "Valid", "currency": "GBP", "countryCode": "GB", "bankAccount": { "bankIdType": "SortCode", "bankId": "XXXXXX", "bankName": "My updated Bank", "accountNumberType": "UnitedKingdom", "last4": "XXXX", }, "createdTimestamp": 1700675204, "lastUpdatedTimestamp": 1700675207, }, "accountId": "ac_XXXXXXXX", "createdTimestamp": 1758627983, "lastUpdatedTimestamp": 1758627983, "deliveryStatus": "Success", } ``` PayoutMethod.deleted This event is triggered whenever an existing payout method is deleted using the [payoutMethodDelete](/documentation/api/reference/openapi#operation/payoutMethodDelete) endpoint. ```json PayoutMethod.deleted - Payload Example { "id": "ev_XXXXXXXX", "eventType": "PayoutMethod.deleted", "data": { "id": "pm_XXXXXXXX", "type": "BankAccount", "displayName": "My bank account", "status": "Valid", "currency": "GBP", "countryCode": "GB", "bankAccount": { "bankIdType": "SortCode", "bankId": "XXXXXX", "bankName": "My Bank", "accountNumberType": "UnitedKingdom", "last4": "XXXX", }, "createdTimestamp": 1700675204, "lastUpdatedTimestamp": 1700675207, }, "accountId": "ac_XXXXXXXX", "createdTimestamp": 1758627983, "lastUpdatedTimestamp": 1758627983, "deliveryStatus": "Success", } ``` ## Payout Events These events will be stored under the Sub-Account, so the `account` header with the Sub-Account ID is required when quering for these events using the [Events API](/documentation/api/reference/openapi#operation/Events). Payout.created This event is triggered whenever a new payout is created and associated with a Sub-Account using the [payoutCreate](/documentation/api/reference/openapi#operation/payoutCreate) endpoint. ```json Payout.created - Payload Example { "id": "ev_XXXXXXXX", "eventType": "Payout.created", "data": { "id": "po_XXXXXXXX", "paymentsTakenDate": "2023-11-21", "paymentsTakenDateFrom": "2023-11-21", "paymentsTakenDateTo": "2023-11-21", "amount": 10000, "currency": "GBP", "status": "InProgress", "scheduleType": "Manual", "payoutMethod": {"id": "pm_XXXXXXXX"}, "payoutCalculation": { "paymentsCapturedAmount": 0, "paymentsRefundedAmount": 0, "paymentsSplitAmount": 0, "paymentsSplitRefundedAmount": 0, "splitPaymentsAmount": 0, "splitPaymentsRefundedAmount": 0, "platformFeesCollectedAmount": 0, "platformFeesRefundedAmount": 0, "platformFeesPaidAmount": 0, "processingFeesPaidAmount": 0, "payoutAmount": 10000, "currency": "GBP", "numberOfPaymentsCaptured": 0, "numberOfPaymentsRefunded": 0, "numberOfPaymentsSplit": 0, "numberOfPaymentsSplitRefunded": 0, "numberOfSplitPayments": 0, "numberOfSplitPaymentsRefunded": 0, "numberOfPlatformFeesCollected": 0, "numberOfPlatformFeesRefunded": 0, "numberOfCustomers": 0, "numberOfNewCustomers": 0, "feeAmount": 0, }, "createdTimestamp": 1700675210, "scheduledTimestamp": 1700675210, }, "accountId": "ac_XXXXXXXX", "createdTimestamp": 1700675210, } ``` Payout.status_updated This event is triggered whenever an existing payout is updated internally by Ryft (e.g., it moves through to completion or fails). ```json Payout.status_updated - Payload Example { "id": "ev_XXXXXXXX", "eventType": "Payout.status_updated", "data": { "id": "po_XXXXXXXX", "paymentsTakenDate": "2023-11-21", "paymentsTakenDateFrom": "2023-11-21", "paymentsTakenDateTo": "2023-11-21", "amount": 10000, "currency": "GBP", "status": "PendingAccountVerification", "scheduleType": "Manual", "payoutMethod": {"id": "pm_XXXXXXXX"}, "payoutCalculation": { "paymentsCapturedAmount": 0, "paymentsRefundedAmount": 0, "paymentsSplitAmount": 0, "paymentsSplitRefundedAmount": 0, "splitPaymentsAmount": 0, "splitPaymentsRefundedAmount": 0, "platformFeesCollectedAmount": 0, "platformFeesRefundedAmount": 0, "platformFeesPaidAmount": 0, "processingFeesPaidAmount": 0, "payoutAmount": 10000, "currency": "GBP", "numberOfPaymentsCaptured": 0, "numberOfPaymentsRefunded": 0, "numberOfPaymentsSplit": 0, "numberOfPaymentsSplitRefunded": 0, "numberOfSplitPayments": 0, "numberOfSplitPaymentsRefunded": 0, "numberOfPlatformFeesCollected": 0, "numberOfPlatformFeesRefunded": 0, "numberOfCustomers": 0, "numberOfNewCustomers": 0, "feeAmount": 0, }, "createdTimestamp": 1700675210, "scheduledTimestamp": 1700675210, }, "accountId": "ac_XXXXXXXX", "createdTimestamp": 1700675255, } ```