CSV Imports

CatalystPay supports CSV imports for leads, orders, transactions, chargebacks, and cancellations through the admin interface. This guide covers the import types, workflow, and column requirements for each.

General workflow

All CSV imports follow the same three-step process:

1. Upload -- Navigate to the Import Sessions page in the CatalystPay admin panel, select the import type, and upload your CSV file.
2. Preview -- The system validates column headers and shows a preview of rows to be processed. Review warnings and errors before proceeding.
3. Process -- The system processes each row, creating or updating records. The import session page shows counts of created, updated, skipped, and errored rows with per-row error details.

Import types

Lead import

Leads are customer records identified by IBAN.

Required columns:

Column	Description
Name	Customer full name
Email	Customer email address
IBAN	Customer IBAN
BIC	Bank identifier code (SWIFT)

Optional columns: Address1, Address2, City, State, Country (ISO 3166-1 alpha-2), Zip, MandateDate, Phone, AssignedGateways

Order import

Order imports create orders and optionally their associated leads. Each row supports either campaign mode or direct mode, and rows can mix both modes in a single CSV.

Campaign mode (per-row):

Column	Description
Campaign ID	UUID of the campaign
Offer ID	UUID of the offer

In campaign mode, pricing and billing configuration are resolved from the linked offer. You can optionally include pricing override columns (see below) to adjust amounts or billing terms per-row.

Direct mode (per-row):

Column	Required	Description
Amount	Yes	Charge amount (e.g., 29.99)
Currency	Yes	ISO 4217 currency code (e.g., EUR)
GatewayID	Yes	UUID of the payment gateway
BillingType	Yes	ONE_OFF, RECURRING, or TRIAL_RECURRING

In direct mode, orders are created without any campaign or offer. All pricing and billing configuration comes directly from the CSV columns. This is ideal for tenants who manage pricing externally or don't use the campaign/offer catalog.

Optional pricing columns (both modes):

Column	Description
BillingFrequency	MONTHLY, WEEKLY, BIWEEKLY, QUARTERLY, SEMIANNUAL, ANNUAL (required for RECURRING and TRIAL_RECURRING)
TrialIntervalUnit	day, week, or month (for trial billing)
TrialPeriod	Number of trial intervals (e.g., 7 for 7 days)
TrialPrice	Trial period price (e.g., 0.00 for free trial)

Optional configuration columns (both modes):

Column	Description
WebhookProfileID	UUID — route order webhooks to a specific profile
HostedPageID	UUID — associate a hosted payment page
MaxPaymentAttempts	Integer 1-10 (default 3) — max payment retry attempts

Both modes require at least one lead identifier: Lead ID or IBAN.

Order imports can create leads inline if lead data columns (Name, Email, BIC) are present alongside the IBAN.

Transaction import

Transaction imports are adapter-specific. The required columns depend on your payment gateway adapter. Column mappings and status mappings are loaded from the adapter's YAML configuration.

When uploading a transaction CSV:

1. Select the payment adapter (e.g., EMP, Finxp, Novalnet)
2. Optionally select the payment gateway to link transactions to a specific gateway
3. Upload the CSV provided by your payment processor

EMP required columns:

• Unique ID, IBAN / Account No, DateTime (UTC), Merchant, BIC / SWIFT code

Finxp required columns:

• END TO END ID, MERCHANT, CUSTOMER BIC, CUSTOMER IBAN, STATUS, TRANSACTION TYPE NAME, AMOUNT, IMPORTED DATE, TRANSACTION INFORMATION

Novalnet required columns:

• TID, IBAN, PaymentDate, MerchantName, BIC

Chargeback import

Chargeback imports are also adapter-specific. Like transaction imports, select the payment adapter and optional gateway before uploading.

EMP required columns:

• Unique ID, Merchant Transaction ID

Finxp required columns:

• End to end id, Transaction Information, Initiated amount, Currency, Status, Chargeback date, Initiated date

Novalnet required columns:

• ChargebackTID, ParentTID

Chargeback imports trigger the status cascade: affected transactions are updated to charged_back, subscriptions to CHARGEDBACK, and lead statuses to CHARGEDBACK.

Cancellation import

Cancellation imports identify subscriptions to cancel using a hierarchical lookup:

Priority	Column	Lookup path
1 (highest)	merchant_transaction_id	Transaction -> Subscription
2	iban	Lead -> Subscriptions
3	email	Lead -> Subscriptions

At least one identifier column must be present. When a lead has multiple active subscriptions, the row is skipped as ambiguous to prevent cancelling the wrong subscription.

Status mapping

Transaction and chargeback imports map gateway-specific status values to CatalystPay's standardized set. For example:

• EMP's chargebacked becomes charged_back
• Finxp's settlement becomes approved
• Novalnet's successful becomes approved

The original gateway status is preserved in audit fields for traceability.

Amount handling

Different adapters use different amount conventions:

Adapter	Transaction amounts	Chargeback amounts
EMP	Major units (no conversion)	Minor units (divided by 100)
Finxp	Major units (no conversion)	Major units (no conversion)
Novalnet	Minor units (divided by 100)	Minor units (divided by 100)

Import limits

• Maximum rows per CSV: 200,000
• File format: .csv only
• Results (including the original file) are stored for audit purposes
• Failed rows include detailed error messages

Next steps

• Architecture -- Understand the data model that imports populate
• Reconciliation -- Query imported data via the API
• Adapters -- Detailed adapter configurations and status mappings