spree-kashflow 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ff9334bd3e09ee1cdb9965f3eddc61af9d887161dd95901c9b54bc6feaf15cdc
+  data.tar.gz: 7e4576dd85f13c15326591811c0d05a6efa17de61a44e1b82b6a62fca8dd0717
+SHA512:
+  metadata.gz: d55939c427bc7154665e69801126b67a35cc95f01024f9303f9d380377b3b290db422ce3e67cd802c98465a65db9b85bdb47f01c015e84340062bdcebe60856a
+  data.tar.gz: b785bbb7a59d6a80686fe13b3cab2f37b83e4d7d7d97d87369c13c09a469852a76604a51d431f5a6e433953ce1e1242feb68f67ffecc10397ee5dff8576f28e7

data/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## 0.1.0
+
+- Initial release.
+- Pushes completed orders to KashFlow as invoices over the SOAP API, with the
+  customer upserted and the payment recorded.
+- Pushes refunds as credit notes (negative invoices) linked to the original
+  invoice.
+- Configured per store through Spree's Integrations framework; nominal codes and
+  bank account are chosen from the connected KashFlow account.
+- Refuses to post an invoice whose assembled total does not match the order
+  total, recording the failure instead.
+- Requires Spree >= 5.6. No migrations.

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2026 Aypex
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,257 @@
+# Spree::Kashflow
+
+A [Spree](https://github.com/spree/spree) extension that posts completed orders to
+[KashFlow](https://www.kashflow.com/) as invoices, and refunds as credit notes, over
+KashFlow's SOAP API.
+
+## Why SOAP, not REST?
+
+KashFlow has two APIs. The REST API's own docs carry a production disclaimer —
+["you should not be using it in a production environment"](https://api.kashflow.com/) —
+that has stood, unrevised, since October 2018. The SOAP API is the one KashFlow
+actually supports for production integrations, so that's what this gem uses.
+
+## Installation
+
+```bash
+bundle add spree-kashflow
+```
+
+Requires Spree >= 5.6 and Ruby >= 3.3. There are no migrations and no generator to
+run — installing the gem and restarting the app is the whole install.
+
+## Configuration
+
+In the Spree admin, go to **Configuration → Integrations → New Integration** and
+choose **KashFlow** (listed under the "Accounting" group).
+
+Enter your KashFlow **API username** and **API password**. Two things trip people up
+here:
+
+- The **SOAP API must be explicitly enabled** on the KashFlow account before these
+  credentials will work — it's not on by default.
+- The KashFlow **API password is often not the same as the login password**. Check
+  KashFlow's API settings for the credentials it issues specifically for API access.
+
+Four more fields decide where money lands in the ledger:
+
+| Field | Purpose |
+|---|---|
+| Sales nominal code | Ledger account line items post to |
+| Shipping nominal code | Ledger account shipping charges post to |
+| Bank account | Account payments are recorded against |
+| Payment method | KashFlow payment method used when recording a payment |
+
+All four are required — there are no defaults, because a wrong nominal code
+silently posts revenue to the wrong place.
+
+**The first save always fails, and that's expected.** All six fields render from
+the start, but the four dropdowns are populated by live lookups against the
+connected account, which can only run once credentials are *persisted*. Since
+all four are also validated as present and greater than zero, the first submit
+cannot pass. The flow is:
+
+1. Enter the API username and password. Leave the four dropdowns alone — they
+   are empty.
+2. Save. The form comes back with validation errors on the four numeric fields.
+   This is the expected outcome, not a misconfiguration.
+3. The dropdowns are now populated from the connected account. Pick all four.
+4. Save again. This one succeeds.
+
+If the dropdowns are still empty after step 2, the credentials were rejected —
+re-check the two gotchas above.
+
+No further setup is needed for metafields: this gem uses Spree's metafields
+framework to track sync state and seeds its own `MetafieldDefinition` records on
+first write, as **back-end only**. Nothing needs to be seeded by hand, and
+nothing this gem stores (invoice numbers, customer codes, raw KashFlow error
+text) is ever exposed on the storefront.
+
+## Before you go live
+
+**No payload in this gem has been verified against a live KashFlow account.**
+Every field name, sequence order and value shape is inferred from the vendored
+WSDL (`docs/kashflow-service.wsdl`) and from KashFlow's documented conventions;
+the test suite asserts the SOAP request bodies this gem *sends*, but nothing has
+been posted to a real account and read back. Verifying an invoice, a payment and
+a credit note end-to-end against a live (or sandbox) KashFlow account is a
+release gate, not an optional extra.
+
+Check these, in this order:
+
+1. **The `"OK"` status token — check this first.** `Client::SUCCESS_STATUS` is
+   `"OK"`. The WSDL declares `Status` as a bare `s:string` with no
+   `<s:enumeration>` and no documentation naming the success value, so `"OK"` is
+   KashFlow's documented *convention*, not something the schema pins down. If the
+   real token differs, **every successful post raises `ApiError`** — the
+   comparison inverts completely. Because `ApiError` is now discarded rather than
+   retried, that failure mode is quiet: no duplicate invoices, but every single
+   order fails with a `kashflow.sync_error` and nothing reaches KashFlow. Post one
+   invoice and read the raw `Status` back before anything else.
+2. **An invoice** — that the lines, VAT and totals render as expected, and that
+   `Sort` orders them the way you want.
+3. **A payment** — that `InsertInvoicePayment` returns a non-zero payment id and
+   the invoice shows as paid.
+4. **A credit note** — that `applyCreditNoteToInvoice` returns `true` and the
+   credit note appears linked to the original invoice, not floating on its own.
+
+### Wiring the customer's VAT number
+
+Spree has no dedicated column for a customer's VAT number, and this gem does not
+invent one. `Spree::Kashflow::CustomerPayload` reads it from
+`order.metadata["vat_number"]` — but **nothing in Spree or this gem writes that
+key**. If your store needs `VATNumber` sent to KashFlow (for EC-zone B2B
+customers, for example), your host application must populate
+`order.metadata["vat_number"]` before the order completes. Left unset, the
+customer payload simply omits `VATNumber` — no error, just silently absent.
+
+## Behaviour
+
+A sync is triggered by:
+
+- **Order completion** — the `order.completed` event enqueues `SyncOrderJob`,
+  which upserts the customer, posts the invoice, and (if the order is paid)
+  records the payment.
+- **A reimbursement** — the `reimbursement.reimbursed` event enqueues
+  `SyncRefundJob` for each refund it produced.
+- **Any refund** — a decorator on `Spree::Refund` enqueues `SyncRefundJob` on
+  every refund's creation, independent of the reimbursement flow. This covers
+  an admin issuing an ad-hoc refund directly against a payment, which Spree
+  doesn't route through a reimbursement event.
+
+### Resume semantics
+
+Each job is a small **resumable state machine**, not an all-or-nothing unit. Both
+make two KashFlow calls that must be tracked separately, and each call is
+followed *immediately* by the metafield that records it:
+
+| Job | Step 1 | Marker | Step 2 | Marker |
+|---|---|---|---|---|
+| `SyncOrderJob` | post the invoice | `kashflow.invoice_number` | record the payment | `kashflow.payment_recorded_at` |
+| `SyncRefundJob` | post the credit note | `kashflow.credit_note_number` | link it to the invoice | `kashflow.credit_note_linked_at` |
+
+Each step is guarded on its **own** marker. A rerun skips whatever has already
+succeeded and resumes at the first unfinished step, so the same order or refund
+firing more than one trigger — or a job retrying — never double-books, and never
+strands a half-finished sync either.
+
+The ordering is the point. **Creating a ledger document must be at-most-once;
+applying a payment or a link is naturally re-attemptable.** So the invoice number
+is written the instant `InsertInvoice_TypeDefined` returns, before the payment is
+even attempted. A duplicate invoice overstates revenue and VAT, is structurally
+valid so nothing in KashFlow flags it, and remains a permanent artefact even
+after being credit-noted. A permanently-unpaid invoice recognises revenue
+correctly, surfaces in aged debtors at month-end, and is a one-click fix. If
+exactly one of those has to be possible, it is the second.
+
+A whole-job guard would undo this, which is why there isn't one: keyed on the
+invoice number, it would see the key the failed run just wrote, no-op, and strand
+the unpaid invoice for good.
+
+One accepted consequence: an order can carry **both** an invoice number and a
+`kashflow.sync_error`. That combination is accurate rather than contradictory —
+the invoice genuinely exists in KashFlow, and only the payment failed. It also
+keeps `SyncRefundJob`'s precondition guard (which refuses to credit-note an order
+with no invoice number) working for such an order.
+
+A business rejection from KashFlow (`Spree::Kashflow::ApiError`) is **discarded,
+not retried**. A nominal code that doesn't exist or a `PayAccount` that isn't a
+bank account does not become valid on the 25th attempt, and the
+`kashflow.sync_error` metafield is already the operator-visible record. Only
+transport failures are retried.
+
+A sync **never blocks checkout**. Both jobs run asynchronously via Active Job,
+after the order has already completed or the refund has already been created.
+Nothing in the checkout or refund path waits on KashFlow.
+
+## The correctness guard
+
+Before posting anything, this gem assembles the invoice's line items and checks
+that they reconcile — both individually (`Rate * Quantity` against each line's
+net total) and in aggregate (the assembled invoice total against
+`order.total`). If they don't match, **nothing is posted**. Instead, the gem
+raises `Spree::Kashflow::TotalMismatchError`, and the failing job records the
+error message on the order's `kashflow.sync_error` metafield.
+
+This is deliberate, not a limitation to work around. A failed sync is a
+queryable flag your team can find and fix. A wrong invoice is a discrepancy
+someone finds at year end, after it's been sitting in KashFlow's ledger for
+months. Refusing to post is the safer failure mode.
+
+One consequence: **orders with exclusive tax are refused, not mis-booked.** The
+guard's arithmetic only accounts for VAT baked into the price
+(`included_tax_total`); an order carrying `additional_tax_total` (tax added on
+top of the price rather than included in it) will never reconcile, and will
+always be refused with a sync error rather than posted with wrong figures.
+
+### Finding failed syncs
+
+Query orders (or refunds) carrying a `kashflow.sync_error` metafield:
+
+```ruby
+Spree::Order.with_metafield_key("kashflow.sync_error")
+```
+
+The metafield's value is the error message from the failed attempt. It is
+cleared automatically on the next successful sync.
+
+## Known limitations
+
+- **Partial refunds are approximated, not apportioned.** Spree carries no
+  information tying a partial refund back to specific line items or their
+  individual VAT rates. A full refund mirrors the original invoice's lines
+  exactly, negated. A partial refund instead posts as a **single negative
+  line**, at the order's *blended* VAT rate (`order.included_tax_total /
+  (order.total - order.included_tax_total)`), rather than apportioned across
+  the lines it actually came from. Apportioning without that information would
+  mean inventing numbers in an accounting ledger, which this gem avoids.
+- **`Sort` on invoice lines is a placeholder.** Lines are sent with a 1-based
+  index in `Sort` (line items first, then shipping). This is KashFlow's line
+  ordering field, but its effect on the rendered invoice has not been
+  confirmed against a live KashFlow account.
+- **`ExchangeRate` is hardcoded to `1`.** Before posting, this gem confirms the
+  order's currency is *enabled* on the connected KashFlow account — but an
+  enabled currency isn't necessarily at parity with the account's base
+  currency. No currency conversion is performed. Multi-currency accounts where
+  the order currency differs from KashFlow's base currency will post at the
+  wrong effective rate. KashFlow's `GetCurrencies` already returns the real
+  rate and `Client#currencies` currently discards it, so this is the **top item
+  for 0.2.0**.
+- **`ValuesInCurrency` is not set, and is unverified.** KashFlow's invoice
+  schema carries a `ValuesInCurrency` flag governing whether the amounts sent
+  are in the order's currency or the account's base currency. This gem leaves it
+  unset and has not confirmed which KashFlow assumes by default. Combined with
+  the `ExchangeRate` limitation above, treat multi-currency as unsupported for
+  now.
+- **Orders that complete *unpaid* post an invoice that stays unpaid.** The only
+  sync trigger is order completion; there is no `payment.completed` trigger. An
+  order paid at checkout posts its payment along with the invoice, but an order
+  completed on bank transfer, on account, or through any pay-later method
+  (including Aypex's own `spree-bank_payments`) posts an invoice with `Paid` of
+  `0` — and *nothing subsequently marks it paid in KashFlow* when the money
+  actually arrives. Those payments have to be reconciled in KashFlow by hand
+  until 0.2.0 adds a payment trigger.
+- **Sequential partial refunds are not capped in aggregate.**
+  `CreditNotePayload` decides full-versus-partial by comparing a *single*
+  refund's amount against the order total, and nothing sums the credit notes
+  already posted for an order. Several partial refunds against one order can
+  therefore credit more than the order was worth. KashFlow may refuse the
+  over-credit itself, but this gem does not prevent the attempt.
+- **A fresh Savon client per call.** `Client` builds a new Savon client — and
+  therefore refetches the 457&nbsp;KB WSDL — on every call. Rendering the admin
+  configuration form makes four lookups, so four fetches. Functionally correct
+  but wasteful; caching is a 0.2.0 item.
+
+## Development
+
+```bash
+bundle install
+bundle exec rake test_app
+bundle exec rspec
+bundle exec standardrb
+```
+
+## Licence
+
+The gem is available as open source under the terms of the
+[MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "bundler"
+Bundler::GemHelper.install_tasks
+
+require "rspec/core/rake_task"
+require "spree/testing_support/extension_rake"
+
+RSpec::Core::RakeTask.new
+
+task default: :spec
+
+desc "Generates a dummy app for testing"
+task :test_app do
+  # Must be the require path, not the gem name -- spree_core's common:test_app
+  # does a literal `require ENV['LIB_NAME']` and templates the same string into
+  # the generated dummy app.
+  ENV["LIB_NAME"] = "spree/kashflow"
+  ENV["DB"] ||= "postgres"
+  Rake::Task["extension:test_app"].execute(install_admin: true)
+end

data/app/jobs/spree/kashflow/sync_order_job.rb

@@ -0,0 +1,245 @@
+# frozen_string_literal: true
+
+module Spree
+  module Kashflow
+    ##
+    # Posts a completed order to KashFlow as an invoice.
+    #
+    # A resumable state machine, not an all-or-nothing job. Posting the invoice
+    # and recording its payment are two separate KashFlow calls, each with its own
+    # metafield marker written the instant it succeeds
+    # ({Metafields::ORDER_INVOICE_NUMBER} and
+    # {Metafields::ORDER_PAYMENT_RECORDED_AT}), and each guarded independently in
+    # {#sync}. A rerun therefore resumes at the first unfinished step rather than
+    # replaying the whole job or skipping it wholesale — which is what makes it
+    # safe both to retry and to enqueue from more than one trigger (a subscriber
+    # and a decorator both firing for the same event, for instance) without
+    # double-booking. Takes an id, never an {Spree::Order}, so ActiveJob's
+    # argument serialisation never has to round-trip a whole AR object.
+    #
+    class SyncOrderJob < Spree::BaseJob
+      # Bad credentials will never succeed on retry, so retrying only fills the
+      # queue; the failure is written to {Metafields::ORDER_SYNC_ERROR} before the
+      # job discards (see the `rescue` in {#perform}, which runs before ActiveJob's
+      # `discard_on` handler).
+      discard_on Spree::Kashflow::AuthenticationError
+
+      # An {Spree::Kashflow::ApiError} is a business rejection — a nominal code
+      # that doesn't exist, a disabled currency, a `PayAccount` that isn't a real
+      # bank account. None of those change by being asked again, and without a
+      # policy here the error would inherit the backend default (25 attempts on
+      # Sidekiq). The {Metafields::ORDER_SYNC_ERROR} metafield written by
+      # {#perform}'s `rescue` — which runs before this handler — is already the
+      # operator-visible record, so the job discards rather than churning.
+      discard_on Spree::Kashflow::ApiError
+
+      # KashFlow being briefly unreachable is exactly the case retrying recovers
+      # from automatically.
+      retry_on Spree::Kashflow::TransportError, wait: :polynomially_longer, attempts: 5
+
+      ##
+      # @param order_id [Integer, String] the {Spree::Order} id
+      # @return [void]
+      # @raise [Spree::Kashflow::Error] any subclass raised while posting; the
+      #   message is written to {Metafields::ORDER_SYNC_ERROR} first
+      #
+      def perform(order_id)
+        order = Spree::Order.find_by(id: order_id)
+        return if order.nil?
+
+        integration = Spree::Integrations::Kashflow.active.find_by(store: order.store)
+        return if integration.nil?
+
+        return if invoice_posted?(order) && payment_settled?(order)
+
+        sync(order, integration)
+      rescue Spree::Kashflow::Error => e
+        Metafields.write(order, Metafields::ORDER_SYNC_ERROR, e.message)
+        raise
+      end
+
+      private
+
+      ##
+      # Each KashFlow call is followed immediately by the metafield that records
+      # it, and each is skipped independently when its metafield is already
+      # present.
+      #
+      # Creating an invoice must be at-most-once; recording a payment against an
+      # invoice that already exists is naturally re-attemptable. So
+      # {Metafields::ORDER_INVOICE_NUMBER} is written the instant
+      # `create_invoice` returns, before `record_payment` is even attempted. A
+      # duplicate invoice overstates revenue and VAT, is structurally valid so no
+      # KashFlow report flags it, and remains a permanent artefact even after
+      # being credit-noted. A permanently-unpaid invoice recognises revenue
+      # correctly, surfaces in aged debtors at month-end, and is a one-click fix.
+      #
+      # Guarding per step rather than at the top of {#perform} is the other half
+      # of that: a whole-job guard keyed on the invoice number would see the key a
+      # retry just wrote and no-op, stranding the unpaid invoice for good.
+      #
+      # A consequence, accepted deliberately: an order can carry both an invoice
+      # number and a {Metafields::ORDER_SYNC_ERROR}. That is accurate — the
+      # invoice genuinely exists in KashFlow — and it keeps {SyncRefundJob}'s
+      # precondition guard working for an order whose payment never posted.
+      #
+      # @param order [Spree::Order]
+      # @param integration [Spree::Integrations::Kashflow]
+      # @return [void]
+      #
+      def sync(order, integration)
+        client = integration.client
+        assert_currency_enabled!(order, client)
+
+        customer_id = client.upsert_customer(CustomerPayload.new(order).to_h)
+        Metafields.write(order, Metafields::ORDER_CUSTOMER_CODE, customer_id)
+
+        unless invoice_posted?(order)
+          invoice_number = client.create_invoice(invoice_envelope(order, integration, customer_id))
+          Metafields.write(order, Metafields::ORDER_INVOICE_NUMBER, invoice_number)
+        end
+
+        unless payment_settled?(order)
+          record_payment(order, integration, client, invoice_number(order))
+          Metafields.write(order, Metafields::ORDER_PAYMENT_RECORDED_AT, Time.current)
+        end
+
+        Metafields.write(order, Metafields::ORDER_SYNCED_AT, Time.current)
+        Metafields.write(order, Metafields::ORDER_SYNC_ERROR, nil)
+      end
+
+      ##
+      # @param order [Spree::Order]
+      # @return [TrueClass, FalseClass] whether the invoice has already been
+      #   posted to KashFlow for this order
+      #
+      def invoice_posted?(order)
+        order.has_metafield?(Metafields::ORDER_INVOICE_NUMBER)
+      end
+
+      ##
+      # An unpaid order has no payment step to complete, so it counts as settled.
+      #
+      # @param order [Spree::Order]
+      # @return [TrueClass, FalseClass] whether the payment step is done or
+      #   inapplicable
+      #
+      def payment_settled?(order)
+        !order.paid? || order.has_metafield?(Metafields::ORDER_PAYMENT_RECORDED_AT)
+      end
+
+      ##
+      # @param order [Spree::Order]
+      # @return [Integer, nil] the KashFlow invoice number recorded on the order
+      #
+      def invoice_number(order)
+        order.get_metafield(Metafields::ORDER_INVOICE_NUMBER)&.value&.to_i
+      end
+
+      ##
+      # Booking a USD order as GBP is worse than not booking it, so this is checked
+      # before anything is posted.
+      #
+      # @param order [Spree::Order]
+      # @param client [Spree::Kashflow::Client]
+      # @return [void]
+      # @raise [Spree::Kashflow::ApiError] when the order's currency is not among
+      #   the currencies enabled on the KashFlow account
+      #
+      def assert_currency_enabled!(order, client)
+        enabled = client.currencies.map { |currency| currency[:code] }
+        return if enabled.include?(order.currency)
+
+        raise Spree::Kashflow::ApiError, "Currency #{order.currency.inspect} is not enabled in KashFlow (enabled: #{enabled.join(", ")})"
+      end
+
+      ##
+      # Wraps {InvoicePayload#to_h}'s four fields in the envelope the WSDL `Invoice`
+      # complex type also declares `minOccurs="1"`, which Task 5 deliberately left
+      # to this job because they depend on things Task 5's mapper doesn't have: the
+      # customer id from the upsert call, and this job's own idempotency/payment
+      # state. Keys are emitted in `Invoice_TypeDefined`'s WSDL `<s:sequence>`
+      # order — Savon serialises a Hash body in insertion order, and a .NET ASMX
+      # endpoint enforcing that sequence drops or mis-binds an out-of-order
+      # element rather than raising.
+      #
+      # `Lines` is nested under an explicit `"InvoiceLine"` key because the WSDL
+      # types it as `ArrayOfInvoiceLine`, whose single member is an unbounded
+      # `InvoiceLine` element. Handing Gyoku a bare Array instead repeats
+      # `<Lines>` as a sibling per line rather than wrapping them, which an ASMX
+      # `XmlSerializer` skips as unknown children — posting an invoice with
+      # header totals and no lines, and still returning an invoice number.
+      #
+      # Defaults for the fields with no natural source:
+      # - `InvoiceDBID`, `InvoiceNumber`: unknown before KashFlow assigns them on
+      #   insert, so `0`.
+      # - `DueDate`: same as `InvoiceDate` — the order is already completed (and
+      #   frequently already paid), so there are no payment terms to express.
+      # - `SuppressTotal`: `0` — show the total on the rendered invoice.
+      # - `ProjectID`: `0` — no KashFlow project is associated with these orders.
+      # - `ExchangeRate`: `1` — {#assert_currency_enabled!} has already refused to
+      #   post an order whose currency isn't one KashFlow itself is configured
+      #   for, so no conversion applies.
+      # - `CustomerReference`: the Spree order number, so an accountant
+      #   reconciling a discrepancy in KashFlow can find the order it came from.
+      # - `CISRCNetAmount`, `CISRCVatAmount`, `IsCISReverseCharge`: UK Construction
+      #   Industry Scheme reverse-charge fields. Structurally required by the
+      #   schema but not applicable to this integration (a supplements retailer,
+      #   not a CIS contractor), so `0` / `false` rather than `nil` — `nil` would
+      #   depend on Gyoku emitting `xsi:nil="true"` and the ASMX deserialiser
+      #   accepting it, an assumption no spec here can exercise since every spec
+      #   stubs the SOAP layer. `0` is arithmetically neutral and unambiguous on
+      #   the wire; revisit if a sandbox call ever shows KashFlow prefers null.
+      #
+      # @param order [Spree::Order]
+      # @param integration [Spree::Integrations::Kashflow]
+      # @param customer_id [Integer] the id returned by `Client#upsert_customer`
+      # @return [Hash{String => Object}] a KashFlow `Invoice` structure, envelope
+      #   fields and {InvoicePayload#to_h}'s fields together, in WSDL sequence order
+      #
+      def invoice_envelope(order, integration, customer_id)
+        payload = InvoicePayload.new(order, integration: integration).to_h
+        invoice_date = order.completed_at || Time.current
+
+        {
+          "InvoiceDBID" => 0,
+          "InvoiceNumber" => 0,
+          "InvoiceDate" => invoice_date,
+          "DueDate" => invoice_date,
+          "CustomerID" => customer_id,
+          "Paid" => order.paid? ? 1 : 0,
+          "CustomerReference" => order.number,
+          "SuppressTotal" => 0,
+          "ProjectID" => 0,
+          "CurrencyCode" => payload["CurrencyCode"],
+          "ExchangeRate" => BigDecimal(1),
+          "Lines" => {"InvoiceLine" => payload["Lines"]},
+          "NetAmount" => payload["NetAmount"],
+          "VATAmount" => payload["VATAmount"],
+          "AmountPaid" => order.paid? ? order.total : BigDecimal(0),
+          "CISRCNetAmount" => 0,
+          "CISRCVatAmount" => 0,
+          "IsCISReverseCharge" => false
+        }
+      end
+
+      ##
+      # @param order [Spree::Order]
+      # @param integration [Spree::Integrations::Kashflow]
+      # @param client [Spree::Kashflow::Client]
+      # @param invoice_number [Integer]
+      # @return [void]
+      #
+      def record_payment(order, integration, client, invoice_number)
+        client.record_invoice_payment(
+          "PayID" => 0,
+          "PayInvoice" => invoice_number,
+          "PayDate" => order.completed_at || Time.current,
+          "PayMethod" => integration.preferred_payment_method_id,
+          "PayAccount" => integration.preferred_bank_account_id,
+          "PayAmount" => order.total
+        )
+      end
+    end
+  end
+end