Payments CSV import API
payments_v1
Import this template via API. Import masked card payments from any CSV — last 4 digits, brand, amount, status. PCI-aware: full PAN never imported, only card_last4.
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"
At a glance
- Pack
- Finance & Payments
- FHIR resource
- —
- Risk level
- high
- Fields
- 7 (3 required, 1 validated)
Why it exists
Why this template?
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 & common foreign headers
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.
Canonical columns
Schema
The canonical column set, with 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.
| Column | Type | Required | Validators | Hints |
|---|---|---|---|---|
| card_last4 | string | yes | regex (^\d{4}$) | kartennummer letzte 4 · derniers 4 chiffres · ultime 4 cifre · last 4 · últimos 4 |
| card_brand | enum | — | — | kartentyp · marque de carte · marca carta · card brand · marca de tarjeta |
| amount | number | yes | — | betrag · montant · importo · amount · importe |
| currency | string | yes | — | währung · devise · valuta · currency · moneda |
| status | enum | — | — | status · statut · stato · estado |
| processor_ref | string | — | — | referenz · référence · riferimento · reference · referencia |
| captured_at | date | — | — | buchungsdatum · date de capture · data di addebito · fecha de captura |
The cascade
How AdaptivMapr maps your headers to this template
Five layers run in order, cheapest first. Layer 1 (Statistics) auto-accepts headers that have been mapped the same way across past uploads. Layer 2 (Heuristic) compares your header to the column name, the optional label, and every registered hint (DE / FR / IT / EN / ES) after a Unicode-and-punctuation-normalising pass. Layer 3 (Fuzzy) catches typos and reordered words. Layer 4 (Semantic) uses cached embeddings to catch the long tail of paraphrases. Layer 5 (LLM) only fires on genuinely ambiguous columns, constrained to the template’s allowed column set so it cannot invent a field. When a layer auto-accepts, the lower-cost layers below it never run — that is the cost lever.
REST · POST /v1/uploads
Pass the template_id; the cascade picks up the rest.
curl -X POST https://api.adaptivmapr.com/v1/uploads \ -H "Authorization: Bearer $ADAPTIVMAPR_API_KEY" \ -F "template=payments_v1" \ -F "file=@your_data.csv"
The canonical template definition is read-only at GET /v1/templates/payments_v1.
MCP · Cursor / Claude Desktop
Drop AdaptivMapr into your IDE. Schema-only calls are free and unlimited.
// In Cursor or Claude Desktop with the AdaptivMapr MCP server installed:
adaptivmapr.match_headers({
template: "payments_v1",
headers: ["card_last4", "card_brand", "amount", "currency"]
})MCP install instructions →Questions
FAQ — Payments CSV import
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.