Transaction data

Why am I missing transactions that appear on the cardholder's bank statement?

A few common causes: the transaction hasn't propagated yet (allow 24–48 hours), the card was enrolled after the charge occurred, a subaccount mismatch is filtering it out of your query, the charge routed over a domestic debit network outside Visa/Mastercard/Amex (see "Why am I missing debit card transactions?" below), or it's a non-network charge (ACH, a bank fee) that never generates a card-network message in the first place.

Why does the amount or number of records not match what I expected?

Multiple network messages from the same merchant can correlate into a single logical record — check cardholderBillingSettledAmount against the statement rather than counting raw messages. Related patterns worth knowing:

• A single large purchase can arrive as several separate partial-clearing messages from the same
  merchant, rather than one clearing for the full amount — everything reconciles once you sum them,
  but a partial view (e.g. only some line items) looks like a shortfall.
• Hotels, car rentals, and similar large-pre-authorization merchants legitimately go
  PENDING → VOIDED → SETTLED for one purchase: the initial hold is authorized, then voided, then a
  separate final folio clearing settles the actual charge. A VOIDED status here is not a
  cancellation — treating it as terminal will make you drop a real, paid charge.
• Travel and airline merchants routinely send multiple genuinely separate authorizations for
  what looks like one purchase — most simply age off in 7–30 days without ever clearing. Each one
  was a real, distinct network event, not a duplicate charge.

Tips, adjustments, and gas-station pre-authorizations can also cause smaller discrepancies.

Why are pending transactions taking days to clear?

Most transactions clear within 1–3 business days. Hotels can take up to 30 days, car rentals 7–10 days after the rental ends, and refunds 5–7 business days.

Why do timestamps or dates not match?

Astrada stores all timestamps in UTC — check for a local timezone difference first. Authorization and settlement dates also legitimately differ, and refund/correction messages can arrive out of sequence.

Two different currencies for one transaction isn't a bug. transactionCurrency reflects the merchant's local currency; cardholderBillingCurrency (and its settled/hold amounts) reflect the card's home currency, FX-converted. A US-issued card used abroad will legitimately show both — one purchase, two currency/amount pairs, by design.

Why do I see what looks like a duplicate transaction?

A few distinct mechanisms, each legitimate:

• Re-presentment or correction messages (FINL_ADVC) updating an existing transaction rather
  than creating a new one.
• Split transactions from one purchase (see above).
• A reissued card with the same PAN producing what looks like a repeat.
• A linked virtual/physical card pair. Some card programs issue a virtual card linked to a
  physical one (or similar bank-side linkage); a bulk feed can deliver these as two separate card
  records that happen to share the same BIN and last four digits. It's two distinct underlying
  cards, not the same card enrolled twice.
• Placeholder or malformed reference fields sent by the network itself — 000000, repeated
  digits, or literal text like N/A/UNKNOWN in approval-code or reference fields. This is network
  data quality, not an Astrada error, but worth knowing if you reconcile against these fields
  yourself: in rare cases it can make two unrelated purchases look correlated.
• A merchant ID that's formatted differently between a purchase's authorization and its clearing
  record (some networks reformat or truncate it). An exact-match reconciliation strategy on merchant
  ID alone can miss that it's the same purchase.

Every transaction has a unique transactionId — use it, not derived fields, to verify identity.

Why do refunds show as positive charges?

Check the underlying Transaction Message's transactionType (a CREDIT_* prefix vs. DEBIT_*) rather than the sign of the amount alone. Allow up to 24 hours for a reversal to reflect, and note the refund's date may differ from the original transaction's date.

How do I match Astrada data to a bank statement?

Our bank data product connects accounts via Plaid, layers card-network data on top for merchant detail, and surfaces "bank only" transactions (fees, transfers, payroll) with no card-side counterpart. Bank availability varies by region.

Card enrollment

What causes card enrollment errors?

Common causes: SCA/3DS failures at the issuer, an unsupported BIN, the card already being enrolled, or a transient server error. When reporting an issue, include the card ID and the full error response.

What's the difference between bulk and individual enrollment?

Individual enrollment connects one cardholder at a time via the SDK, with interactive 3DS verification. Bulk enrollment is file-based or API-driven, with no per-card interaction, and is limited to eligible corporate/commercial programs.

A large bulk enrollment doesn't complete all at once. Cards can activate gradually over several days rather than instantly — that's normal processing behavior, not a sign that enrollment is stuck.

Why does an enrolled card show no transactions?

Check the subscription's status, whether the subaccount is active, whether your webhook endpoint is reachable, whether any transactions have actually occurred since enrollment, and — for virtual cards — see below.

What cards and regions are supported?

Visa and Mastercard open-loop credit and commercial debit; American Express commercial. Coverage includes the US, Canada, UK, select EU countries, Australia, and New Zealand. Not supported: consumer prepaid/debit, closed-loop cards, government prepaid, and FSA/HSA cards.

Why am I missing debit card transactions?

Consumer debit cards aren't supported (only commercial debit is eligible). Domestic debit routing (e.g. Pulse, Interac) can also bypass the Visa/Mastercard systems entirely, in which case Astrada never sees the transaction.

Is American Express supported?

Yes, via bulk enrollment for business, corporate, and commercial Amex programs, with settled transaction data across supported regions.

Are virtual cards supported?

A virtual card enrolled directly behaves like any other card. A virtual card issued under a parent physical card only shows transactions if the issuer processes them against the enrolled parent PAN. Apple Pay / Google Pay provisioned cards aren't supported.

What happens to a card's enrollment when the card expires or is reissued?

Same PAN with a new expiry date: a new subscription is created; the old one remains until you manually deactivate it. A genuinely new PAN: auto-deactivated for bulk enrollments, manual for individual. Subscriptions don't auto-expire when the card does — inactive subscriptions are purged after 60 days.

A cardholder's card number changed — what do I do?

Deactivate the old subscription and enroll the new PAN as a new subscription (individual enrollment requires a fresh 3DS). Don't reuse the old subscription ID. Bulk enrollments submit the new PAN as a new entry automatically.

Why don't I have a cardholder's name or email?

Cardholder identity (firstName, lastName, email) is only available for cards enrolled through a Network Bulk Feed, sourced from the feed itself — the feed typically carries an employee ID rather than full identity detail, and standalone SDK enrollment doesn't collect cardholder identity at all. See Core Resources for the Cardholder resource, and join the employee ID against your own records if you need a name.

Webhooks

I'm not receiving webhooks — why?

Verify your endpoint is publicly reachable and returns an HTTP 2xx, that you're subscribed to the right event types, and that you respond within 5 seconds. Validate signatures using your webhook secret (HMAC-SHA256) — see Webhooks.

Seeing what looks like a duplicate delivery? Two registered endpoints subscribed to the same event types on one subaccount will each legitimately receive their own copy — that's not an Astrada duplicate-send bug. More generally, webhook delivery is at-least-once, not exactly-once, even with a single endpoint — build idempotent handling (dedupe by event ID) regardless.

What's the difference between transaction.created and transaction.updated?

transaction.created fires on the initial authorization. transaction.updated fires whenever the transaction's state changes afterward — pending to cleared, an amount adjustment, and so on. Use transaction.updated for the final settled amount.

What's the expected sequence of transaction messages?

Typically AUTH_REQU (the initial request) → AUTH_ADVC (confirmation/update) → FINL_ADVC (correction/settlement). Messages can arrive out of order — correlate by transactionId, not arrival order.

How do I validate my webhook endpoint?

Accept POST requests and return a 2xx status. Use the webhook-event-type header and subaccountId for routing, validate the signature, handle retries gracefully, and deduplicate by event ID. Respond within 5 seconds.

Account & testing

Why do I get a 4xx Unauthorized error?

Usually an expired token or incorrect scope. Refresh your token before it expires, and verify your account has the right scopes if the error persists.

How do I create and manage test subaccounts?

Create them the same way as any subaccount, via POST /subaccounts. Note: there's no public, self-service API to delete a subaccount — contact your Astrada representative if you need one removed.