Here find the expected payload for the paymentMade event type.
The paymentMade event type is designed to convey detailed information about a financial transaction. Sending paymentMade events allows spektr to monitor transactional behavior, detect anomalies, and contribute to a comprehensive risk assessment of your customers.
When sending paymentMade events, ensure they are encapsulated within the events array of the overall request body to the /v1/events/import endpoint.
Event Structure
Each paymentMade event within the events array adheres to the following structure:
| Field Name | Type | Description | Required |
|---|---|---|---|
| workspaceId | string | Your spektr Workspace ID. This identifies the specific workspace within Spektr to which the event belongs. | Yes |
| spektrId | string | spektr's internal identifier for the customer. If you have previously created a customer in Spektr and received a spektrId, use it here to directly link the event. If customerData.internalId is provided instead, spektr will attempt to resolve the customer. | Yes |
| createdAt | number | Timestamp of when the event occurred/was created in your system (Unix timestamp in milliseconds). This represents the actual time the payment happened, not when it was sent to spektr. | Yes |
| source | string | Identifier of the system or origin from which the event was generated. E.g., "core-banking-system", "payment-gateway", "mobile-app". | No |
| customerData | object | An object containing identifying information about the customer related to this event. | No |
| eventData | object | Contains the specific details of the payment transaction. See eventData sub-fields below for details. | Yes |
| type | string | Always "paymentMade" for this event type. | Yes |
eventData Sub-fields (Payment Details)
| Field Name | Type | Description | Required |
|---|---|---|---|
| transaction_id | string | A unique identifier for the transaction within your system. This is crucial for tracking and de-duplication. | No |
| type | string | The high-level type of payment. Common values include: deposit, withdrawal, transfer, purchase, refund, fee. | Yes |
| subtype | string | A more specific categorization of the payment type. Examples: wireTransfer, ach, sepa, creditCard, debitCard, paypal, crypto. | Yes |
| status | string | The current status of the transaction. Common values: completed, pending, failed, cancelled, refunded. | Yes |
| amount | number | The monetary value of the transaction. Use the smallest currency unit (e.g., cents for USD, yen for JPY) to avoid floating-point issues, or ensure consistent decimal representation. | No |
| currency | string | The 3-letter ISO 4217 currency code (e.g., "USD", "EUR", "GBP"). | Yes |
| source_account | object | Details of the account from which the payment originated. See Account Details sub-fields below. Mandatory for OUT direction. | Yes |
| destination_account | object | Details of the account to which the payment was sent. See Account Details sub-fields below. Mandatory for IN direction. | Yes |
| direction | string | The direction of the payment relative to your customer. IN for incoming payments to your customer, OUT for outgoing payments from your customer. | Yes |
| channel | string | The channel through which the payment was initiated or processed. Examples: SWIFT, API, WEB, MOBILE, POS. | Yes |
| description | string | A brief textual description of the payment. | Yes |
| reference | string | An optional reference number or identifier provided by the payer/payee. | No |
| category | string | A categorization of the transaction purpose. Examples: SALARY, RENT, UTILITIES, FOOD AND BEVERAGES, TRAVEL. Consistent categorization aids in pattern analysis. | No |
| fee | object | Optional. Details about a fee associated with this transaction. See Fee Details sub-fields below. | No |
| related_transactions | array | An array of strings, where each string is the transaction_id of another related transaction (e.g., original payment for a refund). | Yes |
| card_details | object | Optional. Details specific to card-based transactions. See Card Details sub-fields below. | No |
Account Details Sub-fields (for source_account and destination_account)
Both source_account and destination_account objects share the following structure. All fields within these objects are required.
| Field Name | Type | Description | Required |
|---|---|---|---|
| iban | string | International Bank Account Number. | Yes |
| holder_name | string | The name of the account holder. | Yes |
| bank_name | string | The name of the bank or financial institution. | Yes |
| bic | string | Bank Identifier Code (SWIFT code). | Yes |
Card Details Sub-fields (for card_details)
If provided, the card_details object contains the following details for card-based transactions:
| Field Name | Type | Description | Required |
|---|---|---|---|
| card_network | string | The network of the card (e.g., "VISA", "MASTERCARD", "AMEX"). | Yes |
| card_last4 | string | The last four digits of the card number. | Yes |
| merchant | string | Details about the merchant involved in the transaction. See Merchant Details sub-fields below. | Yes |
Example Payload
{
"events": [
{
"workspaceId": "your_spektr_workspace_id",
"spektrId": "customer_spektr_id_optional",
"createdAt": 1720435200000, // Example: July 8, 2024 10:00:00 AM UTC in milliseconds
"source": "your_system_name",
"customerData": {
"internalId": "your_customer_internal_id"
},
"eventData": {
"transaction_id": "TXN-789012345",
"type": "transfer",
"subtype": "sepa",
"status": "completed",
"amount": 250000, // Represents 2500.00 EUR (assuming smallest unit)
"currency": "EUR",
"source_account": {
"iban": "DE12345678901234567890",
"holder_name": "Alice Smith",
"bank_name": "Example Bank AG",
"bic": "EXABDEFFXXX"
},
"destination_account": {
"iban": "FR0012345678901234567890",
"holder_name": "Bob Johnson",
"bank_name": "Another Bank France",
"bic": "ANBFUS33XXX"
},
"direction": "OUT",
"channel": "WEB",
"description": "Payment for services rendered",
"reference": "INV-2024-001",
"category": "BUSINESS SERVICES",
"fee": {
"amount": 500, // 5.00 EUR
"currency": "EUR",
"description": "Processing Fee"
},
"related_transactions": [],
"card_details": {
"card_network": "VISA",
"card_last4": "1234",
"merchant": {
"name": "Online Superstore",
"category": "E-commerce",
"country": "US"
}
}
},
"type": "paymentMade"
}
]
}