Justt answers Order Insight (OI) and Compelling Evidence 3.0 (CE) requests with your order data. Choose one of three ways to give Justt that data:

The rest of this page explains option 2.

Option 2: Connect your order system (Order Lookup API)

How it works

1. Visa asks Justt about a card transaction (Order Insight), or about a past purchase for a disputed transaction (Compelling Evidence).
2. Justt sends one HTTPS POST request to your endpoint for that one order.
3. Your endpoint finds the order and returns its data.
4. Justt sends the data to Visa.

Justt calls your endpoint in two cases:

• Order Insight (source is OI or OID). A cardholder asks their bank about a transaction. Justt asks you for that order.

• Compelling Evidence 3.0 (source is CE). A cardholder disputes a transaction. Visa looks for earlier, undisputed purchases by the same cardholder. Justt asks you for each past purchase, one request per purchase.
  

  

The rules of the call

• One request is about one order. There is no list call and no batch call.
• Justt sends every identifier it has for the order. Optional identifiers are sent only when Justt has them.
• Always answer with HTTP 200 and a JSON body:
  • Order found: {"matchStatus": "MATCHED", "order": {...}}
  • Order not found: {"matchStatus": "NOT_FOUND"}
• Use the same response shape for Order Insight and Compelling Evidence. Send all the data you have. Justt chooses what to send to Visa.
• Do not send your merchant name, website, phone number or store name. Justt has them from onboarding.

Authentication

You create an API key and give it to your Justt contact. Justt sends it in every request:

Authorization: Bearer <API key>

Reject a request without the correct key with HTTP 401.

Time limit

Which orders you must find

• Any order up to 365 days old.
• For Compelling Evidence, Visa asks about up to 5 past purchases, made 120 to 365 days before the dispute. Justt sends a separate request for each one.

How to find the order

Search by the identifiers you store, from the strongest to the weakest:

1. arn (Acquirer Reference Number), transactionId or authCode
2. purchaseIdentifier (often your order number)
3. cardBin + cardLast4 + transactionAmount + transactionDate

If more than one order matches and you cannot choose one, answer NOT_FOUND.

Examples

Order Insight

Request:

{
  "insightId": "7d1e5b2c-4f0a-4c39-9b8e-1f2a3b4c5d6e",
  "source": "OI",
  "verifiEntityInfo": { "partnerId": 37478, "clientId": 85126 },
  "cardBin": "400000",
  "cardLast4": "1111",
  "transactionDate": "2026-05-01T10:00:00Z",
  "transactionAmount": { "amount": 59.9, "currency": "USD" },
  "arn": "24692166123000000000012",
  "authCode": "123456",
  "transactionId": "581234567890123",
  "acquirerBin": "400000",
  "cardAcceptorId": "SHOPEXAMPLE0001",
  "paymentDescriptor": "SHOPEXAMPLE*ORDER",
  "mcc": "5661"
}

Response:

{
  "matchStatus": "MATCHED",
  "order": {
    "receipt": {
      "orderDate": "2026-05-01T09:58:12Z",
      "orderNumber": "ORD-1001",
      "purchaseCategory": "MERCHANDISE",
      "orderTotalAmount": { "amount": 59.9, "currency": "USD" },
      "paymentInformation": {
        "paymentMethod": "VISA **** 1111",
        "billingName": "Dana Levi",
        "billingAddressDetails": {
          "address1": "1 Main St",
          "city": "Austin",
          "postalCode": "73301",
          "country": "US"
        },
        "cvvChecked": true
      },
      "productsPurchasedList": [
        {
          "productDescription": "Running shoes, size 42",
          "quantity": 1,
          "unitPriceAmount": { "amount": 49.9, "currency": "USD" }
        }
      ]
    },
    "customerInformation": {
      "firstName": "Dana",
      "lastName": "Levi",
      "accountId": "cust-42",
      "emailAddress": "[email protected]"
    },
    "deliveryAddress": { "address1": "1 Main St", "city": "Austin", "postalCode": "73301", "country": "US" },
    "recipientCustomerName": "Dana Levi",
    "deliveryDetails": {
      "shippingCarrier": "UPS",
      "trackingNumber": "1Z999AA10123456784",
      "deliveryStatus": "DELIVERED"
    },
    "device": { "ipAddress": "203.0.113.24", "deviceId": "8f14e45fceea167a5a36", "deviceType": "mobile" }
  }
}

Compelling Evidence (one past purchase)

Request:

{
  "insightId": "2b9c0e1f-77a1-4e0d-8c55-0a1b2c3d4e5f",
  "source": "CE",
  "verifiEntityInfo": { "partnerId": 37478, "clientId": 85126 },
  "cardBin": "400000",
  "cardLast4": "1111",
  "transactionDate": "2026-01-12T18:30:00Z",
  "transactionAmount": { "amount": 24.5, "currency": "USD" },
  "transactionId": "581234567000001"
}

Response (same shape as Order Insight):

{
  "matchStatus": "MATCHED",
  "order": {
    "receipt": {
      "orderDate": "2026-01-12T18:29:40Z",
      "orderNumber": "ORD-0713",
      "purchaseCategory": "SERVICE",
      "orderTotalAmount": { "amount": 24.5, "currency": "USD" },
      "productsPurchasedList": [{ "productDescription": "Monthly subscription", "quantity": 1 }]
    },
    "customerInformation": { "accountId": "cust-42", "emailAddress": "[email protected]" },
    "device": { "ipAddress": "203.0.113.24", "deviceId": "8f14e45fceea167a5a36" }
  }
}

Order not found

{ "matchStatus": "NOT_FOUND" }

Test request

A test request has the header X-Justt-Test: true, and its insightId starts with test-. The card and amount may not match a real order. Answer with any example order from your system, so Justt can check the response.

POST /your-order-lookup-path HTTP/1.1
Authorization: Bearer <API key>
X-Justt-Test: true
Content-Type: application/json

{
  "insightId": "test-0f8c2a",
  "source": "OI",
  "cardBin": "400000",
  "cardLast4": "1111",
  "transactionDate": "2026-05-01T10:00:00Z",
  "transactionAmount": { "amount": 1, "currency": "USD" }
}

Data points

Compelling Evidence rules

Visa names four CE elements:

• IP address: device.ipAddress
• Device ID or device fingerprint: device.deviceId or device.deviceFingerprint. These two fields together count as one element. Sending both does not count as two elements.
• Account / login ID: customerInformation.accountId
• Shipping (delivery) address: deliveryAddress

1. Send at least 2 of the 4 elements.
2. At least 1 of them must be the IP address, or the device ID or device fingerprint.
3. For physical goods, also send deliveryAddress. An order is physical goods when purchaseCategory is MERCHANDISE, or when it has a shippingCarrier or a trackingNumber.

A field that fails a data-quality rule does not count for rules 1 and 2. The device element counts when device.deviceId or device.deviceFingerprint passes its rule.

Data-quality rules

• device.ipAddress is the customer's public IPv4 or IPv6 address in plain text. Do not hash or mask it. Justt rejects these ranges:
  • 0.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16
  • 100.64.0.0/10 (carrier-grade NAT)
  • 127.0.0.0/8 (loopback), 169.254.0.0/16 (link-local)
  • 224.0.0.0/3 (multicast and reserved)
  • ::, ::1, fc00::/7, fe80::/10, ff00::/8
  • IPv4-mapped IPv6 forms of the IPv4 ranges above, for example ::ffff:10.0.0.1
• device.deviceId has 15 to 32 characters.
• device.deviceFingerprint has 20 to 45 characters.
• deliveryAddress has address1 and country in clear text. Do not hash or mask address1: Justt rejects a value with *, 32 or more hex characters, or 40 or more base64 characters without spaces.
• country is an ISO 3166-1 alpha-2 code, for example US, in any case. Justt checks it only in the delivery address used for Compelling Evidence.
• Every amount has both amount and currency. amount is a number in major units (59.9, not "59.90" and not 5990). currency is an ISO 4217 code in capital letters, for example USD.
• A field that is null, empty ("") or only spaces counts as not sent.
• receipt.productsPurchasedList has at most 100 items.
• Fields that are not in the contract are ignored.

When something goes wrong

A NOT_FOUND answer is a normal answer, not a failure. For Order Insight, Justt still answers Visa with your onboarding details. For Compelling Evidence, Visa receives no evidence for that purchase.

These are the failure reasons you may see:

If your endpoint keeps failing, Justt stops calling it for a short time and then tries again.

Test before go-live

1. Deploy your endpoint. Give your Justt contact its URL and your API key.
2. Ask your Justt contact to run a test request.
3. Justt sends a request with X-Justt-Test: true and shows the result. It lists every rule that failed and what to fix.
4. Fix the failed rules and ask for another test.

We strongly recommend passing a test before your Justt contact turns on live traffic.

OpenAPI file