Ledger Created

When to use it: Use this webhook to notify the Platform whenever a new ledger is created by a banking provider so the Platform can reflect it and trigger downstream processes.

webhookType: LEDGER_CREATED

Request Body

The webhook payload consists of two main sections:

Ledger Profile (ledgerProfile) Contains complete ledger information including identity, provider configuration, currency/location, and financial status.
Business Profile (businessProfile) Contains information about the business ownership and associations.

{
  "ledgerProfile": {
    "ledgerId": "e7b8a9c2-4f3b-4a2e-9c1d-123456789abc",
    "alias": "Primary Trading Account",
    "ledgerType": "REGULAR",
    "ledgerAttributes": ["MAIN", "EXTERNALLY_MANAGED"],
    "createdAt": "2024-06-01T12:00:00Z",
    "bankingProvider": "BANKING_PROVIDER_ABC",
    "status": "ACTIVE",
    "assetType": "eur",
    "countryCode": "DE",
    "availableBalance": 15000.75,
    "currentBalance": 18500.25,
    "partnerProduct": "PremiumBusiness",
    "productId": "PremiumProduct",
    "ledgerNetworkIdentifiers": [
      {
        "type": "IBAN",
        "value": "DE89370400440532013000"
      },
      {
        "type": "BIC_SWIFT",
        "value": "COBADEFFXXX"
      }
    ]
  },
  "businessProfile": {
    "customer": "TOQIO",
    "merchantId": "507f1f77bcf86cd799439011"
  }
}

ledgerProfile fields

Field	Type	Required	Description
`ledgerId`	string	✅	Unique identifier of the ledger.
`alias`	string	✅	Descriptive name of the ledger.
`ledgerType`	string	✅	Type of ledger. One of `REGULAR`, `ACQUIRING`, `DEPOSIT`, `POS` or `CREDIT`.
`ledgerAttributes`	array of string	❌	Optional flags describing ledger characteristics. See Ledger attributes.
`createdAt`	string or null	❌	ISO 8601 timestamp for when the ledger was created by the provider. If omitted, defaults to Platform ingestion time.
`bankingProvider`	string	✅	Associated banking provider.
`status`	string	✅	Current status, e.g. `ACTIVE`, `PENDING`, `CLOSED`.
`assetType`	string	✅	Currency code (ISO 4217 in lower case).
`countryCode`	string	✅	Country code (ISO 3166-1 alpha-2).
`availableBalance`	number or null	❌	Available balance. Defaults to `0.0` if omitted.
`currentBalance`	number or null	❌	Total balance. Defaults to `0.0` if omitted.
`partnerProduct`	string	❌ (*)	Associated partner product. When `productId` is set, `partnerProduct` is ignored.
`productId`	string	❌ (*)	Associated product. When `productId` is not set, `partnerProduct` is mandatory and the system uses the default product for the given ledger type.
`ledgerNetworkIdentifiers`	array of object	✅	Routing identifiers for funds movement. See Ledger network identifiers.

(*) ⚠️ Clarification:

When productId is set, partnerProduct is ignored.
When productId is not set, partnerProduct is mandatory and the system uses the default product for the given ledger type.

businessProfile fields

Field	Type	Required	Description
`customer`	string	✅	Toqio customer identifier.
`merchantId`	string	✅	Toqio merchant identifier.

Ledger attributes

Attribute	Description	Applies To
`MAIN`	Primary ledger for the merchant.	`REGULAR`
`EXTERNALLY_MANAGED`	Managed by an external provider; used for visualization/reporting in the Platform.	All types
`CARD_ISSUING_RESTRICTED`	Card issuance is disabled for this ledger.	`REGULAR`

An empty array is valid if no special attributes apply.

Ledger network identifiers

Field	Type	Required	Description
`type`	string	✅	Identifier type, e.g. `IBAN`, `BIC_SWIFT`, `LOCAL_ACCOUNT_NUMBER`.
`value`	string	✅	Identifier value.

Supported types

IBAN — International Bank Account Number
BIC_SWIFT — Bank Identifier Code / SWIFT Code
LOCAL_ACCOUNT_NUMBER — Local account number
SORT_CODE — UK sort code
FEDWIRE_ROUTING_NUMBER — US Fedwire routing number
ACH_ROUTING_NUMBER — US ACH routing number

Implementation notes

Idempotency: Use ledgerId as your idempotent key to upsert or de-duplicate events.
Timestamps: Prefer provider event time in createdAt; otherwise rely on Platform ingestion time.
Routing data: Provide at least one primary identifier in ledgerNetworkIdentifiers so funds movement operations work out-of-the-box.