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",
    "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`.
`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).
`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.
`ledgerNetworkIdentifiers`	array of object	✅	Routing identifiers for funds movement. See Ledger network identifiers.

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.