Skip to main content

Credit Card Reconciliation

This guide walks through the end-to-end corporate-card reconciliation flow on the SpendOne Platform, the AI-based platform for indirect corporate spend. It covers card issuance via AirPlus DBI, ingestion of transaction events, automated matching against invoices and receipts, exception handling, and accounting export.

For admins. Card programs are configured under Administration → Credit Cards and the linked AirPlus account. Each tenant maps to one or more AirPlus DBI accounts; the Descriptive Billing Information (DBI) field mapping is set up once per tenant (see the AirPlus DBI Field Configuration guide for the field-by-field setup). Cardholders, spend limits and lifecycle controls (deactivate / reactivate) live on the credit card detail page; finance roles trigger or review reconciliation from the purchase order detail page, where mismatches surface as exceptions for manual resolution. Accounting export configuration is managed under Administration → Accounting.

For integrators. The flow is driven by three subsystems exposed under separate route groups: /credit-cards (issuance and lifecycle), /transaction-events/* (event browsing over ingested statements), and /invoices/{code}/reconciliation* (matching and status, as an invoice-review substep). Statement files are pushed by AirPlus over SFTP and announced by an infrastructure callback that is not part of the integration surface; reconciliation then runs when an invoice is saved against the purchase order. See the OpenAPI reference for full payload schemas.

Sequence​

Step 1: Issue a card​

Issue a virtual card bound to an approved purchase order. DBI fields (cost center, user code, order number) are set at issuance and synced with AirPlus.

  • POST /credit-cards: the body carries one field, purchase_order_code. The limit and the DBI values are derived from the purchase order, not passed here.
  • PUT /credit-cards/{code}: re-syncs DBI fields after PO changes.
  • PATCH /credit-cards/{code}/deactivate and PATCH /credit-cards/{code}/reactivate: lifecycle controls.
  • GET /credit-cards/{code}/budget and GET /purchase-orders/{code}/credit-card-budget: current utilization.

Step 2: Ingest transaction events​

AirPlus drops a CSV/XML statement onto the SFTP endpoint and notifies SpendOne via webhook. The AirPlus account ID embedded in the filename resolves the tenant. Persisted events become browsable transactions.

  • The new-file callback AirPlus fires after an SFTP drop is infrastructure, not an integration surface: it is not reachable at this host and not published in the reference. Nothing on your side calls it.
  • GET /airplus/statements/accrual-report: month-end accrual view over ingested statements.
  • GET /transaction-events/transactions/{identifier}/events: full event history for a single transaction.
  • POST /transaction-events/export: filterable bulk read by status, supplier, cost center and date range, delivered as an export job.

Step 3: Match against documents​

Reconciliation runs as a step of invoice review, not as a purchase-order endpoint. When an invoice is saved against a purchase order paid by corporate card, the engine compares amounts, suppliers, dates and tax fields between the transaction event and the document, and the result is read and corrected through the invoice's reconciliation substep:

  • GET /invoices/{code}/reconciliation reads the result, with the per-field match status.
  • POST /invoices/{code}/reconciliation/correct records a correction.
  • POST /invoices/{code}/reconciliation/confirm accepts the result and advances the workflow.
  • PATCH /invoices/{code}/reconciliation/notes attaches a note.

There is no standalone reconciliation resource and no way to trigger a pass directly: it is driven by the invoice, so re-running means re-saving or correcting the document.

Step 4: Handle exceptions​

When fields disagree (e.g. amount mismatch, missing receipt, supplier-name fuzz), the PO surfaces the exception. Resolution paths:

  • Upload a corrected document: saving re-triggers reconciliation.
  • Correct the field in place with POST /invoices/{code}/reconciliation/correct.
  • Deactivate the card via PATCH /credit-cards/{code}/deactivate if fraud is suspected.

Step 5: Export to accounting​

Once a PO is fully reconciled, the entries are eligible for accounting export. Configure the target system as described in Accounting System Integration. Card transactions are exported as their own journal lines, linked to the source invoice and the cardholder cost center.

  • POST /transaction-events/export: kicks off an async export job (filters mirror the list endpoint).
  • GET /transaction-events/export/{job_code}: poll job status.
  • GET /transaction-events/export/{job_code}/download: fetch the resulting file once complete.

Operational notes​

  • The webhook compares X-API-Key in constant time and additionally verifies the HMAC X-Hub-Signature, failing closed when the signing secret is unset. Both are deployment-level config, not tenant-admin rotatable.
  • DBI field changes on a PO must be propagated by calling PUT /credit-cards/{code}; the platform does not auto-resync on every PO edit.
  • Reconciliation status is idempotent; re-triggering on an unchanged document is a no-op.