Transactions

Search transactions

Finds a project's successful Stripe charges from payment evidence, for a backend that needs to match a transaction without keeping a second copy of the project's transaction database.

Scope: transactions:read

Request

POST /transactions/search?projectId=<project-id>
Content-Type: application/json

The body must include environment plus either an exact Stripe Charge (ch_*), PaymentIntent (pi_*) or Invoice (in_*) reference, or the complete amount, currency and transactionDate tuple.

Parameters

Field	Required	Purpose
environment	Yes	Stripe environment: live or test.
amount	With the core tuple	Integer amount in Stripe minor units.
currency	With the core tuple	Three-letter currency code.
transactionDate	With the core tuple	ISO 8601 transaction timestamp.
reference	When the core tuple is absent	Stripe reference evidence. Only exact ch_*, pi_* or in_* IDs add an indexed reference match; other values require the core tuple.
windowDays	No	Inclusive date window on either side of transactionDate; defaults to 3, range 0..7.
limit	No	Maximum candidates; defaults to 1, range 1..100.
scheme	No	visa or mastercard; not used to filter core candidates.
cardBin	No	Card BIN; not used to filter core candidates.
cardLast4	No	Card last-four fallback. It matches card last4 or wallet dynamic_last4.
authCode	No	Strong authorization-code evidence; an exact match wins over card fallback.

Optional headers:

Header	Purpose
X-Request-ID	A unique ID per lookup; funnelsgrove echoes it in the response.
X-Trace-ID	Groups several related requests in server telemetry.
X-SDK-Request-Mode: shadow	Marks a request whose result does not drive your live response. Omit for primary traffic.

Example

curl -sS "https://sdk-api.funnelsgrove.com/integration/v1/transactions/search" \
  -H "X-SDK-Secret-Key: <project-sdk-secret-key>" \
  -H "X-Request-ID: lookup-<unique-id>" \
  -H "Content-Type: application/json" \
  --data '{
    "environment": "live",
    "scheme": "mastercard",
    "cardLast4": "4444",
    "amount": 3999,
    "currency": "USD",
    "transactionDate": "2026-08-10T12:00:00Z",
    "windowDays": 3
  }'

Response

{
  "transactions": [
    {
      "id": "stripe-mirror-row-id",
      "mode": "live",
      "chargeId": "ch_123",
      "paymentIntentId": "pi_123",
      "invoiceId": "in_123",
      "stripeCustomerId": "cus_123",
      "customerEmail": "buyer@example.com",
      "customerName": "Buyer Name",
      "customerFirstName": "Buyer",
      "customerLastName": "Name",
      "customerPhone": "+15551234567",
      "customerIpAddress": "8.8.8.8",
      "amount": 3999,
      "currency": "USD",
      "transactionDate": "2026-08-10T12:00:00.000Z",
      "cardBrand": "mastercard",
      "cardBin": "555555",
      "cardLast4": "4444",
      "cardDynamicLast4": "1111",
      "walletType": "apple_pay",
      "authCode": "123456",
      "networkTransactionId": "network-transaction-id",
      "paymentDescriptor": "CLAIMBEE",
      "stripePriceId": "price_123",
      "stripeProductId": "prod_123",
      "productName": "ClaimBee Annual Access",
      "productDescription": "Annual ClaimBee access",
      "productType": "subscription",
      "productUrl": null,
      "unitPriceAmount": 3999
    }
  ]
}

A normal miss returns 200 with { "transactions": [] }. Responses use Cache-Control: no-store and carry the handler duration as Server-Timing: transaction-search;dur=<ms>.

funnelsgrove searches successful paid charges by project, environment, amount, currency and date, and can union an exact Stripe reference match. It does not discard candidates based on the requested BIN, last four, scheme, authorization code or network transaction ID; keep the final card-network matching and ambiguity logic on your side so network-tokenized cards can still match using stronger identifiers.

customerIpAddress is the public IP captured with the payment metadata. It is never replaced with the IP of the backend calling this endpoint. Raw Stripe payloads, unfiltered metadata and internal IDs are not returned.

Server telemetry records only the bounded outcome, search strategy, candidate count and presence counts of matching evidence. Transaction IPs, card data, authorization codes, references, customer contact values and request bodies are not copied into telemetry.

Errors

Status	Meaning
400	The request is invalid or the core tuple is incomplete.
503	The lookup exceeded its 800 ms deadline; retry with backoff.
500	An unexpected lookup error occurred.