Single ledger entries and book transfers

This guide explains how to use the Post payment API to create single ledger entries and book transfers.

A single ledger entry applies a one-sided posting to an account, either adding funds with a credit or removing funds with a debit. A book transfer moves funds between two accounts by applying both a debit and a credit within the same request. These patterns form the foundation of all balance updates in the Pismo platform.

Cancellation reverses a transaction by applying opposite postings, preserving a complete transaction history.

Concepts

Single ledger entry

A single ledger entry is a one-sided posting applied to a single account. The request contains either a credit object or a debit object. A credit adds funds to the account. A debit removes funds from the account.

Book transfer

A book transfer moves funds between two accounts at the same financial institution. The request contains both a debit object and a credit object. It can optionally execute force transfers when the force_post attribute is set to true.

The Pismo platform processes both postings together, debiting the source account and crediting the destination account in the same transaction.

How it works

The following diagram shows the unified flow for single ledger entries, book transfers, and cancellation.

A single ledger entry affects one account. A book transfer affects two accounts by applying both a debit and a credit. Cancellation reverses a transaction by applying the opposite posting or postings.  

Operation selection patterns

Required fields

Each post payment request requires a processing_code, which defines the financial operation and determines how the Pismo platform processes the posting. Refer to Post payment and Create transaction type for more information.

Each posting requires an account identifier. Depending on the endpoint, use external_account_id or account_id to identify the target account. Refer to Post payment and Post payment (Pismo account ID) for more information.

The tracking_id uniquely identifies the transaction and is used for reconciliation and cancellation.  

Post payment validation checklist

Before sending a Post payment request:

1. Confirm that each leg uses the correct external_account_id (debit and credit).

2. Confirm that the processing_code is valid and mapped to the intended operation type.

3. If you use debit.earmark_id, confirm that the earmark exists and is the intended balance source.

4. If you set force_post: true, do the following:

   • Confirm that the account status allows force operations.

   • Don’t use force with earmark debit (not supported per reference).

Post a credit

Submit a request that contains only a credit object.

POST /payments

{
"tracking_id": "txn-001",
"credit": {
"external_account_id": "acct-123",
"processing_code": "CREDIT_CODE",
"amount": 100.00,
"currency": "USD",
"description": "Cash-in"
}
}

The Pismo platform posts a credit and increases the account balance.

Post a debit

Submit a request that contains only a debit object.

POST /payments

{
"tracking_id": "txn-002",
"debit": {
"external_account_id": "acct-123",
"processing_code": "DEBIT_CODE",
"amount": 50.00,
"currency": "USD",
"description": "ATM withdrawal"
}
}

The Pismo platform posts a debit and decreases the account balance.  

Debit from an earmark

Include earmark_id to debit from a reserved balance.

{
"tracking_id": "txn-003",
"debit": {
"external_account_id": "acct-123",
"processing_code": "DEBIT_CODE",
"amount": 25.00,
"currency": "USD",
"earmark_id": "earmark-001"
}
}

The Pismo platform deducts the amount from the earmarked balance instead of the available balance.  

Execute a book transfer

Submit a request that contains both debit and credit objects.

POST /payments

{
"tracking_id": "txn-004",
"debit": {
"external_account_id": "acct-source",
"processing_code": "TRANSFER_DEBIT",
"amount": 100.00,
"currency": "USD"
},
"credit": {
"external_account_id": "acct-destination",
"processing_code": "TRANSFER_CREDIT",
"amount": 100.00,
"currency": "USD"
}
}

The Pismo platform debits the source account and credits the destination account in a single operation.

Force a transfer

Set force_post to true to override validation rules.

{
"tracking_id": "txn-006",
"force_post": true,
"debit": {
"external_account_id": "acct-source",
"processing_code": "TRANSFER_DEBIT",
"amount": 200.00
},
"credit": {
"external_account_id": "acct-destination",
"processing_code": "TRANSFER_CREDIT",
"amount": 200.00
}
}

The Pismo platform attempts the transfer even if standard constraints would prevent it.  

Cancel a payment

Use the Cancel payment endpoint to reverse a transaction.

POST /payments/cancel

{
"original_tracking_id": "txn-004",
"tracking_id": "txn-004-cancel",
"cancellation_method": "INSTANT"
}

The Pismo platform creates a reversal transaction by applying opposite postings.

Cancellation methods

INSTANT applies the reversal at the current business date.

ORIGINAL_DATES applies the reversal using the original transaction date.

If not provided, the Pismo platform defaults to INSTANT.