> This page is for Partner API.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.getmodulate.dev/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.getmodulate.dev/_mcp/server.

# Join gateway transactions to settled processor transactions

Use `/api/partner/merchants/{mid}/gateway-transactions` for the gateway list and `/api/partner/merchants/{mid}/transactions` for settled processor rows. Both external Modulate and internal UAT expose the same fields. Keep the authorized MID in the join key; references can repeat across merchants.

For ARISE card sales, `processor_reference` is the normalized `order_number`. For ARISE refunds it is the parent sale's normalized `order_number`. For NMI sales it is the normalized `order_id`, or the gateway transaction ID when the order ID is absent. NMI credits appear as `refund` in the gateway list and do not use a reference match until their processor behavior is verified. A `refund` list filter includes both NMI `refund` and `credit` actions. For a refund or credit followed by a settle action, matching retains the original credit amount and date. Normalization trims surrounding ASCII whitespace, lowercases, then removes the entire leading run of zeros and ASCII whitespace together (`000  370074` becomes `370074`); blank or all-padding references become null. `order_id` remains the gateway-facing display field and may differ from `processor_reference`.

Query the per-merchant settled list with `merchant_reference=<processor_reference>` and a bounded date range when the reference is present. Compare MID and direction (sale to debit, refund to credit); compare absolute amount for a refund. `merchant_reference` is null for legacy history and Fiserv. `auth_code` is the processor approval code on modern Atlas rows when available. The raw TSYS DDF `auth_code` is a network reference, not this approval code.

When the processor reference is absent on either side, use an approval fallback only with the same MID, approval code, four-digit card last4, absolute amount, direction, and processor date from the gateway date minus one through plus four days. ARISE uses its published merchant-local created date. NMI uses the date supplied by its Query API; the API does not provide a verified merchant timezone, so this is a vendor date rather than a converted merchant-local date. Never fall back when both references are known and disagree. Never use last4, amount and date alone. If more than one row qualifies, leave the transaction unresolved. For a single gateway transaction, the detail route performs this bounded lookup and returns `settlement`. A stale authorization manifest, feed error, or lack of usable identifiers produces `unavailable`; it does not change ingestion IDs or write a replica.

An ARISE sale later marked `ChargedBack` has public status `failed` but may still link to its original settled debit. Declines and failed attempts do not settle. `not_found` means no match in the currently published processor feed after the expected five-day window; a delayed feed publication can outlast that window. Response `meta.as_of` describes gateway record freshness, not processor feed freshness.