Returns summarised and aggregated information about a customer gambling and other spend.
Potential Use Cases:
- Understand gambling vs spend
- Identify potential gambling problem
The Insights webhook is HTTPS post request and a typical example of the request body is as follows:
{
"type": "INSIGHTS",
"data": {
"metadata": {
"merchantId": "684af205b26c48042487c93c",
"customerId": "eixyc0oxx9o0",
"reference": "eixyc0oxx9o0",
"citizenTransactionId": "54f97545-a987-cfa9-b2a8-f66b97",
"merchantTradingName": "Test Merchant"
},
"insightGroup": {
"id": "68d6593704a1aa70943d2bb1",
"name": "Payment Basics",
"insights": [
"PAYMENT_BASICS"
],
"period": [
"MONTHLY"
],
"fromDate": "2025-06-28T09:32:33.440188Z",
"toDate": "2025-07-26T09:32:33.440206Z"
},
"insights": {
"PAYMENT_BASICS": {
"insight": "PAYMENT_BASICS",
"fromDate": "2025-06-28T09:32:33.440188Z",
"toDate": "2025-07-26T09:32:33.440206Z",
"accounts": [
{
"accountId": "9800b595-329f-49ff-8519-b6d5622f211f",
"accountType": "CURRENT",
"currency": "GBP",
"closingBalance": 350,
"lastUpdatedAt": "2025-09-26T09:32:33.852805Z",
"consents": [
{
"consentId": "31d99e03-2ae2-40db-a39b-50b2fb650581",
"status": "ACTIVE",
"createdAt": "2025-07-26T09:32:33.126Z",
"expiresAt": "2025-10-25T10:32:33.125Z"
}
],
"paymentBasics": {
"categorisations": {
"OTHER": {
"PAYOUT": {
"paymentCount": 15,
"amount": 200
},
"PAYIN": {
"paymentCount": 5,
"amount": 300
}
},
"GAMBLING": {
"PAYOUT": {
"paymentCount": 6,
"amount": 150
},
"PAYIN": {
"paymentCount": 2,
"amount": 40
}
}
},
"period": {
"MONTHLY": [
{
"fromDate": "2025-06-28T09:32:33.440188Z",
"toDate": "2025-06-30T23:59:59Z",
"description": "2025-06",
"data": {
"OTHER": {
"PAYOUT": {
"paymentCount": 10,
"amount": 170
},
"PAYIN": {
"paymentCount": 3,
"amount": 200
}
},
"GAMBLING": {
"PAYOUT": {
"paymentCount": 2,
"amount": 50
},
"PAYIN": {
"paymentCount": 1,
"amount": 20
}
}
}
},
{
"fromDate": "2025-07-01T00:00:00Z",
"toDate": "2025-07-31T23:59:59Z",
"description": "2025-07",
"data": {
"OTHER": {
"PAYOUT": {
"paymentCount": 5,
"amount": 30
},
"PAYIN": {
"paymentCount": 2,
"amount": 100
}
},
"GAMBLING": {
"PAYOUT": {
"paymentCount": 4,
"amount": 100
},
"PAYIN": {
"paymentCount": 1,
"amount": 20
}
}
}
}
]
}
}
}
]
}
}
}
}
| Field | Type | Description |
|---|
| insight | string | Always PAYMENT_BASICS |
| fromDate | string | Period start date (ISO 8601). |
| toDate | string | Period end date (ISO 8601). |
| accounts | array[Account] | List of account objects. Payment basic insights are calculated per account basis |
| Field | Type | Description |
|---|
| accountId | string | Unique account ID. |
| accountType | string | Type of account (e.g., "CURRENT"). |
| currency | string | 3-letter ISO currency code. |
| closingBalance | number | Account closing balance. |
| lastUpdatedAt | string | ISO 8601 timestamp of last update. |
| consents | array[Consent] | List of consent objects for this account. |
| paymentBasics | Payment Basics | Core payment categorization and periodic breakdowns. |
| Field | Type | Description |
|---|
| consentId | string | Unique consent identifier. |
| status | string | Status of the consent ("ACTIVE", etc.). |
| createdAt | string | ISO 8601 creation timestamp. |
| expiresAt | string | ISO 8601 expiry timestamp. |
| Field | Type | Description |
|---|
| categorisations | Payment Basics Categories | Summary of payment basics over each category. (see Payment basics categories) |
| period | Payment Basics Period | Payment basics consolidated over a period |
| Field | Type | Description |
|---|
| <Period> | array[Payment Basics Period Data] | Payment basics broken down by period. Period can be MONTHLY, WEEKLY, DAILY |
| Field | Type | Description |
|---|
| fromDate | string | Period start date (ISO 8601). |
| toDate | string | Period start date (ISO 8601). |
| description | string | Description of the period |
| data | Payment Basics Categories | Payment basics categories |
| Field | Type | Description |
|---|
| OTHER | Payment Basics Payments | Payment basic for the category OTHER |
| GAMBLING | Payment Basics Payments | Payment basic payments for the category GAMBLING |
| Field | Type | Description |
|---|
| PAYIN | Payment Data | Consolidated credits |
| PAYOUT | Payment Data | Consolidated debits |
| Field | Type | Description |
|---|
| paymentCount | number | Number of payments consolidated |
| amount | number | Consolidated payment amount |
Notes
- All date/time strings must be formatted as ISO 8601 (UTC).
- Category and period objects allow for extensibility; new keys may appear as more insight types are added.
- Amounts are always denominated in the provided currency.
