Reconciliation Fields

Field reference for all reconciliation API endpoints, query parameters, pagination, and response formats.

Base path: https://api.catalystpay.com/api/v1/reconciliation/

Authentication: Bearer rk_xxx (API key required for all reconciliation endpoints).

Transaction Reconciliation

GET /api/v1/reconciliation/transactions/

Query Parameters

Parameter	Type	Required	Description
`start_date`	`YYYY-MM-DD`	Yes	Start of date range (filters on `date_processed`).
`end_date`	`YYYY-MM-DD`	No	End of date range. Maximum 90 days from `start_date`.
`status`	`string`	No	Comma-separated transaction statuses (e.g., `approved,declined`).
`type`	`string`	No	Comma-separated transaction types (e.g., `sdd_sale,sdd_refund`).
`payment_gateway_id`	`uuid`	No	Filter by payment gateway UUID.
`format`	`string`	No	Response format: `json` (default), `xml`, `csv`.
`page_size`	`integer`	No	Results per page. Range: 1-1000. Default: 100.
`cursor`	`string`	No	Opaque pagination cursor from `next`/`previous` URL.

Response Fields

Field	Type	Description
`id`	`uuid`	Internal transaction UUID.
`adapter_unique_id`	`string`	Original unique ID from payment processor.
`merchant_transaction_id`	`string`	Merchant transaction ID (unique).
`transaction_id`	`string`	Processor transaction ID.
`tenant_reference_id`	`string` (nullable)	Merchant-owned reconciliation reference set at payment submission via `/payment-sessions/{token}/pay/`. Unique per tenant when provided. `null` for system-generated transactions (rebills, CSV imports) and for submissions that omitted the field.
`status`	`string`	CatalystPay standardized status. See Status Lifecycles.
`type`	`string`	CatalystPay standardized type (`sdd_sale`, `sdd_refund`, `other_type`).
`amount`	`decimal`	Transaction amount.
`currency`	`string`	Currency code.
`date_processed`	`datetime`	Processing timestamp (UTC).
`iban`	`string`	Masked IBAN (last 4 characters visible, rest replaced with `*`).
`bic`	`string`	BIC/SWIFT code.
`customer_email_csv`	`string`	Customer email from processor CSV.
`customer_name_csv`	`string`	Customer name from processor CSV.
`mandate_reference_id`	`string`	SEPA mandate reference ID.
`mandate_date`	`datetime`	Mandate signing date.
`source`	`string`	Creation source (`csv_import`, `api_submission`, `admin_refund`, `webhook`, `hosted_page`).
`order_id`	`uuid`	Related order UUID.
`subscription_id`	`uuid`	Related subscription UUID.
`lead_id`	`uuid`	Related lead UUID.
`payment_gateway_id`	`uuid`	Payment gateway UUID.
`created_at`	`datetime`	Record creation timestamp.
`updated_at`	`datetime`	Record last update timestamp.

Excluded Fields

The following fields are never exposed in the reconciliation API:

raw_data, import_error, import_session, origin_adapter_status, origin_adapter_txn_type, card_holder, card_number, card_brand, adapter, adapter_id

Chargeback Reconciliation

GET /api/v1/reconciliation/chargebacks/

Query Parameters

Parameter	Type	Required	Description
`start_date`	`YYYY-MM-DD`	Yes	Start of date range (filters on `report_date`).
`end_date`	`YYYY-MM-DD`	No	End of date range. Maximum 90 days from `start_date`.
`status`	`string`	No	Comma-separated chargeback statuses (e.g., `charged_back`).
`type`	`string`	No	Comma-separated chargeback types (e.g., `chargeback`).
`payment_gateway_id`	`uuid`	No	Filter by payment gateway UUID.
`format`	`string`	No	Response format: `json` (default), `xml`, `csv`.
`page_size`	`integer`	No	Results per page. Range: 1-1000. Default: 100.
`cursor`	`string`	No	Opaque pagination cursor from `next`/`previous` URL.

Response Fields

Field	Type	Description
`id`	`uuid`	Internal chargeback UUID.
`adapter_unique_id`	`string`	Original unique ID from payment processor.
`merchant_transaction_id`	`string`	Merchant transaction ID (unique, primary dedup key).
`tenant_reference_id`	`string` (nullable)	Echo of the reference set on the linked original transaction at payment submission. `null` when the chargeback is unlinked or when the original submission did not supply a reference.
`status`	`string`	CatalystPay standardized status (`charged_back`).
`type`	`string`	CatalystPay standardized type (`chargeback`).
`amount`	`decimal`	Chargeback amount.
`currency`	`string`	Currency code.
`report_date`	`datetime`	Chargeback report date.
`transaction_date`	`datetime`	Original transaction date.
`reason_code`	`string`	Chargeback reason code.
`reason_message`	`string`	Chargeback reason message.
`report_type`	`string`	Report type.
`report_message`	`string`	Report message.
`report_info`	`string`	Report info.
`arn`	`string`	Acquirer Reference Number.
`iban`	`string`	Masked IBAN (last 4 characters visible).
`bic`	`string`	BIC/SWIFT code.
`email`	`string`	Customer email.
`country`	`string`	Country.
`source`	`string`	Creation source (`csv_import`, `webhook`, `reconciliation`, `manual`).
`cb_bank_fee`	`decimal`	Bank fee charged for the chargeback (nullable).
`transaction_id`	`uuid`	Linked original transaction UUID.
`lead_id`	`uuid`	Related lead UUID.
`payment_gateway_id`	`uuid`	Payment gateway UUID.
`created_at`	`datetime`	Record creation timestamp.
`updated_at`	`datetime`	Record last update timestamp.

Excluded Fields

raw_data, import_error, import_session, origin_adapter_cb_status, origin_adapter_cb_type, adapter, adapter_id, card_holder, card_number, card_brand, remote_ip, reference_transaction_id, reference_transaction_type, order_id (internal CharField), transition, merchant, terminal

Subscription Reconciliation

GET /api/v1/reconciliation/subscriptions/

Query Parameters

Parameter	Type	Required	Description
`start_date`	`YYYY-MM-DD`	Yes	Start of date range (filters on `created_at`).
`end_date`	`YYYY-MM-DD`	No	End of date range. Maximum 90 days from `start_date`.
`status`	`string`	No	Comma-separated subscription statuses, UPPERCASE (e.g., `ACTIVE,CANCELLED`).
`payment_gateway_id`	`uuid`	No	Filter by payment gateway UUID.
`next_billing_date_from`	`YYYY-MM-DD`	No	Filter subscriptions with `next_billing_date >= date`.
`next_billing_date_to`	`YYYY-MM-DD`	No	Filter subscriptions with `next_billing_date <= date`.
`format`	`string`	No	Response format: `json` (default), `xml`, `csv`.
`page_size`	`integer`	No	Results per page. Range: 1-1000. Default: 100.
`cursor`	`string`	No	Opaque pagination cursor from `next`/`previous` URL.

Response Fields

Field	Type	Description
`id`	`uuid`	Internal subscription UUID.
`status`	`string`	Subscription status (UPPERCASE). See Status Lifecycles.
`billing_amount`	`decimal`	Amount charged per billing cycle.
`currency`	`string`	Currency code.
`billing_frequency`	`string`	Billing frequency (`WEEKLY`, `BIWEEKLY`, `MONTHLY`, etc.).
`start_date`	`datetime`	When subscription started.
`next_billing_date`	`date`	Next scheduled billing date (nullable).
`last_billing_date`	`datetime`	Last successful billing timestamp (nullable).
`cancelled_at`	`datetime`	Cancellation timestamp (nullable).
`trial_end_date`	`date`	Trial period end date (nullable).
`billing_anchor_date`	`date`	Reference date for day-of-month billing alignment (nullable).
`successful_billing_count`	`integer`	Number of successful rebills.
`failed_billing_count`	`integer`	Number of failed rebill attempts.
`total_revenue`	`decimal`	Total revenue from this subscription.
`order_id`	`uuid`	Original order UUID.
`lead_id`	`uuid`	Customer lead UUID.
`offer_id`	`uuid`	Offer UUID (nullable in direct mode).
`payment_gateway_id`	`uuid`	Payment gateway UUID.
`created_at`	`datetime`	Record creation timestamp.
`updated_at`	`datetime`	Record last update timestamp.

Excluded Fields

payment_details_token, edit_history, metadata, error_reason, billing_frequency_days (deprecated)

Pagination

All reconciliation endpoints use cursor-based pagination.

Mechanics

Cursor encodes the position using the ordering field + id for deterministic ordering.
Default ordering: most recent first (-date_processed for transactions, -report_date for chargebacks, -created_at for subscriptions).
Default page size: 100. Maximum page size: 1000.

Paginated Response Structure (JSON)

{
  "next": "https://api.catalystpay.com/api/v1/reconciliation/transactions/?cursor=cD0yMDI0LTA...",
  "previous": null,
  "results": [...]
}

Field	Type	Description
`next`	`string` (nullable)	URL to the next page. `null` when on the last page.
`previous`	`string` (nullable)	URL to the previous page. `null` when on the first page.
`results`	`array`	Array of serialized records.

Query Parameters

Parameter	Type	Description
`cursor`	`string`	Opaque cursor string from `next` or `previous` URL.
`page_size`	`integer`	Number of results per page (1-1000, default 100).

Date Range Constraints

start_date is required on all reconciliation endpoints.
end_date is optional. When provided, the range from start_date to end_date must not exceed 90 days.
Dates are inclusive: start_date filters from start of day UTC, end_date filters through end of day UTC.
Date format: YYYY-MM-DD (ISO 8601).

Output Formats

All reconciliation endpoints support three output formats via the format query parameter:

JSON (default)

Standard paginated JSON response.

XML (`?format=xml`)

<reconciliation>
  <next>https://api.catalystpay.com/api/v1/reconciliation/transactions/?cursor=...</next>
  <previous/>
  <results>
    <transaction>
      <id>...</id>
      <status>approved</status>
      ...
    </transaction>
  </results>
</reconciliation>

Root element: <reconciliation>. Item elements: <transaction>, <chargeback>, or <subscription> depending on endpoint.

CSV (`?format=csv`)

Returns a downloadable CSV file with a Content-Disposition header:

Content-Disposition: attachment; filename="transactions_2024-01-15.csv"

CSV columns match the serializer field order. null values render as empty strings.

See How to Reconcile Transactions for usage examples.

Error Reference

Reconciliation Fields

Transaction Reconciliation

Query Parameters

Response Fields

Excluded Fields

Chargeback Reconciliation

Query Parameters

Response Fields

Excluded Fields

Subscription Reconciliation

Query Parameters

Response Fields

Excluded Fields

Pagination

Mechanics

Paginated Response Structure (JSON)

Query Parameters

Date Range Constraints

Output Formats

JSON (default)

XML (?format=xml)

CSV (?format=csv)

XML (`?format=xml`)

CSV (`?format=csv`)