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.
