Method

payment.fromTransaction

Turn an existing transaction into a payment and apply it, or re-match an existing payment; its other splits are deleted.

Turns a transaction you entered by hand (a deposit that was really a customer's cheque) into a payment, as GnuCash's Assign as Payment does, or changes the matching of an existing payment. It is destructive: every split of the transaction except its transfer split, the one in a bank, cash, asset, liability or equity account, is deleted and rebuilt as the A/R or A/P split of a payment in a new lot, then applied as in payment.process.

Without applyTo it applies to the documents the transaction already pays. A posted document's own transaction cannot be made a payment: unpost the document instead. A void or read-only transaction is refused too.

Examples

Example: with a copy of the synthetic/business-editable example book open as book.gnucash.

JSON-RPC

Request:

{"jsonrpc":"2.0","id":1,"method":"transaction.post","params":{"datePosted":"2024-03-20","description":"Acme cheque","splits":[{"account":"Assets:Bank","value":"500.00"},{"account":"Assets:Receivable","value":"-500.00"}]}}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "…"
}

Request:

{"jsonrpc":"2.0","id":2,"method":"payment.fromTransaction","params":{"transaction":"00ed0000000000000000000000000003","owner":{"type":"customer","id":"5b22073fa4e34411b07c14a77147ce6b"},"applyTo":["aa210b7131de44c48b8513cd27c00e95"]}}

Response:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "transaction": "00ed0000000000000000000000000003",
    "paymentLot": null
  }
}

Request:

{"jsonrpc":"2.0","id":3,"method":"payment.openItems","params":{"owner":{"type":"customer","id":"5b22073fa4e34411b07c14a77147ce6b"},"account":"Assets:Receivable"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "items": [
      {
        "invoice": "aa210b7131de44c48b8513cd27c00e95",
        "balance": {
          "num": "37300",
          "denom": "100"
        },
        "…": "…"
      }
    ]
  }
}

Command line

red-ale exec --book book.gnucash --script - <<'EOF'
transaction.post {"datePosted":"2024-03-20","description":"Acme cheque","splits":[{"account":"Assets:Bank","value":"500.00"},{"account":"Assets:Receivable","value":"-500.00"}]}
payment.fromTransaction {"transaction":"00ed0000000000000000000000000003","owner":{"type":"customer","id":"5b22073fa4e34411b07c14a77147ce6b"},"applyTo":["aa210b7131de44c48b8513cd27c00e95"]}
payment.openItems {"owner":{"type":"customer","id":"5b22073fa4e34411b07c14a77147ce6b"},"account":"Assets:Receivable"}
EOF

It prints:

[
  "…",
  {
    "transaction": "00ed0000000000000000000000000003",
    "paymentLot": null
  },
  {
    "items": [
      {
        "invoice": "aa210b7131de44c48b8513cd27c00e95",
        "balance": {
          "num": "37300",
          "denom": "100"
        },
        "…": "…"
      }
    ]
  }
]

MCP tool call

Tool call:

{"name":"transaction.post","arguments":{"datePosted":"2024-03-20","description":"Acme cheque","splits":[{"account":"Assets:Bank","value":"500.00"},{"account":"Assets:Receivable","value":"-500.00"}]}}

Result:

{
  "content": [
    {
      "type": "text",
      "text": "\"…\""
    }
  ]
}

Tool call:

{"name":"payment.fromTransaction","arguments":{"transaction":"00ed0000000000000000000000000003","owner":{"type":"customer","id":"5b22073fa4e34411b07c14a77147ce6b"},"applyTo":["aa210b7131de44c48b8513cd27c00e95"]}}

Result:

{
  "structuredContent": {
    "transaction": "00ed0000000000000000000000000003",
    "paymentLot": null
  }
}

Tool call:

{"name":"payment.openItems","arguments":{"owner":{"type":"customer","id":"5b22073fa4e34411b07c14a77147ce6b"},"account":"Assets:Receivable"}}

Result:

{
  "structuredContent": {
    "items": [
      {
        "invoice": "aa210b7131de44c48b8513cd27c00e95",
        "balance": {
          "num": "37300",
          "denom": "100"
        },
        "…": "…"
      }
    ]
  }
}

Example: with a copy of the synthetic/business-editable example book open as book.gnucash.

JSON-RPC

Request:

{"jsonrpc":"2.0","id":1,"method":"payment.fromTransaction","params":{"transaction":"0ffd3608651e4faa8e39816c17e6a3b1"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": 2001,
    "message": "a posted document's transaction cannot become a payment; unpost the document",
    "data": {
      "help": "error/invalid"
    }
  }
}

Command line

red-ale exec --book book.gnucash payment.fromTransaction '{"transaction":"0ffd3608651e4faa8e39816c17e6a3b1"}'

It fails with exit status 2, printing on standard error:

{
  "error": {
    "code": 2001,
    "message": "a posted document's transaction cannot become a payment; unpost the document",
    "data": {
      "help": "error/invalid"
    }
  }
}

MCP tool call

Tool call:

{"name":"payment.fromTransaction","arguments":{"transaction":"0ffd3608651e4faa8e39816c17e6a3b1"}}

Result:

{
  "isError": true,
  "structuredContent": {
    "error": {
      "code": 2001,
      "name": "invalid",
      "message": "a posted document's transaction cannot become a payment; unpost the document",
      "data": {
        "help": "error/invalid"
      }
    }
  }
}

Effect: destructive, on the Book.

Params

Params of payment.fromTransaction. Absent params take the payment dialog's defaults.

  • transaction (Guid, required): The transaction.
  • owner (OwnerParam or null): Who pays or is paid. Default: the owner of the document or pre-payment its A/R or A/P split is in.
  • account (AccountRef or null): The A/Receivable or A/Payable account. Default: that of the transaction's A/R or A/P splits.
  • transferSplit (Guid or null): The split to keep as the payment's transfer split. Default: the only split in a bank, cash, asset, liability or equity account.
  • amount (Amount or null): The payment, signed as in payment.process. Default: the transfer split's amount; needed when the transfer and A/R or A/P commodities differ.
  • exchangeRate (Amount or null): Units of the transfer account's commodity per unit of the A/R or A/P account's commodity, when they differ.
  • date (Date or null): The payment date. Default: the transaction's posted date.
  • memo (string or null): Memo of the A/R or A/P split. Default: the transaction's description.
  • num (string or null): Transaction number. Default: the transaction's.
  • applyTo (array of Guid or null): Documents (invoice GUIDs) and pre-payment lots to apply it to. Default: the documents and pre-payments the transaction is already applied to that would stay open without it.
  • autoPay (boolean): With nothing to apply to: apply to all the owner's open documents and pre-payments.

Result

Result of a payment.

  • transaction (Guid or null): The payment transaction (none when the amount is zero).
  • paymentLot (Guid or null): The lot holding what was not applied: a pre-payment.