Payment

Canonical contract for persisted payment payloads.

Identity source_id, connection_id

Attributes

Field

Type

Description

source_idrequiredidentity

string

Source ID — Stable external record ID from the source system. Backfill uses this with source_system and, when present, connection_id for idempotent imports and upserts.

source_systemrequired

string

Source System — Connector or provider that supplied the record, such as stripe, shopify, qbo, csv_upload, or manual.

connection_ididentity

string

Connection ID — Backfill tenant connection ID that scopes records to a specific external account, store, realm, or integration instance. It may participate in source identity without being required on every create payload.

subsidiary_id

string

Subsidiary ID — Business entity or subsidiary identifier for multi-entity accounting. Leave blank when the tenant does not use subsidiaries.

amountrequired

decimal

Amount

currencyrequired

string

Currency

statusrequired

string

Status

customer_id

string

Customer ID — Identifier for the related customer record.

invoice_id

string

Invoice ID — Identifier for the related invoice record.

payment_method

string

Payment Method

payment_method_type

string

Payment Method Type

checkcredit_cardachcashwireother

payment_method_details

map

Payment Method Details

default: %{}

reference_number

string

Reference Number

memo

string

Memo

deposit_to_account_id

string

Deposit Account ID — Backfill account identifier for a related account record. Use account_id for lookups; account_code is display-only when referring to general ledger accounts and may be absent.

deposit_to_account_code

string

Deposit Account Code

fees

decimal

Fees

balance_transaction_id

string

Balance Transaction ID — Identifier for the related balance transaction record.

fee_amount

decimal

Fee Amount

net_amount

decimal

Net Amount

tax_amount

decimal

Tax Amount

fee_details

array<map>

Fee Details

default: []

settlement_payout_id

string

Settlement Payout ID — Identifier for the related settlement payout record.

source_currency

string

Source Currency

settlement_currency

string

Settlement Currency

exchange_rate

decimal

Exchange Rate

occurred_at

datetime

Occurred At

settled_at

datetime

Settled At

dimensions

map

Dimensions

default: %{}

source_metadata

map

Source Metadata

default: %{}

metadata

map

Metadata

default: %{}

allocations[]

array<object>

Allocations

invoice_idrequired

string

Invoice ID — Identifier for the related invoice record.

amountrequired

decimal

Amount

allocated_at

datetime

Allocated At

TypeScript SDK

Import

Every canonical resource is exposed as a top-level entity global on @backfill-io/sdk.

import { Payment } from "@backfill-io/sdk";

Create

Pass an object matching PaymentCreateInput. Required fields are shown below.

const payment = Payment.create({
  source_id: "source_id_123",
  source_system: "…",
  amount: "100.00",
  currency: "USD",
  status: "open",
});

Get and query

Look up a single record by canonical ID, or query with filters and pagination.

const payment = Payment.get("payment_123");

const results = Payment.query({
  where: { },
  orderBy: [{ field: "inserted_at", direction: "desc" }],
  limit: 50,
});

Update

Partial update — pass only the fields you want to change.

Payment.update("payment_123", {
  // …fields to update
});

Delete

Payment.delete("payment_123");

← Expense

Customer →