Finance & Payments pack

Payments CSV import API

Import masked card payments from any CSV — last 4 digits, brand, amount, status. PCI-aware: full PAN never imported, only card_last4.

Try in Workbench Quickstart

30-second curl

curl -X POST https://api.adaptivmapr.com/v1/uploads \
  -H "Authorization: Bearer $ADAPTIVMAPR_API_KEY" \
  -F "template=payments_v1" \
  -F "file=@your_data.csv"

→ 7 canonical fields · 1 validated · high risk

Canonical columns

The whole schema, printed as it ships.

Every canonical column, the type each row carries, whether it is required, the field-level validators that fire on commit, and the multilingual header hints the cascade resolves against. This is the shipped definition, not a summary of it.

payments_v1

fields: 7
required: 3
validated: 1
hints: 41

Canonical column	Type	Required	Validators	Header hints the cascade matches
`card_last4`	string	yes	`regex`	kartennummer letzte 4derniers 4 chiffresultime 4 cifrelast 4últimos 4
`card_brand`	enumvisamastercardamexdiscover	—	—	kartentypkartenmarkemarkemarque de cartemarquemarca cartacard brandcard typemarca de tarjeta
`amount`	number	yes	—	betragmontantimportoamountimporte
`currency`	string	yes	—	währungdevisevalutacurrencymoneda
`status`	enumauthorizedcapturedrefundedfailed	—	—	statusstatutstatoestado
`processor_ref`	string	—	—	referenzréférenceriferimentoreferencereferencia
`captured_at`	date	—	—	buchungsdatumerfasst amerfassungsdatumgebucht amdate de capturedata di addebitocaptured atfecha de captura

Read the same definition as JSON at GET /v1/templates/payments_v1. A hint match resolves on layer 2 — no LLM call, no token spend, just the flat per-map fee. Hover a validator id to see what it checks.

7 canonical fields
3 required
1 validated
41 header hints, 5 languages

Why it exists

Written for the file you actually receive.

The Payments template is the canonical schema for card-payment records — the file a PSP export, a processor settlement report, or a reconciliation extract reduces to. It is deliberately PCI-conscious: it captures the masked card identity (card_last4, a strict four-digit field, and card_brand bounded to visa / mastercard / amex / discover) but never the full PAN. Each row also carries an amount, a currency, a status enum that walks the charge through authorized → captured → refunded → failed, a processor_ref back to the gateway, and a captured_at timestamp parsed across locales. Finance and payments-ops teams reach for this template when migrating between processors, when backfilling a ledger with historical card activity, and when feeding a reconciliation pipeline that matches settlements against an internal order log. Because the row is regulated data, schema-only mode is the default ingress — raw records never leave the customer; only headers and a handful of clamped sample cells are processed to decide the mapping.

Two hard guarantees enforce PCI hygiene: card_last4 must match ^\d{4}$ (exactly four digits — a full PAN pasted into that column is rejected at the dry-run, not silently truncated), and card_brand lands in {visa, mastercard, amex, discover} or surfaces as an error. status is bounded to {authorized, captured, refunded, failed}. The amount field is number-typed and locale-tolerant; captured_at auto-detects ISO-8601, US, and EU formats. Hints cover DE / FR / IT / ES / EN so a European processor export does not escalate to the paid layer.

Migration scenarios & the foreign headers they ship

Migration scenarios for the Payments template: porting card history between PSPs (Stripe → Adyen, Worldline → Stripe) where the new platform needs the prior charge log, backfilling a finance warehouse with a year of settlement reports, daily reconciliation jobs that match captured charges against an internal order ledger, and consolidating multi-acquirer payment data after a merger. Foreign headers the cascade resolves at zero cost: "Kartennummer letzte 4 / Derniers 4 chiffres / Ultime 4 cifre / Últimos 4 / Kartentyp / Marque de carte / Marca carta / Betrag / Montant / Importo / Importe / Währung / Devise / Status / Statut / Estado / Referenz / Référence / Riferimento / Buchungsdatum / Date de capture / Fecha de captura". The multilingual hint set is exhaustive for the masked-payment domain, so the deterministic layers carry the mapping without a single LLM call.

The cascade

Six layers, and the cheapest one wins.

Layers run in order and stop the moment a column resolves. That is the single biggest cost lever in the system: a column caught on layer 2 never reaches the metered layer 5.

L1Statisticsno LLM
Auto-accepts a header that past confirmations already resolved the same way, at {minN:100, minRatio:0.95} or {minN:20, minRatio:1.00}.
L2Heuristicno LLM
Normalises accents, punctuation and whitespace, then compares against the column name, the label, and every registered hint (DE / FR / IT / EN / ES).
L3Fuzzyno LLM
Token-set ratio plus Levenshtein over the normalised strings. Auto-accepts at 0.80 — it absorbs typos and reordered words.
L4Semanticcheap, cached
Embedding cosine between the header and the field’s label + hints. Catches the long tail of paraphrases.
L5LLMmetered
Everything still unresolved goes up in ONE batched, collision-aware call, constrained to this template’s column set so it cannot invent a field.

Try it

One template id, two ways in.

REST for your import pipeline, MCP for your editor. Both run the same cascade and both honour the same schema-only clamp.

REST · POST /v1/uploads

Name the template; the cascade picks up the rest. The canonical definition is read-only at GET /v1/templates/payments_v1.

bash

curl -X POST https://api.adaptivmapr.com/v1/uploads \
  -H "Authorization: Bearer $ADAPTIVMAPR_API_KEY" \
  -F "template=payments_v1" \
  -F "file=@your_data.csv"

→ upload created · mappings ready · confirm before commit

MCP · Cursor / Claude Desktop

Drop AdaptivMapr into your editor and call the same cascade as a tool. Schema-only calls leave only column names and up to three clamped sample rows.

mcp

// In Cursor or Claude Desktop with the AdaptivMapr MCP server installed:
adaptivmapr.match_headers({
  template_id: "payments_v1",
  headers: ["card_last4", "card_brand", "amount", "currency"]
})

schema-only · headers and ≤3 rows, 80 chars each

MCP install instructions

high-risk template

The mappings response comes back flagged. PATCH /uploads/:id/mappings returns requires_hitl: true and hitl_status: "pending_review" so you can hold the commit in your own workflow — the flag is a signal, not a queue we run. Schema-only mode (headers plus at most three sample rows, each clamped to 80 characters) is a data-minimization mode enforced at the HTTP edge. Full-data mode routes the metered layer-5 call to phi-cloud in-region under a BAA, costs 20% more on the whole map charge, and stays locked until the workspace accepts the BAA/NDA in Settings → Security & Data.

How the wallet is charged

Questions

Payments CSV import — FAQ

Can I import the full card number?

No — and the template actively prevents it. card_last4 is constrained to exactly four digits, so a full PAN fails validation at the dry-run. The Payments template maps masked card data only; full cardholder data must stay out of scope to keep your PCI footprint minimal.

How does AdaptivMapr keep payment data from leaving us?

Schema-only mode is the default: only headers and three clamped sample rows (≤80 chars each) are processed to decide the mapping. The full file of card records never touches our infrastructure unless you explicitly run full-data mode under an active subscription.

Can I add a custom status like "disputed" or "chargeback"?

Fork the template and edit enum_values. The canonical set is kept small so cross-processor reconciliation works without translation tables; disputes are usually modelled in a separate schema.

Is processor_ref required?

No — only card_last4, amount, and currency are required. processor_ref is optional but strongly recommended as your upsert key, since it is the stable reference back to the gateway.

Map payments in production — without shipping raw records.

Schema-only mode leaves only headers and a handful of clamped samples. Add full-data when you need row-level AI, routed in-region under a BAA.

Get an API key More Finance & Payments templates →