Prepare a private widget checkout transition

Private widget payment access and one caller-saved transport proposal. The caller saves the transition UUID and cryptographically random gpw1_ permit before sending its digest.

transitionIdRequired

Caller-generated transition UUID saved before submission. Exact repeats recover the first acknowledgement; another UUID cannot replace this access transition.

string · uuid

Full definition

{
  "type": "string",
  "format": "uuid",
  "description": "Caller-generated transition UUID saved before submission. Exact repeats recover the first acknowledgement; another UUID cannot replace this access transition.",
  "example": "863d2796-5dc7-4cf6-8e5b-c010833c0e1d"
}

accessIdRequired

Exact native payment access context opened by the isolated widget.

string · uuid

Full definition

{
  "type": "string",
  "format": "uuid",
  "description": "Exact native payment access context opened by the isolated widget.",
  "example": "b93bc84d-84db-4161-840b-c3c7a7875b1d"
}

capabilityRequired

Private payment access capability held by the widget. Transfer neither this capability nor the native source capability to a parent or receiver.

string

Full definition

{
  "type": "string",
  "minLength": 48,
  "maxLength": 48,
  "pattern": "^gpa1_[A-Za-z0-9_-]{43}$",
  "example": "gpa1_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
  "writeOnly": true,
  "description": "Private payment access capability held by the widget. Transfer neither this capability nor the native source capability to a parent or receiver."
}

permitHashRequired

SHA-256 hex digest of the complete gpw1_ permit, whose suffix is 32 cryptographically random bytes in canonical base64url form. The raw permit is retained privately for the fixed-destination form POST.

string

Full definition

{
  "type": "string",
  "minLength": 64,
  "maxLength": 64,
  "pattern": "^[a-f0-9]{64}$",
  "writeOnly": true,
  "description": "SHA-256 hex digest of the complete gpw1_ permit, whose suffix is 32 cryptographically random bytes in canonical base64url form. The raw permit is retained privately for the fixed-destination form POST.",
  "example": "deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef"
}

{
  "type": "object",
  "properties": {
    "transitionId": {
      "type": "string",
      "format": "uuid",
      "description": "Caller-generated transition UUID saved before submission. Exact repeats recover the first acknowledgement; another UUID cannot replace this access transition.",
      "example": "863d2796-5dc7-4cf6-8e5b-c010833c0e1d"
    },
    "accessId": {
      "type": "string",
      "format": "uuid",
      "description": "Exact native payment access context opened by the isolated widget.",
      "example": "b93bc84d-84db-4161-840b-c3c7a7875b1d"
    },
    "capability": {
      "type": "string",
      "minLength": 48,
      "maxLength": 48,
      "pattern": "^gpa1_[A-Za-z0-9_-]{43}$",
      "example": "gpa1_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
      "writeOnly": true,
      "description": "Private payment access capability held by the widget. Transfer neither this capability nor the native source capability to a parent or receiver."
    },
    "permitHash": {
      "type": "string",
      "minLength": 64,
      "maxLength": 64,
      "pattern": "^[a-f0-9]{64}$",
      "writeOnly": true,
      "description": "SHA-256 hex digest of the complete gpw1_ permit, whose suffix is 32 cryptographically random bytes in canonical base64url form. The raw permit is retained privately for the fixed-destination form POST.",
      "example": "deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef"
    }
  },
  "description": "Private widget payment access and one caller-saved transport proposal. The caller saves the transition UUID and cryptographically random gpw1_ permit before sending its digest.",
  "required": [
    "transitionId",
    "accessId",
    "capability",
    "permitHash"
  ],
  "example": {
    "transitionId": "863d2796-5dc7-4cf6-8e5b-c010833c0e1d",
    "accessId": "b93bc84d-84db-4161-840b-c3c7a7875b1d",
    "capability": "gpa1_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
    "permitHash": "deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef"
  }
}

Private acknowledgement of one immutable widget checkout transport. It contains no native, access, receiver or handoff credential and creates no financial authority.

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"
}

{
  "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"
    }
  },
  "description": "Private acknowledgement of one immutable widget checkout transport. It contains no native, access, receiver or handoff credential and creates no financial authority.",
  "required": [
    "transitionId",
    "accessId",
    "expiresAt",
    "destinationOrigin"
  ],
  "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"
  }
}

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"
}