Skip to content
HallifyDevelopersSearch documentation
Open Hallify
Sections

Guest payments

Review a server-derived automatic order payment

POST/public/guest-payment-accesses/{accessId}/restaurant-payments/quote

Revalidates the current native payment source and derives the canonical item, principal and tip allocations for the selected eligible merchant binding. Actor and payer identity, provider mode, AUTOMATIC capture and return destination come from verified native access and current configuration. The response is a review only; no consent, checkout, financial hold or provider request is created.

Authentication

Authorization: Bearer <HALLIFY_GUEST_PAYMENT_ACCESS_TOKEN>

Private guest payment capability bound to its native actor, tenant, source, transport origin and current authority. Explicit consent is required for collection; exact original receipt disclosure does not grant a new monetary command or a Hallify account session.

Connection guide

Parameters

originHeader · Required

Actual HTTP Origin of the caller, which must exactly match the payment access's current transport audience.

string
Full definition
{
  "type": "string",
  "maxLength": 2048,
  "example": "example"
}
accessIdPath · Required

Noncredential UUID returned when native payment access is opened or handed off. Pair it with that access's bearer capability; the UUID alone grants no authority.

string · uuid
Full definition
{
  "format": "uuid",
  "type": "string",
  "example": "9b6163a8-afea-4877-818b-8e2ae28a2845"
}

Request body

Required

Eligible merchant-binding UUID, one to fifty distinct native Order selections with positive two-decimal principals and nullable four-decimal item selections, the total requested tip and consent locale.

application/json

oneOf
Full definition
{
  "example": {
    "purpose": "RESERVATION_GUARANTEE",
    "merchantBindingId": "a9365a46-0f50-4efd-89fb-cd79e20e0439",
    "locale": "en"
  },
  "allOf": [
    {
      "$ref": "#/components/schemas/GuestPaymentQuoteRequestDto"
    }
  ],
  "oneOf": [
    {
      "required": [
        "purpose"
      ],
      "not": {
        "anyOf": [
          {
            "required": [
              "targets"
            ],
            "example": {
              "targets": "example"
            }
          },
          {
            "required": [
              "requestedTipAmount"
            ],
            "example": {
              "requestedTipAmount": "example"
            }
          }
        ],
        "example": {
          "targets": "example"
        }
      },
      "example": {
        "purpose": "example"
      }
    },
    {
      "required": [
        "targets",
        "requestedTipAmount"
      ],
      "not": {
        "required": [
          "purpose"
        ],
        "example": {
          "purpose": "example"
        }
      },
      "example": {
        "targets": "example",
        "requestedTipAmount": "example"
      }
    }
  ]
}

Responses

200Canonical financial review with semantic quote digest, principal/tip totals, native item allocations, exact localized consent wording and financial-review deadline.
GuestPaymentQuoteDto
Full definition
{
  "$ref": "#/components/schemas/GuestPaymentQuoteDto"
}
Example response · 200 · application/json
{
  "payee": {
    "venueName": "Example name",
    "legalName": "Example name"
  },
  "quoteHash": "deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef",
  "currency": "USD",
  "principalAmount": "12.50",
  "tipAmount": "0.00",
  "totalAmount": "12.50",
  "provider": "BOG_PAYMENT_MANAGER",
  "merchantBindingId": "a9365a46-0f50-4efd-89fb-cd79e20e0439",
  "expiresAt": "2026-12-31T18:00:00.000Z",
  "terms": {
    "version": "example",
    "digest": "deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef",
    "locale": "en",
    "text": "en"
  },
  "targets": [
    {
      "orderId": "f3127edf-ce4f-4da7-8be5-81b962024e6c",
      "principalAmount": "12.50",
      "tipAmount": "0.00",
      "totalAmount": "12.50",
      "items": [
        {
          "orderItemId": "48069d23-be97-4039-8099-9db268ddf890",
          "quantityPortion": "1.0000",
          "totalAmount": "12.50"
        }
      ]
    }
  ]
}
400The bounded request or command key is malformed.
TranslatedErrorDto
Full definition
{
  "$ref": "#/components/schemas/TranslatedErrorDto"
}
Example response · 400 · application/json
{
  "statusCode": 400,
  "error": "errors:http.badRequest",
  "code": "HTTP_BAD_REQUEST",
  "message": "errors:http.badRequest",
  "translationKey": "errors:http.badRequest"
}
401Rejects a missing, malformed, expired, revoked, or invalid guestPaymentAccessToken credential at the owning domain boundary.
TranslatedErrorDto
Full definition
{
  "$ref": "#/components/schemas/TranslatedErrorDto"
}
Example response · 401 · application/json
{
  "statusCode": 401,
  "error": "errors:http.unauthorized",
  "code": "HTTP_UNAUTHORIZED",
  "message": "errors:http.unauthorized",
  "translationKey": "errors:http.unauthorized"
}
404Current native authority, private payment capability or the exact original checkout is unavailable.
TranslatedErrorDto
Full definition
{
  "$ref": "#/components/schemas/TranslatedErrorDto"
}
Example response · 404 · application/json
{
  "statusCode": 404,
  "error": "errors:http.notFound",
  "code": "HTTP_NOT_FOUND",
  "message": "errors:http.notFound",
  "translationKey": "errors:http.notFound"
}
409The native source, reviewed bill, consent revision or concurrent command state changed.
TranslatedErrorDto
Full definition
{
  "$ref": "#/components/schemas/TranslatedErrorDto"
}
Example response · 409 · application/json
{
  "statusCode": 409,
  "error": "errors:http.conflict",
  "code": "HTTP_CONFLICT",
  "message": "errors:http.conflict",
  "translationKey": "errors:http.conflict"
}

Schemas

GuestPaymentQuoteRequestDto

Merchant binding and consent locale with either a fixed native guarantee purpose or an Order principal, item and tip selection used to calculate a guest payment review.

purposeOptional

Selects the exact native reservation guarantee. Omit for the existing Order bill selection. Guarantee amount and capture mode are server-derived; omit Order targets and tip.

string
Full definition
{
  "type": "string",
  "enum": [
    "RESERVATION_GUARANTEE"
  ],
  "description": "Selects the exact native reservation guarantee. Omit for the existing Order bill selection. Guarantee amount and capture mode are server-derived; omit Order targets and tip.",
  "example": "RESERVATION_GUARANTEE"
}
merchantBindingIdRequired

UUID of a currently eligible venue merchant binding returned with the bill; current configuration determines its provider, mode and automatic-capture eligibility.

string · uuid
Full definition
{
  "type": "string",
  "format": "uuid",
  "description": "UUID of a currently eligible venue merchant binding returned with the bill; current configuration determines its provider, mode and automatic-capture eligibility.",
  "example": "a9365a46-0f50-4efd-89fb-cd79e20e0439"
}
requestedTipAmountOptional

Nonnegative total tip requested for the selected Orders in bill currency, as a decimal string with exactly two fractional digits; the canonical calculation allocates it across the accepted targets.

string
Full definition
{
  "type": "string",
  "example": "0.00",
  "maxLength": 32,
  "description": "Nonnegative total tip requested for the selected Orders in bill currency, as a decimal string with exactly two fractional digits; the canonical calculation allocates it across the accepted targets."
}
localeRequired

Locale of the displayed consent text and its terms digest. Provider checkout language is mapped from this locale using the supported provider language contract.

string
Full definition
{
  "type": "string",
  "enum": [
    "en",
    "ru",
    "ka"
  ],
  "description": "Locale of the displayed consent text and its terms digest. Provider checkout language is mapped from this locale using the supported provider language contract.",
  "example": "en"
}
targetsOptional

One to fifty distinct native Orders with positive requested principals and nullable item selections, all within the caller's current payment-purpose scope.

array
Full definition
{
  "minItems": 1,
  "maxItems": 50,
  "description": "One to fifty distinct native Orders with positive requested principals and nullable item selections, all within the caller's current payment-purpose scope.",
  "type": "array",
  "items": {
    "$ref": "#/components/schemas/GuestPaymentOrderSelectionDto"
  },
  "example": [
    {
      "orderId": "f3127edf-ce4f-4da7-8be5-81b962024e6c",
      "principalAmount": "12.50",
      "items": null
    }
  ]
}
Full definition
{
  "type": "object",
  "properties": {
    "purpose": {
      "type": "string",
      "enum": [
        "RESERVATION_GUARANTEE"
      ],
      "description": "Selects the exact native reservation guarantee. Omit for the existing Order bill selection. Guarantee amount and capture mode are server-derived; omit Order targets and tip.",
      "example": "RESERVATION_GUARANTEE"
    },
    "merchantBindingId": {
      "type": "string",
      "format": "uuid",
      "description": "UUID of a currently eligible venue merchant binding returned with the bill; current configuration determines its provider, mode and automatic-capture eligibility.",
      "example": "a9365a46-0f50-4efd-89fb-cd79e20e0439"
    },
    "requestedTipAmount": {
      "type": "string",
      "example": "0.00",
      "maxLength": 32,
      "description": "Nonnegative total tip requested for the selected Orders in bill currency, as a decimal string with exactly two fractional digits; the canonical calculation allocates it across the accepted targets."
    },
    "locale": {
      "type": "string",
      "enum": [
        "en",
        "ru",
        "ka"
      ],
      "description": "Locale of the displayed consent text and its terms digest. Provider checkout language is mapped from this locale using the supported provider language contract.",
      "example": "en"
    },
    "targets": {
      "minItems": 1,
      "maxItems": 50,
      "description": "One to fifty distinct native Orders with positive requested principals and nullable item selections, all within the caller's current payment-purpose scope.",
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/GuestPaymentOrderSelectionDto"
      },
      "example": [
        {
          "orderId": "f3127edf-ce4f-4da7-8be5-81b962024e6c",
          "principalAmount": "12.50",
          "items": null
        }
      ]
    }
  },
  "description": "Merchant binding and consent locale with either a fixed native guarantee purpose or an Order principal, item and tip selection used to calculate a guest payment review.",
  "required": [
    "merchantBindingId",
    "locale"
  ],
  "example": {
    "merchantBindingId": "a9365a46-0f50-4efd-89fb-cd79e20e0439",
    "locale": "en"
  }
}
GuestPaymentOrderSelectionDto

Requested principal and a nullable explicit item selection for one native Order in an automatic guest bill payment.

orderIdRequired

UUID of an Order included in the current verified native payment source; each Order may appear only once in the quote request.

string · uuid
Full definition
{
  "type": "string",
  "format": "uuid",
  "description": "UUID of an Order included in the current verified native payment source; each Order may appear only once in the quote request.",
  "example": "f3127edf-ce4f-4da7-8be5-81b962024e6c"
}
principalAmountRequired

Strictly positive principal requested for this Order in bill currency, excluding tip, as a decimal string with exactly two fractional digits; the canonical Orders calculation enforces its collectible limit.

string
Full definition
{
  "type": "string",
  "example": "12.50",
  "maxLength": 32,
  "description": "Strictly positive principal requested for this Order in bill currency, excluding tip, as a decimal string with exactly two fractional digits; the canonical Orders calculation enforces its collectible limit."
}
itemsRequired

Required nullable item selection. Null requests canonical automatic allocation for this principal; an array supplies one to five hundred explicit item portions. The combined selection across all Orders is also limited to five hundred items.

array · null
Full definition
{
  "nullable": true,
  "minItems": 1,
  "maxItems": 500,
  "description": "Required nullable item selection. Null requests canonical automatic allocation for this principal; an array supplies one to five hundred explicit item portions. The combined selection across all Orders is also limited to five hundred items.",
  "type": "array",
  "items": {
    "$ref": "#/components/schemas/GuestPaymentItemSelectionDto"
  },
  "example": [
    {
      "orderItemId": "48069d23-be97-4039-8099-9db268ddf890",
      "quantityPortion": "1.0000"
    }
  ]
}
Full definition
{
  "type": "object",
  "properties": {
    "orderId": {
      "type": "string",
      "format": "uuid",
      "description": "UUID of an Order included in the current verified native payment source; each Order may appear only once in the quote request.",
      "example": "f3127edf-ce4f-4da7-8be5-81b962024e6c"
    },
    "principalAmount": {
      "type": "string",
      "example": "12.50",
      "maxLength": 32,
      "description": "Strictly positive principal requested for this Order in bill currency, excluding tip, as a decimal string with exactly two fractional digits; the canonical Orders calculation enforces its collectible limit."
    },
    "items": {
      "nullable": true,
      "minItems": 1,
      "maxItems": 500,
      "description": "Required nullable item selection. Null requests canonical automatic allocation for this principal; an array supplies one to five hundred explicit item portions. The combined selection across all Orders is also limited to five hundred items.",
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/GuestPaymentItemSelectionDto"
      },
      "example": [
        {
          "orderItemId": "48069d23-be97-4039-8099-9db268ddf890",
          "quantityPortion": "1.0000"
        }
      ]
    }
  },
  "description": "Requested principal and a nullable explicit item selection for one native Order in an automatic guest bill payment.",
  "required": [
    "orderId",
    "principalAmount",
    "items"
  ],
  "example": {
    "orderId": "f3127edf-ce4f-4da7-8be5-81b962024e6c",
    "principalAmount": "12.50",
    "items": null
  }
}
GuestPaymentItemSelectionDto

One native Order item and a positive four-decimal quantity requested within the current guest allocation limits.

orderItemIdRequired

UUID of the native Order item belonging to the enclosing selected Order and permitted by the current native payment scope.

string · uuid
Full definition
{
  "type": "string",
  "format": "uuid",
  "description": "UUID of the native Order item belonging to the enclosing selected Order and permitted by the current native payment scope.",
  "example": "48069d23-be97-4039-8099-9db268ddf890"
}
quantityPortionRequired

Strictly positive item quantity as a decimal string with exactly four fractional digits; paid portions, active holds and assignment limits constrain the available quantity.

string
Full definition
{
  "type": "string",
  "example": "1.0000",
  "maxLength": 32,
  "description": "Strictly positive item quantity as a decimal string with exactly four fractional digits; paid portions, active holds and assignment limits constrain the available quantity."
}
Full definition
{
  "type": "object",
  "properties": {
    "orderItemId": {
      "type": "string",
      "format": "uuid",
      "description": "UUID of the native Order item belonging to the enclosing selected Order and permitted by the current native payment scope.",
      "example": "48069d23-be97-4039-8099-9db268ddf890"
    },
    "quantityPortion": {
      "type": "string",
      "example": "1.0000",
      "maxLength": 32,
      "description": "Strictly positive item quantity as a decimal string with exactly four fractional digits; paid portions, active holds and assignment limits constrain the available quantity."
    }
  },
  "description": "One native Order item and a positive four-decimal quantity requested within the current guest allocation limits.",
  "required": [
    "orderItemId",
    "quantityPortion"
  ],
  "example": {
    "orderItemId": "48069d23-be97-4039-8099-9db268ddf890",
    "quantityPortion": "1.0000"
  }
}
GuestPaymentQuoteDto

Server-derived automatic payment review containing canonical totals, merchant/provider choice, localized consent text, native item allocations and the applicable review deadline.

purposeOptional

Present when the reviewed payment funds a native reservation guarantee.

string
Full definition
{
  "type": "string",
  "enum": [
    "RESERVATION_GUARANTEE"
  ],
  "description": "Present when the reviewed payment funds a native reservation guarantee.",
  "example": "RESERVATION_GUARANTEE"
}
guaranteeOptional

Exact native guarantee and accepted financial terms; Order targets are empty.

allOf
Full definition
{
  "description": "Exact native guarantee and accepted financial terms; Order targets are empty.",
  "allOf": [
    {
      "$ref": "#/components/schemas/GuestPaymentGuaranteeReviewDto"
    }
  ],
  "example": {
    "reservationId": "b21b31e5-56ea-442f-8594-270e4efd0f5e",
    "guaranteeRequirementId": "97101ce8-3e48-412d-8520-b38e371ebe3b",
    "revision": 1,
    "kind": "DEPOSIT",
    "termsHash": null,
    "dueAt": null,
    "authorizationExpiresAt": null,
    "terms": null
  }
}
payeeRequired

Exact restaurant and legal payee display snapshot bound by quoteHash and the retained consent manifestHash. Offer replay projects the retained snapshot rather than current renamed venue data.

allOf
Full definition
{
  "description": "Exact restaurant and legal payee display snapshot bound by quoteHash and the retained consent manifestHash. Offer replay projects the retained snapshot rather than current renamed venue data.",
  "allOf": [
    {
      "$ref": "#/components/schemas/GuestPaymentPayeeDto"
    }
  ],
  "example": {
    "venueName": "Example name",
    "legalName": "Example name"
  }
}
quoteHashRequired

Lower-case SHA-256 digest of the semantic financial review, submitted with the same selection when requesting an offer. Acceptance references the full manifestHash returned in that offer's consent receipt.

string
Full definition
{
  "type": "string",
  "pattern": "^[a-f0-9]{64}$",
  "description": "Lower-case SHA-256 digest of the semantic financial review, submitted with the same selection when requesting an offer. Acceptance references the full manifestHash returned in that offer's consent receipt.",
  "example": "deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef"
}
currencyRequired

Currency used by every principal, tip and total amount in this reviewed quote.

string
Full definition
{
  "type": "string",
  "enum": [
    "USD",
    "GEL"
  ],
  "description": "Currency used by every principal, tip and total amount in this reviewed quote.",
  "example": "USD"
}
principalAmountRequired

Aggregate canonical principal across the reviewed Order targets before tip, as a positive two-decimal string.

string
Full definition
{
  "type": "string",
  "example": "12.50",
  "description": "Aggregate canonical principal across the reviewed Order targets before tip, as a positive two-decimal string."
}
tipAmountRequired

Aggregate requested tip allocated by the canonical calculation across the reviewed Order targets, as a nonnegative two-decimal string.

string
Full definition
{
  "type": "string",
  "example": "0.00",
  "description": "Aggregate requested tip allocated by the canonical calculation across the reviewed Order targets, as a nonnegative two-decimal string."
}
totalAmountRequired

Sum of aggregate reviewed principal and tip, as a two-decimal string in the quoted currency.

string
Full definition
{
  "type": "string",
  "example": "12.50",
  "description": "Sum of aggregate reviewed principal and tip, as a two-decimal string in the quoted currency."
}
providerRequired

Payment provider resolved from the currently eligible merchant binding retained in this financial review.

string
Full definition
{
  "type": "string",
  "enum": [
    "BOG_PAYMENT_MANAGER",
    "TBC_CHECKOUT",
    "STRIPE_CONNECT"
  ],
  "description": "Payment provider resolved from the currently eligible merchant binding retained in this financial review.",
  "example": "BOG_PAYMENT_MANAGER"
}
merchantBindingIdRequired

UUID of the merchant binding whose current custody, mode and automatic-capture capabilities are covered by this review.

string · uuid
Full definition
{
  "type": "string",
  "format": "uuid",
  "description": "UUID of the merchant binding whose current custody, mode and automatic-capture capabilities are covered by this review.",
  "example": "a9365a46-0f50-4efd-89fb-cd79e20e0439"
}
expiresAtRequired

UTC ISO-8601 financial-review deadline for a preview, or the retained offer expiry when returned with a consent offer; source or bill changes can invalidate the review earlier.

string · date-time
Full definition
{
  "type": "string",
  "format": "date-time",
  "description": "UTC ISO-8601 financial-review deadline for a preview, or the retained offer expiry when returned with a consent offer; source or bill changes can invalidate the review earlier.",
  "example": "2026-12-31T18:00:00.000Z"
}
termsRequired

Exact localized consent wording and the version, digest and locale covered by this financial review.

allOf
Full definition
{
  "description": "Exact localized consent wording and the version, digest and locale covered by this financial review.",
  "allOf": [
    {
      "$ref": "#/components/schemas/GuestPaymentDisplayedTermsDto"
    }
  ],
  "example": {
    "version": "example",
    "digest": "deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef",
    "locale": "en",
    "text": "en"
  }
}
targetsRequired

Reviewed canonical principal, tip and native item allocations for the selected Orders.

array
Full definition
{
  "description": "Reviewed canonical principal, tip and native item allocations for the selected Orders.",
  "type": "array",
  "items": {
    "$ref": "#/components/schemas/GuestPaymentQuotedOrderDto"
  },
  "example": [
    {
      "orderId": "f3127edf-ce4f-4da7-8be5-81b962024e6c",
      "principalAmount": "12.50",
      "tipAmount": "0.00",
      "totalAmount": "12.50",
      "items": [
        {
          "orderItemId": "48069d23-be97-4039-8099-9db268ddf890",
          "quantityPortion": "1.0000",
          "totalAmount": "12.50"
        }
      ]
    }
  ]
}
Full definition
{
  "type": "object",
  "properties": {
    "purpose": {
      "type": "string",
      "enum": [
        "RESERVATION_GUARANTEE"
      ],
      "description": "Present when the reviewed payment funds a native reservation guarantee.",
      "example": "RESERVATION_GUARANTEE"
    },
    "guarantee": {
      "description": "Exact native guarantee and accepted financial terms; Order targets are empty.",
      "allOf": [
        {
          "$ref": "#/components/schemas/GuestPaymentGuaranteeReviewDto"
        }
      ],
      "example": {
        "reservationId": "b21b31e5-56ea-442f-8594-270e4efd0f5e",
        "guaranteeRequirementId": "97101ce8-3e48-412d-8520-b38e371ebe3b",
        "revision": 1,
        "kind": "DEPOSIT",
        "termsHash": null,
        "dueAt": null,
        "authorizationExpiresAt": null,
        "terms": null
      }
    },
    "payee": {
      "description": "Exact restaurant and legal payee display snapshot bound by quoteHash and the retained consent manifestHash. Offer replay projects the retained snapshot rather than current renamed venue data.",
      "allOf": [
        {
          "$ref": "#/components/schemas/GuestPaymentPayeeDto"
        }
      ],
      "example": {
        "venueName": "Example name",
        "legalName": "Example name"
      }
    },
    "quoteHash": {
      "type": "string",
      "pattern": "^[a-f0-9]{64}$",
      "description": "Lower-case SHA-256 digest of the semantic financial review, submitted with the same selection when requesting an offer. Acceptance references the full manifestHash returned in that offer's consent receipt.",
      "example": "deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef"
    },
    "currency": {
      "type": "string",
      "enum": [
        "USD",
        "GEL"
      ],
      "description": "Currency used by every principal, tip and total amount in this reviewed quote.",
      "example": "USD"
    },
    "principalAmount": {
      "type": "string",
      "example": "12.50",
      "description": "Aggregate canonical principal across the reviewed Order targets before tip, as a positive two-decimal string."
    },
    "tipAmount": {
      "type": "string",
      "example": "0.00",
      "description": "Aggregate requested tip allocated by the canonical calculation across the reviewed Order targets, as a nonnegative two-decimal string."
    },
    "totalAmount": {
      "type": "string",
      "example": "12.50",
      "description": "Sum of aggregate reviewed principal and tip, as a two-decimal string in the quoted currency."
    },
    "provider": {
      "type": "string",
      "enum": [
        "BOG_PAYMENT_MANAGER",
        "TBC_CHECKOUT",
        "STRIPE_CONNECT"
      ],
      "description": "Payment provider resolved from the currently eligible merchant binding retained in this financial review.",
      "example": "BOG_PAYMENT_MANAGER"
    },
    "merchantBindingId": {
      "type": "string",
      "format": "uuid",
      "description": "UUID of the merchant binding whose current custody, mode and automatic-capture capabilities are covered by this review.",
      "example": "a9365a46-0f50-4efd-89fb-cd79e20e0439"
    },
    "expiresAt": {
      "type": "string",
      "format": "date-time",
      "description": "UTC ISO-8601 financial-review deadline for a preview, or the retained offer expiry when returned with a consent offer; source or bill changes can invalidate the review earlier.",
      "example": "2026-12-31T18:00:00.000Z"
    },
    "terms": {
      "description": "Exact localized consent wording and the version, digest and locale covered by this financial review.",
      "allOf": [
        {
          "$ref": "#/components/schemas/GuestPaymentDisplayedTermsDto"
        }
      ],
      "example": {
        "version": "example",
        "digest": "deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef",
        "locale": "en",
        "text": "en"
      }
    },
    "targets": {
      "description": "Reviewed canonical principal, tip and native item allocations for the selected Orders.",
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/GuestPaymentQuotedOrderDto"
      },
      "example": [
        {
          "orderId": "f3127edf-ce4f-4da7-8be5-81b962024e6c",
          "principalAmount": "12.50",
          "tipAmount": "0.00",
          "totalAmount": "12.50",
          "items": [
            {
              "orderItemId": "48069d23-be97-4039-8099-9db268ddf890",
              "quantityPortion": "1.0000",
              "totalAmount": "12.50"
            }
          ]
        }
      ]
    }
  },
  "description": "Server-derived automatic payment review containing canonical totals, merchant/provider choice, localized consent text, native item allocations and the applicable review deadline.",
  "required": [
    "payee",
    "quoteHash",
    "currency",
    "principalAmount",
    "tipAmount",
    "totalAmount",
    "provider",
    "merchantBindingId",
    "expiresAt",
    "terms",
    "targets"
  ],
  "example": {
    "payee": {
      "venueName": "Example name",
      "legalName": "Example name"
    },
    "quoteHash": "deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef",
    "currency": "USD",
    "principalAmount": "12.50",
    "tipAmount": "0.00",
    "totalAmount": "12.50",
    "provider": "BOG_PAYMENT_MANAGER",
    "merchantBindingId": "a9365a46-0f50-4efd-89fb-cd79e20e0439",
    "expiresAt": "2026-12-31T18:00:00.000Z",
    "terms": {
      "version": "example",
      "digest": "deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef",
      "locale": "en",
      "text": "en"
    },
    "targets": [
      {
        "orderId": "f3127edf-ce4f-4da7-8be5-81b962024e6c",
        "principalAmount": "12.50",
        "tipAmount": "0.00",
        "totalAmount": "12.50",
        "items": [
          {
            "orderItemId": "48069d23-be97-4039-8099-9db268ddf890",
            "quantityPortion": "1.0000",
            "totalAmount": "12.50"
          }
        ]
      }
    ]
  }
}
GuestPaymentGuaranteeReviewDto

The genuine native reservation guarantee being reviewed; this projection contains no Order target or private grant/capability.

reservationIdRequired

Native Reservation UUID.

string · uuid
Full definition
{
  "type": "string",
  "format": "uuid",
  "description": "Native Reservation UUID.",
  "example": "b21b31e5-56ea-442f-8594-270e4efd0f5e"
}
guaranteeRequirementIdRequired

Exact original guarantee requirement UUID; another agreement does not adopt its funds.

string · uuid
Full definition
{
  "type": "string",
  "format": "uuid",
  "description": "Exact original guarantee requirement UUID; another agreement does not adopt its funds.",
  "example": "97101ce8-3e48-412d-8520-b38e371ebe3b"
}
revisionRequired

Native requirement revision used by the review.

integer
Full definition
{
  "type": "integer",
  "minimum": 1,
  "description": "Native requirement revision used by the review.",
  "example": 1
}
kindRequired

Native guarantee kind determining automatic capture or manual card hold.

string
Full definition
{
  "type": "string",
  "enum": [
    "DEPOSIT",
    "PREPAID",
    "CARD_HOLD"
  ],
  "description": "Native guarantee kind determining automatic capture or manual card hold.",
  "example": "DEPOSIT"
}
termsHashRequired

Digest of the accepted native financial agreement; null only for retained legacy evidence.

string · null
Full definition
{
  "type": "string",
  "nullable": true,
  "minLength": 64,
  "maxLength": 64,
  "pattern": "^[a-f0-9]{64}$",
  "description": "Digest of the accepted native financial agreement; null only for retained legacy evidence.",
  "example": "deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef"
}
dueAtRequired

Native funding deadline retained by this review.

string · date-time · null
Full definition
{
  "type": "string",
  "nullable": true,
  "format": "date-time",
  "description": "Native funding deadline retained by this review.",
  "example": "2026-12-31T18:00:00.000Z"
}
authorizationExpiresAtRequired

Native authorization expiry when available. Initial review may be null; actual authenticated provider expiry controls protection.

string · date-time · null
Full definition
{
  "type": "string",
  "nullable": true,
  "format": "date-time",
  "description": "Native authorization expiry when available. Initial review may be null; actual authenticated provider expiry controls protection.",
  "example": "2026-12-31T18:00:00.000Z"
}
termsRequired

Exact accepted native cancellation and no-show financial terms projected for review.

object · null
Full definition
{
  "nullable": true,
  "description": "Exact accepted native cancellation and no-show financial terms projected for review.",
  "type": "object",
  "properties": {
    "kind": {
      "type": "string",
      "enum": [
        "DEPOSIT",
        "PREPAID",
        "CARD_HOLD"
      ],
      "description": "Accepted guarantee type.",
      "example": "DEPOSIT"
    },
    "amountBasis": {
      "type": "string",
      "enum": [
        "FIXED",
        "PER_GUEST"
      ],
      "description": "Accepted fixed or per-guest amount calculation.",
      "example": "FIXED"
    },
    "unitAmount": {
      "type": "string",
      "pattern": "^(0|[1-9]\\d*)\\.\\d{2}$",
      "description": "Accepted two-decimal unit principal.",
      "example": "1.00"
    },
    "totalAmount": {
      "type": "string",
      "pattern": "^(0|[1-9]\\d*)\\.\\d{2}$",
      "description": "Accepted two-decimal total guarantee principal.",
      "example": "1.00"
    },
    "currency": {
      "type": "string",
      "minLength": 3,
      "maxLength": 3,
      "pattern": "^[A-Z]{3}$",
      "description": "Currency of the accepted guarantee.",
      "example": "GEL"
    },
    "partySize": {
      "type": "integer",
      "minimum": 1,
      "description": "Party size bound to the accepted financial terms.",
      "example": 1
    },
    "scheduledAt": {
      "type": "string",
      "format": "date-time",
      "description": "Scheduled reservation instant bound to this agreement.",
      "example": "2026-01-15T12:00:00.000Z"
    },
    "dueAt": {
      "type": "string",
      "format": "date-time",
      "description": "Accepted guarantee funding deadline.",
      "example": "2026-12-31T18:00:00.000Z"
    },
    "freeCancellationAt": {
      "type": "string",
      "format": "date-time",
      "description": "Accepted free-cancellation deadline.",
      "example": "2026-01-15T12:00:00.000Z"
    },
    "noShowAfter": {
      "type": "string",
      "format": "date-time",
      "description": "Accepted no-show decision instant; actual card authorization must cover the required protection interval.",
      "example": "2026-01-15T12:00:00.000Z"
    },
    "forfeitOnLateCancellation": {
      "type": "boolean",
      "description": "Whether the accepted terms permit forfeiture after late cancellation.",
      "example": true
    },
    "forfeitOnNoShow": {
      "type": "boolean",
      "description": "Whether the accepted terms permit forfeiture for no-show.",
      "example": true
    },
    "termsVersion": {
      "type": "string",
      "description": "Accepted native terms version.",
      "example": "example"
    },
    "privacyVersion": {
      "type": "string",
      "description": "Accepted native privacy version.",
      "example": "example"
    }
  },
  "required": [
    "kind",
    "amountBasis",
    "unitAmount",
    "totalAmount",
    "currency",
    "partySize",
    "scheduledAt",
    "dueAt",
    "freeCancellationAt",
    "noShowAfter",
    "forfeitOnLateCancellation",
    "forfeitOnNoShow",
    "termsVersion",
    "privacyVersion"
  ],
  "example": {
    "kind": "DEPOSIT",
    "amountBasis": "FIXED",
    "unitAmount": "1.00",
    "totalAmount": "1.00",
    "currency": "GEL",
    "partySize": 1,
    "scheduledAt": "2026-01-15T12:00:00.000Z",
    "dueAt": "2026-12-31T18:00:00.000Z",
    "freeCancellationAt": "2026-01-15T12:00:00.000Z",
    "noShowAfter": "2026-01-15T12:00:00.000Z",
    "forfeitOnLateCancellation": true,
    "forfeitOnNoShow": true,
    "termsVersion": "example",
    "privacyVersion": "example"
  }
}
Full definition
{
  "type": "object",
  "properties": {
    "reservationId": {
      "type": "string",
      "format": "uuid",
      "description": "Native Reservation UUID.",
      "example": "b21b31e5-56ea-442f-8594-270e4efd0f5e"
    },
    "guaranteeRequirementId": {
      "type": "string",
      "format": "uuid",
      "description": "Exact original guarantee requirement UUID; another agreement does not adopt its funds.",
      "example": "97101ce8-3e48-412d-8520-b38e371ebe3b"
    },
    "revision": {
      "type": "integer",
      "minimum": 1,
      "description": "Native requirement revision used by the review.",
      "example": 1
    },
    "kind": {
      "type": "string",
      "enum": [
        "DEPOSIT",
        "PREPAID",
        "CARD_HOLD"
      ],
      "description": "Native guarantee kind determining automatic capture or manual card hold.",
      "example": "DEPOSIT"
    },
    "termsHash": {
      "type": "string",
      "nullable": true,
      "minLength": 64,
      "maxLength": 64,
      "pattern": "^[a-f0-9]{64}$",
      "description": "Digest of the accepted native financial agreement; null only for retained legacy evidence.",
      "example": "deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef"
    },
    "dueAt": {
      "type": "string",
      "nullable": true,
      "format": "date-time",
      "description": "Native funding deadline retained by this review.",
      "example": "2026-12-31T18:00:00.000Z"
    },
    "authorizationExpiresAt": {
      "type": "string",
      "nullable": true,
      "format": "date-time",
      "description": "Native authorization expiry when available. Initial review may be null; actual authenticated provider expiry controls protection.",
      "example": "2026-12-31T18:00:00.000Z"
    },
    "terms": {
      "nullable": true,
      "description": "Exact accepted native cancellation and no-show financial terms projected for review.",
      "type": "object",
      "properties": {
        "kind": {
          "type": "string",
          "enum": [
            "DEPOSIT",
            "PREPAID",
            "CARD_HOLD"
          ],
          "description": "Accepted guarantee type.",
          "example": "DEPOSIT"
        },
        "amountBasis": {
          "type": "string",
          "enum": [
            "FIXED",
            "PER_GUEST"
          ],
          "description": "Accepted fixed or per-guest amount calculation.",
          "example": "FIXED"
        },
        "unitAmount": {
          "type": "string",
          "pattern": "^(0|[1-9]\\d*)\\.\\d{2}$",
          "description": "Accepted two-decimal unit principal.",
          "example": "1.00"
        },
        "totalAmount": {
          "type": "string",
          "pattern": "^(0|[1-9]\\d*)\\.\\d{2}$",
          "description": "Accepted two-decimal total guarantee principal.",
          "example": "1.00"
        },
        "currency": {
          "type": "string",
          "minLength": 3,
          "maxLength": 3,
          "pattern": "^[A-Z]{3}$",
          "description": "Currency of the accepted guarantee.",
          "example": "GEL"
        },
        "partySize": {
          "type": "integer",
          "minimum": 1,
          "description": "Party size bound to the accepted financial terms.",
          "example": 1
        },
        "scheduledAt": {
          "type": "string",
          "format": "date-time",
          "description": "Scheduled reservation instant bound to this agreement.",
          "example": "2026-01-15T12:00:00.000Z"
        },
        "dueAt": {
          "type": "string",
          "format": "date-time",
          "description": "Accepted guarantee funding deadline.",
          "example": "2026-12-31T18:00:00.000Z"
        },
        "freeCancellationAt": {
          "type": "string",
          "format": "date-time",
          "description": "Accepted free-cancellation deadline.",
          "example": "2026-01-15T12:00:00.000Z"
        },
        "noShowAfter": {
          "type": "string",
          "format": "date-time",
          "description": "Accepted no-show decision instant; actual card authorization must cover the required protection interval.",
          "example": "2026-01-15T12:00:00.000Z"
        },
        "forfeitOnLateCancellation": {
          "type": "boolean",
          "description": "Whether the accepted terms permit forfeiture after late cancellation.",
          "example": true
        },
        "forfeitOnNoShow": {
          "type": "boolean",
          "description": "Whether the accepted terms permit forfeiture for no-show.",
          "example": true
        },
        "termsVersion": {
          "type": "string",
          "description": "Accepted native terms version.",
          "example": "example"
        },
        "privacyVersion": {
          "type": "string",
          "description": "Accepted native privacy version.",
          "example": "example"
        }
      },
      "required": [
        "kind",
        "amountBasis",
        "unitAmount",
        "totalAmount",
        "currency",
        "partySize",
        "scheduledAt",
        "dueAt",
        "freeCancellationAt",
        "noShowAfter",
        "forfeitOnLateCancellation",
        "forfeitOnNoShow",
        "termsVersion",
        "privacyVersion"
      ],
      "example": {
        "kind": "DEPOSIT",
        "amountBasis": "FIXED",
        "unitAmount": "1.00",
        "totalAmount": "1.00",
        "currency": "GEL",
        "partySize": 1,
        "scheduledAt": "2026-01-15T12:00:00.000Z",
        "dueAt": "2026-12-31T18:00:00.000Z",
        "freeCancellationAt": "2026-01-15T12:00:00.000Z",
        "noShowAfter": "2026-01-15T12:00:00.000Z",
        "forfeitOnLateCancellation": true,
        "forfeitOnNoShow": true,
        "termsVersion": "example",
        "privacyVersion": "example"
      }
    }
  },
  "description": "The genuine native reservation guarantee being reviewed; this projection contains no Order target or private grant/capability.",
  "required": [
    "reservationId",
    "guaranteeRequirementId",
    "revision",
    "kind",
    "termsHash",
    "dueAt",
    "authorizationExpiresAt",
    "terms"
  ],
  "example": {
    "reservationId": "b21b31e5-56ea-442f-8594-270e4efd0f5e",
    "guaranteeRequirementId": "97101ce8-3e48-412d-8520-b38e371ebe3b",
    "revision": 1,
    "kind": "DEPOSIT",
    "termsHash": null,
    "dueAt": null,
    "authorizationExpiresAt": null,
    "terms": null
  }
}
GuestPaymentPayeeDto

Server-derived restaurant and legal payee names from the exact authorized venue and legal entity. Quotes retain this display identity inside the immutable consent manifest.

venueNameRequired

Canonical name of the native venue receiving the reviewed Order payment, derived within the current organization, venue and legal-entity scope; never a client label or staff merchant-binding label.

string
Full definition
{
  "type": "string",
  "minLength": 1,
  "maxLength": 255,
  "description": "Canonical name of the native venue receiving the reviewed Order payment, derived within the current organization, venue and legal-entity scope; never a client label or staff merchant-binding label.",
  "example": "Example name"
}
legalNameRequired

Canonical legal name of the payee entity owning this authorized venue and merchant custody. This is the retained legal-entity identity, not a guessed PSP statement descriptor.

string
Full definition
{
  "type": "string",
  "minLength": 1,
  "maxLength": 255,
  "description": "Canonical legal name of the payee entity owning this authorized venue and merchant custody. This is the retained legal-entity identity, not a guessed PSP statement descriptor.",
  "example": "Example name"
}
Full definition
{
  "type": "object",
  "properties": {
    "venueName": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255,
      "description": "Canonical name of the native venue receiving the reviewed Order payment, derived within the current organization, venue and legal-entity scope; never a client label or staff merchant-binding label.",
      "example": "Example name"
    },
    "legalName": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255,
      "description": "Canonical legal name of the payee entity owning this authorized venue and merchant custody. This is the retained legal-entity identity, not a guessed PSP statement descriptor.",
      "example": "Example name"
    }
  },
  "description": "Server-derived restaurant and legal payee names from the exact authorized venue and legal entity. Quotes retain this display identity inside the immutable consent manifest.",
  "required": [
    "venueName",
    "legalName"
  ],
  "example": {
    "venueName": "Example name",
    "legalName": "Example name"
  }
}
GuestPaymentDisplayedTermsDto

Exact localized consent wording together with the version, locale and digest identifying it for financial review.

versionRequired

Nonempty version identifying the displayed consent wording; acceptance must match the exact version retained in its offer.

string
Full definition
{
  "type": "string",
  "maxLength": 64,
  "description": "Nonempty version identifying the displayed consent wording; acceptance must match the exact version retained in its offer.",
  "example": "example"
}
digestRequired

Lower-case SHA-256 digest binding the terms version, locale and exact displayed text; acceptance must echo the offered digest.

string
Full definition
{
  "type": "string",
  "pattern": "^[a-f0-9]{64}$",
  "description": "Lower-case SHA-256 digest binding the terms version, locale and exact displayed text; acceptance must echo the offered digest.",
  "example": "deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef"
}
localeRequired

Locale covered by the displayed consent text and digest; acceptance must match the locale retained in the offer.

string
Full definition
{
  "type": "string",
  "enum": [
    "en",
    "ru",
    "ka"
  ],
  "description": "Locale covered by the displayed consent text and digest; acceptance must match the locale retained in the offer.",
  "example": "en"
}
textRequired

Exact localized text covered by this terms version, locale and digest.

string
Full definition
{
  "type": "string",
  "description": "Exact localized text covered by this terms version, locale and digest.",
  "example": "en"
}
Full definition
{
  "type": "object",
  "properties": {
    "version": {
      "type": "string",
      "maxLength": 64,
      "description": "Nonempty version identifying the displayed consent wording; acceptance must match the exact version retained in its offer.",
      "example": "example"
    },
    "digest": {
      "type": "string",
      "pattern": "^[a-f0-9]{64}$",
      "description": "Lower-case SHA-256 digest binding the terms version, locale and exact displayed text; acceptance must echo the offered digest.",
      "example": "deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef"
    },
    "locale": {
      "type": "string",
      "enum": [
        "en",
        "ru",
        "ka"
      ],
      "description": "Locale covered by the displayed consent text and digest; acceptance must match the locale retained in the offer.",
      "example": "en"
    },
    "text": {
      "type": "string",
      "description": "Exact localized text covered by this terms version, locale and digest.",
      "example": "en"
    }
  },
  "description": "Exact localized consent wording together with the version, locale and digest identifying it for financial review.",
  "required": [
    "version",
    "digest",
    "locale",
    "text"
  ],
  "example": {
    "version": "example",
    "digest": "deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef",
    "locale": "en",
    "text": "en"
  }
}
GuestPaymentQuotedOrderDto

Frozen principal and allocated share of the requested tip for one native Order, with the item portions covered by the review.

orderIdRequired

UUID of the native Order receiving this reviewed principal and tip allocation.

string · uuid
Full definition
{
  "type": "string",
  "format": "uuid",
  "description": "UUID of the native Order receiving this reviewed principal and tip allocation.",
  "example": "f3127edf-ce4f-4da7-8be5-81b962024e6c"
}
principalAmountRequired

Canonical principal assigned to this Order before tip, as a two-decimal string in quote currency.

string
Full definition
{
  "type": "string",
  "example": "12.50",
  "description": "Canonical principal assigned to this Order before tip, as a two-decimal string in quote currency."
}
tipAmountRequired

Canonical share of the requested tip allocated to this Order, as a nonnegative two-decimal string in quote currency.

string
Full definition
{
  "type": "string",
  "example": "0.00",
  "description": "Canonical share of the requested tip allocated to this Order, as a nonnegative two-decimal string in quote currency."
}
totalAmountRequired

Sum of this Order target's principal and allocated tip, as a two-decimal string in quote currency.

string
Full definition
{
  "type": "string",
  "example": "12.50",
  "description": "Sum of this Order target's principal and allocated tip, as a two-decimal string in quote currency."
}
itemsRequired

Canonical native item portions and their principals covered by this Order target in the reviewed selection.

array
Full definition
{
  "description": "Canonical native item portions and their principals covered by this Order target in the reviewed selection.",
  "type": "array",
  "items": {
    "$ref": "#/components/schemas/GuestPaymentQuotedItemDto"
  },
  "example": [
    {
      "orderItemId": "48069d23-be97-4039-8099-9db268ddf890",
      "quantityPortion": "1.0000",
      "totalAmount": "12.50"
    }
  ]
}
Full definition
{
  "type": "object",
  "properties": {
    "orderId": {
      "type": "string",
      "format": "uuid",
      "description": "UUID of the native Order receiving this reviewed principal and tip allocation.",
      "example": "f3127edf-ce4f-4da7-8be5-81b962024e6c"
    },
    "principalAmount": {
      "type": "string",
      "example": "12.50",
      "description": "Canonical principal assigned to this Order before tip, as a two-decimal string in quote currency."
    },
    "tipAmount": {
      "type": "string",
      "example": "0.00",
      "description": "Canonical share of the requested tip allocated to this Order, as a nonnegative two-decimal string in quote currency."
    },
    "totalAmount": {
      "type": "string",
      "example": "12.50",
      "description": "Sum of this Order target's principal and allocated tip, as a two-decimal string in quote currency."
    },
    "items": {
      "description": "Canonical native item portions and their principals covered by this Order target in the reviewed selection.",
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/GuestPaymentQuotedItemDto"
      },
      "example": [
        {
          "orderItemId": "48069d23-be97-4039-8099-9db268ddf890",
          "quantityPortion": "1.0000",
          "totalAmount": "12.50"
        }
      ]
    }
  },
  "description": "Frozen principal and allocated share of the requested tip for one native Order, with the item portions covered by the review.",
  "required": [
    "orderId",
    "principalAmount",
    "tipAmount",
    "totalAmount",
    "items"
  ],
  "example": {
    "orderId": "f3127edf-ce4f-4da7-8be5-81b962024e6c",
    "principalAmount": "12.50",
    "tipAmount": "0.00",
    "totalAmount": "12.50",
    "items": [
      {
        "orderItemId": "48069d23-be97-4039-8099-9db268ddf890",
        "quantityPortion": "1.0000",
        "totalAmount": "12.50"
      }
    ]
  }
}
GuestPaymentQuotedItemDto

Canonical native item portion and its principal included in a reviewed automatic guest payment quote.

orderItemIdRequired

UUID of the native Order item selected in the enclosing reviewed Order allocation.

string · uuid
Full definition
{
  "type": "string",
  "format": "uuid",
  "description": "UUID of the native Order item selected in the enclosing reviewed Order allocation.",
  "example": "48069d23-be97-4039-8099-9db268ddf890"
}
quantityPortionRequired

Canonical selected item quantity retained in this review, as a positive decimal string with exactly four fractional digits.

string
Full definition
{
  "type": "string",
  "example": "1.0000",
  "description": "Canonical selected item quantity retained in this review, as a positive decimal string with exactly four fractional digits."
}
totalAmountRequired

Canonical principal for the selected item portion in quote currency, as a two-decimal string; tip is allocated separately on the enclosing Order target.

string
Full definition
{
  "type": "string",
  "example": "12.50",
  "description": "Canonical principal for the selected item portion in quote currency, as a two-decimal string; tip is allocated separately on the enclosing Order target."
}
Full definition
{
  "type": "object",
  "properties": {
    "orderItemId": {
      "type": "string",
      "format": "uuid",
      "description": "UUID of the native Order item selected in the enclosing reviewed Order allocation.",
      "example": "48069d23-be97-4039-8099-9db268ddf890"
    },
    "quantityPortion": {
      "type": "string",
      "example": "1.0000",
      "description": "Canonical selected item quantity retained in this review, as a positive decimal string with exactly four fractional digits."
    },
    "totalAmount": {
      "type": "string",
      "example": "12.50",
      "description": "Canonical principal for the selected item portion in quote currency, as a two-decimal string; tip is allocated separately on the enclosing Order target."
    }
  },
  "description": "Canonical native item portion and its principal included in a reviewed automatic guest payment quote.",
  "required": [
    "orderItemId",
    "quantityPortion",
    "totalAmount"
  ],
  "example": {
    "orderItemId": "48069d23-be97-4039-8099-9db268ddf890",
    "quantityPortion": "1.0000",
    "totalAmount": "12.50"
  }
}
TranslatedErrorDto

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"
  ]
}
Full definition
{
  "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"
  }
}
ValidationErrorDto

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"
  }
}
Full definition
{
  "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"
  }
}
JsonValue

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

Full definition
{
  "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"
}

Hallify uses essential cookies and optional analytics.

Essential cookies keep sign-in, locale, and theme preferences working. Analytics is off until you choose to allow it.