Claim a widget transition for its saved receiver

One-use widget transport permit and the tuple generated and privately saved by the trusted top-level receiver. Raw receiver capability and handoff remain local until ordinary redemption.

permitRequired

Exact private transport permit received in the fixed-destination POST body. This secret never appears in a URL or parent message.

string

Full definition

{
  "type": "string",
  "minLength": 48,
  "maxLength": 48,
  "pattern": "^gpw1_[A-Za-z0-9_-]{43}$",
  "example": "gpw1_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
  "writeOnly": true,
  "description": "Exact private transport permit received in the fixed-destination POST body. This secret never appears in a URL or parent message."
}

recipientCapabilityHashRequired

SHA-256 hex digest of the complete fresh gpa1_ capability already saved by this receiver.

string

Full definition

{
  "type": "string",
  "minLength": 64,
  "maxLength": 64,
  "pattern": "^[a-f0-9]{64}$",
  "writeOnly": true,
  "description": "SHA-256 hex digest of the complete fresh gpa1_ capability already saved by this receiver.",
  "example": "deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef"
}

handoffHashRequired

SHA-256 hex digest of the complete fresh gph1_ handoff already saved by this receiver.

string

Full definition

{
  "type": "string",
  "minLength": 64,
  "maxLength": 64,
  "pattern": "^[a-f0-9]{64}$",
  "writeOnly": true,
  "description": "SHA-256 hex digest of the complete fresh gph1_ handoff already saved by this receiver.",
  "example": "deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef"
}

receiverContextKeyRequired

Opaque context key generated with at least 32 random bytes and privately saved with the receiver tuple. It contains no capability, source identifier or personal data and cannot be replaced after claim.

string

Full definition

{
  "type": "string",
  "minLength": 43,
  "maxLength": 128,
  "pattern": "^[A-Za-z0-9_-]{43,128}$",
  "writeOnly": true,
  "description": "Opaque context key generated with at least 32 random bytes and privately saved with the receiver tuple. It contains no capability, source identifier or personal data and cannot be replaced after claim.",
  "example": "synthetic-example-credentialxxxxxxxxxxxxxxx"
}

{
  "type": "object",
  "properties": {
    "permit": {
      "type": "string",
      "minLength": 48,
      "maxLength": 48,
      "pattern": "^gpw1_[A-Za-z0-9_-]{43}$",
      "example": "gpw1_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
      "writeOnly": true,
      "description": "Exact private transport permit received in the fixed-destination POST body. This secret never appears in a URL or parent message."
    },
    "recipientCapabilityHash": {
      "type": "string",
      "minLength": 64,
      "maxLength": 64,
      "pattern": "^[a-f0-9]{64}$",
      "writeOnly": true,
      "description": "SHA-256 hex digest of the complete fresh gpa1_ capability already saved by this receiver.",
      "example": "deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef"
    },
    "handoffHash": {
      "type": "string",
      "minLength": 64,
      "maxLength": 64,
      "pattern": "^[a-f0-9]{64}$",
      "writeOnly": true,
      "description": "SHA-256 hex digest of the complete fresh gph1_ handoff already saved by this receiver.",
      "example": "deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef"
    },
    "receiverContextKey": {
      "type": "string",
      "minLength": 43,
      "maxLength": 128,
      "pattern": "^[A-Za-z0-9_-]{43,128}$",
      "writeOnly": true,
      "description": "Opaque context key generated with at least 32 random bytes and privately saved with the receiver tuple. It contains no capability, source identifier or personal data and cannot be replaced after claim.",
      "example": "synthetic-example-credentialxxxxxxxxxxxxxxx"
    }
  },
  "description": "One-use widget transport permit and the tuple generated and privately saved by the trusted top-level receiver. Raw receiver capability and handoff remain local until ordinary redemption.",
  "required": [
    "permit",
    "recipientCapabilityHash",
    "handoffHash",
    "receiverContextKey"
  ],
  "example": {
    "permit": "gpw1_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
    "recipientCapabilityHash": "deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef",
    "handoffHash": "deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef",
    "receiverContextKey": "synthetic-example-credentialxxxxxxxxxxxxxxx"
  }
}

Private acknowledgement that the existing handoff fields are bound to the exact saved receiver tuple. Continue with ordinary handoff redemption and checkout or original-receipt recovery.

transitionIdRequired

Exact caller-saved noncredential transition UUID.

string · uuid

Full definition

{
  "type": "string",
  "format": "uuid",
  "description": "Exact caller-saved noncredential transition UUID.",
  "example": "863d2796-5dc7-4cf6-8e5b-c010833c0e1d"
}

accessIdRequired

Exact existing payment access context. The identifier grants no payment or receipt access.

string · uuid

Full definition

{
  "type": "string",
  "format": "uuid",
  "description": "Exact existing payment access context. The identifier grants no payment or receipt access.",
  "example": "b93bc84d-84db-4161-840b-c3c7a7875b1d"
}

expiresAtRequired

Frozen initial claim and handoff deadline, at most sixty seconds from preparation and within original native and financial or receipt authority. Replays return this same value, including after it has passed; they never renew authority.

string · date-time

Full definition

{
  "type": "string",
  "format": "date-time",
  "description": "Frozen initial claim and handoff deadline, at most sixty seconds from preparation and within original native and financial or receipt authority. Replays return this same value, including after it has passed; they never renew authority.",
  "example": "2026-12-31T18:00:00.000Z"
}

destinationOriginRequired

Server-selected canonical checkout origin for the private top-level POST receiver. No caller-controlled return or redirect destination is accepted.

string · uri

Full definition

{
  "type": "string",
  "format": "uri",
  "maxLength": 2048,
  "description": "Server-selected canonical checkout origin for the private top-level POST receiver. No caller-controlled return or redirect destination is accepted.",
  "example": "https://hallify.example.test"
}

receiverContextKeyRequired

The same opaque receiver context key supplied on the first claim. Losing its saved private tuple cannot be recovered by choosing a new receiver.

string

Full definition

{
  "type": "string",
  "minLength": 43,
  "maxLength": 128,
  "pattern": "^[A-Za-z0-9_-]{43,128}$",
  "description": "The same opaque receiver context key supplied on the first claim. Losing its saved private tuple cannot be recovered by choosing a new receiver.",
  "example": "synthetic-example-credentialxxxxxxxxxxxxxxx"
}

{
  "type": "object",
  "properties": {
    "transitionId": {
      "type": "string",
      "format": "uuid",
      "description": "Exact caller-saved noncredential transition UUID.",
      "example": "863d2796-5dc7-4cf6-8e5b-c010833c0e1d"
    },
    "accessId": {
      "type": "string",
      "format": "uuid",
      "description": "Exact existing payment access context. The identifier grants no payment or receipt access.",
      "example": "b93bc84d-84db-4161-840b-c3c7a7875b1d"
    },
    "expiresAt": {
      "type": "string",
      "format": "date-time",
      "description": "Frozen initial claim and handoff deadline, at most sixty seconds from preparation and within original native and financial or receipt authority. Replays return this same value, including after it has passed; they never renew authority.",
      "example": "2026-12-31T18:00:00.000Z"
    },
    "destinationOrigin": {
      "type": "string",
      "format": "uri",
      "maxLength": 2048,
      "description": "Server-selected canonical checkout origin for the private top-level POST receiver. No caller-controlled return or redirect destination is accepted.",
      "example": "https://hallify.example.test"
    },
    "receiverContextKey": {
      "type": "string",
      "minLength": 43,
      "maxLength": 128,
      "pattern": "^[A-Za-z0-9_-]{43,128}$",
      "description": "The same opaque receiver context key supplied on the first claim. Losing its saved private tuple cannot be recovered by choosing a new receiver.",
      "example": "synthetic-example-credentialxxxxxxxxxxxxxxx"
    }
  },
  "description": "Private acknowledgement that the existing handoff fields are bound to the exact saved receiver tuple. Continue with ordinary handoff redemption and checkout or original-receipt recovery.",
  "required": [
    "transitionId",
    "accessId",
    "expiresAt",
    "destinationOrigin",
    "receiverContextKey"
  ],
  "example": {
    "transitionId": "863d2796-5dc7-4cf6-8e5b-c010833c0e1d",
    "accessId": "b93bc84d-84db-4161-840b-c3c7a7875b1d",
    "expiresAt": "2026-12-31T18:00:00.000Z",
    "destinationOrigin": "https://hallify.example.test",
    "receiverContextKey": "synthetic-example-credentialxxxxxxxxxxxxxxx"
  }
}

Stable error envelope emitted by the global HTTP exception boundary. Domain-specific machine data, when present, is nested under details.

statusCodeRequired

HTTP status code repeated from the response.

integer

Full definition

{
  "type": "integer",
  "description": "HTTP status code repeated from the response.",
  "example": 400
}

errorRequired

Translation key for the HTTP category, such as errors:http.conflict. The specific cause is identified by code and translationKey.

string

Full definition

{
  "type": "string",
  "description": "Translation key for the HTTP category, such as errors:http.conflict. The specific cause is identified by code and translationKey.",
  "example": "errors.request.invalid"
}

codeRequired

Stable machine-readable domain code, or an HTTP_* fallback when no domain code is provided. Branch on this field and the HTTP status; localized wording never controls retries or business decisions.

string

Full definition

{
  "type": "string",
  "example": "HTTP_BAD_REQUEST",
  "description": "Stable machine-readable domain code, or an HTTP_* fallback when no domain code is provided. Branch on this field and the HTTP status; localized wording never controls retries or business decisions."
}

messageRequired

Translation key, identical to translationKey. The API does not return localized display text. Resolve the key and translationValues in the consuming application.

string

Full definition

{
  "type": "string",
  "example": "errors:http.badRequest",
  "description": "Translation key, identical to translationKey. The API does not return localized display text. Resolve the key and translationValues in the consuming application."
}

translationKeyRequired

Canonical translation key, identical to message. Status-specific errors:http.* keys cover unspecified failures. Public keys and EN/RU explanations are listed in Developers; unknown keys require a localized client fallback.

string

Full definition

{
  "type": "string",
  "example": "errors:http.badRequest",
  "description": "Canonical translation key, identical to message. Status-specific errors:http.* keys cover unspecified failures. Public keys and EN/RU explanations are listed in Developers; unknown keys require a localized client fallback."
}

translationValuesOptional

Optional scalar values for placeholders in the translation. Treat values as data, escape them when rendering, and never use them as translation options.

object

Full definition

{
  "type": "object",
  "additionalProperties": {
    "oneOf": [
      {
        "type": "string",
        "example": "example"
      },
      {
        "type": "number",
        "example": 0
      },
      {
        "type": "boolean",
        "example": true
      }
    ],
    "example": "example"
  },
  "description": "Optional scalar values for placeholders in the translation. Treat values as data, escape them when rendering, and never use them as translation options.",
  "example": {
    "exampleKey": "example"
  }
}

validationErrorsOptional

Field validation failures with translation keys and stable validator codes. Submitted values and raw validator text are not included.

array

Full definition

{
  "description": "Field validation failures with translation keys and stable validator codes. Submitted values and raw validator text are not included.",
  "type": "array",
  "items": {
    "$ref": "#/components/schemas/ValidationErrorDto"
  },
  "example": [
    {
      "field": "email",
      "translationKey": "validation:isEmail",
      "code": "isEmail",
      "message": "validation:isEmail"
    }
  ]
}

detailsOptional

Optional domain-specific blocker or validation details

oneOf

Full definition

{
  "description": "Optional domain-specific blocker or validation details",
  "oneOf": [
    {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/JsonValue"
      },
      "example": [
        "example"
      ]
    },
    {
      "type": "object",
      "additionalProperties": {
        "$ref": "#/components/schemas/JsonValue"
      },
      "example": {
        "exampleKey": "example"
      }
    }
  ],
  "example": [
    "example"
  ]
}

{
  "type": "object",
  "properties": {
    "statusCode": {
      "type": "integer",
      "description": "HTTP status code repeated from the response.",
      "example": 400
    },
    "error": {
      "type": "string",
      "description": "Translation key for the HTTP category, such as errors:http.conflict. The specific cause is identified by code and translationKey.",
      "example": "errors.request.invalid"
    },
    "code": {
      "type": "string",
      "example": "HTTP_BAD_REQUEST",
      "description": "Stable machine-readable domain code, or an HTTP_* fallback when no domain code is provided. Branch on this field and the HTTP status; localized wording never controls retries or business decisions."
    },
    "message": {
      "type": "string",
      "example": "errors:http.badRequest",
      "description": "Translation key, identical to translationKey. The API does not return localized display text. Resolve the key and translationValues in the consuming application."
    },
    "translationKey": {
      "type": "string",
      "example": "errors:http.badRequest",
      "description": "Canonical translation key, identical to message. Status-specific errors:http.* keys cover unspecified failures. Public keys and EN/RU explanations are listed in Developers; unknown keys require a localized client fallback."
    },
    "translationValues": {
      "type": "object",
      "additionalProperties": {
        "oneOf": [
          {
            "type": "string",
            "example": "example"
          },
          {
            "type": "number",
            "example": 0
          },
          {
            "type": "boolean",
            "example": true
          }
        ],
        "example": "example"
      },
      "description": "Optional scalar values for placeholders in the translation. Treat values as data, escape them when rendering, and never use them as translation options.",
      "example": {
        "exampleKey": "example"
      }
    },
    "validationErrors": {
      "description": "Field validation failures with translation keys and stable validator codes. Submitted values and raw validator text are not included.",
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/ValidationErrorDto"
      },
      "example": [
        {
          "field": "email",
          "translationKey": "validation:isEmail",
          "code": "isEmail",
          "message": "validation:isEmail"
        }
      ]
    },
    "details": {
      "description": "Optional domain-specific blocker or validation details",
      "oneOf": [
        {
          "type": "array",
          "items": {
            "$ref": "#/components/schemas/JsonValue"
          },
          "example": [
            "example"
          ]
        },
        {
          "type": "object",
          "additionalProperties": {
            "$ref": "#/components/schemas/JsonValue"
          },
          "example": {
            "exampleKey": "example"
          }
        }
      ],
      "example": [
        "example"
      ]
    }
  },
  "required": [
    "statusCode",
    "error",
    "code",
    "message",
    "translationKey"
  ],
  "description": "Stable error envelope emitted by the global HTTP exception boundary. Domain-specific machine data, when present, is nested under details.",
  "example": {
    "statusCode": 400,
    "error": "errors:http.badRequest",
    "code": "HTTP_BAD_REQUEST",
    "message": "errors:http.badRequest",
    "translationKey": "errors:http.badRequest"
  }
}

Field validation failure with a field path, stable validator code and a translation key. Human-readable text belongs to the consuming application.

fieldRequired

Public field path. Nested properties and array indices are separated by dots.

string

Full definition

{
  "type": "string",
  "example": "email",
  "description": "Public field path. Nested properties and array indices are separated by dots."
}

translationKeyRequired

Translation key for this validator, identical to message. Resolve it using a client dictionary; see the public Developers error catalog.

string

Full definition

{
  "type": "string",
  "example": "validation:isEmail",
  "description": "Translation key for this validator, identical to message. Resolve it using a client dictionary; see the public Developers error catalog."
}

codeRequired

Stable validator identifier for this field failure. Custom validators may define additional identifiers.

string

Full definition

{
  "type": "string",
  "example": "isEmail",
  "description": "Stable validator identifier for this field failure. Custom validators may define additional identifiers."
}

messageRequired

Translation key describing this field validation failure, identical to translationKey. Submitted values and validator prose are not included.

string

Full definition

{
  "type": "string",
  "example": "validation:isEmail",
  "description": "Translation key describing this field validation failure, identical to translationKey. Submitted values and validator prose are not included."
}

translationValuesOptional

Optional scalar values for placeholders in the translation. Treat values as data, escape them when rendering, and never use them as translation options.

object

Full definition

{
  "type": "object",
  "additionalProperties": {
    "oneOf": [
      {
        "type": "string",
        "example": "example"
      },
      {
        "type": "number",
        "example": 0
      },
      {
        "type": "boolean",
        "example": true
      }
    ],
    "example": "example"
  },
  "description": "Optional scalar values for placeholders in the translation. Treat values as data, escape them when rendering, and never use them as translation options.",
  "example": {
    "exampleKey": "example"
  }
}

{
  "type": "object",
  "properties": {
    "field": {
      "type": "string",
      "example": "email",
      "description": "Public field path. Nested properties and array indices are separated by dots."
    },
    "translationKey": {
      "type": "string",
      "example": "validation:isEmail",
      "description": "Translation key for this validator, identical to message. Resolve it using a client dictionary; see the public Developers error catalog."
    },
    "code": {
      "type": "string",
      "example": "isEmail",
      "description": "Stable validator identifier for this field failure. Custom validators may define additional identifiers."
    },
    "message": {
      "type": "string",
      "example": "validation:isEmail",
      "description": "Translation key describing this field validation failure, identical to translationKey. Submitted values and validator prose are not included."
    },
    "translationValues": {
      "type": "object",
      "additionalProperties": {
        "oneOf": [
          {
            "type": "string",
            "example": "example"
          },
          {
            "type": "number",
            "example": 0
          },
          {
            "type": "boolean",
            "example": true
          }
        ],
        "example": "example"
      },
      "description": "Optional scalar values for placeholders in the translation. Treat values as data, escape them when rendering, and never use them as translation options.",
      "example": {
        "exampleKey": "example"
      }
    }
  },
  "required": [
    "field",
    "translationKey",
    "code",
    "message"
  ],
  "description": "Field validation failure with a field path, stable validator code and a translation key. Human-readable text belongs to the consuming application.",
  "example": {
    "field": "email",
    "translationKey": "validation:isEmail",
    "code": "isEmail",
    "message": "validation:isEmail"
  }
}

Recursively JSON-safe value used only where the owning contract intentionally allows free-form structured data.

{
  "oneOf": [
    {
      "type": "string",
      "nullable": true,
      "example": "example"
    },
    {
      "type": "number",
      "example": 0
    },
    {
      "type": "boolean",
      "example": true
    },
    {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/JsonValue"
      },
      "example": [
        "example"
      ]
    },
    {
      "type": "object",
      "additionalProperties": {
        "$ref": "#/components/schemas/JsonValue"
      },
      "example": {
        "exampleKey": "example"
      }
    }
  ],
  "description": "Recursively JSON-safe value used only where the owning contract intentionally allows free-form structured data.",
  "example": "example"
}