Request a saved card from a verified guest

POST /v1/developer/guest/wallet/requests

Operation ID: createDeveloperWalletRequest

Requires a server credential with guest_wallet_requests.write and an existing verified guest visible to this collection (or explicitly registered TEST identity). Kismet sends authentication proof only to the verified guest. partner_link returns navigation context that requires independent guest authentication. Does not charge a card or grant marketing consent. Beta availability is deployment gated.

Contract status

Field	Value
Maturity	`preview`
Required capability	`guest_wallet_requests.write`
Freshness class	`authenticated-state`
Quota cost	`1`

All operations require a Kismet Developer Bearer credential. Collection and resource authority is resolved from the credential’s installation grants; identifiers in the URL never grant access.

Request parameters

Name	In	Type	Required	Description
`idempotency-key`	header	string	yes

Request body

The request body is JSON. The canonical schema is:

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "guestProfileId",
    "returnUrl",
    "delivery"
  ],
  "properties": {
    "guestProfileId": {
      "type": "string",
      "format": "uuid",
      "description": "Canonical guest reference previously obtained through authorized guest account APIs; inaccessible guests return the same not-found response."
    },
    "returnUrl": {
      "type": "string",
      "pattern": "^https?://[^\\s]+$",
      "maxLength": 2048,
      "description": "Start page on an explicitly registered installation origin, without query or fragment. This is not an OAuth callback."
    },
    "delivery": {
      "type": "string",
      "enum": [
        "partner_link",
        "kismet_email"
      ]
    },
    "reference": {
      "type": [
        "null",
        "string"
      ],
      "maxLength": 128,
      "pattern": "^[A-Za-z0-9_.:-]{1,128}$",
      "description": "Opaque caller correlation, not guest contact information."
    }
  }
}

Minimal example:

{
  "guestProfileId": "string",
  "returnUrl": "string",
  "delivery": "partner_link"
}

cURL

Set KISMET_API_ORIGIN=https://api.ksmt.app and configure KISMET_DEVELOPER_API_KEY in your environment. Run server-credential requests from your backend, not browser code.

curl --request POST \
  "$KISMET_API_ORIGIN/v1/developer/guest/wallet/requests" \
  --header "Authorization: Bearer $KISMET_DEVELOPER_API_KEY" \
  --header "Accept: application/json" \
  --header "idempotency-key: $IDEMPOTENCY_KEY" \
  --header "Content-Type: application/json" \
  --data '{"guestProfileId":"string","returnUrl":"string","delivery":"partner_link"}'

Responses

Status	Meaning
200	Success.
400	Invalid request parameters or body.
401	Missing, invalid, expired, or inappropriate credential/session.
403	Credential lacks the required grant/capability, or an origin/CSRF check failed.
404	The authorized resource was not found.
409	Request conflicts with the installation environment or current state.
410	The single-use authentication challenge is no longer valid.
429	Rate limit or quota exceeded; inspect response metadata before retrying.
503	A required Kismet dependency is temporarily unavailable.

200 response schema

Content type: application/json. Required fields, nullable values, and nested structures are defined below.

View complete response schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "id",
    "status",
    "delivery",
    "deliveryState",
    "reference",
    "createdAt",
    "expiresAt",
    "livemode",
    "startUrl"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "status": {
      "type": "string",
      "enum": [
        "pending",
        "in_progress",
        "succeeded",
        "expired",
        "revoked"
      ]
    },
    "delivery": {
      "type": "string",
      "enum": [
        "partner_link",
        "kismet_email"
      ]
    },
    "deliveryState": {
      "type": "string",
      "enum": [
        "not_requested",
        "pending",
        "sent",
        "failed"
      ]
    },
    "reference": {
      "type": [
        "null",
        "string"
      ]
    },
    "createdAt": {
      "type": "string",
      "format": "date-time"
    },
    "expiresAt": {
      "type": "string",
      "format": "date-time"
    },
    "livemode": {
      "type": "boolean"
    },
    "startUrl": {
      "type": [
        "null",
        "string"
      ],
      "description": "Partner navigation context only. Never authenticates a guest. Null for Kismet-delivered email and closed requests."
    }
  }
}