Skip to content
SarvexDocs
Esc
↑↓navigate↵open⌘Jpreview

Negotiation outcomes, failure breakdown, and payment-handler mismatch detail

attempts/successes/failures summed over the range. failures is broken down by the closed failure_reason enum negotiation.Negotiate actually produces (version_unsupported, capabilities_incompatible); each carries missing_capability_counts when the failure reason is itself a capability-set delta (capabilities_incompatible only — version_unsupported fails on the version field, not a capability delta, so that map is absent there). payment_handler_mismatch is its own dedicated breakdown, computed observationally from every negotiation attempt (succeeded or failed) whose offered payment-handler set had no overlap with the merchant’s declared set — an empty payment-handler intersection does not fail negotiation on its own, so this condition would otherwise be invisible in failures. Breakdown entries below the small-count suppression threshold (default 5) are omitted; attempts/successes totals are never suppressed. Max range 92 days.

GET/insights/negotiation
Authorization
AuthorizationBearer token (JWT) · headerrequired

JWT issued by the external IdP via the OAuth 2.0 authorization-code flow (Kinde in production; a simulator in test). The client obtains it and sends it as a Bearer token on every authenticated call. Sarvex's services verify it — issuer, audience, signature (IdP JWKS), expiry — and read identity and tenant from its claims. Sarvex does not issue or revoke these tokens. merchant_id/store_id are read from the verified claims (and the merchant→store mapping), never from the URL. The operator scope is required for /operator/*. Operators acting on a specific merchant pass the X-Operate-As header, which is recorded in the audit log.

Query parameters
fromstring<date>

yyyy-MM-dd, inclusive. Defaults to 29 days before to. Range with to is capped at 92 days.

tostring<date>

yyyy-MM-dd, inclusive. Defaults to today (UTC). Range with from is capped at 92 days.

Responses
200

Negotiation outcome summary for the range.

attemptsinteger
successesinteger
failuresinsights_negotiation_failure[]
Show properties
Array of insights_negotiation_failure
reasoninsights_negotiation_failure_reason

Closed enum derived from negotiation.Negotiate — the only two strings that service ever produces for a failure.

Allowed:version_unsupportedcapabilities_incompatible
countinteger
missing_capability_countsobject | null

Present only when reason=capabilities_incompatible — how many times each requested-but-undeclared capability contributed to this failure reason. Absent for version_unsupported (that failure is caused by the version field, not a capability delta).

payment_handler_mismatchinsights_payment_handler_mismatch

R6: how often agents offered a payment-handler set with no overlap with the merchant's declared set ("no_common_payment_handler") — observational, not itself a hard negotiation-failure condition.

Show properties
occurrencesinteger
offered_handler_countsobject

Per-handler count of how many mismatch occurrences offered it, e.g. “agents offered PayPal 210 times”.

merchant_declared_handlersstring[]

The merchant's declared payment-handler set as of the most recent occurrence in range.

403

Authenticated but not permitted (e.g. non-operator on an operator route).

errorobjectrequired
Show properties
codestringrequired
messagestringrequired
detailsobject | null
422

Request body failed validation.

errorobjectrequired
Show properties
codestringrequired
messagestringrequired
detailsobject | null
Try it
Server
Authorization
Parameters
Request
curl -X GET "https://api.sarvex.example.com/v1/insights/negotiation" \
  -H "Authorization: Bearer YOUR_TOKEN"
Response
{
  "attempts": 0,
  "successes": 0,
  "failures": [
    {
      "reason": "version_unsupported",
      "count": 0,
      "missing_capability_counts": {
        "property1": 0,
        "property2": 0
      }
    }
  ],
  "payment_handler_mismatch": {
    "occurrences": 0,
    "offered_handler_counts": {
      "property1": 0,
      "property2": 0
    },
    "merchant_declared_handlers": [
      "string"
    ]
  }
}