Ledger Reporting
TxB APIs allow Clients to track real-time ledger activity. Clients use this service to understand what transactions have impacted their TxB account balance today (real-time, intraday) or on previous days (end of day, prior days).
Step by step guide
Step 1 - Get a list of all referenceNumbers
Our ledger activities APIs provide information on an account or service level. So, our first step is to get a list of the accounts or services ('referenceNumbers') associated with a TxB Client.
Note
referenceNumber is the unique identifier of a TxB account or service
GET /v1/reports/transactionReports/reportReferences will return a list of accounts or services that the Client currently uses. It returns 2 referenceNumbers, 1 for a deposit account and 1 for a payments only service.
[
{
"referenceNumber": "123456789012",
"referenceType": "DEPOSITACCOUNT", \\ can be Deposit Account or Payments Service Number
"isVirtual": false
},
{
"referenceNumber": "123456789011",
"referenceType": "PAYMENTSONLY", \\ can be Deposit Account or Payments Service Number
"isVirtual": false
}
]Step 2 - Get the transactionReport for the TxB deposit account
GET /v2/reports/transactionReports?referenceNumber='123456789012'&businessDate='10-11-2020&limit=10' returns the full balance info for the account and the first 10 transactions for the requested businessDate:
{
"asOfDateTime": "2020-10-11T23:52:42.279Z",
"references": {
"referenceNumber": "123456789012", // aka accountNumber
"referenceType": "DEPOSITACCOUNT",
"currency": "USD",
"jurisdiction": "US", // Identifies the country of the TxB Branch
"referenceBank": {...}, // Identifies the BIC, Routing Number of the TxB account
"isVirtual": false,
"virtualAccountDetails": { // shows virtual account hierarchy
"parentAccountNumber": null,
"physicalAccountNumber": null
},
"balances": [
{
"balanceType": "AVAILABLE",
"startOfDayBalance": 2000,
"endOfDayBalance": null,
"currentBalance": 1000
},
{
"balanceType": "LEDGER",
"startOfDayBalance": 2000,
"endOfDayBalance": null,
"currentBalance": 1000
}
],
"transactions": [
{
"postingDate": "2020-10-11T16:52:42.279Z",
"valueDate": "2020-10-11",
"transactionType": "Outgoing Wire Return",
"transactionTypeCode": {
"domainCode": "PMNT",
"familyCode": "ICDT",
"subFamilyCode": "RRTN"
},
"transactionDescription": "---"
"returnReasonCode": "AM06" // Return reason code is populated if available.
"returnReasonDescription": "Specified transaction amount is less than agreed minimum" // Return reason description is populated as per the reason code.
"debitOrCredit": "CREDIT"
"amount": 1000.00 ,
"amountCurrency": "USD"
"identifiers": {
"gsUniquePaymentId": "Id_TxB_Created)",
"paymentEndToEndId": "Id_You_Created"
...
},
"linkedRecords": {...} // E.g., returns link to the original payment
...
}
...
],
"hasMore": false
}Step 3 - Interpret the data & repoll if necessary
Based on the data that we return, you will need to perform some analysis and figure out if there are any additional actions required
-
References object
- Use this section to understand how this account fits into a broader portfolio of accounts
- E.g., if this is a multi-currency account or virtual account, you may need to repeat this query on each virtual account to create a full view of transaction activity
-
Balances array
- Use this section to understand how much liquidity is available in the account
- In this case, the
endOfDayBalanceis null, which means that the 'books' have not closed on the account for the day. You may want to poll again at the end of the day (e.g., ~8pm EST) whenendOfDayBalanceis populated - The balances and transactions tie out as expected.
balances[0].startOfDay-transactions[0].amount=balances[0].currentBalance
-
Transactions array
- There is only 1 transaction available for this account on this
businessDate. Note thathasMoreequalsfalse, so there aren't any additional pages of transactions to pull for this account - Each transaction is uniquely identified by the gsUniquePaymentId (think of this as your transactionId)
- In most cases, 1 payment equals 1 transaction, e.g., if I make an outbound wire payment from TxB to another bank, this single wire payment will be reflected as a single transaction
- In other cases, 1 payment equals more than 1 transaction, e.g., if that same wire payment is returned by the receiving bank, then you will see two transactions in your account (1 for the payment and 1 for the return)
- In yet other cases, more than 1 payment equals 1 transaction, e.g., for bulk-processed payments (e.g., US ACH), all N payments within a payment batch will be treated as a single transaction
- There is only 1 transaction available for this account on this
Reference materials
arrow_forwardLearn more about common patterns and standards that TxB APIs use
Transaction Reports API - Standard Version - Sample Response
{
"asOfDateTime": "2026-06-12T06:43:58.309023017Z",
"references": {
"referenceNumber": "107049924",
"referenceName": "Petrochemicals 2",
"referenceBank": {
"bic": "GSCRUS30",
"routingInfo": null,
"bankName": "Goldman Sachs Bank"
},
"referenceType": "DEPOSITACCOUNT",
"jurisdiction": "US",
"currency": "USD",
"isVirtual": false,
"virtualAccountDetails": null
},
"balances": [
{
"balanceType": "LEDGER",
"startOfDayBalance": 2703779455.98,
"endOfDayBalance": 2703777725.20,
"currentBalance": null
},
{
"balanceType": "AVAILABLE",
"startOfDayBalance": 2698560464.62,
"endOfDayBalance": 2698558733.84,
"currentBalance": null
}
],
"transactions": [
{
"postingDate": "2026-05-22T11:05:01Z",
"valueDate": "2026-05-22",
"transactionType": "ACH Credit Payment", // Transaction Type is populated here
"transactionTypeCode": {
"domainCode": "PMNT",
"familyCode": "ICDT",
"subFamilyCode": "ACDT"
},
"transactionDescription": "Entry Description: EXP; -, SEC: CCD, Client Ref ID: 1111, GS ID: BP26142124973427",
"returnReasonCode": null,
"returnReasonDescription": null,
"debitOrCredit": "DEBIT",
"amount": 691.23,
"amountCurrency": "USD",
"fxInfo": null,
"identifiers": {
"paymentRequestId": null,
"collectionRequestId": null,
"paymentEndToEndId": null, // end to end Id is not populated in case of batch postings in standard version
"collectionEndToEndId": null,
"gsUniquePaymentId": "BP26142124973427", // since US ACH is a batch rail, batch level GS ID is populated
"gsPostingIds": [
"BP26142124973427"
],
"railReferenceId": { // rail clearing system reference Id is populated if available
"rail": "ACH",
"railId": null
},
"relatedPartiesTransactionId": null
},
"creditorAccount": null, // since this is a batch posting, creditor details are not populated.
"debtorAccount": {
"accountHolderName": "Petro",
"accountNumber": "107049924 ",
"iban": null,
"bankIdentifier": {
"bic": null,
"routingInfo": {
"code": "USABA",
"value": "026015079"
}
},
"legalEntityIdentifier": ""
},
"messagesFromOriginator": {
"remittanceInfo": null,
"paymentPurpose": null,
"creditorInstruction": null,
"nextAgentInstruction": null,
"structuredRemittance": null
},
"railSpecificInfo": {
"rail": "ACH", // ACH specific information is populated in case of US ACH transactions
"ACHInfo": {
"secCode": "CCD",
"companyName": "Continental Petro",
"companyId": "2880566438",
"companyEntryDescription": "EXP",
"companyDescriptiveDate": null,
"sameOrNextDay": null
},
"SepaMandateInfo": null
},
"relatedParties": null,
"linkedRecords": [],
"paymentPriority": null
},
{
"postingDate": "2026-05-22T17:25:44Z",
"valueDate": "2026-05-22",
"transactionType": "Outgoing Wire",
"transactionTypeCode": {
"domainCode": "PMNT",
"familyCode": "ICDT",
"subFamilyCode": "DMCT"
},
"transactionDescription": "To: UFXQHBE RQHZK OOYV QAA, Remittance Info: \"USD Payment from QAD account\", Client Ref ID: GSU7BZOADPQ, GS ID: GI2614202810249, Clearing Ref: 20260522MMQFMCZZ000157",
"returnReasonCode": null,
"returnReasonDescription": null,
"debitOrCredit": "DEBIT",
"amount": 10.00,
"amountCurrency": "USD",
"fxInfo": null,
"identifiers": {
"paymentRequestId": "GSU7BZOADPQ",
"collectionRequestId": null,
"paymentEndToEndId": "GSU7BZOADPQ", // end to end Id provided by client is populated in case of non-batch postings in standard version
"collectionEndToEndId": null,
"gsUniquePaymentId": "GI2614202810249", // since this is a wire transaction, payment level GS ID is populated
"gsPostingIds": [
"GI2614202810249"
],
"railReferenceId": {
"rail": "FEDWIRE",
"railId": "20260522MMQFMCZZ000157"
},
"relatedPartiesTransactionId": null
},
"creditorAccount": { // since this is a wire payment, creditor details are populated.
"accountHolderName": "UFXQHBE RQHZK OOYV QAA",
"accountNumber": "12345678",
"iban": null,
"bankIdentifier": {
"bic": "ROYCCAT2",
"routingInfo": null
},
"legalEntityIdentifier": ""
},
"debtorAccount": {
"accountHolderName": "Petrochemicals",
"accountNumber": "107049924",
"iban": null,
"bankIdentifier": {
"bic": "GSCRUS30XXX",
"routingInfo": {
"code": "USABA",
"value": "026015079"
}
},
"legalEntityIdentifier": "B1V7KEBTPIMZEU4LTD58"
},
"messagesFromOriginator": {
"remittanceInfo": [ // Remittance information is populated if available
"USD Payment from QAD account"
],
"paymentPurpose": "Tax Payment",
"creditorInstruction": null,
"nextAgentInstruction": null,
"structuredRemittance": null
},
"railSpecificInfo": null,
"relatedParties": null,
"linkedRecords": [],
"paymentPriority": null
},
{
"postingDate": "2026-05-22T17:31:46Z",
"valueDate": "2026-05-22",
"transactionType": "Transfer",
"transactionTypeCode": {
"domainCode": "PMNT",
"familyCode": "ICDT",
"subFamilyCode": "BOOK"
},
"transactionDescription": "To: GOLDMAN SACHS BANK USA, Account: XXXXX-9932, Remittance Info: \"USD Payment from USD account USD Payment from USD account USD Payment from USD account USD Payment from USD account USD Payment from USD acc\", Client Ref ID: GSJ8ZWIZ7EGRND, GS ID: GI2614202810190",
"returnReasonCode": null,
"returnReasonDescription": null,
"debitOrCredit": "DEBIT",
"amount": 13.01,
"amountCurrency": "USD",
"fxInfo": null,
"identifiers": {
"paymentRequestId": "GSWQDEV4FRO",
"collectionRequestId": null,
"paymentEndToEndId": "GSJ8ZWIZ7EGRND",
"collectionEndToEndId": null,
"gsUniquePaymentId": "GI2614202810190",
"gsPostingIds": [
"GI2614202810190"
],
"railReferenceId": {
"rail": "BOOK",
"railId": "GI2614202810190"
},
"relatedPartiesTransactionId": null
},
"creditorAccount": {
"accountHolderName": "GOLDMAN SACHS BANK USA",
"accountNumber": "107049932",
"iban": null,
"bankIdentifier": {
"bic": "GSCRUS30XXX",
"routingInfo": {
"code": "USABA",
"value": "026015079"
}
},
"legalEntityIdentifier": ""
},
"debtorAccount": {
"accountHolderName": "Continental Petrochemicals",
"accountNumber": "107049924",
"iban": null,
"bankIdentifier": {
"bic": "GSCRUS30",
"routingInfo": {
"code": "USABA",
"value": "026015079"
}
},
"legalEntityIdentifier": "B1V7KEBTPIMZEU4LTD58"
},
"messagesFromOriginator": {
"remittanceInfo": [
"USD Payment from USD account USD Payment from USD account USD Payment from USD account USD Payment from USD account USD Payment from USD acc"
],
"paymentPurpose": "Tax Payment",
"creditorInstruction": null,
"nextAgentInstruction": null,
"structuredRemittance": null
},
"railSpecificInfo": null,
"relatedParties": null,
"linkedRecords": [],
"paymentPriority": null
}
],
"hasMore": false
}Transaction Reports API - Itemized Version - Sample Response
{
"asOfDateTime": "2026-06-12T06:46:37.690342198Z",
"references": {
"referenceNumber": "107049924",
"referenceName": "Continental Petrochemicals ACH Test 2",
"referenceBank": {
"bic": "GSCRUS30",
"routingInfo": null,
"bankName": "Goldman Sachs Bank"
},
"referenceType": "DEPOSITACCOUNT",
"jurisdiction": "US",
"currency": "USD",
"isVirtual": false,
"virtualAccountDetails": null
},
"balances": [
{
"balanceType": "LEDGER",
"startOfDayBalance": 2703779455.98,
"endOfDayBalance": 2703777725.20,
"currentBalance": null
},
{
"balanceType": "AVAILABLE",
"startOfDayBalance": 2698560464.62,
"endOfDayBalance": 2698558733.84,
"currentBalance": null
}
],
"transactions": [
{
"postingDate": "2026-05-22T11:05:01Z",
"valueDate": "2026-05-22",
"transactionType": "ACH Credit Payment",
"transactionTypeCode": {
"domainCode": "PMNT",
"familyCode": "ICDT",
"subFamilyCode": "ACDT"
},
"transactionDescription": "Entry Description: EXP; -, SEC: CCD, Client Ref ID: 1111, GS ID: BP26142124973427",
"returnReasonCode": null,
"returnReasonDescription": null,
"debitOrCredit": "DEBIT",
"amount": 234.56,
"amountCurrency": "USD",
"fxInfo": null,
"identifiers": {
"paymentRequestId": null,
"collectionRequestId": null,
"paymentEndToEndId": "GSUSDBKQQN0O", // end to end Id is populated in case of batch rail postings in the itemized version
"collectionEndToEndId": null,
"gsUniquePaymentId": "SB2614203525702", // Since this is an itemized version, payment level GS ID is populated for batch based rails as well.
"gsPostingIds": [
"BP26142124973427" // This is the batch level GS ID and can be used to consolidate all the payments of a single batch in the itemized version.
],
"railReferenceId": {
"rail": "ACH",
"railId": "GSY7FILK1R"
},
"relatedPartiesTransactionId": null
},
"creditorAccount": { // In the itemized version, creditor details are populated for each payment inside the batch.
"accountHolderName": "SMALL COMPANY 1",
"accountNumber": "098765432",
"iban": null,
"bankIdentifier": {
"bic": null,
"routingInfo": {
"code": "USABA",
"value": "021000089"
}
},
"legalEntityIdentifier": ""
},
"debtorAccount": {
"accountHolderName": "Petro",
"accountNumber": "107049924",
"iban": null,
"bankIdentifier": {
"bic": null,
"routingInfo": {
"code": "USABA",
"value": "026015079"
}
},
"legalEntityIdentifier": "B1V7KEBTPIMZEU4LTD58"
},
"messagesFromOriginator": {
"remittanceInfo": null,
"paymentPurpose": null,
"creditorInstruction": null,
"nextAgentInstruction": null,
"structuredRemittance": null
},
"railSpecificInfo": {
"rail": "ACH",
"ACHInfo": {
"secCode": "CCD",
"companyName": "Continental Petro",
"companyId": "2880566438",
"companyEntryDescription": "EXP",
"companyDescriptiveDate": null,
"sameOrNextDay": null
},
"SepaMandateInfo": null
},
"relatedParties": null,
"linkedRecords": [],
"paymentPriority": null
},
{
"postingDate": "2026-05-22T11:05:01Z",
"valueDate": "2026-05-22",
"transactionType": "ACH Credit Payment",
"transactionTypeCode": {
"domainCode": "PMNT",
"familyCode": "ICDT",
"subFamilyCode": "ACDT"
},
"transactionDescription": "Entry Description: EXP; -, SEC: CCD, Client Ref ID: 1111, GS ID: BP26142124973427",
"returnReasonCode": null,
"returnReasonDescription": null,
"debitOrCredit": "DEBIT",
"amount": 456.67,
"amountCurrency": "USD",
"fxInfo": null,
"identifiers": {
"paymentRequestId": null,
"collectionRequestId": null,
"paymentEndToEndId": "GSYRFDORZRCB",
"collectionEndToEndId": null,
"gsUniquePaymentId": "SB2614203525703",
"gsPostingIds": [
"BP26142124973427"
],
"railReferenceId": {
"rail": "ACH",
"railId": null
},
"relatedPartiesTransactionId": null
},
"creditorAccount": {
"accountHolderName": "MEDIUM COMPANY 1",
"accountNumber": "109014056",
"iban": null,
"bankIdentifier": {
"bic": null,
"routingInfo": {
"code": "USABA",
"value": "021000128"
}
},
"legalEntityIdentifier": ""
},
"debtorAccount": {
"accountHolderName": "Continental Petro",
"accountNumber": "107049924",
"iban": null,
"bankIdentifier": {
"bic": null,
"routingInfo": {
"code": "USABA",
"value": "026015079"
}
},
"legalEntityIdentifier": "B1V7KEBTPIMZEU4LTD58"
},
"messagesFromOriginator": {
"remittanceInfo": [
"ADDENDA FOR MEDIUM COMPANY 1"
],
"paymentPurpose": null,
"creditorInstruction": null,
"nextAgentInstruction": null,
"structuredRemittance": null
},
"railSpecificInfo": {
"rail": "ACH",
"ACHInfo": {
"secCode": "CCD",
"companyName": "Continental Petro",
"companyId": "2880566438",
"companyEntryDescription": "EXP",
"companyDescriptiveDate": null,
"sameOrNextDay": null
},
"SepaMandateInfo": null
},
"relatedParties": null,
"linkedRecords": [],
"paymentPriority": null
},
{
"postingDate": "2026-05-22T17:25:44Z",
"valueDate": "2026-05-22",
"transactionType": "Outgoing Wire",
"transactionTypeCode": {
"domainCode": "PMNT",
"familyCode": "ICDT",
"subFamilyCode": "DMCT"
},
"transactionDescription": "To: UFXQHBE RQHZK OOYV QAA, Remittance Info: \"USD Payment from QAD account\", Client Ref ID: GSU7BZOADPQ, GS ID: GI2614202810249, Clearing Ref: 20260522MMQFMCZZ000157",
"returnReasonCode": null,
"returnReasonDescription": null,
"debitOrCredit": "DEBIT",
"amount": 10.00,
"amountCurrency": "USD",
"fxInfo": null,
"identifiers": {
"paymentRequestId": "GSU7BZOADPQ",
"collectionRequestId": null,
"paymentEndToEndId": "GSU7BZOADPQ",
"collectionEndToEndId": null,
"gsUniquePaymentId": "GI2614202810249",
"gsPostingIds": [
"GI2614202810249"
],
"railReferenceId": {
"rail": "FEDWIRE",
"railId": "20260522MMQFMCZZ000157"
},
"relatedPartiesTransactionId": null
},
"creditorAccount": {
"accountHolderName": "UFXQHBE RQHZK OOYV QAA",
"accountNumber": "12345678",
"iban": null,
"bankIdentifier": {
"bic": "ROYCCAT2",
"routingInfo": null
},
"legalEntityIdentifier": ""
},
"debtorAccount": {
"accountHolderName": "Continental Petrochemicals",
"accountNumber": "107049924",
"iban": null,
"bankIdentifier": {
"bic": "GSCRUS30XXX",
"routingInfo": {
"code": "USABA",
"value": "026015079"
}
},
"legalEntityIdentifier": "B1V7KEBTPIMZEU4LTD58"
},
"messagesFromOriginator": {
"remittanceInfo": [
"USD Payment from QAD account"
],
"paymentPurpose": "Tax Payment",
"creditorInstruction": null,
"nextAgentInstruction": null,
"structuredRemittance": null
},
"railSpecificInfo": null,
"relatedParties": null,
"linkedRecords": [],
"paymentPriority": null
},
{
"postingDate": "2026-05-22T17:31:46Z",
"valueDate": "2026-05-22",
"transactionType": "Transfer",
"transactionTypeCode": {
"domainCode": "PMNT",
"familyCode": "ICDT",
"subFamilyCode": "BOOK"
},
"transactionDescription": "To: GOLDMAN SACHS BANK USA, Account: XXXXX-9932, Remittance Info: \"USD Payment from USD account\", Client Ref ID: GSJ8ZWIZ7EGRND, GS ID: GI2614202810190",
"returnReasonCode": null,
"returnReasonDescription": null,
"debitOrCredit": "DEBIT",
"amount": 13.01,
"amountCurrency": "USD",
"fxInfo": null,
"identifiers": {
"paymentRequestId": "GSWQDEV4FRO",
"collectionRequestId": null,
"paymentEndToEndId": "GSJ8ZWIZ7EGRND",
"collectionEndToEndId": null,
"gsUniquePaymentId": "GI2614202810190",
"gsPostingIds": [
"GI2614202810190"
],
"railReferenceId": {
"rail": "BOOK",
"railId": "GI2614202810190"
},
"relatedPartiesTransactionId": null
},
"creditorAccount": {
"accountHolderName": "GOLDMAN SACHS BANK USA",
"accountNumber": "107049932",
"iban": null,
"bankIdentifier": {
"bic": "GSCRUS30XXX",
"routingInfo": {
"code": "USABA",
"value": "026015079"
}
},
"legalEntityIdentifier": ""
},
"debtorAccount": {
"accountHolderName": "Continental Petrochemicals",
"accountNumber": "107049924",
"iban": null,
"bankIdentifier": {
"bic": "GSCRUS30",
"routingInfo": {
"code": "USABA",
"value": "026015079"
}
},
"legalEntityIdentifier": "B1V7KEBTPIMZEU4LTD58"
},
"messagesFromOriginator": {
"remittanceInfo": [
"USD Payment from USD account USD Payment from USD account USD Payment from USD account USD Payment from USD account USD Payment from USD acc"
],
"paymentPurpose": "Tax Payment",
"creditorInstruction": null,
"nextAgentInstruction": null,
"structuredRemittance": null
},
"railSpecificInfo": null,
"relatedParties": null,
"linkedRecords": [],
"paymentPriority": null
}
],
"hasMore": false
}For information about account data access for UK open banking, learn more here.
Was this page useful?
Give feedback to help us improve developer.gs.com and serve you better.