Event types

Tesouro emits the following event types for embedded banking. Every delivery uses the common envelope; each event type below documents the attributes shape and includes an example payload.

attributes.rawData is a verbatim pass-through from the upstream banking core. Tesouro doesn’t control or guarantee its structure, field names, or stability - it can change without notice. Use the documented attributes fields for business logic. Treat rawData as opaque except for debugging and audit.

LEDGER_TRANSACTION

A monetary transaction posted to the ledger.

Attributes

Field	Type	Description
`organizationId`	string (UUID)	Tesouro organization id of the business customer this event applies to.
`organizationName`	string	Display name of the business customer.
`accountNumber`	string	Account number associated with the event.
`bankAccountId`	string (UUID)	Tesouro’s internal id for the account. Empty (`""`) on events recorded before Tesouro started attaching this field.
`routingNumber`	string	Routing number (ABA).
`eventType`	string	Mirrors the envelope `eventType`. Always `"LEDGER_TRANSACTION"`.
`reference`	string	The reference you supplied on the money movement, echoed back when Tesouro ties the event to a transfer you initiated. See the note below.
`rawData`	object	The original event payload from the upstream banking core, passed through unchanged.

reference is best effort. It’s absent on a posting you didn’t originate, such as a deposit from a third party, and on a transfer you did originate whose settlement path carries no identifier Tesouro can match. Which path a transfer takes depends on how your bank routes that payment rail. Correlate against the transfers list when it has to be reliable.

Example

A LEDGER_TRANSACTION delivery for a $50 ACH pull you initiated with the reference INV-10423, settling as an incoming credit to the account:

{
  "version": "1",
  "deliveryId": "00000000-0000-0000-0000-000000000099",
  "webhookUrl": "https://your-endpoint.example.com/webhooks/tesouro",
  "deliveryDateTimeUtc": "2026-05-08T00:00:00.000000Z",
  "attemptCount": "1",
  "eventType": "LEDGER_TRANSACTION",
  "attributes": {
    "organizationId": "00000000-0000-0000-0000-000000000001",
    "organizationName": "Tesouro Test Customer LLC",
    "accountNumber": "9999999999999",
    "bankAccountId": "11111111-1111-1111-1111-111111111111",
    "routingNumber": "000000000",
    "eventType": "LEDGER_TRANSACTION",
    "reference": "INV-10423",
    "rawData": {
      "id": "aabbccdd-1111-2222-3333-444455558888",
      "fisorganizationid": "9700",
      "adtDtl": {
        "evtNme": "monetary_transaction",
        "ver": "1_2_0",
        "msgUuid": "aabbccdd-1111-2222-3333-444455557799",
        "srcId": "BackOffice",
        "applId": "DP_RDP",
        "operTs": "2026-05-07T00:00:00.000000Z",
        "usrId": "MBPAPI_SVC_ACCOUNT",
        "deviceId": "BackOffice",
        "busPrcs": "DPCreateMonetaryTransaction_v2.0.0",
        "pubFeKey": {
          "feId": "9700",
          "sorFe": {
            "sorFeId": "9700",
            "sor": { "prcsrNme": "FIS NextGen", "applNme": "Deposits" }
          }
        },
        "prcsDte": "2026-05-07"
      },
      "mntryTxnKey": {
        "arKey": {
          "entprsArTyp": "Checking",
          "arId": "9999999999999",
          "sor": { "prcsrNme": "FIS NextGen", "applNme": "Deposits" }
        },
        "txnKey": { "txnRefNbr": 9000099999001, "pstId": 7000099999001 }
      },
      "mntryTxnDtl": {
        "pstDtl": {
          "pstCmmnData": {
            "pstStdCde": "ACHIncomingCredit",
            "origAmt": { "amt": 50.0, "crncyCde": "USD" },
            "pstAmt": { "amt": 50.0, "crncyCde": "USD" },
            "baseAmt": { "amt": 50.0, "crncyCde": "USD" },
            "pstEffDte": "2026-05-07",
            "pstEffTme": "00:00:00",
            "pstIntrstValDte": "2026-05-07",
            "pstDfltNarr": "ACH Incoming Credit"
          },
          "pstFeeDtl": []
        },
        "stlmtDtl": {
          "bnkIdTyp": "ABA Number",
          "bnkRefId": "000000000",
          "stlmtAr": {
            "arRefId": {
              "entprsArTyp": "Consumer Checking",
              "arId": "9999999999999",
              "sor": { "prcsrNme": "FIS NextGen", "applNme": "Deposits" }
            },
            "extArRef": { "extArRefIdTyp": "Consumer Checking", "extArRefId": "9999999999999" }
          },
          "stlmtMeth": "ACH",
          "stlmtDte": "2026-05-07",
          "amt": { "amt": 50.0, "crncyCde": "USD" }
        },
        "pubBalDtl": [
          {
            "balCde": "LedgerBalance",
            "balNme": "Ledger Balance",
            "amt": { "amt": 50.0, "crncyCde": "USD" },
            "balTypCde": "LedgerBalance",
            "actgClassCde": "Liability",
            "pmtTyp": "Credit",
            "balChgAmt": { "amt": 50.0, "crncyCde": "USD" },
            "effDte": "2026-05-07",
            "effTme": "00:00:00"
          }
        ],
        "pubPstDtl": {
          "pmtTyp": "Credit",
          "pstDte": "2026-05-07",
          "pstTs": "2026-05-07T00:00:00.100000Z",
          "busEvtCde": "FundsTransfer",
          "busEvtDte": "2026-05-07",
          "txnStat": "Processed",
          "chnlId": "EPS",
          "cshStlmtTypCde": "ACH"
        }
      },
      "adtnlAdtDtl": {
        "bkDte": "2026-05-07",
        "hostTs": "2026-05-07T00:00:00.100000Z",
        "acptTs": "2026-05-07T00:00:00.000000Z",
        "acptTsUtcOfst": "-05:00"
      }
    }
  }
}

LEDGER_POSTING_EXCEPTION

Posting a transaction raised an exception.

Attributes

Same shape as LEDGER_TRANSACTION, with one difference: eventType is always "LEDGER_POSTING_EXCEPTION". rawData carries the upstream exception payload instead of a successful posting.

Example

A posting exception on a transfer you initiated carries that transfer’s reference:

{
  "version": "1",
  "deliveryId": "00000000-0000-0000-0000-000000000098",
  "webhookUrl": "https://your-endpoint.example.com/webhooks/tesouro",
  "deliveryDateTimeUtc": "2026-05-08T00:00:00.000000Z",
  "attemptCount": "1",
  "eventType": "LEDGER_POSTING_EXCEPTION",
  "attributes": {
    "organizationId": "00000000-0000-0000-0000-000000000001",
    "organizationName": "Tesouro Test Customer LLC",
    "accountNumber": "9999999999999",
    "bankAccountId": "11111111-1111-1111-1111-111111111111",
    "routingNumber": "000000000",
    "eventType": "LEDGER_POSTING_EXCEPTION",
    "reference": "INV-10424",
    "rawData": {
      "id": "aabbccdd-1111-2222-3333-555566667777",
      "fisorganizationid": "9700",
      "adtDtl": { "evtNme": "MonetaryTransactionException" },
      "mntryTxnExcpKey": {
        "arKey": { "arId": "9999999999999" },
        "txnKey": { "txnRefNbr": 9000099999002 }
      },
      "mntryTxnExcpDtl": {
        "txnExcpDtl": { "excpStat": "PENDING", "dfltActn": "RETURN" },
        "pubTxnDtl": {
          "stlmtDtl": {
            "bnkRefId": "000000000",
            "stlmtAr": { "arRefId": { "arId": "9999999999999" } }
          }
        }
      }
    }
  }
}

LEDGER_ACCOUNT_EXCEPTION

A ledger account raised an exception.

Attributes

Same shape as LEDGER_TRANSACTION, with two differences: eventType is always "LEDGER_ACCOUNT_EXCEPTION", and routingNumber may be empty. rawData carries the upstream exception payload, and reference never appears.

Example

{
  "version": "1",
  "deliveryId": "00000000-0000-0000-0000-000000000097",
  "webhookUrl": "https://your-endpoint.example.com/webhooks/tesouro",
  "deliveryDateTimeUtc": "2026-05-08T00:00:00.000000Z",
  "attemptCount": "1",
  "eventType": "LEDGER_ACCOUNT_EXCEPTION",
  "attributes": {
    "organizationId": "00000000-0000-0000-0000-000000000001",
    "organizationName": "Tesouro Test Customer LLC",
    "accountNumber": "9999999999999",
    "bankAccountId": "11111111-1111-1111-1111-111111111111",
    "routingNumber": "000000000",
    "eventType": "LEDGER_ACCOUNT_EXCEPTION",
    "rawData": {
      "id": "aabbccdd-1111-2222-3333-888899990000",
      "fisorganizationid": "9700",
      "adtDtl": { "evtNme": "MBPPUBARException" },
      "arBusExcp": {
        "arKey": { "entprsArTyp": "Checking", "arId": "9999999999999" },
        "busEvtCde": "FundsTransfer",
        "msg": [{ "cde": "DP006046", "desc": "Stop Hit occurred", "typ": "Validation Error" }]
      }
    }
  }
}

ACCOUNT_STATUS_CHANGED

A ledger account’s status changed (for example, opened, closed, dormant, or charged off).

Attributes

Same shape as LEDGER_TRANSACTION, with two differences: eventType is always "ACCOUNT_STATUS_CHANGED", and routingNumber is empty. rawData carries the upstream status-change payload, including the new primary and secondary status values. reference never appears.

Example

{
  "version": "1",
  "deliveryId": "00000000-0000-0000-0000-000000000096",
  "webhookUrl": "https://your-endpoint.example.com/webhooks/tesouro",
  "deliveryDateTimeUtc": "2026-05-08T00:00:00.000000Z",
  "attemptCount": "1",
  "eventType": "ACCOUNT_STATUS_CHANGED",
  "attributes": {
    "organizationId": "00000000-0000-0000-0000-000000000001",
    "organizationName": "Tesouro Test Customer LLC",
    "accountNumber": "9999999999999",
    "bankAccountId": "11111111-1111-1111-1111-111111111111",
    "routingNumber": "000000000",
    "eventType": "ACCOUNT_STATUS_CHANGED",
    "rawData": {
      "id": "aabbccdd-1111-2222-3333-111122223333",
      "fisorganizationid": "9700",
      "adtDtl": {
        "evtNme": "account_status_change",
        "ver": "1_2_0",
        "msgUuid": "aabbccdd-1111-2222-3333-111122224444",
        "srcId": "BackOffice",
        "applId": "DP_RDP",
        "operTs": "2026-05-07T00:00:00.000000Z",
        "busPrcs": "DPCasaCreateArrangement_v1.9.0",
        "prcsDte": "2026-05-07"
      },
      "arKey": {
        "entprsArTyp": "Checking",
        "arId": "9999999999999",
        "sor": { "prcsrNme": "FIS NextGen", "applNme": "Deposits" }
      },
      "arStatDtl": {
        "prmyStat": "Active",
        "scndyStat": "Normal",
        "statEffDte": "2026-05-07",
        "custIndcInd": false,
        "adtnlDtl": [{ "typ": "ProductMarketingCode", "val": "MRKT001" }]
      }
    }
  }
}

ACCOUNT_RESTRICTION_CHANGED

A ledger account’s restrictions changed (for example, an account freeze was added for suspected fraud).

Attributes

Same shape as LEDGER_TRANSACTION, with eventType always "ACCOUNT_RESTRICTION_CHANGED". rawData carries the upstream restriction payload, including the action (actnCde is ADD, CHANGE, or DELETE) and the restriction detail. reference never appears.

Example

{
  "version": "1",
  "deliveryId": "00000000-0000-0000-0000-000000000095",
  "webhookUrl": "https://your-endpoint.example.com/webhooks/tesouro",
  "deliveryDateTimeUtc": "2026-05-08T00:00:00.000000Z",
  "attemptCount": "1",
  "eventType": "ACCOUNT_RESTRICTION_CHANGED",
  "attributes": {
    "organizationId": "00000000-0000-0000-0000-000000000001",
    "organizationName": "Tesouro Test Customer LLC",
    "accountNumber": "9999999999999",
    "bankAccountId": "11111111-1111-1111-1111-111111111111",
    "routingNumber": "000000000",
    "eventType": "ACCOUNT_RESTRICTION_CHANGED",
    "rawData": {
      "id": "aabbccdd-1111-2222-3333-555566669999",
      "fisorganizationid": "9700",
      "adtDtl": {
        "evtNme": "account_restriction",
        "ver": "1_0_0",
        "msgUuid": "aabbccdd-1111-2222-3333-555566660001",
        "srcId": "BackOffice",
        "applId": "DP_RDP",
        "operTs": "2026-05-07T00:00:00.000000Z",
        "busPrcs": "DPRecordArrangementException_v1.2.0",
        "prcsDte": "2026-05-07"
      },
      "acctRstrcKey": {
        "entprsArTyp": "Checking",
        "arId": "9999999999999",
        "sor": { "prcsrNme": "FIS NextGen", "applNme": "Deposits" }
      },
      "acctRstrcDtl": {
        "actnCde": "ADD",
        "arExcpDtl": {
          "cde": "AccountFreeze",
          "resn": "Fraud Is Suspected",
          "desc": "Customer lost wallet",
          "effDte": "2026-05-07",
          "clazz": "Error"
        }
      }
    }
  }
}

IDENTITY_VERIFICATION_STATUS_CHANGED

The identity-verification (KYC) status changed for a bank account application. The attributes carry the application, the organization it belongs to, and the status transition.

Attributes

Field	Type	Description
`organizationId`	string (UUID)	Tesouro organization id of the business customer this event applies to.
`organizationName`	string	Display name of the business customer.
`applicationId`	string (UUID)	The bank account application the decision belongs to.
`externalApplicationId`	string	The same application in its original external (identity provider) form.
`eventType`	string	Mirrors the envelope `eventType`. Always `"IDENTITY_VERIFICATION_STATUS_CHANGED"`.
`previousStatus`	string	The status the application held before this change. Empty (`""`) when this is the first status the application received.
`newStatus`	string	The status now persisted on the application. One of the status values below.

Status values (previousStatus and newStatus):

Value	Meaning
`PENDING`	Verification is in progress; no decision yet.
`MANUAL_REVIEW`	Flagged for manual review.
`APPROVED`	Identity verification passed.
`DENIED`	Identity verification did not pass.

This event fires only on an actual status transition. Once a transition is queued for delivery, it follows the standard delivery and retry behavior: failed attempts are retried, and you should deduplicate on deliveryId. Separately, forwarding a transition into the webhook pipeline is best effort, so on rare occasions a status change is never queued and no event is sent for it at all. Where correctness matters, reconcile against the kycVerificationStatus field returned by GET /embedded-banking/v1/bank-account-applications/{id} rather than relying on receiving an event for every transition. Its values (PENDING, MANUAL_REVIEW, APPROVED, DENIED) match this event’s newStatus.

Example

An IDENTITY_VERIFICATION_STATUS_CHANGED delivery for an application that cleared manual review and was approved:

{
  "version": "1",
  "deliveryId": "00000000-0000-0000-0000-000000000094",
  "webhookUrl": "https://your-endpoint.example.com/webhooks/tesouro",
  "deliveryDateTimeUtc": "2026-05-08T00:00:00.000000Z",
  "attemptCount": "1",
  "eventType": "IDENTITY_VERIFICATION_STATUS_CHANGED",
  "attributes": {
    "organizationId": "00000000-0000-0000-0000-000000000001",
    "organizationName": "Tesouro Test Customer LLC",
    "applicationId": "33333333-3333-3333-3333-333333333333",
    "externalApplicationId": "0f1e2d3c-4b5a-6789-abcd-ef0123456789",
    "eventType": "IDENTITY_VERIFICATION_STATUS_CHANGED",
    "previousStatus": "MANUAL_REVIEW",
    "newStatus": "APPROVED"
  }
}

BANK_ACCOUNT_APPLICATION_STATUS_CHANGED

A bank account application’s status changed.

Attributes

Field	Type	Description
`organizationId`	string (UUID)	Tesouro organization id of the business customer this event applies to.
`organizationName`	string	Display name of the business customer.
`applicationId`	string (UUID)	The bank account application that changed.
`bankAccountId`	string (UUID)	The account opened for this application. Empty (`""`) until the application reaches `COMPLETE`.
`eventType`	string	Mirrors the envelope `eventType`. Always `"BANK_ACCOUNT_APPLICATION_STATUS_CHANGED"`.
`previousStatus`	string	The status the application held before this change. Empty (`""`) when this is the first status the application received.
`newStatus`	string	The status now persisted on the application. One of the status values below.

Status values (previousStatus and newStatus):

Value	Meaning
`DRAFT`	The application was created and can still be edited.
`SUBMITTED`	The applicant submitted the application to the bank for a decision.
`COMPLETE`	The bank approved the application and opened the account. `bankAccountId` is set on this transition.
`DENIED`	The bank declined the application.
`CANCELED`	The application was canceled before a decision.
`DELETED`	The application was deleted while still in `DRAFT`.

Example

A BANK_ACCOUNT_APPLICATION_STATUS_CHANGED delivery for an application the bank approved, carrying the new account’s id:

{
  "version": "1",
  "deliveryId": "00000000-0000-0000-0000-000000000093",
  "webhookUrl": "https://your-endpoint.example.com/webhooks/tesouro",
  "deliveryDateTimeUtc": "2026-05-08T00:00:00.000000Z",
  "attemptCount": "1",
  "eventType": "BANK_ACCOUNT_APPLICATION_STATUS_CHANGED",
  "attributes": {
    "organizationId": "00000000-0000-0000-0000-000000000001",
    "organizationName": "Tesouro Test Customer LLC",
    "applicationId": "33333333-3333-3333-3333-333333333333",
    "bankAccountId": "11111111-1111-1111-1111-111111111111",
    "eventType": "BANK_ACCOUNT_APPLICATION_STATUS_CHANGED",
    "previousStatus": "SUBMITTED",
    "newStatus": "COMPLETE"
  }
}

BANK_ACCOUNT_APPLICATION_KYC_STATUS_CHANGED

The KYC decision status changed for a bank account application.

Attributes

Same shape as BANK_ACCOUNT_APPLICATION_STATUS_CHANGED, with two differences: eventType is always "BANK_ACCOUNT_APPLICATION_KYC_STATUS_CHANGED", and previousStatus/newStatus come from the KYC status values below instead of the application status values. Status values (previousStatus and newStatus):

Value	Meaning
`PENDING`	Verification is in progress; no decision yet.
`MANUAL_REVIEW`	Flagged for manual review.
`APPROVED`	Identity verification passed.
`DENIED`	Identity verification did not pass.

bankAccountId is usually empty ("") on this event: KYC is normally decided before the account exists. It’s populated only when the decision is recorded after the account has already been opened.

Example

A BANK_ACCOUNT_APPLICATION_KYC_STATUS_CHANGED delivery for an application that cleared manual review, with no account opened yet:

{
  "version": "1",
  "deliveryId": "00000000-0000-0000-0000-000000000092",
  "webhookUrl": "https://your-endpoint.example.com/webhooks/tesouro",
  "deliveryDateTimeUtc": "2026-05-08T00:00:00.000000Z",
  "attemptCount": "1",
  "eventType": "BANK_ACCOUNT_APPLICATION_KYC_STATUS_CHANGED",
  "attributes": {
    "organizationId": "00000000-0000-0000-0000-000000000001",
    "organizationName": "Tesouro Test Customer LLC",
    "applicationId": "33333333-3333-3333-3333-333333333333",
    "bankAccountId": "",
    "eventType": "BANK_ACCOUNT_APPLICATION_KYC_STATUS_CHANGED",
    "previousStatus": "MANUAL_REVIEW",
    "newStatus": "APPROVED"
  }
}

Getting started

Authentication

Organizations

Users

Bank account applications

Bank accounts

Webhooks

Money movement

Transactions

Embedded components

White-label

LEDGER_TRANSACTION

Attributes

Example

LEDGER_POSTING_EXCEPTION

Attributes

Example

LEDGER_ACCOUNT_EXCEPTION

Attributes

Example

ACCOUNT_STATUS_CHANGED

Attributes

Example

ACCOUNT_RESTRICTION_CHANGED

Attributes

Example

IDENTITY_VERIFICATION_STATUS_CHANGED

Attributes

Example

BANK_ACCOUNT_APPLICATION_STATUS_CHANGED

Attributes

Example

BANK_ACCOUNT_APPLICATION_KYC_STATUS_CHANGED

Attributes

Example

​LEDGER_TRANSACTION

​Attributes

​Example

​LEDGER_POSTING_EXCEPTION

​Attributes

​Example

​LEDGER_ACCOUNT_EXCEPTION

​Attributes

​Example

​ACCOUNT_STATUS_CHANGED

​Attributes

​Example

​ACCOUNT_RESTRICTION_CHANGED

​Attributes

​Example

​IDENTITY_VERIFICATION_STATUS_CHANGED

​Attributes

​Example

​BANK_ACCOUNT_APPLICATION_STATUS_CHANGED

​Attributes

​Example

​BANK_ACCOUNT_APPLICATION_KYC_STATUS_CHANGED

​Attributes

​Example

LEDGER_TRANSACTION

Attributes

Example

LEDGER_POSTING_EXCEPTION

Attributes

Example

LEDGER_ACCOUNT_EXCEPTION

Attributes

Example

ACCOUNT_STATUS_CHANGED

Attributes

Example

ACCOUNT_RESTRICTION_CHANGED

Attributes

Example

IDENTITY_VERIFICATION_STATUS_CHANGED

Attributes

Example

BANK_ACCOUNT_APPLICATION_STATUS_CHANGED

Attributes

Example

BANK_ACCOUNT_APPLICATION_KYC_STATUS_CHANGED

Attributes

Example