Field Mappings
Field mappings transform raw data from Stripe, CSV, and EBICS into incoming transaction attributes. Define source field paths and optional transforms per target field (merchant, amount, date, reference, description).
What are field mappings
Field mappings define how raw data from external sources (Stripe charges, CSV rows, EBICS statements) is transformed into the standard incoming transaction schema. Each mapping is per source (e.g. stripe, csv, ebics). The keys are target fields (merchant, amount, date, reference, description); the values are source field paths or transform expressions.
When you create an incoming transaction with rawData (e.g. a Stripe charge object or CSV row), the field transformer uses the mapping for that source to extract and transform values. If no mapping exists for a source, creation fails.
Mapping structure
Each target field can be:
- Simple path —
"merchant": "description"— Use thedescriptionfield from raw data - Nested path —
"amount": "amount_paid"or"billing_details.name"for nested objects - With transform —
"amount": { "field": "amount", "transform": "divide", "by": 100 }— Stripe amounts are in cents
You can use fieldByLocale to map different source fields per locale (e.g. de-DE → Betrag, en-US → amount).
Available transforms
| Transform | Use case | Example |
|---|---|---|
| divide | Stripe amounts (cents → dollars) | amount / 100 |
| removeCurrencySymbol | Strip €, $, etc. | "1.234,56 €" → 1234.56 |
| parseLocaleNumber | Locale-specific numbers | "1,234.56" (en-US) or "1.234,56" (de-DE) |
| parseDate | Parse dates (iso, european, us, unix) | Various formats → YYYY-MM-DD |
| trim | Trim whitespace | " merchant " → "merchant" |
| toUpperCase / toLowerCase | Case normalization | |
| capitalize | First letter uppercase | |
| regexReplace | Pattern replacement | |
| concat | Join multiple fields | |
| extractMerchant | Extract merchant from string | |
| conditional | If/else based on condition | |
| expression | Custom expression |
Transform parameters (e.g. by for divide, locale for parseLocaleNumber) are documented in the Field Mappings API create/update operations.
Locale and tenant settings
Transforms like parseLocaleNumber and parseDate use the tenant's locale preferences (locale, timezone, currency, date format). Configure these in tenant settings so transformations match your data format.
One mapping per source
Each source (stripe, csv, ebics) has at most one active mapping. Creating a new mapping for a source replaces the previous one. Use Retrieve by source to get the current mapping; Update to modify it.
API Reference
For create/update parameters, request/response samples, and the full mappings schema, see Field Mappings in the API Reference.